🇧🇷 Brazil

Brazil onboarding has country-specific identity and documentation requirements that should be validated early in integration.


Exchange profile

FieldValue
ExchangeBRAZIL
Main fiat currencyBRL
Typical local railsPIX (QR and key-based)

Identity rules (legalId)

In Brazil, legalId can be:

  • CPF (individual)
  • CNPJ (company)
  • RG
  • CNH (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)

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)

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_VA and IDENTITY_VALIDATION already COMPLETED (409 USER_STATUS otherwise).
  • Returns a single-use url to hand to the user. It drives the same EXTERNAL_LIVENESS_VALIDATION task as the virtual account liveness: IN_PROGRESS, then COMPLETED once the verification finishes, or FAILED with a rejectionReason.
  • 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 format
  • exchange: "BRAZIL"
  • name, surname
  • birthDate
  • phoneNumber
  • nationality
  • address.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, surname
  • nationality — any nationality is accepted, and it is not the same field as legalIdNationality
  • address.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.


Did this page help you?