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.
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": "TEST_REF",
"paymentReference": "TRNPAY-89BF0BF3-1F0B-23D7-B45D-F3AF5367CBF8",
"productName": "Collection",
"totalAmountCharged": 50,
"orderAmount": 50,
"statusId": 5,
"status": "Successful",
"paymentMethod": "Pay With Bank Transfer",
"paymentResponseCode": "00",
"paymentResponseMessage": "Bank transfer received successfully",
"narration": "Payment for services",
"remarks": "Order initiated and created successfully",
"currencyId": 1,
"currencyName": "NGN",
"fee": 0.75,
"feeRate": 0.75,
"subsidiaryFee": 0.75,
"customerFee": 0,
"dateCreated": "2025-07-29T12:06:19.6933333",
"dateUpdated": "2025-07-29T12:07:27.556023",
"datePaymentConfirmed": null,
"orderPayments": [
{
"orderId": 886488,
"orderPaymentReference": "PGW-PAYREF-BAD747F1339942D9BBC66D1FB03C1336",
"paymentOptionId": 6,
"paymentOption": "Pay With Bank Transfer",
"statusId": 5,
"status": "Successful",
"responseCode": "00",
"responseMessage": "Bank transfer received successfully",
"orderPaymentInstrument": "6849322524",
"remarks": "Order payment initiated",
"dateCreated": "2025-07-29T12:06:22.3706573",
"dateUpdated": "2025-07-29T12:07:27.5561286"
}
],
"customer": {
"customerId": "[email protected]",
"firstName": "FirstName",
"lastName": "LastName",
"emailAddress": "[email protected]",
"countryShortName": "NG",
"customerGroup": "Default",
"countryId": 1,
"globalStatusId": 2,
"globalStatus": "Active",
"mobileNumber": "123456890",
"isBlacklisted": false,
"reasonBlacklisted": null,
"dateCreated": "2025-06-26T09:34:46.7266667",
"dateUpdated": null
},
"cardDetails": [],
"paymentLink": null
},
"status": "success",
"statusCode": "00",
"message": "Order details fetched successfully"
}- Reserved Account Funding Webhook
{
"statusCode": "00",
"status": "Success",
"orderReference": null,
"paymentReference": "ACCTBTCEDCE48E-F9D0-4BEF-AECD-0F8D6501382A",
"productName": "Account Funding",
"totalAmountCharged": 100.000000,
"statusId": 5,
"paymentMethod": "Bank Transfer",
"paymentResponseCode": null,
"paymentResponseMessage": null,
"narration": "Testing Narration",
"remarks": null,
"currencyId": 1,
"currencyName": "NGN",
"fee": 0.3900,
"feeRate": null,
"dateCreated": "2025-08-12T08:37:07.6224086",
"dateUpdated": "2025-08-12T08:37:07.7904547Z",
"datePaymentConfirmed": "2025-08-12T08:37:07.6224086",
"sessionId": "000023250812093659004167457861",
"sourceAccountName": "TEST ACCOUNT NAME",
"orderPayments": [
{
"orderId": 0,
"orderPaymentReference": null,
"paymentOptionId": 0,
"paymentOption": null,
"statusId": 0,
"paymentStatus": null,
"responseCode": null,
"responseMessage": null,
"orderPaymentInstrument": "01234567890",
"remarks": null,
"dateCreated": "0001-01-01T00:00:00",
"dateUpdated": null
}
],
"customer": null,
"cardDetails": null,
"paymentLink": null,
"bank": "",
"accountReference": "accountReference"
}- Payout Webhook
{
"Data": {
"PayoutReference": "PGW-PAYOUT-F8AECDB77C27492AADB2E16C4EACB131",
"ProductName": "Payout",
"Amount": 198.10,
"StatusId": 5,
"Status": "Successful",
"PayoutResponseCode": "00",
"PayoutResponseMessage": "Transaction successful",
"Narration": "Payout",
"Currency": "NGN",
"Fee": 0.000000,
"DateCreated": "2025-08-20T08:15:58.3406864",
"DateUpdated": "2025-08-20T08:16:00.0152206+00:00",
"SessionId": "000000290820091705431005082045"
},
"Status": "Success",
"StatusCode": "00",
"Message": "Payout Successful"
}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.