Developers

Payouts

What a bank payout to this beneficiary needs

POST/payouts/requirements

The rail a bank_account payout to this beneficiary would travel on, and every field of the bank destination that rail needs — the same choice and the same rules POST /payouts applies, so you never have to know about rails to fill in a payout. The rail depends on your country, the currency and where the IBAN is: SEPA rails only reach IBANs in the SEPA zone.

  • sepa, sepa_instant, swift: the destination's own iban, accountHolderName and bic (required for swift only).
  • instant_bank_transfer: whatever its provider route defines today; the country, the transfer scheme and any pre-filled values come from the IBAN.

Each field is a path inside the bank destination — holderAddress.city, bankName, or additionalFields.taxId for a field with no typed property — and is the same path a validation_failed error on POST /payouts names, prefixed with destination..

A read: nothing is priced, reserved or written, and no Idempotency-Key is needed. It is a POST only so the IBAN travels in the body and stays out of URLs and access logs.

Requirements can change without notice (a rail enabled, a field made mandatory); POST /payouts decides the rail and checks the fields at the time of the payout, not from an answer read earlier.

No rail can reach this beneficiary for you in this currency, or the instant route does not serve it: 400 payout_rail_unavailable, never an empty list. An unreachable instant route is 500 temporarily_unavailable, safe to retry.

Authentication
ApiKeyAuth
Execution
synchronous

Request body application/jsonrequired

  • ibanstringrequired
    The beneficiary's IBAN.

    max length 34

  • currencystringrequired
    ISO 4217 code for fiat (EUR), asset ticker for crypto (USDT).

    Example: EUR

    pattern ^[A-Z0-9]{3,10}$

Responses

The fields, in the order the route lists them.

Headers

  • X-Request-Idstring
    The request's trace id: the same value a problem body carries as traceId. Quote it when you contact support. A replayed response (Idempotent-Replayed: true) carries the replay's own; its body keeps the original request's traceId.
  • RateLimit-Limitinteger
  • RateLimit-Remaininginteger
  • RateLimit-Resetinteger
    Seconds until the window resets.

Schema application/json

  • railstringrequired
    The rail a payout to this beneficiary would travel on — the choice POST /payouts makes.

    Allowed values: sepasepa_instantswiftinstant_bank_transfer

  • fieldsarray<PayoutFieldRequirement>required
    • fieldstringrequired
      Its path inside the bank destination.

      Example: holderAddress.city

    • requiredbooleanrequired
      A payout without it is refused. An optional field is still checked when you send it.
    • patternstring
      A regular expression the whole value must match.
    • minLengthinteger
    • maxLengthinteger
    • allowedValuesarray<string>
      The only values accepted, when the route restricts them.
    • prefilledValuestring
      A value derived from the IBAN, used when you leave the field out.