Webhook

When an event occurs on your KKiaPay account you can use the webhooks provided by KKiaPay to keep an eye on their execution. To date, you can use webhooks to notify your backend of the status of a transaction (is the transaction a success or a failure).

Configuration of webhooks

In order to configure your webhooks, you will need to follow the steps below once on the form to add a webhook available after clicking on the "Add a webhook" button in the Webhook tab of the API Keys submenu of your dashboard:

1. Enter the URL on which you want to be notified. You can enter any URL as the destination for events. However, it must be a dedicated page on your server, configured to receive events.

2. Choose the events for which you want to be notified. You will only be notified of the specified events.

3. Define a hash secret. It will be used to verify the source of the information you receive.

Once the callback has been created, you can perform a test to verify that KKiaPay is contacting your URL.

Manage webhooks

It is important to know how to acknowledge receipt of an event after notification from KKiaPay. To do this, you must first use your URL to identify the type of event and return an HTTP 2xx status code. All response codes outside this range, including 3xx codes, tell KKiaPay that you have not received the event.

In case of non-receipt KKiaPay tries 5 times in a row (in an interval of 500ms incremental) to send you the information.

Verification of webhook signatures

KKiaPay signs webhooks events before sending them to your URLs. Indeed, in the header of each x-kkiapay-secret request (using your hash secret previously entered on your dashboard), a signature is entered. It is used to allow you to verify that the events were sent by KKiaPay and not by a third party.

The skeleton of the request is as follows:

curl -H "x-kkiapay-secret: XXX" -H "Content-Type: application/json http://example.com/webhook

Any x-kkiapay-secret request uses the hash secret provided by your person on the KKiaPay dashboard.

Payloads Response Body

With each event notification we send you a body request in json format below:

• In the case of a failed transaction

{
    "transactionId": "erjEU5P9o",
    "isPaymentSucces": false,
    "account": "22996000001", // null for card and wave payments,
    "failureCode": "processing_error",
    "failureMessage": "processing_error",
    "label": "...",
    "method": "MOBILE_MONEY", // MOBILE_MONEY | WALLET | CARD,
    "amount": 1000,
    "fees": 19,
    "partnerId": "...",
    "performedAt": "2024-03-20T08:55:22.883Z",
    "stateData": {},
    "event": "transaction.failed"
}

• In the case of a successful transaction

{
    "transactionId": "3iH6wjHJ3",
    "isPaymentSucces": true,
    "account": "22996000000", // null for card and wave payments,
    "label": "...",
    "method": "MOBILE_MONEY", // MOBILE_MONEY | WALLET | CARD,
    "amount": 1000,
    "fees": 19,
    "partnerId": "...",
    "performedAt": "2024-03-20T08:55:22.883Z",
    "stateData": {},
    "event": "transaction.success"
}