Once payment is made notification will be sent to the merchant indicating whether the payment was successful or not. The below shows how the notification is sent from the Scan to Pay system as well as how the merchant must respond to the notification to confirm they have received the transaction.



  1. Once a payment is made a notification will be sent to the merchant indicating whether the payment was successful or not.
  2. If the merchant is set up to receive real-time notification an HTTP POST will hit the designated merchant URL.
  3. The payload of the HTTP POST will be a Base64 encoded String if a notification key has been generated for the notification URL. This data needs to be decoded and decrypted using the key created on the Scan to Pay system which is obtained from the Scan to Pay Portal. You will need to be logged on to the Portal with the applicable merchant profile and under the logged on email address dropdown there will be a Notifications button.
  4. The decrypted payload will be a JSON string. The merchant needs to check back if a notification is expected and perform the relevant actions.
  5. Once the merchant is done processing the message a 200 response needs to be returned if the merchant wishes to finalise the payment. Failure to send the 200 response may result in the transaction being rolled back provided the merchant has HTTP real time notification set up. This timeout for sending the 200 is 45 seconds.
  6. If email notification is configured an email will be sent.
  7. If SMS notification is configured an SMS will be sent.

Please note on the Scan to Pay Portal if you add a notification URL and then click the Check button an unencrypted JSON string will be sent as either:

result: TEST

V2 Check: TEST

The actual notification payload on transactions will however be encrypted provided the notification URL has an associated generated notification key.

HTTP Decrypt

The payload of the HTTP POST request is encrypted using a Scan to Pay designated notification key if one has been generated for the notification URL. This has been done for two reasons:

  1. The merchant may have not set up SSL and therefore the data could be transmitted on a non-secure line.
  2. This forces the merchant to verify that the message came from the Scan to Pay system. If the message did not decrypt correctly, it is fake, or the wrong key has been used.

The key can be generated from the Scan to Pay Portal by logging on as a Merchant profile and then clicking on the logged-on email dropdown, and then selecting the Notifications option.

The encryption used is AES/CBC/PKCS5Padding. Please note the IV is set to all nulls (0x00).

Java Decrypt Example:

{"transactionId":4454189,"reference":"81551775_27609000081_13697_16636794098761","amount":110.3300,"currencyCode":"ZAR","status":"SUCCESS","bankResponse":{"retrievalReferenceNumber":730494,"authCode":" DEBUG","bankResponse":"00","bankTxType":"PURCHASE_CNP"},"msisdn":"27609000081","cardInfo":{"cardType":"CHEQUE","binLast4":"522902-6319","accountType":"DEFAULT","cardHolderName":"Test","bin":"522902","last4":"6319"},"merchantId":18888}

The decrypted payload will be a JSON string.

The JSON object looks as follows:

transactionIdLongThis is the Scan to Pay system transaction reference.
referenceStringThis is the merchant’s reference associated to the payment. This is used to tie up the payment of the transaction.
amountBigDecimalThis is the payment amount.
currencyCodeStringThis is the currency of the amount.
statusStringThis is the status of the transaction. HTTP responses that can be expected are:
BankResponseBankResponseThis is the response from the bank. This will only be present if the bank sent a response to the Scan to Pay system.
codeStringThis is numeric code that is displayed below the generated QR code.
cardInfoObjectConsists of:
cardType which can be DEBIT, CREDIT or CHEQUE
binLast4 which consists of the BIN and the last 4 digits of the card in the format 123456-1234
accountType which can be SAVINGS, CURRENT or CREDIT

The bank Response consists of the following:

RetrievalReferenceNumberLongThis is the RRN sent to the bank.
authCodeStringThis is the auth code response from the bank.
bankResponseStringThis is the bank ISO response.

The different statuses that can be expected are as per below:

SUCCESSThe transaction has completed and the bank has sent through a successful response.
FAILEDThe transaction has failed.
CLIENT_CANCELThe customer has cancelled the transaction while trying to pay - Network transaction only.
CLIENT_TIMEOUTThe transaction has timed out and the customer is trying to pay - Network transaction only.
SYSTEM_ERRORThe transaction could not be completed due to a Scan to Pay system error.
TRANSACTION_REJECTEDThe transaction has been rejected by the Scan to Pay system.
BANK_OFFLINEThe transaction failed at the bank - Bank is offline or unavailable.
BANK_REJECTEDThe transaction failed at the bank - Response sent back from the bank for the transaction.
REVERSEDThe transaction has been reversed successfully.
REFUNDEDThe transaction has been refunded successfully.
LIMIT_FAILEDThe transaction has failed as the limit check did not pass.

Sample Notifications

Notification payload with shipping and cardInfo

reference:4e2f5954-9995-4c20-9f16-f18ad2e92456, amount:10.0000,
currencyCode:ZAR, status:SUCCESS,
bankResponse:{retrievalReferenceNumber:229,authCode:123456,bankResponse:00}, code:0437152099,
clientContact:{clientContactId:13,clientId:1,firstName:James,lastName:Smith,country:ZA,emailA ddress:[email protected]},
clientBilling:{clientBillingId:18,clientId:1,alias:Home ,city:Jhb,country:ZA,countrySubdivision:Gauteng,line1:10 Sally Street,line2:Smart Place,postalCode:876767}, clientShipping:{clientShippingId:13,clientId:1,alias:Work,city:Johannesburg,country:ZA,countrySub division:Gauteng,line1:495 Summit Place,line2:Rivonia Road,line3:Morningside,postalCode:2196,recipientName:James Smith,recipientPhoneNumber:27832006283},

Notification payload with shipping, billing and contact suppressed and cardInfo

reference:5c7d7821-7934-49ef-bb11-3383968d0c38, amount:4.0000,
status:SUCCESS,  bankResponse:{retrievalReferenceNumber:277,authCode: DEBUG,bankResponse:00}, code:5114388064, cardInfo:{cardType:CREDIT,binLast4:434196-4664,accountType:CREDIT}}

Notification payload for a reversed transaction:

{transactionId:4071,reference:d21ef033-c62a-4eb5-86a6- 2670cf90bd56,amount:7.0000,currencyCode:ZAR,status:REVERSED,code:0347428061,clientContact :{clientContactId:127,clientId:37,firstName:James,lastName:Smith,country:ZA,emailAddress:ja [email protected],phoneNumber:27832006283},clientBilling:{clientBillingId:261,clientId:37,alias:Hom e,city:TestCity,country:ZA,countrySubdivision:,line1:1  Cottage ,line2:Test,line3:Address,postalCode:2019},clientShipping:{clientShippingId:197,clientId:37,alias: Work,city:TestCity,country:ZA,countrySubdivision:,line1:1  Cottage ,line2:Smith,line3:Line3,postalCode:2188,recipientName:Tesyinf,recipientPhoneNumber:2783123 5555}}

Notification payload for a refunded transaction:

{transactionId:4683,reference:3aa8f9da-d7f6-4338-b329- ee5c28a47545,amount:2.0000,currencyCode:ZAR,status:REFUNDED,originalTransactionId:4680}

Sample Email Notifications

Successful email notification:

Transaction 5415, reference a516dcb7-6825-4333-b758-ed750532af12 for ZAR 4.0000 was Successful, Bank Auth Code 420553.0

cardType CREDIT, binLast4 434196-4664, accountType CREDIT

For a bank rejected transaction the notification should be:

Transaction 2746, reference f47e5f55-8c54-4d6b-9831-1c2cbb1b1c85 for ZAR 4.0000 Failed (Status: BANK_REJECTED).

cardType: CREDIT, binLast4: 434196-4664, accountType: CREDIT