Currently set to Index
Currently set to Follow

Overview

Pay Now is a web service that allows a user to generate payment options on an Invoice/Statement/Quotation or even a membership card, counter display or virtually (Point of Sale) any other place where payment options can be supplied. See demo here(Click the buttons at the bottom to simulate the process).

For this, the Developer will use PayNow.svc with method CreateInvoice (for single invoices). Any software that allows for the printing of invoices, statements and/or quotations that one would like to be paid through the Pay Now service should use this method. If you have multiple invoices/statements/quotations that you would like generated with the payment options on any document, please use the batch file upload service to do this same task.

This service is to be used on input of data into the application to render a reference that will be used to make the payment for a document.

The Pay Now service can also be used to create payment requests which are sent to end-users via SMS and/or email from the Netcash system. Please see Payment Request detail below. Read more about the Payment Request service here

See the service overview here.

Web Service Methods

The list of Netcash web service methods can be found here

QuickStart Guides

We have developed some Quick Start Guides to help you understand this service and to help you get started.

Programmers Guide

To start, refer our Programmers guide for more detail on how to apply the required methodology in this document.
Please ensure that the settings for Developers are correctly set before you proceed with the implementation below specification.

Technical Information

Pay Now is an online, synchronous web service which allows an external system to request an invoice reference for payment and receive an immediate response. This service permits only a single request per web service call.

From your application call:

Web service: https://ws.netcash.co.za/PayNow/PayNow.svc
Method: CreateInvoice
To create a single payment footer

Pay Now Service Key

The service key is used to authenticate access to the Pay Now service. It identifies the origin of the payment instruction. The service key determines the Netcash account to which the proceeds of the payment will be credited.

Payment methods

Netcash currently offers the following payment methods. Read more about the different methods we offer or see the visual representation here.

Service Explanation Real-time notification *more info Suggested use
Debit/Credit Card Online payments via your Master/Visa card. Yes Any product or service where payment online is required
QR Code Payment via a mobile application/wallet on your smartphone Yes Any product or service where a face to face payment is required
Instant EFT Where you log in to your internet banking from a secure third-party system to authorize a system defined EFT payment. Yes Any product or service where seamless EFT payment is required
Bank EFT Where you log in to your internet banking to make an EFT payment. No Any product or service where standard EFT payment is required.
Cash/Retail A barcode is displayed on a document that is scanned by a retailer and payment is made to the retailer. No Any product or service where cash or alternative ‘in-person’ payment is required.

Note:
Although the notification of some transactions may be in real-time; the actual value of the transaction is only available in the Netcash Account the following business day.

NetConnector

The NetConnector profile allows you to customize the service according to your requirements:

  • Active: This field is non-editable.
  • Email: This is the email address to which any errors in processing will be directed. It is also the address to which the service key will be sent. Notifications of transactions will also be sent to this address.
  • Service key: This is the unique service key (field m1) which must be included in the POST to the Netcash URL.
  • Allow Master and Visa payments: This option is used to control whether your client may pay by credit card (master/visa only).
  • Accept url: Enter your accept URL here. If the URL changes for any reason, it can be updated on this page. This is the URL that the browser is sent to if the transaction is successful.
  • Decline url: Enter your decline URL here. If the URL changes for any reason, it can be updated on this page. This is the URL that the browser is sent to if the transaction is declined. If a card transaction is cancelled by the card holder during the payment process, the page will redirect to the decline url page.
  • Notify url: This is the URL that Netcash will call for transactions like EFT and Retail where the payment is not able to be captured in real time. These payments will be picked up when they are made and Netcash will notify your system through this URL.
  • Redirect url: This is the URL that the browser is sent to once the complete button is clicked on the EFT and Retail payment screens on Netcash. This could/would return the customer to your site while you are waiting for a payment to be made.
  • Make test mode active: use this setting while you are testing the system to simulate transactions. Once your development is complete, this box should be un-ticked
  • In TEST MODE use the following numbers to test with:
    4000000000000002 – Returns “Approved”
    4000000000000028 – Returns VISA “Declined”
    5200000000000049 – Returns MasterCard “Declined”

Please note: Use “123” as CVC value and expiry date; any month and year in the future for all test transactions.

