Skip to main content

Create Wallet

Important

To register bolePix, it is necessary that an active random Pix key exists in the account where the boletos will be registered.

Boleto wallets have a unique identification code (requester_profile_code) and specific default configurations for payment, discharge, protest, etc. of the boleto. The same account can have multiple boleto wallets, which allows the user to create multiple wallets with different default configurations. This dynamic facilitates the generation of boletos, with different configurations, in a more agile and automatic manner.

Information

For all accounts, a boleto wallet is created with the client's default configurations. This default configuration pattern can be changed by contacting our support (suporte.baas@qitech.com.br). After account creation, it is also possible to change the account fees using the fee configuration endpoint.

Attention!

The creation of boleto wallets is an asynchronous flow. After approval/rejection of wallet creation by CIP/Nuclea, the requester will be notified via webhook about the result of such request.

Request​

ENDPOINT
/account/ACCOUNT_KEY/requester_profile
METHOD
POST

Path parameters​

FieldTypeDescriptionCharacters
account_keyuuidv4Unique account identification key, in uuid v4 format36
Request Body
{
  "request_control_key": "0868a24b-4a69-4138-ac4d-ecaeddf0005f",
  "configuration_data": {
    "max_payment_days": 1,
    "protest_settings": {
      "days_to_protest": 0
    },
    "bankruptcy_protest_settings": {
      "days_to_bankruptcy_protest": 0
    },
    "write_off_settings": {
      "days_to_write_off": 0
    },
    "fine_settings": {
      "fine_type": "absolute",
      "fine_amount": 10,
      "days_to_fine": 0
    },
    "interest_settings": {
      "interest_type": "workdays_daily_amount",
      "interest_amount": 10,
      "days_to_interest": 0
    },
    "qr_code_settings": {
      "pix_key": "5df7a433-bd61-4f98-9515-df9aedc2980c",
      "qr_code_on_discharge_enabled": false
    },
    "cnab_settings": {
      "default_bank": "qi_scd",
      "preferred_layout": "400"
    }
  }
}

Request Body Params​

FieldTypeDescriptionCharacters
request_control_key *uuidv4Unique request identification key used by the client in uuid v4 format36
configuration_data *objectWallet default configurationsconfiguration_data Object

configuration_data Object​

FieldTypeDescriptionCharacters
max_payment_days *integerMaximum calendar days the boleto will remain available for payment after due date (can be at most 365)-
write_off_settingsobjectDefault discharge configurationwrite_off_settings Object
protest_settingsobjectDefault protest configurationprotest_settings Object
bankruptcy_protest_settingsobjectDefault bankruptcy protest configurationbankruptcy_protest_settings Object
fine_settingsobjectDefault fine configurationfine_settings Object
interest_settingsobjectDefault interest configurationinterest_settings Object
qr_code_settingsobjectDefault PIX QR Code configuration (for bolePix)qr_code_settings Object
cnab_settingsobjectDefault CNAB files configurationcnab_settings Object

write_off_settings Object​

FieldTypeDescriptionCharacters
days_to_write_off *integerDays after due date for the boleto to be automatically discharged-

protest_settings Object​

FieldTypeDescriptionCharacters
days_to_protest *integerDays after due date for the boleto to be automatically protested-

bankruptcy_protest_settings Object​

FieldTypeDescriptionCharacters
days_to_bankruptcy_protest *integerDays after due date for a bankruptcy protest process to be automatically initiated-

fine_settings Object​

Option 1: absolute amount fine (fine_type=absolute)
FieldTypeDescriptionCharacters
fine_type *stringType of finefine_type Enumerators
fine_amount *floatAbsolute amount of the fine-
days_to_fine *integerDays after due date for the fine to be charged-
Option 2: percentage fine (fine_type=percentage)
FieldTypeDescriptionCharacters
fine_type *stringType of finefine_type Enumerators
fine_percentage *integerPercentage amount of the fine, from 1 to 100-
days_to_fine *integerDays after due date for the fine to be charged-

fine_type Enumerators​

EnumeratorDescription
absoluteabsolute amount
percentagepercentage amount

interest_settings Object​

Option 1: interest using absolute amounts (interest_type=calendar_days_daily_amount or interest_type=workdays_daily_amount)
FieldTypeDescriptionCharacters
interest_type *stringType of interestinterest_type Enumerators
interest_amount *floatAmount to be charged per determined time unit (business days or calendar days)-
days_to_interest *integerDays after due date to start charging interest-
Option 2: interest using percentage amounts (interest_type=calendar_days_monthly_percentage)
FieldTypeDescriptionCharacters
interest_type *stringType of interestinterest_type Enumerators
interest_percentage *integerPercentage to be charged per determined time unit (business days or calendar days)-
days_to_interest *integerDays after due date to start charging interest-

interest_type Enumerators​

EnumeratorDescription
calendar_days_daily_amountDaily amount over calendar days
workdays_daily_amountDaily amount over business days
calendar_days_monthly_percentageInterest percentage charged monthly, based on calendar days

