Financial instruments

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.

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:

{
  "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"
  }
}

Financial instrument metadata

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

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.

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.

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.

Bank account rails and fields

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

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.

Next steps

• To see how to create, update, list, and deactivate financial instruments using the API, continue with Create and manage financial instruments.
• To review how account details connect back to KYC data and specific payment roles, see Payment identities.