Fluxo de KYC

Todo usuário final BlendFi precisa completar a verificação de identidade antes de movimentar dinheiro. Isso é uma exigência regulatória — sem um KYC approved, tentativas de criar uma cotação ou transação retornam 403 missing_capability para o usuário. A BlendFi cuida do KYC pela Sumsub; você não fala diretamente com a Sumsub.

Como tudo se encaixa

Seu app                 BlendFi                   Sumsub
   │                       │                         │
   ├─ POST /v1/users ─────►│                         │
   │◄──── usuário criado ──┤                         │
   │   (kyc: not_started)  │                         │
   │                       │                         │
   ├─ POST /v1/users/{id}/kyc ─►                     │
   │                       ├── cria applicant ──────►│
   │                       │◄──── id do applicant ───┤
   │                       ├── gera link websdk ────►│
   │                       │◄──── url assinada ──────┤
   │◄── submissão de kyc ──┤                         │
   │   (kyc: pending,      │                         │
   │    websdk_url)        │                         │
   │                       │                         │
   ├─ redireciona usuário final para websdk_url ─────►
   │                       │ (usuário envia docs)    │
   │                       │◄────── webhook ─────────┤
   │                       │  (resultado da revisão) │
   │◄── webhook pra você ──┤                         │
   │  (kyc: approved)      │                         │

Você só chama a BlendFi. A BlendFi chama a Sumsub por você e reflete os resultados de volta.

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://websdk.sumsub.com/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 Sumsub. Para evitar esperar uma revisão 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 aceitáveis: "approved", "rejected", "expired". O webhook é disparado exatamente como seria 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 gente 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 conseguir avisar o usuário a verificar de novo com antecedência.

Uma reverificação é uma chamada POST /v1/users/{id}/kyc nova — o usuário passa pelo mesmo fluxo do WebSDK de novo. Não tem endpoint separado de "renovação".

Rejeições

Um 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:

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

pep_match e sanctions_match são terminais no nosso fluxo — reenvio não resolve. A gente trata caso a caso com você.

O que ler em seguida

FAQ

O mesmo usuário final pode reenviar se for rejeitado? Pode — para a maioria das razões de rejeição. Chame POST /v1/users/{id}/kyc de novo para pegar um link novo do WebSDK; o usuário passa pelo fluxo de novo. Os dois casos terminais são pep_match e sanctions_match — esses exigem revisão humana do nosso lado.

O que acontece se o usuário fechar o WebSDK no meio? O kyc_status dele continua pending. O WebSDK guarda o estado parcial por uns 24 horas; se ele reabrir o mesmo link nessa janela, retoma de onde parou. Após a expiração, gere um link novo.

Eu preciso verificar a assinatura do webhook? Precisa. Webhooks de produção da BlendFi carregam um cabeçalho X-BlendFi-Signature (HMAC-SHA-256 sobre o corpo, com um segredo por organização). Rejeite qualquer webhook cuja assinatura não bata. A gente fornece snippets de verificação na referência de webhooks.

Por que o estado not_started existe se eu sempre inicio o KYC logo após criar o usuário? Algumas integrações criam usuários cedo (cadastro de waitlist, por exemplo) e só disparam o KYC quando o usuário faz uma ação relevante de dinheiro. O formato em dois passos suporta esse padrão. Se você sempre inicia o KYC na hora, trate not_started como um estado transiente que sua UI nunca exibe.

Posso ver as imagens dos documentos rejeitados? Não. A Sumsub guarda os documentos; a BlendFi só vê o veredicto e a razão da rejeição. Isso é uma fronteira de privacidade por design.

O usuário passou no KYC em outro produto que eu opero — posso pular o KYC da BlendFi para ele? Não. A gente reverifica por organização BlendFi, independente de o mesmo usuário final ter sido verificado em outro lugar. Isso é uma exigência regulatória.