Pular para o conteúdo

Atualizar uma identidade

Corredores compatíveis

Para conhecer os corredores de pagamento compatíveis, consulte Payout network.

Este tutorial mostra como usar PUT /v3/identities/{identity-id} para atualizar uma identidade existente no Identity Management v3. Ele cobre a atualização de metadados, campos de PII e validação de payment rail, e explica como funciona o versionamento de identidades e o que isso significa para a sua integração.

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 o escopo participants:update
  • Um identityId de uma identidade criada anteriormente

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

Como funcionam as atualizações de identidade

Versionamento imutável

Toda chamada bem-sucedida a PUT /v3/identities/{identity-id} cria uma nova versão da identidade. A versão anterior é preservada e continua disponível para consulta e auditoria. O identityId nunca muda.

Por exemplo, se uma identidade está em version: 2, uma atualização bem-sucedida produz version: 3. O registro da versão 2 continua acessível por GET /v3/identities/{identity-id}?version=2.

Atualizações parciais

O corpo da requisição PUT aceita atualizações parciais. Você só precisa incluir os campos que quer alterar. Os campos que você omite mantêm os valores atuais.

Por exemplo, para atualizar apenas o nickName, basta enviar nickName no corpo da requisição. Todos os demais dados de PII e metadados são preservados sem alteração.

Efeito sobre os pagamentos

Os pagamentos ficam vinculados a um identityId e a uma version específicos no momento da criação. Atualizar uma identidade cria uma nova versão, mas não afeta os pagamentos que já foram criados com uma versão anterior. Esses pagamentos continuam referenciando a versão da identidade com que foram criados.

O que você pode e o que não pode alterar

Campo(s)Pode atualizar?Observações
nickNameSim—
tagsSimSubstitui integralmente o array de tags existente
internalIdSimPrecisa continuar único entre todas as identidades ACTIVE da sua organização
validatePayoutRailsSimRevalida o PII da identidade contra os rails especificados
Campos de individualSimQualquer campo dentro do objeto individual (endereço, contato, documentos etc.)
Campos de businessSimQualquer campo dentro do objeto business (nome, endereço, contato, registro etc.)
identityTypeNãoDefinido na criação (INDIVIDUAL ou BUSINESS). Não pode ser alterado.
paymentRoleNãoDefinido na criação (ORIGINATOR ou BENEFICIARY). Não pode ser alterado.
Identidades DEACTIVATED

Não é possível atualizar uma identidade DEACTIVATED. A desativação é permanente. Se você precisar retomar a atividade de uma parte desativada, crie uma nova identidade.

Atualizar os metadados da identidade

Os campos de metadados (nickName, tags) são a atualização mais simples. Nenhuma validação de PII é disparada.

Exemplo: atualizar o apelido e as tags

curl -X PUT "https://{base-url}/v3/identities/99254c4f-f207-4792-a846-06928825018c" \
  -H "Authorization: Bearer <access_token>" \
  -H "Content-Type: application/json" \
  -d '{
    "nickName": "Alice Chen - Primary USD",
    "tags": ["usd", "high-value", "verified"]
  }'

Resposta (200 OK)

{
  "identityId": "99254c4f-f207-4792-a846-06928825018c",
  "identityState": "ACTIVE",
  "version": "2",
  "schemaVersion": "1.0.0",
  "identityType": "INDIVIDUAL",
  "paymentRole": "ORIGINATOR",
  "internalId": "customer-12345",
  "nickName": "Alice Chen - Primary USD",
  "tags": ["usd", "high-value", "verified"],
  "createdAt": "2025-10-01T18:46:41.833Z",
  "updatedAt": "2026-03-10T09:15:10.000Z",
  "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"
    }
  }
}

Observe que version passou de 1 para 2 e que updatedAt reflete o momento da atualização. Todos os demais campos permanecem inalterados.

As tags são substituídas, não mescladas

