Notifications

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:

The bank Response consists of the following:

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

Sample Notifications

Notification payload with shipping and cardInfo

{transactionId:841,
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},
cardInfo:{cardType:CREDIT,binLast4:434196-4664,accountType:CREDIT}}

Notification payload with shipping, billing and contact suppressed and cardInfo

{transactionId:2742,
reference:5c7d7821-7934-49ef-bb11-3383968d0c38, amount:4.0000,
currencyCode:ZAR,
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