# Criar e gerenciar instrumentos financeiros Identity Management v3 Este tópico descreve o modelo de identidade v3. O **Identity Management v3** é recomendado para todas as novas integrações. Para conhecer os corredores de pagamento compatíveis, consulte [Payout network](/pt-br/products/payments-direct-2/introduction/payout-network). Este tutorial mostra como usar os endpoints de instrumento financeiro do **Identity Management v3** para: - Criar um instrumento financeiro para uma identidade - Listar os instrumentos financeiros de uma identidade - Recuperar um instrumento financeiro por ID - Atualizar os dados de um instrumento financeiro - Desativar um instrumento financeiro Ele pressupõe que você já leu [Instrumentos financeiros](/pt-br/products/payments-direct-2/introduction/concepts/financial-instruments) para pagamentos e [Identidades do pagamento](/pt-br/products/payments-direct-2/introduction/concepts/payment-identities). Um instrumento por identidade No Identity Management v3, uma identidade tem **um instrumento financeiro ativo**. Adicionar um segundo instrumento à mesma identidade falha com **422 Unprocessable Entity** (`USR_120`). Para trocar a conta de uma parte, desative o instrumento existente e depois adicione o substituto. O suporte a vários instrumentos por identidade está previsto para uma versão futura. Para mais detalhes, consulte [Um instrumento financeiro por identidade](/pt-br/products/payments-direct-2/introduction/concepts/financial-instruments#um-instrumento-financeiro-por-identidade). ## Antes de começar Para seguir estes exemplos, você precisa de: - URL base da API do Payments Direct (por exemplo,` https://{base-url}`) - Um token de acesso OAuth2 válido com os escopos: - `participants:create` – criar instrumentos financeiros - `participants:read` – listar e obter instrumentos financeiros - `participants:update` – atualizar e desativar instrumentos financeiros - Um `identityId` existente (criado pelos endpoints de identidades) Em todos os exemplos, substitua: - `{base-url}` pela sua URL base de PII - `` por um token de acesso válido - `{identity-id} `e `{financial-instrument-id}` por IDs reais do seu ambiente ## Criar um instrumento financeiro Use `POST /v3/identities/{identity-id}/financial-instruments` para criar um instrumento financeiro para uma identidade existente. Você precisa informar: - `financialInstrumentType` – o rail, como `US_ACH`, `MX_SPEI`,` BR_PIX` - `currency` – código de moeda ISO 4217 (por exemplo, `USD`, `MXN`, `BRL`) - Exatamente um objeto específico do rail (por exemplo, `usAch`, `mxSpei`, `brPix`) com os dados obrigatórios da conta - Metadados opcionais, como `label` ### Exemplo: criar uma conta bancária US ACH ```bash curl -X POST "https://{base-url}/v3/identities/{identity-id}/financial-instruments" \ -H "Authorization: Bearer " \ -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" } }' ``` ### Resposta (201 Created) ```json { "financialInstrumentId": "2f4ac57f-c5ba-4051-b51f-b3565778717b" } ``` Você usará este `financialInstrumentId` ao: - Obter o instrumento por ID - Atualizar ou desativar o instrumento - Referenciá-lo nos fluxos de criação de pagamento ### Exemplo: criar uma conta bancária MX SPEI para a mesma identidade ```bash curl -X POST "https://{base-url}/v3/identities/{identity-id}/financial-instruments" \ -H "Authorization: Bearer " \ -H "Content-Type: application/json" \ -d '{ "financialInstrumentType": "MX_SPEI", "currency": "MXN", "label": "MXN SPEI account", "mxSpei": { "bankName": "Banco Ejemplo", "clabe": "032180000118359719" } }' ``` Agora a mesma identidade tem **dois instrumentos financeiros** (um US ACH e um MX SPEI). ### Exemplo: criar um instrumento financeiro de payout bancário na Nigéria ```bash curl -X POST "https://{base-url}/v3/identities/{identity-id}/financial-instruments" \ -H "Authorization: Bearer " \ -H "Content-Type: application/json" \ -d '{ "financialInstrumentType": "NG_BANK_PAYOUT", "currency": "NGN", "label": "NGN bank account", "ngBankPayout": { "bankName": "Guaranty Trust Bank PLC", "bankCode": "RPL:NG:GTBINGLA:BNK", "accountNumber": "0123456789", "country": "NG" } }' ``` Códigos bancários O campo `bankCode` exige um Ripple Bank Code (RBC), não o código interno do próprio banco. Use a [consulta de códigos bancários](/pt-br/products/payments-direct-2/api-docs/integration-resources/ripple-bank-codes) para localizar o RBC correto do banco de destino antes de criar o instrumento. Campos ausentes ou inválidos 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 **400 Bad Request** com detalhes sobre os campos que falharam. Se o `identity-id` não existir, a API retorna **404 Not Found**. ### Validação de identidade e `validatePayoutRails` Ao criar um instrumento financeiro, a identidade associada precisa ter todos os dados de PII exigidos para o `financialInstrumentType` especificado. **Se a identidade foi criada com `validatePayoutRails`:** - Os dados de PII da identidade já foram validados contra os payment rails especificados no momento da criação da identidade. - Criar um instrumento financeiro para um rail listado em `validatePayoutRails` é bem-sucedido imediatamente (desde que a identidade tenha os dados de PII exigidos). - Criar um instrumento financeiro para um rail **não** listado em `validatePayoutRails` dispara a validação no momento da criação do instrumento. Se faltarem dados de PII obrigatórios, a requisição falha com **400 Bad Request**. **Se a identidade foi criada sem `validatePayoutRails`:** - Os dados de PII da identidade são validados quando você cria o instrumento financeiro. - Se faltarem campos obrigatórios para o `financialInstrumentType` especificado, a requisição falha com **400 Bad Request** e detalhes sobre quais campos estão ausentes. **Exemplo: falha de validação por PII ausente** Se você tentar criar um instrumento financeiro `US_ACH` para uma identidade sem campos obrigatórios como `identityDocuments`, receberá: ```json { "code": "VALIDATION_ERROR", "title": "Identity validation failed", "description": "The identity is missing required fields for the specified financial instrument type.", "details": [ { "field": "individual.identityDocuments", "message": "At least one identity document (SSN or Tax ID) is required for US_ACH beneficiary identities" } ] } ``` Para corrigir isso, atualize a identidade com os campos de PII ausentes usando `PUT /v3/identities/{identity-id}` e tente criar o instrumento financeiro novamente. Tipos de documento não compatíveis 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 `idType` (pessoa física) ou `registration.type` (empresa), portanto uma requisição de instrumento pode falhar com **400 Bad Request** mesmo quando todos os campos obrigatórios estão presentes. Para ver os valores aceitos por corredor e papel, consulte [Tipos de documento aceitos por corredor](/pt-br/products/payments-direct-2/introduction/concepts/payment-identities#tipos-de-documento-aceitos-por-corredor). Validação antecipada Usar `validatePayoutRails` ao criar identidades ajuda a detectar problemas de PII com antecedência, antes de você tentar criar instrumentos financeiros. Para mais detalhes, consulte [Validando identidades para payment rails específicos](/pt-br/products/payments-direct-2/introduction/concepts/payment-identities#validando-identidades-para-payment-rails-espec%C3%ADficos). ## Listar os instrumentos financeiros de uma identidade Use `GET /v3/identities/{identity-id}/financial-instruments` para listar os instrumentos financeiros de uma identidade. Parâmetros de consulta: - `version` – versão opcional da identidade. Se omitido, a versão mais recente da identidade é usada. - `limit` – número máximo de instrumentos a retornar (de 1 a 100, padrão 10). - `next-token` – token de paginação de uma resposta anterior. ### Exemplo: listar os instrumentos de uma identidade ```bash curl -X GET "https://{base-url}/v3/identities/{identity-id}/financial-instruments?limit=10" \ -H "Authorization: Bearer " ``` ### Resposta (200 OK) ```json { "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" } ] } ``` - Como uma identidade tem um instrumento financeiro ativo, o array `data` contém no máximo uma entrada. Ele fica vazio se o instrumento da identidade foi desativado e não substituído. - Apenas os metadados são retornados; os objetos específicos do rail (como `usAch` ou `mxSpei`) não são incluídos. - Os parâmetros `limit` e `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 `nextToken`. Se a identidade ou os instrumentos não forem encontrados, a API retorna **404 Not Found**. ## Obter um instrumento financeiro por ID Use `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. ### Exemplo: obter um instrumento financeiro US ACH ```bash curl -X GET "https://{base-url}/v3/identities/{identity-id}/financial-instruments/{financial-instrument-id}" \ -H "Authorization: Bearer " ``` ### Resposta (200 OK) ```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": { "bankName": "Bank of Example", "bankRoutingNumber": "266231608", "accountNumber": "60480", "accountType": "CHECKING" }, "currency": "USD", "label": "US bank account", "financialInstrumentType": "US_ACH" } } ``` Erros Se o `identity-id` ou o `financial-instrument-id` for inválido ou não existir, a API retorna **400** ou **404**, respectivamente. ## Atualizar um instrumento financeiro Use `PUT /v3/identities/{identity-id}/financial-instruments/{financial-instrument-id}` para atualizar os campos editáveis de um instrumento financeiro existente. **Você pode:** - Atualizar metadados, como o label. - Atualizar dados específicos do rail, como o número da conta ou a chave Pix. **Você não pode alterar:** - `financialInstrumentType` - `currency` ### Atualizações parciais A requisição aceita atualizações parciais: - Os campos que você inclui são **sobrescritos**. - Os campos que você omite permanecem **inalterados**. ### Exemplo: atualizar apenas o label ```bash curl -X PUT "https://{base-url}/v3/identities/{identity-id}/financial-instruments/{financial-instrument-id}" \ -H "Authorization: Bearer " \ -H "Content-Type: application/json" \ -d '{ "label": "US bank account (primary)" }' ``` ### Resposta (200 OK) ```json { "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" } ``` Resposta A resposta da atualização retorna a **entrada do instrumento** (metadados + timestamps), mas **não** inclui o objeto específico do rail (como `usAch`). ### Exemplo: atualizar dados específicos do rail (US ACH) ```bash curl -X PUT "https://{base-url}/v3/identities/{identity-id}/financial-instruments/{financial-instrument-id}" \ -H "Authorization: Bearer " \ -H "Content-Type: application/json" \ -d '{ "usAch": { "bankName": "Bank of Example", "bankRoutingNumber": "266231608", "accountNumber": "987654321", "accountType": "CHECKING" } }' ``` Erros 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 **400 Bad Request** com os detalhes do erro. Se a identidade ou o instrumento não for encontrado, a API retorna **404 Not Found**. Se houver um estado de recurso conflitante (por exemplo, atualização concorrente ou outra restrição interna), a API pode retornar **409 Conflict**. ## Desativar um instrumento financeiro Use `DELETE /v3/identities/{identity-id}/financial-instruments/{financial-instrument-id}` para desativar um instrumento financeiro. **A desativação:** - É **permanente** para aquele instrumento. - Impede que o instrumento seja usado em **novos pagamentos**. - Mantém o histórico de uso e os dados para auditoria e conciliação. Desativação de identidade Desativar uma identidade (pelos endpoints de identidades) também desativa o instrumento financeiro dela. ### Exemplo: desativar um instrumento financeiro ```bash curl -X DELETE "https://{base-url}/v3/identities/{identity-id}/financial-instruments/{financial-instrument-id}" \ -H "Authorization: Bearer " ``` ### Resposta (204 No Content) Os seguintes erros podem ocorrer: - **400 Bad Request** – ID de identidade ou de instrumento malformado. - **404 Not Found** – a identidade ou o instrumento não existe. - **409 Conflict** – o instrumento já está desativado ou não pode ser desativado por causa do estado atual. - **500 Internal Server Error** – erro inesperado no servidor. ## Tratamento de erros Todos os endpoints de instrumento financeiro usam o schema padrão de resposta de erro: - **code** – código de erro legível por máquina - **title** – descrição curta - **description** – explicação detalhada e sugestões de correção Cenários comuns: - **400** – erros de validação estrutural (campos obrigatórios ausentes, violações de padrão, valores de enum inválidos). - **404** – identidade ou instrumento financeiro não encontrado. - **409** – estado conflitante (por exemplo, atualização ou desativação não permitida). - **500** – erro interno de processamento; se persistir, entre em contato com o suporte da Ripple. Consulte a [referência de tratamento de erros](/pt-br/products/payments-direct-2/api-docs/error-handling/api-errors) na documentação da API para ver a lista completa de códigos de erro. ## Próximos passos - Para entender como os instrumentos se encaixam na configuração geral de payout, consulte [Instrumentos financeiros](/pt-br/products/payments-direct-2/introduction/concepts/financial-instruments) para pagamentos. - Para revisar o modelo de KYC / PII ao qual os instrumentos se vinculam, consulte [Identidades do pagamento](/pt-br/products/payments-direct-2/introduction/concepts/payment-identities). - Para ver como identidades e instrumentos financeiros são usados em conjunto no envio de dinheiro, continue com o tutorial [Criar um pagamento](/pt-br/products/payments-direct-2/api-docs/developer-guides/create-a-payment).