O campo tags é substituído integralmente a cada atualização. Se você enviar "tags": ["usd"], todas as tags anteriores são removidas e substituídas pelo novo valor. Busque a identidade atual antes, se precisar preservar as tags existentes.

Atualizar campos de PII

Atualizar uma identidade INDIVIDUAL

Use isto para corrigir ou atualizar dados pessoais, como endereço, informações de contato ou documentos de identidade.

Exemplo: atualizar o endereço

curl -X PUT "https://{base-url}/v3/identities/99254c4f-f207-4792-a846-06928825018c" \
  -H "Authorization: Bearer <access_token>" \
  -H "Content-Type: application/json" \
  -d '{
    "individual": {
      "address": {
        "streetAddress": ["500 Market Street", "Suite 200"],
        "city": "San Francisco",
        "stateOrProvince": "CA",
        "postalCode": "94103",
        "country": "US"
      }
    }
  }'

Resposta (200 OK)

{
  "identityId": "99254c4f-f207-4792-a846-06928825018c",
  "identityState": "ACTIVE",
  "version": "3",
  "schemaVersion": "1.0.0",
  "identityType": "INDIVIDUAL",
  "paymentRole": "ORIGINATOR",
  "internalId": "customer-12345",
  "nickName": "Alice Chen - Primary USD",
  "tags": ["usd", "high-value", "verified"],
  "createdAt": "2025-10-01T18:46:41.833Z",
  "updatedAt": "2026-03-10T10:22:05.000Z",
  "individual": {
    "firstName": "Alice",
    "lastName": "Chen",
    "dateOfBirth": "1990-05-14",
    "citizenship": "US",
    "address": {
      "streetAddress": ["500 Market Street", "Suite 200"],
      "city": "San Francisco",
      "stateOrProvince": "CA",
      "postalCode": "94103",
      "country": "US"
    }
  }
}

Atualizar uma identidade BUSINESS

Exemplo: atualizar e-mail e telefone

curl -X PUT "https://{base-url}/v3/identities/0116bacc-ffbf-4fa2-a29c-ecd9ea346806" \
  -H "Authorization: Bearer <access_token>" \
  -H "Content-Type: application/json" \
  -d '{
    "business": {
      "email": "ops@widgetsorg.com",
      "phone": "+14155550199"
    }
  }'

Resposta (200 OK)

{
  "identityId": "0116bacc-ffbf-4fa2-a29c-ecd9ea346806",
  "identityState": "ACTIVE",
  "version": "2",
  "schemaVersion": "1.0.0",
  "identityType": "BUSINESS",
  "paymentRole": "BENEFICIARY",
  "internalId": "counterparty-7890",
  "nickName": "Widgets Org MX",
  "tags": ["beneficiary", "mx"],
  "createdAt": "2025-10-01T16:14:13.200Z",
  "updatedAt": "2026-03-10T11:05:30.000Z",
  "business": {
    "businessName": "Widgets Org",
    "incorporationCountry": "US",
    "email": "ops@widgetsorg.com",
    "phone": "+14155550199",
    "registration": [
      {
        "number": "123ABC",
        "type": "INCORPORATION_CERTIFICATE"
      }
    ],
    "address": {
      "streetAddress": ["123 Example MA"],
      "city": "Boston",
      "stateOrProvince": "MS",
      "postalCode": "12345",
      "country": "US"
    }
  }
}

Adicionar ou alterar a validação de payment rail

Use validatePayoutRails para validar o PII de uma identidade contra payment rails adicionais. Isso é útil quando você está cadastrando um beneficiário em um novo corredor que exige campos de PII específicos.

Exemplo: adicionar validação de EU SEPA e GB FPS

curl -X PUT "https://{base-url}/v3/identities/99254c4f-f207-4792-a846-06928825018c" \
  -H "Authorization: Bearer <access_token>" \
  -H "Content-Type: application/json" \
  -d '{
    "validatePayoutRails": ["US_ACH", "EU_SEPA", "GB_FPS"]
  }'

