Criar e gerenciar identidades

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 e foca no schema de identidade v3.

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
• <access_token> por um token de acesso OAuth2 válido
• {identity-id} por um identityId real retornado pela API

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.

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

curl -X POST "https://{base-url}/v3/identities" \
  -H "Authorization: Bearer <access_token>" \
  -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)

{
  "identityId": "99254c4f-f207-4792-a846-06928825018c",
  "version": "1"
}

Exemplo: criar um BUSINESS BENEFICIARY

curl -X POST "https://{base-url}/v3/identities" \
  -H "Authorization: Bearer <access_token>" \
  -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)

{
  "identityId": "0116bacc-ffbf-4fa2-a29c-ecd9ea346806",
  "version": "1"
}

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)

{
  "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)

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

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.

Requisição:

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-uuid",
    "individual": {
      "firstName": "Bob",
      "lastName": "Smith",
      "address": {
        "streetAddress": ["456 Oak Ave"],
        "city": "Austin",
        "stateOrProvince": "TX",
        "postalCode": "78701",
        "country": "US"
      }
    }
  }'

Resposta (409 Conflict)

{
  "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)"
    }
  ]
}

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

curl -X GET "https://{base-url}/v3/identities/99254c4f-f207-4792-a846-06928825018c" \
  -H "Authorization: Bearer <access_token>"

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.

Requisição:

curl -X PUT "https://{base-url}/v3/identities/1d927c62-45fa-4f42-b9f8-8210e1a111bb" \
  -H "Authorization: Bearer <access_token>" \
  -H "Content-Type: application/json" \
  -d '{
    "internalId": "customer-99999"
  }'

Se customer-99999 já estiver em uso por uma identidade ACTIVE diferente:

Resposta (409 Conflict)

{
  "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)"
    }
  ]
}

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

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

curl -X GET "https://{base-url}/v3/identities/9d839f58-7fd3-4913-a27e-48d31973d3f9" \
  -H "Authorization: Bearer <access_token>"

Resposta (200 OK)

{
  "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

curl -X GET "https://{base-url}/v3/identities/9d839f58-7fd3-4913-a27e-48d31973d3f9?version=1" \
  -H "Authorization: Bearer <access_token>"

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

curl -X GET "https://{base-url}/v3/identities/by-internal-id/customer-12345-uuid" \
  -H "Authorization: Bearer <access_token>"

Resposta (200 OK)

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

Respostas de erro:

• 404 Not Found – não existe nenhuma identidade ACTIVE com o internalId especificado na sua organização

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

curl -X GET "https://{base-url}/v3/identities?payment-role=BENEFICIARY&limit=2" \
  -H "Authorization: Bearer <access_token>"

Resposta (200 OK)

{
  "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:

curl -X GET "https://{base-url}/v3/identities?payment-role=BENEFICIARY&limit=2&next-token=eyJrZXkxIjoidmFsdWUifQ==" \
  -H "Authorization: Bearer <access_token>"

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.

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

Exemplo: desativar uma identidade

curl -X DELETE "https://{base-url}/v3/identities/146f3c51-c313-47ce-b6f2-691c5a238b3e" \
  -H "Authorization: Bearer <access_token>"

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)

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 da documentação da API para ver a lista completa de códigos de erro.

• Para uma explicação mais aprofundada do modelo de identidade, consulte Identidades do pagamento.
• 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.
• 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.