Fluxo de KYC

Todo cliente final BlendFi precisa completar o KYC de plataforma antes de movimentar dinheiro. É exigência regulatória: sem kyc_status: approved, qualquer cotação ou transação retorna kyc_required (422). A BlendFi conduz a verificação por trás do endpoint; sua integração só conversa com a API da BlendFi.

Como tudo se encaixa

Sua aplicação           BlendFi                Verificação de identidade
   │                       │                              │
   ├── POST /v1/users ────►│                              │
   │◄── usuário criado ────┤                              │
   │   (kyc: not_started)  │                              │
   │                       │                              │
   ├── POST /v1/users/{id}/kyc ─►                         │
   │                       ├── inicia submissão ─────────►│
   │                       │◄────── link assinado ────────┤
   │◄── submissão criada ──┤                              │
   │   (kyc: pending,      │                              │
   │    websdk_url)        │                              │
   │                       │                              │
   ├── redireciona cliente final para websdk_url ─────────►
   │                       │ (cliente envia documentos)   │
   │                       │◄──── webhook de resultado ───┤
   │                       │                              │
   │◄── webhook user.kyc_approved ─┤                      │
   │   (kyc: approved)             │                      │
   │                       │                              │
   │                       ├── inicia KYC cripto em segundo plano
   │                       │

Você só chama a BlendFi. A BlendFi conduz a verificação e reflete os resultados de volta via webhook.

Cinco resultados

O caminho completo

curl -X POST $BLENDFI_BASE/v1/users \
  -H "Authorization: Bearer $BLENDFI_KEY" \
  -H "Idempotency-Key: $(uuidgen)" \
  -H "content-type: application/json" \
  -d '{
    "external_id": "seu-usuario-001",
    "name": "Ada Lovelace",
    "cpf": "52998224725"
  }'

curl -X POST $BLENDFI_BASE/v1/users/01J.../kyc \
  -H "Authorization: Bearer $BLENDFI_KEY" \
  -H "Idempotency-Key: $(uuidgen)"

{
  "user_id": "01J...",
  "status": "pending",
  "websdk_url": "https://verify.blendfi.com.br/start/eyJ...",
  "websdk_url_expires_at": "2026-04-29T13:30:00Z"
}

{
  "type": "user.kyc_approved",
  "user_id": "01J...",
  "external_id": "seu-usuario-001",
  "kyc_status": "approved",
  "approved_at": "2026-04-29T13:08:00Z",
  "expires_at": "2027-04-29T13:08:00Z"
}

curl $BLENDFI_BASE/v1/users/01J.../kyc \
  -H "Authorization: Bearer $BLENDFI_KEY"

{
  "user_id": "01J...",
  "status": "approved",
  "approved_at": "2026-04-29T13:08:00Z",
  "expires_at": "2027-04-29T13:08:00Z"
}

Forçando resultados de KYC no sandbox

O sandbox usa um espelho da verificação. Para evitar esperar uma análise de documento real, use o test helper para forçar qualquer resultado:

curl -X POST $BLENDFI_BASE/v1/test_helpers/users/01J.../kyc \
  -H "Authorization: Bearer $BLENDFI_KEY" \
  -H "Idempotency-Key: $(uuidgen)" \
  -H "content-type: application/json" \
  -d '{"status": "approved"}'

Valores aceitos: "approved", "rejected", "expired". O webhook é disparado exatamente como em produção, então sua lógica de handler é exercitada de ponta a ponta.

Renovação e expiração

KYCs aprovados valem por 12 meses por padrão. A BlendFi monitora a expiração e move o usuário para kyc_status: expired no dia do limite. Você recebe um webhook user.kyc_expired 7 dias antes da expiração para avisar o cliente final com antecedência.

Reverificação é uma chamada POST /v1/users/{id}/kyc nova. O cliente final passa pelo mesmo fluxo. Não há endpoint separado de "renovação".

Rejeições

Resultado rejected inclui um rejection_reason:

{
  "user_id": "01J...",
  "status": "rejected",
  "rejected_at": "2026-04-29T13:08:00Z",
  "rejection_reason": "document_unreadable"
}

Razões comuns:

Cliente final rejected pode reenviar (POST /v1/users/{id}/kyc de novo). A nova submissão substitui a rejeição; status volta para pending.

pep_match e sanctions_match são terminais; reenvio não resolve. Tratamos caso a caso.

Próximos passos

FAQ

O cliente final pode reenviar se for rejeitado? Pode, para a maioria das razões. Chame POST /v1/users/{id}/kyc de novo para gerar novo link; o cliente final passa pelo fluxo de novo. Casos terminais: pep_match e sanctions_match, que exigem revisão humana.

O que acontece se o cliente final fechar a verificação no meio? kyc_status continua pending. O fluxo guarda o estado parcial por cerca de 24 horas; reabrir o mesmo link dentro dessa janela retoma de onde parou. Após expirar, gere um novo link.

Eu preciso verificar a assinatura do webhook? Precisa. Os webhooks da BlendFi carregam o cabeçalho X-Blendfi-Signature (HMAC-SHA-256 sobre {t}.{raw_body}, com segredo por endpoint). Rejeite qualquer entrega cuja assinatura não bata. Detalhes em Webhooks.

Por que not_started existe se eu sempre inicio o KYC logo após criar o usuário? Algumas integrações criam o usuário cedo (ex.: lista de espera) e só disparam o KYC quando o cliente final faz uma ação relevante. Os dois passos suportam esse padrão. Se você sempre inicia na hora, trate not_started como transiente que sua UI nunca mostra.

Posso ver as imagens dos documentos rejeitados? Não. As imagens ficam com a verificação. A BlendFi recebe apenas o veredicto e a razão de rejeição. É uma fronteira de privacidade intencional.

O cliente final passou no KYC em outro produto que eu opero, posso pular o KYC da BlendFi? Não. Reverificamos por organização BlendFi, independente de o mesmo cliente final ter sido verificado em outro lugar. Exigência regulatória.

Preciso fazer alguma chamada para o KYC cripto? Não. O KYC cripto é iniciado automaticamente após o KYC de plataforma ser aprovado. Você só observa o resultado quando uma operação offramp falha com crypto_kyc_required, crypto_kyc_pending ou crypto_kyc_declined, que são situações de borda.