Opens a payout and reserves the full debit — the recipient's amount plus both fees — on the account. The money is held, not yet gone: the payout reads `completed` only once the provider confirms it paid out AND the ledger debit is recorded. Requires an `Idempotency-Key` header. A repeat of the same key returns the original payout untouched rather than paying the recipient twice. The destination can be an opaque `card_token` or the recipient card requisites required by a payout-only rail. Card requisites are validated, encrypted before persistence, never returned by this API, and removed after a definitive provider submission result.
Parameters
| Name | In | Type | Required | Description |
|---|---|---|---|---|
accountId |
path | string |
yes | Unique identifier of the account. |
Request body
application/json
· CreatePayoutRequest
· required
| Field | Type | Required | Description |
|---|---|---|---|
amount |
string |
yes | The amount you are sending. In `deducted` mode this is what leaves the account; in `add_on` mode it is what the recipient receives. |
country |
string |
yes | ISO 3166-1 alpha-2 country of the recipient. |
destination |
PayoutDestination |
yes | |
expectedTotalFee |
string |
yes | Exact totalFee returned by the latest quote. Creation is rejected if the live provider tariff changed before this request. |
feeMode |
PayoutFeeMode |
yes | |
method |
PayoutMethod |
yes | |
userId |
string |
no | User the payout belongs to. Required when the account is not bound to one; must match the account's user when it is. |
Responses
| Status | Body | Description |
|---|---|---|
201 |
Payout |
Payout created and funds reserved. |
400 |
Error |
Invalid request. |
403 |
Error |
Payouts are not enabled for this client. |
404 |
Error |
Account not found. |
409 |
Error |
The idempotency key was already used for a different request. |
Specification
This page is generated from the OpenAPI specification, which remains the authoritative machine-readable source.