{"templateId":"markdown","versions":[{"version":"v2026.03","label":"v2026.03","link":"/products/payments-direct-2/api-docs/tutorials/create-and-manage-financial-instruments","default":true,"active":true,"folderId":"eb16255d"},{"version":"v2025.11","label":"v2025.11","link":"/products/payments-direct-2/v2025.11/api-docs/tutorials/create-and-manage-financial-instruments","default":false,"active":false,"folderId":"eb16255d"}],"sharedDataIds":{"sidebar":"sidebar-products/payments-direct-2/@v2025.11/sidebars.yaml"},"props":{"metadata":{"markdoc":{"tagList":["admonition"]},"type":"markdown"},"seo":{"title":"Create and manage financial instruments","description":"User guides, API reference, and support resources.","siteUrl":"https://docs.ripple.com/products/custody","lang":"en-US","llmstxt":{"hide":false,"sections":[{"title":"Table of contents","includeFiles":["**/*"],"excludeFiles":[]}],"excludeFiles":[]}},"dynamicMarkdocComponents":[],"compilationErrors":[],"ast":{"$$mdtype":"Tag","name":"article","attributes":{},"children":[{"$$mdtype":"Tag","name":"Heading","attributes":{"level":1,"id":"create-and-manage-financial-instruments","__idx":0},"children":["Create and manage financial instruments"]},{"$$mdtype":"Tag","name":"Admonition","attributes":{"type":"info","name":"Identity Management v3"},"children":[{"$$mdtype":"Tag","name":"p","attributes":{},"children":["This topic describes the v3 identity model. ",{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["Identity Management v3"]}," is recommended for all new integrations."]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["The supported payment corridors are:"]},{"$$mdtype":"Tag","name":"ul","attributes":{},"children":[{"$$mdtype":"Tag","name":"li","attributes":{},"children":["US • USD"]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":["EU • EUR"]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":["MX • MXN"]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":["BR • BRL"]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":["CO • COP"]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":["CA • CAD"]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":["GB • GBP"]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":["NG • NGN"]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":["SWIFT • USD"]}]}]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["This tutorial shows how to use the ",{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["Identity Management v3"]}," financial instrument endpoints to:"]},{"$$mdtype":"Tag","name":"ul","attributes":{},"children":[{"$$mdtype":"Tag","name":"li","attributes":{},"children":["Create a financial instrument for an identity"]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":["List an identity’s financial instruments"]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":["Retrieve a financial instrument by ID"]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":["Update financial instrument details"]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":["Deactivate a financial instrument"]}]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["It assumes you’ve read ",{"$$mdtype":"Tag","name":"a","attributes":{"href":"/products/payments-direct-2/api-docs/concepts/financial-instruments"},"children":["Financial instruments"]}," for payments and ",{"$$mdtype":"Tag","name":"a","attributes":{"href":"/products/payments-direct-2/api-docs/concepts/payment-identities"},"children":["Payment identities"]},"."]},{"$$mdtype":"Tag","name":"Admonition","attributes":{"type":"info","name":"Multiple instruments per identity"},"children":[{"$$mdtype":"Tag","name":"p","attributes":{},"children":["In Identity Management v3, an identity can have ",{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["one or more financial instruments"]},", allowing a single party (identity) to hold multiple bank accounts or payout rails."]}]},{"$$mdtype":"Tag","name":"hr","attributes":{},"children":[]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":2,"id":"before-you-begin","__idx":1},"children":["Before you begin"]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["To follow these examples, you need:"]},{"$$mdtype":"Tag","name":"ul","attributes":{},"children":[{"$$mdtype":"Tag","name":"li","attributes":{},"children":["Base URL for the Ripple Payments Direct 2.0 API (for example,",{"$$mdtype":"Tag","name":"code","attributes":{},"children":[" https://{base-url}"]},")"]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":["A valid OAuth2 access token with scopes:",{"$$mdtype":"Tag","name":"ul","attributes":{},"children":[{"$$mdtype":"Tag","name":"li","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["participants:create"]}," – create financial instruments"]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["participants:read"]}," – list and get financial instruments"]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["participants:update"]}," – update and deactivate financial instruments"]}]}]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":["An existing ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["identityId"]}," (created via the identities endpoints)"]}]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["In all examples, replace:"]},{"$$mdtype":"Tag","name":"ul","attributes":{},"children":[{"$$mdtype":"Tag","name":"li","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["{base-url}"]}," with your PII base URL"]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["<access_token>"]}," with a valid access token"]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["{identity-id} "]},"and ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["{financial-instrument-id}"]}," with real IDs from your environment"]}]},{"$$mdtype":"Tag","name":"hr","attributes":{},"children":[]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":2,"id":"create-a-financial-instrument","__idx":2},"children":["Create a financial instrument"]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["Use ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["POST /v3/identities/{identity-id}/financial-instruments"]}," to create a financial instrument for an existing identity."]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["You must provide:"]},{"$$mdtype":"Tag","name":"ul","attributes":{},"children":[{"$$mdtype":"Tag","name":"li","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["financialInstrumentType"]}," – the rail, such as ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["US_ACH"]},", ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["MX_SPEI"]},",",{"$$mdtype":"Tag","name":"code","attributes":{},"children":[" BR_PIX"]}]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["currency"]}," – ISO 4217 currency code (for example, ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["USD"]},", ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["MXN"]},", ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["BRL"]},")"]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":["Exactly one rail-specific object (for example, ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["usAch"]},", ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["mxSpei"]},", ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["brPix"]},") with the required account details"]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":["Optional metadata such as ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["label"]}]}]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":3,"id":"example-create-a-us-ach-bank-account","__idx":3},"children":["Example: Create a US ACH bank account"]},{"$$mdtype":"Tag","name":"CodeBlock","attributes":{"data-language":"bash","header":{"controls":{"copy":{}}},"source":"curl -X POST \"https://{base-url}/v3/identities/{identity-id}/financial-instruments\" \\\n  -H \"Authorization: Bearer <access_token>\" \\\n  -H \"Content-Type: application/json\" \\\n  -d '{\n    \"financialInstrumentType\": \"US_ACH\",\n    \"currency\": \"USD\",\n    \"label\": \"US bank account\",\n    \"usAch\": {\n      \"bankName\": \"Bank of Example\",\n      \"bankRoutingNumber\": \"266231608\",\n      \"accountNumber\": \"60480\",\n      \"accountType\": \"CHECKING\"\n    }\n  }'\n","lang":"bash"},"children":[]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":3,"id":"response-201-created","__idx":4},"children":["Response (201 Created)"]},{"$$mdtype":"Tag","name":"CodeBlock","attributes":{"data-language":"json","header":{"controls":{"copy":{}}},"source":"{\n  \"financialInstrumentId\": \"2f4ac57f-c5ba-4051-b51f-b3565778717b\"\n}\n","lang":"json"},"children":[]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["You’ll use this ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["financialInstrumentId"]}," when:"]},{"$$mdtype":"Tag","name":"ul","attributes":{},"children":[{"$$mdtype":"Tag","name":"li","attributes":{},"children":["Getting the instrument by ID"]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":["Updating or deactivating the instrument"]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":["Referencing it in payment creation flows"]}]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":3,"id":"example-create-an-mx-spei-bank-account-for-the-same-identity","__idx":5},"children":["Example: Create an MX SPEI bank account for the same identity"]},{"$$mdtype":"Tag","name":"CodeBlock","attributes":{"data-language":"bash","header":{"controls":{"copy":{}}},"source":"curl -X POST \"https://{base-url}/v3/identities/{identity-id}/financial-instruments\" \\\n  -H \"Authorization: Bearer <access_token>\" \\\n  -H \"Content-Type: application/json\" \\\n  -d '{\n    \"financialInstrumentType\": \"MX_SPEI\",\n    \"currency\": \"MXN\",\n    \"label\": \"MXN SPEI account\",\n    \"mxSpei\": {\n      \"bankName\": \"Banco Ejemplo\",\n      \"clabe\": \"032180000118359719\"\n    }\n  }'\n","lang":"bash"},"children":[]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["Now the same identity holds ",{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["two financial instruments"]}," (one US ACH, one MX SPEI)."]},{"$$mdtype":"Tag","name":"Admonition","attributes":{"type":"warning","name":"Missing or invalid fields"},"children":[{"$$mdtype":"Tag","name":"p","attributes":{},"children":["If required fields are missing or invalid (for example, CLABE length or routing code format), the API returns ",{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["400 Bad Request"]}," with details about the failing fields."]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["If the ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["identity-id"]}," does not exist, the API returns ",{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["404 Not Found"]},"."]}]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":3,"id":"identity-validation-and-validatepayoutrails","__idx":6},"children":["Identity validation and ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["validatePayoutRails"]}]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["When you create a financial instrument, the associated identity must have all required PII for the specified ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["financialInstrumentType"]},"."]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":[{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["If the identity was created with ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["validatePayoutRails"]},":"]}]},{"$$mdtype":"Tag","name":"ul","attributes":{},"children":[{"$$mdtype":"Tag","name":"li","attributes":{},"children":["The identity's PII was already validated against the specified payout rails at identity creation time."]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":["Creating a financial instrument for a rail listed in ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["validatePayoutRails"]}," succeeds immediately (assuming the identity has the required PII)."]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":["Creating a financial instrument for a rail ",{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["not"]}," listed in ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["validatePayoutRails"]}," triggers validation at instrument creation time. If required PII is missing, the request fails with ",{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["400 Bad Request"]},"."]}]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":[{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["If the identity was created without ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["validatePayoutRails"]},":"]}]},{"$$mdtype":"Tag","name":"ul","attributes":{},"children":[{"$$mdtype":"Tag","name":"li","attributes":{},"children":["The identity's PII is validated when you create the financial instrument."]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":["If required fields are missing for the specified ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["financialInstrumentType"]},", the request fails with ",{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["400 Bad Request"]}," and details about which fields are missing."]}]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":[{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["Example: Validation failure due to missing PII"]}]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["If you try to create a ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["US_ACH"]}," financial instrument for an identity that's missing required fields like ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["dateOfBirth"]}," or ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["identityDocuments"]},", you'll receive:"]},{"$$mdtype":"Tag","name":"CodeBlock","attributes":{"data-language":"json","header":{"controls":{"copy":{}}},"source":"{\n  \"code\": \"VALIDATION_ERROR\",\n  \"title\": \"Identity validation failed\",\n  \"description\": \"The identity is missing required fields for the specified financial instrument type.\",\n  \"details\": [\n    {\n      \"field\": \"individual.dateOfBirth\",\n      \"message\": \"Date of birth is required for US_ACH beneficiary identities\"\n    },\n    {\n      \"field\": \"individual.identityDocuments\",\n      \"message\": \"At least one identity document (SSN or Tax ID) is required for US_ACH beneficiary identities\"\n    }\n  ]\n}\n","lang":"json"},"children":[]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["To fix this, update the identity with the missing PII fields using ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["PUT /v3/identities/{identity-id}"]},", then retry creating the financial instrument."]},{"$$mdtype":"Tag","name":"Admonition","attributes":{"type":"info","name":"Upfront validation"},"children":[{"$$mdtype":"Tag","name":"p","attributes":{},"children":["Using ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["validatePayoutRails"]}," when creating identities helps catch PII issues early, before you attempt to create financial instruments. For details, see ",{"$$mdtype":"Tag","name":"a","attributes":{"href":"/products/payments-direct-2/api-docs/concepts/payment-identities#validating-identities-for-specific-payout-rails"},"children":["Validating identities for specific payout rails"]},"."]}]},{"$$mdtype":"Tag","name":"hr","attributes":{},"children":[]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":2,"id":"list-financial-instruments-for-an-identity","__idx":7},"children":["List financial instruments for an identity"]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["Use ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["GET /v3/identities/{identity-id}/financial-instruments"]}," to list financial instruments for an identity."]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["Query parameters:"]},{"$$mdtype":"Tag","name":"ul","attributes":{},"children":[{"$$mdtype":"Tag","name":"li","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["version"]}," – optional identity version. If omitted, the latest identity version is used."]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["limit"]}," – maximum number of instruments to return (1–100, default 10)."]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["next-token"]}," – pagination token from a previous response."]}]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":3,"id":"example-list-instruments-for-an-identity","__idx":8},"children":["Example: List instruments for an identity"]},{"$$mdtype":"Tag","name":"CodeBlock","attributes":{"data-language":"bash","header":{"controls":{"copy":{}}},"source":"curl -X GET \"https://{base-url}/v3/identities/{identity-id}/financial-instruments?limit=10\" \\\n  -H \"Authorization: Bearer <access_token>\"\n","lang":"bash"},"children":[]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":3,"id":"response-200-ok","__idx":9},"children":["Response (200 OK)"]},{"$$mdtype":"Tag","name":"CodeBlock","attributes":{"data-language":"json","header":{"controls":{"copy":{}}},"source":"{\n  \"data\": [\n    {\n      \"financialInstrumentId\": \"2f4ac57f-c5ba-4051-b51f-b3565778717b\",\n      \"financialInstrumentType\": \"US_ACH\",\n      \"currency\": \"USD\",\n      \"label\": \"US bank account\",\n      \"country\": \"US\",\n      \"createdAt\": \"2025-10-01T18:46:47.430Z\",\n      \"updatedAt\": \"2025-10-01T18:46:47.430Z\"\n    },\n    {\n      \"financialInstrumentId\": \"9e267ec3-0f75-4e8b-93b2-bf7e2f2a9e0d\",\n      \"financialInstrumentType\": \"MX_SPEI\",\n      \"currency\": \"MXN\",\n      \"label\": \"MXN SPEI account\",\n      \"country\": \"MX\",\n      \"createdAt\": \"2025-10-01T18:50:12.100Z\",\n      \"updatedAt\": \"2025-10-01T18:50:12.100Z\"\n    }\n  ],\n  \"nextToken\": \"eyJrZXkxIjoidmFsdWVfMSIsImtleTIiOiJ2YWx1ZTIifQ==\"\n}\n","lang":"json"},"children":[]},{"$$mdtype":"Tag","name":"ul","attributes":{},"children":[{"$$mdtype":"Tag","name":"li","attributes":{},"children":["The data array can contain ",{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["multiple"]}," instruments for the same identity."]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":["Only metadata is returned; rail-specific objects (such as ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["usAch"]}," or ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["mxSpei"]},") are not included."]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":["If ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["nextToken"]}," is present, pass it as ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["next-token"]}," to fetch the next page:"]}]},{"$$mdtype":"Tag","name":"CodeBlock","attributes":{"data-language":"bash","header":{"controls":{"copy":{}}},"source":"curl -X GET \"https://{base-url}/v3/identities/{identity-id}/financial-instruments?limit=10&next-token=eyJrZXkxIjoidmFsdWVfMSIsImtleTIiOiJ2YWx1ZTIifQ==\" \\\n  -H \"Authorization: Bearer <access_token>\"\n","lang":"bash"},"children":[]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["If the identity or instruments are not found, the API returns ",{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["404 Not Found"]},"."]},{"$$mdtype":"Tag","name":"hr","attributes":{},"children":[]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":2,"id":"get-a-financial-instrument-by-id","__idx":10},"children":["Get a financial instrument by ID"]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["Use ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["GET /v3/identities/{identity-id}/financial-instruments/{financial-instrument-id}"]}," to retrieve full details for a specific financial instrument, including the rail-specific object."]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["###Example: Get a US ACH financial instrument"]},{"$$mdtype":"Tag","name":"CodeBlock","attributes":{"data-language":"bash","header":{"controls":{"copy":{}}},"source":"curl -X GET \"https://{base-url}/v3/identities/{identity-id}/financial-instruments/{financial-instrument-id}\" \\\n  -H \"Authorization: Bearer <access_token>\"\n","lang":"bash"},"children":[]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":3,"id":"response-200-ok-1","__idx":11},"children":["Response (200 OK)"]},{"$$mdtype":"Tag","name":"CodeBlock","attributes":{"data-language":"json","header":{"controls":{"copy":{}}},"source":"{\n  \"financialInstrument\": {\n    \"country\": \"US\",\n    \"financialInstrumentId\": \"7f2bac05-42a3-4b26-89fd-333396fdba70\",\n    \"createdAt\": \"2025-10-01T18:46:47.430Z\",\n    \"updatedAt\": \"2025-10-01T18:46:47.430Z\",\n    \"usAch\": {\n      \"bankName\": \"Bank of Example\",\n      \"bankRoutingNumber\": \"266231608\",\n      \"accountNumber\": \"60480\",\n      \"accountType\": \"CHECKING\"\n    },\n    \"currency\": \"USD\",\n    \"label\": \"US bank account\",\n    \"financialInstrumentType\": \"US_ACH\"\n  }\n}\n","lang":"json"},"children":[]},{"$$mdtype":"Tag","name":"Admonition","attributes":{"type":"warning","name":"Errors"},"children":[{"$$mdtype":"Tag","name":"p","attributes":{},"children":["If either the ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["identity-id"]}," or ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["financial-instrument-id"]}," is invalid or does not exist, the API returns ",{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["400"]}," or ",{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["404"]}," respectively."]}]},{"$$mdtype":"Tag","name":"hr","attributes":{},"children":[]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":2,"id":"update-a-financial-instrument","__idx":12},"children":["Update a financial instrument"]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["Use ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["PUT /v3/identities/{identity-id}/financial-instruments/{financial-instrument-id}"]}," to update editable fields of an existing financial instrument."]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":[{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["You can:"]}]},{"$$mdtype":"Tag","name":"ul","attributes":{},"children":[{"$$mdtype":"Tag","name":"li","attributes":{},"children":["Update metadata such as label."]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":["Update rail-specific details, such as account number or PIX key."]}]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":[{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["You cannot change:"]}]},{"$$mdtype":"Tag","name":"ul","attributes":{},"children":[{"$$mdtype":"Tag","name":"li","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["financialInstrumentType"]}]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["currency"]}]}]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":3,"id":"partial-updates","__idx":13},"children":["Partial updates"]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["The request supports partial updates:"]},{"$$mdtype":"Tag","name":"ul","attributes":{},"children":[{"$$mdtype":"Tag","name":"li","attributes":{},"children":["Fields you include are ",{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["overwritten"]},"."]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":["Fields you omit remain ",{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["unchanged"]},"."]}]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":3,"id":"example-update-only-the-label","__idx":14},"children":["Example: Update only the label"]},{"$$mdtype":"Tag","name":"CodeBlock","attributes":{"data-language":"bash","header":{"controls":{"copy":{}}},"source":"curl -X PUT \"https://{base-url}/v3/identities/{identity-id}/financial-instruments/{financial-instrument-id}\" \\\n  -H \"Authorization: Bearer <access_token>\" \\\n  -H \"Content-Type: application/json\" \\\n  -d '{\n    \"label\": \"US bank account (primary)\"\n  }'\n","lang":"bash"},"children":[]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":3,"id":"response-200-ok-2","__idx":15},"children":["Response (200 OK)"]},{"$$mdtype":"Tag","name":"CodeBlock","attributes":{"data-language":"json","header":{"controls":{"copy":{}}},"source":"{\n  \"financialInstrumentId\": \"7f2bac05-42a3-4b26-89fd-333396fdba70\",\n  \"financialInstrumentType\": \"US_ACH\",\n  \"currency\": \"USD\",\n  \"label\": \"US bank account (primary)\",\n  \"country\": \"US\",\n  \"createdAt\": \"2025-10-01T18:46:47.430Z\",\n  \"updatedAt\": \"2025-10-02T09:15:10.000Z\"\n}\n","lang":"json"},"children":[]},{"$$mdtype":"Tag","name":"Admonition","attributes":{"type":"info","name":"Response"},"children":[{"$$mdtype":"Tag","name":"p","attributes":{},"children":["The update response returns the ",{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["instrument entry"]}," (metadata + timestamps) but does ",{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["not"]}," include the rail-specific object (such as ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["usAch"]},")."]}]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":3,"id":"example-update-rail-specific-details-us-ach","__idx":16},"children":["Example: Update rail-specific details (US ACH)"]},{"$$mdtype":"Tag","name":"CodeBlock","attributes":{"data-language":"bash","header":{"controls":{"copy":{}}},"source":"curl -X PUT \"https://{base-url}/v3/identities/{identity-id}/financial-instruments/{financial-instrument-id}\" \\\n  -H \"Authorization: Bearer <access_token>\" \\\n  -H \"Content-Type: application/json\" \\\n  -d '{\n    \"usAch\": {\n      \"bankName\": \"Bank of Example\",\n      \"bankRoutingNumber\": \"266231608\",\n      \"accountNumber\": \"987654321\",\n      \"accountType\": \"CHECKING\"\n    }'\n","lang":"bash"},"children":[]},{"$$mdtype":"Tag","name":"Admonition","attributes":{"type":"warning","name":"Errors"},"children":[{"$$mdtype":"Tag","name":"p","attributes":{},"children":["If the update payload is invalid (for example, unsupported account type or invalid routing format), the API returns ",{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["400 Bad Request"]}," with error details."]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["If the identity or instrument is not found, the API returns ",{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["404 Not Found"]},"."]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["If there is a conflicting resource state (for example, concurrent update or other internal constraint), the API may return ",{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["409 Conflict"]},"."]}]},{"$$mdtype":"Tag","name":"hr","attributes":{},"children":[]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":2,"id":"deactivate-a-financial-instrument","__idx":17},"children":["Deactivate a financial instrument"]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["Use ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["DELETE /v3/identities/{identity-id}/financial-instruments/{financial-instrument-id}"]}," to deactivate a financial instrument."]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":[{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["Deactivation:"]}]},{"$$mdtype":"Tag","name":"ul","attributes":{},"children":[{"$$mdtype":"Tag","name":"li","attributes":{},"children":["Is ",{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["permanent"]}," for that instrument."]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":["Prevents the instrument from being used for ",{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["new payments"]},"."]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":["Keeps historical usage and data for audit and reconciliation."]}]},{"$$mdtype":"Tag","name":"Admonition","attributes":{"type":"warning","name":"Identity deactivation"},"children":[{"$$mdtype":"Tag","name":"p","attributes":{},"children":["Deactivating an identity (via the identities endpoints) also deactivates its financial instrument."]}]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":3,"id":"example-deactivate-a-financial-instrument","__idx":18},"children":["Example: Deactivate a financial instrument"]},{"$$mdtype":"Tag","name":"CodeBlock","attributes":{"data-language":"bash","header":{"controls":{"copy":{}}},"source":"curl -X DELETE \"https://{base-url}/v3/identities/{identity-id}/financial-instruments/{financial-instrument-id}\" \\\n  -H \"Authorization: Bearer <access_token>\"\n","lang":"bash"},"children":[]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":3,"id":"response-204-no-content","__idx":19},"children":["Response (204 No Content)"]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["The following errors may occur:"]},{"$$mdtype":"Tag","name":"ul","attributes":{},"children":[{"$$mdtype":"Tag","name":"li","attributes":{},"children":[{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["400 Bad Request"]}," – malformed identity or instrument ID."]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":[{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["404 Not Found"]}," – the identity or instrument does not exist."]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":[{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["409 Conflict"]}," – the instrument is already deactivated or cannot be deactivated due to its current state."]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":[{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["500 Internal Server Error"]}," – unexpected server-side error."]}]},{"$$mdtype":"Tag","name":"hr","attributes":{},"children":[]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":2,"id":"error-handling","__idx":20},"children":["Error handling"]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["All financial instrument endpoints use the standard error response schema:"]},{"$$mdtype":"Tag","name":"ul","attributes":{},"children":[{"$$mdtype":"Tag","name":"li","attributes":{},"children":[{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["code"]}," – machine-readable error code"]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":[{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["title"]}," – short description"]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":[{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["description"]}," – detailed explanation and remediation hints"]}]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["Common scenarios:"]},{"$$mdtype":"Tag","name":"ul","attributes":{},"children":[{"$$mdtype":"Tag","name":"li","attributes":{},"children":[{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["400"]}," – structural validation errors (missing required fields, pattern violations, invalid enum values)."]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":[{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["404"]}," – identity or financial instrument not found."]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":[{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["409"]}," – conflicting state (for example, update or deactivate not allowed)."]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":[{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["500"]}," – internal processing error; if persistent, contact Ripple support."]}]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["Refer to the ",{"$$mdtype":"Tag","name":"a","attributes":{"href":"/products/payments-direct-2/api-docs/error-codes/api-errors"},"children":["Error handling reference"]}," in the API docs for the complete list of error codes."]},{"$$mdtype":"Tag","name":"hr","attributes":{},"children":[]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":2,"id":"next-steps","__idx":21},"children":["Next steps"]},{"$$mdtype":"Tag","name":"ul","attributes":{},"children":[{"$$mdtype":"Tag","name":"li","attributes":{},"children":["To understand how instruments fit into the overall payout setup, see ",{"$$mdtype":"Tag","name":"a","attributes":{"href":"/products/payments-direct-2/api-docs/concepts/financial-instruments"},"children":["Financial instruments"]}," for payments."]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":["To review the KYC / PII model that instruments attach to, see ",{"$$mdtype":"Tag","name":"a","attributes":{"href":"/products/payments-direct-2/api-docs/concepts/payment-identities"},"children":["Payment identities"]},"."]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":["To see how identities and financial instruments are used together when sending money, continue with the ",{"$$mdtype":"Tag","name":"a","attributes":{"href":"/products/payments-direct-2/api-docs/tutorials/create-a-payment"},"children":["Create a payment"]}," tutorial."]}]}]},"headings":[{"value":"Create and manage financial instruments","id":"create-and-manage-financial-instruments","depth":1},{"value":"Before you begin","id":"before-you-begin","depth":2},{"value":"Create a financial instrument","id":"create-a-financial-instrument","depth":2},{"value":"Example: Create a US ACH bank account","id":"example-create-a-us-ach-bank-account","depth":3},{"value":"Response (201 Created)","id":"response-201-created","depth":3},{"value":"Example: Create an MX SPEI bank account for the same identity","id":"example-create-an-mx-spei-bank-account-for-the-same-identity","depth":3},{"value":"Identity validation and validatePayoutRails","id":"identity-validation-and-validatepayoutrails","depth":3},{"value":"List financial instruments for an identity","id":"list-financial-instruments-for-an-identity","depth":2},{"value":"Example: List instruments for an identity","id":"example-list-instruments-for-an-identity","depth":3},{"value":"Response (200 OK)","id":"response-200-ok","depth":3},{"value":"Get a financial instrument by ID","id":"get-a-financial-instrument-by-id","depth":2},{"value":"Response (200 OK)","id":"response-200-ok-1","depth":3},{"value":"Update a financial instrument","id":"update-a-financial-instrument","depth":2},{"value":"Partial updates","id":"partial-updates","depth":3},{"value":"Example: Update only the label","id":"example-update-only-the-label","depth":3},{"value":"Response (200 OK)","id":"response-200-ok-2","depth":3},{"value":"Example: Update rail-specific details (US ACH)","id":"example-update-rail-specific-details-us-ach","depth":3},{"value":"Deactivate a financial instrument","id":"deactivate-a-financial-instrument","depth":2},{"value":"Example: Deactivate a financial instrument","id":"example-deactivate-a-financial-instrument","depth":3},{"value":"Response (204 No Content)","id":"response-204-no-content","depth":3},{"value":"Error handling","id":"error-handling","depth":2},{"value":"Next steps","id":"next-steps","depth":2}],"frontmatter":{"title":"Create and manage financial instruments","toc":{"enable":true,"maxDepth":2},"seo":{"title":"Create and manage financial instruments"}},"lastModified":"2026-04-03T15:45:06.000Z","pagePropGetterError":{"message":"","name":""}},"slug":"/products/payments-direct-2/api-docs/tutorials/create-and-manage-financial-instruments","userData":{"isAuthenticated":false,"teams":["anonymous"]},"isPublic":true}