# Add a financial instrument (v3)

Create a financial instrument for the specified identity. The request body must include the payment rail (financialInstrumentType), currency or asset code, and the rail-specific details (for example, US ACH account numbers or a wallet address).
In the current release, each identity can have one financial instrument.
Future releases will support multiple instruments per identity.

Endpoint: POST /v3/identities/{identity-id}/financial-instruments
Version: 2026.03
Security: Bearer

## Path parameters:

  - `identity-id` (string, required)
    Unique identifier of the identity that will own the financial instrument.
    Example: "2f4ac57f-c5ba-4051-b51f-b3565778717b"

## Request fields (application/json):

  - `usAch` (object)
    Rails: RTP, ACH

Rail Definitions:

RTP:
  - Availability: 24/7/365
  - Limit: $5,000,000
  - Settlement: <5 minutes
  - Cut-off time: None
  - Banking holidays: Not applicable

ACH:
  - Availability: Business days only
  - Limit: $1,000,000
  - Settlement: Same-day
  - Cut-off time: 3:00 PM EST
  - Banking holidays: U.S. banking holidays apply

Routing Evaluation Order:

  1. RTP
     - Conditions: beneficiary account is RTP-addressable AND amount ≤ $5,000,000
  2. ACH
     - Conditions: otherwise applicable

  - `usAch.bankName` (string, required)
    The name of the identity's bank

  - `usAch.bankRoutingNumber` (string, required)
    The identity's bank routing number

  - `usAch.accountNumber` (string, required)
    The identity's account number into which the funds must be credited

  - `usAch.accountType` (string, required)
    The identity’s account type.

- CHECKING — Checking account  
- SAVINGS — Savings account

  - `usFedwire` (object)
    Rails: FEDWIRE

Rail Definitions:

FEDWIRE:
  - Availability: U.S. business days and operating hours.
  - Limit: No limit
  - Settlement: Real-time gross settlement (typically within minutes).
  - Cut-off time: 5:00 p.m. ET; transfers submitted after cut-off queue for next business day.
  - Banking holidays: Follows the Federal Reserve holiday schedule.

  - `usFedwire.bankName` (string, required)
    The name of the identity's bank.

  - `usFedwire.bankRoutingNumber` (string, required)
    9-digit ABA Routing Transit Number (RTN) of the beneficiary’s bank.

  - `usFedwire.accountNumber` (string, required)
    The identity's account number to be credited.

  - `mxSpei` (object)
    Rails: SPEI

Rail Definitions:

SPEI:
- Availability: 24/7/365
- Limit: None
- Settlement: Instant
- Cut-off time: None
- Banking holidays: Not applicable

Routing Evaluation Order: Not applicable

  - `mxSpei.clabe` (string, required)
    The identity's CLABE account identification code

  - `euSepa` (object)
    Rails: SCT Inst, SCT

Rail Definitions:

SCT Inst:
- Availability: 24/7/365
- Limit: €100,000 (bank-dependent)
- Settlement: Instant
- Cut-off time: None
- Banking holidays: Not applicable

SCT:
- Availability: Business days only
- Limit: No limit
- Settlement: T+2 to T+5 
- Cut-off time: 3:00PM GMT/BST
- Banking holidays: TARGET2 holidays apply

Routing Evaluation Order:

  1. SCT Inst  
     - Conditions: beneficiary account is SCT Inst-addressable AND amount ≤ €100,000
  2. SCT  
     - Conditions: otherwise applicable

  - `euSepa.iban` (string, required)
    The International Bank Account Number (IBAN) of the identity's account

  - `gbFps` (object)
    Rails: FPS, CHAPS

Rail Definitions:

FPS:
- Availability: 24/7/365
- Limit: £1,000,000
- Settlement: Instant
- Cut-off time: None
- Banking holidays: Not applicable

CHAPS:
- Availability: Business days only
- Limit: No limit
- Settlement: Same-day
- Cut-off time: Typically 5:00 PM GMT/BST (bank-dependent)
- Banking holidays: UK banking holidays apply

Routing Evaluation Order:
  1. FPS  
     - Conditions: beneficiary account is FPS-addressable AND amount ≤ £1,000,000
  2. CHAPS  
     - Conditions: otherwise applicable

  - `gbFps.sortCode` (string, required)
    The sort code of the identity's bank account

  - `gbFps.accountNumber` (string, required)
    The account number of the identity's bank account

  - `africaBankPayout` (object)
    Rails: Bank Payout

Rail Definitions:

Bank Payout:
- Availability: Country-dependant
- Limit:
  - Ghana: ₵100,000
  - Nigeria: ₦5,000,000
  - Zambia: ZK 150,000
  - Uganda: UGX 20,000
  - Rwanda: RWF 10,000,000
  - South Africa: R 300,000
- Settlement: Real time to 48 hours
- Cut-off time: Real time
- Banking holidays: Country specific banking holidays apply
- Routing Evaluation Order: Not applicable

  - `africaBankPayout.bankCode` (string, required)
    The bank code of the identity's bank

  - `africaBankPayout.accountNumber` (string, required)
    The identity's account number associated with the Account Identification Scheme

  - `africaBankPayout.country` (string, required)
    The country of the identity’s bank, using the Alpha-2 code as defined in ISO 3166-1.  
Allowed values are:

- GH  
- NG  
- RW  
- UG  
- ZA  
- ZM
    Example: "NG"

  - `brPix` (object)
    Rails: PIX

Rail Definitions:

