# Financial instruments

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

Identity Management v3 is an **upcoming feature**. For information on availability, early access, or migration, please contact your Ripple representative.

The supported payment corridors will be:

- US • USD
- EU • EUR
- MX • MXN
- BR • BRL
- CO • COP
- CA • CAD
- GB • GBP
- Africa • GHS, NGN, RWF, UGX, ZAR, ZMW


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 have multiple financial instruments**, enabling a single party to hold several bank accounts or payout rails.
- 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/api-docs/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. Values include `US_ACH`, `US_FEDWIRE`, `MX_SPEI`, `EU_SEPA`, `GB_FPS`, `AFRICA_BANK_PAYOUT`, `BR_PIX`, `CO_PSE`, `BR_TED`, `CA_EFT`. | "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. | "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**, an identity can have one or more financial instruments (bank accounts or other payout methods) attached to it. This allows you to keep a single, reusable KYC record for a party while managing multiple payout accounts and rails underneath that identity.

**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 one or more financial instruments**Use `POST /v3/identities/{identity-id}/financial-instruments` to attach a new 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

Multiple financial instruments per identity 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; prefer a single identity with multiple financial 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" |
| AFRICA_BANK_PAYOUT | Bank payout rails in supported African markets (for example, Ghana, Nigeria, Rwanda, Uganda, South Africa). | Local-currency payouts to bank accounts in Africa. | Varies by corridor |
| 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" |


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.


AFRICA_BANK_PAYOUT
The `africaBankPayout` object is used when `financialInstrumentType` is `AFRICA_BANK_PAYOUT`.

| Field | Type | Required | Description | Example |
|  --- | --- | --- | --- | --- |
| bankName | string | Yes | Name of the beneficiary’s bank. | "Bank of Example" |
| bankCode | string | Yes | Bank identifier code (format depends on the destination country). | "12345" |
| accountNumber | string | Yes | Account number at the destination bank. | "12345678" |
| country | string | Yes | 2-letter ISO country code representing the destination country. | "GH" |


Usage notes
- `currency` varies by corridor (for example, GHS, NGN, RWF, UGX, ZAR, ZMW).
- Used for bank payouts in supported African markets; exact format and limits are corridor-specific.


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 | 5-digit code for the beneficiary’s bank. | "12345" |
| 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 | 8-digit code for the beneficiary’s bank. | "12345678" |
| branchNumber | string | Yes | 4-digit branch number for the beneficiary’s account. | "1234" |
| accountNumber | string | Yes | 10-digit account number for the beneficiary. | "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.


## 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/api-docs/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/tutorials/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/api-docs/concepts/payment-identities).