Payouts webhook

Kashier sends two webhooks during a transfer:

1. Transfer initiation — fired when the transfer is accepted.
2. Transfer final status — fired when it settles or fails.

Before you start

Kashier only sends a transfer webhook when all three of these are in place. If any one is missing, the transfer still goes through, but no webhook is delivered for it.

1. An API key named transfer. In the Kashier dashboard, create an API key and name it exactly transfer, in the same mode you create transfers in — a test-mode key for test transfers, a live-mode key for live transfers. This is your transfer API key: Kashier signs every payout webhook with it, and you use it to verify the signature. It is a separate key from your Payment API Key.
2. A webhook URL. Register the endpoint that should receive transfer events — see manage your webhooks.
3. A merchantTransferId on the transfer. Send your own unique reference in merchantTransferId when you create the transfer. A transfer created without it never triggers a webhook. For batches, the equivalent field is merchantBatchId.

Authentication

To verify the integrity of data sent from Kashier, you need to validate the x-kashier-signature header using HMAC SHA256.

Verification process

Extract the signatureKeys array from the payload — it lists the keys used to create the signature. Concatenate their values from the payload in the exact order the array lists them, as key_1=value_1&key_2=value_2.... Do not sort the array, and do not URL-encode the values: use them raw. Generate an HMAC SHA256 hash of that string using your transfer API key (the key named transfer) as the secret, then compare it with the x-kashier-signature header value. If they match, the data is authentic and can be safely processed.

For a single transfer the order is fixed as merchantTransferId, method, amount, merchantId, status, so the signed string looks like this:

merchantTransferId=transfer12345&method=wallet&amount=10&merchantId=MID-xxx-xxx&status=INITIATED

Batch webhooks use merchantBatchId, batchId, method, amount, merchantId, status — again in that order.

Webhook types

All webhooks include a signature header for security verification:

• Header name: x-kashier-signature
• The signature covers only the fields listed in the payload's signatureKeys array, joined as key=value&key=value in array order with raw values and hashed with your transfer API key — see Verification process.

Transfer initiation webhook

Sent when a transfer is initially processed by Kashier.

Payload structure

{
    "transferId": "TRS-1007931588",
    "merchantTransferId": "transfer12345",
    "amount": 10,
    "method": "wallet",
    "status": "INITIATED",
    "openForReturn": false,
    "merchantId": "MID-xxx-xxx",
    "recipientName": "Jhon Doe",
    "recipientNumber": "01356839512",
    "businessEmail": "[email protected]",
    "storeName": "kashier store",
    "creatorEmail": "[email protected]",
    "creatorName": "Sara Ahmed",
    "batch": {
        "name": "Jhon Doe",
        "id": "TRS-1007931588",
        "method": "wallet",
        "transfersCount": 1
    },
    "transferResponseCode": "00",
    "transferResponseMessage": {
        "en": "success",
        "ar": "تمت الموافقة"
    },
    "date": "2025-01-15T08:32:37.829Z",
    "signatureKeys": ["merchantTransferId", "method", "amount", "merchantId", "status"]
}

Transfer final status webhook

Sent when the transfer reaches its final state (completed or failed).

Payload structure

{
    "transferId": "TRS-1007931588",
    "amount": 10,
    "method": "wallet",
    "recipientName": "Jhon Doe",
    "recipientNumber": "01123439512",
    "merchantTransferId": "transfer12345",
    "status": "FAILED",
    "openForReturn": false,
    "merchantId": "MID-xxx-xxx",
    "businessEmail": "[email protected]",
    "storeName": "kashier store",
    "creatorEmail": "[email protected]",
    "creatorName": "Sara Ahmed",
    "batch": {
        "name": "Jhon Doe",
        "id": "TRS-1007931588",
        "method": "wallet",
        "transfersCount": 1
    },
    "transferResponseCode": "k_default",
    "transferResponseMessage": {
        "en": "A General Error Occured, please contact support.",
        "ar": ""
    },
    "date": "2025-01-15T08:32:37.929Z",
    "signatureKeys": ["merchantTransferId", "method", "amount", "merchantId", "status"]
}

Body description

Status values

To configure which transfer events actually trigger a webhook delivery — as opposed to the full set of statuses a transfer can reach, listed below — see manage your webhooks.

For single transfers

For batch transfers

openForReturn

A TRANSFERRED transfer with openForReturn: true is settled but still returnable — the receiving wallet or bank can bounce it back (EBC code 8222). Treat it as not final and keep reconciling. openForReturn: false on TRANSFERRED is settled and final.

Error handling

When a transfer fails, the system provides detailed information to help identify and understand the issue:

1. Status: the transfer status will be updated to "FAILED," indicating the operation was not successful.
2. Error code: the transferResponseCode will include a specific code that represents the reason for the failure.
3. Error message: the transferResponseMessage will contain a detailed description of the error in both English and Arabic, allowing for better clarity and support across different audiences.