Payouts
POST /v1/payouts
POST /v1/payoutsCreates the payout and submits it to the banking partner. idempotencyKey is required (max 255 characters). Replaying the same key returns the original result and does not send a second transfer.
A payout needs create Payout. Paying a customer by id does not need a separate customers permission.
Send the payee inside customer.
By id
{
"sourceAccountId": "6f1c8a2e-0000-4000-8000-000000000001",
"amount": 500.00,
"currency": "USD",
"purpose": "goods_sold",
"externalReference": "INV-2026-0419",
"idempotencyKey": "inv-2026-0419-usd",
"customer": { "customerId": "00000000-0000-4000-8000-0000000000b1", "customerReference": "CRM-42" }
}Nothing but customerReference may sit beside customerId. The reference is optional by id: omit it and the payout inherits the customer's own. A customer with no reference gives customerReference: null today, and 400 CUSTOMER_UNBOUND once strict mode is on.
Inline (customerReference is required):
{
"sourceAccountId": "6f1c8a2e-0000-4000-8000-000000000001",
"amount": 1250.00,
"currency": "EUR",
"purpose": "goods_sold",
"externalReference": "INV-2026-0417",
"idempotencyKey": "inv-2026-0417-eur",
"customer": {
"customerReference": "SUP-DE-007",
"fullName": "Acme GmbH",
"rail": "swift",
"iban": "DE89370400440532013000",
"swiftCode": "COBADEFFXXX",
"entityType": "business",
"addressCountryCode": "DE",
"addressLine1": "Hauptstrasse 1"
}
}rail is swift (IBAN and SWIFT code) or local (account number and routing number). entityType is individual or business. amount is major units, minimum 1. currency must equal the source account. externalReference is required, max 140 characters.
customerReference is trimmed, 1 to 128 characters, and compared exactly. LEGACY_UNSET is 400 RESERVED_CUSTOMER_REFERENCE. A customer already bound to a different reference is 409 CUSTOMER_REFERENCE_CONFLICT: nothing is sent.
A key that cannot read the customer reference cannot send one (403 FIELD_EXCLUDED). A Payout grant limited to some customers must pay by customer.customerId; an inline payout is 403 CONDITION_FAILED.
A payout by id is also refused before anything is sent when the customer is missing details a payout needs (400 CUSTOMER_INCOMPLETE, error.details.missingFields), is held in another currency (400 CUSTOMER_CURRENCY_MISMATCH), or is unknown (404, Customer not found).
Success:
{
"message": "Payout submitted.",
"requestId": "payout-req-uuid",
"providerTransactionId": "…",
"customer": { "customerId": "…", "customerReference": "CRM-42" }
}providerStatus moves through created, submitted, executed, or failed / returned. Track it with GET /v1/payouts, GET /v1/payouts/:id, and with webhook events.
GET /v1/payouts
GET /v1/payoutsNewest first, paged. Response: { "data": [PayoutRequest], "meta": { "limit", "offset", "total" } }.
| Query | Default | Description |
|---|---|---|
limit | 10 | Page size (minimum 1, maximum 100) |
offset | 0 | Rows to skip |
Unknown query names are 400. The payee is one customer object: customerId, customerReference, name, rail, entity type, the identifiers of that rail, and the address that was sent. A withheld field is absent. providerPayloadRaw never contains the banking partner's fee, instructed amount or amount-with-fee.
GET /v1/payouts/:id
GET /v1/payouts/:idThe same object as a list row for one payout request. 404 if the id is unknown or belongs to another merchant.
Earlier bodies that put the payee at the top level are still accepted today and carry no customer reference. A body must use one shape. Once strict mode is on, customer is required and the earlier shape is refused, after the idempotency check, so a retry of a payout already accepted is still answered.
Updated 4 days ago
