Instrumentos financeiros

Um instrumento financeiro representa os dados da conta ou da carteira usados para enviar ou receber fundos em um pagamento. Enquanto uma identidade do pagamento descreve quem é a parte, um instrumento financeiro descreve para onde o dinheiro vai — por exemplo, uma conta bancária US ACH, um IBAN SEPA, uma chave PIX ou um payment rail bancário local.

Os instrumentos financeiros são gerenciados pelo Identity Management v3 e estão sempre associados a uma identidade específica. Cada instrumento especifica um payment rail (como US_ACH, EU_SEPA, MX_SPEI, BR_PIX), uma moeda e um payload específico do rail (códigos de roteamento, números de conta, IBANs, CLABE, chaves PIX e assim por diante).

O Identity Management v3 separa identidades e instrumentos para que você possa:

• Manter uma identidade com KYC por parte, independentemente dos dados da conta.
• Reutilizar essa identidade em vários pagamentos sem reenviar PII.
• Alternar ou substituir a conta de uma parte sem recriar a identidade nem perder o histórico.

Neste tópico, você vai aprender:

• Como os instrumentos financeiros se relacionam com as identidades do pagamento e com o fluxo de pagamento como um todo.
• Quais campos de metadados se aplicam a todos os instrumentos financeiros (como financialInstrumentType, currency, country e label).
• Como são os objetos específicos de rail para os payment rails mais comuns (por exemplo, usAch, euSepa, mxSpei, gbFps, brPix).
• Quantos instrumentos financeiros uma identidade pode ter e como substituir um instrumento quando a conta de uma parte muda.
• Como pensar nas regras de validação, na cobertura de corredores e nas boas práticas ao modelar contas bancárias e métodos de pagamento.

Os instrumentos financeiros têm escopo de identidade:

• Cada instrumento financeiro pertence a exatamente uma identidade.
• O instrumento não armazena dados pessoais; ele armazena apenas dados de conta ou carteira.
• O paymentRole da identidade (ORIGINATOR ou BENEFICIARY) determina se o instrumento é usado para financiar ou para receber pagamentos.

Ao montar pagamentos:

• O objeto de pagamento referencia a identidade e o instrumento financeiro por ID.
• A camada de orquestração de pagamentos usa o financialInstrumentType para determinar qual payment rail utilizar (por exemplo, US_ACH, MX_SPEI).
• Regras específicas de corredor garantem que o tipo de instrumento, a moeda e o corredor sejam compatíveis.

Para detalhes sobre o modelo de identidade, consulte Identidades do pagamento.

Em alto nível, um instrumento financeiro é composto por:

1. Metadados que descrevem o instrumento (type, currency, label etc.).
2. Um único objeto específico de rail (por exemplo, usAch, mxSpei, euSepa) que contém os campos de conta exigidos por esse rail.

Forma conceitual:

{
  "financialInstrumentId": "3fc74743-e7f3-414a-9fcf-eb8c1d52356a",
  "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",

  // um objeto específico de rail, dependendo do financialInstrumentType
  "usAch": {
    "bankName": "Bank of Example",
    "bankRoutingNumber": "266231608",
    "accountNumber": "60480",
    "accountType": "CHECKING"
  }
}

Os campos a seguir se aplicam a todos os instrumentos financeiros, independentemente do rail.

No Identity Management v3, cada identidade admite um instrumento financeiro ativo. Adicionar um segundo instrumento a uma identidade que já tem um falha com 422 Unprocessable Entity e o código de erro USR_120 (Maximum financial instruments reached).

O suporte a vários instrumentos financeiros por identidade está previsto para uma versão futura. Ele não está disponível hoje e não pode ser habilitado sob solicitação.

Identidade vs. instrumento financeiro

• A identidade descreve quem você está pagando ou de quem você está recebendo:
  • identityType (INDIVIDUAL ou BUSINESS)
  • paymentRole (ORIGINATOR ou BENEFICIARY)
  • Campos de PII como nomes, endereços, documentos de registro e dados de contato.
• O instrumento financeiro descreve como e para onde os fundos são entregues:
  • financialInstrumentType (por exemplo, US_ACH, EU_SEPA, MX_SPEI, BR_PIX)
  • currency e country
  • Campos específicos de rail como números de roteamento, IBANs, CLABE, chaves PIX e assim por diante.

Cada instrumento financeiro é gerenciado como um recurso filho de uma identidade:

1. Criar uma identidade
   Use POST /v3/identities para criar a identidade com a sua PII e o seu internalId.
   
   
