Webhook

This is a HTTP callback that sends real-time notfication to a configured URL (endpoint) when specific events occur. Unlike pooling where your system repeatedly calls for updates, webhook notifies your system as soon as an event happens by sending a HTTP POST request to the configured URL.

The specified endpoint must support receiving JSON data via an HTTPS POST request.

Setting Up Webhook

In the "API Key" tab on your dashboard, click on "Add webhook"
You can pass the webhook URL in the request body however, you must enable webhook notification on your portal.
Merchants can override the default webhook URL by passing a webhookUrl field in the request body.
The webhookUrl must start with http or https. If invalid, the request will fail with an error:

If a transaction notification fails to deliver to your webhook endpoint, our retry mechanism ensures delivery. Upon successful receipt, your service should respond with an HTTP 200 code. If any other response is received, the notification is marked as ‘failed’ and retried at intervals.

Webhook Events

Below is a list of webhook events:

Event Name	Description
`transaction.success`	A transaction was successfully completed.
`initiate.authentication`	This returns which payer authetication. mechanism recommends you use for a transaction. (3DS authetication version 1 or 2).
`authenticate.payer`	This notification is sent after the Autheticate Payer process is completed.
`authorization`	This notification is sent after the Authorization or Pay transaction process is completed.
`capture`	This notification is sent after the card Capture process is completed.
`refund.success`	A refund was successfully processed. It includes the outcome of the financial transaction processing.
`update.authorization`	This notification is sent after the Update Authorization process is completed.
`void`	This notification is sent on completeion of a Void transaction operatin.
`verify`	This notification is sent after the Verify transaction process is completed. It will include the outcome of the financial transaction processing.

Request Body:

{
  "cardNumber": "4111111111111111",
  "expiryYear": 50,
  "expiryMonth": 5,
  "cvv": "123",
  "amount": 10000,// The amount is formatted in cents/kobo (e.g., 10000 represents 100.00 in the base currency).
  "email": "[email protected]",
  "currency": "USD",
  "reference": "{{randomString}}",
  "callbackUrl": "https://merchant.com/callback",
  "webhookURL": "httpss://merchantwebhookurl.com" //If passed, and if webhook notification is enabled for merchant 
}

Note:

Webhook needs to be enabled and configured on the dashboard

Response:

{
    "authentication": {
        "threeDS": {
            "status": "Y",
            "eci": "05"
        },
        "threeDS2": {
            "status": "N",
            "challengeIndicator": "04"
        },
        "amount": 100.50,
        "time": "2025-03-17T12:34:56Z",
        "transactionId": "txn_123456789",
        "version": "2.1.0"
    },
    "authorizationResponse": {
        "cardSecurityCodeError": "N",
        "commercialCardIndicator": "Y",
        "date": "2025-03-17",
        "financialNetworkCode": "VISA",
        "financialNetworkDate": "2025-03-17",
        "posData": "123456",
        "posEntryMode": "05",
        "processingCode": "00",
        "responseCode": "00",
        "stan": "123456",
        "time": "12:34:56",
        "transactionIdentifier": "456789123"
    },
    "device": {
        "browser": "Chrome"
    },
    "gatewayEntryPoint": "WEB",
    "merchant": "Merchant_001",
    "order": {
        "amount": 100.50,
        "authenticationStatus": "SUCCESS",
        "chargeback": {
            "amount": 0.00,
            "currency": "USD"
        },
        "creationTime": "2025-03-17T12:00:00Z",
        "currency": "USD",
        "id": "order_987654321",
        "lastUpdatedTime": "2025-03-17T12:45:00Z",
        "merchantAmount": 98.00,
        "merchantCategoryCode": "5411",
        "merchantCurrency": "USD",
        "notificationUrl": "https://merchant.com/webhook",
        "reference": "INV-20250317-001",
        "status": "COMPLETED",
        "totalAuthorizedAmount": 100.50,
        "totalCapturedAmount": 100.50,
        "totalDisbursedAmount": 98.00,
        "totalRefundedAmount": 0.00
    },
    "response": {
        "acquirerCode": "00",
        "acquirerMessage": "Approved",
        "cardSecurityCode": {
            "acquirerCode": "00",
            "gatewayCode": "APPROVED"
        },
        "gatewayCode": "APPROVED",
        "gatewayRecommendation": "PROCEED"
    },
    "result": "SUCCESS",
    "sourceOfFunds": {
        "provided": {
            "card": {
                "brand": "VISA",
                "expiry": {
                    "month": "12",
                    "year": "2027"
                },
                "fundingMethod": "CREDIT",
                "number": "411111******1111",
                "scheme": "VISA",
                "storedOnFile": "YES"
            }
        },
        "type": "CARD"
    },
    "timeOfLastUpdate": "2025-03-17T12:45:00Z",
    "timeOfRecord": "2025-03-17T12:34:56Z",
    "transaction": {
        "acquirer": {
            "batch": 12345,
            "date": "2025-03-17",
            "id": "acq_987654",
            "merchantId": "mid_456789",
            "settlementDate": "2025-03-18",
            "timeZone": "UTC",
            "transactionId": "txn_123456789"
        },
        "amount": 100.50,
        "authenticationStatus": "SUCCESS",
        "authorizationCode": "AUTH123",
        "currency": "USD",
        "id": "txn_123456789",
        "receipt": "RCPT-123456",
        "reference": "INV-20250317-001",
        "source": "WEB",
        "stan": "123456",
        "terminal": "TID12345",
        "type": "PURCHASE"
    },
    "version": "1.0"
}