Skip to content

Add a financial instrument

Request

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.

Security
Bearer
Path
identity-idstringrequired

Unique identifier of the identity that will own the financial instrument.

Example:2f4ac57f-c5ba-4051-b51f-b3565778717b
Bodyapplication/jsonrequired
usAchobject

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
usFedwireobject

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

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

euSepaobject

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
gbFpsobject

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
ngBankPayoutobject

Rails: Bank Payout

Rail Definitions:

Bank Payout:

  • Availability: Country-dependant
  • Limit:
  • Nigeria: ₦5,000,000
  • Settlement: Real time to 48 hours
  • Cut-off time: Real time
  • Banking holidays: Nigeria banking holidays apply

Routing Evaluation Order: Not applicable

ghBankPayoutobject

Rails: GIP

Rail Definitions: GIP:

  • Availability: 24/7/365
  • Limit: ₵100,000
  • Settlement: Real time to 48 hours
  • Cut-off time: Real time
  • Banking holidays: Applicable

Routing Evaluation Order:

  1. GIP – Conditions: Account addressability, amount ≤ ₵100,000
rwBankPayoutobject

Rails: RSwitch

Rail Definitions: RSwitch:

  • Availability: 24/7/365
  • Limit: RWF 10,000,000
  • Settlement: Real time to 48 hours
  • Cut-off time: Real time
  • Banking holidays: Applicable

Routing Evaluation Order:

  1. RSwitch – Conditions: Account addressability, amount ≤ RWF 10,000,000
zaBankPayoutobject

Rails: Bank Payout

Rail Definitions: Bank Payout:

  • Availability: 24/7/365
  • Limit: R 300,000
  • Settlement: Real time to 48 hours
  • Cut-off time: Real time
  • Banking holidays: Applicable

Routing Evaluation Order:

  1. Bank Payout – Conditions: Account addressability, amount ≤ R 300,000
ugBankPayoutobject

Rails: Bank Payout

Rail Definitions: Bank Payout:

  • Availability: 24/7/365
  • Limit: UGX 20,000
  • Settlement: Real time to 48 hours
  • Cut-off time: Real time
  • Banking holidays: Applicable

Routing Evaluation Order:

  1. Bank Payout – Conditions: Account addressability, amount ≤ UGX 20,000
zmBankPayoutobject

Rails: Bank Payout

Rail Definitions: Bank Payout:

  • Availability: 24/7/365
  • Limit: ZK 150,000
  • Settlement: Real time to 48 hours
  • Cut-off time: Real time
  • Banking holidays: Applicable

Routing Evaluation Order:

  1. Bank Payout – Conditions: Account addressability, amount ≤ ZK 150,000
ethWalletobject

Rails: CRYPTO

Rail Definitions:

CRYPTO:

  • Availability: 24/7/365
  • Limit: None
  • Settlement: Blockchain dependent
  • Cut-off time: None
  • Banking holidays: Not applicable

Routing Policy: Not applicable

tronWalletobject

Rails: CRYPTO

Rail Definitions:

CRYPTO:

  • Availability: 24/7/365
  • Limit: None
  • Settlement: Blockchain dependent
  • Cut-off time: None
  • Banking holidays: Not applicable

Routing Policy: Not applicable

solWalletobject

Rails: CRYPTO

Rail Definitions:

CRYPTO:

  • Availability: 24/7/365
  • Limit: None
  • Settlement: Blockchain dependent
  • Cut-off time: None
  • Banking holidays: Not applicable

Routing Policy: Not applicable

brPixobject

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

coPseobject

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

brTedobject

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

caEftobject

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

krKftcobject

Rails: KFTC (Korea Financial Telecommunications and Clearings)

Rail Definitions:

KFTC:

  • Availability: 24/7/365
  • Limit: KRW 10,000,000 per transaction (varies)
  • Settlement: Real-time
  • Cut-off time: None
  • Banking holidays: Not applicable

Routing Evaluation Order: Not applicable

inNeftobject

Rails: NEFT (National Electronic Funds Transfer)

Rail Definitions:

NEFT:

  • Availability: Business days and banking hours only
  • Limit: No limit
  • Settlement: Same-day (by end of business day)
  • Cut-off time: 7:00 PM IST (varies by bank)
  • Banking holidays: India banking holidays apply

Routing Evaluation Order: Not applicable

peLbtrobject

Rails: LBTR (Sistema de Liquidación Bruta en Tiempo Real)

Rail Definitions:

LBTR:

  • Availability: Business days and banking hours only
  • Limit: Minimum Transaction amount is 5 USD
  • Settlement: Same-day
  • Cut-off time: 3:00 PM PET
  • Banking holidays: Peru banking holidays apply

Routing Evaluation Order: Not applicable

auNppobject

Rails: NPP (New Payments Platform), Direct Entry (DE/BECS)

Rail Definitions:

NPP:

  • Availability: 24/7/365
  • Limit: AUD 20,000 per transaction (higher with arrangement)
  • Settlement: Real-time (within 15 minutes)
  • Cut-off time: None
  • Banking holidays: Not applicable

Direct Entry (BECS):

  • Availability: Business days only
  • Limit: No limit
  • Settlement: Same-day or next business day
  • Cut-off time: Bank-dependent
  • Banking holidays: Australian banking holidays apply

Routing Evaluation Order:

  1. NPP
    • Conditions: beneficiary account is NPP-addressable AND amount ≤ AUD 20,000
  2. Direct Entry
    • Conditions: otherwise applicable
jpZenginobject

Rails: Zengin, Zengin Prompt Service

Rail Definitions:

Zengin:

  • Availability: Business days and banking hours only
  • Limit: No limit
  • Settlement: Same-day or next business day
  • Cut-off time: 9:00 PM JST (varies by bank)
  • Banking holidays: Japan banking holidays apply

Zengin Prompt Service:

  • Availability: 24/7/365
  • Limit: JPY 1,000,000 (typically)
  • Settlement: Real-time
  • Cut-off time: None
  • Banking holidays: Not applicable

Routing Evaluation Order:

  1. Zengin Prompt Service
    • Conditions: beneficiary account is ZPS-addressable AND amount ≤ JPY 1,000,000
  2. Zengin
    • Conditions: otherwise applicable
cnCfxpsobject

Rails: CFXPS (China Foreign Exchange Payment System)

Rail Definitions:

CFXPS:

  • Availability: Business days and banking hours only
  • Limit: No limit (institutional)
  • Settlement: Same-day or next business day
  • Cut-off time: 5:00 PM CST (varies by bank)
  • Banking holidays: China banking holidays apply
clTefobject

Rails: TEF (Transferencia Electrónica de Fondos)

Rail Definitions:

TEF:

  • Availability: Business days only
  • Limit: No limit
  • Settlement: Same-day or next business day
  • Cut-off time: 3:00 PM CLT
  • Banking holidays: Chile banking holidays apply

Routing Evaluation Order: Not applicable

aeIpiobject

Rails: IPI, FTS

Rail Definitions:

IPI:

  • Availability: 24/7/365
  • Limit: AED 25,000
  • Settlement: Instant
  • Cut-off time: None
  • Banking holidays: Not applicable

FTS:

  • Availability: Business days only
  • Limit: No limit
  • Settlement: Same-day
  • Cut-off time: ~2:00 PM GST
  • Banking holidays: UAE Central Bank holidays apply

Routing Evaluation Order:

  1. IPI
    • Conditions: beneficiary account is IPI-addressable AND amount ≤ AED 25,000
  2. FTS
    • Conditions: otherwise applicable
thPromptpayobject

Rails: PromptPay

Rail Definitions:

PromptPay (National ITMX):

  • Availability: 24/7/365
  • Limit: THB 500,000 per transaction
  • Settlement: Real-time (within seconds)
  • Cut-off time: None
  • Banking holidays: Not applicable

Routing Evaluation Order: Not applicable

arInterbankingobject

Rails: Interbanking

Rail Definitions:

Interbanking:

  • Availability: Business days only
  • Limit: ARS 10,000,000
  • Settlement: Same-day or next business day
  • Cut-off time: 3:00 PM ART
  • Banking holidays: Argentina banking holidays apply

