Webhooks allow your system to receive real-time updates from our platform when important events happen — such as a payment being completed or a customer funding a reserved account.
You can configure a webhook URL on your dashboard by heading to Settings > Developer > Webhooks and specifying a default endpoint. Once set, we’ll send a POST request to this URL for events triggered on your account.
How It Works
- When a transaction or event occurs, we send a POST request to your webhook URL with a JSON payload describing the event.
- Your server should return a 200 OK response to acknowledge receipt.
Securing Webhooks
To verify that webhook requests came from us, inspect the public key sent in the request headers and compare it against your public key.
Testing Webhooks Locally
Use tools like:
To expose your local server to receive webhook requests from our platform.
Event Payloads
Each webhook payload includes a Status, StatusCode, and a nested Data object containing the event-specific information.
Common Fields
| Field | Description |
|---|---|
| OrderReference | Reference for the payment order |
| PaymentReference | Unique reference for the payment |
| ProductName | Type of product being paid for |
| Status | Transaction status (Successful, Failed, Pending) |
| PaymentMethod | E.g., Card Payment, Pay With Bank Transfer |
| TotalAmountCharged | Amount paid |
| CurrencyName | Usually NGN |
| Fee | Total fees applied |
| Customer | Object with customer details |
| OrderPayments | Array of payment records |
| CardDetails | Array of card metadata (for card payments) |
Sample Payloads
- Card Payment Collection Webhook
{
"Data": {
"OrderReference": "11690084",
"PaymentReference": "TRNPAY-19123160-65F8-4261-8EA2-E9ADE2D34A4E",
"ProductName": "Collection",
"TotalAmountCharged": 25.0000,
"StatusId": 5,
"Status": "Successful",
"PaymentMethod": "Card Payment",
"PaymentResponseCode": "00",
"PaymentResponseMessage": "Transaction was completed successfully",
"Narration": "11690084",
"Remarks": "Order initiated and created successfully",
"CurrencyId": 6,
"CurrencyName": "NGN",
"Fee": 1.0600,
"FeeRate": 1.0600,
"SubsidiaryFee": 1.0600,
"CustomerFee": 0.0000,
"DateCreated": "2025-03-25T16:24:12.61",
"DateUpdated": "2025-03-25T16:24:16.3514292",
"DatePaymentConfirmed": null,
"OrderPayments": [
{
"OrderId": 527349,
"OrderPaymentReference": "PGW-PAYREF-BD99FF0C18C74C82123B8A8D4AA7EDA6",
"PaymentOptionId": 2,
"PaymentOption": "Card Payment",
"StatusId": 5,
"Status": "Successful",
"ResponseCode": "00",
"ResponseMessage": "Transaction was completed successfully",
"OrderPaymentInstrument": null,
"Remarks": "Order payment initiated",
"DateCreated": "2025-03-25T16:24:12.7522727",
"DateUpdated": "2025-03-25T16:24:16.3514971"
}
],
"Customer": {
"CustomerId": "[email protected]",
"FirstName": "FirstName",
"LastName": "LastName",
"EmailAddress": "[email protected]",
"CountryShortName": "NG",
"CustomerGroup": "Default",
"CountryId": 1,
"GlobalStatusId": 2,
"GlobalStatus": "Active",
"MobileNumber": "2146059032",
"IsBlacklisted": false,
"ReasonBlacklisted": null,
"DateCreated": "2024-11-26T00:28:43.05",
"DateUpdated": null
},
"CardDetails": [
{
"OrderPaymentId": 516443,
"Status": true,
"Country": "NG",
"CardToken": "CardToken",
"CardExpiryMonth": "01",
"CardExpiryYear": "99",
"CardType": "VISA",
"CardIssuer": "VISA",
"CardFirstSixDigits": "123456",
"CardLastFourDigits": "7890",
"DateCreated": "2025-03-25T16:24:16.3574835",
"AppEnvironmentId": 2
}
],
"PaymentLink": null
},
"Status": "success",
"StatusCode": "00",
"Message": "Order details fetched successfully"
}- Bank Transfer Collection Webhook
{
"Data": {
"OrderReference": "7838651",
"PaymentReference": "TRNPAY-04285495-5468-45CA-B83B-6D2F4327773C",
"ProductName": "Collection",
"TotalAmountCharged": 2000.0000,
"StatusId": 5,
"Status": "Successful",
"PaymentMethod": "Pay With Bank Transfer",
"PaymentResponseCode": "00",
"PaymentResponseMessage": "Bank transfer received successfully",
"Narration": "Test Bank Transfer",
"Remarks": "Order initiated and created successfully",
"CurrencyId": 1,
"CurrencyName": "NGN",
"Fee": 26.0000,
"FeeRate": 26.0000,
"SubsidiaryFee": 26.0000,
"CustomerFee": 0.0000,
"DateCreated": "2025-04-05T04:58:41.57",
"DateUpdated": "2025-04-05T05:00:36.5814965",
"DatePaymentConfirmed": null,
"OrderPayments": [
{
"OrderId": 1234,
"OrderPaymentReference": "PGW-PAYREF-EDF015F3D4944267BC5474143047657F",
"PaymentOptionId": 2,
"PaymentOption": "Card Payment",
"StatusId": 5,
"Status": "Successful",
"ResponseCode": "00",
"ResponseMessage": "Bank transfer received successfully",
"OrderPaymentInstrument": "6857813711",
"Remarks": "Order payment initiated",
"DateCreated": "2025-04-05T04:58:45.8383804",
"DateUpdated": "2025-04-05T05:00:36.5815789"
}
],
"Customer": {
"CustomerId": "[email protected]",
"FirstName": "FirstName ",
"LastName": "LastName ",
"EmailAddress": "[email protected]",
"CountryShortName": "NG",
"CustomerGroup": "Default",
"CountryId": 1,
"GlobalStatusId": 2,
"GlobalStatus": "Active",
"MobileNumber": "07012345678",
"IsBlacklisted": false,
"ReasonBlacklisted": null,
"DateCreated": "2025-04-05T03:57:37.85",
"DateUpdated": null
},
"CardDetails": [],
"PaymentLink": null
},
"Status": "success",
"StatusCode": "00",
"Message": "Order details fetched successfully"
}- Reserve Account Funding Webhook
{
"StatusCode": "00",
"Status": "Success",
"OrderReference": null,
"PaymentReference": "ACCTBT512B9C84-6C1E-423D-A1D8-7864DB350400",
"ProductName": null,
"TotalAmountCharged": 10.000000,
"StatusId": 5,
"PaymentMethod": null,
"PaymentResponseCode": null,
"PaymentResponseMessage": null,
"Narration": null,
"Remarks": null,
"CurrencyId": 1,
"CurrencyName": "NGN",
"Fee": null,
"FeeRate": null,
"SubsidiaryFee": null,
"CustomerFee": null,
"DateCreated": "2025-03-19T15:29:52.4532192",
"DateUpdated": "2025-03-19T16:29:52.6354358Z",
"DatePaymentConfirmed": "2025-03-19T15:29:52.4532192",
"SessionId": "100001250317153130129110404311",
"SourceAccountName": "ACCOUNT NAME",
"OrderPayments": [
{
"OrderId": 0,
"OrderPaymentReference": null,
"PaymentOptionId": 0,
"PaymentOption": null,
"StatusId": 0,
"PaymentStatus": null,
"ResponseCode": null,
"ResponseMessage": null,
"OrderPaymentInstrument": "9020049811",
"Remarks": null,
"DateCreated": "2025-03-19T00:00:00",
"DateUpdated": null
}
],
"Customer": null,
"CardDetails": null,
"PaymentLink": null,
"Bank": "BANK NAME",
"AccountReference": null
}Expected Response
Expected Webhook ResponseHTTP/1.1 200 OK
You can include a response body, but it will be ignored.
Tips
- Use a queue system to process heavy webhook logic asynchronously.
- Log webhook requests for debugging.
- Respond quickly to avoid timeouts.