Create payout

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.

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 with	Status sent in the webhook
`DEMO_SUCCESS`	`SUCCESS`
`DEMO_REJECTED`	`REJECTED`

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

Responses