Routing Evaluation Order: AR_INTERBANKING has a single payment rail; no routing evaluation order applies.

currencystringrequired

The 3-letter ISO currency code of the financial instrument.

Example:"MXN"
labelstring, <= 256 characters

A user-defined label for the financial instrument.

Example:"mexico bank account"
financialInstrumentTypestringrequired

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.

Enum ValueDescription
US_ACH

Automated Clearing House - U.S. batch processing network used for domestic payments.

US_FEDWIRE

Fedwire Funds Service - U.S. real-time gross settlement network for high-value domestic USD transfers.

MX_SPEI

Mexico's real-time interbank transfer system.

EU_SEPA

European Union's standardized payment system for euro-denominated transactions.

GB_FPS

Faster Payments Service in the UK for near-instant payments.

NG_BANK_PAYOUT

Nigeria Bank Payout - A payment method for bank transfers in Nigeria.

GH_BANK_PAYOUT

Ghana Bank Payout - A payment method for bank transfers in Ghana.

RW_BANK_PAYOUT

Rwanda Bank Payout - A payment method for bank transfers in Rwanda.

ZA_BANK_PAYOUT

South Africa Bank Payout - A payment method for bank transfers in South Africa.

UG_BANK_PAYOUT

Uganda Bank Payout - A payment method for bank transfers in Uganda.

ZM_BANK_PAYOUT

Zambia Bank Payout - A payment method for bank transfers in Zambia.

ETH_WALLET

Ethereum-based crypto transactions using blockchain wallet addresses.

TRON_WALLET

Tron-based crypto transactions using blockchain wallet addresses.

SOL_WALLET

Solana-based crypto transactions using blockchain wallet addresses.

BR_PIX

Brazil's instant payment platform developed by the Central Bank of Brazil.

CO_PSE

Colombia's secure online banking payment system.

BR_TED

Brazil's Electronic Funds Transfer system for high-value transactions.

CA_EFT

Canada's Electronic Funds Transfer system for batch processing.

IN_NEFT

India National Electronic Funds Transfer - bank payout for INR denominated transfers using IFSC routing codes.

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.

JP_ZENGIN

Japan Zengin - multi-rail (Zengin + Zengin Prompt Service) domestic clearing system for JPY-denominated payments.

TH_PROMPTPAY

Thailand PromptPay - Thailand's national real-time retail payment system for THB domestic bank transfers.

CN_CFXPS

China Foreign Exchange Payment System, enabling USD business-to-business transfers to China via SWIFT/BIC routing.

CL_TEF

Chile TEF (Transferencia Electrónica de Fondos) - business-day domestic transfer system for CLP-denominated payments.

PE_LBTR

Peru LBTR (Liquidación Bruta en Tiempo Real) - real-time settlement system for PEN-denominated payments.

KR_KFTC

South Korea KFTC - 24/7 real-time payment rail via Korea Financial Telecommunications and Clearings for KRW-denominated payments.

AE_IPI

United Arab Emirates' Instant Payment Interface for real-time transactions.

AR_INTERBANKING

Argentina Interbanking - CBU/CVU-based domestic transfer system for ARS-denominated payments.

Example:"BR_PIX"
curl -i -X POST \
  https://docs.ripple.com/_mock/products/payments-direct-2/api-docs/payments-direct-api/payments-direct-2-api/v3/identities/2f4ac57f-c5ba-4051-b51f-b3565778717b/financial-instruments \
  -H 'Authorization: Bearer <YOUR_JWT_HERE>' \
  -H 'Content-Type: application/json' \
  -d '{
    "financialInstrumentType": "US_ACH",
    "currency": "USD",
    "label": "US bank account",
    "usAch": {
      "bankName": "Bank of Example",
      "bankRoutingNumber": "266231608",
      "accountNumber": "60480",
      "accountType": "CHECKING"
    }
  }'

Responses

Financial instrument created.

Bodyapplication/json
financialInstrumentIdstringrequired

The unique ID of the financial instrument

Example:"2f4ac57f-c5ba-4051-b51f-b3565778717b"
Response
{
  "financialInstrumentId": "d3cd4f8e-3a6d-46e6-bdb6-0b7f358f2ad8"
}