Criar e gerenciar instrumentos financeiros

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 para pagamentos e Identidades do pagamento.

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
• <access_token> por um token de acesso válido
• {identity-id} e {financial-instrument-id} por IDs reais do seu ambiente

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

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"
    }
  }'

{
  "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

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"
    }
  }'

Agora a mesma identidade tem dois instrumentos financeiros (um US ACH e um MX SPEI).

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

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á:

{
  "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.

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.

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

{
  "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.

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.

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

{
  "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"
  }
}

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

A requisição aceita atualizações parciais:

• Os campos que você inclui são sobrescritos.
• Os campos que você omite permanecem inalterados.

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)"
  }'

{
  "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"
}

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"
    }
  }'

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.

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

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.

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 na documentação da API para ver a lista completa de códigos de erro.

• Para entender como os instrumentos se encaixam na configuração geral de payout, consulte Instrumentos financeiros para pagamentos.
• Para revisar o modelo de KYC / PII ao qual os instrumentos se vinculam, consulte Identidades do pagamento.
• Para ver como identidades e instrumentos financeiros são usados em conjunto no envio de dinheiro, continue com o tutorial Criar um pagamento.