Payment Notification

Read more about the postback URL‘s and their functions here to get a better understanding of how notifications are presented back to your system.

Input

Submit the following parameters.

 

Field Explanation
M1 The Pay Now Service Key
M2 The key issued by Netcash to identify the software origin of transactions. (only used by Netcash ISV‘s else use the default value: 24ade73c-98cf-47b3-99be-cc7b867b3080)
Amount The amount of the invoice in cents
P2 Unique reference for this invoice
P3 Invoice Description
M4 Extra data field 1
M5 Extra data field 2
M6 Extra data field 3
M9 Email of the person you are invoicing
M10 Additional return string data
IgnoreAmount True (call for amount to be paid) False (use amount in barcode)                              *see update value details
M11 Mobile number ie. 0812345678
M12 Send SMS (Boolean) – M11 must contain valid data if this field is set to true
M13 Send Email (Boolean) – M9 must contain valid data if this field is set to true

Output

If there is no error you will receive an xml string response with the necessary data to populate your invoice that adheres to the following XSD

https://www.netcash.co.za/sagepay/xsd/paynowinvoice.xsd

The web service will return only the payment types that have been activated in the back office of the system.

The retail / barcode product renders a barcode string that needs to be rendered in the following way:

Barcode standard: Code128C
Image type: SVG_VML
Image width: 400px
Image height: 50px

If an error occurred

You will receive the following numeric code if there is an error in the service.

Numeric Response Description
100 Authentication failed
103 Invalid software vendor key
200 Web service error contact support@netcash.co.za
301 Non unique reference provided
310 Payment request not activated for this account. Contact support@netcash.co.za

Part 2 – Billing

Read the Pay Now service overview

Introduction

Netcash – Pay Now Billing is a service whereby parameters are sent to Netcash via a Web Service in a batch file upload using ‘NIWS_NIF’ to create multiple Pay Now footers. The Netcash web service will then return a footer string with payment options and store the data in the Netcash system for use with Pay Now payments, made by end users.

Technical Information

NIWS_NIF is an asynchronous web service which exposes multiple methods. The method BatchFileUpload allows an external system to upload a batch file of invoices.

Once you have built the file call:

Used for BULK requests

Input

Requests to the web service are sent as strings

Example:

public string BatchFileUpload(string ServiceKey, string File)

Submit the following parameters.

Field Explanation
M1 This would be your Pay Now Service Key
M2 The key issued by Netcash to identify the software origin of transactions. (only used by Netcash ISV‘s else use the default value: 24ade73c-98cf-47b3-99be-cc7b867b3080)
Amount The amount of the invoice in cents
P2 Unique reference for this invoice
P3 Invoice Description
M4 Extra data field 1
M5 Extra data field 2
M6 Extra data field 3
M9 Email of the person you are invoicing
M10 Additional return string data
IgnoreAmount True (call for amount to be paid) False (use amount in barcode)                        *see update value details
M11 Mobile number (ie. 0812345678)
M12 Send SMS (Boolean) – M11 must contain valid data if this field is set to true
M13 Send Email (Boolean) – M9 must contain valid data if this field is set to true
M14 Request credit card token for subscription cards. (Boolean) Default = false                                * see M14 note re QR/POS below

 

  • Request token (M14) is not available/applicable to Masterpass and/or Visa Checkout as the credit card number is stored in the respective application.

 

Updating invoice value

If the invoice/barcode was originally created with IgnoreAmount=true, then sending the invoice call in again will simply update the amount. The minimum send values are M1, M2, Amount, P2, P3 -and IgnoreAmount=true.
Note – Invoice/barcode has to have been created with IgnoreAmount=true. Subsequent calls will not update the IgnoreAmount field if it was not set to true.

 

Successful request

If the method call was successful and the file is being processed, the web service will return a file token which is used to retrieve the load report

Example: 20000000.2550236530.0483.2.2

 

Unsuccessful request

If the method call fails, the web service will return an error code:

Code Description
100 Authentication failure. Ensure that the service key in the method call is correct
102 Parameter error. One or more of the parameters in the string is incorrect
200 General code exception. Please contact Netcash Technical Support.

Input File Structure

