Overview
This document will describe how a Point of Sale device, or any other external system should build a QR code that will be read by all the Netcash supported wallet apps and the Netcash eCommerce. Thus, Netcash allows you to generate one (1) QR code which can be read by any of the supported QR apps. Scan the example below with your own QR app to experience the Point of Sale solution.
The Point of Sale QR product is preferable to the Billing service if the system wants to generate codes without interfacing with the Netcash System in order to lodge and invoice before generating a code.
Netcash supports a variety of mobile wallet applications for the reading of our Point of Sale product. These include but are not only limited to:
More mobile wallet applications are being added and additional coding will not be required from your end if you implement this specification. The new mobile wallet applications will automatically be supported by the Point of Sale product.
See the product overview 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
Point of Sale is a set of rules that need to be followed in order to generate a QR code without the need to call the Netcash Webservice
Input
The base input is a URL as follows
https://paynow.netcash.co.za/Site/PayNowQR.aspx
There after you append the following parameters.
| Name | Description | Required |
| MerchantToken | This would be your merchant token GUID from the retail service in the Netcash backend. |  |
| M2 | Software Vendor Key (SVK). 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 | |
| P2 | Unique reference for this invoice | |
| Extra1 | Extra data field 1* | |
| Extra2 | Extra data field 2 | |
| Extra3 | Extra data field 3 |
* When using the Netcash QR/Pos as in a cash register enabled environment, it is highly advisable to use Extra 1 to define the teller/isle/till. The Extra 1 data is fed back in the Netcash statement for reconciliation purposes.
Using the variables above; you will need to form a URL like the example below in your POS application:
https://paynow.netcash.co.za/Site/PayNowQR.aspx?MerchantToken=MGUID&P2=UniqueREF&Amount=100.00&M2=SVKGUID&Extra1=SomeStuff1&Extra2=SomeStuff2&Extra3=SomeStuff3
Once this has been done, use a QR generator to generate a QR code and print/display this to the customer to read with any one of the Netcash support wallet apps. The URL will require at least the required fields for it to be accepted once the wallet/apps scans the QR.
Example
Failsafe
It is also possible to print an offline (static) code in case there is a connectivity issue. The offline code looks the same as the line above with only the MerchantToken field and no other fields.
https://paynow.netcash.co.za/Site/PayNowQR.aspx?MerchantToken=MGUID
The reason this is good practice is; if bi-directional connectivity is down, the Netcash system would not be able to return the message to the POS system. In this case you could write the offline code to the slip which will then return the message to an email and/or a mobile SMS number and still allow the transaction to take place. One could also keep sending the full code and look up the response via the mobile app or the Netcash website in the statement as an alternative solution.
Example
Notification
Notification of transactions will be sent via email and/or SMS as per the Token setup.
Upfront Request
The Pay Now service also allows a vendor to request payment directly from a device, by sending an SMS/eMail to the client. This means that for instance where delivery takes place, the POS system can generate a payment request to the client and receive instant feedback of payment status as if the customer scanned the QR code.
Refer to the Pay Now Request API
Notify page
After the transaction is complete the following data is returned to these respective pages which were configured in the Pay Now configuration. It is highly advisable that all developers reconcile (indicate payment status) from the data sent to the NOTIFY url.
This URL is called for all transactions asynchronously. Unlike Instant EFT and Credit Card services, services like Retail, QR and Bank EFT do not call the Accept and Decline URL, however all the services do send notification to the Notify URL.
There is also a retry plan built into the Notify URL allowing to retry a number of times before it being noted as not received.
This should be utilised for system updates whereas Accept and Decline URL’s should be used to synchronously update the caller on the status of the transaction.
Notify URL
| Field No: | Field Name: | Alpha / Numeric / Boolean | Description: |
|---|---|---|---|
| 1 | TransactionAccepted | B | “true” means the transaction was successful |
| 2 | CardHolderIpAddr | AN | This is the original IP the request was made from |
| 4 | Reference | AN | This is the unique reference that you sent Netcash in the original request |
| 5 | Extra1 | AN | This is the extra field you sent up in the request that we return for you to integrate into your own system. |
| 6 | Extra2 | AN | This is the extra field you sent up in the request that we return for you to integrate into your own system. |
| 7 | Extra3 | AN | This is the extra field you sent up in the request that we return for you to integrate into your own system. |
| 8 | Amount | N | This is the amount that you sent Netcash in the original request |
Testing
See Testing section for more details. If you require any integration assistance contact our technical support team
Version 2020.1
Copyright © 2020 Netcash (PTY) Ltd