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.

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 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.