Business Rules

All purchase requests must include either PIN data (if AMT) or 3D-Secure data (if the transaction is 3D-Secure) in order for the purchase request to be sent to the acquirer to then be validated by the card issuer. If AMT, then the PIN data will need to be obtained by using the Scan to Pay PinSecLib libraryAll values/codes must be URL encoded before the lookup request is processed.
All values/codes must be URL encoded before the lookup request is processed.
The response for all requests is always a JSON object.
All requests excluding the VAS menu request must include msisdn.
It is advised that the transaction lookup request is done after every purchase to get the correct status should the integrator not be using a webhook.
The purchase history will show only the last 10 transactions from newest to oldest.
The card used in the purchase request won’t be added to any specific bank issued wallet/app as this may cause conflicts with existing cards in wallets/apps.
Once the code/value lookup is done using the generateTransactionId request, the response will return a transactionId. This transactionId must then be used on the subsequent requests. This will apply to all QR codes/values supported by Scan to Pay.
Depending on the complexity of the code/value that is being looked up it might require extra transactional information. The following info is supported: contact info, shipping info, billing info, extra reference, extra input. Anything more than this will be deemed an unsupported value.
The 3D-Secure URL and merchant information will be returned on the value lookup. These details can be used to perform the 3D-Secure MPI Lookup request to the ACS if required by the card issuer.
On the purchase request the card related information must be passed to Scan to Pay in order to complete the transaction to the acquirer.
The msisdn (mobile number) must be supplied on all purchase and lookup requests. (Support for clientIdentifier has been removed on v4.)
A function to retrieve a VAS menu based on a specific app/wallet has been made available. This allows 3rd parties to support airtime top-ups and bill payments.
In order to support VAS payments, one of more inputs could be required from the consumer. This will be determined by the inputsRequired parameter and the app/wallet supporting this functionality will have to gather this information from the consumer on the front end. A basic VAS payment that contains a reference in the value/URL string may not require an additional inputs.
The inputs required will contain a ref, title, type, defaultValue, regex, regexErrorMessage and a template – this is all dependent on the VAS payment required. This is explained on section 2.1.
An integrator can choose to supply device based data. This is optional and allows the following to be sent: device operating system type, operating system version, app/wallet version, device type, device serial, GPS coordinates, client IP address.
A BIN lookup request can be used to confirm the information required by BIN (first 6 to 8 digits of card).
A webhook can be used on the purchase request which Scan to Pay will send the transaction outcome to once the transaction has been completed. The information sent will be transactionId, reference, amount, currencyCode, code, transaction status, msisdn, clientIdentifier, retrievalReferenceNumber, authCode, bankResponse, date and time.
A Secure Code Lookup request can be used to assist in 3D-Secure processing should an integrator not have full Access Control Server logic implemented already. This request is used in conjunction with a new parameter on the purchaseTransactionId request called secureCodeBasic.