Account Creation

To enable the User to operate financially in a fully regulated environment, it’s necessary to validate its personal identification. We use strategic partnerships which enable us to check the input information against a huge set of official databases such as the Receita Federal, Policia Federal, OFAC and other sanctions listings.

Personal Accounts

For signing up individual personal accounts, you'll need:

A valid and unique e-mail address
A valid and active CPF, matching the user data provided in the sign up (name, birthdate, etc.)
No financial or criminal sanctions nationally or internationally
No political exposure or relationships (PEP)
A valid physical address matching the user data (may require additional validation)
A valid and unique phone, verified by SMS (Check the Phone Verification guide)
A valid identification document for upload (Check the Document Verification guide).
The value of the user's financial equity in BRL.
The value of the user's annualised financial profit in BRL.
A recent selfie of the user for proof-of-life and face-matching. (may require additional validation)

In some special cases you might also need:

A picture of the user's handwritten signature
A picture of a valid address statement (public services bill, phone bills, etc)

These checks are needed in the account signup, but some of them are rechecked frequently. If any account does not meet the standards after its creation, it may get blocked. In that case, you'll need to contact the Compliance team at the Help Desk.

❗️
Important!
The field motherName is required by default in our KYC. In some cases, the user does not have any mother registered in his document. In that case you should fill the value as DESCONHECIDO.

Payload to register a Personal Account

curl --location --request POST 'https://<instance-url>.btcore.app/consumers' \
--header 'Content-Type: application/json' \
--header 'Authorization: Bearer <oauth_bearer_token>' \
--data-raw '{
	"password": "p@ssw0rd",
	"firstName": "Fulano",
	"lastName": "de Tal",
	"email": "[email protected]",
	"domain": "0a49471d-1cff-4805-829b-e2409969c111", // Id of the domain where the consmer shall be registered
	"consumer": {
		"type": "personal",
		"taxId": "1231231223", // CPF for Brazilian registrations
		"motherName": "Mae de Fulano de Tal", // mother's name, check if it's not a maiden name
		"birthday": "1980-12-30", //"YYYY-MM-DD"
		"birthCity": "Vila Velha",
		"birthState": "ES",
		"civilStatus": "single", (single, married, widowed, divorced)
		"financialProfit": "1000",
		"financialEquity": "1000",
		"pep": false,		
		"phones": [
			{
				"code": "11",
				"number": "99988998",
				"type": "mobile"
			}
		],
		"addresses": [
			{
				"country": "BR",
				"state": "SP",
				"city": "São Paulo",
				"code": "04004004", (postal code)
				"street": "Av Paulista",
				"number": "600",
				"neighborhood": "Boa Vila",
				"complement": "Ap. 30",
				"reference": "",
			}
		]
	},
	"extra":
		"plan": {
			"id": "b6de433b-7d88-4064-8fa5-0297dddb5ba0", // id of the billing plan to which the consumer will subscribe
		}
  }
}'

{
	"password": "p@ssw0rd",
	"firstName": "Fulano",
	"lastName": "de Tal",
	"email": "[email protected]",
	"role": "consumer", (// always consumer)
	"domain": "0a49471d-1cff-4805-829b-e2409969c111", (domainID that will be registered)
	"consumer": {
		"type": "personal",
		"taxId": "1231231223", (CPF for Brazilian registrations)
		"motherName": "Mae de Fulano de Tal", (mother's name, check if it's not a maiden name)
		"birthday": "1980-12-30 12:00:00", ("YYYY-MM-DD HH:mm")
		"birthCity": "Vila Velha",
		"birthState": "ES",
		"civilStatus": "single", (single, married, widowed, divorced)
		"financialProfit": "1000",
		"financialEquity": "1000",
		"pep": false,		
		"phones": [
			{
				"code": "11",
				"number": "99988998",
				"type": "mobile"
			}
		],
		"addresses": [
			{
				"country": "BR",
				"state": "SP",
				"city": "São Paulo",
				"code": "04004004", (postal code)
				"street": "Av Paulista",
				"number": "600",
				"neighborhood": "Boa Vila",
				"complement": "Ap. 30",
				"reference": "",
				"status": "own" (always 'own')
			}
		]
	},
	
	
	"extra":
		"plan": {
			"id": "b6de433b-7d88-4064-8fa5-0297dddb5ba0", (it defines the planID that this consumer will be associated in teh Billing Plan).
			"prepaid": true (if prepaid billing plan)
		}
       }

}

The full schema of the consumer creation endpoint for a personal account is described below.

User:

Field	Required	Type	Observation
role	false	String	Must equal `'consumer'`. If not provided defaults to `'consumer'`
firstName	true	String	The sum of firstName and lastName's length must not exceed 100 characters.
lastName	true	String	The sum of firstName and lastName's length must not exceed 100 characters.
email	*true	String	- Must be a valid according to RFC 5322 - Must not exceed 50 characters
domain	false	String	- If provided must be a valid UUIDv4 corresponding to the id of an existing domain - if not provided the user will be assigned to the same domain as the user to which the oauth_token used to perform the request belongs to.
password	false	String
consumer	true	Consumer

