Before you start

Please download the suggested API integration process flow document and use it as a reference when developing.
Kindly adhere to the Netcash brand guidelines when developing.

Programmers Guide

Refer to our Programmers guide for more detail on how to apply the required methodology in this document.
Ensure that the settings for developers are adhered to before you proceed with your implementation.

Web Service Methods

The list of Netcash web service methods can be found here.

Quick Start Guides

Quick Start Guides will help you understand this service and get you started.

Overview

Pay Now Billing is an option allowing parameters to be sent to Netcash via a Web Service in a batch file upload using ‘NIWS_NIF’ creating 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.

Also see:

Batched upload service

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 the file is built, call:

Input

Requests to the web service are sent as strings

Example: public string BatchFileUpload(string ServiceKey, string File)

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. These fields 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, being 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 and transaction records.
  • It defines the content, order and length of the transactions records in the file. It can be likened to the column headings in a spreadsheet.
  • All the possible fields contained in the subsequent transaction records are listed, even if not every transaction record contains data in all the fields listed.
  • It is good practice to list keys in ascending order to assist where debugging and support are required.

 

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 fields

The fields indicated by are mandatory for the specified instruction.

See the full API key legend for value requirements

Key Field name Invoice
253 Unique Pay Now reference (p2)
254 x Description of goods (p3)
162 Amount in cents
138 Budget

x 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 referencing Pay Now transaction reports.

 

Optional fields

If 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
165 Ignore Invoice amount AN1 “Y” call for amount to be paid
“N” use the value contained in the barcode
201 Email address (m9) AN100 Card holders email address should you require an email sent to the cardholder.
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)
258 Credit card token (M15) A1 Return credit card subscription token (Y/N)
(Insert ‘Y’ to request a token returned in the postback)
301§ Extra 1 (m4) AN999 Extra field that can contain any data to be returned once the settlement has been done.
302 Extra 2 (m5) AN50 Extra field that can contain any data to be returned once the settlement has been done.
303 Extra 3 (m6) AN50 Extra field that can contain any data to be returned once the settlement has been done.
304 Additional parameters/text (m10) AN100 Any text sent in this field is returned to the Accept and Decline return URL’s.
Normally used with basket products like OSCommerce and VirtueMart.

§ 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, 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 amount 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	20150204	24ade73c-98cf-XXXX-XXXX-cc7b867b3080
K	253	254	162	138	301	302	303	201
T	AB001123456	Serial no 56789012	150000	Y Jones	March Inv123456	ajones@mweb.co.za
T	CD001123457	Serial no 23568901	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)

 

XML 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.

 

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>

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

Single line item service

This web service allows a user to generate an invoice and receive a reference in return to print on the invoice.  Any software that allows for the printing of invoices that one would like to be paid using Netcash’s Pay Now service and are producing invoices on a single invoice at a time basis should use this method. If you have multiple invoices that you would like generated please use the batched file upload service to do this same task.

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

Technical Information

This is an online, synchronous web service that 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:

Single Item Input

Submit the following parameters.

 

Service key Account service key issued by Netcash
M1 This would be your merchant Service Key
M2 Software Vendor Code
Amount The amount of the invoice
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 Boolean (True call for amount to be paid) (False use amount in barcode)
M11 Mobile number
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

Single Item Output

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

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/netcash/xsd/paynowinvoice.xsd

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

Retail Barcode

The retail payment section renders a barcode string that needs to be formatted in the following way:

Barcode standard: Code128C
Image type: SVG_VML
Image width: 400px
Image height: 50px
ExampleCode128C Barcode example<< Human readable text here >>

Unpaid reason codes

Click here for a complete list of unpaid reason codes

Netcash brand guidelines

Please refer to the Netcash brand guidelines here when using any logos, images, icons, labels, descriptions, and references to Netcash in your software.

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.