Bank Payout Overview

A bank payout sends funds from one of your Ralio accounts to an external bank account, using one of three routing types: SEPA, SWIFT or WIRE.

POST /api/v1/account/users/{uid}/accounts/{aid}/bank-payouts

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

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.

Create the payout

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

Complete OTP validation (if required)

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

Track the result

Subscribe to the payout webhooks (payout_processing, payout_completed, payout_failed, payout_canceled) or poll Get bank payout order details.

Choosing the routing type

recipient.routingData selects how the destination bank account is identified:

Routing type	Use it for	`accountNumber` contains	Extra identifiers
`SEPA`	Euro transfers within the SEPA zone	IBAN	—
`SWIFT`	International wires	IBAN or local account number	`swift` always · `abaRoutingCode` for US-linked destinations · `institutionNumber` + `transitNumber` for Canada
`WIRE`	US domestic wires (Fedwire)	US account number	`swift` and `abaRoutingCode` always

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).

Field reference

description

string

required

Human-readable description of the payout (minimum 3 characters). Shown in the order details.

ownReference

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.

amounts

object

required

Hide amounts properties

debitedAmount

object

required

Amount debited from your account.

Show debitedAmount properties

currency

string

required

Must match the account’s currency.

amount

integer

Amount in minor units. Set to 0 when using receivedAmount.amount.

receivedAmount

object

required

Amount the recipient receives.

Show receivedAmount properties

currency

string

required

Fiat currency the recipient gets. Not all currencies are available on every routing type for your account.

amount

integer

Amount in minor units. Set to 0 when using debitedAmount.amount.

recipient

object

required

Hide recipient properties

routingData

string

required

Routing type: SEPA, SWIFT or WIRE.

accountNumber

string

required

Destination account: an IBAN for SEPA, an IBAN or local account number for SWIFT, a US account number for WIRE.

bankCountry

string

required

ISO 3166-1 alpha-2 country of the destination bank. Drives the routing requirements below and the route/currency resolution. Distinct from address.country (the beneficiary’s residence).

swift

string

Destination bank’s SWIFT/BIC. Required for SWIFT and WIRE payouts; not used for SEPA.

abaRoutingCode

string

Destination bank’s 9-digit ABA routing number (numeric). Required for WIRE, and for SWIFT when bankCountry is US, PR, AS, GU, MP or VI.

institutionNumber

string

Canadian institution number (3 digits). Required for SWIFT when bankCountry is CA.

transitNumber

string

Canadian branch transit number (5 digits). Required for SWIFT when bankCountry is CA.

beneficiaryType

string

required

PERSON (natural person) or BUSINESS (company). Decides which identity fields below apply.

name

string

Beneficiary’s first name. Required when beneficiaryType is PERSON.

surname

string

Beneficiary’s last name. Required when beneficiaryType is PERSON.

companyName

string

Legal company name. Required when beneficiaryType is BUSINESS.

relation

string

Your relation to the beneficiary, as a slug from List user relations (e.g. MYSELF, FRIEND, SIBLING, LABOR). Required for PERSON recipients; optional for BUSINESS (defaults to COMERCIAL).

document

object

required

Beneficiary’s identity document.

Show document properties

documentType

string

required

For PERSON: NATIONAL_ID, RESIDENCE_CARD, PASSPORT, DRIVING_LICENSE or CIF. For BUSINESS: TAX_ID only — any other value is rejected, and TAX_ID is rejected for PERSON.

number

string

required

Document number.

address

object

required

Beneficiary’s residence address. All subfields are required.

Show address properties

line1

string

required

Street address.

postalCode

string

required

Postal / ZIP code.

province

string

required

Province, state or region.

city

string

required

City.

country

string

required

ISO 3166-1 alpha-2 country of residence (may differ from bankCountry).

contact

object

Optional contact details.

Show contact properties

phone

string

Beneficiary’s phone number in international format (e.g. +34612345678).

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

Field	`SEPA`	`SWIFT`	`WIRE`
`recipient.swift`	—	✅ Required	✅ Required
`recipient.abaRoutingCode`	—	Required if `bankCountry` ∈ `US` `PR` `AS` `GU` `MP` `VI`	✅ Required
`recipient.institutionNumber`	—	Required if `bankCountry` = `CA`	—
`recipient.transitNumber`	—	Required if `bankCountry` = `CA`	—

By beneficiary type

Field	`PERSON`	`BUSINESS`
`recipient.name`	✅ Required	—
`recipient.surname`	✅ Required	—
`recipient.companyName`	—	✅ Required
`recipient.relation`	✅ Required	Optional (defaults to `COMERCIAL`)
`recipient.document.documentType`	`NATIONAL_ID` · `RESIDENCE_CARD` · `PASSPORT` · `DRIVING_LICENSE` · `CIF`	`TAX_ID`

Complete examples

SEPA · person
SWIFT · business
SWIFT · US bank
SWIFT · Canadian bank
WIRE · US domestic

{
  "description":  "Payment for services rendered",
  "ownReference": "PAY-2026-001234",
  "amounts": {
    "debitedAmount":  { "currency": "EUR", "amount": 25000 },
    "receivedAmount": { "currency": "EUR", "amount": 0 }
  },
  "recipient": {
    "routingData":     "SEPA",
    "accountNumber":   "ES9121000418450200051332",
    "bankCountry":     "ES",
    "beneficiaryType": "PERSON",
    "name":            "Maria",
    "surname":         "Garcia",
    "relation":        "FRIEND",
    "document": { "documentType": "NATIONAL_ID", "number": "87654321B" },
    "address": {
      "line1":      "Calle Gran Via 123",
      "postalCode": "08001",
      "province":   "Barcelona",
      "city":       "Barcelona",
      "country":    "ES"
    }
  }
}

