> ## Documentation Index
> Fetch the complete documentation index at: https://doc.raliopay.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Bank Payout Overview

> Every field of the bank payout request, and which ones are required in each scenario.

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

```text theme={null}
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

<Steps>
  <Step title="Simulate the payout">
    Call [Simulate bank payout](/api-reference/payouts/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.
  </Step>

  <Step title="Create the payout">
    Call [Create bank payout](/api-reference/payouts/create-bank-payout) with the full recipient details. The order is created in `CREATED` state.
  </Step>

  <Step title="Complete OTP validation (if required)">
    The creation response includes `isOTPRequired`. When `true`, complete the [OTP flow](/custom-api-reference/payouts/bank-payout-requirements) before the payout is dispatched.
  </Step>

  <Step title="Track the result">
    Subscribe to the [payout webhooks](/webhooks-events/payout/overview) (`payout_processing`, `payout_completed`, `payout_failed`, `payout_canceled`) or poll [Get bank payout order details](/api-reference/payouts/get-bank-payout-order-details).
  </Step>
</Steps>

***

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

<Warning>
  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.
</Warning>

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

<ParamField body="description" type="string" required>
  Human-readable description of the payout (minimum 3 characters). Shown in the order details.
</ParamField>

<ParamField body="ownReference" type="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.
</ParamField>

<ParamField body="amounts" type="object" required>
  <Expandable title="amounts properties" defaultOpen>
    <ParamField body="debitedAmount" type="object" required>
      Amount debited from your account.

      <Expandable title="debitedAmount properties">
        <ParamField body="currency" type="string" required>
          Must match the account's currency.
        </ParamField>

        <ParamField body="amount" type="integer">
          Amount in minor units. Set to `0` when using `receivedAmount.amount`.
        </ParamField>
      </Expandable>
    </ParamField>

    <ParamField body="receivedAmount" type="object" required>
      Amount the recipient receives.

      <Expandable title="receivedAmount properties">
        <ParamField body="currency" type="string" required>
          Fiat currency the recipient gets. Not all currencies are available on every routing type for your account.
        </ParamField>

        <ParamField body="amount" type="integer">
          Amount in minor units. Set to `0` when using `debitedAmount.amount`.
        </ParamField>
      </Expandable>
    </ParamField>
  </Expandable>
</ParamField>

<ParamField body="recipient" type="object" required>
  <Expandable title="recipient properties" defaultOpen>
    <ParamField body="routingData" type="string" required>
      Routing type: `SEPA`, `SWIFT` or `WIRE`.
    </ParamField>

    <ParamField body="accountNumber" type="string" required>
      Destination account: an IBAN for `SEPA`, an IBAN or local account number for `SWIFT`, a US account number for `WIRE`.
    </ParamField>

    <ParamField body="bankCountry" type="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).
    </ParamField>

    <ParamField body="swift" type="string">
      Destination bank's SWIFT/BIC. **Required for `SWIFT` and `WIRE`** payouts; not used for `SEPA`.
    </ParamField>

    <ParamField body="abaRoutingCode" type="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`.
    </ParamField>

    <ParamField body="institutionNumber" type="string">
      Canadian institution number (3 digits). **Required for `SWIFT` when `bankCountry` is `CA`.**
    </ParamField>

    <ParamField body="transitNumber" type="string">
      Canadian branch transit number (5 digits). **Required for `SWIFT` when `bankCountry` is `CA`.**
    </ParamField>

    <ParamField body="beneficiaryType" type="string" required>
      `PERSON` (natural person) or `BUSINESS` (company). Decides which identity fields below apply.
    </ParamField>

    <ParamField body="name" type="string">
      Beneficiary's first name. **Required when `beneficiaryType` is `PERSON`.**
    </ParamField>

    <ParamField body="surname" type="string">
      Beneficiary's last name. **Required when `beneficiaryType` is `PERSON`.**
    </ParamField>

    <ParamField body="companyName" type="string">
      Legal company name. **Required when `beneficiaryType` is `BUSINESS`.**
    </ParamField>

    <ParamField body="relation" type="string">
      Your relation to the beneficiary, as a slug from [List user relations](/api-reference/user-relations/list-user-relations) (e.g. `MYSELF`, `FRIEND`, `SIBLING`, `LABOR`). **Required for `PERSON`** recipients; optional for `BUSINESS` (defaults to `COMERCIAL`).
    </ParamField>

    <ParamField body="document" type="object" required>
      Beneficiary's identity document.

      <Expandable title="document properties">
        <ParamField body="documentType" type="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`.
        </ParamField>

        <ParamField body="number" type="string" required>
          Document number.
        </ParamField>
      </Expandable>
    </ParamField>

    <ParamField body="address" type="object" required>
      Beneficiary's residence address. All subfields are required.

      <Expandable title="address properties">
        <ParamField body="line1" type="string" required>
          Street address.
        </ParamField>

        <ParamField body="postalCode" type="string" required>
          Postal / ZIP code.
        </ParamField>

        <ParamField body="province" type="string" required>
          Province, state or region.
        </ParamField>

        <ParamField body="city" type="string" required>
          City.
        </ParamField>

        <ParamField body="country" type="string" required>
          ISO 3166-1 alpha-2 country of residence (may differ from `bankCountry`).
        </ParamField>
      </Expandable>
    </ParamField>

    <ParamField body="contact" type="object">
      Optional contact details.

      <Expandable title="contact properties">
        <ParamField body="phone" type="string">
          Beneficiary's phone number in international format (e.g. `+34612345678`).
        </ParamField>
      </Expandable>
    </ParamField>
  </Expandable>
</ParamField>

***

## 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

<Tabs>
  <Tab title="SEPA · person">
    ```json theme={null}
    {
      "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"
        }
      }
    }
    ```
  </Tab>

  <Tab title="SWIFT · business">
    ```json theme={null}
    {
      "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"
        }
      }
    }
    ```
  </Tab>

  <Tab title="SWIFT · US bank">
    ```json theme={null}
    {
      "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"
        }
      }
    }
    ```
  </Tab>

  <Tab title="SWIFT · Canadian bank">
    ```json theme={null}
    {
      "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"
        }
      }
    }
    ```
  </Tab>

  <Tab title="WIRE · US domestic">
    ```json theme={null}
    {
      "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"
        }
      }
    }
    ```
  </Tab>
</Tabs>

***

## 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](/custom-api-reference/payouts/bank-payout-requirements).
* **`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](/webhooks-events/payout/overview).

## 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](/api-reference/user-relations/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. |