Skip to main content

​
Visão geral

Sessões biométricas incorporadas são geridas de ponta a ponta pela Gu1. Quando o usuário conclui a captura na UI hospedada, a Gu1 persiste a sessão, aplica as políticas da organização (limiares de face match, cruzamento entre entidades, billing) e envia webhooks com o resultado da sessão. Sua integração deve usar payload.status como desfecho biométrico — o mesmo campo retornado por GET /api/kyc/biometric/sessions/:id. Dois canais de entrega:
  1. Webhooks da organização — inscreva-se em biometric.session_* em configuração de webhooks (todas as transições de status).
  2. webhookUrl por request — URL HTTPS opcional em POST /api/kyc/biometric/sessions; a Gu1 faz POST em desfechos terminais de captura (approved, rejected, abandoned, expired). Cancelamento manual via API dispara apenas webhooks da organização.

​
Tipos de evento

EventoQuando
biometric.session_createdSessão criada (status: pending)
biometric.session_in_progressUsuário iniciou a captura na UI hospedada
biometric.session_approvedSessão biométrica aprovada pela Gu1
biometric.session_rejectedSessão biométrica rejeitada pela Gu1
biometric.session_abandonedUsuário abandonou o fluxo sem concluir
biometric.session_cancelledSessão cancelada na Gu1 (apenas pending / in_progress)
biometric.session_expiredSessão expirada

​
Sobre o payload

Mesma envoltória externa dos eventos KYC: 
{
  "event": "biometric.session_approved",
  "timestamp": "2026-06-11T15:00:00Z",
  "organizationId": "org-uuid",
  "payload": { }
}
O payload interno é a linha da sessão biométrica na Gu1 (mesmo formato da API REST).

​
Campos do payload

  • payload.status — Status da sessão: pending, in_progress, approved, rejected, abandoned, cancelled, expired.
  • payload.rejectionCode / payload.rejectionMessage — Quando status é rejected (ex.: FACE_MATCH_SCORE_LOW, CROSS_ENTITY, CAPTURE_DECLINED).
  • payload.mode — face_match (liveness + comparação com retrato do KYC).
  • payload.sessionUrl — URL de captura enquanto a sessão está ativa.
  • payload.decision — Detalhe técnico da captura (scores, chaves de mídia). Imagens via GET /api/kyc/biometric/sessions/:id/media?key=.
  • payload.entity — Snapshot da entidade pessoa (id, externalId, name, type).

​
Exemplo: sessão criada

{
  "event": "biometric.session_created",
  "timestamp": "2026-06-11T14:00:00Z",
  "organizationId": "org-uuid",
  "payload": {
    "id": "bio-session-uuid",
    "entityId": "entity-uuid",
    "status": "pending",
    "mode": "face_match",
    "sessionUrl": "https://verify.example.com/session/abc",
    "hostedSessionId": "hosted-session-id",
    "rejectionCode": null,
    "rejectionMessage": null,
    "createdAt": "2026-06-11T14:00:00.000Z",
    "entity": {
      "id": "entity-uuid",
      "externalId": "cliente-123",
      "name": "Jane Doe",
      "type": "person"
    }
  }
}

​
Exemplo: em progresso

{
  "event": "biometric.session_in_progress",
  "timestamp": "2026-06-11T14:05:00Z",
  "organizationId": "org-uuid",
  "payload": {
    "id": "bio-session-uuid",
    "entityId": "entity-uuid",
    "status": "in_progress",
    "mode": "face_match",
    "sessionUrl": "https://verify.example.com/session/abc",
    "rejectionCode": null
  }
}

​
Exemplo: aprovada

{
  "event": "biometric.session_approved",
  "timestamp": "2026-06-11T14:10:00Z",
  "organizationId": "org-uuid",
  "payload": {
    "id": "bio-session-uuid",
    "entityId": "entity-uuid",
    "status": "approved",
    "mode": "face_match",
    "rejectionCode": null,
    "completedAt": "2026-06-11T14:10:00.000Z",
    "decision": {
      "face_match": { "status": "Approved", "score": 99.2 },
      "liveness": { "status": "Approved", "score": 98.5 }
    },
    "entity": {
      "id": "entity-uuid",
      "externalId": "cliente-123",
      "name": "Jane Doe",
      "type": "person"
    }
  }
}

​
Exemplo: rejeitada

{
  "event": "biometric.session_rejected",
  "timestamp": "2026-06-11T14:12:00Z",
  "organizationId": "org-uuid",
  "payload": {
    "id": "bio-session-uuid",
    "entityId": "entity-uuid",
    "status": "rejected",
    "mode": "face_match",
    "rejectionCode": "FACE_MATCH_SCORE_LOW",
    "rejectionMessage": "Face match score 28.5 is below organization threshold 30",
    "completedAt": "2026-06-11T14:12:00.000Z",
    "entity": {
      "id": "entity-uuid",
      "externalId": "cliente-123",
      "name": "Jane Doe",
      "type": "person"
    }
  }
}

​
Códigos comuns de rejectionCode

CódigoSignificado
FACE_MATCH_SCORE_LOWScore de face match abaixo do limiar (face_match)
CROSS_ENTITYCaptura corresponde a outra entidade da organização
CAPTURE_DECLINEDCaptura recusada no fluxo hospedado

​
webhookUrl por request

  • Mesmos nomes de event e formato de payload dos webhooks da organização.
  • Assinatura HMAC em X-Webhook-Signature com o webhook secret KYC configurado.
  • Headers adicionais: X-Webhook-Event, X-Webhook-ID, X-Webhook-Timestamp.
Ver verificação de assinatura.
Cancelamento manual (POST /api/kyc/biometric/sessions/:id/cancel) emite biometric.session_cancelled apenas nos webhooks da organização; não faz POST ao webhookUrl do request.