KYC (Verificacao de Identidade)

O template integra verificacao de identidade (Know Your Customer) com suporte a multiplos operadores.

Operadores suportados

Operador	Descricao
CAF	Provedor de identidade digital
Legitimuz	Verificacao por documento + selfie
Pay2Free	Verificacao simplificada
Serasa	Bureau de credito (Brasil)
SumSub	Verificacao global
Unico	Biometria facial
ShieldID	Verificacao por dispositivo

O operador ativo e determinado pela lista de operadores habilitados para o pais do usuario, definida no SDK (@cactus-agents/country-config) — nao no fork.

Os operadores se dividem em dois modelos de integracao, e isso muda como a conclusao e detectada:

Modelo	Operadores	Como o template detecta o fim
Iframe generico	Pay2Free, Serasa, Legitimuz, ShieldID, CAF	Mensagens postMessage do iframe
SDK no browser	Unico, SumSub	Callbacks do proprio SDK (onFinish no Unico, eventos do WebSDK no SumSub)

Fluxo

1. Usuario precisa verificar identidade
   (por deposito, saque, ou regra regulatoria)
       |
       v
2. Modal KYC abre — iframe do operador OU SDK do operador,
   conforme o modelo de integracao
       |
       v
3. Usuario completa a verificacao
       |
       v
4. Template faz polling de status (a cada 5s)
       |
       v
5. Resultado: Aprovado / Reprovado / Pendente manual

Status possiveis

Status	Descricao
PROCESSING	Verificacao em andamento
APPROVED	Aprovado automaticamente
MANUAL_APPROVED	Aprovado manualmente
REPROVED	Reprovado
MANUAL_REPROVED	Reprovado manualmente
MANUAL_APPROVE_PENDING	Aguardando aprovacao manual
LIVENESS_PENDING	Prova de vida pendente

Gatilhos

O KYC pode ser disparado por:

• Validacao pos-registro — se o pais/marca exige KYC apos cadastro
• Deposito — se o contexto de deposito requer KYC
• Saque — se o contexto de saque requer KYC
• Mudanca de senha/dispositivo/IP — por seguranca
• Link de recuperacao — via email/SMS (/user/validate/kyc/:token)

Configuracao

A selecao de operador e automatica: o backend resolve pelo pais do usuario. O fork tem uma knob:

// app/config/features/features.ts (ou o override da sua marca)
kyc: {
  // "prod" (default) | "uat" — ambiente do SDK do Unico.
  unicoEnv: "prod",
},

Marcas em QA podem apontar o SDK do Unico para o ambiente UAT sem nenhuma mudanca no backend. Operadores que rodam por iframe ignoram esse campo.

:::danger Override e substituicao do arquivo inteiro features.ts e substituido por completo quando existe no diretorio da sua marca — sem deep-merge. Copie o arquivo base e edite os valores; flags ausentes chegam como undefined. :::

Operadores por pais

A lista de operadores habilitados por pais vive no @cactus-agents/country-config, que e uma dependencia npm publicada — o fork nao pode alterar. Para habilitar, desabilitar ou trocar a ordem dos operadores do seu pais, abra um pedido para o time da plataforma.