KYC Verificação de identidade

Como pedir a verificação de identidade de uma pessoa — prova de vida, comparação do rosto com o documento e idade mínima — e como ler o resultado.

Como funciona (visão geral)

1. Seu backend cria uma sessão e recebe um facelink_url.
2. Você abre o facelink para o usuário (redirect, webview ou iframe).
3. O usuário faz a prova de vida — e envia o documento, se for pedido.
4. No fim, a página volta para o seu callback_url com status e session_id.
5. Seu backend consulta a sessão para ler o resultado completo.

1. Crie a sessão

Chamada servidor-a-servidor com a sua chave de API (X-Api-Key: sk_…). O subject é o identificador da pessoa no seu sistema.

curl -X POST https://api.paygrid.tech/v1/kyc/sessions \
  -H "X-Api-Key: sk_sua_chave" \
  -H "Content-Type: application/json" \
  -d '{
    "subject": "user_123",
    "flow": "liveness",
    "min_age": 18,
    "reference": "pedido-4211",
    "callback_url": "https://sua-loja.com/kyc/retorno",
    "cancel_url": "https://sua-loja.com/kyc/cancelado"
  }'

Resposta (201):

{
  "session_id": "0f2c…",
  "subject": "user_123",
  "flow": "liveness",
  "min_age": 18,
  "status": "initiated",
  "facelink_url": "https://kyc.paygrid.tech/verify/0f2c…?tenant_id=acme&signature=…",
  "signature": "…",
  "callback_url": "https://sua-loja.com/kyc/retorno",
  "expires_at": "2026-09-24T18:00:00Z",
  "created_at": "2026-09-24T17:00:00Z"
}

2. Abra o facelink para o usuário

Redirecione o navegador do usuário para o facelink_url (ou abra numa webview/iframe). A página é responsiva, pede acesso à câmera e guia a captura. Não é preciso passar nada além da URL.

<a href="https://kyc.paygrid.tech/verify/0f2c…?tenant_id=acme&signature=…">
  Verificar minha identidade
</a>

3. O que acontece na página

• Introdução: explica os passos.
• Prova de vida: o usuário enquadra o rosto na máscara e segue as instruções (olhar para a câmera, virar à esquerda, virar à direita). Tudo automático.
• Documento (quando necessário): fotos da frente e do verso. O OCR é feito no servidor.
• Fim: a página redireciona para o seu callback.

4. Receba o callback

No fim, a página volta para o seu callback_url (ou cancel_url), com o resultado na query string:

https://sua-loja.com/kyc/retorno?status=approved&session_id=0f2c…
https://sua-loja.com/kyc/retorno?status=denied&session_id=0f2c…
https://sua-loja.com/kyc/cancelado?status=cancelled&session_id=0f2c…

5. Leia o resultado

Consulte a sessão para ver o desfecho completo:

curl https://api.paygrid.tech/v1/kyc/sessions/{session_id} \
  -H "X-Api-Key: sk_sua_chave"

{
  "session_id": "0f2c…",
  "subject": "user_123",
  "flow": "liveness",
  "min_age": 18,
  "status": "approved",
  "liveness": { "is_live": true, "liveness_score": 0.98 },
  "age": { "estimated_age": 33, "age_confidence": 0.8 },
  "face_match": { "match": true, "similarity_score": 0.62 },
  "document": { "cpf": "03127085567", "name": "LEONARDO R. DA SILVA CASTRO", "birthdate": "1992-06-11" },
  "selfie_url": "https://… (URL assinada, expira)",
  "document_url": "https://… (URL assinada, expira)",
  "denied_reason": "idade estimada abaixo do mínimo",
  "created_at": "2026-09-24T17:00:00Z",
  "updated_at": "2026-09-24T17:03:10Z"
}

Campos da resposta:

Status da sessão

Enquanto a sessão estiver em processing / requires_document, consulte de novo depois — o usuário pode estar no meio do fluxo. Trate como final apenas approved, denied e requires_manual.

Fluxos

Análise manual

Quando a sessão fica requires_manual, ela aparece no dashboard com as imagens (selfie e documento) e o motivo. Um operador aprova ou nega:

curl -X POST https://api.paygrid.tech/v1/kyc/sessions/{session_id}/approve \
  -H "X-Api-Key: sk_sua_chave" -H "Content-Type: application/json" \
  -d '{"reason": "documento legível e idade confirmada"}'

# ou negar
curl -X POST https://api.paygrid.tech/v1/kyc/sessions/{session_id}/deny \
  -H "X-Api-Key: sk_sua_chave" -H "Content-Type: application/json" \
  -d '{"reason": "documento ilegível"}'

Imagens e privacidade

• As imagens ficam em armazenamento privado e são destruídas em ~1 hora.
• selfie_url e document_url são URLs assinadas de curta duração (~15 min) — baixe o que precisar logo após a decisão.
• Use as imagens apenas para a finalidade da verificação (LGPD).

Erros comuns