PIX:
- Availability: 24/7/365
- Limit: No limit
- Settlement: Instant
- Cut-off time: None
- Banking holidays: Not applicable

Routing Evaluation Order: Not applicable

  - `brPix.bankCode` (string, required)
    The code of the identity's bank (BICFI code)

  - `brPix.branchNumber` (string, required)
    The identity's bank branch number

  - `brPix.pixKey` (string, required)
    The identity's PIX key, which can be an email, phone number, or a hash

  - `brPix.pixKeyType` (string, required)
    The type of PIX key used by the identity.

- CPF  
- CNPJ  
- EMAIL  
- PHONE  
- EVP

  - `coPse` (object)
    Rails: PSE

Rail Definitions:

PSE:
- Availability: Business days and banking hours only
- Limit: None
- Settlement: 
	- Major banks (Bancolombia, Davivienda, Banco de Bogotá, BBVA, Grupo Aval, Nequi): 35–100 min
	- Other banks (via ACH): Same-day or T+1 depending on cutoff
- Cut-off time: 3PM COT
- Banking holidays: Colombia banking holidays apply

Routing Evaluation Order: Not applicable

  - `coPse.bankCode` (string, required)
    The identity's bank identifier code

  - `coPse.accountType` (string, required)
    The type of account associated with the identity.

- CURRENT  
- SAVINGS

  - `brTed` (object)
    Rails: TED

Rail Definitions:

TED:
- Availability: Business days only
- Limit: No limit
- Settlement: Same-day
- Cut-off time: ~5:00 PM BRT 
- Banking holidays: Brazil banking holidays apply

Routing Evaluation Order: Not applicable

  - `brTed.branchNumber` (string, required)
    The branch number of the identity's bank account

  - `brTed.accountType` (string, required)
    The identity's account type (Savings, Checking etc.):
    * CHECKING: Checking account
    * SAVINGS: Savings account
    Example: "SAVINGS"

  - `caEft` (object)
    Rails: EFT

Rail Definitions:

EFT:
- Availability: Business days only
- Limit: CAD 1,000,000
- Settlement: T+1
- Cut-off time: ~4:30 PM EST
- Banking holidays: Canadian banking holidays apply

Routing Evaluation Order: Not applicable

  - `caEft.institutionNumber` (string, required)
    The institution number of the identity's bank

  - `caEft.transitNumber` (string, required)
    The transit number of the identity's bank account

  - `currency` (string, required)
    The 3-letter ISO currency code of the financial instrument.
    Example: "MXN"

  - `label` (string)
    A user-defined label for the financial instrument.
    Example: "mexico bank account"

  - `financialInstrumentType` (string, required)
    The type of financial instrument or payment rail used for executing the transaction.
This determines the structure and validation of account details required for the payout.
    Example: "BR_PIX"

## Response 201 fields (application/json):

  - `financialInstrumentId` (string, required)
    The unique ID of the financial instrument
    Example: "2f4ac57f-c5ba-4051-b51f-b3565778717b"

## Response 400 fields (application/json):

  - `status` (integer, required)
    The HTTP status code of the error
    Example: 404

  - `errors` (array, required)

  - `errors.code` (string, required)
    Unique identifier of an error
    Example: "SYS_100"

  - `errors.title` (string, required)
    Error message providing a brief summary of the error
    Example: "No identity exists for identityId"

  - `errors.type` (string, required)
    Identifies the problem type
    Example: "USER_VALIDATION_ERROR"

  - `errors.description` (string, required)
    Provides more technical information
    Example: "Unable to get identity. Identity ID should be in UUID format"

  - `errors.timestamp` (string, required)
    The time when this error occurred, specified in UTC.
    Example: "2023-11-02T18:26:00.000123Z"

  - `timestamp` (string)
    The timestamp of the error
    Example: "2023-11-02T18:26:00.000Z"

## Response 404 fields (application/json):

  - `status` (integer, required)
    The HTTP status code of the error
    Example: 404

  - `errors` (array, required)

  - `errors.code` (string, required)
    Unique identifier of an error
    Example: "SYS_100"

  - `errors.title` (string, required)
    Error message providing a brief summary of the error
    Example: "No identity exists for identityId"

  - `errors.type` (string, required)
    Identifies the problem type
    Example: "USER_VALIDATION_ERROR"

  - `errors.description` (string, required)
    Provides more technical information
    Example: "Unable to get identity. Identity ID should be in UUID format"

  - `errors.timestamp` (string, required)
    The time when this error occurred, specified in UTC.
    Example: "2023-11-02T18:26:00.000123Z"

  - `timestamp` (string)
    The timestamp of the error
    Example: "2023-11-02T18:26:00.000Z"

## Response 500 fields (application/json):

  - `status` (integer, required)
    The HTTP status code of the error
    Example: 404

  - `errors` (array, required)

  - `errors.code` (string, required)
    Unique identifier of an error
    Example: "SYS_100"

  - `errors.title` (string, required)
    Error message providing a brief summary of the error
    Example: "No identity exists for identityId"

  - `errors.type` (string, required)
    Identifies the problem type
    Example: "USER_VALIDATION_ERROR"

  - `errors.description` (string, required)
    Provides more technical information
    Example: "Unable to get identity. Identity ID should be in UUID format"

  - `errors.timestamp` (string, required)
    The time when this error occurred, specified in UTC.
    Example: "2023-11-02T18:26:00.000123Z"

  - `timestamp` (string)
    The timestamp of the error
    Example: "2023-11-02T18:26:00.000Z"