1. Payout
API
English
  • Español
  • English
  • Introduction
    • Kambia API
    • Credentials
    • Authentication
    • Verification
      POST
  • Services
    • Code catalog
    • Payout
      • Notifications
      • Create payout
        POST
      • Get payout
        GET
    • Direct debit
      • How it works
      • Notifications
      • Affiliation
      • Charge
  1. Payout

Create payout

POST
/{{api_version}}/payout/{{merchant_id}}
Description
Creates a bank transfer request.
Authentication
See the section here
Rejections and duplicates
A final rejection returns 4xx with message and error_code: "Invalid bank details" / INVALID_BANK_DETAILS (check the account holder or account details) or "Payout rejected" / PAYOUT_REJECTED (rejected for another reason). No money is sent in either case.
The message starts with that fixed text and may be followed by the reason after a colon ("Invalid bank details: account closed"). Decide by error_code or by the start of the text, never by comparing the full message.
Each payout needs a new, unique order_id. Kambia does not deduplicate by order_id: if you resend the same POST, we can't guarantee that a second real payout won't go out. After a timeout or a lost response, don't retry: check the status.
Status is checked by payout_id, not by order_id, so store the payout_id returned by create. If you get error_code PAYOUT_RESULT_UNKNOWN, the result isn't confirmed: don't resend, check the status.
Destination account
Always send the cci: it is required, payouts go in real time. It can go together with bank_code and account_type. account_number is deprecated: it is not needed, the payout goes to the CCI. It is still accepted.
Current account at Interbank or Scotiabank: also send account_type 2 together with the cci. Without it the payout goes as a savings account and the bank rejects it ("Account Number does not exist"). account_type can go with the cci without account_number.
The payout goes to the CCI's institution (its first 3 digits). With an account number or type, only the institutions in the code catalog are accepted; other institutions go by CCI only, once Kambia enables them for your merchant.
If the CCI's institution is not accepted or not enabled for your merchant, the response is 400 Validation failed with field beneficiary.bank_account.cci.
If the last two digits of the CCI (its check digits) do not match, the response is 400 Validation failed with field beneficiary.bank_account.cci ("CCI check digits are invalid"). It is almost always a mistyped CCI: ask the account holder for it again. This also applies in demo mode: use a real CCI or one of the examples ("Main" or "CCI only").
If you send bank_code together with the cci, it must be the CCI's first 3 digits. Otherwise the response is 400 Validation failed with field beneficiary.bank_account.bank_code ("Bank code 011 does not match the CCI, which belongs to bank code 003").
Without cci, the response is 400 Validation failed with field beneficiary.bank_account.cci ("CCI is required for bank code 011 (BBVA)").
Demo mode (automatic notifications)
To make webhook integration testing easier, the API detects certain order_id prefixes and sends the matching notification to the merchant's payout_webhook ~500 ms after the payout is created.
Reserved prefixes
order_id starts withStatus sent in the webhook
DEMO_SUCCESSSUCCESS
DEMO_REJECTEDREJECTED
Any suffix works: DEMO_SUCCESS_001, DEMO_REJECTED_test, etc.
Behavior
The create response is the same as for a regular payout (status: "PENDING").
The webhook has the same format and signature (x-kambia-signature) as a real notification.
Demo SUCCESS includes receipt_url: "https://demo.kambia.app" (test link).

Request

Body Params application/jsonRequired

Examples

Responses

🟢201Created
application/json
Bodyapplication/json

🟠400Missing field
🟠400Invalid field
🟠400Invalid bank details
Response Response Example
201 - Created
{
    "status_code": 201,
    "message": "Payout created successfully",
    "payout": {
        "id": "645",
        "country": "PER",
        "amount": 25000,
        "currency": "PEN",
        "order_id": "CU_1767031321",
        "status": "CREATED",
        "created_at": "2026-01-19T21:31:16.475102"
    }
}
Modified at 2026-11-16 00:05:47
Previous
Notifications
Next
Get payout
Built with