Business Rules

A username and password must be used to authenticate all requests to the API.
All requests must be sent over HTTPS.
All requests use HTTPS digest authentication. For merchants, the username is a merchant-{merchant id}, for example, merchant-25. For PSPs, the username is PSP-{merchant id} - example PSP-13, where 13 is the merchant Id that is present on the Scan to Pay Portal.
The API username and password are available from the Scan to Pay Portal under the API tab.
Content-Type must be set to application/JSON.
The REST API can also be implemented for In-App or App-to-App scenarios. For App to App refer to section 10.
Once a transaction has been performed a notification will be sent from the Scan to Pay system to the merchant/PSP. The merchant/PSP must then accept the notification. Failure to accept the notification will result in the transaction possibly being reversed. Refer to section 9.
At the time the merchant registers for the Scan to Pay service via the Portal or is registered as a Scan to Pay merchant the following information will be provided:
a. Merchant name
b. Merchant admin URL (or integrator’s admin URL)
c. Merchant address information
d. Merchant phone and contact information
e. Merchant checkout brand information
The currency code is linked to a merchant at the time of creation and this will be used for all payments via the Scan to Pay service.
If a unique merchant reference is not sent on the request this will result in an error.
Unless otherwise specified the field lengths for all the parameters are determined by the parameter types.
A cardInfo object will be sent on the HTTP notification payload as well as email notifications on bank successful and unsuccessful responses. The cardInfo consists of the card type, the card BIN and last 4 digits as well as the account type used for the card in the transaction.
The limitBasket parameter on the create code and update code requests can be set to check a limit if the itemType is AIRTIME or AIRTIME_BUNDLE and the destination mobile number is sent. The merchant must be enabled for limits; failure to do this will result in an HTTP validation error. If the limit check fails on any of the basket items a LIMIT_FAILED status will be returned on the notification. Limits can only be used if the code is a useOnce code and are applied as per below:
a. DAILY: AIRTIME: 1000
b. AIRTIME_BUNDLE: 2000 MONTHLY:
c. AIRTIME: 2000
d. AIRTIME_BUNDLE: 5000
The create code requests allows you to now include the following:
a. Sub-merchant name
b. Alternate terminal id or application id per code
c. SMS and email notifications per code
d. Request partial payment
e. Request tip