# Identidades do pagamento

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.

Uma *identidade do pagamento* é um registro estruturado que representa o **ordenante** ou o **beneficiário** de um pagamento. As identidades armazenam informações de identificação pessoal (PII), como nomes, endereços, nacionalidade, dados de contato e documentos de identificação.

Com o **Identity Management v3**, as identidades são recursos de primeira classe que você cria uma vez e reutiliza em vários pagamentos. Elas ficam ao lado dos instrumentos financeiros (contas bancárias, payment rails locais, carteiras) e são referenciadas por ID a partir da API do Payments Direct, em vez de enviar PII bruta em cada requisição de pagamento.

O **Identity Management v3** permite que você:

- Crie identidades reutilizáveis em vez de embutir PII em cada pagamento.
- Mantenha uma separação clara entre **quem** está envolvido em um pagamento (identidades) e **como** os recursos são movimentados (instrumentos financeiros).
- Acompanhe o histórico da identidade por meio de versões imutáveis, para fins de auditoria e compliance.
- Imponha um mapeamento um-para-um entre os seus **registros de clientes** e as **identidades ACTIVE** por meio do `internalId`.


Este tópico se concentra no **modelo de identidade v3**. A API v3 também pode ler identidades legadas v2, mas a v3 é o modelo recomendado para novas integrações.

## O que você vai aprender

Neste tópico, você vai aprender:

- Como as identidades são classificadas por **identityType** (`INDIVIDUAL`, `BUSINESS`) e **paymentRole** (`ORIGINATOR`, `BENEFICIARY`).
- Quais campos de PII estão disponíveis nas identidades **INDIVIDUAL** e **BUSINESS**, e como as regras de corredor afetam quais campos são obrigatórios.
- Como funcionam o versionamento de identidades e os estados do ciclo de vida (`ACTIVE`, `BLOCKED`, `DEACTIVATED`).
- Como o `internalId` fornece **idempotência e deduplicação**, de modo que, no máximo, uma identidade ACTIVE na sua organização use um determinado ID de cliente upstream.
- Como as identidades se relacionam com os **instrumentos financeiros**, que armazenam os dados de conta bancária e de pagamento.


## Tipos de identidade e papéis de pagamento

Toda identidade é definida por duas propriedades principais:

- **`identityType`** – se a identidade é um **indivíduo** ou uma **empresa**
- **`paymentRole`** – se a identidade atua como **ordenante** ou **beneficiário** nos pagamentos


### Tipos de identidade

| Tipo de identidade | Descrição |
|  --- | --- |
| INDIVIDUAL | Usado para pessoas físicas. Inclui dados pessoais como nome, data de nascimento, endereço, informações de contato e dados de documento de identidade oficial. |
| BUSINESS | Usado para empresas, instituições ou outras organizações. Inclui a razão social, o endereço registrado, identificadores empresariais (como certificado de constituição ou identificação fiscal) e informações de contato. |


O tipo de identidade determina qual seção do objeto de identidade é preenchida:

- individual – para identidades **INDIVIDUAL**
- business – para identidades **BUSINESS**


Apenas uma dessas seções é preenchida para uma determinada identidade.

### Papéis de pagamento

| Papel de pagamento | Descrição |
|  --- | --- |
| ORIGINATOR | A parte que inicia o pagamento e atua como a fonte final dos recursos. Este papel representa a pessoa ou entidade que financia a transação, mesmo que a requisição de pagamento seja enviada por meio de um intermediário ou de um fluxo de pagamento aninhado. |
| BENEFICIARY | A parte que atua como o destino final dos recursos. Este papel representa o recebedor final do valor do pagamento, distinto da instituição financeira, do parceiro pagador ou do intermediário que facilita a transferência. |


## Ciclo de vida e versionamento da identidade

As identidades são imutáveis e versionadas:

- Cada identidade tem um `identityId` estável.
- Cada atualização cria uma nova **versão**, mantendo intactas as versões anteriores para fins de auditoria.
- O serviço rastreia uma **versão de schema** e timestamps de criação e de atualização.


### Estados da identidade

O campo `identityState` descreve em que ponto do ciclo de vida uma identidade se encontra:

| Estado | Descrição |
|  --- | --- |
| ACTIVE | A identidade existe e pode ser usada em pagamentos. |
| BLOCKED | A identidade existe, mas não pode ser usada até ser desbloqueada (por exemplo, devido a uma análise de compliance). |
| DEACTIVATED | A identidade foi desativada e não deve mais ser usada em novos pagamentos. |


As mudanças de estado são rastreadas por versão; normalmente, os chamadores usam a versão mais recente ao construir novos pagamentos.

## Relação com os instrumentos financeiros

Uma identidade do pagamento representa a parte, não a conta.

- As identidades armazenam **quem** é a parte (PII).
- Os **instrumentos financeiros** armazenam **para onde** o dinheiro é enviado ou recebido (por exemplo, dados de conta bancária ou endereços de carteira).


Identidades e instrumentos financeiros
Cada identidade tem **um instrumento financeiro ativo**. Isso mantém um único registro de KYC para uma parte e ao mesmo tempo permite que você substitua os dados da conta dessa parte sem recriar a identidade. O suporte a vários instrumentos financeiros por identidade está previsto para uma versão futura.

Para mais detalhes, consulte [Instrumentos financeiros](/pt-br/products/payments-direct-2/introduction/concepts/financial-instruments).

## Referência do objeto de identidade

As seções a seguir descrevem o objeto de identidade principal retornado nas respostas do **Identity Management v3**.

### Metadados da identidade

Estes campos se aplicam a todas as identidades, independentemente do tipo ou do papel.

