Pay Now Solutions

Overview

Pay Now is a web service that allows for the generation of payment options on documents( eg. Invoice, Statement, Quotation)  or membership cards, counter displays or Point of Sale or any media where payment options are required. See demo. ^{(Click the options at the bottom to simulate the process)}.

PayNow.svc will be used with the method CreateInvoice (for single invoices). Software that allows for the printing of invoices, statements or quotations that would like to utilize the Pay Now service should use this method. If Should you have multiple invoices/statements/quotations that you would like generated with payment options, please use the batch file upload service

The Pay Now service can also be used to create payment requests which are sent to payers via SMS or email by Netcash.

Please see Payment Request detail below and read more here

Web Service Methods

The list of Netcash web service methods can be found here

Quick Start 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.

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.

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://api.netcash.co.za/xsd/paynowinvoice.xsd

<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="xs:string" name="ServiceKey"/>
        <xs:element type="xs:string" name="FileToken"/>
        <xs:element name="Invoices">
          <xs:complexType>
            <xs:sequence>
              <xs:element name="Invoice">
                <xs:complexType>
                  <xs:sequence>
                    <xs:element type="xs:string" name="ClientReference"/>
                    <xs:element type="xs:string" name="UniqueReference"/>
                    <xs:element type="xs:string" 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="xs:string" name="Type"/>
                                <xs:element type="xs:string" name="Text"/>
                                <xs:element name="Data">
                                  <xs:complexType>
                                    <xs:sequence>
                                      <xs:element name="Entry" maxOccurs="unbounded" minOccurs="0">
                                        <xs:complexType>
                                          <xs:sequence>
                                            <xs:element type="xs:string" name="Name"/>
                                            <xs:element type="xs:string" name="Value"/>
                                          </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:sequence>
          </xs:complexType>
        </xs:element>
      </xs:sequence>
    </xs:complexType>
  </xs:element>
</xs:schema>

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

example: more on Code128C Barcodes

If an error occurred

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

Part 2 – Billing

Read the Pay Now service overview

Introduction

Pay Now Billing is an option allowing parameters are 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.

Technical Information

NIWS_NIF is an asynchronous web service that 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)

Submit the following parameters.

• Request token (M14) is not available for Masterpass and Visa Click to Pay 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 must have been created with IgnoreAmount=true. Subsequent calls will not update the IgnoreAmount field if it was not set to true.

Should you no longer require the payment to be accepted at the pay point; set the amount field to zero (Amount=0). The payer will then be informed that the barcode has expired and he will have to contact the service provider.

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

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 confirm 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}

• 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

• 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
  • 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 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:

• 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)

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:

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