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.
| Time | Status | User Agent | |
|---|---|---|---|
Retrieving recent requests… | |||
