Identidades do pagamento

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.

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.

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

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.

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.

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

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

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

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

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

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.

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.

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.

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

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.

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

Para detalhes específicos de corredor, consulte Recursos de integração.

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.

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.

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

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:

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

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.

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.

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.

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

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.

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.

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

Cada elemento de individual.identityDocuments tem a seguinte estrutura:

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

Cada elemento de business.registration tem a seguinte estrutura:

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.

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.

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

O Utilitário de schema de payload tem uma seleção de Jurisdição. 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.

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)

Identidades de empresa (registration.type)

• 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.
• Para entender como as identidades se conectam aos dados de conta de pagamento, consulte Instrumentos financeiros.