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

NameInTypeRequiredDescription
accountId path string yes

Unique identifier of the account.

Request body

application/json · CreatePayoutRequest · required

FieldTypeRequiredDescription
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
ipAddress string no

IP address of the device the payout was requested from. Some payout methods require it.
method PayoutMethod yes
payerReference string no

Your own stable identifier of the recipient, 1-128 characters. Required on an account that is not bound to a user, unless userId is sent: the recipient is then not a PayCA user, nothing is created for them, and their details come in recipient with every request. Send the same value for the same person every time, and a different value for every other person. Optional on a user's account. Returned on the payout and in its webhooks.
recipient DepositPayer no

Identity of the person paid out to. Some payout methods require the full profile (name, email, phone, date of birth, address). On a user's account what is omitted is taken from the identity already held for the user; with payerReference nothing is held, so send the whole profile every time.
userId string no

User the payout belongs to. On an account bound to a user it may be omitted and, when sent, must be that user. On an account not bound to a user it names an existing user of yours; to pay out to a recipient who is not a PayCA user, send payerReference instead.

Responses

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