# Criar e gerenciar identidades 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). Este tutorial mostra como usar os endpoints de identidade do **Identity Management v3** para: - Criar uma nova identidade - Recuperar uma identidade por ID (e por versão) - Listar identidades com filtros e paginação - Atualizar os dados de uma identidade - Desativar uma identidade Ele parte do modelo descrito em [Identidades do pagamento](/pt-br/products/payments-direct-2/introduction/concepts/payment-identities) e foca no schema de identidade v3. internalId Um comportamento central da v3 é que **no máximo uma identidade ACTIVE** no seu ambiente pode usar um determinado `internalId`. Tentativas de criar ou atualizar uma identidade de modo que o `internalId` dela colida com o de outra identidade ACTIVE resultam em **409 Conflict**. ## Antes de começar Para seguir estes exemplos, você precisa de: - URL base do Identity Management (por exemplo, `https://{base-url}`) - Um token de acesso com os seguintes escopos (ou equivalentes): - `participants:create `para criar identidades - `participants:read` para ler e listar identidades - `participants:update` para atualizar e desativar identidades - O modelo de identidade v3 de **Identidades do pagamento** (INDIVIDUAL vs BUSINESS e ORIGINATOR vs BENEFICIARY) Em todos os exemplos abaixo, substitua: - `{base-url}` pela sua URL base de PII real - `` por um token de acesso OAuth2 válido - `{identity-id} `por um `identityId` real retornado pela API ## Criar uma identidade Use `POST /v3/identities` para criar uma nova identidade. No mínimo, você precisa informar: - `identityType` – INDIVIDUAL ou BUSINESS - `paymentRole` – ORIGINATOR ou BENEFICIARY - Os dados de pessoa física ou de empresa, conforme o `identityType` - `internalId` para identidades ORIGINATOR Para identidades **BENEFICIARY**, o `internalId` é opcional, mas recomendado se você quiser vincular beneficiários aos seus próprios registros de clientes. Deduplicação via internalId O Identity Management v3 garante que no máximo uma identidade **ACTIVE** por organização possa usar um determinado `internalId`. - Se você tentar criar uma identidade e o `internalId` informado já estiver em uso por outra identidade **ACTIVE**, a requisição falha com **409 Conflict**. - Você pode tratar esse erro na sua integração para sinalizar situações de “cliente duplicado” ou orientar os usuários a reutilizar a identidade existente. Número da conta do ordenante para pagamentos em USD à China Alguns corredores exigem o número da conta do próprio ordenante. Envie-o em `originatorAccountNumber`, e não em `internalId`. Em uma identidade de ordenante validada em relação a `CN_CFXPS` (pagamentos em USD à China), omitir `originatorAccountNumber` falha com **400 Bad Request** (`USR_111`), e um UUID gerado aleatoriamente ou outra referência arbitrária faz o payout ser rejeitado. Consulte [O número da conta do ordenante](/pt-br/products/payments-direct-2/introduction/concepts/payment-identities#o-n%C3%BAmero-de-conta-do-ordenante). Documentos de identidade na jurisdição do Brasil (BR) Se a sua organização estiver configurada para a jurisdição do Brasil (BR), `identityDocuments` é obrigatório em toda identidade ORIGINATOR, em todos os corredores, inclusive naqueles que de outra forma não o exigiriam. Omiti-lo falha com **400 Bad Request** (`USR_111`). Isso vale tanto para atualizações quanto para criações. Uma atualização valida o corpo que você envia, não o registro já armazenado, portanto uma atualização que omita `identityDocuments` falha mesmo quando você está alterando algo não relacionado. Consulte [Requisitos por jurisdição](/pt-br/products/payments-direct-2/introduction/concepts/payment-identities#requisitos-por-jurisdi%C3%A7%C3%A3o). Opcionalmente, você também pode: - Definir um `nickName` amigável e `tags` - Adicionar `validatePayoutRails` para validar a identidade contra payment rails específicos (por exemplo, `US_ACH`, `BR_PIX`, `MX_SPEI`) **Exemplo: criar um INDIVIDUAL ORIGINATOR** ```bash curl -X POST "https://{base-url}/v3/identities" \ -H "Authorization: Bearer " \ -H "Content-Type: application/json" \ -d '{ "identityType": "INDIVIDUAL", "paymentRole": "ORIGINATOR", "internalId": "customer-12345-uuid", "nickName": "Alice Sender USD", "tags": ["sender", "priority"], "validatePayoutRails": ["US_ACH"], "individual": { "firstName": "Alice", "lastName": "Chen", "dateOfBirth": "1990-05-14", "citizenship": "US", "address": { "streetAddress": ["123 Main Street"], "city": "San Francisco", "stateOrProvince": "CA", "postalCode": "94105", "country": "US" } } }' ``` **Resposta (201 Created)** ```json { "identityId": "99254c4f-f207-4792-a846-06928825018c", "version": "1" } ``` Deduplicação via internalId Se você enviar outro `POST /v3/identities` com o mesmo `internalId` enquanto esta identidade ainda estiver ACTIVE, o serviço retorna: - **409 Conflict** – indicando que outra identidade **ACTIVE** já usa esse `internalId`. Trate o 409 como um sinal de que você deve localizar e reutilizar a identidade existente em vez de criar uma duplicada. **Exemplo: criar um BUSINESS BENEFICIARY** ```bash curl -X POST "https://{base-url}/v3/identities" \ -H "Authorization: Bearer " \ -H "Content-Type: application/json" \ -d '{ "identityType": "BUSINESS", "paymentRole": "BENEFICIARY", "internalId": "counterparty-7890", "nickName": "Widgets Org MX", "tags": ["beneficiary", "mx"], "validatePayoutRails": ["MX_SPEI"], "business": { "businessName": "Widgets Org", "incorporationCountry": "US", "registration": [ { "number": "123ABC", "type": "INCORPORATION_CERTIFICATE" } ], "email": "fake@example.com", "phone": "+1234567890", "address": { "streetAddress": ["123 Example MA"], "city": "Boston", "stateOrProvince": "MS", "postalCode": "12345", "country": "US" } } }' ``` **Resposta (201 Created)** ```json { "identityId": "0116bacc-ffbf-4fa2-a29c-ecd9ea346806", "version": "1" } ``` PII ausente ou inválido Se algum dado de PII obrigatório estiver ausente ou inválido para os rails em `validatePayoutRails`, a API retorna um erro 400 descrevendo quais campos falharam na validação. **Exemplo: falha de validação por campos obrigatórios ausentes** Se você tentar criar uma identidade com `validatePayoutRails: ["US_ACH"]` mas omitir campos obrigatórios como `identityDocuments`, receberá: **Resposta (400 Bad Request)** ```json { "code": "VALIDATION_ERROR", "title": "Identity validation failed", "description": "The identity is missing required fields for the specified payment rails.", "details": [ { "field": "individual.identityDocuments", "message": "At least one identity document (SSN or Tax ID) is required for US_ACH beneficiary identities" } ] } ``` Para corrigir isso, adicione os campos ausentes e envie a requisição novamente. **Exemplo: falha de validação por tipo de documento não compatível** Alguns corredores aceitam apenas um subconjunto do enum `idType` (pessoa física) ou `registration.type` (empresa), e a API rejeita os tipos não compatíveis com um erro 400. Por exemplo, ordenantes `KR_KFTC` aceitam apenas `PASSPORT`, portanto enviar `NATIONAL_ID_NUMBER` falha: **Resposta (400 Bad Request)** ```json { "code": "VALIDATION_ERROR", "title": "Identity validation failed", "description": "The identity uses a document type that is not supported for the specified payment rails.", "details": [ { "field": "individual.identityDocuments.idType", "message": "Document type NATIONAL_ID_NUMBER is not accepted for KR_KFTC originator identities. Accepted values: PASSPORT." } ] } ``` Para ver os tipos de documento aceitos por corredor e papel, consulte [Tipos de documento aceitos por corredor](/pt-br/products/payments-direct-2/introduction/concepts/payment-identities#tipos-de-documento-aceitos-por-corredor). ## Tratamento de conflitos de `internalId` (409 Conflict) Quando você cria ou atualiza uma identidade com um `internalId` que já está em uso por outra identidade **ACTIVE**, a API retorna **409 Conflict**. Este é um **recurso de deduplicação** que evita que você crie acidentalmente várias identidades para o mesmo cliente. ### Exemplo: `internalId` duplicado na criação **Requisição:** ```bash curl -X POST "https://{base-url}/v3/identities" \ -H "Authorization: Bearer " \ -H "Content-Type: application/json" \ -d '{ "identityType": "INDIVIDUAL", "paymentRole": "BENEFICIARY", "internalId": "customer-12345-uuid", "individual": { "firstName": "Bob", "lastName": "Smith", "address": { "streetAddress": ["456 Oak Ave"], "city": "Austin", "stateOrProvince": "TX", "postalCode": "78701", "country": "US" } } }' ``` **Resposta (409 Conflict)** ```json { "code": "CONFLICT", "title": "Identity conflict", "description": "An identity with the provided internalId already exists.", "details": [ { "field": "internalId", "message": "An ACTIVE identity with internalId 'customer-12345-uuid' already exists (identityId: 99254c4f-f207-4792-a846-06928825018c)" } ] } ``` ### Como tratar o 409 Conflict Quando você receber um 409 Conflict: 1. **Localize a identidade existente** usando o `identityId` da mensagem de erro 2. **Reutilize a identidade existente** em vez de criar uma nova 3. **Atualize a identidade existente** se necessário (por exemplo, para adicionar novos dados de PII ou alterar `validatePayoutRails`) 4. **Investigue os seus sistemas upstream** se estiver recebendo conflitos inesperados (isso pode indicar registros de clientes duplicados no seu CRM ou banco de dados) **Exemplo: localizar a identidade existente** ```bash curl -X GET "https://{base-url}/v3/identities/99254c4f-f207-4792-a846-06928825018c" \ -H "Authorization: Bearer " ``` Se a identidade existente estiver correta, use-a na criação do seu pagamento ou instrumento financeiro. Se ela precisar de atualizações, use `PUT /v3/identities/{identity-id}` para modificá-la. ### Exemplo: `internalId` duplicado na atualização **Requisição:** ```bash curl -X PUT "https://{base-url}/v3/identities/1d927c62-45fa-4f42-b9f8-8210e1a111bb" \ -H "Authorization: Bearer " \ -H "Content-Type: application/json" \ -d '{ "internalId": "customer-99999" }' ``` Se `customer-99999` já estiver em uso por uma identidade ACTIVE diferente: **Resposta (409 Conflict)** ```json { "code": "CONFLICT", "title": "Identity conflict", "description": "The provided internalId already exists on a different identity.", "details": [ { "field": "internalId", "message": "An ACTIVE identity with internalId 'customer-99999' already exists (identityId: 7ea3399c-1234-5678-8d8f-d320ea406630)" } ] } ``` ### Boas práticas para conflitos de `internalId` - **Use chaves upstream estáveis** – use o ID de cliente do seu CRM, o ID de cliente do core bancário ou o ID do registro mestre de KYC como `internalId` - **Mantenha-o como a sua própria chave** – você não precisa adaptar o `internalId` para nenhum corredor. Os corredores que precisam do número da conta do ordenante leem `originatorAccountNumber`. Consulte [O número da conta do ordenante](/pt-br/products/payments-direct-2/introduction/concepts/payment-identities#o-n%C3%BAmero-de-conta-do-ordenante) - **Implemente uma lógica de criação idempotente** – ao criar identidades, capture os erros 409 e localize a identidade existente em vez de falhar - **Evite PII no `internalId`** – não use e-mails, telefones ou documentos nacionais diretamente; use identificadores opacos - **Monitore os conflitos** – acompanhe os erros 409 nos seus logs para identificar problemas de qualidade de dados nos sistemas upstream ## Obter uma identidade por ID (e versão) Use `GET /v3/identities/{identity-id}` para recuperar uma identidade específica. - Se você omitir o parâmetro de consulta version, a versão mais recente é retornada. - Para recuperar uma versão específica, inclua `?version={version-number}`. **Exemplo: obter a versão mais recente** ```bash curl -X GET "https://{base-url}/v3/identities/9d839f58-7fd3-4913-a27e-48d31973d3f9" \ -H "Authorization: Bearer " ``` **Resposta (200 OK)** ```json { "identityId": "9d839f58-7fd3-4913-a27e-48d31973d3f9", "identityState": "ACTIVE", "nickName": "nickName", "tags": ["tag1"], "version": "2", "schemaVersion": "1.0.0", "createdAt": "2025-10-01T18:46:41.833Z", "updatedAt": "2025-10-01T18:46:47.430Z", "identityType": "BUSINESS", "paymentRole": "BENEFICIARY", "internalId": "counterparty-7890", "business": { "businessName": "Widgets Org", "address": { "streetAddress": ["123 Example MA"], "country": "US", "city": "Boston", "stateOrProvince": "MS", "postalCode": "12345" }, "email": "fake@example.com", "phone": "+1234567890", "registration": [ { "number": "123ABC", "type": "INCORPORATION_CERTIFICATE" } ], "incorporationCountry": "US" } } ``` **Exemplo: obter uma versão específica** ```bash curl -X GET "https://{base-url}/v3/identities/9d839f58-7fd3-4913-a27e-48d31973d3f9?version=1" \ -H "Authorization: Bearer " ``` Consultas versionadas Use consultas versionadas quando precisar: - Comparar mudanças ao longo do tempo para auditoria - Conciliar pagamentos que usaram uma versão anterior de uma identidade Se a identidade ou a versão não existir, o serviço retorna **404 Not Found**. ## Obter uma identidade pelo ID interno Use `GET /v3/identities/by-internal-id/{internal-id}` para localizar uma identidade diretamente pelo `internalId` fornecido por você, sem precisar saber antes o `identityId` gerado pelo servidor. Este endpoint é especialmente útil para: - Resolver o `identityId` de uma identidade de cliente existente quando você tem apenas a sua própria referência (por exemplo, um ID de cliente do CRM). - Implementar fluxos idempotentes de criar-ou-buscar sem armazenar o `identityId` separadamente. - Tratar respostas 409 Conflict localizando imediatamente a identidade conflitante. **Exemplo: localizar uma identidade pelo ID interno** ```bash curl -X GET "https://{base-url}/v3/identities/by-internal-id/customer-12345-uuid" \ -H "Authorization: Bearer " ``` **Resposta (200 OK)** ```json { "identityId": "99254c4f-f207-4792-a846-06928825018c", "identityState": "ACTIVE", "identityType": "INDIVIDUAL", "paymentRole": "ORIGINATOR", "internalId": "customer-12345-uuid", "nickName": "Alice Sender USD", "tags": ["sender", "priority"], "version": "1", "schemaVersion": "1.0.0", "createdAt": "2025-10-01T18:46:41.833Z", "updatedAt": "2025-10-01T18:46:47.430Z", "individual": { "firstName": "Alice", "lastName": "Chen", "dateOfBirth": "1990-05-14", "citizenship": "US", "address": { "streetAddress": ["123 Main Street"], "city": "San Francisco", "stateOrProvince": "CA", "postalCode": "94105", "country": "US" } } } ``` Apenas identidades ACTIVE Este endpoint retorna a identidade apenas se ela estiver **ACTIVE** no momento. Se a identidade existir mas tiver sido desativada ou bloqueada, o serviço retorna **404 Not Found**. A consulta é restrita à sua organização. Valores de `internalId` de outras organizações não geram conflito. Respostas de erro: - **404 Not Found** – não existe nenhuma identidade ACTIVE com o `internalId` especificado na sua organização ## Listar identidades Use `GET /v3/identities` para recuperar as identidades da sua organização com filtros e paginação opcionais. Parâmetros de consulta compatíveis: - `payment-role` – filtra por papel de pagamento (ORIGINATOR ou BENEFICIARY) - `nick-name` – filtra por apelido (correspondência exata) - `limit` – número máximo de identidades a retornar (de 1 a 100, padrão 10) - `next-token` – token opaco retornado em uma resposta anterior, usado para buscar a próxima página **Exemplo: listar identidades por papel** ```bash curl -X GET "https://{base-url}/v3/identities?payment-role=BENEFICIARY&limit=2" \ -H "Authorization: Bearer " ``` **Resposta (200 OK)** ```json { "data": [ { "identityId": "0116bacc-ffbf-4fa2-a29c-ecd9ea346806", "identityType": "BUSINESS", "paymentRole": "BENEFICIARY", "createdAt": "2025-10-01T16:14:13.200Z", "updatedAt": "2025-10-01T16:14:15.763Z", "identityState": "ACTIVE", "nickName": "testNickName", "tags": ["tag1"], "version": 2, "schemaVersion": "1.0.0", "internalId": "counterparty-7890" }, { "identityId": "1d927c62-45fa-4f42-b9f8-8210e1a111bb", "identityType": "INDIVIDUAL", "paymentRole": "ORIGINATOR", "createdAt": "2025-10-01T17:20:05.111Z", "updatedAt": "2025-10-01T17:20:06.500Z", "identityState": "ACTIVE", "nickName": "Alice Originator", "tags": ["sender", "priority"], "version": 1, "schemaVersion": "1.0.0", "internalId": "customer-12345-uuid" } ], "nextToken": "eyJrZXkxIjoidmFsdWUifQ==" } ``` Se você receber um `nextToken`, devolva-o como `next-token` para buscar a próxima página: ```bash curl -X GET "https://{base-url}/v3/identities?payment-role=BENEFICIARY&limit=2&next-token=eyJrZXkxIjoidmFsdWUifQ==" \ -H "Authorization: Bearer " ``` Nenhuma identidade encontrada Se nenhuma identidade corresponder aos seus filtros, o serviço retorna **404 Not Found**. ## Atualizar uma identidade Use `PUT /v3/identities/{identity-id}` para atualizar uma identidade existente. Cada atualização bem-sucedida cria uma **nova versão da identidade**. O `identityId` nunca muda, e as versões anteriores continuam disponíveis para consulta e auditoria. O corpo da requisição aceita **atualizações parciais**. Inclua apenas os campos que você quer alterar. Você pode atualizar: - Metadados: `nickName`, `tags` - PII: qualquer campo dentro de `individual` ou `business` - `internalId` (precisa continuar único entre todas as identidades ACTIVE) - `validatePayoutRails` (revalida o PII contra os rails especificados) O `identityType` e o `paymentRole` não podem ser alterados após a criação. Para ver exemplos completos, tratamento de erros e orientações sobre a atualização de identidades BLOCKED, consulte [Atualizar uma identidade](/pt-br/products/payments-direct-2/api-docs/developer-guides/update-an-identity). ## Desativar uma identidade Use `DELETE /v3/identities/{identity-id}` para desativar uma identidade. A desativação: - Define o estado da identidade como **DEACTIVATED** - Desativa os **instrumentos financeiros** associados à identidade - Impede que **novos pagamentos** usem esta identidade - Mantém as versões históricas disponíveis para auditoria Permanente A desativação é **permanente**; não é possível reativar uma identidade desativada. **Exemplo: desativar uma identidade** ```bash curl -X DELETE "https://{base-url}/v3/identities/146f3c51-c313-47ce-b6f2-691c5a238b3e" \ -H "Authorization: Bearer " ``` **Resposta (204 No Content) – a identidade foi desativada com sucesso.** Respostas de erro: - **400 Bad Request** – requisição malformada ou formato inválido de `identityId` - **404 Not Found** – a identidade não existe - **422 Unprocessable Entity** – a identidade já está desativada ou não pode ser desativada (por exemplo, por restrições internas) ## Tratamento de erros e validação Todos os endpoints de identidade usam um schema padrão de resposta de erro com: - **code** – código de erro legível por máquina - **title** – resumo curto legível por humanos - **description** – explicação detalhada e sugestões de correção Casos comuns: - **400** – campos ausentes ou inválidos na requisição, ou identidade reprovada nas regras de validação específicas do corredor - **404** – identidade não encontrada (para um ID, versão ou consulta específicos) - **409** – conflito de `internalId` (outra identidade ACTIVE já usa o mesmo `internalId`) - **422** – transição de ciclo de vida inválida (por exemplo, tentar desativar uma identidade já desativada) - **500** – erro interno de processamento; tente novamente ou entre em contato com o suporte se persistir Consulte a seção geral de [Tratamento de erros](/pt-br/products/payments-direct-2/api-docs/error-handling/api-errors) da documentação da API para ver a lista completa de códigos de erro. ## Próximos passos - Para uma explicação mais aprofundada do modelo de identidade, consulte [Identidades do pagamento](/pt-br/products/payments-direct-2/introduction/concepts/payment-identities). - Para ver exemplos completos de atualização e orientações sobre versionamento imutável, validação de payment rail e reativação de identidades BLOCKED, consulte [Atualizar uma identidade](/pt-br/products/payments-direct-2/api-docs/developer-guides/update-an-identity). - Para saber como vincular dados de conta de payout às identidades (contas bancárias, carteiras, payment rails locais), continue com [Criar e gerenciar instrumentos financeiros](/pt-br/products/payments-direct-2/api-docs/developer-guides/create-and-manage-financial-instruments).