Create a payout

Creates the payout and submits it to the banking partner. idempotencyKey is required (max 255).
Replaying the same key for the same merchant returns the original result and does not send a second transfer.
Needs the create Payout permission and nothing else; paying a customer by id needs no permission on customers.

Send the payee inside a customer object, in one of two forms. By id: { customerId, customerReference? }, nothing else beside the id; the reference is inherited from the customer when you send none. Inline: customerReference (required), fullName, rail, entityType, the identifiers of the rail (iban and swiftCode, or accountNumber and routingNumber) and the address. An identifier of the other rail than the one declared is 400 VALIDATION_ERROR. Every inline payout finds or creates the customer for the payee (same rail, account identifier and currency) and links it to the payout; the payout request and the banking partner get the payee as sent, with the identifiers of its own rail only, a reused customer keeps its saved values and the payout is never refused because the name or address differs. After the banking partner accepts the payout, a reused customer's blank entity type and blank address fields are completed from what you sent, one field at a time; a value the customer already holds is never changed.

The reference is trimmed, 1 to 128 characters, kept exactly as sent and never sent to the banking partner. LEGACY_UNSET is 400 RESERVED_CUSTOMER_REFERENCE. By id with none sent: the customer's own reference is used; a customer with no reference gives a payout with a null reference today, and 400 CUSTOMER_UNBOUND once strict mode is on. A reference sent binds an unbound customer and must equal a bound customer's (409 CUSTOMER_REFERENCE_CONFLICT). A credential whose customer read hides customerReference cannot send one (403 FIELD_EXCLUDED).

Before anything is sent to the banking partner, the customer is resolved: none active, a new customer bound to your reference; active and unbound, reused and bound; bound to the same reference, reused; bound to another reference, 409 CUSTOMER_REFERENCE_CONFLICT (nothing created or bound, nothing sent; the message never says which reference). By id, a customer that lacks details a payout needs is 400 CUSTOMER_INCOMPLETE with error.details.missingFields, and one held in another currency is 400 CUSTOMER_CURRENCY_MISMATCH (a customer with no currency passes until strict mode is on). A merged id leads to the surviving customer. A scoped credential's rules are judged on the resolved customer: a prohibition on creating payouts to a customer follows its bank account across currencies and merged ids, and refuses with 403 CONDITION_FAILED. A local payee identifier containing : is 400 VALIDATION_ERROR naming the field.

beneficiaryId, the top-level payee fields and saveBeneficiary are earlier shapes: still accepted, carrying no reference, and refused with 400 once strict mode is on (after the idempotency check, so a retry of an earlier accepted payout is still answered). Sending a customer together with them is 400 VALIDATION_ERROR.

Rate limit: 20 / minute.

Recent Requests
Log in to see full request history
TimeStatusUser Agent
Retrieving recent requests…
LoadingLoading…
Body Params
uuid
required
number
required
≥ 1

Major units (minimum 1.00 in that currency)

string
enum
required
Allowed:
string
enum
required
string
required
length ≤ 140
string
required
length ≤ 255

Required. Unique per distinct payout; reuse only to retry the same one.

customer

The payee of a payout, by id or written out. Never together with the earlier top-level payee fields or beneficiaryId. Required once strict mode is on.

uuid
deprecated

Earlier shape; the same as customer.customerId but carries no reference. Never together with customer. Refused once strict mode is on.

boolean
deprecated

Legacy, does nothing; inline payouts always find or create and link a customer. Refused once strict mode is on.

string
deprecated

Earlier shape; the same as customer.fullName. Never together with customer. Refused once strict mode is on.

string
enum
deprecated
Allowed:
string
enum
deprecated
Allowed:
string
deprecated
string
deprecated
string
deprecated
string
deprecated
string
deprecated
string
length ≤ 50
deprecated
string
length ≤ 50
deprecated
string
length ≤ 50
deprecated
string
length ≤ 50
deprecated
Headers
string

Optional; echoed so you can thread your logs with ours.

Responses

Language
Credentials
Basic
base64
:
LoadingLoading…
Response
Click Try It! to start a request and see the response here! Or choose an example:
application/json