Introduction
Webhook provides a server-to-server messaging system that facilitates communication regarding various transaction types and agreement-related changes. The service enables your systems to receive notifications about important events such as refunds, voids, or agreement modifications. You have the flexibility to choose the specific transaction types or agreement actions you want to receive messages for. Once selected, the webhook service will deliver relevant information for those actions. These events may include:- Transactions processed through payment processing APIs like Hosted Payment Pages or Remote.
- Manually processed transactions through the Merchant Administration System.
- Agreement-related changes made via the system or API.
Service Configuration
To configure webhook notifications, navigate to the Merchant Administration System and select either the ‘Payment Page’ or ‘Security’ menu, then click on the ‘Transaction Advice’ option. This will display the configuration page, where you can specify the transaction types or agreement actions for which you want to receive notifications. You can also choose to receive messages only for transactions that have been authorised (transaction statusA or H).
📘 Note:You will need to supply the URL that is to be used by the advice service. This URL must use either the HTTP or HTTPS protocol and must be on either port 80 or 443. The connection is a direct server-to-server connection with no browser involvement, so the URL must be accessible over the internet.
If the “Only include authorised transactions (status ‘A’ or ‘H’)” option is not selected, then declined transaction data will also be sent along with authorised entries.
Message Format
Transaction-Related Webhooks
Transaction-related webhooks are sent using the HTTP POST method and contain the following fields:| Field | Description |
|---|---|
invoice_no | Invoice number |
order_id | Order ID |
payment_due_date | Payment due date |
bin_country_name | BIN country name |
first_six_digit_card_no | First six digits of the card number |
transaction_amount | Transaction amount |
transaction_reference_no | Transaction reference number |
transaction_failed_message | Transaction failure message |
transaction_date | Transaction date |
bank_ref_no | Bank reference number |
tracking_id | Tracking ID |
is_active | Is active flag |
created_on | Created timestamp |
updated_on | Updated timestamp |
currency | Currency code |
payer_address | Payer’s address |
payer_country | Payer’s country |
type_of_card | Type of card used |
payer_name | Payer’s name |
card_issuing_bank | Bank that issued the card |
payment_option | Payment option used |
card_name | Name of the cardholder |
eci_value | (ECI) value |
op_transaction_status | OP transaction status |
Transaction Types
Webhook Transaction Statuses
The webhook transaction lifecycle includes various statuses that represent the state of a payment link or transaction at different stages:| Status | Description |
|---|---|
| Initiated | Payment link has been created. |
| null | Status is not yet set or is undefined. |
| Awaited | Waiting for user or system action. |
| Aborted | Transaction was prematurely terminated. |
| Invalid | Invalid request or payload encountered. |
| Success | Payment was successfully completed. |
| Authorized | Payment has been authorized. |
| Confirmed | Payment has been confirmed. |
| Payout | Funds have been processed for payout. |
| Cancelled | Transaction was cancelled by user/system. |
| Failed | Payment attempt failed. |
| Settled | Payment has been settled in the system. |
| Refunded | Payment was refunded to the customer. |
Card Codes
| Code | Card Type |
|---|---|
VC | Visa Credit |
VD | Visa Debit |
| … | (More card types available upon request) |
Message Delivery
Webhook messages are sent immediately after transaction processing or agreement actions. If delivery fails:- A retry will be attempted after a short delay.
- Up to 4 retries will be made, with increasing delay intervals.
- The receiving system must respond with HTTP 200 OK for successful receipt.
Data Security
To authenticate webhook messages, a SHA1 hash check is used with key transaction, card, billing, or agreement fields.Hashing Process
- Concatenate field values using
:as a separator. - Convert percent-encoded characters (e.g.,
%20) to their original characters. - Generate a SHA1 hash of the string.
- Compare with the received hash value.