Notifications

The Kambia API can notify your webhook when a payout changes status (success or rejection).

How the notification is sent

Method: POST

Content-Type: application/json

Signature header: x-kambia-signature: an HMAC-SHA256 signature so you can verify the notification comes from Kambia (see below).

Setup

Set up a webhook that receives the following data structure:

Once it receives the notification, your webhook must respond with HTTP 200 OK. Otherwise, it will receive retries of the same notification.

Give Kambia a valid URL to register as your payout_webhook.

Possible statuses

status	Description
SUCCESS	The bank processed the payout. Includes `receipt_url` if the receipt was generated successfully.
REJECTED	The bank rejected the payout.

Signature verification

Every notification includes the x-kambia-signature header. Verify the authenticity and integrity of the body as follows:

Get the request body (the JSON string exactly as received).

Build the string to sign: merchant_id + body (concatenated, no separator).

Compute HMAC-SHA256 using your merchant_secret as the key and the string from step 2 as the message.

Compare the hex result with the value of the x-kambia-signature header.

If they don't match, the notification must not be considered valid.

Automated testing

To test your webhook integration without completing a real payment, use demo mode: when you create a payout with an order_id that starts with DEMO_SUCCESS or DEMO_REJECTED, the API automatically sends the matching notification to your payout_webhook ~500 ms later.

See the "Demo mode" section in Create payout

Examples

1. Payout processed

When the bank processes a payout, a SUCCESS notification is sent. If the receipt was generated successfully, receipt_url is included inside payout: a link to open or download the receipt image. The URL is temporary and valid for 1 hour. If there is an internal failure generating the receipt, the notification is still sent, without receipt_url.

{
    "status": "SUCCESS",
    "message": "Payout successful",
    "timestamp": "2025-02-12T15:30:00.000Z",
    "payout": {
        "id": "634",
        "country": "PE",
        "amount": "50000",
        "currency": "PEN",
        "order_id": "1768526334152-70042575",
        "bank_code": "002",
        "account_number": "19006234576522",
        "name": "Cristian Zavaleta",
        "receipt_url": "https://..."
    }
}

2. Payout rejected

When the bank rejects a payout, a REJECTED notification is sent. The message field starts with "Invalid bank details" (check the account holder or account details) or "Payout rejected" (rejected for another reason), and may be followed by the reason after a colon: "Invalid bank details: account closed". Compare by the start of the text, never by exact match. No money is sent in either case.

{
    "status": "REJECTED",
    "message": "Invalid bank details",
    "timestamp": "2025-02-12T14:00:00.000Z",
    "payout": {
        "id": "613",
        "country": "PER",
        "amount": "25000",
        "currency": "PEN",
        "order_id": "CU_1767031321",
        "bank_code": "002",
        "account_number": "19206434476528",
        "name": "Jose Jeri"
    }
}

How the notification is sent#

Setup#

Possible statuses#

Signature verification#

Automated testing#

Examples#

1. Payout processed#

2. Payout rejected#