@cactus-agents/kyc

Service para verificação de identidade (KYC). Suporta múltiplos operadores (pay2free, serasa, legitimuz, caf, sumsub, unico, shieldid). Oferece start/status de verificação e helpers para interpretar o estado do KYC.

Instalação

pnpm add @cactus-agents/kyc

Uso recomendado (via wrapper)

import { createKycFromClient } from "@cactus-agents/kyc";

const kyc = createKycFromClient(client);
const startResponse = await kyc.start("global");
const statusResponse = await kyc.getStatus(startResponse.correlation_id!);

Uso manual (com fetcher)

import { createKycService } from "@cactus-agents/kyc";

const kyc = createKycService({
  get: <T>(path: string) => fetcher.get<T>(path),
});

API — KycService

start(source?)

Inicia uma verificação KYC. Retorna URL do iframe do operador e dados da sessão.

start(source?: KycSource): Promise<KycStartResponse>

Param	Tipo	Default	Descrição
source	string	"global"	Contexto que disparou o KYC

Endpoint: GET /bff/users/kyc?source={source}

startRecovery(source, token)

Inicia KYC com token de recuperação (link enviado por e-mail/SMS).

startRecovery(source: KycSource, token: string): Promise<KycStartResponse>

Endpoint: GET /bff/users/kyc/recovery?source={source}&token={token}

getStatus(kycId)

Consulta o status de uma verificação em andamento.

getStatus(kycId: number | string): Promise<KycStatusResponse>

Endpoint: GET /bff/users/kyc/status?kyc_id={kycId}

getStatusRecovery(kycId, token)

Consulta status com token de recuperação.

getStatusRecovery(kycId: number | string, token: string): Promise<KycStatusResponse>

Endpoint: GET /bff/users/kyc/status/recovery?kyc_id={kycId}&token={token}

Helpers de status

Funções para interpretar o status retornado pela API. Aceitam number, string ou enum.

import {
  isKycApprovedStatus,
  isKycReprovedStatus,
  isKycProcessingStatus,
  isKycLivenessPendingStatus,
  isKycManualApprovePendingStatus,
  normalizeKycStatus,
} from "@cactus-agents/kyc";

Helper	Retorna true quando
isKycApprovedStatus(status)	APPROVED ou MANUAL_APPROVED
isKycReprovedStatus(status)	REPROVED ou MANUAL_REPROVED
isKycProcessingStatus(status)	PROCESSING ou LIVENESS_PENDING
isKycLivenessPendingStatus(status)	LIVENESS_PENDING
isKycManualApprovePendingStatus(status)	MANUAL_APPROVE_PENDING

normalizeKycStatus(status)

Converte qualquer representação (number, string, enum) para KycStatus enum.

normalizeKycStatus(status: KycStatusLike): KycStatus | null

Tipos

KycStatus (enum)

enum KycStatus {
  PROCESSING = 0,
  APPROVED = 1,
  REPROVED = 2,
  MANUAL_APPROVED = 3,
  MANUAL_APPROVE_PENDING = 4,
  MANUAL_REPROVED = 5,
  LIVENESS_PENDING = 6,
}

KycStartResponse

interface KycStartResponse {
  correlation_id?: number;
  operator?: KycOperatorName;
  status?: KycStatusLike;
  operation_type?: KycOperationType;
  url?: string;
  exception?: string;
}

KycStatusResponse

interface KycStatusResponse {
  status: KycStatusLike;
  token?: string;
}

KycOperatorName

type KycOperatorName =
  | "caf" | "legitimuz" | "pay2free" | "serasa"
  | "sumsub" | "unico" | "shielid" | "shieldid"
  | string;

Parsing de mensagens do operador

parseKycOperatorMessage interpreta payloads postMessage dos iframes dos operadores KYC, retornando eventos tipados:

import { parseKycOperatorMessage } from "@cactus-agents/kyc";

const event = parseKycOperatorMessage(operator, messageEvent.data);
// event.type: "completed" | "failed" | "manual_approve_pending" | "mobile_started" | "unknown"

Operadores suportados: pay2free, serasa, legitimuz, shieldid.

Tipos de evento:

Tipo	Interface	Descricao
completed	KycEventCompleted	Verificacao concluida com sucesso
failed	KycEventFailed	Verificacao falhou
manual_approve_pending	KycEventManualApprovePending	Aguardando aprovacao manual
mobile_started	KycEventMobileStarted	Fluxo mobile iniciado
unknown	KycEventUnknown	Evento nao reconhecido

O tipo union KycMessageEvent engloba todos os eventos possiveis.

Labels de motivo de KYC forcado

import { getKycReasonLabel, KYC_REASON_LABELS } from "@cactus-agents/kyc";

const label = getKycReasonLabel("password_changed");
// → "validation:kyc_reasons.password_change"

Motivos conhecidos:

Reason	i18n Key
password_changed	validation:kyc_reasons.password_change
reset_password	validation:kyc_reasons.password_recovery
admin_change_password	validation:kyc_reasons.admin_password_change
location_changed_login	validation:kyc_reasons.login_location_change
device_changed_login	validation:kyc_reasons.login_device_change
ip_changed	validation:kyc_reasons.ip_change
login_7_days_ago	validation:kyc_reasons.access_after_7_days

Motivos com cookie_liveness retornam validation:kyc_reasons.selfie_validation. Demais retornam validation:kyc_reasons.unknown.

Tipo KycForceReason: union dos motivos acima + string (extensivel).

Arquivos relevantes

Arquivo	Conteúdo
src/service.ts	createKycService, createKycFromClient
src/status.ts	Helpers de status (isKycApprovedStatus, etc.)
src/types.ts	Todos os tipos e enums
src/index.ts	Re-exports públicos
src/messages.ts	parseKycOperatorMessage, tipos de evento
src/reasons.ts	getKycReasonLabel, KYC_REASON_LABELS, KycForceReason