Skip to content

Create and manage financial instruments

This tutorial shows how to use the Identity Management v3 financial instrument endpoints to:

  • Create a financial instrument for an identity
  • List an identity’s financial instruments
  • Retrieve a financial instrument by ID
  • Update financial instrument details
  • Deactivate a financial instrument

It assumes you’ve read Financial instruments for payments and Payment identities.

Multiple instruments per identity

In Identity Management v3, an identity can have one or more financial instruments, allowing a single party (identity) to hold multiple bank accounts or payout rails.

Before you begin

To follow these examples, you need:

  • Base URL for the Ripple Payments Direct 2.0 API (for example, https://{base-url})
  • A valid OAuth2 access token with scopes:
    • participants:create – create financial instruments
    • participants:read – list and get financial instruments
    • participants:update – update and deactivate financial instruments
  • An existing identityId (created via the identities endpoints)

In all examples, replace:

  • {base-url} with your PII base URL
  • <access_token> with a valid access token
  • {identity-id} and {financial-instrument-id} with real IDs from your environment

Create a financial instrument

Use POST /v3/identities/{identity-id}/financial-instruments to create a financial instrument for an existing identity.

You must provide:

  • financialInstrumentType – the rail, such as US_ACH, MX_SPEI, BR_PIX
  • currency – ISO 4217 currency code (for example, USD, MXN, BRL)
  • Exactly one rail-specific object (for example, usAch, mxSpei, brPix) with the required account details
  • Optional metadata such as label

Example: Create a US ACH bank account

curl -X POST "https://{base-url}/v3/identities/{identity-id}/financial-instruments" \
  -H "Authorization: Bearer <access_token>" \
  -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 (201 Created)

{
  "financialInstrumentId": "2f4ac57f-c5ba-4051-b51f-b3565778717b"
}

You’ll use this financialInstrumentId when:

  • Getting the instrument by ID
  • Updating or deactivating the instrument
  • Referencing it in payment creation flows

Example: Create an MX SPEI bank account for the same identity

curl -X POST "https://{base-url}/v3/identities/{identity-id}/financial-instruments" \
  -H "Authorization: Bearer <access_token>" \
  -H "Content-Type: application/json" \
  -d '{
    "financialInstrumentType": "MX_SPEI",
    "currency": "MXN",
    "label": "MXN SPEI account",
    "mxSpei": {
      "bankName": "Banco Ejemplo",
      "clabe": "032180000118359719"
    }
  }'

Now the same identity holds two financial instruments (one US ACH, one MX SPEI).

Missing or invalid fields

If required fields are missing or invalid (for example, CLABE length or routing code format), the API returns 400 Bad Request with details about the failing fields.

If the identity-id does not exist, the API returns 404 Not Found.

List financial instruments for an identity

Use GET /v3/identities/{identity-id}/financial-instruments to list financial instruments for an identity.

Query parameters:

  • version – optional identity version. If omitted, the latest identity version is used.
  • limit – maximum number of instruments to return (1–100, default 10).
  • next-token – pagination token from a previous response.

Example: List instruments for an identity

curl -X GET "https://{base-url}/v3/identities/{identity-id}/financial-instruments?limit=10" \
  -H "Authorization: Bearer <access_token>"

Response (200 OK)

{
  "data": [
    {
      "financialInstrumentId": "2f4ac57f-c5ba-4051-b51f-b3565778717b",
      "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"
    },
    {
      "financialInstrumentId": "9e267ec3-0f75-4e8b-93b2-bf7e2f2a9e0d",
      "financialInstrumentType": "MX_SPEI",
      "currency": "MXN",
      "label": "MXN SPEI account",
      "country": "MX",
      "createdAt": "2025-10-01T18:50:12.100Z",
      "updatedAt": "2025-10-01T18:50:12.100Z"
    }
  ],
  "nextToken": "eyJrZXkxIjoidmFsdWVfMSIsImtleTIiOiJ2YWx1ZTIifQ=="
}
  • The data array can contain multiple instruments for the same identity.
  • Only metadata is returned; rail-specific objects (such as usAch or mxSpei) are not included.
  • If nextToken is present, pass it as next-token to fetch the next page:
curl -X GET "https://{base-url}/v3/identities/{identity-id}/financial-instruments?limit=10&next-token=eyJrZXkxIjoidmFsdWVfMSIsImtleTIiOiJ2YWx1ZTIifQ==" \
  -H "Authorization: Bearer <access_token>"

If the identity or instruments are not found, the API returns 404 Not Found.

Get a financial instrument by ID

Use GET /v3/identities/{identity-id}/financial-instruments/{financial-instrument-id} to retrieve full details for a specific financial instrument, including the rail-specific object.