{
  "description":  "Supplier invoice settlement",
  "ownReference": "PAY-2026-001235",
  "amounts": {
    "debitedAmount":  { "currency": "EUR", "amount": 500000 },
    "receivedAmount": { "currency": "GBP", "amount": 0 }
  },
  "recipient": {
    "routingData":     "SWIFT",
    "accountNumber":   "GB29NWBK60161331926819",
    "bankCountry":     "GB",
    "swift":           "NWBKGB2L",
    "beneficiaryType": "BUSINESS",
    "companyName":     "Acme Trading Ltd",
    "document": { "documentType": "TAX_ID", "number": "GB123456789" },
    "address": {
      "line1":      "1 King Street",
      "postalCode": "EC2V 8AU",
      "province":   "Greater London",
      "city":       "London",
      "country":    "GB"
    }
  }
}

{
  "description":  "Contractor payment",
  "ownReference": "PAY-2026-001236",
  "amounts": {
    "debitedAmount":  { "currency": "EUR", "amount": 100000 },
    "receivedAmount": { "currency": "USD", "amount": 0 }
  },
  "recipient": {
    "routingData":     "SWIFT",
    "accountNumber":   "1234567890",
    "bankCountry":     "US",
    "swift":           "CHASUS33",
    "abaRoutingCode":  "021000021",
    "beneficiaryType": "PERSON",
    "name":            "John",
    "surname":         "Smith",
    "relation":        "LABOR",
    "document": { "documentType": "PASSPORT", "number": "X1234567" },
    "address": {
      "line1":      "350 Fifth Avenue",
      "postalCode": "10118",
      "province":   "NY",
      "city":       "New York",
      "country":    "US"
    }
  }
}

{
  "description":  "Consulting fee",
  "ownReference": "PAY-2026-001237",
  "amounts": {
    "debitedAmount":  { "currency": "EUR", "amount": 75000 },
    "receivedAmount": { "currency": "CAD", "amount": 0 }
  },
  "recipient": {
    "routingData":       "SWIFT",
    "accountNumber":     "1234567",
    "bankCountry":       "CA",
    "swift":             "ROYCCAT2",
    "institutionNumber": "003",
    "transitNumber":     "00011",
    "beneficiaryType":   "PERSON",
    "name":              "Anne",
    "surname":           "Tremblay",
    "relation":          "SIBLING",
    "document": { "documentType": "PASSPORT", "number": "CA9876543" },
    "address": {
      "line1":      "100 Rue Sainte-Catherine",
      "postalCode": "H2X 1Z4",
      "province":   "QC",
      "city":       "Montreal",
      "country":    "CA"
    }
  }
}

{
  "description":  "Vendor settlement",
  "ownReference": "PAY-2026-001238",
  "amounts": {
    "debitedAmount":  { "currency": "USD", "amount": 250000 },
    "receivedAmount": { "currency": "USD", "amount": 0 }
  },
  "recipient": {
    "routingData":     "WIRE",
    "accountNumber":   "000123456789",
    "bankCountry":     "US",
    "swift":           "BOFAUS3N",
    "abaRoutingCode":  "026009593",
    "beneficiaryType": "BUSINESS",
    "companyName":     "Globex Corporation",
    "document": { "documentType": "TAX_ID", "number": "12-3456789" },
    "address": {
      "line1":      "1209 Orange Street",
      "postalCode": "19801",
      "province":   "DE",
      "city":       "Wilmington",
      "country":    "US"
    }
  }
}

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

Error	Fix
`recipient.swift is required when recipient.routingData is SWIFT`	Add the destination bank’s BIC (`SWIFT` and `WIRE` payouts).
`recipient.abaRoutingCode (ABA) is required for SWIFT payouts to US/PR/AS/GU/MP/VI`	Add the 9-digit ABA routing number of the destination bank.
`recipient.institutionNumber is required for SWIFT payouts to CA`	Add the 3-digit institution number (and the 5-digit `transitNumber`).
`surname is required when recipient is PERSON`	`PERSON` recipients need `name`, `surname` and `relation`.
`companyName is required when recipient is BUSINESS`	`BUSINESS` recipients need `companyName` instead of `name`/`surname`.
`document.documentType must be TAX_ID for BUSINESS recipients`	Businesses are identified by `TAX_ID`; personal document types are rejected.
`invalid relation: X is not a valid user relation`	Use a slug from List user relations.
`you can only specify one amount: the amount to send or the amount to receive, not both`	Set exactly one of the two amounts; the other must be `0`.
`the amount to send must be in the account currency (EUR)`	`debitedAmount.currency` must match the account you are paying out from.
`recipient currency X is not supported for rail Y`	That currency is not available on the selected routing type for your account — contact support if you need it enabled.

Getting started

Authentication

Users

User verification

Accounts

Payins

Payouts

Transfers

FX

Orders

Ledger

Reference

Integration flow

Choosing the routing type

Amounts

Field reference

Required fields by scenario

By routing type

By beneficiary type

Complete examples

After you create it

Common validation errors

​Integration flow

​Choosing the routing type

​Amounts

​Field reference

​Required fields by scenario

​By routing type

​By beneficiary type

​Complete examples

​After you create it

​Common validation errors

Integration flow

Choosing the routing type

Amounts

Field reference

Required fields by scenario

By routing type

By beneficiary type

Complete examples

After you create it

Common validation errors