qr_code_settings Object​

FieldTypeDescriptionCharacters
pix_key *uuidv4Random type Pix key36
qr_code_on_discharge_enabled *booleanDetermines if QR Code information will appear in the return file (CNAB)-
Information

The PIX copy and paste will be returned in the CNAB file at position 029 to 105.

Attention!

If the qr_code_settings object is sent in the request, this wallet will have bolePix generation as its default configuration. BolePix are boletos whose payment is linked to a PIX QR Code. Therefore, the payer can make payment of the boletos either using their readable lines, or by reading the linked PIX QR Codes. If payment is made via QR Code, financial settlement happens instantly. Regarding notifications, two webhooks are sent: one upon PIX transfer (payment notice, boleto goes to payment_notice status); and another a few seconds or minutes later, after confirmation of discharge at CIP/Nuclea (paid, boleto goes to paid status).

cnab_settings Object​

FieldTypeDescriptionCharacters
default_bankstringDefault bank layout for CNAB file processingdefault_bank Enumerators
preferred_layoutstringPreferred layout for CNAB filespreferred_layout Enumerators

default_bank Enumerators​

EnumeratorDescription
santanderSantander Bank
itauItaú Bank
bradescoBradesco Bank
qi_scdQI SCD

preferred_layout Enumerators​

EnumeratorDescription
400CNAB 400 Layout
240CNAB 240 Layout

Response​

STATUS
202
Response Body
{
  "requester_profile_key": "fd86d9b1-2a5e-4e03-9a59-a043c7632c97",
  "requester_profile_code": "329-04-2338-2625918",
  "request_control_key": "0868a24b-4a69-4138-ac4d-ecaeddf0005f",
  "account_key": "0494902f-b21c-4ae6-b37e-854cfe883402",
  "requester_profile_status": "pending",
  "configuration_data": {
    "max_payment_days": 1,
    "protest_settings": {
      "days_to_protest": 0
    },
    "bankruptcy_protest_settings": {
      "days_to_bankruptcy_protest": 0
    },
    "write_off_settings": {
      "days_to_write_off": 0
    },
    "fine_settings": {
      "fine_type": "absolute",
      "fine_amount": 10,
      "days_to_fine": 0
    },
    "interest_settings": {
      "interest_type": "workdays_daily_amount",
      "interest_amount": 10,
      "days_to_interest": 0
    },
    "qr_code_settings": {
      "pix_key": "5df7a433-bd61-4f98-9515-df9aedc2980c",
      "qr_code_on_discharge_enabled": false
    },
    "cnab_settings": {
      "default_bank": "qi_scd",
      "preferred_layout": "400"
    }
  }
}

Response Body Params​

FieldTypeDescriptionCharacters
requester_profile_key *uuidv4Unique wallet identification key in uuid v4 format36
requester_profile_code *stringUnique wallet identification code19
request_control_key *uuidv4Unique request identification key used by the client in uuid v4 format36
account_key *uuidv4Unique account identification key in uuid v4 format36
requester_profile_status *stringWallet statusrequester_profile_status Enumerators
configuration_data *objectWallet default configurationsconfiguration_data Object

profile_status Enumerators​

EnumeratorDescription
pendingWallet accepted and pending confirmation

Error Response​

STATUS
4xx
Response Body: Error
{
  "title": "titulo",
  "description": "description in English",
  "translation": "descrição em portugues",
  "code": "codigo",
  "extra_fields": {}
}
HTTP Code
status		QI Code
code		Title
title		Description (eng)
description		Description (pt-br)
translation
400QIT000001Bad RequestSchema ErrorSchema Inválido
404BKS000001Not FoundPerson not found with key: person_key`Pessoa não encontrada com a chave: person_key`
404BKS000004Not FoundPix key not found: {pix_key}Chave pix não encontrada: {pix_key}
403BKS000005ForbiddenUser is not allowed to do this actionUsuário não tem autorização para fazer essa ação
404BKS000006Not FoundThe source account key was not found.A chave da conta de origem não foi encontrada.
400BKS000007Bad RequestIt was not possible to consult the source account at this time. Please try again in a few minutes.Não foi possível consultar a conta de origem neste momento. Por favor, tente novamente em alguns minutos.
400BKS000008Bad RequestThe source account is closed.A conta de origem está fechada.
400BKS000009Bad RequestThe source account is blocked.A conta de origem está bloqueada.
403BKS000010ForbiddenThe pix key owner does not match the account owner.O proprietário da chave pix não corresponde ao proprietário da conta.
409BKS000014ConflictRequest control key already sent or duplicated sent: {request_control_key}Chave de controle da requisição já utilizada ou enviada duplicada: {request_control_key}
400BKS000047Bad RequestIt was not possible to consult the sent pix key at this time. Please try again in a few minutes.Não foi possível consultar a chave pix enviada no momento. Por favor, tente novamente em alguns minutos.