Consumer:

Field	Required	Type	Observation
type	true	Enum	Allowed values: - `'personal'` - `'corporate'` Must be equal to 'personal' for personal accounts.
taxId	true	String	Must be a valid CPF
pep	true	boolean
financialEquity	true	String	Must be a valid amount with 2 digits after the decimal point.
financialProfit	true	String	Must be a valid amount with 2 digits after the decimal point.
motherName	true	String	- Must not exceed 80 characters - if the consumer does not have a registered mother replace with `'DESCONHECIDO'`
birthday	true	String	- Must be a valid date in YYYY-MM-DD format
civilStatus	true	Enum	Allowed values: - `'single'` - `'married'`, - `'divorced'` - `'widowed'` - `'other'` - `'unknown'`
phones	true	Array	- Must contain at least one item - Array items must conform to the Phone schema
addresses	true	Array	- Must contain at least one item - Array items must conform to the Address schema

Phone:

Field	Required	Type	Observations
code	true	String	Must contain exactly two numeric characters
number	true	String

Address:

Field	Required	Type	Observations
country	true	String	Must equal `'Brasil'`
state	true	String	- Must be exactly 2 characters long - Must be a valid state
city	true	String	Must not exceed 30 characters
code	true	String	- Must be exactly 8 characters long - Must be a valid Brazilian zip code (CEP)
neighborhood	true	String	Must not exceed 40 characters
street	true	String	Must not exceed 40 characters
number	true	String
complement	false	String	Must not exceed 30 characters
reference	false	String	Must not exceed 80 characters

Corporate Accounts

For signing up company accounts, you'll need:

A valid and unique e-mail address
A valid CNPJ, matching the company data provided in the sign up (trading name, foundation date, etc.)
A valid physical address matching the user data (may require additional validation)
The legal nature of this company (see the official reference)
The establishment format of this company: MEI, EI, EIRELI, LTDA, SS, SA, ME, EPP or EMGP.
The value of the company's financial equity in BRL.
The value of the company's annualised financial profit in BRL.

Additionally, personal information regarding all company related people (both individual and legal) (such as direct and indirect shareholders, legal representatives and/or attorneys) must be provided and in accordance with the guidelines described above in the the Personal Verification section, including uploading their documents, bear in mind a related person may also themselves be a legal person (PJ) and thus information regarding their related people must also be prov. These checks are needed in the account signup, but some of them are rechecked frequently. If any account does not meet the standards after its creation, it might get blocked without any previous notice.

Payload to register a Corporate Account

curl --location --request POST 'https://<instance-url>.btcore.app/consumers' \
--header 'Authorization: Bearer <oauth_bearer_token>'\
--header 'Content-Type: application/json' \
--data-raw '{
  "firstName":"BIT CAPITAL",
  "lastName":"LTDA",
  "email":"[email protected]",
	"password": "example",
  "role":"consumer",
  "consumer":{
    "taxId":"29079725000107",
    "type":"corporate",
    "phones":[
    	{
      	"code": "11",
        "number":"42002480"
       }
    ],
    "addresses":[
      {
        "street":"Av Nove de Julho",
        "number":"4939",
        "neighborhood":"Jardim Paulista",
        "code":"01407100",
        "city":"São Paulo",
        "state":"SP",
        "country":"BR"
      }
    ],
    "companyData":{
      "tradeName":"Bit Capital Ltda",
      "legalName":"Bit Capital Ltda",
      "openingDate": "1995-08-02",
      "establishmentFormat":"LTDA",
      "activities":[
        {
          "isMain":true,
          "code":"62.04-0-00",
        }
      ],
      "partners":[
        {
          "firstName":"SOCIO",
          "lastName": "DA EMPRESA"
          "profile":"owner",
          "email":"[email protected]",
          "consumer": {
            "birthday": "1990-01-01" // YYYY-MM-DD,
            "taxId":"01234567890",
            "motherName":"MÃE DO SOCIO",
            "isPep":false,
						"civilStatus": "single",
            "phones":[
            	{
              	"code": "11",
                "number": "42002480"
              }
            ],
          	"addresses":[
            	{
              	"street":"Av Paulista",
              	"number":"123",
              	"neighborhood":"Jardim Paulista",
              	"code":"04004000",
              	"city":"São Paulo",
              	"state":"SP",
              	"country":"BR",
              	"status":"own"
            	}
          	]
          }
        }
      ]
    }
  }
}'