Each file has the following mandatory records:

H – Header record identifies the upload and passes instructions to the Netcash server to determine the purpose of the file. K – Key record must follow the header record. The key record describes the transaction records which follow. The format defined in the key record is used to validate the record structure and content. T – Transaction records follow the key record. The fields in the transaction records must conform to the layout defined in the key. F – Footer record must be the last record in the file and confirms that the file is complete.

Header record (H)

Every file must contain a header record as the first record in the file.

Record Structure

Field Name Type Value
1 Record Identifier AN H
2 Service Key AN Pay Now Service Key
3 Version AN 1
4 Instruction AN Purpose of the file
5 Batch name AN Your identifier
6 Action date N CCYYMMDD
7 Software vendor key AN The key issued by Netcash to identify the software origin of transactions. (only used by Netcash ISV‘s else use the default value: 24ade73c-98cf-47b3-99be-cc7b867b3080)

Field explanations

Field Explanation
Record Id “H” – Identifies the record as a header
Service key Pay Now service key
Version “1” – This is the Netcash version of the file specification
Instruction Invoice – upload invoices to the Netcash system
Batch name Use this field as an identifier of your batch.
Action date Current date
Software vendor key The key issued by Netcash to identify the software origin of transactions. (only used by Netcash ISV‘s else use the default value: 24ade73c-98cf-47b3-99be-cc7b867b3080)

Example

H C74EXXX5-5499-4663-85FB-2A6XXXXFB9EF 1 Invoice My Test Batch 20100331 24ade73c-98cf-47b3-99be-cc7b867b3080

Key record (K)

  • The key record is mandatory and must appear in the file between the header record and the transaction records.
  • The key defines the content, order and length of the transactions records in the file. It can be likened to the column headings in a spreadsheet.
  • The key lists allthe possible fields contained in the subsequent transaction records, even if not every transaction record contains data in all the fields.
  • While the file is customizable, it is recommended that keys are listed in ascending numerical order for ease of debugging and support.

Example

K 138 162 165 201 253 254 301 302 303 304

Transaction record (T)

  • There must be at least one transaction record in the file.
  • The transaction records must conform to the order of the fields as described in the key record.
    (In the example above, the account reference (field id 138) is defined as the first field in the record therefore every transaction record MUST have the Budget as the first field or it will fail validation)
  • Every transaction record must have the same number of fields as defined in the key record (K).
  • Empty fields should be replaced by a blank tab or a default value, where one has been defined.
    Where fields are left empty, the Netcash system will assume spaces or zeroes for fields defined in the key record.

Mandatory field

The fields indicated by tick is mandatory for the specified instruction.

See the full API key legend for value requirements

Key Field name Invoice
253 Unique Pay Now reference (p2) required
254 Description of goods (p3) required
162 Amount in cents required
165 Ignore invoice amount
138 Budget required
301 Extra 1 (m4)
302 Extra 2 (m5)
303 Extra 3 (m6)
201 Email address (m9)
304 Additional Accept/Decline text (m10)
202 Mobile number (M11) *requirement
255 Send SMS for Pay Now invoice Y/N (M12)
256 Send Email for Pay Now invoice Y/N (M13)
257 Request token for Pay Now Invoice Y/N (M14)
  • Request token (Key 257) is not available/applicable to Masterpass and/or Visa Checkout as the credit card number is stored in the respective application.

Optional fields

If the optional fields are to be included in the transaction records, they must be specified in the key record (K).

Transaction fields

