🇧🇷 Brazil
Brazil onboarding has country-specific identity and documentation requirements that should be validated early in integration.
Exchange profile
| Field | Value |
|---|---|
| Exchange | BRAZIL |
| Main fiat currency | BRL |
| Typical local rails | PIX (QR and key-based) |
Identity rules (legalId)
legalId)In Brazil, legalId can be:
CPF(individual)CNPJ(company)RGCNH(driver's license)
Accepted formats:
- CPF:
/^[0-9]{3}[.]?[0-9]{3}[.]?[0-9]{3}-?[0-9]{2}$/ - CNPJ:
/^[0-9]{2}[.]?[0-9]{3}[.]?[0-9]{3}\/?[0-9]{4}-?[0-9]{2}$/ - RG:
/^[0-9]{7,9}[0-9Xx]?$/or/^[0-9]{1,2}\.[0-9]{3}\.[0-9]{3}-?[0-9Xx]?$/ - CNH:
/^[0-9]{11}$/or/^[0-9]{3}\.[0-9]{3}\.[0-9]{3}-[0-9]{2}$/
CPF, CNPJ and CNH are also validated with checksum rules in addition to regex format (CPF/CNPJ use the standard mod-11 digit-verifier algorithm; CNH uses the DENATRAN mod-11 algorithm). RG has no checksum — regex format is the only check.
Documentation requirements
Identity image uploads may be omitted for lower cumulative operation amounts, but full flows require valid identity documents when threshold controls are reached.
Use Upload Identity Image for signed upload URLs.
Virtual accounts
Brazil supports virtual accounts in BRL over PIX rails. The user's legalIdNationality must be BRAZIL. Both individuals (CPF) and companies (CNPJ) are supported; foreign users are not.
Individuals (CPF)
CPF)Identity documents must be uploaded as part of the onboarding payload — selfie, ID front, ID back, and the document type (RG or CNH):
{
"externalId": "user-bra-001",
"email": "[email protected]",
"name": "Nome",
"surname": "Sobrenome",
"legalId": "00000000000",
"legalIdDocumentType": "CPF",
"legalIdNationality": "BRAZIL",
"documents": {
"selfieKey": "uploads/selfie-xyz.jpg",
"documentFrontKey": "uploads/id-front-xyz.jpg",
"documentBackKey": "uploads/id-back-xyz.jpg",
"documentFileType": "rg"
}
}Once ACTIVE, assign the virtual account:
{
"userAnyId": "100012345",
"asset": "BRL",
"externalId": "user-acc-brl-001"
}See POST /wallet/v1/user-actions/assign-virtual-account.
Companies (CNPJ)
CNPJ)Companies onboard with type: "BUSINESS", their corporate data, the shareholder structure (shareholders), and their legal representatives (beneficiaries) — each representative completing a full identity verification. The corporate data and shareholder structure are auto-populated from official records using the CNPJ.
See the dedicated Creating a virtual account for a company guide for the full flow and payload.
Deposit address
Each user can get a permanent deposit address for ramps: a PIX key issued in the user's name. Assign it once the user is ACTIVE and has completed the liveness check (409 LIVENESS_REQUIRED otherwise); deposits the user sends to it are credited to their balance. The key can be issued after the call returns; in that case the response has no address yet and it becomes available on the user once issued.
Only transfers from an account in the user's own name (same CPF) are accepted. A transfer from anyone else is returned automatically to the account it came from, and no webhook is sent for it.
{
"userAnyId": "100012345",
"asset": "BRL",
"externalId": "user-dep-brl-001"
}See POST /crypto/v2/user-actions/assign-deposit-address.
Crypto liveness check
Crypto users can also complete a liveness check with POST /crypto/v2/onboarding-actions/perform-external-liveness. The user becomes ACTIVE on the crypto platform without it, but it is required before assigning a BRL deposit address.
- Requires
BASIC_PERSONAL_DATA_DEFINITION_VAandIDENTITY_VALIDATIONalreadyCOMPLETED(409 USER_STATUSotherwise). - Returns a single-use
urlto hand to the user. It drives the sameEXTERNAL_LIVENESS_VALIDATIONtask as the virtual account liveness:IN_PROGRESS, thenCOMPLETEDonce the verification finishes, orFAILEDwith arejectionReason. - After a
FAILED, request a new link to restart the check. - The check runs on the user's BRL deposit address account. An asset is either a virtual account or a deposit address, never both: requesting it for a user who already has a BRL virtual account, assigning a BRL virtual account to a user who already has a BRL deposit address, or the other way around, answers
409 BANK_ACCOUNT_EXISTS.
Identity data auto-population
For crypto onboarding, identity data is pulled automatically from official records using the CPF. This means most personal data fields (name, surname, birthDate, etc.) are populated without integrator input. Use GET /crypto/v2/stats/onboarding/missing-personal-data/:userAnyId to check if any fields still need to be submitted manually.
For WALLET (virtual accounts) onboarding, individuals still send address and nationality themselves, either in the signup call or afterwards with POST /wallet/v1/onboarding-actions/define-personal-data. nationality, name and surname are always taken as sent. address is validated against official records: a complete, valid address you send is kept as-is; any field that is missing or doesn't check out is filled in or corrected automatically. Use GET /wallet/v1/info/user-missing-data/USERANYID to check what is still missing — the WALLET required-field set is different from the crypto one (see Virtual accounts above).
Companies (CNPJ) go through the same address validation as individuals: their corporate data (name, shareholder structure) is still auto-populated from official records as before, and their registered address is now also validated the same way — kept as sent if complete and valid, filled in or corrected otherwise.
Payload guidance
For Brazil cripto onboarding, the required personalData fields are:
legalId— CPF formatexchange: "BRAZIL"name,surnamebirthDatephoneNumbernationalityaddress.street
Most of these are auto-populated from the CPF (see above). sex, maritalStatus and work are not required for Brazil.
For Brazil WALLET onboarding, the required personalData fields are different — see Required personal data:
name,surnamenationality— any nationality is accepted, and it is not the same field aslegalIdNationalityaddress.street,address.numeration,address.postalCode,address.locality,address.province
You send all of these in the signup call, or afterwards with POST /wallet/v1/onboarding-actions/define-personal-data. name, surname and nationality are kept as sent. address is checked against official records: if what you sent is complete and valid it is kept, otherwise any missing or incorrect field is filled in or corrected automatically.
Request example
{
"externalId": "user-BRA",
"email": "[email protected]",
"legalId": "123.456.789-09",
"type": "INDIVIDUAL",
"exchange": "BRAZIL",
"personalData": {
"name": "JOHN",
"surname": "DOE",
"birthDate": "1990-01-01",
"isPep": false,
"isFacta": false,
"isFep": false,
"phoneNumber": "5511900000000",
"nationality": "Brasil",
"address": {
"street": "RUA EXEMPLO",
"postalCode": "01000000",
"locality": "SAO PAULO",
"province": "SAO PAULO",
"numeration": "100",
"floor": "",
"apartment": ""
}
},
"banking": {
"accounts": [
{
"cbu": "12345678909",
"currency": "BRL",
"description": "Cta BRL"
}
]
}
}Example entrypoint
Then use the missing-data (crypto) or missing-data (WALLET) endpoint, plus onboarding-task endpoints, to complete remaining requirements before operating.
Updated 16 days ago