2. Adicionar um instrumento financeiro
   Use POST /v3/identities/{identity-id}/financial-instruments para vincular uma conta bancária ou um método de pagamento a essa identidade.
   
   Você especifica:
   • financialInstrumentType
   • currency
   • O objeto de rail correspondente (por exemplo, usAch, euSepa, mxSpei, brPix) com os seus campos obrigatórios.
     
     
3. Listar os instrumentos de uma identidade
   Use GET /v3/identities/{identity-id}/financial-instruments para ver todos os instrumentos vinculados a uma identidade. A resposta retorna uma lista de instrumentos com os metadados (IDs, tipos, moedas, rótulos, timestamps).
   
   
4. Obter os detalhes de um único instrumento
   Use GET /v3/identities/{identity-id}/financial-instruments/{financial-instrument-id} para recuperar os detalhes completos específicos do rail, como números de conta e códigos de roteamento.
   
   
5. Atualizar ou desativar instrumentos
   • Use PUT para atualizar os campos editáveis (por exemplo, alterar um rótulo ou atualizar um número de conta bancária quando permitido).
   • Use DELETE para desativar um instrumento, de modo que ele não possa mais ser usado em novos pagamentos. O uso histórico permanece disponível para auditoria.

Se um beneficiário mudar de conta bancária, mantenha a identidade e substitua o instrumento. Como uma identidade tem um instrumento por vez, a ordem importa:

1. Desative o instrumento existente
   Use DELETE /v3/identities/{identity-id}/financial-instruments/{financial-instrument-id}. Isso libera o espaço de instrumento da identidade. O uso histórico do instrumento desativado permanece disponível para auditoria.
   
   
2. Adicione o instrumento substituto
   Use POST /v3/identities/{identity-id}/financial-instruments.

Adicionar o novo instrumento primeiro falha com 422 Unprocessable Entity (USR_120), porque a identidade ainda tem o antigo.

Para corrigir os dados de uma conta que o beneficiário vai manter, use PUT em vez de substituir o instrumento. O PUT atualiza o label e os campos específicos de rail, como o número da conta, mas não pode alterar o financialInstrumentType nem a currency. Alterar o rail ou a moeda exige desativar o instrumento e adicionar um novo.

• Use o campo label dos instrumentos financeiros para facilitar a distinção entre contas (por exemplo, "operating-USD", "payroll-EUR", "MXN-SPEI-local").
• Mantenha uma identidade por parte do mundo real sempre que possível e substitua o instrumento dessa identidade quando a conta da parte mudar. Crie uma segunda identidade apenas quando uma parte precisar de duas contas ativas ao mesmo tempo.
• Use as tags no nível da identidade para expressar a segmentação de negócio (por exemplo, ["vendor-emea", "high-value"]) e trate os detalhes específicos de conta no nível do instrumento financeiro.

O financialInstrumentType determina qual objeto específico de rail é preenchido e quais campos são obrigatórios.

Esta seção resume os principais campos de cada instrumento baseado em conta bancária.

Os dados do instrumento financeiro são validados de duas formas:

1. Validação estrutural
   • O Identity Management v3 garante que os campos obrigatórios do financialInstrumentType especificado estejam presentes.
   • Os padrões de campo (comprimento, conjuntos de caracteres, formatos de IBAN/CLABE, formatos de roteamento e assim por diante) são aplicados.
2. Compatibilidade de corredor
   • Apenas certas combinações de tipo de instrumento, moeda e corredor de pagamento são compatíveis.
   • Se um instrumento não puder ser usado em nenhum corredor para o qual você esteja habilitado, a criação ou as atualizações podem falhar.

Ao criar um instrumento financeiro, a identidade associada precisa ter toda a PII exigida pelo financialInstrumentType especificado. Você pode usar o campo validatePayoutRails na identidade para validar os requisitos de PII antecipadamente:

• Se você especificou o validatePayoutRails ao criar a identidade (por exemplo, ["US_ACH", "MX_SPEI"]), a PII da identidade já foi validada em relação a esses rails.
• Quando você cria um instrumento financeiro com um financialInstrumentType correspondente (por exemplo, US_ACH), a criação do instrumento é bem-sucedida imediatamente, porque a identidade já está validada.
• Se você criar um instrumento financeiro para um rail não listado no validatePayoutRails, a PII da identidade é validada no momento da criação do instrumento. Se faltarem campos obrigatórios, a requisição falha com 400 Bad Request.

• Para saber como criar, atualizar, listar e desativar instrumentos financeiros por meio da API, continue com Criar e gerenciar instrumentos financeiros.
• Para revisar como os dados da conta se conectam aos dados de KYC e a papéis de pagamento específicos, consulte Identidades do pagamento.