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

- Keep one KYC’d identity per party, independent of the account details.
- Reuse that identity across payments without resubmitting PII.
- Rotate or replace a party’s account without re-creating the identity or losing history.


One instrument per identity
Each identity supports **one active financial instrument**. See [One financial instrument per identity](#one-financial-instrument-per-identity).

## 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 payment rails (for example, `usAch`, `euSepa`, `mxSpei`, `gbFps`, `brPix`).
- How many financial instruments an identity can hold, and how to replace an instrument when a party’s account changes.
- 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 payment 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.

## One financial instrument per identity

In **Identity Management v3**, each identity supports **one active financial instrument**. Adding a second instrument to an identity that already has one fails with **422 Unprocessable Entity** and error code `USR_120` (Maximum financial instruments reached).

Support for multiple financial instruments per identity is planned for a future release. It is not available today and cannot be enabled on request.

**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 keep a single KYC record per party. The identity is reused across payments, and its financial instrument can be replaced over time without re-creating the identity or resubmitting PII.

If a party needs two accounts at once
Because an identity holds one instrument at a time, a party that must receive payments to two different accounts concurrently (for example, an MXN SPEI account and a USD ACH account) currently requires a **separate identity for each account**.

Each identity needs its own unique `internalId`. Reusing an `internalId` that belongs to an active identity fails with **409 Conflict**.

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

### Replacing a beneficiary’s account

If a beneficiary changes their bank account, keep the identity and replace the instrument. Because an identity holds one instrument at a time, the order matters:

1. **Deactivate the existing instrument**Use `DELETE /v3/identities/{identity-id}/financial-instruments/{financial-instrument-id}`. This frees the identity’s instrument slot. Historical usage of the deactivated instrument remains available for audit.
2. **Add the replacement instrument**Use `POST /v3/identities/{identity-id}/financial-instruments`.


Adding the new instrument first fails with **422 Unprocessable Entity** (`USR_120`), because the identity still holds the old one.

To correct details on an account the beneficiary is keeping, use `PUT` instead of replacing the instrument. `PUT` updates the `label` and rail-specific fields such as the account number, but it cannot change `financialInstrumentType` or `currency`. Changing the rail or currency requires deactivating the instrument and adding a new one.

### Best practices

- Use the `label` field on financial instruments to make accounts easy to distinguish (for example, "operating-USD", "payroll-EUR", "MXN-SPEI-local").
- Keep one identity per real-world party wherever possible, and replace that identity’s instrument when the party’s account changes. Create a second identity only when a party needs two accounts active at the same time.
- 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 | RTP-primary U.S. domestic rail. Routes over RTP first, falling back to ACH when the beneficiary routing number isn't RTP-enabled. | Domestic U.S. bank transfers in USD. | "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 payment 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 payment rail via GIS. | GHS payouts to Ghanaian bank accounts. | "GHS" |
| RW_BANK_PAYOUT | Rwanda bank payment rail via RSwitch. | RWF payouts to Rwandan bank accounts. | "RWF" |
| ZA_BANK_PAYOUT | South Africa bank payment rail via PayShap. | ZAR payouts to South African bank accounts. | "ZAR" |
| UG_BANK_PAYOUT | Uganda bank payment rail. | UGX payouts to Ugandan bank accounts. | "UGX" |
| ZM_BANK_PAYOUT | Zambia bank payment rail via ZECHL. | ZMW payouts to Zambian bank accounts. | "ZMW" |
| 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" |
| 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" |
| JP_ZENGIN | Japan Zengin - multi-rail (Zengin + Zengin Prompt Service) domestic clearing system for JPY-denominated payments. | JPY payouts to Japanese bank accounts via Zengin, with Zengin Prompt Service for real-time low-value transfers. | "JPY" |
| 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" |
| AU_NPP | Australia New Payments Platform - real-time payment rail for AUD-denominated domestic transfers, with Direct Entry (BECS) fallback for high-value and batch. | AUD payouts to Australian bank accounts via NPP, with Direct Entry (BECS) fallback for high-value and batch. | "AUD" |
| CN_CFXPS | China Foreign Exchange Payment System (CFXPS). | USD payouts to Chinese bank accounts via CFXPS. | "USD" |
| 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`.
- `US_ACH` routes over RTP first and falls back to ACH when the beneficiary routing number isn't RTP-enabled. The name reflects U.S. routing-number terminology (ACH routing numbers are reused for RTP).


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. | "RPL:GH:BARCGHAC:BNK" |
| 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. | "RPL:RW:ABBRRWRW:BNK" |
| 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. | "RPL:ZA:ABSAZAJJ:BNK" |
| 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. | "RPL:UG:ABCFUGKA:BNK" |
| 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. | "RPL:ZM:ABBAZMLU:BNK" |
| 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.


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.


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. | "BCHICLRMCUS" |
| 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.


JP_ZENGIN
The `jpZengin` object is used when `financialInstrumentType` is `JP_ZENGIN`.

| Field | Type | Required | Description | Example |
|  --- | --- | --- | --- | --- |
| bankName | string | Yes | Name of the identity's bank. | "MUFG Bank" |
| bankCode | string | Yes | Zengin-Net/BOJ-assigned 4-digit Japanese bank code. Use the [Bank Codes](/products/payments-direct-2/api-docs/integration-resources/ripple-bank-codes) lookup to find the correct code. | "0005" |
| branchCode | string | Yes | Bank-assigned branch code identifying the specific branch. | "001" |
| accountNumber | string | Yes | Identity's bank account number. | "1234567" |
| accountType | string | Yes | Account type. One of `CHECKING` (当座預金), `ORDINARY` (普通預金), or `SAVINGS` (貯蓄預金). | "ORDINARY" |
| accountHolderName | string | Yes | Name of the account holder in Japanese Katakana characters. | "ヤマダタロウ" |


Usage notes
- `currency` is `JPY`.
- Two rails are evaluated in order: **Zengin Prompt Service** (real-time, typically up to JPY 1,000,000, no cutoff, no banking holidays) is used first when the beneficiary account is ZPS-addressable; otherwise **Zengin** (same-day or next business day, no limit, 9:00 PM JST cutoff) is used. Japan banking holidays apply to Zengin.
- `accountHolderName` must be supplied in Katakana. The schema pattern accepts other scripts, so a name in Latin characters passes schema validation even though it does not meet the corridor requirement.


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


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

AU_NPP
The `auNpp` object is used when `financialInstrumentType` is `AU_NPP`.

| Field | Type | Required | Description | Example |
|  --- | --- | --- | --- | --- |
| bankName | string | Yes | Name of the identity's bank. | "Commonwealth Bank of Australia" |
| bsbCode | string | Yes | The 6-digit Bank-State-Branch (BSB) routing code. | "062000" |
| accountNumber | string | Yes | Identity's bank account number. | "12345678" |


Usage notes
- `currency` is `AUD`.
- Two rails are evaluated in order: **NPP** (real-time, within 15 minutes, up to AUD 20,000 per transaction, no cutoff, no banking holidays) is used first when the beneficiary account is NPP-addressable; otherwise **Direct Entry (BECS)** (same-day or next business day, no limit, bank-dependent cutoff) is used. Australian banking holidays apply to Direct Entry.


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 payment rails](/products/payments-direct-2/introduction/concepts/payment-identities#validating-identities-for-specific-payment-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).