Integration Guides

Business Rules

Suggest Edits

  1. A username and password must be used to authenticate all requests to the API.

  2. All requests must be sent over HTTPS.

  3. All requests use HTTPS authentication. For merchants the username is merchant-{merchant id}`, 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.

  4. The API username and password are available from the Scan to Pay Portal under the API tab.

  5. Content-Type must be set to application/json on all requests.

  6. The following must be done in order to successfully implement the REST API:
    a. Perform a createTx API request
    b. Implement a redirect after the createTx call to the redirectUrl from the response received back on createTx
    c. Implement a callback that was specified in the API request
    d. Implement the Notification API (section 6) to receive the payment confirmation and transaction details

  7. The createTx request can be sent with or without additional basket information.

  8. If the createTx request fails the redirectUrl will not be sent on the response.

  9. If a unique reference is not sent on the createTx request this will result in an error.

  10. The REST API can be implemented for Web and Mobi transactions. The user will either visit the Web or Mobi site on their device which has the Scan to Pay app installed. They then must click on “Tap to open the app” when the QR code is displayed – this will then invoke the Scan to Pay app. This process only works on the Android and iOS versions of the Scan to Pay app.

  11. Once a transaction is performed a notification will be sent from the Scan to Pay system to the merchant/PSP. The merchant/PSP must then acknowledge this notification. Failure to do this will result in the transaction being reversed. Refer to section 6 on Notifications.

  12. 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 URL
    c. Email address that the Portal access will be granted to

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

  14. Unless otherwise specified the field lengths for all the parameters are determined by the parameter types.

  15. The cardInfo parameter 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, cardholder name, the card BIN (first 6 digits) and last 4 digits as well as the account type used for the card in the transaction.

  16. The cartItems parameter on the createTx request can be set to check a limit if the itemType is AIRTIME or AIRTIME_BUNDLE and the destination mobile number is sent; AIRTIME_BUNDLE refers to both SMS and Data/Internet Bundles. The merchant must be enabled for limits; failure to do this will result in a FAILED error on the createTx request. If any of the limit checks fail on the cartItems a LIMIT_FAILED status will be returned on the notification. Limits are applied as per below:
    a. DAILY AIRTIME = 1000
    b. DAILY AIRTIME_BUNDLE: 2000
    c. MONTHLY AIRTIME: 2000
    d. MONTHLY AIRTIME_BUNDLE: 5000

  17. If the merchant is operating as a super merchant there is an option to populate the subMerchantName, Merchant Category Code and Terminal ID of the sub-merchant related to the main merchant – these are all optional fields.

Updated about 2 years ago