| Campo | Tipo | Obrigatório | Descrição | Exemplo |
|  --- | --- | --- | --- | --- |
| **identityId** | string | Sim | Identificador único gerado pelo servidor para a identidade. Estável em todas as versões. | "2f4ac57f-c5ba-4051-b51f-b3565778717b" |
| **identityType** | string | Sim | Categoria da identidade. Valores permitidos: INDIVIDUAL, BUSINESS. | "INDIVIDUAL" |
| **paymentRole** | string | Sim | Papel de pagamento desta identidade. Valores permitidos: ORIGINATOR, BENEFICIARY. | "BENEFICIARY" |
| **internalId** | string | Condicional | Identificador único fornecido pelo cliente que vincula esta identidade ao seu registro de cliente ou de conta upstream. Obrigatório para identidades ORIGINATOR; opcional, mas recomendado, para identidades BENEFICIARY.**Deve ser único entre todas as identidades ACTIVE da sua organização.**Se você tentar criar ou atualizar uma identidade com um internalId que coincida com o de uma identidade ACTIVE diferente, a requisição falhará com **HTTP 409 Conflict**. Isso proporciona idempotência e ajuda a evitar identidades duplicadas para a mesma parte do mundo real.Esta é a sua própria chave de referência, não o número de conta do ordenante. Consulte [O número de conta do ordenante](#o-n%C3%BAmero-de-conta-do-ordenante). | "customer-12345-uuid" |
| **originatorAccountNumber** | string | Condicional | O número de conta do ordenante ou o seu identificador de cliente para o ordenante. A Ripple encaminha esse valor ao parceiro pagador.Obrigatório em identidades ORIGINATOR validadas em relação a `CN_CFXPS`; opcional nos demais casos. Ele só é enviado aos parceiros pagadores para ordenantes, portanto normalmente não há motivo para defini-lo em um beneficiário.**Deve ser único entre todas as identidades ACTIVE da sua organização, incluindo as identidades BENEFICIARY.** Valores duplicados falham com **HTTP 409 Conflict**.Os limites de comprimento e de caracteres do corredor se aplicam, mas não são validados neste campo. Consulte [O número de conta do ordenante](#o-n%C3%BAmero-de-conta-do-ordenante). | "6222021001125874" |
| **nickName** | string | Não | Alias legível por humanos para simplificar o gerenciamento nos seus sistemas. | "primary-gbp-sender" |
| **tags** | array | Não | Rótulos livres (strings) para categorizar ou filtrar identidades (por exemplo, por segmento, região ou nível de cliente). | ["vip", "gb-smb"] |
| **validatePayoutRails** | array | Não | Lista de métodos de pagamento (tipos de instrumento financeiro) em relação aos quais esta identidade deve ser validada. Quando informada, os dados pessoais da identidade são validados para garantir que atendam aos requisitos dos payment rails especificados.Os valores incluem: `US_ACH`, `US_FEDWIRE`, `MX_SPEI`, `EU_SEPA`, `GB_FPS`, `CA_EFT`, `NG_BANK_PAYOUT`, `BR_PIX`, `BR_TED`, `CO_PSE`, `GH_BANK_PAYOUT`, `RW_BANK_PAYOUT`, `ZA_BANK_PAYOUT`, `UG_BANK_PAYOUT`, `ZM_BANK_PAYOUT`, `ETH_WALLET`, `TRON_WALLET`, `SOL_WALLET`, `AE_IPI`, `IN_NEFT`, `CN_CFXPS`, `CL_TEF`, `TH_PROMPTPAY`, `KR_KFTC`, `AU_NPP`, `JP_ZENGIN`, `PE_LBTR`, `AR_INTERBANKING`.Consulte [Validando identidades para payment rails específicos](#validando-identidades-para-payment-rails-espec%C3%ADficos) para mais detalhes. | ["US_ACH", "MX_SPEI"] |
| **version** | integer | Sim | Número de versão sequencial desta identidade. É incrementado a cada atualização bem-sucedida. | 2 |
| **schemaVersion** | string | Sim | Versão de schema usada para validar o payload de PII desta identidade. | "1.0.0" |
| **identityState** | string | Sim | Estado do ciclo de vida da identidade: `ACTIVE`, `BLOCKED` ou `DEACTIVATED`. | "ACTIVE" |
| **createdAt** | string | Sim | Timestamp RFC 3339 de quando a identidade foi criada pela primeira vez. | "2025-11-02T18:26:00.000Z" |
| **updatedAt** | string | Sim | Timestamp RFC 3339 de quando a identidade foi atualizada pela última vez (criação da versão mais recente). | "2025-11-03T18:26:00.000Z" |


### Idempotência e deduplicação com `internalId`

Cada identidade pode carregar um `internalId` fornecido pelo cliente que a vincula ao seu próprio registro de cliente ou de conta. Isso permite que o **Identity Management v3** ajude você a evitar identidades duplicadas para a mesma parte do mundo real e facilita a conciliação de identidades entre sistemas.

**Em alto nível:**

- O `internalId` é **obrigatório** para identidades ORIGINATOR e **opcional** para identidades BENEFICIARY.
- O `internalId` deve ser **único entre todas as identidades ACTIVE** da sua organização.
- Se você tentar criar ou atualizar uma identidade de modo que o seu `internalId` coincida com o de uma identidade ACTIVE diferente, a requisição falha com **HTTP 409 Conflict**.
- O `internalId` é a sua própria chave de referência. Ele não é o número de conta do ordenante: envie esse valor em `originatorAccountNumber`. Consulte [O número de conta do ordenante](#o-n%C3%BAmero-de-conta-do-ordenante).


Esse comportamento oferece a você uma forma simples e confiável de impor uma relação um-para-um entre o seu registro de cliente upstream e uma identidade ACTIVE no **Identity Management v3**.

#### Como o `internalId` é usado

O **Identity Management v3** usa o `internalId` em três lugares principais:

- **Criar identidade (v3)**: Ao chamar `POST /v3/identities`, você pode (e, para ORIGINATORs, deve) fornecer o `internalId` no corpo da requisição. Se outra identidade ACTIVE na sua organização já usar o mesmo valor, a requisição falha com **409 Conflict**.
- **Atualizar identidade (v3)** Ao chamar `PUT /v3/identities/{identity-id}`, você pode alterar o `internalId`. Se o novo valor já estiver atribuído a uma identidade ACTIVE diferente, a atualização falha com **409 Conflict**.
- **Respostas de identidade**: As respostas de identidade incluem o `internalId` atual, para que você possa mapear facilmente um `identityId` de volta ao seu próprio registro de cliente.


A verificação de unicidade tem escopo na sua organização. Organizações diferentes podem reutilizar os mesmos valores de `internalId` sem conflito.

#### Padrões recomendados

Ao escolher e usar o `internalId`, recomendamos que você:

- Use uma **chave upstream estável**, como um ID de cliente do CRM, um ID de cliente do core banking ou um ID do registro mestre de KYC. Você não precisa adaptá-la para nenhum corredor: os corredores que precisam do número de conta do ordenante leem o [`originatorAccountNumber`](#o-n%C3%BAmero-de-conta-do-ordenante) em vez dela.
- Evite embutir PII (por exemplo, e-mails, números de telefone, documentos nacionais) diretamente no `internalId`.
- Trate o `internalId` como efetivamente imutável durante toda a vida de uma identidade, sempre que possível.
- Trate as respostas **409 Conflict** como sinais de "identidade duplicada":
  - Localize e reutilize a identidade existente em vez de criar uma nova.
  - Investigue os seus sistemas upstream se vários registros estiverem tentando reutilizar o mesmo `internalId`.


Para ver exemplos passo a passo de como enviar o `internalId` em chamadas de criação e atualização e como tratar conflitos 409, consulte [Criar e gerenciar identidades](/pt-br/products/payments-direct-2/api-docs/developer-guides/create-and-manage-identities).

### O número de conta do ordenante

Alguns parceiros pagadores precisam do número de conta do próprio ordenante, e não apenas de uma referência à identidade. Envie esse valor em `originatorAccountNumber` na identidade ORIGINATOR. A Ripple o encaminha ao parceiro pagador.

`originatorAccountNumber` é opcional na maioria dos corredores. No corredor abaixo ele é obrigatório, e criar ou atualizar a identidade sem ele falha com **400 Bad Request** (`USR_111`). Nesse corredor, um UUID gerado aleatoriamente ou outra referência arbitrária faz o payout ser rejeitado.

| Corredor  | Obrigatório quando  | Valor a enviar  | Formato |
|  --- | --- | --- | --- |
| China (USD) | A identidade é validada em relação a `CN_CFXPS` | O número da conta bancária do ordenante ou o seu identificador de cliente para o ordenante | Máximo de 34 caracteres, correspondendo a `/^[A-Za-z0-9/?:().,'+ -]+$/` |


Os formatos de corredor não são validados neste campo
A API aceita qualquer string em `originatorAccountNumber`. Os limites de comprimento e de caracteres acima vêm do parceiro pagador e são aplicados quando o pagamento é enviado, não quando você cria a identidade. Um valor que os descumpra é aceito na criação da identidade e falha depois, no pagamento ao beneficiário.

#### Como o `originatorAccountNumber` funciona

- **A unicidade abrange os dois papéis.** O valor deve ser único entre todas as identidades ACTIVE da sua organização. Um valor duplicado retorna **409 Conflict** (`USR_122`). Uma identidade de beneficiário que já carrega um valor impede que um ordenante posterior o use, portanto você não pode reutilizar um mesmo número de conta compartilhado em várias identidades.
- **Um valor por identidade.** O valor é enviado em todos os pagamentos originados por essa identidade. Se um ordenante enviar pelo corredor acima, o valor dele precisa atender aos limites desse corredor, mesmo quando o mesmo ordenante também envia por corredores que não impõem restrições a esse campo.
- **O PUT substitui o estado.** Omitir o `originatorAccountNumber` em uma atualização o apaga, do mesmo modo que ocorre com o `internalId`. Envie o valor novamente em toda atualização em que você queira preservá-lo.
- **Omitido nas respostas de listagem.** Como PII, o campo é omitido na operação de listagem de identidades. Ele é retornado quando você recupera uma única identidade, recupera por ID interno ou atualiza uma identidade.
- **Omiti-lo faz o sistema recorrer ao `internalId`.** Quando `originatorAccountNumber` está vazio, a Ripple envia `internalId` ao parceiro pagador no lugar dele, como número da conta do ordenante. No corredor acima, esse é quase sempre o valor errado e, no Payments Direct UI, trata-se de um UUID gerado que o remetente nunca vê.


Não é o mesmo que o internalId
`internalId` é a sua própria chave de referência para a identidade e tem sua própria regra de unicidade. Ele não é o número da conta do ordenante.

Ainda assim, é o que o parceiro pagador recebe como número da conta sempre que `originatorAccountNumber` está vazio. Envie o número da conta em `originatorAccountNumber` para que esse comportamento nunca se aplique.

Para detalhes específicos de corredor, consulte [Recursos de integração](/pt-br/products/payments-direct-2/api-docs/integration-resources).

### Validando identidades para payment rails específicos

O campo `validatePayoutRails` permite que você especifique contra quais métodos de pagamento (tipos de instrumento financeiro) uma identidade deve ser validada quando é criada ou atualizada. Isso garante que a PII da identidade atenda a todos os requisitos dos payment rails que você pretende usar.

#### O que o `validatePayoutRails` faz

Quando você fornece `validatePayoutRails` em uma requisição de criação ou atualização:

1. O **Identity Management v3** valida a PII da identidade em relação aos requisitos específicos de corredor de cada payment rail especificado.
2. Se faltarem campos obrigatórios à identidade para algum dos payment rails especificados, a requisição falha com **400 Bad Request** e com detalhes sobre quais campos estão faltando.
3. Se a validação passar, a identidade é criada ou atualizada, e o valor de `validatePayoutRails` é armazenado com a identidade.


**O campo `validatePayoutRails` é opcional.** Se você o omitir, a identidade é criada apenas com validação estrutural básica, cobrindo campos como `firstName`, `lastName` e `address`. O que acontece depois disso depende do papel de pagamento:

- **Identidades de beneficiário** são verificadas em relação ao corredor quando você adiciona um instrumento financeiro, porque o instrumento indica o payment rail.
- **Identidades de ordenante** não são. Um ordenante não pode ter um instrumento financeiro, portanto não há um ponto de verificação posterior. Os campos exigidos pelo corredor ficam sem verificação, e o primeiro sinal de que falta algum é o parceiro pagador rejeitar o pagamento.


Para um ordenante que vai enviar por um corredor com requisitos próprios, indicar o payment rail em `validatePayoutRails` é a única forma de detectar um campo ausente na criação da identidade, em vez de quando um pagamento falha.

#### Quando usar o `validatePayoutRails`

Use o `validatePayoutRails` quando você quiser:

- **Validar antecipadamente** que uma identidade tem toda a PII exigida para corredores específicos antes de criar instrumentos financeiros ou pagamentos.
- **Evitar erros posteriores** detectando cedo, no fluxo de criação da identidade, PII faltante ou inválida.
- **Dar suporte a vários corredores** validando que uma única identidade pode ser usada em diferentes payment rails (por exemplo, tanto `US_ACH` quanto `MX_SPEI`).


#### Valores compatíveis

O array `validatePayoutRails` aceita qualquer um dos seguintes tipos de instrumento financeiro:

- `US_ACH` – Transferências bancárias domésticas nos EUA (RTP como principal, ACH como alternativa)
- `US_FEDWIRE` – Liquidação bruta em tempo real Fedwire dos EUA
- `MX_SPEI` – Sistema de transferência interbancária SPEI do México
- `EU_SEPA` – Transferências de crédito SEPA para pagamentos em EUR
- `GB_FPS` – Faster Payments Service do Reino Unido
- `CA_EFT` – Electronic Funds Transfer do Canadá
- `NG_BANK_PAYOUT` – Pagamento bancário na Nigéria (NGN)
- `BR_PIX` – Plataforma de pagamentos instantâneos do Brasil (PIX)
- `BR_TED` – Electronic Funds Transfer do Brasil (TED)
- `CO_PSE` – Sistema de pagamento bancário online seguro da Colômbia
- `GH_BANK_PAYOUT` – Pagamento bancário em Gana (GHS), via GIS
- `RW_BANK_PAYOUT` – Pagamento bancário em Ruanda (RWF), via RSwitch
- `ZA_BANK_PAYOUT` – Pagamento bancário na África do Sul (ZAR), via PayShap
- `UG_BANK_PAYOUT` – Pagamento bancário em Uganda (UGX)
- `ZM_BANK_PAYOUT` – Pagamento bancário na Zâmbia (ZMW), via ZECHL
- `ETH_WALLET` – Pagamentos para carteira na rede Ethereum (USDT, USDC, RLUSD)
- `TRON_WALLET` – Pagamentos para carteira na rede Tron (USDT)
- `SOL_WALLET` – Pagamentos para carteira na rede Solana (USDC)
- `AE_IPI` – Instant Payment Interface dos Emirados Árabes Unidos (AED), com fallback FTS
- `IN_NEFT` – National Electronic Funds Transfer da Índia (INR)
- `CN_CFXPS` – Payouts em USD à China via China Foreign Exchange Payment System (CFXPS)
- `CL_TEF` – TEF do Chile (CLP)
- `TH_PROMPTPAY` – PromptPay da Tailândia (THB)
- `KR_KFTC` – KFTC da Coreia do Sul (KRW)
- `AU_NPP` – New Payments Platform da Austrália (AUD), com Direct Entry (BECS) como alternativa
- `JP_ZENGIN` – Zengin do Japão (JPY), com o Zengin Prompt Service para transferências de baixo valor em tempo real
- `PE_LBTR` – LBTR do Peru (PEN)
- `AR_INTERBANKING` – Interbanking da Argentina (ARS)


Você pode especificar um ou mais valores. Por exemplo:

```json
{
  "validatePayoutRails": ["US_ACH", "MX_SPEI", "EU_SEPA"]
}
```

#### Como a validação funciona

Cada payment rail tem requisitos de PII específicos com base em:

- **Papel de pagamento** (ORIGINATOR vs. BENEFICIARY)
- **Tipo de identidade** (INDIVIDUAL vs. BUSINESS)
- **País de destino e regulamentações locais**


Por exemplo:

- **`US_ACH` para BENEFICIARY INDIVIDUAL** exige: `firstName`, `lastName`, `address` e ao menos um `identityDocument` (normalmente SSN ou Tax ID).
- **`BR_PIX` para BENEFICIARY INDIVIDUAL** exige: `firstName`, `lastName`, `address`, `dateOfBirth`, `email`, `phone`, `citizenship` e ao menos um `identityDocument` (normalmente CPF).
- **`MX_SPEI` para BENEFICIARY BUSINESS** exige: `businessName`, `address`, `email`, `phone` e ao menos uma `registration` (normalmente o identificador fiscal RFC).


Quando você especifica `validatePayoutRails`, o **Identity Management v3** verifica se todos os campos obrigatórios de cada payment rail estão presentes e válidos. Se algum campo obrigatório estiver faltando, a requisição falha com uma resposta de erro detalhada.

#### Exemplo: Criar uma identidade com validação de payment rail

```bash
curl -X POST "https://{base-url}/v3/identities" \
  -H "Authorization: Bearer <access_token>" \
  -H "Content-Type: application/json" \
  -d '{
    "identityType": "INDIVIDUAL",
    "paymentRole": "BENEFICIARY",
    "internalId": "customer-12345",
    "validatePayoutRails": ["US_ACH", "MX_SPEI"],
    "individual": {
      "firstName": "Jane",
      "lastName": "Doe",
      "dateOfBirth": "1990-01-15",
      "email": "jane.doe@example.com",
      "phone": "+12025551234",
      "address": {
        "streetAddress": ["123 Main St"],
        "city": "Boston",
        "stateOrProvince": "MA",
        "postalCode": "02125",
        "country": "US"
      },
      "identityDocuments": [
        {
          "idType": "SSN",
          "idNumber": "123-45-6789"
        }
      ]
    }
  }'
```

Neste exemplo:

- A identidade é validada em relação aos requisitos de `US_ACH` e `MX_SPEI`.
- Se faltar à identidade algum campo obrigatório de qualquer um dos payment rails (por exemplo, `identityDocuments` faltando para `US_ACH`), a requisição falha com **400 Bad Request**.
- Se a validação passar, a identidade é criada e pode ser usada com instrumentos financeiros US ACH e MX SPEI.


#### Relação com os instrumentos financeiros

O `validatePayoutRails` na identidade é **independente** dos instrumentos financeiros que você cria:

- Você pode validar uma identidade em relação a `US_ACH` e `MX_SPEI` e, então, criar inicialmente apenas um instrumento financeiro `US_ACH`.
- Mais tarde, você pode adicionar um instrumento financeiro `MX_SPEI` à mesma identidade sem revalidá-la.
- A PII da identidade permanece validada para ambos os payment rails, mesmo que você ainda não tenha criado instrumentos financeiros para todos eles.


A validação é orientativa
O `validatePayoutRails` fornece **validação antecipada**, mas não restringe quais instrumentos financeiros você pode criar. Você ainda pode criar instrumentos financeiros para payment rails não listados em `validatePayoutRails`, mas esses instrumentos podem falhar na validação se a PII da identidade estiver incompleta para aquele payment rail.

#### Atualizando o `validatePayoutRails`

Você pode atualizar o `validatePayoutRails` usando `PUT /v3/identities/{identity-id}`:

```bash
curl -X PUT "https://{base-url}/v3/identities/{identity-id}" \
  -H "Authorization: Bearer <access_token>" \
  -H "Content-Type: application/json" \
  -d '{
    "validatePayoutRails": ["US_ACH", "MX_SPEI", "EU_SEPA"]
  }'
```

Quando você atualiza o `validatePayoutRails`:

- A PII da identidade é revalidada em relação ao novo conjunto de payment rails.
- Se faltarem campos obrigatórios à identidade para algum payment rail recém-adicionado, a atualização falha com **400 Bad Request**.
- Se a validação passar, uma nova versão da identidade é criada com o valor atualizado de `validatePayoutRails`.


#### Boas práticas

Ao usar o `validatePayoutRails`:

- **Especifique todos os payment rails que você pretende usar** para uma identidade logo no início, para detectar cedo problemas de PII.
- **Use-o em identidades BENEFICIARY**, nas quais você pode não saber qual payment rail será usado até mais tarde (por exemplo, um fornecedor que pode receber pagamentos via ACH ou SPEI dependendo da moeda).
- **Combine-o com o `internalId`** para garantir que cada cliente tenha exatamente uma identidade validada em todos os corredores.
- **Trate os erros 400 com elegância**, solicitando aos usuários que forneçam os campos de PII faltantes antes de tentar novamente.


### Propriedades da identidade de pessoa física (individual)

Quando o `identityType` é `INDIVIDUAL`, o objeto individual contém os dados de PII da pessoa.

Requisitos condicionais
Muitos desses campos são **condicionalmente obrigatórios** para payment rails e papéis específicos (por exemplo, certas regulamentações locais podem exigir a data de nascimento ou o documento nacional). Essas condições estão resumidas na coluna "Requisitos condicionais".

#### Dados pessoais principais

| Campo | Tipo | Obrigatório | Descrição | Requisitos condicionais (exemplos) | Exemplo |
|  --- | --- | --- | --- | --- | --- |
| **firstName** | string | Sim | Nome do indivíduo. | — | "John" |
| **lastName** | string | Sim | Sobrenome do indivíduo. | — | "Smith" |
| **address** | object | Sim | Endereço postal do indivíduo, incluindo logradouro, cidade, código postal, estado/província e país. | O país deve usar o código ISO 3166-1 alfa-2 (por exemplo, US, GB, BR). Algumas validações de corredor podem exigir que todas as linhas de endereço estejam presentes e formatadas corretamente. | — |


#### Estrutura do endereço

| Campo | Tipo | Obrigatório | Descrição | Exemplo |
|  --- | --- | --- | --- | --- |
| **streetAddress** | string[] | Sim | Uma ou mais linhas de endereço em formato livre (por exemplo, logradouro, prédio, apartamento). | ["123 Example St. Apt 4B"] |
| **city** | string | Sim | Cidade ou localidade. | "Boston" |
| **stateOrProvince** | string | Condicional | Estado, província ou região, conforme definido pelos serviços postais locais.Obrigatório na maioria dos corredores, mas não nos corredores africanos de payout bancário (`NG_BANK_PAYOUT`, `GH_BANK_PAYOUT`, `RW_BANK_PAYOUT`, `UG_BANK_PAYOUT`, `ZA_BANK_PAYOUT`, `ZM_BANK_PAYOUT`). Use o [Utilitário de schema de payload](/pt-br/products/payments-direct-2/api-docs/integration-resources/payload-schema-utility) para verificar um corredor e um papel específicos. | "Massachusetts" |
| **postalCode** | string | Condicional | Código postal ou CEP.Obrigatório na maioria dos corredores, mas não nos corredores africanos de payout bancário (`NG_BANK_PAYOUT`, `GH_BANK_PAYOUT`, `RW_BANK_PAYOUT`, `UG_BANK_PAYOUT`, `ZA_BANK_PAYOUT`, `ZM_BANK_PAYOUT`). Use o [Utilitário de schema de payload](/pt-br/products/payments-direct-2/api-docs/integration-resources/payload-schema-utility) para verificar um corredor e um papel específicos. | "02125" |
| **country** | string | Sim | País de residência, usando o código ISO 3166-1 alfa-2. | "US" |


#### Dados de contato e identificação

| Campo | Tipo | Obrigatório | Descrição | Requisitos condicionais (exemplos) | Exemplo |
|  --- | --- | --- | --- | --- | --- |
| **email** | string | Condicional | Endereço de e-mail do indivíduo. | Obrigatório para BENEFICIARY em alguns payment rails (por exemplo, BR_PIX, BR_TED, CO_PSE) em que os parceiros pagadores exigem o e-mail como parte dos fluxos de KYC ou de notificação. | "fake@example.com" |
| **phone** | string | Condicional | Número de telefone celular ou de contato em formato internacional (+ e código do país). | Obrigatório para alguns payment rails (por exemplo, `BR_PIX`, `BR_TED`, `NG_BANK_PAYOUT`) para o ordenante, o beneficiário ou ambos, dependendo das regulamentações específicas do corredor. | "+1234567890" |
| **identityDocuments** | array | Condicional | Um ou mais documentos de identificação usados para verificar o indivíduo (por exemplo, passaporte, documento nacional, identificação fiscal). | Obrigatório para BENEFICIARY em `AR_INTERBANKING`, `BR_PIX`, `BR_TED`, `CL_TEF`, `CO_PSE` e `PE_LBTR`, e para ORIGINATOR em `AR_INTERBANKING`, `BR_PIX`, `CL_TEF` e `PE_LBTR`. | — |
| **dateOfBirth** | string | Condicional | Data de nascimento no formato YYYY-MM-DD. | Comumente obrigatória para BENEFICIARY em payment rails como `EU_SEPA`, `GB_FPS`, `BR_PIX`, `BR_TED`, `CA_EFT`, e para ORIGINATOR em alguns corredores (por exemplo, `EU_SEPA`, `GB_FPS`, `BR_PIX`, `BR_TED`). | "2001-01-24" |
| **countryOfBirth** | string | Condicional | País de nascimento, código ISO 3166-1 alfa-2. | Obrigatório para ORIGINATOR em `AR_INTERBANKING`, `BR_PIX`, `BR_TED`, `CL_TEF` e `PE_LBTR`, onde as regulamentações locais exigem esses dados. Não é obrigatório para beneficiários. | "US" |
| **citizenship** | string | Condicional | País de cidadania, código ISO 3166-1 alfa-2. | Obrigatório para BENEFICIARY em alguns payment rails (por exemplo, `BR_PIX`, `BR_TED`, `KR_KFTC`, `TH_PROMPTPAY`) e, às vezes, para ORIGINATOR, dependendo das regras do corredor. | "US" |
| **gender** | string | Condicional | Gênero do indivíduo. Os valores permitidos incluem `MALE`, `FEMALE`, `OTHER`. | Não é obrigatório em nenhum corredor. Envie-o apenas se os seus próprios processos de compliance exigirem. | "FEMALE" |


#### Estrutura do documento de identidade

Cada elemento de individual.identityDocuments tem a seguinte estrutura:

| Campo | Tipo | Obrigatório | Descrição | Exemplo |
|  --- | --- | --- | --- | --- |
| **idNumber** | string | Sim | Número de identificação impresso no documento (por exemplo, número do passaporte, documento nacional). | "123ABC" |
| **idType** | string | Sim | Tipo de documento de identificação. O enum completo é `ALIEN_REGISTRATION`, `CUSTOMER_ID`, `DRIVERS_LICENSE`, `PASSPORT`, `EMPLOYEE_ID`, `NATIONAL_ID_NUMBER`, `SSN`, `TAX_ID`. Os valores aceitos variam conforme o corredor e o papel de pagamento, e a API rejeita tipos não compatíveis com um erro 400. Consulte [Tipos de documento aceitos por corredor](#tipos-de-documento-aceitos-por-corredor). | "PASSPORT" |
| **expiryDate** | string | Condicional | Data de validade do documento de identificação, como data ISO 8601 (`YYYY-MM-DD`).Obrigatório em identidades ORIGINATOR validadas em relação a `IN_NEFT`, `KR_KFTC` ou `TH_PROMPTPAY`; opcional nos demais casos. | "2030-01-15" |


### Propriedades da identidade de empresa (business)

Quando o `identityType` é BUSINESS, o objeto business contém os dados de PII da organização.

#### Dados empresariais principais

| Campo | Tipo | Obrigatório | Descrição | Requisitos condicionais (exemplos) | Exemplo |
|  --- | --- | --- | --- | --- | --- |
| **businessName** | string | Sim | Razão social da empresa ou instituição. | — | "Widgets Org" |
| **address** | object | Sim | Endereço registrado ou principal de operação da empresa, incluindo logradouro, cidade, código postal, estado e país. | O país deve usar o código ISO 3166-1 alfa-2 (por exemplo, `US`, `GB`, `BR`). Algumas validações de corredor podem exigir que todas as linhas de endereço estejam presentes e formatadas corretamente. | — |


#### Estrutura do endereço

| Campo | Tipo | Obrigatório | Descrição | Exemplo |
|  --- | --- | --- | --- | --- |
| **streetAddress** | string[] | Sim | Uma ou mais linhas de endereço em formato livre para a empresa. | ["123 Example St. Boston, MA"] |
| **city** | string | Sim | Cidade ou localidade. | "Boston" |
| **stateOrProvince** | string | Condicional | Estado, província ou região, conforme definido pelos serviços postais locais.Obrigatório na maioria dos corredores, mas não nos corredores africanos de payout bancário (`NG_BANK_PAYOUT`, `GH_BANK_PAYOUT`, `RW_BANK_PAYOUT`, `UG_BANK_PAYOUT`, `ZA_BANK_PAYOUT`, `ZM_BANK_PAYOUT`). Use o [Utilitário de schema de payload](/pt-br/products/payments-direct-2/api-docs/integration-resources/payload-schema-utility) para verificar um corredor e um papel específicos. | "Massachusetts" |
| **postalCode** | string | Condicional | Código postal ou CEP.Obrigatório na maioria dos corredores, mas não nos corredores africanos de payout bancário (`NG_BANK_PAYOUT`, `GH_BANK_PAYOUT`, `RW_BANK_PAYOUT`, `UG_BANK_PAYOUT`, `ZA_BANK_PAYOUT`, `ZM_BANK_PAYOUT`). Use o [Utilitário de schema de payload](/pt-br/products/payments-direct-2/api-docs/integration-resources/payload-schema-utility) para verificar um corredor e um papel específicos. | "02125" |
| **country** | string | Sim | País do endereço da empresa, usando o código ISO 3166-1 alfa-2. | "US" |


#### Dados de contato e registro

| Campo | Tipo | Obrigatório | Descrição | Requisitos condicionais (exemplos) | Exemplo |
|  --- | --- | --- | --- | --- | --- |
| **email** | string | Condicional | Endereço de e-mail de contato geral da empresa. | Obrigatório em alguns payment rails para ORIGINATOR e/ou BENEFICIARY (por exemplo, `AR_INTERBANKING`, `BR_PIX`, `BR_TED`, `CO_PSE`), quando o payment rail de destino exige dados de contato por e-mail. | "fake@example.com" |
| **phone** | string | Condicional | Número de telefone principal da empresa em formato internacional (+ e código do país). | Obrigatório em payment rails selecionados, como `BR_PIX`, `BR_TED`, `NG_BANK_PAYOUT`, para ordenantes e beneficiários, dependendo do corredor. | "+1234567890" |
| **registration** | array | Condicional | Um ou mais identificadores de registro empresarial (por exemplo, certificado de constituição, identificação fiscal). | Obrigatório em payment rails específicos cujas regulamentações locais exigem um número de registro empresarial (por exemplo, `BR_PIX`, `BR_TED`, `CA_EFT`, `CO_PSE`, `EU_SEPA`). | — |
| **incorporationCountry** | string | Condicional | País onde a empresa está constituída, usando o código ISO 3166-1 alfa-2. | Obrigatório para BENEFICIARY em alguns payment rails (por exemplo, `BR_PIX`, `BR_TED`, `NG_BANK_PAYOUT`) e para ORIGINATOR em payment rails selecionados (por exemplo, `BR_PIX`, `BR_TED`). | "US" |
| **incorporationDate** | string | Condicional | Data em que a empresa foi constituída, no formato YYYY-MM-DD. | — | "2020-01-15" |
| **legalEntityType** | string | Condicional | Classificação da entidade jurídica empresarial. Determina o tratamento regulatório e os requisitos de compliance para certos corredores de pagamento. Valores: `BANK_CENTRAL`, `BANK_COMMERCIAL`, `PAYMENT_INSTITUTION`, `CORPORATE_PRIVATE`, `CORPORATE_PUBLIC`, `GOVERNMENT_ENTITY`, `NON_PROFIT`, `SOLE_TRADER`. | Obrigatório para ORIGINATOR em `BR_PIX`. | "CORPORATE_PRIVATE" |


#### Estrutura do registro empresarial

Cada elemento de business.registration tem a seguinte estrutura:

| Campo | Tipo | Obrigatório | Descrição | Exemplo |
|  --- | --- | --- | --- | --- |
| **number** | string | Sim | Identificador de registro único emitido para a empresa (por exemplo, número de registro da empresa). | "123ABC" |
| **type** | string | Sim | Tipo de identificador de registro. O enum completo é `INCORPORATION_CERTIFICATE`, `TAX_ID`. Os valores aceitos variam conforme o corredor e o papel de pagamento, e a API rejeita tipos não compatíveis com um erro 400. Consulte [Tipos de documento aceitos por corredor](#tipos-de-documento-aceitos-por-corredor). | "TAX_ID" |


### Requisitos específicos de corredor e de payment rail

Os requisitos de PII variam dependendo de:

- **Papel de pagamento**: ordenante vs. beneficiário
- **Payment rail / tipo de instrumento financeiro**: por exemplo, `US_ACH`, `MX_SPEI`, `BR_PIX`, `NG_BANK_PAYOUT`
- **País de destino e regulamentações locais**


As anotações `x-requiredByOriginatorFor` e `x-requiredByBeneficiaryFor` no schema da API capturam essas condições para cada campo. Na prática:

- O **Identity Management v3** e as ferramentas relacionadas validam as identidades em relação às regras apropriadas para os payment rails selecionados.
- Você deve fornecer todos os campos que possam ser exigidos para os corredores que pretende usar, mesmo que não sejam globalmente obrigatórios para toda identidade.


Para detalhes de schema em nível de corredor e regras de validação, consulte o tópico Instrumentos financeiros.

### Requisitos por jurisdição

**Jurisdição** é uma região regulatória que a Ripple registra na conta da sua organização. A jurisdição é uma propriedade da sua organização, e não um valor que você envia em uma requisição, portanto se aplica a todas as identidades que você cria, em todos os corredores.

A sua jurisdição é a sua própria e não muda conforme a parte para quem você transaciona. Se você cria identidades em nome de terceiros, como fazem um provedor de serviços de pagamento ou um banco, a sua jurisdição continua regendo essas identidades, onde quer que essas partes estejam sediadas e seja qual for o corredor pelo qual elas pagam.

Os requisitos de jurisdição se somam aos requisitos de corredor acima, em vez de substituí-los. Um campo exigido pela sua jurisdição é obrigatório mesmo em corredores que de outra forma o tratariam como opcional.

| Jurisdição  | Campo  | Aplica-se a  | Efeito |
|  --- | --- | --- | --- |
| Brasil (`BR`) | `identityDocuments` | Identidades ORIGINATOR | Obrigatório em todos os corredores, inclusive naqueles que de outra forma não o exigiriam |


Criar ou atualizar uma identidade de ordenante sem o campo falha com **400 Bad Request** (`USR_111`).

As atualizações precisam reenviar `identityDocuments`
Uma atualização valida o corpo que você envia, não o registro já armazenado. Se a sua organização estiver configurada para a jurisdição BR, qualquer atualização de uma identidade de ordenante que omita `identityDocuments` falha, mesmo quando você está alterando algo não relacionado, como um apelido ou um endereço. Envie `identityDocuments` em toda atualização de uma identidade de ordenante.

As identidades criadas antes de este requisito entrar em vigor são afetadas da mesma forma.

O [Utilitário de schema de payload](/pt-br/products/payments-direct-2/api-docs/integration-resources/payload-schema-utility) tem uma seleção de **Jurisdiction**. Defina-a com a jurisdição da sua organização e a ferramenta informa os campos exigidos por ela junto com os do próprio corredor.

Para confirmar como a sua organização está configurada, entre em contato com o seu representante da Ripple.

### Tipos de documento aceitos por corredor

Alguns corredores aceitam apenas um subconjunto do enum de tipo de documento, e a API rejeita valores não compatíveis com um **erro 400**. A imposição se baseia nos corredores em `validatePayoutRails` (na criação da identidade) ou no tipo de instrumento financeiro (na criação do instrumento). Corredores e papéis não listados abaixo aceitam o enum completo do campo.

**Identidades de pessoa física (`identityDocuments.type` / `idType`)**

| Corredor | Ordenante | Beneficiário |
|  --- | --- | --- |
| `AR_INTERBANKING` | TAX_ID | NATIONAL_ID_NUMBER, SSN |
| `AU_NPP` | PASSPORT | Todos |
| `BR_PIX` | PASSPORT, TAX_ID | TAX_ID |
| `BR_TED` | PASSPORT, TAX_ID | TAX_ID |
| `CL_TEF` | PASSPORT, TAX_ID | NATIONAL_ID_NUMBER, TAX_ID |
| `CO_PSE` | Todos | ALIEN_REGISTRATION, NATIONAL_ID_NUMBER, TAX_ID |
| `IN_NEFT` | PASSPORT | Todos |
| `KR_KFTC` | PASSPORT | Todos |
| `PE_LBTR` | PASSPORT, TAX_ID | NATIONAL_ID_NUMBER, TAX_ID |
| `TH_PROMPTPAY` | PASSPORT | ALIEN_REGISTRATION, DRIVERS_LICENSE, EMPLOYEE_ID, NATIONAL_ID_NUMBER, PASSPORT, SSN, TAX_ID |


**Identidades de empresa (`registration.type`)**

| Corredor | Ordenante | Beneficiário |
|  --- | --- | --- |
| `AR_INTERBANKING` | TAX_ID | TAX_ID |
| `BR_PIX` | TAX_ID | TAX_ID |
| `BR_TED` | TAX_ID | TAX_ID |
| `CL_TEF` | TAX_ID | TAX_ID |
| `CO_PSE` | Todos | TAX_ID |
| `ETH_WALLET` | Todos | INCORPORATION_CERTIFICATE |
| `PE_LBTR` | TAX_ID | TAX_ID |
| `SOL_WALLET` | Todos | INCORPORATION_CERTIFICATE |
| `TRON_WALLET` | Todos | INCORPORATION_CERTIFICATE |


## Próximos passos

- Para saber como criar, atualizar, listar e desativar identidades por meio da API, incluindo como usar o `internalId` e o `validatePayoutRails`, consulte [Criar e gerenciar identidades](/pt-br/products/payments-direct-2/api-docs/developer-guides/create-and-manage-identities).
- Para entender como as identidades se conectam aos dados de conta de pagamento, consulte [Instrumentos financeiros](/pt-br/products/payments-direct-2/introduction/concepts/financial-instruments).