Field Name Type Value
253 Unique Pay Now reference (p2) AN25 This is a unique reference that you will assign to each transaction. This reference should only ever be USED ONCE.
254 Description of goods (p3) AN50 The description of the goods sent for payment for your internal reference. (* see tip below)
162 Amount in cents N Transactional amount in cent value that is to be settled. (Invoice amount)
165 Ignore Invoice amount AN1 “Y” call for amount to be paid
“N” use the value contained in the barcode
138 Budget A1 “Y” will display the budget option in the card details page
“N” will not display the budget option in the card details page
301 Extra 1 (m4) AN999 This is an extra field that can contain any data that you require back once the settlement has been done.
302 Extra 2 (m5) AN50 This is an extra field that can contain any data that you require back once the settlement has been done.
303 Extra 3 (m6) AN50 This is an extra field that can contain any data that you require back once the settlement has been done.
201 Email address (m9) AN100 Card holders email address should you want an email sent to the cardholder.
304 Additional parameters/text (m10) AN100 Any text sent in this field is returned to the Accept and Decline return URL’s. This is usually used with basket products like OSCommerce and VirtueMart.
202 Mobile number (M11) N11 The cell number to which the payment instruction is to be sent *requirement
255 Send SMS (M12) A1 Send payment instruction via SMS (Y/N) – 202 must contain valid data if this field is set to Y
256 Send Email (M13) A1 Send payment instruction via Email (Y/N) – 201 must contain valid data if this field is set to Y
257 Request token A1 Return credit card subscription token (Y/N)
(Insert ‘Y’ to request a token returned in the postback)
259 Subscription indicator (M16) N1 0 = No subscription (Default) 1 = Log as subscription payment
NOTE: Subscriptions are only valid if the initial transaction is a 3D secure credit card payment
260 Subscription cycle (M17) N Subscription cycle – number of subscription payments to be made
261 Subscription frequency (M18) N Subscription frequency
1          Monthly
2          Weekly
3          Bi-weekly
4          Quarterly
5          Six monthly
6          Annually
262 Subscription start date (M19) N8 Subscription start date CCYYMMDD
263 Subscription recurring amount (M20) N Subscription recurring amount
  • Add the purchaser’s name -and/or the order/invoice number in brackets after the description to easily identify the transaction on your Netcash statement without looking at Pay Now transaction reports.
    • Add the purchaser’s name –and/or the order/invoice number in this field to easily identify the transaction on your Pay Now transaction report, please note – this field does not display on the Netcash statement.
      • Request token (Key 257) is not available/applicable to Masterpass and/or Visa Checkout as the credit card number is stored in the respective application.

Footer record (F)

The footer record indicates that the complete file has been received. It must be the last record in the file. If the record is not present, the system will fail the file without processing any transaction records.

Structure

Field Name Type Value
1 Record Identifier AN F
2 No of transactions N A count of the transaction records
3 Sum of amounts N The sum of the monetary fields (in cents)
4 End-of-file indicator N 9999

Field explanations

Field Explanation
Record Identifier “F” – Identifies the record as a footer
No of transactions This is the count of all the ‘T’ records in the file.
Sum of amounts This is the sum of all the values in the 161 fields.
If field 161 is not specified in the key record, this will be the sum of all the 162 fields.
End-of-file indicator ‘9999’ – Indicates there are no more records.

Example

F 2 0 9999

Example of input file

H C74EXXX5-5499-4663-85FB-2A6XXXXFB9EF 1 Invoice March invoices 20150204 24ade73c-98cf-XXXX-XXXX-cc7b867b3080
K 253 254 162 138 301 302 303 201
T AB001123456 Serial no 56789012 (Inv123456) 150000 Y Jones March Inv123456 ajones@mweb.co.za
T CD001123457 Serial no 23568901 (Inv123457) 155090 N Brown March Inv123457 sbrown@gmail.com
F 2 170090 9999

Output

Method: BatchFileUpload

Retrieving the Load Report

Postback option

Postback has not been activated in this version of the service

Polling option

You will need to request the load report using the file token received from the BatchFileUpload method call.

Using the file token, call:

Requests to the web service are sent as strings

Example:

public string RequestFileUploadReport(string ServiceKey, string FileToken)

 

Output file

File content

Only errors are reported in the file. If all the entries in the file are successfully validated, the Load report header will contain “SUCCESSFUL” and there will be no detail messages.

File structure

The report is tab delimited with a linefeed character as line terminator.

Load report header (occurs once at the start of each load report)

Field Name Type Value
1 Record identifier AN8 ###BEGIN
2 Batch name AN {your batch name}
3 Result of upload A13 SUCCESSFUL / UNSUCCESSFUL / SUCCESSFUL WITH ERRORS
4 Start time of report AN8 HH:MM AM/PM

Load report message (occurs multiple times – once per error record)