###Example: Get a US ACH financial instrument

curl -X GET "https://{base-url}/v3/identities/{identity-id}/financial-instruments/{financial-instrument-id}" \
  -H "Authorization: Bearer <access_token>"

Response (200 OK)

{
  "financialInstrument": {
    "country": "US",
    "financialInstrumentId": "7f2bac05-42a3-4b26-89fd-333396fdba70",
    "createdAt": "2025-10-01T18:46:47.430Z",
    "updatedAt": "2025-10-01T18:46:47.430Z",
    "usAch": {
      "bankName": "Bank of Example",
      "bankRoutingNumber": "266231608",
      "accountNumber": "60480",
      "accountType": "CHECKING"
    },
    "currency": "USD",
    "label": "US bank account",
    "financialInstrumentType": "US_ACH"
  }
}
Errors

If either the identity-id or financial-instrument-id is invalid or does not exist, the API returns 400 or 404 respectively.

Update a financial instrument

Use PUT /v3/identities/{identity-id}/financial-instruments/{financial-instrument-id} to update editable fields of an existing financial instrument.

You can:

  • Update metadata such as label.
  • Update rail-specific details, such as account number or PIX key.

You cannot change:

  • financialInstrumentType
  • currency

Partial updates

The request supports partial updates:

  • Fields you include are overwritten.
  • Fields you omit remain unchanged.

Example: Update only the label

curl -X PUT "https://{base-url}/v3/identities/{identity-id}/financial-instruments/{financial-instrument-id}" \
  -H "Authorization: Bearer <access_token>" \
  -H "Content-Type: application/json" \
  -d '{
    "label": "US bank account (primary)"
  }'

Response (200 OK)

{
  "financialInstrumentId": "7f2bac05-42a3-4b26-89fd-333396fdba70",
  "financialInstrumentType": "US_ACH",
  "currency": "USD",
  "label": "US bank account (primary)",
  "country": "US",
  "createdAt": "2025-10-01T18:46:47.430Z",
  "updatedAt": "2025-10-02T09:15:10.000Z"
}
Response

The update response returns the instrument entry (metadata + timestamps) but does not include the rail-specific object (such as usAch).

Example: Update rail-specific details (US ACH)

curl -X PUT "https://{base-url}/v3/identities/{identity-id}/financial-instruments/{financial-instrument-id}" \
  -H "Authorization: Bearer <access_token>" \
  -H "Content-Type: application/json" \
  -d '{
    "usAch": {
      "bankName": "Bank of Example",
      "bankRoutingNumber": "266231608",
      "accountNumber": "987654321",
      "accountType": "CHECKING"
    }'
Errors

If the update payload is invalid (for example, unsupported account type or invalid routing format), the API returns 400 Bad Request with error details.

If the identity or instrument is not found, the API returns 404 Not Found.

If there is a conflicting resource state (for example, concurrent update or other internal constraint), the API may return 409 Conflict.

Deactivate a financial instrument

Use DELETE /v3/identities/{identity-id}/financial-instruments/{financial-instrument-id} to deactivate a financial instrument.

Deactivation:

  • Is permanent for that instrument.
  • Prevents the instrument from being used for new payments.
  • Keeps historical usage and data for audit and reconciliation.
Identity deactivation

Deactivating an identity (via the identities endpoints) also deactivates its financial instrument.

Example: Deactivate a financial instrument

curl -X DELETE "https://{base-url}/v3/identities/{identity-id}/financial-instruments/{financial-instrument-id}" \
  -H "Authorization: Bearer <access_token>"

Response (204 No Content)

The following errors may occur:

  • 400 Bad Request – malformed identity or instrument ID.
  • 404 Not Found – the identity or instrument does not exist.
  • 409 Conflict – the instrument is already deactivated or cannot be deactivated due to its current state.
  • 500 Internal Server Error – unexpected server-side error.

Error handling

All financial instrument endpoints use the standard error response schema:

  • code – machine-readable error code
  • title – short description
  • description – detailed explanation and remediation hints

Common scenarios:

  • 400 – structural validation errors (missing required fields, pattern violations, invalid enum values).
  • 404 – identity or financial instrument not found.
  • 409 – conflicting state (for example, update or deactivate not allowed).
  • 500 – internal processing error; if persistent, contact Ripple support.

Refer to the Error handling reference in the API docs for the complete list of error codes.

Next steps

  • To understand how instruments fit into the overall payout setup, see Financial instruments for payments.
  • To review the KYC / PII model that instruments attach to, see Payment identities.
  • To see how identities and financial instruments are used together when sending money, continue with the Create a payment tutorial.