Create a new payment identity as an ORIGINATOR or BENEFICIARY for either an INDIVIDUAL or BUSINESS. The request body must follow the v3 identity schema and will be validated against corridor rules where applicable. On success, the API returns the new identityId and its initial version.
Payments Direct API (0.0.3)
Use the Payments Direct API to get quotes, create and manage payments, and manage originator and beneficiary identities.
The Payments Direct API offers the following environments:
Environment | Base URL | Description |
|---|---|---|
| UAT | https://api.test.ripple.com | UAT environment with simulated currency. |
| Production | https://api.ripple.com | Production environment |
All {{process.env.VAR_RPD}} API operations require a Bearer access token specific to the environment you're using. Ripple provides a secure model for authentication and authorization by providing access tokens scoped for a set of credentials.
You will need your client ID and client secret to obtain an access token.
If you do not already have your client ID and client secret, do the following:
- Log into the Ripple Payments UI.
- In the left navigation menu, click Settings.
- Under Administration, click API Credentials.
- In the dropdown list next to the page title, select the access environment. For example, to provision credentials for the test environment, select UAT from the dropdown list.
- In the upper right corner of the page, click New Credential.
- Click Save and Generate Key.
Caution: The client secret is displayed only once when you are creating new credentials. You cannot retrieve the secret after exiting this page. Copy and store the client secret securely and share it with authorized individuals in accordance with your organization's security policy.
You can now use the client ID and client secret to generate access tokens using the Request an access token operation.
To get an access token, use the Request an access token operation with your client_id and client_secret. The response contains a token in the access_token field.
We recommend rotating your API credentials at regular intervals according to your organization's security policy.
Note: Authentication tokens are not a fixed length and can vary, avoid validating tokens based on character length.
Overview
License
Languages
Servers
Mock server
https://docs.ripple.com/_mock/products/payments-direct-2/api-docs/payments-direct-api/payments-direct-2-api/
UAT environment with simulated currency
https://api.test.ripple.com/
Production environment
https://api.ripple.com/
Authentication
Use these API operations to manage your authentication tokens.
| Operation | Method | Description |
|---|---|---|
| Request an access token | POST | Request an access token for authentication with Ripple APIs. |
| Test access token | GET | Test if an access token can be used for authentication. |
Operations
Identities (v3)
Use these API operations to manage your identities with Identity Management v3 (recommended for all new integrations).
| Operation | Method | Description |
|---|---|---|
| Create an identity (v3) | POST | Create a new identity (INDIVIDUAL/BUSINESS; ORIGINATOR/BENEFICIARY). |
| Get a list of identies (v3) | GET | Retrieve a list of identities with optional filters (e.g., paymentRole, identityType). |
| Get an identity by ID (v3) | GET | Retrieve a specific identity by identityId (latest version by default). |
| Update an identity (v3) | PUT | Update one or more fields; creates a new version. |
| Deactivate an identity (v3) | DELETE | Set the identity state to DEACTIVATED (cannot be used for new payments). |
| Add a financial instrument (v3) | POST | Add a financial instrument to an identity. |
| Get a list of financial instruments (v3) | GET | Get a list of financial instruments for an identity. |
| Get a financial instrument by ID (v3) | GET | Get a specific financial instrument by financialInstrumentId. |
| Update a financial instrument (v3) | PUT | Update a financial instrument by financialInstrumentId. |
| Deactivate a financial instrument (v3) | DELETE | Deactivate a financial instrument by financialInstrumentId. |
Operations
Bodyapplication/jsonrequired
The payout rails to validate the identity against
| Items Enum Value | Description |
|---|---|
| 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. |
| AFRICA_BANK_PAYOUT | Nigeria Bank Payout - A payment method for bank transfers in Nigeria. |
| 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. |
Example: ["BR_PIX"]
The type of the identity
| Enum Value | Description |
|---|---|
| BUSINESS | Identity associated with an institution or business |
| INDIVIDUAL | Identity associated with an individual |
Example: "BUSINESS"
The payment role of the identity
| Enum Value | Description |
|---|---|
| ORIGINATOR | Refers to originator identity |
| BENEFICIARY | Refers to beneficiary identity |
Example: "BENEFICIARY"
Optional client-provided unique identifier for idempotency and deduplication. Must be unique across all active identities within your tenant. Duplicate values will result in a 409 Conflict error.
Example: "customer-12345-uuid"
PII data to support business and institutional identities
Business Legal Name
Example: "Widgets Org"
Holds general information about the business
Allows the street address of the business to be held
Example: ["123 Example St. Boston, MA"]
Allows the country of the business to be held. Use Alpha-2 Code as defined in the ISO CountryCode ISO 3166-1 list.
Example: "US"
City
Example: "Boston"
Address for electronic mail (e-mail).
Example: "fake@example.com"
Unique and unambiguous way to identify a business or organization. An array of objects, each containing unique identification of an organization, as assigned by an institution, using an identification scheme.
The unique identifier of the organization
Example: "123ABC"
Data for an individual
First name of the individual
Example: "John"
Last name of the individual
Example: "Smith"
Holds general information about the individual
Allows the street address of the individual to be held
Example: ["123 Example St. Boston, MA"]
Allows the Country of the individual to be held. Use Alpha-2 Code as defined in the ISO CountryCode ISO 3166-1 list.
Example: "US"
City
Example: "Boston"
Address for electronic mail (e-mail).
Example: "fake@example.com"
Gathers identifying documentation
Identification Number.
Example: "123ABC"
The type of identification document used to identify the identity.
ALIEN_REGISTRATION— Alien Registration NumberCUSTOMER_ID— Customer Identification NumberDRIVERS_LICENSE— Driver’s License NumberPASSPORT— Passport NumberEMPLOYEE_ID— Employee IDNATIONAL_ID_NUMBER— National IDSSN— Social Security NumberTAX_ID— Tax ID
Country of Birth. Use Alpha-2 Code as defined in the ISO CountryCode ISO 3166-1 list.
Example: "US"
Alpha-2 country code for the nationality of the individual in ISO 3166-1 format.
Example: "US"
- Mock server
https://docs.ripple.com/_mock/products/payments-direct-2/api-docs/payments-direct-api/payments-direct-2-api/v3/identities
- UAT environment with simulated currency
https://api.test.ripple.com/v3/identities
- Production environment
https://api.ripple.com/v3/identities
- curl
- Python
curl -i -X POST \
https://docs.ripple.com/_mock/products/payments-direct-2/api-docs/payments-direct-api/payments-direct-2-api/v3/identities \
-H 'Authorization: Bearer <YOUR_JWT_HERE>' \
-H 'Content-Type: application/json' \
-d '{
"identityType": "INDIVIDUAL",
"paymentRole": "ORIGINATOR",
"nickName": "Alice Sender USD",
"tags": [
"sender",
"priority"
],
"individual": {
"firstName": "Alice",
"lastName": "Chen",
"dateOfBirth": "1990-05-14",
"citizenship": "US",
"address": {
"streetAddress": [
"123 Main Street"
],
"city": "San Francisco",
"stateOrProvince": "CA",
"postalCode": "94105",
"country": "US"
}
}
}'Response
application/json
{ "identityId": "99254c4f-f207-4792-a846-06928825018c", "version": "1" }
- Mock server
https://docs.ripple.com/_mock/products/payments-direct-2/api-docs/payments-direct-api/payments-direct-2-api/v3/identities
- UAT environment with simulated currency
https://api.test.ripple.com/v3/identities
- Production environment
https://api.ripple.com/v3/identities
- curl
- Python
curl -i -X GET \
'https://docs.ripple.com/_mock/products/payments-direct-2/api-docs/payments-direct-api/payments-direct-2-api/v3/identities?payment-role=BENEFICIARY&nick-name=Alice&limit=20&next-token=eyJrZXkxIjoidmFsdWVfMSIsImtleTIiOiJ2YWx1ZTIifQ%3D%3D' \
-H 'Authorization: Bearer <YOUR_JWT_HERE>'A page of identities.
The list of the identities that match the query parameters
The unique ID of the identity
Example: "2f4ac57f-c5ba-4051-b51f-b3565778717b"
The type of the identity
| Enum Value | Description |
|---|---|
| BUSINESS | Identity associated with an institution or business |
| INDIVIDUAL | Identity associated with an individual |
Example: "BUSINESS"
The payment role of the identity
| Enum Value | Description |
|---|---|
| ORIGINATOR | Refers to originator identity |
| BENEFICIARY | Refers to beneficiary identity |
Example: "BENEFICIARY"
The time at which the identity was created
Example: "2023-11-02T18:26:00.000Z"
The time at which the identity was last updated
Example: "2023-11-03T18:26:00.000Z"
The state of the identity.
| Enum Value | Description |
|---|---|
| ACTIVE | The identity requested exists and is active. |
| BLOCKED | The identity requested exists, but is blocked. |
| DEACTIVATED | The identity requested has been deactivated. |
Example: "ACTIVE"
The nickname for the identity provided at the time of identity creation
Example: "nickName"
The internal ID of the identity used for internal processing
Example: "2f4ac57f-c5ba-4051-b51f-b3565778717b"
Response
application/json
{ "data": [ { … }, { … } ], "nextToken": "eyJrZXkxIjoidmFsdWUifQ==" }
- Mock server
https://docs.ripple.com/_mock/products/payments-direct-2/api-docs/payments-direct-api/payments-direct-2-api/v3/identities/{identity-id}
- UAT environment with simulated currency
https://api.test.ripple.com/v3/identities/{identity-id}
- Production environment
https://api.ripple.com/v3/identities/{identity-id}
- curl
- Python
curl -i -X GET \
'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?version=2' \
-H 'Authorization: Bearer <YOUR_JWT_HERE>'Identity details.
Server-generated unique identifier of the identity.
Example: "2f4ac57f-c5ba-4051-b51f-b3565778717b"
The state of the identity.
| Enum Value | Description |
|---|---|
| ACTIVE | The identity requested exists and is active. |
| BLOCKED | The identity requested exists, but is blocked. |
| DEACTIVATED | The identity requested has been deactivated. |
Example: "ACTIVE"
List of payout methods where this identity is considered valid. Use this to indicate which payout methods (for example, US_ACH, EU_SEPA) the identity can be used with in payments.
| Items Enum Value | Description |
|---|---|
| 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. |
| AFRICA_BANK_PAYOUT | Nigeria Bank Payout - A payment method for bank transfers in Nigeria. |
| 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. |
Example: ["BR_PIX"]
Schema version used to validate this identity, for example 1.0.0.
Example: "1.0.0"
RFC 3339 timestamp when the identity was created.
Example: "2023-11-02T18:26:00.000Z"
RFC 3339 timestamp when the identity was last updated.
Example: "2023-11-03T18:26:00.000Z"
The type of the identity
| Enum Value | Description |
|---|---|
| BUSINESS | Identity associated with an institution or business |
| INDIVIDUAL | Identity associated with an individual |
Example: "BUSINESS"
The payment role of the identity
| Enum Value | Description |
|---|---|
| ORIGINATOR | Refers to originator identity |
| BENEFICIARY | Refers to beneficiary identity |
Example: "BENEFICIARY"
Optional client-provided unique identifier for idempotency and deduplication. Must be unique across all active identities within your tenant. Duplicate values will result in a 409 Conflict error.
Example: "customer-12345-uuid"
PII data to support business and institutional identities
Business Legal Name
Example: "Widgets Org"
Holds general information about the business
Allows the street address of the business to be held
Example: ["123 Example St. Boston, MA"]
Allows the country of the business to be held. Use Alpha-2 Code as defined in the ISO CountryCode ISO 3166-1 list.
Example: "US"
City
Example: "Boston"
Address for electronic mail (e-mail).
Example: "fake@example.com"
Unique and unambiguous way to identify a business or organization. An array of objects, each containing unique identification of an organization, as assigned by an institution, using an identification scheme.
The unique identifier of the organization
Example: "123ABC"
Data for an individual
First name of the individual
Example: "John"
Last name of the individual
Example: "Smith"
Holds general information about the individual
Allows the street address of the individual to be held
Example: ["123 Example St. Boston, MA"]
Allows the Country of the individual to be held. Use Alpha-2 Code as defined in the ISO CountryCode ISO 3166-1 list.
Example: "US"
City
Example: "Boston"
Address for electronic mail (e-mail).
Example: "fake@example.com"
Gathers identifying documentation
Identification Number.
Example: "123ABC"
The type of identification document used to identify the identity.
ALIEN_REGISTRATION— Alien Registration NumberCUSTOMER_ID— Customer Identification NumberDRIVERS_LICENSE— Driver’s License NumberPASSPORT— Passport NumberEMPLOYEE_ID— Employee IDNATIONAL_ID_NUMBER— National IDSSN— Social Security NumberTAX_ID— Tax ID
Country of Birth. Use Alpha-2 Code as defined in the ISO CountryCode ISO 3166-1 list.
Example: "US"
Alpha-2 country code for the nationality of the individual in ISO 3166-1 format.
Example: "US"
Response
application/json
{ "identityId": "9d839f58-7fd3-4913-a27e-48d31973d3f9", "identityState": "ACTIVE", "nickName": "nickName", "tags": [ "tag1" ], "version": "2", "schemaVersion": "1.0.0", "createdAt": "2025-10-01T18:46:41.833Z", "updatedAt": "2025-10-01T18:46:47.430Z", "identityType": "BUSINESS", "paymentRole": "BENEFICIARY", "business": { "businessName": "Widgets Org", "address": { … }, "email": "fake@example.com", "phone": "+1234567890", "registration": [ … ], "incorporationCountry": "US" } }
Bodyapplication/jsonrequired
The payout rails to validate the identity against
| Items Enum Value | Description |
|---|---|
| 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. |
| AFRICA_BANK_PAYOUT | Nigeria Bank Payout - A payment method for bank transfers in Nigeria. |
| 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. |
Example: ["BR_PIX"]
Optional client-provided unique identifier for idempotency and deduplication. Must be unique across all active identities within your tenant. Duplicate values will result in a 409 Conflict error.
Example: "customer-12345-uuid"
PII data to support business and institutional identities
Business Legal Name
Example: "Widgets Org"
Holds general information about the business
Allows the street address of the business to be held
Example: ["123 Example St. Boston, MA"]
Allows the country of the business to be held. Use Alpha-2 Code as defined in the ISO CountryCode ISO 3166-1 list.
Example: "US"
City
Example: "Boston"
Address for electronic mail (e-mail).
Example: "fake@example.com"
Unique and unambiguous way to identify a business or organization. An array of objects, each containing unique identification of an organization, as assigned by an institution, using an identification scheme.
The unique identifier of the organization
Example: "123ABC"
Data for an individual
First name of the individual
Example: "John"
Last name of the individual
Example: "Smith"
Holds general information about the individual
Allows the street address of the individual to be held
Example: ["123 Example St. Boston, MA"]
Allows the Country of the individual to be held. Use Alpha-2 Code as defined in the ISO CountryCode ISO 3166-1 list.
Example: "US"
City
Example: "Boston"
Address for electronic mail (e-mail).
Example: "fake@example.com"
Gathers identifying documentation
Identification Number.
Example: "123ABC"
The type of identification document used to identify the identity.
ALIEN_REGISTRATION— Alien Registration NumberCUSTOMER_ID— Customer Identification NumberDRIVERS_LICENSE— Driver’s License NumberPASSPORT— Passport NumberEMPLOYEE_ID— Employee IDNATIONAL_ID_NUMBER— National IDSSN— Social Security NumberTAX_ID— Tax ID
Country of Birth. Use Alpha-2 Code as defined in the ISO CountryCode ISO 3166-1 list.
Example: "US"
Alpha-2 country code for the nationality of the individual in ISO 3166-1 format.
Example: "US"
- Mock server
https://docs.ripple.com/_mock/products/payments-direct-2/api-docs/payments-direct-api/payments-direct-2-api/v3/identities/{identity-id}
- UAT environment with simulated currency
https://api.test.ripple.com/v3/identities/{identity-id}
- Production environment
https://api.ripple.com/v3/identities/{identity-id}
- curl
- Python
curl -i -X PUT \
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 \
-H 'Authorization: Bearer <YOUR_JWT_HERE>' \
-H 'Content-Type: application/json' \
-d '{
"nickName": "Alice Sender USD - Updated",
"tags": [
"usd",
"high-value"
]
}'Identity updated. Latest version returned.
Server-generated unique identifier of the identity.
Example: "2f4ac57f-c5ba-4051-b51f-b3565778717b"
The state of the identity.
| Enum Value | Description |
|---|---|
| ACTIVE | The identity requested exists and is active. |
| BLOCKED | The identity requested exists, but is blocked. |
| DEACTIVATED | The identity requested has been deactivated. |
Example: "ACTIVE"
List of payout methods where this identity is considered valid. Use this to indicate which payout methods (for example, US_ACH, EU_SEPA) the identity can be used with in payments.
| Items Enum Value | Description |
|---|---|
| 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. |
| AFRICA_BANK_PAYOUT | Nigeria Bank Payout - A payment method for bank transfers in Nigeria. |
| 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. |
Example: ["BR_PIX"]
Schema version used to validate this identity, for example 1.0.0.
Example: "1.0.0"
RFC 3339 timestamp when the identity was created.
Example: "2023-11-02T18:26:00.000Z"
RFC 3339 timestamp when the identity was last updated.
Example: "2023-11-03T18:26:00.000Z"
The type of the identity
| Enum Value | Description |
|---|---|
| BUSINESS | Identity associated with an institution or business |
| INDIVIDUAL | Identity associated with an individual |
Example: "BUSINESS"
The payment role of the identity
| Enum Value | Description |
|---|---|
| ORIGINATOR | Refers to originator identity |
| BENEFICIARY | Refers to beneficiary identity |
Example: "BENEFICIARY"
Optional client-provided unique identifier for idempotency and deduplication. Must be unique across all active identities within your tenant. Duplicate values will result in a 409 Conflict error.
Example: "customer-12345-uuid"
PII data to support business and institutional identities
Business Legal Name
Example: "Widgets Org"
Holds general information about the business
Allows the street address of the business to be held
Example: ["123 Example St. Boston, MA"]
Allows the country of the business to be held. Use Alpha-2 Code as defined in the ISO CountryCode ISO 3166-1 list.
Example: "US"
City
Example: "Boston"
Address for electronic mail (e-mail).
Example: "fake@example.com"
Unique and unambiguous way to identify a business or organization. An array of objects, each containing unique identification of an organization, as assigned by an institution, using an identification scheme.
The unique identifier of the organization
Example: "123ABC"
Data for an individual
First name of the individual
Example: "John"
Last name of the individual
Example: "Smith"
Holds general information about the individual
Allows the street address of the individual to be held
Example: ["123 Example St. Boston, MA"]
Allows the Country of the individual to be held. Use Alpha-2 Code as defined in the ISO CountryCode ISO 3166-1 list.
Example: "US"
City
Example: "Boston"
Address for electronic mail (e-mail).
Example: "fake@example.com"
Gathers identifying documentation
Identification Number.
Example: "123ABC"
The type of identification document used to identify the identity.
ALIEN_REGISTRATION— Alien Registration NumberCUSTOMER_ID— Customer Identification NumberDRIVERS_LICENSE— Driver’s License NumberPASSPORT— Passport NumberEMPLOYEE_ID— Employee IDNATIONAL_ID_NUMBER— National IDSSN— Social Security NumberTAX_ID— Tax ID
Country of Birth. Use Alpha-2 Code as defined in the ISO CountryCode ISO 3166-1 list.
Example: "US"
Alpha-2 country code for the nationality of the individual in ISO 3166-1 format.
Example: "US"
Response
application/json
{ "identityId": "2f4ac57f-c5ba-4051-b51f-b3565778717b", "identityState": "ACTIVE", "nickName": "nickName", "tags": [ "tag1" ], "validatePayoutRails": [ "BR_PIX" ], "version": 2, "schemaVersion": "1.0.0", "createdAt": "2023-11-02T18:26:00.000Z", "updatedAt": "2023-11-03T18:26:00.000Z", "identityType": "BUSINESS", "paymentRole": "BENEFICIARY", "internalId": "customer-12345-uuid", "business": { "businessName": "Widgets Org", "address": { … }, "email": "fake@example.com", "phone": 1234567890, "registration": [ … ], "incorporationCountry": "US" }, "individual": { "firstName": "John", "lastName": "Smith", "address": { … }, "email": "fake@example.com", "phone": 1234567890, "identityDocuments": [ … ], "dateOfBirth": "2001-01-24", "countryOfBirth": "US", "citizenship": "US", "gender": "string" } }
- Mock server
https://docs.ripple.com/_mock/products/payments-direct-2/api-docs/payments-direct-api/payments-direct-2-api/v3/identities/{identity-id}
- UAT environment with simulated currency
https://api.test.ripple.com/v3/identities/{identity-id}
- Production environment
https://api.ripple.com/v3/identities/{identity-id}
- curl
- Python
curl -i -X DELETE \
https://docs.ripple.com/_mock/products/payments-direct-2/api-docs/payments-direct-api/payments-direct-2-api/v3/identities/146f3c51-c313-47ce-b6f2-691c5a238b3e \
-H 'Authorization: Bearer <YOUR_JWT_HERE>'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
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:
- RTP
- Conditions: beneficiary account is RTP-addressable AND amount ≤ $5,000,000
- ACH
- Conditions: otherwise applicable
The name of the identity's bank
The identity's account number into which the funds must be credited
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.
The name of the identity's bank.
9-digit ABA Routing Transit Number (RTN) of the beneficiary’s bank.
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
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:
- SCT Inst
- Conditions: beneficiary account is SCT Inst-addressable AND amount ≤ €100,000
- SCT
- Conditions: otherwise applicable
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:
- FPS
- Conditions: beneficiary account is FPS-addressable AND amount ≤ £1,000,000
- CHAPS
- Conditions: otherwise applicable
The name of the identity's bank
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
The name of the identity's bank
The identity's account number associated with the Account Identification Scheme
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
The name of the identity's bank
The code of the identity's bank (BICFI code)
The identity's PIX key, which can be an email, phone number, or a hash
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
The name of the identity's bank
The identity's account number associated with the Account Identification Scheme
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
The name of the identity's bank
The code of the identity's bank (BICFI code)
The branch number of the identity's bank account
The identity's account number associated with the Account Identification Scheme
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
The name of the identity's bank
The identity's account number associated with the Account Identification Scheme
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 Value | Description |
|---|---|
| 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. |
| AFRICA_BANK_PAYOUT | Nigeria Bank Payout - A payment method for bank transfers in Nigeria. |
| 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. |
Example: "BR_PIX"
- Mock server
https://docs.ripple.com/_mock/products/payments-direct-2/api-docs/payments-direct-api/payments-direct-2-api/v3/identities/{identity-id}/financial-instruments
- UAT environment with simulated currency
https://api.test.ripple.com/v3/identities/{identity-id}/financial-instruments
- Production environment
https://api.ripple.com/v3/identities/{identity-id}/financial-instruments
- curl
- Python
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"
}
}'Response
application/json
{ "financialInstrumentId": "d3cd4f8e-3a6d-46e6-bdb6-0b7f358f2ad8" }
- Mock server
https://docs.ripple.com/_mock/products/payments-direct-2/api-docs/payments-direct-api/payments-direct-2-api/v3/identities/{identity-id}/financial-instruments
- UAT environment with simulated currency
https://api.test.ripple.com/v3/identities/{identity-id}/financial-instruments
- Production environment
https://api.ripple.com/v3/identities/{identity-id}/financial-instruments
- curl
- Python
curl -i -X GET \
'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?version=2&next-token=eyJrZXkxIjoidmFsdWVfMSIsImtleTIiOiJ2YWx1ZTIifQ%3D%3D&limit=20' \
-H 'Authorization: Bearer <YOUR_JWT_HERE>'Requested financial instruments of the identity in JSON format
The list of the financial instruments that match the query parameters
The unique identifier of the financial instrument.
Example: "3fc74743-e7f3-414a-9fcf-eb8c1d52356a"
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 Value | Description |
|---|---|
| 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. |
| AFRICA_BANK_PAYOUT | Nigeria Bank Payout - A payment method for bank transfers in Nigeria. |
| 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. |
Example: "BR_PIX"
The time at which the financial instrument was created
Example: "2023-11-02T18:26:00.000Z"
Response
application/json
{ "data": [ { … } ] }
- Mock server
https://docs.ripple.com/_mock/products/payments-direct-2/api-docs/payments-direct-api/payments-direct-2-api/v3/identities/{identity-id}/financial-instruments/{financial-instrument-id}
- UAT environment with simulated currency
https://api.test.ripple.com/v3/identities/{identity-id}/financial-instruments/{financial-instrument-id}
- Production environment
https://api.ripple.com/v3/identities/{identity-id}/financial-instruments/{financial-instrument-id}
- curl
- Python
curl -i -X GET \
'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/2f4ac57f-c5ba-4051-b51f-b3565778717b?version=2&expand-identity=true' \
-H 'Authorization: Bearer <YOUR_JWT_HERE>'List of financial instruments for the identity.
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:
- RTP
- Conditions: beneficiary account is RTP-addressable AND amount ≤ $5,000,000
- ACH
- Conditions: otherwise applicable
The name of the identity's bank
The identity's account number into which the funds must be credited
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.
The name of the identity's bank.
9-digit ABA Routing Transit Number (RTN) of the beneficiary’s bank.
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
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:
- SCT Inst
- Conditions: beneficiary account is SCT Inst-addressable AND amount ≤ €100,000
- SCT
- Conditions: otherwise applicable
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:
- FPS
- Conditions: beneficiary account is FPS-addressable AND amount ≤ £1,000,000
- CHAPS
- Conditions: otherwise applicable
The name of the identity's bank
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
The name of the identity's bank
The identity's account number associated with the Account Identification Scheme
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
The name of the identity's bank
The code of the identity's bank (BICFI code)
The identity's PIX key, which can be an email, phone number, or a hash
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
The name of the identity's bank
The identity's account number associated with the Account Identification Scheme
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
The name of the identity's bank
The code of the identity's bank (BICFI code)
The branch number of the identity's bank account
The identity's account number associated with the Account Identification Scheme
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
The name of the identity's bank
The identity's account number associated with the Account Identification Scheme
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 Value | Description |
|---|---|
| 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. |
| AFRICA_BANK_PAYOUT | Nigeria Bank Payout - A payment method for bank transfers in Nigeria. |
| 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. |
Example: "BR_PIX"
The unique identifier of the financial instrument.
Example: "3fc74743-e7f3-414a-9fcf-eb8c1d52356a"
The time at which the financial instrument was created
Example: "2023-11-02T18:26:00.000Z"
Server-generated unique identifier of the identity.
Example: "2f4ac57f-c5ba-4051-b51f-b3565778717b"
The state of the identity.
| Enum Value | Description |
|---|---|
| ACTIVE | The identity requested exists and is active. |
| BLOCKED | The identity requested exists, but is blocked. |
| DEACTIVATED | The identity requested has been deactivated. |
Example: "ACTIVE"
List of payout methods where this identity is considered valid. Use this to indicate which payout methods (for example, US_ACH, EU_SEPA) the identity can be used with in payments.
| Items Enum Value | Description |
|---|---|
| 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. |
| AFRICA_BANK_PAYOUT | Nigeria Bank Payout - A payment method for bank transfers in Nigeria. |
| 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. |
Example: ["BR_PIX"]
Schema version used to validate this identity, for example 1.0.0.
Example: "1.0.0"
RFC 3339 timestamp when the identity was created.
Example: "2023-11-02T18:26:00.000Z"
RFC 3339 timestamp when the identity was last updated.
Example: "2023-11-03T18:26:00.000Z"
The type of the identity
| Enum Value | Description |
|---|---|
| BUSINESS | Identity associated with an institution or business |
| INDIVIDUAL | Identity associated with an individual |
Example: "BUSINESS"
The payment role of the identity
| Enum Value | Description |
|---|---|
| ORIGINATOR | Refers to originator identity |
| BENEFICIARY | Refers to beneficiary identity |
Example: "BENEFICIARY"
Optional client-provided unique identifier for idempotency and deduplication. Must be unique across all active identities within your tenant. Duplicate values will result in a 409 Conflict error.
Example: "customer-12345-uuid"
PII data to support business and institutional identities
Business Legal Name
Example: "Widgets Org"
Holds general information about the business
Allows the street address of the business to be held
Example: ["123 Example St. Boston, MA"]
Allows the country of the business to be held. Use Alpha-2 Code as defined in the ISO CountryCode ISO 3166-1 list.
Example: "US"
City
Example: "Boston"
Address for electronic mail (e-mail).
Example: "fake@example.com"
Unique and unambiguous way to identify a business or organization. An array of objects, each containing unique identification of an organization, as assigned by an institution, using an identification scheme.
The unique identifier of the organization
Example: "123ABC"
Data for an individual
First name of the individual
Example: "John"
Last name of the individual
Example: "Smith"
Holds general information about the individual
Allows the street address of the individual to be held
Example: ["123 Example St. Boston, MA"]
Allows the Country of the individual to be held. Use Alpha-2 Code as defined in the ISO CountryCode ISO 3166-1 list.
Example: "US"
City
Example: "Boston"
Address for electronic mail (e-mail).
Example: "fake@example.com"
Gathers identifying documentation
Identification Number.
Example: "123ABC"
The type of identification document used to identify the identity.
ALIEN_REGISTRATION— Alien Registration NumberCUSTOMER_ID— Customer Identification NumberDRIVERS_LICENSE— Driver’s License NumberPASSPORT— Passport NumberEMPLOYEE_ID— Employee IDNATIONAL_ID_NUMBER— National IDSSN— Social Security NumberTAX_ID— Tax ID
Country of Birth. Use Alpha-2 Code as defined in the ISO CountryCode ISO 3166-1 list.
Example: "US"
Alpha-2 country code for the nationality of the individual in ISO 3166-1 format.
Example: "US"
Response
application/json
{ "financialInstrument": { "country": "US", "financialInstrumentId": "7f2bac05-42a3-4b26-89fd-333396fdba70", "createdAt": "2025-10-01T18:46:47.430Z", "updatedAt": "2025-10-01T18:46:47.430Z", "usAch": { … }, "currency": "USD", "label": "US bank account", "financialInstrumentType": "US_ACH" } }
Bodyapplication/jsonrequired
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:
- RTP
- Conditions: beneficiary account is RTP-addressable AND amount ≤ $5,000,000
- ACH
- Conditions: otherwise applicable
The name of the identity's bank
The identity's account number into which the funds must be credited
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.
The name of the identity's bank.
9-digit ABA Routing Transit Number (RTN) of the beneficiary’s bank.
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
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:
- SCT Inst
- Conditions: beneficiary account is SCT Inst-addressable AND amount ≤ €100,000
- SCT
- Conditions: otherwise applicable
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:
- FPS
- Conditions: beneficiary account is FPS-addressable AND amount ≤ £1,000,000
- CHAPS
- Conditions: otherwise applicable
The name of the identity's bank
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
The name of the identity's bank
The identity's account number associated with the Account Identification Scheme
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
The name of the identity's bank
The code of the identity's bank (BICFI code)
The identity's PIX key, which can be an email, phone number, or a hash
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
The name of the identity's bank
The identity's account number associated with the Account Identification Scheme
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
The name of the identity's bank
The code of the identity's bank (BICFI code)
The branch number of the identity's bank account
The identity's account number associated with the Account Identification Scheme
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
The name of the identity's bank
The identity's account number associated with the Account Identification Scheme
- Mock server
https://docs.ripple.com/_mock/products/payments-direct-2/api-docs/payments-direct-api/payments-direct-2-api/v3/identities/{identity-id}/financial-instruments/{financial-instrument-id}
- UAT environment with simulated currency
https://api.test.ripple.com/v3/identities/{identity-id}/financial-instruments/{financial-instrument-id}
- Production environment
https://api.ripple.com/v3/identities/{identity-id}/financial-instruments/{financial-instrument-id}
- curl
- Python
curl -i -X PUT \
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/c7e2f5b4-d1a2-4c3a-9e1b-4d5c6f7e8a9d \
-H 'Authorization: Bearer <YOUR_JWT_HERE>' \
-H 'Content-Type: application/json' \
-d '{
"label": "Operating account"
}'Financial instrument updated.
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:
- RTP
- Conditions: beneficiary account is RTP-addressable AND amount ≤ $5,000,000
- ACH
- Conditions: otherwise applicable
The name of the identity's bank
The identity's account number into which the funds must be credited
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.
The name of the identity's bank.
9-digit ABA Routing Transit Number (RTN) of the beneficiary’s bank.
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
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:
- SCT Inst
- Conditions: beneficiary account is SCT Inst-addressable AND amount ≤ €100,000
- SCT
- Conditions: otherwise applicable
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:
- FPS
- Conditions: beneficiary account is FPS-addressable AND amount ≤ £1,000,000
- CHAPS
- Conditions: otherwise applicable
The name of the identity's bank
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
The name of the identity's bank
The identity's account number associated with the Account Identification Scheme
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
The name of the identity's bank
The code of the identity's bank (BICFI code)
The identity's PIX key, which can be an email, phone number, or a hash
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
The name of the identity's bank
The identity's account number associated with the Account Identification Scheme
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
The name of the identity's bank
The code of the identity's bank (BICFI code)
The branch number of the identity's bank account
The identity's account number associated with the Account Identification Scheme
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
The name of the identity's bank
The identity's account number associated with the Account Identification Scheme
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 Value | Description |
|---|---|
| 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. |
| AFRICA_BANK_PAYOUT | Nigeria Bank Payout - A payment method for bank transfers in Nigeria. |
| 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. |
Example: "BR_PIX"
The unique identifier of the financial instrument.
Example: "3fc74743-e7f3-414a-9fcf-eb8c1d52356a"
The time at which the financial instrument was created
Example: "2023-11-02T18:26:00.000Z"
Response
application/json
{ "usAch": { "bankName": "string", "bankRoutingNumber": "stringstr", "accountNumber": "string", "accountType": "string" }, "usFedwire": { "bankName": "string", "bankRoutingNumber": "stringstr", "accountNumber": "string" }, "mxSpei": { "bankName": "string", "clabe": "stringstringstring" }, "euSepa": { "bankName": "string", "iban": "stringstringstr" }, "gbFps": { "bankName": "string", "sortCode": "string", "accountNumber": "stringst" }, "africaBankPayout": { "bankName": "string", "bankCode": "string", "accountNumber": "string", "country": "NG" }, "brPix": { "bankName": "string", "bankCode": "stringst", "branchNumber": "string", "pixKey": "string", "pixKeyType": "string" }, "coPse": { "bankName": "string", "bankCode": "stri", "accountNumber": "string", "accountType": "string" }, "brTed": { "bankName": "string", "bankCode": "stringst", "branchNumber": "string", "accountNumber": "string", "accountType": "SAVINGS" }, "caEft": { "bankName": "string", "institutionNumber": "str", "transitNumber": "strin", "accountNumber": "strings", "accountType": "string" }, "currency": "MXN", "label": "mexico bank account", "financialInstrumentType": "BR_PIX", "country": "MX", "financialInstrumentId": "3fc74743-e7f3-414a-9fcf-eb8c1d52356a", "createdAt": "2023-11-02T18:26:00.000Z", "updatedAt": "2023-11-03T18:26:00.000Z" }
- Mock server
https://docs.ripple.com/_mock/products/payments-direct-2/api-docs/payments-direct-api/payments-direct-2-api/v3/identities/{identity-id}/financial-instruments/{financial-instrument-id}
- UAT environment with simulated currency
https://api.test.ripple.com/v3/identities/{identity-id}/financial-instruments/{financial-instrument-id}
- Production environment
https://api.ripple.com/v3/identities/{identity-id}/financial-instruments/{financial-instrument-id}
- curl
- Python
curl -i -X DELETE \
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/c7e2f5b4-d1a2-4c3a-9e1b-4d5c6f7e8a9d \
-H 'Authorization: Bearer <YOUR_JWT_HERE>'Identities (v2) — Legacy
Use these API operations to manage your identities for existing integrations built on Identity Management v2.
Versioning notes
- v2 identities remain fully supported for ongoing operations.
- New integrations should use v3.
| Operation | Method | Description |
|---|---|---|
| Create a new identity (v2) - Legacy | POST | Create a new v2 legacy identity. |
| Get a list of identities (v2) - Legacy | GET | Get a list of existing v2 legacy identities. |
| Get an identity by ID (v2) - Legacy | GET | Get a v2 legacy identity by its unique ID. |
| Delete an identity (v2) - Legacy | DELETE | Deactivate a v2 legacy identity. |
Operations
Quotes
Use these API operations to manage your quotes.
| Operation | Method | Description |
|---|---|---|
| Create quote collection | POST | Create a collection of quotes. |
| Get quote collection | GET | Get a quote collection by ID. |
| Get a quote | GET | Get a specific quote by ID. |
Operations
Payments (v3)
Use these API operations to manage your payments with Payment Management v3 (recommended for all new integrations).
| Operation | Method | Description |
|---|---|---|
| Search payments (v3) | POST | Search for v3 payments based on filtering criteria. |
| Create a payment (v3) | POST | Create a v3payment by accepting a quote. |
| Get payment by payment ID (v3) | GET | Get a specific v3 payment by payment ID. |
| Get state transitions by payment ID (v3) | GET | Get the state transitions for a specific v3 payment by payment ID. |
| Update payment labels (v3) | PATCH | Update the labels for a specific v3 payment by payment ID. |
Operations
Payments (v2) - Legacy
Use these API operations to manage your v2 legacy payments.
| Operation | Method | Description |
|---|---|---|
| Search payments (v2) - Legacy) | POST | Search for legacy v2 payments based on filtering criteria. |
| Create a payment (v2) - Legacy) | POST | Create a legacy v2 payment by accepting a quote. |
| Get a payment by payment ID (v2) - Legacy | GET | Get a specific legacy v2 payment by payment ID. |
| Get state transitions by payment ID (v2) - Legacy | GET | Get the state transitions for a specific legacy v2 payment by payment ID. |
| Update payment labels (v2) - Legacy | PATCH | Update the labels for a specific legacy v2 payment by payment ID. |
Operations
Ledger
Use these API operation to fetch ledger transactions and check balances.
| Operation | Method | Description |
|---|---|---|
| Get balances | GET | View your existing balances |
| Get ledger transactions | GET | View your ledger transactions. |
Operations