When the payment process, facilitated on the instaPay® WebPay gateway, is completed, a notification message is sent to the website/e-commerce platform URL. A notification URL must be provided for the notification to be sent. The notification URL can either be specified on the Check-out form, or a default notification URL can be specified when the website/e-commerce platform is registered on the InstaPay Money Manager portal.
Once the website/e-commerce platform receives the notification response message, several steps need to be completed to verify the validity of the data in the message.
Notification message layout
The following table specifies the information returned from instaPay® WebPay gateway to the e-commerce webserver as part of the payment notification:
| Field name | Format | Presence | Description |
|---|---|---|---|
Merchant (Payee) details |
|||
|
payeeSiteId |
string(20) |
M |
The unique Site ID as per the WebPay website regsitration on the InspaPay Money Manager portal. |
|
payeeUuid |
string(36) |
M |
The Merchant’s member UUID as per the account settings on the InstaPay Money Manager portal. |
|
payeeAccountUuid |
string(36) |
M |
The Merchant’s account UUID as per the account settings on the InstaPay Money Manager portal where the payment is intended to be settled.
|
|
payeeRefInfo |
string(36) |
M |
The unique transaction reference as provided in the check-out form. |
|
payeeCategory1 |
string(50) |
O |
Custom field (1) to categorise the transaction |
|
payeeCategory2 |
string(50) |
O |
Custom field (2) to categorise the transaction |
|
payeeCategory3 |
string(50) |
O |
Custom field (3) to categorise the transaction |
|
payeeSiteName |
string(100) |
O |
Custom field to identify the site / location / subsystem where the transaction originated from |
|
payeeSiteReference |
string(36) |
O |
Custom field used to provide a site / location / subsystem related reference |
|
payeeOrderNr |
string(20) |
M |
A unique order number used by the consumer/payer as a reference for the order on the e-commerce platform.
The first 3 characters MUST be set to the Merchant Short/Routing Code. The remaining 17 characters should be unique within the Merchant’s system |
|
payeeOrderItemName |
string(60) |
M |
Custom field to name the item(s) being ordered (e.g. ‘basket of goods’) |
|
payeeOrderItemDescription |
string(60) |
M |
Custom field to describe the item(s) being ordered |
|
payeeInvoiceNr |
string(50) |
O |
Custom field to specify the invoice number as per the e-commerce platform accounting system |
Payer/Buyer details |
|||
|
payerName |
string(80) |
O |
The payer/buyer’s first names. |
|
payerSurname |
string(80) |
O |
The payer/buyer’s surname. |
|
payerEmail |
string(80) |
O |
The payer/buyer’s email address. |
|
payerMobile |
string(15) |
O |
The payer/buyer’s mobile number. |
Request details |
|||
|
requestTokenId |
string(10) |
M |
The token identifier allocated to the payment request. |
|
requestAmount |
decimal(33,2) |
M |
Amount requested through the instaPay® Gateway platform. |
|
requestCurrency |
string(3) |
M |
The currency code of the requested amount |
|
requestStatus |
string(enum) |
M |
The status of the payment request on the instaPay® Gateway platform.
Valid values:
– COMPLETED
– EXPIRED
– PENDING
– CANCELLED
|
Payment details |
|||
|
paymentSystemReference |
string(36) |
C |
The payment system reference received from the server. Only specified if requestStatus field is COMPLETED, EXPIRED or CANCELLED. |
|
paymentAmount |
decimal(33,2) |
C |
Amount paid through the instaPay® WebPay gateway platform. Only specified if requestStatus previous status field is COMPLETED. |
|
paymentCurrency |
string(3) |
C |
The currency code applicable to the payment that was received (ISO4217) |
|
paymentDateTime |
string(20) |
C |
The date and time when payment was made.
(ISO8601 yyyy-mm-dd hh:mm:ss)
|
|
paymentType |
string(enum) |
C |
The type of payment that was made on the platform.
Valid values:
– DEPOSIT
– RECEIPT |
|
paymentMethod |
string(enum) |
C |
The payment method that was used on instaPay® WebPay to make the payment.
Valid values:
– CARD
– CARD_AMEX
– CARD_CREDIT
– CARD_DEBIT
– CARD_DINERS
– CARD_INT
– CASH
– CASH_WALLET
– DEFAULT
– EFT_INSTANT
– HAPPYPAY
– SNAPSCAN
– VOUCHER
– ZAPPER |
Subscription payment details |
|||
|
subscriptionFrequency |
string(enum) |
C |
EVERY, every so many days. 1 being every day, 2 being every 2nd day, and 30 being every 30 day. |
|
subscriptionCollectionDay |
integer(3) |
C |
The day, based on the frequency, the subscription was collected. |
|
subscriptionStartDate |
string(255) |
C |
The start date of the subscription.
(UTC Date – ISO8601 yyyy-mm-dd) |
|
subscriptionEndDate |
string(255) |
C |
The end date of the subscription.
(UTC Date – ISO8601 yyyy-mm-dd) |
|
subscriptionAccountNumber |
string(255) |
C |
Content |
Security check |
|||
|
checksum |
string(50) |
M |
Calculated hash value based on predefined field values and a security key to enable data integrity verification. </br> |
Confirm receipt of notification response
Upon receiving the payment notification response from instaPay® WebPay gateway, a 200 OK should be returned to prevent instaPay® WebPay gateway from further retries – if no 200 OK response is returned the notification will be re-sent a few times.
Verify Data Integrity
When the payment notification message is received from instaPay® WebPay gateway, several security checks should be conducted to verify the integrity of the data:
1. Verify the source of the received notification message
Only notification messages from the following IP addresses should be accepted:
- 102.212.37.50
- 102.67.176.33
- 102.67.176.34
- 102.67.176.35
- 102.67.176.36
- 102.67.176.37
- 102.67.176.38
Information from unknown sources (domains) should be rejected.
2. Check that data exists
This is just a simple check to determine if the data that is expected exists.
3. Verify the received checksum
The received payment notification message contains a MD5 hash checksum that must be used to validate the data integrity of the received message.
To verify the the received checksum, its value is compared with an expected checksum that is calculated by concatenating specific received field values in a predefined order, using an underscore (_) as separator.
The Security key, created when the WebPay configuration is done on the InstaPay Money Manager portal, is appended to the string and then passed through an MD5 hash algorithm to produce the checksum.
The following fields are used:
| Payment notification field | Order | Description |
|---|---|---|
|
payeeUuid |
1 |
Merchant UUID received on the payment notification message. |
|
payeeAccountUuid |
2 |
Merchant Account UUID received on the payment notification message. |
|
payeeRefInfo |
3 |
The unique Transaction Reference received on the payment notification message. |
|
requestAmount
(converted to cents) |
4 |
The Requested Amount received on the payment notification message in cents (e.g. R4.87 in cents is 487). |
|
requestCurrency |
5 |
The Requested Currency received on the payment notification message. |
|
Security key |
6 |
Security key for the WebPay configuration as per InstaPay Money Manager portal for involved website. |
The string used for the MD5 hash should be in the following formats:
{payeeUuid}_{payeeAccountUuid}_{payeeRefInfo}_{requestAmount_in_cents}_requestCurrency_{Security key}
If the expected checksum (calculated above) does not match the checksum received in the payment notification message, the payment notification should be rejected.
4. Validate payment notification data
Several fields that are received back in the notification response from the instaPay® WebPay gateway, can be compared to the internal data that was used to submit the original request form. The following list provides a mapping between the notification response fields and the internal data. These values can be compared and should be equal. Should any value comparison fail, the data should be rejected:
| Description | Payment notification field | Description |
|---|---|---|
|
Merchant’s (payee) unique identifier (UUID) |
payeeUuid |
Must be equal to the Merchant UUID as per the InstaPay Money Manager portal. This is a static value that is created during the registration process and specified with ‘m_uuid’ on the request form submitted to the instaPay® WebPay gateway |
|
Merchant’s (payee) account identifier (UUID) |
payeeAccountUuid |
Must be equal to the Merchant’s account UUID as per the InstaPay Money Manager portal. This is a static value that is created during the registration process and specified with ‘m_account_uuid’ on the request form submitted to the instaPay® WebPay gateway and is equal to the Merchant’s UUID for the current implementation. |
|
Unique Transaction Reference |
payeeRefInfo |
Must be equal to the unique transaction/order reference dynamically created by the e-commerce platform per transaction and specified with ‘m_tx_order_nr’ on the request form submitted to the instaPay® WebPay gateway |
|
Transaction Amount |
requestAmount |
Must be equal to the transaction/order amount of the involved transaction as specified with ‘m_tx_amount’ on the request form submitted to the instaPay® WebPay gateway. It is best to convert compared values to an integer to eliminate decimal errors. |
|
Transaction Currency |
requestCurrency |
Must be equal to the currency of the involved transaction as specified with ‘m_tx_currency’ on the request form submitted to the instaPay® WebPay gateway. |
5. Verify that the transaction status is not in a final status
If a transaction/order on the website/e-commerce platform has already been processed and put into a final status (e.g., ‘completed’ or ‘cancelled’) then no further processing should be done. This could typically happen when the notification response received from instaPay® WebPay gateway is sent multiple times.