Skip to main content
A bank payout sends funds from one of your Ralio accounts to an external bank account, using one of ten routing types: SEPA, SWIFT, WIRE, PIX, SPEI, UEMOA, MOBILE_MONEY, UAEFTS, FPS or NIP.
This page explains every field of the request and — more importantly — which fields are required in each scenario, since the requirements change depending on the routing type, the destination bank’s country and the beneficiary type.

​
Integration flow

1

Simulate the payout

Call Simulate bank payout with the amounts, routingData and bankCountry to preview the fees, the exchange rate and the exact amount the recipient will receive — without moving funds.
2

Create the payout

Call Create bank payout with the full recipient details. The order is created in CREATED state.
3

Complete OTP validation (if required)

The creation response includes isOTPRequired. When true, complete the OTP flow before the payout is dispatched.
4

Track the result

Subscribe to the payout webhooks (payout_processing, payout_completed, payout_failed, payout_canceled) or poll Get bank payout order details.
Send an idempotency key when creating the payout so a timeout or a retry can never dispatch it twice.

​
Choosing the routing type

recipient.routingData selects how the destination bank account is identified: The local networks only reach their own countries, so bankCountry is restricted and the recipient gets the local currency: Not every currency is available on every routing type — it depends on what is enabled for your account. If a combination is not available, the API responds recipient currency X is not supported for rail Y.

​
Amounts

All amounts are integers in minor units (25000 = 250.00 EUR).
Provide exactly one of amounts.debitedAmount.amount or amounts.receivedAmount.amount, and set the other to 0:
  • Debited amount: “send exactly this from my account” — fees and FX are deducted from it.
  • Received amount: “the recipient must get exactly this” — your account is debited whatever is needed to cover it. Not every route supports this mode; the API returns an explicit error when it doesn’t.
Two more rules:
  • amounts.debitedAmount.currency must always be your account’s currency, even when you only provide the received amount.
  • amounts.receivedAmount.currency is the currency the recipient gets, and must be a fiat currency. When it differs from the account currency, the payout includes a currency conversion (the simulation shows the applied rate).
  • XOF and XAF have no minor unit, so a receivedAmount.amount in those currencies must be a whole number of units — a multiple of 100 (100000 = 1000 XOF). Anything else is rejected.

​
Field reference

​
string
required
Human-readable description of the payout. Shown in the order details and forwarded to the destination network as the payment reference, so the local networks constrain it: only letters, digits, spaces and - . & /, with 6–140 characters on SEPA and 6–18 characters on PIX, SPEI, UEMOA, MOBILE_MONEY, UAEFTS, FPS and NIP. SWIFT and WIRE only require a minimum of 3 characters.
​
string
required
Your own identifier for this payout (e.g. an invoice or batch number). Returned in order details and webhooks so you can correlate it with your systems.
​
object
required
​
object
required

​
Required fields by scenario

Fields always required, on every payout: description · ownReference · amounts (with exactly one non-zero amount) · recipient.routingData · recipient.accountNumber · recipient.bankCountry · recipient.beneficiaryType · recipient.document · recipient.address (all subfields)

​
By routing type

The local networks never use the fields above. Each needs at most one identifier of its own:

​
By beneficiary type

​
Complete examples

​
After you create it

A successful creation returns 201 with the order and the isOTPRequired flag:
  • isOTPRequired: true — the payout stays in CREATED until you complete the OTP flow.
  • isOTPRequired: false — the payout continues automatically.
From there the order moves through the standard lifecycle (CREATED → PENDING → SETTLED, or FAILED / CANCELED), and each transition fires the corresponding payout webhook.

​
Common validation errors