{"templateId":"markdown","versions":[{"version":"v2026.04","label":"v2026.04","link":"/pt-br/products/payments-direct-2/api-docs/developer-guides/create-and-manage-financial-instruments","default":true,"active":true,"folderId":"7e5507fe"},{"version":"v2026.03","label":"v2026.03","link":"/pt-br/products/payments-direct-2/v2026.03/api-docs/developer-guides/create-and-manage-financial-instruments","default":false,"active":false,"folderId":"7e5507fe"},{"version":"v2025.11","label":"v2025.11","link":"/pt-br/products/payments-direct-2/v2025.11/api-docs/developer-guides/create-and-manage-financial-instruments","default":false,"active":false,"folderId":"7e5507fe"}],"sharedDataIds":{"sidebar":"sidebar-@l10n/pt-BR/products/payments-direct-2/@v2025.11/sidebars.yaml"},"props":{"metadata":{"markdoc":{"tagList":["admonition"]},"type":"markdown"},"seo":{"title":"Criar e gerenciar instrumentos financeiros","description":"User guides, API reference, and support resources.","siteUrl":"https://docs.ripple.com","lang":"en-US"},"dynamicMarkdocComponents":[],"compilationErrors":[],"ast":{"$$mdtype":"Tag","name":"article","attributes":{},"children":[{"$$mdtype":"Tag","name":"Heading","attributes":{"level":1,"id":"criar-e-gerenciar-instrumentos-financeiros","__idx":0},"children":["Criar e gerenciar instrumentos financeiros"]},{"$$mdtype":"Tag","name":"Admonition","attributes":{"type":"info","name":"Corredores compatíveis"},"children":[{"$$mdtype":"Tag","name":"p","attributes":{},"children":["Para conhecer os corredores de pagamento compatíveis, consulte ",{"$$mdtype":"Tag","name":"MarkdownLink","attributes":{"href":"/pt-br/products/payments-direct-2/introduction/payout-network"},"children":["Payout network"]},"."]}]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["Este tutorial mostra como usar os endpoints de instrumento financeiro do ",{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["Identity Management v3"]}," para:"]},{"$$mdtype":"Tag","name":"ul","attributes":{},"children":[{"$$mdtype":"Tag","name":"li","attributes":{},"children":["Criar um instrumento financeiro para uma identidade"]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":["Listar os instrumentos financeiros de uma identidade"]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":["Recuperar um instrumento financeiro por ID"]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":["Atualizar os dados de um instrumento financeiro"]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":["Desativar um instrumento financeiro"]}]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["Ele pressupõe que você já leu ",{"$$mdtype":"Tag","name":"MarkdownLink","attributes":{"href":"/pt-br/products/payments-direct-2/introduction/concepts/financial-instruments"},"children":["Instrumentos financeiros"]}," para pagamentos e ",{"$$mdtype":"Tag","name":"MarkdownLink","attributes":{"href":"/pt-br/products/payments-direct-2/introduction/concepts/payment-identities"},"children":["Identidades do pagamento"]},"."]},{"$$mdtype":"Tag","name":"Admonition","attributes":{"type":"info","name":"Um instrumento por identidade"},"children":[{"$$mdtype":"Tag","name":"p","attributes":{},"children":["No Identity Management v3, uma identidade tem ",{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["um instrumento financeiro ativo"]},". Adicionar um segundo instrumento à mesma identidade falha com ",{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["422 Unprocessable Entity"]}," (",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["USR_120"]},"). Para trocar a conta de uma parte, desative o instrumento existente e depois adicione o substituto."]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["O suporte a vários instrumentos por identidade está previsto para uma versão futura. Para mais detalhes, consulte ",{"$$mdtype":"Tag","name":"MarkdownLink","attributes":{"href":"/pt-br/products/payments-direct-2/introduction/concepts/financial-instruments#um-instrumento-financeiro-por-identidade"},"children":["Um instrumento financeiro por identidade"]},"."]}]},{"$$mdtype":"Tag","name":"hr","attributes":{},"children":[]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":2,"id":"antes-de-começar","__idx":1},"children":["Antes de começar"]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["Para seguir estes exemplos, você precisa de:"]},{"$$mdtype":"Tag","name":"ul","attributes":{},"children":[{"$$mdtype":"Tag","name":"li","attributes":{},"children":["URL base da API do ","Payments Direct"," (por exemplo,",{"$$mdtype":"Tag","name":"code","attributes":{},"children":[" https://{base-url}"]},")"]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":["Um token de acesso OAuth2 válido com os escopos:",{"$$mdtype":"Tag","name":"ul","attributes":{},"children":[{"$$mdtype":"Tag","name":"li","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["participants:create"]}," – criar instrumentos financeiros"]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["participants:read"]}," – listar e obter instrumentos financeiros"]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["participants:update"]}," – atualizar e desativar instrumentos financeiros"]}]}]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":["Um ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["identityId"]}," existente (criado pelos endpoints de identidades)"]}]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["Em todos os exemplos, substitua:"]},{"$$mdtype":"Tag","name":"ul","attributes":{},"children":[{"$$mdtype":"Tag","name":"li","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["{base-url}"]}," pela sua URL base de PII"]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["<access_token>"]}," por um token de acesso válido"]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["{identity-id} "]},"e ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["{financial-instrument-id}"]}," por IDs reais do seu ambiente"]}]},{"$$mdtype":"Tag","name":"hr","attributes":{},"children":[]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":2,"id":"criar-um-instrumento-financeiro","__idx":2},"children":["Criar um instrumento financeiro"]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["Use ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["POST /v3/identities/{identity-id}/financial-instruments"]}," para criar um instrumento financeiro para uma identidade existente."]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["Você precisa informar:"]},{"$$mdtype":"Tag","name":"ul","attributes":{},"children":[{"$$mdtype":"Tag","name":"li","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["financialInstrumentType"]}," – o rail, como ",{"$$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"]}," – código de moeda ISO 4217 (por exemplo, ",{"$$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":["Exatamente um objeto específico do rail (por exemplo, ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["usAch"]},", ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["mxSpei"]},", ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["brPix"]},") com os dados obrigatórios da conta"]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":["Metadados opcionais, como ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["label"]}]}]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":3,"id":"exemplo-criar-uma-conta-bancária-us-ach","__idx":3},"children":["Exemplo: criar uma conta bancária US ACH"]},{"$$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":"resposta-201-created","__idx":4},"children":["Resposta (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":["Você usará este ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["financialInstrumentId"]}," ao:"]},{"$$mdtype":"Tag","name":"ul","attributes":{},"children":[{"$$mdtype":"Tag","name":"li","attributes":{},"children":["Obter o instrumento por ID"]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":["Atualizar ou desativar o instrumento"]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":["Referenciá-lo nos fluxos de criação de pagamento"]}]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":3,"id":"exemplo-criar-uma-conta-bancária-mx-spei-para-a-mesma-identidade","__idx":5},"children":["Exemplo: criar uma conta bancária MX SPEI para a mesma identidade"]},{"$$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":["Agora a mesma identidade tem ",{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["dois instrumentos financeiros"]}," (um US ACH e um MX SPEI)."]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":3,"id":"exemplo-criar-um-instrumento-financeiro-de-payout-bancário-na-nigéria","__idx":6},"children":["Exemplo: criar um instrumento financeiro de payout bancário na Nigéria"]},{"$$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\": \"NG_BANK_PAYOUT\",\n    \"currency\": \"NGN\",\n    \"label\": \"NGN bank account\",\n    \"ngBankPayout\": {\n      \"bankName\": \"Guaranty Trust Bank PLC\",\n      \"bankCode\": \"RPL:NG:GTBINGLA:BNK\",\n      \"accountNumber\": \"0123456789\",\n      \"country\": \"NG\"\n    }\n  }'\n","lang":"bash"},"children":[]},{"$$mdtype":"Tag","name":"Admonition","attributes":{"type":"info","name":"Códigos bancários"},"children":[{"$$mdtype":"Tag","name":"p","attributes":{},"children":["O campo ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["bankCode"]}," exige um Ripple Bank Code (RBC), não o código interno do próprio banco. Use a ",{"$$mdtype":"Tag","name":"MarkdownLink","attributes":{"href":"/pt-br/products/payments-direct-2/api-docs/integration-resources/ripple-bank-codes"},"children":["consulta de códigos bancários"]}," para localizar o RBC correto do banco de destino antes de criar o instrumento."]}]},{"$$mdtype":"Tag","name":"Admonition","attributes":{"type":"warning","name":"Campos ausentes ou inválidos"},"children":[{"$$mdtype":"Tag","name":"p","attributes":{},"children":["Se campos obrigatórios estiverem ausentes ou inválidos (por exemplo, o comprimento da CLABE ou o formato do código de roteamento), a API retorna ",{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["400 Bad Request"]}," com detalhes sobre os campos que falharam."]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["Se o ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["identity-id"]}," não existir, a API retorna ",{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["404 Not Found"]},"."]}]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":3,"id":"validação-de-identidade-e-validatepayoutrails","__idx":7},"children":["Validação de identidade e ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["validatePayoutRails"]}]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["Ao criar um instrumento financeiro, a identidade associada precisa ter todos os dados de PII exigidos para o ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["financialInstrumentType"]}," especificado."]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":[{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["Se a identidade foi criada com ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["validatePayoutRails"]},":"]}]},{"$$mdtype":"Tag","name":"ul","attributes":{},"children":[{"$$mdtype":"Tag","name":"li","attributes":{},"children":["Os dados de PII da identidade já foram validados contra os payment rails especificados no momento da criação da identidade."]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":["Criar um instrumento financeiro para um rail listado em ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["validatePayoutRails"]}," é bem-sucedido imediatamente (desde que a identidade tenha os dados de PII exigidos)."]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":["Criar um instrumento financeiro para um rail ",{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["não"]}," listado em ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["validatePayoutRails"]}," dispara a validação no momento da criação do instrumento. Se faltarem dados de PII obrigatórios, a requisição falha com ",{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["400 Bad Request"]},"."]}]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":[{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["Se a identidade foi criada sem ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["validatePayoutRails"]},":"]}]},{"$$mdtype":"Tag","name":"ul","attributes":{},"children":[{"$$mdtype":"Tag","name":"li","attributes":{},"children":["Os dados de PII da identidade são validados quando você cria o instrumento financeiro."]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":["Se faltarem campos obrigatórios para o ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["financialInstrumentType"]}," especificado, a requisição falha com ",{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["400 Bad Request"]}," e detalhes sobre quais campos estão ausentes."]}]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":[{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["Exemplo: falha de validação por PII ausente"]}]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["Se você tentar criar um instrumento financeiro ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["US_ACH"]}," para uma identidade sem campos obrigatórios como ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["identityDocuments"]},", receberá:"]},{"$$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.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":["Para corrigir isso, atualize a identidade com os campos de PII ausentes usando ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["PUT /v3/identities/{identity-id}"]}," e tente criar o instrumento financeiro novamente."]},{"$$mdtype":"Tag","name":"Admonition","attributes":{"type":"warning","name":"Tipos de documento não compatíveis"},"children":[{"$$mdtype":"Tag","name":"p","attributes":{},"children":["A criação de um instrumento financeiro também valida os tipos de documento da identidade contra o corredor do instrumento. Alguns corredores aceitam apenas um subconjunto do enum ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["idType"]}," (pessoa física) ou ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["registration.type"]}," (empresa), portanto uma requisição de instrumento pode falhar com ",{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["400 Bad Request"]}," mesmo quando todos os campos obrigatórios estão presentes. Para ver os valores aceitos por corredor e papel, consulte ",{"$$mdtype":"Tag","name":"MarkdownLink","attributes":{"href":"/pt-br/products/payments-direct-2/introduction/concepts/payment-identities#tipos-de-documento-aceitos-por-corredor"},"children":["Tipos de documento aceitos por corredor"]},"."]}]},{"$$mdtype":"Tag","name":"Admonition","attributes":{"type":"info","name":"Validação antecipada"},"children":[{"$$mdtype":"Tag","name":"p","attributes":{},"children":["Usar ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["validatePayoutRails"]}," ao criar identidades ajuda a detectar problemas de PII com antecedência, antes de você tentar criar instrumentos financeiros. Para mais detalhes, consulte ",{"$$mdtype":"Tag","name":"MarkdownLink","attributes":{"href":"/pt-br/products/payments-direct-2/introduction/concepts/payment-identities#validando-identidades-para-payment-rails-espec%C3%ADficos"},"children":["Validando identidades para payment rails específicos"]},"."]}]},{"$$mdtype":"Tag","name":"hr","attributes":{},"children":[]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":2,"id":"listar-os-instrumentos-financeiros-de-uma-identidade","__idx":8},"children":["Listar os instrumentos financeiros de uma identidade"]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["Use ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["GET /v3/identities/{identity-id}/financial-instruments"]}," para listar os instrumentos financeiros de uma identidade."]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["Parâmetros de consulta:"]},{"$$mdtype":"Tag","name":"ul","attributes":{},"children":[{"$$mdtype":"Tag","name":"li","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["version"]}," – versão opcional da identidade. Se omitido, a versão mais recente da identidade é usada."]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["limit"]}," – número máximo de instrumentos a retornar (de 1 a 100, padrão 10)."]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["next-token"]}," – token de paginação de uma resposta anterior."]}]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":3,"id":"exemplo-listar-os-instrumentos-de-uma-identidade","__idx":9},"children":["Exemplo: listar os instrumentos de uma identidade"]},{"$$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":"resposta-200-ok","__idx":10},"children":["Resposta (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}\n","lang":"json"},"children":[]},{"$$mdtype":"Tag","name":"ul","attributes":{},"children":[{"$$mdtype":"Tag","name":"li","attributes":{},"children":["Como uma identidade tem um instrumento financeiro ativo, o array ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["data"]}," contém no máximo uma entrada. Ele fica vazio se o instrumento da identidade foi desativado e não substituído."]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":["Apenas os metadados são retornados; os objetos específicos do rail (como ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["usAch"]}," ou ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["mxSpei"]},") não são incluídos."]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":["Os parâmetros ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["limit"]}," e ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["next-token"]}," são aceitos por consistência com as demais operações de listagem, mas uma resposta de instrumento único não é paginada e não retorna ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["nextToken"]},"."]}]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["Se a identidade ou os instrumentos não forem encontrados, a API retorna ",{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["404 Not Found"]},"."]},{"$$mdtype":"Tag","name":"hr","attributes":{},"children":[]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":2,"id":"obter-um-instrumento-financeiro-por-id","__idx":11},"children":["Obter um instrumento financeiro por ID"]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["Use ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["GET /v3/identities/{identity-id}/financial-instruments/{financial-instrument-id}"]}," para recuperar os dados completos de um instrumento financeiro específico, incluindo o objeto específico do rail."]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":3,"id":"exemplo-obter-um-instrumento-financeiro-us-ach","__idx":12},"children":["Exemplo: obter um instrumento financeiro US ACH"]},{"$$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":"resposta-200-ok-1","__idx":13},"children":["Resposta (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":"Erros"},"children":[{"$$mdtype":"Tag","name":"p","attributes":{},"children":["Se o ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["identity-id"]}," ou o ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["financial-instrument-id"]}," for inválido ou não existir, a API retorna ",{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["400"]}," ou ",{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["404"]},", respectivamente."]}]},{"$$mdtype":"Tag","name":"hr","attributes":{},"children":[]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":2,"id":"atualizar-um-instrumento-financeiro","__idx":14},"children":["Atualizar um instrumento financeiro"]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["Use ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["PUT /v3/identities/{identity-id}/financial-instruments/{financial-instrument-id}"]}," para atualizar os campos editáveis de um instrumento financeiro existente."]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":[{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["Você pode:"]}]},{"$$mdtype":"Tag","name":"ul","attributes":{},"children":[{"$$mdtype":"Tag","name":"li","attributes":{},"children":["Atualizar metadados, como o label."]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":["Atualizar dados específicos do rail, como o número da conta ou a chave Pix."]}]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":[{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["Você não pode alterar:"]}]},{"$$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":"atualizações-parciais","__idx":15},"children":["Atualizações parciais"]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["A requisição aceita atualizações parciais:"]},{"$$mdtype":"Tag","name":"ul","attributes":{},"children":[{"$$mdtype":"Tag","name":"li","attributes":{},"children":["Os campos que você inclui são ",{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["sobrescritos"]},"."]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":["Os campos que você omite permanecem ",{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["inalterados"]},"."]}]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":3,"id":"exemplo-atualizar-apenas-o-label","__idx":16},"children":["Exemplo: atualizar apenas o 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":"resposta-200-ok-2","__idx":17},"children":["Resposta (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":"Resposta"},"children":[{"$$mdtype":"Tag","name":"p","attributes":{},"children":["A resposta da atualização retorna a ",{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["entrada do instrumento"]}," (metadados + timestamps), mas ",{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["não"]}," inclui o objeto específico do rail (como ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["usAch"]},")."]}]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":3,"id":"exemplo-atualizar-dados-específicos-do-rail-us-ach","__idx":18},"children":["Exemplo: atualizar dados específicos do rail (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  }'\n","lang":"bash"},"children":[]},{"$$mdtype":"Tag","name":"Admonition","attributes":{"type":"warning","name":"Erros"},"children":[{"$$mdtype":"Tag","name":"p","attributes":{},"children":["Se o payload da atualização for inválido (por exemplo, tipo de conta não compatível ou formato de roteamento inválido), a API retorna ",{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["400 Bad Request"]}," com os detalhes do erro."]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["Se a identidade ou o instrumento não for encontrado, a API retorna ",{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["404 Not Found"]},"."]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["Se houver um estado de recurso conflitante (por exemplo, atualização concorrente ou outra restrição interna), a API pode retornar ",{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["409 Conflict"]},"."]}]},{"$$mdtype":"Tag","name":"hr","attributes":{},"children":[]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":2,"id":"desativar-um-instrumento-financeiro","__idx":19},"children":["Desativar um instrumento financeiro"]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["Use ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["DELETE /v3/identities/{identity-id}/financial-instruments/{financial-instrument-id}"]}," para desativar um instrumento financeiro."]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":[{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["A desativação:"]}]},{"$$mdtype":"Tag","name":"ul","attributes":{},"children":[{"$$mdtype":"Tag","name":"li","attributes":{},"children":["É ",{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["permanente"]}," para aquele instrumento."]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":["Impede que o instrumento seja usado em ",{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["novos pagamentos"]},"."]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":["Mantém o histórico de uso e os dados para auditoria e conciliação."]}]},{"$$mdtype":"Tag","name":"Admonition","attributes":{"type":"warning","name":"Desativação de identidade"},"children":[{"$$mdtype":"Tag","name":"p","attributes":{},"children":["Desativar uma identidade (pelos endpoints de identidades) também desativa o instrumento financeiro dela."]}]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":3,"id":"exemplo-desativar-um-instrumento-financeiro","__idx":20},"children":["Exemplo: desativar um instrumento financeiro"]},{"$$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":"resposta-204-no-content","__idx":21},"children":["Resposta (204 No Content)"]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["Os seguintes erros podem ocorrer:"]},{"$$mdtype":"Tag","name":"ul","attributes":{},"children":[{"$$mdtype":"Tag","name":"li","attributes":{},"children":[{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["400 Bad Request"]}," – ID de identidade ou de instrumento malformado."]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":[{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["404 Not Found"]}," – a identidade ou o instrumento não existe."]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":[{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["409 Conflict"]}," – o instrumento já está desativado ou não pode ser desativado por causa do estado atual."]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":[{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["500 Internal Server Error"]}," – erro inesperado no servidor."]}]},{"$$mdtype":"Tag","name":"hr","attributes":{},"children":[]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":2,"id":"tratamento-de-erros","__idx":22},"children":["Tratamento de erros"]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["Todos os endpoints de instrumento financeiro usam o schema padrão de resposta de erro:"]},{"$$mdtype":"Tag","name":"ul","attributes":{},"children":[{"$$mdtype":"Tag","name":"li","attributes":{},"children":[{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["code"]}," – código de erro legível por máquina"]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":[{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["title"]}," – descrição curta"]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":[{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["description"]}," – explicação detalhada e sugestões de correção"]}]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["Cenários comuns:"]},{"$$mdtype":"Tag","name":"ul","attributes":{},"children":[{"$$mdtype":"Tag","name":"li","attributes":{},"children":[{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["400"]}," – erros de validação estrutural (campos obrigatórios ausentes, violações de padrão, valores de enum inválidos)."]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":[{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["404"]}," – identidade ou instrumento financeiro não encontrado."]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":[{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["409"]}," – estado conflitante (por exemplo, atualização ou desativação não permitida)."]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":[{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["500"]}," – erro interno de processamento; se persistir, entre em contato com o suporte da Ripple."]}]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["Consulte a ",{"$$mdtype":"Tag","name":"MarkdownLink","attributes":{"href":"/pt-br/products/payments-direct-2/api-docs/error-handling/api-errors"},"children":["referência de tratamento de erros"]}," na documentação da API para ver a lista completa de códigos de erro."]},{"$$mdtype":"Tag","name":"hr","attributes":{},"children":[]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":2,"id":"próximos-passos","__idx":23},"children":["Próximos passos"]},{"$$mdtype":"Tag","name":"ul","attributes":{},"children":[{"$$mdtype":"Tag","name":"li","attributes":{},"children":["Para entender como os instrumentos se encaixam na configuração geral de payout, consulte ",{"$$mdtype":"Tag","name":"MarkdownLink","attributes":{"href":"/pt-br/products/payments-direct-2/introduction/concepts/financial-instruments"},"children":["Instrumentos financeiros"]}," para pagamentos."]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":["Para revisar o modelo de KYC / PII ao qual os instrumentos se vinculam, consulte ",{"$$mdtype":"Tag","name":"MarkdownLink","attributes":{"href":"/pt-br/products/payments-direct-2/introduction/concepts/payment-identities"},"children":["Identidades do pagamento"]},"."]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":["Para ver como identidades e instrumentos financeiros são usados em conjunto no envio de dinheiro, continue com o tutorial ",{"$$mdtype":"Tag","name":"MarkdownLink","attributes":{"href":"/pt-br/products/payments-direct-2/api-docs/developer-guides/create-a-payment"},"children":["Criar um pagamento"]},"."]}]}]},"headings":[{"value":"Criar e gerenciar instrumentos financeiros","id":"criar-e-gerenciar-instrumentos-financeiros","depth":1},{"value":"Antes de começar","id":"antes-de-começar","depth":2},{"value":"Criar um instrumento financeiro","id":"criar-um-instrumento-financeiro","depth":2},{"value":"Exemplo: criar uma conta bancária US ACH","id":"exemplo-criar-uma-conta-bancária-us-ach","depth":3},{"value":"Resposta (201 Created)","id":"resposta-201-created","depth":3},{"value":"Exemplo: criar uma conta bancária MX SPEI para a mesma identidade","id":"exemplo-criar-uma-conta-bancária-mx-spei-para-a-mesma-identidade","depth":3},{"value":"Exemplo: criar um instrumento financeiro de payout bancário na Nigéria","id":"exemplo-criar-um-instrumento-financeiro-de-payout-bancário-na-nigéria","depth":3},{"value":"Validação de identidade e validatePayoutRails","id":"validação-de-identidade-e-validatepayoutrails","depth":3},{"value":"Listar os instrumentos financeiros de uma identidade","id":"listar-os-instrumentos-financeiros-de-uma-identidade","depth":2},{"value":"Exemplo: listar os instrumentos de uma identidade","id":"exemplo-listar-os-instrumentos-de-uma-identidade","depth":3},{"value":"Resposta (200 OK)","id":"resposta-200-ok","depth":3},{"value":"Obter um instrumento financeiro por ID","id":"obter-um-instrumento-financeiro-por-id","depth":2},{"value":"Exemplo: obter um instrumento financeiro US ACH","id":"exemplo-obter-um-instrumento-financeiro-us-ach","depth":3},{"value":"Resposta (200 OK)","id":"resposta-200-ok-1","depth":3},{"value":"Atualizar um instrumento financeiro","id":"atualizar-um-instrumento-financeiro","depth":2},{"value":"Atualizações parciais","id":"atualizações-parciais","depth":3},{"value":"Exemplo: atualizar apenas o label","id":"exemplo-atualizar-apenas-o-label","depth":3},{"value":"Resposta (200 OK)","id":"resposta-200-ok-2","depth":3},{"value":"Exemplo: atualizar dados específicos do rail (US ACH)","id":"exemplo-atualizar-dados-específicos-do-rail-us-ach","depth":3},{"value":"Desativar um instrumento financeiro","id":"desativar-um-instrumento-financeiro","depth":2},{"value":"Exemplo: desativar um instrumento financeiro","id":"exemplo-desativar-um-instrumento-financeiro","depth":3},{"value":"Resposta (204 No Content)","id":"resposta-204-no-content","depth":3},{"value":"Tratamento de erros","id":"tratamento-de-erros","depth":2},{"value":"Próximos passos","id":"próximos-passos","depth":2}],"frontmatter":{"title":"Criar e gerenciar instrumentos financeiros","toc":{"enable":true,"maxDepth":2},"seo":{"title":"Criar e gerenciar instrumentos financeiros"}},"lastModified":"2026-10-21T04:11:32.000Z","pagePropGetterError":{"message":"","name":""}},"slug":"/pt-br/products/payments-direct-2/api-docs/developer-guides/create-and-manage-financial-instruments","userData":{"isAuthenticated":false,"teams":["anonymous"]},"isPublic":true}