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 / the type of Payment Event
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": "CustomerId@transactpay.ai",
            "firstName": "FirstName",
            "lastName": "LastName",
            "emailAddress": "CustomerId@transactpay.ai",
            "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": "test@gmail.COM",
      "firstName": "FirstName",
      "lastName": "LastName",
      "emailAddress": "test@gmail.com",
      "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 Response
HTTP/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.