Field Name Type Value
1 Unique reference AN25 The unique reference you supplied in (p2)
2 Line number AN Line :{line in your file where error was found}
3 Error message AN The error message
OR
1 Record identifier AN8 ###ERROR
2 Error message AN The error message

Load report trailer (occurs once – the last line in the report)

Field Name Type Value
1 Record identifier AN6 ###END
2 End time of report AN8 HH:MM AM/PM

Retrieving the XML Invoice data

Postback option

Postback has not been activated in this version of the service

Polling option

You will need to request the Invoice file using the file token received from the BatchFileUpload method call.

Using the file token, call:

Requests to the web service are sent as strings

Example:

public string RequestPayNowInvoice(string ServiceKey, string FileToken)

Output file

File content

Returns “FILE NOT READY” if the file is not yet available.

or

Returns all the invoices successfully loaded into the system.

Unpaid reason codes

Click here for a complete list of unpaid reason codes

Payment Request

Read the Pay Now service overview first if you are only integrating the Payment Request service.

Using either the single line item service and/or the batched upload service, your system can create a Pay Now Payment SMS Email request by including the following additional parameters:

Field Name Type Comment
M12 Send SMS Boolean Mobile number (M11) compulsory if this field is used
M13 Send eMail Boolean eMail address (M9) compulsory if this field is used

Pay Now SMS/Email was formerly known as Pay Now Request.

File Structure

<xs:schema attributeFormDefault="unqualified" elementFormDefault="qualified" xmlns:xs="http://www.w3.org/2001/XMLSchema">
  <xs:element name="PayNowInvoices">
    <xs:complexType>
      <xs:sequence>
        <xs:element type="guid" name="ServiceKey"/>
        <xs:element type="xs:string" name="FileToken"/>
        <xs:element name="Invoices">
          <xs:complexType>
            <xs:sequence>
              <xs:element name="Invoice" maxOccurs="unbounded" minOccurs="0">
                <xs:complexType>
                  <xs:sequence>
                    <xs:element type="xs:string" name="ClientReference"/>
                    <xs:element type="xs:string" name="UniqueReference"/>
                    <xs:element type="guid" name="SecurityToken"/>
                    <xs:element name="PaymentMethods">
                      <xs:complexType>
                        <xs:sequence>
                          <xs:element name="PaymentMethod" maxOccurs="unbounded" minOccurs="0">
                            <xs:complexType>
                              <xs:sequence>
                                <xs:element type="paymentTypeEnum" name="Type"/>
                                <xs:element type="xs:string" name="Text"/>
                              </xs:sequence>
                            </xs:complexType>
                          </xs:element>
                        </xs:sequence>
                      </xs:complexType>
                    </xs:element>
                  </xs:sequence>
                </xs:complexType>
              </xs:element>
            </xs:sequence>
          </xs:complexType>
        </xs:element>
      </xs:sequence>
    </xs:complexType>
  </xs:element>


<xs:simpleType name = "paymentTypeEnum">
    <xs:restriction base = "xs:string">
        <xs:enumeration value = "EFT"/>
        <xs:enumeration value = "CreditCard"/>
        <xs:enumeration value = "Retail"/>
        <xs:enumeration value = "QR"/>
    </xs:restriction>
</xs:simpleType>


<xs:simpleType name="guid">
    <xs:restriction base="xs:string">
        <xs:pattern value="[a-fA-F0-9]{8}-[a-fA-F0-9]{4}-[a-fA-F0-9]{4}-[a-fA-F0-9]{4}-[a-fA-F0-9]{12}"/>
    </xs:restriction>
</xs:simpleType>

Testing

See Testing section for more details. If you require any integration assistance contact our technical support team

Netcash may provide example/sample/demo ‘code snippets’ and/or external links in this Technical Document. Such are for guidance purposes only and may not function on every developer’s system/s. Netcash disclaims any and all liability for the usage of guidance resources provided -and you as the Developer; must accept full responsibility for the usage of such. While every possible effort has been taken to ensure compatibility across multiple system configurations, the contents of this document cannot be guaranteed to work on all systems, with all operating systems -and/or with all system configuration/s.

Version 2020.1

Copyright © 2020 Netcash (PTY) Ltd