KYC

Integracao de verificacao de identidade (Know Your Customer) no template. Suporta multiplos operadores via o pacote @cactus-agents/kyc.

Visao geral

Usuario clica "Iniciar verificacao"
    │
    ▼
useKycFlow → POST /api/kyc/start
    │
    ▼
API retorna URL do iframe + kycId + operador
    │
    ▼
KycModal renderiza iframe do operador
    │
    ▼
Polling: POST /api/kyc/status (a cada 5s)
    │
    ├── PROCESSING / LIVENESS_PENDING → continua polling
    ├── APPROVED / MANUAL_APPROVED    → step: "validated" → onValidated()
    ├── REPROVED / MANUAL_REPROVED    → step: "failed"
    └── MANUAL_APPROVE_PENDING        → step: "manual_refresh"

Arquivos principais

Arquivo	Tipo	Descricao
hooks/useKycFlow.ts	Hook	Orquestra start, iframe, polling de status
store/kyc.ts	Store (Zustand)	Estado completo do fluxo KYC
components/kyc/KycModal.tsx	Component	Modal com iframe do operador
components/kyc/LazyKycModal.tsx	Component	Lazy wrapper para o modal
services/kyc.client.ts	Service (client)	Chama API routes de KYC
services/kyc.server.ts	Service (server)	Chama SDK KYC no server
routes/api.kyc.start.ts	API Route	Inicia KYC via SDK
routes/api.kyc.status.ts	API Route	Consulta status via SDK

Store — useKycStore

interface KycState {
  open: boolean;
  source: string;                    // contexto que disparou (global, deposit, etc.)
  recoveryToken: string | null;      // token de link de recuperacao

  kycId: number | null;              // ID da verificacao
  operator: KycOperatorName | null;  // operador ativo
  iframeUrl: string;                 // URL do iframe
  flow: KycFlowType;                 // "default" | "mobile" | "manual_approve_pending"
  step: KycVerificationStep;         // estado atual do fluxo

  isKycLoading: boolean;
  isCheckStatusLoading: boolean;
  isPollingRunning: boolean;
  error: string | null;

  reloadOnValidated: boolean;
  onValidated: ((payload) => void) | null;

  openKycModal(options?: OpenKycOptions): void;
  closeKycModal(): void;
  // ... setters
}

Steps do fluxo

Step	Descricao
initial	Estado inicial, aguardando usuario clicar
started	KYC iniciado, iframe carregando
checking	Polling de status ativo
finished	Operador finalizou (aguardando resultado)
validated	KYC aprovado
failed	KYC reprovado
expired	Sessao expirada
manual_refresh	Aprovacao manual pendente
internal_start_error	Erro ao iniciar
internal_status_error	Erro ao consultar status

Abrindo o KYC programaticamente

O modal KYC pode ser aberto de qualquer lugar via store:

import { useKycStore } from "~/store/kyc";

const openKycModal = useKycStore((s) => s.openKycModal);

openKycModal({
  source: "deposit",
  autoStart: true,
  reloadOnValidated: false,
  onValidated: async (payload) => {
    // payload.kyc_id disponivel
    console.log("KYC aprovado", payload);
  },
});

Dentro do sistema de validacoes

O KycStep (em components/validation/steps/KycStep.tsx) abre o modal com autoStart: true e reloadOnValidated: false, usando o callback onValidated para notificar a resolucao ao sistema de steps.

Rota de recuperacao

A rota user/validate/:type/:token permite que o usuario complete o KYC via link enviado por e-mail/SMS:

/user/validate/kyc/abc123

O type identifica o tipo de validacao e o token e o token de recuperacao. O componente abre o modal KYC com recoveryToken preenchido.