Overview
Why the Brazilian Central Bank requires identity verification, BlendFi's two KYC tiers (platform and crypto), and how each affects your integration.
Brazilian regulation requires every end customer who transacts to be identified before any money moves. BlendFi runs two KYC tiers: the platform KYC, which you drive via the API and gates every operation, and the crypto KYC, which BlendFi initiates automatically after platform KYC is approved and is required for offramp operations. Your code observes state through kyc_status on the user and through specific error codes.
Why it exists
KYC is a regulatory gate, not a product choice. BlendFi operates under the Brazilian Central Bank framework, which requires verified identity before any financial movement. The effect for your integration is direct: until the end customer is approved, any call that touches money returns an error with a stable code.
The two tiers
BlendFi separates KYC into two tiers with distinct scopes:
| Tier | What it verifies | Who drives it | Webhook |
|---|---|---|---|
| Platform KYC | End customer identity (document, liveness, restrictive lists) | Your organization, via POST /v1/users/{id}/kyc | Yes, user.kyc_* events |
| Crypto KYC | Additional checks for the end customer to operate USDT (crypto movement) | Initiated automatically by BlendFi after platform KYC is approved | No dedicated event |
When each one is required
| Operation | Platform KYC | Crypto KYC |
|---|---|---|
| Creating users, updating data | Not required | Not required |
| Onramp quotes and transactions (Pix → USDT) | ✅ Required | Not required |
| Offramp quotes and transactions (USDT → Pix) | ✅ Required | ✅ Required |
For an end customer who is onramp-only, an approved platform KYC is enough. For any end customer who will operate offramp, both must be approved.
Crypto KYC is automatic
You don't call any endpoint to start the crypto KYC. After platform KYC is approved, BlendFi initiates the crypto KYC in the background. Under normal conditions, by the time the end customer attempts an offramp operation, both are ready.
Platform KYC states
kyc_status on the user object exposes the current state:
| State | Meaning | Can transact? |
|---|---|---|
not_started | User created; submission not yet started | ❌ |
pending | Submission in progress, under review | ❌ |
approved | Identity verified; cleared to transact | ✅ |
rejected | Verification failed; reason in rejection_reason | ❌ |
expired | Was approved; verification has lapsed | ❌ |
Approvals have a limited validity window and expire. Your integration should treat kyc_status as current state, not a one-shot event: monitor expiration and proactively request reverification before the deadline when applicable.
Platform KYC webhooks
Four events fire as platform KYC transitions:
| Event | When it fires |
|---|---|
user.kyc_pending | Submission registered, under review |
user.kyc_approved | Approved, end customer cleared |
user.kyc_rejected | Rejected, payload includes rejection_reason |
user.kyc_expired | Approval validity has lapsed |
Crypto KYC does not emit dedicated webhooks.
Errors your integration must handle
The most common codes. Full list in the errors catalog.
Platform KYC:
| Code | Status | When |
|---|---|---|
kyc_required | 422 | Operation attempted before platform KYC is approved |
invalid_kyc_state | 422 | Operation not allowed in the current KYC state |
kyc_already_approved | 409 | Resubmitting KYC for an already-approved user |
kyc_submission_not_found | 404 | Querying a submission that does not exist |
kyc_provider_unavailable | 502 | Transient provider failure; safe to retry |
Crypto KYC (only appear in offramp operations):
| Code | Status | When |
|---|---|---|
crypto_kyc_required | 422 | End customer does not yet have crypto KYC. Under normal conditions, indicates the background flow has not run yet |
crypto_kyc_pending | 422 | Crypto KYC in progress. Wait for completion and retry |
crypto_kyc_declined | 422 | Crypto KYC declined. End customer cannot operate offramp; contact support |
Corporate clients (KYB):
| Code | Status | When |
|---|---|---|
kyb_not_yet_supported | 422 | Corporate KYC not available in v1 |
Next steps
- KYC flow: the practical step-by-step with example calls and webhook handling.
- Webhooks: signature contract, retries, replay window.
- Errors and retries: how to branch on the codes above.
- Glossary: definitions for
KYC,KYB,CPF,CNPJ.