Se o PII atual da identidade atender a todos os requisitos dos rails especificados, a atualização é bem-sucedida e retorna a nova versão. Se faltar algum campo obrigatório para qualquer um dos rails especificados, a requisição retorna 400 Bad Request com detalhes por campo:

{
  "code": "VALIDATION_ERROR",
  "title": "Identity validation failed",
  "description": "The identity is missing required fields for the specified payment rails.",
  "details": [
    {
      "field": "individual.dateOfBirth",
      "message": "Date of birth is required for EU_SEPA beneficiary identities"
    }
  ]
}

Para resolver isso, adicione os campos de PII ausentes à mesma requisição de atualização:

curl -X PUT "https://{base-url}/v3/identities/99254c4f-f207-4792-a846-06928825018c" \
  -H "Authorization: Bearer <access_token>" \
  -H "Content-Type: application/json" \
  -d '{
    "validatePayoutRails": ["US_ACH", "EU_SEPA", "GB_FPS"],
    "individual": {
      "dateOfBirth": "1990-05-14"
    }
  }'
validatePayoutRails é orientativo

Incluir um rail em validatePayoutRails não impede que você adicione instrumentos financeiros para outros rails, e omitir um rail não impede que você o use depois. De qualquer forma, a validação é feita no momento da criação do instrumento financeiro e da iniciação do pagamento.

Atualizar o internalId

Você pode alterar o internalId de uma identidade com uma requisição PUT. O novo valor não pode já estar em uso por outra identidade ACTIVE da sua organização.

Exemplo: renomear um internalId

curl -X PUT "https://{base-url}/v3/identities/99254c4f-f207-4792-a846-06928825018c" \
  -H "Authorization: Bearer <access_token>" \
  -H "Content-Type: application/json" \
  -d '{
    "internalId": "customer-12345-v2"
  }'

Se o internalId solicitado já estiver em uso por outra identidade ACTIVE, a requisição retorna 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-12345-v2' already exists (identityId: 7ea3399c-1234-5678-8d8f-d320ea406630)"
    }
  ]
}

Para orientações sobre o tratamento de conflitos 409, consulte Criar e gerenciar identidades.

Atualizar uma identidade BLOCKED

Uma identidade pode estar no estado BLOCKED se foi sinalizada para análise de compliance ou se foi importada de uma versão anterior da API. Identidades BLOCKED não podem ser usadas para criar novos pagamentos.

Chamar PUT /v3/identities/{identity-id} em uma identidade BLOCKED atualiza os dados da identidade e transiciona o estado dela de BLOCKED de volta para ACTIVE.

Estado BLOCKED e reativação

Um PUT bem-sucedido em uma identidade BLOCKED define identityState como ACTIVE. Confirme com a sua equipe de compliance que a reativação é adequada antes de enviar uma atualização para uma identidade BLOCKED.

Exemplo: atualizar uma identidade BLOCKED

curl -X PUT "https://{base-url}/v3/identities/{identity-id}" \
  -H "Authorization: Bearer <access_token>" \
  -H "Content-Type: application/json" \
  -d '{
    "nickName": "Reviewed and cleared"
  }'

Resposta (200 OK)

{
  "identityId": "{identity-id}",
  "identityState": "ACTIVE",
  "version": "3",
  ...
}

O identityState na resposta é ACTIVE, confirmando que a identidade foi reativada como parte da atualização.

Referência de erros

Status HTTPQuando ocorreO que fazer
400 Bad RequestCampos ausentes ou inválidos, ou PII reprovado na validação dos validatePayoutRails especificadosVerifique o array details[] para ver as mensagens por campo. Corrija a requisição e tente novamente.
404 Not FoundO identity-id não existeConfira o identityId e tente novamente.
409 ConflictO internalId da requisição já está em uso por outra identidade ACTIVEUse a identidade existente ou escolha outro internalId.
500 Internal Server ErrorErro de processamento no lado da RippleTente novamente após um breve intervalo. Entre em contato com o suporte se o erro persistir.

Próximos passos

Create and manage financial instruments

Fetch a quote collection