# Financial instruments

Identity Management v3
This topic describes the v3 identity model. **Identity Management v3** is recommended for all new integrations.

For supported payment corridors, see [Payout network](/products/payments-direct-2/introduction/payout-network).

For migration details or questions, contact your Ripple representative.

A *financial instrument* represents the **account or wallet details** used to send or receive funds in a payment. While a **payment identity** describes *who* the party is, a financial instrument describes *where* the money goes — for example, a US ACH bank account, a SEPA IBAN, a PIX key, or a local bank payout rail.

Financial instruments are managed by the **Identity Management v3** and are always associated with a specific identity. Each instrument specifies a payment rail (such as `US_ACH`, `EU_SEPA`, `MX_SPEI`, `BR_PIX`), a currency, and a rail-specific payload (routing codes, account numbers, IBANs, CLABE, PIX keys, and so on).

**Identity Management v3** separates identities and instruments so that you can:

- Reuse a single KYC’d identity across different payout rails and currencies.
- Manage **multiple bank accounts or payout methods** for the same party.
- Rotate or replace accounts without duplicating identities or losing history.


## What you’ll learn

In this topic, you’ll learn:

- How financial instruments relate to **payment identities** and the overall payment workflow.
- Which metadata fields apply to every financial instrument (such as `financialInstrumentType`, `currency`, `country`, and `label`).
- What rail-specific objects look like for common payout rails (for example, `usAch`, `euSepa`, `mxSpei`, `gbFps`, `brPix`).
- How **one identity can hold financial instruments** for different payout rails, enabling a single party to manage multiple bank accounts under one KYC record.
- How to think about validation rules, corridor coverage, and best practices when modeling bank accounts and payout methods.


## Relationship between identities, instruments, and payments

Financial instruments are scoped to identities:

- Each financial instrument belongs to **exactly one identity**.
- The instrument does **not** store personal details; it only stores account/wallet data.
- The identity’s `paymentRole` (ORIGINATOR or BENEFICIARY) determines whether the instrument is used to fund or receive payments.


When building payments:

- The **payment object** references the **identity** and **financial instrument** by ID.
- The payment orchestration layer uses the **financialInstrumentType** to determine which payout rail to use (for example, `US_ACH`, `MX_SPEI`).
- Corridor-specific rules ensure that instrument type, currency, and corridor are compatible.


For details on the identity model, see [Payment identities](/products/payments-direct-2/introduction/concepts/payment-identities).

## Financial instrument structure

**At a high level, a financial instrument consists of:**

1. Metadata describing the instrument (`type`, `currency`, `label`, etc.).
2. A single rail-specific object (for example, `usAch`, `mxSpei`, `euSepa`) that contains the account fields required for that rail.


**Conceptual shape:**


```json
{
  "financialInstrumentId": "3fc74743-e7f3-414a-9fcf-eb8c1d52356a",
  "financialInstrumentType": "US_ACH",
  "currency": "USD",
  "label": "US bank account",
  "country": "US",
  "createdAt": "2025-10-01T18:46:47.430Z",
  "updatedAt": "2025-10-01T18:46:47.430Z",

  // one rail-specific object, depending on financialInstrumentType
  "usAch": {
    "bankName": "Bank of Example",
    "bankRoutingNumber": "266231608",
    "accountNumber": "60480",
    "accountType": "CHECKING"
  }
}
```

One rail per instrument
Only one of the rail-specific objects (`usAch`, `mxSpei`, `euSepa`, and so on) is populated for a given instrument.

## Financial instrument metadata

The following fields apply to every financial instrument, regardless of rail.

