The webhook specification allows you to receive instant notifications about payment status from the payment gateway. A callback object is sent in JSON, similar to what you would get in response to a typical API request. Below is the body of the Payment Gateway webhook.
API ARCHITECTURE: REST
API Method: POST
Endpoint: To be updated on the API settings.
To set up your webhook from the Merchant Portal, navigate to the Profile and Settings, select the API Integrations, and click "Setup Callback". Enter the URL, select the API from the dropdown and hit save.
JSON Request
{
"id": "4f340000-d2d4-bec5-2307-08dc8460d262",
"amount": 50,
"chargedAmount": 50,
"currency": "NGN",
"customerEmail": "[email protected]",
"narration": "Callback transaction",
"status": "Paid",
"transactionRef": "36934683_2338018bd8",
"processorResponse": null,
"createdAt": "0001-01-01T00:00:00",
"paidAt": "2024-06-04T06:37:36.1141504",
"ip": "102.89.46.13",
"paymentType": "Card",
"authorizationObject": null,
"fees": 0,
"meta": "Dev payment, new user"
}
Response
| Field | Type | Description |
|---|---|---|
| id | String | Unique identifier for the transaction. |
| amount | Decimal | The total amount of the transaction |
| chargedAmount | Decimal | The actual amount charged for the transaction. |
| currency | String | The currency in which the transaction is conducted (NGN, USD or GBP). |
| customerEmail | String | Email address of the customer making the transaction. |
| narration | String | A brief description or note about the transaction. |
| status | String | The current state of the transaction. Possible values are Pending, Failed, and Paid. |
| transactionRef | String | Reference code for the transaction, useful for tracking and identification. |
| processorResponse | String | Response from the payment processor. |
| createdAt | DateTime | The timestamp when the transaction was created. |
| paidAt | DateTime | The timestamp when the transaction was done. |
| ip | String | The IP address from which the transaction was initiated. |
| paymentType | String | The method of payment used for the transaction (e.g., Card or BankTransfer). |
| authorizationObject | Obect | Contains details related to the authorization of the transaction, null if not applicable. |
| fees | Decimal | Any fees associated with the transaction, in the smallest unit of the currency. |
| meta | String | Additional metadata about the transaction, useful for custom information. |