# 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).

Para detalhes ou dúvidas sobre migração, entre em contato com o seu representante Ripple.

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.


Um instrumento por identidade
Cada identidade admite **um instrumento financeiro ativo**. Consulte [Um instrumento financeiro por identidade](#um-instrumento-financeiro-por-identidade).

## O que você vai aprender

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.


## Relação entre identidades, instrumentos e pagamentos

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](/pt-br/products/payments-direct-2/introduction/concepts/payment-identities).

## Estrutura do instrumento financeiro

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

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

Um rail por instrumento
Apenas um dos objetos específicos de rail (`usAch`, `mxSpei`, `euSepa` e assim por diante) é preenchido em um determinado instrumento.

## Metadados do instrumento financeiro

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

| Campo | Tipo | Obrigatório | Descrição | Exemplo |
|  --- | --- | --- | --- | --- |
| **financialInstrumentId** | string | Sim | Identificador único do instrumento financeiro gerado pelo servidor. Estável em todas as versões. | "3fc74743-e7f3-414a-9fcf-eb8c1d52356a" |
| **financialInstrumentType** | string | Sim | Payment rail usado por este instrumento. Consulte [Tipos de instrumento financeiro](#tipos-de-instrumento-financeiro) para ver todos os valores compatíveis. | "US_ACH" |
| **currency** | string | Sim | Código de moeda ISO 4217 do instrumento (por exemplo, `USD`, `EUR`, `MXN`). Deve ser compatível com o rail e o corredor escolhidos. | "USD" |
| **label** | string | Não | Rótulo definido pelo usuário para ajudar os seus sistemas a distinguir instrumentos (por exemplo, por região ou por uso). | "US bank account" |
| **country** | string | Não | Código do país (ISO 3166-1 alfa-2) onde o instrumento é mantido ou usado. Retorna `ZZ` para instrumentos de carteira de criptomoedas (ETH_WALLET, TRON_WALLET, SOL_WALLET). | "US" |
| **createdAt** | string | Sim | Timestamp RFC 3339 de quando o instrumento foi criado. | "2023-11-02T18:26:00.000Z" |
| **updatedAt** | string | Sim | Timestamp RFC 3339 de quando o instrumento foi atualizado pela última vez. | "2023-11-03T18:26:00.000Z" |


Apenas metadados na listagem
Ao listar instrumentos, a API retorna **apenas os metadados** (sem os campos específicos de rail) de cada instrumento.

Para ver os detalhes completos específicos do rail, recupere o instrumento por ID.

## Um instrumento financeiro por identidade

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.


Reutilizando identidades
Ao separar esses dois conceitos, você mantém um único registro de KYC por parte. A identidade é reutilizada em vários pagamentos, e o instrumento financeiro dela pode ser substituído ao longo do tempo sem recriar a identidade nem reenviar PII.

Se uma parte precisar de duas contas ao mesmo tempo
Como uma identidade tem um instrumento por vez, uma parte que precise receber pagamentos em duas contas diferentes simultaneamente (por exemplo, uma conta MXN SPEI e uma conta USD ACH) exige atualmente uma **identidade separada para cada conta**.

Cada identidade precisa do seu próprio `internalId` único. Reutilizar um `internalId` que pertence a uma identidade ativa falha com **409 Conflict**.

## Ciclo de vida e fluxo de trabalho da API

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.


Desativação
Desativar uma identidade também desativa os instrumentos financeiros dela e impede que sejam usados em novos pagamentos.

### Substituindo a conta de um beneficiário

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.

### Boas práticas

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


## Tipos de instrumento financeiro

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

| Tipo | Descrição | Uso típico | Moeda comum |
|  --- | --- | --- | --- |
| US_ACH | Rail doméstico dos EUA com RTP como principal. Roteia primeiro pelo RTP e recorre ao ACH quando o número de roteamento do beneficiário não está habilitado para RTP. | Transferências bancárias domésticas nos EUA em USD. | "USD" |
| US_FEDWIRE | Sistema de liquidação bruta em tempo real Fedwire dos EUA, para transferências domésticas de alto valor. | Transferências bancárias domésticas de alto valor em USD. | "USD" |
| MX_SPEI | Sistema de transferência interbancária em tempo real do México (SPEI). | Pagamentos bancários domésticos no México em MXN. | "MXN" |
| EU_SEPA | Rails de transferência a crédito SEPA para pagamentos denominados em EUR nos países da zona SEPA. | Pagamentos bancários em EUR para contas da região SEPA (IBAN). | "EUR" |
| GB_FPS | Faster Payments Service e CHAPS do Reino Unido. | Pagamentos em GBP para contas bancárias do Reino Unido. | "GBP" |
| CA_EFT | Sistema de transferência eletrônica de fundos do Canadá. | Pagamentos em CAD para contas bancárias canadenses. | "CAD" |
| NG_BANK_PAYOUT | Payment rail bancário da Nigéria. | Pagamentos em NGN para contas bancárias nigerianas. | "NGN" |
| BR_PIX | Plataforma de pagamentos instantâneos do Brasil (PIX), operada pelo Banco Central do Brasil. | Pagamentos em BRL para contas PIX usando chaves PIX. | "BRL" |
| CO_PSE | Sistema de pagamento seguro por internet banking da Colômbia (PSE). | Pagamentos em COP para contas bancárias colombianas via PSE. | "COP" |
| BR_TED | Sistema de Transferência Eletrônica Disponível (TED) do Brasil, para transações de maior valor. | Pagamentos em BRL para contas bancárias brasileiras via TED. | "BRL" |
| GH_BANK_PAYOUT | Payment rail bancário de Gana via GIS. | Pagamentos em GHS para contas bancárias ganesas. | "GHS" |
| RW_BANK_PAYOUT | Payment rail bancário de Ruanda via RSwitch. | Pagamentos em RWF para contas bancárias ruandesas. | "RWF" |
| ZA_BANK_PAYOUT | Payment rail bancário da África do Sul via PayShap. | Pagamentos em ZAR para contas bancárias sul-africanas. | "ZAR" |
| UG_BANK_PAYOUT | Payment rail bancário de Uganda. | Pagamentos em UGX para contas bancárias ugandenses. | "UGX" |
| ZM_BANK_PAYOUT | Payment rail bancário da Zâmbia via ZECHL. | Pagamentos em ZMW para contas bancárias zambianas. | "ZMW" |
| AE_IPI | Instant Payment Interface dos Emirados Árabes Unidos, para transações em tempo real. | Pagamentos em AED para contas bancárias dos Emirados via IPI, com o FTS como alternativa para transferências maiores. | "AED" |
| IN_NEFT | National Electronic Funds Transfer da Índia: pagamento bancário para transferências denominadas em INR usando códigos de roteamento IFSC. | Pagamentos em INR para contas bancárias indianas via NEFT. | "INR" |
| CL_TEF | TEF do Chile (Transferencia Electrónica de Fondos): sistema de transferência doméstica em dia útil para pagamentos denominados em CLP. | Pagamentos em CLP para contas bancárias chilenas via TEF. | "CLP" |
| JP_ZENGIN | Zengin do Japão: sistema de compensação doméstica multi-rail (Zengin + Zengin Prompt Service) para pagamentos denominados em JPY. | Pagamentos em JPY para contas bancárias japonesas via Zengin, com o Zengin Prompt Service para transferências de baixo valor em tempo real. | "JPY" |
| TH_PROMPTPAY | PromptPay da Tailândia: o sistema nacional de pagamentos de varejo em tempo real do país, para transferências bancárias domésticas em THB. | Pagamentos em THB para contas bancárias tailandesas via PromptPay. | "THB" |
| KR_KFTC | KFTC da Coreia do Sul: payment rail em tempo real 24/7 via Korea Financial Telecommunications and Clearings, para pagamentos denominados em KRW. | Pagamentos em KRW para contas bancárias sul-coreanas via KFTC. | "KRW" |
| AU_NPP | New Payments Platform da Austrália: payment rail em tempo real para transferências domésticas denominadas em AUD, com o Direct Entry (BECS) como alternativa para alto valor e lotes. | Pagamentos em AUD para contas bancárias australianas via NPP, com o Direct Entry (BECS) como alternativa para alto valor e lotes. | "AUD" |
| CN_CFXPS | China Foreign Exchange Payment System (CFXPS). | Pagamentos em USD para contas bancárias chinesas via CFXPS. | "USD" |
| PE_LBTR | LBTR do Peru (Liquidación Bruta en Tiempo Real): sistema de liquidação em tempo real para pagamentos denominados em PEN. | Pagamentos em PEN para contas bancárias peruanas via LBTR. | "PEN" |
| AR_INTERBANKING | Interbanking da Argentina: sistema de transferência doméstica baseado em CBU/CVU para pagamentos denominados em ARS. | Pagamentos em ARS para contas bancárias argentinas via Interbanking. | "ARS" |
| ETH_WALLET | Carteira da rede Ethereum para pagamentos em stablecoin (USDT, USDC, RLUSD). | Pagamentos em cripto para endereços de carteira Ethereum. | "USDT / USDC / RLUSD" |
| TRON_WALLET | Carteira da rede Tron para pagamentos em USDT. | Pagamentos em USDT para endereços de carteira Tron. | "USDT" |
| SOL_WALLET | Carteira da rede Solana para pagamentos em USDC. | Pagamentos em USDC para endereços de carteira Solana. | "USDC" |


Cobertura de corredores
Cada tipo de instrumento é compatível apenas com corredores país–moeda específicos.

Para ver a cobertura completa de corredores, consulte [Payout network](/pt-br/products/payments-direct-2/introduction/payout-network).

## Rails de conta bancária e campos

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

US_ACH
O objeto `usAch` é usado quando o `financialInstrumentType` é `US_ACH`.

| Campo | Tipo | Obrigatório | Descrição | Exemplo |
|  --- | --- | --- | --- | --- |
| bankName | string | Sim | Nome do banco onde a conta é mantida. | "Bank of Example" |
| bankRoutingNumber | string | Sim | Número de roteamento de 9 dígitos (ABA Routing Transit Number). | "266231608" |
| accountNumber | string | Sim | Número da conta a ser creditada. | "60480" |
| accountType | string | Sim | Tipo de conta bancária. Os valores incluem CHECKING e SAVINGS. | "CHECKING" |


Observações de uso
- A `currency` normalmente é `USD`.
- O `US_ACH` roteia primeiro pelo RTP e recorre ao ACH quando o número de roteamento do beneficiário não está habilitado para RTP. O nome reflete a terminologia de números de roteamento dos EUA (os números de roteamento ACH são reaproveitados no RTP).


US_FEDWIRE
O objeto `usFedwire` é usado quando o `financialInstrumentType` é `US_FEDWIRE`.

| Campo | Tipo | Obrigatório | Descrição | Exemplo |
|  --- | --- | --- | --- | --- |
| bankName | string | Sim | Nome do banco onde os fundos serão creditados. | "Bank of Example" |
| bankRoutingNumber | string | Sim | Número de roteamento ABA de 9 dígitos do banco do beneficiário. | "266231608" |
| accountNumber | string | Sim | Número da conta a ser creditada (destino Fedwire de alto valor). | "60480" |


Observações de uso
- A `currency` normalmente é `USD`.
- Destinado a transferências domésticas nos EUA de alto valor ou sensíveis ao tempo.


MX_SPEI
O objeto `mxSpei` é usado quando o `financialInstrumentType` é `MX_SPEI`.

| Campo | Tipo | Obrigatório | Descrição | Exemplo |
|  --- | --- | --- | --- | --- |
| bankName | string | Sim | Nome do banco mexicano. | "Bank of Example" |
| clabe | string | Sim | Identificador de conta CLABE de 18 dígitos do beneficiário. | "014027000005555558" |


Observações de uso
- A `currency` normalmente é `MXN`.
- Usado para pagamentos em MXN para contas bancárias mexicanas.


EU_SEPA
O objeto `euSepa` é usado quando o `financialInstrumentType` é `EU_SEPA`.

| Campo | Tipo | Obrigatório | Descrição | Exemplo |
|  --- | --- | --- | --- | --- |
| bankName | string | Sim | Nome do banco. | "Bank of Example" |
| iban | string | Sim | IBAN da conta (de 15 a 34 caracteres, prefixado com país e dígito verificador). | "DE89370400440532013000" |


Observações de uso
- A `currency` normalmente é `EUR`.
- O IBAN deve seguir as regras do formato SEPA; a validação é aplicada pela API.


GB_FPS
O objeto `gbFps` é usado quando o `financialInstrumentType` é `GB_FPS`.

| Campo | Tipo | Obrigatório | Descrição | Exemplo |
|  --- | --- | --- | --- | --- |
| bankName | string | Sim | Nome do banco do Reino Unido. | "Bank of Example" |
| sortCode | string | Sim | Sort code de 6 dígitos do banco/agência. | "123456" |
| accountNumber | string | Sim | Número de conta com 8 dígitos. | "12345678" |


Observações de uso
- A `currency` normalmente é `GBP`.
- Usado para pagamentos no modelo Faster Payments/CHAPS.


CA_EFT
O objeto `caEft` é usado quando o `financialInstrumentType` é `CA_EFT`.

| Campo | Tipo | Obrigatório | Descrição | Exemplo |
|  --- | --- | --- | --- | --- |
| bankName | string | Sim | Nome da instituição financeira canadense. | "Bank of Example" |
| institutionNumber | string | Sim | Número da instituição, com 3 dígitos. | "123" |
| transitNumber | string | Sim | Número de trânsito da agência, com 5 dígitos. | "12345" |
| accountNumber | string | Sim | Número da conta (normalmente de 7 a 12 dígitos). | "12345678" |
| accountType | string | Sim | Tipo de conta bancária. Os valores incluem CHECKING e SAVINGS. | "CHECKING" |


Observações de uso
- A `currency` normalmente é `CAD`.
- Usado para pagamentos domésticos canadenses via EFT.


NG_BANK_PAYOUT
O objeto `ngBankPayout` é usado quando o `financialInstrumentType` é `NG_BANK_PAYOUT`.

| Campo | Tipo | Obrigatório | Descrição | Exemplo |
|  --- | --- | --- | --- | --- |
| bankName | string | Sim | Nome do banco do beneficiário. | "Guaranty Trust Bank PLC" |
| bankCode | string | Sim | Ripple Bank Code do banco de destino. Formato: `RPL:NG:[ALIAS]:BNK`. Use a consulta [Códigos bancários](/pt-br/products/payments-direct-2/api-docs/integration-resources/ripple-bank-codes) para encontrar o código correto antes de criar o instrumento. | "RPL:NG:GTBINGLA:BNK" |
| accountNumber | string | Sim | Número da conta no banco de destino. | "0123456789" |


Observações de uso
- A `currency` é `NGN`.
- O `bankCode` deve ser um Ripple Bank Code (RBC) válido. Use o utilitário de consulta [Códigos bancários](/pt-br/products/payments-direct-2/api-docs/integration-resources/ripple-bank-codes) para encontrar o RBC correto do banco de destino antes de criar o instrumento.


CO_PSE
O objeto `coPse` é usado quando o `financialInstrumentType` é `CO_PSE`.

| Campo | Tipo | Obrigatório | Descrição | Exemplo |
|  --- | --- | --- | --- | --- |
| bankName | string | Sim | Nome do banco colombiano. | "Bank of Example" |
| bankCode | string | Sim | Código do banco para o pagamento via PSE (de 2 a 4 dígitos, numérico). | "1007" |
| accountNumber | string | Sim | Número da conta para o pagamento via PSE. | "12345678" |
| accountType | string | Sim | Tipo de conta. Os valores incluem CURRENT e SAVINGS. | "CURRENT" |


Observações de uso
- A `currency` normalmente é `COP`.
- Usado para pagamentos colombianos via PSE.


BR_TED
O objeto `brTed` é usado quando o `financialInstrumentType` é `BR_TED`.

| Campo | Tipo | Obrigatório | Descrição | Exemplo |
|  --- | --- | --- | --- | --- |
| bankName | string | Sim | Nome do banco brasileiro. | "Bank of Example" |
| bankCode | string | Sim | Código bancário BICFI do banco do beneficiário (de 8 a 11 caracteres alfanuméricos). | "BRASTCAA" |
| branchNumber | string | Sim | Número da agência da conta do beneficiário, com 4 dígitos. | "1234" |
| accountNumber | string | Sim | Número da conta do beneficiário (de 5 a 14 dígitos). | "1234567890" |
| accountType | string | Sim | Tipo de conta bancária. Os valores incluem CHECKING e SAVINGS. | "CHECKING" |


Observações de uso
- A `currency` normalmente é `BRL`.
- Usado para transferências bancárias brasileiras via TED.


BR_PIX
O objeto `brPix` é usado quando o `financialInstrumentType` é `BR_PIX`.

| Campo | Tipo | Obrigatório | Descrição | Exemplo |
|  --- | --- | --- | --- | --- |
| bankName | string | Sim | Nome do banco brasileiro. | "Bank of Example" |
| bankCode | string | Sim | Código bancário BICFI do banco do beneficiário (de 8 a 11 caracteres). | "BRASBRRJBHE" |
| branchNumber | string | Sim | Número da agência bancária (de 4 a 6 dígitos). | "0001" |
| pixKey | string | Sim | A chave PIX do beneficiário: um endereço de e-mail, número de telefone, CPF/CNPJ ou chave aleatória EVP. | "fake@example.com" |
| pixKeyType | string | Sim | Tipo de chave PIX informada. Valores: `CPF`, `CNPJ`, `EMAIL`, `PHONE`, `EVP`. | "EMAIL" |


Observações de uso
- A `currency` normalmente é `BRL`.
- Usado para pagamentos instantâneos brasileiros via PIX.


GH_BANK_PAYOUT
O objeto `ghBankPayout` é usado quando o `financialInstrumentType` é `GH_BANK_PAYOUT`.

| Campo | Tipo | Obrigatório | Descrição | Exemplo |
|  --- | --- | --- | --- | --- |
| bankName | string | Sim | Nome do banco do beneficiário. | "Ecobank Ghana" |
| bankCode | string | Sim | Código do banco do beneficiário. | "RPL:GH:BARCGHAC:BNK" |
| accountNumber | string | Sim | Número da conta no banco de destino (de 4 a 21 caracteres alfanuméricos). | "0123456789" |


Observações de uso
- A `currency` é `GHS`.
- Usado para pagamentos em GHS para contas bancárias ganesas via GIS.


RW_BANK_PAYOUT
O objeto `rwBankPayout` é usado quando o `financialInstrumentType` é `RW_BANK_PAYOUT`.

| Campo | Tipo | Obrigatório | Descrição | Exemplo |
|  --- | --- | --- | --- | --- |
| bankName | string | Sim | Nome do banco do beneficiário. | "Bank of Kigali" |
| bankCode | string | Sim | Código do banco do beneficiário. | "RPL:RW:ABBRRWRW:BNK" |
| accountNumber | string | Sim | Número da conta no banco de destino (de 4 a 21 caracteres alfanuméricos). | "0123456789" |


Observações de uso
- A `currency` é `RWF`.
- Usado para pagamentos em RWF para contas bancárias ruandesas via RSwitch.
- Caso de uso compatível: apenas C2B2C.


ZA_BANK_PAYOUT
O objeto `zaBankPayout` é usado quando o `financialInstrumentType` é `ZA_BANK_PAYOUT`.

| Campo | Tipo | Obrigatório | Descrição | Exemplo |
|  --- | --- | --- | --- | --- |
| bankName | string | Sim | Nome do banco do beneficiário. | "Standard Bank" |
| bankCode | string | Sim | Código do banco do beneficiário. | "RPL:ZA:ABSAZAJJ:BNK" |
| accountNumber | string | Sim | Número da conta no banco de destino (de 4 a 21 caracteres alfanuméricos). | "0123456789" |


Observações de uso
- A `currency` é `ZAR`.
- Usado para pagamentos em ZAR para contas bancárias sul-africanas via PayShap.
- Caso de uso compatível: apenas C2B2C.


UG_BANK_PAYOUT
O objeto `ugBankPayout` é usado quando o `financialInstrumentType` é `UG_BANK_PAYOUT`.

| Campo | Tipo | Obrigatório | Descrição | Exemplo |
|  --- | --- | --- | --- | --- |
| bankName | string | Sim | Nome do banco do beneficiário. | "Stanbic Bank Uganda" |
| bankCode | string | Sim | Código do banco do beneficiário. | "RPL:UG:ABCFUGKA:BNK" |
| accountNumber | string | Sim | Número da conta no banco de destino (de 4 a 21 caracteres alfanuméricos). | "0123456789" |


Observações de uso
- A `currency` é `UGX`.
- Usado para pagamentos em UGX para contas bancárias ugandenses.


ZM_BANK_PAYOUT
O objeto `zmBankPayout` é usado quando o `financialInstrumentType` é `ZM_BANK_PAYOUT`.

| Campo | Tipo | Obrigatório | Descrição | Exemplo |
|  --- | --- | --- | --- | --- |
| bankName | string | Sim | Nome do banco do beneficiário. | "Zanaco" |
| bankCode | string | Sim | Código do banco do beneficiário. | "RPL:ZM:ABBAZMLU:BNK" |
| accountNumber | string | Sim | Número da conta no banco de destino (de 4 a 21 caracteres alfanuméricos). | "0123456789" |


Observações de uso
- A `currency` é `ZMW`.
- Usado para pagamentos em ZMW para contas bancárias zambianas via ZECHL.


AE_IPI
O objeto `aeIpi` é usado quando o `financialInstrumentType` é `AE_IPI`.

| Campo | Tipo | Obrigatório | Descrição | Exemplo |
|  --- | --- | --- | --- | --- |
| bankName | string | Sim | Nome do banco da identidade. | "Emirates NBD" |
| iban | string | Sim | International Bank Account Number (IBAN) da conta da identidade (23 caracteres, começando com `AE`). | "AE460330000012345678901" |


Observações de uso
- A `currency` é `AED`.
- Dois rails são avaliados em ordem: o **IPI** (em tempo real, até AED 25.000, sem horário de corte) é usado primeiro quando a conta do beneficiário é endereçável por IPI; caso contrário, é usado o **FTS** (mesmo dia, sem limite, corte às 14h00 GST aproximadamente). Os feriados do Banco Central dos Emirados se aplicam ao FTS.


IN_NEFT
O objeto `inNeft` é usado quando o `financialInstrumentType` é `IN_NEFT`.

| Campo | Tipo | Obrigatório | Descrição | Exemplo |
|  --- | --- | --- | --- | --- |
| bankName | string | Sim | Nome do banco da identidade. | "HDFC Bank" |
| ifscCode | string | Sim | Código IFSC de 11 caracteres da agência bancária da identidade. | "HDFC0001234" |
| accountNumber | string | Sim | Número da conta bancária da identidade. | "1234567890" |


Observações de uso
- A `currency` é `INR`.
- Usado para pagamentos em INR via NEFT (National Electronic Funds Transfer). Apenas em dias úteis e no horário bancário; sem limite por transação; o horário de corte é às 19h00 IST (varia conforme o banco). Os feriados bancários da Índia se aplicam.


CL_TEF
O objeto `clTef` é usado quando o `financialInstrumentType` é `CL_TEF`.

| Campo | Tipo | Obrigatório | Descrição | Exemplo |
|  --- | --- | --- | --- | --- |
| bankName | string | Sim | Nome do banco da identidade. | "Banco de Chile" |
| swiftCode | string | Sim | Código SWIFT/BIC do banco da identidade. | "BCHICLRMCUS" |
| accountNumber | string | Sim | Número da conta bancária da identidade. | "1234567890123" |
| accountType | string | Sim | Tipo de conta bancária. Os valores incluem `CHECKING` e `SAVINGS`. | "CHECKING" |


Observações de uso
- A `currency` é `CLP`.
- Usado para pagamentos em CLP via TEF (Transferencia Electrónica de Fondos). Apenas em dias úteis; sem limite por transação; o horário de corte é às 15h00 CLT. Os feriados bancários do Chile se aplicam.


JP_ZENGIN
O objeto `jpZengin` é usado quando o `financialInstrumentType` é `JP_ZENGIN`.

| Campo | Tipo | Obrigatório | Descrição | Exemplo |
|  --- | --- | --- | --- | --- |
| bankName | string | Sim | Nome do banco da identidade. | "MUFG Bank" |
| bankCode | string | Sim | Código bancário japonês de 4 dígitos atribuído pelo Zengin-Net/BOJ. Use a consulta [Códigos bancários](/pt-br/products/payments-direct-2/api-docs/integration-resources/ripple-bank-codes) para encontrar o código correto. | "0005" |
| branchCode | string | Sim | Código de agência atribuído pelo banco que identifica a agência específica. | "001" |
| accountNumber | string | Sim | Número da conta bancária da identidade. | "1234567" |
| accountType | string | Sim | Tipo de conta. Um de `CHECKING` (当座預金), `ORDINARY` (普通預金) ou `SAVINGS` (貯蓄預金). | "ORDINARY" |
| accountHolderName | string | Sim | Nome do titular da conta em caracteres katakana japoneses. | "ヤマダタロウ" |


Observações de uso
- A `currency` é `JPY`.
- Dois rails são avaliados em ordem: o **Zengin Prompt Service** (em tempo real, normalmente até JPY 1.000.000, sem horário de corte, sem feriados bancários) é usado primeiro quando a conta do beneficiário é endereçável por ZPS; caso contrário, é usado o **Zengin** (mesmo dia ou próximo dia útil, sem limite, corte às 21h00 JST). Os feriados bancários do Japão se aplicam ao Zengin.
- O `accountHolderName` deve ser informado em katakana. O padrão do schema aceita outros sistemas de escrita, portanto um nome em caracteres latinos passa pela validação de schema mesmo sem atender ao requisito do corredor.


TH_PROMPTPAY
O objeto `thPromptpay` é usado quando o `financialInstrumentType` é `TH_PROMPTPAY`.

| Campo | Tipo | Obrigatório | Descrição | Exemplo |
|  --- | --- | --- | --- | --- |
| bankName | string | Sim | Nome do banco da identidade. | "Bangkok Bank" |
| bankCode | string | Sim | Código bancário doméstico do banco da identidade na Tailândia. Consulte o recurso [Códigos bancários](/pt-br/products/payments-direct-2/api-docs/integration-resources/ripple-bank-codes) para ver a lista oficial de valores compatíveis. | "002" |
| accountNumber | string | Sim | Número da conta bancária da identidade. | "1234567890" |


Observações de uso
- A `currency` é `THB`.
- Usado para pagamentos em THB via PromptPay (National ITMX). Disponível 24/7/365, sem horário de corte, com um limite de THB 500.000 por transação.


KR_KFTC
O objeto `krKftc` é usado quando o `financialInstrumentType` é `KR_KFTC`.

| Campo | Tipo | Obrigatório | Descrição | Exemplo |
|  --- | --- | --- | --- | --- |
| bankName | string | Sim | Nome do banco da identidade. | "Kookmin Bank" |
| bankCode | string | Sim | Código de compensação doméstica coreano atribuído pelo KFTC. Consulte o recurso [Códigos bancários](/pt-br/products/payments-direct-2/api-docs/integration-resources/ripple-bank-codes) para ver a lista oficial de valores compatíveis. | "004" |
| accountNumber | string | Sim | Número da conta bancária da identidade. | "110123456789" |


Observações de uso
- A `currency` é `KRW`.
- Usado para pagamentos em KRW via KFTC (Korea Financial Telecommunications and Clearings). Disponível 24/7/365, sem horário de corte, com um limite de KRW 10.000.000 por transação (variável).


CN_CFXPS
O objeto `cnCfxps` é usado quando o `financialInstrumentType` é `CN_CFXPS`.

| Campo | Tipo | Obrigatório | Descrição | Exemplo |
|  --- | --- | --- | --- | --- |
| bankName | string | Sim | Nome do banco do beneficiário. Resolvido a partir do `swiftCode`. | "Industrial and Commercial Bank of China" |
| swiftCode | string | Sim | Código SWIFT/BIC do banco do beneficiário (8 ou 11 caracteres). | "ICBKCNBJXXX" |
| accountNumber | string | Sim | Número da conta do beneficiário. | "0123456789012345" |
| accountHolderName | string | Sim | Nome do titular da conta do beneficiário (em inglês). | "Zhang San" |


Observações de uso
- A `currency` é `USD`.
- Usado para payouts em USD à China via China Foreign Exchange Payment System (CFXPS).


Coleta de documentos do beneficiário
Depois que um pagamento CN_CFXPS atinge o status `COMPLETED`, o banco do beneficiário entra em contato diretamente com o beneficiário para coletar a documentação de compliance antes de liberar os fundos na conta dele. Esse processo está fora do controle da Ripple e nenhum SLA se aplica. A liquidação final pode levar de 2 a 3 dias úteis ou mais, dependendo de quando o beneficiário fornecer a documentação satisfatória.

Consulte [Requisitos de Dados de Transação da China (USD)](/pt-br/products/payments-direct-2/api-docs/integration-resources/apac/cn/usd) para ver os detalhes completos.

AU_NPP
O objeto `auNpp` é usado quando o `financialInstrumentType` é `AU_NPP`.

| Campo | Tipo | Obrigatório | Descrição | Exemplo |
|  --- | --- | --- | --- | --- |
| bankName | string | Sim | Nome do banco da identidade. | "Commonwealth Bank of Australia" |
| bsbCode | string | Sim | Código de roteamento Bank-State-Branch (BSB) de 6 dígitos. | "062000" |
| accountNumber | string | Sim | Número da conta bancária da identidade. | "12345678" |


Observações de uso
- A `currency` é `AUD`.
- Dois rails são avaliados em ordem: o **NPP** (em tempo real, em até 15 minutos, até AUD 20.000 por transação, sem horário de corte, sem feriados bancários) é usado primeiro quando a conta do beneficiário é endereçável por NPP; caso contrário, é usado o **Direct Entry (BECS)** (mesmo dia ou próximo dia útil, sem limite, corte dependente do banco). Os feriados bancários australianos se aplicam ao Direct Entry.


PE_LBTR
O objeto `peLbtr` é usado quando o `financialInstrumentType` é `PE_LBTR`.

| Campo | Tipo | Obrigatório | Descrição | Exemplo |
|  --- | --- | --- | --- | --- |
| bankName | string | Sim | Nome do banco da identidade. | "Banco de Crédito del Perú" |
| swiftCode | string | Sim | Código SWIFT/BIC do banco da identidade. | "BCPLPEPL" |
| accountNumber | string | Sim | Número da conta bancária da identidade. | "1234567890" |
| accountType | string | Sim | Tipo de conta bancária. Os valores incluem `CHECKING` e `SAVINGS`. | "CHECKING" |


Observações de uso
- A `currency` é `PEN`.
- Usado para pagamentos em PEN via LBTR (Sistema de Liquidación Bruta en Tiempo Real). Apenas em dias úteis e no horário bancário; o valor mínimo por transação é de 5 USD; o horário de corte é às 15h00 PET. Os feriados bancários do Peru se aplicam.


AR_INTERBANKING
O objeto `arInterbanking` é usado quando o `financialInstrumentType` é `AR_INTERBANKING`.

| Campo | Tipo | Obrigatório | Descrição | Exemplo |
|  --- | --- | --- | --- | --- |
| bankName | string | Sim | Nome do banco da identidade. | "Banco de la Nación Argentina" |
| bankCode | string | Sim | Código bancário argentino de 3 dígitos atribuído pelo BCRA. Consulte o recurso [Códigos bancários](/pt-br/products/payments-direct-2/api-docs/integration-resources/ripple-bank-codes) para ver a lista oficial de valores compatíveis. | "011" |
| accountNumber | string | Sim | Número da conta da identidade (CBU ou CVU, 22 dígitos). | "0110599520000001234567" |
| accountType | string | Sim | Tipo de conta bancária. Os valores incluem `CHECKING` (Cuenta Corriente) e `SAVINGS` (Caja de Ahorro). | "CHECKING" |


Observações de uso
- A `currency` é `ARS`.
- Usado para pagamentos em ARS via Interbanking. Apenas em dias úteis; o limite é de ARS 10.000.000 por transação; o horário de corte é às 15h00 ART. Os feriados bancários da Argentina se aplicam.


ETH_WALLET
O objeto `ethWallet` é usado quando o `financialInstrumentType` é `ETH_WALLET`.

| Campo | Tipo | Obrigatório | Descrição | Exemplo |
|  --- | --- | --- | --- | --- |
| walletAddress | string | Sim | Endereço da carteira Ethereum na corretora (42 caracteres, começando com `0x`). | "0x742d35Cc6634C0532925a3b844Bc454e4438f44e" |
| cryptoInstitutionName | string | Sim | Nome da corretora de criptomoedas que mantém a carteira. | "Bitso" |


Observações de uso
- Compatível com pagamentos em USDT, USDC e RLUSD na rede Ethereum.
- O campo de metadados `country` retorna `ZZ` para todos os instrumentos de carteira de criptomoedas.


TRON_WALLET
O objeto `tronWallet` é usado quando o `financialInstrumentType` é `TRON_WALLET`.

| Campo | Tipo | Obrigatório | Descrição | Exemplo |
|  --- | --- | --- | --- | --- |
| walletAddress | string | Sim | Endereço da carteira Tron na corretora (34 caracteres, começando com `T`). | "T9yD14Nj9j7xAB4dbGeiX9h8unkKHxuWwb" |
| cryptoInstitutionName | string | Sim | Nome da corretora de criptomoedas que mantém a carteira. | "Bitso" |


Observações de uso
- Compatível com pagamentos em USDT na rede Tron.
- O campo de metadados `country` retorna `ZZ` para todos os instrumentos de carteira de criptomoedas.


SOL_WALLET
O objeto `solWallet` é usado quando o `financialInstrumentType` é `SOL_WALLET`.

| Campo | Tipo | Obrigatório | Descrição | Exemplo |
|  --- | --- | --- | --- | --- |
| walletAddress | string | Sim | Endereço da carteira Solana na corretora (de 32 a 44 caracteres, codificado em base58). | "7EcDhSYGxXyscszYEp35KHN8vvw3svAuLKTzXwCFLtV" |
| cryptoInstitutionName | string | Sim | Nome da corretora de criptomoedas que mantém a carteira. | "Bitso" |


Observações de uso
- Compatível com pagamentos em USDC na rede Solana.
- O campo de metadados `country` retorna `ZZ` para todos os instrumentos de carteira de criptomoedas.


## Validação e requisitos de dados

**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.


### Validação da identidade com `validatePayoutRails`

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**.


Validação antecipada
Usar o `validatePayoutRails` nas identidades ajuda a detectar problemas de PII com antecedência, antes de você tentar criar instrumentos financeiros ou pagamentos. 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).

## Próximos passos

- Para saber como criar, atualizar, listar e desativar instrumentos financeiros por meio da API, continue com [Criar e gerenciar instrumentos financeiros](/pt-br/products/payments-direct-2/api-docs/developer-guides/create-and-manage-financial-instruments).
- 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](/pt-br/products/payments-direct-2/introduction/concepts/payment-identities).