| Field | Type | Required | Description | Example |
|  --- | --- | --- | --- | --- |
| **financialInstrumentId** | string | Yes | Server-generated unique identifier for the financial instrument. Stable across all versions. | "3fc74743-e7f3-414a-9fcf-eb8c1d52356a" |
| **financialInstrumentType** | string | Yes | Payment rail used by this instrument. See [Financial instrument types](#financial-instrument-types) for all supported values. | "US_ACH" |
| **currency** | string | Yes | ISO 4217 currency code of the instrument (for example, `USD`, `EUR`, `MXN`). Must be compatible with the chosen rail and corridor. | "USD" |
| **label** | string | No | User-defined label to help your systems distinguish instruments (for example, by region or usage). | "US bank account" |
| **country** | string | No | Country code (ISO 3166-1 alpha-2) where the instrument is held or used. Returns `ZZ` for crypto wallet instruments (ETH_WALLET, TRON_WALLET, SOL_WALLET). | "US" |
| **createdAt** | string | Yes | RFC 3339 timestamp when the instrument was created. | "2023-11-02T18:26:00.000Z" |
| **updatedAt** | string | Yes | RFC 3339 timestamp when the instrument was last updated. | "2023-11-03T18:26:00.000Z" |


Metadata only onlist
When listing instruments, the API returns **metadata only** (no rail-specific fields) for each instrument.

To see full rail-specific details, retrieve the instrument by ID.

## Multiple financial instruments per identity

In **Identity Management v3**, each identity can have financial instruments attached to it. By default, each identity supports **one active financial instrument**. Support for multiple financial instruments per identity is available to eligible tenants — contact your Ripple representative to find out whether this capability is enabled for your account.

**Identity vs financial instrument**

- The **identity** describes who you are paying or collecting from:
  - `identityType` (INDIVIDUAL or BUSINESS)
  - `paymentRole` (ORIGINATOR or BENEFICIARY)
  - PII fields such as names, addresses, registration documents, and contact details.
- The **financial instrument** describes how and where funds are delivered:
  - `financialInstrumentType` (for example, US_ACH, EU_SEPA, MX_SPEI, BR_PIX)
  - `currency` and `country`
  - Rail-specific fields such as routing numbers, IBANs, CLABE, PIX keys, and so on.


Reusing identities
By separating these two concepts, you can reuse the same identity across different corridors, currencies, and payout rails without duplicating PII.

## Lifecycle and API workflow

Each financial instrument is managed as a child resource of an identity:

1. **Create an identity**Use `POST /v3/identities` to create the identity with its PII and `internalId`.
2. **Add a financial instrument**Use `POST /v3/identities/{identity-id}/financial-instruments` to attach a bank account or payout method to that identity.You specify:
  - `financialInstrumentType`
  - `currency`
  - The corresponding rail object (for example, `usAch`, `euSepa`, `mxSpei`, `brPix`) with its required fields.
3. **List instruments for an identity**Use `GET /v3/identities/{identity-id}/financial-instruments` to see all instruments attached to an identity. The response returns a list of instruments with metadata (IDs, types, currencies, labels, timestamps).
4. **Get details for a single instrument**Use `GET /v3/identities/{identity-id}/financial-instruments/{financial-instrument-id}` to retrieve full rail-specific details, such as account numbers and routing codes.
5. **Update or deactivate instruments**
  - Use `PUT` to update editable fields (for example, changing a label or updating a bank account number where allowed).
  - Use `DELETE` to deactivate an instrument so it can no longer be used for new payments. Historical usage remains available for audit.


Deactivation
Deactivating an identity also deactivates its financial instruments and prevents them from being used in new payments.

### Example scenarios

When multiple financial instruments per identity are available, they are useful when:

- **A single beneficiary uses multiple accounts**For example, a vendor in Mexico may want:
  - An MXN SPEI account for local MXN payouts (`MX_SPEI`), and
  - A USD ACH account for USD payouts (`US_ACH`).
- **A corporate beneficiary has multi-currency accounts**For example, a business might maintain EUR SEPA, GBP FPS, and USD ACH accounts. All of these can live under the same BUSINESS BENEFICIARY identity, each as a separate financial instrument.
- **You rotate or replace accounts without duplicating identities**If a beneficiary changes their bank account, you can:
  - Add a new financial instrument,
  - Switch new payments to the new instrument, and
  - Deactivate the old instrument,while keeping the identity (and its history) intact.


### Best practices

- Use the `label` field on financial instruments to make accounts easy to distinguish (for example, "operating-USD", "payroll-EUR", "MXN-SPEI-local").
- Avoid creating multiple identities for the same real-world party just to handle different bank accounts; where multiple financial instruments are supported, prefer a single identity with multiple instruments.
- Use identity-level tags to express business segmentation (for example, ["vendor-emea", "high-value"]) and handle account-specific details at the financial instrument level.


## Financial instrument types

The `financialInstrumentType` determines which rail-specific object is populated and what fields are required.

| Type | Description | Typical use | Common currency |
|  --- | --- | --- | --- |
| US_ACH | U.S. Automated Clearing House batch processing network. | Domestic U.S. bank transfers (ACH/RTP-backed). | "USD" |
| US_FEDWIRE | U.S. Fedwire real-time gross settlement system for high-value domestic transfers. | High-value domestic USD bank transfers. | "USD" |
| MX_SPEI | Mexico’s real-time interbank transfer system (SPEI). | MX domestic bank payouts in MXN. | "MXN" |
| EU_SEPA | SEPA credit transfer rails for EUR-denominated payments across SEPA countries. | EUR bank payouts to SEPA-region accounts (IBAN). | "EUR" |
| GB_FPS | UK Faster Payments Service and CHAPS. | GBP payouts to UK bank accounts. | "GBP" |
| CA_EFT | Canada’s Electronic Funds Transfer system. | CAD payouts to Canadian bank accounts. | "CAD" |
| NG_BANK_PAYOUT | Nigeria bank payout rail. | NGN payouts to Nigerian bank accounts. | "NGN" |
| BR_PIX | Brazil’s instant payment platform (PIX) operated by the Central Bank of Brazil. | BRL payouts to PIX accounts using PIX keys. | "BRL" |
| CO_PSE | Colombia’s secure online banking payment system (PSE). | COP payouts to Colombian bank accounts over PSE. | "COP" |
| BR_TED | Brazil’s Electronic Funds Transfer (TED) system for higher-value transactions. | BRL payouts to Brazilian bank accounts over TED. | "BRL" |
| GH_BANK_PAYOUT | Ghana bank payout rail via GIS. | GHS payouts to Ghanaian bank accounts. | "GHS" |
| RW_BANK_PAYOUT | Rwanda bank payout rail via RSwitch. | RWF payouts to Rwandan bank accounts. | "RWF" |
| ZA_BANK_PAYOUT | South Africa bank payout rail via PayShap. | ZAR payouts to South African bank accounts. | "ZAR" |
| UG_BANK_PAYOUT | Uganda bank payout rail. | UGX payouts to Ugandan bank accounts. | "UGX" |
| ZM_BANK_PAYOUT | Zambia bank payout rail via ZECHL. | ZMW payouts to Zambian bank accounts. | "ZMW" |
| HK_BANK_PAYOUT | Hong Kong bank payout rail via CHATS. | HKD payouts to Hong Kong bank accounts. | "HKD" |
| CN_TRADE | China bank transfer for trade transactions via CNAPS. | CNY payouts for trade purposes to Chinese bank accounts. | "CNY" |
| CN_INDIVIDUAL | China bank transfer for individual payouts via CUP or CNAPS. | CNY payouts to individual Chinese bank accounts. | "CNY" |
| CN_INDIVIDUAL_TRADE | China UnionPay for individual trade transactions. | CNY trade payouts to Chinese bank accounts via CUP. | "CNY" |
| CN_CFXPS | China Cross-Border Foreign Exchange Payment System (CFXPS). | USD payouts to Chinese bank accounts via CFXPS. | "USD" |
| AE_IPI | United Arab Emirates' Instant Payment Interface for real-time transactions. | AED payouts to UAE bank accounts via IPI, with FTS fallback for larger transfers. | "AED" |
| IN_NEFT | India National Electronic Funds Transfer - bank payout for INR denominated transfers using IFSC routing codes. | INR payouts to Indian bank accounts via NEFT. | "INR" |
| ID_BIFAST | Indonesia BI-FAST - Bank Indonesia's 24/7 real-time payment rail for IDR-denominated domestic transfers. | IDR payouts to Indonesian bank accounts via BI-FAST. | "IDR" |
| TR_FAST | Turkey FAST - 24/7 real-time payment rail for TRY-denominated domestic transfers, with EFT (business-day) fallback. | TRY payouts to Turkish bank accounts via FAST. | "TRY" |
| PH_NRPS | Philippines National Retail Payment System (InstaPay/PESONet) for PHP-denominated bank payouts. | PHP payouts to Philippine bank accounts via InstaPay, with PESONet fallback for larger transfers. | "PHP" |
| CL_TEF | Chile TEF (Transferencia Electrónica de Fondos) - business-day domestic transfer system for CLP-denominated payments. | CLP payouts to Chilean bank accounts via TEF. | "CLP" |
| TH_PROMPTPAY | Thailand PromptPay - Thailand's national real-time retail payment system for THB domestic bank transfers. | THB payouts to Thai bank accounts via PromptPay. | "THB" |
| KR_KFTC | South Korea KFTC - 24/7 real-time payment rail via Korea Financial Telecommunications and Clearings for KRW-denominated payments. | KRW payouts to South Korean bank accounts via KFTC. | "KRW" |
| PE_LBTR | Peru LBTR (Liquidación Bruta en Tiempo Real) - real-time settlement system for PEN-denominated payments. | PEN payouts to Peruvian bank accounts via LBTR. | "PEN" |
| AR_INTERBANKING | Argentina Interbanking - CBU/CVU-based domestic transfer system for ARS-denominated payments. | ARS payouts to Argentine bank accounts via Interbanking. | "ARS" |
| ETH_WALLET | Ethereum network wallet for stablecoin payouts (USDT, USDC, RLUSD). | Crypto payouts to Ethereum wallet addresses. | "USDT / USDC / RLUSD" |
| TRON_WALLET | Tron network wallet for USDT payouts. | USDT payouts to Tron wallet addresses. | "USDT" |
| SOL_WALLET | Solana network wallet for USDC payouts. | USDC payouts to Solana wallet addresses. | "USDC" |


Corridor coverage
Each instrument type is supported only for specific country–currency corridors.

For full corridor coverage, see [Payout network](/products/payments-direct-2/introduction/payout-network).

## Bank account rails and fields

This section summarizes the key fields for each bank-account-based instrument.

US_ACH
The `usAch` object is used when `financialInstrumentType` is `US_ACH`.

| Field | Type | Required | Description | Example |
|  --- | --- | --- | --- | --- |
| bankName | string | Yes | Name of the bank holding the account. | "Bank of Example" |
| bankRoutingNumber | string | Yes | 9-digit routing number (ABA Routing Transit Number). | "266231608" |
| accountNumber | string | Yes | Account number to be credited. | "60480" |
| accountType | string | Yes | Type of bank account. Values include CHECKING and SAVINGS. | "CHECKING" |


Usage notes
- `currency` is typically `USD`.
- Used for U.S. domestic payouts over ACH (and related real-time rails where applicable).


US_FEDWIRE
The `usFedwire` object is used when `financialInstrumentType` is `US_FEDWIRE`.

| Field | Type | Required | Description | Example |
|  --- | --- | --- | --- | --- |
| bankName | string | Yes | Name of the bank where funds will be credited. | "Bank of Example" |
| bankRoutingNumber | string | Yes | 9-digit ABA routing number of the beneficiary’s bank. | "266231608" |
| accountNumber | string | Yes | Account number to be credited (high-value Fedwire destination). | "60480" |


Usage notes
- `currency` is typically `USD`.
- Intended for high-value or time-critical U.S. domestic transfers.


MX_SPEI
The `mxSpei` object is used when `financialInstrumentType` is `MX_SPEI`.

| Field | Type | Required | Description | Example |
|  --- | --- | --- | --- | --- |
| bankName | string | Yes | Name of the Mexican bank. | "Bank of Example" |
| clabe | string | Yes | 18-digit CLABE account identifier for the beneficiary. | "014027000005555558" |


Usage notes
- `currency` is typically `MXN`.
- Used for MXN payouts to Mexican bank accounts.


EU_SEPA
The `euSepa` object is used when `financialInstrumentType` is `EU_SEPA`.

| Field | Type | Required | Description | Example |
|  --- | --- | --- | --- | --- |
| bankName | string | Yes | Name of the bank. | "Bank of Example" |
| iban | string | Yes | IBAN of the account (15–34 characters, country and checksum-prefixed). | "DE89370400440532013000" |


Usage notes
- `currency` is typically `EUR`.
- IBAN must follow SEPA-format rules; validation is enforced by the API.


GB_FPS
The `gbFps` object is used when `financialInstrumentType` is `GB_FPS`.

| Field | Type | Required | Description | Example |
|  --- | --- | --- | --- | --- |
| bankName | string | Yes | Name of the UK bank. | "Bank of Example" |
| sortCode | string | Yes | 6-digit sort code for the bank/branch. | "123456" |
| accountNumber | string | Yes | 8-digit account number. | "12345678" |


Usage notes
- `currency` is typically `GBP`.
- Used for Faster Payments/CHAPS-style payouts.


CA_EFT
The `caEft` object is used when `financialInstrumentType` is `CA_EFT`.

| Field | Type | Required | Description | Example |
|  --- | --- | --- | --- | --- |
| bankName | string | Yes | Name of the Canadian financial institution. | "Bank of Example" |
| institutionNumber | string | Yes | 3-digit institution number. | "123" |
| transitNumber | string | Yes | 5-digit transit number for the branch. | "12345" |
| accountNumber | string | Yes | Account number (typically 7–12 digits). | "12345678" |
| accountType | string | Yes | Type of bank account. Values include CHECKING and SAVINGS. | "CHECKING" |


Usage notes
- `currency` is typically `CAD`.
- Used for Canadian domestic payouts over EFT.


NG_BANK_PAYOUT
The `ngBankPayout` object is used when `financialInstrumentType` is `NG_BANK_PAYOUT`.

| Field | Type | Required | Description | Example |
|  --- | --- | --- | --- | --- |
| bankName | string | Yes | Name of the beneficiary’s bank. | "Guaranty Trust Bank PLC" |
| bankCode | string | Yes | Ripple Bank Code for the destination bank. Format: `RPL:NG:[ALIAS]:BNK`. Use the [Bank Codes](/products/payments-direct-2/api-docs/integration-resources/ripple-bank-codes) lookup to find the correct code before creating the instrument. | "RPL:NG:GTBINGLA:BNK" |
| accountNumber | string | Yes | Account number at the destination bank. | "0123456789" |


Usage notes
- `currency` is `NGN`.
- `bankCode` must be a valid Ripple Bank Code (RBC). Use the [Bank Codes](/products/payments-direct-2/api-docs/integration-resources/ripple-bank-codes) lookup utility to find the correct RBC for the destination bank before creating the instrument.


CO_PSE
The `coPse` object is used when `financialInstrumentType` is `CO_PSE`.

| Field | Type | Required | Description | Example |
|  --- | --- | --- | --- | --- |
| bankName | string | Yes | Name of the Colombian bank. | "Bank of Example" |
| bankCode | string | Yes | Bank code for the PSE payout (2-4 digits, numeric). | "1007" |
| accountNumber | string | Yes | Account number for the PSE payout. | "12345678" |
| accountType | string | Yes | Type of account. Values include CURRENT and SAVINGS. | "CURRENT" |


Usage notes
- `currency` is typically `COP`.
- Used for Colombian PSE payouts.


BR_TED
The `brTed` object is used when `financialInstrumentType` is `BR_TED`.

| Field | Type | Required | Description | Example |
|  --- | --- | --- | --- | --- |
| bankName | string | Yes | Name of the Brazilian bank. | "Bank of Example" |
| bankCode | string | Yes | BICFI bank code for the beneficiary’s bank (8-11 alphanumeric characters). | "BRASTCAA" |
| branchNumber | string | Yes | 4-digit branch number for the beneficiary’s account. | "1234" |
| accountNumber | string | Yes | Account number for the beneficiary (5-14 digits). | "1234567890" |
| accountType | string | Yes | Type of bank account. Values include CHECKING and SAVINGS. | "CHECKING" |


Usage notes
- `currency` is typically `BRL`.
- Used for Brazilian bank transfers via TED.


BR_PIX
The `brPix` object is used when `financialInstrumentType` is `BR_PIX`.

| Field | Type | Required | Description | Example |
|  --- | --- | --- | --- | --- |
| bankName | string | Yes | Name of the Brazilian bank. | "Bank of Example" |
| bankCode | string | Yes | BICFI bank code for the beneficiary’s bank (8–11 characters). | "BRASBRRJBHE" |
| branchNumber | string | Yes | Bank branch number (4–6 digits). | "0001" |
| pixKey | string | Yes | The PIX key for the beneficiary: an email address, phone number, CPF/CNPJ, or EVP random key. | "fake@example.com" |
| pixKeyType | string | Yes | Type of PIX key provided. Values: `CPF`, `CNPJ`, `EMAIL`, `PHONE`, `EVP`. | "EMAIL" |


Usage notes
- `currency` is typically `BRL`.
- Used for Brazilian instant payments via PIX.


GH_BANK_PAYOUT
The `ghBankPayout` object is used when `financialInstrumentType` is `GH_BANK_PAYOUT`.

| Field | Type | Required | Description | Example |
|  --- | --- | --- | --- | --- |
| bankName | string | Yes | Name of the beneficiary’s bank. | "Ecobank Ghana" |
| bankCode | string | Yes | Bank code of the beneficiary’s bank. | "GH123" |
| accountNumber | string | Yes | Account number at the destination bank (4–21 alphanumeric characters). | "0123456789" |


Usage notes
- `currency` is `GHS`.
- Used for GHS payouts to Ghanaian bank accounts via GIS.


RW_BANK_PAYOUT
The `rwBankPayout` object is used when `financialInstrumentType` is `RW_BANK_PAYOUT`.

| Field | Type | Required | Description | Example |
|  --- | --- | --- | --- | --- |
| bankName | string | Yes | Name of the beneficiary’s bank. | "Bank of Kigali" |
| bankCode | string | Yes | Bank code of the beneficiary’s bank. | "RW123" |
| accountNumber | string | Yes | Account number at the destination bank (4–21 alphanumeric characters). | "0123456789" |


Usage notes
- `currency` is `RWF`.
- Used for RWF payouts to Rwandan bank accounts via RSwitch.
- Supported use case: C2B2C only.


ZA_BANK_PAYOUT
The `zaBankPayout` object is used when `financialInstrumentType` is `ZA_BANK_PAYOUT`.

| Field | Type | Required | Description | Example |
|  --- | --- | --- | --- | --- |
| bankName | string | Yes | Name of the beneficiary’s bank. | "Standard Bank" |
| bankCode | string | Yes | Bank code of the beneficiary’s bank. | "ZA123" |
| accountNumber | string | Yes | Account number at the destination bank (4–21 alphanumeric characters). | "0123456789" |


Usage notes
- `currency` is `ZAR`.
- Used for ZAR payouts to South African bank accounts via PayShap.
- Supported use case: C2B2C only.


UG_BANK_PAYOUT
The `ugBankPayout` object is used when `financialInstrumentType` is `UG_BANK_PAYOUT`.

| Field | Type | Required | Description | Example |
|  --- | --- | --- | --- | --- |
| bankName | string | Yes | Name of the beneficiary’s bank. | "Stanbic Bank Uganda" |
| bankCode | string | Yes | Bank code of the beneficiary’s bank. | "UG123" |
| accountNumber | string | Yes | Account number at the destination bank (4–21 alphanumeric characters). | "0123456789" |


Usage notes
- `currency` is `UGX`.
- Used for UGX payouts to Ugandan bank accounts.


ZM_BANK_PAYOUT
The `zmBankPayout` object is used when `financialInstrumentType` is `ZM_BANK_PAYOUT`.

| Field | Type | Required | Description | Example |
|  --- | --- | --- | --- | --- |
| bankName | string | Yes | Name of the beneficiary’s bank. | "Zanaco" |
| bankCode | string | Yes | Bank code of the beneficiary’s bank. | "ZM123" |
| accountNumber | string | Yes | Account number at the destination bank (4–21 alphanumeric characters). | "0123456789" |


Usage notes
- `currency` is `ZMW`.
- Used for ZMW payouts to Zambian bank accounts via ZECHL.


HK_BANK_PAYOUT
The `hkBankPayout` object is used when `financialInstrumentType` is `HK_BANK_PAYOUT`.

| Field | Type | Required | Description | Example |
|  --- | --- | --- | --- | --- |
| bankName | string | Yes | Name of the beneficiary’s bank. | "DBS Bank (Hong Kong) Limited" |
| accountNumber | string | Yes | Bank account number (BBAN, 2–30 alphanumeric characters). | "0123456789" |
| accountHolderName | string | Yes | Name of the account holder. | "Jane Smith" |
| swiftCode | string | Yes | SWIFT/BIC code of the bank (8 or 11 characters). | "DHBKHKHHXXX" |


Usage notes
- `currency` is `HKD`.
- Used for HKD payouts to Hong Kong bank accounts via CHATS.
- Pre-clearance is required for all senders. Contact your Ripple representative to confirm eligibility before onboarding HKD instruments.


CN_TRADE
The `cnTrade` object is used when `financialInstrumentType` is `CN_TRADE`.

| Field | Type | Required | Description | Example |
|  --- | --- | --- | --- | --- |
| bankName | string | Yes | Beneficiary bank name. Resolved from `bankCode`. | "Industrial and Commercial Bank of China" |
| bankCode | string | Yes | Bank code for the destination bank. Use the [Bank Codes](/products/payments-direct-2/api-docs/integration-resources/ripple-bank-codes) lookup to find the correct code by searching the bank’s English name. | "102100099996" |
| branchName | string | Yes | Bank branch name in Chinese Hanzi characters. | "北京市分行" |
| branchProvince | string | Yes | Province code (numeric). For example, `110000` = Beijing. | "110000" |
| branchCity | string | Yes | City code (numeric). For example, `110000` = Beijing. | "110000" |
| accountNumber | string | Yes | Beneficiary account number. | "0123456789012345" |
| accountHolderName | string | Yes | Beneficiary account holder name in Chinese Hanzi characters. | "张三" |


Usage notes
- `currency` is `CNY`.
- Used for CNY trade payouts via CNAPS. Purpose code is restricted to trade purposes (`GDDS` — goods, or `SCVE` — services).


Invoice document required
All CN_TRADE payments require a supporting invoice or purchase order per transaction. Document attachment via the API is not yet available. UI customers can upload documents directly in the payment submission flow. API customers should coordinate document submission with their Ripple representative.

See [China (CNY) Transaction Data Requirements](/products/payments-direct-2/api-docs/integration-resources/apac/cn/cny) for full details.

CN_INDIVIDUAL
The `cnIndividual` object is used when `financialInstrumentType` is `CN_INDIVIDUAL`.

| Field | Type | Required | Description | Example |
|  --- | --- | --- | --- | --- |
| bankName | string | Yes | Beneficiary bank name (English). See the published bank list. | "Industrial and Commercial Bank of China" |
| bankCode | string | Yes | Beneficiary bank code. See the published bank code list. | "1021" |
| accountNumber | string | Yes | Beneficiary account number. | "0123456789012345" |


Usage notes
- `currency` is `CNY`.
- Used for CNY payouts to individual Chinese bank accounts via CUP or CNAPS.


CN_INDIVIDUAL_TRADE
The `cnIndividualTrade` object is used when `financialInstrumentType` is `CN_INDIVIDUAL_TRADE`.

| Field | Type | Required | Description | Example |
|  --- | --- | --- | --- | --- |
| bankName | string | Yes | Beneficiary bank name. | "Industrial and Commercial Bank of China" |
| accountNumber | string | Yes | Beneficiary account number. | "0123456789012345" |
| accountHolderName | string | Yes | Beneficiary account holder name in Chinese Hanzi characters. For sole proprietors, this may be the business name. | "张三" |


Usage notes
- `currency` is `CNY`.
- Used for CNY individual trade payouts via China UnionPay (CUP).


Invoice document required
All CN_INDIVIDUAL_TRADE payments require a supporting invoice or purchase order per transaction. Document attachment via the API is not yet available. UI customers can upload documents directly in the payment submission flow. API customers should coordinate document submission with their Ripple representative.

See [China (CNY) Transaction Data Requirements](/products/payments-direct-2/api-docs/integration-resources/apac/cn/cny) for full details.

CN_CFXPS
The `cnCfxps` object is used when `financialInstrumentType` is `CN_CFXPS`.

| Field | Type | Required | Description | Example |
|  --- | --- | --- | --- | --- |
| bankName | string | Yes | Beneficiary bank name. Resolved from `swiftCode`. | "Industrial and Commercial Bank of China" |
| swiftCode | string | Yes | SWIFT/BIC code of the beneficiary’s bank (8 or 11 characters). | "ICBKCNBJXXX" |
| accountNumber | string | Yes | Beneficiary account number. | "0123456789012345" |
| accountHolderName | string | Yes | Beneficiary account holder name (English). | "Zhang San" |


Usage notes
- `currency` is `USD`.
- Used for USD payouts to China via the Cross-Border Foreign Exchange Payment System (CFXPS).


Beneficiary document collection
After a CN_CFXPS payment reaches `COMPLETED` status, the beneficiary's bank will contact the beneficiary directly to collect compliance documentation before releasing funds to the beneficiary's account. This process is outside Ripple's control and no SLA applies. Final settlement may take 2–3 business days or longer depending on when the beneficiary provides satisfactory documentation.

See [China (USD) Transaction Data Requirements](/products/payments-direct-2/api-docs/integration-resources/apac/cn/usd) for full details.

AE_IPI
The `aeIpi` object is used when `financialInstrumentType` is `AE_IPI`.

| Field | Type | Required | Description | Example |
|  --- | --- | --- | --- | --- |
| bankName | string | Yes | Name of the identity's bank. | "Emirates NBD" |
| iban | string | Yes | International Bank Account Number (IBAN) of the identity's account (23 characters, starting with `AE`). | "AE460330000012345678901" |


Usage notes
- `currency` is `AED`.
- Two rails are evaluated in order: **IPI** (real-time, up to AED 25,000, no cutoff) is used first when the beneficiary account is IPI-addressable; otherwise **FTS** (same-day, no limit, ~2:00 PM GST cutoff) is used. UAE Central Bank holidays apply to FTS.


IN_NEFT
The `inNeft` object is used when `financialInstrumentType` is `IN_NEFT`.

| Field | Type | Required | Description | Example |
|  --- | --- | --- | --- | --- |
| bankName | string | Yes | Name of the identity's bank. | "HDFC Bank" |
| ifscCode | string | Yes | 11-character IFSC code of the identity's bank branch. | "HDFC0001234" |
| accountNumber | string | Yes | Identity's bank account number. | "1234567890" |


Usage notes
- `currency` is `INR`.
- Used for INR payouts via NEFT (National Electronic Funds Transfer). Business days and banking hours only; no transaction limit; cutoff is 7:00 PM IST (varies by bank). India banking holidays apply.


ID_BIFAST
The `idBifast` object is used when `financialInstrumentType` is `ID_BIFAST`.

| Field | Type | Required | Description | Example |
|  --- | --- | --- | --- | --- |
| bankName | string | Yes | Name of the identity's bank. | "Bank Mandiri" |
| bankCode | string | Yes | Bank Indonesia-assigned domestic clearing code. Use the [Bank Codes](/products/payments-direct-2/api-docs/integration-resources/ripple-bank-codes) lookup to find the correct code. | "008" |
| accountNumber | string | Yes | Identity's bank account number. | "1234567890" |


Usage notes
- `currency` is `IDR`.
- Used for IDR payouts via BI-FAST. Available 24/7/365, no cutoff, with a limit of IDR 50,000,000 per transaction.


TR_FAST
The `trFast` object is used when `financialInstrumentType` is `TR_FAST`.

| Field | Type | Required | Description | Example |
|  --- | --- | --- | --- | --- |
| bankName | string | Yes | Name of the identity's bank. | "Türkiye İş Bankası" |
| iban | string | Yes | Turkey IBAN (26 characters, starting with `TR`). | "TR330006100519786457841326" |
| bankCode | string | Yes | SWIFT/BIC code of the identity's bank. Named `bankCode` for v2 ADR compatibility; maps to BICFI in ISO 20022. | "ISBKTRIS" |


Usage notes
- `currency` is `TRY`.
- Two rails are evaluated in order: **FAST** (real-time, within minutes, no limit, no cutoff) is used first when the beneficiary account is FAST-addressable; otherwise **EFT** (same-day or next business day, no limit, 5:30 PM TRT cutoff) is used. Turkey banking holidays apply to EFT.


PH_NRPS
The `phNrps` object is used when `financialInstrumentType` is `PH_NRPS`.

| Field | Type | Required | Description | Example |
|  --- | --- | --- | --- | --- |
| bankName | string | Yes | Name of the identity's bank. | "BDO Unibank" |
| swiftCode | string | Yes | SWIFT/BIC code of the beneficiary bank. Constrained to the SWIFT/BIC code list published on Ripple Docs. | "BNORPHMMXXX" |
| accountNumber | string | Yes | Identity's bank account number. | "123456789012" |


Usage notes
- `currency` is `PHP`.
- Two rails are evaluated in order: **InstaPay** (real-time, within 15 minutes, up to PHP 1,000,000, no cutoff) is used first; otherwise **PESONet** (same-day or next business day, no limit, 2:00 PM PHT cutoff) is used. Philippines banking holidays apply.


CL_TEF
The `clTef` object is used when `financialInstrumentType` is `CL_TEF`.

| Field | Type | Required | Description | Example |
|  --- | --- | --- | --- | --- |
| bankName | string | Yes | Name of the identity's bank. | "Banco de Chile" |
| swiftCode | string | Yes | SWIFT/BIC code of the identity's bank. | "BCHICLRM" |
| accountNumber | string | Yes | Identity's bank account number. | "1234567890123" |
| accountType | string | Yes | Type of bank account. Values include `CHECKING` and `SAVINGS`. | "CHECKING" |


Usage notes
- `currency` is `CLP`.
- Used for CLP payouts via TEF (Transferencia Electrónica de Fondos). Business days only; no transaction limit; cutoff is 3:00 PM CLT. Chile banking holidays apply.


TH_PROMPTPAY
The `thPromptpay` object is used when `financialInstrumentType` is `TH_PROMPTPAY`.

| Field | Type | Required | Description | Example |
|  --- | --- | --- | --- | --- |
| bankName | string | Yes | Name of the identity's bank. | "Bangkok Bank" |
| bankCode | string | Yes | Domestic bank code for the identity's bank in Thailand. See the [Bank Codes](/products/payments-direct-2/api-docs/integration-resources/ripple-bank-codes) resource for the authoritative list of supported values. | "002" |
| accountNumber | string | Yes | Identity's bank account number. | "1234567890" |


Usage notes
- `currency` is `THB`.
- Used for THB payouts via PromptPay (National ITMX). Available 24/7/365, no cutoff, with a limit of THB 500,000 per transaction.


KR_KFTC
The `krKftc` object is used when `financialInstrumentType` is `KR_KFTC`.

| Field | Type | Required | Description | Example |
|  --- | --- | --- | --- | --- |
| bankName | string | Yes | Name of the identity's bank. | "Kookmin Bank" |
| bankCode | string | Yes | KFTC-assigned Korean domestic clearing code. See the [Bank Codes](/products/payments-direct-2/api-docs/integration-resources/ripple-bank-codes) resource for the authoritative list of supported values. | "004" |
| accountNumber | string | Yes | Identity's bank account number. | "110123456789" |


Usage notes
- `currency` is `KRW`.
- Used for KRW payouts via KFTC (Korea Financial Telecommunications and Clearings). Available 24/7/365, no cutoff, with a limit of KRW 10,000,000 per transaction (varies).


PE_LBTR
The `peLbtr` object is used when `financialInstrumentType` is `PE_LBTR`.

| Field | Type | Required | Description | Example |
|  --- | --- | --- | --- | --- |
| bankName | string | Yes | Name of the identity's bank. | "Banco de Crédito del Perú" |
| swiftCode | string | Yes | SWIFT/BIC code of the identity's bank. | "BCPLPEPL" |
| accountNumber | string | Yes | Identity's bank account number. | "1234567890" |
| accountType | string | Yes | Type of bank account. Values include `CHECKING` and `SAVINGS`. | "CHECKING" |


Usage notes
- `currency` is `PEN`.
- Used for PEN payouts via LBTR (Sistema de Liquidación Bruta en Tiempo Real). Business days and banking hours only; minimum transaction amount is 5 USD; cutoff is 3:00 PM PET. Peru banking holidays apply.


AR_INTERBANKING
The `arInterbanking` object is used when `financialInstrumentType` is `AR_INTERBANKING`.

| Field | Type | Required | Description | Example |
|  --- | --- | --- | --- | --- |
| bankName | string | Yes | Name of the identity's bank. | "Banco de la Nación Argentina" |
| bankCode | string | Yes | BCRA-assigned 3-digit Argentine bank code. See the [Bank Codes](/products/payments-direct-2/api-docs/integration-resources/ripple-bank-codes) resource for the authoritative list of supported values. | "011" |
| accountNumber | string | Yes | Identity's account number (CBU or CVU, 22 digits). | "0110599520000001234567" |
| accountType | string | Yes | Type of bank account. Values include `CHECKING` (Cuenta Corriente) and `SAVINGS` (Caja de Ahorro). | "CHECKING" |


Usage notes
- `currency` is `ARS`.
- Used for ARS payouts via Interbanking. Business days only; limit is ARS 10,000,000 per transaction; cutoff is 3:00 PM ART. Argentina banking holidays apply.


ETH_WALLET
The `ethWallet` object is used when `financialInstrumentType` is `ETH_WALLET`.

| Field | Type | Required | Description | Example |
|  --- | --- | --- | --- | --- |
| walletAddress | string | Yes | Ethereum wallet address at the exchange (42 characters, starting with `0x`). | "0x742d35Cc6634C0532925a3b844Bc454e4438f44e" |
| cryptoInstitutionName | string | Yes | Name of the crypto exchange holding the wallet. | "Bitso" |


Usage notes
- Supports USDT, USDC, and RLUSD payouts on the Ethereum network.
- The `country` metadata field returns `ZZ` for all crypto wallet instruments.


TRON_WALLET
The `tronWallet` object is used when `financialInstrumentType` is `TRON_WALLET`.

| Field | Type | Required | Description | Example |
|  --- | --- | --- | --- | --- |
| walletAddress | string | Yes | Tron wallet address at the exchange (34 characters, starting with `T`). | "T9yD14Nj9j7xAB4dbGeiX9h8unkKHxuWwb" |
| cryptoInstitutionName | string | Yes | Name of the crypto exchange holding the wallet. | "Bitso" |


Usage notes
- Supports USDT payouts on the Tron network.
- The `country` metadata field returns `ZZ` for all crypto wallet instruments.


SOL_WALLET
The `solWallet` object is used when `financialInstrumentType` is `SOL_WALLET`.

| Field | Type | Required | Description | Example |
|  --- | --- | --- | --- | --- |
| walletAddress | string | Yes | Solana wallet address at the exchange (32–44 characters, base58-encoded). | "7EcDhSYGxXyscszYEp35KHN8vvw3svAuLKTzXwCFLtV" |
| cryptoInstitutionName | string | Yes | Name of the crypto exchange holding the wallet. | "Bitso" |


Usage notes
- Supports USDC payouts on the Solana network.
- The `country` metadata field returns `ZZ` for all crypto wallet instruments.


## Validation and data requirements

**Financial instrument data is validated in two ways:**

1. Structural validation
  - **Identity Management v3** ensures required fields for the specified `financialInstrumentType` are present.
  - Field patterns (length, character sets, IBAN/CLABE formats, routing formats, and so on) are enforced.
2. Corridor compatibility
  - Only certain combinations of instrument type, currency, and payout corridor are supported.
  - If an instrument cannot be used for any corridor you’re enabled for, creation or updates may fail.


### Identity validation with `validatePayoutRails`

When creating a financial instrument, the associated identity must have all required PII for the specified `financialInstrumentType`. You can use the `validatePayoutRails` field on the identity to validate PII requirements upfront:

- If you specified `validatePayoutRails` when creating the identity (for example, `["US_ACH", "MX_SPEI"]`), the identity's PII was already validated against those rails.
- When you create a financial instrument with a matching `financialInstrumentType` (for example, `US_ACH`), the instrument creation succeeds immediately because the identity is already validated.
- If you create a financial instrument for a rail **not** listed in `validatePayoutRails`, the identity's PII is validated at instrument creation time. If required fields are missing, the request fails with **400 Bad Request**.


Upfront validation
Using `validatePayoutRails` on identities helps catch PII issues early, before you attempt to create financial instruments or payments. For details, see [Validating identities for specific payout rails](/products/payments-direct-2/introduction/concepts/payment-identities#validating-identities-for-specific-payout-rails).

## Next steps

- To see how to create, update, list, and deactivate financial instruments using the API, continue with [Create and manage financial instruments](/products/payments-direct-2/api-docs/developer-guides/create-and-manage-financial-instruments).
- To review how account details connect back to KYC data and specific payment roles, see [Payment identities](/products/payments-direct-2/introduction/concepts/payment-identities).