Webhooks

Introduction

Webhooks serve as a vital communication channel between the payment gateway and the merchant, providing real-time updates on transaction statuses and events. When certain events occur, such as successful payments or transaction failures, the payment gateway sends HTTP POST requests to URLs specified by the merchant. These requests contain pertinent information about the event, allowing merchants to react promptly and programmatically to various transaction scenarios.

Decrypting and Verifying the Web-hook

To decrypt and process web-hook payloads, merchants can utilize decryption methods outlined in the payment gateway documentation. As highlighted previously, responses from the payment gateway are encrypted using the following algorithms AES-256-GCM. Merchants should implement decryption functions in their server-side applications to securely decrypt webhook payloads and extract relevant details such as transaction IDs, statuses, and metadata.

Sample Response

Field	Description
order_id	The unique identifier assigned to the transaction order, facilitating tracking and reference.
status	An integer code representing the outcome of the transaction process.
result	Describes the outcome or result of the transaction process.
message	Provides supplementary information or details regarding the transaction status.
metadata	Additional data or information associated with the transaction, often used for custom parameters or tracking for merchant's purposes only

JSON

{
    "payload": {
        "order_id": "40", // your order id
        "status": 203,
        "result": "completed",
        "message": "Payment was processed successfully",
        "transaction_ref": "CST172106307093",
        "metadata": {
              "subscription_id": 43,  
              "currency": "TZS",  
              "client_name": "Twaisa",  
              "charge_id": 3,  
              "isMobile": true  
        },
        "sent_on": "2024-07-15T17:35:31.592003Z",
        "payment_url": []
    }
}

Above is what the merchant will get once the web-hook is triggered. if the Webhook seems like it has delayed, then the merchant has the option to either trigger the request from the API endpoint using the get status endpoint highlighted in the following subsection or the merchant can trigger the webhook from their admin dashboard. All methods should work to give you the status of the transaction.