Pay Now – Billing

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:

• Payment Request
• Pay Now eCommerce
• Pay Now Scan to Pay

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:

• Web service: https://ws.netcash.co.za/NIWS/niws_nif.svc
• Method: BatchFileUpload
• Service key: Pay Now service key

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:

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 explanations

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

^§ 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 explanations

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:

• Web service: https://ws.netcash.co.za/NIWS/niws_nif.svc
• Method: RequestFileUploadReport
• Service key: Pay Now service key

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)

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

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

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:

• Web service: https://ws.netcash.co.za/NIWS/niws_nif.svc
• Method: RequestPayNowInvoice
• Service key: Pay Now service key

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:

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:

• Web service: https://ws.Netcash.co.za/PayNow/PayNow.svc
• Method: CreateInvoice

Single Item Input

Submit the following parameters.

Single Item Output

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

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/invoices.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

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