Visão geral

Por que o Banco Central exige verificação de identidade, os dois níveis de KYC da BlendFi (plataforma e cripto), e como cada um afeta sua integração.

A regulação brasileira exige que todo cliente final que transaciona seja identificado antes de o dinheiro se mover. A BlendFi opera dois níveis de KYC: o KYC de plataforma, que você dirige via API e cobre toda operação, e o KYC cripto, que a BlendFi inicia automaticamente após a aprovação do KYC de plataforma e é exigido para operações offramp. Seu código observa o estado pelo campo kyc_status no usuário e por códigos de erro específicos.

Por que existe

KYC é um portão regulatório, não uma escolha de produto. A BlendFi opera sob o framework do Banco Central, que exige identificação verificada antes de qualquer movimentação financeira. O efeito pra sua integração é direto: até o cliente final estar approved, qualquer chamada que toque dinheiro retorna erro com código estável.

Os dois níveis

A BlendFi separa o KYC em dois níveis com escopos distintos:

Nível	O que verifica	Quem dirige	Webhook
KYC de plataforma	Identidade do cliente final (documento, prova de vida, listas restritivas)	Sua organização, via `POST /v1/users/{id}/kyc`	Sim, eventos `user.kyc_*`
KYC cripto	Verificações adicionais para o cliente final operar com USDT (movimentação de cripto)	Iniciado automaticamente pela BlendFi após o KYC de plataforma ser aprovado	Não há evento dedicado

Quando cada um é exigido

Operação	KYC de plataforma	KYC cripto
Cadastrar usuário, atualizar dados	Não exigido	Não exigido
Cotação e transação onramp (Pix → USDT)	✅ Exigido	Não exigido
Cotação e transação offramp (USDT → Pix)	✅ Exigido	✅ Exigido

Para um cliente final apenas onramp, basta o KYC de plataforma aprovado. Para qualquer cliente final que vá operar offramp, ambos precisam estar aprovados.

O KYC cripto é automático

Você não chama nenhum endpoint para iniciar o KYC cripto. Após o KYC de plataforma ser aprovado, a BlendFi inicia o KYC cripto em segundo plano. Em condições normais, quando o cliente final tenta uma operação offramp, ambos já estão prontos.

Estados do KYC de plataforma

kyc_status no objeto do usuário expõe o estado atual:

Estado	O que significa	Pode transacionar?
`not_started`	Usuário criado; submissão ainda não iniciada	❌
`pending`	Submissão em andamento, sob análise	❌
`approved`	Identidade verificada; liberado para transacionar	✅
`rejected`	Verificação falhou; motivo em `rejection_reason`	❌
`expired`	Estava aprovado; verificação caducou	❌

Aprovações têm validade limitada e expiram. Sua integração deve tratar kyc_status como estado atual, não como evento único: monitore expiração e peça reverificação proativa antes do prazo quando aplicável.

Webhooks do KYC de plataforma

Quatro eventos disparam conforme o KYC de plataforma transiciona:

Evento	Quando dispara
`user.kyc_pending`	Submissão registrada, sob análise
`user.kyc_approved`	Aprovado, cliente final liberado
`user.kyc_rejected`	Rejeitado, payload inclui `rejection_reason`
`user.kyc_expired`	Validade da aprovação caducou

O KYC cripto não emite webhooks dedicados.

Erros que sua integração precisa tratar

Os códigos mais comuns. Lista completa no catálogo de erros.

KYC de plataforma:

Código	Status	Quando
`kyc_required`	422	Operação tentada antes de o KYC de plataforma estar aprovado
`invalid_kyc_state`	422	Operação não permitida no estado de KYC atual
`kyc_already_approved`	409	Resubmetendo KYC para usuário já aprovado
`kyc_submission_not_found`	404	Consulta a uma submissão que não existe
`kyc_provider_unavailable`	502	Falha transitória do provedor; seguro retentar

KYC cripto (só aparecem em operações offramp):

Código	Status	Quando
`crypto_kyc_required`	422	Cliente final ainda não tem KYC cripto. Em condições normais, indica que o KYC cripto ainda não rodou em segundo plano
`crypto_kyc_pending`	422	KYC cripto em andamento. Aguarde a conclusão e retente
`crypto_kyc_declined`	422	KYC cripto recusado. Cliente final não pode operar offramp; entre em contato com o suporte

Cliente jurídico (KYB):

Código	Status	Quando
`kyb_not_yet_supported`	422	KYC empresarial ainda não disponível na v1

Próximos passos

Fluxo de KYC: o passo a passo prático com exemplos de chamada e tratamento dos webhooks.
Webhooks: contrato de assinatura, retentativas, janela de replay.
Erros e retentativas: como bifurcar nos códigos acima.
Glossário: definições para KYC, KYB, CPF, CNPJ.