Verificação de identidade

A API cria uma prova independente de conta para proteger redefinição de senha, reset de segundo fator, transação de alto valor ou outra ação sensível. O backend do banco cria a jornada para um CPF, entrega o link ao correntista e consome a aprovação uma única vez antes de concluir a ação.

Pré-requisitos

• token client_credentials da master;
• host https://client.api.corpx.com e os três headers de assinatura;
• X-Tenant-Id;
• escopo identity_verification.manage;
• feature identity_verification habilitada para criar jornadas;
• callbackUri previamente cadastrada, com comparação exata.

O download de evidências usa o escopo dedicado kyc.read.

Criar

curl -X POST "https://client.api.corpx.com/v1/identity-verifications" \
  -H "Authorization: Bearer $TOKEN" \
  -H "X-Tenant-Id: $TENANT_ID" \
  -H "X-Request-Timestamp: $TS" \
  -H "X-Content-SHA256: $BODY_SHA256" \
  -H "X-Request-Signature: $SIGNATURE" \
  -H "Content-Type: application/json" \
  -d '{
    "document": "12345678909",
    "purpose": "second_factor_reset",
    "referenceId": "reset_01J8Y6N7M8P9Q0R1S2T3",
    "displayMessage": "Confirme sua identidade para cadastrar o novo dispositivo.",
    "callbackUri": "https://ib.example.com/identity-verification/return",
    "ttlMinutes": 30,
    "consumeTtlMinutes": 10
  }'

document é um CPF de 11 dígitos. referenceId é obrigatório e identifica a ação no seu sistema. As finalidades aceitas são password_reset, second_factor_reset, high_value_transaction e sensitive_action. displayMessage é texto simples opcional de até 240 caracteres. ttlMinutes tem padrão 30 e consumeTtlMinutes, 10; ambos têm máximo 60.

Não envie Idempotency-Key: cada POST abre intencionalmente uma prova nova e consome uma unidade da cota quando responde 201.

Resposta 201:

{
  "verificationId": "idv_01J8Y7C8D9E0F1G2H3J4",
  "status": "PENDING",
  "verificationLink": "https://tenant.api.corpx.com/v1/identity-verifications/verify#capability-redacted",
  "expiresAt": "2026-09-24T14:30:00Z"
}

Consultar

curl "https://client.api.corpx.com/v1/identity-verifications/$VERIFICATION_ID" \
  -H "Authorization: Bearer $TOKEN" \
  -H "X-Tenant-Id: $TENANT_ID" \
  -H "X-Request-Timestamp: $TS" \
  -H "X-Content-SHA256: e3b0c44298fc1c149afbf4c8996fb92427ae41e4649b934ca495991b7852b855" \
  -H "X-Request-Signature: $SIGNATURE"

A resposta inclui purpose, referenceId, document, provider, expiresAt, failureReason, completedAt, consumableUntil e consumedAt quando aplicáveis. verificationLink só existe em PENDING.

Consumir

curl -X POST \
  "https://client.api.corpx.com/v1/identity-verifications/$VERIFICATION_ID/consume" \
  -H "Authorization: Bearer $TOKEN" \
  -H "X-Tenant-Id: $TENANT_ID" \
  -H "X-Request-Timestamp: $TS" \
  -H "X-Content-SHA256: $BODY_SHA256" \
  -H "X-Request-Signature: $SIGNATURE" \
  -H "Content-Type: application/json" \
  -d '{
    "purpose": "second_factor_reset",
    "referenceId": "reset_01J8Y6N7M8P9Q0R1S2T3"
  }'

A finalidade e a referência precisam coincidir exatamente com a criação. A primeira chamada válida grava consumedAt. Repetir o mesmo id e o mesmo corpo é idempotente; finalidade/referência diferentes, consumo concorrente, estado não aprovado ou janela vencida respondem 409.

Consuma no backend imediatamente antes da ação protegida. Ver APPROVED no GET não reserva a prova e, sozinho, não impede reutilização concorrente.

Callback e webhook

A callbackUri só devolve o navegador. Ela precisa ser idêntica à URI cadastrada — sem wildcard, prefixo ou normalização — e não prova o resultado.

identity.verification.completed é enviado para APPROVED, FAILED e EXPIRED, com X-Signature. Valide os bytes brutos e deduplique pelo id do envelope. Exemplo completo em Webhooks da conta.

Evidências

GET /v1/identity-verifications/{verificationId}/artifacts exige kyc.read no lugar do escopo de gerenciamento e a feature kyc_artifacts. Assine a chamada como qualquer outra no host client. O retorno pode conter biometria e evidências do provedor; não registre URLs nem conteúdo em logs.

Erros principais