// Registers a new subaccount for a consumer user
// This is create a "pending" account, after its creation
// the phone number and the user documents must be verified 
const user = await bitcapital.consumers().create({
  firstName: 'BIT CAPITAL',
  lastName: 'LTDA',
  email: '[email protected]',
	password: "example",
  consumer: {
    taxId: '29079725000107',
    type: 'corporate',
    birthday: new Date('2017-11-16'),
    phones: [{
      code: '11',
      number: '42002480',
    }],
    addresses: [{
      street: 'Av Nove de Julho',
      number: '4939',
      neighborhood: 'Jardim Paulista',
      code: '01407100',
      city: 'São Paulo',
      state: 'SP',
      country: 'BR',
      status: 'own',
      type: 'work',
    }],
    companyData: {
      taxId: '29079725000107',
      stateRegistration:'164677191686',
      tradeName: 'Bit Capital Ltda',
      legalName: 'Bit Capital Ltda',
      openingDate: new Date('2017-11-16'),
      establishmentFormat: 'LTDA',
      revenue: "1000000.00",
      partnerChanged: false,
      legalNature: '2062',
      legalStatus: 'active',
      activities: [{
        isMain: true,
        code: '62.04-0-00',
        description: 'Consultoria em tecnologia da informação',
      }],
      partners: [{
        name: 'RICARDO ROESSLE GUIMARAES FILHO',
        gender: 'M',
        type: 'personal',
        birthDate: new Date('1995-08-02'),
        birthCountry: 'Brasil',
        taxId: '1234567890',
        motherName: 'ELISABETH GUIMARAES',
        isPep: false,
        profile: 'owner',
        email: '[email protected]',
        phones: [{
          code: '11',
          number: '42002480',
        }],
        addresses: [{
          street: 'Av Nove de Julho',
          number: '4939',
          neighborhood: 'Jardim Paulista',
          code: '01407100',
          city: 'São Paulo',
          state: 'SP',
          country: 'BR',
          status: 'own',
          type: 'home',
        }],
      }],
    },
  },
});

The full schema of the consumer creation endpoint for a corporate account is described below.

User:
The same as described for a personal consumer

Consumer:

Field	Required	Type	Observation
type	true	Enum	Allowed values: - `'personal'` - `'corporate'` Must be equal to 'corporate' for corporate accounts.
taxId	true	String	Must be a valid CNPJ
pep	true	boolean
financialEquity	true	String	Must be a valid amount with 2 digits after the decimal point.
financialProfit	true	String	Must be a valid amount with 2 digits after the decimal point.
phones	true	Array	- Must contain at least one item - Array items must conform to the Phone schema
addresses	true	Array	- Must contain at least one item - Array items must conform to the Address schema
companyData	true	CompanyData

CompanyData:

Field	Required	Type	Observations
legalName	true	String	Must not exceed 100 characters
tradeName	true	String	Must not exceed 40 characters
establishmentFormat	true	Enum	Accepted values: - `'ME'` - `'MEI'` - `'EI'` - `'EIRELI'` - `'LTDA'` - `'SA'` - `'SS'` - `'EPP'` - `'EMGP'`
openingDate	true	String	Must be a valid date in the YYYY-MM-DD format
Activities	true	Array	- Must contain at least one item - items must conform to the Activity schema - Must contain at least one item where the field `isMain` is true
partners	true	Array	- Must contain at least one item - Items must conform Partner schema

Activity:

Field	Required	Type	Observation
code	true	String	- Must be exactly 7 characters long containing only digits - Must be a valid brazilian occupation code (CNAE)
isMain	true	boolean
description	false	String

Partner:

Field	Required	Type	Observation
profile	true	Enum	Accepted values: - `'OWNER'` - `'ATTORNEY'`
firstName	true	String	The sum of firstName and lastName's length must not exceed 100 characters.
lastName	true	String	The sum of firstName and lastName's length must not exceed 100 characters.
email	true	String	- Must be a valid according to RFC 5322 - Must not exceed 50 characters
consumer	true	Object	Must conform to either the personal or corporate Consumer schema

SaaS Extra Fields

When using BT Core SaaS Platform, you can optionally add some other fields when creating a user related to this account:

Field	Description
extra.branch	* Optional field: `number` The branch number to assign this user to. Remember: The branch has to be previously created and setup for it to be available in account creation.
extra.number	* Optional field: `number` Explicitly tell which account number this consumer's first wallet should have. If not specified the system will generate a number randomly.

Handling failed verifications

An account creation may be rejected due to various reasons such as the provided information not matching information found ou bureaus, text on documents not being readable/discernible, user has sanctions, taxId is inactive, among others. Such cases may be identified by a rejected status in the related user's AssetRegistration. When a user is rejected please contact the compliance Help Desk. for further action.

Personal Accounts

❗️Important!

Payload to register a Personal Account

Corporate Accounts

Payload to register a Corporate Account

SaaS Extra Fields

Handling failed verifications

❗️
Important!