**[Objeto account_owner PF](#objeto-account_owner-abertura-de-conta-pf)** |
| **signed_contract** * | object | Objeto contendo os dados de contrato e dos assinantes do contrato da conta. | **[Objeto signed_contract](#objeto-signed_contract)** |
| **destinations** ** | list | Lista de contas destino autorizadas a receber transaferências. | **[Objeto destinations](#objeto-destinations)** |
| **additional_documents** | list | Lista de id's de documentos extras/opcionais . | Array de UUID's |
| **guarantee_document_key** | uuidv4 | DOCUMENT_KEY do PDF do documento de caução/garantia do contrato de conta escrow (enviado previamente). (A DOCUMENT_KEY é retornada na resposta do endpoint de [Upload de documentos](./upload_de_documentos)) | 36 |
`(**) Obrigatório para conta Escrow`
### Objeto account_owner Abertura de Conta PJ
| Campo | Tipo | Descrição | Caracteres |
|-------------------------------|------------|-----------------------------------------------------------------------------------------------------------------|-----------------------------------------------------------------------|
| **address** * | object | Objeto endereço do titular da conta | **[Objeto address](#objeto-address)** |
| **cnae_code** * | string | Classificação Nacional de Atividades Econômicas | 9 |
| **company_document_number** * | string | CNPJ | 14 |
| **company_statute** * | uuidv4 | DOCUMENT_KEY do PDF do estatuto da empresa (enviado previamente). | 36 |
| **company_type** * | enumerator | Tipo da empresa | **[Enumeradores company_type](#enumeradores-company_type)** |
| **email** * | string | Email institucional da empresa. | 200 |
| **foundation_date** * | string | Data de abertura da empresa (formato "AAAA-MM-DD"). | 10 |
| **name** * | string | Razão social do titular da conta. | 50 |
| **person_type** * | enumerator | Identificador de que o objeto enviado é uma pessoa jurídica. Deve conter SEMPRE o valor "legal" para Objeto PJ. | **[Enumeradores person_type](#enumeradores-person_type)** |
| **phone** * | object | Telefone do titular da conta. | **[Objeto phone](#objeto-phone)** |
| **trading_name** * | string | Nome fantasia. | 200 |
| **company_representatives** * | list | Lista dos representantes legais da empresa | **[Objeto company_representatives](#objeto-company_representatives)** |
### Objeto account_owner Abertura de Conta PF
| Campo | Tipo | Descrição | Caracteres |
|----------------------------------|---------|-------------------------------------------------------------------------------------------------------------------|-----------------------------------------------------------|
| **address** | string | Objeto endereço do titular da conta | **[Objeto address](#objeto-address)** |
| **birth_date** * | string | Data de nascimento da pessoa (formato "AAAA-MM-DD") | - |
| **document_identification** * | uuidv4 | DOCUMENT_KEY do PDF do documento de identificação da pessoa com foto (RG ou CNH) (enviado previamente) | 36 |
| **email** * | string | Email do titular da conta. | 200 |
| **individual_document_number** * | string | CPF da pessoa (apenas números). | 11 |
| **is_pep** * | boolean | Declaração se a pessoa é PEP (http://www.portaldatransparencia.gov.br/download-de-dados/pep). | - |
| **mother_name** * | string | Nome da mãe do titular da conta. | - |
| **name** * | string | Nome do titular da conta. | - |
| **nationality** * | string | Nacionalidade do cliente. | - |
| **person_type** * | string | Identificador de que o objeto enviado é uma pessoa jurídica. Deve conter SEMPRE o valor "natural" para Objeto PF. | **[Enumeradores person_type](#enumeradores-person_type)** |
| **phone** | string | Objeto com dados do telefone do titular da conta | 36 |
| **proof_of_residence** | uuidv4 | DOCUMENT_KEY do PDF do comprovante de endereço do endereço enviado (enviado previamente). | |
### Objeto address
| Campo | Descrição | Exemplo | Caracteres |
|--------------------|-----------|-------------------------------------------------------------------------------------------|------------|
| **street** * | string | Rua do endereço | 500 |
| **state** * | enum | Estado do endereço (com dois caracteres maiúsculos) | 2 |
| **city** * | string | Cidade do endereço | 255 |
| **neighborhood** * | string | Bairro do endereço | 500 |
| **number** * | string | Número da rua | 10 |
| **postal_code** * | string | CEP do endereço (http://www.buscacep.correios.com.br/sistemas/buscacep/) (apenas números) | 8 |
| **complement** | string | Complemento do endereço (texto livre) | 500 |
### Objeto phone
| Campo | Descrição | Exemplo | Caracteres |
|--------------------|-----------|-------------------------------------------------------|--------------|
| **country_code** * | string | Código DDI do telefone (https://ddi.guiamais.com.br/) | 3 |
| **area_code** * | string | Código DDD do telefone (https://ddd.guiamais.com.br/) | 3 |
| **number** * | string | Número de telefone (apenas números) | 10 |
### Objeto company_representatives
| Campo | Tipo | Descrição | Caracteres |
|------------------------------------|---------|--------------------------------------------------------------------------------------------------------|-----------------------------------------------------------------------------------------|
| **name** * | string | Nome do representante da empresa | 100 |
| **address** * | object | Objeto endereço do representante da empresa | **[Objeto address](#objeto-address)** |
| **email** * | string | Email do representante da empresa | 254 |
| **birth_date** * | string | Data de nascimento representante da empresa (formato "AAAA-MM-DD") | 10 |
| **individual_document_number** * | string | CPF do representante da empresa (apenas números). | 11 |
| **document_identification** * | uuidv4 | DOCUMENT_KEY do PDF do documento de identificação da pessoa com foto (RG ou CNH) (enviado previamente) | 36 |
| **document_identification_number** | string | Número do documento de identificação com foto da pessoa (RG ou CNH) | 16 |
| **document_identification_type** | enum | Tipo do documento de identificação com foto da pessoa (RG ou CNH) | [Enumeradores document_identification_type](#enumeradores-document_identification_type) |
| **is_pep** * | boolean | Declaração se a pessoa é PEP (http://www.portaldatransparencia.gov.br/download-de-dados/pep). | - |
| **final_beneficiary** | boolean | Declaração se o representante é beneficiário final da empresa. | - |
| **marital_status** | enum | Estado civil do representante da empresa | **[Enumeradores marital status](#enumeradores-marital_status)** |
| **mother_name** * | string | Nome da mãe do representante da empresa | 100 |
| **nationality** | string | Nacionalidade do representante da empresa | 50 |
| **person_type** * | enum | Identificador de que o objeto enviado é uma pessoa física | **[Enumeradores person_type](#enumeradores-person_type)** |
| **phone** * | object | Objeto com dados do telefone do representante da empresa | **[Objeto phone](#objeto-phone)** |
### Objeto signed_contract conta livre
| Campo | Tipo | Descrição | Caracteres |
|--------------------|--------|---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|-----------------------------------------|
| **document_key** * | uuidv4 | Chave única de identificação do documento do **Termo de Abertura de Conta** ou **Contrato de Conta Escrow**. (A DOCUMENT_KEY é retornada na resposta do endpoint de [Upload de documentos](./upload_de_documentos)) | 36 |
| **signatures** * | list | Dados de assinatura do documento enviado. Cada item da lista, corresponde a um assinante do documento. | [Objeto signatures](#objeto-signatures) |
### Objeto signatures
| Campo | Tipo | Descrição | Caracteres |
|--------------------|------------|------------------------------------------------------------------------------------|---------------------------------------------|
| **authenticity** * | object | Conjunto de dados que evidenciam a assinatura eletrônica realizada pelo assinante. | [Objeto authenticity](#objeto-authenticity) |
| **signer** * | object | Objeto contendo os dados de um dos assinantes do documento. | [Objeto signer](#objeto-signer) |
| **authentication_type** * | enumerator | Tipo de assinatura. Sempre será "**opt-in**" | "**opt-in**" |
### Objeto authenticity
| Campo | Tipo | Descrição | Caracteres |
|----------------------------|--------|----------------------------------------------------------------------------------------------------------------------------------------------------------------------------|------------|
| **timestamp** * | string | Data e hora do momento da assinatura do documento. | 27 |
| **facial_recognition_key** | uuidv4 | Chave única de identificação da foto da selfie do titular da conta. (A DOCUMENT_KEY é retornada na resposta do endpoint de [Upload de documentos](./upload_de_documentos)) | 36 |
| **lang** | string | Coordenada de longitude da geolocalização do assinante capturada no momento da assinatura. | - |
| **lat** | string | Coordenada de latitude da geolocalização do assinante capturada no momento da assinatura. | - |
| **ip_address** | string | Endereço IP do dispositivo do assinante. | - |
| **session_id** | string | ID da seção do assinante no momento da assinatura. | - |
### Objeto signer
| Campo | Tipo | Descrição | Caracteres |
|-----------------------|--------|-------------------------------------------|-----------------------------------|
| **name** * | string | Nome do assinante. | - |
| **email** * | string | Email do assinante. | - |
| **phone** * | object | Objeto com dados do telefone do assinante | **[Objeto phone](#objeto-phone)** |
| **document_number** * | string | CPF do assinante. | 11 |
### Objeto destinations
| Campo | Tipo | Descrição | Caracteres |
|-----------------------------------------|--------|-----------------------------------------------------------------|------------|
| **account_branch** * | string | Número da Agência da conta destino. | 4 |
| **account_number** * | string | Número da conta destino. | - |
| **account_digit** * | string | Dígito verificador do número da conta destino. | 1 |
| **document_number** * | string | CPF/CNPJ do titular da conta destino. | - |
| **name** * | string | Nome/Razão Social do titular da conta destino. | - |
| **ispb_number** * | string | ISPB (base do CNPJ) da instituição financeira da conta destino. | 8 |
| **financial_institution_code_number** * | string | Código da instituição financeira da conta destino. | 3 |
### Enumeradores person_type
| Enum | Description |
|-------------|-------------------|
| **natural** | Pessoa física |
| **legal** | Pessoa jurídica |
### Enumeradores document_identification_type
| Enum | Description |
|---------|----------------------------------------|
| **rg** | RG - Registro Geral |
| **cnh** | CNH - Carteira Nacional de Habilitação |
### Enumeradores company_type
| Enum | Description |
|-------------------------|---------------------------------------------------------------------------|
| **ltda** | Limitada |
| **sa** | Sociedade Anônima |
| **micro_enterprise** | Micro Empresa |
| **freelancer** | Freelancer |
| **sa_opened** | Sociedade Anônima de Capital Aberto |
| **sa_closed** | Sociedade Anônima de Capital Fechado |
| **se_ltda** | Sociedade Empresária Limitada |
| **se_cn** | Sociedade Empresária em Nome Coletivo |
| **se_cs** | Sociedade Empresária em Comandita Simples |
| **se_ca** | Sociedade Empresária em Comandita por Ações |
| **scp** | Sociedade em Conta de Participação |
| **ei** | Empresário Individual |
| **ese** | Estabelecimento, no Brasil, de Sociedade Estrangeira |
| **eeab** | Estabelecimento, no Brasil, de Empresa Binacional Argentino-Brasileira |
| **ssp** | Sociedade Simples Pura |
| **ss_ltda** | Sociedade Simples Limitada |
| **ss_cn** | Sociedade Simples em Nome Coletivo |
| **ss_cs** | Sociedade Simples em Comandita Simples |
| **eireli_ne** | Empresa Individual de Responsabilidade Limitada (de Natureza Empresária) |
| **eireli_ns** | Empresa Individual de Responsabilidade Limitada (de Natureza Simples) |
| **eireli** | Empresa de Responsabilidade Individual |
| **mei** | Micro Empreendedor Individual |
| **me** | Micro Empresa |
| **cop** | Cooperativa |
| **private_association** | Sociedade Privada |
| **association** | Associação |
| **others** | Outros |
### Enumeradores marital_status
| Enum | Description |
|--------------|---------------|
| **single** | Solteiro(a) |
| **married** | Casado(a) |
| **widower** | Viúvo(a) |
| **divorced** | Divorciado(a) |
| **separated** | Separado(a) |
---
# Manual de Aditamento
URL: /en/documentation/aditamento/manual_aditamento
Este manual descreve o passo a passo envolvido no processo de aditamento. Trata-se do postergamento do prazo da dívida, em que ocorre a mudança na data de vencimento das parcelas e se mantém o número de contrato.
Nesse processo de aditamento, a `final_debt_key` retornada no webhook de desembolso é a nova chave da operação e, após esse processo, novos boletos das parcelas aditadas serão gerados.
O aditamento só é válido para operações pré-fixadas.
## 1 - Criação da operação de aditamento
O campo `desired_installments` é uma lista de objetos com o atributo `due_date`.
O campo de `calculate_delay` só está disponível no Response Body se for enviado na requisição de POST.
Nesse momento, como ainda não houve desembolso da operação originada do aditamento, os campos relacionados ao boleto, como `bank_slip_key`, `digitable_line`, `qr_code_key` e `qr_code_url`, serão nulos.
**1.1.** Simulação:
**Request**
ENDPOINT /amendment_simulation
MÉTODO POST
Request Body
```json
{
"amendment_debt_key": "\",
"amendment_date": "\",
"financial": {
"calculate_delay": "\",
"monthly_rate": "\",
"desired_installments" : [
{
"due_date": "\",
}
]
},
"additional_data": "\",
}
```
**Response**
Response Body
```json
{
"amendment_debt_key": "\",
"amendment_date": "\",
"financial":{
"calculate_delay": "\",
"monthly_rate": "\",
"desired_installments" : [
{
"due_date": "\",
"total_amount": "\",
}
]
},
"additional_data": "\",
"final_debt": {
"annual_cet": "\",
"cet": "\",
"installments":{
"bank_slip_key": "\",
"business_due_date": "\",
"calendar_days": "\",
"digitable_line": "\",
"due_date": "\",
"due_interest": "\",
"due_principal":"\",
"installment_key": "\",
"installment_number": "\",
"post_fixed_amount": "\",
"pre_fixed_amount": "\",
"principal_amortization_amount": "\",
"qr_code_key": "\",
"qr_code_url": "\",
"total_amount": "\",
"workdays": "\",
},
"prefixed_interest_rate": {
"annual_rate": "\",
"daily_rate": "\",
"interest_base": "\",
"monthly_rate": "\",
},
"issue_amount": "\",
"number_of_installments": "\",
"total_iof": "\"
}
}
```
**1.2.** Criação:
**Request**
ENDPOINT /amendment
MÉTODO POST
Request Body
```json
{
"amendment_debt_key": "\",
"amendment_date": "\",
"financial": {
"calculate_delay": "\",
"monthly_rate": "\",
"desired_installments" : [
{
"due_date": "\",
}
]
},
"additional_data": "\",
}
```
**Response**
Response Body
```json
{
"amendment_key": "\",
"amendment_debt_key": "\",
"amendment_date": "\",
"financial":{
"calculate_delay": "\",
"monthly_rate": "\",
"desired_installments" : [
{
"due_date": "\",
"total_amount": "\",
}
]
},
"additional_data": "\",
"amendment_status": "waiting_signature",
"document_key": "\",
"document_url": "\",
"final_debt": {
"annual_cet": "\",
"cet": "\",
"installments":{
"bank_slip_key": "\",
"business_due_date": "\",
"calendar_days": "\",
"digitable_line": "\",
"due_date": "\",
"due_interest": "\",
"due_principal":"\",
"installment_key": "\",
"installment_number": "\",
"post_fixed_amount": "\",
"pre_fixed_amount": "\",
"principal_amortization_amount": "\",
"qr_code_key": "\",
"qr_code_url": "\",
"total_amount": "\",
"workdays": "\",
},
"prefixed_interest_rate": {
"annual_rate": "\",
"daily_rate": "\",
"interest_base": "\",
"monthly_rate": "\",
},
"issue_amount": "\",
"number_of_installments": "\",
"total_iof": "\"
}
}
```
Em relação a simulação, o Response Body da criação se diferencia pela presença da `amendment_key`, da `amendment_status`, da `document_key` e da `document_url`.
Na criação do operação de aditamento, sempre se retorna o `amendment_status` como "waiting_signature".
## 2 - GET da operação de aditamento
**Request**
ENDPOINT /amendment/[AMENDMENT_KEY]
MÉTODO GET
O `amendment_key` que deve ser enviado para realização do GET é o valor do campo, de mesmo nome, retornado na criação da operação de aditamento e que representa a chave unitária característica do aditamento.
**Response**
Response Body
```json
{
"amendment_key": "\",
"amendment_debt_key": "\",
"amendment_date": "\",
"financial":{
"calculate_delay": "\",
"monthly_rate": "\",
"desired_installments" : [
{
"due_date": "\",
"total_amount": "\",
}
]
},
"additional_data": "\",
"amendment_status": "\",
"document_key": "\",
"document_url": "\",
"final_debt": {
"annual_cet": "\",
"cet": "\",
"installments":{
"bank_slip_key": "\",
"business_due_date": "\",
"calendar_days": "\",
"digitable_line": "\",
"due_date": "\",
"due_interest": "\",
"due_principal":"\",
"installment_key": "\",
"installment_number": "\",
"post_fixed_amount": "\",
"pre_fixed_amount": "\",
"principal_amortization_amount": "\",
"qr_code_key": "\",
"qr_code_url": "\",
"total_amount": "\",
"workdays": "\",
},
"prefixed_interest_rate": {
"annual_rate": "\",
"daily_rate": "\",
"interest_base": "\",
"monthly_rate": "\",
},
"issue_amount": "\",
"number_of_installments": "\",
"total_iof": "\"
}
}
```
**Response Canceled**
Response Body
```json
{
"amendment_key": "\",
"amendment_debt_key": "\",
"amendment_date": "\",
"financial":{
"calculate_delay": "\",
"monthly_rate": "\",
"desired_installments" : [
{
"due_date": "\",
"total_amount": "\",
}
]
},
"additional_data": "\",
"amendment_status": "canceled",
"cancel_reason": {
"enumerator": "non_signed_amendment",
"description": "It wasn't possible to effect the amendment of the operation, because the amended operation hasn't been signed until the sent reference date (2023-09-19).",
"translation": "Não foi possível efetivar o aditamento da operação, pois a operação de aditamento não foi assinada até a data de referência enviada (2023-09-19)."
},
"document_key": "\",
"document_url": "\",
"final_debt": {
"annual_cet": "\",
"cet": "\",
"installments":{
"bank_slip_key": "\",
"business_due_date": "\",
"calendar_days": "\",
"digitable_line": "\",
"due_date": "\",
"due_interest": "\",
"due_principal":"\",
"installment_key": "\",
"installment_number": "\",
"post_fixed_amount": "\",
"pre_fixed_amount": "\",
"principal_amortization_amount": "\",
"qr_code_key": "\",
"qr_code_url": "\",
"total_amount": "\",
"workdays": "\",
},
"prefixed_interest_rate": {
"annual_rate": "\",
"daily_rate": "\",
"interest_base": "\",
"monthly_rate": "\",
},
"issue_amount": "\",
"number_of_installments": "\",
"total_iof": "\"
}
}
```
## 3 - Cancelamento da operação de aditamento
**Request**
ENDPOINT /amendment/[AMENDMENT_KEY]
MÉTODO DELETE
O `amendment_key` que deve ser enviado para realização do DELETE é o valor do campo, de mesmo nome, retornado na criação da operação de aditamento e que representa a chave unitária característica do aditamento.
No DELETE do aditamento, não há payload de resposta e o status da operação de aditamento é alterado para "canceled".
## 4 - Webhooks
:::danger Atenção!
Os webhooks da QI Tech não devem ser mapeadas de forma restrita.
Campos adicionais podem ser incluídos aos payloads dos webhooks retornados em nossas APIs.
:::
:::info Reenvio de Webhooks
Você pode consultar e reenviar webhooks seguindo as instruções detalhadas na documentação: [Reenvio de Webhooks](/documentation/notificacoes/reenvio_de_notificacoes).
:::
Abaixo estão descritos os webhooks que serão enviados nas situações de assinatura, de desembolso e de cancelamento da operação de aditamento.
**4.1.** Assinatura:
Body
```json
{
"webhook_type": "amendment",
"amendment_key": "\",
"event_datetime": "\",
"data": {
"amendment_status": "signed",
"document_key": "\",
"signed_document_url": "\"
}
}
```
**4.2.** Desembolso:
Body
```json
{
"webhook_type": "amendment",
"amendment_key": "\",
"event_datetime": "\",
"data": {
"amendment_status": "disbursed",
"final_debt_key": "\",
"installments": [
{
"bank_slip_key": "\",
"business_due_date": "\",
"calendar_days": "\",
"digitable_line": "\",
"due_date": "\",
"due_interest": "\",
"due_principal":"\",
"installment_key": "\",
"installment_number": "\",
"post_fixed_amount": "\",
"pre_fixed_amount": "\",
"principal_amortization_amount": "\",
"qr_code_key": "\",
"qr_code_url": "\",
"total_amount": "\",
"workdays": "\"
}
]
}
}
```
**4.3.** Cancelamento:
Body
```json
{
"webhook_type": "amendment",
"amendment_key": "\",
"event_datetime": "\",
"data": {
"amendment_status": "canceled",
"cancel_reason": {
"enumerator": "\",
"description": "\",
"translation": "\"
}
}
}
```
A cancel_reason segue os seguintes enumeradores: **[Enumerador Cancel Reason](#enumerador-cancel-reason)**.
## 5 - Informações Gerais
A referência anterior nos campos `calendar_days` ou `workdays` é a data de desembolso na primeira parcela e a data de vencimento da parcela anterior nos demais casos.
O campo installments é uma lista preenchida de objetos. Nesse caso, para cada parcela do aditamento, deve haver um objeto com as respectivas informações.
| Campo | Tipo | Exemplo | Observações |
|---| ---| ---| ---|
| `additional_data` | json | { } | Não é obrigatório seu envio |
| `amendment_key` | string | 5fd3ecc8-1ea5-4d23-835c-37338da96181 | |
| `amendment_date` | string | "2023-06-05" | |
| `amendment_debt_key` | string | 31327efa-a96e-4a17-b703-e9fc39e17902 | |
| `amendment_status` | enumerador | **[Enumerador Amendment Status](#enumerador-amendment-status)** | |
| `annual_cet` | float | 0.0012 | |
| `annual_rate` | float | 0.0012 | |
| `bank_slip_key` | string | aea9ab16-d211-4c17-8f46-8a2669154a37 | |
| `business_due_date` | string | "2023-10-05" | |
| `calculate_delay` | bool | True | Não é obrigatório seu envio e é default como Falso |
| `calendar_days` | int | 27 | |
| `cet` | float | 0.0012 | |
| `daily_rate` | float | 0.0012 | |
| `digitable_line` | string | 32990001031000699925351000000201192690000055231 | |
| `document_key` | string | 7f49d9ff-0878-4d48-8cc3-cb0c3c6769d2 | |
| `document_url` | string | "https://storage.googleapis.com/sandbox-doc-api/documents/7f49d9ff-0878-4d48-8cc3-cb0c3c6769d2/image_166618030043.jpg" | |
| `due_date` | string | "2023-06-05" | |
| `due_interest` | float | 0.0 | |
| `due_principal` | float | 1000.10 | |
| `event_datetime` | string | "2023-05-05T22:20:10Z" | |
| `final_debt_key` | string | 8779a554-1ec9-40ec-8ff2-cbd52fc776ef | Essa é a nova debt key |
| `installment_number` | int | 3 | |
| `installment_key` | string | 1b65d775-b5ab-49d5-a833-46980387afb1 | |
| `interest_base` | enumerador | **[Enumerador Interest Base](#enumerador-interest-base)** | |
| `issue_amount` | float | 1000.00 | |
| `monthly_rate` | float | 0.0012 | |
| `number_of_installments` | int | 3 | |
| `post_fixed_amount` | int | 0 | Sempre zero, já que o aditamento só é válido para operações pré-fixadas |
| `pre_fixed_amount` | float | 2.00 | |
| `principal_amortization_amount` | float | 20.00 | |
| `qr_code_key` | string | 003590d0-29f8-4d18-93bb-a7c36f0f1785 | |
| `qr_code_url` | string | "00020126970014br.gov.bcb.pix2575qrcode-h.sandbox.qitech.app/bacen/cobv/cf7d2d2e-003a-4296-9daf-350864d282245204000053039865802BR5925QI SOCIEDADE DE CREDITO D6009Sao Paulo61080145200062070503***63047335"| |
| `signed_document_url` | string | "https://storage.googleapis.com/sandbox-doc-api/documents/7f49d9ff-0878-4d48-8cc3-cb0c3c6769d2/image_166618030043.jpg" | |
| `total_amount` | float | 100.00 | |
| `total_iof` | float | 11.03 | |
| `workdays` | int | 10 | |
### Enumerador _Interest Base_
| Enumerador | Descrição |
|-----------------------|---------------------------------------------------------------------------|
| **workdays** | Base de cálculo de juros em dias úteis considerando um ano de 252 dias |
| **calendar_days** | Base de cálculo de juros em dias corridos considerando um ano de 360 dias |
| **calendar_days_365** | Base de cálculo de juros em dias corridos considerando um ano de 365 dias |
### Enumerador _Amendment Status_
| Enumerador | Descrição |
|-----------------------|---------------------------------------------------------------------------|
| **waiting_signature** | Aguardando assinatura |
| **signed** | Assinada |
| **disbursed** | Desembolsada |
| **canceled** | Cancelada |
| **disbursing_error** | Erro no momento do desembolso |
:::caution Atenção!
O status 'disbursing_error' representa um status intermediário, o contrato de aditamento será cancelado ou desembolsado.
:::
### Enumerador _Cancel Reason_
| Enumerador | Descrição |
|---------------------------|------------------------------------------------------------------------------|
| **delete_amendment** | Requisição no endpoint de DELETE |
| **non_signed_amendment** | Operação de aditamento não foi assinada até a data de referência enviada (amendment_date) |
| **different_balance_due** | Saldo devedor diferente entre a criação da operação de aditamento e o desembolso |
| **different_installments_number** | Número de parcelas em aberto diferente entre a criação da operação de aditamento e o desembolso |
---
# Schedule boleto payment
URL: /en/documentation/agendamentos/agendamento_boleto
It follows the same principle as payment in other flows, with the main difference being that you must send the schedule_date, and in this case, you will receive the schedule_key.
## Request
ENDPOINT /bank_slip/payment
METHOD POST
Request Body
```json
{
"digitable_line": "32990001031000000001708001075103794890000015000",
"source_account_key": "6d30a0b1-cb90-4ceb-b1ea-5bd600cdf3c8",
"payment_date": "2023-09-25",
"transaction_amount": 150.00
}
```
### Body params
| Field | Type | Description | Characters |
|--------------------------|--------|-------------------------------------------------------------------|------------|
| `digitable_line` * | string | Boleto's digitable line. | - |
| `resource_account_key` * | string | Key of the account to be used. | - |
| `payment_date` * | date | Date for payment. If not sent, the date will be today. | - |
| `transaction_amount` | float | Amount to be paid. | - |
:::info Information
To view the accepted payment agreements, [click here](https://storage.googleapis.com/live-doc-api/public_samples/convenios_qi_tech.xlsx).
:::
## Response
STATUS 200
Response Body: Payment through a free movement account
```json
{
"data": {
"digitable_line": "09990001029100010009895007444201283400000001000",
"resource_account_key": "21af482f-b8ac-48dd-8f9a-ea23429d28be"
},
"event_datetime": "2020-08-06 19:22:06",
"key": "e7719f95-a31d-4171-ae83-2d8b3d419dc2",
"status": "waiting_approval",
"webhook_type": "bank_slip_payment"
"schedule_key": "e7719f95-a31d-4171-ae83-2d8b3d419dc2"
}
```
STATUS 200
Response Body: Payment through a escrow account
```json
{
"data": {
"digitable_line": "09990001029100010009895007444201283400000001000",
"resource_account_key": "21af482f-b8ac-48dd-8f9a-ea23429d28be"
},
"event_datetime": "2020-08-06 19:22:06",
"key": "e7719f95-a31d-4171-ae83-2d8b3d419dc2",
"status": "waiting_approval",
"webhook_type": "bank_slip_payment",
"schedule_key": "e7719f95-a31d-4171-ae83-2d8b3d419dc2"
}
```
STATUS 400
Response Body
```json
{
"data": "{\"title\": \"Bad Request\", \"description\": \"Invalid request body.\", \"translation\": \"Corpo da requisição inválido.\", \"extra_fields\": {}, \"code\": \"LEG000069\"}"
}
```
---
# Schedule Pix Transfer
URL: /en/documentation/agendamentos/agendamento_pix
It follows the same principle as Pix transfer, with the main difference being that you must send the schedule_date, and in this case, you will receive the schedule_key.
## Request
ENDPOINT /baas/pix_transfer
METHOD POST
**Manual**
Request Body: Manual transfer
```json
{
"pix_transfer_type": "manual",
"source_account": {
"account_branch": "0001",
"account_digit": "2",
"account_number": "2359934",
"owner_document_number": "09080702000105"
},
"schedule_date": "2023-08-24",
"target_account": {
"bank_code": "104",
"account_branch": "0001",
"account_digit": "4",
"account_number": "6717606",
"owner_document_number": "60744463000190",
"owner_name": "Qi Tech",
"account_type": "checking",
"ispb": "32402502"
},
"transaction_amount": 15
}
```
## Response
STATUS 200
Response Body: Manual transfer
```json
{
"data": {
"operation_key": "8cb70dea-9fb0-4a68-9572-99a72849c8d6",
"status": "pending",
"event_datetime": "2021-08-04 20:05:54",
"pix_transfer_key": "8cb70dea-9fb0-4a68-9572-99a72849c8d6",
"pix_transaction": {
"pix_message": "",
"pix_transfer_key": "8cb70dea-9fb0-4a68-9572-99a72849c8d6",
"transaction_amount": 1891268.97,
"source_account": {
"account_branch": "0001",
"account_digit": "3",
"account_number": "24339",
"owner_document_number": "32402502000135",
"owner_name": "Qi Tech",
"account_type": "checking"
},
"target_account": {
"target_account": "78340-6",
"financial_institution_code": "329",
"owner_document_number": "32402502000135",
"owner_name": "QI Tech",
"target_account_type": "checking_account",
"owner_person_type": "legal",
"trading_name": "QITech"
},
"fee_amount": 0,
"schedule_date": "2020-08-04"
}
}
}
```
**Chave**
Request Body: Key transfer
```json
{
"pix_transfer_type": "key",
"source_account": {
"account_branch": "0001",
"account_digit": "2",
"account_number": "2359934",
"owner_document_number": "09080702000105"
},
"schedule_date": "2023-08-24",
"end_to_end_id": "E32402502202308231745g1goFJ577mp",
"pix_key":"52720072800",
"target_account": {
"bank_code": "104",
"account_branch": "0001",
"account_digit": "4",
"account_number": "6717606",
"owner_document_number": "60744463000190",
"owner_name": "Qi Tech",
"ispb": "32402502"
},
"transaction_amount": 15
}
```
## Response
STATUS 200
Response Body: Key transfer
```json
{
"data": {
"end_to_end_id": "E32402502202308231825nkKhXiA9DEA",
"fee_amount": 1,
"pix_message": "",
"pix_transfer_key": "c32ad14a-6bfe-43f4-b5a1-4f335dcdd543",
"source_account": {
"account_brach": "0001",
"account_digit": "2",
"account_number": "2359934",
"account_type": "checking",
"owner_document_number": "09080702000105",
"owner_name": "VOVO LUCIA CONVENIENCIA LTDA"
},
"target_account": {
"document_number": "***.951.18*-**",
"financial_institution": "CAIXA ECONOMICA FEDERAL"
},
"transaction_amount": 15,
"transfer_purpose": "transfer"
},
"event_datetime": "2023-08-23 15:25:36",
"operation_key": "b37224f2-9a8c-4816-b446-acb213bfe5f0",
"schedule_key": "c32ad14a-6bfe-43f4-b5a1-4f335dcdd543",
"status": "pending_approval"
}
```
### Body Params
| Field | Type | Description | Characters |
|---|---| ---| ---|
| `pix_transfer_type` * | string | Pix has different types of initiation: "manual", where the user must send the destination and source account fields, and "key", where the user must send the Pix key fields of the receiver (destination account) and the source account details. | 10 |
| `source_account` * | Object | Source account. | **[Object source_account](#object-source_account)** |
| `target_account` | Object | Destination account - Should only be sent in transactions of type "manual". | **[Object target_account](#object-target-account)** | 10 |
| `transaction_amount` * | string | Transfer amount. | 10 |
| `schedule_date` | date | Scheduled date of the transaction (if not sent, the transfer is made at the time of approval). | 10 |
| `receiver_conciliation_id` | string | Receiver's conciliation ID. | 10 |
| `is_chargeback` | string | Flag identifying a Pix transaction refund (boolean True or False). | 10 |
| `requester_document_identification` * | string | CPF of the user requesting the transfer. | 10 |
| `pix_transfer_key` | string | Idempotency key of a Pix transaction - should only be sent if the transfer type is "key". | 10 |
| `chargeback_amount` | string | Refund amount - This field should be sent only in case of chargeback and excludes the requirement for the "transaction_amount" field. | 10 |
| `chargeback_other_reason` | string | Refund reason (This field should be sent only in case of chargeback). | 10 |
| `chargeback_message` | string | Field for the user to insert a message during the refund (This field should be sent only in case of chargeback). | 10 |
### Object source_account
| Field | Type | Description | Characters |
|---|---| ---| ---|
| `account_branch` * | string | Branch number. | 0 |
| `branch_digit` | string | Branch digit. | 0 |
| `account_digit` * | string | Account digit. | 0 |
| `account_number` * | string | Account number. | 0 |
| `owner_document_number` * | string | CPF or CNPJ (numbers only) of the account holder. | 0 |
### Object target_account
| Field | Type | Description | Characters |
|---|---| ---| ---|
| `account_branch` * | string | Branch. | 10 |
| `account_digit` * | string | Account digit. | 10 |
| `account_number` * | string | Account number. | 10 |
| `owner_document_number` * | string | CPF or CNPJ (numbers only) of the account holder. | 10 |
| `owner_name` * | string | Account holder's name. | 10 |
| `account_type` * | string | CPF or CNPJ (numbers only) of the account holder. | 10 |
| `trading_name` | string | Trade name for legal entities. | 10 |
| `ispb` | string | Eight-digit code that identifies banks in the Central Bank's reserve transfer system. | 10 |
## Response
STATUS 400
Response Body
```json
{
"data": "{\"title\": \"Bad Request\", \"description\": \"Invalid request body.\", \"translation\": \"Corpo da requisição inválido.\", \"extra_fields\": {}, \"code\": \"LEG000069\"}"
}
```
---
# Schedule TED Transfer
URL: /en/documentation/agendamentos/agendamento_ted
It follows the same principle as a regular transfer, with the main difference being that you must send the schedule_date, and in this case, you will receive the schedule_key.
## Request
ENDPOINT /wire_transfer
METHOD POST
Request Body
```json
{
"source_account": {
"account_branch": "0001",
"account_number": "9477323",
"account_digit": "0",
"owner_document_number": "38299588000107"
},
"target_account": {
"financial_institution_code": "341",
"account_branch": "0001",
"account_number": "92796",
"account_digit": "1",
"owner_document_number": "23599885000192",
"owner_name": "plugify"
},
"schedule_date": "2023-10-10",
"transaction_amount": 8.86
}
```
### BODY PARAMS
| Field | Type | Description | Characters |
|---|---| ---| ---|
| `source_account` * | object | Source account. | **[Object source_account](#object-source_account)** |
| `target_account` * | object | Destination account. | **[Object target_account](#object-target_account)** |
| `transaction_amount` * | double | Transfer amount. | 10 |
| `schedule_date` * | date | Scheduled date of the transaction, if not specified the transaction will be made at the time of sending or as soon as approved. | 10 |
### Object source_account
| Field | Type | Description | Characters |
|---|---| ---| ---|
| `account_branch` * | string | Branch. | 10 |
| `account_digit` * | string | Account digit. | 10 |
| `account_number` * | string | Account number. | 10 |
| `owner_document_number` * | string | CPF or CNPJ (numbers only) of the account holder. | 10 |
| `target_account_type` * | string | Destination account type | **[Enumerators](#enumeradores-ted_account_type)** |
### Object target_account
| Field | Type | Description | Characters |
|---|---| ---| ---|
| `account_branch` * | string | Branch. | 10 |
| `account_digit` * | string | Account digit. | 10 |
| `account_number` * | string | Account number. | 10 |
| `owner_document_number` * | string | CPF or CNPJ (numbers only) of the account holder. | 10 |
| `owner_name` * | string | Account holder's name. | 10 |
### Enumerators target_account_type
| Enumerator | Translation |
|---|---|
| checking_account | current account |
| deposit_account | deposit account |
| guaranteed_account | guarantee account |
| investment_account | investment account |
| payment_account | payment account |
| saving_account | savings account |
## Response
### Transfer from a free movement account
STATUS 200
Response Body
```json
{
"data": {
"outgoing_ted_key": null,
"schedule_date": "2023-10-10",
"schedule_key": "3be3e5ef-5e43-4d04-b987-be80ae983529",
"source_account": {
"account_branch": "0001",
"account_digit": "0",
"account_number": "9477323",
"owner_document_number": "38299588000107"
},
"target_account": {
"account_branch": "0001",
"account_digit": "1",
"account_number": "92796",
"financial_institution_code": "341",
"owner_document_number": "23599885000192",
"owner_name": "plugify"
},
"transaction_amount": 8.86
},
"event_datetime": "2023-08-23 19:40:54",
"key": "2b198f4d-1b1d-4116-8cd6-ec3da64e6b96",
"status": "success",
"webhook_type": "wire_transfer"
}
```
### Transferência a partir de uma conta de escrow
STATUS 200
Response Body
```json
{
"data": {
"source_account": {
"account_branch": "0001",
"account_digit": "3",
"account_number": "24339",
"owner_document_number": "32402502000135"
},
"target_account": {
"account_branch": "0001",
"account_digit": "6",
"account_number": "78340",
"financial_institution_code": "329",
"owner_document_number": "32402502000135",
"owner_name": "QI Tech"
},
"transaction_key": "7986dcc7-4331-478f-af47-adfbdf7f4a36",
"transaction_amount": 1891268.97
},
"event_datetime": "2019-11-28 19:22:04",
"key": "fa80723e-4f9a-42b1-9410-d5fa3c183fa8",
"status": "success",
"webhook_type": "wire_transfer"
}
```
STATUS 400
Response Body
```json
{
"data": "{\"title\": \"Bad Request\", \"description\": \"Invalid request body.\", \"translation\": \"Corpo da requisição inválido.\", \"extra_fields\": {}, \"code\": \"LEG000069\"}"
}
```
---
# Cancellation of scheduling
URL: /en/documentation/agendamentos/cancelar_agendamento
## Request
ENDPOINT /account/transaction/schedule/SCHEDULED_TRANSACTION_KEY/cancel
METHOD PATCH
Request Body
```json
{
"reason": "reason (opcional)"
}
```
### PATH PARAMS
| Field | Type | Description |
|---------------|--------|------------------------------------|
| `SCHEDULED_TRANSACTION_KEY` | string | Key that identifies the scheduling |
Response Body
```json
{}
```
STATUS 400
Response Body
```json
{
"data": "{\"title\": \"Bad Request\", \"description\": \"Invalid request body.\", \"translation\": \"Corpo da requisição inválido.\", \"extra_fields\": {}, \"code\": \"LEG000069\"}"
}
```
:::danger General Observations:
Only approved schedules are subject to cancellation when approval is applicable!
:::
---
# List of scheduled transactions
URL: /en/documentation/agendamentos/consulta_agendamentos
## Request
ENDPOINT /account/ACCOUNT_KEY/scheduled_transactions
METHOD GET
### QUERY PARAMS
| Field | Description |
|----------------------|--------------------------------------------|
| `status` | Status of a boleto |
| `date` | Date of the scheduling. |
| `page_number` | Current page being consulted |
| `page_size` | Number of results per page |
### PATH PARAMS
| Field | Description |
|----------------------|--------------------------------------------|
| `ACCOUNT_KEY` | account_key of the source account of the transactions |
## Response
STATUS 200
Response Body
```json
{
"data": [{
"outgoing_pix_key": "chave da schedule",
"outgoing_ted_key": "chave da schedule",
"schedule_date": "iso date string",
"source_account_key": "chave da conta de origem da transação",
"target_account_bank_code": "banco destino (opcional)",
"target_account_bank_ispb": "ispb destino (opcional)",
"target_account_branch": "agencia destino",
"target_account_number": "conta de destino",
"target_account_digit": "digito conta destino",
"target_account_type": "tipo de conta destino (opcional)",
"beneficiary_name": "nomoe do beneficiario",
"beneficiary_document_number": "documento do beneficiario (cpf/cnpj)",
"scheduled_amount": "valor agendadp",
"beneficiary_person_type": "tipo de beneficiario",
"target_account_key": "chave da conta destino (opcional)",
"source_subtype": "tipo de transação (enum)",
"created_at": "data em que o agendamento foi feito",
"status": "status do agendamento",
"pix_key": "chave pix destino (opcional)",
"cancellation_requester": "identificação do requisitor do cancelamento",
"cancellation_reason": "origem do cancelamento (enum)",
"updated_at": "data de atualização"
}],
"pagination": {
"current_page": 1,
"next_page": null,
"rows_per_page": 10
}
}
```
:::danger General Observations:
Only approved schedules will be listed when approval is applicable!
:::
---
# arranjos_e_adquirentes
URL: /en/documentation/arranjos_e_adquirentes/
## Arranjos e Adquirentes
### Adquirentes
As adquirentes são empresas como a Stone, a Cielo e a Rede, e seu papel é liquidar as transações financeiras por meio de cartão de crédito e débito. Para isso, elas se comunicam com as bandeiras de cartão e os bancos emissores (como Nubank, Itaú, Santander etc.) para processar as transações.
Lista de adquirentes:
| Nome | CNPJ |
|---|---|
|BRB – BANCO DE BRASÍLIA S.A|208000100|
|CIELO S.A.|1027058000191|
|BANCO COOPERATIVO SICREDI S.A.|1181521000155|
|REDECARD S.A.|1425787000104|
|CREDICARD|1425787003383|
|VERDECARD ADMINISTRADORA DE CARTÕES S.A.|1722480000167|
|WORLDPAY DO BRASIL PROCESSAMENTO DE PAGAMENTOS LTDA|991143000102|
|BANCO COOPERATIVO DO BRASIL S.A.|2038232000164|
|CABAL BRASIL LTDA|3766873000106|
|CRED-SYSTEM|4670195000138|
|FD DO BRASIL SOLUÇÕES DE PAGAMENTO LTDA|4962772000165|
|PAGSEGURO INTERNET S.A.|8561701000101|
|ELO SERVIÇOS S.A|9227084000175|
|GETNET ADQUIRENCIA E SERVIÇOS PARA MEIOS DE PAGAMENTO S.A.|10440482000154|
|MERCADO.COM REPRESENTAÇÕES LTDA|10573521000515|
|ELAVON DO BRASIL SA|12592831000189|
|SAQUE E PAGUE REDE DE AUTOATENDIMENTO|12901364000121|
|HUB PAGAMENTOS S.A.|13884775000119|
|ADYEN DO BRASIL LTDA|14796606000190|
|STONE PAGAMENTOS S.A.|16501555000157|
|BANCO TRIÂNGULO S.A|17351180000159|
|CLOUDWALK MEIOS DE PAGAMENTOS E SERVICOS LTDA|18189547000142|
|BANCO BONSUCESSO S.A. ADQUIRENTE|20520298000178|
|BANCO BONSUCESSO S.A. ADQUIRENTE|20520298000178|
|STRIPE BRASIL SOLUÇÕES DE PAGAMENTO LTDA|22121209000146|
|BMG GRANITO SOLUÇÕES EM PAGAMENTO S.A|22177858000169|
|BOLT CARD CREDENCIADORA DE CARTAO DE CREDITO LTDA|28080769000186|
|BEN BENEFÍCIOS E SERVIÇOS S.A.|30798783000161|
|LISTO INSTITUIÇÃO DE PAGAMENTO LTDA|32971064000126|
|ACQIO ADQUIRÊNCIA S.A|33171211000146|
|BANCO SAFRA S.A.|58160789000128|
|BANCO SMARTBANK S.A.|58497702000102|
|SOROCRED MEIOS DE PAGAMENTO|60114865000100|
|BANCO CREFISA S.A|61033106000186|
|BANCO RENDIMENTO S.A|68900810000138|
|BANRISUL CARTÕES S.A|92934215000106|
|Global Payments - Servicos de Pagamentos S.a.|17887874000105|
|POVIG TECNOLOGIA EM PAGAMENTOS ELETRONICOS LTDA.|35524559000103|
### Arranjos de Pagamentos
Os arranjos de pagamentos são, basicamente, um conjunto de regras, regulamentos e processos que permitem a realização de serviços financeiros, como saques, transferências, emissão de cartão de crédito, débito e outras soluções de pagamento.
Lista de arranjos:
| Código | Descrição |
|---|---|
|ACC|Amex Cartão de Crédito|
|BCC|Banescard Cartão de Crédito|
|BCD|Banescard Cartão de Débito|
|BVV|Banescard Cartão de Débito|
|BVV|Ben Visa Vale|
|CAC|Cielo Amex Crédito|
|CBC|Cabal Crédito|
|CBD|Cabal Débito|
|CBP|Cabal Pré-pago|
|CDC|Cielo Diners Cartão de Crédito|
|CEC|Cielo Elo Cartão de Crédito|
|CED|Cielo Elo Cartão de Débito|
|CHC|Cielo Hipercard Crédito|
|CMC|Cielo Mastercard Crédito|
|CMD|Cielo Mastercard Débito|
|CZC|Credz Crédito|
|DCC|Diners Cartão de Crédito|
|ECC|Elo Cartão de Crédito|
|ECD|Elo Cartão de Débito|
|GCC|Goodcard Crédito|
|GDC|Global Payments Diners Crédito|
|GMC|Global Payments Mastercard Crédito|
|GMD|Global Payments Mastercard Débito|
|GVC|Global Payments Visa Crédito|
|GVD|Global Payments Visa Débito|
|HCC|Hipercard Cartão de Crédito|
|JCC|JCB Cartão de Crédito|
|MAC|Mais Cartão de Crédito|
|MCA|Mastercard Cartão ATM|
|MCC|Mastercard Cartão de Crédito|
|MCD|Mastercard Cartão de Débito|
|MCP|Mastercard Cartão Pré-pago|
|OCD|Ourocard Cartão de Débito|
|SCC|Sorocred Cartão de Crédito|
|SCD|Sorocred Cartão de Débito|
|VCA|Visa Cartão ATM|
|VCC|Visa Cartão de Crédito|
|VCD|Visa Cartão de Débito|
|VCP|Visa Cartão Pré-pago|
|VDC|Verdecard Cartão de Crédito|
|VIC|Visa Internacional Compra Crédito|
|VID|Visa Internacional Compra Débito|
|HCD|Hiper Débito|
|SIC|Sicredi|
|BRS|Banrisul|
|CUP|Cup Crédito|
|FRC|Fortbrasil|
|MXC|Maxifrota|
|SFC|Senff|
|TKC|TicketLog|
|BNC|Banese Card|
|BRC|Brasil Card|
|SPC|Sem Parar|
|CSC|Credi-Shop|
|DAC|Dacasa|
|AGC|Agiplan|
|AUC|Aura|
|RCC|Redesplan|
|AVC|Avista|
|CCD|Calcard|
|DBC|Discover|
|99T|Todas|
---
# Criar uma renegociação
URL: /en/documentation/arranjos_e_adquirentes/consulta_de_agenda
## Request
ENDPOINT /debt
MÉTODO POST
Request Body
```json
{
"notification_type": "webhook",
"owner_person_type": "legal",
"owner_person_name": "John Sample Inc",
"owner_document_number": "86498542000151",
"reference_code": "5830c2f9-fd17-4c9c-b30c-68ddd1a92751",
"signature": {
"signers": [
{
"name": "John Sample",
"email": "john.sample@yopmail.com",
"person_type": "natural",
"document_number": "42889916090"
}
]
},
"agenda": {
"acquirers": [
"cdc"
],
"card_schemes": [
"cdc"
],
"end_date": "2021-06-23",
"start_date": "2021-06-23"
}
}
```
:::caution Atenção!
O payload ultilizado na emissão de um refinanciamento é o mesmo ultilizado na emissã de uma divida simples, com a adição da lista de operações que serão quitadas em **"refinanced_credit_operations"**.
:::
### Body Params
| Campo | Tipo | Descrição | Máx. Caract. |
|---------------------------------|--------|------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|--------------|
| **notification_type** * | enum | tipo de notificação | - |
| **owner_person_type** * | enum |Tipo de pessoa (natural ou juridica) objeto da consulta de agenda. | - |
| **owner_person_name** * | string | Nome do objeto da consulta de agenda. | - |
| **owner_document_number** * | string | Numero de documento do objeto da consulta de agenda. | - |
| **reference_code** * | object | Identificador único do opt-in. | - |
| **signature** * | object | Informações do opt-in. refinanciadas. | - |
| **agenda** * | object | Parâmetros para a consulta de agenda. | - |
## Definições
### Objeto agenda
| Campo | Tipo | Descrição | Máx. Caract. |
|---------------------------------|--------|------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|--------------|
| **acquirers** * | array | Lista de números de documentos da Credenciadoras. | - |
| **card_schemes** * | array | Lista de arranjos de pagamento. | - |
| **end_date** * | string | Data de termino da consulta. | - |
| **start_date** * | string | Data de início da consulta. | - |
# Enumeradores
### Enumerador _Person Type_
| Enumerador | Descrição |
|------------------------|-----------------------|
| **legal** | Pessoa juridica |
| **natural** | Pesso física |
### Enumerador _Account Type_
| Enumerador | Descrição |
|------------------------|-----------------------|
| **webhook** | Conta corrente |
## Response
STATUS 200
Response Body
```json
{}
```
STATUS 400
Response Body
```json
{
"data": "{\"title\": \"Bad Request\", \"description\": \"Invalid request body.\", \"translation\": \"Corpo da requisição inválido.\", \"extra_fields\": {}, \"code\": \"LEG000069\"}"
}
```
---
# trava_de_domicilio_bancario
URL: /en/documentation/arranjos_e_adquirentes/trava_de_domicilio_bancario
Caso o cliente deseje realizar uma operação de crédito com garantia em recebíveis, a QI Tech juntamente com a CERC, está preparada para criar essa operação de maneira muito semelhante ao fluxo de emissão de dívida comum.
# Criar uma renegociação
## Request
ENDPOINT /baas/debt_receivables
MÉTODO POST
Request Body
```json
{
"borrower": {
"name": "Alan Mathison Turing",
"email": "alan.turing@email.com",
"phone": {
"number": "912345678",
"area_code": "11",
"country_code": "055"
},
"is_pep": false,
"address": {
"city": "São Paulo",
"state": "SP",
"number": "1000",
"street": "Avenida Feliz",
"complement": "AP 801",
"postal_code": "49026100",
"neighborhood": "Centro"
},
"role_type": "issuer",
"birth_date": "1990-11-20",
"mother_name": "Nome da Mãe do Alan",
"nationality": "brasileiro",
"person_type": "natural",
"individual_document_number": "96969879003",
"document_identification": "494598fd-c226-4332-a500-591ae3884673"
},
"financial": {
"amount": 123456,
"interest_type": "pre_price_days",
"credit_operation_type": "ccb",
"annual_interest_rate": 2.32,
"disbursement_date": "2023-03-01",
"interest_grace_period": 0,
"principal_grace_period": 0,
"number_of_installments": 2,
"fine_configuration": {
"contract_fine_rate": 0.02,
"interest_base": "calendar_days",
"monthly_rate": 0.01
}
},
"disbursement_bank_account": {
"name": "Alan Mathison Turing",
"document_number": "96969879003",
"bank_code": "341",
"branch_number": "8615",
"account_number": "22110",
"account_digit": "2",
"account_type": "checking_account"
},
"purchaser_document_number": "32402502000135",
"contract": {
"payment_account": {
"account_number": "48391",
"account_branch": "0001",
"account_digit": "6",
"owner_document_number": "86498542000151"
},
"collaterals": [
{
"card_scheme": [
"abc"
],
"initial_date": "2021-06-28",
"final_date": "2021-07-06",
"division_rule": 2,
"encumbered_amount": 30
}
],
"collateral_management": {
"collateral_management_type": "absolute",
"amount": 2000,
"maximum_value": 2000,
"maximum_daily_value": 200,
"minimum_date": "2021-06-28",
"contract_payment_type": "partial_payment"
}
}
}
```
## Response
STATUS 200
Response Body
```json
{
"data": {
"additional_iof": 38000,
"annual_cet": "253,2642%",
"assignment_amount": 10000000,
"base_iof": 69331,
"borrower": {
"document_number": "89940878025962",
"name": "Parmalat"
},
"cet": "11,0900%",
"collaterals": [],
"contract": {
"external_contract_key": "2f0b8b6e-0b60-47f0-b27f-e291c028549b",
"number": "1907258737/P",
"signature_information": [
{
"signature_url": "https://sign.qitech.com.br/s/hNrwjda",
"signer_document_number": "94632180173",
"signer_email": "pedro.alves@yopmail.com",
"signer_external_key": "07a1c438-43a4-49a9-85a9-29667507453b",
"signer_name": "Pedro Felipe Henrique Alves",
"signer_role": "issuer"
},
{
"signature_url": "https://sign.qitech.com.br/s/EaTajda",
"signer_document_number": "34651104630",
"signer_email": "patricia.tereza@yopmail.com",
"signer_external_key": "61a1ea50-769a-410a-8ef8-09f0ce4611f6",
"signer_name": "Patrícia Tereza Bernardes",
"signer_role": "guarantor"
}
],
"urls": [
"https://storage.googleapis.com/sandbox-doc-api/documents/abedfeab-dcf8-4e13-897b-da02c222cef4/SALGADINHO_SALETE_LTDA-PARMALAT-CCB-1907258737-20220512165254.pdf"
]
},
"contract_fee_amount": 50000,
"contract_fees": [
{
"fee_amount": 50000,
"fee_type": "tac"
}
],
"external_contract_fee_amount": 0,
"external_contract_fees": [],
"installments": [
{
"additional_costs": [],
"advanced_paid_amount": 0,
"bank_slip_key": null,
"business_due_date": "2019-08-26",
"calendar_days": 32,
"digitable_line": null,
"due_date": "2019-08-26",
"due_interest": null,
"due_principal": 10000000,
"fine_amount": null,
"has_interest": true,
"installment_key": "81e4a732-d300-4e39-b6d5-2d9ac8df429b",
"installment_number": 1,
"installment_payment": [],
"installment_status": "created",
"installment_type": "principal",
"original_due_principal": 10000000,
"original_pre_fixed_amount": 1125598.54,
"original_principal_amortization_amount": 1000000,
"original_total_amount": null,
"paid_amount": 0,
"paid_at": null,
"payments": [],
"post_fixed_amount": null,
"pre_fixed_amount": 1125598.54,
"principal_amortization_amount": 1000000,
"tax_amount": 1312,
"total_amount": null,
"total_paid_amount": 0,
"workdays": 22
},
{
"additional_costs": [],
"advanced_paid_amount": 0,
"bank_slip_key": null,
"business_due_date": "2019-09-25",
"calendar_days": 30,
"digitable_line": null,
"due_date": "2019-09-25",
"due_interest": null,
"due_principal": 9000000,
"fine_amount": null,
"has_interest": true,
"installment_key": "bac4fe3e-9559-4380-9f4b-bdda3492738e",
"installment_number": 2,
"installment_payment": [],
"installment_status": "created",
"installment_type": "principal",
"original_due_principal": 9000000,
"original_pre_fixed_amount": 946509.06,
"original_principal_amortization_amount": 1000000,
"original_total_amount": null,
"paid_amount": 0,
"paid_at": null,
"payments": [],
"post_fixed_amount": null,
"pre_fixed_amount": 946509.06,
"principal_amortization_amount": 1000000,
"tax_amount": 2542,
"total_amount": null,
"total_paid_amount": 0,
"workdays": 22
},
{
"additional_costs": [],
"advanced_paid_amount": 0,
"bank_slip_key": null,
"business_due_date": "2019-10-25",
"calendar_days": 30,
"digitable_line": null,
"due_date": "2019-10-25",
"due_interest": null,
"due_principal": 8000000,
"fine_amount": null,
"has_interest": true,
"installment_key": "aaaec4d7-94a0-418d-8a8e-ac7af6787aec",
"installment_number": 3,
"installment_payment": [],
"installment_status": "created",
"installment_type": "principal",
"original_due_principal": 8000000,
"original_pre_fixed_amount": 841341.39,
"original_principal_amortization_amount": 1000000,
"original_total_amount": null,
"paid_amount": 0,
"paid_at": null,
"payments": [],
"post_fixed_amount": null,
"pre_fixed_amount": 841341.39,
"principal_amortization_amount": 1000000,
"tax_amount": 3772,
"total_amount": null,
"total_paid_amount": 0,
"workdays": 22
},
{
"additional_costs": [],
"advanced_paid_amount": 0,
"bank_slip_key": null,
"business_due_date": "2019-11-25",
"calendar_days": 31,
"digitable_line": null,
"due_date": "2019-11-25",
"due_interest": null,
"due_principal": 7000000,
"fine_amount": null,
"has_interest": true,
"installment_key": "bead5a38-c56e-4cfc-98f9-af6d71ec7d65",
"installment_number": 4,
"installment_payment": [],
"installment_status": "created",
"installment_type": "principal",
"original_due_principal": 7000000,
"original_pre_fixed_amount": 762003.23,
"original_principal_amortization_amount": 1000000,
"original_total_amount": null,
"paid_amount": 0,
"paid_at": null,
"payments": [],
"post_fixed_amount": null,
"pre_fixed_amount": 762003.23,
"principal_amortization_amount": 1000000,
"tax_amount": 5043,
"total_amount": null,
"total_paid_amount": 0,
"workdays": 20
},
{
"additional_costs": [],
"advanced_paid_amount": 0,
"bank_slip_key": null,
"business_due_date": "2019-12-26",
"calendar_days": 31,
"digitable_line": null,
"due_date": "2019-12-26",
"due_interest": null,
"due_principal": 6000000,
"fine_amount": null,
"has_interest": true,
"installment_key": "350a89e3-58a7-4879-b7ff-5fa0391da39c",
"installment_number": 5,
"installment_payment": [],
"installment_status": "created",
"installment_type": "principal",
"original_due_principal": 6000000,
"original_pre_fixed_amount": 653145.63,
"original_principal_amortization_amount": 1000000,
"original_total_amount": null,
"paid_amount": 0,
"paid_at": null,
"payments": [],
"post_fixed_amount": null,
"pre_fixed_amount": 653145.63,
"principal_amortization_amount": 1000000,
"tax_amount": 6314,
"total_amount": null,
"total_paid_amount": 0,
"workdays": 22
},
{
"additional_costs": [],
"advanced_paid_amount": 0,
"bank_slip_key": null,
"business_due_date": "2020-01-27",
"calendar_days": 32,
"digitable_line": null,
"due_date": "2020-01-27",
"due_interest": null,
"due_principal": 5000000,
"fine_amount": null,
"has_interest": true,
"installment_key": "bf935dc2-3151-4f66-91c6-35e446b57f2e",
"installment_number": 6,
"installment_payment": [],
"installment_status": "created",
"installment_type": "principal",
"original_due_principal": 5000000,
"original_pre_fixed_amount": 562799.27,
"original_principal_amortization_amount": 1000000,
"original_total_amount": null,
"paid_amount": 0,
"paid_at": null,
"payments": [],
"post_fixed_amount": null,
"pre_fixed_amount": 562799.27,
"principal_amortization_amount": 1000000,
"tax_amount": 7626,
"total_amount": null,
"total_paid_amount": 0,
"workdays": 20
},
{
"additional_costs": [],
"advanced_paid_amount": 0,
"bank_slip_key": null,
"business_due_date": "2020-02-26",
"calendar_days": 30,
"digitable_line": null,
"due_date": "2020-02-26",
"due_interest": null,
"due_principal": 4000000,
"fine_amount": null,
"has_interest": true,
"installment_key": "76aad8ce-3ee1-464c-90db-d72a2729560e",
"installment_number": 7,
"installment_payment": [],
"installment_status": "created",
"installment_type": "principal",
"original_due_principal": 4000000,
"original_pre_fixed_amount": 420670.69,
"original_principal_amortization_amount": 1000000,
"original_total_amount": null,
"paid_amount": 0,
"paid_at": null,
"payments": [],
"post_fixed_amount": null,
"pre_fixed_amount": 420670.69,
"principal_amortization_amount": 1000000,
"tax_amount": 8856,
"total_amount": null,
"total_paid_amount": 0,
"workdays": 20
},
{
"additional_costs": [],
"advanced_paid_amount": 0,
"bank_slip_key": null,
"business_due_date": "2020-03-25",
"calendar_days": 28,
"digitable_line": null,
"due_date": "2020-03-25",
"due_interest": null,
"due_principal": 3000000,
"fine_amount": null,
"has_interest": true,
"installment_key": "fc190222-5baf-4023-9e93-95b25774a37e",
"installment_number": 8,
"installment_payment": [],
"installment_status": "created",
"installment_type": "principal",
"original_due_principal": 3000000,
"original_pre_fixed_amount": 293473.82,
"original_principal_amortization_amount": 1000000,
"original_total_amount": null,
"paid_amount": 0,
"paid_at": null,
"payments": [],
"post_fixed_amount": null,
"pre_fixed_amount": 293473.82,
"principal_amortization_amount": 1000000,
"tax_amount": 10004,
"total_amount": null,
"total_paid_amount": 0,
"workdays": 20
},
{
"additional_costs": [],
"advanced_paid_amount": 0,
"bank_slip_key": null,
"business_due_date": "2020-04-27",
"calendar_days": 33,
"digitable_line": null,
"due_date": "2020-04-27",
"due_interest": null,
"due_principal": 2000000,
"fine_amount": null,
"has_interest": true,
"installment_key": "7c2972a8-def7-4b76-b215-0ade0a5bca13",
"installment_number": 9,
"installment_payment": [],
"installment_status": "created",
"installment_type": "principal",
"original_due_principal": 2000000,
"original_pre_fixed_amount": 232548.93,
"original_principal_amortization_amount": 1000000,
"original_total_amount": null,
"paid_amount": 0,
"paid_at": null,
"payments": [],
"post_fixed_amount": null,
"pre_fixed_amount": 232548.93,
"principal_amortization_amount": 1000000,
"tax_amount": 11357,
"total_amount": null,
"total_paid_amount": 0,
"workdays": 21
},
{
"additional_costs": [],
"advanced_paid_amount": 0,
"bank_slip_key": null,
"business_due_date": "2020-05-25",
"calendar_days": 28,
"digitable_line": null,
"due_date": "2020-05-25",
"due_interest": null,
"due_principal": 1000000,
"fine_amount": null,
"has_interest": true,
"installment_key": "d848c880-f489-4bc1-a9e4-101f8d664317",
"installment_number": 10,
"installment_payment": [],
"installment_status": "created",
"installment_type": "principal",
"original_due_principal": 1000000,
"original_pre_fixed_amount": 97824.6,
"original_principal_amortization_amount": 1000000,
"original_total_amount": null,
"paid_amount": 0,
"paid_at": null,
"payments": [],
"post_fixed_amount": null,
"pre_fixed_amount": 97824.6,
"principal_amortization_amount": 1000000,
"tax_amount": 12505,
"total_amount": null,
"total_paid_amount": 0,
"workdays": 19
}
],
"iof_charge_method": "financed",
"issue_amount": 10000000,
"net_external_contract_fee_amount": 0,
"number_of_installments": 10,
"post_fixed_interest_base": "workdays",
"post_fixed_interest_rate": 1,
"prefixed_interest_rate": {
"annual_rate": 2.32,
"created_at": null,
"daily_rate": 0.0033388,
"interest_base": "calendar_days",
"monthly_rate": 0.10516767
},
"requester_identifier_key": "b7ddbcfb-3de0-49d8-8014-07972d8b27f2",
"total_iof": 107331,
"total_pre_fixed_amount": 5935915.16
},
"event_datetime": "2022-05-12 16:53:10",
"key": "b7ddbcfb-3de0-49d8-8014-07972d8b27f2",
"status": "waiting_signature",
"webhook_type": "debt"
}
```
:::caution Atenção!
O payload ultilizado na emissão de um refinanciamento é o mesmo ultilizado na emissã de uma divida simples, com a adição da lista de operações que serão quitadas em **"refinanced_credit_operations"**.
:::
### Body Params
| Campo | Tipo | Descrição | Máx. Caract. |
|---------------------------------|--------|------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|--------------|
| **borrower** * | object | **[Objeto Borrower](#objeto-borrower)** - Devedor da operação de crédito. | - |
| **disbursement_bank_account** * | object | **[Objeto Disbursement Bank Account](#objeto-disbursement_bank_accounts)** - Dados da conta bancária para desembolso da operação. | - |
| **financial** * | object | **[Objeto Financial](#objeto-financial)** - Dados da conta bancária para desembolso da operaçãoIdentificador de que o objeto enviado é uma pessoa física. Deve conter SEMPRE o valor "natural" para borrower PF. | - |
| **purchaser_document_number** * | string | CNPJ do cessionário (comprador) da operação de crédito. | - |
| **refinanced_credit_operations** * | array of objects | Lista de **[Objetos Refinanced Credit Operations](#objeto-refinanced_credit_operations)** contendo as operações refinanciadas. | - |
## Definições
### Objeto Request Body
| Campo | Tipo | Descrição | Máx. Caract. |
|---------------------------------|--------|------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|--------------|
| **borrower** * | object | **[Objeto Borrower](#objeto-borrower)** - Devedor da operação de crédito | - |
| **disbursement_bank_account** * | object | **[Objeto Disbursement Bank Account](#objeto-disbursement_bank_accounts)** - Dados da conta bancária para desembolso da operação | - |
| **financial** * | object | **[Objeto Financial](#objeto-financial)** - Dados da conta bancária para desembolso da operaçãoIdentificador de que o objeto enviado é uma pessoa física. Deve conter SEMPRE o valor "natural" para borrower PF | - |
| **purchaser_document_number** * | string | CNPJ do cessionário (comprador) da operação de crédito | - |
| **contract** * | object | **[Objeto Financial](#objeto-contract)** com dados da garantia. | - |
### Objeto Borrower
| Campo | Tipo | Descrição | Máx. Caract. |
|----------------------------------|---------|---------------------------------------------------------------------------------------|--------------|
| **name** * | string | Nome do devedor | 100 |
| **email** | string | Email do devedor | 254 |
| **phone** | object | **[Objeto Phone](#objeto-phone)** - Telefone de contato do devedor | - |
| **is_pep** * | boolean | Indicador de PEP (http://www.portaldatransparencia.gov.br/download-de-dados/pep) | - |
| **address** * | object | **[Objeto Address](#objeto-address)** - Endereço do devedor | - |
| **role_type** * | enum | default: _issuer_ | - |
| **birth_date** * | date | Data de nascimento do devedor (formato "AAAA-MM-DD") | - |
| **mother_name** * | string | Nome da mãe do devedor | 100 |
| **nationality** | string | Nacionalidade do devedor | 50 |
| **person_type** * | string | Indicador de pessoa física - default: _natural_ | - |
| **individual_document_number** * | string | CPF do devedor (apenas números) | 11 |
| **document_identification** * | string | **DOCUMENT_KEY** do PDF do documento de identificação do devedor com foto (RG ou CNH) | - |
| **document_identification_back** |string | DOCUMENT_KEY do PDF da parte de trás do documento de identificação da pessoa com foto (RG ou CNH) (enviado previamente). | 11 |
| **wedding_certificate** | string | DOCUMENT_KEY do PDF do certificado de casamento da pessoa (enviado previamente). No caso de marital_status ser "single", o valor deste campo deve ser NULL. | 11 |
| **proof_of_residence** * |string | DOCUMENT_KEY do PDF do comprovante de endereço do endereço enviado (enviado previamente). | 11 |
### Objeto Address
| Campo | Tipo | Descrição | Máx. Caract. |
|--------------------|--------|--------------------------------------------------------------------------|--------------|
| **city** * | string | Cidade do endereço | 100 |
| **state** * | string | Estado do endereço (com dois caracteres maiúsculos) | 2 |
| **number** * | string | Número do endereço | 10 |
| **street** * | string | Rua do endereço | 100 |
| **complement** * | string | Complemento do endereço (texto livre) | 100 |
| **postal_code** * | string | CEP do endereço (http://www.buscacep.correios.com.br/sistemas/buscacep/) | 8 |
| **neighborhood** * | string | Bairro do endereço | 100 |
### Objeto Phone
| Campo | Descrição | Exemplo | Máx. Caract. |
|--------------------|-----------|-------------------------------------------------------|--------------|
| **number** * | string | Número de telefone | 10 |
| **area_code** * | string | Código DDD do telefone (https://ddd.guiamais.com.br/) | 2 |
| **country_code** * | string | Código DDI do telefone (https://ddi.guiamais.com.br/) | 3 |
### Objeto Disbursement Bank Account
Uma emissão de dívida deve conter as informações bancárias para desembolso, por padrão, uma conta de titularidade do devedor.
| Campo | Tipo | Descrição | Máx. Caract. |
|-----------------------|--------|----------------------------------------------------------------------------------------------------|--------------|
| name | string | Nome do titular da conta | 50 |
| document_number | string | CPF do titular da conta | 11 |
| bank_code * | string | Código COMPE da instituição financeira (https://www.bcb.gov.br/pom/spb/estatistica/port/ASTR003.pdf) | 3 |
| branch_number * | string | Número da agência (não informar o dígito verificador da agência!) | 4 |
| account_number * | string | Número da conta (sem o dígito verificador da conta!) | 10 |
| account_digit * | string | Dígito verificador da conta (informar zero no lugar de letras) | 1 |
| account_type | enum | [Enumerador Account Type](#enumerador-account-type) Tipo da conta | 1 |
### Objeto Financial
O objeto financial descreve as informações financeiras da operação de crédito.
| Campo | Tipo | Descrição | Máx. Caract. |
|----------------------------|--------|---------------------------------------------------------------------------------------------------------------|--------------|
| **amout** | float | Valor de emissão/nominal da operação de crédito | - |
| **interest_type** | object | **[Enumerador Interest Type](#enumerador-interest-type)** - Método de amortização e forma de cálculo de juros | - |
| **credit_operation_type** | object | **[Enumerador Credit Operation Type](#enumerador-credit-operation-type)** - Tipo do contrato de crédito | - |
| **annual_interest_rate** | float | Taxa de juros pré-fixada expressa em decimal ao ano | - |
| **disbursement_date** | date | Data do desembolso da operação | - |
| **interest_grace_period** | int | Carência de juros (em meses) | - |
| **principal_grace_period** | int | Período carência de principal | - |
| **number_of_installments** | int | Número de parcelas da operação de crédito | - |
| **fine_configuration** | object | **[Objeto Fine Configuration](#objeto-fine-configuration)** - Configuração de juros e multa por atraso | - |
### Objeto Fine Configuration
No Objeto Fine Configuration são informados os valor de multa e juros por atraso da operação de crédito.
| Campo | Tipo | Descrição | Máx. Caract. |
|------------------------|-------|--------------------------------------------------------------------------------------|--------------|
| **contract_fine_rate** | float | Percentual de multa por atraso | - |
| **interest_base** | enum | **[Enumerador Interest Base](#enumerador-interest-base)** - Base de cálculo de juros | - |
| **monthly_rate** | float | Percentual de juros de atraso ao mês | - |
### Objeto Contract
O objeto financial descreve as informações financeiras da operação de crédito.
| Campo | Tipo | Descrição | Máx. Caract. |
|----------------------------|--------|---------------------------------------------------------------------------------------------------------------|--------------|
| **payment_account** | object | Conta de pagamentos para os recebíveis. | - |
| **collaterals** | array | Listas de garantias. | - |
| **collateral_management** | object | **[Objeto Collateral Management](#objeto-collateral-management)** - Configurações de garantia. | - |
### Objeto Collateral Management
O objeto financial descreve as informações financeiras da operação de crédito.
| Campo | Tipo | Descrição | Máx. Caract. |
|----------------------------|--------|---------------------------------------------------------------------------------------------------------------|--------------|
| **collateral_management_type** | enum | **[Enumerador Collateral Management Type](#enumerador-collateral-management-type)** - Tipo de gestão a ser utilizada para amortizar a divida. | - |
| **amount** | float | Valor a ser utilizado. | - |
| **maximum_value** | float | Valor máximo que será utilizado para pagamento da operação. | - |
| **maximum_daily_value** | float | Valor máximo que será utilizado por dia. | - |
| **minimum_date** | string | Data mínima para começar à utilizar os recebiveis. | - |
| **contract_payment_type** | enum | **[Enumerador Credit Operation Type](#enumerador-credit-operation-type)** - Tipo de pagamento para o contrato | - |
# Enumeradores
### Enumerador _Person Type_
| Enumerador | Descrição |
|------------------------|-----------------------|
| **legal** | Pessoa juridica |
| **natural** | Pesso física |
### Enumerador _Account Type_
| Enumerador | Descrição |
|------------------------|-----------------------|
| **checking_account** | Conta corrente |
| **deposit_account** | Conta de depósito |
| **guaranteed_account** | Conta de garantia |
| **investment_account** | Conta de investimento |
| **payment_account** | Conta de pagamento |
| **saving_account** | Conta poupança |
| **salary_account** | Conta salário |
### Enumerador _Interest Type_
| Enumerador | Descrição |
|----------------------|--------------------------------------------------------------------------------------------------------------------------------------------------------------------------|
| **pre_price_days** | Método de amortização Price (parcelas iguais) com cálculo do juros pré-fixado ao dia |
| **pre_price** | Método de amortização Price (parcelas iguais) com cálculo do juros pré-fixado em períodos fixos (30 dias) |
| **pre_sac** | Método de amortização SAC (amortização constante) com cálculo do juros pré-fixado ao dia |
| **post_sac** | Método de amortização SAC (amortização constante) com cálculo do juros baseado em uma taxa pré-fixada + indexador pós-fixado (cdi, ipca ou igpm) ao dia |
| **post_price** | Método de amortização Price (parcelas iguais) com cálculo do juros baseado em uma taxa pré-fixada + indexador pós-fixado (cdi, ipca ou igpm) em períodos fixos (30 dias) |
| **post_price_days** | Método de amortização Price (parcelas iguais) com cálculo do juros baseado em uma taxa pré-fixada + indexador pós-fixado (cdi, ipca ou igpm) ao dia |
### Enumerador _Credit Operation Type_
| Enumerador | Descrição |
|---------------|--------------------------------|
| **ccb** | Cédula de Crédito Bancário |
| **cce** | Cédula de Crédito à Exportação |
| **cci** | Cédula de Crédito Imobiliário |
| **nce** | Nota de Crédito à Exportação |
### Enumerador _Interest Base_
| Enumerador | Descrição |
|-----------------------|---------------------------------------------------------------------------|
| **workdays** | Base de cálculo de juros em dias úteis considerando um ano de 252 dias |
| **calendar_days** | Base de cálculo de juros em dias corridos considerando um ano de 360 dias |
| **calendar_days_365** | Base de cálculo de juros em dias corridos considerando um ano de 365 dias |
### Enumerador _Fee Type_
Cada tipo de fee deve ser previamente habilitado e configurado pela QI Tech
| Enumerador | Descrição |
|-----------------------|----------------------------------------------------------------------------|
| **tac** | Tarifa de abertura de cadastro |
| **spread** | Ágio cobrado no valor de aquisição da operação de crédito |
| **warranty_analysis** | Tarifa de análise de garantias |
| **ted_fee** | Tarifa de TED |
| **spread_ted_fee** | Ágio da tarifa de TED cobrado no valor de aquisição da operação de crédito |
### Enumerador _Collateral Management Type_
| Enumerador | Descrição |
|------------------------|-----------------------|
| **absolute** | Valor absoluto |
| **percentage** | Valor percentual |
### Enumerador _Person Type_
| Enumerador | Descrição |
|------------------------|-----------------------|
| **partial_payment** | Pagamento parcial |
| **total_payment** | Pagamento total |
| **monthly_payment** | Pagamento mensal |
## Response
STATUS 200
Response Body
```json
{
"data": {
"additional_iof": 469.1328,
"annual_cet": "283,3821%",
"assignment_amount": 124690.56,
"base_iof": 473.6829374063069,
"borrower": {
"document_number": "96969879003",
"name": "Alan Mathison Turing"
},
"cet": "11,8500%",
"collaterals": [],
"contract": {
"number": "0000067563/AMT",
"signature_information": [
{
"signature_url": null,
"signer_document_number": "15627918004",
"signer_email": "alan.turing@email.com",
"signer_external_key": null,
"signer_name": "Alan Mathison Turing",
"signer_role": "issuer"
}
],
"urls": [
"https://storage.googleapis.com/sandbox-doc-api/documents/5af36fcd-8e4c-4421-ad45-7bcba899c0d3/SYNGENTASANDBOX-ALAN_MATHISON_TURING-CCB-0000067563-20230302234816.pdf"
]
},
"contract_fee_amount": 1234.56,
"contract_fees": [
{
"fee_amount": 1234.56,
"fee_type": "tac"
}
],
"external_contract_fee_amount": 1234.56,
"external_contract_fees": [
{
"fee_amount": 1234.56,
"fee_type": "spread",
"net_fee_amount": 1120.36,
"tax_amount": 114.2
}
],
"installments": [
{
"accrual_reference_date": null,
"additional_costs": [],
"advanced_paid_amount": 0,
"bank_slip_key": null,
"business_due_date": "2023-04-03",
"calendar_days": 31,
"digitable_line": null,
"due_date": "2023-04-02",
"due_interest": 0,
"due_principal": 123456,
"fine_amount": null,
"has_interest": true,
"installment_history": [],
"installment_key": "da264e95-2bbd-47de-876b-bfea7d25e266",
"installment_number": 1,
"installment_payment": [],
"installment_status": "created",
"installment_type": "principal",
"original_due_principal": 123456,
"original_pre_fixed_amount": 13245.468714162304,
"original_principal_amortization_amount": 58473.151285837695,
"original_total_amount": 71718.62,
"paid_amount": 0,
"paid_at": null,
"post_fixed_amount": 0,
"pre_fixed_amount": 13245.468714162304,
"principal_amortization_amount": 58473.151285837695,
"qr_code_key": null,
"qr_code_url": null,
"renegotiation_proposal_key": null,
"tax_amount": 148.63875056859942,
"total_accrual_amount": null,
"total_amount": 71718.62,
"total_paid_amount": 0,
"workdays": 21
},
{
"accrual_reference_date": null,
"additional_costs": [],
"advanced_paid_amount": 0,
"bank_slip_key": null,
"business_due_date": "2023-05-02",
"calendar_days": 30,
"digitable_line": null,
"due_date": "2023-05-02",
"due_interest": 0,
"due_principal": 64982.848714162305,
"fine_amount": null,
"has_interest": true,
"installment_history": [],
"installment_key": "cac7064b-2310-45e1-a91f-5e8f39f0f0ea",
"installment_number": 2,
"installment_payment": [],
"installment_status": "created",
"installment_type": "principal",
"original_due_principal": 64982.848714162305,
"original_pre_fixed_amount": 6735.77577015044,
"original_principal_amortization_amount": 64982.84422984956,
"original_total_amount": 71718.62,
"paid_amount": 0,
"paid_at": null,
"post_fixed_amount": 0,
"pre_fixed_amount": 6735.77577015044,
"principal_amortization_amount": 64982.84422984956,
"qr_code_key": null,
"qr_code_url": null,
"renegotiation_proposal_key": null,
"tax_amount": 325.0441868377075,
"total_accrual_amount": null,
"total_amount": 71718.62,
"total_paid_amount": 0,
"workdays": 19
}
],
"iof_charge_method": "financed",
"issue_amount": 123456,
"net_external_contract_fee_amount": 1120.36,
"number_of_installments": 2,
"prefixed_interest_rate": {
"annual_rate": 2.32,
"created_at": "2023-03-02T23:48:15",
"daily_rate": 0.00329298,
"interest_base": "calendar_days_365",
"monthly_rate": 0.10516767
},
"requester_identifier_key": "1c2ca4dc-2a20-4dd4-bd5f-af143fadadf4",
"total_iof": 942.82,
"total_pre_fixed_amount": 19981.244484312745
},
"event_datetime": "2023-03-02 23:48:20",
"key": "1c2ca4dc-2a20-4dd4-bd5f-af143fadadf4",
"status": "waiting_signature",
"webhook_type": "debt"
}
```
STATUS 400
Response Body
```json
{
"data": "{\"title\": \"Bad Request\", \"description\": \"Invalid request body.\", \"translation\": \"Corpo da requisição inválido.\", \"extra_fields\": {}, \"code\": \"LEG000069\"}"
}
```
---
# emissao_de_divida
URL: /en/documentation/auxilio_brasil/emissao_de_divida
## Emissão de dívida
## Request
- ENDPOINT /debt
- MÉTODO POST
- BODY (antes de ser assinado):
YOUR REQUEST HISTORY
**body.json**
```json
{
"borrower": {
"person_type": "natural",
"name": "Qi Tech Ltda.",
"mother_name": "Maria Mariane",
"birth_date": "1990-05-06",
"profession": "Deputada",
"nationality": "nationality",
"marital_status": "married",
"wedding_certificate": "56ab7849-4d90-490b-b539-96ac3c5a619b",
"spouse": {
"person_type": "natural",
"name": "Qi Tech Ltda.",
"mother_name": "Maria Mariane",
"birth_date": "1990-05-06",
"profession": "Deputada",
"nationality": "nationality",
"marital_status": "married",
"wedding_certificate": "56ab7849-4d90-490b-b539-96ac3c5a619b",
"is_pep": False,
"individual_document_number": "34651104630",
"document_identification": "3c24579b-9810-4fa6-9b08-fe67d237160a",
"document_identification_back": "2f43456a-3664-4805-82b8-96a2ec72c04c",
"document_identification_type": "cnh",
"document_identification_number": "232479719",
"email": "api@qitech.com.br",
"phone": {
"country_code": "055",
"area_code": "11",
"number": "999999999"
},
"proof_of_residence": "780456bd-1eec-4e5f-82c0-d8c3921497ea",
"address": {
"street": "Av. Brigadeiro Faria Lima",
"state": "SP",
"city": "São Paulo",
"neighborhood": "Jardim Paulistano",
"number": "2391",
"postal_code": "01452905",
"complement": "1o. Andar"
}
},
"is_pep": False,
"individual_document_number": "34651104630",
"document_identification": "3c24579b-9810-4fa6-9b08-fe67d237160a",
"document_identification_back": "2f43456a-3664-4805-82b8-96a2ec72c04c",
"document_identification_type": "cnh",
"document_identification_number": "232479719",
"email": "api@qitech.com.br",
"phone": {
"country_code": "055",
"area_code": "11",
"number": "999999999"
},
"proof_of_residence": "780456bd-1eec-4e5f-82c0-d8c3921497ea",
"address": {
"street": "Av. Brigadeiro Faria Lima",
"state": "SP",
"city": "São Paulo",
"neighborhood": "Jardim Paulistano",
"number": "2391",
"postal_code": "01452905",
"complement": "1o. Andar"
}
},
"financial": {
"interest_type": "pre_price_days",
"disbursement_start_date": "2019-07-25",
"disbursement_end_date": "2019-07-29",
"fine_configuration": {
"contract_fine_rate": 0.02,
"interest_base": "workdays",
"monthly_rate": 0.01
},
"annual_interest_rate": 0.02,
"credit_operation_type": "ccb",
"interest_grace_period": 0,
"number_of_installments": 10,
"principal_grace_period": 0
}
}
```
### Body Params
| Campo | Descrição |
|---|---|
| `borrower` *(obrigatório)* | Dados do mutuário. |
| `guarantors` | Garantidores da operação (que pode ser uma lista de Objeto PF e/ou Objeto PJ e não é um campo obrigatório). |
| `collaterals` *(obrigatório)* | Informações das parcelas de pagamento. |
| `financial` *(obrigatório)* | O objeto financeiro descreve as informações financeiras da emissão. Aqui são definidas a taxa de juros, carência e valor da dívida entre outros. |
| `disbursement_bank_accounts` | Lista de informações bancárias para o desembolso (Objeto Conta Bancária). |
### BORROWER OBJECT
| Campo | Descrição |
|---|---|
| `person_type` *(obrigatório)* | Identificador de que o objeto enviado é uma pessoa física ou jurídica. |
| `name` *(obrigatório)* | Nome da pessoa. Limitado a 100 caracteres. |
| `mother_name` | mother_name |
| `birth_date` | Data de nascimento da pessoa (formato "AAAA-MM-DD") |
| `profession` | Profissão da pessoa |
| `nationality` | Nacionalidade do cliente. Limitado a 50 caracteres. |
| `marital_status` | Estado civil do cliente. |
| `property_system` | Regime de separação de bens (obrigatório apenas para pessoas com marital_status "married"). |
| `wedding_certificate` | DOCUMENT_KEY do PDF do certificado de casamento da pessoa (enviado previamente). No caso de marital_status ser "single", o valor deste campo deve ser NULL.|
| `spouse` | Objeto PF do esposo/esposa da pessoa (obrigatório apenas quando "compulsory_separation_of_goods" for "total_communion_of_goods", "partial_communion_of_goods", "final_participation_of_acquisitions" ou "compulsory_separation_of_goods"). No caso de marital_status ser "single", o valor deste campo deve ser NULL. |
| `is_pep` *(obrigatório)* | Declaração se a pessoa é PEP (http://www.portaldatransparencia.gov.br/download-de-dados/pep) valor booleano |
| `individual_document_number` | CPF da pessoa (apenas números) |
| `document_identification` *(obrigatório)* | DOCUMENT_KEY do PDF do documento de identificação da pessoa com foto (RG ou CNH) (enviado previamente) |
| `document_identification_back` | DOCUMENT_KEY do PDF da parte de trás do documento de identificação da pessoa com foto (RG ou CNH) (enviado previamente) |
| `document_identification_type` | Tipo do documento de identificação. Valores aceitos: `rg`, `rne`, `cnh`, `ctps`, `class_document`, `passport`, `other`, `cin`. Quando `cin`, o campo `document_identification_number` deve ser igual ao CPF. |
| `document_identification_number` *(obrigatório)* | Número do documento de identificação da pessoa enviado em document_identification. Quando `document_identification_type` for `cin`, deve ser igual ao CPF. |
| `email` | Email da pessoa |
| `phone` | Telefone da pessoa |
| `address` | Endereço da pessoa |
| `proof_of_residence` *(obrigatório)* | DOCUMENT_KEY do PDF do comprovante de endereço do endereço enviado (enviado previamente) |
### GUARANTORS OBJECT
| Campo | Descrição |
|---|---|
| `person_type` *(obrigatório)* | Identificador de que o objeto enviado é uma pessoa física ou jurídica. |
| `name` *(obrigatório)* | Nome da pessoa. Limitado a 100 caracteres. |
| `mother_name` *(obrigatório)* | Nome da mãe do cliente em caso de PF. Limitado a 100 caracteres. |
| `birth_date` *(obrigatório)* | Data de nascimento da pessoa (formato "AAAA-MM-DD") |
| `profession` *(obrigatório)* | Profissão do cliente. Limitado a 64 caracteres. |
| `nationality` *(obrigatório)* | Nacionalidade do cliente. Limitado a 50 caracteres. |
| `marital_status` *(obrigatório)* | Estado civil do cliente. |
| `property_system` | Regime de separação de bens (obrigatório apenas para pessoas com marital_status "married"). |
| `wedding_certificate` *(obrigatório)* | DOCUMENT_KEY do PDF do certificado de casamento da pessoa (enviado previamente). No caso de marital_status ser "single", o valor deste campo deve ser NULL. |
| `spouse` *(obrigatório)* | Objeto PF do esposo/esposa da pessoa (obrigatório apenas quando "compulsory_separation_of_goods" for "total_communion_of_goods", "partial_communion_of_goods", "final_participation_of_acquisitions" ou "compulsory_separation_of_goods"). No caso de marital_status ser "single", o valor deste campo deve ser NULL. |
| `is_pep` *(obrigatório)* | Declaração se a pessoa é PEP (http://www.portaldatransparencia.gov.br/download-de-dados/pep). |
| `individual_document_number` *(obrigatório)* | CPF da pessoa (apenas números). Limitado a 11 caracteres. |
| `document_identification` *(obrigatório)* | DOCUMENT_KEY do PDF do documento de identificação da pessoa com foto (RG ou CNH) (enviado previamente) |
| `document_identification_back` | DOCUMENT_KEY do PDF da parte de trás do documento de identificação da pessoa com foto (RG ou CNH) (enviado previamente) |
| `document_identification_type` | Qual o tipo do documento de identificação enviado. |
| `document_identification_number` *(obrigatório)* | Número do documento de identificação da pessoa enviado em "document_identification". Limitado a 16 caracteres. |
| `email` | Email da pessoa |
| `phone` | Telefone da pessoa |
| `proof_of_residence` *(obrigatório)* | DOCUMENT_KEY do PDF do comprovante de endereço do endereço enviado (enviado previamente) |
| `address` | Endereço da pessoa |
### SPOUSE OBJECT
| Campo | Descrição |
|---|---|
| `person_type` *(obrigatório)* | Identificador de que o objeto enviado é uma pessoa física. Deve conter SEMPRE o valor "natural" para Objeto PF |
| `name` *(obrigatório)* | Nome da pessoa |
| `mother_name` *(obrigatório)* | mother_name |
| `birth_date` *(obrigatório)* | Data de nascimento da pessoa (formato "AAAA-MM-DD") |
| `profession` *(obrigatório)* | Profissão da pessoa |
| `nationality` *(obrigatório)* | Nacionalidade da pessoa |
| `marital_status` *(obrigatório)* | Estado civil da pessoa: "single", "married", "widower" ou "divorced" |
| `property_system` | Regime de separação de bens (obrigatório apenas para pessoas com marital_status "married"): "total_communion_of_goods", "partial_communion_of_goods", "total_separation_of_goods", "final_participation_of_acquisitions" ou "compulsory_separation_of_goods" |
| `wedding_certificate` *(obrigatório)* | DOCUMENT_KEY do PDF do certificado de casamento da pessoa (enviado previamente). No caso de marital_status ser "single", o valor deste campo deve ser null |
| `spouse` *(obrigatório)* | Objeto PF do esposo/esposa da pessoa (obrigatório apenas quando "compulsory_separation_of_goods" for "total_communion_of_goods", "partial_communion_of_goods", "final_participation_of_acquisitions" ou "compulsory_separation_of_goods"). No caso de marital_status ser "single", o valor deste campo deve ser null |
| `is_pep` *(obrigatório)* | Declaração se a pessoa é PEP (http://www.portaldatransparencia.gov.br/download-de-dados/pep) valor booleano |
| `individual_document_number` *(obrigatório)* | CPF da pessoa (apenas números) |
| `document_identification` *(obrigatório)* | DOCUMENT_KEY do PDF do documento de identificação da pessoa com foto (RG ou CNH) (enviado previamente) |
| `document_identification_back` | DOCUMENT_KEY do PDF da parte de trás do documento de identificação da pessoa com foto (RG ou CNH) (enviado previamente) |
| `document_identification_type` | Tipo do documento de identificação. Valores aceitos: `rg`, `rne`, `cnh`, `ctps`, `class_document`, `passport`, `other`, `cin`. Quando `cin`, o campo `document_identification_number` deve ser igual ao CPF. |
| `document_identification_number` *(obrigatório)* | Número do documento de identificação da pessoa enviado em document_identification. Quando `document_identification_type` for `cin`, deve ser igual ao CPF. |
| `email` | Email da pessoa |
| `phone` | Telefone da pessoa |
| `proof_of_residence` *(obrigatório)* | DOCUMENT_KEY do PDF do comprovante de endereço do endereço enviado (enviado previamente) |
| `address` | Endereço da pessoa |
### PHONE OBJECT
| Campo | Descrição |
|---|---|
| `country_code` *(obrigatório)* | Código DDI do telefone (https://ddi.guiamais.com.br/)(deve ter obrigatoriamente 3 dígitos). |
| `area_code` *(obrigatório)* | Código DDD do telefone (https://ddd.guiamais.com.br/).) |
| `number` *(obrigatório)* | Número de telefone (apenas números). |
| `document_number` *(obrigatório)* | Numero de documento do signatário. |
### ADDRESS OBJECT
| Campo | Descrição |
|---|---|
| `street` *(obrigatório)* | Rua do endereço. |
| `state` *(obrigatório)* | Estado do endereço (com dois caracteres maiúsculos). |
| `city` *(obrigatório)* | Cidade do endereço. |
| `neighborhood` *(obrigatório)* | Bairro do endereço. |
| `number` *(obrigatório)* | Número da rua. |
| `postal_code` *(obrigatório)* | CEP do endereço (http://www.buscacep.correios.com.br/sistemas/buscacep/) (apenas números). |
| `complement` *(obrigatório)* | Complemento do endereço (texto livre). |
### OCR OBJECT
| Campo | Descrição |
|---|---|
| `ocr` | Objeto para entrega das chaves geradas pelo SDK de OCR |
### COLLATERALS OBJECT
| Campo | Descrição |
|---|---|
| `collateral_data` | Lista de garantias da operação. |
| `percentage` | |
| `collateral_type` *(obrigatório)* | Tipo de collateral. No caso do Auxílio Brasil, precisa ser "social_benefit" |
### COLLATERAL DATA OBJECT
| Campo | Descrição |
|---|---|
| `reservation_period` | Período do beneficio bloqueado como garantia. |
| `reservation_amount` | Valor do beneficio bloqueado como garantia. |
| `family_code` | Código da Família do beneficio. |
| `state` | UF da família do beneficio. |
| `financial_education_term` | Respostas do Termo de Educação Financeira exigido pelo Ministério da Cidadania |
### FINANCIAL EDUCATION TERM OBJECT
| Campo | Descrição |
|---|---|
| `questions` | |
### QUESTIONS OBJECT
| Campo | Descrição |
|---|---|
| `answer` | |
### FINANCIAL OBJECT
| Campo | Descrição |
|---|---|
| `desired_installments` | Lista de parcelas. |
| `interest_type` *(obrigatório)* | Tipo de juros da operação. |
| `disbursement_start_date` | Data início do período de desembolso (formato "AAAA-MM-DD"). |
| `disbursement_end_date` | Data final do período de desembolso (formato "AAAA-MM-DD"). |
| `annual_interest_rate` *(obrigatório)* | Valor porcentual da parcela prefixada de juros (atenção: 1 = 100%) |
| `credit_operation_type` *(obrigatório)* | Tipo de operação de crédito. |
| `interest_grace_period` | Carência de juros (em meses) |
| `number_of_installments` | Número de parcelas (mensais) |
| `principal_grace_period` | Carência do principal (em meses) |
### DESIRED INSTALLMENTS OBJECT
| Campo | Descrição |
|---|---|
| `due_date` | Data da parcela. |
| `total_amount` | Valor total da parcela |
### REBATES OBJECT
| Campo | Descrição |
|---|---|
| `amount` | Valor do rebate. |
| `fee_type` | Tipo de fee |
| `amount_type` | Tipo do valor inserido (valor absoluto, valor em porcentagem) |
| `rebate_bank_account` | Objeto conta bancária de rebate. |
### FINE CONFIGURATION OBJECT
| Campo | Descrição |
|---|---|
| `contract_fine_rate` *(obrigatório)* | Valor porcentual fixo da multa |
| `interest_base` | Contagem do tempo para multa ("calendar_days" para dias corridos, "workdays" para dias úteis) |
| `monthly_rate` | Valor porcentual mensal da multa |
### DISBURSEMENT BANK ACCOUNT OBJECT
| Campo | Descrição |
|---|---|
| `name` | Nome do dono da conta para desembolso - Obrigatório apenas se o método de transferência for ted ou pix. e caso haja mais de uma conta para desembolso (Limite de 80 caracteres). |
| `bank_code` | Código COMPE da instituição financeira (https://www.bcb.gov.br/pom/spb/estatistica/port/ASTR003.pdf) com 3 dígitos - Obrigatório apenas se o método de transferência for ted ou pix e se "ispb_number" não for enviado. |
| `branch_number` | Número da agência - Obrigatório apenas se o método de transferência for ted ou pix. |
| `account_number` | Número da conta - Obrigatório apenas se o método de transferência for ted ou pix - Obrigatório apenas se o método de transferência for ted ou pix. |
| `document_number`| CPF ou CNPJ do dono da conta para desembolso - Obrigatório apenas se o método de transferência for ted ou pix. e caso haja mais de uma conta para desembolso. |
| `percentage_receivable` | Valor em porcentagem que a conta receberá no desembolso. Este campo é utilizado para definir a quantidade a ser dividida caso haja mais de uma conta para desembolso (no caso de ser somente uma conta, o valor integral será transferido). Caso a porcentagem não seja enviada (de uma, ou de todas as contas), a porcentagem restante será dividida igualmente entre as contas sem porcentagem definida. Caso todas as porcentagens sejam enviadas, a soma delas não pode passar de 100 - Obrigatório apenas se o método de transferência for ted ou pix. |
| `ispb_number` | Identificador da instituição no Sistema de Pagamentos Brasileiro - Obrigatório apenas se o método de transferência for ted ou pix e se o "bank_code" não for enviado. |
| `qr_code_key` | Chave fornecida no momento da criação de um QR Code PIX - Pode ser enviado como o único parâmetro deste objeto, assim o desembolso acontece como pagamento desse QR code PIX. |
| `digitable_line` | Representação numérica de um código de barras de um boleto - Pode ser enviado como o único parâmetro deste objeto, assim o desembolso acontece como pagamento desse boleto. |
| `transfer_method` | Por padrão as operações são desembolsadas via PIX, então quando existr a necessidade de que uma operação seja desembolsada via TED este campo pode ser enviado. |
---
# webhook_auxilio_brasil
URL: /en/documentation/auxilio_brasil/webhook_auxilio_brasil
## Webhook auxílio brasil
**Criação de uma operação**
Na criação de uma operação do Auxílio Brasil dentro do nosso sistema, são possíveis os seguintes status:
- **success**: Informa o sucesso na consulta do benefício.
- **failure**: Informa que ocorreu um erro na consulta do benefício.
**Exemplos**
Webhook de sucesso na consulta
**body.json**
```json
{
"callback": {
"key": "bfbe918d-fe58-55a0-bdaf-5a3733b7a12d",
"data": {
"name": "LUIZ ANTONIO DA SILVA",
"state": "RJ",
"balance": "111",
"family_code": 8553463416,
"reference_date": "2022-08-03",
"benefit_net_amount": 294,
"benefit_total_amount": 294,
"disbursement_bank_account": {
"bank_code": "103",
"account_digit": "5",
"account_branch": "3880",
"account_number": "000925559475"
},
"number_of_active_reservations": 0
},
"status": "success",
"webhook_type": "social_benefit_balance",
"event_datetime": "2022-08-29T20:47:48"
}
}
```
Webhook de erro na consulta
**body.json**
```json
{
"callback": {
"key": "5d85a8eb-94c1-4fcc-8f66-15b6301f6kfe",
"data": {
"enumerator": "not_found_family_member",
"description": "there is not an active authorization for person"
},
"status": "failure",
"webhook_type": "social_benefit_balance",
"event_datetime": "2022-10-17T21:54:16"
}
}
```
| Enumerators | Descrição |
|---|---|
| `dataprev_error` | erro inesperado no Dataprev |
| `not_found_family_member` | não há uma autorização ativa para pessoa |
| `benefit_deleted` | benefício foi excluído |
**Cancelamento de uma operação**
Existem alguns processos que cancelam uma operação de crédito, majoritariamente:
1. PIX/TED falhou ou foi estornado;
2. Passamos da data de desembolso;
3. Tentativa de averbação foi rejeitada;
Toda operação que está cancelada em nosso sistema pode voltar ao seu estado anterior através do método de mudança da data de desembolso.
Alguns casos não são possíveis de voltarem ao estado inicial porque nunca será desembolsada, como é o caso 3, cuja tentativa de averbação foi rejeitada.
Para o primeiro caso:
**body.json**
```json
{
"key": "\",
"data": {
"pix_refusal": {
"reason": "Número da conta de destino é inexistente ou inválido.",
"reason_enumerator": "invalid_account"
},
"cancel_reason": "pix_refusal"
},
"status": "canceled",
"webhook_type": "debt",
"event_datetime": "2022-11-01 13:39:44"
}
```
A reason_enumerator pode ser conforme a lista abaixo:
| Enumerators | Descrição |
|---|---|
| `invalid_document_number` | Documento inválido |
| `invalid_account` | Conta inválida |
| `unsupported_transaction` | Transação não suportada |
| `blocked_account` | Conta bloqueada |
| `closed_account` | Conta fechada |
| `rejected_payment` | Pagamento rejeitado |
| `amount_too_great` | Valor monetário muito alto |
| `spi_timeout` | Timeout do prestador de serviço |
| `receiver_error` | Erro do receptor |
| `incorrect_account_type` | Tipo de conta incorreta |
| `duplicity_of_payment_order` | Ordem de pagamento duplicado |
| `refund_after_unexpected_value` | Reembolso depois de valor inesperado |
| `refund_after_psp_error` | Reembolso depois de erros no PSP |
| `refund_after_technical_issues` | Reembolso depois de problemas técnicos |
| `refund_after_cancellation` | Reembolso depois de cancelamento |
| `refund_after_fraud` | Reembolso depois de fraude |
| `refund_after_payee_request` | Reembolso após solicitação do beneficiário |
| `refund_after_fraud_report` | Reembolso depois de relatório de fraude |
| `payee_not_in_allowed_list` | Beneficiário não se encontra na lista permitida |
| `payee_in_blocked_list` | Beneficiário se encontra na lista bloqueada |
| `unjustified_payment_order` | Ordem de pagamento não justificado |
O segundo caso, ocorre quando algum processo interno dispara o cancelamento da Operação:
**body.json**
```json
{
"key": "\",
"data": {
"cancel_reason": "Operacao cancelada manualmente",
"cancel_reason_enumerator": "manual"
},
"status": "canceled",
"webhook_type": "debt",
"event_datetime": "2022-11-01 03:46:31"
}
```
Aqui podemos ter os seguintes "cancel_reason_enumerators":
- Cancel Reason Enumerators em rejeição de PAB:
| Enumerators | Descrição |
|---|---|
| `social_benefit_ineligible_benefit` | Beneficio inelegível |
| `social_benefit_invalid_beneficiary_data` | Dados do beneficiário inválidos |
| `social_benefit_invalid_balance` | Margem indisponível |
| `social_benefit_contract_limit_exceeded` | O cliente não pode ter mais contratos |
| `social_benefit_installments_limit_exceeded` | O cliente não pode ter esse numero de parcelas em um contrato |
| `social_benefit_invalid_disbursement_account` | Conta divergente com o DataPrev |
- Cancel Reason Enumerators mudança de dia
| Enumerators | Descrição |
|---|---|
| `not_collateral_constituted_social_benefit` | Mudou de dia e a operação não teve a garantia averbada |
| `waiting_signature` | Mudou de dia e a operação não foi assinada |
| `not_assigned` | Mudou de dia e a CCB está configurada para desembolsar após a cessão, mas nao foi cedida |
| `disburse_is_not_allowed` | Mudou de dia e a CCB está configurada com o fluxo de "Liberar o desembolso" mas não foi liberado |
| `manual` | Mudou de dia e a operação não foi desembolsada. |
Os cancel reason começados com "social_benefit" são permanentes, então a reserva foi de fato rejeitada. Mas em relação aos outros, ainda podem retornar ao estado inicial então deve ser devidamente analisado.
---
# Confirm Individual Account Opening
URL: /en/documentation/baas/account/2fa_v2/abrir_conta_pf
As a second step in individual account opening, [after account reservation](/documentation/baas/account/abrir_conta_pf), the complete registration data of the account holder and evidence of acceptance of the account opening terms must be sent.
## Request
ENDPOINT /account_request/checking
METHOD POST
## Path Params
| Field | Type | Description | Characters |
|---------------|--------|----------------------------------------|------------|
| `account_request_key` | uuidv4 | Unique identification key for the account reservation request. | 36 |
Request Body
```json
{
"account_owner": {
"address": {
"street": "Av. Brigadeiro Faria Lima",
"state": "SP",
"city": "São Paulo",
"neighborhood": "Jardim Paulistano",
"number": "2391",
"postal_code": "01452905",
"complement": "Complemento"
},
"birth_date": "1990-05-06",
"document_identification": "3884579b-9810-4fa6-9b08-fe67d237160a",
"email": "teste@gmail.com",
"individual_document_number": "99999999999",
"is_pep": false,
"mother_name": "Dona Maria Mariane",
"name": "Nome do Titular da Conta",
"nationality": "nationality",
"person_type": "natural",
"phone": {
"country_code": "055",
"area_code": "11",
"number": "999999999"
},
"proof_of_residence": "4d7f4e-1eec-4e5f-82c0-d8c3921497ea"
},
"signed_contract": {
"document_key": "48a8f4g9-4b58-4905-9a69-b1f9215263f5",
"signatures": [
{
"authenticity": {
"timestamp": "1970-01-01T00:00:01.080100Z",
"facial_recognition_key": "79003de0-2590-455d-9b73-426b8ca284eb",
"lang": "-35.8916627",
"lat": "-7.2226067",
"ip_address": "177.51.1.186",
"session_id": "jdifj329842"
},
"signer": {
"name": "Nome do Titular da Conta",
"email": "teste@gmail.com",
"phone": {
"country_code": "055",
"area_code": "11",
"number": "999999999"
},
"document_number": "999999999"
},
"authentication_type": "opt-in"
}
]
},
"additional_documents": ["b12c8807-8f3f-4083-9cb1-7cce641f3786"]
}
```
### Request Body Params
| Field | Type | Description | Characters |
|---|---|--------------------------------------------------------------------------------------------|---|
| `account_owner` * | object | Object containing the Account Holder information | **[account_owner Object](#account_owner-object)** |
| `signed_contract` * | object | Object containing evidence of the Holder's acceptance of the account opening terms. | **[signed_contract Object](#signed_contract-object)** |
### account_owner Object
| Field | Type | Description | Characters |
|---| ---| ---|---------------------------------------|
| `address` * | string | Customer address. | **[address Object](#address-object)** | |
| `birth_date` * | string | Person's birth date (format "YYYY-MM-DD") | |
| `document_identification` * | string | DOCUMENT_KEY of the PDF of the person's photo identification document (ID or Driver's License) (previously sent) | |
| `document_identification_type` * | string | Type of previously sent document (ID or Driver's License) | |
| `email` * | string | Customer email. | |
| `individual_document_number` | string | Person's SSN (numbers only). Limited to 11 characters. | |
| `is_pep` * | string | Declaration if the person is PEP (http://www.portaldatransparencia.gov.br/download-de-dados/pep).| |
| `mother_name` * | string | Customer's mother's name for individual customers. | 100 |
| `name` * | string | Company name for corporate operations or Person's name for individual operations. | 100 |
| `nationality` * | string | Customer nationality. | 50 |
| `person_type` * | string | Identifier whether the sent object is an individual or corporate person.| |
| `phone` * | string | Object with phone data | **[phone Object](#phone-object)** |
| `proof_of_residence` | string | DOCUMENT_KEY of the PDF proof of address for the sent address (previously sent).| |
### address Object
This object, present in both individual and corporate objects, is a simple object to represent an address.
| Field | Description | Example | Max. Characters |
|---|---|---|---|
| `street` *| string | Street address | 100 |
| `state` *| string | State of the address (with two uppercase characters) | 2 |
| `city` *| string | City of the address | 100 |
| `neighborhood` *| string |Neighborhood of the address | 100 |
| `number` *| string | Street number | 10 |
| `postal_code` *| string |ZIP code of the address (http://www.buscacep.correios.com.br/sistemas/buscacep/) (numbers only) | 8 |
| `complement` *| string |Address complement (free text) | 100 |
### signed_contract Object
| Field | Type | Description | Characters |
|-------|--------|------------------|---------------|
| **document_key** * | uuidv4 | Unique identification key of the **Account Opening Terms** or **Escrow Account Contract** document. (The DOCUMENT_KEY is returned in the response of the [Document upload](./upload_de_documentos) endpoint) | 36 |
| **signatures** * | list | Signature data of the sent document. Each item in the list corresponds to a document signer. | [signatures Object](#signatures-object) |
### signatures Object
| Field | Type | Description | Characters |
|-------|------------|-------------------|-------------------|
| **authenticity** * | object | Set of data that evidences the electronic signature performed by the signer. | [authenticity Object](#authenticity-object) |
| **signer** * | object | Object containing the data of one of the document signers. | [signer Object](#signer-object)|
| **authentication_type** * | enumerator | Signature type. Will always be "**opt-in**"| "**opt-in**" |
### authenticity Object
| Field | Type | Description | Characters |
|-------|--------|-------------------------|------------|
| **timestamp** * | string | Date and time of the document signing moment. | 27 |
| **facial_recognition_key** | uuidv4 | Unique identification key of the account holder's selfie photo. (The DOCUMENT_KEY is returned in the response of the [Document upload](./upload_de_documentos) endpoint) | 36 |
| **lang** | string | Longitude coordinate of the signer's geolocation captured at the signing moment. | - |
| **lat** | string | Latitude coordinate of the signer's geolocation captured at the signing moment. | - |
| **ip_address** | string | IP address of the signer's device. | - |
| **session_id** | string | Signer's session ID at the signing moment. | - |
### signer Object
| Field | Type | Description | Characters |
|-----------------------|--------|-------------------------------------------|-----------------------------------|
| **name** * | string | Signer's name. | - |
| **email** * | string | Signer's email. | - |
| **phone** * | object | Object with signer's phone data | **[phone Object](#phone-object)** |
| **document_number** * | string | Signer's SSN. | 11 |
### phone Object
| Field | Description | Example | Max. Characters |
| --- | --- | --- | --- |
|`country_code` *| string | Phone country code (https://ddi.guiamais.com.br/) | 3 |
| `area_code` *| string | Phone area code (https://ddd.guiamais.com.br/) | 2 |
| `number` *| string |Phone number (numbers only) | 10 |
## Response
STATUS 201
Response Body
```json
{
"account_info": {
"account_branch": "0001",
"account_digit": "0",
"account_number": "1693580"
},
"account_request_key": "f230f1b5-07af-4737-b0e3-8a472304f5e7",
"account_request_status": "pending_kyc_analysis"
}
```
:::warning Warning
The `account_request_key` field must be stored and will be used for account opening confirmation.
:::
### Response Body Params
| Field | Type | Description | Characters|
|---|---| ---|---|
| `account_info` * | object | Object containing the Account Holder information |**[account_info Object](#account_info-object)** | - |
| `account_request_key` * | string | Creation request identification key | - | - |
| `account_request_status` * | string | KYC status | - | - |
### account_info Object
| Field | Type | Description | Characters |
|---|---| ---| --- |
| `account_branch` * | string | Branch Number | 4 |
| `account_digit` * | string | Email | 11 |
| `account_number` * | string | Account Holder Full Name | 50 |
STATUS 4xx
Response Body: Error
```json
{
"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(ptbr) `translation`|
|---| --- | --- | --- | --- |
| 400 | QIT000001 | Bad Request | Schema Error | Erro de Schema|
| 404 | QIT000404 | Not Found | Resource could not be found | Recurso não encontrado|
---
# Legal Entity Account Opening
URL: /en/documentation/baas/account/2fa_v2/abrir_conta_pj
Account opening occurs in two mandatory steps. First, a POST request sends preliminary data to reserve the account. Then, a webhook of type `account_request.status_change` with status `pending_additional_data` is triggered. In the second step, a PATCH request finalizes the opening, officializing the account with the complementary information.
## Request
ENDPOINT /account_request/checking
METHOD POST
## Path Params
| Field | Type | Description | Characters |
|---------------|--------|----------------------------------------|------------|
| `account_request_key` | uuidv4 | Unique identification key for account reservation request. | 36 |
## Free Movement Account Opening
Request Body
```json
{
"account_owner": {
"phone": {
"country_code": "55",
"area_code": "11",
"number": "999999999"
},
"email": "email@teste.com.br",
"person_type": "legal",
"name": "Empresa de Teste",
"address": {
"street": "Rua Abrahão Calux",
"state": "SP",
"city": "São Paulo",
"neighborhood": "Vila Teste",
"number": "116",
"postal_code": "04286100",
"complement": "Complemento"
},
"trading_name": "Nome fantasia",
"company_document_number": "99999999000130",
"cnae_code": "4721102",
"foundation_date": "1980-07-11",
"company_statute": "99999999-01c9-4cf5-a0fa-1d2a96f4b34d",
"company_representatives": [
{
"name": "Nome do Socio",
"individual_document_number": "99999999999",
"document_identification_number": "999999999",
"birth_date": "1989-09-01",
"mother_name": "Maria da Silva",
"email": "teste@gmail.com",
"is_pep": false,
"final_beneficiary": true,
"person_type": "natural",
"nationality": "brasileiro(a)",
"marital_status": "single",
"document_identification": "88888-0ddf-4932-874f-9231794963da",
"phone": {
"country_code": "055",
"area_code": "19",
"number": "999999999"
},
"address": {
"street": "Rua dos Limões",
"neighborhood": "Vila Moinho Velho",
"city": "São Paulo",
"state": "SP",
"postal_code": "04286100",
"number": "116",
"complement": "complemento"
}
}
],
"company_type": "ltda"
},
"signed_contract": {
"document_key": "57cda530-d469-4427-a9d4-2523a510dee1",
"signatures": [
{
"authenticity": {
"timestamp": "2024-05-10T14:15:03.114895Z",
"ip_address": "192168161",
"lang": "-35.8916627",
"lat": "-7.2226067",
"session_id": "54b8e3cf-15de-41e5-9305-0ecf059d6e2a",
"facial_recognition_key": "c367a540-2e7e-4373-a167-61bc43c30dc1"
},
"signer": {
"name": "Nome do assinante",
"email": "teste@gmail.com.br",
"phone": {
"country_code": "55",
"area_code": "11",
"number": "999999999"
},
"document_number": "99999999"
},
"authentication_type": "opt-in"
}
]
},
"additional_documents": [
"61f2a65e-0ddf-4932-874f-9231794963da"
]
}
```
### Request Body Params
| Field | Type | Description | Characters |
|-----------------------|--------|------------------------------------------------------------------------------|-------------------------------------------------------|
| **account_owner** * | object | Account owner object | **[Object account_owner](#object-account_owner)** |
| **allowed_user** * | object | User linked to the account. | **[Object allowed_user](#object-allowed_user)** |
| **account_manager** | object | Data of the integrating partner who will handle account transactions via API. | **[Object account_manager](#object-account_manager)** |
| `signed_contract` *| object | Object containing contract signature information. | **[Object signed_contract](#object-signed_contract)** |
### Object account_owner
| Field | Type | Description | Characters |
|-------------------------------|--------|-----------------------------------------------------------------------------------------------------------------------------------|-----------------------------------------------------------------------|
| **address** * | object | Account holder address object | **[Object address](#object-address)** |
| **cnae_code** * | string | National Classification of Economic Activities | 9 |
| **company_document_number** * | string | CNPJ | 14 |
| **company_statute** * | string | DOCUMENT_KEY of the company statute PDF (sent previously). | 36 |
| **company_type** | enum | Company type | **[Enumerators company_type](#enumerators-company_type)** |
| **company_representatives** * | list | List of company legal representatives | **[Object company_representatives](#object-company_representatives)** |
| **email** * | string | Company institutional email. | 254 |
| **foundation_date** * | string | Company establishment date (format "YYYY-MM-DD"). | 10 |
| **name** * | string | Legal name. | 100 |
| **person_type** * | enum | Identifier that the sent object is a legal entity. Must ALWAYS contain the value "legal" for Legal Entity Object. | **[Enumerators person_type](#enumerators-person_type)** |
| **phone** * | object | Account holder phone. | **[Object phone](#object-phone)** | - |
| **trading_name** * | string | Trade name. | 200 |
### Object company_representatives
| Field | Type | Description | Characters |
|------------------------------------|---------|--------------------------------------------------------------------------------------------------------|-----------------------------------------------------------------------------------------|
| **name** * | string | Company representative name | 100 |
| **address** * | object | Company representative address object | **[Object address](#object-address)** |
| **email** * | string | Company representative email | 254 |
| **birth_date** * | string | Company representative birth date (format "YYYY-MM-DD") | 10 |
| **individual_document_number** * | string | Company representative CPF (numbers only). | 11 |
| **document_identification** | string | DOCUMENT_KEY of the person's photo identification document PDF (ID or driver's license) (sent previously) | 36 |
| **document_identification_number** | string | Person's photo identification document number (ID or driver's license) | 16 |
| **document_identification_type** | enum | Person's photo identification document type (ID or driver's license) | [Enumerators document_identification_type](#enumerators-document_identification_type) |
| **is_pep** * | boolean | Declaration if the person is PEP (http://www.portaldatransparencia.gov.br/download-de-dados/pep). | - |
| **final_beneficiary** | boolean | Declaration if the person is the final beneficiary of the company. | - |
| **marital_status** | enum | Company representative marital status | **[Enumerators marital status](#enumerators-marital_status)** |
| **mother_name** * | string | Company representative mother's name | 100 |
| **nationality** | string | Company representative nationality | 50 |
| **person_type** * | enum | Identifier that the sent object is a natural person | **[Enumerators person_type](#enumerators-person_type)** |
| **phone** * | object | Object with company representative phone data | **[Object phone](#object-phone)** |
### Object address
This object, present in both the Natural Person and Legal Entity objects, is a simple object to represent an address.
| Field | Description | Example | Characters |
|--------------------|-----------|-------------------------------------------------------------------------------------------|------------|
| **street** * | string | Street address | 500 |
| **state** * | enum | State address (with two uppercase characters) | 2 |
| **city** * | string | City address | 255 |
| **neighborhood** * | string | Neighborhood address | 500 |
| **number** * | string | Street number | 10 |
| **postal_code** * | string | ZIP code address (http://www.buscacep.correios.com.br/sistemas/buscacep/) (numbers only) | 8 |
| **complement** | string | Address complement (free text) | 500 |
### Object signed_contract
| Field | Type | Description | Characters |
|-------|--------|------------------|---------------|
| **document_key** * | uuidv4 | Unique identification key for **Account Opening Agreement** or **Escrow Account Contract** document. (The DOCUMENT_KEY is returned in the [Document upload](./upload_de_documentos) endpoint response) | 36 |
| **signatures** * | list | Signature data of the sent document. Each list item corresponds to a document signer. | [Object signatures](#object-signatures) |
### Object signatures
| Field | Type | Description | Characters |
|-------|------------|-------------------|-------------------|
| **authenticity** * | object | Set of data evidencing the electronic signature performed by the signer. | [Object authenticity](#object-authenticity) |
| **signer** * | object | Object containing data of one of the document signers. | [Object signer](#object-signer)|
| **authentication_type** * | enumerator | Signature type. Will always be "**opt-in**"| "**opt-in**" |
### Object authenticity
| Field | Type | Description | Characters |
|-------|--------|-------------------------|------------|
| **timestamp** * | string | Date and time of document signature moment. | 27 |
| **facial_recognition_key** | uuidv4 | Unique identification key for the account holder's selfie photo. (The DOCUMENT_KEY is returned in the [Document upload](./upload_de_documentos) endpoint response) | 36 |
| **lang** | string | Longitude coordinate of signer's geolocation captured at signature moment. | - |
| **lat** | string | Latitude coordinate of signer's geolocation captured at signature moment. | - |
| **ip_address** | string | Signer's device IP address. | - |
| **session_id** | string | Signer's session ID at signature moment. | - |
### Object signer
| Field | Type | Description | Characters |
|-----------------------|--------|-------------------------------------------|-----------------------------------|
| **name** * | string | Signer name. | - |
| **email** * | string | Signer email. | - |
| **phone** * | object | Object with signer phone data | **[Object phone](#object-phone)** |
| **document_number** * | string | Signer CPF. | 11 |
### Object phone
| Field | Description | Example | Max Characters |
| --- | --- | --- | --- |
|`country_code` *| string | Phone country code (https://ddi.guiamais.com.br/) | 3 |
| `area_code` *| string | Phone area code (https://ddd.guiamais.com.br/) | 2 |
| `number` *| string |Phone number (numbers only) | 10 |
### Enumerators person_type
| Enum | Description |
|-------------|-------------------|
| **natural** | Natural person |
| **legal** | Legal entity |
### Enumerators document_identification_type
| Enum | Description |
|---------|----------------------------------------|
| **rg** | ID - General Registry |
| **cnh** | Driver's License |
### Enumerators company_type
| Enum | Description |
|----------------------------|--------------------------------------------------------------------------|
| **ltda** | Limited Liability Company |
| **sa** | Corporation |
| **micro_enterprise** | Micro Enterprise |
| **freelancer** | Freelancer |
| **sa_opened** | Public Corporation |
| **sa_closed** | Private Corporation |
| **se_ltda** | Limited Business Partnership |
| **se_cn** | General Partnership |
| **se_cs** | Limited Partnership |
| **se_ca** | Partnership Limited by Shares |
| **scp** | Joint Venture |
| **ei** | Individual Entrepreneur |
| **ese** | Foreign Company Establishment in Brazil |
| **eeab** | Argentine-Brazilian Binational Company Establishment in Brazil |
| **ssp** | Pure Simple Partnership |
| **ss_ltda** | Limited Simple Partnership |
| **ss_cn** | General Simple Partnership |
| **ss_cs** | Simple Limited Partnership |
| **eireli_ne** | Individual Limited Liability Company (Business Nature) |
| **eireli_ns** | Individual Limited Liability Company (Simple Nature) |
| **eireli** | Individual Liability Company |
| **mei** | Individual Micro Entrepreneur |
| **me** | Micro Enterprise |
| **cop** | Cooperative |
| **private_association** | Private Association |
### Enumerators marital_status
| Enum | Description |
|--------------|---------------|
| **single** | Single |
| **married** | Married |
| **widower** | Widowed |
| **divorced** | Divorced |
| **separated** | Separated |
## Response
STATUS 201
Response Body
```json
{
"account_info": {
"account_branch": "0001",
"account_digit": "0",
"account_number": "1693580"
},
"account_request_key": "f230f1b5-07af-4737-b0e3-8a472304f5e7",
"account_request_status": "pending_kyc_analysis"
}
```
:::warning Warning
The `account_request_key` field must be stored and will be used for account opening confirmation.
:::
### Response Body Params
| Field | Type | Description | Characters|
|---|---| ---|---|
| `account_info` * | object | Object containing Account Holder information |**[Object account_info](#object-account_info)** | - |
| `account_request_key` * | string | Creation request identification key | - | - |
| `account_request_status` * | string | KYC Status | - | - |
### Object account_info
| Field | Type | Description | Characters |
|---|---| ---| --- |
| `account_branch` * | string | Branch Number | 4 |
| `account_digit` * | string | Email | 11 |
| `account_number` * | string | Account Holder Full Name | 50 |
STATUS 4xx
Response Body: Error
```json
{
"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(ptbr) `translation`|
|---| --- | --- | --- | --- |
| 400 | QIT000001 | Bad Request | Schema Error | Schema Error|
| 404 | QIT000404 | Not Found | Resource could not be found | Resource not found|
---
# Confirm Individual Account Opening
URL: /en/documentation/baas/account/abrir_conta_pf
As the second step in individual account opening, [after account reservation](/documentation/baas/account/abrir_conta_pf), complete registration data of the account holder and evidence of acceptance of the account opening terms must be submitted.
## Request
ENDPOINT /account_request/ ACCOUNT_REQUEST_KEY /checking
METHOD PATCH
## Path Params
| Field | Type | Description | Characters |
|---------------|--------|----------------------------------------|------------|
| `account_request_key` | uuidv4 | Unique identification key for account reservation request. | 36 |
Request Body
```json
{
"account_owner": {
"address": {
"street": "Av. Brigadeiro Faria Lima",
"state": "SP",
"city": "São Paulo",
"neighborhood": "Jardim Paulistano",
"number": "2391",
"postal_code": "01452905",
"complement": "Complemento"
},
"birth_date": "1990-05-06",
"document_identification": "3884579b-9810-4fa6-9b08-fe67d237160a",
"email": "teste@gmail.com",
"individual_document_number": "99999999999",
"is_pep": false,
"mother_name": "Dona Maria Mariane",
"name": "Nome do Titular da Conta",
"nationality": "nationality",
"person_type": "natural",
"phone": {
"country_code": "055",
"area_code": "11",
"number": "999999999"
},
"proof_of_residence": "4d7f4e-1eec-4e5f-82c0-d8c3921497ea",
"monthly_income": 1000
},
"signed_contract": {
"document_key": "48a8f4g9-4b58-4905-9a69-b1f9215263f5",
"signatures": [
{
"authenticity": {
"timestamp": "1970-01-01T00:00:01.080100Z",
"facial_recognition_key": "79003de0-2590-455d-9b73-426b8ca284eb",
"lang": "-35.8916627",
"lat": "-7.2226067",
"ip_address": "177.51.1.186",
"session_id": "jdifj329842"
},
"signer": {
"name": "Nome do Titular da Conta",
"email": "teste@gmail.com",
"phone": {
"country_code": "055",
"area_code": "11",
"number": "999999999"
},
"document_number": "999999999"
},
"authentication_type": "opt-in"
}
]
},
"additional_documents": ["b12c8807-8f3f-4083-9cb1-7cce641f3786"]
}
```
### Request Body Params
| Field | Type | Description | Characters |
|---|---|--------------------------------------------------------------------------------------------|---|
| `account_owner` * | object | Object containing account holder information | **[account_owner Object](#account_owner-object)** |
| `signed_contract` * | object | Object containing evidence of the holder's acceptance of account opening terms. | **[signed_contract Object](#signed_contract-object)** |
### account_owner Object
| Field | Type | Description | Characters |
|---| ---| ---|---------------------------------------|
| `address` * | string | Customer address. | **[address Object](#address-object)** | |
| `birth_date` | string | Person's date of birth (format "YYYY-MM-DD") | |
| `document_identification` * | string | DOCUMENT_KEY of the PDF of the person's photo identification document (ID or driver's license) (previously uploaded) | | |
| `email` * | string | Customer email. | |
| `individual_document_number`* | string | Person's CPF (numbers only). Limited to 11 characters. | |
| `is_pep` * | string | Declaration if the person is PEP (http://www.portaldatransparencia.gov.br/download-de-dados/pep).| |
| `mother_name` | string | Customer's mother's name for individuals. | 100 |
| `name` * | string | Company name for business operations or Person's name for individual operations. | 100 |
| `nationality` * | string | Customer nationality. | 50 |
| `person_type` * | string | Identifier indicating whether the submitted object is an individual or legal entity.| |
| `phone` * | string | Object with phone data | **[phone Object](#phone-object)** |
| `proof_of_residence` | string | DOCUMENT_KEY of the PDF proof of address for the submitted address (previously uploaded).| |
|`monthly_income`* | number | Account holder's monthly income | |
### address Object
This object, present in both individual and legal entity objects, is a simple object to represent an address.
| Field | Description | Example | Max Characters |
|---|---|---|---|
| `street` *| string | Street address | 100 |
| `state` *| enum | Address state (two uppercase characters) | 2 |
| `city` *| string | Address city | 100 |
| `neighborhood` *| string |Address neighborhood | 100 |
| `number` *| string | Street number | 10 |
| `postal_code` *| string |Address postal code (http://www.buscacep.correios.com.br/sistemas/buscacep/) (numbers only) | 8 |
| `complement` *| string |Address complement (free text) | 100 |
### signed_contract Object
| Field | Type | Description | Characters |
|-------|--------|------------------|-------------------------------------------|
| `document_key` * | uuidv4 | Unique identification key of the **Account Opening Terms** or **Escrow Account Contract** document. (The DOCUMENT_KEY is returned in the response of the [Document upload](./upload_de_documentos) endpoint) | 36 |
| `signatures` * | list | Signature data for the submitted document. Each list item corresponds to one document signer. | **[signatures Object](#signatures-object)** |
### signatures Object
| Field | Type | Description | Characters |
|-------|------------|-------------------|-------------------------------------------------|
| `authenticity` * | object | Set of data that evidences the electronic signature performed by the signer. | **[authenticity Object](#authenticity-object)** |
| `signer` * | object | Object containing data of one of the document signers. | **[signer Object](#signer-object)** |
| `authentication_type` * | enumerator | Signature type. Will always be "**opt-in**"| "**opt-in**" |
### authenticity Object
| Field | Type | Description | Characters |
|-------|--------|-------------------------|------------|
| `timestamp` * | string | Date and time when the document was signed. | 27 |
| `facial_recognition_key`* | uuidv4 | Unique identification key of the account holder's selfie photo. | 36 |
| `lang` | string | Longitude coordinate of the signer's geolocation captured at the time of signing. | - |
| `lat` | string | Latitude coordinate of the signer's geolocation captured at the time of signing. | - |
| `ip_address` | string | IP address of the signer's device. | - |
| `session_id` * | string | Signer's session ID at the time of signing. | - |
### signer Object
| Field | Type | Description | Characters |
|-----------------------|--------|-------------------------------------------|-----------------------------------|
| `name` * | string | Signer's name. | - |
| `email` * | string | Signer's email. | - |
| `phone` * | object | Object with signer's phone data | **[phone Object](#phone-object)** |
| `document_number` * | string | Signer's CPF. | 11 |
### phone Object
| Field | Description | Example | Max Characters |
| --- | --- | --- | --- |
|`country_code` *| string | Phone country code (https://ddi.guiamais.com.br/) | 3 |
| `area_code` *| string | Phone area code (https://ddd.guiamais.com.br/) | 2 |
| `number` *| string |Phone number (numbers only) | 10 |
## Response
STATUS 201
Response Body
```json
{ "account_key": "78ea0fa6-8ea6-46ff-b66b-d2bc36fc8869" }
```
:::warning Warning
The `account_request_key` field must be stored and will be used for account opening confirmation.
:::
### Response Body Params
| Field | Type | Description | Characters |
|---|---| ---|-------------------------------------------------|
| `account_key` * | string | Unique account identification key| - | - |
STATUS 4xx
Response Body: Error
```json
{
"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(ptbr) `translation`|
|---| --- | --- | --- | --- |
| 400 | QIT000001 | Bad Request | Schema Error | Erro de Schema|
| 404 | QIT000404 | Not Found | Resource could not be found | Recurso não encontrado|
---
# Confirm Legal Entity Account Opening
URL: /en/documentation/baas/account/abrir_conta_pj
Account opening occurs in two mandatory steps. First, a POST request sends preliminary data to reserve the account. Then, a webhook of type `account_request.status_change` with status `pending_additional_data` is triggered. In the second step, a PATCH request finalizes the opening, officializing the account with complementary information.
## Request
ENDPOINT /account_request/ ACCOUNT_REQUEST_KEY /checking
METHOD PATCH
## Path Params
| Field | Type | Description | Characters |
|---------------|--------|----------------------------------------|------------|
| `account_request_key` | uuidv4 | Unique identification key for account reservation request. | 36 |
## Free Movement Account Opening
Request Body
```json
{
"account_owner": {
"phone": {
"country_code": "55",
"area_code": "11",
"number": "999999999"
},
"email": "email@teste.com.br",
"person_type": "legal",
"name": "Empresa de Teste",
"address": {
"street": "Rua Abrahão Calux",
"state": "SP",
"city": "São Paulo",
"neighborhood": "Vila Teste",
"number": "116",
"postal_code": "04286100",
"complement": "Complemento"
},
"trading_name": "Nome fantasia",
"company_document_number": "99999999000130",
"cnae_code": "4721102",
"foundation_date": "1980-07-11",
"company_statute": "99999999-01c9-4cf5-a0fa-1d2a96f4b34d",
"monthly_revenue": 100000,
"company_representatives": [
{
"name": "Nome do Socio",
"individual_document_number": "99999999999",
"document_identification_number": "999999999",
"birth_date": "1989-09-01",
"mother_name": "Maria da Silva",
"email": "teste@gmail.com",
"is_pep": false,
"final_beneficiary": true,
"person_type": "natural",
"nationality": "brasileiro(a)",
"marital_status": "single",
"document_identification": "88888-0ddf-4932-874f-9231794963da",
"phone": {
"country_code": "055",
"area_code": "19",
"number": "999999999"
},
"address": {
"street": "Rua dos Limões",
"neighborhood": "Vila Moinho Velho",
"city": "São Paulo",
"state": "SP",
"postal_code": "04286100",
"number": "116",
"complement": "complemento"
},
"representative_relationship": "ceo"
}
],
"company_type": "ltda"
},
"signed_contract": {
"document_key": "57cda530-d469-4427-a9d4-2523a510dee1",
"signatures": [
{
"authenticity": {
"timestamp": "2024-05-10T14:15:03.114895Z",
"ip_address": "192168161",
"lang": "-35.8916627",
"lat": "-7.2226067",
"session_id": "54b8e3cf-15de-41e5-9305-0ecf059d6e2a",
"facial_recognition_key": "c367a540-2e7e-4373-a167-61bc43c30dc1"
},
"signer": {
"name": "Nome do assinante",
"email": "teste@gmail.com.br",
"phone": {
"country_code": "55",
"area_code": "11",
"number": "999999999"
},
"document_number": "99999999"
},
"authentication_type": "opt-in"
}
]
},
"additional_documents": [
"61f2a65e-0ddf-4932-874f-9231794963da"
]
}
```
### Request Body Params
| Field | Type | Description | Characters |
|-----------------------|--------|--------------------------------------------------------------------------------------|-------------------------------------------------------|
| `account_owner` * | object | Account holder object | **[account_owner Object](#account_owner-object)** |
| `signed_contract` *| object | Object containing information about electronic acceptance of account opening terms. | **[signed_contract Object](#signed_contract-object)** |
| `additional_documents` *| list | List with `document_key` (uuidv4) of additional documents from the account holder. | 36 |
### account_owner Object
| Field | Type | Description | Characters |
|-------------------------------|--------|-----------------------------------------------------------------------------------------------------------------------------------|-----------------------------------------------------------------------|
| `address` * | object | Account holder address object | **[address Object](#address-object)** |
| `cnae_code` | string | National Classification of Economic Activities | 9 |
| `company_document_number` * | string | CNPJ | 14 |
| `company_statute` * | string | DOCUMENT_KEY of the company statute PDF (sent previously). | 36 |
| `company_type`* | enum | Company type | **[company_type Enumerators](#company_type-enumerators)** |
| `company_representatives` * | list | List of company legal representatives | **[company_representatives Object](#company_representatives-object)** |
| `email` * | string | Company institutional email. | 254 |
| `foundation_date` | string | Company establishment date (format "YYYY-MM-DD"). | 10 |
| `name` * | string | Corporate name. | 100 |
| `person_type` * | enum | Identifier that the sent object is a legal entity. Must ALWAYS contain the value "legal" for legal entity object. | **[person_type Enumerators](#person_type-enumerators)** |
| `phone` * | object | Account holder phone number. | **[phone Object](#phone-object)** | - |
| `trading_name` * | string | Trade name. | 200 |
| `monthly_revenue`* | number | Company monthly revenue | |
### company_representatives Object
| Field | Type | Description | Characters |
|------------------------------------|---------|--------------------------------------------------------------------------------------------------------|---------------------------------------------------------------------------------------------|
| `name` * | string | Company representative name | 100 |
| `address` * | object | Company representative address object | **[address Object](#address-object)** |
| `email` * | string | Company representative email | 254 |
| `birth_date` | string | Company representative birth date (format "YYYY-MM-DD") | 10 |
| `individual_document_number` * | string | Company representative CPF (numbers only). | 11 |
| `document_identification`* | string | DOCUMENT_KEY of the PDF of person's photo identification document (ID or Driver's License) (sent previously) | 36 |
| `document_identification_number`* | string | Photo identification document number (ID or Driver's License) | 16 |
| `document_identification_type` | enum | Photo identification document type (ID or Driver's License) | **[document_identification_type Enumerators](#document_identification_type-enumerators)** |
| `is_pep` * | boolean | Declaration if the person is PEP (http://www.portaldatransparencia.gov.br/download-de-dados/pep). | - |
| `final_beneficiary` | boolean | Declaration if the person is the final beneficiary of the company. | - |
| `marital_status` | enum | Company representative marital status | **[marital_status Enumerators](#marital_status-enumerators)** |
| `mother_name` | string | Company representative mother's name | 100 |
| `nationality` | string | Company representative nationality | 50 |
| `person_type` * | enum | Identifier that the sent object is a natural person | **[person_type Enumerators](#person_type-enumerators)** |
| `phone` * | object | Object with company representative phone data | **[phone Object](#phone-object)** |
| `representative_relationship` * | enum | Identifier of the relationship between the company and its representative | **[representative_relationship Enumerators](#representative_relationship-enumerators)
### address Object
This object, present in both the natural person and legal entity objects, is a simple object to represent an address.
| Field | Description | Example | Characters |
|--------------------|-----------|-------------------------------------------------------------------------------------------|------------|
| `street` * | string | Street address | 500 |
| `state` * | enum | Address state (with two uppercase characters) | 2 |
| `city` * | string | Address city | 255 |
| `neighborhood` * | string | Address neighborhood | 500 |
| `number` * | string | Street number | 10 |
| `postal_code` * | string | Address postal code (http://www.buscacep.correios.com.br/sistemas/buscacep/) (numbers only) | 8 |
| `complement`* | string | Address complement (free text) | 500 |
### signed_contract Object
| Field | Type | Description | Characters |
|-------|--------|------------------|---------------|
| `document_key` * | uuidv4 | Unique identification key for the **Account Opening Terms** or **Escrow Account Contract** document. (The DOCUMENT_KEY is returned in the response of the [Document upload](./upload_de_documentos) endpoint) | 36 |
| `signatures` * | list | Signature data for the sent document. Each list item corresponds to a document signatory. | [signatures Object](#signatures-object) |
### signatures Object
| Field | Type | Description | Characters |
|-------|------------|-------------------|-------------------|
| `authenticity` * | object | Set of data that evidences the electronic signature made by the signatory. | [authenticity Object](#authenticity-object) |
| `signer` * | object | Object containing data of one of the document signatories. | [signer Object](#signer-object)|
| `authentication_type` * | enumerator | Signature type. Will always be "**opt-in**"| "**opt-in**" |
### authenticity Object
| Field | Type | Description | Characters |
|-------|--------|-------------------------|------------|
| `timestamp` * | string | Date and time of document signature moment. | 27 |
| `facial_recognition_key`* | uuidv4 | Unique identification key for the account holder's selfie photo. | 36 |
| `lang` | string | Longitude coordinate of signatory's geolocation captured at signature moment. | - |
| `lat` | string | Latitude coordinate of signatory's geolocation captured at signature moment. | - |
| `ip_address` | string | Signatory's device IP address. | - |
| `session_id`* | string | Signatory's session ID at signature moment. | - |
### signer Object
| Field | Type | Description | Characters |
|-----------------------|--------|-------------------------------------------|-----------------------------------|
| `name` * | string | Signatory name. | - |
| `email` * | string | Signatory email. | - |
| `phone` * | object | Object with signatory phone data | **[phone Object](#phone-object)** |
| `document_number` * | string | Signatory CPF. | 11 |
### phone Object
| Field | Description | Example | Max Characters |
| --- | --- | --- | --- |
|`country_code` *| string | Phone country code (https://ddi.guiamais.com.br/) | 3 |
| `area_code` *| string | Phone area code (https://ddd.guiamais.com.br/) | 2 |
| `number` *| string |Phone number (numbers only) | 10 |
### person_type Enumerators
| Enum | Description |
|-------------|-------------------|
| `natural` | Natural person |
| `legal` | Legal entity |
### representative_relationship Enumerators
| Enum | Description |
|-------------|-------------------|
| `ceo` | Administrator |
| `partner` | Partner/Shareholder |
| `attorney` | Attorney|
### document_identification_type Enumerators
| Enum | Description |
|---------|----------------------------------------|
| `rg` | RG - General Registry |
| `cnh` | CNH - National Driver's License |
### company_type Enumerators
| Enum | Description |
|--------------------------|--------------------------------------------------------------------------|
| `ltda` | Limited Liability Company |
| `sa` | Corporation |
| `micro_enterprise` | Micro Enterprise |
| `freelancer` | Freelancer |
| `sa_opened` | Publicly Traded Corporation |
| `sa_closed` | Closed Corporation |
| `se_ltda` | Limited Business Partnership |
| `se_cn` | General Partnership |
| `se_cs` | Limited Partnership |
| `se_ca` | Partnership Limited by Shares |
| `scp` | Silent Partnership |
| `ei` | Individual Entrepreneur |
| `ese` | Brazilian Establishment of Foreign Company |
| `eeab` | Brazilian Establishment of Argentine-Brazilian Binational Company |
| `ssp` | Simple Partnership |
| `ss_ltda` | Limited Simple Partnership |
| `ss_cn` | General Simple Partnership |
| `ss_cs` | Limited Simple Partnership |
| `eireli_ne` | Individual Limited Liability Company (Business Nature) |
| `eireli_ns` | Individual Limited Liability Company (Simple Nature) |
| `eireli` | Individual Limited Liability Company |
| `mei` | Individual Microentrepreneur |
| `me` | Micro Enterprise |
| `cop` | Cooperative |
| `private_association` | Private Association |
| `others` | Others |
### marital_status Enumerators
| Enum | Description |
|--------------|---------------|
| `single` | Single |
| `married` | Married |
| `widower` | Widowed |
| `divorced` | Divorced |
| `separated` | Separated |
## Response
STATUS 201
Response Body
```json
{ "account_key": "78ea0fa6-8ea6-46ff-b66b-d2bc36fc8869" }
```
:::warning Attention
The `account_request_key` field must be stored and will be used to confirm account opening.
:::
### Response Body Params
| Field | Type | Description | Characters |
|---|---| ---|-------------------------------------------------|
| `account_key` * | string | Unique account identification key| - | - |
STATUS 4xx
Response Body: Error
```json
{
"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(ptbr) `translation`|
|---| --- | --- | --- | --- |
| 400 | QIT000001 | Bad Request | Schema Error | Schema Error|
| 404 | QIT000404 | Not Found | Resource could not be found | Resource not found|
---
# Request account reservation
URL: /en/documentation/baas/account/account_draft_checking
## Request
ENDPOINT /account_request/draft_checking
METHOD POST
## Account Opening
Request Body
```json
{
"account_owner":{
"address":{
"street":"Av. Brigadeiro Faria Lima",
"state":"SP",
"city":"São Paulo",
"neighborhood":"Jardim Paulistano",
"number":"2391",
"postal_code":"01452905",
"complement":"Complemento"
},
"birth_date":"1990-05-06",
"email":"teste@gmail.com",
"individual_document_number":"99999999999",
"is_pep":false,
"mother_name":"Dona Maria Mariane",
"name":"Nome do Titular da Conta",
"nationality":"nationality",
"person_type":"natural",
"phone":{
"country_code":"055",
"area_code":"11",
"number":"999999999"
},
"monthly_income":1000
}
}
```
### Account Opening
### Request Body Params
| Field | Type | Description |
|------------------|--------|----------------------------------------------------------------------------|
| `account_owner`* | object | Account holder details, including address and personal information. |
### account_owner Object
| Field | Type | Description |
|-------------------------------|---------|----------------------------------------------------------------|
| `address`* | object | Account holder's address. |
| `birth_date`* | string | Account holder's birth date (format "YYYY-MM-DD"). |
| `email`* | string | Account holder's email. |
| `individual_document_number`* | string | Account holder's CPF (numbers only). |
| `is_pep`* | boolean | Declaration if the person is a PEP. |
| `mother_name`* | string | Account holder's mother's name. |
| `name`* | string | Account holder's full name. |
| `nationality` | string | Account holder's nationality. |
| `person_type`* | enum | Person type, must always be "natural" for natural person. |
| `phone`* | object | Account holder's phone number. |
| `monthly_income` | number | Account holder's monthly income. |
### address Object
| Field | Type | Description | Characters |
|-----------------|--------|------------------------|------------|
| `street`* | string | Address street | - |
| `state`* | enum | Address state | 2 |
| `city`* | string | Address city | - |
| `neighborhood`* | string | Address neighborhood | - |
| `number`* | string | Street number | - |
| `postal_code`* | string | Address ZIP code | - |
| `complement` | string | Address complement| - |
### phone Object
| Field | Type | Description |
|------------------|--------|--------------------------|
| `country_code`* | string | Phone country code |
| `area_code`* | string | Phone area code |
| `number`* | string | Phone number |
### person_type Enumerators
| Enum | Description |
|---------|--------------|
| `natural` | Natural person |
|`legal`| Legal entity |
## Response
STATUS 201
Response Body
```json
{
"account_number": "1638634",
"reserved_account_status":"reserved",
"account_type": "checking",
"account_digit": "3",
"account_key": "b1690f7b-1e82-4f76-a8d3-c326a2b89b67",
"account_branch": "0001",
"account_name": "Nome do Proprietário",
"created_at": "2023-10-07T15:52:24"
}
```
:::warning Attention
The `account_request_key` field must be stored and will be used to confirm the account opening.
:::
### Response Body Params
| Field | Type | Description | Characters |
|---|---| ---|-------------------------------------------------|
| `account_key` * | string | Account unique identification key| - | - |
STATUS 4xx
Response Body: Error
```json
{
"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(ptbr) `translation`|
|---| --- | --- | --- | --- |
| 400 | QIT000001 | Bad Request | Schema Error | Erro de Schema|
| 404 | QIT000404 | Not Found | Resource could not be found | Recurso não encontrado|
---
# Request account reservation
URL: /en/documentation/baas/account/d4bf7f96-69b0-424b-a9d6-0a1bc79629cd
## Request
ENDPOINT /account_request/draft_checking
METHOD POST
## Account Opening
Request Body
```json
{
"account_owner":{
"address":{
"street":"Av. Brigadeiro Faria Lima",
"state":"SP",
"city":"São Paulo",
"neighborhood":"Jardim Paulistano",
"number":"2391",
"postal_code":"01452905",
"complement":"Complemento"
},
"birth_date":"1990-05-06",
"email":"teste@gmail.com",
"individual_document_number":"99999999999",
"is_pep":false,
"mother_name":"Dona Maria Mariane",
"name":"Nome do Titular da Conta",
"nationality":"nationality",
"person_type":"natural",
"phone":{
"country_code":"055",
"area_code":"11",
"number":"999999999"
},
"monthly_income":1000
}
}
```
### Account Opening
### Request Body Params
| Field | Type | Description |
|------------------|--------|----------------------------------------------------------------------------|
| `account_owner`* | object | Account holder details, including address and personal information. |
### account_owner Object
| Field | Type | Description |
|-------------------------------|---------|----------------------------------------------------------------|
| `address`* | object | Account holder's address. |
| `birth_date`* | string | Account holder's date of birth (format "YYYY-MM-DD"). |
| `email`* | string | Account holder's email. |
| `individual_document_number`* | string | Account holder's CPF (numbers only). |
| `is_pep`* | boolean | Declaration if the person is a PEP (Politically Exposed Person). |
| `mother_name`* | string | Account holder's mother's name. |
| `name`* | string | Account holder's full name. |
| `nationality` | string | Account holder's nationality. |
| `person_type`* | enum | Person type, must always be "natural" for individual person. |
| `phone`* | object | Account holder's phone. |
| `monthly_income` | number | Account holder's monthly income. |
### address Object
| Field | Type | Description | Characters |
|-----------------|--------|------------------------|------------|
| `street`* | string | Street address | - |
| `state`* | enum | State | 2 |
| `city`* | string | City | - |
| `neighborhood`* | string | Neighborhood | - |
| `number`* | string | Street number | - |
| `postal_code`* | string | Postal code | - |
| `complement` | string | Address complement| - |
### phone Object
| Field | Type | Description |
|------------------|--------|--------------------------|
| `country_code`* | string | Phone country code |
| `area_code`* | string | Phone area code |
| `number`* | string | Phone number |
### person_type Enumerators
| Enum | Description |
|---------|--------------|
| `natural` | Individual person |
|`legal`| Legal entity |
## Response
STATUS 201
Response Body
```json
{
"account_number": "1638634",
"reserved_account_status":"reserved",
"account_type": "checking",
"account_digit": "3",
"account_key": "b1690f7b-1e82-4f76-a8d3-c326a2b89b67",
"account_branch": "0001",
"account_name": "Nome do Proprietário",
"created_at": "2023-10-07T15:52:24"
}
```
:::warning Attention
The `account_request_key` field must be stored and will be used to confirm the account opening.
:::
### Response Body Params
| Field | Type | Description | Characters |
|---|---| ---|-------------------------------------------------|
| `account_key` * | string | Unique account identification key| - | - |
STATUS 4xx
Response Body: Error
```json
{
"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(ptbr) `translation`|
|---| --- | --- | --- | --- |
| 400 | QIT000001 | Bad Request | Schema Error | Erro de Schema|
| 404 | QIT000404 | Not Found | Resource could not be found | Recurso não encontrado|
---
# Introduction
URL: /en/documentation/baas/account/introducao
One of the features we can offer in our integration is the possibility to manage accounts and transfers to QI Tech accounts or other financial institutions via API, but that's not all - we provide the possibility to OPEN an account via API. Whether for yourself or for third parties.
Like other APIs, service activation must be done with our team and calls are authenticated.
Account opening occurs in two mandatory stages. In the first stage, a POST request is sent with preliminary data to make the account reservation. After this request, a query is automatically executed to the Central Bank, specifically to the repository linked to the BC Protege+ project. This system allows individuals and legal entities to voluntarily register restrictions indicating at which financial institutions they do not want new accounts to be opened in their names, as a fraud prevention measure.
In this flow, the initial status of the reservation is `pending_bacen_validation`.
If the query is approved, a webhook of type `account_request.status_change` is triggered, updating the status to `pending_kyc_analysis`.
After approval in the KYC analysis, a new webhook `account_request.status_change` is sent, changing the status to `pending_additional_data` — a stage that indicates the completion of the analysis and the need to send complementary information.
In the second stage, a PATCH request must be made containing the additional data necessary to finalize the process and formalize the account opening.
---
# Request Individual Account Opening
URL: /en/documentation/baas/account/reservar_conta_pf
Account opening occurs in two mandatory stages. First, a POST request sends preliminary data to reserve the account. Then, a webhook of type `account_request.status_change` with status `pending_additional_data` is triggered. In the second stage, a PATCH request finalizes the opening, officializing the account with complementary information.
## Request Account Reservation
## Request
ENDPOINT /account_request/checking
METHOD POST
Request Body
```json
{
"request_control_key": "5ef0f67a-7672-4d00-8a02-faf847157c4b",
"account_owner": {
"document_number": "99999999999",
"email": "email@teste.com",
"birthdate": "2017-09-16",
"name": "Titular da Conta",
"documents": {
"rg": {
"ocr_front_key": "2ef0f67a-7672-4d00-8a02-faf847157b4a",
"ocr_back_key": "1bd0e0a1-c1fa-4f9c-a230-f7a4163864be"
},
"cnh": {
"ocr_key": "7a73be1a-0b66-4c0a-932a-1d1d02efdc4c"
}
},
"face": "d38dd3c0-6f24-43b9-a37a-425d6700620f"
}
}
```
:::info CPF/CNPJ Mock
To simulate approval, rejection, and manual analysis situations, you can use the first digit of the account owner's CPF/CNPJ:
0 to 7 -> Manual Analysis
8 -> Automatically rejected in KYC
9 -> Automatic Approval
:::
### Request Body Params
| Field | Type | Description | Characters |
|---|--------|---------------------------------------------------|---------------------------------------------------|
| `account_owner` * | object | Object containing the Account Holder information | **[account_owner Object](#account_owner-object)** |
| `request_control_key` * | UUID | Unique identifier per partner request | 36 |
### account_owner Object
| Field | Type | Description | Characters |
|--- | --- | --- | --- |
| `document_number` * | string | Account Holder CPF | 11 |
| `email` * | string | Email | 11 |
| `birthdate` | string | Account Holder birthdate (YYYY-MM-DD format) | 10 |
| `name` * | string | Account Holder Full Name | 50 |
| `documents`* | object | Account holder document(s) | **[documents Object](#documents-object)** |
| `face`* | uuidv4 | Face recognition key from antifraud (`face_recognition_key`) | 36 |
### documents Object
| Field | Type | Description | Characters |
|--------------------------------|-------------|--------------------------------------------------------------------|-------------------------------|
| `rg` | object | OCR keys from front and back RG upload of the holder | **[rg Object](#rg-object)** |
| `cnh` | object | OCR key from CNH upload of the holder | **[cnh Object](#cnh-object)** |
| `cnh_digital` | object | OCR key from digital CNH upload of the holder | **[cnh_digital Object](#cnh_digital-object)** |
| `national_registry_of_foreigners` | object | OCR keys from front and back RNE upload of the holder| **[national_registry_of_foreigners Object](#national_registry_of_foreigners-object)** |
| `national_migration_registry` | object | OCR keys from front and back CRNM upload of the holder| **[national_migration_registry Object](#national_migration_registry-object)** |
| `passport` | object | OCR key from passport upload of the holder | **[passport Object](#passport-object)** |
| `cin_digital` | object | OCR key from digital National Identity Card upload of the holder | **[cin_digital Object](#cin_digital-object)** |
:::info Information
OCR keys (`ocr_key` or `ocr_front_key` and `ocr_back_key`) from document image uploads are provided as responses from image uploads in antifraud. The `face_recognition_key` is returned in the facial recognition response.
:::
### rg Object
| Field | Type | Description | Characters |
|--------------------------------|-------------|--------------------------------------------------------------------|-------------------------------|
| `ocr_front_key` * | uuidv4 | OCR key from RG front image upload | 36 |
| `ocr_back_key` * | uuidv4 | OCR key from RG back image upload | 36 |
OR
| Field | Type | Description | Characters |
|--------------------------------|-------------|--------------------------------------------------------------------|-------------------------------|
| `ocr_key` * | uuidv4 | OCR key from RG image upload | 36 |
### cnh Object
| Field | Type | Description | Characters |
|--------------------------------|-------------|--------------------------------------------------------------------|-------------------------------|
| `ocr_front_key` * | uuidv4 | OCR key from CNH front image upload | 36 |
| `ocr_back_key` * | uuidv4 | OCR key from CNH back image upload | 36 |
OR
| Field | Type | Description | Characters |
|--------------------------------|-------------|--------------------------------------------------------------------|-------------------------------|
| `ocr_key` * | uuidv4 | OCR key from CNH image upload | 36 |
### cnh_digital Object
| Field | Type | Description | Characters |
|--------------------------------|-------------|--------------------------------------------------------------------|-------------------------------|
| `ocr_key` * | uuidv4 | OCR key from digital CNH image upload | 36 |
### national_registry_of_foreigners Object
| Field | Type | Description | Characters |
|--------------------------------|-------------|--------------------------------------------------------------------|-------------------------------|
| `ocr_front_key` * | uuidv4 | OCR key from RNE front image upload | 36 |
| `ocr_back_key` * | uuidv4 | OCR key from RNE back image upload | 36 |
OR
| Field | Type | Description | Characters |
|--------------------------------|-------------|--------------------------------------------------------------------|-------------------------------|
| `ocr_key` * | uuidv4 | OCR key from RNE image upload | 36 |
### national_migration_registry Object
| Field | Type | Description | Characters |
|--------------------------------|-------------|--------------------------------------------------------------------|-------------------------------|
| `ocr_front_key` * | uuidv4 | OCR key from CRNM front image upload | 36 |
| `ocr_back_key` * | uuidv4 | OCR key from CRNM back image upload | 36 |
OR
| Field | Type | Description | Characters |
|--------------------------------|-------------|--------------------------------------------------------------------|-------------------------------|
| `ocr_key` * | uuidv4 | OCR key from CRNM image upload | 36 |
### passport Object
| Field | Type | Description | Characters |
|--------------------------------|-------------|--------------------------------------------------------------------|-------------------------------|
| `ocr_key` * | uuidv4 | OCR key from passport image upload | 36 |
### cin_digital Object
| Field | Type | Description | Characters |
|--------------------------------|-------------|--------------------------------------------------------------------|-------------------------------|
| `ocr_key` * | uuidv4 | OCR key from digital National Identity Card image upload | 36 |
## Response
STATUS 201
Response Body
```json
{
"account_info": {
"account_branch": "0001",
"account_digit": "0",
"account_number": "1693580"
},
"account_request_key": "f230f1b5-07af-4737-b0e3-8a472304f5e7",
"account_request_status": "pending_bacen_validation"
}
```
:::info Bacen Protege+ Flow
The proposal starts with status `pending_bacen_validation`. The system performs a preliminary validation with Bacen Protege+ before proceeding with KYC analysis. After Bacen approval, the status will be automatically updated to `pending_kyc_analysis`.
:::
:::warning Warning
The `account_request_key` field must be stored and will be used for account opening confirmation.
:::
### Response Body Params
| Field | Type | Description | Characters|
|---|---| ---|---|
| `account_info` * | object | Object containing Account Holder information |**[account_info Object](#account_info-object)** | - |
| `account_request_key` * | string | Creation request identification key | - | - |
| `account_request_status` * | string | KYC Status | - | - |
### account_info Object
| Field | Type | Description | Characters |
|---|---| ---| --- |
| `account_branch` * | string | Branch Number | 4 |
| `account_digit` * | string | Account Digit | 11 |
| `account_number` * | string | Account Number | 50 |
STATUS 4xx
Response Body: Error
```json
{
"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(ptbr) `translation`|
|---| --- | --- | --- | --- |
| 400 | QIT000001 | Bad Request | Schema Error | Erro de Schema|
| 404 | QIT000404 | Not Found | Resource could not be found | Recurso não encontrado|
---
# Legal Entity Account Opening
URL: /en/documentation/baas/account/reservar_conta_pj
Account opening occurs in two mandatory stages. First, a POST request sends preliminary data to reserve the account. Then, a webhook of type `account_request.status_change` with the status `pending_additional_data` is triggered. In the second stage, a PATCH request finalizes the opening, making the account official with the complementary information.
## Request Account Reservation
## Request
ENDPOINT /account_request/checking
METHOD POST
Request Body
```json
{
"account_owner": {
"company_document_number": "99999999000199",
"email": "teste@email.com",
"foundation_date": "2017-09-16",
"name": "NOME DA EMPRESA"
},
"legal_representatives": [
{
"birthdate": "1963-07-23",
"name": "Don Corleone",
"document_number": "03912394323",
"email": "teste@gmail.com",
"documents": {
"national_registry_of_foreigners": {
"ocr_front_key": "0aa8a4ca-5873-49bd-851c-1f2c71a1cc28",
"ocr_back_key": "29f6e346-7fae-4dcb-9ea1-2a3e4ef593ea"
}
},
"face": "68da08f1-6cf4-4dce-a297-7b2f09311784"
},
{
"birthdate": "1996-03-10",
"name": "John Doe",
"document_number": "39113492093",
"email": "teste@gmail.com",
"documents": {
"cnh": {
"ocr_key": "beee557e-9240-4c5b-88f1-42812b195168"
}
}
}
]
}
```
:::info CPF/CNPJ Mock
To simulate approval, rejection, and manual analysis situations, you can use the first digit of the account owner's CPF/CNPJ:
0 to 6 -> Manual Analysis
7 -> Rejected by bacen protege+
8 -> Automatically rejected in KYC
9 -> Automatic Approval
:::
### Request Body Params
| Field | Type | Description | Characters |
|---|---| ---|---|
| `account_owner` * | object | Object containing Account Holder information | **[account_owner Object](#account_owner-object)** |
| `legal_representatives`* | object array | List of account representatives and their data | **[legal_representative Object](#legal_representative-object)** |
### account_owner Object
| Field | Type | Description | Characters |
|--- | --- | --- | --- |
| `company_document_number` * | string | Account Holder CNPJ | 50 |
| `email` * | string | Email | 11 |
| `foundation_date` | string | Company foundation date (YYYY-MM-DD format) | 10 |
| `name` * | string | Account Holder Full Name | 50 |
### legal_representative Object
| Field | Type | Description | Characters |
|--- | --- | --- | --- |
| `document_number` * | string | Account Holder CPF | 11 |
| `birthdate` | string | Date of birth (YYYY-MM-DD format) | 10 |
| `name` * | string | Account Holder Name | 50 |
| `documents` * | object | Account holder document(s) | **[documents Object](#documents-object)** |
| `face`* | uuidv4 | Facial recognition key made with antifraud (`face_recognition_key`) | 36 |
### documents Object
| Field | Type | Description | Characters |
|--------------------------------|-------------|--------------------------------------------------------------------|-------------------------------|
| `rg` | object | OCR keys for front and back upload of holder's RG | **[rg Object](#rg-object)** |
| `cnh` | object | OCR key for holder's CNH upload | **[cnh Object](#cnh-object)** |
| `cnh_digital` | object | OCR key for holder's digital CNH upload | **[cnh_digital Object](#cnh_digital-object)** |
| `national_registry_of_foreigners` | object | OCR keys for front and back upload of holder's RNE| **[national_registry_of_foreigners Object](#national_registry_of_foreigners-object)** |
| `national_migration_registry` | object | OCR keys for front and back upload of holder's CRNM| **[national_migration_registry Object](#national_migration_registry-object)** |
| `passport` | object | OCR key for holder's passport upload | **[passport Object](#passport-object)** |
| `cin_digital` | object | OCR key for holder's digital National Identity Card upload | **[cin_digital Object](#cin_digital-object)** |
:::info Information
The OCR keys (`ocr_key` or `ocr_front_key` and `ocr_back_key`) for document image uploads are provided as a response from antifraud image uploads. The `face_recognition_key` is returned in the facial recognition response.
:::
### rg Object
| Field | Type | Description | Characters |
|--------------------------------|-------------|--------------------------------------------------------------------|-------------------------------|
| `ocr_front_key` * | uuidv4 | OCR key for RG front image upload | 36 |
| `ocr_back_key` * | uuidv4 | OCR key for RG back image upload | 36 |
OR
| Field | Type | Description | Characters |
|--------------------------------|-------------|--------------------------------------------------------------------|-------------------------------|
| `ocr_key` * | uuidv4 | OCR key for RG image upload | 36 |
### cnh Object
| Field | Type | Description | Characters |
|--------------------------------|-------------|--------------------------------------------------------------------|-------------------------------|
| `ocr_front_key` * | uuidv4 | OCR key for CNH front image upload | 36 |
| `ocr_back_key` * | uuidv4 | OCR key for CNH back image upload | 36 |
OR
| Field | Type | Description | Characters |
|--------------------------------|-------------|--------------------------------------------------------------------|-------------------------------|
| `ocr_key` * | uuidv4 | OCR key for CNH image upload | 36 |
### cnh_digital Object
| Field | Type | Description | Characters |
|--------------------------------|-------------|--------------------------------------------------------------------|-------------------------------|
| `ocr_key` * | uuidv4 | OCR key for digital CNH image upload | 36 |
### national_registry_of_foreigners Object
| Field | Type | Description | Characters |
|--------------------------------|-------------|--------------------------------------------------------------------|-------------------------------|
| `ocr_front_key` * | uuidv4 | OCR key for RNE front image upload | 36 |
| `ocr_back_key` * | uuidv4 | OCR key for RNE back image upload | 36 |
OR
| Field | Type | Description | Characters |
|--------------------------------|-------------|--------------------------------------------------------------------|-------------------------------|
| `ocr_key` * | uuidv4 | OCR key for RNE image upload | 36 |
### national_migration_registry Object
| Field | Type | Description | Characters |
|--------------------------------|-------------|--------------------------------------------------------------------|-------------------------------|
| `ocr_front_key` * | uuidv4 | OCR key for CRNM front image upload | 36 |
| `ocr_back_key` * | uuidv4 | OCR key for CRNM back image upload | 36 |
OR
| Field | Type | Description | Characters |
|--------------------------------|-------------|--------------------------------------------------------------------|-------------------------------|
| `ocr_key` * | uuidv4 | OCR key for CRNM image upload | 36 |
### passport Object
| Field | Type | Description | Characters |
|--------------------------------|-------------|--------------------------------------------------------------------|-------------------------------|
| `ocr_key` * | uuidv4 | OCR key for passport image upload | 36 |
### cin_digital Object
| Field | Type | Description | Characters |
|--------------------------------|-------------|--------------------------------------------------------------------|-------------------------------|
| `ocr_key` * | uuidv4 | OCR key for digital National Identity Card image upload | 36 |
## Response
STATUS 201
Response Body
```json
{
"account_info": {
"account_branch": "0001",
"account_digit": "0",
"account_number": "1693580"
},
"account_request_key": "f230f1b5-07af-4737-b0e3-8a472304f5e7",
"account_request_status": "pending_bacen_validation"
}
```
:::info Bacen Protege+ Flow
The proposal starts with status `pending_bacen_validation`. The system performs a preliminary validation with Bacen Protege+ before proceeding with KYC analysis. After Bacen approval, the status will be automatically updated to `pending_kyc_analysis`.
:::
:::warning Warning
The `account_request_key` field must be stored and will be used for account opening confirmation.
:::
### Response Body Params
| Field | Type | Description | Characters|
|---|---| ---|---|
| `account_info` * | object | Object containing Account Holder information |**[account_info Object](#account_info-object)** | - |
| `account_request_key` * | string | Creation request identification key | - | - |
| `account_request_status` * | string | KYC Status | - | - |
### account_info Object
| Field | Type | Description | Characters |
|---|---| ---| --- |
| `account_branch` * | string | Branch Number | 4 |
| `account_digit` * | string | Email | 11 |
| `account_number` * | string | Account Holder Full Name | 50 |
STATUS 4xx
Response Body: Error
```json
{
"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(ptbr) `translation`|
|---| --- | --- | --- | --- |
| 400 | QIT000001 | Bad Request | Schema Error | Erro de Schema|
| 404 | QIT000404 | Not Found | Resource could not be found | Recurso não encontrado|
---
# Account opening webhooks
URL: /en/documentation/baas/account/webhooks
After the account reservation request, the initial status is `pending_bacen_validation`. If approved, the reservation status is updated to `pending_kyc_analysis`. Then, upon KYC approval, the status becomes `pending_additional_data`.
For the status `pending_kyc_analysis`, `pending_additional_data` and `rejected`, the webhook of type `account_request.status_change` is sent, being this event essential for controlling the next actions necessary for account opening confirmation.
The account number will be reserved at the time of the opening reservation request, however at this moment **the account will not yet be open**. Only after completion of QI Tech's KYC analysis and subsequent confirmation of the request by the partner, the account will be open.
### account_request_status enumerators
| Enum | Description |
|-----------------------------|-------------------------------------|
| **pending_kyc_analysis** | Pending KYC approval |
| **pending_additional_data** | Pending additional information |
| **rejected** | Opening rejected |
When the status is `rejected`, the webhook includes the `rejection_reason` field in the root of the message. The value of this field is free-form and returned directly from the KYC analysis, and may vary according to the reason identified, whether from KYC analysis or from Bacen Protege+.
### KYC analysis pending webhook
WEBHOOK_TYPE account_request.status_change
STATUS pending_kyc_analysis
Webhook Body
```json
{
"data": {
"account_info": {
"account_digit": "3",
"account_branch": "0001",
"account_number": "1638634"
},
"account_request_key": "dc575950-dcce-48e1-99a6-5fb0ada63d86",
"status": "pending_kyc_analysis"
},
"event_datetime": "2022-09-02 22:39:39",
"key": "dc575950-dcce-48e1-99a6-5fb0ada63d86",
"status": "pending_kyc_analysis",
"webhook_type": "account_request.status_change"
}
```
### Account confirmation pending webhook
WEBHOOK_TYPE account_request.status_change
STATUS pending_additional_data
Webhook Body
```json
{
"key": "dc575950-dcce-48e1-99a6-5fb0ada63d86",
"data": {
"account_info": {
"account_digit": "3",
"account_branch": "0001",
"account_number": "1638634"
},
"account_request_key": "dc575950-dcce-48e1-99a6-5fb0ada63d86"
},
"event_datetime": "2022-09-02 22:39:39",
"status": "pending_additional_data",
"webhook_type": "account_request.status_change"
}
```
### Rejected account opening webhook (KYC)
WEBHOOK_TYPE account_request.status_change
STATUS rejected
Webhook Body
```json
{
"data": {
"account_info": {
"account_digit": "3",
"account_branch": "0001",
"account_number": "1638634"
},
"account_request_key": "dc575950-dcce-48e1-99a6-5fb0ada63d86"
},
"event_datetime": "2022-09-02T22:39:39",
"key": "dc575950-dcce-48e1-99a6-5fb0ada63d86",
"status": "rejected",
"webhook_type": "account_request.status_change",
"rejection_reason": "UNSC"
}
```
### Rejected account opening webhook (Bacen Protege+)
WEBHOOK_TYPE account_request.status_change
STATUS rejected
Webhook Body
```json
{
"data": {
"account_info": {
"account_digit": "3",
"account_branch": "0001",
"account_number": "1638634"
},
"account_request_key": "dc575950-dcce-48e1-99a6-5fb0ada63d86"
},
"event_datetime": "2022-09-02T22:39:39",
"key": "dc575950-dcce-48e1-99a6-5fb0ada63d86",
"status": "rejected",
"webhook_type": "account_request.status_change",
"rejection_reason": "Rejeitado devido ao Bacen Protege+"
}
```
---
# Error Catalog - Banking-as-a-Service
URL: /en/documentation/baas/catalogo_de_erros_baas
Below are all errors that may be returned by Banking-as-a-Service APIs.
Each error code has a unique identifier that can be used as a reference.
:::info
The pix-keys-api service only uses shared errors (QIT) listed in the Common Errors section below.
:::
## Common Errors
Errors shared across all platform APIs.
| Code | HTTP | Message |
|-|-|-|
| `QIT000001` | 400 | **Schema Validator Error** {description} Payload Inválido |
| `QIT000002` | 403 | **Permission Validator Error** Request must be internal |
| `QIT000003` | 403 | **Permission Validator Error** The agent does not have enough roles. O agente não tem funções suficientes. |
| `QIT000004` | 403 | **Permission Validator Error** Selected agent and person_key are different Agente selecionado e person_key são diferentes |
| `QIT000005` | 403 | **Permission Validator Error** Selected agent do not own this item. O agente selecionado não é dono do item. |
| `QIT000006` | 403 | **Permission Validator Error** Selected agent do not own this item and has not enough roles. Agente selecionado não é dono deste item e não tem funções suficientes. |
| `QIT000007` | - | **External API Error (Rest Connector)** {description} {translation} |
| `QIT000010` | 400 | **Search Params Error** Invalid integer value for page or size querystring parameters Valor inválido para parâmetros página ou tamanho de página |
| `QIT000400` | 400 | **Bad Request** The server cannot or will not process the request due to an apparent client error (e.g., malformed request syntax, size too large, invalid request message framing, or deceptive request routing) O servidor não pode ou não processará a requisição devido a um erro do cliente (por exemplo, corpo da requisição inválido, tamanho muito grande, formatação da mensagem inválida ou rota inválida) |
| `QIT000404` | 404 | **Not Found** The requested resource could not be found but may be available in the future. Subsequent requests by the client are permissible O resource solicitado não pôde ser encontrado, mas pode estar disponível no futuro. Requests subsequentes do cliente são permitidos |
| `QIT000500` | 500 | **Internal Error** An internal error has occurred and its being investigated. Um erro interno aconteceu e está sendo investigado. |
| `QIT000753` | 500 | **Internal Error** An internal error has occurred and its being investigated. Um erro interno aconteceu e está sendo investigado. |
## Specific Errors
### ACC — Accounts
224 errors
| Code | HTTP | Message |
|-|-|-|
| `ACC000001` | 400 | **Bad Request** Use POST /account |
| `ACC000002` | 409 | **Reserved Account Error** Reserved account already created Conta reservada já foi criada |
| `ACC000003` | 409 | **Reserved Account Error** Reserved account already released Conta reservada já foi liberada |
| `ACC000004` | 400 | **Bad Request** Use PATCH /account/{account_key} |
| `ACC000005` | 403 | **Unauthorized Agent** This agent can not perform this action Este agente não pode realizar esta ação |
| `ACC000006` | 404 | **Not Found** Account not found for the given key {account_key} Conta não encontrada para a seguinte chave {account_key} |
| `ACC000007` | 400 | **Bad Request** A SELECTED_AGENT or person_key must be provided SELECTED_AGENT ou person_key devem ser fornecidos |
| `ACC000008` | 404 | **Not Found** Account not found for the given parameters. Conta não encontrada para os parâmetros fornecidos. |
| `ACC000009` | 423 | **Invalid Account** Blocked or closed accounts can not perform this action Contas bloqueadas ou fechadas não podem realizar esta ação. |
| `ACC000010` | 404 | **Owner Person Not Found** Owner person_key {person_key} not found. Dono não encontrada para a person_key {person_key}. |
| `ACC000011` | 423 | **Invalid Account** Closed accounts can not perform this action. Contas fechadas não podem realizar esta ação. |
| `ACC000012` | 400 | **Bad Request** Account Key is obligatory Chave da conta (account_key) é obrigatória |
| `ACC000013` | 400 | **Bad Request** Use /account/{account_key}/beneficiary |
| `ACC000014` | 400 | **Bad Request** Use /account/{account_key}/beneficiary?document_number={document_number} or /account/{account_key}/beneficiary/{beneficiary_key} Use /account/{account_key}/beneficiary?document_number={document_number} ou /account/{account_key}/beneficiary/{beneficiary_key} |
| `ACC000015` | 400 | **Bad Request** is_activated is needed in payload Parâmetro is_activated é obrigatório |
| `ACC000016` | 404 | **Not Found** Beneficiary accounts not found for the given parameters. Contas do beneficiário não encontradas para os parâmetros fornecidos |
| `ACC000017` | 404 | **Not Found** Target account not found for the given key Conta destino não encontrada para os parâmetros fornecidos |
| `ACC000018` | 402 | **Block Balance Error** Impossible to block an amount greater than account balance Não é possível blockear uma quantidade maior do que o saldo na conta |
| `ACC000019` | 402 | **Block Balance Error** Account blocked balance cannot be negative. Saldo da conta a ser bloqueada não pode ser negativo. |
| `ACC000020` | 402 | **Block Balance Error** Account blocked balance cannot be 0 or null. Saldo da conta a ser bloqueada não pode ser 0 ou nulo. |
| `ACC000021` | 422 | **Account Status Error** Account status can not perform this action (source_status: {source_account_enumerator}, target_status: {target_account_enumerator}) Status da conta não pode realizar esta ação (source_status: {source_account_enumerator}, target_status: {target_account_enumerator}) |
| `ACC000022` | 422 | **Unprocessable Entity** Transaction already performed Transação já realizada |
| `ACC000023` | 422 | **Unprocessable Entity** Transaction cannot be performed before the transaction_date Transação não pode ser realizada antes da data de transação (transaction_date) |
| `ACC000024` | 404 | **Not Found** Transaction not found Transação não encontrada |
| `ACC000025` | 422 | **Invalid Account** Invalid account. Conta inválida. |
| `ACC000026` | 422 | **Account Error** Transaction must be performed using a system account. Transações devem ser realizadas utilizando uma conta do sistema. |
| `ACC000027` | 402 | **Account Balance Error** Account balance must not be negative after the transaction. Saldo da conta não pode ser negativo após a transação. |
| `ACC000028` | 402 | **Account Balance Error** Transaction cannot be made due to already blocked balance. Transação não pode ser feita pois saldo em conta bloqueado. |
| `ACC000029` | 400 | **Bad Request** No body provided Request não possui body. |
| `ACC000030` | 400 | **Bad Request** Use POST /reserved_account |
| `ACC000031` | 400 | **Bad Request** Use GET /reserved_account/{reserved_account_key} |
| `ACC000032` | 404 | **Not Found** Reserved account not found. Conta reservada não encontrada |
| `ACC000033` | 404 | **Not Found** There is no transaction for the given key Transação não encontrada para a chave fornecida |
| `ACC000034` | 422 | **Account Error** Transaction cannot be performed using a system account. Transações não devem ser realizadas utilizando uma conta do sistema. |
| `ACC000035` | 400 | **Bad Request** Status parameter is required É necessário o parâmetro STATUS na request |
| `ACC000036` | 400 | **Bad Request** Wrong parameters used on the request Parâmetros incorretos |
| `ACC000037` | 400 | **Bad Request** Wrong parameter used on the request: {param} Parâmetro incorreto: {param} |
| `ACC000038` | 400 | **Transaction Request Error** Missing transaction request key Necessária a chave da Solicitação de transação |
| `ACC000039` | 400 | **Transaction Request Error** Transaction request not found Solicitação de transação não encontrada |
| `ACC000040` | 400 | **Transaction Request Error** Transaction request {transaction_request_key} already approved Solicitação de transação {transaction_request_key} já foi aprovada |
| `ACC000041` | 400 | **Transaction Request Error** Transaction {transaction_request_key} request already rejected Solicitação de transação {transaction_request_key} já foi recusada |
| `ACC000042` | 400 | **Transaction Request Error** User has already approved the {transaction_request_key} request O usuário já aprovou a solicitação {transaction_request_key} |
| `ACC000043` | 400 | **Transaction Request Error** User has already rejected the {transaction_request_key} request O usuário já rejeitou a solicitação {transaction_request_key} |
| `ACC000044` | 423 | **Transaction Request Error** Closed target can not receive transfer Conta destino fechada não pode receber transferências |
| `ACC000045` | 400 | **Bad Request** Missing page or size mandatory parameters on request. Request não possui os parâmetros obrigatórios de tamanho e número de página. |
| `ACC000046` | 404 | **Not Found** No match for given schedule_key Nenhum resultado encontrado para a schedule_key fornecida |
| `ACC000047` | 400 | **Bad Request** Scheduling time cannot occur for the same day after 17:00, nor be on a weekend, holiday or on a past date. Data de agendamento não pode ser para o mesmo dia após as 17:00, nem ser finais de semana, feriados ou datas passadas. |
| `ACC000048` | 402 | **Balance Error** Not enough balance to perform transaction Saldo insuficiente para esta transação |
| `ACC000049` | 400 | **Credential Error** This account doesn't have requester credentials Esta conta não possui credenciais de requester |
| `ACC000050` | 400 | **Bad Request** Invalid destination, destination account not permitted for this escrow account COnta de destino inválida, conta de destino não cadastrada para essa conta escrow |
| `ACC000051` | 400 | **Destination Error** Destination isn't a internal account Destino não é uma conta interna |
| `ACC000052` | 400 | **Bad Request** Invalid Transaction Type. Tipo de transação inválido |
| `ACC000053` | 400 | **Bad Request** Invalid operation for this account type Tipo de operação inválida para este tipo de conta |
| `ACC000054` | 400 | **Bad Request** {rule_enum} was not found among registered rules. {rule_enum} não encontrada dentro das regras registradas. |
| `ACC000055` | 400 | **Bad Request** Mismatch between automatic transfer configuration and respective rule template: {message} Incompatibilidade entre a configuração de transferência automática e o modelo da respectiva regra: {message} |
| `ACC000056` | 422 | **Unprocessable Entity** Account is empty. A conta está vazia. |
| `ACC000057` | 400 | **Bad Request** Movement date cannot be a past date Data de movimentação não pode ser uma data passada |
| `ACC000058` | 400 | **Bad Request** Movement date has to be a workday Data de movimentação precisa ser um dia util |
| `ACC000059` | 400 | **Bad Request** Movement date has to be today for movement type: {movement_type} Data de movimentação precisa ser hoje para o tipo: {movement_type} |
| `ACC000060` | 400 | **Bad Request** Movement date cannot be today for movement type: {movement_type} Data de movimentação não pode ser hoje para o tipo: {movement_type} |
| `ACC000061` | 423 | **Locked** Bank slip payment is available from {opening_time} to {closing_time} Pagamento de boleto está disponível entre {opening_time} e {closing_time} |
| `ACC000062` | 423 | **Locked** TED is available from {opening_time} to {closing_time} TED está disponível entre {opening_time} e {closing_time} |
| `ACC000063` | 404 | **Not Found** Movement schema not found for {movement_type} movement type Schema de movimentação não pode ser encontrado para o tipo: {movement_type} |
| `ACC000064` | 400 | **Bad Request** No {product_type} {role_type} found for owner_person_key {person_key} {product_type} {role_type} não encontrado para a person_key {person_key} |
| `ACC000065` | 400 | **Bad Request** Approver feedback must be a boolean Feedback do aprovador precisa ser booleano |
| `ACC000066` | 404 | **Not Found** Movement requests not found for given keys Pedidos de movimentação não encontrados para as chaves informadas |
| `ACC000067` | 409 | **Conflict** A movement request with status {movement_status} already exists for the informed digitable line Um pedido de movimentação com status {movement_status} ja existe para a linha digitavel |
| `ACC000068` | 403 | **Unauthorized** Only master users can change account webhook enablement Apenas usuários master podem mudar a habilitação da conta para o webhook |
| `ACC000069` | 400 | **Bad Request** Use POST /account/{account_key}/webhook_enabled |
| `ACC000070` | 400 | **Bad Request** Use POST /monthly_account_fee |
| `ACC000071` | 400 | **Bad Request** Use PATCH /monthly_account_fee/{account_key} |
| `ACC000072` | 404 | **Not Found** Transaction Receipt Not Found for key {transaction_key} Recibo de transação não encontrado para key {transaction_key} |
| `ACC000073` | 400 | **Bad Request** Remaining balance must not be less than 0 Saldo remanescente mínimo não pode ser menor que 0 |
| `ACC000074` | 423 | **Locked** Bank slip payment greater than or equal to R${amount} is available from {opening_time} to {closing_time} Pagamento de boleto igual ou acima de R${amount} está disponível entre {opening_time} e {closing_time} |
| `ACC000075` | 403 | **Unauthorized** User does not have permission to request this transaction Usuário não tem permissão para requisitar essa transação |
| `ACC000076` | 400 | **Bad Request** Invalid cron for automatic transfer Cron inválida para cadastro de transferência automática |
| `ACC000077` | 400 | **Bad Request** Account number and branch must be integers. Número da conta e da agência devem ser inteiros. |
| `ACC000078` | 404 | **Not Found** Destination account internal not found Conta destino interna não encontrada |
| `ACC000079` | 403 | **Unauthorized** User does not have permission to approve or reject this movement request Usuário não tem permissão para aprovar ou rejeitar um pedido de transação |
| `ACC000080` | 403 | **Bad Request** Setup Fee can not be negative Taxa de configuração não pode ser negativa |
| `ACC000081` | 404 | **Not Found** Transaction Schedule not found Transação não encontrada |
| `ACC000082` | 423 | **Invalid Account** Closed accounts can not perform this action {account_key}. Contas fechadas não podem realizar esta ação. {account_key} |
| `ACC000083` | 400 | **Source Account not found** The source account from CNAB was not found. Source Account number: {account_number} A conta de origem identificada no CNAB não foi encontrada. Conta de origem {account_number} |
| `ACC000084` | 400 | **Payment date in the past** It was found a transaction with payment date in the past. Payment date from transaction: {payment_date} Foi encontrada uma transação que está com a data de pagamento no passado. {payment_date} |
| `ACC000085` | 400 | **Bad Request - CNAB ERROR** Empty or corrupted file. Arquivo vazio ou corrompido. |
| `ACC000085` | 400 | **Bad Request - CNAB ERROR** CNAB version not supported yet. Versão de CNAB não suportada. |
| `ACC000086` | 400 | **Bad Request - CNAB ERROR** Could not find the CNAB type. Não foi possível identificar o tipo de arquivo CNAB enviado. |
| `ACC000088` | 400 | **Bad Request - CNAB ERROR** Registry line size incorrect. Registro com tamanho incorreto. |
| `ACC000089` | 400 | **Bad Request - CNAB ERROR** Could not determine Bank Code. Não foi possível determinar o código do banco operador detalhess: {details_br} cnab_filename: {cnab_filename} cnab_line: {cnab_line} cnab_inline_start_position: {cnab_inline_start_position} cnab_inline_end_position: {cnab_inline_end_position} cnab_inline_field: {cnab_inline_field} cnab_inline_field_type: {cnab_inline_field_type} cnab_inline_field_value: {cnab_inline_field_value} |
| `ACC000090` | 400 | **Bad Request - CNAB ERROR** Could not determine CNAB version. Não foi possível determinar a versão do CNAB. |
| `ACC000091` | 400 | **Bad Request - CNAB ERROR** Could not determine CNAB type (Remittance / Discharge). Não foi possível determinar o tipo do CNAB (Remessa / Retorno). |
| `ACC000092` | 400 | **Bad Request - CNAB ERROR** Could not set the field. Não foi possível ler o campo. |
| `ACC000093` | 400 | **Bad Request - CNAB ERROR** Max field size exceeded. Número máximo de dígitos excedido para o campo. |
| `ACC000094` | 400 | **Bad Request - CNAB ERROR** Tipo de valor incorreto. Value type incorrect. |
| `ACC000095` | 400 | **Bad Request - CNAB ERROR** Wrong number of decimal places. Número de casas decimais incorreto. |
| `ACC000096` | 400 | **Bad Request - CNAB ERROR** Wrong header record position in file. Registro Header colocado na posição incorreta. |
| `ACC000097` | 400 | **Bad Request - CNAB ERROR** Wrong cnab record sequence. Sequência de registros incorreta no arquivo. |
| `ACC000098` | 400 | **Bad Request - CNAB ERROR** Record type not supported. Tipo de registro não suportado. |
| `ACC000099` | 400 | **Bad Request - CNAB ERROR** Could not determine bank name. Não foi possível determinar o nome do banco. |
| `ACC000100` | 400 | **Bad Request** Unable to read CNAB file. Check file data for special characters at line {line} and position {position} Não foi possível ler o CNAB devido presença de caracteres especiais na linha {line} e posição {position} do arquivo. |
| `ACC000101` | 422 | **Unprocessable Entity** The field Identification of the Beneficiary Institution {beneficiary_code} on the registration lines (positions 021 to 037) is different from the beneficiary company identification {company_code} in the header (positions 027 to 046). O campo Identificação da Empresa Beneficiária {beneficiary_code} nas linhas de registro (posições 021 a 037) é diferente da identificação da empresa beneficiária {company_code} no cabeçalho (posições 027 a 046). |
| `ACC000102` | 400 | **Invalid FileName** Invalid filename ({cnab_filename}). Please do not use specials characters like '!,@,(,),$' . Nome de arquivo inválido ({cnab_filename}). Favor não utilizar caracteres especiais como '!,@,(,),$' . |
| `ACC000103` | 404 | **Not Found** Could not find financial institution with bank code: {code_number} Não foi possível encontrar a instituicao financeira com o codigo bancario {code_number} |
| `ACC000104` | 400 | **Bad Request** Total Percentage Split is greater than 100% Porcentagem total da divisão é maior que 100% |
| `ACC000105` | 400 | **Bad Request** Errors in batch transactions Erros nas transações em lote |
| `ACC000106` | 403 | **Forbidden** Account {account_key} is closed and cannot perform movement request Conta {account_key} está fechada e não pode realizar transação |
| `ACC000107` | 400 | **Bad Request** The account webhook to be changed was not informed Não foi informado a conta do webhook a ser alterado |
| `ACC000108` | 404 | **Not Found** No match for given schedule_category Nenhum resultado encontrado para a schedule_category informada |
| `ACC000109` | 400 | **Bad Request** The chosen scheduled movement date cannot happen outside a limit of 60 days from now. A data de agendamento escolhida não pode estar fora do intervalo de 60 dias futuros a partir de hoje. |
| `ACC000110` | 400 | **Bad Request** Requesting a scheduled chargeback is not an allowed operation. Solicitar uma devolução agendada de PIX não é uma operação permitida. |
| `ACC000111` | 400 | **Bad Request** Pix field {field} required Campo {field} necessário para o pix |
| `ACC000112` | 404 | **Not Found** An automatic_transfer not found for the given parameters A automatic_transfer não foi encontrada com os parâmetros fornecidos |
| `ACC000113` | 400 | **Bad Request** Unable to perform a transaction with a null transaction amount Não é possível realizar uma operação com um valor de transação nulo. |
| `ACC000114` | 400 | **Bad Request** Unable to perform a transaction with a transaction amount with more than 2 decimal places Não é possível realizar uma operação com um valor que tenha mais de duas casas decimais. |
| `ACC000115` | 400 | **Bad Request** Unable to deactivate the last credential from a person. Impossível deletar a ultima permissão de uma pessoa. |
| `ACC000116` | 404 | **Not Found** Ted account type not found for type: {type}. Tipo de conta ted não encontrado para tipo: {type}. |
| `ACC000117` | 409 | **Conflict** There's already an account destination with the same data. Já existe um destino de conta com os mesmos dados. |
| `ACC000118` | 404 | **Not Found** Account destination status not found. Status da conta de destino não foi encontrado. |
| `ACC000119` | 400 | **Bad Request** Account destination document number must be the same of the account owner. O número do documento de destino da conta deve ser o mesmo do proprietário da conta. |
| `ACC000120` | 400 | **Bad Request** prefixed amount is greater than available amount. valor pré fixado é superior ao valor disponível. |
| `ACC000121` | 400 | **Bad Request** Date format is invalid.It must be YYYY-mm-dd Formato da data está invalido. Este deve ser YYYY-mm-dd |
| `ACC000122` | 400 | **Bad Request** Name field cannot be longer than 50 characters Campo nome não pode ter mais de 50 caracteres |
| `ACC000123` | 400 | **Bad Request** Account balance cannot be greater than 0. Saldo remanescente nao pode ser maior que 0. |
| `ACC000124` | 400 | **Bad Request** Can't perform this action. There'are few unpaid fees Não é possível realizar essa ação. Há transações futuras que não foram pagas. |
| `ACC000125` | 400 | **Bad Request** Can't perform this action. There'are few unpaid bankslip fees Não é possível realizar essa ação. Há taxas de boleto que não foram pagas. |
| `ACC000126` | 400 | **Bad Request** There are accepted, registered or payment notice bank slips yet Ainda há boletos aceitos, registrados ou com aviso de pagamento |
| `ACC000127` | 500 | **Bad Request** Failed to create account cancelling term Falha ao criar termo de cancelamento de conta |
| `ACC000128` | 400 | **Bad Request** Pix unavailable in this moment. Please use TED. Pix indisponível no momento. Por favor utilizar a TED. |
| `ACC000129` | 400 | **Bad Request** {type} is not a valid balance type. {type} não é um tipo válido de extrato. |
| `ACC000130` | 400 | **Bad Request** System Account is not allowed to do that transaction Contas de sistema não são habilitadas para executar essa transação. |
| `ACC000131` | 400 | **Bad Request** Outgoing transfer must not have a target account Transações de saída não podem possuir uma conta destino |
| `ACC000132` | 400 | **Bad Request** Incoming transfer must not have a source account Transações de entrada não podem possuir uma conta origem |
| `ACC000133` | 401 | **Unauthorized** Invalid token Token inválido |
| `ACC000134` | 401 | **Unauthorized** Expired token Token Expirado |
| `ACC000135` | 400 | **Bad Request** Contact does not exist Contato nao existe |
| `ACC000136` | 400 | **Bad Request** Target account branch or number must not be 0. Agência ou número da conta de destino não podem ser 0. |
| `ACC000137` | 400 | **Bad Request** There is no pending movement correspondent to sent payload Não há nenhum pedido de movimentação correspondente à payload enviada |
| `ACC000138` | 400 | **Bad Request** Movement request has null movement type Movement request tem movement type nulo |
| `ACC000139` | 400 | **Bad Request** Movement request has invalid movement status: {old_movement_status} Movement request possui movement status inválido: {old_movement_status} |
| `ACC000140` | 400 | **Bad Request** Could not find movement approval for agent {selected_agent} Não foi possível encontrar movement approval para o agente {selected_agent} |
| `ACC000141` | 400 | **Bad Request** Movement request has already received feedback Movement request já recebeu um feedback |
| `ACC000142` | 400 | **Bad Request** Your account has no approver. Please, contact our support. Sua conta não possui aprovador. Por favor, contate nosso suporte. |
| `ACC000143` | 404 | **Not Found** Investment not found Investmento não foi encontrado. |
| `ACC000144` | 400 | **Bad Request** Accounts do not have proper investment relationship Contas não possuem relacionamento de investimento adequado |
| `ACC000145` | 400 | **Not Found** Invalid yield percentage amount Valor de procentagem de rendimento inválido. |
| `ACC000146` | 422 | **Unprocessable Entity** Account investment configuration already exists for this account Já existe uma configuração de investimento para esta conta |
| `ACC000147` | 422 | **Unprocessable Entity** Account has not a existing investment configuration linked A conta não tem uma configuração de investimento associada. |
| `ACC000148` | 422 | **Unprocessable Entity** Cannot setup a investment configuration to a closed account Não pode criar uma configuração de investimento em uma conta fechada |
| `ACC000149` | 422 | **Unprocessable Entity** There was a problem performing this withdraw. Please contact our support Houve um problema ao efetuar este saque. Por favor contate nosso suporte |
| `ACC000150` | 400 | **Bad Request** International messaging not allowed Envio de mensagens internacionais não permitido |
| `ACC000151` | 400 | **Bad Request** Operation not identified Operação não identificada |
| `ACC000152` | 400 | **Bad Request** Contact type {contact_type} not allowed Forma de contato por {contact_type} não permitida |
| `ACC000153` | 400 | **Bad Request** Incorrect or incomplete mobile number Número de celular incorreto ou incompleto |
| `ACC000154` | 404 | **Not Found** Professional Data not found Professional Data não encontrada |
| `ACC000155` | 400 | **Bad Request** Transaction {source_subtype} cannot be performed with given accounts Transação {source_subtype} não pode ser realizada com as contas informadas |
| `ACC000156` | 400 | **Bad Request** Transaction amount cannot be zero Valor de transação não deve ser zero |
| `ACC000157` | 404 | **Not Found** Investment Configuration not found Configuração de Investimento não encontrada |
| `ACC000158` | 400 | **Bad Request** Investment available amount not enough to perform withdraw Somatório de investimentos insuficiente para realizar a transação |
| `ACC000159` | 400 | **Bad Request** Invalid Investment Movement type Tipo de Movimentação de investimento inválida |
| `ACC000160` | 400 | **Bad Request** Account number {account_number} already in use Número de conta {account_number} já em uso |
| `ACC000161` | 400 | **Bad Request** Required investment deposit amount greater than allowed Depósito de investimento requerido maior que permitido |
| `ACC000162` | 400 | **Conflict** Update of investment_available_balance did not meet expectations. Expected: {expected}. Calculated: {calculated} Update de investment_available_balance não atendeu às espectativas. Esperado: {expected}. Calculado: {calculated} |
| `ACC000163` | 400 | **Conflict** Value {value} not allowed for attribute {attribute} in object {object_name} Valor {value} não permitido para atributo {attribute} no objeto {object_name} |
| `ACC000164` | 400 | **Bad Request** Date interval (date_from and date_to) must be provided to generate statement Intervalo de datas (date_from and date_to) deve ser fornecido para geração de extrato |
| `ACC000165` | 400 | **Bad Request** Date interval greater than allowed of {maximum_days} Intervalo de datas maior que o permitido de {maximum_days} |
| `ACC000166` | 400 | **Bad Request** Person_key must be provided Person_key deve ser fornecida |
| `ACC000167` | 400 | **Conflict** Discrepancy detected on available yield transfer Discrepância detectada em available yield transfer |
| `ACC000168` | 400 | **Bad Request** The agent document number is not linked to the company that owns the account to approve this request. O agent document number enviado não esta vinculado a empresa titular da conta para aprovar esta solicitação. |
| `ACC000169` | 400 | **Bad Request** External transactions cannot be reversed Transações externas não podem ser revertidas |
| `ACC000170` | 400 | **Bad Request** Reversal transaction already made Reversão de transação já realizada |
| `ACC000171` | 400 | **Bad Request** Subtype is not allowed to have transaction reversed Subtipo não pode ter transação revertida |
| `ACC000172` | 400 | **Bad Request** Account balance must have a maximum of 2 decimal places Balanço de conta deve ter no máximo 2 casas decimais |
| `ACC000173` | 400 | **Bad Request** Transaction account balance must be equal to account balance Balanço de conta da transação deve ser igual ao balanço de conta |
| `ACC000174` | 400 | **Bad Request** System accounts must be owned and requested by QITECH Contas de sistema devem ser requeridas e propeietárias da QITECH |
| `ACC000175` | 400 | **Bad Request** Account status {account_status} not allowed Status da conta {account_status} não permitido |
| `ACC000176` | 400 | **Transaction limit exceeded** The transactions within this date range exceeds the limit, please try again with a smaller date range! As transações nesse intervalo de data excedem o limite, tente novamente com um intervalo de data menor! |
| `ACC000177` | 400 | **Bad Request** The date range must be provided! Intervalo de datas deve ser fornecido! |
| `ACC000178` | 400 | **Bad Request** Person_key and account_key must be provided Person_key e account_key deve ser fornecida |
| `ACC000179` | 429 | **Conflict** The request_control_key {request_control_key} already exists A request_control_jey {request_control_key} já existe |
| `ACC000180` | 400 | **Bad Request** The owner_trading_name can only be sent by a legal person type O owner_trading_name só pode ser utilizado por uma pessoa jurídica |
| `ACC000181` | 404 | **Not found** Alias {alias_key} not found Alias {alias_key} não encontrado |
| `ACC000182` | 404 | **Alias Key Not found** The alias_key {alias_key} was not Found A alias_key {alias_key} não foi encontrada |
| `ACC000183` | 400 | **Wrong Pagination Query Parameter Set** If page_number was informed, the page_size should also be informed Se o page_number foi informado, o page_size deve ser informado tambem |
| `ACC000184` | 400 | **Wrong Datetime** The datetime contined in the string {datetime_string} is not in datetime-Zulu format A datetime contida na string {datetime_string} não está em formato datetime-Zulu |
| `ACC000185` | 403 | **Invalid Owner Person Key** The informed account_key {account_key} is not allowed to access this resource, because the SELECTED-AGENT key is not the same from the informed account A account_key informada {account_key} não tem permissão de acessar esse recurso, pois a SELECTED-AGENT key não é a mesma da account informada |
| `ACC000186` | 404 | **Request Control Key Not found** The informed request_control_key {request_control_key} has no original registered entry associated A request_control_key informada {request_control_key} não possui entrada original associada |
| `ACC000187` | 403 | **Forbidden Selected-Agent** The informed SELECTED-AGENT {selected_agent_key} is not allowed to access this resource O SELECTED-AGENT informado {selected_agent_key} não tem permissão de acessar esse recurso |
| `ACC000188` | 400 | **Invalid Indirect Participant Key** The informed Indirect Participant Key is invalid a Indirect Participant Key é invalida |
| `ACC000189` | 400 | **Missing Query Parameters** The necessery parameters for the query are not present Os paramentros necessarios para a query não estão presentes |
| `ACC000190` | 404 | **Account Key not Found** The Account key related with the presented parameters was not found A Account Key relacionada com os parametros apresentados não foi encontrada |
| `ACC000191` | 422 | **Repeated Request Informations** The same combination of account_number, account_branch and ispb was already previusly done in another Alias creation requisition A mesma combinação de account_number, account_branch e ispb ja foi previamente registrado em outra requisição de criação de Alias |
| `ACC000192` | 400 | **Bad Request** Account with floating rebate configuration! Conta com configuração de rebate de floating ativo! |
| `ACC000193` | 400 | **Bad Request** There was a problem performing verification in floating rebate configuration Problema durante a verificação de configuração de rebate de floating! |
| `ACC000194` | 400 | **Bad Request** Document number {document_number} is not valid Número de documento {document_number} não é válido |
| `ACC000195` | 400 | **Bad Request** Document number {document_number} sent does not match the person_type {person_type} Número de documento {document_number} não corresponde ao tipo de pessoa {person_type} |
| `ACC000196` | 400 | **Bad Request** The account is bonded in DDA. A conta está vinculada ao DDA. |
| `ACC000197` | 400 | **Bad Request** Selected user agent must be provided. Selected user agent deve ser fornecido. |
| `ACC000198` | 400 | **Bad Request** Unable to change {contact_info} using contact type {contact_type} Não é possível mudar o contato utilizando o contact type {contact_type} |
| `ACC000199` | 400 | **Bad Request** Billing configuration data can not be None Dados de configuração de cobrança não pode ser nula |
| `ACC000200` | 400 | **Invalid reference year** Invalid reference year. Ano de referência inválido. |
| `ACC000201` | 403 | **Invalid Destination** Target account is not a valid Destination Conta alvo não é um destino válido |
| `ACC000202` | 400 | **Invalid permission** Given requester has no permission to the account Requisitante enviado não possui permissão na conta |
| `ACC000203` | 400 | **Invalid permission** Given approver has no permission to the account Aprovador enviado não possui permissão na conta |
| `ACC000204` | 400 | **Mandatory parameters missing** Query parameters requester_person_key and approver_person_key must be sent Parâmetros de query requester_person_key e approver_person_key são obrigatórios |
| `ACC000205` | 400 | **Conflicting parameters** Send only a document_number or a person_key Envie apenas um document_number ou uma person_key |
| `ACC000206` | 400 | **Bad Request** Natural person account does not have allowed users. Conta de pessoa física não possui usuários autorizados. |
| `ACC000207` | 400 | **Bad Request** Transaction amount must be greater than 0. Valor da transação deve ser maior que 0. |
| `ACC000208` | 404 | **Account not found** Account not found. Conta não encontrada. |
| `ACC000209` | 405 | **Method not allowed** you are not allowed to call this method. Você não tem permissão para este método. |
| `ACC000210` | 403 | **Forbidden** Escrow account are not allowed to call this method. Método não peermitido para contas escrow. |
| `ACC000211` | 409 | **Conflict** Duplicated request control key {request_control_key}. Entrada duplicada para request control key {request_control_key}. |
| `ACC000212` | 400 | **Bad Request** Agent document number must be provided. Documento do agente deve ser fornecido. |
| `ACC000213` | 400 | **Bad Request** Invalid uuid format. UUID no formato inválido. |
| `ACC000214` | 400 | **Bad Request** Invalid page size. Tamanho da página inválido. |
| `ACC000215` | 400 | **Bad Request** Invalid format for field. It must be a string comprised of only digits Formato inválido para campo. Deve ser uma string compostas por apenas digitos |
| `ACC000216` | 400 | **Bad Request** Open Pix Schedules for this account detected Agendamentos de pix em aberto detectados para esta conta |
| `ACC000217` | 400 | **Bad Request** Can't perform peer to peer with the same target and source account Não é possível realizar transação de ponta a ponta com mesma origem e destino |
| `ACC000218` | 400 | **Automatic Transfer External Transaction Error** An error occurred while performing automatic transfer transaction Um erro ocorreu durante tentativa de realizar transferência automática |
| `ACC000219` | 403 | **Requester not allowed to perform this action** Requester not allowed to create destination Requester não autorizado a criar conta destino |
| `ACC000220` | 400 | **Max attempts for automatic transfer reached** Maximum number of failed attempts for automatic transfer reached Número máximo de tentativas falhas de transferências atingida |
| `ACC000221` | 404 | **Not Found** Financial institution branch not found Filial da instituição financeira não encontrada |
| `ACC000222` | 400 | **Bad Request** Automatic transfer to the same account as source Transferência automática para a mesma conta que de origem. |
| `ACC000223` | 409 | **Conflict** Account with number {account_number} already exists Conta com número {account_number} já existe |
| `ACC000224` | 400 | **Bad Request** Source and target accounts must be different Contas de origem e destino devem ser diferentes |
### ACR — Account Request
47 errors
| Code | HTTP | Message |
|-|-|-|
| `ACR000001` | 404 | **Account Request Not Found** Account Request not found for the given parameters Solicitação de conta não encontrada para os parâmetros dados. |
| `ACR000002` | 404 | **Account Request Not Found** Account Request not found for the given key {account_request_key}. Solicitação de conta não encontrada para a seguinte chave {account_request_key}. |
| `ACR000003` | 404 | **Proposal Not Found** Proposal not found. Proposta não encontrada. |
| `ACR000004` | 400 | **Bad Request** This account don't have valid credentials to this proposal. Esta conta não tem credenciais válidas para esta proposta. |
| `ACR000005` | 400 | **Bad Request** Use PUT account_request/{account_request_key} |
| `ACR000006` | 400 | **Account Request Error** Account Request is not pending master approval Pedido de conta não está pendente de aprovação master |
| `ACR000007` | 400 | **Bad Request** Use PATCH /account/{account_key} |
| `ACR000008` | 403 | **Unauthorized Agent** This agent can not perform this action Este agente não pode realizar esta ação |
| `ACR000009` | 400 | **Bad Request** Requester key needed! Requester key necessária! |
| `ACR000010` | 400 | **Bad Request** Related Party Owner needed! Related Party Owner necessário! |
| `ACR000011` | 400 | **Proposal Error** Proposal Isn't Pending Administrator Approval! Proposta não está pendente de aprovação do administrador! |
| `ACR000012` | 400 | **Proposal Update Error** Update Error Erro no update |
| `ACR000013` | 400 | **Bad Request** Invalid Action! Ação inválida! |
| `ACR000014` | 400 | **Bad Request** Rejection Reason Needed! Necessário uma razão para a rejeição! |
| `ACR000015` | 400 | **Fee Error** Fee value can not be negative! O valor de Fee não pode ser negativo! |
| `ACR000016` | 400 | **Fee Error** Ted fixed amount fee value can not be negative! O valor de taxa fixa de TED não pode ser negativo! |
| `ACR000017` | 400 | **Fee Error** Ted percentage fee value can not be negative! O valor de taxa percentual de TED não pode ser negativo! |
| `ACR000018` | 400 | **Proposal Error** Proposal Isn't Pending Document Signature! A proposta não está com assinatura do documento pendente! |
| `ACR000019` | 400 | **Proposal Error** Proposal Isn't Pending User Agreement! A proposta não está com contrato de usuário pendente! |
| `ACR000020` | 400 | **Proposal Error** Invalid Proposal Status! Status de proposta inválido! |
| `ACR000021` | 400 | **Bad Request** Automatic transfer rule does not follow rule template: {message} A regra de transferência automática não segue o modelo de regra: {message} |
| `ACR000022` | 422 | **Unprocessable Entity** Proposal requester has incomplete configuration in billing system Solicitante da proposta possui configuração incompleta no sistema de faturamento |
| `ACR000023` | 400 | **Bad Request** Invalid Document Number {document_number} for {name}. Documento inválido {document_number} para {name}. |
| `ACR000024` | 400 | **Bad Request** Use POST account_request/{account_request_key}/generate_document |
| `ACR000025` | 400 | **Bad Request** Proposal status must be pending to get updated. O status da proposta deve estar pendente para ser atualizado. |
| `ACR000026` | 400 | **Bad Request** Could not create destination due inexistent financial code numbers: {codes_list} Não foi possível criar um destino devido a um código de instituição inexistent: {codes_list} |
| `ACR000027` | 404 | **Not Found** Requester email not found. Email do solicitante não foi encontrado. |
| `ACR000028` | 400 | **Bad Request** An operation reason is required to register fees for bankslip products Motivo da transferência é obrigatório para cadastrar tarifas para operações de boleto. |
| `ACR000029` | 400 | **Bad Request** A package value of PIX operations to not be charged fees is required Um valor para o pacote de operações PIX que não serão cobradas tarifas é obrigatório. |
| `ACR000030` | 400 | **Bad Request** Unable to process a repeated fee_configuration in the payload Não é possível processar uma configuração de tarifa repetida no payload |
| `ACR000031` | 400 | **Bad Request** Account type is not escrow. Tipo de conta não é escrow. |
| `ACR000032` | 400 | **Bad Request** Proposal {proposal_key} Account type is not checking. Proposal {proposal_key} Tipo de conta não é checking. |
| `ACR000033` | 400 | **Bad Request** Name {name} has invalid characters. O nome {name} contém caractéres inválidos. Aceitos apenas caractéres alfanuméricos e os simbolos: . / & - ’ |
| `ACR000034` | 400 | **Bad Request** It is not allowed to change account default billing configuration data. Não é permitido alterar as configurações de cobrança de tarifas desta conta. |
| `ACR000035` | 400 | **Bad Request** Account maintenance monthly fee value cannot be negative! O valor da tarifa mensal de manutenção de conta não pode ser negativo! |
| `ACR000036` | 400 | **Bad Request** At least '1' fee configuration is required for account_maintenance billing configuration data in the payload É necessária ao menos uma configuração de tarifa mensal de conta nos dados de 'billing_configuration_data' no payload |
| `ACR000037` | 400 | **Bad Request** 'billing_account_key' cannot be null 'billing_account_key' não pode ser nula |
| `ACR000038` | 400 | **Bad Request** Proposal with status pending operation issue cannot be signed Proposta com status de operação pendente de emissão não pode ser assinada |
| `ACR000039` | 400 | **Bad Request** Email is required for billing configurations paid via bank-slip Email É obrigatorio para configurações de tarifas pagas via boleto |
| `ACR000040` | 403 | **Forbidden** This user does not have permission to request account Este usuário não tem permissão para requisitar conta |
| `ACR000041` | 404 | **Account request not found** Account request not found for {account_request_key} Requisição de abertura de conta não encontrada para {account_request_key} |
| `ACR000042` | 400 | **Account request in wrong status** Account request in wrong status for conclusion Requisição de abertura de conta com status inválido para conclusão |
| `ACR000043` | 400 | **Account request is pending kyc analysis** Account request is pending kyc analysis Requisição de abertura de conta pendente de análise KYC |
| `ACR000044` | 400 | **Conflictingly ispb and code number** Conflictingly ISPB and financial_institution_code ISPB e financial_institution_code conflitantes |
| `ACR000045` | 404 | **ISPB not found** ISB not found ISPB não encontrado |
| `ACR000046` | 404 | **Account Not Found** Account not found. Conta não encontrada. |
| `ACR000047` | 403 | **Forbidden** Person is not requester of this account. Agente não é solicitante da conta. |
### BLP — Bank Slips
191 errors
| Code | HTTP | Message |
|-|-|-|
| `BLP000001` | 400 | **Bad Request** Invalid Registration Institution {registration_institution_enumerator} Instituição registradora inválida {registration_institution_enumerator} |
| `BLP000002` | 404 | **Not Found** Cannot generate empty file Não é possível gerar arquivo vazio |
| `BLP000003` | 400 | **Bad Request** Use POST /cnab/{action_type} |
| `BLP000004` | 404 | **Not Found** Bank Slip not found. Boleto não encontrado. |
| `BLP000005` | 400 | **Bad Request** Use GET /bank_slip/{bank_slip_key} or /bank_slip/person/{person_key} Use GET /bank_slip/{bank_slip_key} ou /bank_slip/person/{person_key} |
| `BLP000006` | 400 | **Bad Request** Request needs one of the following parameters: requester_profile_code, beneficiary_key A request precisa de um dos seguintes parâmetros: requester_profile_code, beneficiary_key |
| `BLP000007` | 400 | **Bad Request** Missing mandatory parameter: content_type Parâmetro obrigatório ausente: content_type |
| `BLP000008` | 400 | **Bad Request** Invalid content_type, try one of: {valid_content_types} content_type inválido, tente um dos seguintes: {valid_content_types} |
| `BLP000009` | 400 | **Bad Request** Expense already paid Despesa já paga |
| `BLP000010` | 400 | **Bad Request** Please set the expense to settle Defina a despesa para liquidar |
| `BLP000011` | 400 | **Bad Request** Missing mandatory parameter: beneficiary_key Parâmetro obrigatório ausente: beneficiary_key |
| `BLP000012` | 400 | **Bad Request** Missing mandatory parameter: digitable_line Parâmetro obrigatório ausente: digitable_line |
| `BLP000013` | 400 | **Bad Request** Please set the subject_account_key to settle Defina subject_account_key para liquidar |
| `BLP000014` | 400 | **Bad Request** Impossible to schedule or execute payment: entry already exists in database with {existing_payment_status} status. Já existe um boleto com o status {status_br}. |
| `BLP000015` | 400 | **Bad Request** Impossible to schedule payment after expiration date. Impossível agendar pagamento após data de vencimento. |
| `BLP000016` | 400 | **Bad Request** Impossible to execute payment after valid time frame. Impossível executar o pagamento para o período desejado. |
| `BLP000017` | 400 | **Bad Request** Impossible to execute or schedule payments with a total amount greater than 249,999.99 Impossível executar ou agendar pagamentos com um valor total superior a 249.999,99 |
| `BLP000018` | 400 | **Bad Request** Invalid payment calculation! Calculation model: {calculation_model}; Calculation date: {calculation_date} Cálculo de pagamento inválido! Modelo de cálculo: {calculation_model}; Data do cálculo: {calculation_date} |
| `BLP000019` | 404 | **Not Found** Payment entry not found for key {payment_key}. Pagamento não encontrada para a chave {payment_key}. |
| `BLP000020` | 400 | **Bad Request** Impossible to execute payment for payment_key {payment_key}. Payment status is not 'scheduled'. Impossível executar o pagamento para a chave de pagamento {payment_key}. Seu status é diferente de 'agendado'. |
| `BLP000021` | 400 | **Bad Request** Invalid payment: scheduled payment date is not today for key {payment_key}. Pagamento inválido: a data agendada do pagamento {payment_key} não é hoje. |
| `BLP000022` | 400 | **Bad Request** Payment date has to be from today onwards. A data do pagamento deve ser a partir de hoje. |
| `BLP000023` | 400 | **Bad Request** Payment date has to be a workday. A data do pagamento deve ser um dia útil. |
| `BLP000024` | 423 | **Locked** Operation window closed. System available from {opening_time} to {closing_time} Operação encerrada. Sistema disponível de {opening_time} a {closing_time} |
| `BLP000025` | 400 | **Bad Request** Missing mandatory parameter: {param} Parâmetro obrigatório ausente: {param} |
| `BLP000026` | 400 | **Bad Request** It's only possible to search for scheduled payments with the following status: {valid_payment_status_set}. Só é possível procurar pagamentos agendados com o seguinte status: {valid_payment_status_set}. |
| `BLP000027` | 400 | **Bad Request** It's only possible to change scheduled payment to the following status: {valid_payment_status_set}. Só é possível alterar o pagamento agendado para o seguinte status: {valid_payment_status_set}. |
| `BLP000028` | 400 | **Bad Request** Payment is not scheduled. Current payment status: {current_payment_status}. O pagamento não está agendado. Status atual do pagamento: {current_payment_status}. |
| `BLP000029` | 400 | **Bad Request** Use GET /bank_slip/{bank_slip_key}/2-way |
| `BLP000030` | 404 | **Not Found** Bank Slip beneficiary account not found. Conta do beneficiário do boleto não encontrada. |
| `BLP000031` | 404 | **Not Found** Bank Slip beneficiary not found. Beneficiário do boleto não encontrado. |
| `BLP000032` | 400 | **Bad Request** This settlement is already paid Este acordo já foi pago |
| `BLP000033` | 400 | **Bad Request** Use POST /cnab/{action_type} |
| `BLP000034` | 400 | **Bad Request** Invalid CNAB Type Tipo CNAB inválido |
| `BLP000035` | 400 | **Bad Request** Use GET /cnab_file/{person_key}/{cnab_type} |
| `BLP000036` | 404 | **Not Found** There is no CNAB File with the specified cnab_key. Não há um arquivo CNAB para a cnab_key especificada. |
| `BLP000037` | 400 | **Bad Request** Requester Profile Code Needed Código da carteira necessário |
| `BLP000038` | 404 | **Not Found** Requester Profile not found for the given requester profile code Carteira não encontrada para o código da carteira fornecido |
| `BLP000039` | 404 | **Not Found** Occurrences for submission not found Ocorrências para envio não encontradas |
| `BLP000040` | 404 | **Not Found** No Occurrence found for the given key. Ocorrências para envio não encontradas para a chave fornecida |
| `BLP000041` | 400 | **Bad Request** Use GET /cnab_temporary/{remittance_key} |
| `BLP000042` | 400 | **Bad Request** Action Type not allowed, use edit or submit Tipo de ação não permitido, use editar ou enviar |
| `BLP000043` | 400 | **Bad Request** Use PATCH /cnab_temporary/{remittance_key}/{action_type} |
| `BLP000044` | 423 | **Locked** Discharge generation can not be performed on holidays A geração de retorno não pode ser realizada nos feriados |
| `BLP000045` | 423 | **Locked** Discharge generation not ready to continue Geração de retorno não está pronta para continuar |
| `BLP000046` | 400 | **Bad Request** Use PUT /expense_configuration/{beneficiary_account_key} |
| `BLP000047` | 400 | **Bad Request** No company_key found Nenhuma company_key encontrada |
| `BLP000048` | 400 | **Bad Request** Header selected-agent is needed. O campo selected-agent do cabeçalho é necessário. |
| `BLP000049` | 400 | **Bad Request** Header selected-agent is needed. O campo selected-agent do cabeçalho é necessário. |
| `BLP000050` | 400 | **Bad Request** Found record without our_number Registro encontrado sem o nosso número |
| `BLP000051` | 400 | **Bad Request** Remitter can't be a registration institution in case of REM files. O remetente não pode ser uma instituição de registro no caso de arquivos REM. |
| `BLP000052` | 404 | **Not Found** Bank Slip for notary office payment not found Boleto para pagamento em cartório não encontrado |
| `BLP000053` | 400 | **Bad Request** File type {file_type} not implemented. Tipo de arquivo {file_type} não implementado. |
| `BLP000055` | 404 | **Not Found** Bank SLip for protest not found Nenhum boleto para protesto encontrado |
| `BLP000056` | 400 | **Bad Request** Use POST /requester_configuration |
| `BLP000057` | 404 | **Not Found** Requester Profile not found. Carteira não encontrada. |
| `BLP000058` | 400 | **Bad Request** Missing mandatory parameter: person_key Parâmetro obrigatório ausente: person_key |
| `BLP000059` | 400 | **Bad Request** Use POST /requester_profile/{requester_profile_key} |
| `BLP000060` | 404 | **Not Found** Account not found for person key {person_key}. Conta não encontrada para a chave {person_key}. |
| `BLP000061` | 400 | **Bad Request** Range already used Intervalo já usado |
| `BLP000062` | 400 | **Bad Request** Use POST /requester_profile_range |
| `BLP000064` | 400 | **Bad Request** Missing Registration Institution config Falta REGISTRATION_INSTITUTION_CONFIG |
| `BLP000065` | 422 | **Pub Sub Ocurrence Error** Invalid CNAB file occurrence order. Ordem de ocorrência de arquivo CNAB inválida. |
| `BLP000066` | 400 | **Bad Request** Occurrence type {occurrence_type} not supported Tipo de ocorrência {occurrence_type} não suportado |
| `BLP000067` | 400 | **Bad Request** Errors found on return CNAB File: {occurrence_sequence} Erros encontrados no arquivo CNAB de retorno: {occurrence_sequence} |
| `BLP000068` | 400 | **Bad Request** File: {filename}. Error: {error} Arquivo: {filename}. Erro: {error} |
| `BLP000069` | 400 | **Bad Request - CNAB ERROR** Empty or corrupted file. Arquivo vazio ou corrompido. |
| `BLP000070` | 400 | **Bad Request - CNAB ERROR** Could not find the CNAB type. Não foi possível identificar o tipo de arquivo CNAB enviado. |
| `BLP000071` | 400 | **Bad Request - CNAB ERROR** CNAB version not supported yet. Versão de CNAB não suportada. |
| `BLP000072` | 400 | **Bad Request - CNAB ERROR** Registry line size incorrect. Linha de registro com tamanho incorreto. |
| `BLP000073` | 400 | **Bad Request - CNAB ERROR** Could not determine Bank Code. Não foi possível determinar o código do banco operador |
| `BLP000074` | 400 | **Bad Request - CNAB ERROR** Could not determine CNAB version. Não foi possível determinar a versão do CNAB. |
| `BLP000075` | 400 | **Bad Request - CNAB ERROR** Could not determine CNAB type (Remittance / Discharge). Não foi possível determinar o tipo do CNAB (Remessa / Retorno). |
| `BLP000076` | 400 | **Bad Request - CNAB ERROR** Invalid CNAB type, must be Remittance(1) or Discharge(2). Tipo de arquivo incorreto, deve ser Remessa(1) ou Retorno(2). |
| `BLP000077` | 400 | **Bad Request - CNAB ERROR** CNAB translator not implemented yet for the type sent. Tradutor de CNAB não implementado para o tipo enviado. |
| `BLP000078` | 400 | **Bad Request - CNAB ERROR** Could not set the field. Não foi possível ler o campo. |
| `BLP000079` | 400 | **Bad Request - CNAB ERROR** Max field size exceeded. Número máximo de dígitos excedido para o campo. |
| `BLP000080` | 400 | **Bad Request - CNAB ERROR** Value type incorrect. Tipo de valor incorreto. |
| `BLP000081` | 400 | **Bad Request - CNAB ERROR** Wrong number of decimal places. Número de casas decimais incorreto. |
| `BLP000082` | 400 | **Bad Request - CNAB ERROR** Wrong header record position in file. Linha de Registro Header colocado na posição incorreta. |
| `BLP000083` | 400 | **Bad Request - CNAB ERROR** Wrong cnab record sequence. Sequência de registros incorreta no arquivo. |
| `BLP000084` | 400 | **Bad Request - CNAB ERROR** Wrong trailer record position in file. Linha de Registro trailer colocado na posição incorreta. |
| `BLP000085` | 400 | **Bad Request - CNAB ERROR** Record type not supported. Tipo de registro não suportado. |
| `BLP000086` | 400 | **Bad Request - CNAB ERROR** Asset type not supported. Espécie de Título não suportada. |
| `BLP000087` | 400 | **Bad Request - CNAB ERROR** Occurrence not supported. Tipo de ocorrência não suportada. |
| `BLP000088` | 400 | **Bad Request - CNAB ERROR** Remittance sequence number invalid or in use. Número sequencial de remessa inválido ou em uso. |
| `BLP000089` | 400 | **Bad Request - CNAB ERROR** Invalid Remittance filename. Nome do arquivo de remessa inválido. |
| `BLP000090` | 400 | **Bad Request - CNAB ERROR** Invalid record sequence or not sequential. Número sequencial de registro inválido ou não sequencial. |
| `BLP000091` | 400 | **Bad Request - CNAB ERROR** Max Number of Discharges reached. Número máximo de retornos gerados alcançado. |
| `BLP000094` | 400 | **Bad Request - CNAB ERROR** Duplicated Remittance filename. Nome do arquivo de remessa duplicado. |
| `BLP000097` | 400 | **Bad Request - CNAB ERROR** Could not determine bank name. Não foi possível determinar o nome do banco. |
| `BLP000098` | 400 | **Bad Request - CNAB ERROR** Requester profile not found: {requester_profiles}. Check CNAB field beneficiary identification (positions 21 to 37) Carteira não encontrada: {requester_profiles}. Verifique o campo Identificação da Empresa Beneficiária (posições 21 a 37) |
| `BLP000099` | 400 | **Bad Request - CNAB ERROR** Max Number of Remittances reached. Número máximo de remessas alcançado. |
| `BLP000100` | 400 | **Bad Request - CNAB ERROR** Not supported occurrence type. Tipo de ocorrência não suportado. |
| `BLP000102` | 400 | **Bad Request** Request needs at least one of the following parameters: barcode, digitable_line A Request precisa de pelo menos um dos seguintes parâmetros: barcode, digitable_line |
| `BLP000103` | 400 | **Bad Request** Keys must not be empty Lista de chaves não pode ser vazia |
| `BLP000104` | 400 | **Bad Request** CIP registration not valid please try again in a few minutes Registro na CIP inválido, por favor tente novamente daqui alguns minutos |
| `BLP000105` | 400 | **Bad Request** A SELECTED_AGENT must be provided SELECTED_AGENT deve ser fornecido |
| `BLP000106` | 400 | **Bad Request** Use PATCH /expense_configuration/{requester_profile_key} |
| `BLP000107` | 400 | **Bad Request** Invalid bank teller instruction, occurrence {occurrence_sequence} Mensagem para o boleto inválida, ocorrência {occurrence_sequence} |
| `BLP000108` | 400 | **Bad Request** Use GET expense?subject_account_key={account_key} |
| `BLP000109` | 404 | **Not Found** Cnab not found for the given key {cnab_key} Cnab não encontrado para a chave {cnab_key}. |
| `BLP000110` | 422 | **Unprocessable Entity** Duplicate our number {our_number}, occurrence sequence {occurrence_sequence} Nosso número {our_number} duplicado, ordem da ocorrência {occurrence_sequence} |
| `BLP000111` | 422 | **Unprocessable Entity** Invalid our number {our_number} for requester profile code {requester_profile_code}, occurrence sequence {occurrence_sequence} Nosso número {our_number} inválido para código de carteira {requester_profile_code}, ordem da ocorrência {occurrence_sequence} |
| `BLP000112` | 422 | **Unprocessable Entity** Rejected Remittance Remessa Rejeitada |
| `BLP000113` | 422 | **Unprocessable Entity** Bank Code not sent, occurrence sequence {occurrence_sequence} Código do banco não enviado, ordem da ocorrência {occurrence_sequence} |
| `BLP000114` | 422 | **Unprocessable Entity** Payment branch not sent, occurrence sequence {occurrence_sequence} Agência não enviada, ordem da ocorrência {occurrence_sequence} |
| `BLP000115` | 422 | **Unprocessable Entity** Payment Credit Date not sent, occurrence sequence {occurrence_sequence} Data de Pagamento não enviada, ordem da ocorrência {occurrence_sequence} |
| `BLP000116` | 422 | **Unprocessable Entity** Invalid digitable line: {digitable_line} Linha digitável inválida: {digitable_line} |
| `BLP000117` | 400 | **Bad Request** This requester profile has {bank_slips_count} open bank slips. You cannot deactivate this profile. A carteira selecionada possui {bank_slips_count} boletos em aberto. Não é possível desativar esta carteira. |
| `BLP000118` | 422 | **Unprocessable Entity** Blocked or closed requester profile can not register new bank slips, occurrence sequence {occurrence_sequence} Carteira bloqueada ou fechada não pode registrar novos boletos , ordem da ocorrência {occurrence_sequence} |
| `BLP000119` | 400 | **Bad Request** Closed requester profile can not register new occurrences Carteiras fechadas não podem gerar novas ocorrências |
| `BLP000120` | 400 | **Bad Request** Unable to read CNAB file. Check file data for special characters at line {line} and position {position} Não foi possível ler o CNAB devido presença de caracteres especiais na linha {line} e posição {position} do arquivo. |
| `BLP000121` | 404 | **Not Found** Not Found bank Slip to generate permanency expense Boletos não encontrados para gerar tarifa de permanência |
| `BLP000122` | 404 | **Not Found** Not Found bank Slip to generate write off term Boletos não encontrados para gerar baixa por decurso de prazo |
| `BLP000123` | 400 | **Bad Request** CNAB file with more than one requester profile (positions 021 a 037). Arquivo CNAB com mais de uma carteira (posições 021 a 037). |
| `BLP000124` | 400 | **Bad Request** Missing mandatory parameter: requester_profile_key Parâmetro obrigatório ausente: requester_profile_key |
| `BLP000125` | 404 | **Not Found** No bankslips with notifications to be sent found Nenhum boleto com notificações a serem enviadas foi encontrado |
| `BLP000126` | 400 | **Bad Request** Invalid file type. Logo upload should be a .png image type Tipo de arquivo inválido. O upload do logo deve ser uma imagem .png |
| `BLP000127` | 400 | **Bad Request** Invalid image width. Logo image width should be 300px max. Largura inválida. A largura máxima do logo deve ser 300px. |
| `BLP000128` | 400 | **Bad Request** Invalid image height. Logo image height should be 100px max. Altura inválida. A altura máxima do logo deve ser 100px. |
| `BLP000129` | 400 | **Bad Request** Invalid image orientation. Logo image orientation should be landscape and not portrait/square Orientação inválida. A orientação do logo deve ser paisagem e não retrato/quadrado |
| `BLP000130` | 400 | **Bad Request** Missing file. Falta o arquivo. |
| `BLP000131` | 400 | **Bad Request** Request without occurrences. Request sem ocorrências. |
| `BLP000132` | 403 | **Unauthorized** Occurrence type is not allowed. Occurrence type não permitida. |
| `BLP000134` | 422 | **Unprocessable Entity** Our duplicate number, {our_number} Nosso número duplicado, {our_number} |
| `BLP000135` | 422 | **Unprocessable Entity** The field Identification of the Beneficiary Institution {beneficiary_code} on the registration lines (positions 021 to 037) is different from the beneficiary company identification {company_code} in the header (positions 027 to 046). O campo Identificação da Empresa Beneficiária {beneficiary_code} nas linhas de registro (posições 021 a 037) é diferente da identificação da empresa beneficiária {company_code} no cabeçalho (posições 027 a 046). |
| `BLP000136` | 400 | **Invalid FileName** Invalid filename ({cnab_filename}). Please do not use specials characters like '!,@,(,),$' . Nome de arquivo inválido ({cnab_filename}). Favor não utilizar caracteres especiais como '!,@,(,),$' . |
| `BLP000137` | 400 | **Bad Request** Invalid barcode length ({barcode_length}). Barcode must be 44 digits. Tamanho inválido do código de barras. Código de barras deve possuir 44 dígitos. |
| `BLP000138` | 404 | **Not Found** Bank Slip for automatic write-off not found Nenhum boleto para baixa automática encontrado |
| `BLP000139` | 404 | **Not Found** Notification configuration not found for the given parameters. Não foi possível encontrar a configuração de notificação para os parâmetros enviados. |
| `BLP000140` | 400 | **Bad Request** The given CNAB filename is too long to be saved in our database. O nome do arquivo CNAB é muito longo para ser salvo no nosso Banco de Dados. |
| `BLP000141` | 400 | **Bad Request** The given digitable_line must have only numbers. A linha digitável fornecida deve conter somente números. |
| `BLP000142` | 400 | **Bad Request** This digitable line is out of minimum or maximum length. Esta linha digitável está fora do comprimento mínimo ou máximo. |
| `BLP000143` | 404 | **Not Found** Account not found for key {account_key}. Conta não encontrada para a chave {account_key}. |
| `BLP000144` | 400 | **Bad Request** This digitable line is not accepted. Essa linha digitável não é aceita. |
| `BLP000145` | 400 | **Bad Request** Cannot generate PDF from a rejected bank slip. Não é possível gerar PDF a partir de um boleto bancário rejeitado. |
| `BLP000146` | 400 | **Bad Request** Payment rejected. Pagamento rejeitado. |
| `BLP000147` | 400 | **Bad Request** To enable QR Code a valid defaul pix key must be send. Para habilitar o QR Code uma chave pix padrão válida deve ser enviada. |
| `BLP000148` | 400 | **Bad Request** Beneficiary account and pix key must match. Conta beneficiária deve ser a mesma da chave pix. |
| `BLP000149` | 400 | **Bad Request** Requester Profile {requester_profile_key} must be active. Carteira {requester_profile_key} deve estar ativa. |
| `BLP000150` | 400 | **Bad Request** Wrong Date format. Format must be YYYY-MM-DD. Formato de data incorreto, Dever ser do tipo YYYY-MM-DD. |
| `BLP000151` | 400 | **Bad Request** Protest expense must be percentage. Custas de cartório deven ser em porcentagem. |
| `BLP000152` | 400 | **Bad Request** Requester Profile Code {requester_profile_code} already in use Código de carteira {requester_profile_code} |
| `BLP000153` | 400 | **Bad Request** {filter_param} must have min length of {min_length} {filter_param} deve ter tamanho mínimo de {min_length} |
| `BLP000154` | 422 | **Unprocessable Entity** Error paying tax collection: {message} Erro ao realizar pagamento de arrecadação: {message} |
| `BLP000155` | 402 | **Bad Request** Not enough funds for bank-slip payment Fundos insuficientes para pagamento de boleto |
| `BLP000156` | 400 | **Bad Request** Use GET /cnab_file/return/{cnab_type}/{requester_profile_code} |
| `BLP000157` | 400 | **Bad Request** Missing mandatory parameter: cnab_type Parâmetro obrigatório ausente: cnab_type |
| `BLP000158` | 400 | **Bad Request** Remitter key must be provided. Please send SELECTED-AGENT or make an internal request Chave de emissor de remessa deve ser fornecida. Por favor envie um SELECTED-AGENT ou faça uma requisição interna |
| `BLP000159` | 412 | **Bad Request** Error generating {file_type}, user with document {document_number} does not have a registered address! Erro ao gerar {file_type}, usuário com o documento {document_number} não possui endereço cadastrado! |
| `BLP000160` | 422 | **Unprocessable Entity** Expiration date cannot be after 2049-10-13 Data de vencimento não pode ser depois de 2049-10-13 |
| `BLP000161` | 400 | **Bad Request** Interest Daily Value must match format 9999999.99 Juros diário deve estar no formato 9999999.99 |
| `BLP000162` | 400 | **Bad Request** Fine Percentage Value must match format 9999999.99 Valor multa deve estar no formato 9999999.99 |
| `BLP000163` | 400 | **Bad Request** Discount Value must match format 9999999.99 Valor de Desconto diário deve estar no formato 9999999.99 |
| `BLP000164` | 404 | **Not Found** Payment entry not found for barcode {barcode}. Pagamento não encontrada para o código de barras {barcode}. |
| `BLP000165` | 400 | **Bad Request** Payment is not paid. Current payment status: {current_payment_status}. O pagamento não está pago. Status atual do pagamento: {current_payment_status}. |
| `BLP000166` | 400 | **Bad Request** Failed to cancel payment in PCR. Barcode: {barcode}. Falha ao cancelar pagamento no PCR. Código de barras: {barcode}. |
| `BLP000167` | 400 | **Bad Request** Requester max_payment_days must be an integer no greater than 360 and must not be 0. A configuração max_payment_days da carteira deve ser um número inteiro igual ou menor a 360 e diferente de 0 |
| `BLP000168` | 400 | **Bad Request** Bank slip is not does not have a payment notice. Current bank slip status: {bank_slip_status}. O boleto não está com aviso de pagamento. Status atual do boleto: {bank_slip_status}. |
| `BLP000169` | 400 | **Bad Request** Bank slip does not have a confirmed payment notice occurrence. O boleto não possui uma ocorrência de aviso de pagamento confirmada. |
| `BLP000170` | 400 | **Bad Request** If override_automatic_bankruptcy_protest_settings is true, bankruptcy protest settings must be filled. Se sobreescrever configurações de interesse estiver ativado, as suas configurações devem ser preenchidas. |
| `BLP000171` | 400 | **Bad Request** If override_fine_settings is true, bankruptcy protest settings must be filled. Se sobreescrever configurações de multa estiver ativado, as suas configurações devem ser preenchidas. |
| `BLP000172` | 400 | **Bad Request** If override_automatic_write_off_settings is true, bankruptcy protest settings must be filled. Se sobreescrever configurações de baixa automática estiver ativado, as suas configurações devem ser preenchidas. |
| `BLP000173` | 400 | **Bad Request** If override_automatic_bankruptcy_protest_settings is true, bankruptcy protest settings must be filled. Se sobreescrever configurações de protesto por falência estiver ativado, as suas configurações devem ser preenchidas. |
| `BLP000174` | 400 | **Bad Request** If override_automatic_protest_settings is true, protest settings must be filled. Se sobreescrever configurações de protesto estiver ativado, as suas configurações devem ser preenchidas. |
| `BLP000175` | 400 | **Bad Request** If override_printing_policy_settings is true, printing policy settings must be filled. Se sobreescrever configurações de política de impressão estiver ativado, as suas configurações devem ser preenchidas. |
| `BLP000176` | 400 | **Bad Request** Failed to consult payment in PCR. Barcode: {barcode}. Falha ao consultar pagamento no PCR. Código de barras: {barcode}. |
| `BLP000177` | 400 | **Bad Request** Purpose not allowed. Propósito não permitido. |
| `BLP000178` | 400 | **Bad Request** It's not possible to schedule payments for tax collection Não é possível agendar pagamentos para arrecadação |
| `BLP000179` | 400 | **Bad Request** Payment date can't be before today. Data de pagamento não pode ser anterior a data de hoje. |
| `BLP000180` | 400 | **Bad Request** Invalid purpose. Propósito inválido . |
| `BLP000181` | 400 | **Bad Request** Invalid guarantor document. Documento inválido. |
| `BLP000182` | 400 | **Bad Request** Invalid expiration date. Data de validade inválida. |
| `BLP000183` | 400 | **Bad Request** Invalid character in line {line}. Caracter inválido na linha {line}. |
| `BLP000184` | 501 | **Not Implemented** Resource only available in sandbox Recurso disponível apenas em sandbox |
| `BLP000185` | 400 | **Invalid Qr Code Type** The Qr Code payload given did not provide a proper Qr Code type O payload de QR Code fornecido não contêm um tipo de Qr Code Válido |
| `BLP000186` | 400 | **Invalid Qr Code Format** The Qr Code format is invalid O formato do Qr Code é inválido |
| `BLP000187` | 404 | **Not Found** Payment entry not found for digitable line {digitable_line}. Pagamento não encontrada para a linha digitável {digitable_line}. |
| `BLP000188` | 400 | **Bad Request** It was not possible to consult the bank slip at this time. Please try again in a few minutes. Não foi possível consultar o boleto neste momento. Por favor, tente novamente em alguns minutos. |
| `BLP000189` | 400 | **Bad Request** There was a problem processing the payment. Please verify your information and, if necessary, contact us for assistance. Houve um problema ao processar o pagamento. Por favor, verifique suas informações e, se necessário, entre em contato conosco para obter assistência. |
| `BLP000190` | 400 | **Bad Request** Settlement cycle not found Ciclo de liquidação não encontrado |
| `BLP000191` | 400 | **Bad Request** Temporary unavalilable Temporariamente indisponível |
| `BLP000192` | 400 | **Bad Request** Cnab profile output in progress for requester_profile_code Genaração de cnab para a carteira em progresso |
| `BLP000193` | 422 | **Unprocessable Entity** Requester profile {requester_profile_code} is locked by other action, please try again later. Carteira {requester_profile_code} está bloqueada por outra ação, por favor tente novamente mais tarde. |
| `BLP000194` | 400 | **Bad Request** Field requester_key is required in the request body. O campo requester_key é obrigatório no corpo da requisição. |
| `BLP000195` | 400 | **Bad Request** Bank slip settlement type must be informed. O tipo de liquidação do boleto deve ser informado. |
| `BLP000196` | 400 | **Bad Request** Invalid guarantor name. Nome do sacador avalista inválido. |
| `BLP000197` | 400 | **Bad Request** Beneficiary account is not opened Conta beneficiária não está aberta |
| `BLP000198` | 400 | **Bad Request** Multiple payment entries found for barcode {barcode}. Múltiplas entradas de pagamento encontradas para o código de barras {barcode}. |
| `BLP000199` | 400 | **Bad Request** Bank slip payment total amount is different from the returned amount. O valor total do pagamento do boleto é diferente do valor retornado. |
### GDF — Platform
28 errors
| Code | HTTP | Message |
|-|-|-|
| `GDF000001` | 403 | **Permission Validation Error** Only master user's are allowed Somente usuários master são permitidos |
| `GDF000002` | 403 | **Permission Validation Error** A SELECTED-AGENT must be provided Um SELECTED-AGENT deve ser fornecido |
| `GDF000003` | 400 | **Bad Request** No API Client Key received Nenhuma chave de API do cliente recebida |
| `GDF000004` | 400 | **Bad Request** Empty body received Corpo da request vazio |
| `GDF000005` | 400 | **Bad Request** API Client already created for this person_key Cliente da API já criado para esta person_key |
| `GDF000006` | 400 | **Bad Request** Duplicated allowed_endpoint provided allowed_endpoint duplicado |
| `GDF000007` | 404 | **Not Found** No ClientIntegration found for client_integration_key: {client_integration_key} . Nenhuma ClientIntegration encontrada para client_integration_key: {client_integration_key}. |
| `GDF000008` | 400 | **Bad Request** A client_integration_key must be provided Uma client_integration_key deve ser fornecida |
| `GDF000009` | 400 | **Bad Request** A action must be provided Uma ação deve ser fornecida |
| `GDF000010` | 400 | **Bad Request** Action doesnt exist ({action_name}). Ação não existe ({action_name}). |
| `GDF000011` | 404 | **Not Found** No ClientIntegration found for client_integration_key / allowed_endpoint_key: {client_integration_key} / {allowed_endpoint_key}. Nenhuma ClientIntegration encontrada para client_integration_key / allowed_endpoint_key: {client_integration_key} / {allowed_endpoint_key}. |
| `GDF000012` | 404 | **Not Found** No AllowedEndpoint found for client_integration_key / allowed_endpoint_key: {client_integration_key} / {allowed_endpoint_key}. Nenhuma AllowedEndpoint encontrada para client_integration_key / allowed_endpoint_key: {client_integration_key} / {allowed_endpoint_key}. |
| `GDF000013` | 400 | **Bad Request** A allowed_endpoint_key must be provided Uma chave allowed_endpoint_key deve ser fornecida |
| `GDF000014` | 401 | **QI Unauthenticated** Please provide valid credentials as part of the request. (Documentation: https://docs.qitech.com.br) Details: {details} Por favor forneça credenciais válidas como parte da request. (Documentação: https://docs.qitech.com.br) Detalhes: {details_br} |
| `GDF000015` | 400 | **Bad Request** Please provide a valid client_public_key Por favor forneça uma chave pública válida |
| `GDF000016` | 400 | **Bad Request** Error while decoding request's JSON body. Please verify if body is valid. Details: {json_ex} Erro ao decodificar o JSON do corpo da requisição. Por favor verifique se o corpo é válido. Detalhes: {json_ex} |
| `GDF000017` | 400 | **Bad Request** Invalid Value ({info}). Valor inválido ({info}). |
| `GDF000018` | 404 | **Not Found** No ClientIntegration found for api_client_key: {api_client_key}. Nenhuma ClientIntegration encontrada para api_client_key: {api_client_key}. |
| `GDF000019` | 400 | **Bad Request** Informed request_type: '{request_type}' has not been mapped yet. Mapeamento ainda inexistente para request_type: '{request_type}'. |
| `GDF000020` | 500 | **Internal Error** Account Key can't be null when including pix key. Account Key não pode ser nulo quando solicitar uma inclusão de chave. |
| `GDF000021` | 500 | **Internal Error** Failed to request SCR authorization. Falha na requisição para autorização de SCR. |
| `GDF000022` | 400 | **Bad Request** Informed request_type: '{request_type}' has not been mapped yet. Mapeamento ainda inexistente para request_type: '{request_type}'. |
| `GDF000023` | 401 | **Unauthorized** Error na verificação SSL SSL validation error |
| `GDF000024` | 400 | **Bad Request** Error no endpoint de webhook do cliente Error at client webhook endpoint |
| `GDF000025` | 403 | **Permission Validation Error** Only sandbox and dev environment are allowed to request Mock API Somente os ambientes de desenvolvimento e de sandbox são permitidos para realizar requisições na Mock API. |
| `GDF000026` | 400 | **Bad Request** Signature method version not allowed Versão do método de assinatura não permitida |
| `GDF000027` | 404 | **Not Found** No ClientIntegration found for person_key: {person_key}. Nenhuma ClientIntegration encontrada para a person_key: {person_key}. |
| `GDF000028` | 404 | **Not Found** The request needs a body, even an empty one like: '{}'. A requisição precisa de um body, mesmo que um vazio como: '{}'. |
### OBD — Onboarding
88 errors
| Code | HTTP | Message |
|-|-|-|
| `OBD000001` | 400 | **Bad Request** Use DELETE /bank_account/{bank_account_key} with a valid agent Use DELETE /bank_account/{bank_account_key} com um agente válido |
| `OBD000002` | 404 | **Not Found** Bank account not found Conta não encontrada |
| `OBD000003` | 400 | **Bad Request** Use POST /bank_account/ with a valid agent Use POST /bank_account/ com um agente válido |
| `OBD000004` | 404 | **Not Found** There is no person with document number {document_number} Não existe pessoa com número de documento {document_number} |
| `OBD000005` | 400 | **Bad Request** Use GET /cnae/{cnae_code} |
| `OBD000006` | 400 | **Bad Request** Cnae code must be without special characters and must have 7 digits O código Cnae deve ter 7 dígitos e não conter caracteres especiais |
| `OBD000007` | 404 | **Not Found** Cnae was not found. Cnae não encontrado. |
| `OBD000008` | 404 | **Not Found** Owner Person not found. Proprietário (owner_person) não encontrado. |
| `OBD000009` | 404 | **Not Found** Draft person not found for {name} Draft person não encontrada para {name} |
| `OBD000010` | 400 | **Bad Request** Fund already exists, please use PUT /fund/{fund_key}. O fundo já existe, use PUT /fund/{fund_key}. |
| `OBD000011` | 400 | **Bad Request** Custodian Person not found. custodian_person não encontrado. |
| `OBD000012` | 400 | **Bad Request** Custodian Person sent is not a custodian. custodian_person não é válido. |
| `OBD000013` | 400 | **Bad Request** Administrator Person not found. Administrador não encontrado |
| `OBD000014` | 400 | **Bad Request** Administrator Person sent is not a administrator. administrador_person não é um administrador. |
| `OBD000015` | 400 | **Bad Request** Fund not found. Fundo não encontrado. |
| `OBD000016` | 400 | **Bad Request** Fund document_number sent must match an existing fund. Sent: {fund_document_number}. O número do documento do fundo enviado deve corresponder a um fundo existente. Enviado: {fund_document_number}. |
| `OBD000017` | 400 | **Bad Request** Fund document_number sent must match existing fund. Sent: {fund_document_number}. Expected: {document_number}. O número do documento do fundo enviado deve corresponder ao fundo existente. Enviado: {fund_document_number}. Experado: {document_number}. |
| `OBD000018` | 400 | **Bad Request** Person already has {qualification_enum} qualification. A pessoa já tem qualificação {qualification_enum}. |
| `OBD000019` | 404 | **Not Found** Person not found Pessoa não encontrada. |
| `OBD000020` | 404 | **Not Found** Company or Agent not found Empresa ou agente não encontrado |
| `OBD000021` | 400 | **Bad Request** Use GET /person/(person_document) or /person?document_number?(document_number) Use GET /person/(person_document) ou /person?document_number?(document_number) |
| `OBD000022` | 400 | **Bad Request** Duplicated document/email E-mail ou documento duplicado |
| `OBD000023` | 500 | **Internal Error** Error creating user:{document_number}. Fail to send welcome email Erro ao criar usuário: {document_number}. Falha ao enviar email de boas-vindas |
| `OBD000024` | 404 | **Not Found** POST Agent Not Found Agente não encontrado |
| `OBD000025` | 400 | **Bad Request** First document must be CPF or CNPJ Documento deve ser CPF ou CNPJ |
| `OBD000026` | 400 | **Bad Request** Use POST /person |
| `OBD000027` | 400 | **Bad Request** Conflict with person key and person type Conflito com chave e tipo de pessoa |
| `OBD000028` | 400 | **Bad Request** Use PATCH /person/{person_key} |
| `OBD000029` | 400 | **Bad Request** Use GET /person_qualification/{qualification} |
| `OBD000030` | 400 | **Bad Request** Use PUT /person_qualification |
| `OBD000031` | 400 | **Bad Request** Person does not have {qualification_enum} qualification. A pessoa não tem qualificação {qualification_enum}. |
| `OBD000032` | 400 | **Bad Request** Use DELETE /person_qualification |
| `OBD000033` | 400 | **Bad Request** Natural person not found Pessoa física não encontrada |
| `OBD000034` | 400 | **Bad Request** Legal person not found Pessoa jurídica não encontrada |
| `OBD000035` | 400 | **Bad Request** Professional data already exists Dados profissionais já existem |
| `OBD000036` | 400 | **Bad Request** Professional data not found Dados profissionais não encontrados |
| `OBD000037` | 400 | **Bad Request** Use POST /professional_data |
| `OBD000038` | 400 | **Bad Request** You cannot remove yourself Você não pode se remover |
| `OBD000039` | 400 | **Bad Request** Missing attribute person_key in request body Atributo person_key ausente no corpo da request |
| `OBD000040` | 400 | **Bad Request** You must provide a name. Você deve fornecer um nome. |
| `OBD000041` | 400 | **Bad Request** You must provide a name and a document number to do the PEP check. Você deve fornecer um nome e um número de documento para fazer a verificação do PEP. |
| `OBD000042` | 500 | **Internal Error** KeyCloak did not returned location header KeyCloak não retornou o cabeçalho do local |
| `OBD000043` | 400 | **Bad Request** Qualification does not exist Qualificação não existe |
| `OBD000044` | 400 | **Bad Request** Could not find either legal nor natural person Pessoa fisica ou juridica nao encontradas. |
| `OBD000045` | 400 | **Bad Request** Missing attribute owner_person_key Atributo owner_person_key ausente |
| `OBD000046` | 400 | **Bad Request** Professional data is not active Professional data não está ativo |
| `OBD000047` | 403 | **Unauthorized** User does not have permission to add or modify users to this person Usuário não tem permissão para adicionar ou modificar usuários |
| `OBD000048` | 400 | **Bad Request** Client Key must be provided. A chave de usuário deve ser enviada. |
| `OBD000049` | 404 | **Bad Request** Client not found. Client não encontrado |
| `OBD000050` | 400 | **Bad Request** Parameter client_key not allowed no POST method Parâmetro client_key não permitido no método POST |
| `OBD000051` | 400 | **Bad Request** Person is not active Person não está ativa |
| `OBD000052` | 400 | **Bad Request** document_type: {document_type} not allowed for {person_type} person document_type: {document_type} não permitido para person {person_type} |
| `OBD000053` | 400 | **Bad Request** Wrong document_type: {document_type} used in document: {document_field_name} document_type: {document_type} incorreto utilizado no documento: {document_field_name} |
| `OBD000054` | 400 | **Bad Request** Client already registered for document_number: {document_number}. Use PATCH method to update a client Cliente já registrado para o document_number: {document_number}. use o método PATCH para atualizar um cliente |
| `OBD000055` | 404 | **Bad Request** Can not find any result for search parameters Não foi possíel encontrar nenhum resultado com os parâmetros eviados. |
| `OBD000056` | 403 | **Unauthorized** User does not have permission to add or modify clients to this person Usuário não tem permissão para adicionar ou modificar clientes |
| `OBD000057` | 403 | **Bad Request** Client {document_number} is blocked, please contact support. O cliente {document_number} está bloqueado, favor contactar o suporte. |
| `OBD000058` | 403 | **Bad Request** Action not implemented. Ação não implementada. |
| `OBD000059` | 400 | **Bad Request** Duplicated document_key on company representative with document_number: {document_number} document_key duplicada no company representative com document_number: {document_number} |
| `OBD000060` | 400 | **Bad Request** Duplicated company_representative received company_representative duplicado recebido |
| `OBD000061` | 400 | **Bad Request** Duplicated document_key on client's attached_documents document_key duplicada nos attached_documents do client |
| `OBD000062` | 400 | **Bad Request** order_by filter must be one of: {order_by_list} filtro order_by permitido para os seguintes valores: {order_by_list} |
| `OBD000063` | 401 | **Unauthorized** password reset not authorized out of app reset de senha não autorizado fora do app |
| `OBD000064` | 400 | **Bad Request** professional data is already active professional data já está ativo |
| `OBD000065` | 400 | **Bad Request** You must provide an email. Você deve fornecer um email. |
| `OBD000066` | 412 | **Precondition Failed** OwnerPerson must be in the QI SCD Domain. OwnerPerson deve pertencer ao Domain da QI SCD |
| `OBD000067` | 400 | **Bad Request** Domain already exists for owner person. Domínio já existe para OwnerPerson. |
| `OBD000068` | 404 | **Not Found** Domain not found Domínio não encontrado. |
| `OBD000069` | 400 | **Bad Request** Only legal person may own domains. Apenas pessoas jurídicas podem ter domínios. |
| `OBD000070` | 400 | **Bad Request** Wrong type for {variable}. Must be {type} Tipo errado para {variable}. Deve ser {type} |
| `OBD000071` | 400 | **Bad Request** You must provide an email or a phone number. Você deve fornecer um email ou um número de telefone. |
| `OBD000072` | 400 | **Bad Request** Use either owner_person_key or domain_key in search. Use owner_person_key ou domain_key na busca. |
| `OBD000073` | 403 | **Unauthorized** User does not have permission to add or modify persons to this domain Usuário não tem permissão para adicionar ou modificar pessoas a este domínio. |
| `OBD000075` | 400 | **Bad Request** Natural and legal person must be in the same domain. Pessoas físicas e jurídicas deves pertencer ao mesmo domínio. |
| `OBD000076` | 400 | **Bad Request** A professional_data_key must be provided. Uma professional_data_key deve ser fornecida. |
| `OBD000077` | 400 | **Bad Request** Invalid legal person role sent {role}. Permissão inválida para pessoa juurídica, enviado {role} |
| `OBD000078` | 400 | **Bad Request** There must always be an account administrator left Sempre deve existir ao menos um administrador de conta |
| `OBD000079` | 400 | **Bad Request** Endpoint used for natural person updates only Endpoint utilizado apenas para atualizações de pessoas fisicas |
| `OBD000080` | 400 | **Bad Request** Invalid phone number Número de telefone inválido |
| `OBD000081` | 400 | **Bad Request** Invalid e-mail E-mail inválido |
| `OBD000082` | 400 | **Bad Request** Natural person does not have allowed users. Pessoa física não possui usuários autorizados. |
| `OBD000083` | 404 | **Not found** Professional data not found. Dados proficionais não encontrados. |
| `OBD000084` | 400 | **Bad Request** The openfinance user is already validated. O usuário open finance já foi validado. |
| `OBD000085` | 400 | **Bad Request** Method only allowed for domain users. Método permitido apenas para usuários de domain. |
| `OBD000086` | 400 | **Bad Request** Reproved person data. Dados recusados. |
| `OBD000087` | 400 | **Requester Configuration Already Exists** Requester Configuration already exists for this requester_key. Requester Configuration já existe para essa requester_key. |
| `OBD000088` | 400 | **Invalid Requester Configuration Info** The configuration format sent is not valid. O formato de configuração enviado não é válido. |
| `OBD000089` | 404 | **Requester Configuration not found** There is no Requester Configuration attributed to requester_key given Não há Requester Configuration para a requester_key enviada |
### PMB — Pombo
34 errors
| Code | HTTP | Message |
|-|-|-|
| `PMB000001` | 403 | **Permission Validator Error** Only master user's are allowed Somente usuários master estão autorizados |
| `PMB000002` | 403 | **Permission Validator Error** A SELECTED-AGENT must be provided Um SELECTED-AGENT deve ser fornecido |
| `PMB000003` | 404 | **Not Found** No callback found for callback_key: {callback_key} . Nenhum callback encontrado para callback_key: {callback_key}. |
| `PMB000004` | 400 | **Bad Request** The requested event_type ({callback_event_name}) does not exists. O event_type solicitado ({callback_event_name}) não existe. |
| `PMB000005` | 400 | **Bad Request** Unable to perform retry action with current callback_status ({callback_status_enumerator}) Não foi possível executar a ação de nova tentativa com o callback_status atual ({callback_status_enumerator}) |
| `PMB000006` | 400 | **Bad Request** A NotificationConfiguration already exists for event_type: {event_type} . Já existe uma NotificationConfiguration para event_type: {event_type}. |
| `PMB000007` | 400 | **Bad Request** No NotificationConfiguration found for event_type: {event_type} . Nenhuma NotificationConfiguration encontrada para event_type: {event_type}. |
| `PMB000008` | 404 | **Not Found** Event not found (event_key = {event_key}) Evento não encontrado (event_key = {event_key}) |
| `PMB000009` | 400 | **Bad Request** Event already exists (event_key: {event_key}) Evento já existe (event_key = {event_key}) |
| `PMB000010` | 400 | **Bad Request** A NotificationConfiguration already exists for person_key: {person_key} / event_type: {event_type} . Já existe uma NotificationConfiguration para person_key: {person_key} / event_type: {event_type} . |
| `PMB000011` | 400 | **Bad Request** Origin '{enumerator}' already exists. Origem '{enumerador}' já existe. |
| `PMB000012` | 400 | **Bad Request** EventType '{enumerator}' already exists. EventType '{enumerator}' já existe. |
| `PMB000013` | 400 | **Bad Request** A person_key must be provided Uma person_key deve ser fornecida |
| `PMB000014` | 400 | **Bad Request** A CallbackConfiguration already exists for person_key: {person_key} . Já existe uma CallbackConfiguration para person_key: {person_key}. |
| `PMB000015` | 404 | **Not Found** No CallbackConfiguration found for person_key: {person_key} . Nenhuma cCallbackConfiguration encontrada para person_key: {person_key}. |
| `PMB000016` | 404 | **Not Found** The CallbackConfiguration URL must be in https. A URL do CallbackConfiguration precisa estar em https. |
| `PMB000017` | 404 | **Not Found** The CallbackConfiguration Headers must be a dict or a json object Os Headers do CallbackConfiguration precisa ser um dicionário, ou um objeto JSON. |
| `PMB000018` | 404 | **Not Found** SMS Try not found by external key SMS Try não encontrado pela chave externa |
| `PMB000019` | 400 | **Bad Request** The requested origin ({origin}) does not exists. A origem solicitada ({origin}) não existe. |
| `PMB000020` | 400 | **Bad Request** The {invalid_uuid} sent is not valid A {invalid_uuid} enviada não é válida |
| `PMB000021` | 400 | **Bad Request** The template type {enumerator} is not valid O tipo de template {enumerator} enviado não é válida |
| `PMB000022` | 400 | **Bad Request** The event type {enumerator} is not valid O tipo de evento {enumerator} enviado não é válida |
| `PMB000023` | 400 | **Bad Request** Already exists an template configuration to this person and event type Já existe um template configuration para essa pessoa e event type |
| `PMB000024` | 404 | **Not found** Template configuration not found Configuração de template não encontrada |
| `PMB000025` | 404 | **Not found** Template not found Template não encontrado |
| `PMB000026` | 400 | **Invalid notification for event type** Invalid notification method for event type Método de notificação inválido para tipo de evento |
| `PMB000027` | 409 | **Conflict** Notification configuration already exists for this person and event type Configuração de notificação já existe para essa pessoa e tipo de evento |
| `PMB000028` | 404 | **Not found** Notification configuration not found Configuração de notificação já não encontrada |
| `PMB000029` | 403 | **Forbidden** User does not own this callback Callback não pertence a este usuário |
| `PMB000030` | 429 | **Too Many Requests** SMS per second threshold has been reached. O limiar de SMS por segundo foi atingido. |
| `PMB000031` | 400 | **Bad Request** A client_integration_key must be provided Uma client_integration_key deve ser fornecida |
| `PMB000032` | 400 | **Bad Request** Selected timeframe should have a maximum of 14 days O intervalo de tempo selecionado deve ter no máximo 14 dias |
| `PMB000033` | 400 | **Bad Request** 'template_id' must be an integer 'template_id' deve ser um inteiro |
| `PMB000034` | 400 | **Bad Request** This resource is temporary unavailable Este recurso está temporariamente indisponível |
### PXT — Pix
185 errors
| Code | HTTP | Message |
|-|-|-|
| `PXT000002` | - | **Person is not Account Owner** Person {person_key} is not account owner A pessoa {person_key} não é dona da conta |
| `PXT000003` | - | **Account is Closed** Account {account_key} is closed Conta {account_key} está fechada |
| `PXT000004` | - | **Account not found** Account not found for: {account_datum} Conta não encontrada para: {account_datum} |
| `PXT000005` | - | **Account not found** Account not found for pix key: {pix_key} Conta não encontrada para chave pix: {pix_key} |
| `PXT000006` | - | **Account not found** Account was not provided for this query Chave de identificação da conta não foi fornecida |
| `PXT000008` | - | **Invalid Permission** Person {person_key} does not have administration roles for account {account_key} Pessoa {person_key} não tem permissões de administrador para a conta {account_key} |
| `PXT000009` | - | **Person Not Found** Person with document number {person_document_number} not found Pessoa com número de documento {person_document_number} não encontrada |
| `PXT000010` | - | **Account is Blocked** Account {account_key} is blocked Conta {account_key} está bloqueada |
| `PXT000011` | - | **Account Type Mismatch** Given account type does not match one registered O tipo de conta fornecido não condiz com o registrado |
| `PXT000012` | - | **Invalid Document Number** Given {document_number} document number is invalid CPF/CNPJ {document_number} fornecido não é valido |
| `PXT0000126` | - | **Error on qr code decode** There was an error on decode qr code Houve um erro ao decodificar o qr code |
| `PXT0000127` | - | **Invalid Reversal Reason** Reversal reason {reversal_reason} is not valid Razão de reversão {reversal_reason} não é válida |
| `PXT000013` | - | **Account Validation Failure** Account validation for received end_to_end_id is not valid Validação da conta para o end_to_end_id recebido não é válida |
| `PXT000014` | - | **Target Account mismatch** Received target account data doesn Dados da conta de destino recebida não corresponde à conta validada |
| `PXT000015` | - | **Reversal date expired** Reversal original transaction is older than 90 days A data de criação da transação original é mais antiga que 90 dias |
| `PXT000016` | - | **Reversal Account Flow Mismatch** Reversal account flow does not match original pix transfer O fluxo de contas de destino e de origem não correspondem ao da transação original |
| `PXT000017` | - | **Reversal Too Great** Reversal transfers sum amount surpasses that of original pix transfer A soma das transações de devolução ultrapassam o valor da transação pix original |
| `PXT000018` | - | **Reversal Original Transfer not Found** Reversal original pix transfer not found Transferência original da devolução não foi encontrada |
| `PXT000019` | - | **Chargeback Validation Failure** Previously done validation values do match with incoming chargeback Os valores da atual devolução não correspondem com aqueles das validação |
| `PXT000020` | - | **Incoming PIX Validation Not Found** No previously done validation was found for given end to end id Não se encontrou validação anterior para o id ponta-a-ponta provido |
| `PXT000021` | - | **Incoming Validation Already Done** There A validação para o id ponta a ponta {end_to_end_id} já foi feita |
| `PXT000022` | - | **Wrong ISPB** ISPB is different from 32402502 ISPB é diferente de 32402502 |
| `PXT000023` | - | **Outgoing PIX Transfer Not Found** Pix transfer key {pix_transfer_key} was not found Transferência PIX de saída com chave {pix_transfer_key} não foi encontrada |
| `PXT000024` | - | **PIX Transfer Not Pending Confirmation** Pix transfer {pix_transfer_key} is not pending confirmation Transferência PIX {pix_transfer_key} não está aguardando confirmação |
| `PXT000025` | - | **Invalid pix transfer key** Pix transfer {pix_transfer_key} is not pending confirmation or does not exist Transferência PIX {pix_transfer_key} não está aguardando confirmação ou não existe |
| `PXT000026` | - | **Search Params Error** Invalid integer value for page or size querystring parameters Valor inválido para parâmetros de página ou tamanho de página |
| `PXT000027` | - | **Invalid Permission** Selected Person does not have administration roles Pessoa selecionada não tem credencial de administrador |
| `PXT000028` | - | **Account Key can not be null when search for config fees** Account key can not be null when search for config fees A chave de conta não pode ser nula quando buscar por configurações de tarifa |
| `PXT000029` | - | **Invalid Value for Enumerator Type** Invalid value {value} used for enumerator type {enumerator} Valor inválido {value} para o tipo de enumerador {enumerator} |
| `PXT000030` | - | **To update or delete a fee configuration must be provided a valid fee ID** To update or delete a fee configuration must be provided a valid fee ID. ID provided: {identification} Para atualizar ou remover uma configuração de tarifa deve ser fornecido um ID válido. ID fornecido: {identification} |
| `PXT000031` | - | **Fee configuration already exists** Fee configuration already exists for {person_owner_type} account with: purpose= {purpose} and {transfer_type}. Please use update Configuração de tarifa já existe para conta {person_owner_type} com: finalidade= {purpose} e {transfer_type}. Por favor utilize o update |
| `PXT000032` | - | **Unable To Delete Default Configuration** Unable To Delete Default Configuration. Please use update Não é permitido deletar uma configuração default. Por favor utilize o update |
| `PXT000033` | - | **Target Account Must Not Be Source Account** Target Account Must Not Be Source Account A conta de destino não pode ser a conta de origem |
| `PXT000034` | - | **Account Key Must Not Be Null** You Need To Define An Account Key To Create A Fee Configuration É necessário definir uma chave de conta para definir uma configuração de tarifa para a mesma |
| `PXT000035` | - | **Limit configuration already exists** Limit configuration already exists for {account_key} account for period(s) {existing_limit_periods}. Please use update Configuração de limite já existe para conta {account_key} para o período(s) {existing_limit_periods}. Por favor utilize o update |
| `PXT000036` | - | **No limit configuration found. Please set default configurations** No limit configuration found. Please set default configurations for {person_type} person Não foi possível encontrar configurações de limite, favor utilizar configurações padrões para {person_type} |
| `PXT000037` | - | **Person Not Found** Person with key {person_key} not found Pessoa com chave {person_key} não encontrada |
| `PXT000038` | - | **Not enough balance** Not enough balance to pay for incoming pix fee Saldo insuficiente para pagar por tarifa de pix de entrada |
| `PXT000039` | - | **Invalid Batch Limit Configuration** Received {} wrong configuration(s) for accounts: {}. Configurations must be None or positive float Recebido {} configuração(ões) erradas para contas: {}. Configurações devem ser None ou float positivo |
| `PXT000040` | - | **Bad Request** Amount limit must be null, positive float or int. Sent {limit} Limite deve ser nulo, positivo inteiro ou decimal. Sent {limit} |
| `PXT000041` | - | **Not Found** Qr Code not found Qr Code não encontrado |
| `PXT000042` | - | **Bad Request** There is no ISPB number for this Bank Code Não existe código ISPB para esse Bank Code |
| `PXT000043` | - | **Bad Request** Invalid decimal amount, sent {number} Valor decimal inválido, enviado {number} |
| `PXT000044` | - | **Not Found** Pix Key {pix_key} is not activated Chave PIX {pix_key} não está ativada |
| `PXT000045` | - | **Not Found** QR Code Payment is invalid for Receiver Conciliation ID {receiver_conciliation_id} Pagamento via QR Code é inválido para Cliente Recebedor {receiver_conciliation_id} |
| `PXT000046` | - | **Bad Request** Invalid value for Valor inválido para o query parameter |
| `PXT000047` | - | **Bad Request** {field_name} could not be larger than {max_length} characters {field_name} não pode ser maior que {max_length} caracteres |
| `PXT000048` | - | **Bad Request** Emoji not allowed in pix message Emoji não é permitido na mensagem pix |
| `PXT000049` | - | **Bad Request** When paying QR Code end_to_end_id could not be none Ao pagar um QR Code o end_to_end_id não pode ser nulo |
| `PXT000050` | - | **Bad Request** Could not read QR Code type, please try to read qr_code again Não foi possível ler o tipo de QR Code. Favor tente ler o qr_code outra vez |
| `PXT000051` | - | **Invalid Requester Configuration Info** The configuration {configuration} format sent is not valid O formato enviado da configuração {configuration} não é válido |
| `PXT000052` | - | **Bad Request** Only Master QI Tech can change default limits configurations Apenas o Master QI Tech pode alterar as configurações de limites padrões |
| `PXT000053` | - | **Bad Request** QrCode already paid Qr Code já Pago |
| `PXT000054` | - | **Bad Request** Invalid Pix Key, sent {pix_key} Chave pix inválida, enviado {pix_key} |
| `PXT000055` | - | **Pix error** Invalid Limit Type Sent Tipo inválido de limite enviado |
| `PXT000056` | - | **Bad Request** Only Master QI Tech can handle limit events Apenas o Master QI Tech pode alterar eventos de limites |
| `PXT000057` | - | **Bad Request** Invalid request_key or no request found, request_key sent {request_key} requisição inválida ou requisição não encontrado, requisição enviada {request_key} |
| `PXT000058` | - | **Bad Request** When limit request is rejected, rejected reason could not be null Quando uma requisição de limite é rejeitada, o motivo não pode ser nulo |
| `PXT000059` | - | **Bad Request** Target document number is not account owner document number O documento infomado não é o mesmo da conta de destino |
| `PXT000060` | - | **Bad Request** Nonexistent account in destination bank Conta inexistente no banco de destino |
| `PXT000061` | - | **Conflict** End to end id invalid. A pix transfer with the end to end id {end_to_end} has already been registered! End to end id inválido. Uma transação pix com o identificador único {end_to_end} já foi registrada! |
| `PXT000062` | - | **Conflict** Missing fields detected on jd connector response: {response} Campos faltantes detectados em resposta do JD connector: {response} |
| `PXT000063` | - | **Conflict** Unexpected response: {response} Resposta inesperada: {response} |
| `PXT000064` | - | **Bad Request** For Manual Pix Transfer Type a target account must be provided Para transação pix do tipo manual, uma conta destino deve ser fornecida |
| `PXT000065` | - | **Bad Request** Pix transfer sent was already rejected. Rejection_reason: {error_description} Pix transfer já rejeitada. Motivo da rejeição: {error_description_translated} |
| `PXT000067` | - | **Pix Key is Unregistered** Pix key {pix_key} is not currently used A chave pix {pix_key} não está sendo utilizada |
| `PXT000068` | - | **Pix Key is Unregistered** Pix key inquiry timeout. Please try again Consulta de chave pix excedeu o tempo limite. Por favor tente novamente |
| `PXT000069` | - | **Error in Qr Code Payload Request** An error occurred while requesting the qr code payload to the registry institution Um erro ocorreu durante a requisição do payload do qr code para a instituição de registro |
| `PXT000070` | - | **Invalid Qr Code Format** The Qr Code format is invalid, please enter a valid Qr Code O formato do Qr Code é inválido, por favor insira um Qr Code válido |
| `PXT000071` | - | **Invalid Qr Code Type** The Qr Code payload given did not provide a propper Qr Code type O payload de QR Code fornecido não contêm um tipo de Qr Code Válido |
| `PXT000072` | - | **Pending Transfer** The transaction ({end_to_end_id}) could not be completed and is pending confirmation Não foi possível concluir a transação ({end_to_end_id}) e ela está pendente de confirmação |
| `PXT000073` | - | **Outgoing PIX Transfer Not Found** Pix transfer end to end id {end_to_end_id} was not found Transferência PIX de saída com identificador único {end_to_end_id} não foi encontrada |
| `PXT000074` | - | **Invalid Transaction Status** Unable to update transaction status. The status {status} is invalid Não foi possível atualizar o status da transação. O status {status} é invalido |
| `PXT000075` | - | **Pix Transfer Key or End To End Not Provided** No pix transfer key or end to end id provided Não foram fornecidos uma pix transfer key ou end to end id |
| `PXT000076` | - | **Incoming PIX Transfer Not Found** Pix transfer key {pix_transfer_key} was not found Transferência PIX de entrada com chave {pix_transfer_key} não foi encontrada |
| `PXT000077` | - | **Pix Transfer Receipt not allowed** Pix Transfer Receipt cannot be generated for rejected transfers Recibo de transação pix não pode ser gerado para transações rejeitadas |
| `PXT000078` | - | **Pix Transfer Receipt not available** Receipt not available due to pix transfer currently being processed. Wait a few minutes and try again Comprovante não disponível pois transação Pix está em processamento. Por favor, aguarde alguns minutos e tente novamente |
| `PXT000079` | - | **Bad Request** Insufficient billing account balance for fee Saldo de conta de cobrança insuficiente para a taxa |
| `PXT000080` | - | **Bad Request** Could not complete the transaction and the transaction was rejected Não foi possível concluir a transação e a transferência foi rejeitada |
| `PXT000081` | - | **Bad Request** Pix key not sent Chave PIX não enviada |
| `PXT000082` | - | **Bad Request** The sent PIX key {pix_key} does not match the decoded PIX key A chave PIX enviada {pix_key} não coincide com a chave PIX decodificada |
| `PXT000083` | - | **Bad Request** Pix rejected. Pix rejeitado. |
| `PXT000084` | - | **Original Pix Transfer Was Not Found** Original Pix Transfer Was Not Found A transação PIX original não foi encontrada |
| `PXT000085` | - | **Invalid Permission** User do not has sufficient permissions Usuário não tem permissões suficientes |
| `PXT000086` | - | **Update Default Failed** To update default requester configuration send default as requester_key in url Para alterar a configuracao de requester padrao, envie default como requester_key na url |
| `PXT000087` | - | **Amount limit not approved try a lower value** Amount limit for {person_type} person not approved, please try a lower value Limite total não aprovado para pessoa {person_type}, por favor tente um menor |
| `PXT000088` | - | **Bad Request** Invalid account information when translating to account DTO Informações da conta inválidas na tradução do DTO |
| `PXT000089` | - | **Incoming Pix not pending** Incoming Pix with pix transfer key {pix_transfer_key} is not pending Transferência de Entrada PIX {pix_transfer_key} não está pendente |
| `PXT000090` | - | **Service Unavailable** Pix transfer is not available right now. Please wait or use TED service Transferência Pix não esta disponível no momento. Favor aguardar ou utilizar TED |
| `PXT000091` | - | **Bad Request** System account has no limits. Account key {account_key} is system account Contas de sistema não possuem limite. Chave de conta {account_key} é conta de sistema |
| `PXT000092` | - | **Invalid Account Type** Pix is not yet implemented for non-checking or non-escrow account types Transações Pix não estão implementadas para conta que não sejam escrow ou livres |
| `PXT000093` | - | **Bad Request** Fee must be either fixed_amount or percentage Tarifas fixas e percentuais são multualmente exclusivas |
| `PXT000094` | - | **Bad Request** Failed to fetch transactions by origin key Falha ao obter transações por origin key |
| `PXT000095` | - | **Unforeseen Error Scenario on Reprocess** Scenario: pix_transfer_key: {pix_transfer_key}, pix_status: {pix_status}, bacen_status: {bacen_status}, internal_tx: {internal_tx}, reverse_tx: {reverse_tx}, external_tx: {external_tx} Cenário: pix_transfer_key: {pix_transfer_key}, pix_status: {pix_status}, bacen_status: {bacen_status}, internal_tx: {internal_tx}, reverse_tx: {reverse_tx}, external_tx: {external_tx} |
| `PXT000096` | - | **Expectation Failed** Unexpected error trying to reprocess external transaction for outgoing Pix {pix_transfer_key} Erro inesperado ao tentar refazer transação externa de saída Pix {pix_transfer_key} |
| `PXT000097` | - | **Expectation Failed** Unexpected error trying to reprocess reverse transaction for outgoing Pix {pix_transfer_key} Erro inesperado ao tentar refazer transação reversa de saída Pix {pix_transfer_key} |
| `PXT000098` | - | **Expectation Failed** Unexpected subtype encountered: {subtype} Subtipo inesperado encontrado: {subtype} |
| `PXT000099` | - | **Error retrieving account data** Error while retrieving data for account_key {account_key} Erro ao recolher informações da conta {account_key} |
| `PXT000100` | - | **Rejected by external analysis** The transaction was rejected by external analysis A transação foi rejeitada pela análise externa |
| `PXT000101` | - | **Bad Request** It is not allowed to set a maximum or a minumum value to a fixed amount fee Não é permitido inserir valores de mínimo e máximo para tarifas de valor fixo |
| `PXT000102` | - | **Invalid caas_client_key** There caas_client_key is not valid A caas_client_key enviada não é válida |
| `PXT000103` | - | {key} was not accepted for not being a valid uuid v4 string {key} não foi aceito por não ser uma palavra uuid v4 válida |
| `PXT000104` | - | **Invalid Transaction Amount** Transaction amount of {transaction_amount} is not valid. It must be a positive value with at maximum 2 decimal places O valor de transação {transaction_amount} não é válido. Deve ser um valor positivo com no máximo duas casas decimais |
| `PXT000105` | - | **Invalid end_to_end_id** The end_to_end_id sent {end_to_end_id} is not valid O end_to_end_id enviado {end_to_end_id} não é válido |
| `PXT000106` | - | **Failed to load pix limit used** Failed to load pix limit used. Please try again. If the problem persists contact our support Falha ao carregar limite pix utilizado. Caso o problema persista, por favor contate nosso suporte |
| `PXT000107` | - | **Failed to load pix limit configuration** Failed to load pix limit configuration. Please try again. If the problem persists contact our support Falha ao carregar configuração de limite pix. Caso o problema persista, por favor contate nosso suporte |
| `PXT000108` | - | **Bad Request** Billing account closed or blocked Conta de cobrança encerrada ou bloqueada |
| `PXT000109` | - | **Bad Request** request_control_key {request_control_key} already in use request_control_key {request_control_key} já utilizada |
| `PXT000110` | - | **Failed external analysis** The transaction failed to be validated by external analysis A transação foi rejeitada falhou em ser validada pela análise externa |
| `PXT000111` | - | **Bad Request** invalid pix transfer type sent Tipo de transação pix inválida |
| `PXT000112` | - | **Bad Request** Receiver Conciliation id sent does not match expected Número de conciliação do recebedor não atende ao esperado |
| `PXT000113` | - | **Bad Request** It has been identified by request_control_key or end_to_end_id that this request is already being processed Foi identificado por request_control_key ou end_to_end_id que está requisição está sendo processada |
| `PXT000114` | - | **Bad Request** Requester Configuration already exists for {requester_key} Requester Configuration já existe para o {requester_key} |
| `PXT000115` | - | **Bad Request** Insufficient account balance for transfer and fee amount Saldo de conta insuficiente para a transação e a taxa |
| `PXT000117` | - | **Pix Transfer Pending** An error occurred while sending pix_transfer {pix_transfer.pix_transfer_key} to SPI Um erro ocorreu ao enviar a pix_transfer {pix_transfer.pix_transfer_key} ao SPI |
| `PXT000118` | - | **Requester is not Pix Participant** The requester sent an alias key but is not a indirect pix participant O requisitante enviou uma alias key no entanto não é um participante do pix indireto |
| `PXT000119` | - | **Requester is not account Owner** The requester is not the owner for the account sent O requisitante não é dono da conta enviada |
| `PXT000120` | - | **Alias sent not found** Alias key attached to this account not found Alias key vinculada à conta não encontrada |
| `PXT000121` | - | **Pix Transfer Direction Invalid** Pix transfer direction must be either outgoing or incoming Pix transfer direction deve ser outgoing ou incoming |
| `PXT000122` | - | **Pix Transfer key or Request Control Key needed** A pix_transfer_key or a request_control_key must be provided Uma pix_transfer_key ou uma request_control_key deve ser fornecida |
| `PXT000123` | - | **Invalid Timestamp Format sent** Given parameter is not in the correct format {timestamp_format} Parametro enviado não está no formato correto {timestamp_format} |
| `PXT000124` | - | **Outgoing Pix Transfer not found** Given parameters returned no results found Parâmetros enviados não retornaram resultados |
| `PXT000125` | - | **Incoming Pix Transfer not found** Given parameters returned no results found Parâmetros enviados não retornaram resultados |
| `PXT000128` | - | **Bad Request** Pix key {pix_key} sent does match inquiry pix key. Verify if end_to_end_id sent is correct Chave Pix {pix_key} enviada não condiz com consulta. Verifique se end_to_end_id enviado está correto |
| `PXT000129` | - | **SPI Error message** Message rejected by SPI-ICOM Mensagem rejeitada pela SPI-ICOM |
| `PXT000130` | - | **SPI Timeout Control** SPI Timeout Control Controle de timeout no SPI |
| `PXT000131` | - | **Receiver Internal Error** Cancelled transaction due to receiver Transação interrompida devido a erro no PSP do Recebedor |
| `PXT000132` | - | **Invalid Target Account Number** Target account number is invalid Número da conta de destino é inexistente ou inválido |
| `PXT000133` | - | **Blocked Target Account** Target account is blocked A conta de destino encontra-se bloqueada |
| `PXT000134` | - | **Closed Target Account** Target account is closed A conta de destino encontra-se encerrada |
| `PXT000135` | - | **Unsupported Transaction** Unsupported transaction for given target account A conta de destino não suporta este tipo de transação |
| `PXT000136` | - | **Invalid Participant** SPI participant is not PSP settler agent of payer nor receiver Participante direto do SPI não é liquidante do PSP do Pagador / Recebedor |
| `PXT000137` | - | **Zero Value Payment Order** Zero value payment order Ordem de pagamento com valor zero |
| `PXT000138` | - | **Insufficient Funds** Insufficient funds in PI account from payer Saldo insuficiente na conta PI do pagador |
| `PXT000139` | - | **Return Value Too Great** Return value greater than corresponding payment order Valor de devolução acima do valor de pagamento correspondente |
| `PXT000140` | - | **Invalid Transactions Number** Invalid transactions number Quantidade de transações inválida |
| `PXT000141` | - | **Unrelated Beneficiary Document Number** Beneficiary document number is not that of target account owner CPF/CNPJ do usuário recebedor não é compatível com o titular da conta de destino |
| `PXT000142` | - | **Invalid Beneficiary Document Number** Invalid beneficiary document number CPF/CNPJ da conta de destino está incorreto |
| `PXT000143` | - | **Incorrect Message Element** Incorrect message element Elemento da mensagem incorreto |
| `PXT000144` | - | **Rejected Payment Order** Beneficiary Ordem de pagamento foi rejeitada pelo banco recebedor |
| `PXT000145` | - | **Unauthorized Payer** Signing participant is unauthorized to make a payment order for paying account Participante que assinou a mensagem não é autorizado a realizar a operação na conta PI |
| `PXT000146` | - | **Invalid Datetime** Invalid datetime for message delivery Data e Hora do envio da mensagem inválida |
| `PXT000147` | - | **Generic Error** Error while processing payment (generic error) Erro no processamento do pagamento (erro genérico) |
| `PXT000148` | - | **Bad Format Operation Identifier** Badly formatted operation Identificador da operação mal formatado |
| `PXT000149` | - | **Invalid Payer ISPB** Invalid or non-existent payer Número ISPB do PSP do Pagador é inválido ou inexistente |
| `PXT000150` | - | **Invalid Beneficiary ISPB** Invalid or non-existent beneficiary Número ISPB do banco recebedor é inválido ou inexistente |
| `PXT000151` | - | **Incorrect Type** Incorrect type for target account Tipo incorreto para a conta transacional especificada |
| `PXT000152` | - | **SPI Repeated E2E ID** The end_to_end_id was already used O end_to_end_id já foi utilizado |
| `PXT000153` | - | **Invalid Target Account Type** The target account type can not receive PIX transactions O tipo de conta destino não pode receber transações PIX |
| `PXT000154` | - | **Invalid ISPB** Invalid or non-existent ISPB number Número ISPB é inválido ou inexistente |
| `PXT000155` | - | **Amount too Great** Amount too great for credited account Valor de pagamento/devolução acima do permitido para a conta de destino creditada |
| `PXT000156` | - | **QR Code Rejected** QR Code rejected by beneficiary QR Code rejeitado pelo PSP do usuário recebedor |
| `PXT000157` | - | **Bacen Service Unavailable** Could not sent the message to ICOM after 3 retries Não pode enviar a mensagem para a ICOM depois de 3 tentativas |
| `PXT000158` | - | **Invalid Amount** Paid amount diverges from expected amount of {expected_amount} O valor do pagamento diverge do valor esperado de {expected_amount} |
| `PXT000159` | - | **QR code inactive** QR code is not active at the time of payment QR code não está ativo no instante do pagamento |
| `PXT000160` | - | **QR code inactive** QR code is not active at the time of payment QR code não está ativo no instante do pagamento |
| `PXT000161` | - | |
| `PXT000162` | - | |
| `PXT000163` | - | |
| `PXT000164` | - | **Unmapped Rejection Error Code** Settlement failed, unknown error reason code from receiver PSP Código de recusa desconhecido do PSP recebedor |
| `PXT000165` | - | **Request Control Key needed** A request_control_key must be provided Uma request_control_key deve ser fornecida |
| `PXT000166` | - | **Invalid Target** Account does not have permission to transfer to the given target account A conta não possui permissão para realizar transferências para a conta enviada |
| `PXT000167` | - | **Requester not allowed to access this endpoint** Requester has no permission to perform pix transfers on this endpoint Requester não possui permissão de realizar transações pix através deste endpoint |
| `PXT000168` | - | **No approver permission** Given document number does not belong to an approver for this account Número de documento enviado não pertence a um aprovador da conta |
| `PXT000169` | - | **tfa_info is required** Client must send object tfa_info Cliente deve enviar objeto tfa_info |
| `PXT000170` | - | **Error occurred while sending token** An unexpected error occurred while sending token Um erro inexperado ocorreu ao tentar enviar token |
| `PXT000171` | - | **Number of token validation attempts exceeded** The maximum number of failed token validation attempts has been reached Número máximo de tentativas de validação de token atingida |
| `PXT000172` | - | **Token Expired** Token has expired. Resend token or recreate transfer Token expirado. Reenvie token ou recrie a transferência |
| `PXT000173` | - | **Incorrect Token** Token sent does not match expected Token enviado não condiz com, o esperado |
| `PXT000174` | - | **Error Sending Token** An error occurred while sending token and its being investigated Um erro ocorreu ao enviar token e está sendo investigado |
| `PXT000175` | - | **Invalid Status** Pix transfer not in pending_2fa_approval status Pix transfer não está pendente de aprovação por autenticação de dois fatores |
| `PXT000176` | - | **Error Sending Token** An error occurred while resending token and its being investigated Um erro ocorreu ao reenviar token e está sendo investigado |
| `PXT000177` | - | **Pix Transfer Batch key needed** A pix_transfer_batch_key must be provided Uma pix_transfer_batch_key deve ser fornecida |
| `PXT000178` | - | **Pix Transfer Batch not found** A pix_transfer_batch not found Uma pix_transfer_batch não encontrada |
| `PXT000179` | - | **Empty pix-transfer list received** A list of pix transfers must be provided Uma lista de transferências pix deve ser fornecida |
| `PXT000180` | - | **Invalid Status** Pix transfer Batch not in pending_2fa_approval status Pix transfer em lote não está pendente de aprovação por autenticação de dois fatores |
| `PXT000181` | - | **Target PSP Timeout** Beneficiary Timeout do participante recebedor da ordem de pagamento |
| `PXT000182` | - | **Bad Request** The given Pix transfer is tied to a batch. It cannot be individually approved. Please approve batch A Pix transfer enviada está ligada a um lote. Ela não pode ser individualmente aprovada. Por favor aprove o lote |
| `PXT000183` | - | **Invalid Person Type** Natural Person Cannot Pay for a PIX Fee Pessoa Física não pode pagar tarifa de PIX |
| `PXT000184` | - | **Outgoing PIX Transfer must hold to be reprocessed** Pix transfer key {pix_transfer_key} must wait to be reprocessed Transferência PIX de saída com chave {pix_transfer_key} deve aguardar para ser reprocessada |
| `PXT000185` | - | **Invalid Limit Request Status** Invalid limit request status to perform request Status de requisição de limite pix inválida para realizar operação |
| `PXT000186` | - | **Invalid pix transfer Status** Invalid pix transfer status to perform request Status de pix inválido para realizar operação |
| `PXT000187` | - | **Reprocessing Blocked. Reversal Transaction Detected** Pix transfer cannot be reprocessed due to reversal being detected Pix transfer não pode ser reprocessda devido a presença de reversal |
| `PXT000188` | - | **Session ID needed** A session_id must be provided Uma session_id deve ser fornecida |
| `PXT000189` | - | **Token Required** A token is required for SMS or email validation. Um token é necessário para validação via SMS ou email. |
---
# Cancel payment scheduling batch
URL: /en/documentation/baas/cobranca/2fa_v2/agendamento/cancelar_agendamento_em_lote_de_pagamento
This endpoint allows cancelar um batch de scheduling de payments enquanto o batch estiver em status cancelável.
:::info Boleto bancário
É o bank slip convencional (linhas digitáveis não iniciadas com dígito 8). Possui registro na Câmara Interbancária de Pagamento (CIP/Núclea) e pode ser pago em instituições financeiras e de payment autorizadas a funcionar pelo Banco Central.
:::
:::info Fatura de recolhimento
Esse tipo de cobrança é emitido por concessionárias de serviços (account de água, luz, telefone e gás) e órgãos públicos (tributos). Eles não são registrados na Câmara Interbancária de Pagamento (CIP/Núclea), por isso, não retornam as mesmas informações que um Boleto bancário apresenta.
:::
## Request
### Request Endpoint
ENDPOINT /account/ ACCOUNT_KEY /batch_payment_schedule/ BATCH_PAYMENT_SCHEDULE_KEY /cancel
METHOD PATCH
### Request Path Params
| Field | Type | Description | Characters |
|-----------------------|-------|--------------------------------------------------|------------|
| `account_key` * | uuid4 | Chave única de identificação da account. | 36 |
| `batch_payment_key` * | uuid4 | Chave única de identificação do batch de scheduling. | 36 |
## Response
### Success Response
STATUS 200
Response Body: Batch de scheduling cancelado
```json
{
"batch_payment_schedule_key": "a3214093-e51c-55e2-b5d3-60244475b3fb",
"request_control_key": "b6804f32-101e-4702-8fbc-c2dbc4c2caec",
"account_key": "6dc89d57-fac7-4643-b151-cd2ca0a7f68f",
"total_amount": 1357.3,
"batch_payment_schedule_status": "canceled",
"payment_type": "bank_slip"
}
```
### Response Body Params
| Field | Type | Description |
|--------------------------------|--------|-----------|
| `batch_payment_schedule_key` * | uuid4 | Chave única de identificação do batch de scheduling. |
| `request_control_key` * | uuid4 | Chave única de identificação da request do cliente (batch). |
| `account_key` * | uuid4 | Chave da account debitada. |
| `total_amount` * | number | Soma dos valores dos itens do batch. |
| `batch_payment_schedule_status` * | [enum](#enumeradores-batch_payment_schedule_status) | Status do batch após a solicitação de cancelamento. |
| `payment_type` * | [enum](#enumeradores-payment_type) | Type do payment. |
### Enumerators batch_payment_schedule_status
| Enumerator | Description |
|------------------------|---------------------------|
| `pending_2fa_approval` | Pendente de aprovação 2FA |
| `scheduled` | Scheduled |
| `rejected` | Rejected |
| `canceled` | Canceled |
| `error` | Scheduling error |
### Enumerators payment_type
| Enumerator | Description |
|-------------------|------------------------|
| `bank_slip` | Boleto bancário |
| `collection_slip` | Fatura de recolhimento |
### Error Response
STATUS 4XX
Response Body
```json
{
"title": "Título",
"description": "Description in english",
"translation": "Description em português",
"code": "Código"
}
```
| Código HTTP | Código QI | Título | Description (eng) | Description (pt-br) |
|-------------|-----------|-------------|----------------------------------------------|--------------------------------------------------------|
| 403 | BIP000010 | Forbidden | User is not allowed to do this action | Usuário não tem autorização para fazer essa ação |
| 404 | BIP000011 | Not Found | The source account key was not found. | A chave da account de origem não foi encontrada. |
| 404 | BIP000083 | Not Found | Batch payment not found by batch payment key.| Batch de payments não encontrado pela chave do batch. |
| 400 | BIP000085 | Bad Request | Batch payment status is not pending approval.| Status do batch de payments não é de aprovação pendente. |
---
# Confirmar Agendamento de Boleto Bancário
URL: /en/documentation/baas/cobranca/2fa_v2/agendamento/confirmar_agendamento_de_boleto_bancario
Este endpoint permite realizar a confirmação do agendamento de pagamento de um boleto bancário.
:::info Boleto bancário
É o boleto bancário convencional (linhas digitáveis não iniciadas com dígito 8). Possui registro na Câmara Interbancária de Pagamento (CIP/Núclea) e pode ser pago em instituições financeiras e de pagamento autorizadas a funcionar pelo Banco Central.
:::
## Request
ENDPOINT /account/ ACCOUNT_KEY /payment_schedule/ PAYMENT_SCHEDULE_KEY /bank_slip/validate_token
MÉTODO PATCH
### Request Path Params
| Campo | Tipo | Descrição | Caracteres |
|---------------------|---------|-----------------------------------------|------------|
| `account_key` * | uuid4 | Chave única de identificação da conta. | 36 |
| `payment_schedule_key` * | uuid4 | Chave única de identificação do agendamento. | 36 |
Request Body: Confirmação de agendamento de boleto bancário
```json
{
"token": "329adf"
}
```
### Body Params
| Campo | Tipo | Descrição |
|---------------------|---------------|-----------------------------------|
| `token` * | string | Código de autenticação enviado ao aprovador de movimentações da conta |
## Response
### Success Response
STATUS 200
Response Body: Agendamento confirmado
```json
{
"payment_schedule_key":"c4325104-d60b-44f3-aae4-49155564a2ea",
"request_control_key":"b713b2f6-2f48-4d18-b0c9-7186e4edf189",
"payer_name":"COOPERATIVA INDUSTRIAL MURILO",
"payer_document_number":"00037025000160",
"source_account_key":"6dc89d57-fac7-4643-b151-cd2ca0a7f68f",
"paid_amount":1050.1,
"payment_date":"2024-04-03",
"payment_type":"bank_slip",
"bank_slip": {
"bank_slip_key":"95080ffd-3ac5-48d7-b3fe-659e4aaba81a",
"barcode":"00193967000009910000000003615574000000002417",
"digitable_line":"00190000090361557400500000024174396700000991000",
"payer_name":"COOPERATIVA TESTE",
"payer_document_number":"00037025000160",
"beneficiary_name":"TESTE EQUIPAMENTOS E SERVICOS LTDA",
"beneficiary_trading_name":"TESTE EQUIPAMENTOS E SERVICOS LTDA",
"beneficiary_document_number":"52069937000117",
"beneficiary_bank_ispb":"00000000",
"guarantor_name":null,
"guarantor_document_number":null,
"expiration_date":"2024-03-29",
"max_payment_data": "2026-03-29",
"partial_payment_indicator":"allowed",
"registered_payment_amount":9029.0,
"nominal_amount":9910.0,
"total_amount":10129.1,
"rebate_amount":0.0,
"discount_amount":0.0,
"fine_amount":0.0,
"interest_amount":219.1
},
"collection_slip":null,
"payment_schedule_status":"scheduled"
}
```
### Response Body Params
| Campo | Tipo | Descrição |
|---------------------|---------|-----------------------------------------------------|
| `payment_key` * | uuid4 | Chave única de identificação do pagamento. |
| `request_control_key` * | uuid4 | Chave única de identificação da request do cliente. |
| `payer_name` * | string | Nome do pagador efetivo. |
| `payer_document_number` * | string | Número do documento do pagador efetivo (CPF/CNPJ). |
| `source_account_key` * | uuid4 | Chave da conta debitada. |
| `paid_amount` * | number | Valor pago efetivamente. |
| `payment_date` * | string | Data do pagamento. |
| `payment_type` * | [enum](#enumeradores-payment_type) | Tipo do pagamento. |
| `bank_slip` | [object](#objeto-bank_slip) | Boleto bancário. |
| `collection_slip` | object | Fatura de recolhimento. |
| `payment_schedule_status` * | [enum](#enumeradores-payment_schedule_status) | Status do agendamento. |
### Enumeradores payment_type
| Enumerador | Tipo | Descrição |
|---------------|-----------|---------------|
| `bank_slip` | string | Boleto bancário |
| `collection_slip` | string | Fatura de recolhimento |
:::danger Aviso
O enumerador `collection_slip` não se aplica para o fluxo de boletos bancários, assim como o objeto collection_slip que sempre será nulo.
:::
### Enumeradores payment_schedule_status
| Enumerador | Descrição |
|---------------------|------------------------------------------------------------------|
| `pending_2fa_approval` | Agendamento pendente de autenticação de dois fatores (2FA) |
| `scheduled` | Pagamento agendado com sucesso |
| `executed` | O agendamento foi executado com sucesso e o pagamento referente ao agendamento gerado |
| `rejected` | O agendamento foi rejeitado e nenhum pagamento foi gerado |
| `canceled` | Agendamento cancelado |
| `error` | Erro ao realizar o agendamento |
### Objeto bank_slip
| Campo | Tipo | Descrição |
|-----------------------------------|---------|-----------------------------------|
| `barcode` * | string | Código de barras. |
| `digitable_line` * | string | Linha digitável. |
| `payer_name` * | string | Nome do pagador.|
| `payer_document_number` * | string | Número do documento do pagador (CPF/CNPJ). |
| `beneficiary_name` * | string | Nome do beneficiário. |
| `beneficiary_trading_name` | string | Nome fantasia do beneficiário. |
| `beneficiary_document_number` * | string | Número do documento do beneficiário (CPF/CNPJ). |
| `beneficiary_bank_ispb` * | string | Código ispb do banco do beneficiário. |
| `guarantor_name` | string | Nome do sacador avalista. |
| `guarantor_document_number` | string | Número do documento do sacador avalista (CPF/CNPJ). |
| `expiration_date` * | string | Data de vencimento. |
| `max_payment_date` * | string | Data máxima de pagamento. |
| `partial_payment_indicator` * | [enum](#enumeradores-partial_payment_indicator) | Indicador de pagamento parcial. |
| `registered_payment_amount` | string | Valor total de pagamento registrado. |
| `nominal_amount` * | number | Valor original. |
| `total_amount` * | number | Valor total. |
| `rebate_amount` * | number | Valor do batimento. |
| `discount_amount` * | number | Valor do desconto. |
| `fine_amount` * | number | Valor da multa. |
| `interest_amount` * | number | Valor do juros. |
### Enumeradores partial_payment_indicator
| Enumerador | Tipo | Descrição |
|---------------|-----------|---------------|
| `allowed` | string | Permitido |
| `not_allowed` | string | Não permitido |
### Error Response
STATUS 4XX
Response Body
```json
{
"title": "Título",
"description": "Description in english",
"translation": "Descrição em português",
"code": "Código"
}
```
| Código HTTP | Código QI | Título | Descrição (eng) | Descrição (pt-br) |
|-------------|-----------|--------|------------------|------------------|
| 403 | BIP000010 | Forbidden | User is not allowed to do this action | Usuário não tem autorização para fazer essa ação |
| 404 | BIP000011 | Not Found | The source account key was not found. | A chave da conta de origem não foi encontrada. |
| 400 | BIP000012 | Bad Request | It 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. |
| 400 | BIP000013 | Bad Request | The source account is closed. | A conta de origem está fechada. |
| 400 | BIP000014 | Bad Request | The source account is blocked. | A conta de origem está bloqueada. |
| 400 | BIP000022 | Bad Request | Bank slip payment service is closed. | Serviço de pagamento de boleto está fechado. |
| 400 | BIP000023 | Bad Request | The source account has insufficient balance. Payment cannot be made. | A conta de origem possui saldo insuficiente. Pagamento não pode ser realizado. |
| 400 | BIP000025 | Bad Request | It was not possible to pay the bank slip at this time. Please verify your information and, if necessary, contact us for assistance. | Não foi possível pagar o boleto neste momento. Por favor, verifique suas informações e, se necessário, entre em contato conosco para assistência. |
| 400 | BIP000028 | Bad Request | The source account has blocked balance. Payment cannot be made. | A conta de origem possui saldo em conta bloqueado. Pagamento não pode ser realizado. |
| 404 | BIP000056 | Not Found | Payment not found. | Pagamento não encontrado. |
| 400 | BIP000057 | Bad Request | Payment status is not pending approval. | Status de pagamento não é de aprovação pendente. |
| 400 | BIP000058 | Bad Request | Error while validating verification token | Erro ao validar token de verificação |
| 400 | BIP000059 | Bad Request | Number of verification token validation attempts exceeded. | Número de tentativas de validação de token de verificação excedido. |
| 400 | BIP000060 | Bad Request | Verification token expired. | Token de verificação expirado. |
| 400 | BIP000061 | Bad Request | Verification token validation failed. | Falha na validação do token de verificação. |
| 400 | BIP000062 | Bad Request | Payment type is not bank slip. | Tipo de pagamento não é boleto. |
| 400 | BIP000065 | Bad Request | Payment verification time window exceeded. | Janela de tempo de verificação de pagamento excedida. |
---
# Confirmação de Pagamento de Fatura de Recolhimento
URL: /en/documentation/baas/cobranca/2fa_v2/agendamento/confirmar_agendamento_de_fatura_de_recolhimento
Este endpoint permite realizar a confirmação do pagamento de faturas de recolhimento.
:::info Fatura de recolhimento
Esse tipo de cobrança é emitido por concessionárias de serviços (conta de água, luz, telefone e gás) e órgão públicos (tributos). Eles não são registrados na Câmara Interbancária de Pagamento (CIP/Núclea), por isso, não retornam as mesmas informações que um Boleto bancário apresenta.
:::
## Request
### Request Endpoint
ENDPOINT /account/ ACCOUNT_KEY /payment_schedule/ PAYMENT_SCHEDULE_KEY /collection_slip/validate_token
MÉTODO PATCH
### Request Path Params
| Campo | Tipo | Descrição | Caracteres |
|---------------------|---------|-----------------------------------------|------------|
| `account_key` * | uuid4 | Chave única de identificação da conta. | 36 |
| `payment_schedule_key` * | uuid4 | Chave única de identificação do agendamento. | 36 |
Request Body: Confirmação de agendamento de fatura de recolhimento
```json
{
"token": "329adf"
}
```
### Body Params
| Campo | Tipo | Descrição |
|---------------------|---------------|-----------------------------------|
| `token` * | string | Código de autenticação enviado ao aprovador de movimentações da conta |
## Response
### Success Response
STATUS 200
Response Body: Agendamento confirmado
```json
{
"payment_schedule_key": "33860ad0-bcb0-47b7-bbe7-c7e3ec2fc61a",
"request_control_key": "ae4508df-f2cb-4e28-9f04-a19b7f2758c9",
"payer_name": "COOPERATIVA INDUSTRIAL MURILO",
"payer_document_number": "62069937000118",
"source_account_key": "daae79e6-ee8b-449f-aa1e-96959d5d5a72",
"paid_amount": 1389.21,
"payment_date": "2024-04-30",
"payment_type": "collection_slip",
"bank_slip": null,
"collection_slip": {
"barcode": null,
"digitable_line": "836200000138892100450006762142420244046000010192",
"collection_name": "CIA ULTRAGAZ SA-COD",
"collection_document_number": "00394460005887",
"expiration_date": "2024-04-15",
"total_amount": 1389.21
},
"payment_status": "scheduled"
}
```
### Response Body Params
| Campo | Tipo | Descrição |
|---------------------|---------|-----------------------------------------------------|
| `payment_key` * | uuid4 | Chave única de identificação do pagamento. |
| `request_control_key` * | uuid4 | Chave única de identificação da request do cliente. |
| `payer_name` * | string | Nome do pagador efetivo. |
| `payer_document_number` * | string | Número do documento do pagador efetivo (CPF/CNPJ). |
| `source_account_key` * | uuid4 | Chave da conta debitada. |
| `paid_amount` * | number | Valor pago efetivamente. |
| `payment_date` * | string | Data do pagamento. |
| `payment_type` * | [enum](#enumeradores-payment_type) | Tipo do pagamento. |
| `bank_slip` | object | Boleto bancário. |
| `collection_slip` | [object](#objeto-collection_slip) | Fatura de recolhimento. |
| `payment_schedule_status` * | [enum](#enumeradores-payment_schedule_status) | Status do agendamento. |
### Enumeradores payment_type
| Enumerador | Tipo | Descrição |
|---------------|-----------|---------------|
| `bank_slip` | string | Boleto bancário |
| `collection_slip` | string | Fatura de recolhimento |
:::danger Aviso
O enumerador `bank_slip` não se aplica para o fluxo de faturas de recolhimento, assim como o objeto bank_slip que sempre será nulo.
:::
### Enumeradores payment_schedule_status
| Enumerador | Descrição |
|---------------------|------------------------------------------------------------------|
| `pending_2fa_approval` | Agendamento pendente de autenticação de dois fatores (2FA) |
| `scheduled` | Pagamento agendado com sucesso |
| `executed` | O agendamento foi executado com sucesso e o pagamento referente ao agendamento gerado |
| `rejected` | O agendamento foi rejeitado e nenhum pagamento foi gerado |
| `canceled` | Agendamento cancelado |
| `error` | Erro ao realizar o agendamento |
### Objeto collection_slip
| Campo | Tipo | Descrição |
|-----------------------------------|---------|-----------------------------------|
| `barcode` | string | Código de barras. |
| `digitable_line` | string | Linha digitável. |
| `collection_name` * | string | Nome do convênio.|
| `collection_document_number` | string | Número de documento do convênio (CPF/CNPJ).|
| `expiration_date` * | string | Data de vencimento. |
| `total_amount` * | number | Valor total. |
### Error Response
STATUS 4XX
Response Body
```json
{
"title": "Título",
"description": "Description in english",
"translation": "Descrição em português",
"code": "Código"
}
```
| Código HTTP | Código QI | Título | Descrição (eng) | Descrição (pt-br) |
|-------------|-----------|--------|------------------|------------------|
| 403 | BIP000010 | Forbidden | User is not allowed to do this action | Usuário não tem autorização para fazer essa ação |
| 404 | BIP000011 | Not Found | The source account key was not found. | A chave da conta de origem não foi encontrada. |
| 400 | BIP000012 | Bad Request | It 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. |
| 400 | BIP000013 | Bad Request | The source account is closed. | A conta de origem está fechada. |
| 400 | BIP000014 | Bad Request | The source account is blocked. | A conta de origem está bloqueada. |s
| 400 | BIP000023 | Bad Request | The source account has insufficient balance. Payment cannot be made. | A conta de origem possui saldo insuficiente. Pagamento não pode ser realizado. |
| 400 | BIP000028 | Bad Request | The source account has blocked balance. Payment cannot be made. | A conta de origem possui saldo em conta bloqueado. Pagamento não pode ser realizado. |
| 400 | BIP000036 | Bad Request | Covenant slip overdue. | Fatura de recolhimento vencida. |
| 400 | BIP000038 | Bad Request | Outside of covenant payment hours. | Fora do horário de pagamento do convênio. |
| 400 | BIP000044 | Bad Request | It was not possible to pay the collection slip at this time. Please verify your information and, if necessary, contact us for assistance. | Não foi possível pagar a fatura de recolhimento neste momento. Por favor, verifique suas informações e, se necessário, entre em contato conosco para assistência. |
| 400 | BIP000045 | Bad Request | Collection slip payment service is closed. | Serviço de pagamento de fatura de recolhimento está fechado. |
| 404 | BIP000056 | Not Found | Payment not found. | Pagamento não encontrado. |
| 400 | BIP000057 | Bad Request | Payment status is not pending approval. | Status de pagamento não é de aprovação pendente. |
| 400 | BIP000058 | Bad Request | Error while validating verification token | Erro ao validar token de verificação |
| 400 | BIP000059 | Bad Request | Number of verification token validation attempts exceeded. | Número de tentativas de validação de token de verificação excedido. |
| 400 | BIP000060 | Bad Request | Verification token expired. | Token de verificação expirado. |
| 400 | BIP000061 | Bad Request | Verification token validation failed. | Falha na validação do token de verificação. |
| 400 | BIP000063 | Bad Request | Payment type is not collection slip. | Tipo de pagamento não é fatura de recolhimento. |
| 400 | BIP000065 | Bad Request | Payment verification time window exceeded. | Janela de tempo de verificação de pagamento excedida. |
---
# Confirm bank slip batch scheduling
URL: /en/documentation/baas/cobranca/2fa_v2/agendamento/confirmar_agendamento_em_lote_de_boleto_bancario
This endpoint allows validating the two-factor authentication (2FA) token for a bank slip scheduling batch in `batch_payment_schedule_status` **`pending_2fa_approval`**.
:::info Bank slip
A traditional bank slip (digitable line does not start with 8). It is registered in the Interbank Payment Chamber (CIP/Nuclea) and can be paid through financial and payment institutions authorized by the Central Bank.
:::
## Request
### Request Endpoint
ENDPOINT /bill_payment/account/ ACCOUNT_KEY /payment/schedule_bank_slip/ BATCH_PAYMENT_SCHEDULE_KEY /validate_token
METHOD PATCH
### Request Path Params
| Field | Type | Description | Characters |
| --------------------- | ----- | ---------------------------------------------------------------------------------------- | ---------- |
| `account_key` * | uuid4 | Unique account identifier key. | 36 |
| `batch_payment_schedule_key` * | uuid4 | Unique batch scheduling identifier key. | 36 |
Request Body: Batch scheduling token validation
```json
{
"token": "329adf"
}
```
### Body Params
| Field | Type | Description | Characters |
| ------- | ------ | ---------------------------------------------------------------------------------------------------------------- | ---------- |
| `token` | string | Authentication code sent to the account transaction approver | 6 |
## Response
### Success Response
STATUS 200
Response Body: Confirmed scheduling batch
```json
{
"batch_payment_schedule_key": "c4325104-d60b-44f3-aae4-49155564a2ea",
"request_control_key": "b6804f32-101e-4702-8fbc-c2dbc4c2caec",
"account_key": "6dc89d57-fac7-4643-b151-cd2ca0a7f68f",
"total_amount": 1357.3,
"batch_payment_schedule_status": "scheduled",
"payment_type": "bank_slip"
}
```
### Response Body Params
| Field | Type | Description |
| ----------------------- | ------ | --------- |
| `batch_payment_schedule_key` * | uuid4 | Unique batch scheduling identifier key. |
| `request_control_key` * | uuid4 | Unique client request identifier key (batch). |
| `account_key` * | uuid4 | Debited account key. |
| `total_amount` * | number | Sum of item amounts in the batch. |
| `batch_payment_schedule_status` * | [enum](#enumeradores-batch_payment_schedule_status) | Batch scheduling status after token validation. |
| `payment_type` * | string | Payment type; for this flow, expected value is `bank_slip`. |
### Enumerators batch_payment_schedule_status
| Enumerator | Description |
|---------------|---------------|
| `pending_2fa_approval` | Pending 2FA approval |
| `scheduled` | Scheduled |
| `rejected` | Rejected |
| `error` | Scheduling error |
### Error Response
STATUS 4XX
Response Body
```json
{
"title": "Title",
"description": "Description in English",
"translation": "Description in Portuguese",
"code": "Code"
}
```
| HTTP Code | QI Code | Title | Description (eng) | Description (pt-br) |
| ----------- | --------- | ----------- | --------------------------------------------- | ---------------------------------------------------------------- |
| 403 | BIP000010 | Forbidden | User is not allowed to do this action | User is not allowed to do this action |
| 404 | BIP000011 | Not Found | The source account key was not found. | The source account key was not found. |
| 400 | BIP000058 | Bad Request | Error while validating verification token | Error while validating verification token |
| 400 | BIP000059 | Bad Request | Number of verification token validation attempts exceeded. | Number of verification token validation attempts exceeded. |
| 400 | BIP000060 | Bad Request | Verification token expired. | Verification token expired. |
| 400 | BIP000061 | Bad Request | Verification token validation failed. | Verification token validation failed. |
| 400 | BIP000065 | Bad Request | Payment verification time window exceeded. | Payment verification time window exceeded. |
| 404 | BIP000083 | Not Found | Batch payment not found by batch payment key. | Batch payment not found by batch payment key. |
| 400 | BIP000085 | Bad Request | Batch payment status is not pending approval. | Batch payment status is not pending approval. |
| 400 | BIP000086 | Bad Request | A token is required for SMS or email validation. | A token is required for SMS or email validation. |
---
# Confirm collection slip batch scheduling
URL: /en/documentation/baas/cobranca/2fa_v2/agendamento/confirmar_agendamento_em_lote_de_fatura_de_recolhimento
This endpoint allows validar o token de autenticação de dois fatores (2FA) de um batch de scheduling de collection slips em `batch_payment_schedule_status` **`pending_2fa_approval`**.
:::info Fatura de recolhimento
Esse tipo de cobrança é emitido por concessionárias de serviços (account de água, luz, telefone e gás) e órgãos públicos (tributos). Eles não são registrados na Câmara Interbancária de Pagamento (CIP/Núclea), por isso, não retornam as mesmas informações que um Boleto bancário apresenta.
:::
## Request
### Request Endpoint
ENDPOINT /bill_payment/account/ ACCOUNT_KEY /payment/schedule_collection_slip/ BATCH_PAYMENT_SCHEDULE_KEY /validate_token
METHOD PATCH
### Request Path Params
| Field | Type | Description | Characters |
| --------------------- | ----- | ---------------------------------------------------------------------------------------- | ---------- |
| `account_key` * | uuid4 | Chave única de identificação da account. | 36 |
| `batch_payment_schedule_key` * | uuid4 | Chave única de identificação do batch de scheduling. | 36 |
Request Body: Validação de token do batch de scheduling
```json
{
"token": "329adf"
}
```
### Body Params
| Field | Type | Description | Characters |
| ------- | ------ | ---------------------------------------------------------------------------------------------------------------- | ---------- |
| `token` | string | Código de autenticação enviado ao aprovador de movimentações da account | 6 |
## Response
### Success Response
STATUS 200
Response Body: Batch de scheduling confirmado
```json
{
"batch_payment_schedule_key": "33860ad0-bcb0-47b7-bbe7-c7e3ec2fc61a",
"request_control_key": "ae4508df-f2cb-4e28-9f04-a19b7f2758c9",
"account_key": "daae79e6-ee8b-449f-aa1e-96959d5d5a72",
"total_amount": 1939.31,
"batch_payment_schedule_status": "scheduled",
"payment_type": "collection_slip"
}
```
### Response Body Params
| Field | Type | Description |
| ----------------------- | ------ | --------- |
| `batch_payment_schedule_key` * | uuid4 | Chave única de identificação do scheduling em batch. |
| `request_control_key` * | uuid4 | Chave única de identificação da request do cliente (batch). |
| `account_key` * | uuid4 | Chave da account debitada. |
| `total_amount` * | number | Soma dos valores dos itens do batch. |
| `batch_payment_schedule_status` * | [enum](#enumeradores-batch_payment_schedule_status) | Status do batch de scheduling após a validação do token. |
| `payment_type` * | string | Type do payment; para este fluxo, espera-se `collection_slip`. |
### Enumerators batch_payment_schedule_status
| Enumerator | Description |
|---------------|---------------|
| `pending_2fa_approval` | Pendente de aprovação 2FA |
| `scheduled` | Scheduled |
| `rejected` | Rejected |
| `error` | Scheduling error |
### Error Response
STATUS 4XX
Response Body
```json
{
"title": "Título",
"description": "Description in english",
"translation": "Description em português",
"code": "Código"
}
```
| Código HTTP | Código QI | Título | Description (eng) | Description (pt-br) |
| ----------- | --------- | ----------- | --------------------------------------------- | ---------------------------------------------------------------- |
| 403 | BIP000010 | Forbidden | User is not allowed to do this action | Usuário não tem autorização para fazer essa ação |
| 404 | BIP000011 | Not Found | The source account key was not found. | A chave da account de origem não foi encontrada. |
| 400 | BIP000058 | Bad Request | Error while validating verification token | Erro ao validar token de verificação |
| 400 | BIP000059 | Bad Request | Number of verification token validation attempts exceeded. | Número de tentativas de validação de token de verificação excedido. |
| 400 | BIP000060 | Bad Request | Verification token expired. | Token de verificação expirado. |
| 400 | BIP000061 | Bad Request | Verification token validation failed. | Falha na validação do token de verificação. |
| 400 | BIP000065 | Bad Request | Payment verification time window exceeded. | Janela de tempo de verificação de payment excedida. |
| 404 | BIP000083 | Not Found | Batch payment not found by batch payment key. | Batch de payments não encontrado pela chave do batch. |
| 400 | BIP000085 | Bad Request | Batch payment status is not pending approval. | Status do batch de payments não é de aprovação pendente. |
| 400 | BIP000086 | Bad Request | A token is required for SMS or email validation. | Um token é necessário para validação via SMS ou email. |
---
# Get payment scheduling batch
URL: /en/documentation/baas/cobranca/2fa_v2/agendamento/consultar_lote_de_agendamento_de_pagamento
This endpoint returns o resumo do batch de scheduling e a lista paginada dos schedulings que o compõem (bank slips ou collection slips).
Para localizar `batch_payment_schedule_key`, utilize [List batchs de scheduling de payment](./listar_batchs_de_scheduling_de_payment.md).
:::info Boleto bancário
É o bank slip convencional (linhas digitáveis não iniciadas com dígito 8). Possui registro na Câmara Interbancária de Pagamento (CIP/Núclea) e pode ser pago em instituições financeiras e de payment autorizadas a funcionar pelo Banco Central.
:::
:::info Fatura de recolhimento
Esse tipo de cobrança é emitido por concessionárias de serviços (account de água, luz, telefone e gás) e órgãos públicos (tributos). Eles não são registrados na Câmara Interbancária de Pagamento (CIP/Núclea), por isso, não retornam as mesmas informações que um Boleto bancário apresenta.
:::
## Request
### Request Endpoint
ENDPOINT /bill_payment/account/ ACCOUNT_KEY /schedule/ BATCH_PAYMENT_SCHEDULE_KEY
METHOD GET
### Request Path Params
| Field | Type | Description | Characters |
|-----------------------------|-------|----------------------------------------------------|------------|
| `account_key` * | uuid4 | Chave única de identificação da account. | 36 |
| `batch_payment_schedule_key` * | uuid4 | Chave única de identificação do batch de scheduling. | 36 |
### Request Query String Params
| Field | Type | Description |
|-------------|--------|-------------------------------------------------------------------------------|
| `page` | string | Número da página dos itens em `payment_schedules.data`. 1 por padrão. |
| `page_size` | string | Tamanho da página dos itens em `payment_schedules.data`. 30 por padrão e valor máximo. |
## Response
### Success Response
STATUS 200
Response Body: Detalhes do batch de scheduling
```json
{
"request_control_key": "b6804f32-101e-4702-8fbc-c2dbc4c2caec",
"total_scheduled": 10,
"total_pending": 0,
"total_error": 0,
"total_amount": 1357.3,
"batch_payment_schedule_status": "scheduled",
"payment_schedules": {
"pagination": {
"current_page": 1,
"rows_per_page": 30
},
"date": [
{
"payment_schedule_key": "c4325104-d60b-44f3-aae4-49155564a2ea",
"request_control_key": "b713b2f6-2f48-4d18-b0c9-7186e4edf189",
"payer_name": "COOPERATIVA INDUSTRIAL MURILO",
"payer_document_number": "00037025000160",
"source_account_key": "6dc89d57-fac7-4643-b151-cd2ca0a7f68f",
"paid_amount": 1050.1,
"payment_date": "2024-04-03",
"payment_type": "bank_slip",
"bank_slip": {
"bank_slip_key": "95080ffd-3ac5-48d7-b3fe-659e4aaba81a",
"barcode": "00193967000009910000000003615574000000002417",
"digitable_line": "00190000090361557400500000024174396700000991000",
"payer_name": "COOPERATIVA TESTE",
"payer_document_number": "00037025000160",
"beneficiary_name": "TESTE EQUIPAMENTOS E SERVICOS LTDA",
"beneficiary_trading_name": "TESTE EQUIPAMENTOS E SERVICOS LTDA",
"beneficiary_document_number": "52069937000117",
"beneficiary_bank_ispb": "00000000",
"guarantor_name": null,
"guarantor_document_number": null,
"expiration_date": "2024-03-29",
"max_payment_date": "2026-03-29",
"partial_payment_indicator": "allowed",
"registered_payment_amount": 9029.0,
"nominal_amount": 9910.0,
"total_amount": 10129.1,
"rebate_amount": 0.0,
"discount_amount": 0.0,
"fine_amount": 0.0,
"interest_amount": 219.1
},
"collection_slip": null,
"payment_schedule_status": "scheduled",
"error_reason": null
}
]
}
}
```
### Response Body Params
| Field | Type | Description |
|--------------------------------|------------------------------------------|---------------------------------------------------------------|
| `request_control_key` * | uuid4 | Chave única de identificação da request do cliente (batch). |
| `total_scheduled` * | int | Quantidade de itens do batch agendados com sucesso. |
| `total_pending` * | int | Quantidade de itens ainda pendentes no batch. |
| `total_error` * | int | Quantidade de itens com erro no batch. |
| `total_amount` * | number | Valor total do batch. |
| `batch_payment_schedule_status` * | [enum](#enumeradores-batch_payment_schedule_status) | Status do batch de scheduling. |
| `payment_schedules` * | [object](#objeto-payment_schedules) | Lista paginada dos schedulings do batch. |
### Object payment_schedules
| Field | Type | Description |
|----------------|------------------------------|----------------------------------------------------------|
| `pagination` * | [object](#objeto-pagination) | Paginação da lista de schedulings do batch. |
| `date` * | array | Itens do batch (schedulings individuais). |
Cada elemento de `payment_schedules.data` contém:
| Field | Type | Description |
|--------------------------|--------------------------------------|--------------------------------------------------------------------------------|
| `payment_schedule_key` * | uuid4 | Chave única de identificação do scheduling. |
| `request_control_key` * | uuid4 | Chave única de identificação da request do cliente para o item do batch. |
| `payer_name` * | string | Nome do pagador efetivo. |
| `payer_document_number` *| string | Número de documento do pagador efetivo (CPF/CNPJ). |
| `source_account_key` * | uuid4 | Chave da account debitada. |
| `paid_amount` * | number | Valor agendado para payment. |
| `payment_date` * | string | Data do scheduling. |
| `payment_type` * | [enum](#enumeradores-payment_type) | Type do payment. |
| `bank_slip` | [object](#objeto-bank_slip) | Boleto bancário. Pode ser `null` quando `payment_type` for `collection_slip`. |
| `collection_slip` | [object](#objeto-collection_slip) | Fatura de recolhimento. Pode ser `null` quando `payment_type` for `bank_slip`.|
| `payment_schedule_status` * | [enum](#enumeradores-payment_schedule_status) | Status do scheduling. |
| `error_reason` | string | Motivo do erro, quando aplicável; caso contrário `null`. |
### Object pagination
| Field | Type | Description |
|------------------|------|-------------------------------------|
| `current_page` * | int | Página atual retornada. |
| `rows_per_page` *| int | Quantidade de registros por página. |
### Enumerators payment_type
| Enumerator | Description |
|-------------------|------------------------|
| `bank_slip` | Boleto bancário |
| `collection_slip` | Fatura de recolhimento |
### Enumerators payment_schedule_status
| Enumerator | Description |
|------------------------|------------------------------------------------------------------|
| `pending_2fa_approval` | Scheduling pendente de autenticação de dois fatores (2FA) |
| `scheduled` | Pagamento agendado com sucesso |
| `executed` | O scheduling foi executado com sucesso e o payment foi gerado |
| `rejected` | O scheduling foi rejeitado e nenhum payment foi gerado |
| `canceled` | Scheduling cancelado |
| `error` | Erro ao realizar o scheduling |
### Enumerators batch_payment_schedule_status
| Enumerator | Description |
|------------------------|---------------------------|
| `pending_2fa_approval` | Pendente de aprovação 2FA |
| `scheduled` | Scheduled |
| `rejected` | Rejected |
| `canceled` | Canceled |
| `error` | Scheduling error |
### Object bank_slip
| Field | Type | Description |
|--------------------------------|-------------------------------------------------|-----------------------------------------------------|
| `bank_slip_key` * | uuid4 | Chave única de identificação do bank slip. |
| `barcode` * | string | Código de barras. |
| `digitable_line` * | string | Linha digitável. |
| `payer_name` * | string | Nome do pagador. |
| `payer_document_number` * | string | Número de documento do pagador (CPF/CNPJ). |
| `beneficiary_name` * | string | Nome do beneficiário. |
| `beneficiary_trading_name` | string | Nome fantasia do beneficiário. |
| `beneficiary_document_number` *| string | Número de documento do beneficiário (CPF/CNPJ). |
| `beneficiary_bank_ispb` * | string | Código ispb do banco do beneficiário. |
| `guarantor_name` | string | Nome do sacador avalista. |
| `guarantor_document_number` | string | Número de documento do sacador avalista (CPF/CNPJ). |
| `expiration_date` * | string | Data de vencimento. |
| `max_payment_date` * | string | Data máxima de payment. |
| `partial_payment_indicator` * | [enum](#enumeradores-partial_payment_indicator) | Indicador de payment parcial. |
| `registered_payment_amount` | number | Valor total de payment registrado. |
| `nominal_amount` * | number | Valor original. |
| `total_amount` * | number | Valor total. |
| `rebate_amount` * | number | Valor do abatimento. |
| `discount_amount` * | number | Valor do desconto. |
| `fine_amount` * | number | Valor da multa. |
| `interest_amount` * | number | Valor dos juros. |
### Enumerators partial_payment_indicator
| Enumerator | Description |
|---------------|---------------|
| `allowed` | Permitido |
| `not_allowed` | Não permitido |
### Object collection_slip
| Field | Type | Description |
|--------------------------------|--------|---------------------------------------------|
| `barcode` * | string | Código de barras. |
| `digitable_line` * | string | Linha digitável. |
| `collection_name` * | string | Nome do convênio. |
| `collection_document_number` * | string | Número de documento do convênio (CPF/CNPJ). |
| `expiration_date` * | string | Data de vencimento. |
| `total_amount` * | number | Valor total. |
### Error Response
STATUS 4XX
Response Body
```json
{
"title": "Título",
"description": "Description in english",
"translation": "Description em português",
"code": "Código"
}
```
| Código HTTP | Código QI | Título | Description (eng) | Description (pt-br) |
|-------------|-----------|-------------|-----------------------------------------------------------------|----------------------------------------------------------------|
| 400 | BIP000027 | Bad Request | Invalid integer value for page or size query string parameters. | Valor inválido para parâmetros de página ou tamanho de página. |
| 404 | BIP000083 | Not Found | Batch payment not found by batch payment key. | Batch de payments não encontrado pela chave do batch. |
---
# List payment scheduling batches
URL: /en/documentation/baas/cobranca/2fa_v2/agendamento/listar_lotes_de_agendamento_de_pagamento
This endpoint returns os batchs de scheduling de payments de bank slips e collection slips associados à account, com suporte a filtros e paginação.
:::info Boleto bancário
É o bank slip convencional (linhas digitáveis não iniciadas com dígito 8). Possui registro na Câmara Interbancária de Pagamento (CIP/Núclea) e pode ser pago em instituições financeiras e de payment autorizadas a funcionar pelo Banco Central.
:::
:::info Fatura de recolhimento
Esse tipo de cobrança é emitido por concessionárias de serviços (account de água, luz, telefone e gás) e órgãos públicos (tributos). Eles não são registrados na Câmara Interbancária de Pagamento (CIP/Núclea), por isso, não retornam as mesmas informações que um Boleto bancário apresenta.
:::
## Request
### Request Endpoint
ENDPOINT /bill_payment/account/ ACCOUNT_KEY /schedules
METHOD GET
### Request Path Params
| Field | Type | Description | Characters |
|---------------------|---------|-----------------------------------------|------------|
| `account_key` * | uuid4 | Chave única de identificação da account. | 36 |
### Request Query String Params
| Field | Type | Description |
|--------------------------------|-------------|-----------------------------------|
| `request_control_key` | uuid4 | Chave única de identificação da request do cliente (batch). |
| `batch_payment_schedule_key` | uuid4 | Chave única de identificação do batch de scheduling. |
| `payment_type` | [enum](#enumeradores-payment_type) | Type do payment do batch. |
| `batch_payment_schedule_status`| [enum](#enumeradores-batch_payment_schedule_status) | Status do batch de scheduling. |
| `date_from` | string | Data inicial. Formato `YYYY-MM-DD`. |
| `date_to` | string | Data final. Formato `YYYY-MM-DD`. |
| `page` | string | Número da página requisitada. 1 por padrão. |
| `page_size` | string | Tamanho da página requisitada na consulta. 30 por padrão e valor máximo. |
### Enumerators payment_type
| Enumerator | Type | Description |
|-------------------|--------|------------------------|
| `bank_slip` | string | Boleto bancário |
| `collection_slip` | string | Fatura de recolhimento |
### Enumerators batch_payment_schedule_status
| Enumerator | Description |
|------------------------|------------------------------------|
| `pending_2fa_approval` | Pendente de aprovação 2FA |
| `scheduled` | Scheduled |
| `rejected` | Rejected |
| `canceled` | Canceled |
| `error` | Scheduling error |
## Response
### Success Response
STATUS 200
Response Body: Listagem de batchs de scheduling
```json
{
"pagination": {
"current_page": 1,
"rows_per_page": 30
},
"date": [
{
"batch_payment_schedule_key": "a3214093-e51c-55e2-b5d3-60244475b3fb",
"request_control_key": "b6804f32-101e-4702-8fbc-c2dbc4c2caec",
"batch_payment_schedule_status": "scheduled",
"payment_type": "bank_slip",
"total_scheduled": 10,
"total_pending": 0,
"total_error": 0,
"total_amount": 1357.3
}
]
}
```
### Response Body Params
| Field | Type | Description |
|---------------------|---------|-----------------------------------|
| `pagination` * | [object](#objeto-pagination) | Informações de paginação da consulta. |
| `date` * | array | Lista de batchs encontrados. |
Cada elemento de `date` contém:
| Field | Type | Description |
|---------------------------------|---------|-----------------------------------|
| `batch_payment_schedule_key` * | uuid4 | Chave única de identificação do batch de scheduling. |
| `request_control_key` * | uuid4 | Chave única de identificação da request do cliente (batch). |
| `batch_payment_schedule_status` * | [enum](#enumeradores-batch_payment_schedule_status-1) | Status atual do batch de scheduling. |
| `payment_type` * | [enum](#enumeradores-payment_type-1) | Type do payment do batch. |
| `total_scheduled` * | int | Quantidade de itens do batch agendados com sucesso. |
| `total_pending` * | int | Quantidade de itens ainda pendentes no batch. |
| `total_error` * | int | Quantidade de itens com erro no batch. |
| `total_amount` * | number | Valor total do batch. |
### Object pagination
| Field | Type | Description |
|---------------------|---------|-----------------------------------|
| `current_page` * | int | Página atual retornada. |
| `rows_per_page` * | int | Quantidade de registros por página. |
### Enumerators payment_type
| Enumerator | Description |
|-------------------|------------------------|
| `bank_slip` | Boleto bancário |
| `collection_slip` | Fatura de recolhimento |
### Enumerators batch_payment_schedule_status
| Enumerator | Description |
|------------------------|---------------------------|
| `pending_2fa_approval` | Pendente de aprovação 2FA |
| `scheduled` | Scheduled |
| `rejected` | Rejected |
| `canceled` | Canceled |
| `error` | Scheduling error |
### Error Response
STATUS 4XX
Response Body
```json
{
"title": "Título",
"description": "Description in english",
"translation": "Description em português",
"code": "Código"
}
```
| Código HTTP | Código QI | Título | Description (eng) | Description (pt-br) |
|-------------|-----------|--------|------------------|------------------|
| 400 | BIP000026 | Bad Request | Invalid payment date format. The correct format is YYYY-MM-DD. | Formato de date de payment inválido. O formato correto é YYYY-MM-DD. |
| 400 | BIP000027 | Bad Request | Invalid integer value for page or size query string parameters. | Valor inválido para parâmetros de página ou tamanho de página. |
| 400 | BIP000047 | Bad Request | Invalid payment type. | Type de payment inválido. |
---
# Reenviar Token Autenticação de Dois Fatores de Agendamento de Boleto Bancário
URL: /en/documentation/baas/cobranca/2fa_v2/agendamento/reenviar_token_de_agendamento_boleto_bancario
Este endpoint permite realizar o reenvio do token de autenticação de agendamento de Boletos Bancários.
:::info Boleto bancário
É o boleto bancário convencional (linhas digitáveis não iniciadas com dígito 8). Possui registro na Câmara Interbancária de Pagamento (CIP/Núclea) e pode ser pago em instituições financeiras e de pagamento autorizadas a funcionar pelo Banco Central.
:::
## Request
ENDPOINT /account/ ACCOUNT_KEY /payment_schedule/ PAYMENT_SCHEDULE_KEY /bank_slip/resend_token
MÉTODO PATCH
### Request Path Params
| Campo | Tipo | Descrição | Caracteres |
|---------------------|---------|-----------------------------------------|------------|
| `account_key` * | uuid4 | Chave única de identificação da conta. | 36 |
| `payment_schedule_key` * | uuid4 | Chave única de identificação do agendamento. | 36 |
## Response
### Success Response
STATUS 200
Response Body: Token reenviado com sucesso
```json
{
"payment_key":"c4325104-d60b-44f3-aae4-49155564a2ea",
"request_control_key":"b713b2f6-2f48-4d18-b0c9-7186e4edf189",
"payer_name":"COOPERATIVA INDUSTRIAL MURILO",
"payer_document_number":"00037025000160",
"source_account_key":"6dc89d57-fac7-4643-b151-cd2ca0a7f68f",
"paid_amount":1050.1,
"payment_date":"2024-04-03",
"payment_type":"bank_slip",
"bank_slip": {
"bank_slip_key":"95080ffd-3ac5-48d7-b3fe-659e4aaba81a",
"barcode":"00193967000009910000000003615574000000002417",
"digitable_line":"00190000090361557400500000024174396700000991000",
"payer_name":"COOPERATIVA TESTE",
"payer_document_number":"00037025000160",
"beneficiary_name":"TESTE EQUIPAMENTOS E SERVICOS LTDA",
"beneficiary_trading_name":"TESTE EQUIPAMENTOS E SERVICOS LTDA",
"beneficiary_document_number":"52069937000117",
"beneficiary_bank_ispb":"00000000",
"guarantor_name":null,
"guarantor_document_number":null,
"expiration_date":"2024-03-29",
"max_payment_data": "2026-03-29",
"partial_payment_indicator":"allowed",
"registered_payment_amount":9029.0,
"nominal_amount":9910.0,
"total_amount":10129.1,
"rebate_amount":0.0,
"discount_amount":0.0,
"fine_amount":0.0,
"interest_amount":219.1
},
"collection_slip":null,
"payment_schedule_status":"pending_2fa_approval"
}
```
### Response Body Params
| Campo | Tipo | Descrição |
|---------------------|---------|-----------------------------------------------------|
| `payment_key` * | uuid4 | Chave única de identificação do pagamento. |
| `request_control_key` * | uuid4 | Chave única de identificação da request do cliente. |
| `payer_name` * | string | Nome do pagador efetivo. |
| `payer_document_number` * | string | Número documento do pagador efetivo (CPF/CNPJ). |
| `source_account_key` * | uuid4 | Chave da conta debitada. |
| `transaction_key` * | uuid4 | Chave da transação do pagamento. |
| `transaction_revert_key` | uuid4 | Chave da transação de reversão do pagamento. |
| `paid_amount` * | number | Valor pago efetivamente. |
| `payment_date` * | string | Data do pagamento. |
| `payment_type` * | [enum](#enumeradores-payment_type) | Tipo do pagamento. |
| `bank_slip` | [object](#object-bank_slip) | Boleto bancário. |
| `collection_slip` | object | Fatura de recolhimento. |
| `payment_schedule_status` * | [enum](#enumeradores-payment_schedule_status) | Status do agendamento. |
### Enumeradores payment_type
| Enumerador | Tipo | Descrição |
|---------------|-----------|---------------|
| `bank_slip` | string | Boleto bancário |
| `collection_slip` | string | Fatura de recolhimento |
:::danger Aviso
O enumerador `collection_slip` não se aplica para o fluxo de boletos bancários, assim como o objeto collection_slip que sempre será nulo.
:::
### Enumeradores payment_schedule_status
| Enumerador | Tipo | Descrição |
|---------------|-----------|---------------|
| `pending_2fa_approval` | string | pendente de aprovação de dois fatores |
### Object bank_slip
| Campo | Tipo | Descrição |
|-----------------------------------|---------|-----------------------------------|
| `barcode` * | string | Código de barras. |
| `digitable_line` * | string | Linha digitável. |
| `payer_name` * | string | Nome do pagador.|
| `payer_document_number` * | string | Número de documento do pagador (CPF/CNPJ). |
| `beneficiary_name` * | string | Nome do beneficiário. |
| `beneficiary_trading_name` | string | Nome fantasia do beneficiário. |
| `beneficiary_document_number` * | string | Número de documento do beneficiário (CPF/CNPJ). |
| `beneficiary_bank_ispb` * | string | Código ispb do banco do beneficiário. |
| `guarantor_name` | string | Nome do sacador avalista. |
| `guarantor_document_number` | string | Número de documento do sacador avalista (CPF/CNPJ). |
| `expiration_date` * | string | Data de vencimento. |
| `max_payment_date` * | string | Data máxima de pagamento. |
| `partial_payment_indicator` * | [enum](#enumeradores-partial_payment_indicator) | Indicador de pagamento parcial. |
| `registered_payment_amount` | string | Valor total de pagamento registrado. |
| `nominal_amount` * | number | Valor original. |
| `total_amount` * | number | Valor total. |
| `rebate_amount` * | number | Valor do abatimento. |
| `discount_amount` * | number | Valor do desconto. |
| `fine_amount` * | number | Valor da multa. |
| `interest_amount` * | number | Valor do juros. |
### Enumeradores partial_payment_indicator
| Enumerador | Tipo | Descrição |
|---------------|-----------|---------------|
| `allowed` | string | Permitido |
| `not_allowed` | string | Não permitido |
### Error Response
STATUS 4XX
Response Body
```json
{
"title": "Título",
"description": "Description in english",
"translation": "Descrição em português",
"code": "Código"
}
```
| Código HTTP | Código QI | Título | Descrição (eng) | Descrição (pt-br) |
|-------------|-----------|--------|------------------|------------------|
| 403 | BIP000010 | Forbidden | User is not allowed to do this action | Usuário não tem autorização para fazer essa ação |
| 404 | BIP000011 | Not Found | The source account key was not found. | A chave da conta de origem não foi encontrada. |
| 400 | BIP000012 | Bad Request | It 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. |
| 400 | BIP000013 | Bad Request | The source account is closed. | A conta de origem está fechada. |
| 400 | BIP000014 | Bad Request | The source account is blocked. | A conta de origem está bloqueada. |
| 404 | BIP000056 | Not Found | Payment not found. | Pagamento não encontrado. |
| 400 | BIP000057 | Bad Request | Payment status is not pending approval. | Status de pagamento não é de aprovação pendente. |
| 400 | BIP000062 | Bad Request | Payment type is not bank slip. | Tipo de pagamento não é boleto. |
| 400 | BIP000064 | Bad Request | Error resending verification token | Erro ao reenviar token de verificação |
| 400 | BIP000065 | Bad Request | Payment verification time window exceeded. | Janela de tempo de verificação de pagamento excedida. |
---
# Reenviar Token Autenticação de Dois Fatores de Agendamento de Fatura de Recolhimento
URL: /en/documentation/baas/cobranca/2fa_v2/agendamento/reenviar_token_de_agendamento_de_fatura_de_recolhimento
Este endpoint permite realizar o reenvio do token de autenticação de agendamento de Faturas de Recolhimento.
:::info Fatura de recolhimento
Esse tipo de cobrança é emitido por concessionárias de serviços (conta de água, luz, telefone e gás) e órgão públicos (tributos). Eles não são registrados na Câmara Interbancária de Pagamento (CIP/Núclea), por isso, não retornam as mesmas informações que um Boleto bancário apresenta.
:::
## Request
ENDPOINT /account/ ACCOUNT_KEY /payment_schedule/ PAYMENT_SCHEDULE_KEY /collection_slip/resend_token
MÉTODO PATCH
### Request Path Params
| Campo | Tipo | Descrição | Caracteres |
|---------------------|---------|-----------------------------------------|------------|
| `account_key` * | uuid4 | Chave única de identificação da conta. | 36 |
| `payment_schedule_key` * | uuid4 | Chave única de identificação do agendamento. | 36 |
## Response
### Success Response
STATUS 200
Response Body: Token reenviado com sucesso
```json
{
"payment_schedule_key": "33860ad0-bcb0-47b7-bbe7-c7e3ec2fc61a",
"request_control_key": "ae4508df-f2cb-4e28-9f04-a19b7f2758c9",
"payer_name": "COOPERATIVA INDUSTRIAL MURILO",
"payer_document_number": "62069937000118",
"source_account_key": "daae79e6-ee8b-449f-aa1e-96959d5d5a72",
"paid_amount": 1389.21,
"payment_date": "2024-04-30",
"payment_type": "collection_slip",
"bank_slip": null,
"collection_slip": {
"barcode": null,
"digitable_line": "836200000138892100450006762142420244046000010192",
"collection_name": "CIA ULTRAGAZ SA-COD",
"collection_document_number": "00394460005887",
"expiration_date": "2024-04-15",
"total_amount": 1389.21
},
"payment_schedule_status": "pending_2fa_approval"
}
```
### Response Body Params
| Campo | Tipo | Descrição |
|---------------------|---------|-----------------------------------|
| `payment_key` * | uuid4 | Chave única de identificação do pagamento. |
| `request_control_key` * | uuid4 | Chave única de identificação da request do cliente. |
| `payer_name` * | string | Nome do pagador efetivo.|
| `payer_document_number` * | string | Número de documento do pagador efetivo (CPF/CNPJ). |
| `source_account_key` * | uuid4 | Chave da conta debitada. |
| `transaction_key` * | uuid4 | Chave da transação do pagamento. |
| `transaction_revert_key` | uuid4 | Chave da transação de reversão do pagamento. |
| `paid_amount` * | number | Valor pago efetivamente. |
| `payment_date` * | string | Data do pagamento. |
| `payment_type` * | [enum](#enumeradores-payment_type) | Tipo do pagamento. |
| `bank_slip` | object | Boleto bancário. |
| `collection_slip` | [object](#objeto-collection_slip) | Fatura de recolhimento. |
| `payment_schedule_status` * | [enum](#enumeradores-payment_schedule_status) | Status do pagamento. |
### Enumeradores payment_type
| Enumerador | Tipo | Descrição |
|---------------|-----------|---------------|
| `bank_slip` | string | Boleto bancário |
| `collection_slip` | string | Fatura de recolhimento |
:::danger Aviso
O enumerador `bank_slip` não se aplica para o fluxo de faturas de recolhimento, assim como o objeto bank_slip que sempre será nulo.
:::
### Enumeradores payment_schedule_status
| Enumerador | Tipo | Descrição |
|---------------|-----------|---------------|
| `pending_2fa_approval` | string | pendente de aprovação de dois fatores |
### Objeto collection_slip
| Campo | Tipo | Descrição |
|-----------------------------------|---------|-----------------------------------|
| `barcode` | string | Código de barras. |
| `digitable_line` | string | Linha digitável. |
| `collection_name` * | string | Nome do convênio.|
| `collection_document_number` | string | Número de documento do convênio (CPF/CNPJ).|
| `expiration_date` * | string | Data de vencimento. |
| `total_amount` * | number | Valor total. |
### Error Response
STATUS 4XX
Response Body
```json
{
"title": "Título",
"description": "Description in english",
"translation": "Descrição em português",
"code": "Código"
}
```
| Código HTTP | Código QI | Título | Descrição (eng) | Descrição (pt-br) |
|-------------|-----------|--------|------------------|------------------|
| 403 | BIP000010 | Forbidden | User is not allowed to do this action | Usuário não tem autorização para fazer essa ação |
| 404 | BIP000011 | Not Found | The source account key was not found. | A chave da conta de origem não foi encontrada. |
| 400 | BIP000012 | Bad Request | It 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. |
| 400 | BIP000013 | Bad Request | The source account is closed. | A conta de origem está fechada. |
| 400 | BIP000014 | Bad Request | The source account is blocked. | A conta de origem está bloqueada. |
| 404 | BIP000056 | Not Found | Payment not found. | Pagamento não encontrado. |
| 400 | BIP000057 | Bad Request | Payment status is not pending approval. | Status de pagamento não é de aprovação pendente. |
| 400 | BIP000063 | Bad Request | Payment type is not collection slip. | Tipo de pagamento não é fatura de recolhimento. |
| 400 | BIP000064 | Bad Request | Error resending verification token | Erro ao reenviar token de verificação |
| 400 | BIP000065 | Bad Request | Payment verification time window exceeded. | Janela de tempo de verificação de pagamento excedida. |
---
# Resend token for bank slip batch scheduling
URL: /en/documentation/baas/cobranca/2fa_v2/agendamento/reenviar_token_de_agendamento_em_lote_de_boleto_bancario
This endpoint allows resending the two-factor authentication (2FA) token for a bank slip scheduling batch currently in `batch_payment_schedule_status` **`pending_2fa_approval`**.
:::info Bank slip
A traditional bank slip (digitable line does not start with 8). It is registered in the Interbank Payment Chamber (CIP/Nuclea) and can be paid through financial and payment institutions authorized by the Central Bank.
:::
## Request
### Request Endpoint
ENDPOINT /bill_payment/account/ ACCOUNT_KEY /payment/schedule_bank_slip/ BATCH_PAYMENT_SCHEDULE_KEY /resend_token
METHOD PATCH
### Request Path Params
| Field | Type | Description | Characters |
| --------------------- | ----- | ---------------------------------------------------------------------------------------- | ---------- |
| `account_key` * | uuid4 | Unique account identifier key. | 36 |
| `batch_payment_schedule_key` * | uuid4 | Unique batch scheduling identifier key. | 36 |
### Request Body
Request Body (optional)
```json
{
"contact_type": "sms"
}
```
### Body Params
| Field | Type | Description | Characters |
| -------------- | ---------- | --------------------------------------- | ------------------------------------------------------- |
| `contact_type` | enumerator | Authentication token delivery channel | **[Enumerator contact_type](#enumerador-contact_type)** |
:::info Information
If `contact_type` is not sent, the token will be delivered using the channel originally requested in the batch scheduling (`tfa_info.contact_type`).
:::
### Enumerator contact_type
| Enumerator | Description |
| ---------- | ------------------------------------------------- |
| **sms** | Send token via SMS |
| **email** | Send token via email |
## Response
### Success Response
STATUS 200
Response Body: Token resent successfully
```json
{
"batch_payment_schedule_key": "c4325104-d60b-44f3-aae4-49155564a2ea",
"request_control_key": "b6804f32-101e-4702-8fbc-c2dbc4c2caec",
"account_key": "6dc89d57-fac7-4643-b151-cd2ca0a7f68f",
"total_amount": 1357.3,
"batch_payment_schedule_status": "pending_2fa_approval",
"payment_type": "bank_slip"
}
```
### Response Body Params
| Field | Type | Description |
| ----------------------- | ------ | --------- |
| `batch_payment_schedule_key` * | uuid4 | Unique batch scheduling identifier key. |
| `request_control_key` * | uuid4 | Unique client request identifier key (batch). |
| `account_key` * | uuid4 | Debited account key. |
| `total_amount` * | number | Sum of item amounts in the batch. |
| `batch_payment_schedule_status` * | string | After resend, the batch remains waiting for token validation (`pending_2fa_approval`). |
| `payment_type` * | string | Payment type; for this flow, expected value is `bank_slip`. |
Then use [Confirm bank slip batch scheduling](./confirmar_agendamento_em_lote_de_boleto_bancario.md) to complete 2FA.
### Error Response
STATUS 4XX
Response Body
```json
{
"title": "Title",
"description": "Description in English",
"translation": "Description in Portuguese",
"code": "Code"
}
```
| HTTP Code | QI Code | Title | Description (eng) | Description (pt-br) |
| ----------- | --------- | ----------- | -------------------------------------------------------------------------------------------------- | --------------------------------------------------------------------------------------------------------- |
| 403 | BIP000010 | Forbidden | User is not allowed to do this action | User is not allowed to do this action |
| 404 | BIP000011 | Not Found | The source account key was not found. | The source account key was not found. |
| 400 | BIP000012 | Bad Request | It was not possible to consult the source account at this time. Please try again in a few minutes. | It was not possible to consult the source account at this time. Please try again in a few minutes. |
| 400 | BIP000059 | Bad Request | Number of verification token validation attempts exceeded. | Number of verification token validation attempts exceeded. |
| 400 | BIP000064 | Bad Request | Error resending verification token | Error resending verification token |
| 400 | BIP000065 | Bad Request | Payment verification time window exceeded. | Payment verification time window exceeded. |
| 404 | BIP000083 | Not Found | Batch payment not found by batch payment key. | Batch payment not found by batch payment key. |
| 400 | BIP000085 | Bad Request | Batch payment status is not pending approval. | Batch payment status is not pending approval. |
---
# Resend token for collection slip batch scheduling
URL: /en/documentation/baas/cobranca/2fa_v2/agendamento/reenviar_token_de_agendamento_em_lote_de_fatura_de_recolhimento
This endpoint allows **reenviar** o token de autenticação de dois fatores (2FA) para um batch de scheduling de collection slips que esteja em `batch_payment_schedule_status` **`pending_2fa_approval`**.
:::info Fatura de recolhimento
Esse tipo de cobrança é emitido por concessionárias de serviços (account de água, luz, telefone e gás) e órgãos públicos (tributos). Eles não são registrados na Câmara Interbancária de Pagamento (CIP/Núclea), por isso, não retornam as mesmas informações que um Boleto bancário apresenta.
:::
## Request
### Request Endpoint
ENDPOINT /bill_payment/account/ ACCOUNT_KEY /payment/schedule_collection_slip/ BATCH_PAYMENT_SCHEDULE_KEY /resend_token
METHOD PATCH
### Request Path Params
| Field | Type | Description | Characters |
| --------------------- | ----- | ---------------------------------------------------------------------------------------- | ---------- |
| `account_key` * | uuid4 | Chave única de identificação da account. | 36 |
| `batch_payment_schedule_key` * | uuid4 | Chave única de identificação do batch de scheduling. | 36 |
### Request Body
Request Body (opcional)
```json
{
"contact_type": "sms"
}
```
### Body Params
| Field | Type | Description | Characters |
| -------------- | ---------- | --------------------------------------- | ------------------------------------------------------- |
| `contact_type` | enumerator | Forma de envio do token de autenticação | **[Enumerator contact_type](#enumerador-contact_type)** |
:::info Information
Caso não seja enviado um `contact_type`, o token será enviado da forma solicitada originalmente no scheduling do batch (`tfa_info.contact_type`).
:::
### Enumerator contact_type
| Enumerator | Description |
| ---------- | ------------------------------------------------- |
| **sms** | Envio por mensagem de texto para telefone celular |
| **email** | Envio por correio eletrônico |
## Response
### Success Response
STATUS 200
Response Body: Token resent successfully
```json
{
"batch_payment_schedule_key": "33860ad0-bcb0-47b7-bbe7-c7e3ec2fc61a",
"request_control_key": "ae4508df-f2cb-4e28-9f04-a19b7f2758c9",
"account_key": "daae79e6-ee8b-449f-aa1e-96959d5d5a72",
"total_amount": 1939.31,
"batch_payment_schedule_status": "pending_2fa_approval",
"payment_type": "collection_slip"
}
```
### Response Body Params
| Field | Type | Description |
| ----------------------- | ------ | --------- |
| `batch_payment_schedule_key` * | uuid4 | Chave única de identificação do scheduling em batch. |
| `request_control_key` * | uuid4 | Chave única de identificação da request do cliente (batch). |
| `account_key` * | uuid4 | Chave da account debitada. |
| `total_amount` * | number | Soma dos valores dos itens do batch. |
| `batch_payment_schedule_status` * | string | Após o reenvio, o batch permanece aguardando validação do token (`pending_2fa_approval`). |
| `payment_type` * | string | Type do payment; para este fluxo, espera-se `collection_slip`. |
In sequence, use [Confirm scheduling em batch de collection slip](./confirmar_scheduling_em_batch_de_fatura_de_recolhimento.md) para concluir o 2FA.
### Error Response
STATUS 4XX
Response Body
```json
{
"title": "Título",
"description": "Description in english",
"translation": "Description em português",
"code": "Código"
}
```
| Código HTTP | Código QI | Título | Description (eng) | Description (pt-br) |
| ----------- | --------- | ----------- | -------------------------------------------------------------------------------------------------- | --------------------------------------------------------------------------------------------------------- |
| 403 | BIP000010 | Forbidden | User is not allowed to do this action | Usuário não tem autorização para fazer essa ação |
| 404 | BIP000011 | Not Found | The source account key was not found. | A chave da account de origem não foi encontrada. |
| 400 | BIP000012 | Bad Request | It 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 account de origem neste momento. Por favor, tente novamente em alguns minutos. |
| 400 | BIP000059 | Bad Request | Number of verification token validation attempts exceeded. | Número de tentativas de validação de token de verificação excedido. |
| 400 | BIP000064 | Bad Request | Error resending verification token | Erro ao reenviar token de verificação |
| 400 | BIP000065 | Bad Request | Payment verification time window exceeded. | Janela de tempo de verificação de payment excedida. |
| 404 | BIP000083 | Not Found | Batch payment not found by batch payment key. | Batch de payments não encontrado pela chave do batch. |
| 400 | BIP000085 | Bad Request | Batch payment status is not pending approval. | Status do batch de payments não é de aprovação pendente. |
---
# Solicitar Agendamento de Pagamento de Boleto Bancário com Autenticação de Dois Fatores (2FA)
URL: /en/documentation/baas/cobranca/2fa_v2/agendamento/solicitar_agendamento_de_boleto_bancario
Este endpoint permite realizar a solicitação de agendamento de pagamento de boletos bancários.
A solicitação deve ser realizado após a consulta, utilizando as informações retornadas
para garantir o funcionamento correto do fluxo, evitando falhas durante o processo.
:::info Boleto bancário
É o boleto bancário convencional (linhas digitáveis não iniciadas com dígito 8).
Possui registro na Câmara Interbancária de Pagamento (CIP/Núclea) e pode ser pago em instituições financeiras e de
pagamento autorizadas a funcionar pelo Banco Central.
:::
## Request
ENDPOINT /account/ ACCOUNT_KEY /payment_schedule/bank_slip
MÉTODO POST
### Request Path Params
| Campo | Tipo | Descrição | Caracteres |
|---------------------|---------|-----------------------------------------|------------|
| `account_key` * | uuid4 | Chave única de identificação da conta. | 36 |
Request Body: Solicitação de agendamento com linha digitável
```json
{
"request_control_key": "b6804f32-101e-4702-8fbc-c2dbc4c2caec",
"digitable_line": "00190000090361557400500000024174396700000991000",
"payment_amount": 1156.8,
"payment_date": "2024-03-30",
"tfa_info": {
"approver_document_number": "98765432100",
"contact_type": "email"
}
}
```
Request Body: Solicitação de agendamento com código de barras
```json
{
"request_control_key": "b6804f32-101e-4702-8fbc-c2dbc4c2caec",
"barcode": "00190000090361557400500000024174396700000991000",
"payment_amount": 1156.8,
"payment_date": "2024-03-30",
"tfa_info": {
"approver_document_number": "98765432100",
"contact_type": "email"
}
}
```
### Body Params
| Campo | Tipo | Descrição |
|---------------------|---------------|-----------------------------------|
| `request_control_key` * | uuid4 | Chave única de identificação da request do cliente. |
| `barcode` | string | Código de barras. |
| `digitable_line` | string | Linha digitável. |
| `payment_amount` * | number | Valor a ser pago. |
| `payment_date` * | string | Data do agendamento. |
| `tfa_info` * | [object](#object-tfa_info) | Objeto contendo o documento da pessoa aprovadora da conta e a forma de contato. |
:::danger Aviso
O `payment_amount` deve sempre igual ao `total_amount` retornado na consulta do boleto bancário caso o pagamento parcial não seja permitido para o boleto bancário. Para títulos em que o pagamento parcial é permitido, o cliente pode escolher o `payment_amount`, desde que a soma do mesmo com o `registered_payment_amount` do boleto bancário não seja superior que o `total_amount`.
:::
### Object tfa_info
| Campo | Tipo | Descrição |
|-----------------------------------|---------|-----------------------------------|
| `approver_document_number`* | string | Número de documento da pessoa aprovadora da conta. |
| `contact_type`* | string | Forma de contato com a pessoa aprovadora da conta, podendo ser **sms** ou **email** |
## Response
### Success Response
STATUS 201
Response Body: Agendamento pendente de aprovação de dois fatores
```json
{
"payment_key":"c4325104-d60b-44f3-aae4-49155564a2ea",
"request_control_key":"b713b2f6-2f48-4d18-b0c9-7186e4edf189",
"payer_name":"COOPERATIVA INDUSTRIAL MURILO",
"payer_document_number":"00037025000160",
"source_account_key":"6dc89d57-fac7-4643-b151-cd2ca0a7f68f",
"paid_amount":1050.1,
"payment_date":"2024-04-03",
"payment_type":"bank_slip",
"bank_slip": {
"bank_slip_key":"95080ffd-3ac5-48d7-b3fe-659e4aaba81a",
"barcode":"00193967000009910000000003615574000000002417",
"digitable_line":"00190000090361557400500000024174396700000991000",
"payer_name":"COOPERATIVA TESTE",
"payer_document_number":"00037025000160",
"beneficiary_name":"TESTE EQUIPAMENTOS E SERVICOS LTDA",
"beneficiary_trading_name":"TESTE EQUIPAMENTOS E SERVICOS LTDA",
"beneficiary_document_number":"52069937000117",
"beneficiary_bank_ispb":"00000000",
"guarantor_name":null,
"guarantor_document_number":null,
"expiration_date":"2024-03-29",
"max_payment_data": "2026-03-29",
"partial_payment_indicator":"allowed",
"registered_payment_amount":9029.0,
"nominal_amount":9910.0,
"total_amount":10129.1,
"rebate_amount":0.0,
"discount_amount":0.0,
"fine_amount":0.0,
"interest_amount":219.1
},
"collection_slip":null,
"payment_schedule_status":"pending_2fa_approval"
}
```
### Response Body Params
| Campo | Tipo | Descrição |
|---------------------|---------|-----------------------------------------------------|
| `payment_key` * | uuid4 | Chave única de identificação do pagamento. |
| `request_control_key` * | uuid4 | Chave única de identificação da request do cliente. |
| `payer_name` * | string | Nome do pagador efetivo. |
| `payer_document_number` * | string | Número do documento do pagador efetivo (CPF/CNPJ). |
| `source_account_key` * | uuid4 | Chave da conta debitada. |
| `transaction_key` * | uuid4 | Chave da transação do pagamento. |
| `transaction_revert_key` | uuid4 | Chave da transação de reversão do pagamento. |
| `paid_amount` * | number | Valor pago efetivamente. |
| `payment_date` * | string | Data do agendamento. |
| `payment_type` * | [enum](#enumeradores-payment_type) | Tipo do pagamento. |
| `bank_slip` | [object](#object-bank_slip) | Boleto bancário. |
| `collection_slip` | object | Fatura de recolhimento. |
| `payment_schedule_status` * | [enum](#enumeradores-payment_schedule_status) | Status do agendamento. |
### Enumeradores payment_type
| Enumerador | Tipo | Descrição |
|---------------|-----------|---------------|
| `bank_slip` | string | Boleto bancário |
| `collection_slip` | string | Fatura de recolhimento |
:::danger Aviso
O enumerador `collection_slip` não se aplica para o fluxo de boletos bancários, assim como o objeto collection_slip que sempre será nulo.
:::
### Enumeradores payment_schedule_status
| Enumerador | Tipo | Descrição |
|---------------|-----------|---------------|
| `pending_2fa_approval` | string | pendente de aprovação de dois fatores |
### Object bank_slip
| Campo | Tipo | Descrição |
|-----------------------------------|---------|-----------------------------------|
| `barcode` * | string | Código de barras. |
| `digitable_line` * | string | Linha digitável. |
| `payer_name` * | string | Nome do pagador.|
| `payer_document_number` * | string | Número do documento do pagador (CPF/CNPJ). |
| `beneficiary_name` * | string | Nome do beneficiário. |
| `beneficiary_trading_name` | string | Nome fantasia do beneficiário. |
| `beneficiary_document_number` * | string | Número do documento do beneficiário (CPF/CNPJ). |
| `beneficiary_bank_ispb` * | string | Código ispb do banco do beneficiário. |
| `guarantor_name` | string | Nome do sacador avalista. |
| `guarantor_document_number` | string | Número do documento do sacador avalista (CPF/CNPJ). |
| `expiration_date` * | string | Data de vencimento. |
| `max_payment_date` * | string | Data máxima de pagamento. |
| `partial_payment_indicator` * | [enum](#enumeradores-partial_payment_indicator) | Indicador de pagamento parcial. |
| `registered_payment_amount` | string | Valor total de pagamento registrado. |
| `nominal_amount` * | number | Valor original. |
| `total_amount` * | number | Valor total. |
| `rebate_amount` * | number | Valor do abatimento. |
| `discount_amount` * | number | Valor do desconto. |
| `fine_amount` * | number | Valor da multa. |
| `interest_amount` * | number | Valor do juros. |
### Enumeradores partial_payment_indicator
| Enumerador | Tipo | Descrição |
|---------------|-----------|---------------|
| `allowed` | string | Permitido |
| `not_allowed` | string | Não permitido |
### Error Response
STATUS 4XX
Response Body
```json
{
"title": "Título",
"description": "Description in english",
"translation": "Descrição em português",
"code": "Código"
}
```
| Código HTTP | Código QI | Título | Descrição (eng) | Descrição (pt-br) |
|-------------|-----------|--------|------------------|------------------|
| 400 | BIP000001 | Bad Request | The barcode or digitable line must have 44 or 47 characters. | O código de barras ou linha digitável deve ter 44 ou 47 caracteres. |
| 400 | BIP000002 | Bad Request | The bill sent does not correspond to a bank slip. | A conta enviado não corresponde a um boleto bancário. |
| 400 | BIP000003 | Bad Request | The digitable line sent is invalid. | A linha digitável enviada é inválida. |
| 404 | BIP000004 | Not Found | The bank slip was not found. | O boleto não foi encontrado. |
| 400 | BIP000005 | Bad Request | It was not possible to consult the bank slip at this time. Please try again in a few minutes. | Não foi possível consultar o boleto neste momento. Por favor, tente novamente em alguns minutos. |
| 400 | BIP000006 | Bad Request | Bank slip already written off | Boleto já baixado |
| 400 | BIP000007 | Bad Request | Bank slip blocked for payment | Boleto bloqueado para pagamento |
| 400 | BIP000008 | Bad Request | Bank slip already paid | Boleto já pago |
| 400 | BIP000009 | Bad Request | Invalid bank slip. Please consult issuing bank | Boleto inválido. Favor consultar banco emissor |
| 403 | BIP000010 | Forbidden | User is not allowed to do this action | Usuário não tem autorização para fazer essa ação |
| 404 | BIP000011 | Not Found | The source account key was not found. | A chave da conta de origem não foi encontrada. |
| 400 | BIP000012 | Bad Request | It 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. |
| 400 | BIP000013 | Bad Request | The source account is closed. | A conta de origem está fechada. |
| 400 | BIP000014 | Bad Request | The source account is blocked. | A conta de origem está bloqueada. |
| 400 | BIP000015 | Bad Request | Payment date is greater than the maximum payment date. | A data de pagamento é maior que a data máxima de pagamento. |
| 400 | BIP000016 | Bad Request | Payment date is smaller than the calculation date. | A data de pagamento é menor que a data de cálculo. |
| 400 | BIP000017 | Bad Request | Invalid payment amount. | Valor de pagamento inválido. |
| 400 | BIP000018 | Bad Request | Partial payment is not allowed. | Pagamento parcial não é permitido. |
| 400 | BIP000019 | Bad Request | The payment amount is greater than the available amount. | O valor do pagamento é maior que o valor disponível. |
| 400 | BIP000020 | Bad Request | All partial payments for this bank slip have already been made. | Todos os pagamentos parciais deste boleto já foram realizados. |
| 400 | BIP000024 | Bad Request | Request control key already exists. | Chave de controle da requisição já existe. |
| 403 | BIP000052 | Forbidden | Given document number does not belong to an approver for this account | Número de documento enviado não pertence a um aprovador da conta |
| 400 | BIP000053 | Bad Request | Error getting approver data | Erro ao obter dados do aprovador |
| 400 | BIP000054 | Bad Request | TFA info required | Informações de TFA necessárias |
| 400 | BIP000055 | Bad Request | Error sending verification token | Erro ao enviar token de verificação |
| 400 | BIP000065 | Bad Request | Payment verification time window exceeded. | Janela de tempo de verificação de pagamento excedida. |
## Ambiente de Sandbox
Em nosso ambiente de sandbox, disponibilizamos linhas digitáveis mockadas para a simulação de pagamentos bem-sucedidos e testes de cenários de erro.
| Linha digitável |
|-----------------|
| 00190000090361557400500000024174396700000991000 |
| 00190000090282802601919212747174596760001294161 |
| 23793390014000000455277000249001596900000103995 |
| 75691434020137513680900001040013196770002417240 |
| 21390001171200000570700168167484796770000148206 |
| 34191090083273252027893634770007296690012513600 |
| 42297048060005815702500130494123896770000239491 |
| 07090010287045349010776686070590896770001160123 |
| 74891123702849020818918378871083196690000050000 |
| 23792374119000209350986000372408496610000122810 |
---
# Solicitar Agendamento de Pagamento de Facutara de Recolhimento com Autenticação de Dois Fatores (2FA)
URL: /en/documentation/baas/cobranca/2fa_v2/agendamento/solicitar_agendamento_de_pagamento_de_fatura_de_recolhimento
Este endpoint permite realizar a solicitação de agendamento de pagamento de faturas de recolhimento com autenticação de dois fatores.
A solicitação deve ser realizado após a consulta, utilizando as informações retornadas para garantir o funcionamento correto do fluxo,
evitando falhas durante o processo.
:::info Fatura de recolhimento
Esse tipo de cobrança é emitido por concessionárias de serviços (conta de água, luz, telefone e gás) e órgão públicos (tributos). Eles não são registrados na Câmara Interbancária de Pagamento (CIP/Núclea), por isso, não retornam as mesmas informações que um Boleto bancário apresenta.
:::
## Request
ENDPOINT /account/ ACCOUNT_KEY /payment_schedule/collection_slip
MÉTODO POST
### Request Path Params
| Campo | Tipo | Descrição | Caracteres |
|---------------------|---------|-----------------------------------------|------------|
| `account_key` * | uuid4 | Chave única de identificação da conta. | 36 |
Request Body: Solicitação de com linha digitável
```json
{
"request_control_key": "b6804f32-101e-4702-8fbc-c2dbc4c2caec",
"digitable_line": "00190000090361557400500000024174396700000991000",
"payment_amount": 1156.8,
"payment_date": "2024-03-30",
"tfa_info": {
"approver_document_number": "98765432100",
"contact_type": "email"
}
}
```
Request Body: Solicitação de agendamento com código de barras
```json
{
"request_control_key": "b6804f32-101e-4702-8fbc-c2dbc4c2caec",
"barcode": "00190000090361557400500000024174396700000991000",
"payment_amount": 1156.8,
"payment_date": "2024-03-30",
"tfa_info": {
"approver_document_number": "98765432100",
"contact_type": "email"
}
}
```
### Body Params
| Campo | Tipo | Descrição |
|---------------------|---------------|-----------------------------------|
| `request_control_key` * | uuid4 | Chave única de identificação da request do cliente. |
| `barcode` | string | Código de barras. |
| `digitable_line` | string | Linha digitável. |
| `payment_amount` * | number | Valor a ser pago. |
| `tfa_info` * | [object](#object-tfa_info) | Objeto contendo o documento da pessoa aprovadora da conta e a forma de contato. |
:::danger Aviso
O `payment_amount` deve sempre igual ao `total_amount` retornado na consulta do boleto bancário.
:::
### Object tfa_info
| Campo | Tipo | Descrição |
|-----------------------------------|---------|-----------------------------------|
| `approver_document_number`* | string | Número de documento da pessoa aprovadora da conta (CPF/CNPJ). |
| `contact_type`* | string | Forma de contato com a pessoa aprovadora da conta, podendo ser **sms** ou **email** |
## Response
### Success Response
STATUS 201
Response Body: Agendamento pendente de aprovação de dois fatores
```json
{
"payment_key": "33860ad0-bcb0-47b7-bbe7-c7e3ec2fc61a",
"request_control_key": "ae4508df-f2cb-4e28-9f04-a19b7f2758c9",
"payer_name": "COOPERATIVA INDUSTRIAL MURILO",
"payer_document_number": "62069937000118",
"source_account_key": "daae79e6-ee8b-449f-aa1e-96959d5d5a72",
"paid_amount": 1389.21,
"payment_date": "2024-04-30",
"payment_type": "collection_slip",
"bank_slip": null,
"collection_slip": {
"barcode": null,
"digitable_line": "836200000138892100450006762142420244046000010192",
"collection_name": "CIA ULTRAGAZ SA-COD",
"collection_document_number": "00394460005887",
"expiration_date": "2024-04-15",
"total_amount": 1389.21
},
"payment_schedule_status": "pending_2fa_approval"
}
```
### Response Body Params
| Campo | Tipo | Descrição |
|---------------------|---------|-----------------------------------------------------|
| `payment_key` * | uuid4 | Chave única de identificação do pagamento. |
| `request_control_key` * | uuid4 | Chave única de identificação da request do cliente. |
| `payer_name` * | string | Nome do pagador efetivo. |
| `payer_document_number` * | string | Documento do pagador efetivo (CPF/CNPJ). |
| `source_account_key` * | uuid4 | Chave da conta debitada. |
| `transaction_key` * | uuid4 | Chave da transação do pagamento. |
| `transaction_revert_key` | uuid4 | Chave da transação de reversão do pagamento. |
| `paid_amount` * | number | Valor pago efetivamente. |
| `payment_date` * | string | Data do agendamento. |
| `payment_type` * | [enum](#enumeradores-payment_type) | Tipo do pagamento. |
| `bank_slip` | object | Boleto bancário. |
| `collection_slip` | [object](#object-collection_slip) | Fatura de recolhimento. |
| `payment_schedule_status` * | [enum](#enumeradores-payment_schedule_status) | Status do agendamento. |
### Enumeradores payment_type
| Enumerador | Tipo | Descrição |
|---------------|-----------|---------------|
| `bank_slip` | string | Boleto bancário |
| `collection_slip` | string | Fatura de recolhimento |
:::danger Aviso
O enumerador `bank_slip` não se aplica para o fluxo de faturas de recolhimento, assim como o objeto bank_slip que sempre será nulo.
:::
### Enumeradores payment_schedule_status
| Enumerador | Tipo | Descrição |
|---------------|-----------|---------------|
| `pending_2fa_approval` | string | pendente de aprovação de dois fatores |
### Object collection_slip
| Campo | Tipo | Descrição |
|-----------------------------------|---------|-----------------------------------|
| `barcode` | string | Código de barras. |
| `digitable_line` | string | Linha digitável. |
| `collection_name` * | string | Nome do convênio.|
| `collection_document_number` | string | Número de documento do convênio (CPF/CNPJ).|
| `expiration_date` * | string | Data de vencimento. |
| `total_amount` * | number | Valor total. |
### Error Response
STATUS 4XX
Response Body
```json
{
"title": "Título",
"description": "Description in english",
"translation": "Descrição em português",
"code": "Código"
}
```
| Código HTTP | Código QI | Título | Descrição (eng) | Descrição (pt-br) |
|-------------|-----------|--------|------------------|------------------|
| 400 | BIP000032 | Bad Request | The bill sent does not correspond to a collection slip. | A conta enviada não corresponde a uma fatura de recolhimento. |
| 400 | BIP000033 | Bad Request | The barcode or digitable line of the collection slip must have 44 or 48 characters. | O código de barras ou linha digitável da fatura de recolhimento deve ter 44 ou 48 caracteres. |
| 403 | BIP000010 | Forbidden | User is not allowed to do this action | Usuário não tem autorização para fazer essa ação |
| 404 | BIP000011 | Not Found | The source account key was not found. | A chave da conta de origem não foi encontrada. |
| 400 | BIP000012 | Bad Request | It 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. |
| 400 | BIP000013 | Bad Request | The source account is closed. | A conta de origem está fechada. |
| 400 | BIP000014 | Bad Request | The source account is blocked. | A conta de origem está bloqueada. |
| 400 | BIP000024 | Bad Request | Request control key already exists. | Chave de controle da requisição já existe. |
| 400 | BIP000028 | Bad Request | The source account has blocked balance. Payment cannot be made. | A conta de origem possui saldo em conta bloqueado. Pagamento não pode ser realizado. |
| 400 | BIP000034 | Bad Request | Collection slip already paid. | Fatura de recolhimento já paga. |
| 400 | BIP000035 | Bad Request | Covenant slip invalid barcode. | Código de barras da fatura de recolhimento inválido. |
| 400 | BIP000036 | Bad Request | Covenant slip overdue. | Fatura de recolhimento vencida. |
| 400 | BIP000037 | Bad Request | Error in collection slip consultation. | Erro na consulta da fatura de recolhimento. |
| 400 | BIP000038 | Bad Request | Outside of covenant payment hours. | Fora do horário de pagamento do convênio. |
| 400 | BIP000039 | Bad Request | Collection slip not accepted. | Fatura de recolhimento não aceita. |
| 400 | BIP000040 | Bad Request | Minimum advance not reached. | Mínimo de dias de adiantamento não atingido. |
| 400 | BIP000041 | Bad Request | Max payment amount exceeded. | Valor máximo de pagamento excedido. |
| 400 | BIP000044 | Bad Request | It was not possible to pay the collection slip at this time. Please verify your information and, if necessary, contact us for assistance. | Não foi possível pagar a fatura de recolhimento neste momento. Por favor, verifique suas informações e, se necessário, entre em contato conosco para assistência. |
| 403 | BIP000052 | Forbidden | Given document number does not belong to an approver for this account | Número de documento enviado não pertence a um aprovador da conta |
| 400 | BIP000053 | Bad Request | Error getting approver data | Erro ao obter dados do aprovador |
| 400 | BIP000054 | Bad Request | TFA info required | Informações de TFA necessárias |
| 400 | BIP000055 | Bad Request | Error sending verification token | Erro ao enviar token de verificação |
| 400 | BIP000065 | Bad Request | Payment verification time window exceeded. | Janela de tempo de verificação de pagamento excedida. |
## Ambiente de Sandbox
Em nosso ambiente de sandbox, disponibilizamos linhas digitáveis mockadas para a simulação de pagamentos bem-sucedidos e testes de cenários de erro.
| Linha digitável |
|---|
| 828300000007411100972013905080001546763201900028 |
| 838000000009235700481007241345219112001474229880 |
| 848000000006308600802021201071261517689002201070 |
| 858200000015000000643025703477209504800448091020 |
| 858500000037350000643217212883260006147448091022 |
---
# Request bank slip batch scheduling with 2FA
URL: /en/documentation/baas/cobranca/2fa_v2/agendamento/solicitar_agendamento_em_lote_de_boleto_bancario
This endpoint allows requesting **batch scheduling** for bank slips in a single request, with two-factor authentication when applicable.
:::info Bank slip
A traditional bank slip (digitable line does not start with 8). It is registered in the Interbank Payment Chamber (CIP/Nuclea) and can be paid through financial and payment institutions authorized by the Central Bank.
:::
## Request
### Request Endpoint
ENDPOINT /bill_payment/account/ ACCOUNT_KEY /payments_schedule/batch_bank_slip
METHOD POST
### Request Path Params
| Field | Type | Description | Characters |
|---------------------|---------|-----------------------------------------|------------|
| `account_key` * | uuid4 | Unique account identifier key. | 36 |
Request Body: Bank slip batch scheduling
```json
{
"request_control_key": "b6804f32-101e-4702-8fbc-c2dbc4c2caec",
"bank_slip_payment_schedules": [
{
"request_control_key": "c7915a43-212f-5813-9adc-d3ed5d3d3bfd",
"digitable_line": "00190000090361557400500000024174396700000991000",
"payment_amount": 1156.8,
"payment_date": "2026-04-10"
},
{
"request_control_key": "d8a26b54-323a-4924-0aed-e4fe6e4e4c0e",
"barcode": "00190000090361557400500000024174396700000991000",
"payment_amount": 200.5,
"payment_date": "2026-04-15"
}
],
"tfa_info": {
"approver_document_number": "98765432100",
"contact_type": "email"
}
}
```
### Body Params
| Field | Type | Description |
|---------------------|---------------|-----------------------------------|
| `request_control_key` * | uuid4 | Unique client request identifier key (batch). |
| `bank_slip_payment_schedules` * | array | List of bank slip schedules. Limit of **1000** items per request. |
| `tfa_info` * | [object](#objeto-tfa_info) | Object containing the approver document and token delivery channel. |
Each element in `bank_slip_payment_schedules` must contain:
| Field | Type | Description |
|---------------------|---------------|-----------------------------------|
| `request_control_key` * | uuid4 | Unique client request identifier key for that batch item. |
| `barcode` | string | Barcode. |
| `digitable_line` | string | Digitable line. |
| `payment_amount` * | number | Amount to be paid. |
| `payment_date` * | string | Scheduled execution date for the item. |
:::danger Warning
For each item, `payment_amount` must follow the bank slip rules returned by the lookup. If partial payment is not allowed, the amount must match the updated total amount.
:::
### Object tfa_info
| Field | Type | Description |
|-----------------------------|---------|-----------------------------------|
| `approver_document_number`* | string | Approver document number (CPF/CNPJ). |
| `contact_type`* | enumerator | Authentication token delivery channel | **[Enumerator contact_type](#enumerador-contact_type)** |
| Enumerator | Description |
|------------|---------------------------------------------------|
| **sms** | Send token via SMS |
| **email** | Send token via email |
## Response
### Success Response
STATUS 202
Response Body: Scheduling batch pending two-factor approval
```json
{
"batch_payment_schedule_key": "c4325104-d60b-44f3-aae4-49155564a2ea",
"request_control_key": "b6804f32-101e-4702-8fbc-c2dbc4c2caec",
"account_key": "6dc89d57-fac7-4643-b151-cd2ca0a7f68f",
"total_amount": 1357.3,
"batch_payment_schedule_status": "pending_2fa_approval",
"payment_type": "bank_slip"
}
```
### Response Body Params
| Field | Type | Description |
|---------------------|---------|-----------------------------------|
| `batch_payment_schedule_key` * | uuid4 | Unique batch scheduling identifier key. |
| `request_control_key` * | uuid4 | Unique client request identifier key (batch). |
| `account_key` * | uuid4 | Debited account key. |
| `total_amount` * | number | Sum of (`payment_amount`) values for batch items. |
| `batch_payment_schedule_status` * | [enum](#enumeradores-batch_payment_schedule_status) | Batch scheduling status after request. |
| `payment_type` * | [enum](#enumeradores-payment_type) | Payment type. |
### Enumerators batch_payment_schedule_status
| Enumerator | Description |
|---------------|---------------|
| `pending_2fa_approval` | Pending 2FA approval |
| `scheduled` | Scheduled |
| `rejected` | Rejected |
| `error` | Scheduling error |
### Enumerators payment_type
| Enumerator | Type | Description |
|---------------|-----------|---------------|
| `bank_slip` | string | Bank slip |
| `collection_slip` | string | Collection slip |
:::danger Warning
The `collection_slip` enumerator does not apply to the bank slip batch scheduling flow for this endpoint; expected `payment_type` value is `bank_slip`.
:::
### Error Response
STATUS 4XX
Response Body
```json
{
"title": "Title",
"description": "Description in English",
"translation": "Description in Portuguese",
"code": "Code"
}
```
| HTTP Code | QI Code | Title | Description (eng) | Description (pt-br) |
|-------------|-----------|--------|------------------|------------------|
| 403 | BIP000010 | Forbidden | User is not allowed to do this action | User is not allowed to do this action |
| 404 | BIP000011 | Not Found | The source account key was not found. | The source account key was not found. |
| 400 | BIP000012 | Bad Request | It was not possible to consult the source account at this time. Please try again in a few minutes. | It was not possible to consult the source account at this time. Please try again in a few minutes. |
| 400 | BIP000024 | Bad Request | Request control key already exists. | Request control key already exists. |
| 400 | BIP000052 | Bad Request | Given document number does not belong to an approver for this account | Given document number does not belong to an approver for this account |
| 400 | BIP000053 | Bad Request | Error getting approver date | Error getting approver date |
| 400 | BIP000054 | Bad Request | TFA info required | TFA info required |
| 400 | BIP000055 | Bad Request | Error sending verification token | Error sending verification token |
| 400 | BIP000065 | Bad Request | Payment verification time window exceeded. | Payment verification time window exceeded. |
---
# Request collection slip batch scheduling with 2FA
URL: /en/documentation/baas/cobranca/2fa_v2/agendamento/solicitar_agendamento_em_lote_de_fatura_de_recolhimento
This endpoint allows solicitar o **scheduling em batch** de collection slips (convênio/tributo) em uma única request, com autenticação de dois fatores quando aplicável.
:::info Fatura de recolhimento
Esse tipo de cobrança é emitido por concessionárias de serviços (account de água, luz, telefone e gás) e órgãos públicos (tributos). Eles não são registrados na Câmara Interbancária de Pagamento (CIP/Núclea), por isso, não retornam as mesmas informações que um Boleto bancário apresenta.
:::
## Request
### Request Endpoint
ENDPOINT /bill_payment/account/ ACCOUNT_KEY /payments_schedule/batch_collection_slip
METHOD POST
### Request Path Params
| Field | Type | Description | Characters |
|---------------------|---------|-----------------------------------------|------------|
| `account_key` * | uuid4 | Chave única de identificação da account. | 36 |
Request Body: Scheduling em batch de collection slips
```json
{
"request_control_key": "b6804f32-101e-4702-8fbc-c2dbc4c2caec",
"collection_slip_payment_schedules": [
{
"request_control_key": "c7915a43-212f-5813-9adc-d3ed5d3d3bfd",
"digitable_line": "836200000138892100450006762142420244046000010192",
"payment_amount": 1389.21,
"payment_date": "2026-04-10"
},
{
"request_control_key": "d8a26b54-323a-4924-0aed-e4fe6e4e4c0e",
"barcode": "836200000138892100450006762142420244046000010192",
"payment_amount": 550.10,
"payment_date": "2026-04-15"
}
],
"tfa_info": {
"approver_document_number": "98765432100",
"contact_type": "email"
}
}
```
### Body Params
| Field | Type | Description |
|---------------------|---------------|-----------------------------------|
| `request_control_key` * | uuid4 | Chave única de identificação da request do cliente (batch). |
| `collection_slip_payment_schedules` * | array | Lista de schedulings de collection slip. Limite de **1000** itens por request. |
| `tfa_info` * | [object](#objeto-tfa_info) | Object contendo o documento da pessoa aprovadora da account e a forma de accountto. |
Cada elemento de `collection_slip_payment_schedules` deve conter:
| Field | Type | Description |
|---------------------|---------------|-----------------------------------|
| `request_control_key` * | uuid4 | Chave única de identificação da request do cliente para aquele item do batch. |
| `barcode` | string | Código de barras. |
| `digitable_line` | string | Linha digitável. |
| `payment_amount` * | number | Valor a ser pago. |
| `payment_date` * | string | Data do scheduling do item. |
### Object tfa_info
| Field | Type | Description |
|-----------------------------|---------|-----------------------------------|
| `approver_document_number`* | string | Número de documento da pessoa aprovadora da account (CPF/CNPJ). |
| `contact_type`* | enumerator | Forma de envio do token de autenticação | **[Enumerator contact_type](#enumerador-contact_type)** |
| Enumerator | Description |
|------------|---------------------------------------------------|
| **sms** | Envio por mensagem de texto para telefone celular |
| **email** | Envio por correio eletrônico |
## Response
### Success Response
STATUS 202
Response Body: Batch de scheduling pendente de aprovação de dois fatores
```json
{
"batch_payment_schedule_key": "33860ad0-bcb0-47b7-bbe7-c7e3ec2fc61a",
"request_control_key": "ae4508df-f2cb-4e28-9f04-a19b7f2758c9",
"account_key": "daae79e6-ee8b-449f-aa1e-96959d5d5a72",
"total_amount": 1939.31,
"batch_payment_schedule_status": "pending_2fa_approval",
"payment_type": "collection_slip"
}
```
### Response Body Params
| Field | Type | Description |
|---------------------|---------|-----------------------------------|
| `batch_payment_schedule_key` * | uuid4 | Chave única de identificação do scheduling em batch. |
| `request_control_key` * | uuid4 | Chave única de identificação da request do cliente (batch). |
| `account_key` * | uuid4 | Chave da account debitada. |
| `total_amount` * | number | Soma dos valores (`payment_amount`) dos itens do batch. |
| `batch_payment_schedule_status` * | [enum](#enumeradores-batch_payment_schedule_status) | Batch scheduling status after request. |
| `payment_type` * | [enum](#enumeradores-payment_type) | Type do payment. |
### Enumerators batch_payment_schedule_status
| Enumerator | Description |
|---------------|---------------|
| `pending_2fa_approval` | Pendente de aprovação 2FA |
| `scheduled` | Scheduled |
| `rejected` | Rejected |
| `error` | Scheduling error |
### Enumerators payment_type
| Enumerator | Type | Description |
|---------------|-----------|---------------|
| `bank_slip` | string | Boleto bancário |
| `collection_slip` | string | Fatura de recolhimento |
:::danger Warning
O enumerador `bank_slip` não se aplica ao fluxo de scheduling em batch de collection slips deste endpoint; para este caso, espera-se `payment_type` com valor `collection_slip`.
:::
### Error Response
STATUS 4XX
Response Body
```json
{
"title": "Título",
"description": "Description in english",
"translation": "Description em português",
"code": "Código"
}
```
| Código HTTP | Código QI | Título | Description (eng) | Description (pt-br) |
|-------------|-----------|--------|------------------|------------------|
| 400 | BIP000032 | Bad Request | The bill sent does not correspond to a collection slip. | A account enviada não corresponde a uma collection slip. |
| 400 | BIP000033 | Bad Request | The barcode or digitable line of the collection slip must have 44 or 48 characters. | O código de barras ou linha digitável da collection slip deve ter 44 ou 48 caracteres. |
| 403 | BIP000010 | Forbidden | User is not allowed to do this action | Usuário não tem autorização para fazer essa ação |
| 404 | BIP000011 | Not Found | The source account key was not found. | A chave da account de origem não foi encontrada. |
| 400 | BIP000012 | Bad Request | It 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 account de origem neste momento. Por favor, tente novamente em alguns minutos. |
| 400 | BIP000024 | Bad Request | Request control key already exists. | Chave de controle da request já existe. |
| 403 | BIP000052 | Forbidden | Given document number does not belong to an approver for this account | Número de documento enviado não pertence a um aprovador da account |
| 400 | BIP000053 | Bad Request | Error getting approver date | Erro ao obter dados do aprovador |
| 400 | BIP000054 | Bad Request | TFA info required | Informações de TFA necessárias |
| 400 | BIP000055 | Bad Request | Error sending verification token | Erro ao enviar token de verificação |
| 400 | BIP000065 | Bad Request | Payment verification time window exceeded. | Janela de tempo de verificação de payment excedida. |
---
# Bank slip payment batch confirmation
URL: /en/documentation/baas/cobranca/2fa_v2/confirmacao_de_lote_de_boleto_bancario
This document describes the **same route** as [Bank slip payment batch confirmation](../confirmacao_de_lote_de_boleto_bancario.md) when the operation requires **two-factor authentication (2FA)** at the confirmation step: the request body must include **`tfa_info`** together with `batch_status: approved` or `batch_status: rejected`. Then, the batch may remain in `pending_2fa_approval` (approval) or `pending_2fa_rejection` (rejection) until **token validation**.
:::info Bank slip
A traditional bank slip (digitable line not starting with digit 8). It is registered in the Interbank Payment Chamber (CIP/Núclea) and can be paid at financial and payment institutions authorized by the Central Bank.
:::
## Request
### Request Endpoint
ENDPOINT /bill_payment/account/**ACCOUNT_KEY**/payment/batch_bank_slip/**PAYMENT_BATCH_KEY**/confirmation
METHOD PATCH
### Request Path Params
| Field | Type | Description | Characters |
| --------------------- | ----- | ---------------------------------------------------------------------------------------- | ---------- |
| `account_key` * | uuid4 | Unique account identifier. | 36 |
| `payment_batch_key` * | uuid4 | Unique batch identifier (`batch_payment_key` returned at batch creation). | 36 |
### Request Body
**Request Body: Batch rejection (with `tfa_info`)**
```json
{
"batch_status": "rejected",
"tfa_info": {
"approver_document_number": "98765432100",
"contact_type": "email"
}
}
```
**Request Body: Batch approval (with `tfa_info`)**
```json
{
"batch_status": "approved",
"tfa_info": {
"approver_document_number": "98765432100",
"contact_type": "email"
}
}
```
### Body Params
| Field | Type | Description |
| ---------------- | ------ | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
| `batch_status` * | string | Batch decision. Values: `approved` (continue processing) or `rejected` (cancel the batch). See [batch_confirmation_status enumerator](#enumerador-batch_confirmation_status). |
| `tfa_info` | object | Required in this flow with `batch_status: approved` or `batch_status: rejected`; provide approver information and token delivery channel in [tfa_info object](#object-tfa_info). |
### Enumerator batch_confirmation_status
| Value | Description |
| ---------- | ------------------------------------------------------------- |
| `approved` | Approve the batch and continue the processing flow. |
| `rejected` | Reject the batch; there is no asynchronous processing of bank slips. |
### Object tfa_info
| Field | Type | Description |
| ---------------------------- | ------ | -------------------------------------------------------------------------------------------------------------------------------------------------- |
| `approver_document_number` * | string | Approver person's document number (CPF) that will receive the token. Required when `tfa_info` is provided. |
| `contact_type` * | string | Channel used to send the token (for example, `sms` or `email`), according to operation and registration rules. Required when `tfa_info` is provided. |
## Response
The HTTP status and the `batch_status` field in the response depend on the submitted decision and whether the flow requires token validation after this call.
### Response: rejected batch — pending token validation (2FA)
STATUS 202
When `batch_status` in the request body is `rejected` and the request includes `tfa_info`, the API responds with **202**. The batch waits for token validation, and the body returns `batch_status` as `pending_2fa_rejection`. After token validation, the rejection decision is applied.
**Response Body: Batch waiting for token validation (rejection decision)**
```json
{
"batch_payment_key": "a3214093-e51c-55e2-b5d3-60244475b3fb",
"request_control_key": "b6804f32-101e-4702-8fbc-c2dbc4c2caec",
"account_key": "6dc89d57-fac7-4643-b151-cd2ca0a7f68f",
"total_amount": 1357.3,
"batch_status": "pending_2fa_approval",
"payment_type": "bank_slip"
}
```
### Response: approved batch — pending token validation (2FA)
STATUS 202
When `batch_status` in the body is `approved` and the request includes `tfa_info`, the API responds with **202**. The batch waits for token validation, and the body returns `batch_status` as `pending_2fa_approval`. Next steps (code delivery, validation, and resend) are documented in [Batch bank slip token validation](./validacao_de_token_de_lote_de_boleto_bancario.md) and [Resend batch bank slip token](./solicitacao_de_reenvio_de_token_de_lote_de_boleto_bancario.md).
**Response Body: Batch waiting for token validation**
```json
{
"batch_payment_key": "a3214093-e51c-55e2-b5d3-60244475b3fb",
"request_control_key": "b6804f32-101e-4702-8fbc-c2dbc4c2caec",
"account_key": "6dc89d57-fac7-4643-b151-cd2ca0a7f68f",
"total_amount": 1357.3,
"batch_status": "pending_2fa_rejection",
"payment_type": "bank_slip"
}
```
### Response Body Params
| Field | Type | Description |
| ----------------------- | ------ | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `batch_payment_key` * | uuid4 | Unique batch payment identifier. |
| `request_control_key` * | uuid4 | Unique client request identifier (batch). |
| `account_key` * | uuid4 | Debited account key. |
| `total_amount` * | number | Sum of the amounts of all batch items. |
| `batch_status` * | string | In this call, the batch remains in `pending_2fa_approval` (approval) or `pending_2fa_rejection` (rejection) until token validation. After validation, the final status reflects the decision sent in confirmation (`approved` or `rejected`). |
| `payment_type` * | string | Payment type; for this flow, expected value is `bank_slip`. |
### Error Response
STATUS 4XX
**Response Body**
```json
{
"title": "Title",
"description": "Description in english",
"translation": "Description em português",
"code": "Code"
}
```
| HTTP code | QI code | Title | Description (eng) | Description (pt-br) |
| ----------- | --------- | ----------- | --------------------------------------------- | ----------------------------------------------------- |
| 400 | BIP000013 | Bad Request | The source account is closed. | The source account is closed. |
| 400 | BIP000050 | Bad Request | Requester configuration does not exist | Requester configuration does not exist. |
| 400 | BIP000054 | Bad Request | TFA info required. | TFA info required. |
| 404 | BIP000083 | Not Found | Batch payment not found by batch payment key. | Batch payment not found by batch payment key. |
| 400 | BIP000084 | Bad Request | Batch payment status is not pending. | Batch payment status is not pending. |
---
# Collection slip (utility/tax) payment batch confirmation
URL: /en/documentation/baas/cobranca/2fa_v2/confirmacao_de_lote_de_fatura_de_recolhimento
This document describes the **same route** as [Collection slip payment batch confirmation (utility/tax)](../confirmacao_de_lote_de_fatura_de_recolhimento.md) when the operation requires **two-factor authentication (2FA)** at the confirmation step: the request body must include **`tfa_info`** together with `batch_status: approved` or `batch_status: rejected`. Then, the batch may remain in `pending_2fa_approval` (approval) or `pending_2fa_rejection` (rejection) until **token validation**.
:::info Collection slip (utility/tax bill)
This charge type is issued by utility companies (water, electricity, phone, and gas) and public agencies (taxes). It is not registered in the Interbank Payment Chamber (CIP/Núclea), so it does not return the same information as a bank slip.
:::
## Request
### Request Endpoint
ENDPOINT /bill_payment/account/**ACCOUNT_KEY**/payment/batch_collection_slip/**PAYMENT_BATCH_KEY**/confirmation
METHOD PATCH
### Request Path Params
| Field | Type | Description | Characters |
| --------------------- | ----- | ---------------------------------------------------------------------------------------- | ---------- |
| `account_key` * | uuid4 | Unique account identifier. | 36 |
| `payment_batch_key` * | uuid4 | Unique batch identifier (`batch_payment_key` returned at batch creation). | 36 |
### Request Body
**Request Body: Batch rejection (with `tfa_info`)**
```json
{
"batch_status": "rejected",
"tfa_info": {
"approver_document_number": "98765432100",
"contact_type": "email"
}
}
```
**Request Body: Batch approval (with `tfa_info`)**
```json
{
"batch_status": "approved",
"tfa_info": {
"approver_document_number": "98765432100",
"contact_type": "email"
}
}
```
### Body Params
| Field | Type | Description |
| ---------------- | ------ | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
| `batch_status` * | string | Batch decision. Values: `approved` (continue processing) or `rejected` (cancel the batch). See [batch_confirmation_status enumerator](#enumerador-batch_confirmation_status). |
| `tfa_info` | object | Required in this flow with `batch_status: approved` or `batch_status: rejected`; provide approver information and token delivery channel in [tfa_info object](#object-tfa_info). |
### Enumerator batch_confirmation_status
Accepted values in the request body for `batch_status`:
| Value | Description |
| ---------- | ----------------------------------------------------------------------------- |
| `approved` | Approve the batch and continue the processing flow. |
| `rejected` | Reject the batch; there is no asynchronous processing of collection slips. |
### Object tfa_info
| Field | Type | Description |
| ---------------------------- | ------ | -------------------------------------------------------------------------------------------------------------------------------------------------- |
| `approver_document_number` * | string | Approver person's document number (CPF) that will receive the token. Required when `tfa_info` is provided. |
| `contact_type` * | string | Channel used to send the token (for example, `sms` or `email`), according to operation and registration rules. Required when `tfa_info` is provided. |
## Response
The HTTP status and the `batch_status` field in the response depend on the submitted decision and whether the flow requires token validation after this call.
### Response: rejected batch — pending token validation (2FA)
STATUS 202
When `batch_status` in the request body is `rejected` and the request includes `tfa_info`, the API responds with **202**. The batch waits for token validation, and the body returns `batch_status` as `pending_2fa_rejection`. After token validation, the rejection decision is applied.
**Response Body: Batch waiting for token validation (rejection decision)**
```json
{
"batch_payment_key": "a3214093-e51c-55e2-b5d3-60244475b3fb",
"request_control_key": "b6804f32-101e-4702-8fbc-c2dbc4c2caec",
"account_key": "daae79e6-ee8b-449f-aa1e-96959d5d5a72",
"total_amount": 2778.42,
"batch_status": "pending_2fa_rejection",
"payment_type": "collection_slip"
}
```
### Response: approved batch — pending token validation (2FA)
STATUS 202
When `batch_status` in the body is `approved` and the request includes `tfa_info`, the API responds with **202**. The batch waits for token validation, and the body returns `batch_status` as `pending_2fa_approval`. Next steps are documented in [Batch collection slip token validation](./validacao_de_token_de_lote_de_fatura_de_recolhimento.md) and [Resend batch collection slip token](./solicitacao_de_reenvio_de_token_de_lote_de_fatura_de_recolhimento.md).
**Response Body: Batch waiting for token validation**
```json
{
"batch_payment_key": "a3214093-e51c-55e2-b5d3-60244475b3fb",
"request_control_key": "b6804f32-101e-4702-8fbc-c2dbc4c2caec",
"account_key": "daae79e6-ee8b-449f-aa1e-96959d5d5a72",
"total_amount": 2778.42,
"batch_status": "pending_2fa_rejection",
"payment_type": "collection_slip"
}
```
### Response Body Params
| Field | Type | Description |
| ----------------------- | ------ | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `batch_payment_key` * | uuid4 | Unique batch payment identifier. |
| `request_control_key` * | uuid4 | Unique client request identifier (batch). |
| `account_key` * | uuid4 | Debited account key. |
| `total_amount` * | number | Sum of the amounts of all batch items. |
| `batch_status` * | string | In this call, the batch remains in `pending_2fa_approval` (approval) or `pending_2fa_rejection` (rejection) until token validation. After validation, the final status reflects the decision sent in confirmation (`approved` or `rejected`). |
| `payment_type` * | string | Payment type; for this flow, expected value is `collection_slip`. |
### Error Response
STATUS 4XX
**Response Body**
```json
{
"title": "Title",
"description": "Description in english",
"translation": "Description em português",
"code": "Code"
}
```
| HTTP code | QI code | Title | Description (eng) | Description (pt-br) |
| ----------- | --------- | ----------- | --------------------------------------------- | ----------------------------------------------------- |
| 400 | BIP000013 | Bad Request | The source account is closed. | The source account is closed. |
| 400 | BIP000050 | Bad Request | Requester configuration does not exist | Requester configuration does not exist. |
| 400 | BIP000054 | Bad Request | TFA info required. | TFA info required. |
| 404 | BIP000083 | Not Found | Batch payment not found by batch payment key. | Batch payment not found by batch payment key. |
| 400 | BIP000084 | Bad Request | Batch payment status is not pending. | Batch payment status is not pending. |
---
# Confirm boleto payment
URL: /en/documentation/baas/cobranca/2fa_v2/confirmacao_de_pagamento_de_boleto_bancario
This endpoint allows the confirmation of boleto payment.
:::info Boleto
This is the conventional boleto (with digitable lines not starting with the digit 8). It is registered with the Interbank Payment Clearinghouse (CIP/Núclea) and can be paid at financial institutions and payment institutions authorized to operate by the Central Bank.
:::
## Request
### Request Endpoint
ENDPOINT /account/ ACCOUNT_KEY /payment/ PAYMENT_KEY /bank_slip/validate_token
MÉTODO PATCH
### Request Path Params
| Field | Type | Description | Characters |
|---------------------|---------|-----------------------------------------|------------|
| `account_key` * | uuid4 | Unique account identification key. | 36 |
| `payment_key` * | uuid4 | Unique payment identification key. | 36 |
Request Body: Boleto payment confirmation
```json
{
"token": "329adf"
}
```
### Body Params
| Field | Type | Description |
|---------------------|---------------|-----------------------------------|
| `token` * | string | Authentication code sent to the account's transaction approver |
## Response
### Success Response
STATUS 200
Response Body: Payment executed
```json
{
"payment_key":"c4325104-d60b-44f3-aae4-49155564a2ea",
"request_control_key":"b713b2f6-2f48-4d18-b0c9-7186e4edf189",
"payer_name":"COOPERATIVA INDUSTRIAL MURILO",
"payer_document_number":"00037025000160",
"source_account_key":"6dc89d57-fac7-4643-b151-cd2ca0a7f68f",
"transaction_key":"4e80070a-a0bb-4be2-8178-55fbd73a3704",
"transaction_revert_key":null,
"paid_amount":1050.1,
"payment_date":"2024-04-03",
"payment_type":"bank_slip",
"bank_slip": {
"bank_slip_key":"95080ffd-3ac5-48d7-b3fe-659e4aaba81a",
"barcode":"00193967000009910000000003615574000000002417",
"digitable_line":"00190000090361557400500000024174396700000991000",
"payer_name":"COOPERATIVA TESTE",
"payer_document_number":"00037025000160",
"beneficiary_name":"TESTE EQUIPAMENTOS E SERVICOS LTDA",
"beneficiary_trading_name":"TESTE EQUIPAMENTOS E SERVICOS LTDA",
"beneficiary_document_number":"52069937000117",
"beneficiary_bank_ispb":"00000000",
"guarantor_name":null,
"guarantor_document_number":null,
"expiration_date":"2024-03-29",
"max_payment_data": "2026-03-29",
"partial_payment_indicator":"allowed",
"registered_payment_amount":9029.0,
"nominal_amount":9910.0,
"total_amount":10129.1,
"rebate_amount":0.0,
"discount_amount":0.0,
"fine_amount":0.0,
"interest_amount":219.1
},
"collection_slip":null,
"payment_status":"executed"
}
```
STATUS 202
Response Body: Payment pending execution
```json
{
"payment_key":"c4325104-d60b-44f3-aae4-49155564a2ea",
"request_control_key":"b713b2f6-2f48-4d18-b0c9-7186e4edf189",
"payer_name":"COOPERATIVA INDUSTRIAL MURILO",
"payer_document_number":"00037025000160",
"source_account_key":"6dc89d57-fac7-4643-b151-cd2ca0a7f68f",
"transaction_key":"4e80070a-a0bb-4be2-8178-55fbd73a3704",
"transaction_revert_key":null,
"paid_amount":1050.1,
"payment_date":"2024-04-03",
"payment_type":"bank_slip",
"bank_slip": {
"bank_slip_key":"95080ffd-3ac5-48d7-b3fe-659e4aaba81a",
"barcode":"00193967000009910000000003615574000000002417",
"digitable_line":"00190000090361557400500000024174396700000991000",
"payer_name":"COOPERATIVA TESTE",
"payer_document_number":"00037025000160",
"beneficiary_name":"TESTE EQUIPAMENTOS E SERVICOS LTDA",
"beneficiary_trading_name":"TESTE EQUIPAMENTOS E SERVICOS LTDA",
"beneficiary_document_number":"52069937000117",
"beneficiary_bank_ispb":"00000000",
"guarantor_name":null,
"guarantor_document_number":null,
"expiration_date":"2024-03-29",
"max_payment_data": "2026-03-29",
"partial_payment_indicator":"allowed",
"registered_payment_amount":9029.0,
"nominal_amount":9910.0,
"total_amount":10129.1,
"rebate_amount":0.0,
"discount_amount":0.0,
"fine_amount":0.0,
"interest_amount":219.1
},
"collection_slip":null,
"payment_status": "pending_execution"
}
```
:::info Information
If **HTTP Status 202** is returned with the field `payment_status` having the value **pending_execution**, the payment should not be retried.
This payment will be processed asynchronously. It is necessary to check the transfer status through the payment query, or wait for the pending payment webhook described on the [webhooks page](/documentation/baas_v2/cobranca/webhooks).
:::
### Response Body Params
| Field | Type | Description |
|---------------------|---------|-----------------------------------|
| `payment_key` * | uuid4 | Unique payment identification key. |
| `request_control_key` * | uuid4 | Unique identification key for the client's request. |
| `payer_name` * | string | Name of the effective payer. |
| `payer_document_number` * | string | Document number of the effective payer (CPF/CNPJ). |
| `source_account_key` * | uuid4 | Key of the debited account. |
| `transaction_key` * | uuid4 | Payment transaction key. |
| `transaction_revert_key` | uuid4 | Payment reversal transaction key. |
| `paid_amount` * | number | Amount effectively paid. |
| `payment_date` * | string | Payment date. |
| `payment_type` * | [enum](#enumerators-payment_type) | Payment type. |
| `bank_slip` | [object](#object-bank_slip) | Boleto. |
| `collection_slip` | object | Collection invoice. |
| `payment_status` * | [enum](#enumerators-payment_status) | Payment status. |
### Enumerators payment_type
| Enumerator | Type | Description |
|---------------|-----------|---------------|
| `bank_slip` | string | Boleto |
| `collection_slip` | string | Collection invoice |
:::danger Warning
The enumerator `collection_slip` does not apply to the boleto flow, and the collection_slip object will always be null.
:::
### Enumerators payment_status
| Enumerator | Description |
|---------------|---------------|
| `pending_execution` | Pending execution |
| `executed` | Executed |
| `reverted` | Reverted |
| `rejected` | Rejected |
| `error` | Error |
:::danger Warning
For payments where QI does not receive a response from CIP within two minutes, the payment will be returned with the status `pending_execution`. After QI receives the response from CIP, the pending payment webhook described on the [webhooks page](/documentation/baas_v2/cobranca/webhooks) will be sent to the client.
:::
### Object bank_slip
| Field | Type | Description |
|-----------------------------------|---------|-----------------------------------|
| `barcode` * | string | Barcode. |
| `digitable_line` * | string | Digitable line. |
| `payer_name` * | string | Payer's name. |
| `payer_document_number` * | string | Payer's document number (CPF/CNPJ). |
| `beneficiary_name` * | string | Beneficiary's name. |
| `beneficiary_trading_name` | string | Beneficiary's trade name. |
| `beneficiary_document_number` * | string | Beneficiary's document number (CPF/CNPJ). |
| `beneficiary_bank_ispb` * | string | ISPB code of the beneficiary's bank. |
| `guarantor_name` | string | Name of the guarantor. |
| `guarantor_document_number` | string | Guarantor's document number (CPF/CNPJ). |
| `expiration_date` * | string | Due date. |
| `max_payment_date` * | string | Maximum payment date. |
| `partial_payment_indicator` * | [enum](#enumerators-partial_payment_indicator) | Partial payment indicator. |
| `registered_payment_amount` | string | Total registered payment amount. |
| `nominal_amount` * | number | Original amount. |
| `total_amount` * | number | Total amount. |
| `rebate_amount` * | number | Rebate amount. |
| `discount_amount` * | number | Discount amount. |
| `fine_amount` * | number | Fine amount. |
| `interest_amount` * | number | Interest amount. |
### Enumerators partial_payment_indicator
| Enumerator | Type | Description |
|---------------|-----------|---------------|
| `allowed` | string | Allowed |
| `not_allowed` | string | Not allowed |
### Error Response
STATUS 4XX
Response Body
```json
{
"title": "Título",
"description": "Description in english",
"translation": "Description in portuguese",
"code": "Código"
}
```
| HTTP Code | QI Code | Title | Description (eng) | Description (pt-br) |
|-------------|-----------|--------|------------------|------------------|
| 403 | BIP000010 | Forbidden | User is not allowed to do this action | Usuário não tem autorização para fazer essa ação |
| 404 | BIP000011 | Not Found | The source account key was not found. | A chave da conta de origem não foi encontrada. |
| 400 | BIP000012 | Bad Request | It 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. |
| 400 | BIP000013 | Bad Request | The source account is closed. | A conta de origem está fechada. |
| 400 | BIP000014 | Bad Request | The source account is blocked. | A conta de origem está bloqueada. |
| 400 | BIP000022 | Bad Request | Bank slip payment service is closed. | Serviço de pagamento de boleto está fechado. |
| 400 | BIP000023 | Bad Request | The source account has insufficient balance. Payment cannot be made. | A conta de origem possui saldo insuficiente. Pagamento não pode ser realizado. |
| 400 | BIP000025 | Bad Request | It was not possible to pay the bank slip at this time. Please verify your information and, if necessary, contact us for assistance. | Não foi possível pagar o boleto neste momento. Por favor, verifique suas informações e, se necessário, entre em contato conosco para assistência. |
| 400 | BIP000028 | Bad Request | The source account has blocked balance. Payment cannot be made. | A conta de origem possui saldo em conta bloqueado. Pagamento não pode ser realizado. |
| 404 | BIP000056 | Not Found | Payment not found. | Pagamento não encontrado. |
| 400 | BIP000057 | Bad Request | Payment status is not pending approval. | Status de pagamento não é de aprovação pendente. |
| 400 | BIP000058 | Bad Request | Error while validating verification token | Erro ao validar token de verificação |
| 400 | BIP000059 | Bad Request | Number of verification token validation attempts exceeded. | Número de tentativas de validação de token de verificação excedido. |
| 400 | BIP000060 | Bad Request | Verification token expired. | Token de verificação expirado. |
| 400 | BIP000061 | Bad Request | Verification token validation failed. | Falha na validação do token de verificação. |
| 400 | BIP000062 | Bad Request | Payment type is not bank slip. | Tipo de pagamento não é boleto. |
| 400 | BIP000065 | Bad Request | Payment verification time window exceeded. | Janela de tempo de verificação de pagamento excedida. |
---
# Confirm payment of collection invoice (agreement/tribute)
URL: /en/documentation/baas/cobranca/2fa_v2/confirmacao_de_pagamento_de_fatura_de_recolhimento
This endpoint allows the confirmation of collection invoice payments.
:::info Collection Invoice
This type of charge is issued by utility companies (water, electricity, telephone, and gas bills) and public entities (taxes). They are not registered with the Interbank Payment Clearinghouse (CIP/Núclea) and, therefore, do not return the same information as a boleto.
:::
## Request
### Request Endpoint
ENDPOINT /account/ ACCOUNT_KEY /payment/ PAYMENT_KEY /collection_slip/validate_token
MÉTODO PATCH
### Request Path Params
| Field | Type | Description | Characters |
|---------------------|---------|-----------------------------------------|------------|
| `account_key` * | uuid4 | Unique account identification key. | 36 |
| `payment_key` * | uuid4 | Unique payment identification key. | 36 |
Request Body: Collection invoice payment confirmation
```json
{
"token": "329adf"
}
```
### Body Params
| Field | Type | Description |
|---------------------|---------------|-----------------------------------|
| `token` * | string | Authentication code sent to the account's transaction approver |
## Response
### Success Response
STATUS 200
Response Body: Payment executed
```json
{
"payment_key": "33860ad0-bcb0-47b7-bbe7-c7e3ec2fc61a",
"request_control_key": "ae4508df-f2cb-4e28-9f04-a19b7f2758c9",
"payer_name": "COOPERATIVA INDUSTRIAL MURILO",
"payer_document_number": "62069937000118",
"source_account_key": "daae79e6-ee8b-449f-aa1e-96959d5d5a72",
"transaction_key": "fc9ccfd0-2f21-4207-9772-69238be74152",
"transaction_revert_key": null,
"paid_amount": 1389.21,
"payment_date": "2024-04-30",
"payment_type": "collection_slip",
"bank_slip": null,
"collection_slip": {
"barcode": null,
"digitable_line": "836200000138892100450006762142420244046000010192",
"collection_name": "CIA ULTRAGAZ SA-COD",
"collection_document_number": "00394460005887",
"expiration_date": "2024-04-15",
"total_amount": 1389.21
},
"payment_status": "executed"
}
```
### Response Body Params
| Field | Type | Description |
|---------------------|---------|-----------------------------------|
| `payment_key` * | uuid4 | Unique payment identification key. |
| `request_control_key` * | uuid4 | Unique identification key for the client's request. |
| `payer_name` * | string | Name of the effective payer. |
| `payer_document_number` * | string | Document number of the effective payer (CPF/CNPJ). |
| `source_account_key` * | uuid4 | Key of the debited account. |
| `transaction_key` * | uuid4 | Payment transaction key. |
| `transaction_revert_key` | uuid4 | Payment reversal transaction key. |
| `paid_amount` * | number | Amount effectively paid. |
| `payment_date` * | string | Payment date. |
| `payment_type` * | [enum](#enumerators-payment_type) | Payment type. |
| `bank_slip` | object | Boleto bancário. |
| `collection_slip` | [object](#object-collection_slip) | Collection invoice. |
| `payment_status` * | [enum](#enumerators-payment_status) | Payment status. |
### Enumerators payment_type
| Enumerator | Type | Description |
|---------------|-----------|---------------|
| `bank_slip` | string | Boleto bancário |
| `collection_slip` | string | Collection invoice |
:::danger Warning
The enumerator `bank_slip` does not apply to the collection invoice flow, and the bank_slip object will always be null.
:::
### Enumerators payment_status
| Enumerator | Description |
|---------------|---------------|
| `executed` | Executed |
| `reverted` | Reverted |
| `rejected` | Rejected |
| `error` | Error |
### Object collection_slip
| Field | Type | Description |
|-----------------------------------|---------|-----------------------------------|
| `barcode` | string | Barcode. |
| `digitable_line` | string | Digitable line. |
| `collection_name` * | string | Name of the agreement. |
| `collection_document_number` | string | Document number of the agreement (CPF/CNPJ). |
| `expiration_date` * | string | Due date. |
| `total_amount` * | number | Total amount. |
### Error Response
STATUS 4XX
Response Body
```json
{
"title": "Título",
"description": "Description in english",
"translation": "Description in portuguese",
"code": "Código"
}
```
| HTTP Code | QI Code | Title | Description (eng) | Description (pt-br) |
|-------------|-----------|--------|------------------|------------------|
| 403 | BIP000010 | Forbidden | User is not allowed to do this action | Usuário não tem autorização para fazer essa ação |
| 404 | BIP000011 | Not Found | The source account key was not found. | A chave da conta de origem não foi encontrada. |
| 400 | BIP000012 | Bad Request | It 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. |
| 400 | BIP000013 | Bad Request | The source account is closed. | A conta de origem está fechada. |
| 400 | BIP000014 | Bad Request | The source account is blocked. | A conta de origem está bloqueada. |
| 400 | BIP000023 | Bad Request | The source account has insufficient balance. Payment cannot be made. | A conta de origem possui saldo insuficiente. Pagamento não pode ser realizado. |
| 400 | BIP000028 | Bad Request | The source account has blocked balance. Payment cannot be made. | A conta de origem possui saldo em conta bloqueado. Pagamento não pode ser realizado. |
| 400 | BIP000036 | Bad Request | Covenant slip overdue. | Fatura de recolhimento vencida. |
| 400 | BIP000038 | Bad Request | Outside of covenant payment hours. | Fora do horário de pagamento do convênio. |
| 400 | BIP000044 | Bad Request | It was not possible to pay the collection slip at this time. Please verify your information and, if necessary, contact us for assistance. | Não foi possível pagar a fatura de recolhimento neste momento. Por favor, verifique suas informações e, se necessário, entre em contato conosco para assistência. |
| 400 | BIP000045 | Bad Request | Collection slip payment service is closed. | Serviço de pagamento de fatura de recolhimento está fechado. |
| 404 | BIP000056 | Not Found | Payment not found. | Pagamento não encontrado. |
| 400 | BIP000057 | Bad Request | Payment status is not pending approval. | Status de pagamento não é de aprovação pendente. |
| 400 | BIP000058 | Bad Request | Error while validating verification token | Erro ao validar token de verificação |
| 400 | BIP000059 | Bad Request | Number of verification token validation attempts exceeded. | Número de tentativas de validação de token de verificação excedido. |
| 400 | BIP000060 | Bad Request | Verification token expired. | Token de verificação expirado. |
| 400 | BIP000061 | Bad Request | Verification token validation failed. | Falha na validação do token de verificação. |
| 400 | BIP000063 | Bad Request | Payment type is not collection slip. | Tipo de pagamento não é fatura de recolhimento. |
| 400 | BIP000065 | Bad Request | Payment verification time window exceeded. | Janela de tempo de verificação de pagamento excedida. |
---
# Introduction to Two-Factor Authentication
URL: /en/documentation/baas/cobranca/2fa_v2/introducao_ao_pagamento_2fa
In this type of payment, payment confirmation via token sent to the person with approval powers for transactions on the payer's account is required.
The payment request by integrator partners configured to use two-factor authentication is performed similarly to what is described in [boleto payment](/documentation/baas/cobranca/pagar_boleto_bancario) and [collection invoice payment](/documentation/baas/cobranca/pagar_fatura_de_recolhimento). The difference is the addition of the `tfa_info` object in the request, containing information about the transfer approver and the means of contact, and the status of the request in the response. The status of the request will always be returned as **pending_2fa_approval**.
## Flow for a Payment with Authorization
The successful payment will follow the following process flow:
- Perform the [boleto payment request](/documentation/baas/cobranca/2fa_v2/solicitacao_de_pagamento_de_boleto_bancario) or [collection invoice payment request](/documentation/baas_v2/cobranca/2fa_v2/solicitacao_de_pagamento_de_fatura_de_recolhimento) and receive a synchronous response with status **pending_2fa_approval** and the `payment_key`.
- The indicated approver will receive a 6-digit `token` consisting of letters and digits.
- The requester performs the [boleto payment confirmation](/documentation/baas/cobranca/2fa_v2/confirmacao_de_pagamento_de_boleto_bancario) or [collection invoice payment confirmation](/documentation/baas/cobranca/2fa_v2/confirmacao_de_pagamento_de_fatura_de_recolhimento) with the `payment_key` and the `token`.
- The payment will be completed synchronously.
## Observations
- Each payment has a maximum limit of 5 validation attempts for the `token`. When this limit is reached, the payment will be automatically set to rejected (**rejected**) status.
- Each `token` has a maximum duration of 5 minutes.
- A payment can have its `token` renewed and resent to the account approver. This process resets the 5-minute time but does not reset the invalid attempt counter. The previous `token` becomes invalid.
- Once the payment is approved, it will be completed synchronously.
- The notification event for sending the `token` to the approver is **baas.token_validation.bill_payment.payment.single**. It is possible to [customize](/documentation/notificacoes/template) the sent message.
- The implemented `contact_type` for sending tokens are **sms** and **email**.
---
# Request boleto payment (2FA)
URL: /en/documentation/baas/cobranca/2fa_v2/solicitacao_de_pagamento_de_boleto_bancario
This endpoint allows the payment request for boletos. The request should be made after a consultation, using the returned information to ensure the correct flow and avoid failures during the process.
:::info Boleto
This is the conventional boleto (with digitable lines not starting with the digit 8). It is registered with the Interbank Payment Clearinghouse (CIP/Núclea) and can be paid at financial institutions and payment institutions authorized to operate by the Central Bank.
:::
## Request
### Request Endpoint
ENDPOINT /account/ ACCOUNT_KEY /payment/bank_slip
MÉTODO POST
### Request Path Params
| Field | Type | Description | Characters |
|---------------------|---------|-----------------------------------------|------------|
| `account_key` * | uuid4 | Unique account identification key. | 36 |
Request Body: Boleto request with digitable line
```json
{
"request_control_key": "b6804f32-101e-4702-8fbc-c2dbc4c2caec",
"digitable_line": "00190000090361557400500000024174396700000991000",
"payment_amount": 1156.8,
"tfa_info": {
"approver_document_number": "98765432100",
"contact_type": "email"
}
}
```
Request Body: Boleto request with barcode
```json
{
"request_control_key": "b6804f32-101e-4702-8fbc-c2dbc4c2caec",
"barcode": "00190000090361557400500000024174396700000991000",
"payment_amount": 1156.8,
"tfa_info": {
"approver_document_number": "98765432100",
"contact_type": "email"
}
}
```
### Body Params
| Field | Type | Description |
|---------------------|---------------|-----------------------------------|
| `request_control_key` * | uuid4 | Unique identification key for the client's request. |
| `barcode` | string | Barcode. |
| `digitable_line` | string | Digitable line. |
| `payment_amount` * | number | Amount to be paid. |
| `tfa_info` * | [object](#object-tfa_info) | Object containing the document of the account approver and the means of contact. |
:::danger Warning
The `payment_amount` must always be equal to the `total_amount` returned in the boleto query if partial payment is not allowed for the boleto. For titles where partial payment is allowed, the client may choose the `payment_amount`, as long as its sum with the boleto's `registered_payment_amount` does not exceed the `total_amount`.
:::
### Object tfa_info
| Field | Type | Description |
|-----------------------------------|---------|-----------------------------------|
| `approver_document_number`* | string | Document number of the account approver. |
| `contact_type`* | string | Means of contact with the account approver, can be **sms** or **email** |
## Response
### Success Response
STATUS 201
Response Body: Payment pending two-factor approval
```json
{
"payment_key":"c4325104-d60b-44f3-aae4-49155564a2ea",
"request_control_key":"b713b2f6-2f48-4d18-b0c9-7186e4edf189",
"payer_name":"COOPERATIVA INDUSTRIAL MURILO",
"payer_document_number":"00037025000160",
"source_account_key":"6dc89d57-fac7-4643-b151-cd2ca0a7f68f",
"transaction_key":"4e80070a-a0bb-4be2-8178-55fbd73a3704",
"transaction_revert_key":null,
"paid_amount":1050.1,
"payment_date":"2024-04-03",
"payment_type":"bank_slip",
"bank_slip": {
"bank_slip_key":"95080ffd-3ac5-48d7-b3fe-659e4aaba81a",
"barcode":"00193967000009910000000003615574000000002417",
"digitable_line":"00190000090361557400500000024174396700000991000",
"payer_name":"COOPERATIVA TESTE",
"payer_document_number":"00037025000160",
"beneficiary_name":"TESTE EQUIPAMENTOS E SERVICOS LTDA",
"beneficiary_trading_name":"TESTE EQUIPAMENTOS E SERVICOS LTDA",
"beneficiary_document_number":"52069937000117",
"beneficiary_bank_ispb":"00000000",
"guarantor_name":null,
"guarantor_document_number":null,
"expiration_date":"2024-03-29",
"max_payment_data": "2026-03-29",
"partial_payment_indicator":"allowed",
"registered_payment_amount":9029.0,
"nominal_amount":9910.0,
"total_amount":10129.1,
"rebate_amount":0.0,
"discount_amount":0.0,
"fine_amount":0.0,
"interest_amount":219.1
},
"collection_slip":null,
"payment_status":"pending_2fa_approval"
}
```
### Response Body Params
| Field | Type | Description |
|---------------------|---------|-----------------------------------|
| `payment_key` * | uuid4 | Unique payment identification key. |
| `request_control_key` * | uuid4 | Unique identification key for the client's request. |
| `payer_name` * | string | Name of the effective payer.|
| `payer_document_number` * | string | Document number of the effective payer (CPF/CNPJ). |
| `source_account_key` * | uuid4 | Key of the debited account. |
| `transaction_key` * | uuid4 | Payment transaction key. |
| `transaction_revert_key` | uuid4 | Payment reversal transaction key. |
| `paid_amount` * | number | Amount effectively paid. |
| `payment_date` * | string | Payment date. |
| `payment_type` * | [enum](#enumerators-payment_type) | Payment type. |
| `bank_slip` | [object](#object-bank_slip) | Boleto. |
| `collection_slip` | object | Collection invoice. |
| `payment_status` * | [enum](#enumerators-payment_status) | Payment status. |
### Enumerators payment_type
| Enumerator | Type | Description |
|---------------|-----------|---------------|
| `bank_slip` | string | Boleto |
| `collection_slip` | string | Collection invoice |
:::danger Warning
The enumerator `collection_slip` does not apply to the boleto flow, and the collection_slip object will always be null.
:::
### Enumerators payment_status
| Enumerator | Description |
|---------------|---------------|
| `pending_2fa_approval` | pending two-factor approval |
### Object bank_slip
| Field | Type | Description |
|-----------------------------------|---------|-----------------------------------|
| `barcode` * | string | Barcode. |
| `digitable_line` * | string | Digitable line. |
| `payer_name` * | string | Payer's name.|
| `payer_document_number` * | string | Payer's document number (CPF/CNPJ). |
| `beneficiary_name` * | string | Beneficiary's name. |
| `beneficiary_trading_name` | string | Beneficiary's trade name. |
| `beneficiary_document_number` * | string | Beneficiary's document number (CPF/CNPJ). |
| `beneficiary_bank_ispb` * | string | ISPB code of the beneficiary's bank. |
| `guarantor_name` | string | Name of the guarantor. |
| `guarantor_document_number` | string | Guarantor's document number (CPF/CNPJ). |
| `expiration_date` * | string | Due date. |
| `max_payment_date` * | string | Maximum payment date. |
| `partial_payment_indicator` * | [enum](#enumerators-partial_payment_indicator) | Partial payment indicator. |
| `registered_payment_amount` | string | Total registered payment amount. |
| `nominal_amount` * | number | Original amount. |
| `total_amount` * | number | Total amount. |
| `rebate_amount` * | number | Rebate amount. |
| `discount_amount` * | number | Discount amount. |
| `fine_amount` * | number | Fine amount. |
| `interest_amount` * | number | Interest amount. |
### Enumerators partial_payment_indicator
| Enumerator | Type | Description |
|---------------|-----------|---------------|
| `allowed` | string | Allowed |
| `not_allowed` | string | Not allowed |
### Error Response
STATUS 4XX
Response Body
```json
{
"title": "Título",
"description": "Description in english",
"translation": "Description in portuguese",
"code": "Código"
}
```
| HTTP Code | QI Code | Title | Description (eng) | Description (pt-br) |
|-------------|-----------|--------|------------------|------------------|
| 400 | BIP000001 | Bad Request | The barcode or digitable line must have 44 or 47 characters. | O código de barras ou linha digitável deve ter 44 ou 47 caracteres. |
| 400 | BIP000002 | Bad Request | The bill sent does not correspond to a bank slip. | A conta enviado não corresponde a um boleto bancário. |
| 400 | BIP000003 | Bad Request | The digitable line sent is invalid. | A linha digitável enviada é inválida. |
| 404 | BIP000004 | Not Found | The bank slip was not found. | O boleto não foi encontrado. |
| 400 | BIP000005 | Bad Request | It was not possible to consult the bank slip at this time. Please try again in a few minutes. | Não foi possível consultar o boleto neste momento. Por favor, tente novamente em alguns minutos. |
| 400 | BIP000006 | Bad Request | Bank slip already written off | Boleto já baixado |
| 400 | BIP000007 | Bad Request | Bank slip blocked for payment | Boleto bloqueado para pagamento |
| 400 | BIP000008 | Bad Request | Bank slip already paid | Boleto já pago |
| 400 | BIP000009 | Bad Request | Invalid bank slip. Please consult issuing bank | Boleto inválido. Favor consultar banco emissor |
| 403 | BIP000010 | Forbidden | User is not allowed to do this action | Usuário não tem autorização para fazer essa ação |
| 404 | BIP000011 | Not Found | The source account key was not found. | A chave da conta de origem não foi encontrada. |
| 400 | BIP000012 | Bad Request | It 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. |
| 400 | BIP000013 | Bad Request | The source account is closed. | A conta de origem está fechada. |
| 400 | BIP000014 | Bad Request | The source account is blocked. | A conta de origem está bloqueada. |
| 400 | BIP000015 | Bad Request | Payment date is greater than the maximum payment date. | A data de pagamento é maior que a data máxima de pagamento. |
| 400 | BIP000016 | Bad Request | Payment date is smaller than the calculation date. | A data de pagamento é menor que a data de cálculo. |
| 400 | BIP000017 | Bad Request | Invalid payment amount. | Valor de pagamento inválido. |
| 400 | BIP000018 | Bad Request | Partial payment is not allowed. | Pagamento parcial não é permitido. |
| 400 | BIP000019 | Bad Request | The payment amount is greater than the available amount. | O valor do pagamento é maior que o valor disponível. |
| 400 | BIP000020 | Bad Request | All partial payments for this bank slip have already been made. | Todos os pagamentos parciais deste boleto já foram realizados. |
| 400 | BIP000024 | Bad Request | Request control key already exists. | Chave de controle da requisição já existe. |
| 403 | BIP000052 | Forbidden | Given document number does not belong to an approver for this account | Número de documento enviado não pertence a um aprovador da conta |
| 400 | BIP000053 | Bad Request | Error getting approver data | Erro ao obter dados do aprovador |
| 400 | BIP000054 | Bad Request | TFA info required | Informações de TFA necessárias |
| 400 | BIP000055 | Bad Request | Error sending verification token | Erro ao enviar token de verificação |
| 400 | BIP000065 | Bad Request | Payment verification time window exceeded. | Janela de tempo de verificação de pagamento excedida. |
## Sandbox environment
In our sandbox environment, we provide mocked digitable lines for simulating successful payments and testing error scenarios.
| Digitable line |
|-----------------|
| 00190000090361557400500000024174396700000991000 |
| 00190000090282802601919212747174596760001294161 |
| 23793390014000000455277000249001596900000103995 |
| 75691434020137513680900001040013196770002417240 |
| 21390001171200000570700168167484796770000148206 |
| 34191090083273252027893634770007296690012513600 |
| 42297048060005815702500130494123896770000239491 |
| 07090010287045349010776686070590896770001160123 |
| 74891123702849020818918378871083196690000050000 |
| 23792374119000209350986000372408496610000122810 |
---
# Request payment of collection invoice (agreement/tribute)
URL: /en/documentation/baas/cobranca/2fa_v2/solicitacao_de_pagamento_de_fatura_de_recolhimento
This endpoint allows the payment request for collection invoices with two-factor authentication. The request should be made after a consultation, using the returned information to ensure the correct flow and avoid failures during the process.
:::info Collection Invoice
This type of charge is issued by utility companies (water, electricity, telephone, and gas bills) and public entities (taxes). They are not registered with the Interbank Payment Clearinghouse (CIP/Núclea) and, therefore, do not return the same information as a boleto.
:::
## Request
### Request Endpoint
ENDPOINT /account/ ACCOUNT_KEY /payment/collection_slip
MÉTODO POST
### Request Path Params
| Field | Type | Description | Characters |
|---------------------|---------|-----------------------------------------|------------|
| `account_key` * | uuid4 | Unique account identification key. | 36 |
Request Body: Collection invoice request with digitable line
```json
{
"request_control_key": "b6804f32-101e-4702-8fbc-c2dbc4c2caec",
"digitable_line": "00190000090361557400500000024174396700000991000",
"payment_amount": 1156.8,
"tfa_info": {
"approver_document_number": "98765432100",
"contact_type": "email"
}
}
```
Request Body: Collection invoice request with barcode
```json
{
"request_control_key": "b6804f32-101e-4702-8fbc-c2dbc4c2caec",
"barcode": "00190000090361557400500000024174396700000991000",
"payment_amount": 1156.8,
"tfa_info": {
"approver_document_number": "98765432100",
"contact_type": "email"
}
}
```
### Body Params
| Field | Type | Description |
|---------------------|---------------|-----------------------------------|
| `request_control_key` * | uuid4 | Unique identification key for the client's request. |
| `barcode` | string | Barcode. |
| `digitable_line` | string | Digitable line. |
| `payment_amount` * | number | Amount to be paid. |
| `tfa_info` * | [object](#object-tfa_info) | Object containing the document of the account approver and the means of contact. |
:::danger Warning
The `payment_amount` must always be equal to the `total_amount` returned in the boleto query.
:::
### Object tfa_info
| Field | Type | Description |
|-----------------------------------|---------|-----------------------------------|
| `approver_document_number`* | string | Document number of the account approver (CPF/CNPJ). |
| `contact_type`* | string | Means of contact with the account approver, can be **sms** or **email** |
## Response
### Success Response
STATUS 201
Response Body: Payment pending two-factor approval
```json
{
"payment_key": "33860ad0-bcb0-47b7-bbe7-c7e3ec2fc61a",
"request_control_key": "ae4508df-f2cb-4e28-9f04-a19b7f2758c9",
"payer_name": "COOPERATIVA INDUSTRIAL MURILO",
"payer_document_number": "62069937000118",
"source_account_key": "daae79e6-ee8b-449f-aa1e-96959d5d5a72",
"transaction_key": "fc9ccfd0-2f21-4207-9772-69238be74152",
"transaction_revert_key": null,
"paid_amount": 1389.21,
"payment_date": "2024-04-30",
"payment_type": "collection_slip",
"bank_slip": null,
"collection_slip": {
"barcode": null,
"digitable_line": "836200000138892100450006762142420244046000010192",
"collection_name": "CIA ULTRAGAZ SA-COD",
"collection_document_number": "00394460005887",
"expiration_date": "2024-04-15",
"total_amount": 1389.21
},
"payment_status": "pending_2fa_approval"
}
```
### Response Body Params
| Field | Type | Description |
|---------------------|---------|-----------------------------------|
| `payment_key` * | uuid4 | Unique payment identification key. |
| `request_control_key` * | uuid4 | Unique identification key for the client's request. |
| `payer_name` * | string | Name of the effective payer. |
| `payer_document_number` * | string | Document of the effective payer (CPF/CNPJ). |
| `source_account_key` * | uuid4 | Key of the debited account. |
| `transaction_key` * | uuid4 | Payment transaction key. |
| `transaction_revert_key` | uuid4 | Payment reversal transaction key. |
| `paid_amount` * | number | Amount effectively paid. |
| `payment_date` * | string | Payment date. |
| `payment_type` * | [enum](#enumerators-payment_type) | Payment type. |
| `bank_slip` | object | Boleto bancário. |
| `collection_slip` | [object](#object-collection_slip) | Collection invoice. |
| `payment_status` * | [enum](#enumerators-payment_status) | Payment status. |
### Enumerators payment_type
| Enumerator | Type | Description |
|---------------|-----------|---------------|
| `bank_slip` | string | Boleto bancário |
| `collection_slip` | string | Collection invoice |
:::danger Warning
The enumerator `bank_slip` does not apply to the collection invoice flow, and the bank_slip object will always be null.
:::
### Enumerators payment_status
| Enumerator | Description |
|---------------|---------------|
| `pending_2fa_approval` | pending two-factor approval |
### Object collection_slip
| Field | Type | Description |
|-----------------------------------|---------|-----------------------------------|
| `barcode` | string | Barcode. |
| `digitable_line` | string | Digitable line. |
| `collection_name` * | string | Name of the agreement. |
| `collection_document_number` | string | Document number of the agreement (CPF/CNPJ).|
| `expiration_date` * | string | Due date. |
| `total_amount` * | number | Total amount. |
### Error Response
STATUS 4XX
Response Body
```json
{
"title": "Título",
"description": "Description in english",
"translation": "Description in portuguese",
"code": "Código"
}
```
| HTTP Code | QI Code | Title | Description (eng) | Description (pt-br) |
|-------------|-----------|--------|------------------|------------------|
| 400 | BIP000032 | Bad Request | The bill sent does not correspond to a collection slip. | A conta enviada não corresponde a uma fatura de recolhimento. |
| 400 | BIP000033 | Bad Request | The barcode or digitable line of the collection slip must have 44 or 48 characters. | O código de barras ou linha digitável da fatura de recolhimento deve ter 44 ou 48 caracteres. |
| 403 | BIP000010 | Forbidden | User is not allowed to do this action | Usuário não tem autorização para fazer essa ação |
| 404 | BIP000011 | Not Found | The source account key was not found. | A chave da conta de origem não foi encontrada. |
| 400 | BIP000012 | Bad Request | It 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. |
| 400 | BIP000013 | Bad Request | The source account is closed. | A conta de origem está fechada. |
| 400 | BIP000014 | Bad Request | The source account is blocked. | A conta de origem está bloqueada. |
| 400 | BIP000024 | Bad Request | Request control key already exists. | Chave de controle da requisição já existe. |
| 400 | BIP000028 | Bad Request | The source account has blocked balance. Payment cannot be made. | A conta de origem possui saldo em conta bloqueado. Pagamento não pode ser realizado. |
| 400 | BIP000034 | Bad Request | Collection slip already paid. | Fatura de recolhimento já paga. |
| 400 | BIP000035 | Bad Request | Covenant slip invalid barcode. | Código de barras da fatura de recolhimento inválido. |
| 400 | BIP000036 | Bad Request | Covenant slip overdue. | Fatura de recolhimento vencida. |
| 400 | BIP000037 | Bad Request | Error in collection slip consultation. | Erro na consulta da fatura de recolhimento. |
| 400 | BIP000038 | Bad Request | Outside of covenant payment hours. | Fora do horário de pagamento do convênio. |
| 400 | BIP000039 | Bad Request | Collection slip not accepted. | Fatura de recolhimento não aceita. |
| 400 | BIP000040 | Bad Request | Minimum advance not reached. | Mínimo de dias de adiantamento não atingido. |
| 400 | BIP000041 | Bad Request | Max payment amount exceeded. | Valor máximo de pagamento excedido. |
| 400 | BIP000044 | Bad Request | It was not possible to pay the collection slip at this time. Please verify your information and, if necessary, contact us for assistance. | Não foi possível pagar a fatura de recolhimento neste momento. Por favor, verifique suas informações e, se necessário, entre em contato conosco para assistência. |
| 403 | BIP000052 | Forbidden | Given document number does not belong to an approver for this account | Número de documento enviado não pertence a um aprovador da conta |
| 400 | BIP000053 | Bad Request | Error getting approver data | Erro ao obter dados do aprovador |
| 400 | BIP000054 | Bad Request | TFA info required | Informações de TFA necessárias |
| 400 | BIP000055 | Bad Request | Error sending verification token | Erro ao enviar token de verificação |
| 400 | BIP000065 | Bad Request | Payment verification time window exceeded. | Janela de tempo de verificação de pagamento excedida. |
## Sandbox Environment
In our sandbox environment, we provide mocked digitable lines for simulating successful payments and testing error scenarios.
| Digitable Line |
|---|
| 828300000007411100972013905080001546763201900028 |
| 838000000009235700481007241345219112001474229880 |
| 848000000006308600802021201071261517689002201070 |
| 858200000015000000643025703477209504800448091020 |
| 858500000037350000643217212883260006147448091022 |
---
# Resend payment confirmation token for Boleto
URL: /en/documentation/baas/cobranca/2fa_v2/solicitacao_de_reenvio_de_token_de_boleto_bancario
This endpoint allows the resending of the authentication token for Boleto payments.
:::info Boleto
This is the conventional boleto (with digitable lines not starting with the digit 8). It is registered with the Interbank Payment Clearinghouse (CIP/Núclea) and can be paid at financial institutions and payment institutions authorized to operate by the Central Bank.
:::
## Request
### Request Endpoint
ENDPOINT /account/ ACCOUNT_KEY /payment/ PAYMENT_KEY /bank_slip/resend_token
MÉTODO PATCH
### Request Path Params
| Field | Type | Description | Characters |
|---------------------|---------|-----------------------------------------|------------|
| `account_key` * | uuid4 | Unique account identification key. | 36 |
| `payment_key` * | uuid4 | Unique payment identification key. | 36 |
## Response
### Success Response
STATUS 200
Response Body: Token successfully resent
```json
{
"payment_key":"c4325104-d60b-44f3-aae4-49155564a2ea",
"request_control_key":"b713b2f6-2f48-4d18-b0c9-7186e4edf189",
"payer_name":"COOPERATIVA INDUSTRIAL MURILO",
"payer_document_number":"00037025000160",
"source_account_key":"6dc89d57-fac7-4643-b151-cd2ca0a7f68f",
"transaction_key":"4e80070a-a0bb-4be2-8178-55fbd73a3704",
"transaction_revert_key":null,
"paid_amount":1050.1,
"payment_date":"2024-04-03",
"payment_type":"bank_slip",
"bank_slip": {
"bank_slip_key":"95080ffd-3ac5-48d7-b3fe-659e4aaba81a",
"barcode":"00193967000009910000000003615574000000002417",
"digitable_line":"00190000090361557400500000024174396700000991000",
"payer_name":"COOPERATIVA TESTE",
"payer_document_number":"00037025000160",
"beneficiary_name":"TESTE EQUIPAMENTOS E SERVICOS LTDA",
"beneficiary_trading_name":"TESTE EQUIPAMENTOS E SERVICOS LTDA",
"beneficiary_document_number":"52069937000117",
"beneficiary_bank_ispb":"00000000",
"guarantor_name":null,
"guarantor_document_number":null,
"expiration_date":"2024-03-29",
"max_payment_data": "2026-03-29",
"partial_payment_indicator":"allowed",
"registered_payment_amount":9029.0,
"nominal_amount":9910.0,
"total_amount":10129.1,
"rebate_amount":0.0,
"discount_amount":0.0,
"fine_amount":0.0,
"interest_amount":219.1
},
"collection_slip":null,
"payment_status":"pending_2fa_approval"
}
```
### Response Body Params
| Field | Type | Description |
|---------------------|---------|-----------------------------------|
| `payment_key` * | uuid4 | Unique payment identification key. |
| `request_control_key` * | uuid4 | Unique identification key for the client's request. |
| `payer_name` * | string | Name of the effective payer. |
| `payer_document_number` * | string | Document number of the effective payer (CPF/CNPJ). |
| `source_account_key` * | uuid4 | Key of the debited account. |
| `transaction_key` * | uuid4 | Payment transaction key. |
| `transaction_revert_key` | uuid4 | Payment reversal transaction key. |
| `paid_amount` * | number | Amount effectively paid. |
| `payment_date` * | string | Payment date. |
| `payment_type` * | [enum](#enumerators-payment_type) | Payment type. |
| `bank_slip` | [object](#object-bank_slip) | Boleto. |
| `collection_slip` | object | Collection invoice. |
| `payment_status` * | [enum](#enumerators-payment_status) | Payment status. |
### Enumerators payment_type
| Enumerator | Type | Description |
|---------------|-----------|---------------|
| `bank_slip` | string | Boleto |
| `collection_slip` | string | Collection invoice |
:::danger Warning
The enumerator `collection_slip` does not apply to the boleto flow, and the collection_slip object will always be null.
:::
### Enumerators payment_status
| Enumerator | Description |
|---------------|---------------|
| `pending_2fa_approval` | pending two-factor approval |
### Object bank_slip
| Field | Type | Description |
|-----------------------------------|---------|-----------------------------------|
| `barcode` * | string | Barcode. |
| `digitable_line` * | string | Digitable line. |
| `payer_name` * | string | Payer's name. |
| `payer_document_number` * | string | Payer's document number (CPF/CNPJ). |
| `beneficiary_name` * | string | Beneficiary's name. |
| `beneficiary_trading_name` | string | Beneficiary's trade name. |
| `beneficiary_document_number` * | string | Beneficiary's document number (CPF/CNPJ). |
| `beneficiary_bank_ispb` * | string | ISPB code of the beneficiary's bank. |
| `guarantor_name` | string | Name of the guarantor. |
| `guarantor_document_number` | string | Guarantor's document number (CPF/CNPJ). |
| `expiration_date` * | string | Due date. |
| `max_payment_date` * | string | Maximum payment date. |
| `partial_payment_indicator` * | [enum](#enumerators-partial_payment_indicator) | Partial payment indicator. |
| `registered_payment_amount` | string | Total registered payment amount. |
| `nominal_amount` * | number | Original amount. |
| `total_amount` * | number | Total amount. |
| `rebate_amount` * | number | Rebate amount. |
| `discount_amount` * | number | Discount amount. |
| `fine_amount` * | number | Fine amount. |
| `interest_amount` * | number | Interest amount. |
### Enumerators partial_payment_indicator
| Enumerator | Type | Description |
|---------------|-----------|---------------|
| `allowed` | string | Allowed |
| `not_allowed` | string | Not allowed |
### Error Response
STATUS 4XX
Response Body
```json
{
"title": "Título",
"description": "Description in english",
"translation": "Descrição em português",
"code": "Código"
}
```
| HTTP Code | QI Code | Title | Description (eng) | Description (pt-br) |
|-------------|-----------|--------|------------------|------------------|
| 403 | BIP000010 | Forbidden | User is not allowed to do this action | Usuário não tem autorização para fazer essa ação |
| 404 | BIP000011 | Not Found | The source account key was not found. | A chave da conta de origem não foi encontrada. |
| 400 | BIP000012 | Bad Request | It 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. |
| 400 | BIP000013 | Bad Request | The source account is closed. | A conta de origem está fechada. |
| 400 | BIP000014 | Bad Request | The source account is blocked. | A conta de origem está bloqueada. |
| 404 | BIP000056 | Not Found | Payment not found. | Pagamento não encontrado. |
| 400 | BIP000057 | Bad Request | Payment status is not pending approval. | Status de pagamento não é de aprovação pendente. |
| 400 | BIP000062 | Bad Request | Payment type is not bank slip. | Tipo de pagamento não é boleto. |
| 400 | BIP000064 | Bad Request | Error resending verification token | Erro ao reenviar token de verificação |
| 400 | BIP000065 | Bad Request | Payment verification time window exceeded. | Janela de tempo de verificação de pagamento excedida. |
---
# Resend Two-Factor Authentication Token for Collection Invoice Payments
URL: /en/documentation/baas/cobranca/2fa_v2/solicitacao_de_reenvio_de_token_de_fatura_de_recolhimento
This endpoint allows the resending of the authentication token for collection invoice payments.
:::info Collection Invoice
This type of charge is issued by utility companies (water, electricity, telephone, and gas bills) and public entities (taxes). They are not registered with the Interbank Payment Clearinghouse (CIP/Núclea) and, therefore, do not return the same information as a boleto.
:::
## Request
### Request Endpoint
ENDPOINT /account/ ACCOUNT_KEY /payment/ PAYMENT_KEY /collection_slip/resend_token
MÉTODO PATCH
### Request Path Params
| Field | Type | Description | Characters |
|---------------------|---------|-----------------------------------------|------------|
| `account_key` * | uuid4 | Unique account identification key. | 36 |
| `payment_key` * | uuid4 | Unique payment identification key. | 36 |
## Response
### Success Response
STATUS 200
Response Body: Token successfully resent
```json
{
"payment_key": "33860ad0-bcb0-47b7-bbe7-c7e3ec2fc61a",
"request_control_key": "ae4508df-f2cb-4e28-9f04-a19b7f2758c9",
"payer_name": "COOPERATIVA INDUSTRIAL MURILO",
"payer_document_number": "62069937000118",
"source_account_key": "daae79e6-ee8b-449f-aa1e-96959d5d5a72",
"transaction_key": "fc9ccfd0-2f21-4207-9772-69238be74152",
"transaction_revert_key": null,
"paid_amount": 1389.21,
"payment_date": "2024-04-30",
"payment_type": "collection_slip",
"bank_slip": null,
"collection_slip": {
"barcode": null,
"digitable_line": "836200000138892100450006762142420244046000010192",
"collection_name": "CIA ULTRAGAZ SA-COD",
"collection_document_number": "00394460005887",
"expiration_date": "2024-04-15",
"total_amount": 1389.21
},
"payment_status": "pending_2fa_approval"
}
```
### Response Body Params
| Field | Type | Description |
|---------------------|---------|-----------------------------------|
| `payment_key` * | uuid4 | Unique payment identification key. |
| `request_control_key` * | uuid4 | Unique identification key for the client's request. |
| `payer_name` * | string | Name of the effective payer. |
| `payer_document_number` * | string | Document number of the effective payer (CPF/CNPJ). |
| `source_account_key` * | uuid4 | Key of the debited account. |
| `transaction_key` * | uuid4 | Payment transaction key. |
| `transaction_revert_key` | uuid4 | Payment reversal transaction key. |
| `paid_amount` * | number | Amount effectively paid. |
| `payment_date` * | string | Payment date. |
| `payment_type` * | [enum](#enumerators-payment_type) | Payment type. |
| `bank_slip` | object | Boleto. |
| `collection_slip` | [object](#object-collection_slip) | Collection invoice. |
| `payment_status` * | [enum](#enumerators-payment_status) | Payment status. |
### Enumerators payment_type
| Enumerator | Type | Description |
|---------------|-----------|---------------|
| `bank_slip` | string | Boleto bancário |
| `collection_slip` | string | Collection invoice |
:::danger Warning
The enumerator `bank_slip` does not apply to the collection invoice flow, and the bank_slip object will always be null.
:::
### Enumerators payment_status
| Enumerator | Description |
|---------------|---------------|
| `pending_2fa_approval` | pending two-factor approval |
### Object collection_slip
| Field | Type | Description |
|-----------------------------------|---------|-----------------------------------|
| `barcode` | string | Barcode. |
| `digitable_line` | string | Digitable line. |
| `collection_name` * | string | Name of the agreement.|
| `collection_document_number` | string | Document number of the agreement (CPF/CNPJ).|
| `expiration_date` * | string | Due date. |
| `total_amount` * | number | Total amount. |
### Error Response
STATUS 4XX
Response Body
```json
{
"title": "Título",
"description": "Description in english",
"translation": "Descrição em português",
"code": "Código"
}
```
| HTTP Code | QI Code | Title | Description (eng) | Description (pt-br) |
|-------------|-----------|--------|------------------|------------------|
| 403 | BIP000010 | Forbidden | User is not allowed to do this action | Usuário não tem autorização para fazer essa ação |
| 404 | BIP000011 | Not Found | The source account key was not found. | A chave da conta de origem não foi encontrada. |
| 400 | BIP000012 | Bad Request | It 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. |
| 400 | BIP000013 | Bad Request | The source account is closed. | A conta de origem está fechada. |
| 400 | BIP000014 | Bad Request | The source account is blocked. | A conta de origem está bloqueada. |
| 404 | BIP000056 | Not Found | Payment not found. | Pagamento não encontrado. |
| 400 | BIP000057 | Bad Request | Payment status is not pending approval. | Status de pagamento não é de aprovação pendente. |
| 400 | BIP000063 | Bad Request | Payment type is not collection slip. | Tipo de pagamento não é fatura de recolhimento. |
| 400 | BIP000064 | Bad Request | Error resending verification token | Erro ao reenviar token de verificação |
| 400 | BIP000065 | Bad Request | Payment verification time window exceeded. | Janela de tempo de verificação de pagamento excedida. |
---
# Resend token for bank slip payment batch confirmation
URL: /en/documentation/baas/cobranca/2fa_v2/solicitacao_de_reenvio_de_token_de_lote_de_boleto_bancario
This endpoint allows **resending** the two-factor authentication (2FA) token for a bank slip batch that is waiting for token validation. A new token is generated and sent to the approver. If the token validation attempt limit has been exceeded, resending may not be allowed.
:::info Bank slip
A traditional bank slip (digitable line not starting with digit 8). It is registered in the Interbank Payment Chamber (CIP/Núclea) and can be paid at financial and payment institutions authorized by the Central Bank.
:::
## Request
### Request Endpoint
ENDPOINT /bill_payment/account/**ACCOUNT_KEY**/payment/batch_bank_slip/**PAYMENT_BATCH_KEY**/resend_token
METHOD PATCH
### Request Path Params
| Field | Type | Description | Characters |
| --------------------- | ----- | ---------------------------------------------------------------------------------------- | ---------- |
| `account_key` * | uuid4 | Unique account identifier. | 36 |
| `payment_batch_key` * | uuid4 | Unique batch identifier (`batch_payment_key` returned at batch creation). | 36 |
### Request Body
Request Body (opcional)
```json
{
"contact_type": "sms"
}
```
### Body Params
| Field | Type | Description | Characters |
| -------------- | ---------- | --------------------------------------- | ------------------------------------------------------- |
| `contact_type` | enumerator | Authentication token delivery method | **[Enumerador contact_type](#enumerador-contact_type)** |
:::info Information
If `contact_type` is not sent, the token will be sent using the originally requested method (`tfa_info.contact_type`).
:::
### Enumerator contact_type
| Enumerador | Description |
| ---------- | ------------------------------------------------- |
| **sms** | Send via SMS to mobile phone |
| **email** | Send via email |
## Response
### Success Response
STATUS 200
Response Body: Token resent successfully
```json
{
"batch_payment_key": "a3214093-e51c-55e2-b5d3-60244475b3fb",
"request_control_key": "b6804f32-101e-4702-8fbc-c2dbc4c2caec",
"account_key": "6dc89d57-fac7-4643-b151-cd2ca0a7f68f",
"total_amount": 1357.3,
"batch_status": "pending_2fa_approval",
"payment_type": "bank_slip"
}
```
### Response Body Params
| Field | Type | Description |
| ----------------------- | ------ | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `batch_payment_key` * | uuid4 | Unique batch payment identifier. |
| `request_control_key` * | uuid4 | Unique client request identifier (batch). |
| `account_key` * | uuid4 | Debited account key. |
| `total_amount` * | number | Sum of the amounts of all batch items. |
| `batch_status` * | string | After resend, the batch remains waiting for token validation. The `batch_status` cycle follows the batch payment request documentation available for your operation (enumerator `batch_payment_status`). |
| `payment_type` * | string | Payment type; for this flow, expected value is `bank_slip`. |
Then use [Batch bank slip token validation](./validacao_de_token_de_lote_de_boleto_bancario.md) to complete 2FA.
### Error Response
STATUS 4XX
Response Body
```json
{
"title": "Title",
"description": "Description in english",
"translation": "Description em português",
"code": "Code"
}
```
| HTTP code | QI code | Title | Description (eng) | Description (pt-br) |
| ----------- | --------- | ----------- | -------------------------------------------------------------------------------------------------- | --------------------------------------------------------------------------------------------------------- |
| 403 | BIP000010 | Forbidden | User is not allowed to do this action | User is not allowed to do this action |
| 404 | BIP000011 | Not Found | The source account key was not found. | The source account key was not found. |
| 400 | BIP000012 | Bad Request | It was not possible to consult the source account at this time. Please try again in a few minutes. | It was not possible to consult the source account at this time. Please try again in a few minutes. |
| 400 | BIP000013 | Bad Request | The source account is closed. | The source account is closed. |
| 400 | BIP000014 | Bad Request | The source account is blocked. | The source account is blocked. |
| 400 | BIP000059 | Bad Request | Number of verification token validation attempts exceeded. | Number of verification token validation attempts exceeded. |
| 400 | BIP000064 | Bad Request | Error resending verification token | Error resending verification token |
| 400 | BIP000065 | Bad Request | Payment verification time window exceeded. | Payment verification time window exceeded. |
| 404 | BIP000083 | Not Found | Batch payment not found by batch payment key. | Batch payment not found by batch payment key. |
| 400 | BIP000085 | Bad Request | Batch payment status is not pending approval. | Batch payment status is not pending approval. |
| 400 | BIP000086 | Bad Request | A token is required for SMS or email validation. | A token is required for SMS or email validation. |
---
# Resend token for collection slip payment batch confirmation (utility/tax)
URL: /en/documentation/baas/cobranca/2fa_v2/solicitacao_de_reenvio_de_token_de_lote_de_fatura_de_recolhimento
This endpoint allows **resending** the two-factor authentication (2FA) token for a collection slip batch that is waiting for token validation. A new token is generated and sent to the approver. If the token validation attempt limit has been exceeded, resending may not be allowed.
:::info Collection slip (utility/tax bill)
This charge type is issued by utility companies (water, electricity, phone, and gas) and public agencies (taxes). It is not registered in the Interbank Payment Chamber (CIP/Núclea), so it does not return the same information as a bank slip.
:::
## Request
### Request Endpoint
ENDPOINT /bill_payment/account/**ACCOUNT_KEY**/payment/batch_collection_slip/**PAYMENT_BATCH_KEY**/resend_token
METHOD PATCH
### Request Path Params
| Field | Type | Description | Characters |
| --------------------- | ----- | ---------------------------------------------------------------------------------------- | ---------- |
| `account_key` * | uuid4 | Unique account identifier. | 36 |
| `payment_batch_key` * | uuid4 | Unique batch identifier (`batch_payment_key` returned at batch creation). | 36 |
### Request Body
Request Body (opcional)
```json
{
"contact_type": "sms"
}
```
### Body Params
| Field | Type | Description | Characters |
| -------------- | ---------- | --------------------------------------- | ------------------------------------------------------- |
| `contact_type` | enumerator | Authentication token delivery method | **[Enumerador contact_type](#enumerador-contact_type)** |
:::info Information
If `contact_type` is not sent, the token will be sent using the originally requested method (`tfa_info.contact_type`).
:::
### Enumerator contact_type
| Enumerador | Description |
| ---------- | ------------------------------------------------- |
| **sms** | Send via SMS to mobile phone |
| **email** | Send via email |
## Response
### Success Response
STATUS 200
Response Body: Token resent successfully
```json
{
"batch_payment_key": "a3214093-e51c-55e2-b5d3-60244475b3fb",
"request_control_key": "b6804f32-101e-4702-8fbc-c2dbc4c2caec",
"account_key": "daae79e6-ee8b-449f-aa1e-96959d5d5a72",
"total_amount": 2778.42,
"batch_status": "pending_2fa_approval",
"payment_type": "collection_slip"
}
```
### Response Body Params
| Field | Type | Description |
| ----------------------- | ------ | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `batch_payment_key` * | uuid4 | Unique batch payment identifier. |
| `request_control_key` * | uuid4 | Unique client request identifier (batch). |
| `account_key` * | uuid4 | Debited account key. |
| `total_amount` * | number | Sum of the amounts of all batch items. |
| `batch_status` * | string | After resend, the batch remains waiting for token validation. The `batch_status` cycle follows the batch payment request documentation available for your operation (enumerator `batch_payment_status`). |
| `payment_type` * | string | Payment type; for this flow, expected value is `collection_slip`. |
Then use [Batch collection slip token validation](./validacao_de_token_de_lote_de_fatura_de_recolhimento.md) to complete 2FA.
### Error Response
STATUS 4XX
Response Body
```json
{
"title": "Title",
"description": "Description in english",
"translation": "Description em português",
"code": "Code"
}
```
| HTTP code | QI code | Title | Description (eng) | Description (pt-br) |
| ----------- | --------- | ----------- | -------------------------------------------------------------------------------------------------- | --------------------------------------------------------------------------------------------------------- |
| 403 | BIP000010 | Forbidden | User is not allowed to do this action | User is not allowed to do this action |
| 404 | BIP000011 | Not Found | The source account key was not found. | The source account key was not found. |
| 400 | BIP000012 | Bad Request | It was not possible to consult the source account at this time. Please try again in a few minutes. | It was not possible to consult the source account at this time. Please try again in a few minutes. |
| 400 | BIP000013 | Bad Request | The source account is closed. | The source account is closed. |
| 400 | BIP000014 | Bad Request | The source account is blocked. | The source account is blocked. | |
| 400 | BIP000059 | Bad Request | Number of verification token validation attempts exceeded. | Number of verification token validation attempts exceeded. |
| 400 | BIP000064 | Bad Request | Error resending verification token | Error resending verification token |
| 400 | BIP000065 | Bad Request | Payment verification time window exceeded. | Payment verification time window exceeded. |
| 404 | BIP000083 | Not Found | Batch payment not found by batch payment key. | Batch payment not found by batch payment key. |
| 400 | BIP000085 | Bad Request | Batch payment status is not pending approval. | Batch payment status is not pending approval.
| 400 | BIP000086 | Bad Request | A token is required for SMS or email validation. | A token is required for SMS or email validation. |
---
# Request bank slip batch payment with two-factor authentication
URL: /en/documentation/baas/cobranca/2fa_v2/solicitar_pagamento_lote_de_boleto_bancario_com_confirmacao_de_lote
This endpoint allows requesting payment of multiple bank slips in a single request, with **`tfa_info`** when the operation requires two-factor authentication **at this request step**.
:::info Bank slip
A traditional bank slip (digitable line not starting with digit 8). It is registered in the Interbank Payment Chamber (CIP/Núclea) and can be paid at financial and payment institutions authorized by the Central Bank.
:::
:::info Flow after the request
After the request, the batch may remain waiting for [batch confirmation with two-factor authentication](./confirmacao_de_lote_de_boleto_bancario.md), according to operation rules. In this confirmation step, follow the flow with `tfa_info` described in that document.
:::
## Request
### Request Endpoint
ENDPOINT /bill_payment/account/ ACCOUNT_KEY /payments/batch_bank_slip
METHOD POST
### Request Path Params
| Field | Type | Description | Characters |
|---------------------|---------|-----------------------------------------|------------|
| `account_key` * | uuid4 | Unique account identifier. | 36 |
Request Body: Batch bank slip payment (without TFA at this step)
```json
{
"request_control_key": "b6804f32-101e-4702-8fbc-c2dbc4c2caec",
"bank_slip_payments": [
{
"request_control_key": "c7915a43-212f-5813-9adc-d3ed5d3d3bfd",
"digitable_line": "00190000090361557400500000024174396700000991000",
"payment_amount": 1156.8
},
{
"request_control_key": "d8a26b54-323a-4924-0aed-e4fe6e4e4c0e",
"barcode": "00190000090361557400500000024174396700000991000",
"payment_amount": 200.5
}
]
}
```
### Body Params
| Field | Type | Description |
|---------------------|---------------|-----------------------------------|
| `request_control_key` * | uuid4 | Unique client request identifier (batch). |
| `bank_slip_payments` * | array | List of bank slip payments. Limit of **1000** items per request. |
Each item in `bank_slip_payments` must include:
| Field | Type | Description |
|---------------------|---------------|-----------------------------------|
| `request_control_key` * | uuid4 | Unique client request identifier for that batch item. |
| `barcode` | string | Barcode. |
| `digitable_line` | string | Digitable line. |
| `payment_amount` * | number | Value a ser pago. |
:::danger Warning
For each item, the submitted `payment_amount` must be compatible with the internal bank slip lookup: if partial payment is **not** allowed, the amount must match the updated total; if allowed, `payment_amount` may follow title rules (including, when applicable, values above nominal), as in the single bank slip payment flow.
:::
### Object tfa_info
| Field | Type | Description |
| ---------------------------- | ------ | -------------------------------------------------------------------------------------------------------------------------------------------------- |
| `approver_document_number` * | string | Document number (CPF/CNPJ) of the approver who will receive the token or approve via device. Required when `tfa_info` is provided. |
| `session_id` | string | Unique device session identifier in UUID v4 format (**required** for device-based TFA). |
| `contact_type` * | string | Channel for token delivery or validation: **[contact_type enumerator](#enumerador-contact_type)**. Required when `tfa_info` is provided. |
#### Enumerator contact_type
| Enumerador | Description |
|------------|---------------------------------------------------|
| **sms** | Send via SMS to mobile phone |
| **email** | Send via email |
| **device** | Validation via device token |
## Response
### Success Response
STATUS 202
Response Body: Batch accepted for processing
```json
{
"batch_payment_key": "a3214093-e51c-55e2-b5d3-60244475b3fb",
"request_control_key": "b6804f32-101e-4702-8fbc-c2dbc4c2caec",
"account_key": "6dc89d57-fac7-4643-b151-cd2ca0a7f68f",
"total_amount": 1357.3,
"batch_status": "pending",
"payment_type": "bank_slip"
}
```
Response Body: exemplo ilustrativo (`batch_status` aprovado)
```json
{
"batch_payment_key": "a3214093-e51c-55e2-b5d3-60244475b3fb",
"request_control_key": "b6804f32-101e-4702-8fbc-c2dbc4c2caec",
"account_key": "6dc89d57-fac7-4643-b151-cd2ca0a7f68f",
"total_amount": 1357.3,
"batch_status": "approved",
"payment_type": "bank_slip"
}
```
:::info Batch processing
The `batch_status` field in the response indicates the **immediate state** of the batch after this request (for example, pending confirmation, pending 2FA approval, or already routed to processing), according to the applicable flow. When there is a [batch confirmation](./confirmacao_de_lote_de_boleto_bancario.md) step, follow that documentation to approve or reject the batch with two-factor authentication. Possible `batch_status` values are listed in [batch_payment_status](#enumeradores-batch_payment_status).
:::
### Response Body Params
| Field | Type | Description |
|---------------------|---------|-----------------------------------|
| `batch_payment_key` * | uuid4 | Unique batch payment identifier. |
| `request_control_key` * | uuid4 | Unique client request identifier (batch). |
| `account_key` * | uuid4 | Debited account key. |
| `total_amount` * | number | Sum of `payment_amount` across all batch items. |
| `batch_status` * | [enum](#enumeradores-batch_payment_status) | Batch status right after request; depends on the flow (confirmation, 2FA, and immediate processing). |
| `payment_type` * | [enum](#enumeradores-payment_type) | Payment type. |
### Enumeratores batch_payment_status
| Enumerador | Description |
|---------------|---------------|
| `pending` | Pendente de processamento |
| `pending_2fa_approval` | Pending 2FA approval |
| `rejected` | Rejeitado |
| `approved` | Aprovado |
| `processed` | Processado |
### Enumeratores payment_type
| Enumerador | Type | Description |
|---------------|-----------|---------------|
| `bank_slip` | string | Bank slip |
| `collection_slip` | string | Collection slip (utility/tax bill) |
:::danger Warning
The `collection_slip` enumerator does not apply to this bank slip batch endpoint; in this flow, `payment_type` must be `bank_slip`.
:::
### Error Response
STATUS 4XX
Response Body
```json
{
"title": "Title",
"description": "Description in english",
"translation": "Description em português",
"code": "Code"
}
```
| HTTP code | QI code | Title | Description (eng) | Description (pt-br) |
|-------------|-----------|--------|------------------|------------------|
| 403 | BIP000010 | Forbidden | User is not allowed to do this action | User is not allowed to do this action |
| 404 | BIP000011 | Not Found | The source account key was not found. | The source account key was not found. |
| 400 | BIP000012 | Bad Request | It was not possible to consult the source account at this time. Please try again in a few minutes. | It was not possible to consult the source account at this time. Please try again in a few minutes. |
| 400 | BIP000024 | Bad Request | Request control key already exists. | Request control key already exists. |
| 400 | BIP000050 | Bad Request | Requester configuration does not exist. | Requester configuration does not exist. |
| 400 | BIP000052 | Bad Request | Given document number does not belong to an approver for this account | Provided document number does not belong to an account approver |
| 400 | BIP000053 | Bad Request | Error getting approver data | Error getting approver data |
| 400 | BIP000054 | Bad Request | TFA info required | TFA info required |
| 400 | BIP000055 | Bad Request | Error sending verification token | Error sending verification token |
| 400 | BIP000065 | Bad Request | Payment verification time window exceeded. | Payment verification time window exceeded. |
| 400 | BIP000079 | Bad Request | A session_id must be provided token | A session_id must be provided |
| 400 | BIP000080 | Bad Request | Beneficiary bank code of this bank slip is not allowed. | Beneficiary bank code of this bank slip is not allowed. |
| 400 | BIP000081 | Bad Request | A list of bank slip payments must be provided. | A list of bank slip payments must be provided. |
---
# Solicitar pagamento em lote de boleto bancário com autenticação de dois fatores
URL: /en/documentation/baas/cobranca/2fa_v2/solicitar_pagamento_lote_de_boleto_bancario_sem_confirmacao_de_lote
Este endpoint permite solicitar o pagamento de múltiplos boletos bancários em uma única requisição, com **`tfa_info`** quando a operação exigir autenticação de dois fatores **nesta solicitação**.
:::info Boleto bancário
É o boleto bancário convencional (linhas digitáveis não iniciadas com dígito 8). Possui registro na Câmara Interbancária de Pagamento (CIP/Núclea) e pode ser pago em instituições financeiras e de pagamento autorizadas a funcionar pelo Banco Central.
:::
## Request
### Request Endpoint
ENDPOINT /bill_payment/account/ ACCOUNT_KEY /payments/batch_bank_slip
MÉTODO POST
### Request Path Params
| Campo | Tipo | Descrição | Caracteres |
|---------------------|---------|-----------------------------------------|------------|
| `account_key` * | uuid4 | Chave única de identificação da conta. | 36 |
## Autenticação via email e SMS
Request Body: lote com linha digitável e TFA por SMS ou email
```json
{
"request_control_key": "b6804f32-101e-4702-8fbc-c2dbc4c2caec",
"tfa_info": {
"approver_document_number": "98765432100",
"contact_type": "email"
},
"bank_slip_payments": [
{
"request_control_key": "c7915a43-212f-5813-9adc-d3ed5d3d3bfd",
"digitable_line": "00190000090361557400500000024174396700000991000",
"payment_amount": 1156.8
}
]
}
```
Request Body: lote com código de barras e TFA por SMS ou email
```json
{
"request_control_key": "b6804f32-101e-4702-8fbc-c2dbc4c2caec",
"tfa_info": {
"approver_document_number": "98765432100",
"contact_type": "email"
},
"bank_slip_payments": [
{
"request_control_key": "c7915a43-212f-5813-9adc-d3ed5d3d3bfd",
"barcode": "00190000090361557400500000024174396700000991000",
"payment_amount": 1156.8
}
]
}
```
## Autenticação via dispositivo
Além das formas já existentes de autenticação via **sms** e **email**, é possível autenticar a transação utilizando um dispositivo [previamente cadastrado](/documentation/baas/dispositivo/create/solicitacao_cadastro_dispositivo). Nesse caso, o `session_id` deve ser obtido na **Device Scan** e enviado no `tfa_info`.
Request Body: lote com linha digitável e TFA por dispositivo
```json
{
"request_control_key": "b6804f32-101e-4702-8fbc-c2dbc4c2caec",
"tfa_info": {
"approver_document_number": "98765432100",
"session_id": "b2f18d3a-67c2-4a7f-98e5-1d3f5c6b8a72",
"contact_type": "device"
},
"bank_slip_payments": [
{
"request_control_key": "c7915a43-212f-5813-9adc-d3ed5d3d3bfd",
"digitable_line": "00190000090361557400500000024174396700000991000",
"payment_amount": 1156.8
}
]
}
```
Request Body: lote com código de barras e TFA por dispositivo
```json
{
"request_control_key": "b6804f32-101e-4702-8fbc-c2dbc4c2caec",
"tfa_info": {
"approver_document_number": "98765432100",
"session_id": "b2f18d3a-67c2-4a7f-98e5-1d3f5c6b8a72",
"contact_type": "device"
},
"bank_slip_payments": [
{
"request_control_key": "c7915a43-212f-5813-9adc-d3ed5d3d3bfd",
"barcode": "00190000090361557400500000024174396700000991000",
"payment_amount": 1156.8
}
]
}
```
### Body Params
| Campo | Tipo | Descrição |
|---------------------|---------------|-----------------------------------|
| `request_control_key` * | uuid4 | Chave única de identificação da requisição do cliente (lote). |
| `tfa_info` | object | Quando o 2FA for exigido **nesta etapa** (solicitação do lote), envie aprovador e canal de envio do token no [objeto `tfa_info`](#objeto-tfa_info). Caso o fluxo não exija 2FA na solicitação, omita o campo. |
| `bank_slip_payments` * | array | Lista de pagamentos de boleto bancário. Limite de **1000** itens por requisição. |
Cada elemento de `bank_slip_payments` deve conter:
| Campo | Tipo | Descrição |
|---------------------|---------------|-----------------------------------|
| `request_control_key` * | uuid4 | Chave única de identificação da requisição do cliente para aquele item do lote. |
| `barcode` | string | Código de barras. |
| `digitable_line` | string | Linha digitável. |
| `payment_amount` * | number | Valor a ser pago. |
:::danger Aviso
Para cada item, o `payment_amount` enviado deve ser compatível com o que a consulta interna do boleto determinar: se o pagamento parcial **não** for permitido para aquele título, o valor deve corresponder ao total atualizado; se for permitido, o `payment_amount` pode seguir as regras do título (incluindo, quando aplicável, valores acima do nominal), como no fluxo de pagamento unitário de boleto bancário.
:::
### Objeto tfa_info
| Campo | Tipo | Descrição |
| ---------------------------- | ------ | -------------------------------------------------------------------------------------------------------------------------------------------------- |
| `approver_document_number` * | string | Documento (CPF/CNPJ) da pessoa aprovadora que receberá o token ou aprovará via dispositivo. Obrigatório quando `tfa_info` é enviado. |
| `session_id` | string | Chave única de identificação da sessão do dispositivo no formato UUID v4 (**obrigatório** para TFA via dispositivo). |
| `contact_type` * | string | Canal para envio ou validação do token: **[Enumerador contact_type](#enumerador-contact_type)**. Obrigatório quando `tfa_info` é enviado. |
#### Enumerador contact_type
| Enumerador | Descrição |
|------------|---------------------------------------------------|
| **sms** | Envio por mensagem de texto para telefone celular |
| **email** | Envio por correio eletrônico |
| **device** | Validação por token do dispositivo |
## Response
### Success Response
STATUS 201
Response Body: Lote pendente de aprovação de dois fatores
```json
{
"batch_payment_key": "a3214093-e51c-55e2-b5d3-60244475b3fb",
"request_control_key": "b6804f32-101e-4702-8fbc-c2dbc4c2caec",
"account_key": "6dc89d57-fac7-4643-b151-cd2ca0a7f68f",
"total_amount": 1357.3,
"batch_status": "pending_2fa_approval",
"payment_type": "bank_slip"
}
```
:::info Processamento do lote
O campo `batch_status` na resposta indica o **estado imediato** do lote após esta solicitação (por exemplo, pendente de aprovação 2FA ou já encaminhado ao processamento), conforme o fluxo aplicável. O 2FA pode integrar esta solicitação (`tfa_info`) ou outras etapas do fluxo, conforme a operação. Os valores possíveis de `batch_status` estão em [batch_payment_status](#enumeradores-batch_payment_status).
:::
### Response Body Params
| Campo | Tipo | Descrição |
|---------------------|---------|-----------------------------------|
| `batch_payment_key` * | uuid4 | Chave única de identificação do pagamento em lote. |
| `request_control_key` * | uuid4 | Chave única de identificação da requisição do cliente (lote). |
| `account_key` * | uuid4 | Chave da conta debitada. |
| `total_amount` * | number | Soma dos valores (`payment_amount`) dos itens do lote. |
| `batch_status` * | [enum](#enumeradores-batch_payment_status) | Status do lote logo após a solicitação; depende do fluxo (2FA e processamento imediato). |
| `payment_type` * | [enum](#enumeradores-payment_type) | Tipo do pagamento. |
### Enumeradores batch_payment_status
| Enumerador | Descrição |
|---------------|---------------|
| `pending` | Pendente de processamento |
| `pending_2fa_approval` | Lote pendente de 2FA para aprovação |
| `pending_2fa_rejection` | Lote pendente de 2FA para rejeição |
| `rejected` | Rejeitado |
| `approved` | Aprovado |
| `processed` | Processado |
### Enumeradores payment_type
| Enumerador | Tipo | Descrição |
|---------------|-----------|---------------|
| `bank_slip` | string | Boleto bancário |
| `collection_slip` | string | Fatura de recolhimento |
:::danger Aviso
O enumerador `collection_slip` não se aplica ao fluxo de lote de boletos bancários deste endpoint; para este caso, espera-se `payment_type` com valor `bank_slip`.
:::
### Error Response
STATUS 4XX
Response Body
```json
{
"title": "Título",
"description": "Description in english",
"translation": "Descrição em português",
"code": "Código"
}
```
| Código HTTP | Código QI | Título | Descrição (eng) | Descrição (pt-br) |
|-------------|-----------|--------|------------------|------------------|
| 403 | BIP000010 | Forbidden | User is not allowed to do this action | Usuário não tem autorização para fazer essa ação |
| 404 | BIP000011 | Not Found | The source account key was not found. | A chave da conta de origem não foi encontrada. |
| 400 | BIP000012 | Bad Request | It 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. |
| 400 | BIP000024 | Bad Request | Request control key already exists. | Chave de controle da requisição já existe. |
| 400 | BIP000050 | Bad Request | Requester configuration does not exist. | Configuração do requester não existe. |
| 400 | BIP000052 | Bad Request | Given document number does not belong to an approver for this account | Número de documento enviado não pertence a um aprovador da conta |
| 400 | BIP000053 | Bad Request | Error getting approver data | Erro ao obter dados do aprovador |
| 400 | BIP000054 | Bad Request | TFA info required | Informações de TFA necessárias |
| 400 | BIP000055 | Bad Request | Error sending verification token | Erro ao enviar token de verificação |
| 400 | BIP000065 | Bad Request | Payment verification time window exceeded. | Janela de tempo de verificação de pagamento excedida. |
| 400 | BIP000079 | Bad Request | A session_id must be provided token | Uma session_id deve ser fornecida |
| 400 | BIP000080 | Bad Request | Beneficiary bank code of this bank slip is not allowed. | Banco beneficiário desse boleto não é permitido. |
| 400 | BIP000081 | Bad Request | A list of bank slip payments must be provided. | Uma lista de boletos bancários deve ser fornecida. |
---
# Request collection slip (utility/tax) batch payment with two-factor authentication
URL: /en/documentation/baas/cobranca/2fa_v2/solicitar_pagamento_lote_de_fatura_de_recolhimento_com_confirmacao_de_lote
This endpoint allows requesting payment of multiple collection slips in a single request, with **`tfa_info`** when the operation requires two-factor authentication **at this request step**.
:::info Collection slip (utility/tax bill)
This charge type is issued by utility companies (water, electricity, phone, and gas) and public agencies (taxes). It is not registered in the Interbank Payment Chamber (CIP/Núclea), so it does not return the same information as a bank slip.
:::
:::info Flow after the request
After the request, the batch may remain waiting for [batch confirmation with two-factor authentication](./confirmacao_de_lote_de_fatura_de_recolhimento.md), according to operation rules. When 2FA is required at this request step, include **`tfa_info`** as shown below and in the [tfa_info object](#object-tfa_info). In the batch confirmation step for this flow, follow the documentation with `tfa_info`.
:::
## Request
### Request Endpoint
ENDPOINT /bill_payment/account/ ACCOUNT_KEY /payments/batch_collection_slip
METHOD POST
### Request Path Params
| Field | Type | Description | Characters |
|---------------------|---------|-----------------------------------------|------------|
| `account_key` * | uuid4 | Unique account identifier. | 36 |
Request Body: Batch collection slip payment (without TFA at this step)
```json
{
"request_control_key": "b6804f32-101e-4702-8fbc-c2dbc4c2caec",
"collection_slip_payments": [
{
"request_control_key": "c7915a43-212f-5813-9adc-d3ed5d3d3bfd",
"digitable_line": "836200000138892100450006762142420244046000010192",
"payment_amount": 1389.21
},
{
"request_control_key": "d8a26b54-323a-4924-0aed-e4fe6e4e4c0e",
"barcode": "83620000001388921004500067621424202440460000101",
"payment_amount": 1389.21
}
]
}
```
## Authentication via Email and SMS
Request Body: batch with digitable line and TFA via SMS or email
```json
{
"request_control_key": "b6804f32-101e-4702-8fbc-c2dbc4c2caec",
"tfa_info": {
"approver_document_number": "98765432100",
"contact_type": "email"
},
"collection_slip_payments": [
{
"request_control_key": "c7915a43-212f-5813-9adc-d3ed5d3d3bfd",
"digitable_line": "836200000138892100450006762142420244046000010192",
"payment_amount": 1389.21
}
]
}
```
Request Body: batch with barcode and TFA via SMS or email
```json
{
"request_control_key": "b6804f32-101e-4702-8fbc-c2dbc4c2caec",
"tfa_info": {
"approver_document_number": "98765432100",
"contact_type": "email"
},
"collection_slip_payments": [
{
"request_control_key": "c7915a43-212f-5813-9adc-d3ed5d3d3bfd",
"barcode": "83620000001388921004500067621424202440460000101",
"payment_amount": 1389.21
}
]
}
```
## Authentication via Device
Besides existing authentication methods via **sms** and **email**, you can authenticate the transaction using a [previously registered device](/documentation/baas/dispositivo/create/solicitacao_cadastro_dispositivo). In this case, `session_id` must be obtained in **Device Scan** and sent in `tfa_info`.
Request Body: batch with digitable line and device TFA
```json
{
"request_control_key": "b6804f32-101e-4702-8fbc-c2dbc4c2caec",
"tfa_info": {
"approver_document_number": "98765432100",
"session_id": "b2f18d3a-67c2-4a7f-98e5-1d3f5c6b8a72",
"contact_type": "device"
},
"collection_slip_payments": [
{
"request_control_key": "c7915a43-212f-5813-9adc-d3ed5d3d3bfd",
"digitable_line": "836200000138892100450006762142420244046000010192",
"payment_amount": 1389.21
}
]
}
```
Request Body: batch with barcode and device TFA
```json
{
"request_control_key": "b6804f32-101e-4702-8fbc-c2dbc4c2caec",
"tfa_info": {
"approver_document_number": "98765432100",
"session_id": "b2f18d3a-67c2-4a7f-98e5-1d3f5c6b8a72",
"contact_type": "device"
},
"collection_slip_payments": [
{
"request_control_key": "c7915a43-212f-5813-9adc-d3ed5d3d3bfd",
"barcode": "83620000001388921004500067621424202440460000101",
"payment_amount": 1389.21
}
]
}
```
### Body Params
| Field | Type | Description |
|---------------------|---------------|-----------------------------------|
| `request_control_key` * | uuid4 | Unique client request identifier (batch). |
| `tfa_info` | object | When 2FA is required **at this step** (batch request), send approver and token channel fields in the [tfa_info object](#object-tfa_info). If this flow does not require 2FA at request time, omit this field. |
| `collection_slip_payments` * | array | List of collection slip payments. Limit of **1000** items per request. |
Each item in `collection_slip_payments` must include:
| Field | Type | Description |
|---------------------|---------------|-----------------------------------|
| `request_control_key` * | uuid4 | Unique client request identifier for that batch item. |
| `barcode` | string | Barcode. |
| `digitable_line` | string | Digitable line. |
| `payment_amount` * | number | Value a ser pago. |
:::danger Warning
For each item, `payment_amount` must be compatible with the internal collection slip lookup (for example, aligned with `total_amount` and utility/tax rules), under the same conditions as the single collection slip payment flow.
:::
### Object tfa_info
| Field | Type | Description |
| ---------------------------- | ------ | -------------------------------------------------------------------------------------------------------------------------------------------------- |
| `approver_document_number` * | string | Document number (CPF/CNPJ) of the approver who will receive the token or approve via device. Required when `tfa_info` is provided. |
| `session_id` | string | Unique device session identifier in UUID v4 format (**required** for device-based TFA). |
| `contact_type` * | string | Channel for token delivery or validation: **[contact_type enumerator](#enumerador-contact_type)**. Required when `tfa_info` is provided. |
#### Enumerator contact_type
| Enumerador | Description |
|------------|---------------------------------------------------|
| **sms** | Send via SMS to mobile phone |
| **email** | Send via email |
| **device** | Validation via device token |
## Response
### Success Response
STATUS 202
Response Body: Batch accepted for processing
```json
{
"batch_payment_key": "a3214093-e51c-55e2-b5d3-60244475b3fb",
"request_control_key": "b6804f32-101e-4702-8fbc-c2dbc4c2caec",
"account_key": "daae79e6-ee8b-449f-aa1e-96959d5d5a72",
"total_amount": 2778.42,
"batch_status": "pending",
"payment_type": "collection_slip"
}
```
Response Body: exemplo ilustrativo (`batch_status` aprovado)
```json
{
"batch_payment_key": "a3214093-e51c-55e2-b5d3-60244475b3fb",
"request_control_key": "b6804f32-101e-4702-8fbc-c2dbc4c2caec",
"account_key": "daae79e6-ee8b-449f-aa1e-96959d5d5a72",
"total_amount": 2778.42,
"batch_status": "approved",
"payment_type": "collection_slip"
}
```
:::info Batch processing
The `batch_status` field in the response indicates the **immediate state** of the batch after this request (for example, pending confirmation, pending 2FA approval, or already routed to processing), according to the applicable flow. When there is a [batch confirmation](./confirmacao_de_lote_de_fatura_de_recolhimento.md) step, follow that documentation to approve or reject the batch with two-factor authentication. Possible `batch_status` values are listed in [batch_payment_status](#enumeradores-batch_payment_status).
:::
### Response Body Params
| Field | Type | Description |
|---------------------|---------|-----------------------------------|
| `batch_payment_key` * | uuid4 | Unique batch payment identifier. |
| `request_control_key` * | uuid4 | Unique client request identifier (batch). |
| `account_key` * | uuid4 | Debited account key. |
| `total_amount` * | number | Sum of `payment_amount` across all batch items. |
| `batch_status` * | [enum](#enumeradores-batch_payment_status) | Batch status right after request; depends on the flow (confirmation, 2FA, and immediate processing). |
| `payment_type` * | [enum](#enumeradores-payment_type) | Payment type. |
### Enumeratores batch_payment_status
| Enumerador | Description |
|---------------|---------------|
| `pending` | Pendente de processamento |
| `pending_2fa_approval` | Pending 2FA approval |
| `rejected` | Rejeitado |
| `approved` | Aprovado |
| `processed` | Processado |
### Enumeratores payment_type
| Enumerador | Type | Description |
|---------------|-----------|---------------|
| `bank_slip` | string | Bank slip |
| `collection_slip` | string | Collection slip (utility/tax bill) |
:::danger Warning
The `bank_slip` enumerator does not apply to this collection slip batch endpoint; in this flow, `payment_type` must be `collection_slip`.
:::
### Error Response
STATUS 4XX
Response Body
```json
{
"title": "Title",
"description": "Description in english",
"translation": "Description em português",
"code": "Code"
}
```
| HTTP code | QI code | Title | Description (eng) | Description (pt-br) |
|-------------|-----------|--------|------------------|------------------|
| 400 | BIP000024 | Bad Request | Request control key already exists. | Request control key already exists. |
| 400 | BIP000050 | Bad Request | Requester configuration does not exist. | Requester configuration does not exist. |
| 400 | BIP000052 | Bad Request | Given document number does not belong to an approver for this account | Provided document number does not belong to an account approver |
| 400 | BIP000053 | Bad Request | Error getting approver data | Error getting approver data |
| 400 | BIP000054 | Bad Request | TFA info required | TFA info required |
| 400 | BIP000055 | Bad Request | Error sending verification token | Error sending verification token |
| 400 | BIP000065 | Bad Request | Payment verification time window exceeded. | Payment verification time window exceeded. |
| 400 | BIP000079 | Bad Request | A session_id must be provided token | A session_id must be provided |
| 400 | BIP000082 | Bad Request | A list of collection slip payments must be provided. | A list of collection slip payments must be provided. |
---
# Solicitar pagamento em lote de fatura de recolhimento (convênio/tributo) com autenticação de dois fatores
URL: /en/documentation/baas/cobranca/2fa_v2/solicitar_pagamento_lote_de_fatura_de_recolhimento_sem_confirmacao_de_lote
Este endpoint permite solicitar o pagamento de múltiplas faturas de recolhimento em uma única requisição, com **`tfa_info`** quando a operação exigir autenticação de dois fatores **nesta solicitação**.
:::info Fatura de recolhimento
Esse tipo de cobrança é emitido por concessionárias de serviços (conta de água, luz, telefone e gás) e órgãos públicos (tributos). Eles não são registrados na Câmara Interbancária de Pagamento (CIP/Núclea), por isso, não retornam as mesmas informações que um boleto bancário apresenta.
:::
:::info Fluxo após a solicitação
A **autenticação de dois fatores (2FA)** é exigida **nesta solicitação**; o corpo deve incluir **`tfa_info`** conforme as seções abaixo e o [objeto `tfa_info`](#objeto-tfa_info).
:::
## Request
### Request Endpoint
ENDPOINT /bill_payment/account/ ACCOUNT_KEY /payments/batch_collection_slip
MÉTODO POST
### Request Path Params
| Campo | Tipo | Descrição | Caracteres |
|---------------------|---------|-----------------------------------------|------------|
| `account_key` * | uuid4 | Chave única de identificação da conta. | 36 |
## Autenticação via email e SMS
Request Body: lote com linha digitável e TFA por SMS ou email
```json
{
"request_control_key": "b6804f32-101e-4702-8fbc-c2dbc4c2caec",
"tfa_info": {
"approver_document_number": "98765432100",
"contact_type": "email"
},
"collection_slip_payments": [
{
"request_control_key": "c7915a43-212f-5813-9adc-d3ed5d3d3bfd",
"digitable_line": "836200000138892100450006762142420244046000010192",
"payment_amount": 1389.21
}
]
}
```
Request Body: lote com código de barras e TFA por SMS ou email
```json
{
"request_control_key": "b6804f32-101e-4702-8fbc-c2dbc4c2caec",
"tfa_info": {
"approver_document_number": "98765432100",
"contact_type": "email"
},
"collection_slip_payments": [
{
"request_control_key": "c7915a43-212f-5813-9adc-d3ed5d3d3bfd",
"barcode": "83620000001388921004500067621424202440460000101",
"payment_amount": 1389.21
}
]
}
```
## Autenticação via dispositivo
Além das formas já existentes de autenticação via **sms** e **email**, é possível autenticar a transação utilizando um dispositivo [previamente cadastrado](/documentation/baas/dispositivo/create/solicitacao_cadastro_dispositivo). Nesse caso, o `session_id` deve ser obtido na **Device Scan** e enviado no `tfa_info`.
Request Body: lote com linha digitável e TFA por dispositivo
```json
{
"request_control_key": "b6804f32-101e-4702-8fbc-c2dbc4c2caec",
"tfa_info": {
"approver_document_number": "98765432100",
"session_id": "b2f18d3a-67c2-4a7f-98e5-1d3f5c6b8a72",
"contact_type": "device"
},
"collection_slip_payments": [
{
"request_control_key": "c7915a43-212f-5813-9adc-d3ed5d3d3bfd",
"digitable_line": "836200000138892100450006762142420244046000010192",
"payment_amount": 1389.21
}
]
}
```
Request Body: lote com código de barras e TFA por dispositivo
```json
{
"request_control_key": "b6804f32-101e-4702-8fbc-c2dbc4c2caec",
"tfa_info": {
"approver_document_number": "98765432100",
"session_id": "b2f18d3a-67c2-4a7f-98e5-1d3f5c6b8a72",
"contact_type": "device"
},
"collection_slip_payments": [
{
"request_control_key": "c7915a43-212f-5813-9adc-d3ed5d3d3bfd",
"barcode": "83620000001388921004500067621424202440460000101",
"payment_amount": 1389.21
}
]
}
```
### Body Params
| Campo | Tipo | Descrição |
|---------------------|---------------|-----------------------------------|
| `request_control_key` * | uuid4 | Chave única de identificação da requisição do cliente (lote). |
| `tfa_info` | object | Quando o 2FA for exigido **nesta etapa** (solicitação do lote), envie aprovador e canal de envio do token no [objeto `tfa_info`](#objeto-tfa_info). Caso o fluxo não exija 2FA na solicitação, omita o campo. |
| `collection_slip_payments` * | array | Lista de pagamentos de fatura de recolhimento. Limite de **1000** itens por requisição. |
Cada elemento de `collection_slip_payments` deve conter:
| Campo | Tipo | Descrição |
|---------------------|---------------|-----------------------------------|
| `request_control_key` * | uuid4 | Chave única de identificação da requisição do cliente para aquele item do lote. |
| `barcode` | string | Código de barras. |
| `digitable_line` | string | Linha digitável. |
| `payment_amount` * | number | Valor a ser pago. |
:::danger Aviso
Para cada item, o `payment_amount` enviado deve ser compatível com o que a consulta interna da fatura de recolhimento determinar (por exemplo, alinhado ao `total_amount` e às regras do convênio/tributo), nas mesmas condições do fluxo de pagamento unitário de fatura de recolhimento.
:::
### Objeto tfa_info
Os campos seguem o mesmo formato da [solicitação de pagamento de fatura de recolhimento](./solicitacao_de_pagamento_de_fatura_de_recolhimento.md#objeto-tfa_info).
| Campo | Tipo | Descrição |
| ---------------------------- | ------ | -------------------------------------------------------------------------------------------------------------------------------------------------- |
| `approver_document_number` * | string | Documento (CPF/CNPJ) da pessoa aprovadora que receberá o token ou aprovará via dispositivo. Obrigatório quando `tfa_info` é enviado. |
| `session_id` | string | Chave única de identificação da sessão do dispositivo no formato UUID v4 (**obrigatório** para TFA via dispositivo). |
| `contact_type` * | string | Canal para envio ou validação do token: **[Enumerador contact_type](#enumerador-contact_type)**. Obrigatório quando `tfa_info` é enviado. |
#### Enumerador contact_type
| Enumerador | Descrição |
|------------|---------------------------------------------------|
| **sms** | Envio por mensagem de texto para telefone celular |
| **email** | Envio por correio eletrônico |
| **device** | Validação por token do dispositivo |
## Response
### Success Response
STATUS 202
Response Body: Lote aceito para processamento
```json
{
"batch_payment_key": "a3214093-e51c-55e2-b5d3-60244475b3fb",
"request_control_key": "b6804f32-101e-4702-8fbc-c2dbc4c2caec",
"account_key": "daae79e6-ee8b-449f-aa1e-96959d5d5a72",
"total_amount": 2778.42,
"batch_status": "pending",
"payment_type": "collection_slip"
}
```
Response Body: exemplo ilustrativo com `batch_status` aprovado
```json
{
"batch_payment_key": "a3214093-e51c-55e2-b5d3-60244475b3fb",
"request_control_key": "b6804f32-101e-4702-8fbc-c2dbc4c2caec",
"account_key": "daae79e6-ee8b-449f-aa1e-96959d5d5a72",
"total_amount": 2778.42,
"batch_status": "approved",
"payment_type": "collection_slip"
}
```
:::info Processamento do lote
O campo `batch_status` na resposta indica o **estado imediato** do lote após esta solicitação (por exemplo, pendente de aprovação 2FA ou já encaminhado ao processamento), conforme o fluxo aplicável. O 2FA pode integrar esta solicitação (`tfa_info`) ou outras etapas do fluxo, conforme a operação. Os valores possíveis de `batch_status` estão em [batch_payment_status](#enumeradores-batch_payment_status).
:::
### Response Body Params
| Campo | Tipo | Descrição |
|---------------------|---------|-----------------------------------|
| `batch_payment_key` * | uuid4 | Chave única de identificação do pagamento em lote. |
| `request_control_key` * | uuid4 | Chave única de identificação da requisição do cliente (lote). |
| `account_key` * | uuid4 | Chave da conta debitada. |
| `total_amount` * | number | Soma dos valores (`payment_amount`) dos itens do lote. |
| `batch_status` * | [enum](#enumeradores-batch_payment_status) | Status do lote logo após a solicitação; depende do fluxo (2FA e processamento imediato). |
| `payment_type` * | [enum](#enumeradores-payment_type) | Tipo do pagamento. |
### Enumeradores batch_payment_status
| Enumerador | Descrição |
|---------------|---------------|
| `pending` | Pendente de processamento |
| `pending_2fa_approval` | Pendente de aprovação 2FA |
| `rejected` | Rejeitado |
| `approved` | Aprovado |
| `processed` | Processado |
### Enumeradores payment_type
| Enumerador | Tipo | Descrição |
|---------------|-----------|---------------|
| `bank_slip` | string | Boleto bancário |
| `collection_slip` | string | Fatura de recolhimento |
:::danger Aviso
O enumerador `bank_slip` não se aplica ao fluxo de lote de faturas de recolhimento deste endpoint; para este caso, espera-se `payment_type` com valor `collection_slip`.
:::
### Error Response
STATUS 4XX
Response Body
```json
{
"title": "Título",
"description": "Description in english",
"translation": "Descrição em português",
"code": "Código"
}
```
| Código HTTP | Código QI | Título | Descrição (eng) | Descrição (pt-br) |
|-------------|-----------|--------|------------------|------------------|
| 400 | BIP000024 | Bad Request | Request control key already exists. | Chave de controle da requisição já existe. |
| 400 | BIP000050 | Bad Request | Requester configuration does not exist. | Configuração do requester não existe. |
| 400 | BIP000052 | Bad Request | Given document number does not belong to an approver for this account | Número de documento enviado não pertence a um aprovador da conta |
| 400 | BIP000053 | Bad Request | Error getting approver data | Erro ao obter dados do aprovador |
| 400 | BIP000054 | Bad Request | TFA info required | Informações de TFA necessárias |
| 400 | BIP000055 | Bad Request | Error sending verification token | Erro ao enviar token de verificação |
| 400 | BIP000065 | Bad Request | Payment verification time window exceeded. | Janela de tempo de verificação de pagamento excedida. |
| 400 | BIP000079 | Bad Request | A session_id must be provided token | Uma session_id deve ser fornecida |
| 400 | BIP000082 | Bad Request | A list of collection slip payments must be provided. | Uma lista de faturas de recolhimento deve ser fornecida. |
---
# Token validation for bank slip payment batch
URL: /en/documentation/baas/cobranca/2fa_v2/validacao_de_token_de_lote_de_boleto_bancario
This endpoint completes the **two-factor authentication (2FA)** step for a bank slip batch that, after [batch confirmation with `tfa_info`](../confirmacao_de_lote_de_boleto_bancario_autenticacao_dois_fatores.md), is in `batch_status` **`pending_2fa_approval`** (approval) or **`pending_2fa_rejection`** (rejection). After token validation, the batch proceeds to **asynchronous payment processing**, and the final status reflects the decision recorded at confirmation (`approved` or `rejected`). To request a new token while the batch is in **pending_2fa_approval** (approval) or **pending_2fa_rejection** (rejection), use [Resend token for bank slip payment batch confirmation](./solicitacao_de_reenvio_de_token_de_lote_de_boleto_bancario.md).
:::info Bank slip
A traditional bank slip (digitable line not starting with digit 8). It is registered in the Interbank Payment Chamber (CIP/Núclea) and can be paid at financial and payment institutions authorized by the Central Bank.
:::
## Request
### Request Endpoint
ENDPOINT /bill_payment/account/**ACCOUNT_KEY**/payment/batch_bank_slip/**PAYMENT_BATCH_KEY**/validate_token
METHOD PATCH
### Request Path Params
| Field | Type | Description | Characters |
| --------------------- | ----- | ---------------------------------------------------------------------------------------- | ---------- |
| `account_key` * | uuid4 | Unique account identifier. | 36 |
| `payment_batch_key` * | uuid4 | Unique batch identifier (`batch_payment_key` returned at batch creation). | 36 |
### Authentication via Email and SMS
Request Body: Batch token validation
```json
{
"token": "329adf"
}
```
### Authentication via Device
To complete device authentication, the request must be sent with an empty payload. Validation is performed internally, with no additional request body information required. This endpoint should only be used after the batch enters **`pending_2fa_approval`** (approval) or **`pending_2fa_rejection`** (rejection) at [batch confirmation with `tfa_info`](../confirmacao_de_lote_de_boleto_bancario_autenticacao_dois_fatores.md).
Request Body: Batch token validation
```json
{
}
```
### Body Params
| Field | Type | Description | Characters |
| ------- | ------ | ---------------------------------------------------------------------------------------------------------------- | ---------- |
| `token` | string | Authentication code sent to the account transaction approver **required for TFA via SMS or email** | 6 |
## Response
### Success Response
After successful validation, the API responds with **202** and the batch is processed asynchronously. The final status follows the decision registered in confirmation (`approved` or `rejected`).
STATUS 202
Response Body: Batch after token validation (example with `approved` decision)
```json
{
"batch_payment_key": "a3214093-e51c-55e2-b5d3-60244475b3fb",
"request_control_key": "b6804f32-101e-4702-8fbc-c2dbc4c2caec",
"account_key": "6dc89d57-fac7-4643-b151-cd2ca0a7f68f",
"total_amount": 1357.3,
"batch_status": "approved",
"payment_type": "bank_slip"
}
```
### Response Body Params
| Field | Type | Description |
| ----------------------- | ------ | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `batch_payment_key` * | uuid4 | Unique batch payment identifier. |
| `request_control_key` * | uuid4 | Unique client request identifier (batch). |
| `account_key` * | uuid4 | Debited account key. |
| `total_amount` * | number | Sum of the amounts of all batch items. |
| `batch_status` * | string | After token validation, the final status reflects the decision registered during confirmation (`approved` or `rejected`). The `batch_status` cycle follows the batch payment request documentation available for your operation (enumerator `batch_payment_status`). |
| `payment_type` * | string | Payment type; for this flow, expected value is `bank_slip`. |
### Error Response
STATUS 4XX
Response Body
```json
{
"title": "Title",
"description": "Description in english",
"translation": "Description em português",
"code": "Code"
}
```
| HTTP code | QI code | Title | Description (eng) | Description (pt-br) |
| ----------- | --------- | ----------- | --------------------------------------------- | ---------------------------------------------------------------- |
| 403 | BIP000010 | Forbidden | User is not allowed to do this action | User is not allowed to do this action |
| 404 | BIP000011 | Not Found | The source account key was not found. | The source account key was not found. |
| 400 | BIP000013 | Bad Request | The source account is closed. | The source account is closed. |
| 400 | BIP000050 | Bad Request | Requester configuration does not exist | Requester configuration does not exist. |
| 400 | BIP000058 | Bad Request | Error while validating verification token | Error while validating verification token |
| 400 | BIP000059 | Bad Request | Number of verification token validation attempts exceeded. | Number of verification token validation attempts exceeded. |
| 400 | BIP000060 | Bad Request | Verification token expired. | Verification token expired. |
| 400 | BIP000061 | Bad Request | Verification token validation failed. | Verification token validation failed. |
| 400 | BIP000065 | Bad Request | Payment verification time window exceeded. | Payment verification time window exceeded. |
| 404 | BIP000083 | Not Found | Batch payment not found by batch payment key. | Batch payment not found by batch payment key. |
| 400 | BIP000085 | Bad Request | Batch payment status is not pending approval. | Batch payment status is not pending approval. |
| 400 | BIP000086 | Bad Request | A token is required for SMS or email validation. | A token is required for SMS or email validation. |
---
# Token validation for collection slip payment batch (utility/tax)
URL: /en/documentation/baas/cobranca/2fa_v2/validacao_de_token_de_lote_de_fatura_de_recolhimento
This endpoint completes the **two-factor authentication (2FA)** step for a collection slip batch that, after [batch confirmation with `tfa_info`](../confirmacao_de_lote_de_fatura_de_recolhimento_autenticacao_dois_fatores.md), is in `batch_status` **`pending_2fa_approval`** (approval) or **`pending_2fa_rejection`** (rejection). After token validation, the batch proceeds to **asynchronous payment processing**, and the final status reflects the decision recorded at confirmation (`approved` or `rejected`). To request a new token while the batch is in **pending_2fa_approval** (approval) or **pending_2fa_rejection** (rejection), use [Resend token for collection slip payment batch confirmation (utility/tax)](./solicitacao_de_reenvio_de_token_de_lote_de_fatura_de_recolhimento.md).
:::info Collection slip (utility/tax bill)
This charge type is issued by utility companies (water, electricity, phone, and gas) and public agencies (taxes). It is not registered in the Interbank Payment Chamber (CIP/Núclea), so it does not return the same information as a bank slip.
:::
## Request
### Request Endpoint
ENDPOINT /bill_payment/account/**ACCOUNT_KEY**/payment/batch_collection_slip/**PAYMENT_BATCH_KEY**/validate_token
METHOD PATCH
### Request Path Params
| Field | Type | Description | Characters |
| --------------------- | ----- | ---------------------------------------------------------------------------------------- | ---------- |
| `account_key` * | uuid4 | Unique account identifier. | 36 |
| `payment_batch_key` * | uuid4 | Unique batch identifier (`batch_payment_key` returned at batch creation). | 36 |
### Authentication via Email and SMS
Request Body: Batch token validation
```json
{
"token": "329adf"
}
```
### Authentication via Device
To complete device authentication, the request must be sent with an empty payload. Validation is performed internally, with no additional request body information required. This endpoint should only be used after the batch enters **`pending_2fa_approval`** (approval) or **`pending_2fa_rejection`** (rejection) at [batch confirmation with `tfa_info`](../confirmacao_de_lote_de_fatura_de_recolhimento_autenticacao_dois_fatores.md).
Request Body: Batch token validation
```json
{
}
```
### Body Params
| Field | Type | Description | Characters |
| ------- | ------ | ---------------------------------------------------------------------------------------------------------------- | ---------- |
| `token` | string | Authentication code sent to the account transaction approver **required for TFA via SMS or email** | 6 |
## Response
### Success Response
After successful validation, the API responds with **202** and the batch is processed asynchronously. The final status follows the decision registered in confirmation (`approved` or `rejected`).
STATUS 202
Response Body: Batch after token validation (example with `approved` decision)
```json
{
"batch_payment_key": "a3214093-e51c-55e2-b5d3-60244475b3fb",
"request_control_key": "b6804f32-101e-4702-8fbc-c2dbc4c2caec",
"account_key": "daae79e6-ee8b-449f-aa1e-96959d5d5a72",
"total_amount": 2778.42,
"batch_status": "approved",
"payment_type": "collection_slip"
}
```
### Response Body Params
| Field | Type | Description |
| ----------------------- | ------ | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `batch_payment_key` * | uuid4 | Unique batch payment identifier. |
| `request_control_key` * | uuid4 | Unique client request identifier (batch). |
| `account_key` * | uuid4 | Debited account key. |
| `total_amount` * | number | Sum of the amounts of all batch items. |
| `batch_status` * | string | After token validation, the final status reflects the decision registered during confirmation (`approved` or `rejected`). The `batch_status` cycle follows the batch payment request documentation available for your operation (enumerator `batch_payment_status`). |
| `payment_type` * | string | Payment type; for this flow, expected value is `collection_slip`. |
### Error Response
STATUS 4XX
Response Body
```json
{
"title": "Title",
"description": "Description in english",
"translation": "Description em português",
"code": "Code"
}
```
| HTTP code | QI code | Title | Description (eng) | Description (pt-br) |
| ----------- | --------- | ----------- | --------------------------------------------- | ---------------------------------------------------------------- |
| 403 | BIP000010 | Forbidden | User is not allowed to do this action | User is not allowed to do this action |
| 404 | BIP000011 | Not Found | The source account key was not found. | The source account key was not found. |
| 400 | BIP000013 | Bad Request | The source account is closed. | The source account is closed. |
| 400 | BIP000050 | Bad Request | Requester configuration does not exist | Requester configuration does not exist. |
| 400 | BIP000058 | Bad Request | Error while validating verification token | Error while validating verification token |
| 400 | BIP000059 | Bad Request | Number of verification token validation attempts exceeded. | Number of verification token validation attempts exceeded. |
| 400 | BIP000060 | Bad Request | Verification token expired. | Verification token expired. |
| 400 | BIP000061 | Bad Request | Verification token validation failed. | Verification token validation failed. |
| 400 | BIP000065 | Bad Request | Payment verification time window exceeded. | Payment verification time window exceeded. |
| 404 | BIP000083 | Not Found | Batch payment not found by batch payment key. | Batch payment not found by batch payment key. |
| 400 | BIP000085 | Bad Request | Batch payment status is not pending approval. | Batch payment status is not pending approval. |
| 400 | BIP000086 | Bad Request | A token is required for SMS or email validation. | A token is required for SMS or email validation. |
---
# Schedule Boleto payment
URL: /en/documentation/baas/cobranca/agendamento/agendar_pagamento_de_boleto_bancario
This endpoint allows scheduling the payment of boletos. The scheduling should be made after consulting the boleto, using the returned information to ensure the correct flow and avoid failures during the payment process.
:::info Boleto
This is the conventional boleto (with digitable lines not starting with the digit 8). It is registered with the Interbank Payment Clearinghouse (CIP/Núclea) and can be paid at financial institutions and payment institutions authorized to operate by the Central Bank.
:::
## Request
ENDPOINT /account/ ACCOUNT_KEY /payment_schedule/bank_slip
METHOD POST
### Request Path Params
| Field | Type | Description | Characters |
|----------------|--------|-------------------------------------------|------------|
| `account_key` *| uuidv4 | Unique account identification key. | 36 |
Request Body: Payment of boleto with digitable line
```json
{
"request_control_key": "b6804f32-101e-4702-8fbc-c2dbc4c2caec",
"digitable_line": "00190000090361557400500000024174396700000991000",
"payment_amount": 1156.8,
"payment_date": "2024-03-30"
}
```
Request Body: Payment of boleto with barcode
```json
{
"request_control_key": "b6804f32-101e-4702-8fbc-c2dbc4c2caec",
"barcode": "00190000090361557400500000024174396700000991000",
"payment_amount": 1156.8,
"payment_date": "2024-03-30"
}
```
### Body Params
| Field | Type | Description |
|-----------------------|--------|--------------------------------------------------------|
| `request_control_key` * | uuid4 | Unique identification key for the client's request. |
| `barcode` | string | Barcode. |
| `digitable_line` | string | Digitable line. |
| `payment_amount` * | number | Amount to be paid. |
| `payment_date` * | string | Scheduling date. |
:::danger Warning
The `payment_amount` must always be equal to the `total_amount` returned in the boleto query if partial payment is not allowed for the boleto. For titles where partial payment is allowed, the client may choose the `payment_amount`, as long as its sum with the boleto's `registered_payment_amount` does not exceed the `total_amount`.
:::
## Response
### Success Response
STATUS 201
Response Body: Schedule confirmed
```json
{
"payment_key":"c4325104-d60b-44f3-aae4-49155564a2ea",
"request_control_key":"b713b2f6-2f48-4d18-b0c9-7186e4edf189",
"payer_name":"COOPERATIVA INDUSTRIAL MURILO",
"payer_document_number":"00037025000160",
"source_account_key":"6dc89d57-fac7-4643-b151-cd2ca0a7f68f",
"paid_amount":1050.1,
"payment_date":"2024-04-03",
"payment_type":"bank_slip",
"bank_slip": {
"bank_slip_key":"95080ffd-3ac5-48d7-b3fe-659e4aaba81a",
"barcode":"00193967000009910000000003615574000000002417",
"digitable_line":"00190000090361557400500000024174396700000991000",
"payer_name":"COOPERATIVA TESTE",
"payer_document_number":"00037025000160",
"beneficiary_name":"TESTE EQUIPAMENTOS E SERVICOS LTDA",
"beneficiary_trading_name":"TESTE EQUIPAMENTOS E SERVICOS LTDA",
"beneficiary_document_number":"52069937000117",
"beneficiary_bank_ispb":"00000000",
"guarantor_name":null,
"guarantor_document_number":null,
"expiration_date":"2024-03-29",
"max_payment_data": "2026-03-29",
"partial_payment_indicator":"allowed",
"registered_payment_amount":9029.0,
"nominal_amount":9910.0,
"total_amount":10129.1,
"rebate_amount":0.0,
"discount_amount":0.0,
"fine_amount":0.0,
"interest_amount":219.1
},
"collection_slip":null,
"payment_schedule_status":"scheduled"
}
```
### Response Body Params
| Field | Type | Description |
|----------------------|--------|-------------------------------------------------------------------|
| `payment_key` * | uuid4 | Unique payment identification key. |
| `request_control_key` * | uuid4| Unique identification key for the client's request. |
| `payer_name` * | string | Name of the effective payer. |
| `payer_document_number` * | string| Document number of the effective payer (CPF/CNPJ). |
| `source_account_key` * | uuid4 | Key of the debited account. |
| `paid_amount` * | number | Amount effectively paid. |
| `payment_date` * | string | Payment date. |
| `payment_type` * | [enum](#enumeradores-payment_type) | Payment type. |
| `bank_slip` | [object](#object-bank_slip) | Boleto. |
| `collection_slip` | object | Collection invoice. |
| `payment_schedule_status` * | [enum](#enumeradores-payment_schedule_status) | Payment status. |
### Enumeradores payment_type
| Enumerator | Description |
|---------------------|---------------------------|
| `bank_slip` | Boleto |
| `collection_slip` | Collection invoice |
:::danger Warning
The enumerator `collection_slip` does not apply to the boleto flow, and the collection_slip object will always be null.
:::
### Enumeradores payment_schedule_status
| Enumerator | Description |
|---------------------------|------------------------------------------------------------------------------------------------|
| `pending_2fa_approval` | Schedule pending two-factor authentication (2FA) |
| `scheduled` | Payment successfully scheduled |
| `executed` | The payment related to the schedule was successfully executed |
| `rejected` | The payment related to the schedule was rejected |
| `canceled` | Schedule canceled |
| `error` | Error during scheduling |
:::danger Warning
For payments where QI does not receive a response from CIP within two minutes, the payment will be returned with the status `pending_execution`. After QI receives the response from CIP, the pending payment webhook described on the [webhooks page](/documentation/baas_v2/cobranca/webhooks) will be sent to the client.
:::
### Object bank_slip
| Field | Type | Description |
|-------------------------|-----------|-----------------------------------------------------------------------------|
| `barcode` * | string | Barcode. |
| `digitable_line` * | string | Digitable line. |
| `payer_name` * | string | Payer's name. |
| `payer_document_number` * | string | Payer's document number (CPF/CNPJ). |
| `beneficiary_name` * | string | Beneficiary's name. |
| `beneficiary_trading_name` | string | Beneficiary's trade name. |
| `beneficiary_document_number` * | string | Beneficiary's document number (CPF/CNPJ). |
| `beneficiary_bank_ispb` * | string | ISPB code of the beneficiary's bank. |
| `guarantor_name` | string | Name of the guarantor. |
| `guarantor_document_number` | string | Guarantor's document number (CPF/CNPJ). |
| `expiration_date` * | string | Due date. |
| `max_payment_date` * | string | Maximum payment date. |
| `partial_payment_indicator` * | [enum](#enumeradores-partial_payment_indicator) | Partial payment indicator. |
| `registered_payment_amount` | string| Total registered payment amount. |
| `nominal_amount` * | number | Original amount. |
| `total_amount` * | number | Total amount. |
| `rebate_amount` * | number | Rebate amount. |
| `discount_amount` * | number | Discount amount. |
| `fine_amount` * | number | Fine amount. |
| `interest_amount` * | number | Interest amount. |
### Enumeradores partial_payment_indicator
| Enumerator | Description |
|--------------- |-----------------------|
| `allowed` | Allowed |
| `not_allowed` | Not allowed |
### Error Response
STATUS 4XX
Response Body
```json
{
"title": "Título",
"description": "Description in english",
"translation": "Description in portuguese",
"code": "Código"
}
```
| HTTP Code | QI Code | Title | Description (eng) | Description (pt-br) |
|-------------|-----------|--------|------------------|------------------|
| 400 | BIP000001 | Bad Request | The barcode or digitable line must have 44 or 47 characters. | O código de barras ou linha digitável deve ter 44 ou 47 caracteres. |
| 400 | BIP000002 | Bad Request | The bill sent does not correspond to a bank slip. | A conta enviado não corresponde a um boleto bancário. |
| 400 | BIP000003 | Bad Request | The digitable line sent is invalid. | A linha digitável enviada é inválida. |
| 404 | BIP000004 | Not Found | The bank slip was not found. | O boleto não foi encontrado. |
| 400 | BIP000005 | Bad Request | It was not possible to consult the bank slip at this time. Please try again in a few minutes. | Não foi possível consultar o boleto neste momento. Por favor, tente novamente em alguns minutos. |
| 400 | BIP000006 | Bad Request | Bank slip already written off | Boleto já baixado |
| 400 | BIP000007 | Bad Request | Bank slip blocked for payment | Boleto bloqueado para pagamento |
| 400 | BIP000008 | Bad Request | Bank slip already paid | Boleto já pago |
| 400 | BIP000009 | Bad Request | Invalid bank slip. Please consult issuing bank | Boleto inválido. Favor consultar banco emissor |
| 403 | BIP000010 | Forbidden | User is not allowed to do this action | Usuário não tem autorização para fazer essa ação |
| 404 | BIP000011 | Not Found | The source account key was not found. | A chave da conta de origem não foi encontrada. |
| 400 | BIP000012 | Bad Request | It 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. |
| 400 | BIP000013 | Bad Request | The source account is closed. | A conta de origem está fechada. |
| 400 | BIP000014 | Bad Request | The source account is blocked. | A conta de origem está bloqueada. |
| 400 | BIP000015 | Bad Request | Payment date is greater than the maximum payment date. | A data de pagamento é maior que a data máxima de pagamento. |
| 400 | BIP000016 | Bad Request | Payment date is smaller than the calculation date. | A data de pagamento é menor que a data de cálculo. |
| 400 | BIP000017 | Bad Request | Invalid payment amount. | Valor de pagamento inválido. |
| 400 | BIP000018 | Bad Request | Partial payment is not allowed. | Pagamento parcial não é permitido. |
| 400 | BIP000019 | Bad Request | The payment amount is greater than the available amount. | O valor do pagamento é maior que o valor disponível. |
| 400 | BIP000020 | Bad Request | All partial payments for this bank slip have already been made. | Todos os pagamentos parciais deste boleto já foram realizados. |
| 400 | BIP000022 | Bad Request | Bank slip payment service is closed. | Serviço de pagamento de boleto está fechado. |
| 400 | BIP000023 | Bad Request | The source account has insufficient balance. Payment cannot be made. | A conta de origem possui saldo insuficiente. Pagamento não pode ser realizado. |
| 400 | BIP000024 | Bad Request | Request control key already exists. | Chave de controle da requisição já existe. |
| 400 | BIP000025 | Bad Request | It was not possible to pay the bank slip at this time. Please verify your information and, if necessary, contact us for assistance. | Não foi possível pagar o boleto neste momento. Por favor, verifique suas informações e, se necessário, entre em contato conosco para assistência. |
| 400 | BIP000028 | Bad Request | The source account has blocked balance. Payment cannot be made. | A conta de origem possui saldo em conta bloqueado. Pagamento não pode ser realizado. |
## Ambiente de Sandbox
Para realizar os testes em ambiente de sandbox, devem ser usadas as linhas digitáveis listadas na [Seção de pagamento de boleto bancário](/documentation/baas/cobranca/pagar_boleto_bancario).
---
# Schedule payment of collection invoice (agreement/tribute)
URL: /en/documentation/baas/cobranca/agendamento/agendar_pagamento_de_fatura_de_recolhimento
This endpoint allows scheduling the payment of collection invoices.
The scheduling should be made after consulting the Collection Invoice, using the returned information to ensure the correct flow and avoid failures during the payment process.
:::info Collection Invoice
This type of charge is issued by utility companies (water, electricity, telephone, and gas bills) and public entities (taxes). They are not registered with the Interbank Payment Clearinghouse (CIP/Núclea) and, therefore, do not return the same information as a boleto.
:::
## Request
ENDPOINT /account/ ACCOUNT_KEY /payment_schedule/collection_slip
METHOD POST
### Request Path Params
| Field | Type | Description | Characters |
|----------------|--------|-------------------------------------------|------------|
| `account_key` *| uuidv4 | Unique account identification key. | 36 |
Request Body: Scheduling of collection invoice with digitable line
```json
{
"request_control_key": "b6804f32-101e-4702-8fbc-c2dbc4c2caec",
"digitable_line": "00190000090361557400500000024174396700000991000",
"payment_amount": 1156.8,
"payment_date": "2024-03-30"
}
```
Request Body: Scheduling of collection invoice with barcode
```json
{
"request_control_key": "b6804f32-101e-4702-8fbc-c2dbc4c2caec",
"barcode": "00190000090361557400500000024174396700000991000",
"payment_amount": 1156.8,
"payment_date": "2024-03-30"
}
```
### Body Params
| Field | Type | Description |
|----------------------|---------|--------------------------------------------|
| `request_control_key` *| uuid4 | Unique identification key for the client's request. |
| `barcode` | string | Barcode. |
| `digitable_line` | string | Digitable line. |
| `payment_amount` * | number | Amount to be paid. |
| `payment_date` * | string | Scheduling date. |
:::danger Warning
The `payment_amount` must always be equal to the `total_amount` returned in the boleto query.
:::
## Response
### Success Response
STATUS 201
Response Body: Schedule confirmed
```json
{
"payment_key": "33860ad0-bcb0-47b7-bbe7-c7e3ec2fc61a",
"request_control_key": "ae4508df-f2cb-4e28-9f04-a19b7f2758c9",
"payer_name": "COOPERATIVA INDUSTRIAL MURILO",
"payer_document_number": "62069937000118",
"source_account_key": "daae79e6-ee8b-449f-aa1e-96959d5d5a72",
"paid_amount": 1389.21,
"payment_date": "2024-04-30",
"payment_type": "collection_slip",
"bank_slip": null,
"collection_slip": {
"barcode": null,
"digitable_line": "836200000138892100450006762142420244046000010192",
"collection_name": "CIA ULTRAGAZ SA-COD",
"collection_document_number": "00394460005887",
"expiration_date": "2024-04-15",
"total_amount": 1389.21
},
"payment_schedule_status": "scheduled"
}
```
### Response Body Params
| Field | Type | Description |
|----------------------|--------|---------------------------------------------------|
| `payment_key` * | uuid4 | Unique payment identification key. |
| `request_control_key` *| uuid4 | Unique identification key for the client's request.|
| `payer_name` * | string | Name of the effective payer. |
| `payer_document_number` *| string | Document number of the effective payer (CPF/CNPJ).|
| `source_account_key` *| uuid4 | Key of the debited account. |
| `transaction_key` * | uuid4 | Payment transaction key. |
| `transaction_revert_key` | uuid4 | Payment reversal transaction key. |
| `paid_amount` * | number | Amount effectively paid. |
| `payment_date` * | string | Payment date. |
| `payment_type` * | [enum](#enumeradores-payment_type) | Payment type. |
| `bank_slip` | object | Boleto. |
| `collection_slip` | [object](#object-collection_slip) | Collection invoice. |
| `payment_schedule_status` * | [enum](#enumeradores-payment_schedule_status) | Schedule status. |
### Enumeradores payment_type
| Enumerator | Description |
|---------------------|---------------------------|
| `bank_slip` | Boleto |
| `collection_slip` | Collection invoice |
:::danger Warning
The enumerator `bank_slip` does not apply to the collection invoice flow, and the bank_slip object will always be null.
:::
### Enumeradores payment_schedule_status
| Enumerator | Description |
|---------------------------|------------------------------------------------------------------------------------------------|
| `pending_2fa_approval` | Schedule pending two-factor authentication (2FA) |
| `scheduled` | Payment successfully scheduled |
| `executed` | The payment related to the schedule was successfully executed |
| `rejected` | The payment related to the schedule was rejected |
| `canceled` | Schedule canceled |
| `error` | Error during scheduling |
### Object collection_slip
| Field | Type | Description |
|---------------------------|-----------|-----------------------------------------------------------------------------------|
| `barcode` | string | Barcode. |
| `digitable_line` | string | Digitable line. |
| `collection_name` * | string | Name of the agreement. |
| `collection_document_number` | string | Document number of the agreement (CPF/CNPJ). |
| `expiration_date` * | string | Due date. |
| `total_amount` * | number | Total amount. |
### Error Response
STATUS 4XX
Response Body
```json
{
"title": "Título",
"description": "Description in english",
"translation": "Description em portuguese",
"code": "Código"
}
```
| HTTP Code | QI Code | Title | Description (eng) | Description (pt-br) |
|-------------|-----------|--------|------------------|------------------|
| 400 | BIP000032 | Bad Request | The bill sent does not correspond to a collection slip. | A conta enviada não corresponde a uma fatura de recolhimento. |
| 400 | BIP000033 | Bad Request | The barcode or digitable line of the collection slip must have 44 or 48 characters. | O código de barras ou linha digitável da fatura de recolhimento deve ter 44 ou 48 caracteres. |
| 403 | BIP000010 | Forbidden | User is not allowed to do this action | Usuário não tem autorização para fazer essa ação |
| 404 | BIP000011 | Not Found | The source account key was not found. | A chave da conta de origem não foi encontrada. |
| 400 | BIP000012 | Bad Request | It 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. |
| 400 | BIP000013 | Bad Request | The source account is closed. | A conta de origem está fechada. |
| 400 | BIP000014 | Bad Request | The source account is blocked. | A conta de origem está bloqueada. |
| 400 | BIP000023 | Bad Request | The source account has insufficient balance. Payment cannot be made. | A conta de origem possui saldo insuficiente. Pagamento não pode ser realizado. |
| 400 | BIP000024 | Bad Request | Request control key already exists. | Chave de controle da requisição já existe. |
| 400 | BIP000028 | Bad Request | The source account has blocked balance. Payment cannot be made. | A conta de origem possui saldo em conta bloqueado. Pagamento não pode ser realizado. |
| 400 | BIP000034 | Bad Request | Collection slip already paid. | Fatura de recolhimento já paga. |
| 400 | BIP000035 | Bad Request | Covenant slip invalid barcode. | Código de barras da fatura de recolhimento inválido. |
| 400 | BIP000036 | Bad Request | Covenant slip overdue. | Fatura de recolhimento vencida. |
| 400 | BIP000037 | Bad Request | Error in collection slip consultation. | Erro na consulta da fatura de recolhimento. |
| 400 | BIP000038 | Bad Request | Outside of covenant payment hours. | Fora do horário de pagamento do convênio. |
| 400 | BIP000039 | Bad Request | Collection slip not accepted. | Fatura de recolhimento não aceita. |
| 400 | BIP000040 | Bad Request | Minimum advance not reached. | Mínimo de dias de adiantamento não atingido. |
| 400 | BIP000041 | Bad Request | Max payment amount exceeded. | Valor máximo de pagamento excedido. |
| 400 | BIP000044 | Bad Request | It was not possible to pay the collection slip at this time. Please verify your information and, if necessary, contact us for assistance. | Não foi possível pagar a fatura de recolhimento neste momento. Por favor, verifique suas informações e, se necessário, entre em contato conosco para assistência. |
| 400 | BIP000045 | Bad Request | Collection slip payment service is closed. | Serviço de pagamento de fatura de recolhimento está fechado. |
## Sandbox Environment
In our sandbox environment, we provide mocked digitable lines for simulating successful payments and testing error scenarios.
### Success scenarios
| Digitable line |
|---|
| 828300000007411100972013905080001546763201900028 |
| 838000000009235700481007241345219112001474229880 |
| 848000000006308600802021201071261517689002201070 |
| 858200000015000000643025703477209504800448091020 |
### Error Scenarios
| Digitable line | Error code0 |
|---|---|
| 858500000037350000643217212883260006147448091022 | BIP000035 |
---
# Cancel schedule
URL: /en/documentation/baas/cobranca/agendamento/cancelar_agendamento
This endpoint is used to cancel a scheduled payment of a Boleto or Collection Invoice.
:::info Boleto
This is the conventional boleto (with digitable lines not starting with the digit 8). It is registered with the Interbank Payment Clearinghouse (CIP/Núclea) and can be paid at financial institutions and payment institutions authorized to operate by the Central Bank.
:::
:::info Collection Invoice
This type of charge is issued by utility companies (water, electricity, telephone, and gas bills) and public entities (taxes). They are not registered with the Interbank Payment Clearinghouse (CIP/Núclea) and, therefore, do not return the same information as a boleto.
:::
## Request
ENDPOINT /account/ ACCOUNT_KEY /payment_schedule/ PAYMENT_SCHEDULE_KEY /cancel
METHOD PATCH
### Request Path Params
| Field | Type | Description | Characters |
|-------------------------|--------|-----------------------------------------------|------------|
| `account_key` * | uuidv4 | Unique account identification key. | 36 |
| `payment_schedule_key` *| uuidv4 | Unique schedule identification key. | 36 |
## Response
### Success Response
STATUS 200
Response Body: Scheduled payment of boleto cancelled
```json
{
"payment_key":"c4325104-d60b-44f3-aae4-49155564a2ea",
"request_control_key":"b713b2f6-2f48-4d18-b0c9-7186e4edf189",
"payer_name":"COOPERATIVA INDUSTRIAL MURILO",
"payer_document_number":"00037025000160",
"source_account_key":"6dc89d57-fac7-4643-b151-cd2ca0a7f68f",
"paid_amount":1050.1,
"payment_date":"2024-04-03",
"payment_type":"bank_slip",
"bank_slip": {
"bank_slip_key":"95080ffd-3ac5-48d7-b3fe-659e4aaba81a",
"barcode":"00193967000009910000000003615574000000002417",
"digitable_line":"00190000090361557400500000024174396700000991000",
"payer_name":"COOPERATIVA TESTE",
"payer_document_number":"00037025000160",
"beneficiary_name":"TESTE EQUIPAMENTOS E SERVICOS LTDA",
"beneficiary_trading_name":"TESTE EQUIPAMENTOS E SERVICOS LTDA",
"beneficiary_document_number":"52069937000117",
"beneficiary_bank_ispb":"00000000",
"guarantor_name":null,
"guarantor_document_number":null,
"expiration_date":"2024-03-29",
"max_payment_data": "2026-03-29",
"partial_payment_indicator":"allowed",
"registered_payment_amount":9029.0,
"nominal_amount":9910.0,
"total_amount":10129.1,
"rebate_amount":0.0,
"discount_amount":0.0,
"fine_amount":0.0,
"interest_amount":219.1
},
"collection_slip":null,
"payment_schedule_status":"canceled"
}
```
Response Body: Scheduled payment of collection invoice cancelled
```json
{
"payment_key": "33860ad0-bcb0-47b7-bbe7-c7e3ec2fc61a",
"request_control_key": "ae4508df-f2cb-4e28-9f04-a19b7f2758c9",
"payer_name": "COOPERATIVA INDUSTRIAL MURILO",
"payer_document_number": "62069937000118",
"source_account_key": "daae79e6-ee8b-449f-aa1e-96959d5d5a72",
"paid_amount": 1389.21,
"payment_date": "2024-04-30",
"payment_type": "collection_slip",
"bank_slip": null,
"collection_slip": {
"barcode": null,
"digitable_line": "836200000138892100450006762142420244046000010192",
"collection_name": "CIA ULTRAGAZ SA-COD",
"collection_document_number": "00394460005887",
"expiration_date": "2024-04-15",
"total_amount": 1389.21
},
"payment_schedule_status": "canceled"
}
```
### Response Body Params
| Field | Type | Description |
|---------------------------|--------|----------------------------------------------------------------|
| `payment_key` * | uuid4 | Unique payment identification key. |
| `request_control_key` * | uuid4 | Unique identification key for the client's request. |
| `payer_name` * | string | Name of the effective payer. |
| `payer_document_number` * | string | Document number of the effective payer (CPF/CNPJ). |
| `source_account_key` * | uuid4 | Key of the debited account. |
| `paid_amount` * | number | Amount effectively paid. |
| `payment_date` * | string | Scheduling date. |
| `payment_type` * | [enum](#enumeradores-payment_type) | Payment type. |
| `bank_slip` | [object](#object-bank_slip) | Boleto. |
| `collection_slip` | object | Collection invoice. |
| `payment_schedule_status` * | [enum](#enumeradores-payment_schedule_status) | Schedule status. |
### Enumerators payment_type
| Enumerator | Type | Description |
|-------------------|--------|---------------------------|
| `bank_slip` | string | Boleto |
| `collection_slip` | string | Collection invoice |
### Enumerators payment_schedule_status
| Enumerator | Description |
|-------------------|---------------------------|
| `canceled` | Schedule canceled |
### Object bank_slip
| Field | Type | Description |
|--------------------------------|-----------|---------------------------------------------------------------------------|
| `barcode` * | string | Barcode. |
| `digitable_line` * | string | Digitable line. |
| `payer_name` * | string | Payer's name. |
| `payer_document_number` * | string | Payer's document number (CPF/CNPJ). |
| `beneficiary_name` * | string | Beneficiary's name. |
| `beneficiary_trading_name` | string | Beneficiary's trade name. |
| `beneficiary_document_number` * | string | Beneficiary's document number (CPF/CNPJ). |
| `beneficiary_bank_ispb` * | string | ISPB code of the beneficiary's bank. |
| `guarantor_name` | string | Name of the guarantor. |
| `guarantor_document_number` | string | Guarantor's document number (CPF/CNPJ). |
| `expiration_date` * | string | Due date. |
| `max_payment_date` * | string | Maximum payment date. |
| `partial_payment_indicator` * | [enum](#enumeradores-partial_payment_indicator) | Partial payment indicator. |
| `registered_payment_amount` | string | Total registered payment amount. |
| `nominal_amount` * | number | Original amount. |
| `total_amount` * | number | Total amount. |
| `rebate_amount` * | number | Rebate amount. |
| `discount_amount` * | number | Discount amount. |
| `fine_amount` * | number | Fine amount. |
| `interest_amount` * | number | Interest amount. |
### Enumerators partial_payment_indicator
| Enumerator | Description |
|----------------|---------------------------|
| `allowed` | Allowed |
| `not_allowed` | Not allowed |
### Object collection_slip
| Field | Type | Description |
|--------------------------------|-----------|---------------------------------------------------------------------------|
| `barcode` | string | Barcode. |
| `digitable_line` | string | Digitable line. |
| `collection_name` * | string | Name of the agreement. |
| `collection_document_number` * | string | Document number of the agreement (CPF/CNPJ). |
| `expiration_date` * | string | Due date. |
| `total_amount` * | number | Total amount. |
### Error Response
STATUS 4XX
Response Body
```json
{
"title": "Título",
"description": "Description in english",
"translation": "Description em português",
"code": "Código"
}
```
| HTTP Code | QI Code | Title | Description (eng) | Description (pt-br) |
|-------------|-----------|--------|------------------|------------------|
| 400 | BIP000001 | Bad Request | The barcode or digitable line must have 44 or 47 characters. | O código de barras ou linha digitável deve ter 44 ou 47 caracteres. |
| 400 | BIP000002 | Bad Request | The bill sent does not correspond to a bank slip. | A conta enviado não corresponde a um boleto bancário. |
| 400 | BIP000003 | Bad Request | The digitable line sent is invalid. | A linha digitável enviada é inválida. |
| 404 | BIP000004 | Not Found | The bank slip was not found. | O boleto não foi encontrado. |
| 400 | BIP000005 | Bad Request | It was not possible to consult the bank slip at this time. Please try again in a few minutes. | Não foi possível consultar o boleto neste momento. Por favor, tente novamente em alguns minutos. |
| 400 | BIP000006 | Bad Request | Bank slip already written off | Boleto já baixado |
| 400 | BIP000007 | Bad Request | Bank slip blocked for payment | Boleto bloqueado para pagamento |
| 400 | BIP000008 | Bad Request | Bank slip already paid | Boleto já pago |
| 400 | BIP000009 | Bad Request | Invalid bank slip. Please consult issuing bank | Boleto inválido. Favor consultar banco emissor |
---
# Check scheduling
URL: /en/documentation/baas/cobranca/agendamento/consultar_agendamento
This endpoint is used to query information about a scheduled payment of a Boleto or Collection Invoice.
:::info Boleto
This is the conventional boleto (with digitable lines not starting with the digit 8). It is registered with the Interbank Payment Clearinghouse (CIP/Núclea) and can be paid at financial institutions and payment institutions authorized to operate by the Central Bank.
:::
:::info Collection Invoice
This type of charge is issued by utility companies (water, electricity, telephone, and gas bills) and public entities (taxes). They are not registered with the Interbank Payment Clearinghouse (CIP/Núclea) and, therefore, do not return the same information as a boleto.
:::
## Request
ENDPOINT /account/ ACCOUNT_KEY /payment_schedule/ PAYMENT_SCHEDULE_KEY
METHOD GET
### Request Path Params
| Field | Type | Description | Characters |
|-------------------------|--------|-----------------------------------------------|------------|
| `account_key` * | uuidv4 | Unique account identification key. | 36 |
| `payment_schedule_key` *| uuidv4 | Unique schedule identification key. | 36 |
## Response
### Success Response
STATUS 200
Response Body: Scheduled payment of boleto
```json
{
"payment_key":"c4325104-d60b-44f3-aae4-49155564a2ea",
"request_control_key":"b713b2f6-2f48-4d18-b0c9-7186e4edf189",
"payer_name":"COOPERATIVA INDUSTRIAL MURILO",
"payer_document_number":"00037025000160",
"source_account_key":"6dc89d57-fac7-4643-b151-cd2ca0a7f68f",
"paid_amount":1050.1,
"payment_date":"2024-04-03",
"payment_type":"bank_slip",
"bank_slip": {
"bank_slip_key":"95080ffd-3ac5-48d7-b3fe-659e4aaba81a",
"barcode":"00193967000009910000000003615574000000002417",
"digitable_line":"00190000090361557400500000024174396700000991000",
"payer_name":"COOPERATIVA TESTE",
"payer_document_number":"00037025000160",
"beneficiary_name":"TESTE EQUIPAMENTOS E SERVICOS LTDA",
"beneficiary_trading_name":"TESTE EQUIPAMENTOS E SERVICOS LTDA",
"beneficiary_document_number":"52069937000117",
"beneficiary_bank_ispb":"00000000",
"guarantor_name":null,
"guarantor_document_number":null,
"expiration_date":"2024-03-29",
"max_payment_data": "2026-03-29",
"partial_payment_indicator":"allowed",
"registered_payment_amount":9029.0,
"nominal_amount":9910.0,
"total_amount":10129.1,
"rebate_amount":0.0,
"discount_amount":0.0,
"fine_amount":0.0,
"interest_amount":219.1
},
"collection_slip":null,
"payment_schedule_status":"scheduled"
}
```
Response Body: Scheduled payment of collection invoice
```json
{
"payment_key": "33860ad0-bcb0-47b7-bbe7-c7e3ec2fc61a",
"request_control_key": "ae4508df-f2cb-4e28-9f04-a19b7f2758c9",
"payer_name": "COOPERATIVA INDUSTRIAL MURILO",
"payer_document_number": "62069937000118",
"source_account_key": "daae79e6-ee8b-449f-aa1e-96959d5d5a72",
"paid_amount": 1389.21,
"payment_date": "2024-04-30",
"payment_type": "collection_slip",
"bank_slip": null,
"collection_slip": {
"barcode": null,
"digitable_line": "836200000138892100450006762142420244046000010192",
"collection_name": "CIA ULTRAGAZ SA-COD",
"collection_document_number": "00394460005887",
"expiration_date": "2024-04-15",
"total_amount": 1389.21
},
"payment_schedule_status": "scheduled"
}
```
### Response Body Params
| Field | Type | Description |
|----------------------|--------|---------------------------------------------------|
| `payment_key` * | uuid4 | Unique payment identification key. |
| `request_control_key` *| uuid4 | Unique identification key for the client's request.|
| `payer_name` * | string | Name of the effective payer. |
| `payer_document_number` *| string | Document number of the effective payer (CPF/CNPJ).|
| `source_account_key` *| uuid4 | Key of the debited account. |
| `transaction_key` * | uuid4 | Payment transaction key. |
| `transaction_revert_key` | uuid4 | Payment reversal transaction key. |
| `paid_amount` * | number | Amount effectively paid. |
| `payment_date` * | string | Scheduling date. |
| `payment_type` * | [enum](#enumerators-payment_type) | Payment type. |
| `bank_slip` | [object](#object-bank_slip) | Boleto. |
| `collection_slip` | object | Collection invoice. |
| `payment_schedule_status` * | [enum](#enumerators-payment_schedule_status) | Schedule status. |
### Enumerators payment_type
| Enumerator | Type | Description |
|---------------------|--------|---------------------------|
| `bank_slip` | string | Boleto |
| `collection_slip` | string | Collection invoice |
### Enumerators payment_schedule_status
| Enumerator | Description |
|-------------------------|-------------------------------------------------------------------------------------------|
| `pending_2fa_approval` | Schedule pending two-factor authentication (2FA) |
| `scheduled` | Payment successfully scheduled |
| `executed` | The payment related to the schedule was successfully executed |
| `rejected` | The payment related to the schedule was rejected |
| `canceled` | Schedule canceled |
| `error` | Error during scheduling |
### Object bank_slip
| Field | Type | Description |
|--------------------------------|-----------|-----------------------------------------------------------------------------|
| `barcode` * | string | Barcode. |
| `digitable_line` * | string | Digitable line. |
| `payer_name` * | string | Payer's name. |
| `payer_document_number` * | string | Payer's document number (CPF/CNPJ). |
| `beneficiary_name` * | string | Beneficiary's name. |
| `beneficiary_trading_name` | string | Beneficiary's trade name. |
| `beneficiary_document_number` * | string | Beneficiary's document number (CPF/CNPJ). |
| `beneficiary_bank_ispb` * | string | ISPB code of the beneficiary's bank. |
| `guarantor_name` | string | Name of the guarantor. |
| `guarantor_document_number` | string | Guarantor's document number (CPF/CNPJ). |
| `expiration_date` * | string | Due date. |
| `max_payment_date` * | string | Maximum payment date. |
| `partial_payment_indicator` * | [enum](#enumerators-partial_payment_indicator) | Partial payment indicator. |
| `registered_payment_amount` | string | Total registered payment amount. |
| `nominal_amount` * | number | Original amount. |
| `total_amount` * | number | Total amount. |
| `rebate_amount` * | number | Rebate amount. |
| `discount_amount` * | number | Discount amount. |
| `fine_amount` * | number | Fine amount. |
| `interest_amount` * | number | Interest amount. |
### Enumerators partial_payment_indicator
| Enumerator | Description |
|--------------- |-----------------------|
| `allowed` | Allowed |
| `not_allowed` | Not allowed |
### Object collection_slip
| Field | Type | Description |
|--------------------------------|-----------|-----------------------------------------------------------------------------|
| `barcode` | string | Barcode. |
| `digitable_line` | string | Digitable line. |
| `collection_name` * | string | Name of the agreement. |
| `collection_document_number` | string | Document number of the agreement (CPF/CNPJ). |
| `expiration_date` * | string | Due date. |
| `total_amount` * | number | Total amount. |
### Error Response
STATUS 4XX
Response Body
```json
{
"title": "Título",
"description": "Description in english",
"translation": "Description em português",
"code": "Código"
}
```
| HTTP Code | QI Code | Title | Description (eng) | Description (pt-br) |
|-------------|-----------|--------|------------------|------------------|
| 400 | BIP000001 | Bad Request | The barcode or digitable line must have 44 or 47 characters. | O código de barras ou linha digitável deve ter 44 ou 47 caracteres. |
| 400 | BIP000002 | Bad Request | The bill sent does not correspond to a bank slip. | A conta enviado não corresponde a um boleto bancário. |
| 400 | BIP000003 | Bad Request | The digitable line sent is invalid. | A linha digitável enviada é inválida. |
| 404 | BIP000004 | Not Found | The bank slip was not found. | O boleto não foi encontrado. |
| 400 | BIP000005 | Bad Request | It was not possible to consult the bank slip at this time. Please try again in a few minutes. | Não foi possível consultar o boleto neste momento. Por favor, tente novamente em alguns minutos. |
| 400 | BIP000006 | Bad Request | Bank slip already written off | Boleto já baixado |
| 400 | BIP000007 | Bad Request | Bank slip blocked for payment | Boleto bloqueado para pagamento |
| 400 | BIP000008 | Bad Request | Bank slip already paid | Boleto já pago |
| 400 | BIP000009 | Bad Request | Invalid bank slip. Please consult issuing bank | Boleto inválido. Favor consultar banco emissor |
---
# List schedules
URL: /en/documentation/baas/cobranca/agendamento/listar_agendamentos
This endpoint aims to provide details of all schedules made by the integration partner, including boletos and collection invoices.
:::info Boleto
This is the conventional boleto (with digitable lines not starting with the digit 8). It is registered with the Interbank Payment Clearinghouse (CIP/Núclea) and can be paid at financial institutions and payment institutions authorized to operate by the Central Bank.
:::
:::info Collection Invoice
This type of charge is issued by utility companies (water, electricity, telephone, and gas bills) and public entities (taxes). They are not registered with the Interbank Payment Clearinghouse (CIP/Núclea) and, therefore, do not return the same information as a boleto.
:::
## Request
ENDPOINT /account/ ACCOUNT_KEY /payment_schedules
MÉTODO GET
### Request Path Params
| Field | Type | Description | Characters |
|----------------|--------|-------------------------------------------|------------|
| `account_key` *| uuidv4 | Unique account identification key. | 36 |
### Request Query String Params
| Field | Type | Description |
|------------------------|-----------|--------------------------------------------------------------------|
| `request_control_key` | uuidv4 | Unique identification key for the client's request. |
| `payment_schedule_key` | uuidv4 | Unique schedule identification key. |
| `payment_type` | [enum](#enumerators-payment_type) | Payment type. |
| `date_from` | string | Start date. Format "YYYY-MM-DD". |
| `date_to` | string | End date. Format "YYYY-MM-DD". |
| `page` | string | Requested page number. 1 by default. |
| `page_size` | string | Requested page size in the query. 30 by default and maximum value. |
### Enumerators payment_type
| Enumerator | Type | Description |
|-------------------|--------|---------------------------|
| `bank_slip` | string | Boleto |
| `collection_slip` | string | Collection invoice |
## Response
### Success Response
STATUS 200
Response Body: Payment query
```json
{
"data": [
{
"payment_key":"c4325104-d60b-44f3-aae4-49155564a2ea",
"request_control_key":"b713b2f6-2f48-4d18-b0c9-7186e4edf189",
"payer_name":"COOPERATIVA INDUSTRIAL MURILO",
"payer_document_number":"00037025000160",
"source_account_key":"6dc89d57-fac7-4643-b151-cd2ca0a7f68f",
"paid_amount":1050.1,
"payment_date":"2024-04-03",
"payment_type":"bank_slip",
"bank_slip": {
"bank_slip_key":"95080ffd-3ac5-48d7-b3fe-659e4aaba81a",
"barcode":"00193967000009910000000003615574000000002417",
"digitable_line":"00190000090361557400500000024174396700000991000",
"payer_name":"COOPERATIVA TESTE",
"payer_document_number":"00037025000160",
"beneficiary_name":"TESTE EQUIPAMENTOS E SERVICOS LTDA",
"beneficiary_trading_name":"TESTE EQUIPAMENTOS E SERVICOS LTDA",
"beneficiary_document_number":"52069937000117",
"beneficiary_bank_ispb":"00000000",
"guarantor_name":null,
"guarantor_document_number":null,
"expiration_date":"2024-03-29",
"max_payment_data": "2026-03-29",
"partial_payment_indicator":"allowed",
"registered_payment_amount":9029.0,
"nominal_amount":9910.0,
"total_amount":10129.1,
"rebate_amount":0.0,
"discount_amount":0.0,
"fine_amount":0.0,
"interest_amount":219.1
},
"collection_slip":null,
"payment_schedule_status":"scheduled"
},
{
"payment_key": "33860ad0-bcb0-47b7-bbe7-c7e3ec2fc61a",
"request_control_key": "ae4508df-f2cb-4e28-9f04-a19b7f2758c9",
"payer_name": "COOPERATIVA INDUSTRIAL MURILO",
"payer_document_number": "62069937000118",
"source_account_key": "daae79e6-ee8b-449f-aa1e-96959d5d5a72",
"paid_amount": 1389.21,
"payment_date": "2024-04-30",
"payment_type": "collection_slip",
"bank_slip": null,
"collection_slip": {
"barcode": null,
"digitable_line": "836200000138892100450006762142420244046000010192",
"collection_name": "CIA ULTRAGAZ SA-COD",
"collection_document_number": "00394460005887",
"expiration_date": "2024-04-15",
"total_amount": 1389.21
},
"payment_schedule_status": "scheduled"
}
],
"pagination": {
"current_page": 1,
"rows_per_page": 30
}
}
```
### Response Body Params
| Field | Type | Description |
|----------------------|--------|---------------------------------------------------|
| `payment_key` * | uuid4 | Unique payment identification key. |
| `request_control_key` *| uuid4 | Unique identification key for the client's request.|
| `payer_name` * | string | Name of the effective payer. |
| `payer_document_number` *| string | Document number of the effective payer (CPF/CNPJ).|
| `source_account_key` *| uuid4 | Key of the debited account. |
| `paid_amount` * | number | Amount effectively paid. |
| `payment_date` * | string | Payment date. |
| `payment_type` * | [enum](#enumerators-payment_type-1) | Payment type. |
| `bank_slip` | [object](#object-bank_slip) | Boleto. |
| `collection_slip` | [object](#object-collection_slip) | Collection invoice. |
| `payment_schedule_status` * | [enum](#enumerators-payment_schedule_status) | Schedule status. |
### Enumerators payment_type
| Enumerator | Type | Description |
|---------------------|--------|-------------------------------|
| `bank_slip` | string | Boleto |
| `collection_slip` | string | Collection invoice |
### Enumerators payment_schedule_status
| Enumerator | Description |
|-------------------------|------------------------------------------------------------------------|
| `pending_2fa_approval` | Schedule pending two-factor authentication (2FA) |
| `scheduled` | Payment successfully scheduled |
| `executed` | The payment related to the schedule was successfully executed |
| `rejected` | The payment related to the schedule was rejected |
| `canceled` | Schedule canceled |
| `error` | Error during scheduling |
### Object bank_slip
| Field | Type | Description |
|--------------------------------|-----------|-----------------------------------------------------------------------------|
| `barcode` * | string | Barcode. |
| `digitable_line` * | string | Digitable line. |
| `payer_name` * | string | Payer's name. |
| `payer_document_number` * | string | Payer's document number (CPF/CNPJ). |
| `beneficiary_name` * | string | Beneficiary's name. |
| `beneficiary_trading_name` | string | Beneficiary's trade name. |
| `beneficiary_document_number` * | string | Beneficiary's document number (CPF/CNPJ). |
| `beneficiary_bank_ispb` * | string | ISPB code of the beneficiary's bank. |
| `guarantor_name` | string | Name of the guarantor. |
| `guarantor_document_number` | string | Guarantor's document number (CPF/CNPJ). |
| `expiration_date` * | string | Due date. |
| `max_payment_date` * | string | Maximum payment date. |
| `partial_payment_indicator` * | [enum](#enumerators-partial_payment_indicator) | Partial payment indicator. |
| `registered_payment_amount` | string | Total registered payment amount. |
| `nominal_amount` * | number | Original amount. |
| `total_amount` * | number | Total amount. |
| `rebate_amount` * | number | Rebate amount. |
| `discount_amount` * | number | Discount amount. |
| `fine_amount` * | number | Fine amount. |
| `interest_amount` * | number | Interest amount. |
### Enumerators partial_payment_indicator
| Enumerator | Type | Description |
|----------------|--------|---------------------------|
| `allowed` | string | Allowed |
| `not_allowed` | string | Not allowed |
### Object collection_slip
| Field | Type | Description |
|--------------------------------|-----------|------------------------------------|
| `barcode` * | string | Barcode. |
| `digitable_line` * | string | Digitable line. |
| `collection_name` * | string | Name of the agreement. |
| `collection_document_number` * | string | Document number of the agreement (CPF/CNPJ). |
| `expiration_date` * | string | Due date. |
| `total_amount` * | number | Total amount. |
### Error Response
STATUS 4XX
Response Body
```json
{
"title": "Título",
"description": "Description in english",
"translation": "Description in portuguese",
"code": "Código"
}
```
| HTTP Code| QI Code | Title | Description (eng) | Description (pt-br) |
|-------------|-----------|--------|------------------|------------------|
| 400 | BIP000026 | Bad Request | Invalid payment date format. The correct format is YYYY-MM-DD. | Formato de data de pagamento inválido. O formato correto é YYYY-MM-DD. |
| 400 | BIP000027 | Bad Request | Invalid integer value for page or size query string parameters. | Valor inválido para parâmetros de página ou tamanho de página. |
| 400 | BIP000047 | Bad Request | Invalid payment type. | Tipo de pagamento inválido. |
---
# Request batch scheduling of bank slip payments
URL: /en/documentation/baas/cobranca/agendamento/solicitar_agendamento_em_lote_de_boleto_bancario
This endpoint allows you to **schedule multiple bank slips in a single request**.
:::info Bank slip
This is the conventional bank slip (digitable lines not starting with the digit 8). It is registered with the Interbank Payment Clearinghouse (CIP/Núclea) and can be paid at financial institutions and payment institutions authorized to operate by the Central Bank.
:::
## Request
### Request Endpoint
ENDPOINT /bill_payment/account/ ACCOUNT_KEY /payments_schedule/batch_bank_slip
METHOD POST
### Request Path Params
| Field | Type | Description | Characters |
|---------------------|---------|-------------------------------------------|------------|
| `account_key` * | uuid4 | Unique account identification key. | 36 |
Request Body: Batch scheduling of bank slips
```json
{
"request_control_key": "b6804f32-101e-4702-8fbc-c2dbc4c2caec",
"bank_slip_payment_schedules": [
{
"request_control_key": "c7915a43-212f-5813-9adc-d3ed5d3d3bfd",
"digitable_line": "00190000090361557400500000024174396700000991000",
"payment_amount": 1156.8,
"payment_date": "2026-04-10"
},
{
"request_control_key": "d8a26b54-323a-4924-0aed-e4fe6e4e4c0e",
"barcode": "00190000090361557400500000024174396700000991000",
"payment_amount": 200.5,
"payment_date": "2026-04-15"
}
]
}
```
### Body Params
| Field | Type | Description |
|---------------------|---------------|-----------------------------------|
| `request_control_key` * | uuid4 | Unique client request key (batch). |
| `bank_slip_payment_schedules` * | array | List of bank slip schedules. **1000** items maximum per request. |
Each element of `bank_slip_payment_schedules` must contain:
| Field | Type | Description |
|---------------------|---------------|-----------------------------------|
| `request_control_key` * | uuid4 | Unique client request key for that batch item. |
| `barcode` | string | Barcode. |
| `digitable_line` | string | Digitable line. |
| `payment_amount` * | number | Amount to pay. |
| `payment_date` * | string | Scheduled payment date for the item. |
:::danger Warning
For each item, `payment_amount` must follow the rules for the title returned in the bank slip inquiry. If partial payment is not allowed, the amount must match the updated total of the title.
:::
## Response
### Success Response
STATUS 202
Response Body: Batch schedule created
```json
{
"batch_payment_schedule_key": "c4325104-d60b-44f3-aae4-49155564a2ea",
"request_control_key": "b6804f32-101e-4702-8fbc-c2dbc4c2caec",
"account_key": "6dc89d57-fac7-4643-b151-cd2ca0a7f68f",
"total_amount": 1357.3,
"batch_payment_schedule_status": "scheduled",
"payment_type": "bank_slip"
}
```
### Response Body Params
| Field | Type | Description |
|---------------------|---------|-----------------------------------|
| `batch_payment_schedule_key` * | uuid4 | Unique batch schedule key. |
| `request_control_key` * | uuid4 | Unique client request key (batch). |
| `account_key` * | uuid4 | Debited account key. |
| `total_amount` * | number | Sum of item `payment_amount` values in the batch. |
| `batch_payment_schedule_status` * | [enum](#enumeradores-batch_payment_schedule_status) | Batch schedule status after the request. |
| `payment_type` * | [enum](#enumeradores-payment_type) | Payment type. |
### Enumeradores batch_payment_schedule_status
| Value | Description |
|---------------|---------------|
| `pending_2fa_approval` | Pending 2FA approval |
| `scheduled` | Scheduled |
| `rejected` | Rejected |
| `error` | Scheduling error |
### Enumeradores payment_type
| Value | Type | Description |
|---------------|-----------|---------------|
| `bank_slip` | string | Bank slip |
| `collection_slip` | string | Collection slip |
:::danger Warning
The `collection_slip` value does not apply to this bank slip batch scheduling endpoint; for this flow, `payment_type` must be `bank_slip`.
:::
### Error Response
STATUS 4XX
Response Body
```json
{
"title": "Title",
"description": "Description in english",
"translation": "Portuguese description",
"code": "Code"
}
```
| HTTP code | QI code | Title | Description (eng) | Description (pt-br) |
|-------------|-----------|--------|------------------|------------------|
| 403 | BIP000010 | Forbidden | User is not allowed to do this action | Usuário não tem autorização para fazer essa ação |
| 404 | BIP000011 | Not Found | The source account key was not found. | A chave da conta de origem não foi encontrada. |
| 400 | BIP000012 | Bad Request | It 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. |
| 400 | BIP000024 | Bad Request | Request control key already exists. | Chave de controle da requisição já existe. |
| 400 | BIP000065 | Bad Request | Payment verification time window exceeded. | Janela de tempo de verificação de pagamento excedida. |
---
# Request batch scheduling of collection slip payments
URL: /en/documentation/baas/cobranca/agendamento/solicitar_agendamento_em_lote_de_fatura_de_recolhimento
This endpoint allows you to **schedule multiple collection slips (utility/tax) in a single request**.
:::info Collection slip
This charge type is issued by utility companies (water, electricity, phone, gas) and public agencies (taxes). They are not registered with the Interbank Payment Clearinghouse (CIP/Núclea), so they do not return the same information as a bank slip.
:::
## Request
### Request Endpoint
ENDPOINT /bill_payment/account/ ACCOUNT_KEY /payments_schedule/batch_collection_slip
METHOD POST
### Request Path Params
| Field | Type | Description | Characters |
|---------------------|---------|-------------------------------------------|------------|
| `account_key` * | uuid4 | Unique account identification key. | 36 |
Request Body: Batch scheduling of collection slips
```json
{
"request_control_key": "b6804f32-101e-4702-8fbc-c2dbc4c2caec",
"collection_slip_payment_schedules": [
{
"request_control_key": "c7915a43-212f-5813-9adc-d3ed5d3d3bfd",
"digitable_line": "836200000138892100450006762142420244046000010192",
"payment_amount": 1389.21,
"payment_date": "2026-04-10"
},
{
"request_control_key": "d8a26b54-323a-4924-0aed-e4fe6e4e4c0e",
"barcode": "836200000138892100450006762142420244046000010192",
"payment_amount": 550.10,
"payment_date": "2026-04-15"
}
]
}
```
### Body Params
| Field | Type | Description |
|---------------------|---------------|-----------------------------------|
| `request_control_key` * | uuid4 | Unique client request key (batch). |
| `collection_slip_payment_schedules` * | array | List of collection slip schedules. **1000** items maximum per request. |
Each element of `collection_slip_payment_schedules` must contain:
| Field | Type | Description |
|---------------------|---------------|-----------------------------------|
| `request_control_key` * | uuid4 | Unique client request key for that batch item. |
| `barcode` | string | Barcode. |
| `digitable_line` | string | Digitable line. |
| `payment_amount` * | number | Amount to pay. |
| `payment_date` * | string | Scheduled payment date for the item. |
## Response
### Success Response
STATUS 202
Response Body: Batch schedule created
```json
{
"batch_payment_schedule_key": "33860ad0-bcb0-47b7-bbe7-c7e3ec2fc61a",
"request_control_key": "ae4508df-f2cb-4e28-9f04-a19b7f2758c9",
"account_key": "daae79e6-ee8b-449f-aa1e-96959d5d5a72",
"total_amount": 1939.31,
"batch_payment_schedule_status": "scheduled",
"payment_type": "collection_slip"
}
```
### Response Body Params
| Field | Type | Description |
|---------------------|---------|-----------------------------------|
| `batch_payment_schedule_key` * | uuid4 | Unique batch schedule key. |
| `request_control_key` * | uuid4 | Unique client request key (batch). |
| `account_key` * | uuid4 | Debited account key. |
| `total_amount` * | number | Sum of item `payment_amount` values in the batch. |
| `batch_payment_schedule_status` * | [enum](#enumeradores-batch_payment_schedule_status) | Batch schedule status after the request. |
| `payment_type` * | [enum](#enumeradores-payment_type) | Payment type. |
### Enumeradores batch_payment_schedule_status
| Value | Description |
|---------------|---------------|
| `pending_2fa_approval` | Pending 2FA approval |
| `scheduled` | Scheduled |
| `rejected` | Rejected |
| `error` | Scheduling error |
### Enumeradores payment_type
| Value | Type | Description |
|---------------|-----------|---------------|
| `bank_slip` | string | Bank slip |
| `collection_slip` | string | Collection slip |
:::danger Warning
The `bank_slip` value does not apply to this collection slip batch scheduling endpoint; for this flow, `payment_type` must be `collection_slip`.
:::
### Error Response
STATUS 4XX
Response Body
```json
{
"title": "Title",
"description": "Description in english",
"translation": "Portuguese description",
"code": "Code"
}
```
| HTTP code | QI code | Title | Description (eng) | Description (pt-br) |
|-------------|-----------|--------|------------------|------------------|
| 400 | BIP000032 | Bad Request | The bill sent does not correspond to a collection slip. | A conta enviada não corresponde a uma fatura de recolhimento. |
| 400 | BIP000033 | Bad Request | The barcode or digitable line of the collection slip must have 44 or 48 characters. | O código de barras ou linha digitável da fatura de recolhimento deve ter 44 ou 48 caracteres. |
| 403 | BIP000010 | Forbidden | User is not allowed to do this action | Usuário não tem autorização para fazer essa ação |
| 404 | BIP000011 | Not Found | The source account key was not found. | A chave da conta de origem não foi encontrada. |
| 400 | BIP000012 | Bad Request | It 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. |
| 400 | BIP000024 | Bad Request | Request control key already exists. | Chave de controle da requisição já existe. |
| 400 | BIP000065 | Bad Request | Payment verification time window exceeded. | Janela de tempo de verificação de pagamento excedida. |
---
# Confirmação de lote de pagamento de boleto bancário
URL: /en/documentation/baas/cobranca/confirmacao_de_lote_de_boleto_bancario
Este endpoint permite **confirmar ou rejeitar** um lote de pagamento de boletos bancários previamente criado com [Solicitar pagamento em lote de boleto bancário](./solicitar_pagamento_lote_de_boleto_bancario_com_confirmacao_de_lote.md). A confirmação é a etapa que define se o processamento do lote segue (aprovação) ou é encerrado sem débito dos títulos (rejeição).
:::info Boleto bancário
É o boleto bancário convencional (linhas digitáveis não iniciadas com dígito 8). Possui registro na Câmara Interbancária de Pagamento (CIP/Núclea) e pode ser pago em instituições financeiras e de pagamento autorizadas a funcionar pelo Banco Central.
:::
## Request
### Request Endpoint
ENDPOINT /bill_payment/account/**ACCOUNT_KEY**/payment/batch_bank_slip/**PAYMENT_BATCH_KEY**/confirmation
MÉTODO PATCH
### Request Path Params
| Campo | Tipo | Descrição | Caracteres |
| --------------------- | ----- | ---------------------------------------------------------------------------------------- | ---------- |
| `account_key` * | uuid4 | Chave única de identificação da conta. | 36 |
| `payment_batch_key` * | uuid4 | Chave única de identificação do lote (`batch_payment_key` retornado na criação do lote). | 36 |
### Request Body
**Request Body: Rejeição do lote**
```json
{
"batch_status": "rejected"
}
```
**Request Body: Aprovação do lote**
```json
{
"batch_status": "approved"
}
```
### Body Params
| Campo | Tipo | Descrição |
| ---------------- | ------ | ------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `batch_status` * | string | Decisão sobre o lote. Valores: `approved` (seguir com o processamento) ou `rejected` (cancelar o lote). Ver [enumerador batch_confirmation_status](#enumerador-batch_confirmation_status). |
### Enumerador batch_confirmation_status
Valores aceitos no corpo da requisição para `batch_status`:
| Valor | Descrição |
| ---------- | ------------------------------------------------------------- |
| `approved` | Aprovar o lote e continuar o fluxo de processamento. |
| `rejected` | Rejeitar o lote; não há processamento assíncrono dos boletos. |
## Response
### Resposta: lote rejeitado
STATUS 200
Quando `batch_status` no corpo da requisição é `rejected`, a API responde com **200**. O lote fica encerrado como rejeitado; não há fila assíncrona de pagamento dos boletos.
**Response Body: Lote rejeitado**
```json
{
"batch_payment_key": "a3214093-e51c-55e2-b5d3-60244475b3fb",
"request_control_key": "b6804f32-101e-4702-8fbc-c2dbc4c2caec",
"account_key": "6dc89d57-fac7-4643-b151-cd2ca0a7f68f",
"total_amount": 1357.3,
"batch_status": "rejected",
"payment_type": "bank_slip"
}
```
### Resposta: lote aprovado — processamento assíncrono
STATUS 202
Quando `batch_status` no corpo é `approved`, a API responde com **202** e o lote segue para **processamento assíncrono** dos boletos. O corpo retorna `batch_status` como `approved`.
**Response Body: Lote aprovado para processamento assíncrono**
```json
{
"batch_payment_key": "a3214093-e51c-55e2-b5d3-60244475b3fb",
"request_control_key": "b6804f32-101e-4702-8fbc-c2dbc4c2caec",
"account_key": "6dc89d57-fac7-4643-b151-cd2ca0a7f68f",
"total_amount": 1357.3,
"batch_status": "approved",
"payment_type": "bank_slip"
}
```
### Response Body Params
| Campo | Tipo | Descrição |
| ----------------------- | ------ | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `batch_payment_key` * | uuid4 | Chave única de identificação do pagamento em lote. |
| `request_control_key` * | uuid4 | Chave única de identificação da requisição do cliente (lote). |
| `account_key` * | uuid4 | Chave da conta debitada. |
| `total_amount` * | number | Soma dos valores dos itens do lote. |
| `batch_status` * | string | Status do lote após esta chamada (`rejected` ou `approved` para o fluxo descrito nesta página). Alinhado ao ciclo de vida em [Solicitar pagamento em lote de boleto bancário — batch_payment_status](./solicitar_pagamento_lote_de_boleto_bancario_com_confirmacao_de_lote.md#enumeradores-batch_payment_status). |
| `payment_type` * | string | Tipo do pagamento; para este fluxo, espera-se `bank_slip`. |
### Error Response
STATUS 4XX
**Response Body**
```json
{
"title": "Título",
"description": "Description in english",
"translation": "Descrição em português",
"code": "Código"
}
```
| Código HTTP | Código QI | Título | Descrição (eng) | Descrição (pt-br) |
| ----------- | --------- | ----------- | --------------------------------------------- | ----------------------------------------------------- |
| 400 | BIP000013 | Bad Request | The source account is closed. | A conta de origem está fechada. |
| 400 | BIP000050 | Bad Request | Requester configuration does not exist | Configuração do requester não existe. |
| 404 | BIP000083 | Not Found | Batch payment not found by batch payment key. | Lote de pagamentos não encontrado pela chave do lote. |
| 400 | BIP000084 | Bad Request | Batch payment status is not pending. | O status do lote de pagamentos não está pendente. |
---
# Confirmação de lote de pagamento de fatura de recolhimento (convênio/tributo)
URL: /en/documentation/baas/cobranca/confirmacao_de_lote_de_fatura_de_recolhimento
Este endpoint permite **confirmar ou rejeitar** um lote de pagamento de faturas de recolhimento previamente criado com [Solicitar pagamento em lote de fatura de recolhimento (convênio/tributo)](./solicitar_pagamento_lote_de_fatura_de_recolhimento_com_confirmacao_de_lote.md). A confirmação é a etapa que define se o processamento do lote segue (aprovação) ou é encerrado sem débito dos títulos (rejeição).
:::info Fatura de recolhimento
Esse tipo de cobrança é emitido por concessionárias de serviços (conta de água, luz, telefone e gás) e órgãos públicos (tributos). Eles não são registrados na Câmara Interbancária de Pagamento (CIP/Núclea), por isso, não retornam as mesmas informações que um boleto bancário apresenta.
:::
## Request
### Request Endpoint
ENDPOINT /bill_payment/account/**ACCOUNT_KEY**/payment/batch_collection_slip/**PAYMENT_BATCH_KEY**/confirmation
MÉTODO PATCH
### Request Path Params
| Campo | Tipo | Descrição | Caracteres |
| --------------------- | ----- | ---------------------------------------------------------------------------------------- | ---------- |
| `account_key` * | uuid4 | Chave única de identificação da conta. | 36 |
| `payment_batch_key` * | uuid4 | Chave única de identificação do lote (`batch_payment_key` retornado na criação do lote). | 36 |
### Request Body
**Request Body: Rejeição do lote**
```json
{
"batch_status": "rejected"
}
```
**Request Body: Aprovação do lote**
```json
{
"batch_status": "approved"
}
```
### Body Params
| Campo | Tipo | Descrição |
| ---------------- | ------ | ------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `batch_status` * | string | Decisão sobre o lote. Valores: `approved` (seguir com o processamento) ou `rejected` (cancelar o lote). Ver [enumerador batch_confirmation_status](#enumerador-batch_confirmation_status). |
### Enumerador batch_confirmation_status
Valores aceitos no corpo da requisição para `batch_status`:
| Valor | Descrição |
| ---------- | ----------------------------------------------------------------------------- |
| `approved` | Aprovar o lote e continuar o fluxo de processamento. |
| `rejected` | Rejeitar o lote; não há processamento assíncrono das faturas de recolhimento. |
## Response
### Resposta: lote rejeitado
STATUS 200
Quando `batch_status` no corpo da requisição é `rejected`, a API responde com **200**. O lote fica encerrado como rejeitado; não há fila assíncrona de pagamento das faturas de recolhimento.
**Response Body: Lote rejeitado**
```json
{
"batch_payment_key": "a3214093-e51c-55e2-b5d3-60244475b3fb",
"request_control_key": "b6804f32-101e-4702-8fbc-c2dbc4c2caec",
"account_key": "daae79e6-ee8b-449f-aa1e-96959d5d5a72",
"total_amount": 2778.42,
"batch_status": "rejected",
"payment_type": "collection_slip"
}
```
### Resposta: lote aprovado — processamento assíncrono
STATUS 202
Quando `batch_status` no corpo é `approved`, a API responde com **202** e o lote segue para **processamento assíncrono** das faturas de recolhimento. O corpo retorna `batch_status` como `approved`.
**Response Body: Lote aprovado para processamento assíncrono**
```json
{
"batch_payment_key": "a3214093-e51c-55e2-b5d3-60244475b3fb",
"request_control_key": "b6804f32-101e-4702-8fbc-c2dbc4c2caec",
"account_key": "daae79e6-ee8b-449f-aa1e-96959d5d5a72",
"total_amount": 2778.42,
"batch_status": "approved",
"payment_type": "collection_slip"
}
```
### Response Body Params
| Campo | Tipo | Descrição |
| ----------------------- | ------ | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `batch_payment_key` * | uuid4 | Chave única de identificação do pagamento em lote. |
| `request_control_key` * | uuid4 | Chave única de identificação da requisição do cliente (lote). |
| `account_key` * | uuid4 | Chave da conta debitada. |
| `total_amount` * | number | Soma dos valores dos itens do lote. |
| `batch_status` * | string | Status do lote após esta chamada (`rejected` ou `approved` para o fluxo descrito nesta página). Alinhado ao ciclo de vida em [Solicitar pagamento em lote de fatura de recolhimento — batch_payment_status](./solicitar_pagamento_lote_de_fatura_de_recolhimento_com_confirmacao_de_lote.md#enumeradores-batch_payment_status). |
| `payment_type` * | string | Tipo do pagamento; para este fluxo, espera-se `collection_slip`. |
### Error Response
STATUS 4XX
**Response Body**
```json
{
"title": "Título",
"description": "Description in english",
"translation": "Descrição em português",
"code": "Código"
}
```
| Código HTTP | Código QI | Título | Descrição (eng) | Descrição (pt-br) |
| ----------- | --------- | ----------- | --------------------------------------------- | ----------------------------------------------------- |
| 400 | BIP000013 | Bad Request | The source account is closed. | A conta de origem está fechada. |
| 400 | BIP000050 | Bad Request | Requester configuration does not exist | Configuração do requester não existe. |
| 404 | BIP000083 | Not Found | Batch payment not found by batch payment key. | Lote de pagamentos não encontrado pela chave do lote. |
| 400 | BIP000084 | Bad Request | Batch payment status is not pending. | O status do lote de pagamentos não está pendente. |
---
# Consult boleto
URL: /en/documentation/baas/cobranca/consultar_boleto_bancario
This endpoint is used to query information about a boleto.
:::info Boleto
This is the conventional boleto (with digitable lines not starting with the digit 8). It is registered with the Interbank Payment Clearinghouse (CIP/Núclea) and can be paid at financial institutions and payment institutions authorized to operate by the Central Bank.
:::
## Request
### Request Endpoint
ENDPOINT /bill_payment/bank_slip/ DIGITABLE_LINE or BARCODE
MÉTODO GET
### Request Path Params
| Field | Type | Description | Characters |
|---------------------|---------|-----------------------------------|------------|
| `digitable_line` | string | Digitable line to be queried. | 47 |
| `barcode` | string | Barcode to be queried. | 44 |
## Response
### Success Response
STATUS 200
Response Body: Boleto available for payment
```json
{
"barcode":"00193967000009910000000003615574000000002417",
"digitable_line":"00190000090361557400500000024174396700000991000",
"payer_name":"COOPERATIVA AGRO.INDUSTRIAL TEST",
"payer_document_number":"21063663000125",
"beneficiary_name":"TESTE EQUIPAMENTOS E SERVICOS LTDA.",
"beneficiary_trading_name":"TESTE EQUIPAMENTOS E SERVICOS LTDA",
"beneficiary_document_number":"30639204000138",
"beneficiary_bank_ispb":"00000000",
"guarantor_name":null,
"guarantor_document_number":null,
"expiration_date":"2024-03-29",
"max_payment_data": "2026-03-29",
"partial_payment_indicator":"not_allowed",
"registered_payment_amount":null,
"nominal_amount":9910.0,
"total_amount":10129.1,
"rebate_amount":0.0,
"discount_amount":0.0,
"fine_amount":0.0,
"interest_amount":219.1
}
```
### Response Body Params
| Field | Type | Description |
|---------------------|---------|-----------------------------------|
| `barcode` * | string | Barcode. |
| `digitable_line` * | string | Digitable line. |
| `payer_name` * | string | Payer's name.|
| `payer_document_number` * | string | Payer's document number (CPF/CNPJ). |
| `beneficiary_name` * | string | Beneficiary's name. |
| `beneficiary_trading_name` | string | Beneficiary's trade name. |
| `beneficiary_document_number` * | string | Beneficiary's document number (CPF/CNPJ). |
| `beneficiary_bank_ispb` * | string | ISPB code of the beneficiary's bank. |
| `guarantor_name` | string | Name of the guarantor. |
| `guarantor_document_number` | string | Guarantor's document number (CPF/CNPJ). |
| `expiration_date` * | string | Due date. |
| `max_payment_date` * | string | Maximum payment date. |
| `partial_payment_indicator` * | [enum](#enumerators-partial_payment_indicator) | Partial payment indicator |
| `registered_payment_amount` | string | Total registered payment amount. |
| `nominal_amount` * | number | Original amount. |
| `total_amount` * | number | Total amount. |
| `rebate_amount` * | number | Rebate amount. |
| `discount_amount` * | number | Discount amount. |
| `fine_amount` * | number | Fine amount. |
| `interest_amount` * | number | Interest amount. |
### Enumerators partial_payment_indicator
| Enumerator | Type | Description |
|---------------|-----------|---------------|
| `allowed` | string | Allowed |
| `not_allowed` | string | Not allowed |
### Error Response
STATUS 4XX
Response Body
```json
{
"title": "Título",
"description": "Description in english",
"translation": "Description in portuguese",
"code": "Código"
}
```
| HTTP Code | QI Code | Title | Description (eng) | Description (pt-br) |
|-------------|-----------|--------|------------------|------------------|
| 400 | BIP000001 | Bad Request | The barcode or digitable line must have 44 or 47 characters. | O código de barras ou linha digitável deve ter 44 ou 47 caracteres. |
| 400 | BIP000002 | Bad Request | The bill sent does not correspond to a bank slip. | A conta enviado não corresponde a um boleto bancário. |
| 400 | BIP000003 | Bad Request | The digitable line sent is invalid. | A linha digitável enviada é inválida. |
| 404 | BIP000004 | Not Found | The boleto was not found. | O boleto não foi encontrado. |
| 400 | BIP000005 | Bad Request | It was not possible to consult the boleto at this time. Please try again in a few minutes. | Não foi possível consultar o boleto neste momento. Por favor, tente novamente em alguns minutos. |
| 400 | BIP000006 | Bad Request | Boleto already written off | Boleto já baixado |
| 400 | BIP000007 | Bad Request | Boleto blocked for payment | Boleto bloqueado para pagamento |
| 400 | BIP000008 | Bad Request | Boleto already paid | Boleto já pago |
| 400 | BIP000009 | Bad Request | Invalid boleto. Please consult issuing bank | Boleto inválido. Favor consultar banco emissor |
## Sandbox Environment
In our sandbox environment, we provide mocked digitable lines for simulating successful payments and testing error scenarios.
### Success Scenarios
| Digitable Line |
|---|
| 00190000090361557400500000024174396700000991000 |
| 00190000090282802601919212747174596760001294161 |
| 23793390014000000455277000249001596900000103995 |
| 75691434020137513680900001040013196770002417240 |
| 21390001171200000570700168167484796770000148206 |
### Error Scenarios
| Digitable Line | Error Code |
|---|---|
| 34191090083273252027893634770007296690012513600 | BIP000007 |
| 07090010287045349010776686070590896770001160123 | BIP000007 |
| 42297048060005815702500130494123896770000239491 | BIP000006 |
| 74891123702849020818918378871083196690000050000 | BIP000009 |
| 23792374119000209350986000372408496610000122810 | BIP000008 |
---
# Consult collection invoice (agreement/tribute)
URL: /en/documentation/baas/cobranca/consultar_fatura_de_recolhimento
This endpoint is used to query information about a collection invoice.
:::info Collection Invoice
This type of charge is issued by utility companies (water, electricity, telephone, and gas bills) and public entities (taxes). They are not registered with the Interbank Payment Clearinghouse (CIP/Núclea) and, therefore, do not return the same information as a boleto.
:::
## Request
### Request Endpoint
ENDPOINT /bill_payment/collection_slip/ DIGITABLE_LINE or BARCODE
MÉTODO GET
### Request Path Params
| Field | Type | Description | Characters |
|---------------------|---------|-----------------------------------|------------|
| `digitable_line` | string | Digitable line to be queried. | 48 |
| `barcode` | string | Barcode to be queried. | 44 |
## Response
### Success Response
STATUS 200
Response Body: Collection invoice available for payment
```json
{
"barcode": null,
"digitable_line": "836200000138892100450006762142420244046000010192",
"collection_name": "CIA ULTRAGAZ SA-COD",
"expiration_date": "2024-04-15",
"total_amount": 1389.21
}
```
### Response Body Params
| Field | Type | Description |
|---------------------|---------|-----------------------------------|
| `barcode` | string | Barcode. |
| `digitable_line` | string | Digitable line. |
| `collection_name` * | string | Name of the agreement. |
| `expiration_date` * | string | Due date. |
| `total_amount` * | number | Total amount. |
### Error Response
STATUS 4XX
Response Body
```json
{
"title": "Título",
"description": "Description in english",
"translation": "Description in portuguese",
"code": "Código"
}
```
| HTTP Code | QI Code | Title | Description (eng) | Description (pt-br) |
|-------------|-----------|--------|------------------|------------------|
| 400 | BIP000032 | Bad Request | The bill sent does not correspond to a collection slip. | A conta enviada não corresponde a uma fatura de recolhimento. |
| 400 | BIP000033 | Bad Request | The barcode or digitable line of the collection slip must have 44 or 48 characters. | O código de barras ou linha digitável da fatura de recolhimento deve ter 44 ou 48 caracteres. |
| 400 | BIP000034 | Bad Request | Collection slip already paid. | Fatura de recolhimento já paga. |
| 400 | BIP000035 | Bad Request | Covenant slip invalid barcode. | Código de barras da fatura de recolhimento inválido. |
| 400 | BIP000036 | Bad Request | Covenant slip overdue. | Fatura de recolhimento vencida. |
| 400 | BIP000037 | Bad Request | Error in collection slip consultation. | Erro na consulta da fatura de recolhimento. |
| 400 | BIP000038 | Bad Request | Outside of covenant payment hours. | Fora do horário de pagamento do convênio. |
| 400 | BIP000039 | Bad Request | Collection slip not accepted. | Fatura de recolhimento não aceita. |
| 400 | BIP000040 | Bad Request | Minimum advance not reached. | Mínimo de dias de adiantamento não atingido. |
| 400 | BIP000041 | Bad Request | Max payment amount exceeded. | Valor máximo de pagamento excedido. |
## Sandbox Environment
In our sandbox environment, we provide mocked digitable lines for simulating successful payments and testing error scenarios.
### Success Scenarios
| Digitable Line |
|---|
| 828300000007411100972013905080001546763201900028 |
| 838000000009235700481007241345219112001474229880 |
| 848000000006308600802021201071261517689002201070 |
| 858200000015000000643025703477209504800448091020 |
### Error Scenarios
| Digitable Line | Error Code |
|---|---|
| 858500000037350000643217212883260006147448091022 | BIP000035 |
---
# Consultar lote de pagamento
URL: /en/documentation/baas/cobranca/consultar_lote_de_pagamento
Este endpoint retorna o resumo do lote e a lista paginada dos pagamentos que o compõem (boletos bancários ou faturas de recolhimento).
Para localizar `batch_payment_key`, utilize [Listar lotes de pagamento](./listar_lotes_de_pagamento.md).
:::info Boleto bancário
É o boleto bancário convencional (linhas digitáveis não iniciadas com dígito 8). Possui registro na Câmara Interbancária de Pagamento (CIP/Núclea) e pode ser pago em instituições financeiras e de pagamento autorizadas a funcionar pelo Banco Central.
:::
:::info Fatura de recolhimento
Esse tipo de cobrança é emitido por concessionárias de serviços (conta de água, luz, telefone e gás) e órgão públicos (tributos). Eles não são registrados na Câmara Interbancária de Pagamento (CIP/Núclea), por isso, não retornam as mesmas informações que um Boleto bancário apresenta.
:::
## Request
### Request Endpoint
ENDPOINT /bill_payment/account/**ACCOUNT_KEY**/batch/**BATCH_PAYMENT_KEY**
MÉTODO GET
### Request Path Params
| Campo | Tipo | Descrição | Caracteres |
| --------------------- | ----- | -------------------------------------------------- | ---------- |
| `account_key` * | uuid4 | Chave única de identificação da conta. | 36 |
| `batch_payment_key` * | uuid4 | Chave única de identificação do pagamento em lote. | 36 |
### Request Query String Params
| Campo | Tipo | Descrição |
| ----------- | ------ | ----------------------------------------------------------------------------- |
| `page` | string | Número da página dos itens em `payments.data`. 1 por padrão. |
| `page_size` | string | Tamanho da página dos itens em `payments.data`. 30 por padrão e valor máximo. |
## Response
### Success Response
STATUS
200
**Response Body: Detalhes do lote de pagamento**
```json
{
"request_control_key": "b6804f32-101e-4702-8fbc-c2dbc4c2caec",
"total_paid": 10,
"total_pending": 0,
"total_error": 0,
"total_amount": 1357.3,
"payments": {
"pagination": {
"current_page": 1,
"rows_per_page": 30
},
"data": [
{
"payment_key": "c4325104-d60b-44f3-aae4-49155564a2ea",
"payer_name": "COOPERATIVA INDUSTRIAL MURILO",
"payer_document_number": "00037025000160",
"source_account_key": "6dc89d57-fac7-4643-b151-cd2ca0a7f68f",
"transaction_key": "4e80070a-a0bb-4be2-8178-55fbd73a3704",
"transaction_revert_key": null,
"paid_amount": 1050.1,
"payment_date": "2024-04-03",
"payment_type": "bank_slip",
"bank_slip": {
"bank_slip_key": "95080ffd-3ac5-48d7-b3fe-659e4aaba81a",
"barcode": "00193967000009910000000003615574000000002417",
"digitable_line": "00190000090361557400500000024174396700000991000",
"payer_name": "COOPERATIVA TESTE",
"payer_document_number": "00037025000160",
"beneficiary_name": "TESTE EQUIPAMENTOS E SERVICOS LTDA",
"beneficiary_trading_name": "TESTE EQUIPAMENTOS E SERVICOS LTDA",
"beneficiary_document_number": "52069937000117",
"beneficiary_bank_ispb": "00000000",
"guarantor_name": null,
"guarantor_document_number": null,
"expiration_date": "2024-03-29",
"max_payment_date": "2026-03-29",
"partial_payment_indicator": "allowed",
"registered_payment_amount": 9029.0,
"nominal_amount": 9910.0,
"total_amount": 10129.1,
"rebate_amount": 0.0,
"discount_amount": 0.0,
"fine_amount": 0.0,
"interest_amount": 219.1
},
"collection_slip": null,
"payment_status": "executed",
"error_reason": null
}
]
}
}
```
### Response Body Params
| Campo | Tipo | Descrição |
| ----------------------- | -------------------------- | ------------------------------------------------------------- |
| `request_control_key` * | uuid4 | Chave única de identificação da requisição do cliente (lote). |
| `total_paid` * | int | Quantidade de itens do lote pagos com sucesso. |
| `total_pending` * | int | Quantidade de itens ainda pendentes no lote. |
| `total_error` * | int | Quantidade de itens com erro no lote. |
| `total_amount` * | number | Valor total do lote. |
| `payments` * | [object](#objeto-payments) | Lista paginada dos pagamentos do lote. |
### Objeto payments
| Campo | Tipo | Descrição |
| -------------- | ---------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------- |
| `pagination` * | [object](#objeto-pagination) | Paginação da lista de pagamentos do lote. |
| `data` * | array | Itens do lote (estrutura equivalente a cada elemento de `data` em [Listar pagamentos](./listar_pagamentos.md), com campos adicionais abaixo). |
Cada elemento de `payments.data` contém:
| Campo | Tipo | Descrição |
| ------------------------- | ------------------------------------ | ------------------------------------------------------------------------------ |
| `payment_key` * | uuid4 | Chave única de identificação do pagamento. |
| `payer_name` * | string | Nome do pagador efetivo. |
| `payer_document_number` * | string | Número de documento do pagador efetivo (CPF/CNPJ). |
| `source_account_key` * | uuid4 | Chave da conta debitada. |
| `transaction_key` * | uuid4 | Chave da transação do pagamento. |
| `transaction_revert_key` | uuid4 | Chave da transação de reversão do pagamento. |
| `paid_amount` * | number | Valor pago efetivamente. |
| `payment_date` * | string | Data do pagamento. |
| `payment_type` * | [enum](#enumeradores-payment_type) | Tipo do pagamento. |
| `bank_slip` | [object](#objeto-bank_slip) | Boleto bancário. Pode ser `null` quando `payment_type` for `collection_slip`. |
| `collection_slip` | [object](#objeto-collection_slip) | Fatura de recolhimento. Pode ser `null` quando `payment_type` for `bank_slip`. |
| `payment_status` * | [enum](#enumeradores-payment_status) | Status do pagamento. |
| `error_reason` | string | Motivo do erro, quando aplicável; caso contrário `null`. |
### Objeto pagination
| Campo | Tipo | Descrição |
| ----------------- | ---- | ----------------------------------- |
| `current_page` * | int | Página atual retornada. |
| `rows_per_page` * | int | Quantidade de registros por página. |
### Enumeradores payment_type
| Enumerador | Descrição |
| ----------------- | ---------------------- |
| `bank_slip` | Boleto bancário |
| `collection_slip` | Fatura de recolhimento |
### Enumeradores payment_status
| Enumerador | Descrição |
| ------------------- | -------------------- |
| `pending_execution` | Pendente de execução |
| `executed` | Executado |
| `reverted` | Revertido |
| `rejected` | Rejeitado |
| `error` | Erro |
### Objeto bank_slip
| Campo | Tipo | Descrição |
| ------------------------------- | ----------------------------------------------- | --------------------------------------------------- |
| `bank_slip_key` * | uuid4 | Chave única de identificação do boleto bancário. |
| `barcode` * | string | Código de barras. |
| `digitable_line` * | string | Linha digitável. |
| `payer_name` * | string | Nome do pagador. |
| `payer_document_number` * | string | Número de documento do pagador (CPF/CNPJ). |
| `beneficiary_name` * | string | Nome do beneficiário. |
| `beneficiary_trading_name` | string | Nome fantasia do beneficiário. |
| `beneficiary_document_number` * | string | Número de documento do beneficiário (CPF/CNPJ). |
| `beneficiary_bank_ispb` * | string | Código ispb do banco do beneficiário. |
| `guarantor_name` | string | Nome do sacador avalista. |
| `guarantor_document_number` | string | Número de documento do sacador avalista (CPF/CNPJ). |
| `expiration_date` * | string | Data de vencimento. |
| `max_payment_date` * | string | Data máxima de pagamento. |
| `partial_payment_indicator` * | [enum](#enumeradores-partial_payment_indicator) | Indicador de pagamento parcial. |
| `registered_payment_amount` | number | Valor total de pagamento registrado. |
| `nominal_amount` * | number | Valor original. |
| `total_amount` * | number | Valor total. |
| `rebate_amount` * | number | Valor do abatimento. |
| `discount_amount` * | number | Valor do desconto. |
| `fine_amount` * | number | Valor da multa. |
| `interest_amount` * | number | Valor dos juros. |
### Enumeradores partial_payment_indicator
| Enumerador | Descrição |
| ------------- | ------------- |
| `allowed` | Permitido |
| `not_allowed` | Não permitido |
### Objeto collection_slip
| Campo | Tipo | Descrição |
| ------------------------------ | ------ | ------------------------------------------- |
| `barcode` * | string | Código de barras. |
| `digitable_line` * | string | Linha digitável. |
| `collection_name` * | string | Nome do pagador. |
| `collection_document_number` * | string | Número de documento do convênio (CPF/CNPJ). |
| `expiration_date` * | string | Data de vencimento. |
| `total_amount` * | number | Valor total. |
### Error Response
STATUS
4XX
**Response Body**
```json
{
"title": "Título",
"description": "Description in english",
"translation": "Descrição em português",
"code": "Código"
}
```
| Código HTTP | Código QI | Título | Descrição (eng) | Descrição (pt-br) |
| ----------- | --------- | ----------- | --------------------------------------------------------------- | -------------------------------------------------------------- |
| 400 | BIP000027 | Bad Request | Invalid integer value for page or size query string parameters. | Valor inválido para parâmetros de página ou tamanho de página. |
---
# Listar lotes de pagamento
URL: /en/documentation/baas/cobranca/listar_lotes_de_pagamento
Este endpoint retorna os lotes de pagamento de boletos bancários e faturas de recolhimento associados à conta, com suporte a filtros e paginação.
:::info Boleto bancário
É o boleto bancário convencional (linhas digitáveis não iniciadas com dígito 8). Possui registro na Câmara Interbancária de Pagamento (CIP/Núclea) e pode ser pago em instituições financeiras e de pagamento autorizadas a funcionar pelo Banco Central.
:::
:::info Fatura de recolhimento
Esse tipo de cobrança é emitido por concessionárias de serviços (conta de água, luz, telefone e gás) e órgão públicos (tributos). Eles não são registrados na Câmara Interbancária de Pagamento (CIP/Núclea), por isso, não retornam as mesmas informações que um Boleto bancário apresenta.
:::
## Request
### Request Endpoint
ENDPOINT /bill_payment/account/ ACCOUNT_KEY /batches
MÉTODO GET
### Request Path Params
| Campo | Tipo | Descrição | Caracteres |
|---------------------|---------|-----------------------------------------|------------|
| `account_key` * | uuid4 | Chave única de identificação da conta. | 36 |
### Request Query String Params
| Campo | Tipo | Descrição |
|---------------------|-------------|-----------------------------------|
| `request_control_key` | uuid4 | Chave única de identificação da requisição do cliente (lote). |
| `batch_payment_key` | uuid4 | Chave única de identificação do pagamento em lote. |
| `payment_type` | [enum](#enumeradores-payment_type) | Tipo do pagamento do lote. |
| `batch_payment_status` | [enum](#enumeradores-batch_payment_status) | Status do lote. |
| `date_from` | string | Data inicial. Formato "YYYY-MM-DD". |
| `date_to` | string | Data final. Formato "YYYY-MM-DD". |
| `page` | string | Número da página requisitada. 1 por padrão. |
| `page_size` | string | Tamanho da página requisitada na consulta. 30 por padrão e valor máximo. |
### Enumeradores payment_type
| Enumerador | Tipo | Descrição |
|---------------|-----------|---------------|
| `bank_slip` | string | Boleto bancário |
| `collection_slip` | string | Fatura de recolhimento |
### Enumeradores batch_payment_status
| Enumerador | Descrição |
|---------------|---------------|
| `pending` | Pendente de processamento |
| `pending_2fa_approval` | Pendente de aprovação 2FA |
| `rejected` | Rejeitado |
| `approved` | Aprovado |
| `processed` | Processado |
## Response
### Success Response
STATUS 200
Response Body: Listagem de lotes de pagamento
```json
{
"pagination": {
"current_page": 1,
"rows_per_page": 30
},
"data": [
{
"batch_payment_key": "a3214093-e51c-55e2-b5d3-60244475b3fb",
"request_control_key": "b6804f32-101e-4702-8fbc-c2dbc4c2caec",
"batch_status": "processed",
"payment_type": "bank_slip",
"total_paid": 10,
"total_pending": 0,
"total_error": 0,
"total_amount": 1357.3
}
]
}
```
### Response Body Params
| Campo | Tipo | Descrição |
|---------------------|---------|-----------------------------------|
| `pagination` * | [object](#objeto-pagination) | Informações de paginação da consulta. |
| `data` * | array | Lista de lotes encontrados. |
Cada elemento de `data` contém:
| Campo | Tipo | Descrição |
|---------------------|---------|-----------------------------------|
| `batch_payment_key` * | uuid4 | Chave única de identificação do pagamento em lote. |
| `request_control_key` * | uuid4 | Chave única de identificação da requisição do cliente (lote). |
| `batch_status` * | [enum](#enumeradores-batch_payment_status-1) | Status atual do lote. |
| `payment_type` * | [enum](#enumeradores-payment_type-1) | Tipo do pagamento do lote. |
| `total_paid` * | int | Quantidade de itens do lote pagos com sucesso. |
| `total_pending` * | int | Quantidade de itens ainda pendentes no lote. |
| `total_error` * | int | Quantidade de itens com erro no lote. |
| `total_amount` * | number | Valor total do lote. |
### Objeto pagination
| Campo | Tipo | Descrição |
|---------------------|---------|-----------------------------------|
| `current_page` * | int | Página atual retornada. |
| `rows_per_page` * | int | Quantidade de registros por página. |
### Enumeradores payment_type
| Enumerador | Descrição |
|---------------|---------------|
| `bank_slip` | Boleto bancário |
| `collection_slip` | Fatura de recolhimento |
### Enumeradores batch_payment_status
| Enumerador | Descrição |
|---------------|---------------|
| `pending` | Pendente de processamento |
| `pending_2fa_approval` | Pendente de aprovação 2FA |
| `rejected` | Rejeitado |
| `approved` | Aprovado |
| `processed` | Processado |
### Error Response
STATUS 4XX
Response Body
```json
{
"title": "Título",
"description": "Description in english",
"translation": "Descrição em português",
"code": "Código"
}
```
| Código HTTP | Código QI | Título | Descrição (eng) | Descrição (pt-br) |
|-------------|-----------|--------|------------------|------------------|
| 400 | BIP000026 | Bad Request | Invalid payment date format. The correct format is YYYY-MM-DD. | Formato de data de pagamento inválido. O formato correto é YYYY-MM-DD. |
| 400 | BIP000027 | Bad Request | Invalid integer value for page or size query string parameters. | Valor inválido para parâmetros de página ou tamanho de página. |
| 400 | BIP000047 | Bad Request | Invalid payment type. | Tipo de pagamento inválido. |
---
# List payments
URL: /en/documentation/baas/cobranca/listar_pagamentos
This endpoint aims to provide details of all charges paid by the client, including boletos and collection invoices.
:::info Boleto
This is the conventional boleto (with digitable lines not starting with the digit 8). It is registered with the Interbank Payment Clearinghouse (CIP/Núclea) and can be paid at financial institutions and payment institutions authorized to operate by the Central Bank.
:::
:::info Collection Invoice
This type of charge is issued by utility companies (water, electricity, telephone, and gas bills) and public entities (taxes). They are not registered with the Interbank Payment Clearinghouse (CIP/Núclea) and, therefore, do not return the same information as a boleto.
:::
## Request
### Request Endpoint
ENDPOINT /account/ ACCOUNT_KEY /payments
MÉTODO GET
### Request Path Params
| Campo | Tipo | Descrição | Caracteres |
|---------------------|---------|-----------------------------------------|------------|
| `account_key` * | uuid4 | Chave única de identificação da conta. | 36 |### Request Query String Params
| Field | Type | Description |
|---------------------|-------------|-----------------------------------|
| `request_control_key` | uuid4 | Unique identification key for the client's request. |
| `payment_key` | uuid4 | Unique payment identification key. |
| `payment_type` | [enum](#enumerators-payment_type) | Payment type. |
| `date_from` | string | Start date. Format "YYYY-MM-DD". |
| `date_to` | string | End date. Format "YYYY-MM-DD". |
| `page` | string | Requested page number. 1 by default. |
| `page_size` | string | Requested page size in the query. 30 by default and maximum value. |
### Enumerators payment_type
| Enumerator | Type | Description |
|---------------|-----------|---------------|
| `bank_slip` | string | Boleto |
| `collection_slip` | string | Collection invoice |
## Response
### Success Response
STATUS 200
Response Body: Payment query
```json
{
"data": [
{
"payment_key":"c4325104-d60b-44f3-aae4-49155564a2ea",
"request_control_key":"b713b2f6-2f48-4d18-b0c9-7186e4edf189",
"payer_name":"COOPERATIVA INDUSTRIAL MURILO",
"payer_document_number":"00037025000160",
"source_account_key":"6dc89d57-fac7-4643-b151-cd2ca0a7f68f",
"transaction_key":"4e80070a-a0bb-4be2-8178-55fbd73a3704",
"transaction_revert_key":null,
"paid_amount":1050.1,
"payment_date":"2024-04-03",
"payment_type":"bank_slip",
"bank_slip": {
"bank_slip_key":"95080ffd-3ac5-48d7-b3fe-659e4aaba81a",
"barcode":"00193967000009910000000003615574000000002417",
"digitable_line":"00190000090361557400500000024174396700000991000",
"payer_name":"COOPERATIVA TESTE",
"payer_document_number":"00037025000160",
"beneficiary_name":"TESTE EQUIPAMENTOS E SERVICOS LTDA",
"beneficiary_trading_name":"TESTE EQUIPAMENTOS E SERVICOS LTDA",
"beneficiary_document_number":"52069937000117",
"beneficiary_bank_ispb":"00000000",
"guarantor_name":null,
"guarantor_document_number":null,
"expiration_date":"2024-03-29",
"max_payment_data": "2026-03-29",
"partial_payment_indicator":"allowed",
"registered_payment_amount":9029.0,
"nominal_amount":9910.0,
"total_amount":10129.1,
"rebate_amount":0.0,
"discount_amount":0.0,
"fine_amount":0.0,
"interest_amount":219.1
},
"collection_slip":null,
"payment_status":"executed"
}
],
"pagination": {
"current_page": 1,
"rows_per_page": 30
}
}
```
### Response Body Params
| Field | Type | Description |
|---------------------|---------|-----------------------------------|
| `payment_key` * | uuid4 | Unique payment identification key. |
| `request_control_key` * | uuid4 | Unique identification key for the client's request. |
| `payer_name` * | string | Name of the effective payer.|
| `payer_document_number` * | string | Document number of the effective payer (CPF/CNPJ). |
| `source_account_key` * | uuid4 | Key of the debited account. |
| `transaction_key` * | uuid4 | Payment transaction key. |
| `transaction_revert_key` | uuid4 | Payment reversal transaction key. |
| `paid_amount` * | number | Amount effectively paid. |
| `payment_date` * | string | Payment date. |
| `payment_type` * | [enum](#enumerators-payment_type-1) | Payment type. |
| `bank_slip` | [object](#object-bank_slip) | Boleto. |
| `collection_slip` | [object](#object-collection_slip) | Collection invoice. |
| `payment_status` * | [enum](#enumerators-payment_status) | Payment status. |
### Enumerators payment_type
| Enumerator | Description |
|---------------|---------------|
| `bank_slip` | Boleto |
| `collection_slip` | Collection invoice |
### Enumerators payment_status
| Enumerator | Description |
|---------------|---------------|
| `pending_execution` | Pending execution |
| `executed` | Executed |
| `reverted` | Reverted |
| `rejected` | Rejected |
| `error` | Error |
### Object bank_slip
| Field | Type | Description |
|-----------------------------------|---------|-----------------------------------|
| `barcode` * | string | Barcode. |
| `digitable_line` * | string | Digitable line. |
| `payer_name` * | string | Payer's name.|
| `payer_document_number` * | string | Payer's document number (CPF/CNPJ). |
| `beneficiary_name` * | string | Beneficiary's name. |
| `beneficiary_trading_name` | string | Beneficiary's trade name. |
| `beneficiary_document_number` * | string | Beneficiary's document number (CPF/CNPJ). |
| `beneficiary_bank_ispb` * | string | ISPB code of the beneficiary's bank. |
| `guarantor_name` | string | Name of the guarantor. |
| `guarantor_document_number` | string | Guarantor's document number (CPF/CNPJ). |
| `expiration_date` * | string | Due date. |
| `max_payment_date` * | string | Maximum payment date. |
| `partial_payment_indicator` * | [enum](#enumerators-partial_payment_indicator) | Partial payment indicator. |
| `registered_payment_amount` | string | Total registered payment amount. |
| `nominal_amount` * | number | Original amount. |
| `total_amount` * | number | Total amount. |
| `rebate_amount` * | number | Rebate amount. |
| `discount_amount` * | number | Discount amount. |
| `fine_amount` * | number | Fine amount. |
| `interest_amount` * | number | Interest amount. |
### Enumerators partial_payment_indicator
| Enumerator | Description |
|---------------|---------------|
| `allowed` | Allowed |
| `not_allowed` | Not allowed |
### Object collection_slip
| Field | Type | Description |
|-----------------------------------|---------|-----------------------------------|
| `barcode` * | string | Barcode. |
| `digitable_line` * | string | Digitable line. |
| `collection_name` * | string | Name of the agreement.|
| `collection_document_number` * | string | Document number of the agreement (CPF/CNPJ). |
| `expiration_date` * | string | Due date. |
| `total_amount` * | number | Total amount. |
### Error Response
STATUS 4XX
Response Body
```json
{
"title": "Título",
"description": "Description in english",
"translation": "Description in portuguese",
"code": "Código"
}
```
| HTTP Code | QI Code | Title | Description (eng) | Description (pt-br) |
|-------------|-----------|--------|------------------|------------------|
| 400 | BIP000026 | Bad Request | Invalid payment date format. The correct format is YYYY-MM-DD. | Formato de data de pagamento inválido. O formato correto é YYYY-MM-DD. |
| 400 | BIP000027 | Bad Request | Invalid integer value for page or size query string parameters. | Valor inválido para parâmetros de página ou tamanho de página. |
| 400 | BIP000047 | Bad Request | Invalid payment type. | Tipo de pagamento inválido. |
---
# Make payment of Boleto
URL: /en/documentation/baas/cobranca/pagar_boleto_bancario
This endpoint allows the payment of bank slips (boletos). The payment should be made after a consultation, using the returned information to ensure the correct flow, avoiding failures during the payment process.
:::info Bank Slip
This is the conventional bank slip (with digitable lines not starting with the digit 8). It is registered with the Interbank Payment Clearinghouse (CIP/Núclea) and can be paid at financial institutions and payment institutions authorized to operate by the Central Bank.
:::
## Request
### Request Endpoint
ENDPOINT /account/ ACCOUNT_KEY /payment/bank_slip
MÉTODO POST
### Request Path Params
| Field | Type | Description | Characters |
|---------------------|---------|-----------------------------------------|------------|
| `account_key` * | uuid4 | Unique account identification key. | 36 |
Request Body: Payment of boleto with digitable line
```json
{
"request_control_key": "b6804f32-101e-4702-8fbc-c2dbc4c2caec",
"digitable_line": "00190000090361557400500000024174396700000991000",
"payment_amount": 1156.8
}
```
Request Body: Payment of boleto with barcode
```json
{
"request_control_key": "b6804f32-101e-4702-8fbc-c2dbc4c2caec",
"barcode": "00190000090361557400500000024174396700000991000",
"payment_amount": 1156.8
}
```
### Body Params
| Field | Type | Description |
|---------------------|---------------|-----------------------------------|
| `request_control_key` * | uuid4 | Unique identification key for the client's request. |
| `barcode` | string | Barcode. |
| `digitable_line` | string | Digitable line. |
| `payment_amount` * | number | Amount to be paid. |
:::danger Warning
The `payment_amount` must always be equal to the `total_amount` returned in the bank slip query if partial payment is not allowed for the bank slip. For titles where partial payment is allowed, the client can choose the `payment_amount`, as long as its sum with the bank slip's `registered_payment_amount` does not exceed the `total_amount`.
:::
## Response
### Success Response
STATUS 201
Response Body: Payment executed
```json
{
"payment_key":"c4325104-d60b-44f3-aae4-49155564a2ea",
"request_control_key":"b713b2f6-2f48-4d18-b0c9-7186e4edf189",
"payer_name":"COOPERATIVA INDUSTRIAL MURILO",
"payer_document_number":"00037025000160",
"source_account_key":"6dc89d57-fac7-4643-b151-cd2ca0a7f68f",
"transaction_key":"4e80070a-a0bb-4be2-8178-55fbd73a3704",
"transaction_revert_key":null,
"paid_amount":1050.1,
"payment_date":"2024-04-03",
"payment_type":"bank_slip",
"bank_slip": {
"bank_slip_key":"95080ffd-3ac5-48d7-b3fe-659e4aaba81a",
"barcode":"00193967000009910000000003615574000000002417",
"digitable_line":"00190000090361557400500000024174396700000991000",
"payer_name":"COOPERATIVA TESTE",
"payer_document_number":"00037025000160",
"beneficiary_name":"TESTE EQUIPAMENTOS E SERVICOS LTDA",
"beneficiary_trading_name":"TESTE EQUIPAMENTOS E SERVICOS LTDA",
"beneficiary_document_number":"52069937000117",
"beneficiary_bank_ispb":"00000000",
"guarantor_name":null,
"guarantor_document_number":null,
"expiration_date":"2024-03-29",
"max_payment_data": "2026-03-29",
"partial_payment_indicator":"allowed",
"registered_payment_amount":9029.0,
"nominal_amount":9910.0,
"total_amount":10129.1,
"rebate_amount":0.0,
"discount_amount":0.0,
"fine_amount":0.0,
"interest_amount":219.1
},
"collection_slip":null,
"payment_status":"executed"
}
```
STATUS 202
Response Body: Payment pending execution
```json
{
"payment_key":"c4325104-d60b-44f3-aae4-49155564a2ea",
"request_control_key":"b713b2f6-2f48-4d18-b0c9-7186e4edf189",
"payer_name":"COOPERATIVA INDUSTRIAL MURILO",
"payer_document_number":"00037025000160",
"source_account_key":"6dc89d57-fac7-4643-b151-cd2ca0a7f68f",
"transaction_key":"4e80070a-a0bb-4be2-8178-55fbd73a3704",
"transaction_revert_key":null,
"paid_amount":1050.1,
"payment_date":"2024-04-03",
"payment_type":"bank_slip",
"bank_slip": {
"bank_slip_key":"95080ffd-3ac5-48d7-b3fe-659e4aaba81a",
"barcode":"00193967000009910000000003615574000000002417",
"digitable_line":"00190000090361557400500000024174396700000991000",
"payer_name":"COOPERATIVA TESTE",
"payer_document_number":"00037025000160",
"beneficiary_name":"TESTE EQUIPAMENTOS E SERVICOS LTDA",
"beneficiary_trading_name":"TESTE EQUIPAMENTOS E SERVICOS LTDA",
"beneficiary_document_number":"52069937000117",
"beneficiary_bank_ispb":"00000000",
"guarantor_name":null,
"guarantor_document_number":null,
"expiration_date":"2024-03-29",
"max_payment_data": "2026-03-29",
"partial_payment_indicator":"allowed",
"registered_payment_amount":9029.0,
"nominal_amount":9910.0,
"total_amount":10129.1,
"rebate_amount":0.0,
"discount_amount":0.0,
"fine_amount":0.0,
"interest_amount":219.1
},
"collection_slip":null,
"payment_status": "pending_execution"
}
```
:::info Information
If **HTTP Status 202** is returned with the field `payment_status` having the value **pending_execution**, the payment should not be retried.
This payment will be processed asynchronously. It is necessary to check the transfer status through the payment query, or wait for the pending payment webhook described on the [webhooks page](/documentation/baas_v2/cobranca/webhooks).
:::
### Response Body Params
| Field | Type | Description |
|---------------------|---------|-----------------------------------|
| `payment_key` * | uuid4 | Unique payment identification key. |
| `request_control_key` * | uuid4 | Unique identification key for the client's request. |
| `payer_name` * | string | Name of the effective payer. |
| `payer_document_number` * | string | Document number of the effective payer (CPF/CNPJ). |
| `source_account_key` * | uuid4 | Key of the debited account. |
| `transaction_key` * | uuid4 | Payment transaction key. |
| `transaction_revert_key` | uuid4 | Payment reversal transaction key. |
| `paid_amount` * | number | Amount effectively paid. |
| `payment_date` * | string | Payment date. |
| `payment_type` * | [enum](#enumerators-payment_type) | Payment type. |
| `bank_slip` | [object](#object-bank_slip) | Bank slip. |
| `collection_slip` | object | Collection invoice. |
| `payment_status` * | [enum](#enumerators-payment_status) | Payment status. |
### Enumerators payment_type
| Enumerator | Type | Description |
|---------------|-----------|---------------|
| `bank_slip` | string | Bank slip |
| `collection_slip` | string | Collection invoice |
:::danger Warning
The enumerator `collection_slip` does not apply to the bank slip flow, and the collection_slip object will always be null.
:::
### Enumerators payment_status
| Enumerator | Description |
|---------------|---------------|
| `pending_execution` | Pending execution |
| `executed` | Executed |
| `reverted` | Reverted |
| `rejected` | Rejected |
| `error` | Error |
:::danger Warning
For payments where QI does not receive a response from CIP within two minutes, the payment will be returned with the status `pending_execution`. After QI receives the response from CIP, the pending payment webhook described on the [webhooks page](/documentation/baas_v2/cobranca/webhooks) will be sent to the client.
:::
### Object bank_slip
| Field | Type | Description |
|-----------------------------------|---------|-----------------------------------|
| `barcode` * | string | Barcode. |
| `digitable_line` * | string | Digitable line. |
| `payer_name` * | string | Payer's name.|
| `payer_document_number` * | string | Payer's document number (CPF/CNPJ). |
| `beneficiary_name` * | string | Beneficiary's name. |
| `beneficiary_trading_name` | string | Beneficiary's trade name. |
| `beneficiary_document_number` * | string | Beneficiary's document number (CPF/CNPJ). |
| `beneficiary_bank_ispb` * | string | ISPB code of the beneficiary's bank. |
| `guarantor_name` | string | Name of the guarantor. |
| `guarantor_document_number` | string | Guarantor's document number (CPF/CNPJ). |
| `expiration_date` * | string | Due date. |
| `max_payment_date` * | string | Maximum payment date. |
| `partial_payment_indicator` * | [enum](#enumerators-partial_payment_indicator) | Partial payment indicator. |
| `registered_payment_amount` | string | Total registered payment amount. |
| `nominal_amount` * | number | Original amount. |
| `total_amount` * | number | Total amount. |
| `rebate_amount` * | number | Rebate amount. |
| `discount_amount` * | number | Discount amount. |
| `fine_amount` * | number | Fine amount. |
| `interest_amount` * | number | Interest amount. |
### Enumerators partial_payment_indicator
| Enumerator | Type | Description |
|---------------|-----------|---------------|
| `allowed` | string | Allowed |
| `not_allowed` | string | Not allowed |
### Error Response
STATUS 4XX
Response Body
```json
{
"title": "Título",
"description": "Description in english",
"translation": "Description in portuguese",
"code": "Código"
}
```
| HTTP Code | QI Code | Title | Description (eng) | Description (pt-br) |
|-------------|-----------|--------|------------------|------------------|
| 400 | BIP000001 | Bad Request | The barcode or digitable line must have 44 or 47 characters. | O código de barras ou linha digitável deve ter 44 ou 47 caracteres. |
| 400 | BIP000002 | Bad Request | The bill sent does not correspond to a bank slip. | A conta enviado não corresponde a um boleto bancário. |
| 400 | BIP000003 | Bad Request | The digitable line sent is invalid. | A linha digitável enviada é inválida. |
| 404 | BIP000004 | Not Found | The bank slip was not found. | O boleto não foi encontrado. |
| 400 | BIP000005 | Bad Request | It was not possible to consult the bank slip at this time. Please try again in a few minutes. | Não foi possível consultar o boleto neste momento. Por favor, tente novamente em alguns minutos. |
| 400 | BIP000006 | Bad Request | Bank slip already written off | Boleto já baixado |
| 400 | BIP000007 | Bad Request | Bank slip blocked for payment | Boleto bloqueado para pagamento |
| 400 | BIP000008 | Bad Request | Bank slip already paid | Boleto já pago |
| 400 | BIP000009 | Bad Request | Invalid bank slip. Please consult issuing bank | Boleto inválido. Favor consultar banco emissor |
| 403 | BIP000010 | Forbidden | User is not allowed to do this action | Usuário não tem autorização para fazer essa ação |
| 404 | BIP000011 | Not Found | The source account key was not found. | A chave da conta de origem não foi encontrada. |
| 400 | BIP000012 | Bad Request | It 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. |
| 400 | BIP000013 | Bad Request | The source account is closed. | A conta de origem está fechada. |
| 400 | BIP000014 | Bad Request | The source account is blocked. | A conta de origem está bloqueada. |
| 400 | BIP000015 | Bad Request | Payment date is greater than the maximum payment date. | A data de pagamento é maior que a data máxima de pagamento. |
| 400 | BIP000016 | Bad Request | Payment date is smaller than the calculation date. | A data de pagamento é menor que a data de cálculo. |
| 400 | BIP000017 | Bad Request | Invalid payment amount. | Valor de pagamento inválido. |
| 400 | BIP000018 | Bad Request | Partial payment is not allowed. | Pagamento parcial não é permitido. |
| 400 | BIP000019 | Bad Request | The payment amount is greater than the available amount. | O valor do pagamento é maior que o valor disponível. |
| 400 | BIP000020 | Bad Request | All partial payments for this bank slip have already been made. | Todos os pagamentos parciais deste boleto já foram realizados. |
| 400 | BIP000022 | Bad Request | Bank slip payment service is closed. | Serviço de pagamento de boleto está fechado. |
| 400 | BIP000023 | Bad Request | The source account has insufficient balance. Payment cannot be made. | A conta de origem possui saldo insuficiente. Pagamento não pode ser realizado. |
| 400 | BIP000024 | Bad Request | Request control key already exists. | Chave de controle da requisição já existe. |
| 400 | BIP000025 | Bad Request | It was not possible to pay the bank slip at this time. Please verify your information and, if necessary, contact us for assistance. | Não foi possível pagar o boleto neste momento. Por favor, verifique suas informações e, se necessário, entre em contato conosco para assistência. |
| 400 | BIP000028 | Bad Request | The source account has blocked balance. Payment cannot be made. | A conta de origem possui saldo em conta bloqueado. Pagamento não pode ser realizado. |
## Sandbox Environment
In our sandbox environment, we provide mocked digitable lines for simulating successful payments and testing error scenarios.
### Success scenarios
| Digitable line |
|---|
| 00190000090361557400500000024174396700000991000 |
| 00190000090282802601919212747174596760001294161 |
| 23793390014000000455277000249001596900000103995 |
| 75691434020137513680900001040013196770002417240 |
| 21390001171200000570700168167484796770000148206 |
### `pending_execution` scenarios
The simulation of this scenario is better described on the [simulation page](/documentation/baas_v2/cobranca/simulacao).
| Digitable line |
|---|
| 75691333790100505390300569460017397220000306867 |
### Error scenarios
| Digitable line | Error code |
|---|---|
| 34191090083273252027893634770007296690012513600 | BIP000007 |
| 07090010287045349010776686070590896770001160123 | BIP000007 |
| 42297048060005815702500130494123896770000239491 | BIP000006 |
| 74891123702849020818918378871083196690000050000 | BIP000009 |
| 23792374119000209350986000372408496610000122810 | BIP000008 |
---
# Make payment of collection invoice (agreement/tribute)
URL: /en/documentation/baas/cobranca/pagar_fatura_de_recolhimento
This endpoint allows the payment of collection invoices. The payment should be made after a consultation, using the information returned in it, to ensure the correct flow and avoid failures during the payment process.
:::info Collection Invoice
This type of charge is issued by utility companies (water, electricity, telephone, and gas bills) and public entities (taxes). They are not registered with the Interbank Payment Clearinghouse (CIP/Núclea), and thus, do not return the same information as a bank slip.
:::
## Request
### Request Endpoint
ENDPOINT /account/ ACCOUNT_KEY /payment/collection_slip
MÉTODO POST
### Request Path Params
| Field | Type | Description | Characters |
|---------------------|---------|-----------------------------------------|------------|
| `account_key` * | uuid4 | Unique account identification key. | 36 |
Request Body: Payment of collection invoice with digitable line
```json
{
"request_control_key": "b6804f32-101e-4702-8fbc-c2dbc4c2caec",
"digitable_line": "00190000090361557400500000024174396700000991000",
"payment_amount": 1156.8
}
```
Request Body: Payment of collection invoice with barcode
```json
{
"request_control_key": "b6804f32-101e-4702-8fbc-c2dbc4c2caec",
"barcode": "00190000090361557400500000024174396700000991000",
"payment_amount": 1156.8
}
```
### Body Params
| Field | Type | Description |
|---------------------|---------------|-----------------------------------|
| `request_control_key` * | uuid4 | Unique identification key for the client's request. |
| `barcode` | string | Barcode. |
| `digitable_line` | string | Digitable line. |
| `payment_amount` * | number | Amount to be paid. |
:::danger Warning
The `payment_amount` must always be equal to the `total_amount` returned in the bank slip query.
:::
## Response
### Success Response
STATUS 201
Response Body: Payment executed
```json
{
"payment_key": "33860ad0-bcb0-47b7-bbe7-c7e3ec2fc61a",
"request_control_key": "ae4508df-f2cb-4e28-9f04-a19b7f2758c9",
"payer_name": "COOPERATIVA INDUSTRIAL MURILO",
"payer_document_number": "62069937000118",
"source_account_key": "daae79e6-ee8b-449f-aa1e-96959d5d5a72",
"transaction_key": "fc9ccfd0-2f21-4207-9772-69238be74152",
"transaction_revert_key": null,
"paid_amount": 1389.21,
"payment_date": "2024-04-30",
"payment_type": "collection_slip",
"bank_slip": null,
"collection_slip": {
"barcode": null,
"digitable_line": "836200000138892100450006762142420244046000010192",
"collection_name": "CIA ULTRAGAZ SA-COD",
"collection_document_number": "00394460005887",
"expiration_date": "2024-04-15",
"total_amount": 1389.21
},
"payment_status": "executed"
}
```
STATUS 202
:::info Webhook
When the payment returns status `202`, processing is still in progress. **Do not retry the payment** until you receive the final status update via webhook.
:::
Response Body: Pending payment
```json
{
"payment_key": "33860ad0-bcb0-47b7-bbe7-c7e3ec2fc61a",
"request_control_key": "ae4508df-f2cb-4e28-9f04-a19b7f2758c9",
"payer_name": "COOPERATIVA INDUSTRIAL MURILO",
"payer_document_number": "62069937000118",
"source_account_key": "daae79e6-ee8b-449f-aa1e-96959d5d5a72",
"transaction_key": "fc9ccfd0-2f21-4207-9772-69238be74152",
"transaction_revert_key": null,
"paid_amount": 1389.21,
"payment_date": "2024-04-30",
"payment_type": "collection_slip",
"bank_slip": null,
"collection_slip": {
"barcode": null,
"digitable_line": "836200000138892100450006762142420244046000010192",
"collection_name": "CIA ULTRAGAZ SA-COD",
"collection_document_number": "00394460005887",
"expiration_date": "2024-04-15",
"total_amount": 1389.21
},
"payment_status": "pending"
}
```
### Response Body Params
| Field | Type | Description |
|---------------------|---------|-----------------------------------|
| `payment_key` * | uuid4 | Unique payment identification key. |
| `request_control_key` * | uuid4 | Unique identification key for the client's request. |
| `payer_name` * | string | Name of the effective payer.|
| `payer_document_number` * | string | Document number of the effective payer (CPF/CNPJ). |
| `source_account_key` * | uuid4 | Key of the debited account. |
| `transaction_key` * | uuid4 | Payment transaction key. |
| `transaction_revert_key` | uuid4 | Payment reversal transaction key. |
| `paid_amount` * | number | Amount effectively paid. |
| `payment_date` * | string | Payment date. |
| `payment_type` * | [enum](#enumerators-payment_type) | Payment type. |
| `bank_slip` | object | Bank slip. |
| `collection_slip` | [object](#object-collection_slip) | Collection invoice. |
| `payment_status` * | [enum](#enumerators-payment_status) | Payment status. |
### Enumerators payment_type
| Enumerator | Type | Description |
|---------------|-----------|---------------|
| `bank_slip` | string | Bank slip |
| `collection_slip` | string | Collection invoice |
:::danger Warning
The enumerator `bank_slip` does not apply to the collection invoice flow, and the bank_slip object will always be null.
:::
### Enumerators payment_status
| Enumerator | Description |
|---------------|---------------|
| `pending` | Pending |
| `executed` | Executed |
| `reverted` | Reverted |
| `rejected` | Rejected |
| `error` | Error |
### Object collection_slip
| Field | Type | Description |
|-----------------------------------|---------|-----------------------------------|
| `barcode` | string | Barcode. |
| `digitable_line` | string | Digitable line. |
| `collection_name` * | string | Name of the agreement.|
| `collection_document_number` | string | Document number of the agreement (CPF/CNPJ).|
| `expiration_date` * | string | Due date. |
| `total_amount` * | number | Total amount. |
### Error Response
STATUS 4XX
Response Body
```json
{
"title": "Título",
"description": "Description in english",
"translation": "Descrição em português",
"code": "Código"
}
```
| HTTP Code | QI Code | Title | Description (eng) | Description (pt-br) |
|-------------|-----------|--------|------------------|------------------|
| 400 | BIP000032 | Bad Request | The bill sent does not correspond to a collection slip. | A conta enviada não corresponde a uma fatura de recolhimento. |
| 400 | BIP000033 | Bad Request | The barcode or digitable line of the collection slip must have 44 or 48 characters. | O código de barras ou linha digitável da fatura de recolhimento deve ter 44 ou 48 caracteres. |
| 403 | BIP000010 | Forbidden | User is not allowed to do this action | Usuário não tem autorização para fazer essa ação |
| 404 | BIP000011 | Not Found | The source account key was not found. | A chave da conta de origem não foi encontrada. |
| 400 | BIP000012 | Bad Request | It 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. |
| 400 | BIP000013 | Bad Request | The source account is closed. | A conta de origem está fechada. |
| 400 | BIP000014 | Bad Request | The source account is blocked. | A conta de origem está bloqueada. |
| 400 | BIP000023 | Bad Request | The source account has insufficient balance. Payment cannot be made. | A conta de origem possui saldo insuficiente. Pagamento não pode ser realizado. |
| 400 | BIP000024 | Bad Request | Request control key already exists. | Chave de controle da requisição já existe. |
| 400 | BIP000028 | Bad Request | The source account has blocked balance. Payment cannot be made. | A conta de origem possui saldo em conta bloqueado. Pagamento não pode ser realizado. |
| 400 | BIP000034 | Bad Request | Collection slip already paid. | Fatura de recolhimento já paga. |
| 400 | BIP000035 | Bad Request | Covenant slip invalid barcode. | Código de barras da fatura de recolhimento inválido. |
| 400 | BIP000036 | Bad Request | Covenant slip overdue. | Fatura de recolhimento vencida. |
| 400 | BIP000037 | Bad Request | Error in collection slip consultation. | Erro na consulta da fatura de recolhimento. |
| 400 | BIP000038 | Bad Request | Outside of covenant payment hours. | Fora do horário de pagamento do convênio. |
| 400 | BIP000039 | Bad Request | Collection slip not accepted. | Fatura de recolhimento não aceita. |
| 400 | BIP000040 | Bad Request | Minimum advance not reached. | Mínimo de dias de adiantamento não atingido. |
| 400 | BIP000041 | Bad Request | Max payment amount exceeded. | Valor máximo de pagamento excedido. |
| 400 | BIP000044 | Bad Request | It was not possible to pay the collection slip at this time. Please verify your information and, if necessary, contact us for assistance. | Não foi possível pagar a fatura de recolhimento neste momento. Por favor, verifique suas informações e, se necessário, entre em contato conosco para assistência. |
| 400 | BIP000045 | Bad Request | Collection slip payment service is closed. | Serviço de pagamento de fatura de recolhimento está fechado. |
## Sandbox Environment
In our sandbox environment, we provide mocked digitable lines for simulating successful payments and testing error scenarios.
### Success Scenarios
| Digitable Line |
|---|
| 828300000007411100972013905080001546763201900028 |
| 838000000009235700481007241345219112001474229880 |
| 848000000006308600802021201071261517689002201070 |
| 858200000015000000643025703477209504800448091020 |
### Error Scenarios
| Digitable Line | Error Code |
|---|---|
| 858500000037350000643217212883260006147448091022 | BIP000035 |
---
# Scenario Simulation
URL: /en/documentation/baas/cobranca/simulacao_de_cenarios
## 1 - Simulating Payment in Pending Execution State
For payments where QI does not receive a response from CIP within two minutes, the payment will be returned with the status `pending_execution`. After QI receives the response from CIP, the pending payment webhook described on the [webhooks page](/documentation/baas/cobranca/webhooks) will be sent to the client. To simulate this scenario, make a payment with the digitable line `"digitable_line": "75691333790100505390300569460017397220000306867"`.
To update the payment status, make the request below with `payment_status` as **approved** to approve the payment, or **rejected** to reject it.
## Request
### Request Endpoint
ENDPOINT /mock/account/ ACCOUNT_KEY /payment/ PAYMENT_KEY /bank_slip/confirmation
MÉTODO PATCH
### Request Path Params
| Field | Type | Description | Characters |
|---------------------|---------|-----------------------------------------|------------|
| `account_key` * | uuid4 | Unique account identification key. | 36 |
| `payment_key` * | uuid4 | Unique payment identification key. | 36 |
Request Body: Simulating payment confirmation
```json
{
"payment_status": "approved",
}
```
### Body Parameters
| Field | Type | Description |
|-----------------------------|--------|-----------------------------------------------------------------------|
| `payment_status` * | [enum](#enumerators-payment_status) | Payment status |
### Enumerators payment_status
| Enumerator | Description |
|--------------|-----------|
| `approved` | Approve and complete the payment |
| `rejected` | Reject and revert the payment |
## Response
### Success Response
STATUS 204
Response Body: Simulation completed
```json
{}
```
---
# Solicitar Pagamento em Lote de Boleto Bancário
URL: /en/documentation/baas/cobranca/solicitar_pagamento_lote_de_boleto_bancario_com_confirmacao_de_lote
Este endpoint permite solicitar o pagamento de múltiplos boletos bancários em uma única requisição.
:::info Boleto bancário
É o boleto bancário convencional (linhas digitáveis não iniciadas com dígito 8). Possui registro na Câmara Interbancária de Pagamento (CIP/Núclea) e pode ser pago em instituições financeiras e de pagamento autorizadas a funcionar pelo Banco Central.
:::
:::info Fluxo após a solicitação
Após a solicitação, o lote pode permanecer aguardando a [confirmação do lote](./confirmacao_de_lote_de_boleto_bancario.md), conforme as regras da operação.
:::
## Request
### Request Endpoint
ENDPOINT /bill_payment/account/ ACCOUNT_KEY /payments/batch_bank_slip
MÉTODO POST
### Request Path Params
| Campo | Tipo | Descrição | Caracteres |
|---------------------|---------|-----------------------------------------|------------|
| `account_key` * | uuid4 | Chave única de identificação da conta. | 36 |
Request Body: Pagamento em lote de boletos bancários
```json
{
"request_control_key": "b6804f32-101e-4702-8fbc-c2dbc4c2caec",
"bank_slip_payments": [
{
"request_control_key": "c7915a43-212f-5813-9adc-d3ed5d3d3bfd",
"digitable_line": "00190000090361557400500000024174396700000991000",
"payment_amount": 1156.8
},
{
"request_control_key": "d8a26b54-323a-4924-0aed-e4fe6e4e4c0e",
"barcode": "00190000090361557400500000024174396700000991000",
"payment_amount": 200.5
}
]
}
```
### Body Params
| Campo | Tipo | Descrição |
|---------------------|---------------|-----------------------------------|
| `request_control_key` * | uuid4 | Chave única de identificação da requisição do cliente (lote). |
| `bank_slip_payments` * | array | Lista de pagamentos de boleto bancário. Limite de **1000** itens por requisição. |
Cada elemento de `bank_slip_payments` deve conter:
| Campo | Tipo | Descrição |
|---------------------|---------------|-----------------------------------|
| `request_control_key` * | uuid4 | Chave única de identificação da requisição do cliente para aquele item do lote. |
| `barcode` | string | Código de barras. |
| `digitable_line` | string | Linha digitável. |
| `payment_amount` * | number | Valor a ser pago. |
:::danger Aviso
Para cada item, o `payment_amount` enviado deve ser compatível com o que a consulta interna do boleto determinar: se o pagamento parcial **não** for permitido para aquele título, o valor deve corresponder ao total atualizado; se for permitido, o `payment_amount` pode seguir as regras do título (incluindo, quando aplicável, valores acima do nominal), como no fluxo de pagamento unitário de boleto bancário.
:::
## Response
### Success Response
STATUS 202
Response Body: Lote aceito para processamento
```json
{
"batch_payment_key": "a3214093-e51c-55e2-b5d3-60244475b3fb",
"request_control_key": "b6804f32-101e-4702-8fbc-c2dbc4c2caec",
"account_key": "6dc89d57-fac7-4643-b151-cd2ca0a7f68f",
"total_amount": 1357.3,
"batch_status": "pending",
"payment_type": "bank_slip"
}
```
Response Body: exemplo ilustrativo (`batch_status` aprovado)
```json
{
"batch_payment_key": "a3214093-e51c-55e2-b5d3-60244475b3fb",
"request_control_key": "b6804f32-101e-4702-8fbc-c2dbc4c2caec",
"account_key": "6dc89d57-fac7-4643-b151-cd2ca0a7f68f",
"total_amount": 1357.3,
"batch_status": "approved",
"payment_type": "bank_slip"
}
```
:::info Processamento do lote
O campo `batch_status` na resposta indica o **estado imediato** do lote após esta solicitação (por exemplo, pendente de confirmação ou já encaminhado ao processamento), conforme o fluxo aplicável. Quando houver etapa de [confirmação do lote](./confirmacao_de_lote_de_boleto_bancario.md), utilize essa chamada para aprovar ou rejeitar o lote antes do débito dos títulos. Os valores possíveis de `batch_status` estão em [batch_payment_status](#enumeradores-batch_payment_status).
:::
### Response Body Params
| Campo | Tipo | Descrição |
|---------------------|---------|-----------------------------------|
| `batch_payment_key` * | uuid4 | Chave única de identificação do pagamento em lote. |
| `request_control_key` * | uuid4 | Chave única de identificação da requisição do cliente (lote). |
| `account_key` * | uuid4 | Chave da conta debitada. |
| `total_amount` * | number | Soma dos valores (`payment_amount`) dos itens do lote. |
| `batch_status` * | [enum](#enumeradores-batch_payment_status) | Status do lote logo após a solicitação; depende do fluxo (confirmação e processamento imediato). |
| `payment_type` * | [enum](#enumeradores-payment_type) | Tipo do pagamento. |
### Enumeradores batch_payment_status
| Enumerador | Descrição |
|---------------|---------------|
| `pending` | Pendente de processamento |
| `pending_2fa_approval` | Pendente de aprovação 2FA |
| `rejected` | Rejeitado |
| `approved` | Aprovado |
| `processed` | Processado |
### Enumeradores payment_type
| Enumerador | Tipo | Descrição |
|---------------|-----------|---------------|
| `bank_slip` | string | Boleto bancário |
| `collection_slip` | string | Fatura de recolhimento |
:::danger Aviso
O enumerador `collection_slip` não se aplica ao fluxo de lote de boletos bancários deste endpoint; para este caso, espera-se `payment_type` com valor `bank_slip`.
:::
### Error Response
STATUS 4XX
Response Body
```json
{
"title": "Título",
"description": "Description in english",
"translation": "Descrição em português",
"code": "Código"
}
```
| Código HTTP | Código QI | Título | Descrição (eng) | Descrição (pt-br) |
|-------------|-----------|--------|------------------|------------------|
| 403 | BIP000010 | Forbidden | User is not allowed to do this action | Usuário não tem autorização para fazer essa ação |
| 404 | BIP000011 | Not Found | The source account key was not found. | A chave da conta de origem não foi encontrada. |
| 400 | BIP000012 | Bad Request | It 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. |
| 400 | BIP000024 | Bad Request | Request control key already exists. | Chave de controle da requisição já existe. |
| 400 | BIP000050 | Bad Request | Requester configuration does not exist. | Configuração do requester não existe. |
| 400 | BIP000080 | Bad Request | Beneficiary bank code of this bank slip is not allowed. | Banco beneficiário desse boleto não é permitido. |
| 400 | BIP000081 | Bad Request | A list of bank slip payments must be provided. | Uma lista de boletos bancários deve ser fornecida. |
---
# Solicitar Pagamento em Lote de Boleto Bancário
URL: /en/documentation/baas/cobranca/solicitar_pagamento_lote_de_boleto_bancario_sem_confirmacao_de_lote
Este endpoint permite solicitar o pagamento de múltiplos boletos bancários em uma única requisição.
:::info Boleto bancário
É o boleto bancário convencional (linhas digitáveis não iniciadas com dígito 8). Possui registro na Câmara Interbancária de Pagamento (CIP/Núclea) e pode ser pago em instituições financeiras e de pagamento autorizadas a funcionar pelo Banco Central.
:::
:::info Fluxo após a solicitação
Após a solicitação, o lote é encaminhado conforme o processamento definido para a operação. O campo `batch_status` reflete o estado imediato (por exemplo, pendente de processamento ou já em fila de débito). Os valores possíveis estão em [batch_payment_status](#enumeradores-batch_payment_status).
:::
## Request
### Request Endpoint
ENDPOINT /bill_payment/account/ ACCOUNT_KEY /payments/batch_bank_slip
MÉTODO POST
### Request Path Params
| Campo | Tipo | Descrição | Caracteres |
|---------------------|---------|-----------------------------------------|------------|
| `account_key` * | uuid4 | Chave única de identificação da conta. | 36 |
Request Body: Pagamento em lote de boletos bancários
```json
{
"request_control_key": "b6804f32-101e-4702-8fbc-c2dbc4c2caec",
"bank_slip_payments": [
{
"request_control_key": "c7915a43-212f-5813-9adc-d3ed5d3d3bfd",
"digitable_line": "00190000090361557400500000024174396700000991000",
"payment_amount": 1156.8
},
{
"request_control_key": "d8a26b54-323a-4924-0aed-e4fe6e4e4c0e",
"barcode": "00190000090361557400500000024174396700000991000",
"payment_amount": 200.5
}
]
}
```
### Body Params
| Campo | Tipo | Descrição |
|---------------------|---------------|-----------------------------------|
| `request_control_key` * | uuid4 | Chave única de identificação da requisição do cliente (lote). |
| `bank_slip_payments` * | array | Lista de pagamentos de boleto bancário. Limite de **1000** itens por requisição. |
Cada elemento de `bank_slip_payments` deve conter:
| Campo | Tipo | Descrição |
|---------------------|---------------|-----------------------------------|
| `request_control_key` * | uuid4 | Chave única de identificação da requisição do cliente para aquele item do lote. |
| `barcode` | string | Código de barras. |
| `digitable_line` | string | Linha digitável. |
| `payment_amount` * | number | Valor a ser pago. |
:::danger Aviso
Para cada item, o `payment_amount` enviado deve ser compatível com o que a consulta interna do boleto determinar: se o pagamento parcial **não** for permitido para aquele título, o valor deve corresponder ao total atualizado; se for permitido, o `payment_amount` pode seguir as regras do título (incluindo, quando aplicável, valores acima do nominal), como no fluxo de pagamento unitário de boleto bancário.
:::
## Response
### Success Response
STATUS 202
Response Body: Lote aceito para processamento
```json
{
"batch_payment_key": "a3214093-e51c-55e2-b5d3-60244475b3fb",
"request_control_key": "b6804f32-101e-4702-8fbc-c2dbc4c2caec",
"account_key": "6dc89d57-fac7-4643-b151-cd2ca0a7f68f",
"total_amount": 1357.3,
"batch_status": "pending",
"payment_type": "bank_slip"
}
```
Response Body: exemplo ilustrativo com `batch_status` aprovado
```json
{
"batch_payment_key": "a3214093-e51c-55e2-b5d3-60244475b3fb",
"request_control_key": "b6804f32-101e-4702-8fbc-c2dbc4c2caec",
"account_key": "6dc89d57-fac7-4643-b151-cd2ca0a7f68f",
"total_amount": 1357.3,
"batch_status": "approved",
"payment_type": "bank_slip"
}
```
:::info Processamento do lote
O campo `batch_status` na resposta indica o **estado imediato** do lote após esta solicitação (por exemplo, pendente de processamento ou já encaminhado ao processamento dos títulos), conforme o fluxo aplicável. Os valores possíveis de `batch_status` estão em [batch_payment_status](#enumeradores-batch_payment_status).
:::
### Response Body Params
| Campo | Tipo | Descrição |
|---------------------|---------|-----------------------------------|
| `batch_payment_key` * | uuid4 | Chave única de identificação do pagamento em lote. |
| `request_control_key` * | uuid4 | Chave única de identificação da requisição do cliente (lote). |
| `account_key` * | uuid4 | Chave da conta debitada. |
| `total_amount` * | number | Soma dos valores (`payment_amount`) dos itens do lote. |
| `batch_status` * | [enum](#enumeradores-batch_payment_status) | Status do lote logo após a solicitação; depende do processamento imediato e das regras da operação. |
| `payment_type` * | [enum](#enumeradores-payment_type) | Tipo do pagamento. |
### Enumeradores batch_payment_status
| Enumerador | Descrição |
|---------------|---------------|
| `pending` | Pendente de processamento |
| `pending_2fa_approval` | Pendente de aprovação 2FA |
| `rejected` | Rejeitado |
| `approved` | Aprovado |
| `processed` | Processado |
### Enumeradores payment_type
| Enumerador | Tipo | Descrição |
|---------------|-----------|---------------|
| `bank_slip` | string | Boleto bancário |
| `collection_slip` | string | Fatura de recolhimento |
:::danger Aviso
O enumerador `collection_slip` não se aplica ao fluxo de lote de boletos bancários deste endpoint; para este caso, espera-se `payment_type` com valor `bank_slip`.
:::
### Error Response
STATUS 4XX
Response Body
```json
{
"title": "Título",
"description": "Description in english",
"translation": "Descrição em português",
"code": "Código"
}
```
| Código HTTP | Código QI | Título | Descrição (eng) | Descrição (pt-br) |
|-------------|-----------|--------|------------------|------------------|
| 403 | BIP000010 | Forbidden | User is not allowed to do this action | Usuário não tem autorização para fazer essa ação |
| 404 | BIP000011 | Not Found | The source account key was not found. | A chave da conta de origem não foi encontrada. |
| 400 | BIP000012 | Bad Request | It 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. |
| 400 | BIP000024 | Bad Request | Request control key already exists. | Chave de controle da requisição já existe. |
| 400 | BIP000050 | Bad Request | Requester configuration does not exist. | Configuração do requester não existe. |
| 400 | BIP000080 | Bad Request | Beneficiary bank code of this bank slip is not allowed. | Banco beneficiário desse boleto não é permitido. |
| 400 | BIP000081 | Bad Request | A list of bank slip payments must be provided. | Uma lista de boletos bancários deve ser fornecida. |
---
# Solicitar Pagamento em Lote de Fatura de Recolhimento (convênio/tributo)
URL: /en/documentation/baas/cobranca/solicitar_pagamento_lote_de_fatura_de_recolhimento_com_confirmacao_de_lote
Este endpoint permite solicitar o pagamento de múltiplas faturas de recolhimento em uma única requisição.
:::info Fatura de recolhimento
Esse tipo de cobrança é emitido por concessionárias de serviços (conta de água, luz, telefone e gás) e órgãos públicos (tributos). Eles não são registrados na Câmara Interbancária de Pagamento (CIP/Núclea), por isso, não retornam as mesmas informações que um boleto bancário apresenta.
:::
:::info Fluxo após a solicitação
Após a solicitação, o lote pode permanecer aguardando a [confirmação do lote](./confirmacao_de_lote_de_fatura_de_recolhimento.md), conforme as regras da operação.
:::
## Request
### Request Endpoint
ENDPOINT /bill_payment/account/ ACCOUNT_KEY /payments/batch_collection_slip
MÉTODO POST
### Request Path Params
| Campo | Tipo | Descrição | Caracteres |
|---------------------|---------|-----------------------------------------|------------|
| `account_key` * | uuid4 | Chave única de identificação da conta. | 36 |
Request Body: Pagamento em lote de faturas de recolhimento
```json
{
"request_control_key": "b6804f32-101e-4702-8fbc-c2dbc4c2caec",
"collection_slip_payments": [
{
"request_control_key": "c7915a43-212f-5813-9adc-d3ed5d3d3bfd",
"digitable_line": "836200000138892100450006762142420244046000010192",
"payment_amount": 1389.21
},
{
"request_control_key": "d8a26b54-323a-4924-0aed-e4fe6e4e4c0e",
"barcode": "83620000001388921004500067621424202440460000101",
"payment_amount": 1389.21
}
]
}
```
### Body Params
| Campo | Tipo | Descrição |
|---------------------|---------------|-----------------------------------|
| `request_control_key` * | uuid4 | Chave única de identificação da requisição do cliente (lote). |
| `collection_slip_payments` * | array | Lista de pagamentos de fatura de recolhimento. Limite de **1000** itens por requisição. |
Cada elemento de `collection_slip_payments` deve conter:
| Campo | Tipo | Descrição |
|---------------------|---------------|-----------------------------------|
| `request_control_key` * | uuid4 | Chave única de identificação da requisição do cliente para aquele item do lote. |
| `barcode` | string | Código de barras. |
| `digitable_line` | string | Linha digitável. |
| `payment_amount` * | number | Valor a ser pago. |
:::danger Aviso
Para cada item, o `payment_amount` enviado deve ser compatível com o que a consulta interna da fatura de recolhimento determinar (por exemplo, alinhado ao `total_amount` e às regras do convênio/tributo), nas mesmas condições do fluxo de pagamento unitário de fatura de recolhimento.
:::
## Response
### Success Response
STATUS 202
Response Body: Lote aceito para processamento
```json
{
"batch_payment_key": "a3214093-e51c-55e2-b5d3-60244475b3fb",
"request_control_key": "b6804f32-101e-4702-8fbc-c2dbc4c2caec",
"account_key": "daae79e6-ee8b-449f-aa1e-96959d5d5a72",
"total_amount": 2778.42,
"batch_status": "pending",
"payment_type": "collection_slip"
}
```
Response Body: exemplo ilustrativo (`batch_status` aprovado)
```json
{
"batch_payment_key": "a3214093-e51c-55e2-b5d3-60244475b3fb",
"request_control_key": "b6804f32-101e-4702-8fbc-c2dbc4c2caec",
"account_key": "daae79e6-ee8b-449f-aa1e-96959d5d5a72",
"total_amount": 2778.42,
"batch_status": "approved",
"payment_type": "collection_slip"
}
```
:::info Processamento do lote
O campo `batch_status` na resposta indica o **estado imediato** do lote após esta solicitação (por exemplo, pendente de confirmação ou já encaminhado ao processamento), conforme o fluxo aplicável. Quando houver etapa de [confirmação do lote](./confirmacao_de_lote_de_fatura_de_recolhimento.md), utilize essa chamada para aprovar ou rejeitar o lote antes do débito dos títulos. Os valores possíveis de `batch_status` estão em [batch_payment_status](#enumeradores-batch_payment_status).
:::
### Response Body Params
| Campo | Tipo | Descrição |
|---------------------|---------|-----------------------------------|
| `batch_payment_key` * | uuid4 | Chave única de identificação do pagamento em lote. |
| `request_control_key` * | uuid4 | Chave única de identificação da requisição do cliente (lote). |
| `account_key` * | uuid4 | Chave da conta debitada. |
| `total_amount` * | number | Soma dos valores (`payment_amount`) dos itens do lote. |
| `batch_status` * | [enum](#enumeradores-batch_payment_status) | Status do lote logo após a solicitação; depende do fluxo (confirmação e processamento imediato). |
| `payment_type` * | [enum](#enumeradores-payment_type) | Tipo do pagamento. |
### Enumeradores batch_payment_status
| Enumerador | Descrição |
|---------------|---------------|
| `pending` | Pendente de processamento |
| `pending_2fa_approval` | Pendente de aprovação 2FA |
| `rejected` | Rejeitado |
| `approved` | Aprovado |
| `processed` | Processado |
### Enumeradores payment_type
| Enumerador | Tipo | Descrição |
|---------------|-----------|---------------|
| `bank_slip` | string | Boleto bancário |
| `collection_slip` | string | Fatura de recolhimento |
:::danger Aviso
O enumerador `bank_slip` não se aplica ao fluxo de lote de faturas de recolhimento deste endpoint; para este caso, espera-se `payment_type` com valor `collection_slip`.
:::
### Error Response
STATUS 4XX
Response Body
```json
{
"title": "Título",
"description": "Description in english",
"translation": "Descrição em português",
"code": "Código"
}
```
| Código HTTP | Código QI | Título | Descrição (eng) | Descrição (pt-br) |
|-------------|-----------|--------|------------------|------------------|
| 400 | BIP000024 | Bad Request | Request control key already exists. | Chave de controle da requisição já existe. |
| 400 | BIP000050 | Bad Request | Requester configuration does not exist. | Configuração do requester não existe. |
| 400 | BIP000082 | Bad Request | A list of collection slip payments must be provided. | Uma lista de faturas de recolhimento deve ser fornecida. |
---
# Solicitar Pagamento em Lote de Fatura de Recolhimento (convênio/tributo)
URL: /en/documentation/baas/cobranca/solicitar_pagamento_lote_de_fatura_de_recolhimento_sem_confirmacao_de_lote
Este endpoint permite solicitar o pagamento de múltiplas faturas de recolhimento em uma única requisição.
:::info Fatura de recolhimento
Esse tipo de cobrança é emitido por concessionárias de serviços (conta de água, luz, telefone e gás) e órgãos públicos (tributos). Eles não são registrados na Câmara Interbancária de Pagamento (CIP/Núclea), por isso, não retornam as mesmas informações que um boleto bancário apresenta.
:::
:::info Fluxo após a solicitação
Após a solicitação, o lote é encaminhado conforme o processamento definido para a operação. O campo `batch_status` reflete o estado imediato (por exemplo, pendente de processamento ou já em fila de débito). Os valores possíveis estão em [batch_payment_status](#enumeradores-batch_payment_status).
:::
## Request
### Request Endpoint
ENDPOINT /bill_payment/account/ ACCOUNT_KEY /payments/batch_collection_slip
MÉTODO POST
### Request Path Params
| Campo | Tipo | Descrição | Caracteres |
|---------------------|---------|-----------------------------------------|------------|
| `account_key` * | uuid4 | Chave única de identificação da conta. | 36 |
Request Body: Pagamento em lote de faturas de recolhimento
```json
{
"request_control_key": "b6804f32-101e-4702-8fbc-c2dbc4c2caec",
"collection_slip_payments": [
{
"request_control_key": "c7915a43-212f-5813-9adc-d3ed5d3d3bfd",
"digitable_line": "836200000138892100450006762142420244046000010192",
"payment_amount": 1389.21
},
{
"request_control_key": "d8a26b54-323a-4924-0aed-e4fe6e4e4c0e",
"barcode": "83620000001388921004500067621424202440460000101",
"payment_amount": 1389.21
}
]
}
```
### Body Params
| Campo | Tipo | Descrição |
|---------------------|---------------|-----------------------------------|
| `request_control_key` * | uuid4 | Chave única de identificação da requisição do cliente (lote). |
| `collection_slip_payments` * | array | Lista de pagamentos de fatura de recolhimento. Limite de **1000** itens por requisição. |
Cada elemento de `collection_slip_payments` deve conter:
| Campo | Tipo | Descrição |
|---------------------|---------------|-----------------------------------|
| `request_control_key` * | uuid4 | Chave única de identificação da requisição do cliente para aquele item do lote. |
| `barcode` | string | Código de barras. |
| `digitable_line` | string | Linha digitável. |
| `payment_amount` * | number | Valor a ser pago. |
:::danger Aviso
Para cada item, o `payment_amount` enviado deve ser compatível com o que a consulta interna da fatura de recolhimento determinar (por exemplo, alinhado ao `total_amount` e às regras do convênio/tributo), nas mesmas condições do fluxo de pagamento unitário de fatura de recolhimento.
:::
## Response
### Success Response
STATUS 202
Response Body: Lote aceito para processamento
```json
{
"batch_payment_key": "a3214093-e51c-55e2-b5d3-60244475b3fb",
"request_control_key": "b6804f32-101e-4702-8fbc-c2dbc4c2caec",
"account_key": "daae79e6-ee8b-449f-aa1e-96959d5d5a72",
"total_amount": 2778.42,
"batch_status": "pending",
"payment_type": "collection_slip"
}
```
Response Body: exemplo ilustrativo com `batch_status` aprovado
```json
{
"batch_payment_key": "a3214093-e51c-55e2-b5d3-60244475b3fb",
"request_control_key": "b6804f32-101e-4702-8fbc-c2dbc4c2caec",
"account_key": "daae79e6-ee8b-449f-aa1e-96959d5d5a72",
"total_amount": 2778.42,
"batch_status": "approved",
"payment_type": "collection_slip"
}
```
:::info Processamento do lote
O campo `batch_status` na resposta indica o **estado imediato** do lote após esta solicitação (por exemplo, pendente de processamento ou já encaminhado ao processamento dos títulos), conforme o fluxo aplicável. Os valores possíveis de `batch_status` estão em [batch_payment_status](#enumeradores-batch_payment_status).
:::
### Response Body Params
| Campo | Tipo | Descrição |
|---------------------|---------|-----------------------------------|
| `batch_payment_key` * | uuid4 | Chave única de identificação do pagamento em lote. |
| `request_control_key` * | uuid4 | Chave única de identificação da requisição do cliente (lote). |
| `account_key` * | uuid4 | Chave da conta debitada. |
| `total_amount` * | number | Soma dos valores (`payment_amount`) dos itens do lote. |
| `batch_status` * | [enum](#enumeradores-batch_payment_status) | Status do lote logo após a solicitação; depende do processamento imediato e das regras da operação. |
| `payment_type` * | [enum](#enumeradores-payment_type) | Tipo do pagamento. |
### Enumeradores batch_payment_status
| Enumerador | Descrição |
|---------------|---------------|
| `pending` | Pendente de processamento |
| `pending_2fa_approval` | Pendente de aprovação 2FA |
| `rejected` | Rejeitado |
| `approved` | Aprovado |
| `processed` | Processado |
### Enumeradores payment_type
| Enumerador | Tipo | Descrição |
|---------------|-----------|---------------|
| `bank_slip` | string | Boleto bancário |
| `collection_slip` | string | Fatura de recolhimento |
:::danger Aviso
O enumerador `bank_slip` não se aplica ao fluxo de lote de faturas de recolhimento deste endpoint; para este caso, espera-se `payment_type` com valor `collection_slip`.
:::
### Error Response
STATUS 4XX
Response Body
```json
{
"title": "Título",
"description": "Description in english",
"translation": "Descrição em português",
"code": "Código"
}
```
| Código HTTP | Código QI | Título | Descrição (eng) | Descrição (pt-br) |
|-------------|-----------|--------|------------------|------------------|
| 400 | BIP000024 | Bad Request | Request control key already exists. | Chave de controle da requisição já existe. |
| 400 | BIP000050 | Bad Request | Requester configuration does not exist. | Configuração do requester não existe. |
| 400 | BIP000082 | Bad Request | A list of collection slip payments must be provided. | Uma lista de faturas de recolhimento deve ser fornecida. |
---
# Webhooks
URL: /en/documentation/baas/cobranca/webhooks
:::danger Warning!
QI Tech webhooks should not be mapped in a restrictive manner.
Additional fields may be included in the payloads of the webhooks returned by our APIs.
:::
## Webhook for Pending Payments
Webhook intended to update the status of payments that were pending (status 202) when making a boleto payment.
### Webhook Request Body
Request Body: Payment executed
```json
{
"webhook_type": "baas.bill_payment.payment",
"webhook_datetime": "2021-10-22T20:30:23.459Z",
"data": {
"payment_key": "8cb70dea-9fb0-4a68-9572-99a72849c8d6",
"request_control_key": "b6804f32-101e-4702-8fbc-c2dbc4c2caec",
"barcode":"00193967000009910000000003615574000000002417",
"digitable_line":"00190000090361557400500000024174396700000991000",
"payment_status": "executed",
"payment_type":"bank_slip"
}
}
```
Request Body: Payment reverted
```json
{
"webhook_type": "baas.bill_payment.payment",
"webhook_datetime": "2021-10-22T20:30:23.459Z",
"data": {
"payment_key": "8cb70dea-9fb0-4a68-9572-99a72849c8d6",
"request_control_key": "b6804f32-101e-4702-8fbc-c2dbc4c2caec",
"barcode":"81620000000000336592028110120200020214942099",
"digitable_line":"816200000007000336592027811012020004202149420996",
"payment_status": "reverted",
"payment_type":"collection_slip"
}
}
```
### Webhook Body Params
| Field | Type | Description |
|-----------------------|--------|-----------------------------------------------------------|
| `webhook_type` | string | An enumerator that defines the type of event being reported. |
| `webhook_datetime` | string | Date and time the webhook was sent. |
| `request_control_key` | uuid4 | Unique identification key for the client's request. |
| `payment_key` * | uuid4 | Unique payment identification key. |
| `barcode` * | string | Barcode. |
| `digitable_line` * | string | Digitable line. |
| `payment_type` * | [enum](#enumerators-payment_type) | Payment type. |
| `payment_status` * | [enum](#enumerators-payment_status) | Payment status. |
### Enumerators payment_type
| Enumerator | Type | Description |
|---------------|-----------|---------------|
| `bank_slip` | string | Boleto |
| `collection_slip` | string | Collection invoice |
### Enumerators payment_status
| Enumerator | Type | Description |
|---------------|-----------|---------------|
| `executed` | string | Executed |
| `reverted` | string | Reverted |
---
# Query device
URL: /en/documentation/baas/dispositivo/consultar_dispositivo
## Request
ENDPOINT /account/ ACCOUNT_KEY /device/ DEVICE_KEY
METHOD GET
### Path Params
| Field | Type | Description | Characters |
|---------------|--------|----------------------------------------|------------|
| `account_key` | uuidv4 | Unique account identification key. | 36 |
| `device_key` | uuidv4 | Unique device identification key. | 36 |
## Response
STATUS 200
Response Body: Device found
```json
{
"device_key": "b6804f32-101e-4702-8fbc-c2dbc4c2caec",
"session_id": "05894BAD-C94E-4A61-B2A8-57EDAE868A0F",
"analysis_status": "automatically_approved",
"status": "registered",
"device_registration_data": {
"device_key": "b6804f32-101e-4702-8fbc-c2dbc4c2caec",
"session_id": "05894BAD-C94E-4A61-B2A8-57EDAE868A0F",
"document_number": "438.858.048-16",
"registration_date": "2025-06-30T14:52:13-03:00",
"face_recognition_key": "367195fc-de24-46b0-9ddb-79231dc7eeff"
},
"analysis_status_events": [
{
"new_analisys_status": "automatically_approved",
"reason": null,
"reason_description": null,
"event_date": "2025-06-30T14:52:13Z"
}
],
"status_events": [
{
"new_status": "registered",
"event_date": "2025-06-30T14:52:13Z"
}
],
"registration_date": "2025-06-30T14:52:14Z",
"created_at": "2025-06-30T14:52:13Z"
}
```
### Response Body Params
| Field | Type | Description | Characters |
|-------------------------|--------|-------------------------------------------------------------------------------------|------------|
| `device_key` * | uuidv4 | Unique device identification key in uuid v4 format | 36 |
| `session_id` * | uuidv4 | Session identifier obtained via device_scan | 36 |
| `analysis_status` * | string | Fraud engine analysis status | **[analysis_status Enumerators](#analysis_status-enumerators)** |
| `status` * | string | Device status | **[status Enumerators](#status-enumerators)** |
| `device_registration_data` * | object | Device registration data | **[device_registration_data Object](#device_registration_data-object)** |
| `analysis_status_events` * | array | History of analysis status change events | - |
| `status_events` * | array | History of device status change events | - |
| `registration_date` * | string | Device registration date in ISO format (UTC - "YYYY-MM-DDTHH:MM:SSZ") | 20 |
| `created_at` * | string | Device creation date in ISO format (UTC - "YYYY-MM-DDTHH:MM:SSZ") | 20 |
### device_registration_data Object
| Field | Type | Description | Characters |
|-------------------------|--------|-------------------------------------------------------------------------------------|------------|
| `device_key` * | uuidv4 | Unique device identification key in uuid v4 format | 36 |
| `session_id` * | uuidv4 | Session identifier obtained via device_scan | 36 |
| `document_number` | string | User's document number (CPF/CNPJ) | 14 |
| `registration_date` * | string | Registration date in ISO format with timezone | 25 |
| `face_recognition_key` | uuidv4 | Face recognition key (when applicable) | 36 |
### analysis_status_event Object
| Field | Type | Description | Characters |
|-------------------------|--------|-------------------------------------------------------------------------------------|------------|
| `new_analisys_status` * | string | New analysis status | **[analysis_status Enumerators](#analysis_status-enumerators)** |
| `reason` | string | Reason for status change (when applicable) | - |
| `reason_description` | string | Description of the reason for status change (when applicable) | - |
| `event_date` * | string | Event date in ISO format (UTC - "YYYY-MM-DDTHH:MM:SSZ") | 20 |
### status_event Object
| Field | Type | Description | Characters |
|-------------------------|--------|-------------------------------------------------------------------------------------|------------|
| `new_status` * | string | New device status | **[status Enumerators](#status-enumerators)** |
| `event_date` * | string | Event date in ISO format (UTC - "YYYY-MM-DDTHH:MM:SSZ") | 20 |
### analysis_status Enumerators
| Enumerator | Description |
|-------------------------|-----------------------------------------|
| automatically_approved | Automatically approved by fraud engine |
| automatically_reproved | Automatically rejected by fraud engine |
| pending | Pending analysis |
### status Enumerators
| Enumerator | Description |
|--------------------|-----------------------------------------|
| registered | Registered device |
| disabled | Disabled device |
| pending | Device pending approval |
STATUS 4xx
Response Body: Error
```json
{
"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 (ptbr) `translation` |
|--------------------------|----------------------|----------------------------------------------------|-------------------------------------------------------------------------------------------------------------------------|------------------------------------------------------------------------------------------------------------------------|
| 400 | QIT000001 | Bad Request | Schema Error | Erro de Schema |
| 404 | OBD000002 | Not Found | Bank account not found | Conta não encontrada |
| 404 | OBD000100 | Device not found | No device is associated with the provided device_key. | Nenhum dispositivo está associado à device_key fornecida. |
---
# Approve device creation
URL: /en/documentation/baas/dispositivo/create/aprovar_cadastro_dispositivo
## Request
ENDPOINT /account/ ACCOUNT_KEY /device/ DEVICE_KEY /validate
METHOD PUT
### Path Params
| Field | Type | Description | Characters |
|---------------|--------|----------------------------------------|------------|
| `account_key` | uuidv4 | Unique account identification key. | 36 |
| `device_key` | uuidv4 | Unique device identification key. | 36 |
Request Body
```json
{
"token": "329adf"
}
```
### Body Params
| Field | Type | Description | Characters |
|-----------|--------|-----------------------------------------------------------------------|------------|
| `token` * | string | Authentication code sent to the account transaction approver | 6 |
## Response
STATUS 201
Response Body: Device Created
```json
{
"device_key": "b6804f32-101e-4702-8fbc-c2dbc4c2caec",
"device_status": "created",
"created_at": "2024-12-22T20:30:23.459Z"
}
```
STATUS 4xx
Response Body: Error
```json
{
"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 (ptbr) `translation` |
|--------------------------|----------------------|----------------------------------------------------|-------------------------------------------------------------------------------------------------------------------------|------------------------------------------------------------------------------------------------------------------------|
| 400 | QIT000001 | Bad Request | Schema Error | Erro de Schema |
| 404 | OBD000002 | Not Found | Bank account not found | Conta não encontrada |
| 400 | OBD000088 | Bad Request | Account blocked or closed can not perform this action | A conta bloqueada ou fechada não pode executar esta ação |
| 400 | OBD000089 | Bad Request | Hub account can not perform this action | A conta hub não pode executar esta ação |
| 400 | OBD000099 | Number of token validation attempts exceeded | The maximum number of failed token validation attempts has been reached | Número máximo de tentativas de validação de token atingida |
| 404 | OBD000100 | Device not found | No device is associated with the provided device_key. | Nenhum dispositivo está associado à device_key fornecida. |
| 400 | OBD0000100 | Incorrect Token | Token sent does not match expected | Token enviado não condiz com, o esperado |
---
# Request Device Creation
URL: /en/documentation/baas/dispositivo/create/solicitacao_cadastro_dispositivo
## Request
ENDPOINT /account/ ACCOUNT_KEY /device
METHOD POST
### Path Params
| Field | Type | Description | Characters |
|---------------|--------|----------------------------------------|------------|
| `account_key` | uuidv4 | Unique account identification key. | 36 |
**SMS**
Request Body: SMS Authentication
```json
{
"device_key": "b6804f32-101e-4702-8fbc-c2dbc4c2caec",
"session_id": "fae3cb6c-9012-4b1c-9d61-7e8b2a6a5ed2",
"tfa_info": {
"approver_document_number": "98765432100",
"contact_type": "sms",
},
}
```
### Body Params
| Field | Type | Description | Characters |
|-------------------------|------------|--------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|-----------------------------------------|
| `device_key` * | uuidv4 | Unique device identification key in uuid v4 format, obtained through **device_scan** (created at this moment by the integrating client). | 36 |
| `session_id` * | uuidv4 | Unique session identification key in uuid v4 format, obtained through **device_scan** (created at this moment by the integrating client). | 36 |
| `tfa_info`* | Object | Object containing the approver's document number and contact method or `image_key`. | **[tfa_info Object](#tfa_info-object)** |
### tfa_info Object
| Field | Type | Description | Characters |
|-----------------------------|--------|-------------------------------------------------------------------------------------|------------|
| `approver_document_number`* | string | Document number of the account approver. | 11 |
| `contact_type`* | string | Indicates the contact method with the person responsible for account approval. Possible values are **sms**, **email**, or **liveness** (when authentication is performed using image_key).| |
## Response
STATUS 202
Response Body: Transaction Requested
```json
{
"device_key": "b6804f32-101e-4702-8fbc-c2dbc4c2caec",
"device_status": "pending_2fa_approval",
"created_at": "2024-12-22T20:30:23.459Z"
}
```
**Email**
Request Body: Email Authentication
```json
{
"device_key": "b6804f32-101e-4702-8fbc-c2dbc4c2caec",
"session_id": "fae3cb6c-9012-4b1c-9d61-7e8b2a6a5ed2",
"tfa_info": {
"approver_document_number": "98765432100",
"contact_type": "email",
},
}
```
### Body Params
| Field | Type | Description | Characters |
|-------------------------|------------|---------------------------------------------------------------------------------------------------|-----------------------------------------------------|
| `device_key` * | uuidv4 | Unique device identification key in uuid v4 format, obtained through **device_scan** (created at this moment by the integrating client). | 36 |
| `session_id` * | uuidv4 | Unique session identification key in uuid v4 format, obtained through **device_scan** (created at this moment by the integrating client). | 36 |
| `tfa_info`* | Object | Object containing the approver's document number and contact method or `image_key`. | **[tfa_info Object](#tfa_info-object)** |
### tfa_info Object
| Field | Type | Description | Characters |
|-----------------------------|--------|-------------------------------------------------------------------------------------|------------|
| `approver_document_number`* | string | Document number of the account approver. | 11 |
| `contact_type`* | string | Indicates the contact method with the person responsible for account approval. Possible values are **sms**, **email**, or **liveness** (when authentication is performed using image_key).| |
## Response
STATUS 202
Response Body: Transaction Requested
```json
{
"device_key": "b6804f32-101e-4702-8fbc-c2dbc4c2caec",
"device_status": "pending_2fa_approval",
"created_at": "2024-12-22T20:30:23.459Z"
}
```
**Image Key**
Request Body: Image Key Authentication
```json
{
"device_key": "b6804f32-101e-4702-8fbc-c2dbc4c2caec",
"session_id": "fae3cb6c-9012-4b1c-9d61-7e8b2a6a5ed2",
"tfa_info": {
"approver_document_number": "98765432100",
"contact_type": "liveness",
"image_key": "367195fc-de24-46b0-9ddb-79231dc7eeff",
},
}
```
### Body Params
| Field | Type | Description | Characters |
|----------------------------|------------|---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|-------------------------------------------|
| `device_key` * | uuidv4 | Unique device identification key in uuid v4 format, obtained through **device_scan** (created at this moment by the integrating client). | 36 |
| `session_id` * | uuidv4 | Unique session identification key in uuid v4 format, obtained through **device_scan** (created at this moment by the integrating client). | 36 |
| `tfa_info`* | Object | Object containing the approver's document number and contact method or `image_key`. | **[tfa_info Object](#tfa_info-object)** |
### tfa_info Object
| Field | Type | Description | Characters |
|-----------------------------|--------|-------------------------------------------------------------------------------------|------------|
| `approver_document_number`* | string | Document number of the account approver. | 11 |
| `contact_type`* | string | Indicates the contact method with the person responsible for account approval. Possible values are **sms**, **email**, or **liveness** (when authentication is performed using image_key).| |
| `image_key` * | uuidv4 | Unique identification key of the image used for facial recognition, in UUID v4 format, obtained through the **liveness** process. | 36 |
## Response
STATUS 202
Response Body: Device Created
```json
{
"device_key": "b6804f32-101e-4702-8fbc-c2dbc4c2caec",
"device_status": "created",
"created_at": "2024-12-22T20:30:23.459Z"
}
```
STATUS 4xx
Response Body: Error
```json
{
"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 (ptbr) `translation` |
|--------------------------|----------------------|----------------------------------------------------|-------------------------------------------------------------------------------------------------------------------------|------------------------------------------------------------------------------------------------------------------------|
| 400 | QIT000001 | Bad Request | Schema Error | Erro de Schema |
| 404 | OBD000002 | Not Found | Bank account not found | Conta não encontrada |
| 400 | OBD000088 | Bad Request | Account blocked or closed can not perform this action | A conta bloqueada ou fechada não pode executar esta ação |
| 400 | OBD000089 | Bad Request | Hub account can not perform this action | A conta hub não pode executar esta ação |
| 403 | OBD000090 | No approver permission | Given document number does not belong to an approver for this account string | Número de documento enviado não pertence a um aprovador da conta |
| 400 | OBD000091 | tfa_info is required | Client must send object tfa_info | Cliente deve enviar objeto tfa_info. |
| 400 | OBD000092 | Invalid device info | Session ID and Device Key must be a valid UUID4 | A Session ID e o Device Key devem ser um UUID4 válidos |
| 404 | OBD000093 | Requester Configuration not found | There is no Requester Configuration attributed to requester_key | Não há Requester Configuration para a requester_key enviada |
| 403 | OBD000094 | Requester not allowed to create a device | Requester has no permission to create a device | Requester não possui permissão para criar um dispositivo |
| 400 | OBD000097 | Error occurred while sending token | An unexpected error occurred while sending token | Um erro inexperado ocorreu ao tentar enviar token |
---
# Request token resend
URL: /en/documentation/baas/dispositivo/create/solicitacao_reenvio_token
A new token will be generated and sent to the approver responsible for creating the device (only for email or SMS contact cases). If the token validation attempt limit is exceeded, resending will not be allowed.
## Request
ENDPOINT /account/ ACCOUNT_KEY /device/ DEVICE_KEY /resend_token
METHOD PATCH
### Path Params
| Field | Type | Description | Characters |
|---------------|--------|----------------------------------------|------------|
| `account_key` | uuidv4 | Unique account identification key. | 36 |
| `device_key` | uuidv4 | Unique device identification key. | 36 |
### Body Params
| Field | Type | Description | Characters |
|---------------|--------|----------------------------------------|------------|
| `contact_type`* | string | Indicates the contact method with the person responsible for account approval. Possible values are **sms**, **email**| **[contact_type Enumerator](#contact_type-enumerator)** |
:::info Information
If no `contact_type` is sent, the token will be sent in the originally requested format.
:::
| Enumerator | Description |
|------------|---------------------------------------------------|
| **sms** | Send via Text Message to mobile phone |
| **email** | Send via electronic mail |
## Response
STATUS 202
Response Body: Resend Requested
```json
{
"device_key": "b6804f32-101e-4702-8fbc-c2dbc4c2caec",
"device_status": "pending_2fa_approval",
"created_at": "2024-12-22T20:30:23.459Z"
}
```
STATUS 4xx
Response Body: Error
```json
{
"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 (ptbr) `translation` |
|--------------------------|----------------------|----------------------------------------------------|-------------------------------------------------------------------------------------------------------------------------|------------------------------------------------------------------------------------------------------------------------|
| 400 | QIT000001 | Bad Request | Schema Error | Erro de Schema |
| 404 | OBD000002 | Not Found | Bank account not found | Conta não encontrada |
| 400 | OBD000088 | Bad Request | Account blocked or closed can not perform this action | A conta bloqueada ou fechada não pode executar esta ação |
| 400 | OBD000089 | Bad Request | Hub account can not perform this action | A conta hub não pode executar esta ação |
| 400 | OBD000097 | Error occurred while sending token | An unexpected error occurred while sending token | Um erro inexperado ocorreu ao tentar enviar token |
| 400 | OBD000099 | Number of token validation attempts exceeded | The maximum number of failed token validation attempts has been reached | Número máximo de tentativas de validação de token atingida |
| 404 | OBD000100 | Device not found | No device is associated with the provided device_key. | Nenhum dispositivo está associado à device_key fornecida. |
---
# Disable device
URL: /en/documentation/baas/dispositivo/delete/desativar_dispositivo
## Request
ENDPOINT /account/ ACCOUNT_KEY /device/ DEVICE_KEY /disable
METHOD DELETE
### Path Params
| Field | Type | Description | Characters |
|---------------|--------|----------------------------------------|------------|
| `account_key` | uuidv4 | Unique account identification key. | 36 |
| `device_key` | uuidv4 | Unique device identification key. | 36 |
## Response
STATUS 200
Response Body: Device disabled
```json
{
"device_key": "b6804f32-101e-4702-8fbc-c2dbc4c2caec",
"device_status": "disabled",
"created_at": "2024-12-22T20:30:23.459Z"
}
```
### Response Body Params
| Field | Type | Description | Characters |
|-------------------------|--------|-------------------------------------------------------------------------------------|------------|
| `device_key` * | uuidv4 | Unique device identification key in uuid v4 format | 36 |
| `device_status` * | string | Device status | **[device_status Enumerators](#device_status-enumerators)** |
| `created_at` * | string | Device creation date in ISO format (UTC - "YYYY-MM-DDTHH:MM:SSZ") | 20 |
### device_status Enumerators
| Enumerator | Description |
|--------------------|-----------------------------------------|
| active | Device active and available for use |
| disabled | Device disabled |
| pending | Device pending approval |
STATUS 4xx
Response Body: Error
```json
{
"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 (ptbr) `translation` |
|--------------------------|----------------------|----------------------------------------------------|-------------------------------------------------------------------------------------------------------------------------|------------------------------------------------------------------------------------------------------------------------|
| 400 | QIT000001 | Bad Request | Schema Error | Erro de Schema |
| 404 | OBD000002 | Not Found | Bank account not found | Conta não encontrada |
| 400 | OBD000088 | Bad Request | Account blocked or closed can not perform this action | A conta bloqueada ou fechada não pode executar esta ação |
| 400 | OBD000089 | Bad Request | Hub account can not perform this action | A conta hub não pode executar esta ação |
| 404 | OBD000100 | Device not found | No device is associated with the provided device_key. | Nenhum dispositivo está associado à device_key fornecida. |
---
# Introduction
URL: /en/documentation/baas/dispositivo/introducao
The Onboarding API offers Device Management functionality, allowing partners to register specific devices to users linked to an account. With this functionality, it is possible to reinforce transaction security, ensuring that only authorized devices can perform transactions, which will be validated through the **device token**.
### Device Registration
The registration of a new device for transaction validation is performed through a flow divided into three steps:
---
**I. Registration Request (POST)**
In this step, a `POST` request is sent containing:
- Device data obtained via `device_scan`
- Information required for two-factor authentication (2FA)
Upon completing the request, a 2FA token is generated and sent to the user (by email or SMS). This token ensures that the registration is being performed by the person effectively authorized to link the device.
:::info Note
If authentication is performed through facial recognition, the **image_key** acquired through [liveness](/documentation/caas/face_recognition/api/introduction) must be sent in the 2FA field.
In this case, it will not be necessary to go through the next validation steps.
:::
---
**II. 2FA Token Validation (PUT/PATCH)**
After receiving the 2FA token, the user must validate it using a `PUT` request. If the code needs to be resent (due to loss, non-receipt, or expiration), a `PATCH` request is used to request a new token.
Once the token is successfully validated, the device will be effectively registered in the system.
---
**III. Authentication with Device Token in Future Transactions**
With the device properly registered, it can be used for validation of future transactions. Transactions will be authenticated using the device token, making the process more secure and reliable.
---
### Query a Device
It is possible to query information about a specific device through a `GET` request, providing the `account_key` and `device_key`. This operation returns device details, including its current status, creation date, and last update.
---
### Deactivate a Device
When necessary, a device can be deactivated through a `DELETE` request. Once deactivated, the device can no longer be used for transaction validation, ensuring greater control over operation security.
---
# Confirm Individual Account Opening
URL: /en/documentation/baas/escrow/abrir_conta_pf
Account opening occurs in two mandatory steps. First, a POST request sends preliminary data to reserve the account. Then, a webhook of type `account_request.status_change` with status `pending_additional_data` is triggered. In the second step, a PATCH request finalizes the opening, officially creating the account with the complementary information.
## Request
ENDPOINT /account_request/ ACCOUNT_REQUEST_KEY /escrow
METHOD PATCH
## Path Params
| Field | Type | Description | Characters |
|---------------|--------|----------------------------------------|------------|
| `account_request_key` | uuidv4 | Unique identification key for account reservation request. | 36 |
## Escrow account opening
Request Body
```json
{
"account_owner": {
"address": {
"street": "Av. Brigadeiro Faria Lima",
"state": "SP",
"city": "São Paulo",
"neighborhood": "Jardim Paulistano",
"number": "2391",
"postal_code": "01452905",
"complement": "Complemento"
},
"birth_date": "1990-05-06",
"document_identification": "3884579b-9810-4fa6-9b08-fe67d237160a",
"email": "teste@gmail.com",
"individual_document_number": "99999999999",
"is_pep": false,
"mother_name": "Dona Maria Mariane",
"name": "Nome do Titular da Conta",
"nationality": "nationality",
"person_type": "natural",
"phone": {
"country_code": "055",
"area_code": "11",
"number": "999999999"
},
"proof_of_residence": "4d7f4e-1eec-4e5f-82c0-d8c3921497ea",
"monthly_income": 1000
},
"signed_contract": {
"document_key": "48a8f4g9-4b58-4905-9a69-b1f9215263f5",
"signatures": [
{
"authenticity": {
"timestamp": "1970-01-01T00:00:01.080100Z",
"facial_recognition_key":"79003de0-2590-455d-9b73-426b8ca284eb",
"lang": "-35.8916627",
"lat": "-7.2226067",
"ip_address": "177.51.1.186",
"session_id": "jdifj329842"
},
"signer": {
"name": "Nome do Titular da Conta",
"email": "teste@gmail.com",
"phone": {
"country_code": "055",
"area_code": "11",
"number": "999999999"
},
"document_number": "999999999"
},
"authentication_type": "opt-in"
}
]
},
"destinations": [
{
"account_branch": "0001",
"account_number": "1234567",
"account_digit": "1",
"document_number": "04252012000123",
"name": "Conta do FIDC",
"ispb_number": "32402502",
"financial_institution_code_number": "329"
}
],
"additional_documents": ["b12c8807-8f3f-4083-9cb1-7cce641f3786"]
}
```
### Request Body Params
| Field | Type | Description | Characters |
|---|---| ---|---|
| `account_owner` * | object | Object containing the Account Holder information | **[account_owner Object](#account_owner-object)** |
| `signed_contract` * | object | Object containing the Account Holder information | **[signed_contract Object](#signed_contract-object)** |
| `destinations ` * | list | List of destination accounts authorized to receive transfers. | **[destinations Object](#destinations-object)** |
| `additional_documents` | list | List of additional/optional document IDs. | Array of UUIDs |
### account_owner Object
| Field | Type | Description | Characters |
|---| ---| ---| ---|
| `address` * | object | Address of the account holder. | **[address Object](#address-object)** | |
| `birth_date` | string | Birth date of the account holder (format "YYYY-MM-DD"). | - |
| `document_identification` * | uuidv4 | DOCUMENT_KEY of the PDF of the account holder's identification document with photo (ID or Driver's License) (previously uploaded) | 36 |
| `email` * | string | Email of the account holder. | 200 |
| `individual_document_number` | string | CPF of the account holder (numbers only). Limited to 11 characters. | 11 |
| `is_pep` * | string | Declaration if the person is a PEP (http://www.portaldatransparencia.gov.br/download-de-dados/pep).| - |
| `mother_name` | string | Mother's name of the client in case of individual. | - |
| `name` * | string | Name of the account holder. | - |
| `nationality` * | string | Nationality of the client. | - |
| `person_type` * | enumerator | Identifier that the sent object is an individual or legal entity.| **[person_type Enumerators](#person_type-enumerators)**|
| `phone` * | string | Object with phone data | **[phone Object](#phone-object)**|
| `proof_of_residence` | string | DOCUMENT_KEY of the PDF of the address proof for the sent address (previously uploaded).| - |
| `monthly_income`* | number | Monthly income of the account holder | |
### address Object
This object, present in both individual and legal entity objects, is a simple object to represent an address.
| Field | Type | Description | Characters |
|---|---|---|---|
| `street` *| string | Street of the address | 500 |
| `state` *| string | State of the address (with two uppercase characters) | 2 |
| `city` *| string | City of the address | 255 |
| `neighborhood` *| string | Neighborhood of the address | 500 |
| `number` *| string | Street number | 10 |
| `postal_code` *| string | Postal code of the address (http://www.buscacep.correios.com.br/sistemas/buscacep/) (numbers only) | 8 |
| `complement` *| string | Address complement (free text) | 500 |
### destinations Object
| Field | Type | Description | Characters |
|---| ---| ---| ---|
| `account_branch` * | string | Branch number of the destination account. | 4 |
| `account_number` * | string | Destination account number. | - |
| `account_digit` * | string | Check digit of the destination account number. | 1 |
| `document_number` * | string | CPF/CNPJ of the destination account holder. | - |
| `name ` | string | Name/Corporate Name of the destination account holder. | - |
| `ispb_number` * | string | ISPB (CNPJ base) of the destination account's financial institution.| 8 |
| `financial_institution_code_number ` * | string | Code of the destination account's financial institution. | 3 |
### signed_contract Object
| Field | Type | Description | Characters |
|-------|--------|------------------|---------------|
| **document_key** * | uuidv4 | Unique identification key of the **Account Opening Agreement** or **Escrow Account Contract** document. (The DOCUMENT_KEY is returned in the response of the [Document upload](./upload_de_documentos) endpoint) | 36 |
| **signatures** * | list | Signature data of the sent document. Each item in the list corresponds to a document signer. | [signatures Object](#signatures-object) |
### signatures Object
| Field | Type | Description | Characters |
|-------|------------|-------------------|-------------------|
| **authenticity** * | object | Set of data that evidences the electronic signature performed by the signer. | [authenticity Object](#authenticity-object) |
| **signer** * | object | Object containing the data of one of the document signers. | [signer Object](#signer-object)|
| **authentication_type** * | enumerator | Signature type. Will always be "**opt-in**"| "**opt-in**" |
### person_type Enumerators
| Enum | Description |
|-------|-------------------|
| **natural** * | Individual |
| **legal** * | Legal Entity |
### authenticity Object
| Field | Type | Description | Characters |
|-------|--------|-------------------------|------------|
| **timestamp** * | string | Date and time of the document signing moment. | 27 |
| **facial_recognition_key** *| uuidv4 | Unique identification key of the account holder's selfie photo. | 36 |
| **lang** | string | Longitude coordinate of the signer's geolocation captured at the time of signature. | - |
| **lat** | string | Latitude coordinate of the signer's geolocation captured at the time of signature. | - |
| **ip_address** | string | IP address of the signer's device. | - |
| **session_id** * | string | Session ID of the signer at the time of signature. | - |
### signer Object
| Field | Type | Description | Characters |
|-----------------------|--------|-------------------------------------------|-----------------------------------|
| **name** * | string | Signer's name. | - |
| **email** * | string | Signer's email. | - |
| **phone** * | object | Object with signer's phone data | **[phone Object](#phone-object)** |
| **document_number** * | string | Signer's CPF. | 11 |
### phone Object
| Field | Description | Example | Max. Characters |
| --- | --- | --- | --- |
|`country_code` *| string | Country code of the phone (https://ddi.guiamais.com.br/) | 3 |
| `area_code` *| string | Area code of the phone (https://ddd.guiamais.com.br/) | 3 |
| `number` *| string | Phone number (numbers only) | 10 |
## Response
STATUS 201
Response Body
```json
{
"account_key": "e48eb139-448e-43b9-9aee-df5f4b51158c"
}
```
:::warning Attention
The `account_key` field will be the unique identification key of the account. All interaction with the account will be done through it.
:::
STATUS 4xx
Response Body: Error
```json
{
"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(ptbr) `translation`|
|---| --- | --- | --- | --- |
| 400 | QIT000001 | Bad Request | Schema Error | Schema Error|
| 404 | QIT000404 | Not Found | Resource could not be found | Resource not found|
---
# Confirm Legal Entity Account Opening
URL: /en/documentation/baas/escrow/abrir_conta_pj
Account opening occurs in two mandatory steps. First, a POST request sends preliminary data to reserve the account. Then, a webhook of type `account_request.status_change` with status `pending_additional_data` is triggered. In the second step, a PATCH request finalizes the opening, officially creating the account with the complementary information.
## Request
ENDPOINT /account_request/ ACCOUNT_REQUEST_KEY /escrow
METHOD PATCH
## Path Params
| Field | Type | Description | Characters |
|---------------|--------|----------------------------------------|------------|
| `account_request_key` | uuidv4 | Unique identification key for the account reservation request. | 36 |
## Escrow Account Opening
Request Body
```json
{
"account_owner": {
"address": {
"city": "Caraguatatuba",
"complement": "complemento",
"neighborhood": "Jaraguazinho",
"number": "924",
"postal_code": "11675200",
"state": "SP",
"street": "Praça Jorge Vitório de Souza"
},
"cnae_code": "4721-1/02",
"company_document_number": "64669455000187",
"company_statute": "8b0d8c33-01c9-4cf5-a0fa-1d2a96f4b34d",
"company_type": "ltda",
"email": "marcos.alves@yopmail.com",
"foundation_date": "2017-09-16",
"name": "NOME DA EMPRESA",
"person_type": "legal",
"phone": {
"area_code": "19",
"country_code": "055",
"number": "988888888"
},
"trading_name": "Pães e Doces",
"monthly_revenue": 100000,
"company_representatives": [
{
"name": "Marcos Felipe Henrique Alves",
"address": {
"city": "Recife",
"complement": null,
"neighborhood": "Fundão",
"number": "137",
"postal_code": "52221110",
"state": "PE",
"street": "Rua Camapuã"
},
"email": "marcos.alves@yopmail.com",
"birth_date": "1972-02-02",
"individual_document_number": "08531309069",
"document_identification": "8b0d8c33-01c9-4cf5-a0fa-1d2a96f4b34d",
"document_identification_number": "339122924",
"is_pep": false,
"final_beneficiary": true,
"marital_status": "single",
"mother_name": "Sueli Isadora Alves",
"nationality": "Brasileira",
"person_type": "natural",
"phone": {
"area_code": "88",
"country_code": "055",
"number": "995924634"
}
}
]
},
"signed_contract": {
"document_key": "4d7f4e29-4b58-4905-9a69-b1f9215263f5",
"signatures": [
{
"authenticity": {
"timestamp": "1970-01-01T00:00:01.080100Z",
"facial_recognition_key": "79003de0-2590-455d-9b73-426b8ca284eb",
"lang": "-35.8916627",
"lat": "-7.2226067",
"ip_address": "177.51.1.186",
"session_id": "jdifj329842"
},
"signer": {
"name": "IVANILDO DE SENA LIMA",
"email": "ivanlima2604@gmail.com",
"phone": {
"country_code": "055",
"area_code": "11",
"number": "999999999"
},
"document_number": "61766976204"
},
"authentication_type": "opt-in"
}
]
},
"destinations": [
{
"account_branch": "0001",
"account_number": "1234567",
"account_digit": "1",
"document_number": "04252012000123",
"name": "Conta do FIDC",
"ispb_number": "32402502",
"financial_institution_code_number": "329"
}
],
"additional_documents": ["b12c8807-8f3f-4083-9cb1-7cce641f3786"]
}
```
### Request Body Params
| Field | Type | Description | Characters |
|---|---| ---|---|
| `account_owner` * | object | Object containing Account Holder information | **[account_owner Object](#account_owner-object)** |
`signed_contract` * | object | Object containing Account Holder information | **[signed_contract Object](#signed_contract-object)** |
| `destinations ` * | list | List of destination accounts authorized to receive transfers. | **[destinations Object](#destinations-object)** |
| `additional_documents` | list | List of additional/optional document IDs. | Array of UUIDs |
### account_owner Object
| Field | Type | Description | Characters |
|---| ---| ---| ---|
| `address` * | object | Account holder address. | **[address Object](#address-object)** | |
| `cnae_code` | string | National Classification of Economic Activities | 9 |
| `company_document_number ` * | string | CNPJ | 14 |
| `company_statute ` | uuidv4 | DOCUMENT_KEY of the company statute PDF (previously uploaded). | 36 |
| `company_type` * | enumerator | Company type| **[company_type Enumerators](#company_type-enumerators)** |
| `email` * | string | Account holder email. | 200 |
| `foundation_date` | string | Company founding date (format "YYYY-MM-DD"). | 10 |
| `name` * | string | Account holder company name. | 50 |
| `person_type` * | enumerator | Identifier indicating whether the submitted object is a natural person or legal entity.| **[person_type Enumerators](#person_type-enumerators)**|
| `phone` * | object | Object with phone data | **[phone Object](#phone-object)**|
| `trading_name ` * | string | Trade name. | 200 |
| `company_representatives` | list | List of the company's legal representatives | **[company_representatives Object](#company_representatives-object)** |
| `monthly_revenue`* | number | Company monthly revenue | |
### signed_contract Object
| Field | Type | Description | Characters |
|-------|--------|------------------|---------------|
| ` document_key` * | uuidv4 | Unique identification key for the **Account Opening Agreement** or **Escrow Account Contract** document. (The DOCUMENT_KEY is returned in the response from the [Document upload](./upload_de_documentos) endpoint) | 36 |
|` signatures` * | list | Signature data for the submitted document. Each item in the list corresponds to a document signer. | [signatures Object](#signatures-object) |
### destinations Object
| Field | Type | Description | Characters |
|---| ---| ---| ---|
| `account_branch` * | string | Destination account branch number. | 4 |
| `account_number` * | string | Destination account number. | - |
| `account_digit` * | string | Destination account number check digit. | 1 |
| `document_number` * | string | CPF/CNPJ of the destination account holder. | - |
| `name ` | string | Name/Company Name of the destination account holder. | - |
| `ispb_number` * | string | ISPB (CNPJ base) of the destination account financial institution.| 8 |
| `financial_institution_code_number ` * | string | Destination account financial institution code. | 3 |
### company_representatives Object
| Field | Type | Description | Characters |
|------------------------------------|---------|--------------------------------------------------------------------------------------------------------|-----------------------------------------------------------------------------------------|
| **name** * | string | Company representative name | 100 |
| **address** * | object | Company representative address object | **[address Object](#address-object)** |
| **email** * | string | Company representative email | 254 |
| **birth_date** | string | Company representative birth date (format "YYYY-MM-DD") | 10 |
| **individual_document_number** * | string | Company representative CPF (numbers only). | 11 |
| **document_identification** | string | DOCUMENT_KEY of the person's photo identification document PDF (ID or Driver's License) (previously uploaded) | 36 |
| **document_identification_number** | string | Person's photo identification document number (ID or Driver's License) | 16 |
| **document_identification_type** | enum | Person's photo identification document type (ID or Driver's License) | [document_identification_type Enumerators](#document_identification_type-enumerators) |
| **is_pep** * | boolean | Declaration whether the person is PEP (http://www.portaldatransparencia.gov.br/download-de-dados/pep). | - |
| **final_beneficiary** | boolean | Declaration if the person is the final beneficiary of the company. | - |
| **marital_status** | enum | Company representative marital status | **[marital_status Enumerators](#marital_status-enumerators)** |
| **mother_name** | string | Company representative mother's name | 100 |
| **nationality** | string | Company representative nationality | 50 |
| **person_type** * | enum | Identifier indicating that the submitted object is a natural person | **[person_type Enumerators](#person_type-enumerators)** |
| **phone** * | object | Object with company representative phone data | **[phone Object](#phone-object)** |
### address Object
This object, present in both natural person and legal entity objects, is a simple object to represent an address.
| Field | Description | Example | Characters |
|--------------------|-----------|-------------------------------------------------------------------------------------------|------------|
| **street** * | string | Address street | 500 |
| **state** * | enum | Address state (with two uppercase characters) | 2 |
| **city** * | string | Address city | 255 |
| **neighborhood** * | string | Address neighborhood | 500 |
| **number** * | string | Street number | 10 |
| **postal_code** * | string | Address ZIP code (http://www.buscacep.correios.com.br/sistemas/buscacep/) (numbers only) | 8 |
| **complement** | string | Address complement (free text) | 500 |
### signed_contract Object
| Field | Type | Description | Characters |
|-------|--------|------------------|---------------|
| **document_key** * | uuidv4 | Unique identification key for the **Account Opening Agreement** or **Escrow Account Contract** document. (The DOCUMENT_KEY is returned in the response from the [Document upload](./upload_de_documentos) endpoint) | 36 |
| **signatures** * | list | Signature data for the submitted document. Each item in the list corresponds to a document signer. | [signatures Object](#signatures-object) |
### signatures Object
| Field | Type | Description | Characters |
|-------|------------|-------------------|-------------------|
| **authenticity** * | object | Set of data that evidence the electronic signature performed by the signer. | [authenticity Object](#authenticity-object) |
| **signer** * | object | Object containing data of one of the document signers. | [signer Object](#signer-object)|
| **authentication_type** * | enumerator | Signature type. Will always be "**opt-in**"| "**opt-in**" |
### authenticity Object
| Field | Type | Description | Characters |
|-------|--------|-------------------------|------------|
| **timestamp** * | string | Date and time of the document signing moment. | 27 |
| **facial_recognition_key** *| uuidv4 | Unique identification key for the account holder's selfie photo.| 36 |
| **lang** | string | Longitude coordinate of the signer's geolocation captured at the signing moment. | - |
| **lat** | string | Latitude coordinate of the signer's geolocation captured at the signing moment. | - |
| **ip_address** | string | Signer's device IP address. | - |
| **session_id** * | string | Signer's session ID at the signing moment. | - |
### signer Object
| Field | Type | Description | Characters |
|-----------------------|--------|-------------------------------------------|-----------------------------------|
| **name** * | string | Signer name. | - |
| **email** * | string | Signer email. | - |
| **phone** * | object | Object with signer phone data | **[phone Object](#phone-object)** |
| **document_number** * | string | Signer CPF. | 11 |
### phone Object
| Field | Description | Example | Max Characters |
| --- | --- | --- | --- |
|`country_code` *| string | Phone country code (https://ddi.guiamais.com.br/) | 3 |
| `area_code` *| string | Phone area code (https://ddd.guiamais.com.br/) | 2 |
| `number` *| string |Phone number (numbers only) | 10 |
### person_type Enumerators
| Enum | Description |
|-------------|-------------------|
| **natural** | Natural person |
| **legal** | Legal entity |
### document_identification_type Enumerators
| Enum | Description |
|---------|----------------------------------------|
| **rg** | RG - General Registry |
| **cnh** | CNH - National Driver's License |
### company_type Enumerators
| Enum | Description |
|----------------------------|--------------------------------------------------------------------------|
| **ltda** | Limited Liability Company |
| **sa** | Corporation |
| **micro_enterprise** | Micro Enterprise |
| **freelancer** | Freelancer |
| **sa_opened** | Publicly Traded Corporation |
| **sa_closed** | Privately Held Corporation |
| **se_ltda** | Limited Business Partnership |
| **se_cn** | General Partnership |
| **se_cs** | Limited Partnership |
| **se_ca** | Partnership Limited by Shares |
| **scp** | Silent Partnership |
| **ei** | Individual Entrepreneur |
| **ese** | Branch Office in Brazil of Foreign Company |
| **eeab** | Branch Office in Brazil of Argentine-Brazilian Binational Company |
| **ssp** | Simple Partnership |
| **ss_ltda** | Limited Simple Partnership |
| **ss_cn** | Simple General Partnership |
| **ss_cs** | Simple Limited Partnership |
| **eireli_ne** | Individual Limited Liability Company (Business Nature) |
| **eireli_ns** | Individual Limited Liability Company (Simple Nature) |
| **eireli** | Individual Limited Liability Company |
| **mei** | Individual Microentrepreneur |
| **me** | Micro Enterprise |
| **cop** | Cooperative |
| **private_association** | Private Association
| **association** | Association |
| **others** | Others |
### marital_status Enumerators
| Enum | Description |
|--------------|---------------|
| **single** | Single |
| **married** | Married |
| **widower** | Widowed |
| **divorced** | Divorced |
| **separated** | Separated |
## Response
STATUS 201
Response Body
```json
{
"account_key": "e48eb139-448e-43b9-9aee-df5f4b51158c"
}
```
:::warning Attention
The `account_key` will be the account's unique identification key. All account interactions will be performed through it.
STATUS 4xx
Response Body: Error
```json
{
"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(ptbr) `translation`|
|---| --- | --- | --- | --- |
| 400 | QIT000001 | Bad Request | Schema Error | Schema Error|
| 404 | QIT000404 | Not Found | Resource could not be found | Resource not found|
---
# Individual Account Opening
URL: /en/documentation/baas/escrow/reservar_conta_pf
Account opening occurs in two mandatory stages. First, a POST request sends preliminary data to reserve the account. Then, a webhook of type `account_request.status_change` with status `pending_additional_data` is triggered. In the second stage, a PATCH request finalizes the opening, making the account official with the complementary information.
## Request Account Reservation
## Request
ENDPOINT /account_request/escrow
METHOD POST
Request Body
```json
{
"account_owner": {
"document_number": "64669455000187",
"email": "marcos.alves@yopmail.com",
"birthdate": "2017-09-16",
"name": "NOME",
"documents": {
"rg": {
"ocr_front_key": "9d6fefc0-77c9-4acc-8526-53523ff155b9",
"ocr_back_key": "30157d15-3b93-46ad-9c94-cd8bd533f9ed"
},
"cnh": {
"ocr_key": "f30cea56-dd66-415b-9a28-746f7330b708"
}
},
"face": "dbdaf3c9-cdf6-4737-8551-92910b213b7e"
}
}
```
:::info CPF/CNPJ Mock
To simulate approval, rejection, and manual review situations, the first digit of the account owner's CPF/CNPJ can be used:
0 to 6 -> Manual Review
7 -> Rejected by bacen protege+
8 -> Automatically rejected in KYC
9 -> Automatic Approval
:::
### Request Body Params
| Field | Type | Description | Characters |
|---|---| ---|---|
| `account_owner` * | object | Object containing Account Holder information | **[account_owner object](#account_owner-object)** |
### account_owner object
| Field | Type | Description | Characters |
|--- | --- | --- | --- |
| `document_number` * | string | Account Holder's CPF | 11 |
| `email` * | string | Account Holder's Email | 200 |
| `birthdate` | string | Date of birth. (YYYY-MM-DD format) | 10 |
| `name` * | string | Account Holder's Name | 50 |
| `documents` *| object | Account holder's document(s) | **[documents object](#documents-object)** |
| `face` * | uuidv4 | Facial recognition key from antifraud (`face_recognition_key`) | 36 |
### documents object
| Field | Type | Description | Characters |
|--------------------------------|-------------|--------------------------------------------------------------------|-------------------------------|
| `rg` | object | OCR keys for front and back upload of holder's RG | **[rg object](#rg-object)** |
| `cnh` | object | OCR key for holder's CNH upload | **[cnh object](#cnh-object)** |
| `cnh_digital` | object | OCR key for holder's digital CNH upload | **[cnh_digital object](#cnh_digital-object)** |
| `national_registry_of_foreigners` | object | OCR keys for front and back upload of holder's RNE| **[national_registry_of_foreigners object](#national_registry_of_foreigners-object)** |
| `national_migration_registry` | object | OCR keys for front and back upload of holder's CRNM| **[national_migration_registry object](#national_migration_registry-object)** |
| `passport` | object | OCR key for holder's passport upload | **[passport object](#passport-object)** |
| `cin_digital` | object | OCR key for holder's digital National Identity Card upload | **[cin_digital object](#cin_digital-object)** |
:::info Information
The OCR keys (`ocr_key` or `ocr_front_key` and `ocr_back_key`) for document image uploads are provided as a response from the image upload in antifraud. The `face_recognition_key` is returned in the facial recognition response.
:::
### rg object
| Field | Type | Description | Characters |
|--------------------------------|-------------|--------------------------------------------------------------------|-------------------------------|
| `ocr_front_key` * | uuidv4 | OCR key for RG front image upload | 36 |
| `ocr_back_key` * | uuidv4 | OCR key for RG back image upload | 36 |
OR
| Field | Type | Description | Characters |
|--------------------------------|-------------|--------------------------------------------------------------------|-------------------------------|
| `ocr_key` * | uuidv4 | OCR key for RG image upload | 36 |
### cnh object
| Field | Type | Description | Characters |
|--------------------------------|-------------|--------------------------------------------------------------------|-------------------------------|
| `ocr_front_key` * | uuidv4 | OCR key for CNH front image upload | 36 |
| `ocr_back_key` * | uuidv4 | OCR key for CNH back image upload | 36 |
OR
| Field | Type | Description | Characters |
|--------------------------------|-------------|--------------------------------------------------------------------|-------------------------------|
| `ocr_key` * | uuidv4 | OCR key for CNH image upload | 36 |
### cnh_digital object
| Field | Type | Description | Characters |
|--------------------------------|-------------|--------------------------------------------------------------------|-------------------------------|
| `ocr_key` * | uuidv4 | OCR key for digital CNH image upload | 36 |
### national_registry_of_foreigners object
| Field | Type | Description | Characters |
|--------------------------------|-------------|--------------------------------------------------------------------|-------------------------------|
| `ocr_front_key` * | uuidv4 | OCR key for RNE front image upload | 36 |
| `ocr_back_key` * | uuidv4 | OCR key for RNE back image upload | 36 |
OR
| Field | Type | Description | Characters |
|--------------------------------|-------------|--------------------------------------------------------------------|-------------------------------|
| `ocr_key` * | uuidv4 | OCR key for RNE image upload | 36 |
### national_migration_registry object
| Field | Type | Description | Characters |
|--------------------------------|-------------|--------------------------------------------------------------------|-------------------------------|
| `ocr_front_key` * | uuidv4 | OCR key for CRNM front image upload | 36 |
| `ocr_back_key` * | uuidv4 | OCR key for CRNM back image upload | 36 |
OR
| Field | Type | Description | Characters |
|--------------------------------|-------------|--------------------------------------------------------------------|-------------------------------|
| `ocr_key` * | uuidv4 | OCR key for CRNM image upload | 36 |
### passport object
| Field | Type | Description | Characters |
|--------------------------------|-------------|--------------------------------------------------------------------|-------------------------------|
| `ocr_key` * | uuidv4 | OCR key for passport image upload | 36 |
### cin_digital object
| Field | Type | Description | Characters |
|--------------------------------|-------------|--------------------------------------------------------------------|-------------------------------|
| `ocr_key` * | uuidv4 | OCR key for digital National Identity Card image upload | 36 |
## Response
STATUS 201
Response Body
```json
{
"account_info": {
"account_branch": "0001",
"account_digit": "0",
"account_number": "1693580"
},
"account_request_key": "f230f1b5-07af-4737-b0e3-8a472304f5e7",
"account_request_status": "pending_bacen_validation"
}
```
:::info Bacen Protege+ Flow
The proposal starts with status `pending_bacen_validation`. The system performs a preliminary validation with Bacen Protege+ before proceeding with KYC analysis. After Bacen approval, the status will be automatically updated to `pending_kyc_analysis`.
:::
:::warning Warning
The `account_request_key` field must be stored and will be used for account opening confirmation.
:::
### Response Body Params
| Field | Type | Description | Characters|
|---|---| ---|---|
| `account_info` * | object | Object containing Account Holder information |**[account_info object](#account_info-object)** | - |
| `account_request_key` * | string | Creation request identification key | - | - |
| `account_request_status` * | string | KYC Status | - | - |
### account_info object
| Field | Type | Description | Characters |
|---|---| ---| --- |
| `account_branch` * | string | Branch Number | 4 |
| `account_digit` * | string | Account Digit | 11 |
| `account_number` * | string | Account Number | 50 |
STATUS 4xx
Response Body: Error
```json
{
"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(ptbr) `translation`|
|---| --- | --- | --- | --- |
| 400 | QIT000001 | Bad Request | Schema Error | Erro de Schema|
| 404 | QIT000404 | Not Found | Resource could not be found | Recurso não encontrado|
---
# Business Account Opening
URL: /en/documentation/baas/escrow/reservar_conta_pj
Business account opening occurs in two mandatory steps. First, a POST request sends preliminary data to reserve the account. Then, a webhook of type `account_request.status_change` with the status `pending_additional_data` is triggered. In the second step, a PATCH request finalizes the opening, officially establishing the account with the complementary information.
## Request Account Reservation
## Request
ENDPOINT /account_request/escrow
METHOD POST
Request Body
```json
{
"account_owner": {
"company_document_number": "99999999999",
"email": "email@teste.com",
"foundation_date": "2017-09-16",
"name": "Nome da Empresa"
},
"legal_representatives": [
{
"birthdate": "1963-07-23",
"name": "Don Corleone",
"document_number": "03912394323",
"documents": {
"national_registry_of_foreigners": {
"ocr_front_key": "0aa8a4ca-5873-49bd-851c-1f2c71a1cc28",
"ocr_back_key": "29f6e346-7fae-4dcb-9ea1-2a3e4ef593ea"
}
},
"face": "68da08f1-6cf4-4dce-a297-7b2f09311784"
},
{
"birthdate": "1996-03-10",
"name": "John Doe",
"document_number": "39113492093",
"documents": {
"cnh": {
"ocr_key": "beee557e-9240-4c5b-88f1-42812b195168"
}
}
}
]
}
```
:::info CPF/CNPJ Mock
To simulate approval, rejection, and manual analysis situations, the first digit of the account owner's CPF/CNPJ can be used:
0 to 6 -> Manual Analysis
7 -> Rejected by bacen protege+
8 -> Automatically rejected in KYC
9 -> Automatic Approval
:::
### Request Body Params
| Field | Type | Description | Characters |
|---|---| ---|---|
| `account_owner` * | object | Object containing the Account Holder's information | **[account_owner Object](#account_owner-object)** |
| `legal_representatives` | object array | List of account representatives and their data | **[legal_representative Object](#legal_representative-object)** |
### account_owner Object
| Field | Type | Description | Characters |
|--- | --- | --- | --- |
| `"company_document_number"` * | string | Account Holder's CNPJ | 14 |
| `email` * | string | Contract holder company's email | 200 |
| `foundation_date` | string | Company opening date (YYYY-MM-DD format) | 10 |
| `name` * | string | Company Name | 50 |
### legal_representative Object
| Field | Type | Description | Characters |
|--- | --- | --- | --- |
| `document_number` * | string | Account Holder's CPF | 11 |
| `birthdate` | string | Birth date. (YYYY-MM-DD format) | 10 |
| `name` * | string | Account Holder's Name | 50 |
| `documents` * | object | Account holder's document(s) | **[documents Object](#documents-object)** |
| `face` | uuidv4 | Face recognition key made with antifraud (`face_recognition_key`) | 36 |
### documents Object
| Field | Type | Description | Characters |
|--------------------------------|-------------|--------------------------------------------------------------------|-------------------------------|
| `rg` | object | OCR keys for front and back RG upload of the holder | **[rg Object](#rg-object)** |
| `cnh` | object | OCR key for holder's CNH upload | **[cnh Object](#cnh-object)** |
| `cnh_digital` | object | OCR key for holder's digital CNH upload | **[cnh_digital Object](#cnh_digital-object)** |
| `national_registry_of_foreigners` | object | OCR keys for front and back RNE upload of the holder| **[national_registry_of_foreigners Object](#national_registry_of_foreigners-object)** |
| `national_migration_registry` | object | OCR keys for front and back CRNM upload of the holder| **[national_migration_registry Object](#national_migration_registry-object)** |
| `passport` | object | OCR key for holder's passport upload | **[passport Object](#passport-object)** |
| `cin_digital` | object | OCR key for holder's digital National Identity Card upload | **[cin_digital Object](#cin_digital-object)** |
:::info Information
The OCR keys (`ocr_key` or `ocr_front_key` and `ocr_back_key`) for document image uploads are provided as a response from uploading images to antifraud. The `face_recognition_key` is returned in the face recognition response.
:::
### rg Object
| Field | Type | Description | Characters |
|--------------------------------|-------------|--------------------------------------------------------------------|-------------------------------|
| `ocr_front_key` * | uuidv4 | OCR key for RG front image upload | 36 |
| `ocr_back_key` * | uuidv4 | OCR key for RG back image upload | 36 |
OR
| Field | Type | Description | Characters |
|--------------------------------|-------------|--------------------------------------------------------------------|-------------------------------|
| `ocr_key` * | uuidv4 | OCR key for RG image upload | 36 |
### cnh Object
| Field | Type | Description | Characters |
|--------------------------------|-------------|--------------------------------------------------------------------|-------------------------------|
| `ocr_front_key` * | uuidv4 | OCR key for CNH front image upload | 36 |
| `ocr_back_key` * | uuidv4 | OCR key for CNH back image upload | 36 |
OR
| Field | Type | Description | Characters |
|--------------------------------|-------------|--------------------------------------------------------------------|-------------------------------|
| `ocr_key` * | uuidv4 | OCR key for CNH image upload | 36 |
### cnh_digital Object
| Field | Type | Description | Characters |
|--------------------------------|-------------|--------------------------------------------------------------------|-------------------------------|
| `ocr_key` * | uuidv4 | OCR key for digital CNH image upload | 36 |
### national_registry_of_foreigners Object
| Field | Type | Description | Characters |
|--------------------------------|-------------|--------------------------------------------------------------------|-------------------------------|
| `ocr_front_key` * | uuidv4 | OCR key for RNE front image upload | 36 |
| `ocr_back_key` * | uuidv4 | OCR key for RNE back image upload | 36 |
OR
| Field | Type | Description | Characters |
|--------------------------------|-------------|--------------------------------------------------------------------|-------------------------------|
| `ocr_key` * | uuidv4 | OCR key for RNE image upload | 36 |
### national_migration_registry Object
| Field | Type | Description | Characters |
|--------------------------------|-------------|--------------------------------------------------------------------|-------------------------------|
| `ocr_front_key` * | uuidv4 | OCR key for CRNM front image upload | 36 |
| `ocr_back_key` * | uuidv4 | OCR key for CRNM back image upload | 36 |
OR
| Field | Type | Description | Characters |
|--------------------------------|-------------|--------------------------------------------------------------------|-------------------------------|
| `ocr_key` * | uuidv4 | OCR key for CRNM image upload | 36 |
### passport Object
| Field | Type | Description | Characters |
|--------------------------------|-------------|--------------------------------------------------------------------|-------------------------------|
| `ocr_key` * | uuidv4 | OCR key for passport image upload | 36 |
### cin_digital Object
| Field | Type | Description | Characters |
|--------------------------------|-------------|--------------------------------------------------------------------|-------------------------------|
| `ocr_key` * | uuidv4 | OCR key for digital National Identity Card image upload | 36 |
## Response
STATUS 201
Response Body
```json
{
"account_info": {
"account_branch": "0001",
"account_digit": "0",
"account_number": "1693580"
},
"account_request_key": "f230f1b5-07af-4737-b0e3-8a472304f5e7",
"account_request_status": "pending_bacen_validation"
}
```
:::info Bacen Protege+ Flow
The proposal starts with status `pending_bacen_validation`. The system performs a preliminary validation with Bacen Protege+ before proceeding with KYC analysis. After Bacen approval, the status will be automatically updated to `pending_kyc_analysis`.
:::
:::warning Attention
The `account_request_key` field must be stored and will be used for account opening confirmation.
:::
### Response Body Params
| Field | Type | Description | Characters|
|---|---| ---|---|
| `account_info` * | object | Object containing the Account Holder's information |**[account_info Object](#account_info-object)** | - |
| `account_request_key` * | string | Creation request identification key | - | - |
| `account_request_status` * | string | KYC Status | - | - |
### account_info Object
| Field | Type | Description | Characters |
|---|---| ---| --- |
| `account_branch` * | string | Branch Number | 4 |
| `account_digit` * | string | Account Digit | 11 |
| `account_number` * | string | Account Number | 50 |
STATUS 4xx
Response Body: Error
```json
{
"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(ptbr) `translation`|
|---| --- | --- | --- | --- |
| 400 | QIT000001 | Bad Request | Schema Error | Erro de Schema|
| 404 | QIT000404 | Not Found | Resource could not be found | Recurso não encontrado|
---
# Account Opening Webhooks
URL: /en/documentation/baas/escrow/webhooks
After the account reservation request call, a webhook of type account_request.status_change is sent with the status pending_additional_data. This event serves as the trigger for sending the request to confirm account opening.
The account opening request response may return the status "pending_kyc_analysis" depending on the partner's integration configuration.
In this case, the response regarding account opening approval or rejection will be returned asynchronously via webhook.
The account number will be reserved at the moment of the opening request, however at this moment **the account will not yet be open**. Only after completion of QI Tech's KYC analysis will the account be open.
## Webhook Pending KYC Analysis
After Bacen Protege+ approval, the account opening request status is updated to `pending_kyc_analysis` and a webhook is sent to notify the partner.
WEBHOOK_TYPE account_request.status_change
STATUS pending_kyc_analysis
Webhook Body
```json
{
"data": {
"account_info": {
"account_digit": "3",
"account_branch": "0001",
"account_number": "1638634"
},
"account_request_key": "dc575950-dcce-48e1-99a6-5fb0ada63d86",
"status": "pending_kyc_analysis"
},
"event_datetime": "2022-09-02 22:39:39",
"key": "dc575950-dcce-48e1-99a6-5fb0ada63d86",
"status": "pending_kyc_analysis",
"webhook_type": "account_request.status_change"
}
```
## KYC Approval Webhook
Webhook Body
```json
{
"data": {
"account_info": {
"account_digit": "3",
"account_branch": "0001",
"account_number": "1638634"
},
"account_request_key": "dc575950-dcce-48e1-99a6-5fb0ada63d86"
},
"event_datetime": "2022-09-02 22:39:39",
"key": "dc575950-dcce-48e1-99a6-5fb0ada63d86",
"status": "pending_additional_data",
"webhook_type": "account_request.status_change"
}
```
### Account Request Status Enumerators
| Enum | Description |
|-----------------------------|--------------------------------|
| **pending_kyc_analysis** | Pending KYC approval |
| **pending_additional_data** | Pending additional information |
| **rejected** | Opening rejected |
## Legal Entity Accounts
# Account Rejected
WEBHOOK_TYPE account
STATUS account_rejected
Webhook Body
```json
{
"data": {
"account_info": {
"account_digit": "2",
"account_branch": "0001",
"account_number": "2359934",
"financial_institution_code": "329"
},
"allowed_user": {
"name": "Juliana Tereza Bernardes",
"document_number": "97564480084"
},
"account_owner": {
"name": "VOVO LUCIA CONVENIENCIA LTDA",
"document_number": "09080702000105"
}
},
"event_datetime": "2022-09-02 22:39:39",
"key": "dc575950-dcce-48e1-99a6-5fb0ada63d86",
"status": "account_rejected",
"webhook_type": "account"
}
```
## Individual Accounts
# Account Rejected
WEBHOOK_TYPE account
STATUS account_rejected
Webhook Body
```json
{
"key":"84864614-2860-4b78-bd44-77b961354014",
"data":{
"account_info":{
"account_key":"1435dbavf-2860-4b78-bd44-77b961354014",
"account_digit":"5",
"account_branch":"0001",
"account_number":"3998360",
"financial_institution_code":"329"
},
"account_owner":{
"name":"Pedro Pinho",
"document_number":"97634408077"
}
},
"status":"account_rejected",
"webhook_type":"account",
"event_datetime":"2024-01-09 14:35:46"
}
```
---
# baas_consulta_de_instituicoes_financeiras
URL: /en/documentation/baas/lista_de_instituicoes_financeiras/baas_consulta_de_instituicoes_financeiras
---
# baas_configuracao_de_notificacao
URL: /en/documentation/baas/notificacoes/baas_configuracao_de_notificacao
---
# baas_configuracao_template
URL: /en/documentation/baas/notificacoes/baas_configuracao_template
---
# baas_introducao
URL: /en/documentation/baas/notificacoes/baas_introducao
---
# baas_reenvio_de_notificacoes
URL: /en/documentation/baas/notificacoes/baas_reenvio_de_notificacoes
---
# baas_template
URL: /en/documentation/baas/notificacoes/baas_template
---
# baas_tipos_de_evento
URL: /en/documentation/baas/notificacoes/baas_tipos_de_evento
---
# Remittance file upload (CNAB)
URL: /en/documentation/baas/pagamento_em_lote/envio_de_remessa
:::caution Attention!
The call must be authenticated following the standard described in the [**Document upload**](/documentation/upload_de_documentos) section.
:::
## Request
ENDPOINT /payments/account/ ACCOUNT_KEY /remittance
METHOD POST
### Path parameters
| Field | Type | Description | Characters |
|-------------------------|--------|--------------------------------------------------------------|------------|
| `account_key` | uuidv4 | Unique account identification key, in uuid v4 format | 36 |
## Request Body Params
The following data must be sent as form-data in the request body:
| Field | Type | Description | Characters |
|-------------------------|--------|--------------------------------------------------------------|------------|
| `file` * | file | CNAB file in the standard stipulated by QI Tech | - |
## Response
STATUS 202
Response Body
```json
{
"cnab_remittance_key": "f14e9bac-94ed-4eb1-87b4-7fd7b7a2d280",
"cnab_remittance_status": "accepted"
}
```
### Response Body Params
| Field | Type | Description | Characters |
|--------------------------------|---------|-----------------------------------------------------------------|----------------------------|
| `cnab_remittance_key` * | uuidv4 | Unique CNAB file identification key in uuid v4 format | 36 |
| `cnab_remittance_status` * | string | CNAB file status | **[cnab_remittance_status enumerators](#enumeradores-cnab_file_status)** |
### cnab_remittance_status enumerators
| Enumerator | Description |
|------------|---------------------------------------------------------------------------|
| uploaded | Upload successful, but file hasn't started processing yet |
| processing | File being read |
| accepted | File read and accepted |
| rejected | File read and rejected (all file occurrences are rejected) |
## Error Response
STATUS 4xx
Response Body: Error
```json
{
"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 (ptbr) `translation` |
|------------------------|--------------------|----------------------------------------------------|------------------------------------------------------------------------------------------------------------------------|-----------------------------------------------------------------------------------------------------------------------|
| 400 | QIT000001 | Bad Request | Schema Error | Schema Inválido |
| 409 | PAP000002 | Conflict | CNAB file alredy received | Arquivo CNAB já recebido |
| 400 | PAP000003 | Bad Request | Invalid file name '``' . Please do not use specials characters like '!', '@', '(', ')', '$'. | Nome de arquivo invalido '``'. Favor não utilizar caracteres especiais como '!', '@', '(', ')', '$'." |
| 403 | PAP000004 | Forbidden | Usuario não tem autorização para fazer essa ação | User is not allowed to do this action |
| 404 | PAP000005 | Not Found | The source account key was not found | A chave da conta de origem não foi encontrada |
---
# Introduction to CNAB240 Batch Transaction
URL: /en/documentation/baas/pagamento_em_lote/introducao
QI Tech, through the Payments API, enables payments using the CNAB240 format, supporting different types of transactions, such as boletos, PIX and TED, in a single call. This system enables batch payment execution, ensuring greater efficiency for high-volume financial processes.
Payments are processed asynchronously, with rigorous validations during CNAB240 file submission. If the initial request results in an HTTP status 4xx, no payment will be processed.
After submission, the file can be approved or rejected. If rejected, the API will return a detailed list of errors related to file formatting, allowing the integrator to make necessary corrections before attempting to send again. The file will be rejected if any syntactic error is found. However, it is read in its entirety, or until a limit of 100 errors is found, so that all errors can be returned and corrected in a more practical and efficient manner.
While the file is being read, occurrences are added to a queue, but will only be processed if it is accepted. That is, if the file is rejected (status rejected), all its occurrences will also be discarded. On the other hand, the moment the file is completely read and accepted (status accepted), processing of these occurrences begins, ensuring continuity of transactions based on the provided data.
---
# Query Payment Batch Data by Account
URL: /en/documentation/baas/pix_automatico/conciliacao/consultar_lote_por_conta
## Request
ENDPOINT /account/ ACCOUNT_KEY /payment_order_conciliation_batch/ PAYMENT_ORDER_CONCILIATION_BATCH_KEY
METHOD GET
### Path Params
| Field | Type | Description | Characters |
|--------------------------|--------|---------------------------------------------------|------------|
| **`ACCOUNT_KEY`** * | uuidv4 | Unique account identification key. | 36 |
| **`PAYMENT_ORDER_CONCILIATION_BATCH_KEY`***| uuidv4 | Unique batch identification key. | 36 |
## Response
STATUS 200
Response Body
```json
{
"payment_order_conciliation_batch_status": "open",
"payment_order_conciliation_batch_type": "fixed_amount",
"total_amount": 1000.00,
"conciliated_amount": 500.00,
"total_payment_orders": 10,
"conciliated_payment_orders": 5,
"reference_date": "2025-06-13",
"created_at": "2025-06-10T20:30:23.459Z"
}
```
### Response Body Params
| Field | Type | Description | Characters |
|------------------------------------------|------------|----------------------------------------------------------------|------------|
| `payment_order_conciliation_batch_status`| enumerator | Payment order conciliation batch status. | [payment_order_conciliation_batch_status Enumerators](#payment_order_conciliation_batch_status-enumerators) |
| `payment_order_conciliation_batch_type` | enumerator | Payment order conciliation batch type. | [payment_order_conciliation_batch_type Enumerators](#payment_order_conciliation_batch_type-enumerators) |
| `total_amount` | number | Total value of the conciliation batch in reais (R$). | - |
| `conciliated_amount` | number | Already conciliated value of the batch in reais (R$). | - |
| `total_payment_orders` | integer | Total number of payment orders in the batch. | - |
| `conciliated_payment_orders` | integer | Number of payment orders already conciliated in the batch. | - |
| `reference_date` | string | Batch reference date (ISO 8601 format, e.g., "2025-06-13"). | 10 |
| `created_at` | string | Batch creation date and time (ISO 8601 format). | - |
### payment_order_conciliation_batch_status Enumerators
| Enumerator | Description |
|--------------|---------------------------------------------|
| `open` | Open conciliation batch |
| `closed` | Closed conciliation batch |
| `processing` | Conciliation batch in processing |
| `completed` | Completed conciliation batch |
| `cancelled` | Cancelled conciliation batch |
### payment_order_conciliation_batch_type Enumerators
| Enumerator | Description |
|-------------------|---------------------------------------------|
| `fixed_amount` | Fixed amount conciliation batch |
| `variable_amount` | Variable amount conciliation batch |
STATUS 4XX
Response Error
```json
{
"title": "titulo",
"description": "description in English",
"translation": "descrição em português",
"code": "codigo"
}
```
| HTTP Code | QI Code `code` | Title `title` | Description (eng) `description` | Description (ptbr) `translation` |
|-------------|----------------------|-----------------------------------|----------------------------------------------------------------------------|--------------------------------------------------------------------|
| 400 | QIT000002 | Bad Request | Invalid request schema. | Erro no esquema da requisição. |
| 404 | APX000003 | Conciliation Batch Not Found | Conciliation batch \{conciliation_batch_key\} not found. | Lote de conciliação \{conciliation_batch_key\} não encontrado. |
---
# Query Payment Batches by Requester
URL: /en/documentation/baas/pix_automatico/conciliacao/consultar_lote_requester
## Request
ENDPOINT /payment_order_conciliation_batches
METHOD GET
### Query Params
| Field | Type | Description | Required |
|------------------------------------------|------------|----------------------------------------------------------------|----------|
| `payment_order_conciliation_batch_status`| enumerator | Filter by conciliation batch status. | No |
| `payment_order_conciliation_batch_type` | enumerator | Filter by conciliation batch type. | No |
| `page` | integer | Page number for pagination (default: 1). | No |
| `page_size` | integer | Page size for pagination (default: 25). | No |
| `from_date` | string | Start date for filter (ISO 8601 format, e.g., "2025-06-01"). | No |
| `to_date` | string | End date for filter (ISO 8601 format, e.g., "2025-06-30"). | No |
## Response
STATUS 200
Response Body
```json
{
"payment_order_conciliation_batches": [
{
"payment_order_conciliation_batch_key": "98fc62fd-b0a0-4604-9bea-475e91a9dc82",
"payment_order_conciliation_batch_status": "closed",
"payment_order_conciliation_batch_type": "fixed_amount",
"account_key": "9b9ae7b0-7292-4b0d-9131-0167525ab067",
"total_amount": 1200,
"conciliated_amount": 1200,
"total_payment_orders": 12,
"conciliated_payment_orders": 12,
"reference_date": "2025-06-13",
"created_at": "2025-06-10T20:30:23.459Z"
},
{
"payment_order_conciliation_batch_key": "98fc62fd-b0a0-4604-9bea-475e91a9dc82",
"payment_order_conciliation_batch_status": "closed",
"payment_order_conciliation_batch_type": "variable_amount",
"account_key": "9b9ae7b0-7292-4b0d-9131-0167525ab067",
"total_amount": 700,
"conciliated_amount": 600,
"total_payment_orders": 7,
"conciliated_payment_orders": 6,
"reference_date": "2025-06-13",
"created_at": "2025-06-10T20:30:23.459Z"
},
{
"payment_order_conciliation_batch_key": "98fc62fd-b0a0-4604-9bea-475e91a9dc82",
"payment_order_conciliation_batch_status": "open",
"payment_order_conciliation_batch_type": "variable_amount",
"account_key": "9b9ae7b0-7292-4b0d-9131-0167525ab067",
"total_amount": 900,
"conciliated_amount": 700,
"total_payment_orders": 9,
"conciliated_payment_orders": 7,
"reference_date": "2025-06-17",
"created_at": "2025-06-10T20:30:23.459Z"
},
{
"payment_order_conciliation_batch_key": "98fc62fd-b0a0-4604-9bea-475e91a9dc82",
"payment_order_conciliation_batch_status": "closed",
"payment_order_conciliation_batch_type": "fixed_amount",
"account_key": "c24a0ac4-792c-494e-b887-6185e07a33a3",
"total_amount": 800,
"conciliated_amount": 800,
"total_payment_orders": 8,
"conciliated_payment_orders": 8,
"reference_date": "2025-06-13",
"created_at": "2025-06-10T20:30:23.459Z"
},
{
"payment_order_conciliation_batch_key": "98fc62fd-b0a0-4604-9bea-475e91a9dc82",
"payment_order_conciliation_batch_status": "open",
"payment_order_conciliation_batch_type": "variable_amount",
"account_key": "c24a0ac4-792c-494e-b887-6185e07a33a3",
"total_amount": 1000,
"conciliated_amount": 500,
"total_payment_orders": 10,
"conciliated_payment_orders": 5,
"reference_date": "2025-06-17",
"created_at": "2025-06-10T20:30:23.459Z"
}
],
"pagination": {
"page": 1,
"page_size": 25,
"number_of_pages": 1
}
}
```
### Response Body Params
| Field | Type | Description | Characters |
|--------------------------------------|-------|--------------------------------------------------------------|------------|
| `payment_order_conciliation_batches` | array | List of payment order conciliation batches. | [Array payment_order_conciliation_batches](#array-payment_order_conciliation_batches) |
| `pagination` | object| Query pagination information. | [Object pagination](#objeto-pagination) |
### Array payment_order_conciliation_batches
| Field | Type | Description | Characters |
|------------------------------------------|------------|----------------------------------------------------------------|------------|
| `payment_order_conciliation_batch_key` | uuidv4 | Unique identifier of the conciliation batch. | 36 |
| `payment_order_conciliation_batch_status`| enumerator | Status of the payment order conciliation batch. | [Enumerators payment_order_conciliation_batch_status](#enumeradores-payment_order_conciliation_batch_status) |
| `payment_order_conciliation_batch_type` | enumerator | Type of the payment order conciliation batch. | [Enumerators payment_order_conciliation_batch_type](#enumeradores-payment_order_conciliation_batch_type) |
| `account_key` | uuidv4 | Unique account identification key. | 36 |
| `total_amount` | number | Total amount of the conciliation batch in Brazilian reais (R$). | - |
| `conciliated_amount` | number | Already conciliated amount of the batch in Brazilian reais (R$). | - |
| `total_payment_orders` | integer | Total number of payment orders in the batch. | - |
| `conciliated_payment_orders` | integer | Number of payment orders already conciliated in the batch. | - |
| `reference_date` | string | Reference date of the batch (ISO 8601 format, e.g., "2025-06-13"). | 10 |
| `created_at` | string | Batch creation date and time (ISO 8601 format). | - |
### Object pagination
| Field | Type | Description | Characters |
|-------------------|---------|-----------------------------------------------------|------------|
| `page` | integer | Current page of the query. | - |
| `page_size` | integer | Page size (number of items per page). | - |
| `number_of_pages` | integer | Total number of available pages. | - |
### Enumerators payment_order_conciliation_batch_status
| Enumerator | Description |
|--------------|-------------------------------------------------|
| `open` | Open conciliation batch |
| `closed` | Closed conciliation batch |
| `processing` | Conciliation batch in processing |
| `completed` | Completed conciliation batch |
| `cancelled` | Cancelled conciliation batch |
### Enumerators payment_order_conciliation_batch_type
| Enumerator | Description |
|-------------------|-------------------------------------------------|
| `fixed_amount` | Fixed amount conciliation batch |
| `variable_amount` | Variable amount conciliation batch |
STATUS 4XX
Response Error
```json
{
"title": "titulo",
"description": "description in English",
"translation": "descrição em português",
"code": "codigo"
}
```
| HTTP Code | QI Code `code` | Title `title` | Description (eng) `description` | Description (ptbr) `translation` |
|-----------|--------------------|---------------------------------|----------------------------------------------------------------------------|--------------------------------------------------------------------|
| 400 | QIT000002 | Bad Request | Invalid request schema. | Erro no esquema da requisição. |
| 404 | APX000003 | Conciliation Batch Not Found | Conciliation batch not found. | Lote de conciliação não encontrado. |
---
# Payment Listing for an Account
URL: /en/documentation/baas/pix_automatico/conciliacao/listar_payment_orders
## Request
ENDPOINT /account/ ACCOUNT_KEY /payment_order_conciliation_batch/ PAYMENT_ORDER_CONCILIATION_BATCH_KEY /payment_orders
METHOD GET
### Query Params
| Field | Type | Description | Characters |
|------------------------|------------|--------------------------------------------------------------------------------|------------|
| `payment_order_status` | enumerator | Filters payments by status (e.g., `processed`, `pending`, `failed`). | 30 |
| `page` | integer | Page number to be returned (pagination). | - |
| `page_size` | integer | Number of items per page (pagination). | - |
## Response
STATUS 200
Response Body
```json
{
"payment_orders": [
{
"payment_order_key": "a1b2c3d4-e5f6-7890-ghij-1234567890kl",
"payment_order_status": "processed",
"amount": 150.75,
"currency": "BRL",
"transaction_date": "2023-10-05",
"recipient_data": {
"name": "Maria Silva",
"document_number": "12345678900",
"bank_account": {
"account_number": "987654",
"account_digit": "2",
"account_branch": "1234",
"ispb": "12345678"
}
},
"pix_key": "maria@example.com",
"pix_message": "Pagamento ref. Fatura 123",
"conciliation_id": "uuid-conciliation"
}
],
"pagination": {
"page": 1,
"page_size": 25,
"number_of_pages": 3
}
}
```
## Response Body Params
| Field | Type | Description | Characters |
|-----------------|--------|---------------------------------------------------------|------------|
| `payment_orders`| array | List of payment order objects. | [Array payment_orders](#array-payment_orders) |
| `pagination` | object | Pagination object containing results information. | [Object pagination](#object-pagination) |
---
### Array payment_orders
| Field | Type | Description | Characters |
|-----------------------|------------|-------------------------------------------------------------------------|------------|
| `payment_order_key` | uuidv4 | Unique identifier of the payment order. | 36 |
| `payment_order_status`| string | Payment order status (`processed`, `pending`, `failed`, etc.). | 30 |
| `amount` | number | Payment order amount in reais (R$). | - |
| `currency` | string | Payment currency. | 3 |
| `transaction_date` | string | Transaction date (ISO 8601 format, e.g., `2023-10-05`). | 10 |
| `recipient_data` | object | Payment recipient data. | [Object recipient_data](#object-recipient_data) |
| `pix_key` | string | Recipient's Pix key. | 77 |
| `pix_message` | string | Message sent with the Pix transaction. | 140 |
| `conciliation_id` | string | Payment conciliation identifier. | 36 |
---
### Object recipient_data
| Field | Type | Description | Characters |
|-------------------|--------|-----------------------------|------------|
| `name` | string | Recipient's name. | 50 |
| `document_number` | string | Recipient's CPF or CNPJ. | 14 |
| `bank_account` | object | Recipient's bank account data. | [Object bank_account](#object-bank_account) |
---
### Object bank_account
| Field | Type | Description | Characters |
|-----------------|--------|----------------------------------|------------|
| `account_number`| string | Account number. | - |
| `account_digit` | string | Account digit. | - |
| `account_branch`| string | Branch. | - |
| `ispb` | string | Financial institution ISPB. | - |
### Object pagination
| Field | Type | Description | Characters |
|------------------|---------|-------------------------------------|------------|
| `page` | integer | Returned page number. | - |
| `page_size` | integer | Number of items per page. | - |
| `number_of_pages`| integer | Total available pages. | - |
### Enumerators payment_order_status
| Enumerator | Description |
|-----------------------|----------------------------------------------------|
| `pending_conciliation`| Awaiting conciliation. |
| `pending` | Pending and not yet processed. |
| `accepted` | Accepted and awaiting payment. |
| `paid` | Successfully paid. |
| `rejected` | Rejected and will not be processed. |
| `cancelled` | Cancelled before payment. |
STATUS 4XX
Response Error
```json
{
"title": "titulo",
"description": "description in English",
"translation": "descrição em português",
"code": "codigo"
}
```
| HTTP Code | QI Code `code` | Title `title` | Description (eng) `description` | Description (ptbr) `translation` |
|-----------|--------------------|---------------------------------|----------------------------------------------------------------------------|--------------------------------------------------------------------|
| 400 | QIT000002 | Bad Request | Invalid request schema. | Erro no esquema da requisição. |
| 404 | APX000002 | Payment Order Not Found | Payment order \{payment_order_key\} not found. | Pedido de pagamento \{payment_order_key\} não encontrado. |
---
# Payment Order Conciliation Batch Creation Webhook
URL: /en/documentation/baas/pix_automatico/conciliacao/webhooks
Webhook notifications are essential for processing events about payment conciliation in Automatic Pix. This webhook informs about the creation of payment order conciliation batches.
## Conciliation Batch Creation Webhook
This webhook is issued when a new payment order conciliation batch is created.
:::danger Attention!
QI Tech webhooks should not be mapped in a restrictive way.
Additional fields may be included in the webhook payloads returned by our APIs.
:::
### Webhook Request Body
Request Body: Journey 1
```json
{
"webhook_type": "baas.automatic_pix.payment_order_conciliation_batch.creation",
"webhook_datetime": "2021-10-22T20:30:23.459Z",
"data": {
"payment_order_conciliation_batches": [
{
"payment_order_conciliation_batch_key": "98fc62fd-b0a0-4604-9bea-475e91a9dc82",
"payment_order_conciliation_batch_status": "open",
"payment_order_conciliation_batch_type": "fixed_amount",
"account_key": "uuid",
"total_amount": 0,
"conciliated_amount": 0,
"total_payment_orders": 0,
"conciliated_payment_orders": 0,
"reference_date": "2025-06-13",
"created_at": "2025-06-10T20:30:23.459Z"
},
{
"payment_order_conciliation_batch_key": "99fc62fd-b0a0-4604-9bea-475e91a9dc82",
"payment_order_conciliation_batch_status": "open",
"payment_order_conciliation_batch_type": "variable_amount",
"account_key": "uuid",
"total_amount": 0,
"conciliated_amount": 0,
"total_payment_orders": 0,
"conciliated_payment_orders": 0,
"reference_date": "2025-06-13",
"created_at": "2025-06-10T20:30:23.459Z"
}
]
}
}
```
### Webhook Body Params
| Field | Type | Description | Characters |
|-------------------|---------|-----------------------------------------------------------------------------------------------|------------|
| `webhook_type` * | string | Webhook event type (`baas.automatic_pix.payment_order_conciliation_batch.creation`). | 100 |
| `webhook_datetime` * | string | Date and time when the webhook was generated (ISO 8601 format). | - |
| `data` * | Object | Object containing conciliation batch details. | [data Object](#data-object) |
---
### data Object
| Field | Type | Description | Characters |
|---------------------------------------|-------|-----------------------------------------------------------------------------------|------------|
| `payment_order_conciliation_batches` * | array | List of created conciliation batches. | [payment_order_conciliation_batches Array](#payment_order_conciliation_batches-array) |
### payment_order_conciliation_batches Array
| Field | Type | Description | Characters |
|----------------------------------------|---------|--------------------------------------------------------------------------|------------|
| `payment_order_conciliation_batch_key` | string | Unique key of the conciliation batch. | 36 |
| `payment_order_conciliation_batch_status` | string | Status of the conciliation batch (`open`). | - |
| `payment_order_conciliation_batch_type` | string | Type of conciliation batch (`fixed_amount`, `variable_amount`). | - |
| `account_key` | uuidv4 | Identification key of the account associated with the batch. | 36 |
| `total_amount` | number | Total amount of the conciliation batch. | - |
| `conciliated_amount` | number | Total conciliated amount in the batch. | - |
| `total_payment_orders` | number | Total number of payment orders in the batch. | - |
| `conciliated_payment_orders` | number | Number of conciliated payment orders in the batch. | - |
| `reference_date` | string | Reference date of the batch (YYYY-MM-DD format). | 10 |
| `created_at` | string | Creation date of the batch (ISO 8601 format). | - |
---
# FAQ - Pix Automático
URL: /en/documentation/baas/pix_automatico/faq
{`
.faq-container {
margin: 30px 0;
}
.faq-section {
margin-bottom: 40px;
}
.faq-section-title {
font-size: 20px;
font-weight: 700;
color: #0f172a;
margin-bottom: 24px;
padding-bottom: 12px;
border-bottom: 2px solid #e5e7eb;
}
.faq-grid {
display: grid;
grid-template-columns: 1fr;
gap: 20px;
}
.faq-card {
background: linear-gradient(135deg, #ffffff 0%, #f8fafc 100%);
border: 2px solid #1e40af;
border-radius: 12px;
padding: 24px;
transition: all 0.3s ease;
position: relative;
overflow: hidden;
width: 100%;
}
.faq-card::before {
content: '';
position: absolute;
top: 0;
left: 0;
width: 4px;
height: 100%;
background: linear-gradient(to bottom, rgb(40, 85, 232), #0f172a);
transition: width 0.3s ease;
}
.faq-card:hover {
transform: translateY(-4px);
box-shadow: 0 10px 25px rgba(0, 0, 0, 0.1);
border-color: #1e3a8a;
}
.faq-card:hover::before {
width: 6px;
}
.faq-question {
font-size: 18px;
font-weight: 700;
color: #0f172a;
margin-bottom: 16px;
display: flex;
align-items: flex-start;
gap: 12px;
line-height: 1.4;
}
.faq-question::before {
content: '';
font-size: 20px;
flex-shrink: 0;
margin-top: 2px;
}
.faq-answer {
font-size: 14px;
line-height: 1.7;
color: #475569;
margin: 0;
}
.faq-answer ul {
margin: 12px 0;
padding-left: 20px;
}
.faq-answer li {
margin-bottom: 8px;
line-height: 1.6;
}
.faq-answer strong {
color: #0f172a;
font-weight: 700;
}
@media (max-width: 768px) {
.faq-grid {
grid-template-columns: 1fr;
}
}
`}
Questions about Recurrences
Does a recurrence need to have pre-defined validity or number of payments?
The recurrence validity is a parameter defined in the relationship between the receiver and the payer. Authorization can be granted for an indefinite period , or alternatively have pre-defined number of charges or final validity date .
Can the date chosen for the debit be any date within the cycle?
Yes, as long as the minimum 2-day advance between the scheduling date and the expected settlement date is respected, which must be before the start date of the next cycle .
Questions about Authorization Journeys
What is the main difference between journeys with QR Code?
The main difference lies in the user experience and the timing of recurrence authorization. Journey 2 only authorizes the future recurrence without processing payment immediately. Journey 3 allows the first immediate payment together with the recurrence authorization - the payment made is what activates the recurrence. Journey 4 works differently: the user reads a QR Code as if it were a normal PIX, and after making the payment or scheduling, the system offers the automatic pix option. Journey 4 is the only one that supports variable amount recurrences and offers more flexibility in user experience.
If, through journey 3, settlement succeeds and authorization fails, will payment cancellation be necessary, since the flow expects both to succeed?
It's at the receiver user's discretion . They may return the settled Pix and enable a new journey 3 or may offer another authorization journey for Pix Automático with the exclusive purpose of enabling authorization for subsequent payments.
Frequently Asked Questions about Reconciliation Batches
What are reconciliation batches?
Reconciliation batches are payment groupings that are automatically created by the system to facilitate reconciliation and control of Pix Automático payments. They serve as a way to organize and track payments by settlement date and recurrence type.
How are payments grouped into batches?
Payments are automatically grouped into batches based on criteria such as:
Expected settlement date for the payment
Recurrence type: fixed_amount or variable_amount
Specific account
Specific requester
When is a batch created?
Batches are automatically created by the system when there are payment orders that need to be processed for a specific payment date. The system groups these orders that have settlement on the same day into batches , to facilitate processing, visualization, and reconciliation.
When is a batch closed?
A batch is closed always three days before the payment reference date of that batch, because payment orders need to be sent at most two days in advance relative to the payment date of that cycle. That is, when its closing date arrives.
The system automatically calculates this date based on the payment settlement date minus 3 days, ensuring that payment instructions are sent within the regulatory deadline established by the Central Bank.
Can I query payments from closed batches?
Yes, you can query payments from closed batches through the batch query endpoints and listing payments from a specific batch.
Questions about Payment Orders and Attempts
What's the difference between payment order and payment attempt?
Payment Order: It's the instruction created by the system to make a specific payment on a determined date.
Payment Attempt: It's each individual execution of this payment order, and there can be multiple attempts if the first one fails.
How many payment attempts are made?
The system makes up to 4 payment attempts per payment order. If all attempts fail, the payment order is marked as rejected.
What happens when all attempts fail?
When all 4 payment attempts fail, the payment order has its status changed to "rejected" and no more attempts will be made for the payment of that cycle.
How do retries work?
Retries are automatically executed by the system according to the retry days configured by the receiver when creating the recurrence. Each attempt that fails generates a webhook notification so you can track the status of this payment.
Questions about Cancellations
Can I cancel a specific payment order?
Yes, you can cancel a specific payment order through the payment order cancellation endpoint, as long as it hasn't been settled yet.
What's the difference between canceling a recurrence and canceling a payment order?
Cancel Recurrence: Cancels the entire recurrence and all future payment orders associated with it.
Cancel Payment Order: Cancels only the specific payment order for that cycle, without affecting the recurrence or other orders.
Questions about Simulation
What are simulation scenarios for?
Simulation scenarios serve to test the complete Pix Automático flow in the sandbox environment, simulating the responses and interactions of the PSP Pagador (Payment Service Provider).
How to properly use simulation scenarios?
Scenarios should be executed in sequence to simulate the complete flow:
Create a recurrence
Process payment orders
Update execution dates (sandbox)
Process payment attempts
Simulate incoming PIX
Simulate rejected attempts (if necessary)
Questions about Webhooks
Which webhooks are sent by Pix Automático?
The system sends webhooks for various events, including:
Recurrence status changes
Payment order status changes
Payment attempt status changes
Creation and closing of reconciliation batches
Questions about Benefits and Comparisons
What are the main benefits for receivers adopting Pix Automático compared to other existing payment methods?
Pix Automático offers a new option to receiver users for receiving and managing periodic recurring charges, using the Pix infrastructure. Among the advantages, the following stand out: increased customer base , lower operational cost for not needing to establish agreements with more than one institution, diversification of payment methods , offering Pix as an alternative to customers who use card or bank slip, in addition to reducing delinquency and more agility in managing their receivables.
What's the main difference between traditional automatic account debit and Pix Automático?
Focusing on the experience of both receiver and payer users, Pix Automático presents new functionalities for managing authorizations and recurring schedules . Furthermore, any Pix participant can offer the product to their customers, expanding access for citizens and companies that today are not served by the automatic debit service, offered more restrictively only between banking institutions.
---
# Introduction to Automatic Pix
URL: /en/documentation/baas/pix_automatico/introducao
**Automatic Pix** is an innovative solution that automates recurring payments in a simplified, efficient, and secure manner. Ideal for businesses that work with subscriptions, monthly fees, or recurring bill charges, Automatic Pix evolves from traditional methods by eliminating the need for manual interaction, reducing defaults, and facilitating financial management, serving both companies and consumers.
{`
.hero-section {
background: linear-gradient(135deg, #eff6ff 0%, #ffffff 100%);
border: 1px solid #e5e7eb;
border-radius: 16px;
padding: 24px;
margin: 24px 0 32px 0;
}
.hero-grid {
display: grid;
grid-template-columns: repeat(auto-fit, minmax(200px, 1fr));
gap: 16px;
margin-top: 20px;
}
.hero-item {
background: #ffffff;
border: 1px solid #e5e7eb;
border-radius: 10px;
padding: 16px;
}
.hero-item strong {
display: block;
color: #1e40af;
font-size: 14px;
margin-bottom: 6px;
}
.hero-item p {
margin: 0;
font-size: 13px;
color: #475569;
line-height: 1.5;
}
.flow-section {
margin: 32px 0;
}
.flow-grid {
display: grid;
grid-template-columns: repeat(auto-fit, minmax(220px, 1fr));
gap: 16px;
margin-top: 20px;
}
.flow-step-card {
border-radius: 12px;
padding: 18px;
color: #ffffff;
min-height: 100px;
display: flex;
flex-direction: column;
gap: 8px;
}
.flow-step-card h4 {
margin: 0;
font-size: 15px;
font-weight: 700;
}
.flow-step-card p {
margin: 0;
font-size: 13px;
opacity: 0.95;
line-height: 1.5;
}
`}
How does it work in practice?
For whom?
Ideal for companies that offer subscriptions, recurring services, school tuition, health plans and similar services.
What do I need to do?
The receiver creates a recurrence and the payer authorizes it only once. Then, payments happen automatically in each cycle.
Main advantages
Reduces delays, eliminates the need to remember payment dates and simplifies financial management for both parties.
### Flow in 4 simple steps
1. Create Recurrence
The receiver defines the recurring charge characteristics (amount, frequency, start date).
2. Authorize
The payer authorizes only once in the bank app, choosing one of the 4 available journeys.
3. Schedule
Each cycle, the receiver sends the payment instruction and the payer's bank automatically schedules it.
4. Settle
On the scheduled date, debit and credit are automatically processed in each party's account.
---
## Automatic Pix API Features
QI Tech, through its **Automatic Pix API**, enables the integration of automatic payments using Pix, based on prior payer-to-receiver authorizations. The system covers the following responsibilities:
{`
.features-grid {
display: grid;
grid-template-columns: repeat(auto-fit, minmax(280px, 1fr));
gap: 20px;
margin: 30px 0;
}
.feature-card {
background: linear-gradient(135deg, #ffffff 0%, #f8fafc 100%);
border: 2px solid #e5e7eb;
border-radius: 12px;
padding: 24px;
transition: all 0.3s ease;
position: relative;
overflow: hidden;
}
.feature-card::before {
content: '';
position: absolute;
top: 0;
left: 0;
width: 4px;
height: 100%;
background: linear-gradient(to bottom, #3b82f6, #1e40af);
transition: width 0.3s ease;
}
.feature-card:hover {
transform: translateY(-4px);
box-shadow: 0 10px 25px rgba(0, 0, 0, 0.1);
border-color: #3b82f6;
}
.feature-card:hover::before {
width: 6px;
}
.feature-title {
font-size: 16px;
font-weight: 700;
color: #1e40af;
margin-bottom: 12px;
display: flex;
align-items: center;
gap: 10px;
}
.feature-icon {
font-size: 20px;
}
.feature-description {
font-size: 14px;
line-height: 1.6;
color: #475569;
margin: 0;
}
.recurrence-types {
display: grid;
grid-template-columns: repeat(auto-fit, minmax(300px, 1fr));
gap: 24px;
margin: 30px 0;
}
.recurrence-card {
background: #ffffff;
border-radius: 16px;
padding: 28px;
border: 2px solid;
position: relative;
transition: all 0.3s ease;
box-shadow: 0 4px 12px rgba(0, 0, 0, 0.08);
}
.recurrence-card:hover {
transform: translateY(-5px);
box-shadow: 0 12px 30px rgba(0, 0, 0, 0.12);
}
.recurrence-card.fixed {
border-color:rgb(11, 63, 250);
background: linear-gradient(135deg, #ffffff 0%,rgb(235, 240, 255) 100%);
}
.recurrence-card.variable {
border-color:rgb(11, 63, 250);
background: linear-gradient(135deg, #ffffff 0%,rgb(235, 240, 255) 100%);
}
.recurrence-header {
display: flex;
align-items: center;
gap: 12px;
margin-bottom: 16px;
}
.recurrence-badge {
padding: 6px 14px;
border-radius: 20px;
font-size: 12px;
font-weight: 700;
text-transform: uppercase;
letter-spacing: 0.5px;
}
.recurrence-card.fixed .recurrence-badge {
background:rgb(16, 64, 185);
color: #ffffff;
}
.recurrence-card.variable .recurrence-badge {
background:rgb(16, 64, 185);
color: #ffffff;
}
.recurrence-title {
font-size: 20px;
font-weight: 700;
color: #0f172a;
margin: 0;
}
.recurrence-description {
font-size: 15px;
line-height: 1.7;
color: #475569;
margin-bottom: 16px;
}
.recurrence-detail {
background: rgba(255, 255, 255, 0.7);
border-left: 3px solid;
padding: 12px 16px;
border-radius: 8px;
font-size: 13px;
line-height: 1.6;
color: #64748b;
}
.recurrence-card.fixed .recurrence-detail {
border-left-color:rgb(203, 15, 68);
}
.recurrence-card.variable .recurrence-detail {
border-left-color:rgb(203, 15, 68);
}
.periodicity-container {
background: linear-gradient(135deg, #eff6ff 0%, #ffffff 100%);
border: 2px solid #e5e7eb;
border-radius: 16px;
padding: 28px;
margin: 30px 0;
}
.periodicity-grid {
display: grid;
grid-template-columns: repeat(auto-fit, minmax(150px, 1fr));
gap: 16px;
margin-top: 20px;
}
.periodicity-item {
background: #ffffff;
padding: 16px;
border-radius: 10px;
text-align: center;
border: 2px solid #e5e7eb;
transition: all 0.3s ease;
}
.periodicity-item:hover {
border-color: #3b82f6;
transform: translateY(-3px);
box-shadow: 0 6px 20px rgba(59, 130, 246, 0.15);
}
.periodicity-label {
font-size: 14px;
font-weight: 600;
color: #1e40af;
margin: 0;
}
.journeys-container {
margin: 30px 0;
}
.journey-card {
background: #ffffff;
border: 2px solid #e5e7eb;
border-radius: 12px;
padding: 24px;
margin-bottom: 16px;
transition: all 0.3s ease;
border-left: 5px solid;
}
.journey-card:hover {
transform: translateX(5px);
box-shadow: 0 8px 20px rgba(0, 0, 0, 0.1);
}
.journey-card.journey-1 {
border-left-color: #3b82f6;
}
.journey-card.journey-2 {
border-left-color: #10b981;
}
.journey-card.journey-3 {
border-left-color: #f59e0b;
}
.journey-card.journey-4 {
border-left-color: #ec4899;
}
.journey-header {
display: flex;
align-items: center;
gap: 12px;
margin-bottom: 12px;
}
.journey-number {
background: linear-gradient(135deg, #1e40af, #3b82f6);
color: #ffffff;
width: 36px;
height: 36px;
border-radius: 50%;
display: flex;
align-items: center;
justify-content: center;
font-weight: 700;
font-size: 16px;
flex-shrink: 0;
}
.journey-card.journey-1 .journey-number {
background: linear-gradient(135deg, #1e40af, #3b82f6);
}
.journey-card.journey-2 .journey-number {
background: linear-gradient(135deg, #059669, #10b981);
}
.journey-card.journey-3 .journey-number {
background: linear-gradient(135deg, #d97706, #f59e0b);
}
.journey-card.journey-4 .journey-number {
background: linear-gradient(135deg, #db2777, #ec4899);
}
.journey-title {
font-size: 18px;
font-weight: 700;
color: #0f172a;
margin: 0;
}
.journey-description {
font-size: 14px;
line-height: 1.7;
color: #475569;
margin: 0;
padding-left: 48px;
}
.cancellation-info {
background: linear-gradient(135deg, #f8fafc 0%, #ffffff 100%);
border: 2px solid #e5e7eb;
border-radius: 16px;
padding: 28px;
margin: 30px 0;
}
.cancellation-list {
list-style: none;
padding: 0;
margin: 20px 0 0 0;
}
.cancellation-item {
background: #ffffff;
padding: 16px 20px;
border-radius: 10px;
margin-bottom: 12px;
border-left: 4px solid #3b82f6;
display: flex;
gap: 12px;
}
.cancellation-item:last-child {
margin-bottom: 0;
}
.cancellation-label {
font-weight: 700;
color: #1e40af;
min-width: 180px;
}
.cancellation-text {
color: #475569;
flex: 1;
margin: 0;
}
.advantages-grid {
display: grid;
grid-template-columns: repeat(auto-fit, minmax(280px, 1fr));
gap: 20px;
margin: 30px 0;
}
.advantage-card {
background: linear-gradient(135deg, #ffffff 0%, #f0fdf4 100%);
border: 2px solid #d1fae5;
border-radius: 12px;
padding: 20px;
transition: all 0.3s ease;
}
.advantage-card:hover {
transform: translateY(-4px);
border-color: #10b981;
box-shadow: 0 10px 25px rgba(16, 185, 129, 0.15);
}
.advantage-text {
font-size: 14px;
line-height: 1.7;
color: #475569;
margin: 0;
display: flex;
align-items: flex-start;
gap: 10px;
}
.advantage-icon {
color: #10b981;
font-size: 18px;
flex-shrink: 0;
margin-top: 2px;
}
@media (max-width: 768px) {
.features-grid,
.recurrence-types,
.advantages-grid {
grid-template-columns: 1fr;
}
.periodicity-grid {
grid-template-columns: repeat(2, 1fr);
}
.journey-description {
padding-left: 0;
margin-top: 12px;
}
}
`}
Creation and Management
Facilitates the creation, management, and cancellation of recurrences in a simplified and efficient way.
Authorization Orchestration
Ensures that Automatic Pix recurring payments are properly authorized by the payer.
Scheduling and Settlement
Completely automates payment cycles, from scheduling to settlement.
Logs and Audits
Maintains complete records of all operations for compliance with Bacen rules.
---
## Recurrence Types
Fixed Value
Fixed Value Recurrence
In the fixed value mode, the payer authorizes recurring payments of fixed amounts, previously established when creating the recurrence.
Ideal for: Monthly subscriptions, school tuition, service plans with fixed values.
Variable Value
Variable Value Recurrence
In the variable value mode, the payer and receiver agree on a range of allowed amounts for each recurring charge. The receiver defines the minimum value and the payer defines the maximum value.
Important: The receiver must reconcile the payment order with the amount to be charged within 10 to 3 days before the charge date.
Ideal for: Consumption-based models, variable service bills, payments adjustable over time.
---
## Recurrence Frequency
Currently, it is possible to create recurrences with the following frequencies:
Available Frequencies
Weekly
Monthly
Quarterly
Semi-annual
Annual
---
## Automatic Pix Authorization Journeys
Automatic Pix supports various authorization journeys to meet different business scenarios:
1
Journey 1: Push Notification
App notification for recurrence confirmation, without need for QR Code. The payer receives a notification and authorizes directly in the app.
2
Journey 2: QR Code - Recurrence
Authorization with QR Code containing only recurrence data. The payer scans the QR Code and authorizes only the future recurrence.
3
Journey 3: QR Code + First Payment
QR Code allowing immediate first payment and recurrence setup simultaneously. Ideal for cases where you want to receive the first payment and create the recurrence in the same transaction.
4
Journey 4: Complete QR Code
QR Code including data for immediate payment/scheduling and automatic pix offer for that charge, after payment or scheduling. Allows payment (or scheduling) and automatic pix offer in a single operation.
:::info Journey Documentation
For complete details on how to implement each journey, see:
- [Journey 1 - Push Notification](./recebedor/journey_one.md)
- [Journey 2 - QR Code (recurrence only)](./recebedor/journey_two.md)
- [Journey 3 - QR Code (with first payment)](./recebedor/journey_three.md)
- [Journey 4 - QR Code (with first payment and variable values)](./recebedor/journey_four.md)
:::
---
## Recurrence Cancellation
Cancellation Rules
Cancellation Request
Can be made by both the payer and receiver user unilaterally, without need for mutual approval.
Cancellation Impact
Authorization and recurrence are cancelled simultaneously, automatically blocking new payment instructions.
Cancellation Process
The payer user updates and communicates the cancellation status to the receiver user, who must be informed immediately.
Immediate Effects
Automatically cancels all associated schedules, except those scheduled for settlement on the cancellation day itself.
Receiver Initiative
The receiver can cancel the recurrence by their own decision or upon payer request through the API.
---
## Advantages and Potential
Automatic Pix offers various advantages, such as centralization of authorizations and payments, incentive to financial digitization, and efficiency in automatic debit solutions, filling gaps in traditional payment methods.
✓
Reduction of delay risk and the need to remember due dates, with elimination of manual steps
✓
Centralization of authorization and payment control in a single platform
✓
Incentive to digitization of financial processes and modernization of customer relationships
✓
Simplification of operations for merchants and end customers
✓
Efficiency in automatic debit solutions with Pix technology
✓
Filling existing gaps in traditional payment instruments
---
## Scenario Simulation
During the development and testing of integration with Automatic Pix, it is essential to validate all flows before using the production environment. **Scenario Simulation** provides a complete sandbox environment that allows testing the entire lifecycle of a recurrence, from creation to payment settlement.
### What is Scenario Simulation?
Scenario Simulation is a tool that allows **testing the complete Automatic Pix flow** in the sandbox environment, simulating SPI (Instant Payment System) responses without performing real transactions. It covers:
- **Creation and approval of recurrences** using the 4 available journeys
- **Processing of payment orders** and creation of reconciliation batches
- **Simulation of payment attempts** with different results (success or rejection)
- **Testing of cancellation flows** and recurrence management
### When to use?
Simulation is recommended for:
- **Integration validation**: Test if your application is correctly integrated with the API
- **Development**: Develop and debug your implementation without costs
- **Flow testing**: Validate different scenarios (successful payments, rejections, cancellations)
- **Training**: Familiarize your team with Automatic Pix flows before going to production
### How to use?
The simulation process follows a sequence of steps that replicates the real flow:
1. **Create a recurrence** using one of the authorization journeys
2. **Approve the recurrence** via mock, simulating payer confirmation
3. **Process payment orders** that automatically create reconciliation batches
4. **Query and reconcile** orders (mandatory for variable values)
5. **Update execution date** to accelerate tests in sandbox
6. **Process attempts** of payment
7. **Simulate the result**: Incoming Pix (success) or rejection
:::tip Complete Documentation
For a detailed step-by-step guide on how to use scenario simulation, including all available endpoints and request examples, see:
**[📋 Scenario Simulation Guide](./recebedor/simulacao.md)**
:::
### Simulation Benefits
✓
Testing without costs or risks, in controlled and isolated environment
✓
Complete validation of all flows before production
✓
Acceleration of dates and processes for faster testing
✓
Simulation of different scenarios (successes, failures, cancellations)
---
# Accept payment recurrence
URL: /en/documentation/baas/pix_automatico/movimentacoes/aceitar_recorrencia
## Request
ENDPOINT /account/ ACCOUNT_KEY /incoming_recurrence/ INCOMING_RECURRENCE_KEY /approve
METHOD PATCH
### Request Path Params
| Field | Type | Description | Characters |
|-------------|--------|--------------------------------|------------|
| `account_key` * | uuid4 | Unique account identification key. | 36 |
| `incoming_recurrence_key` * | uuid4 | Unique authorization identification key | 36 |
### Request Body
Request Body: Approve fixed amount recurrence
```json
{
"incoming_recurrence_status": "active"
}
```
Request Body: Approve variable amount recurrence with maximum limit
```json
{
"incoming_recurrence_status": "active",
"maximum_transaction_amount": 500.00
}
```
### Body Params
| Field | Type | Description | Characters |
|-------------------------|------------|--------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|------------|
| `incoming_recurrence_status` * | string | PIX recurrence status identifier. Must be "active" to activate the recurrence | 20 |
| `maximum_transaction_amount` | number | Maximum amount the user accepts to pay per transaction (optional, only for variable amount recurrences) | 10 |
:::info Maximum Amount for Variable Recurrences
The `maximum_transaction_amount` field is **optional** and should be used only for **variable amount recurrences**. It allows the payer to define the maximum amount they accept to pay per transaction within the authorized recurrence.
:::
## Response
STATUS 200
Response Body: Recurrence activated
```json
{
"incoming_recurrence_key": "cfa32109-a6dd-4304-94db-03a7b6d92a47",
"incoming_recurrence_status": "active",
"created_at": "2025-05-22T20:30:23.459Z",
"updated_at": "2025-05-22T20:39:23.459Z"
}
```
STATUS 4XX
Response Body
```json
{
"title": "titulo",
"description": "description in English",
"translation": "descrição em portugues",
"code": "codigo"
}
```
| HTTP Code | QI Code `code` | Title `title` | Description (eng) `Description` | Description (ptbr) `translation` |
|-------------|----------------------|------------------------------|---------------------------------------------------------------------|-------------------------------------------------------------------|
| 400 | QIT000001 | Bad Request | Schema Error | Erro de Schema |
403 | APX000025 | User is not allowed to do this transaction | User is not allowed to do this transaction | Usuário não tem autorização para fazer essa transação |
| 403 | APX000017 | Requester not allowed to access this endpoint | Requester has no permission to perform pix transfers on this endpoint | Requester não possui permissão de realizar transações pix através deste endpoint |
| 404 | APX000020 | Account not Found | Account was not found | Conta \{account_key\} não foi encontrada. |
| 404 | APX000001 | Recurrence not Found | Recurrence was not found | Recorrência \{incoming_recurrence_key\} não foi encontrada |
---
# Cancel recurrence
URL: /en/documentation/baas/pix_automatico/movimentacoes/cancelar_recorrencia
## Request
ENDPOINT /account/ ACCOUNT_KEY /incoming_recurrence/ INCOMING_RECURRENCE_KEY /cancel
METHOD PATCH
### Request Path Params
| Field | Type | Description | Characters |
|-------------|--------|--------------------------------|------------|
| `account_key` * | uuid4 | Unique account identification key. | 36 |
| `incoming_recurrence_key` * | uuid4 | Unique authorization identification key | 36 |
### Request Body
Request Body: Cancel a recurrence
```json
{
"incoming_recurrence_status": "cancelled",
}
```
### Body Params
| Field | Type | Description | Characters |
|-------------------------|------------|--------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|------------|
| `incoming_recurrence_status` * | string | Pix recurrence status identifier. | cancelled |
## Response
STATUS 200
Response Body: Recurrence cancelled
```json
{
"incoming_recurrence_key": "cfa32109-a6dd-4304-94db-03a7b6d92a47",
"incoming_recurrence_status": "cancelled",
"created_at": "2025-05-22T20:30:23.459Z",
"updated_at": "2025-05-22T20:39:23.459Z"
}
```
STATUS 4XX
Response Body
```json
{
"title": "titulo",
"description": "description in English",
"translation": "descrição em portugues",
"code": "codigo"
}
```
| HTTP Code | QI Code `code` | Title `title` | Description (eng) `Description` | Description (ptbr) `translation` |
|-------------|----------------------|------------------------------|---------------------------------------------------------------------|-------------------------------------------------------------------|
| 400 | QIT000001 | Bad Request | Schema Error | Erro de Schema |
403 | APX000025 | User is not allowed to do this transaction | User is not allowed to do this transaction | Usuário não tem autorização para fazer essa transação |
| 403 | APX000017 | Requester not allowed to access this endpoint | Requester has no permission to perform pix transfers on this endpoint | Requester não possui permissão de realizar transações pix através deste endpoint |
| 404 | APX000020 | Account not Found | Account was not found | Conta \{account_key\} não foi encontrada. |
| 404 | APX000001 | Recurrence not Found | Recurrence was not found | Recorrência \{incoming_recurrence_key\} não foi encontrada |
---
# Query Recurrence
URL: /en/documentation/baas/pix_automatico/movimentacoes/consultar_recorrencia
## Query Pix recurrence by incoming_recurrency_key
### Request
ENDPOINT /account/ ACCOUNT_KEY /incoming_recurrence/ INCOMING_RECURRENCE_KEY
METHOD GET
### Path Params
| Field | Type | Description | Characters |
|----------------------------|------------|-------------------------------------------------------|-----------------------------------------------------------------------------|
| `account_key` * | uuid4 | QI account unique identification key. | 36 |
| `incoming_recurrency_key` * | uuid4 | Automatic Pix recurrence unique identification key. | 36 |
### Response
STATUS 200
Response Body: Recurrence query
```json
{
"incoming_recurrence_key": "c2f3eefa-1b8e-4d5f-9b9d-123456789abc",
"incoming_recurrence_status": "pending_confirmation",
"request_control_key": "e04197f6-433e-48d2-8a8e-9258a70aba0b",
"transaction_amount": "150.00",
"periodicity": "monthly",
"journey_type": "journey_one",
"pix_transfer_type": "key",
"end_to_end_id": "E1234567890123456789012",
"start_date": "2025-06-01",
"end_date": "2026-06-01",
"next_execution_date": "2025-07-01",
"receiver_conciliation_id": "rec-conc-789",
"target_pix_key": "receiver@bank.com.br",
"payer_document_number": "12345678900",
"pix_message": "Pagamento mensal de serviço",
"created_at": "2025-05-22T10:00:00Z",
"updated_at": "2025-05-22T12:00:00Z",
}
```
| Field | Type | Description | Max. Characters |
|--------------------------------|---------|-----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|-------------------------------------------------------------------|
| `incoming_recurrence_key` | uuid4 | Authorization unique identification key | 36 |
| `incoming_recurrence_status` | string |Recurrence status identifier | [Enumerator incoming_recurrence_status](#enumerator-incoming_recurrence_status) |
| `request_control_key` | uuid4 | Request unique identification key used by the client | 36 |
| `transaction_amount` | number | Transfer amount for fixed value occurrence. | 10 |
| `minimum_transaction_amount` | number | Minimum transfer amount for variable value occurrence. | 10 |
| `maximum_transaction_amount` | number | Maximum transfer amount for variable value occurrence. | 10 |
| `periodicity` | enumerator | Periodicity type associated with the payment | [Enumerators periodicity](#enumerators-periodicity) |
| `journey_type` | enumerator | Request journey type | [Enumerators journey_type](#enumerators-journey_type) |
| `pix_transfer_type` | enumerator | Type of pix to be performed | [Enumerators pix_transfer_type](#enumerators-pix_transfer_type) |
| `end_to_end_id` | string | Idempotency key of a Pix transaction within SPI (Instant Payment System). This key is returned in the Pix key query. | 32 |
| `start_date` | string | Recurrence start date | - |
| `end_date` | string | Recurrence end date, for indefinite time cases, send as null
| `next_execution_date` | string | Next recurrence transaction execution date | - |
| `receiver_conciliation_id` | string | Receiver conciliation identification. | 35 |
| `target_pix_key` | string | Transaction account pix key. | 100 |
| `payer_document_number` | string | Transaction payer document number. | 14 |
| `pix_message` | string | Message to be sent along with the Pix transfer. | 140 |
| `created_at` | string | Recurrence request creation time | -
| `updated_at` | string | Recurrence request update time | -
### Enumerator incoming_recurrence_status
| Enumerator | Description |
|----------------------|---------------------|
| `pending_confirmation` | Recurrence pending confirmation |
| `active` | Active recurrence |
| `cancelled` | Cancelled recurrence |
| `suspended` | Suspended recurrence |
| `expired` | Expired recurrence |
### Enumerators periodicity
| Enumerator | Description |
|------------------|--------------------|
| `weekly` | Weekly recurrence |
| `monthly` | Monthly recurrence |
| `quarterly` | Quarterly recurrence |
| `semiannual` | Semiannual recurrence |
| `annual` | Annual recurrence |
### Enumerators journey_type
| Enumerator | Description |
|------------------|--------------------|
| `journey_one` | Authorization request via app notification |
| `jouney_two` | Authorization request via QR Code reading |
| `journey_three` | Recurrence authorization through immediate pix via QR Code reading |
| `journey_four` | Payment or scheduling of a pix with a recurrence authorization request in sequence |
### Enumerators pix_transfer_type
| Enumerator | Description |
|---------------------|------------------------------------------|
| `manual` | Pix using destination account data |
| `key` | Pix using a pix key |
| `static_qr_code` | Pix using a static QR code |
| `dynamic_qr_code` | Pix using a dynamic QR code |
STATUS 4xx
Response Body: Error
```json
{
"title": "titulo",
"description": "description in English",
"translation": "descrição em portugues",
"code": "codigo",
"extra_fields": {}
}
```
| HTTP Code | QI Code `code` | Title `title` | Description (eng) `Description` | Description (ptbr) `translation` |
|-------------|----------------------|---------------------------------------------|-----------------------------------------------------|-------------------------------------------------------------------------------|
403 | APX000025 | User is not allowed to do this transaction | User is not allowed to do this transaction | Usuário não tem autorização para fazer essa transação |
| 403 | APX000017 | Requester not allowed to access this endpoint | Requester has no permission to perform pix transfers on this endpoint | Requester não possui permissão de realizar transações pix através deste endpoint |
| 404 | APX000020 | Account not Found | Account was not found | Conta \{account_key\} não foi encontrada. |
| 404 | APX000001 | Recurrence not Found | Recurrence was not found | Recorrência \{incoming_recurrence_key\} não foi encontrada |
---
# Create payment recurrence
URL: /en/documentation/baas/pix_automatico/movimentacoes/criar_recorrencia
## Request
ENDPOINT /account/ ACCOUNT_KEY /incoming_recurrence
METHOD POST
### Request Path Params
| Field | Type | Description | Characters |
|-------------|--------|--------------------------------|------------|
| `account_key` * | uuid4 | Unique account identification key. | 36 |
### Request Body
Request Body: Create fixed amount recurrence
```json
{
"request_control_key": "01585acf-b0c3-4389-baf3-a58abbe92d58",
"end_to_end_id": "E73856642202309201429bZKfklNlbwu",
"periodicity": "monthly",
"journey_type": "journey_one",
"start_date": "2025-04-01",
"end_date": "2027-04-01",
"target_pix_key": "pix_key@test.bcb.com",
"pix_message": "Informação do pagamento",
"is_retry_allowed": true,
"transaction_amount": 150.04
}
```
Request Body: Create variable amount recurrence
```json
{
"request_control_key": "12385acf-b0c3-4389-baf3-a58abbe92d58",
"end_to_end_id": "E73856642202309201429bZKfklNlbwu",
"periodicity": "monthly",
"journey_type": "journey_one",
"start_date": "2025-07-01",
"end_date": null,
"target_pix_key": "pix_key@test.bcb.com",
"pix_message": "Pagamento da conta de energia elétrica",
"is_retry_allowed": true,
"minimum_transaction_amount": 50.00,
"maximum_transaction_amount": 300.00
}
```
### Body Params
| Field | Type | Description | Characters |
|-------------------------|------------|--------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|------------|
| `request_control_key` * | uuid | Unique request identification key used by the client in uuid4 format. | 36 |
| `periodicity` * | enumerator | Type of periodicity associated with payment | [periodicity enumerators](#periodicity-enumerators) |
| `journey_type` * | enumerator | Type of request journey | [journey_type enumerators](#journey_type-enumerators) |
| `start_date` * | string | Recurrence start date | - |
| `end_to_end_id` * | string | Idempotency key for a Pix transaction within SPI (Instant Payment System). This key is returned in the Pix key query. | 32 |
| `target_pix_key` | string | Pix key of the account to which the transaction will be sent. | 100 |
| `target_account` | Object | Target account - Should only be sent for manual transfers. | [target_account object](#target_account-object) | 10 |
| `transaction_amount` | number | Transfer amount for fixed value occurrence. | 10 |
| `minimum_transaction_amount` | number | Minimum transfer amount for variable value occurrence. | 10 |
| `maximum_transaction_amount` | number | Maximum transfer amount for variable value occurrence. | 10 |
| `end_date` | string | Recurrence end date, for indefinite time cases, send as null | - |
| `pix_message` | string | Message to be sent with the Pix transfer. | 140 |
| `is_retry_allowed` | boolean | Permission for Pix transaction retry. | - |
### periodicity enumerators
| Enumerator | Description |
|------------------|--------------------|
| `weekly` | Weekly recurrence |
| `monthly` | Monthly recurrence |
| `quarterly` | Quarterly recurrence |
| `semiannual` | Semi-annual recurrence |
| `annual` | Annual recurrence |
### journey_type enumerators
| Enumerator | Description |
|------------------|--------------------|
| `journey_one` | Authorization request through an app notification |
| `journey_two` | Authorization request through QR Code reading |
| `journey_three` | Recurrence authorization through an immediate pix via QR Code reading |
| `journey_four` | Payment or scheduling of a pix with a recurrence authorization request in sequence |
### target_account object
| Field | Type | Description | Characters |
|---------------------------|------------|-----------------------------------------------------|---------------------------------------------------------|
| `account_branch` | string | Account branch. | 6 |
| `account_digit` | string | Account digit. | 1 |
| `account_number` | string | Account number. | 20 |
| `owner_document_number` | string | CPF or CNPJ (numbers only) of the account holder. | 14 |
| `owner_name` | string | Account holder's name. | 150 |
| `account_type` | enumerator | Account type. | [account_type enumerator](#account_type-enumerator) |
| `ispb` | string | Based on the financial institution's CNPJ (8 digits). | 8 |
:::info
Different enumerators may mean the same account type due to information returned by different
institutions.
:::
### account_type enumerator
| Enumerator | Description |
|----------------------|---------------------|
| `checking_account` | Checking Account |
| `salary_account` | Salary Account |
| `saving_account` | Savings Account |
| `payment_account` | Payment Account |
## Response
STATUS 200
Response Body: Recurrence created
```json
{
"incoming_recurrence_key": "cfa32109-a6dd-4304-94db-03a7b6d92a47",
"incoming_recurrence_status": "pending_confirmation",
"created_at": "2025-05-22T20:30:23.459Z",
}
```
| Field | Type | Description | Max. Characters |
|--------------------------------|---------|-----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|-------------------------------------------------------------------|
| `incoming_recurrence_key` | uuid | Unique authorization identification key | 36 |
| `incoming_recurrence_status` | string |Recurrence status identifier | [incoming_recurrence_status enumerator](#incoming_recurrence_status-enumerator) |
| `created_at` | string | Recurrence request creation time | -
### incoming_recurrence_status enumerator
| Enumerator | Description |
|----------------------|---------------------|
| **pending_confirmation** | Recurrence pending confirmation |
| **active** | Active recurrence |
| **cancelled** | Cancelled recurrence |
| **suspended** | Suspended recurrence |
| **expired** | Expired recurrence |
STATUS 4XX
Response Body
```json
{
"title": "titulo",
"description": "description in English",
"translation": "descrição em portugues",
"code": "codigo"
}
```
| HTTP Code | QI Code `code` | Title `title` | Description (eng) `Description` | Description (ptbr) `translation` |
|-------------|----------------------|------------------------------|---------------------------------------------------------------------|-------------------------------------------------------------------|
| 400 | QIT000001 | Bad Request | Schema Error | Erro de Schema |
| 403 | APX000025 | User is not allowed to do this transaction | User is not allowed to do this transaction | Usuário não tem autorização para fazer essa transação |
| 403 | APX000017 | Requester not allowed to access this endpoint | Requester has no permission to perform pix transfers on this endpoint | Requester não possui permissão de realizar transações pix através deste endpoint |
| 404 | APX000020 | Account not Found | Account was not found | Conta \{account_key\} não foi encontrada. |
| 406 | APX000026 | Invalid end_to_end_id | The end_to_end_id sent \{end_to_end_id\} is not valid. | O end_to_end_id enviado \{end_to_end_id\} não é válido |
| 406 | APX000005 | Invalid Transaction Amount | Transaction amount of \{transaction_amount\} is not valid. It must be a positive value with at maximum 2 decimal places | O valor de transação \{transaction_amount\} não é válido. Deve ser um valor positivo com no máximo duas casas decimais |
| 409 | APX000013 | Request Control Key Reuse Error | The request_control_key \{request_control_key\} already in use | A request_control_key \{request_control_key\} já utilizada |
---
# Recurrence Listing
URL: /en/documentation/baas/pix_automatico/movimentacoes/listar_recorrencias
## Pix recurrence listing for an account
### Request
ENDPOINT /account/ ACCOUNT_KEY /incoming_recurrences
METHOD GET
### Path Params
| Field | Type | Description | Characters |
|----------------------------|------------|-------------------------------------------------------|-----------------------------------------------------------------------------|
| `account_key` * | uuid4 | Unique identification key of the QI account. | 36 |
### Query Params
| Field | Type | Description | Characters |
|--------------------------|------------|------------------------------------------------------------------------------------------------------------|-----------------------------------------------------------------------------|
| `request_control_key` | uuid4 | Unique identification key of the request used by the client. | 36 |
| `status` | string | Pix recurrence status identifier | [Status enumerator](#status-enumerator) |
| `date_from` | string | Start date for listing filter. | Format "YYYY-MM-DD" |
| `date_to` | string | End date for listing filter. | Format "YYYY-MM-DD" |
| `page` | integer | Requested page number. | Default 1 |
| `page_size` | integer | Requested page size for the query. | Default and maximum value of 30
### Status enumerator
| Enumerator | Description |
|----------------------|---------------------|
| `pending_confirmation` | Recurrence pending confirmation |
| `active` | Active recurrence |
| `cancelled` | Cancelled recurrence |
| `suspended` | Suspended recurrence |
| `expired` | Expired recurrence |
### Response
STATUS 200
Response Body: Recurrence listing
```json
{
"data": [
{
"incoming_recurrence_key": "c2f3eefa-1b8e-4d5f-9b9d-123456789abc",
"incoming_recurrence_status": "pending_confirmation",
"request_control_key": "e04197f6-433e-48d2-8a8e-9258a70aba0b",
"transaction_amount": "150.00",
"periodicity": "monthly",
"journey_type": "journey_one",
"pix_transfer_type": "key",
"end_to_end_id": "E1234567890123456789012",
"start_date": "2025-06-01",
"end_date": "2026-06-01",
"next_execution_date": "2025-07-01",
"receiver_conciliation_id": "rec-conc-789",
"target_pix_key": "receiver@bank.com.br",
"payer_document_number": "12345678900",
"pix_message": "Pagamento mensal de serviço",
"created_at": "2025-05-22T10:00:00Z",
"updated_at": "2025-05-22T12:00:00Z"
}
],
"pagination": {
"current_page": 1,
"rows_per_page": 30
}
}
```
STATUS 4xx
Response Body: Error
```json
{
"title": "titulo",
"description": "description in English",
"translation": "descrição em portugues",
"code": "codigo",
"extra_fields": {}
}
```
| HTTP Code | QI Code `code` | Title `title` | Description (eng) `Description` | Description (ptbr) `translation` |
|-------------|----------------------|---------------------------------------------|-----------------------------------------------------|-------------------------------------------------------------------------------|
403 | APX000025 | User is not allowed to do this transaction | User is not allowed to do this transaction | Usuário não tem autorização para fazer essa transação |
| 403 | APX000017 | Requester not allowed to access this endpoint | Requester has no permission to perform pix transfers on this endpoint | Requester não possui permissão de realizar transações pix através deste endpoint |
| 404 | APX000020 | Account not Found | Account was not found | Conta \{account_key\} não foi encontrada. |
---
# Scenario simulation
URL: /en/documentation/baas/pix_automatico/movimentacoes/simulacao
Step-by-step guide to simulate the creation of recurrences and automatic payments within the scope of PIX Automático. These simulations include creating recurrences and creating scheduled payments.
## 1 - Recurrence creation simulation
### Request
ENDPOINT /mock/incoming_recurrence
METHOD POST
Request Body: Fixed amount recurrence
```json
{
"request_control_key": "01585acf-b0c3-4389-baf3-a58abbe92d58",
"recurrence_type": "fixed_amount",
"transaction_amount": 100.50,
"periodicity": "monthly",
"journey_type": "journey_one",
"start_date": "2025-07-01",
"is_retry_allowed": true,
"payer_account_information": {
"owner_name": "John Doe",
"document_number": "06975239000136",
"ispb": "32402502",
"account_digit": "7",
"account_branch": "3",
"account_number": "9552432"
}
```
Request Body: Variable amount recurrence
```json
{
"request_control_key": "01585acf-b0c3-4389-baf3-a58abbe92d58",
"recurrence_type": "variable_amount",
"minimum_transaction_amount": 50.00,
"periodicity": "monthly",
"journey_type": "journey_one",
"start_date": "2025-07-01",
"is_retry_allowed": true,
"payer_account_information": {
"owner_name": "John Doe",
"document_number": "06975239000136",
"ispb": "32402502",
"account_digit": "7",
"account_branch": "3",
"account_number": "9552432"}
```
### Request Body Object
| Field | Type | Description | Max. Char. |
|--------------------------------|----------------|--------------------------------------------------------------|--------------|
| **request_control_key*** | string | Unique request identification key in uuid4 format | 36 |
| **recurrence_type*** | string | Recurrence type (fixed_amount or variable_amount) | 20 |
| **transaction_amount** | number, null | Transaction amount for fixed amount recurrence (fixed_amount) | 10 |
| **minimum_transaction_amount** | number, null | Minimum transaction amount for variable amount recurrence (variable_amount) | 10 |
| **periodicity*** | string | Recurrence periodicity | 20 |
| **journey_type*** | string | Authorization journey type | 50 |
| **start_date*** | string | Recurrence start date (YYYY-MM-DD format) | 10 |
| **end_date** | string, null | Recurrence end date (YYYY-MM-DD format) | 10 |
| **is_retry_allowed*** | boolean | Transaction retry permission | - |
| **payer_account_information*** | object | Payer account data | - |
| **pix_message** | string, null | PIX message associated with the transaction | 140 |
:::caution Note
At least one of the fields `transaction_amount` or `minimum_transaction_amount` must be provided with a non-null value. Both fields cannot be null simultaneously.
:::
### payer_account_information Object
| Field | Type | Description | Max. Char. |
|----------------------------|--------|-----------------------------------------------------|--------------|
| **owner_name*** | string | Account holder name | 150 |
| **document_number*** | string | Account holder CPF or CNPJ (numbers only) | 14 |
| **ispb*** | string | Financial institution ISPB code | 8 |
| **account_digit*** | string | Account digit | 1 |
| **account_branch*** | string | Account branch | 6 |
| **account_number*** | string | Account number | 20 |
:::info Recurrence Types
- **Fixed amount recurrence (fixed_amount)**: Use the `transaction_amount` field and do not send `minimum_transaction_amount`
- **Variable amount recurrence (variable_amount)**: Use the `minimum_transaction_amount` field and do not send `transaction_amount`
:::
## Response
STATUS 200
Response Body
```json
{
"incoming_recurrence_key": "e13c5986-f4d1-4d07-a56b-eda90862630a",
"incoming_recurrence_spi_id": "RR32402502202507170197A5B7CB9",
"incoming_recurrence_status": "pending_confirmation",
"created_at": "2025-07-17T14:44:38Z",
"account_key": "ba685cfd-3aee-4992-b6bf-58f8038faa6b"
}
```
### Response Body
| Field | Type | Description | Characters |
|-------------------------------|------------|--------------------------------------------------------------|------------|
| `incoming_recurrence_key` | uuid | Unique incoming recurrence identification key | 36 |
| `incoming_recurrence_spi_id` | string | Incoming recurrence SPI identifier | 29 |
| `incoming_recurrence_status` | enumerator | Current incoming recurrence status | [incoming_recurrence_status Enumerators](#incoming_recurrence_status-enumerators) |
| `created_at` | string | Recurrence creation date and time (ISO 8601 format) | - |
| `account_key` | uuid | Unique account identification key | 36 |
### incoming_recurrence_status Enumerators
| Enumerator | Description |
|-------------------------|------------------------------------|
| `pending_confirmation` | Recurrence pending confirmation |
| `active` | Active recurrence |
| `cancelled` | Cancelled recurrence |
| `suspended` | Suspended recurrence |
| `expired` | Expired recurrence |
## 2 - Payment creation simulation
### Request
ENDPOINT /mock/incoming_recurrence/ INCOMING_RECURRENCE_SPI_ID /outgoing_payment
METHOD POST
Request Body
```json
{
"transaction_amount": 100.50,
"target_account_data": {
"owner_name": "John Doe",
"owner_document_number": "06975239000136",
"ispb": "32402502",
"account_digit": "7",
"account_branch": "3",
"account_type": "checking_account",
"account_number": "9552432"
},
"receiver_conciliation_id": "3d7d6a2bf72f44z7bb2079a2b94dff56452",
"outgoing_payment_spi_id": "7d2d1b6cd72f44z7bb2079a2b94dff52673",
"end_to_end_id": "E60701190202110191604DY5LHIZ9O66",
"next_execution_datetime": "2023-06-01"
}
```
### Request Body Object
| Field | Type | Description | Max. Char. |
|-------------------------------|--------|--------------------------------------------------------------|--------------|
| **transaction_amount*** | number | Transaction amount | 10 |
| **target_account_data** | object | Target account data | - |
| **receiver_conciliation_id*** | string | Receiver conciliation identification | 35 |
| **outgoing_payment_spi_id*** | string | Payment SPI identifier | 20 |
| **end_to_end_id*** | string | PIX transaction idempotency key in SPI | 32 |
| **next_execution_datetime** | string | Next execution date and time (YYYY-MM-DD format) | 10 |
### target_account_data Object
| Field | Type | Description | Max. Char. |
|----------------------------|--------|-----------------------------------------------------|--------------|
| **owner_name*** | string | Account holder name | 150 |
| **owner_document_number*** | string | Account holder CPF or CNPJ (numbers only) | 14 |
| **ispb_number*** | string | Financial institution ISPB code | 8 |
| **account_digit*** | string | Account digit | 1 |
| **account_branch*** | string | Account branch | 6 |
| **account_type*** | string | Account type | 20 |
| **account_number*** | string | Account number | 20 |
### account_type Enumerator
| Enumerator | Description |
|----------------------|---------------------|
| **checking_account** | Checking Account |
| **salary_account** | Salary Account |
| **saving_account** | Savings Account |
| **payment_account** | Payment Account |
### periodicity Enumerators
| Enumerator | Description |
|---------------|-----------------------|
| **weekly** | Weekly recurrence |
| **monthly** | Monthly recurrence |
| **quarterly** | Quarterly recurrence |
| **semiannual**| Semiannual recurrence |
| **annual** | Annual recurrence |
### journey_type Enumerators
| Enumerator | Description |
|--------------------------------|------------------------------------------------------------------------------|
| **journey_one** | Authorization request via app notification |
| **journey_two** | Authorization request via QR Code reading |
| **journey_three** | Recurrence authorization through an immediate pix via QR Code reading |
| **journey_four** | Payment or scheduling of a pix with a recurrence authorization request in sequence |
---
# Webhooks
URL: /en/documentation/baas/pix_automatico/movimentacoes/webhooks
Once transfers occur asynchronously, proper mapping and handling of sent webhooks is of utmost importance.
:::danger Attention!
QI Tech webhooks should not be mapped in a restrictive manner.
Additional fields may be included in webhook payloads returned by our APIs.
:::
## Webhook for Automatic PIX recurrence creation
Webhook intended with information about customer recurrence creation
### Webhook Request Body
Request Body: Recurrence creation
```json
{
"webhook_type": "baas.automatic_pix.incoming_recurrence",
"webhook_datetime": "2025-10-22T20:30:23.459Z",
"data": {
"account_key": "13385acf-b0c3-4389-baf3-a58abbe92d58",
"incoming_recurrence_key": "12385acf-b0c3-4389-baf3-a58abbe92d58",
"incoming_recurrence_status": "pending_confirmation",
"transaction_amount": "150.00",
"periodicity": "monthly",
"journey_type": "journey_one",
"pix_transfer_type": "key",
"end_to_end_id": "E1234567890123456789012",
"start_date": "2025-06-01",
"end_date": "2026-06-01",
"receiver_conciliation_id": "rec-conc-789",
"target_pix_key": "receiver@bank.com.br",
"payer_document_number": "12345678900",
"pix_message": "Pagamento mensal de serviço",
"created_at": "2025-05-22T10:00:00Z",
"updated_at": "2025-05-22T12:00:00Z"
}
}
```
### Webhook Body Param
| Field | Type | Description | Max. Characters |
|------------------------------|-----------|----------------------------------------------------------------------------------------------------------|-----------------|
| `webhook_type` | string | An enumerator that defines the type of event being reported | 23 |
| `webhook_datetime` | string | Date and time of webhook sending | 20 |
| `account_key` | uuid4 | Unique account identification key. | 36 |
| `incoming_recurrence_key` | uuid4 | Unique authorization identification key | 36 |
| `incoming_recurrence_status` | string | PIX recurrence status identifier. | [incoming_recurrence_status enumerators](#incoming_recurrence_status-enumerators) |
| `transaction_amount` | number | Transfer amount for fixed value occurrence. | 10 |
| `minimum_transaction_amount` | number | Minimum transfer amount for variable value occurrence. | 10 |
| `maximum_transaction_amount` | number | Maximum transfer amount for variable value occurrence. | 10 |
| `periodicity` | enum | Type of periodicity associated with the payment | [periodicity enumerators](#periodicity-enumerators) |
| `journey_type` | enum | Type of request journey | [journey_type enumerators](#journey_type-enumerators) |
| `pix_transfer_type` | enum | Type of PIX to be performed | [pix_transfer_type enumerators](#pix_transfer_type-enumerators) |
| `end_to_end_id` | string | Idempotency key of a PIX transaction within SPI. | 32 |
| `start_date` | string | Recurrence start date | - |
| `end_date` | string | Recurrence end date, for indefinite time cases, send as null | - |
| `receiver_conciliation_id` | string | Receiver conciliation identification. | 35 |
| `target_pix_key` | string | PIX key of the transaction account. | 100 |
| `payer_document_number` | string | Transaction payer's document number | 14 |
| `pix_message` | string | Message to be sent along with the PIX transfer. | 140 |
| `created_at` | string | Recurrence request creation time | - |
| `updated_at` | string | Recurrence request update time | - |
### incoming_recurrence_status Enumerators
| Enumerator | Description |
|----------------------|---------------------|
| `pending_confirmation` | Recurrence pending confirmation |
| `active` | Active recurrence |
| `cancelled` | Cancelled recurrence |
| `suspended` | Suspended recurrence |
| `expired` | Expired recurrence |
### periodicity Enumerators
| Enumerator | Description |
|------------------|--------------------|
| `weekly` | Weekly recurrence |
| `monthly` | Monthly recurrence |
| `quarterly` | Quarterly recurrence |
| `semiannual` | Semiannual recurrence |
| `annual` | Annual recurrence |
### journey_type Enumerators
| Enumerator | Description |
|------------------|--------------------|
| `journey_one` | Authorization request through an app notification |
| `journey_two` | Authorization request through QR Code reading |
| `journey_three` | Recurrence authorization through an immediate PIX via QR Code reading |
| `journey_four` | Payment or scheduling of a PIX with a recurrence authorization request in sequence |
### pix_transfer_type Enumerators
| Enumerator | Description |
|---------------------|------------------------------------------|
| `manual` | PIX using destination account data |
| `key` | PIX using a PIX key |
| `static_qr_code` | PIX using a static QR code |
| `dynamic_qr_code` | PIX using a dynamic QR code |
[//]: # (Break here for new page -----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------)
---
# Update Payment Order Value
URL: /en/documentation/baas/pix_automatico/pagamentos/atualizar_payment_order
## Request
ENDPOINT /account/ ACCOUNT_KEY /outgoing_recurrence/ OUTGOING_RECURRENCE_KEY /payment_order/ PAYMENT_ORDER_KEY
METHOD PATCH
### Path Params
| Field | Type | Description | Characters |
|--------------------------|--------|----------------------------------------------------|------------|
| `ACCOUNT_KEY` | uuidv4 | Unique account identification key. | 36 |
| `OUTGOING_RECURRENCE_KEY`| uuidv4 | Unique key of the recurrence to be updated. | 36 |
| `PAYMENT_ORDER_KEY` | uuidv4 | Unique key of the payment order to be updated. | 36 |
### Request Body
Update Payment Order
```json
{
"transaction_amount": 100
}
```
### Request Body Params
| Field | Type | Description | Characters |
|----------------------|----------|------------------------------------|------------|
| `transaction_amount` | floating | Transaction amount to be updated. | - |
## Response
STATUS 200
Response Body
```json
{}
```
STATUS 4XX
Response Error
```json
{
"title": "titulo",
"description": "description in English",
"translation": "descrição em português",
"code": "codigo"
}
```
| HTTP Code | QI Code `code` | Title `title` | Description (eng) `description` | Description (ptbr) `translation` |
|-------------|----------------------|-----------------------------------|----------------------------------------------------------------------------|--------------------------------------------------------------------|
| 400 | QIT000002 | Bad Request | Invalid request schema. | Erro no esquema da requisição. |
| 404 | APX000404 | Payment Order Not Found | Payment Order \{payment_order_key\} not found. | Lote de conciliação \{payment_order_key\} não encontrado. |
---
# Cancel a Payment Order
URL: /en/documentation/baas/pix_automatico/pagamentos/cancelar_payment_order
This endpoint allows canceling a specific payment order associated with an automatic Pix recurrence.
:::warning
It is only possible to cancel a payment order that has pending_conciliation or pending status, until 10 PM on the day before the reference_date.
:::
## Request
ENDPOINT /automatic_pix/account/ ACCOUNT_KEY /outgoing_recurrence/ OUTGOING_RECURRENCE_KEY /payment_order/ PAYMENT_ORDER_KEY /cancel
METHOD PATCH
### Path Params
| Field | Type | Description | Characters |
|--------------------------|--------|----------------------------------------------------|------------|
| `ACCOUNT_KEY` | uuidv4 | Unique account identification key. | 36 |
| `OUTGOING_RECURRENCE_KEY`| uuidv4 | Unique recurrence key. | 36 |
| `PAYMENT_ORDER_KEY` | uuidv4 | Unique key of the payment order to be canceled. | 36 |
### Request Body
Cancel Payment Order
```json
{}
```
## Response
STATUS 200
Response Body
```json
{
"payment_order_key": "10fc62fd-b0a0-4604-9bea-475e91a9dc82",
"payment_order_conciliation_batch_key": "11fc62fd-b0a0-4604-9bea-475e91a9dc82",
"payment_order_status": "cancelled"
}
```
### Response Body Params
| Field | Type | Description | Characters |
|----------------------------------------|--------|----------------------------------------------------|------------|
| `payment_order_key` | string | Unique key of the payment order. | 36 |
| `payment_order_conciliation_batch_key` | string | Key of the payment order conciliation batch. | 36 |
| `payment_order_status` | string | Current status of the payment order. | - |
### payment_order_status Enumerators
| Enumerator | Description |
|-----------------------|----------------------------------------------------|
| `pending_conciliation`| Awaiting conciliation. |
| `pending` | Pending and not yet processed. |
| `accepted` | Accepted and awaiting payment. |
| `paid` | Successfully paid. |
| `rejected` | Rejected and will not be processed. |
| `cancelled` | Canceled before payment. |
STATUS 4XX
Response Error
```json
{
"title": "titulo",
"description": "description in English",
"translation": "descrição em português",
"code": "codigo"
}
```
| HTTP Code | QI Code `code` | Title `title` | Description (eng) `description` | Description (ptbr) `translation` |
|-------------|----------------------|-----------------------------------|----------------------------------------------------------------------------|--------------------------------------------------------------------|
| 400 | QIT000002 | Bad Request | Invalid request schema. | Erro no esquema da requisição. |
| 404 | APX000404 | Payment Order Not Found | Payment Order \{payment_order_key\} not found. | Lote de conciliação \{payment_order_key\} não encontrado. |
---
# Query Payment Order
URL: /en/documentation/baas/pix_automatico/pagamentos/consultar_payment_order
## Request
This endpoint allows querying the details of a specific payment order associated with an automatic Pix recurrence.
ENDPOINT /account/ ACCOUNT_KEY /outgoing_recurrence/ OUTGOING_RECURRENCE_KEY /payment_order/ PAYMENT_ORDER_KEY
METHOD GET
### Path Params
| Field | Type | Description | Characters |
|--------------------------|--------|---------------------------------------------------|------------|
| `account_key` | uuidv4 | Unique account identification key. | 36 |
| `outgoing_recurrence_key`| uuidv4 | Unique key of the recurrence to be queried. | 36 |
| `payment_order_key` | uuidv4 | Unique key of the payment order to be queried. | 36 |
## Response Body
STATUS 200
Response Body
```json
{
"outgoing_recurrence_spi_id": "RR2222222220240429njua7shf40k",
"payment_order_status": "paid",
"reference_date": "2025-06-30",
"payment_order_conciliation_batch_key": "21fc62fd-b0a0-4604-9bea-475e91a9dc82",
"receiver_conciliation_id": "cac0b5f7-4ee2-40f1-b2ad-16902506503d",
"transaction_amount": 125.53,
"transaction_key": "21fc62fd-b0a0-4604-9bea-475e91a9dc56",
"incoming_pix_transfer_key": "21fc62fd-b0a0-4604-9bea-475e91a9dc56",
"debtor_account_data": {
"account_number": "897465",
"account_digit": "1",
"account_branch": "0123",
"ispb": "323243"
},
"created_at": "2021-10-22T20:30:23.459Z",
"paid_at": "2023-10-22T20:30:23.459Z",
"payment_order_attempts": [
{
"payment_order_attempt_key": "uuid",
"end_to_end_id": "id",
"payment_order_attempt_status": "sent",
"payment_order_attempt_error": {
"code": "code",
"description": "description do error",
"translation": "translation"
},
"created_at": "2021-10-22T20:30:23.459Z"
}
]
}
```
### Response Body Params
| Field | Type | Description | Characters |
|------------------------------------|----------|---------------------------------------------------------------------------|------------|
| `outgoing_recurrence_spi_id` | string | SPI ID of the automatic recurrence. | 36 |
| `payment_order_status` | string | Current status of the payment order. |[payment_order_status Enumerators](#payment_order_status) |
| `reference_date` | string | Reference date of the charge. | 10 |
| `payment_order_conciliation_batch_key`| uuidv4 | Conciliation batch key of the payment order. | 36 |
| `receiver_conciliation_id` | uuidv4 | Receiver conciliation ID. | 36 |
| `transaction_amount` | number | Transaction amount. | - |
| `transaction_key` | uuidv4 | Unique transaction key. | 36 |
| `incoming_pix_transfer_key` | uuidv4 | Incoming Pix transfer key. | 36 |
| `debtor_account_data` | object | Debtor account data. | [debtor_account_data Object](#debtor_account_data-object) |
| `created_at` | string | Order creation date/time. | - |
| `paid_at` | string | Payment completion date/time. | - |
| `payment_order_attempts` | array | Payment attempts for the order. | [payment_order_attempts Array](#payment_order_attempts-array) |
### debtor_account_data Object
| Field | Type | Description | Characters |
|------------------|--------|----------------------------|------------|
| `account_number` | string | Account number | - |
| `account_digit` | string | Account digit | - |
| `account_branch` | string | Branch | - |
| `ispb` | string | Financial institution ISPB | - |
### payment_order_attempts Array
| Field | Type | Description | Characters |
|------------------------------|----------|----------------------------------------------------------------|------------|
| `payment_order_attempt_key` | string | Unique key of the payment attempt. | 36 |
| `end_to_end_id` | string | End-to-end identifier of the attempt. | 36 |
| `payment_order_attempt_status`| string | Status of the payment attempt. | - |
| `payment_order_attempt_error`| object | Error associated with the payment attempt. | [payment_order_attempt_error Object](#payment_order_attempt_error-object) |
| `created_at` | string | Attempt creation date/time. | - |
### payment_order_attempt_error Object
| Field | Type | Description | Characters |
|-------------|--------|-----------------------|------------|
| `code` | string | Error code. | - |
| `description`| string | Error description. | - |
| `translation`| string | Description translation. | - |
### payment_order_status Enumerators
| Enumerator | Description |
|-----------------------|----------------------------------------------------|
| `pending_conciliation`| Awaiting conciliation. |
| `pending` | Pending and not yet processed. |
| `accepted` | Accepted and awaiting payment. |
| `paid` | Successfully paid. |
| `rejected` | Rejected and will not be processed. |
| `cancelled` | Cancelled before payment. |
STATUS 4XX
Response Error
```json
{
"title": "titulo",
"description": "description in English",
"translation": "descrição em português",
"code": "codigo"
}
```
| HTTP Code | QI Code `code` | Title `title` | Description (eng) `description` | Description (ptbr) `translation` |
|-------------|----------------------|-----------------------------------|----------------------------------------------------------------------------|--------------------------------------------------------------------|
| 400 | QIT000002 | Bad Request | Invalid request schema. | Erro no esquema da requisição. |
| 404 | APX000002 | Payment Order Not Found | Payment order \{payment_order_key\} not found. | Ordem de pagamento \{payment_order_key\} não encontrada. |
---
# List Payment Orders by Account
URL: /en/documentation/baas/pix_automatico/pagamentos/listar_account_payment_orders
This endpoint allows listing payment orders associated with a specific account.
ENDPOINT /account/ ACCOUNT_KEY /payment_orders
METHOD GET
### Path Params
| Field | Type | Description | Characters |
|--------------|--------|----------------------------------------------------|------------|
| `account_key`| uuidv4 | Unique account identification key. | 36 |
### Query Params
| Field | Type | Description | Characters |
|----------------------|--------|--------------------------------------------------|------------|
| `payment_order_status`| string | Filters orders by status (e.g., `paid`). | - |
| `start_date` | string | Start date to filter orders (YYYY-MM-DD format). | 10 |
| `end_date` | string | End date to filter orders (YYYY-MM-DD format). | 10 |
## Response Body
STATUS 200
Response Body
```json
{
"payment_orders": [
{
"payment_order_key": "a1b2c3d4-e5f6-4789-a123-456789abcdef",
"payment_order_spi_id": "1a2b3c4d5e6f7890abcdef1234567890",
"outgoing_recurrence_key": "b2c3d4e5-f6a7-4890-b234-567890abcdef",
"outgoing_recurrence_spi_id": "RR3240250220251025A1B2C3D4E5F",
"payment_order_conciliation_batch_key": "c3d4e5f6-a7b8-4901-c345-678901abcdef",
"payment_order_status": "pending_conciliation",
"reference_date": "2025-11-15",
"receiver_conciliation_id": "2b3c4d5e6f7890abcdef1234567890ab",
"transaction_amount": null,
"account_key": "d4e5f6a7-b8c9-4012-d456-789012abcdef",
"transaction_key": null,
"incoming_pix_transfer_key": null,
"debtor_account_data": {
"ispb": "31872495",
"account_digit": "7",
"account_branch": "0001",
"account_number": "123456"
},
"created_at": "2025-10-15T03:00:12Z",
"paid_at": null,
"payment_order_attempts": []
},
{
"payment_order_key": "e5f6a7b8-c9d0-4123-e567-890123abcdef",
"payment_order_spi_id": "3c4d5e6f7890abcdef1234567890abcd",
"outgoing_recurrence_key": "f6a7b8c9-d0e1-4234-f678-901234abcdef",
"outgoing_recurrence_spi_id": "RR3240250220251025B2C3D4E5F6A",
"payment_order_conciliation_batch_key": "c3d4e5f6-a7b8-4901-c345-678901abcdef",
"payment_order_status": "pending",
"reference_date": "2025-11-15",
"receiver_conciliation_id": "4d5e6f7890abcdef1234567890abcdef",
"transaction_amount": 220.00,
"account_key": "d4e5f6a7-b8c9-4012-d456-789012abcdef",
"transaction_key": null,
"incoming_pix_transfer_key": null,
"debtor_account_data": {
"ispb": "31872495",
"account_digit": "7",
"account_branch": "0001",
"account_number": "123456"
},
"created_at": "2025-10-15T03:00:10Z",
"paid_at": null,
"payment_order_attempts": []
}
],
"pagination": {
"page": 1,
"page_size": 25,
"number_of_pages": 9
}
}
```
### Response Body Params
| Field | Type | Description | Characters |
|----------------------------------------|----------|---------------------------------------------------------------------|------------|
| `payment_order_key` | uuidv4 | Unique payment order key. | 36 |
| `payment_order_spi_id` | string | Payment order SPI ID. | 32 |
| `outgoing_recurrence_key` | uuidv4 | Unique outgoing recurrence key. | 36 |
| `outgoing_recurrence_spi_id` | string | Automatic recurrence SPI ID. | 27 |
| `payment_order_conciliation_batch_key` | uuidv4 | Payment order conciliation batch key. | 36 |
| `payment_order_status` | string | Current payment order status. | - |
| `reference_date` | string | Charge reference date. | 10 |
| `receiver_conciliation_id` | string | Receiver conciliation ID. | 32 |
| `transaction_amount` | number | Transaction amount (can be null). | - |
| `account_key` | uuidv4 | Unique account key. | 36 |
| `transaction_key` | uuidv4 | Unique transaction key (can be null). | 36 |
| `incoming_pix_transfer_key` | uuidv4 | Incoming PIX transfer key (can be null). | 36 |
| `debtor_account_data` | object | Debtor account data. | [debtor_account_data Object](#debtor_account_data-object) |
| `created_at` | string | Order creation date/time (ISO 8601 format). | - |
| `paid_at` | string | Payment completion date/time (ISO 8601 format, can be null). | - |
| `payment_order_attempts` | array | Payment order attempts. | [payment_order_attempts Array](#payment_order_attempts-array) |
### debtor_account_data Object
| Field | Type | Description | Characters |
|------------------|--------|--------------------------------|------------|
| `account_number` | string | Account number | - |
| `account_digit` | string | Account digit | - |
| `account_branch` | string | Branch | - |
| `ispb` | string | Financial institution ISPB | - |
### payment_order_attempts Array
| Field | Type | Description | Characters |
|------------------------------|----------|----------------------------------------------------------------|------------|
| `payment_order_attempt_key` | string | Unique payment attempt key. | 36 |
| `end_to_end_id` | string | End-to-end identifier for the attempt. | 32 |
| `due_date` | string | Attempt due date (YYYY-MM-DD format, can be null). | 10 |
| `payment_order_attempt_status`| string | Payment attempt status. | - |
| `payment_order_attempt_error`| object | Error associated with the payment attempt (can be null). | [payment_order_attempt_error Object](#payment_order_attempt_error-object) |
| `sent_at` | string | Attempt send date/time (ISO 8601 format, can be null). | - |
| `created_at` | string | Attempt creation date/time (ISO 8601 format). | - |
### payment_order_attempt_error Object
| Field | Type | Description | Characters |
|-------------|--------|--------------------------|------------|
| `code` | string | Error code. | - |
| `description`| string | Error description. | - |
| `translation`| string | Description translation. | - |
### payment_order_status Enumerators
| Enumerator | Description |
|-------------------------|----------------------------------------------------|
| `pending_conciliation` | Payment order is pending conciliation |
| `pending` | Payment order is pending |
| `accepted` | Payment order has been accepted |
| `paid` | Payment order has been paid |
| `rejected` | Payment order has been rejected |
| `cancelled` | Payment order has been cancelled |
STATUS 4XX
Response Error
```json
{
"title": "titulo",
"description": "description in English",
"translation": "descrição em português",
"code": "codigo"
}
```
| HTTP Code | QI Code `code` | Title `title` | Description (eng) `description` | Description (ptbr) `translation` |
|-------------|----------------------|-----------------------------------|----------------------------------------------------------------------------|--------------------------------------------------------------------|
| 400 | QIT000002 | Bad Request | Invalid request schema. | Erro no esquema da requisição. |
| 404 | APX000002 | Payment Order Not Found | Payment order \{payment_order_key\} not found. | Ordem de pagamento \{payment_order_key\} não encontrada. |
---
# Decode QR Code for Automatic PIX
URL: /en/documentation/baas/pix_automatico/qr_code/decodificar_qr_code
## Request
ENDPOINT /account/ ACCOUNT_KEY /qrcode/decode
METHOD POST
### Request Path Params
| Field | Type | Description | Characters |
|-------------|--------|--------------------------------|------------|
| `account_key` * | uuid4 | Unique account identification key. | 36 |
### Request Body
Request Body: Decode QR Code
```json
{
"qr_code_payload": "00020101021226840014br.gov.bcb.pix2562invoice.starkbank.com/v2/cobv/8b434df48c30482a81f7c936ae35cc87080400005303986540555.595802BR5925Stark Bank S.A.6015Sao Caetano do Sul62070503***80740014br.gov.bcb.pix2552pix.example.com/rec/2353c790eefb11eaadc10242ac120002630411FC"
}
```
### Body Params
| Field | Type | Description | Characters |
|-------------------------|------------|--------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|------------|
| `qr_code_payload` * | string | PIX Copy and Paste URL | - |
## Response
STATUS 200
Response Body: Decoded QR
```json
{
"end_to_end_id": "E32402502202303101532yCipbxgUnUj",
"qr_code_payload": "00020101021226840014br.gov.bcb.pix2562invoice.starkbank.com/v2/cobv/8b434df48c30482a81f7c936ae35cc87080400005303986540555.595802BR5925Stark Bank S.A.6015Sao Caetano do Sul62070503***80740014br.gov.bcb.pix2552pix.example.com/rec/2353c790eefb11eaadc10242ac120002630411FC",
"qr_code_key": "8c2c19bd-f260-4714-955c-956f3eaa30ca",
"qr_code_type": "dynamic_composed",
"qr_code_data": {
"incoming_recurrence": {
"incoming_recurrence_key": "67abc123-4567-89ab-cdef-1234567890ab",
"journey_type": "j2_recurrence_only_qrcode",
"incoming_recurrence_type": "variable_amount",
"incoming_recurrence_status": "pending_confirmation",
"start_date": "2024-08-01",
"end_date": null,
"periodicity": "weekly",
"target_pix_key": "teste.recorrencia@email.com.br",
"minimum_transaction_amount": "100.00",
"maximum_transaction_amount": "500.00",
"transaction_amount": null,
"is_retry_allowed": true,
"created_at": "2024-07-23T14:30:45.123Z",
"payer_document_number": "12345678901",
"payer_name": "João da Silva",
"payer_account_key": "a5d7e60f-1c9b-4b8a-9de7-6f3b919cc45d",
"request_control_key": "c7d7e60f-1c9b-4b8a-9de7-6f3b919cc45f",
"receiver_conciliation_id": "RRAUTOTESTE001",
"pix_message": "Autorização de débito mensal"
},
"payment_data": {
"request_control_key": "c7d7e60f-1c9b-4b8a-9de7-6f3b919cc45f",
"transaction_amount": "150.75",
"target_pix_key": "teste.recorrencia@email.com.br",
"target_account": null,
"receiver_conciliation_id": "fgnb4NTt7pOUBGfrcporERwVVqr0f8PWRfK",
"pix_message": "Assinatura mensal do serviço"
}
}
}
```
| Field | Type | Description | Max. Characters |
|--------------------------------|---------|-----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|-------------------------------------------------------------------|
| `end_to_end_id` | string | Idempotency key for a PIX transaction within the SPI (Instant Payment System). This key is returned when querying PIX keys. | 32 |
| `qr_code_payload` | string | PIX Copy and Paste URL | |
| `qr_code_key` | uuid4 | Unique QR code identification key | 36 |
`qr_code_data` | Object | QR code data | [qr_code_data Object](#qr_code_data-object) | 10 |
### qr_code_data Object
| Field | Type | Description | Characters |
|---------------------------|------------|-----------------------------------------------------|---------------------------------------------------------|
| `incoming_recurrence` | object | Recurrence identification object | [incoming_recurrence Object](#incoming_recurrence-object) |
| `payment_data` | object | Object with payment information for journey_types: *j3_payment_and_recurrence_qrcode*, *j4_recurrence_offer_post_payment* | [payment_data Object](#payment_data-object)
### incoming_recurrence Object
| Field | Type | Description | Characters |
|---------------------------|------------|-----------------------------------------------------|---------------------------------------------------------|
| `incoming_recurrence_key` | uuid4 | Unique authorization identification key | 36 |
| `incoming_recurrence_status` | string |Recurrence status identifier | [incoming_recurrence_status Enumerator](#incoming_recurrence_status-enumerator) |
| `request_control_key` | uuid4 | Unique request identification key used by the client | 36 |
| `transaction_amount` | number | Transfer amount for fixed value occurrence. | 10 |
| `minimum_transaction_amount` | number | Minimum transfer amount for variable value occurrence. | 10 |
| `maximum_transaction_amount` | number | Maximum transfer amount for variable value occurrence. | 10 |
| `periodicity` | enumerator | Type of periodicity associated with the payment | [periodicity Enumerators](#periodicity-enumerators) |
| `journey_type` | enumerator | Type of request journey | [journey_type Enumerators](#journey_type-enumerators) |
| `end_to_end_id` | string | Idempotency key for a PIX transaction within the SPI (Instant Payment System). This key is returned when querying PIX keys. | 32 |
| `start_date` | string | Recurrence start date | - |
| `end_date` | string | Recurrence end date, for indefinite time cases, send as null
| `next_execution_date` | string | Execution date for the next recurrence transaction | - |
| `receiver_conciliation_id` | string | Receiver reconciliation identification. | 35 |
| `target_pix_key` | string | PIX key for the transaction account. | 100 |
| `is_retry_allowed` | boolean | Permission for PIX transaction retry. | - |
| `payer_document_number` | string | Transaction payer document number. | 14 |
| `payer_name` | string | Transaction payer name. | - |
| `payer_account_key` | string | Transaction payer account identifier. | - |
| `pix_message` | string | Message to be sent along with the PIX transfer. | 140 |
| `created_at` | string | Recurrence request creation time | -
### payment_data Object
| Field | Type | Description | Characters |
|---------------------------|------------|-----------------------------------------------------|---------------------------------------------------------|
| `request_control_key` | uuid4 | Unique request identification key used by the client | 36 |
| `transaction_amount` | number | Transfer amount for fixed value occurrence. | 10 |
| `target_pix_key` | string | PIX key for the transaction account. | 100 |
| `target_account` | Object | Destination account for manual transfers. | [target_account Object](#target_account-object) | 10 |
| `receiver_conciliation_id` | string | Receiver reconciliation identification. | 35 |
| `pix_message` | string | Message to be sent along with the PIX transfer. | 140 |
### target_account Object
| Field | Type | Description | Characters |
|---------------------------|------------|-----------------------------------------------------|---------------------------------------------------------|
| `account_branch` | string | Account branch. | 6 |
| `account_digit` | string | Account digit. | 1 |
| `account_number` | string | Account number. | 20 |
| `owner_document_number` | string | CPF or CNPJ (numbers only) of the account holder. | 14 |
| `owner_name` | string | Account holder name. | 150 |
| `account_type` | enumerator | Account type. | [account_type Enumerator](#account_type-enumerator) |
| `ispb` | string | Based on the financial institution's CNPJ (8 digits). | 8 |
:::info
Different enumerators may represent the same account type due to information returned by different
institutions.
:::
### account_type Enumerator
| Enumerator | Description |
|----------------------|---------------------|
| `checking_account`| Checking Account |
| `salary_account` | Salary Account |
| `saving_account` | Savings Account |
| `payment_account` | Payment Account |
### incoming_recurrence_status Enumerator
| Enumerator | Description |
|----------------------|---------------------|
| **pending_confirmation** | Recurrence pending confirmation |
| **active** | Active recurrence |
| **cancelled** | Cancelled recurrence |
| **suspended** | Suspended recurrence |
| **expired** | Expired recurrence |
### periodicity Enumerators
| Enumerator | Description |
|------------------|--------------------|
| `weekly` | Weekly recurrence |
| `monthly` | Monthly recurrence |
| `quarterly` | Quarterly recurrence |
| `semiannual` | Semiannual recurrence |
| `annual` | Annual recurrence |
### journey_type Enumerators
| Enumerator | Description |
|------------------|--------------------|
| `j1_in_app_only_recurrence` | Authorization request through an in-app notification |
| `j2_recurrence_only_qrcode` | Authorization request through QR Code reading |
| `j3_payment_and_recurrence_qrcode` | Recurrence authorization through an immediate PIX by reading a QR Code |
| `j4_recurrence_offer_post_payment` | PIX payment or scheduling with a subsequent recurrence authorization request |
### pix_transfer_type Enumerators
| Enumerator | Description |
|---------------------|------------------------------------------|
| `manual` | PIX using destination account data |
| `key` | PIX using a PIX key |
| `static_qr_code` | PIX using a static QR code |
| `dynamic_qr_code` | PIX using a dynamic QR code |
STATUS 4XX
Response Body
```json
{
"title": "titulo",
"description": "description in English",
"translation": "descrição em portugues",
"code": "codigo"
}
```
| HTTP Code | QI Code `code` | Title `title` | Description (eng) `Description` | Description (ptbr) `translation` |
|-------------|----------------------|------------------------------|---------------------------------------------------------------------|-------------------------------------------------------------------|
| 400 | QIT000001 | Bad Request | Schema Error | Erro de Schema |
403 | APX000025 | User is not allowed to do this transaction | User is not allowed to do this transaction | Usuário não tem autorização para fazer essa transação |
| 403 | APX000017 | Requester not allowed to access this endpoint | Requester has no permission to perform pix transfers on this endpoint | Requester não possui permissão de realizar transações pix através deste endpoint |
| 404 | APX000020 | Account not Found | Account was not found | Conta \{account_key\} não foi encontrada. |
---
# Cancel payment recurrence
URL: /en/documentation/baas/pix_automatico/recebedor/cancelar_recorrencia
## Request
ENDPOINT /account/ ACCOUNT_KEY /outgoing_recurrence/ OUTGOING_RECURRENCE_KEY /cancel
METHOD PATCH
### Request Path Params
| Field | Type | Description | Characters |
|-------------|--------|--------------------------------|------------|
| `account_key` * | uuid4 | Unique account identification key. | 36 |
| `outgoing_recurrence_key` * | uuid4 | Unique authorization identification key | 36 |
### Request Body
Request Body: Cancel a recurrence
```json
{
"outgoing_recurrence_status": "cancelled",
}
```
### Body Params
| Field | Type | Description | Characters |
|-------------------------|------------|--------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|------------|
| `outgoing_recurrence_status` * | string | Pix recurrence status identifier. | cancelled |
## Response
STATUS 200
Response Body: Recurrence cancelled
```json
{
"outgoing_recurrence_key": "cfa32109-a6dd-4304-94db-03a7b6d92a47",
"outgoing_recurrence_status": "cancelled",
"created_at": "2025-05-22T20:30:23.459Z",
"updated_at": "2025-05-22T20:39:23.459Z"
}
```
STATUS 4XX
Response Body
```json
{
"title": "titulo",
"description": "description in English",
"translation": "descrição em portugues",
"code": "codigo"
}
```
| HTTP Code | QI Code `code` | Title `title` | Description (eng) `Description` | Description (ptbr) `translation` |
|-------------|----------------------|------------------------------|---------------------------------------------------------------------|-------------------------------------------------------------------|
| 400 | QIT000001 | Bad Request | Schema Error | Erro de Schema |
403 | APX000025 | User is not allowed to do this transaction | User is not allowed to do this transaction | Usuário não tem autorização para fazer essa transação |
| 403 | APX000017 | Requester not allowed to access this endpoint | Requester has no permission to perform pix transfers on this endpoint | Requester não possui permissão de realizar transações pix através deste endpoint |
| 404 | APX000020 | Account not Found | Account was not found | Conta \{account_key\} não foi encontrada. |
| 404 | APX000001 | Recurrence not Found | Recurrence was not found | Recorrência \{outgoing_recurrence_key\} não foi encontrada |
---
# Query data of a recurrence by outgoing_recurrence_key
URL: /en/documentation/baas/pix_automatico/recebedor/consultar_recorrencia
## Request
ENDPOINT /account/ ACCOUNT_KEY /outgoing_recurrence/ OUTGOING_RECURRENCE_KEY
METHOD GET
### Path Params
| Field | Type | Description | Characters |
|--------------------------|--------|---------------------------------------------------|------------|
| `account_key` * | uuidv4 | Unique account identification key. | 36 |
| `outgoing_recurrence_key`*| uuidv4 | Unique key of the recurrence to be queried. | 36 |
## Response
STATUS 200
Response Body
```json
{
"request_control_key":"98fc62fd-b0a0-4604-9bea-475e91a9dc82",
"outgoing_recurrence_key":"8cb70dea-9fb0-4a68-9572-99a72849c8d6",
"outgoing_recurrence_status":"approved",
"periodicity":"monthly",
"journey_type":"journey_four",
"start_date":"2025-06-10",
"end_date":"2027-06-10",
"outgoing_recurrence_data":{
"minimum_recurrence_amount":123.45,
"recurrence_amount":null,
"retry_configuration":{
"retry_allowed":true,
"retry_rule":{
"first_retry":{
"day":"1",
"time":"14:00"
},
"second_retry":{
"day":"3",
"time":"12:00"
},
"third_retry":{
"day":"4",
"time":"15:32"
}
}
},
"debtor_data":{
"name":"Sebastião",
"email":"sebastiao@test.com",
"document_number":"05431134850",
"address":{
"city":"São Paulo",
"postal_code":"123456-789",
"uf":"SP",
"street":"Av Paulista 123"
},
"account_data":{
"account_number":"123456",
"account_digit":"7",
"account_branch":"0001",
"ispb":"31872495"
}
},
"qr_code_data":{
"qr_code_key":"0f45cc3d-9bd1-4d68-a865-4cf477b5da45",
"qr_code_url":"urlqrcode.url",
"qr_code_image":"image_base64"
},
"initial_payment_data":{
"amount":22.34,
"pix_key":"3d7d6a2b-f72f-44z7-bb20-79a94dff5645",
"qr_code_type":"dynamic_term",
"additional_data":[
{
"key_name":"Juros e Multa",
"value":"Juros 2 ao mes e multa de 1%"
}
],
"fine_amount":3,
"interest_amount":2,
"expiration_date":"2023-03-25",
"max_payment_days":128,
"rebate_amount":1,
"discounts":[],
"receiver_conciliation_id":"3d7d6a2bf72f44z7bb2079a94dff5645",
"transaction_data":{
"transaction_key":"4d7d6a2b-f72f-44z7-bb20-79a94dff5645",
"pix_transfer_key":"5d7d6a2b-f72f-44z7-bb20-79a94dff5645",
"end_to_end_id":"E32402502202303141907qlBAF1evdJ2"
}
},
"pix_message":"Conta de Luz Residencial nº123",
"settlement_date_type":"calendar_days"
},
"payment_orders":[
{
"payment_order_key":"10fc62fd-b0a0-4604-9bea-475e91a9dc82",
"payment_order_status":"paid",
"reference_date":"2025-06-30",
"receiver_conciliation_id":"cac0b5f74ee240f1b2ad16902506503d",
"transaction_amount":125.53,
"transaction_key":"21fc62fd-b0a0-4604-9bea-475e91a9dc56",
"incoming_pix_transfer_key":"21fc62fd-b0a0-4604-9bea-475e91a9dc56",
"created_at":"2021-10-22T20:30:23.459Z",
"paid_at":"2023-10-22T20:30:23.459Z"
}
],
"outgoing_recurrence_events":[
{
"outgoing_recurrence_event_key":"20fc62fd-b0a0-4604-9bea-475e91a9dc82",
"outgoing_recurrence_status":"created",
"created_at":"2021-10-22T20:30:23.459Z"
}
]
}
```
### Response Body Params
| Field | Type | Description | Characters |
|------------------------------|------------|---------------------------------------------------------------------------------------------|------------|
| `request_control_key` | uuidv4 | Unique key for request control. | 36 |
| `outgoing_recurrence_key` | uuidv4 | Identifier of the automatic recurrence. | 36 |
| `outgoing_recurrence_status` | string | Current status of the recurrence (`approved`, `pending`, `rejected`, etc.). | 30 |
| `periodicity` | enumerator | Recurrence periodicity. | [periodicity Enumerators](#periodicity-enumerators) |
| `journey_type` | enumerator | Automatic recurrence journey. | [journey_type Enumerators](#journey_type-enumerators) |
| `start_date` | string | Recurrence start date (ISO 8601 format, e.g., `2025-06-10`). | 10 |
| `end_date` | string | Recurrence end date (ISO 8601 format) or null if indefinite. | 10 or null |
| `outgoing_recurrence_data` | object | Object grouping subscription parameters and additional data. | [outgoing_recurrence_data Object](#outgoing_recurrence_data-object) |
| `payment_orders` | array | Object grouping subscription parameters and additional data. | [payment_orders Object](#payment_orders-object) |
| `outgoing_recurrence_events` | array | Object grouping recurrence event parameters | [outgoing_recurrence_events Object](#outgoing_recurrence_events-object) |
### outgoing_recurrence_data Object
| Field | Type | Description | Characters |
|-----------------------------|----------|--------------------------------------------------------------------|------------|
| `minimum_recurrence_amount` | number | Minimum expected amount in variable amount recurrences | - |
| `recurrence_amount` | number | Recurrence amount (for fixed amount; null if variable) | - |
| `retry_configuration` | object | Retry configuration for incomplete recurrences | [retry_configuration Object](#retry_configuration-object) |
| `debtor_data` | object | Debtor (subscriber) data | [debtor_data Object](#debtor_data-object) |
| `qr_code_data` | object | QR Code data generated for payment (if any) | [qr_code_data Object](#qr_code_data-object) |
| `initial_payment_data` | object | Initial charge data | [initial_payment_data Object](#initial_payment_data-object) |
| `pix_message` | string | Message sent along with the PIX transaction | 140 |
| `settlement_date_type` | enumerator| Settlement date adjustment type | [settlement_date_type Enumerators](#settlement_date_type-enumerators) |
---
### retry_configuration Object
| Field | Type | Description | Characters |
|-----------------|---------|---------------------------------------------|------------|
| `retry_allowed` | boolean | Indicates if retries are enabled | - |
| `retry_rule` | object | Detailed retry rules | [retry_rule Object](#retry_rule-object) |
---
### retry_rule Object
| Field | Type | Description | Characters |
|---------------|--------|-----------------------------------|------------|
| `first_retry` | object | Configuration for 1st retry | [retry_detail Object](#retry_detail-object) |
| `second_retry`| object | Configuration for 2nd retry | [retry_detail Object](#retry_detail-object) |
| `third_retry` | object | Configuration for 3rd retry | [retry_detail Object](#retry_detail-object) |
---
### retry_detail Object
| Field | Type | Description | Characters |
|-------|--------|-------------------------|------------|
| `day` | string | Retry day. | - |
| `time`| string | Retry time. | - |
---
### debtor_data Object
| Field | Type | Description | Characters |
|-------------------|--------|------------------------|------------|
| `name` | string | Subscriber name. | 50 |
| `email` | string | Subscriber email. | 100 |
| `document_number` | string | CPF or CNPJ. | 14 |
| `address` | object | Subscriber address. | [address Object](#address-object) |
| `account_data` | object | Bank account data. | [account_data Object](#account_data-object) |
---
### address Object
| Field | Type | Description | Characters |
|---------------|--------|-------------------|------------|
| `city` | string | City. | - |
| `postal_code` | string | ZIP code. | - |
| `uf` | string | State (abbreviation). | - |
| `street` | string | Street address. | - |
---
### account_data Object
| Field | Type | Description | Characters |
|-----------------|--------|------------------------------|------------|
| `account_number`| string | Account number | - |
| `account_digit` | string | Account digit | - |
| `account_branch`| string | Branch | - |
| `ispb` | string | Financial institution ISPB| - |
---
### qr_code_data Object
| Field | Type | Description | Characters |
|------------------|--------|---------------------------------------------|------------|
| `qr_code_key` | string | Generated QR Code identifier | - |
| `qr_code_url` | string | URL for QR Code viewing | - |
| `qr_code_image` | string | QR Code image (Base64 encoded) | - |
---
### initial_payment_data Object
| Field | Type | Description | Characters |
|---------------------------|----------|--------------------------------------------------------------------------|------------|
| `amount` | number | Principal amount of the initial charge in reais (R$) | - |
| `pix_key` | string | Destination PIX key for initial payment | 77 |
| `qr_code_type` | enum | QR Code type for initial charge. | [qr_code_type Enumerators](#qr_code_type-enumerators) |
| `additional_data` | array | List of additional information related to the charge | [additional_data Array](#additional_data-array) |
| `fine_amount` | number | Fine amount in case of late payment | - |
| `interest_amount` | number | Interest amount in case of late payment | - |
| `expiration_date` | string | Initial charge expiration date (ISO 8601 format) | 10 |
| `max_payment_days` | integer | Maximum number of acceptance days after expiration | - |
| `rebate_amount` | number | Discount amount for early payment | - |
| `discounts` | array | List of additional discounts | - |
| `receiver_conciliation_id`| string | Payment conciliation identifier by the receiver | 35 |
| `transaction_data` | object | Transaction details related to the initial charge | [transaction_data Object](#transaction_data-object) |
---
### additional_data Array
| Field | Type | Description | Characters |
|--------------|---------|-----------------------------------------------------------------|------------|
| `key_name` | string | Additional information name (e.g., "Interest and Fine") | 140 |
| `value` | string | Additional information value or description | 140 |
---
### transaction_data Object
| Field | Type | Description | Characters |
|---------------------|--------|----------------------------------------|------------|
| `transaction_key` | string | Unique transaction key | 36 |
| `pix_transfer_key` | string | PIX transfer identifier | 36 |
| `end_to_end_id` | string | PIX end-to-end identifier | 32 |
---
### payment_orders Object
| Field | Type | Description | Characters |
|-----------------------------|---------|---------------------------------------------------------|------------|
| `payment_order_key` | string | Unique payment order identifier key | 32 |
| `payment_order_status` | string | Payment order status | - |
| `reference_date` | string | Charge reference date | - |
| `receiver_conciliation_id` | uuidv4 | Receiver conciliation ID | 35 |
| `transaction_amount` | number | Transaction monetary amount | - |
| `transaction_key` | uuidv4 | Unique transaction key | 36 |
| `incoming_pix_transfer_key` | uuidv4 | Received PIX transfer key | 36 |
| `created_at` | string | Order creation date/time (ISO 8601 format) | - |
| `paid_at` | string | Payment execution date/time (ISO 8601 format) | - |
### outgoing_recurrence_events Object
| Field | Type | Description | Characters |
|-----------------------------|---------|---------------------------------------------------------|------------|
| `outgoing_recurrence_event_key` | string | Unique recurrence event identifier key | 36 |
| `outgoing_recurrence_status` | string | Recurrence status | - |
| `created_at` | string | Order creation date/time (ISO 8601 format) | - |
### periodicity Enumerators
| Enumerator | Description |
|--------------|----------------------|
| `weekly` | Weekly recurrence |
| `monthly` | Monthly recurrence |
| `quarterly` | Quarterly recurrence|
| `semiannual` | Semiannual recurrence |
| `annual` | Annual recurrence |
---
### journey_type Enumerators
| Enumerator | Description |
|-----------------|-----------------------------------------------|
| `journey_one` | Direct notification in the banking app |
| `journey_two` | QR Code experience for recurring charge |
| `journey_three` | Instant payment + QR Code recurrence |
| `journey_four` | Recurring opt-in from PIX operation |
---
### settlement_date_type Enumerators
| Enumerator | Description |
|-----------------|----------------------|
| `workdays` | Working days |
| `calendar_days` | Calendar days |
---
### qr_code_type Enumerators
| Enumerator | Description |
|-------------------|------------------------------------------------------------|
| `dynamic_instant` | Dynamic QR Code for instant payment |
| `dynamic_term` | Dynamic QR Code for payment with future due date |
STATUS 4XX
Response Error
```json
{
"title": "titulo",
"description": "description in English",
"translation": "descrição em português",
"code": "codigo"
}
```
| HTTP Code | QI Code `code` | Title `title` | Description (eng) `description` | Description (ptbr) `translation` |
|-------------|----------------------|-----------------------------------|----------------------------------------------------------------------------|--------------------------------------------------------------------|
| 400 | QIT000002 | Bad Request | Invalid request schema. | Erro no esquema da requisição. |
| 404 | APX000002 | Recurrence Not Found | Recurrence \{recurrence_key\} not found. | Recorrência \{recurrence_key\} não encontrada. |
---
# Query Automatic Pix Recurrence Data by QRCode
URL: /en/documentation/baas/pix_automatico/recebedor/consultar_recorrencia_receiver
## Request
ENDPOINT /account/ ACCOUNT_KEY /outgoing_recurrence/qr_code_initial_payment/ RECEIVER_CONCILIATION_ID
METHOD GET
### Path Params
| Field | Type | Description | Characters |
|--------------------------|--------|-----------------------------------------------------|------------|
| `account_key` * | uuidv4 | Unique account identification key. | 36 |
| `receiver_conciliation_id`*| string | Conciliation ID of the qr_code associated with the recurrence | 32 |
## Response
STATUS 200
Response Body
```json
{
"request_control_key": "98fc62fd-b0a0-4604-9bea-475e91a9dc82",
"outgoing_recurrence_key": "8cb70dea-9fb0-4a68-9572-99a72849c8d6",
"outgoing_recurrence_status": "approved",
"periodicity": "monthly",
"journey_type": "journey_four",
"start_date": "2025-06-10",
"end_date": "2027-06-10",
"outgoing_recurrence_data": {
"minimum_recurrence_amount": 123.45,
"recurrence_amount": null,
"retry_configuration": {
"retry_allowed": true,
"retry_rule": {
"first_retry": {
"day": "1"
},
"second_retry": {
"day": "3"
},
"third_retry": {
"day": "4"
}
}
},
"debtor_data": {
"name": "Sebastião",
"email": "sebastiao@test.com",
"document_number": "05431134850",
"address": {
"city": "São Paulo",
"postal_code": "123456-789",
"uf": "SP",
"street": "Av Paulista 123"
},
"account_data": {
"account_number": "123456",
"account_digit": "7",
"account_branch": "0001",
"ispb": "31872495"
}
},
"qr_code_data": {
"qr_code_key": "0f45cc3d-9bd1-4d68-a865-4cf477b5da45",
"qr_code_url": "urlqrcode.url",
"qr_code_image": "image_base64"
},
"initial_payment_data": {
"amount": 22.34,
"pix_key": "3d7d6a2b-f72f-44z7-bb20-79a94dff5645",
"qr_code_type": "dynamic_term",
"additional_data": [
{
"key_name": "Juros e Multa",
"value": "Juros 2 ao mes e multa de 1%"
}
],
"fine_amount": 3,
"interest_amount": 2,
"expiration_date": "2023-03-25",
"max_payment_days": 128,
"rebate_amount": 1,
"discounts": [],
"receiver_conciliation_id":"3d7d6a2bf72f44z7bb2079a94dff5645",
"transaction_data":{
"transaction_key":"4d7d6a2b-f72f-44z7-bb20-79a94dff5645",
"pix_transfer_key":"5d7d6a2b-f72f-44z7-bb20-79a94dff5645",
"end_to_end_id":"E32402502202303141907qlBAF1evdJ2"
}
},
"pix_message": "Conta de Luz Residencial nº123",
"settlement_date_type": "calendar_days"
}
}
```
### Response Body Params
| Field | Type | Description | Characters |
|------------------------------|------------|------------------------------------------------------------------------------------------|------------|
| `request_control_key` | uuidv4 | Unique key for request control. | 36 |
| `outgoing_recurrence_key` | uuidv4 | Automatic recurrence identifier. | 36 |
| `outgoing_recurrence_status` | string | Current recurrence status (`approved`, `pending`, `rejected`, etc.). | 30 |
| `periodicity` | enumerator | Recurrence periodicity. | [periodicity Enumerators](#enumerators-periodicity) |
| `journey_type` | enumerator | Automatic recurrence journey. | [journey_type Enumerators](#enumerators-journey_type) |
| `start_date` | string | Recurrence start date (ISO 8601 format, e.g., `2025-06-10`). | 10 |
| `end_date` | string | Recurrence end date (ISO 8601 format) or null, if indefinite. | 10 or null |
| `outgoing_recurrence_data` | object | Object grouping subscription parameters and complementary data. | [outgoing_recurrence_data Object](#outgoing_recurrence_data-object) |
---
### outgoing_recurrence_data Object
| Field | Type | Description | Characters |
|-----------------------------|----------|----------------------------------------------------------------------|------------|
| `minimum_recurrence_amount` | number | Minimum expected amount for variable amount recurrences | - |
| `recurrence_amount` | number | Recurrence amount (for fixed amount; null if variable) | - |
| `retry_configuration` | object | Configuration for attempts on uncompleted recurrences | [retry_configuration Object](#retry_configuration-object) |
| `debtor_data` | object | Debtor (subscriber) data | [debtor_data Object](#debtor_data-object) |
| `qr_code_data` | object | QR Code data generated for payment (if any) | [qr_code_data Object](#qr_code_data-object) |
| `initial_payment_data` | object | Initial charge data | [initial_payment_data Object](#initial_payment_data-object) |
| `pix_message` | string | Message sent with the Pix transaction | 140 |
| `settlement_date_type` | enumerator| Settlement date adjustment type | [settlement_date_type Enumerators](#enumerators-settlement_date_type) |
---
### retry_configuration Object
| Field | Type | Description | Characters |
|-----------------|---------|---------------------------------------|------------|
| `retry_allowed` | boolean | Indicates if retries are enabled | - |
| `retry_rule` | object | Detailed retry rules | [retry_rule Object](#retry_rule-object) |
---
### retry_rule Object
| Field | Type | Description | Characters |
|---------------|--------|---------------------------------|------------|
| `first_retry` | object | Configuration for 1st retry | [retry_detail Object](#retry_detail-object) |
| `second_retry`| object | Configuration for 2nd retry | [retry_detail Object](#retry_detail-object) |
| `third_retry` | object | Configuration for 3rd retry | [retry_detail Object](#retry_detail-object) |
---
### retry_detail Object
| Field | Type | Description | Characters |
|-------|--------|-------------------|------------|
| `day` | string | Retry day. | - |
| `time`| string | Retry time. | - |
---
### debtor_data Object
| Field | Type | Description | Characters |
|-------------------|--------|-----------------------|------------|
| `name` | string | Subscriber name. | 50 |
| `email` | string | Subscriber email. | 100 |
| `document_number` | string | CPF or CNPJ. | 14 |
| `address` | object | Subscriber address. | [address Object](#address-object) |
| `account_data` | object | Bank account data. | [account_data Object](#account_data-object) |
---
### address Object
| Field | Type | Description | Characters |
|---------------|--------|---------------------|------------|
| `city` | string | City. | - |
| `postal_code` | string | Postal code. | - |
| `uf` | string | State (abbreviation).| - |
| `street` | string | Street address. | - |
---
### account_data Object
| Field | Type | Description | Characters |
|-----------------|--------|----------------------------------|------------|
| `account_number`| string | Account number | - |
| `account_digit` | string | Account digit | - |
| `account_branch`| string | Branch | - |
| `ispb` | string | Financial institution ISPB | - |
---
### qr_code_data Object
| Field | Type | Description | Characters |
|------------------|--------|----------------------------------------|------------|
| `qr_code_key` | string | Generated QR Code identifier | - |
| `qr_code_url` | string | URL for QR Code visualization | - |
| `qr_code_image` | string | QR Code image (in Base64) | - |
---
### initial_payment_data Object
| Field | Type | Description | Characters |
|---------------------------|----------|-----------------------------------------------------------------------|------------|
| `amount` | number | Principal amount of the initial charge in reais (R$) | - |
| `pix_key` | string | Destination Pix key for initial payment | 77 |
| `qr_code_type` | enum | QR Code type for initial charge. | [qr_code_type Enumerators](#enumerators-qr_code_type) |
| `additional_data` | array | List of additional information related to the charge | [additional_data Array of objects](#additional_data-array) |
| `fine_amount` | number | Fine amount, in case of payment delay | - |
| `interest_amount` | number | Interest amount, in case of payment delay | - |
| `expiration_date` | string | Initial charge expiration date (ISO 8601 format) | 10 |
| `max_payment_days` | integer | Maximum number of acceptance days after expiration | - |
| `rebate_amount` | number | Discount amount for early payment | - |
| `discounts` | array | List of additional discounts | - |
| `receiver_conciliation_id`| string | Payment conciliation identifier by the receiver | 35 |
| `transaction_data` | object | Transaction details related to the initial charge | [transaction_data Object](#transaction_data-object) |
---
### additional_data Array
| Field | Type | Description | Characters |
|--------------|---------|-------------------------------------------------------------|------------|
| `key_name` | string | Additional information name (e.g.: "Interest and Fine") | 140 |
| `value` | string | Value or description of the additional information | 140 |
---
### transaction_data Object
| Field | Type | Description | Characters |
|---------------------|--------|------------------------------------|------------|
| `transaction_key` | string | Unique transaction key | 36 |
| `pix_transfer_key` | string | Pix transfer identifier | 36 |
| `end_to_end_id` | string | Pix end-to-end identifier | 32 |
---
### Enumerators periodicity
| Enumerator | Description |
|--------------|----------------------|
| `weekly` | Weekly recurrence |
| `monthly` | Monthly recurrence |
| `quarterly` | Quarterly recurrence |
| `semiannual` | Semiannual recurrence|
| `annual` | Annual recurrence |
---
### Enumerators journey_type
| Enumerator | Description |
|-----------------|------------------------------------------------|
| `journey_one` | Direct notification in banking app |
| `journey_two` | QR Code experience for recurring charge |
| `journey_three` | Instant payment + recurring QR Code |
| `journey_four` | Recurring opt-in from Pix operation |
---
### Enumerators settlement_date_type
| Enumerator | Description |
|-----------------|------------------|
| `workdays` | Business days |
| `calendar_days` | Calendar days |
---
### Enumerators qr_code_type
| Enumerator | Description |
|-------------------|--------------------------------------------------------|
| `dynamic_instant` | Dynamic QR Code for instant payment |
| `dynamic_term` | Dynamic QR Code for payment with future due date |
STATUS 4XX
Response Error
```json
{
"title": "titulo",
"description": "description in English",
"translation": "descrição em português",
"code": "codigo"
}
```
| HTTP Code | QI Code `code` | Title `title` | Description (eng) `description` | Description (ptbr) `translation` |
|-----------|----------------------|-----------------------------------|-----------------------------------------------------------------------------|---------------------------------------------------------------------|
| 400 | QIT000002 | Bad Request | Invalid request schema. | Erro no esquema da requisição. |
| 404 | APX000002 | Recurrence Not Found | Recurrence \{recurrence_key\} not found. | Recorrência \{recurrence_key\} não encontrada. |
---
# Payment Reconciliation and Settlement
URL: /en/documentation/baas/pix_automatico/recebedor/introducao
## Business Overview
The automatic Pix payment system offers an efficient solution to automate recurring debits, providing greater convenience for both the payer and the receiver. By ensuring automation and notification of those involved, the risk of default is minimized and companies' cash flow is optimized.
## Automatic Pix Payment Processing
On the scheduled date for an Automatic Pix debit payment, the payer's bank must issue the payment order between midnight and 8 AM. After payment confirmation, the paying user will receive a notification. If the debit is canceled by the payer or receiver before this step, the transaction will not be processed.
## Variable Value Recurrences
For recurrences with variable values, the receiving user will define the minimum value, while the payer will determine the maximum allowed value. The specific amount to be charged must be sent by the receiver between 10 to 2 days before the payment date.
:::warning
If not sent, the charge will not be processed. This step does not apply to fixed value recurrences.
:::
### Business Context
Variable value recurrences are particularly useful in sectors where chargeable amounts may fluctuate, such as utility provision or usage-based subscriptions, allowing flexibility in payments.
## Payment Reconciliation Batches
A set of recurrences with payments to be received will be called a settlement group (`conciliation_batch`).
- Reconciliation batch creation occurs 10 days before the payment date.
- Batches are closed 2 days before the payment date.
- After creating a batch, a webhook will be sent with the `conciliation_batch_key`. Associated recurrences can be obtained through the specific endpoint.
### Business Impact
Reconciliation batches facilitate large-scale receivables management, providing transparency and control over scheduled financial flows, essential for strategic and financial planning of any organization.
## Receipt Retries
The receiving user can define receipt retries during recurrence creation, respecting the following conditions:
- Retries can occur up to 7 days after the original due date.
- A maximum of three attempts can be made, as defined during creation.
- The value must be the same as the original payment.
### Business Considerations
Receipt retries are a crucial functionality for maximizing receivables, ensuring additional opportunities to settle payments that, for any reason, failed on the original date. This reduces losses from default and improves customer experience by providing additional flexibility.
---
# Create a Recurrence (Journey 4)
URL: /en/documentation/baas/pix_automatico/recebedor/journey_four
> Journey 4 — QR Code + Payment or scheduling + Automatic Pix offer
{`
.hero-section { background: linear-gradient(135deg, #eff6ff 0%, #ffffff 100%); border: 1px solid #e5e7eb; border-radius: 16px; padding: 24px; margin: 24px 0 32px 0; }
.hero-grid { display: grid; grid-template-columns: repeat(auto-fit, minmax(220px, 1fr)); gap: 16px; margin-top: 20px; }
.hero-item { background: #ffffff; border: 1px solid #e5e7eb; border-radius: 10px; padding: 16px; }
.hero-item > strong { display: block; color: #1e40af; font-size: 14px; margin-bottom: 6px; font-weight: 700; }
.hero-item p { margin: 0; font-size: 13px; color: #475569; line-height: 1.5; }
.endpoint-card { background: linear-gradient(135deg, #ffffff 0%, #f8fafc 100%); border: 2px solid #e5e7eb; border-radius: 12px; padding: 24px; position: relative; overflow: hidden; }
.endpoint-card::before { content: ''; position: absolute; top: 0; left: 0; width: 4px; height: 100%; background: linear-gradient(to bottom, #3b82f6, #1e40af); }
.endpoint-list { display: grid; gap: 12px; font-size: 13px; color: #334155; }
.endpoint__item { display: grid; grid-template-columns: 120px 1fr; align-items: center; gap: 12px; background: #ffffff; border: 1px solid #e5e7eb; border-radius: 8px; padding: 10px 14px; }
.badge { font-size: 11px; font-weight: 800; padding: 4px 10px; border-radius: 6px; color: #fff; text-transform: uppercase; letter-spacing: .4px; background: #1e40af; }
.details-container { background: linear-gradient(135deg, #ffffff 0%, #f8fafc 100%); border: 1px solid #e5e7eb; border-radius: 10px; padding: 8px 12px; margin: 20px 0; }
.details-container summary { font-weight: 700; color: #1e40af; cursor: pointer; font-size: 14px; padding: 10px 0 10px 28px; display: flex; align-items: center; position: relative; }
.details-container summary::-webkit-details-marker { display: none; }
.details-container summary::before { content: ''; position: absolute; left: 10px; width: 0; height: 0; border-left: 7px solid #1e40af; border-top: 6px solid transparent; border-bottom: 6px solid transparent; transition: transform .2s ease; }
.details-container[open] summary::before { transform: rotate(90deg); }
.code-block { margin-top: 12px; border-radius: 8px; overflow: hidden; }
.table-container { overflow: auto; border: 0; border-radius: 0; margin: 20px 0; background: transparent; }
.table-container table { width: 100%; border-collapse: collapse; font-size: 13px; }
.table-container th, .table-container td { border-top: 1px solid #e5e7eb; padding: 12px 16px; text-align: left; }
.table-container thead th { background: linear-gradient(135deg, #f8fafc 0%, #ffffff 100%); font-weight: 700; color: #0f172a; font-size: 13px; }
`}
Overview
What it is The customer makes a payment or schedules a QR Code and then receives an offer to activate the Automatic Pix recurrence.
When to use Recommended for invoices, bills or accounts with a recurrence adhesion proposal, but only after the initial payment or scheduling.
How it works Payer reads the QR Code → pays or schedules the payment → upon completion, receives an invitation to activate the Automatic Pix for that charge (optional).
Benefits Flexible: the decision about recurrence occurs after payment/scheduling, allowing voluntary and spontaneous adhesion by the payer.
Key considerations The recurrence offer is made only after payment/scheduling — it can be declined by the customer. If not available for that case, proceed only with the payment, without offering recurrence.
## Request
{`
.endpoint-card { background: linear-gradient(135deg, #ffffff 0%, #f8fafc 100%); border: 2px solid #e5e7eb; border-radius: 12px; padding: 24px; position: relative; overflow: hidden; }
.endpoint-card::before { content: ''; position: absolute; top: 0; left: 0; width: 4px; height: 100%; background: linear-gradient(to bottom, #3b82f6, #1e40af); }
.endpoint-list { display: grid; gap: 12px; font-size: 13px; color: #334155; }
.endpoint__item { display: grid; grid-template-columns: 120px 1fr; align-items: center; gap: 12px; background: #ffffff; border: 1px solid #e5e7eb; border-radius: 8px; padding: 10px 14px; }
.badge { font-size: 11px; font-weight: 800; padding: 4px 10px; border-radius: 6px; color: #fff; text-transform: uppercase; letter-spacing: .4px; background: #1e40af; }
.details-container { background: linear-gradient(135deg, #ffffff 0%, #f8fafc 100%); border: 1px solid #e5e7eb; border-radius: 10px; padding: 8px 12px; margin: 20px 0; }
.details-container summary { font-weight: 700; color: #1e40af; cursor: pointer; font-size: 14px; padding: 10px 0 10px 28px; display: flex; align-items: center; position: relative; }
.details-container summary::-webkit-details-marker { display: none; }
.details-container summary::before { content: ''; position: absolute; left: 10px; width: 0; height: 0; border-left: 7px solid #1e40af; border-top: 6px solid transparent; border-bottom: 6px solid transparent; transition: transform .2s ease; }
.details-container[open] summary::before { transform: rotate(90deg); }
.code-block { margin-top: 12px; border-radius: 8px; overflow: hidden; }
`}
ENDPOINT /account/ account_key /outgoing_recurrence/journey_four
METHOD POST
### Request Path Params
| Field | Type | Description | Characters |
|---------------|-------|------------------------------------------------|------------|
| `account_key`*| uuid4 | Unique account identification key. | 36 |
### Request Body
**Request Body: Create Recurrence (Journey 4)**
```json
{
"request_control_key": "98fc62fd-b0a0-4604-9bea-475e91a9dc82",
"periodicity": "monthly",
"minimum_recurrence_amount": 125,
"start_date": "2025-06-10",
"end_date": "2027-06-10",
"pix_message": "Conta de Luz Residencial nº123",
"recurrence_type": "variable_amount",
"debtor_data": {
"name": "Sebastião",
"email": "sebastiao@test.com",
"document_number": "05431134850",
"contract_id": "12345",
"address": {
"street": "Av. Brigadeiro Faria Lima",
"state": "SP",
"city": "São Paulo",
"neighborhood": "Jardim Paulistano",
"number": "2391",
"postal_code": "01452905",
"complement": "Complemento"
}
},
"initial_payment_data": {
"amount": 22.34,
"pix_key": "3d7d6a2b-f72f-44z7-bb20-79a94dff5645",
"qr_code_type": "dynamic_term",
"additional_data": [
{
"key_name": "Juros e Multa",
"value": "Juros 2 ao mes e multa de 1%"
}
],
"fine_amount": 3,
"interest_amount": 2,
"expiration_date": "2023-03-25",
"max_payment_days": 128,
"rebate_amount": 1,
"discounts": [],
"receiver_conciliation_id": "3d7d6a2bf72f44z7bb2079a94dff5645"
},
"retry_configuration": {
"retry_allowed": true,
"retry_rule": {
"first_retry": {
"day": "1"
},
"second_retry": {
"day": "3"
},
"third_retry": {
"day": "4"
}
}
},
"settlement_date_type": "workdays"
}
```
### Body Params
| Field | Type | Description | Characters |
|-----------------------------------|-------------|-------------------------------------------------------------------------------------------------------------------|------------|
| `request_control_key` * | uuid | Unique request identification key used by the client in uuid4 format. | 36 |
| `periodicity` * | enumerator | Periodicity type associated with the subscription recurrence. | [periodicity Enumerators](#periodicity-enumerators) |
| `minimum_recurrence_amount` | float | Minimum transaction amount for variable amount recurrences | - |
| `start_date` * | string | Recurrence start date (ISO 8601 format, e.g., "2025-07-01"). | - |
| `end_date` | string | Recurrence end date; for indefinite time, send as null. | - |
| `pix_message` * | string | Message to be sent with the Pix transaction. | 140 |
| `debtor_data` * | Object | Debtor (subscriber) data. | [debtor_data Object](#debtor_data-object) |
| `retry_configuration` * | Object | Retry configuration for incomplete transactions. | [retry_configuration Object](#retry_configuration-object) |
| `settlement_date_type` * | enumerator | Settlement date adjustment type | [settlement_date_type Enumerators](#settlement_date_type-enumerators) |
| `recurrence_type` * | enumerator | Recurrence type | [recurrence_type Enumerators](#recurrence_type-enumerators) |
| `initial_payment_data` * | Object | Object with initial charge information to be performed when creating the subscription. | [initial_payment_data Object](#initial_payment_data-object) |
:::caution Attention
The `minimum_recurrence_amount` field is optional and should only be informed for variable amount recurrence. If the recurrence is fixed amount, the `recurrence_amount` field should be sent with the recurrence value. The same applies to the `recurrence_type` enumerator, which should correspond to the recurrence type (Fixed or variable amount).
:::
### periodicity Enumerators
| Enumerator | Description |
|--------------|-----------------------|
| `weekly` | Weekly recurrence |
| `monthly` | Monthly recurrence |
| `quarterly` | Quarterly recurrence |
| `semiannual` | Semiannual recurrence |
| `annual` | Annual recurrence |
### settlement_date_type Enumerators
| Enumerator | Description |
|--------------|-----------------------|
| `workdays` | Workdays |
| `calendar_days` | Calendar days |
### recurrence_type Enumerators
| Enumerator | Description |
|--------------|-----------------------|
| `fixed_amount` | Fixed Amount Recurrence |
| `variable_amount` | Variable Amount Recurrence |
### debtor_data Object
| Field | Type | Description | Characters |
|---------------------|--------|-----------------------|------------|
| `name` * | string | Subscriber name. | 50 |
| `email` * | string | Subscriber email. | 100 |
| `document_number` * | string | Subscriber CPF or CNPJ. | 14 |
| `contract_id` | string | Subscriber contract identifier. | 100 |
| `address` * | Object | Subscriber address. | [address Object](#address-object) |
### address Object
| Field | Type | Description | Characters |
|---------------|--------|-------------------|------------|
| `street` | string | Street. | - |
| `state` | string | State. | - |
| `city` | string | City. | - |
| `neighborhood`| string | Neighborhood. | - |
| `number` | string | Number. | - |
| `postal_code` | string | Postal code. | - |
| `complement` | string | Complement. | - |
### retry_configuration Object
| Field | Type | Description | Characters |
|---------------|---------|---------------------------|------------|
| `retry_allowed`| boolean | Indicates if retries are allowed. | - |
| `retry_rule` | Object | Retry rules. | [retry_rule Object](#retry_rule-object) |
### retry_rule Object
| Field | Type | Description | Characters |
|---------------|--------|---------------------------|------------|
| `first_retry` | Object | First retry configuration. | [retry_detail Object](#retry_detail-object) |
| `second_retry`| Object | Second retry configuration. | [retry_detail Object](#retry_detail-object) |
| `third_retry` | Object | Third retry configuration. | [retry_detail Object](#retry_detail-object) |
### retry_detail Object
| Field | Type | Description | Characters |
|-------|--------|---------------------------|------------|
| `day` | string | Retry day. | - |
### initial_payment_data Object
| Field | Type | Description | Characters |
|----------------------------|------------|------------------------------------------------------------------------------------------|------------|
| `amount` * | number | Main amount of the initial charge in Brazilian Reais (R$). | - |
| `pix_key` * | string | Destination Pix key for the payment. | 77 |
| `qr_code_type`* | enumerator | QR Code type for the initial charge. | [qr_code_type Enumerators](#qr_code_type-enumerators) |
| `additional_data`* | array | List of objects with additional information related to the charge (e.g., interest, fine). | [additional_data Objects](#additional_data-object) |
| `fine_amount` | number | Fine amount in case of late payment. | - |
| `interest_amount` | number | Interest amount in case of late payment. | - |
| `expiration_date` * | string | Initial charge expiration date (ISO 8601 format, e.g., "2023-03-25"). | - |
| `max_payment_days` | integer | Maximum number of days from the expiration date in which payment can be accepted. | - |
| `rebate_amount` | number | Discount amount for early payment. | - |
| `discounts` | array | List of additional applicable discounts (if any). | - |
| `receiver_conciliation_id` | string | Unique identifier for payment reconciliation by the receiver. | 32 |
### qr_code_type Enumerators
| Value | Description |
|--------------------|---------------------------------------------------------------------------|
| `dynamic_instant` | Generates a dynamic QR Code for instant payment, with immediate expiration. |
| `dynamic_term` | Generates a dynamic QR Code with defined payment term (future expiration). |
### additional_data Object
| Field | Type | Description | Characters |
|--------------|---------|-----------------------------------------------------------------|------------|
| `key_name` | string | Additional information field name (example: "Interest and Fine").| - |
| `value` | string | Value or description of the additional information. | - |
## Response
STATUS 200
:::caution Attention
When the payer user receives the notification, they can choose to schedule the Pix or make the transfer at that moment. If the payer makes the payment instantly, the webhook of type `baas.automatic_pix.outgoing_recurrence.status_change` will be sent with the information filled in; in case of scheduling, the values will be `null`.
:::
**Response Body**
```json
{
"request_control_key": "98fc62fd-b0a0-4604-9bea-475e91a9dc82",
"outgoing_recurrence_key": "8cb70dea-9fb0-4a68-9572-99a72849c8d6",
"outgoing_recurrence_status": "pending_confirmation",
"qr_code_data": {
"qr_code_url": "url",
"qr_code_key": "6f270b64-1b7a-4269-91f8-3f9cf30ba0bb",
"qr_code_image": "imageb64"
},
"initial_payment_data": {
"receiver_conciliation_id": "6f270b64-1b7a-4269-91f8-3f9cf30ba0bb"
},
"created_at": "2021-10-22T20:30:23.459Z"
}
```
### Response Body
| Field | Type | Description | Characters |
|-----------------------|------------|---------------------------------------------------------------------------|------------|
| `request_control_key` | uuid | Request control key sent by the client. | 36 |
| `recurrence_key` | uuid | Unique subscription recurrence identification key. | 36 |
| `recurrence_status` | enumerator | Current recurrence status. | [recurrence_status Enumerators](#recurrence_status-enumerators) |
| `qr_code_data` | enumerator | QR Code data | [qr_code_data Object](#qr_code_data-enumerators) |
| `initial_payment_data`| enumerator | Initiated payment information | [qr_code_data Object](#qr_code_data-enumerators) |
| `created_at` | string | Recurrence creation date and time (ISO 8601 format). | - |
### qr_code_data Object
| Field | Type | Description | Characters |
|-------|--------|-------------------------|------------|
| `qr_code_url` | string | QR code copy and paste URL | - |
| `qr_code_key`| uuuid | QR code unique identification key. | 36 |
| `qr_code_image`| string | QR code image base64 | - |
### initial_payment_data Object
| Field | Type | Description | Characters |
|-------|--------|-------------------------|------------|
| `receiver_conciliation_id` | string | Unique identifier for payment reconciliation by the receiver. | 32 |
### recurrence_status Enumerators
| Enumerator | Description |
|----------------------|-----------------------------------|
| `pending_confirmation` | Recurrence pending confirmation |
| `active` | Active recurrence |
| `cancelled` | Cancelled recurrence |
| `suspended` | Suspended recurrence |
| `expired` | Expired recurrence |
STATUS 4XX
**Response Error**
```json
{
"title": "titulo",
"description": "description in English",
"translation": "descrição em português",
"code": "codigo"
}
```
| HTTP Code | QI Code `code` | Title `title` | Description (eng) `description` | Description (ptbr) `translation` |
|-------------|----------------------|-----------------------------------|----------------------------------------------------------------------------|--------------------------------------------------------------------|
| 400 | QIT000002 | Bad Request | Invalid request schema. | Erro no esquema da requisição. |
| 403 | APX000030 | Unauthorized Transaction | User is not authorized to create this recurrence. | Usuário não autorizado a criar esta recorrência. |
| 403 | APX000018 | Endpoint Access Denied | Requester lacks permission to access this endpoint. | Requester não possui permissão para acessar este endpoint. |
| 404 | APX000021 | Subscription Not Found | Subscription \{subscription_key\} not found. | Assinatura \{subscription_key\} não encontrada. |
| 404 | APX000002 | Recurrence Not Found | Recurrence \{recurrence_key\} not found. | Recorrência \{recurrence_key\} não encontrada. |
| 406 | APX000027 | Invalid Transaction Amount | Transaction amount \{minimum_transaction_amount\} is invalid. | Valor da transação \{minimum_transaction_amount\} é inválido. |
| 409 | APX000014 | Request Control Key Conflict | The request_control_key \{request_control_key\} is already in use. | A request_control_key \{request_control_key\} já está em uso. |
---
# Create a Recurrence (Journey 1)
URL: /en/documentation/baas/pix_automatico/recebedor/journey_one
> Journey 1 — Without QR Code (app notification)
{`
.hero-section { background: linear-gradient(135deg, #eff6ff 0%, #ffffff 100%); border: 1px solid #e5e7eb; border-radius: 16px; padding: 24px; margin: 24px 0 32px 0; }
.hero-grid { display: grid; grid-template-columns: repeat(auto-fit, minmax(220px, 1fr)); gap: 16px; margin-top: 20px; }
.hero-item { background: #ffffff; border: 1px solid #e5e7eb; border-radius: 10px; padding: 16px; }
.hero-item > strong { display: block; color: #1e40af; font-size: 14px; margin-bottom: 6px; font-weight: 700; }
.hero-item p { margin: 0; font-size: 13px; color: #475569; line-height: 1.5; }
.endpoint-card { background: linear-gradient(135deg, #ffffff 0%, #f8fafc 100%); border: 2px solid #e5e7eb; border-radius: 12px; padding: 24px; position: relative; overflow: hidden; }
.endpoint-card::before { content: ''; position: absolute; top: 0; left: 0; width: 4px; height: 100%; background: linear-gradient(to bottom, #3b82f6, #1e40af); }
.endpoint-list { display: grid; gap: 12px; font-size: 13px; color: #334155; }
.endpoint__item { display: grid; grid-template-columns: 120px 1fr; align-items: center; gap: 12px; background: #ffffff; border: 1px solid #e5e7eb; border-radius: 8px; padding: 10px 14px; }
.badge { font-size: 11px; font-weight: 800; padding: 4px 10px; border-radius: 6px; color: #fff; text-transform: uppercase; letter-spacing: .4px; background: #1e40af; }
.details-container { background: linear-gradient(135deg, #ffffff 0%, #f8fafc 100%); border: 1px solid #e5e7eb; border-radius: 10px; padding: 8px 12px; margin: 20px 0; }
.details-container summary { font-weight: 700; color: #1e40af; cursor: pointer; font-size: 14px; padding: 10px 0 10px 28px; display: flex; align-items: center; position: relative; }
.details-container summary::-webkit-details-marker { display: none; }
.details-container summary::before { content: ''; position: absolute; left: 10px; width: 0; height: 0; border-left: 7px solid #1e40af; border-top: 6px solid transparent; border-bottom: 6px solid transparent; transition: transform .2s ease; }
.details-container[open] summary::before { transform: rotate(90deg); }
.code-block { margin-top: 12px; border-radius: 8px; overflow: hidden; }
.table-container { overflow: auto; border: 0; border-radius: 0; margin: 20px 0; background: transparent; }
.table-container table { width: 100%; border-collapse: collapse; font-size: 13px; }
.table-container th, .table-container td { border-top: 1px solid #e5e7eb; padding: 12px 16px; text-align: left; }
.table-container thead th { background: linear-gradient(135deg, #f8fafc 0%, #ffffff 100%); font-weight: 700; color: #0f172a; font-size: 13px; }
`}
Overview
What it is Authorization requested from the payer directly in the bank app, without QR Code reading.
When to use Active contact (phone, chat, in-person) or existing relationship with the customer.
How it works Receiver creates the recurrence with payer's account data → the payer receives a notification in the app → approves the recurrence → future charges can be scheduled.
Benefits Simple and direct experience; doesn't require QR Code display.
## Request
ENDPOINT /account/ account_key /outgoing_recurrence/journey_one
METHOD POST
### Request Path Params
| Field | Type | Description | Characters |
|---------------|-------|------------------------------------------------|------------|
| `account_key`*| uuid4 | Unique account identification key. | 36 |
### Request Body
**Request Body: Create Recurrence (Journey 1)**
```json
{
"request_control_key": "98fc62fd-b0a0-4604-9bea-475e91a9dc82",
"periodicity": "monthly",
"minimum_recurrence_amount": 125,
"start_date": "2025-06-10",
"end_date": "2027-06-10",
"pix_message": "Conta de Luz Residencial nº123",
"recurrence_type": "variable_amount",
"debtor_data": {
"name": "Sebastião",
"email": "sebastiao@test.com",
"document_number": "05431134850",
"contract_id": "Contrato de pagamento recorrente",
"address": {
"street": "Av. Brigadeiro Faria Lima",
"state": "SP",
"city": "São Paulo",
"neighborhood": "Jardim Paulistano",
"number": "2391",
"postal_code": "01452905",
"complement": "Complemento"
},
"account_data": {
"account_number": "123456",
"account_digit": "7",
"account_branch": "0001",
"ispb": "31872495"
}
},
"retry_configuration": {
"retry_allowed": true,
"retry_rule": {
"first_retry": {
"day": "1",
},
"second_retry": {
"day": "3",
},
"third_retry": {
"day": "4",
}
}
},
"settlement_date_type": "workdays"
}
```
### Body Params
| Field | Type | Description | Characters |
|--------------------------------|------------|------------------------------------------------------------------------------------------------------------|------------|
| `request_control_key` * | uuid | Unique request identification key used by the client in uuid4 format. | 36 |
| `periodicity` * | enumerator | Type of periodicity associated with the subscription recurrence. | [periodicity Enumerators](#periodicity-enumerators) |
| `minimum_recurrence_amount` | number | Minimum transaction amount for variable amount recurrences (in cents). | - |
| `start_date` * | string | Recurrence start date (ISO 8601 format, e.g., "2025-07-01"). | - |
| `end_date` | string | Recurrence end date; for indefinite duration, send as null. | - |
| `pix_message` * | string | Message to be sent along with the Pix transaction. | 140 |
| `debtor_data` * | Object | Debtor (subscriber) data. | [debtor_data Object](#debtor_data-object) |
| `retry_configuration` * | Object | Retry configuration for incomplete transactions. | [retry_configuration Object](#retry_configuration-object) |
| `settlement_date_type` * | enumerator | Type of settlement date adjustment | [settlement_date_type Enumerators](#settlement_date_type-enumerators) |
| `recurrence_type` * | enumerator | Type of recurrence | [recurrence_type Enumerators](#recurrence_type-enumerators) |
:::caution Attention
The `minimum_recurrence_amount` field is optional and should only be provided for variable amount recurrences. If the recurrence is fixed amount, the `recurrence_amount` field must be sent, with the recurrence value. As well as the `recurrence_type` enumerator, which should correspond to the type of recurrence (Fixed amount or variable).
:::
### periodicity Enumerators
| Enumerator | Description |
|--------------|-----------------------|
| `weekly` | Weekly recurrence |
| `monthly` | Monthly recurrence |
| `quarterly` | Quarterly recurrence|
| `semiannual` | Semiannual recurrence |
| `annual` | Annual recurrence |
### settlement_date_type Enumerators
| Enumerator | Description |
|--------------|-----------------------|
| `workdays` | Business days |
| `calendar_days` | Calendar days |
### recurrence_type Enumerators
| Enumerator | Description |
|--------------|-----------------------|
| `fixed_amount` | Fixed Amount Recurrence |
| `variable_amount` | Variable Amount Recurrence |
### debtor_data Object
| Field | Type | Description | Characters |
|---------------------|--------|-----------------------|------------|
| `name` * | string | Subscriber name. | 50 |
| `email` * | string | Subscriber email. | 100 |
| `document_number` * | string | Subscriber CPF or CNPJ. | 14 |
| `contract_id` | string | Subscriber contract identifier. | 100 |
| `address` * | Object | Subscriber address.| [address Object](#address-object) |
| `account_data` * | Object | Subscriber banking data. | [account_data Object](#account_data-object) |
### address Object
| Field | Type | Description | Characters |
|---------------|--------|-------------------|------------|
| `street` | string | Street. | - |
| `state` | string | State. | - |
| `city` | string | City. | - |
| `neighborhood`| string | Neighborhood. | - |
| `number` | string | Number. | - |
| `postal_code` | string | Postal code. | - |
| `complement` | string | Complement. | - |
### account_data Object
| Field | Type | Description | Characters |
|-----------------|--------|------------------------------|------------|
| `account_number`| string | Account number. | - |
| `account_digit` | string | Account digit. | - |
| `account_branch`| string | Account branch. | - |
| `ispb` | string | Financial institution ISPB. | - |
### retry_configuration Object
| Field | Type | Description | Characters |
|---------------|---------|-------------------------|------------|
| `retry_allowed`| boolean | Indicates if retries are allowed. | - |
| `retry_rule` | Object | Retry rules. | [retry_rule Object](#retry_rule-object) |
### retry_rule Object
| Field | Type | Description | Characters |
|---------------|--------|-------------------------|------------|
| `first_retry` | Object | First retry configuration. | [retry_detail Object](#retry_detail-object) |
| `second_retry`| Object | Second retry configuration. | [retry_detail Object](#retry_detail-object) |
| `third_retry` | Object | Third retry configuration. | [retry_detail Object](#retry_detail-object) |
### retry_detail Object
| Field | Type | Description | Characters |
|-------|--------|-------------------------|------------|
| `day` | string | Retry day. | - |
## Response
STATUS 200
**Response Body**
```json
{
"request_control_key": "a7b9e3c1-f2d4-4a8b-9c7e-123456789abc",
"recurrence_key": "b2c3d4e5-f6g7-4h8i-9j0k-l1m2n3o4p5q6",
"recurrence_status": "pending_confirmation",
"created_at": "2025-06-16T23:52:00.000Z"
}
```
### Response Body
| Field | Type | Description | Characters |
|-----------------------|------------|---------------------------------------------------------------------------|------------|
| `request_control_key` | uuid | Request control key sent by the client. | 36 |
| `recurrence_key` | uuid | Unique subscription recurrence identification key. | 36 |
| `recurrence_status` | enumerator | Current recurrence status. | [recurrence_status Enumerators](#recurrence_status-enumerators) |
| `created_at` | string | Recurrence creation date and time (ISO 8601 format). | - |
### recurrence_status Enumerators
| Enumerator | Description |
|----------------------|-----------------------------------|
| `pending_confirmation` | Recurrence pending confirmation |
| `active` | Active recurrence |
| `cancelled` | Cancelled recurrence |
| `suspended` | Suspended recurrence |
| `expired` | Expired recurrence |
STATUS 4XX
Response Error
```json
{
"title": "titulo",
"description": "description in English",
"translation": "descrição em português",
"code": "codigo"
}
```
| HTTP Code | QI Code `code` | Title `title` | Description (eng) `description` | Description (ptbr) `translation` |
|-------------|----------------------|-----------------------------------|----------------------------------------------------------------------------|--------------------------------------------------------------------|
| 400 | QIT000002 | Bad Request | Invalid request schema. | Erro no esquema da requisição. |
| 403 | APX000030 | Unauthorized Transaction | User is not authorized to create this recurrence. | Usuário não autorizado a criar esta recorrência. |
| 403 | APX000018 | Endpoint Access Denied | Requester lacks permission to access this endpoint. | Requester não possui permissão para acessar este endpoint. |
| 404 | APX000021 | Subscription Not Found | Subscription \{subscription_key\} not found. | Assinatura \{subscription_key\} não encontrada. |
| 404 | APX000002 | Recurrence Not Found | Recurrence \{recurrence_key\} not found. | Recorrência \{recurrence_key\} não encontrada. |
| 406 | APX000027 | Invalid Transaction Amount | Transaction amount \{minimum_transaction_amount\} is invalid. | Valor da transação \{minimum_transaction_amount\} é inválido. |
| 409 | APX000014 | Request Control Key Conflict | The request_control_key \{request_control_key\} is already in use. | A request_control_key \{request_control_key\} já está em uso. |
---
# Create a Recurrence (Journey 3)
URL: /en/documentation/baas/pix_automatico/recebedor/journey_three
> Journey 3 — QR Code + First Payment (immediate recurrence activation)
{`
.hero-section {
background: linear-gradient(135deg, #eff6ff 0%, #ffffff 100%);
border: 1px solid #e5e7eb;
border-radius: 16px;
padding: 24px;
margin: 24px 0 32px 0;
}
.hero-grid {
display: grid;
grid-template-columns: repeat(auto-fit, minmax(220px, 1fr));
gap: 16px;
margin-top: 20px;
}
.hero-item {
background: #ffffff;
border: 1px solid #e5e7eb;
border-radius: 10px;
padding: 16px;
transition: all 0.3s ease;
}
.hero-item:hover {
transform: translateY(-2px);
box-shadow: 0 4px 12px rgba(0, 0, 0, 0.08);
border-color: #3b82f6;
}
/* FIX: título em bloco, destaques inline dentro do parágrafo */
.j3-card > strong,
.hero-item > strong {
display: block;
color: #1e40af;
font-size: 14px;
margin-bottom: 6px;
font-weight: 700;
}
.j3-card p strong,
.hero-item p strong {
display: inline;
color: #1e40af;
font-weight: 700;
}
.hero-item p {
margin: 0;
font-size: 13px;
color: #475569;
line-height: 1.5;
}
.flow-section {
margin: 32px 0;
}
.flow-grid {
display: grid;
grid-template-columns: repeat(auto-fit, minmax(240px, 1fr));
gap: 16px;
margin-top: 20px;
}
.flow-step-card {
border-radius: 12px;
padding: 18px;
color: #ffffff;
min-height: 100px;
display: flex;
flex-direction: column;
gap: 8px;
}
.flow-step-card h4 {
margin: 0;
font-size: 15px;
font-weight: 700;
}
.flow-step-card p {
margin: 0;
font-size: 13px;
opacity: 0.95;
line-height: 1.5;
}
.endpoint-section {
margin: 32px 0;
}
.endpoint-card {
background: linear-gradient(135deg, #ffffff 0%, #f8fafc 100%);
border: 2px solid #e5e7eb;
border-radius: 12px;
padding: 24px;
transition: all 0.3s ease;
position: relative;
overflow: hidden;
}
.endpoint-card::before {
content: '';
position: absolute;
top: 0;
left: 0;
width: 4px;
height: 100%;
background: linear-gradient(to bottom, #3b82f6, #1e40af);
transition: width 0.3s ease;
}
.endpoint-card:hover {
transform: translateY(-4px);
box-shadow: 0 10px 25px rgba(0, 0, 0, 0.1);
border-color: #3b82f6;
}
.endpoint-card:hover::before {
width: 6px;
}
.endpoint-list {
display: grid;
gap: 12px;
font-size: 13px;
color: #334155;
}
.endpoint-item {
display: grid;
grid-template-columns: 120px 1fr;
align-items: center;
gap: 12px;
background: #ffffff;
border: 1px solid #e5e7eb;
border-radius: 8px;
padding: 10px 14px;
}
.badge {
font-size: 11px;
font-weight: 800;
padding: 4px 10px;
border-radius: 6px;
color: #fff;
text-transform: uppercase;
letter-spacing: 0.4px;
background: #1e40af;
}
.info-note {
background: linear-gradient(135deg, #eff6ff 0%, #ffffff 100%);
border-left: 4px solid #3b82f6;
padding: 14px 18px;
border-radius: 8px;
font-size: 13px;
color: #1e40af;
margin: 20px 0;
line-height: 1.6;
}
.warn-note {
background: linear-gradient(135deg, #fef3c7 0%, #ffffff 100%);
border-left: 4px solid #f59e0b;
padding: 14px 18px;
border-radius: 8px;
font-size: 13px;
color: #0f172a;
margin: 20px 0;
line-height: 1.6;
}
.table-container {
overflow: auto;
border: 0;
border-radius: 0;
margin: 20px 0;
background: transparent;
}
.table-container table {
width: 100%;
border-collapse: collapse;
font-size: 13px;
}
.table-container th,
.table-container td {
border-top: 1px solid #e5e7eb;
padding: 12px 16px;
text-align: left;
}
.table-container thead th {
background: linear-gradient(135deg, #f8fafc 0%, #ffffff 100%);
font-weight: 700;
color: #0f172a;
font-size: 13px;
}
.table-container tbody tr:hover {
background: #f8fafc;
}
.details-container {
background: linear-gradient(135deg, #ffffff 0%, #f8fafc 100%);
border: 1px solid #e5e7eb;
border-radius: 10px;
padding: 8px 12px;
margin: 20px 0;
}
.details-container summary {
font-weight: 700;
color: #1e40af;
cursor: pointer;
font-size: 14px;
padding: 10px 0 10px 28px;
display: flex;
align-items: center;
position: relative;
}
.details-container summary::-webkit-details-marker { display: none; }
.details-container summary::before {
content: '';
position: absolute;
left: 10px;
width: 0; height: 0;
border-left: 7px solid #1e40af;
border-top: 6px solid transparent;
border-bottom: 6px solid transparent;
transition: transform .2s ease;
}
.details-container[open] summary::before { transform: rotate(90deg); }
.code-block {
margin-top: 12px;
border-radius: 8px;
overflow: hidden;
}
.tips-section {
margin: 32px 0;
}
.tip-card {
background: linear-gradient(135deg, #ffffff 0%, #f0fdf4 100%);
border: 2px solid #d1fae5;
border-radius: 12px;
padding: 18px 20px;
margin-bottom: 16px;
transition: all 0.3s ease;
}
.tip-card:hover {
transform: translateY(-2px);
border-color: #10b981;
box-shadow: 0 6px 20px rgba(16, 185, 129, 0.15);
}
.tip-text {
font-size: 14px;
line-height: 1.7;
color: #475569;
margin: 0;
display: flex;
align-items: flex-start;
gap: 10px;
}
.tip-icon {
color: #10b981;
font-size: 18px;
flex-shrink: 0;
margin-top: 2px;
font-weight: 700;
}
.section-title {
font-size: 20px;
font-weight: 700;
color: #0f172a;
margin: 32px 0 20px 0;
padding-bottom: 12px;
border-bottom: 2px solid #e5e7eb;
}
@media (max-width: 768px) {
.hero-grid,
.flow-grid {
grid-template-columns: 1fr;
}
.endpoint-item {
grid-template-columns: 100px 1fr;
font-size: 12px;
}
.endpoint-item code {
font-size: 11px;
}
}
`}
Overview
What it is
A single QR Code that allows pay now and activate recurrence in the same flow.
When to use
Cases with mandatory initial charge (e.g., registration, enrollment, first payment).
How it works
The payer scans the QR → makes the first payment → authorizes recurrence immediately.
Benefits
Immediate revenue + configured recurrence, reducing friction and delinquency.
### Journey 3 Flow
1. Read QR Code
The user scans the dynamic QR generated for the initial charge.
2. Pay Now
The immediate payment is processed, recording the initial charge.
3. Authorize Recurrence
In the same experience, the user confirms the recurrence authorization.
4. Active Recurrence
Next cycles are automated; you only need to reconcile amounts when necessary.
---
## Request
ENDPOINT
/account/ account_key /outgoing_recurrence/journey_three
METHOD
POST
### Path Params
Field Type Description Characters
account_key * uuid4 Unique account identification key. 36
### Request Body
**Request Body: Create Recurrence (Journey 3)**
```json
{
"request_control_key": "98fc62fd-b0a0-4604-9bea-475e91a9dc82",
"periodicity": "monthly",
"minimum_recurrence_amount": 125,
"start_date": "2025-06-10",
"end_date": "2027-06-10",
"pix_message": "Conta de Luz Residencial nº123",
"recurrence_type": "variable_amount",
"debtor_data": {
"name": "Sebastião",
"email": "sebastiao@test.com",
"document_number": "05431134850",
"contract_id": "12345",
"address": {
"street": "Av. Brigadeiro Faria Lima",
"state": "SP",
"city": "São Paulo",
"neighborhood": "Jardim Paulistano",
"number": "2391",
"postal_code": "01452905",
"complement": "Complemento"
}
},
"initial_payment_data": {
"amount": 22.34,
"pix_key": "3d7d6a2b-f72f-44z7-bb20-79a94dff5645",
"qr_code_type": "dynamic_term",
"additional_data": [
{
"key_name": "Juros e Multa",
"value": "Juros 2 ao mes e multa de 1%"
}
],
"fine_amount": 3,
"interest_amount": 2,
"expiration_date": "2023-03-25",
"max_payment_days": 128,
"rebate_amount": 1,
"discounts": [],
"receiver_conciliation_id": "3d7d6a2bf72f44z7bb2079a94dff5645"
},
"retry_configuration": {
"retry_allowed": true,
"retry_rule": {
"first_retry": {
"day": "1"
},
"second_retry": {
"day": "3"
},
"third_retry": {
"day": "4"
}
}
},
"settlement_date_type": "workdays"
}
```
### Body Params
Field Type Description Characters
request_control_key * uuid Unique request key (uuid4). 36
periodicity * enumerator Recurrence periodicity. Periodicity enumerators
minimum_recurrence_amount float Minimum amount per transaction (variable recurrences). -
start_date * string Start date (ISO 8601). -
end_date string End date or null for indefinite. -
pix_message * string Message displayed in Pix transaction. 140
debtor_data * Object Subscriber data. debtor_data object
retry_configuration * Object Retry rules. retry_configuration object
settlement_date_type * enumerator Settlement date adjustment. settlement_date_type enumerators
recurrence_type * enumerator Type of recurrence. recurrence_type enumerators
initial_payment_data * Object Initial charge data. initial_payment_data object
Attention: for variable amount recurrence, provide minimum_recurrence_amount . For fixed amount, send recurrence_amount and adjust the recurrence_type enumerator accordingly.
#### Periodicity enumerators
Enumerator Description
weekly Weekly recurrence
monthly Monthly recurrence
quarterly Quarterly recurrence
semiannual Semiannual recurrence
annual Annual recurrence
#### Settlement_date_type enumerators
Enumerator Description
workdays Business days
calendar_days Calendar days
#### Recurrence_type enumerators
Enumerator Description
fixed_amount Fixed Amount Recurrence
variable_amount Variable Amount Recurrence
#### debtor_data object
Field Type Description Characters
name * string Subscriber name. 50
email * string Subscriber email. 100
document_number * string Subscriber CPF/CNPJ. 14
contract_id string Contract identifier. 100
address * Object Subscriber address. address object
#### address object
Field Type Description
street string Street
state string State
city string City
neighborhood string Neighborhood
number string Number
postal_code string ZIP Code
complement string Complement
#### retry_configuration object
Field Type Description
retry_allowed boolean Enable retries
retry_rule Object Retry rules
#### retry_rule object
Field Type Description
first_retry Object First retry
second_retry Object Second retry
third_retry Object Third retry
#### retry_detail object
Field Type Description
day string Retry day
#### initial_payment_data object
Field Type Description Characters
amount * number Initial charge amount (R$). -
pix_key * string Destination Pix key. 77
qr_code_type * enumerator Type of QR Code for initial charge. qr_code_type enumerators
additional_data * array List of additional data (e.g., interest/fine). additional_data objects
fine_amount number Late fee. -
interest_amount number Interest for late payment. -
expiration_date * string Expiration date (ISO 8601). -
max_payment_days integer Maximum days after expiration to accept payment. -
rebate_amount number Early payment discount. -
discounts array Additional discounts. -
receiver_conciliation_id string Identifier for receiver reconciliation. 32
#### qr_code_type enumerators
Value Description
dynamic_instant Dynamic QR for immediate payment
dynamic_term Dynamic QR with term (future due date)
#### additional_data objects
Field Type Description
key_name string Information label (e.g., Interest and Fine)
value string Value/description
---
## Response
STATUS
200
**Response Body (example)**
```json
{
"request_control_key": "98fc62fd-b0a0-4604-9bea-475e91a9dc82",
"outgoing_recurrence_key": "8cb70dea-9fb0-4a68-9572-99a72849c8d6",
"outgoing_recurrence_status": "pending_confirmation",
"qr_code_data": {
"qr_code_url": "url",
"qr_code_key": "98fc62fd-b0a0-4604-9bea-475e91a9dc85",
"qr_code_image": "imageb64"
},
"initial_payment_data": {
"receiver_conciliation_id": "6f270b64-1b7a-4269-91f8-3f9cf30ba0bb"
},
"created_at": "2021-10-22T20:30:23.459Z"
}
```
### Response Fields
Field Type Description Characters
request_control_key uuid Control key sent by client 36
recurrence_key uuid Subscription recurrence identification 36
recurrence_status enumerator Recurrence status recurrence_status enumerators
qr_code_data Object QR generated data for the first payment qr_code_data object
initial_payment_data Object Initial payment information initial_payment_data object
created_at string Creation date/time (ISO 8601) -
#### qr_code_data object
Field Type Description Characters
qr_code_url string Copy and paste URL -
qr_code_key uuid QR identifier 36
qr_code_image string Image (Base64) -
#### initial_payment_data object
Field Type Description Characters
receiver_conciliation_id string Payment reconciliation ID 32
#### recurrence_status enumerators
Enumerator Description
pending_confirmation Pending confirmation
active Active
cancelled Cancelled
suspended Suspended
expired Expired
---
## Tips and Best Practices
✓
Reconciliation in variable recurrence: for variable_amount , reconcile the amount 10 to 3 days before the charge date.
✓
Pix messages: use pix_message with up to 140 characters to clearly explain the initial charge.
⚠
Security: validate documents/accounts and handle network and external integration errors with idempotent retries.
---
# Create a Recurrence (Journey 2)
URL: /en/documentation/baas/pix_automatico/recebedor/journey_two
> Journey 2 — QR Code with recurrence data only
{`
.hero-section { background: linear-gradient(135deg, #eff6ff 0%, #ffffff 100%); border: 1px solid #e5e7eb; border-radius: 16px; padding: 24px; margin: 24px 0 32px 0; }
.hero-grid { display: grid; grid-template-columns: repeat(auto-fit, minmax(220px, 1fr)); gap: 16px; margin-top: 20px; }
.hero-item { background: #ffffff; border: 1px solid #e5e7eb; border-radius: 10px; padding: 16px; }
.hero-item > strong { display: block; color: #1e40af; font-size: 14px; margin-bottom: 6px; font-weight: 700; }
.hero-item p { margin: 0; font-size: 13px; color: #475569; line-height: 1.5; }
.endpoint-card { background: linear-gradient(135deg, #ffffff 0%, #f8fafc 100%); border: 2px solid #e5e7eb; border-radius: 12px; padding: 24px; position: relative; overflow: hidden; }
.endpoint-card::before { content: ''; position: absolute; top: 0; left: 0; width: 4px; height: 100%; background: linear-gradient(to bottom, #3b82f6, #1e40af); }
.endpoint-list { display: grid; gap: 12px; font-size: 13px; color: #334155; }
.endpoint__item { display: grid; grid-template-columns: 120px 1fr; align-items: center; gap: 12px; background: #ffffff; border: 1px solid #e5e7eb; border-radius: 8px; padding: 10px 14px; }
.badge { font-size: 11px; font-weight: 800; padding: 4px 10px; border-radius: 6px; color: #fff; text-transform: uppercase; letter-spacing: .4px; background: #1e40af; }
.details-container { background: linear-gradient(135deg, #ffffff 0%, #f8fafc 100%); border: 1px solid #e5e7eb; border-radius: 10px; padding: 8px 12px; margin: 20px 0; }
.details-container summary { font-weight: 700; color: #1e40af; cursor: pointer; font-size: 14px; padding: 10px 0 10px 28px; display: flex; align-items: center; position: relative; }
.details-container summary::-webkit-details-marker { display: none; }
.details-container summary::before { content: ''; position: absolute; left: 10px; width: 0; height: 0; border-left: 7px solid #1e40af; border-top: 6px solid transparent; border-bottom: 6px solid transparent; transition: transform .2s ease; }
.details-container[open] summary::before { transform: rotate(90deg); }
.code-block { margin-top: 12px; border-radius: 8px; overflow: hidden; }
.table-container { overflow: auto; border: 0; border-radius: 0; margin: 20px 0; background: transparent; }
.table-container table { width: 100%; border-collapse: collapse; font-size: 13px; }
.table-container th, .table-container td { border-top: 1px solid #e5e7eb; padding: 12px 16px; text-align: left; }
.table-container thead th { background: linear-gradient(135deg, #f8fafc 0%, #ffffff 100%); font-weight: 700; color: #0f172a; font-size: 13px; }
`}
Overview
What is it QR Code that presents only the recurrence data for the payer to authorize, without immediate charge.
When to use Onboarding without initial charge; use at points of sale, counters, screens or printed materials.
How it works Payer reads QR → views recurrence data in app → authorizes → future charges can be scheduled.
Benefits Agile enablement via QR; allows mass customer acquisition with low friction and QR can be reused for new recurrences.
## Request
{`
.endpoint-card { background: linear-gradient(135deg, #ffffff 0%, #f8fafc 100%); border: 2px solid #e5e7eb; border-radius: 12px; padding: 24px; position: relative; overflow: hidden; }
.endpoint-card::before { content: ''; position: absolute; top: 0; left: 0; width: 4px; height: 100%; background: linear-gradient(to bottom, #3b82f6, #1e40af); }
.endpoint-list { display: grid; gap: 12px; font-size: 13px; color: #334155; }
.endpoint__item { display: grid; grid-template-columns: 120px 1fr; align-items: center; gap: 12px; background: #ffffff; border: 1px solid #e5e7eb; border-radius: 8px; padding: 10px 14px; }
.badge { font-size: 11px; font-weight: 800; padding: 4px 10px; border-radius: 6px; color: #fff; text-transform: uppercase; letter-spacing: .4px; background: #1e40af; }
.details-container { background: linear-gradient(135deg, #ffffff 0%, #f8fafc 100%); border: 1px solid #e5e7eb; border-radius: 10px; padding: 8px 12px; margin: 20px 0; }
.details-container summary { font-weight: 700; color: #1e40af; cursor: pointer; font-size: 14px; padding: 10px 0 10px 28px; display: flex; align-items: center; position: relative; }
.details-container summary::-webkit-details-marker { display: none; }
.details-container summary::before { content: ''; position: absolute; left: 10px; width: 0; height: 0; border-left: 7px solid #1e40af; border-top: 6px solid transparent; border-bottom: 6px solid transparent; transition: transform .2s ease; }
.details-container[open] summary::before { transform: rotate(90deg); }
.code-block { margin-top: 12px; border-radius: 8px; overflow: hidden; }
`}
ENDPOINT /account/ account_key /outgoing_recurrence/journey_two
METHOD POST
### Request Path Params
| Field | Type | Description | Characters |
|---------------|-------|------------------------------------------------|------------|
| `account_key`*| uuid4 | Unique identifier key for the account. | 36 |
### Request Body
**Request Body: Create Recurrence (Journey 2)**
```json
{
"request_control_key": "98fc62fd-b0a0-4604-9bea-475e91a9dc82",
"periodicity": "monthly",
"minimum_recurrence_amount": 125,
"start_date": "2025-06-10",
"end_date": "2027-06-10",
"pix_message": "Conta de Luz Residencial nº123",
"recurrence_type": "variable_amount",
"debtor_data": {
"name": "Sebastião",
"email": "sebastiao@test.com",
"document_number": "05431134850",
"contract_id": "124587624",
"address": {
"street": "Av. Brigadeiro Faria Lima",
"state": "SP",
"city": "São Paulo",
"neighborhood": "Jardim Paulistano",
"number": "2391",
"postal_code": "01452905",
"complement": "Complemento"
}
},
"retry_configuration": {
"retry_allowed": true,
"retry_rule": {
"first_retry": {
"day": "1"
},
"second_retry": {
"day": "3"
},
"third_retry": {
"day": "4"
}
}
},
"settlement_date_type": "workdays"
}
```
### Body Params
| Field | Type | Description | Characters |
|--------------------------------|------------|------------------------------------------------------------------------------------------------------------|------------|
| `request_control_key` * | uuid | Unique request identifier key used by the client in uuid4 format. | 36 |
| `periodicity` * | enumerator | Type of periodicity associated with the subscription recurrence. | [periodicity Enumerators](#periodicity-enumerators) |
| `minimum_recurrence_amount` | number | Minimum transaction amount for variable amount recurrences (in cents). | - |
| `start_date` * | string | Recurrence start date (ISO 8601 format, e.g., "2025-07-01"). | - |
| `end_date` | string | Recurrence end date; for indefinite period, send as null. | - |
| `pix_message` * | string | Message to be sent with the PIX transaction. | 140 |
| `debtor_data` * | Object | Debtor (subscriber) data. | [debtor_data Object](#debtor_data-object) |
| `retry_configuration` * | Object | Retry configuration for incomplete transactions. | [retry_configuration Object](#retry_configuration-object) |
| `settlement_date_type` * | enumerator | Type of settlement date adjustment | [settlement_date_type Enumerators](#settlement_date_type-enumerators) |
| `recurrence_type` * | enumerator | Type of recurrence | [recurrence_type Enumerators](#recurrence_type-enumerators) |
:::caution Attention
The field `minimum_recurrence_amount` is optional and should only be informed for variable amount recurrence. If the recurrence is fixed amount, the field `recurrence_amount` should be sent with the recurrence amount. As well as the `recurrence_type` enumerator, which should correspond to the recurrence type (Fixed amount or variable).
:::
### periodicity Enumerators
| Enumerator | Description |
|--------------|-----------------------|
| `weekly` | Weekly recurrence |
| `monthly` | Monthly recurrence |
| `quarterly` | Quarterly recurrence|
| `semiannual` | Semiannual recurrence |
| `annual` | Annual recurrence |
### settlement_date_type Enumerators
| Enumerator | Description |
|--------------|-----------------------|
| `workdays` | Business days |
| `calendar_days` | Calendar days |
### recurrence_type Enumerators
| Enumerator | Description |
|--------------|-----------------------|
| `fixed_amount` | Fixed Amount Recurrence |
| `variable_amount` | Variable Amount Recurrence |
### debtor_data Object
| Field | Type | Description | Characters |
|---------------------|--------|-----------------------|------------|
| `name` * | string | Subscriber name. | 50 |
| `email` * | string | Subscriber email. | 100 |
| `document_number` * | string | Subscriber CPF or CNPJ. | 14 |
| `contract_id` | string | Subscriber contract identifier. | 100 |
| `address` * | Object | Subscriber address.| [address Object](#address-object) |
### address Object
| Field | Type | Description | Characters |
|---------------|--------|-------------------|------------|
| `street` | string | Street. | - |
| `state` | string | State. | - |
| `city` | string | City. | - |
| `neighborhood`| string | Neighborhood. | - |
| `number` | string | Number. | - |
| `postal_code` | string | Postal code. | - |
| `complement` | string | Complement. | - |
### retry_configuration Object
| Field | Type | Description | Characters |
|---------------|---------|-------------------------|------------|
| `retry_allowed`| boolean | Indicates whether retries are allowed. | - |
| `retry_rule` | Object | Retry rules. | [retry_rule Object](#retry_rule-object) |
### retry_rule Object
| Field | Type | Description | Characters |
|---------------|--------|-------------------------|------------|
| `first_retry` | Object | First retry configuration. | [retry_detail Object](#retry_detail-object) |
| `second_retry`| Object | Second retry configuration. | [retry_detail Object](#retry_detail-object) |
| `third_retry` | Object | Third retry configuration. | [retry_detail Object](#retry_detail-object) |
### retry_detail Object
| Field | Type | Description | Characters |
|-------|--------|-------------------------|------------|
| `day` | string | Retry day. | - |
## Response
STATUS 200
**Response Body**
```json
{
"request_control_key": "98fc62fd-b0a0-4604-9bea-475e91a9dc82",
"outgoing_recurrence_key": "8cb70dea-9fb0-4a68-9572-99a72849c8d6",
"outgoing_recurrence_status": "pending_confirmation",
"qr_code_data": {
"qr_code_url": "url",
"qr_code_key": "98fc62fd-b0a0-4604-9bea-475e91a9dc85",
"qr_code_image": "imageb64"
},
"created_at": "2021-10-22T20:30:23.459Z"
}
```
### Response Body
| Field | Type | Description | Characters |
|-----------------------|------------|---------------------------------------------------------------------------|------------|
| `request_control_key` | uuid | Request control key sent by the client. | 36 |
| `recurrence_key` | uuid | Unique identifier key for the subscription recurrence. | 36 |
| `recurrence_status` | enumerator | Current recurrence status. | [recurrence_status Enumerators](#recurrence_status-enumerators) |
| `qr_code_data` | enumerator | Current recurrence status. | [qr_code_data Object](#qr_code_data-enumerators) |
| `created_at` | string | Recurrence creation date and time (ISO 8601 format). | - |
### qr_code_data Object
| Field | Type | Description | Characters |
|-------|--------|-------------------------|------------|
| `qr_code_url` | string | URL of the QR code copy and paste | - |
| `qr_code_key`| uuuid | Unique identifier key for the QR code. | 36 |
| `qr_code_image`| string | Base64 of the QR code image | - |
### recurrence_status Enumerators
| Enumerator | Description |
|----------------------|-----------------------------------|
| `pending_confirmation` | Recurrence pending confirmation |
| `active` | Active recurrence |
| `cancelled` | Cancelled recurrence |
| `suspended` | Suspended recurrence |
| `expired` | Expired recurrence |
STATUS 4XX
**Response Error**
```json
{
"title": "titulo",
"description": "description in English",
"translation": "descrição em português",
"code": "codigo"
}
```
| HTTP Code | QI Code `code` | Title `title` | Description (eng) `description` | Description (ptbr) `translation` |
|-------------|----------------------|-----------------------------------|----------------------------------------------------------------------------|--------------------------------------------------------------------|
| 400 | QIT000002 | Bad Request | Invalid request schema. | Erro no esquema da requisição. |
| 403 | APX000030 | Unauthorized Transaction | User is not authorized to create this recurrence. | Usuário não autorizado a criar esta recorrência. |
| 403 | APX000018 | Endpoint Access Denied | Requester lacks permission to access this endpoint. | Requester não possui permissão para acessar este endpoint. |
| 404 | APX000021 | Subscription Not Found | Subscription \{subscription_key\} not found. | Assinatura \{subscription_key\} não encontrada. |
| 404 | APX000002 | Recurrence Not Found | Recurrence \{recurrence_key\} not found. | Recorrência \{recurrence_key\} não encontrada. |
| 406 | APX000027 | Invalid Transaction Amount | Transaction amount \{minimum_transaction_amount\} is invalid. | Valor da transação \{minimum_transaction_amount\} é inválido. |
| 409 | APX000014 | Request Control Key Conflict | The request_control_key \{request_control_key\} is already in use. | A request_control_key \{request_control_key\} já está em uso. |
---
# Requester Recurrence Listing
URL: /en/documentation/baas/pix_automatico/recebedor/listar_recorrencias_de_um_requester
## Request
ENDPOINT /outgoing_recurrences
METHOD GET
### Query Params
| Field | Type | Description | Characters |
|-----------------------------|-------------|----------------------------------------------------------------------------|------------|
| `outgoing_recurrence_status`| enumerator | Filters recurrences by status (`approved`, `pending`, `rejected`, `pending_confirmation`) | 30 |
| `page` | integer | Page number to be returned (pagination). | - |
| `page_size` | integer | Number of items per page (pagination). | - |
---
## Response
STATUS 200
Response Body
```json
{
"outgoing_recurrences": [
{
"request_control_key": "98fc62fd-b0a0-4604-9bea-475e91a9dc82",
"outgoing_recurrence_key": "8cb70dea-9fb0-4a68-9572-99a72849c8d6",
"outgoing_recurrence_status": "approved",
"periodicity": "monthly",
"journey_type": "journey_four",
"start_date": "2025-06-10",
"end_date": "2027-06-10",
"account_key": "uuuid",
"outgoing_recurrence_data": {
"minimum_recurrence_amount": 123.45,
"recurrence_amount": null,
"retry_configuration": {
"retry_allowed": true,
"retry_rule": {
"first_retry": {
"day": "1",
"time": "14:00"
},
"second_retry": {
"day": "3",
"time": "12:00"
},
"third_retry": {
"day": "4",
"time": "15:32"
}
}
},
"debtor_data": {
"name": "Sebastião",
"email": "sebastiao@test.com",
"document_number": "05431134850",
"address": {
"city": "São Paulo",
"postal_code": "123456-789",
"uf": "SP",
"street": "Av Paulista 123"
},
"account_data": {
"account_number": "123456",
"account_digit": "7",
"account_branch": "0001",
"ispb": "31872495"
}
},
"qr_code_data": {
"qr_code_key": "0f45cc3d-9bd1-4d68-a865-4cf477b5da45",
"qr_code_url": "urlqrcode.url",
"qr_code_image": "image_base64"
},
"initial_payment_data": {
"amount": 22.34,
"pix_key": "3d7d6a2b-f72f-44z7-bb20-79a94dff5645",
"qr_code_type": "dynamic_term",
"additional_data": [
{
"key_name": "Juros e Multa",
"value": "Juros 2 ao mes e multa de 1%"
}
],
"fine_amount": 3,
"interest_amount": 2,
"expiration_date": "2023-03-25",
"max_payment_days": 128,
"rebate_amount": 1,
"discounts": [],
"receiver_conciliation_id":"3d7d6a2bf72f44z7bb2079a94dff5645",
"transaction_data":{
"transaction_key":"4d7d6a2b-f72f-44z7-bb20-79a94dff5645",
"pix_transfer_key":"5d7d6a2b-f72f-44z7-bb20-79a94dff5645",
"end_to_end_id":"E32402502202303141907qlBAF1evdJ2"
}
},
"pix_message": "Conta de Luz Residencial nº123",
"settlement_date_type": "calendar_days"
}
}
],
"pagination": {
"page": 1,
"page_size": 25,
"number_of_pages": 4
}
}
```
### Response Body Params
| Field | Type | Description | Characters |
|------------------------|--------|-----------------------------------------------------------------------------------------|------------|
| `outgoing_recurrences` | array | List of automatic recurrence objects. | [Array outgoing_recurrences](#array-outgoing_recurrences) |
| `pagination` | object | Pagination object containing information about result pages. | [Object pagination](#object-pagination) |
---
### Array outgoing_recurrences
| Field | Type | Description | Characters |
|------------------------------|------------|-----------------------------------------------------------------------------------------|------------|
| `request_control_key` | uuidv4 | Unique key for request control. | 36 |
| `outgoing_recurrence_key` | uuidv4 | Automatic recurrence identifier. | 36 |
| `account_key` | uuidv4 | Unique account identification key | 36 |
| `outgoing_recurrence_status` | string | Current recurrence status (`approved`, `pending`, `rejected`, etc.). | 30 |
| `periodicity` | enumerator | Recurrence periodicity. | [Enumerators periodicity](#enumerators-periodicity) |
| `journey_type` | enumerator | Automatic recurrence journey. | [Enumerators journey_type](#enumerators-journey_type) |
| `start_date` | string | Recurrence start date (ISO 8601 format, e.g., `2025-06-10`). | 10 |
| `end_date` | string | Recurrence end date (ISO 8601 format) or null if indeterminate. | 10 or null |
| `outgoing_recurrence_data` | object | Object grouping subscription parameters and complementary data. | [Object outgoing_recurrence_data](#object-outgoing_recurrence_data) |
---
### Object outgoing_recurrence_data
| Field | Type | Description | Characters |
|-----------------------------|----------|----------------------------------------------------------------|------------|
| `minimum_recurrence_amount` | number | Expected minimum value for variable amount recurrences | - |
| `recurrence_amount` | number | Recurrence amount (for fixed value; null if variable) | - |
| `retry_configuration` | object | Retry configuration for incomplete recurrences | [Object retry_configuration](#object-retry_configuration) |
| `debtor_data` | object | Debtor (subscriber) data | [Object debtor_data](#object-debtor_data) |
| `qr_code_data` | object | QR Code data generated for payment (if any) | [Object qr_code_data](#object-qr_code_data) |
| `initial_payment_data` | object | Initial charge data | [Object initial_payment_data](#object-initial_payment_data) |
| `pix_message` | string | Message sent along with the PIX transaction | 140 |
| `settlement_date_type` | enumerator| Settlement date adjustment type | [Enumerators settlement_date_type](#enumerators-settlement_date_type) |
---
### Object retry_configuration
| Field | Type | Description | Characters |
|-----------------|---------|------------------------------------------------|------------|
| `retry_allowed` | boolean | Indicates if retries are enabled | - |
| `retry_rule` | object | Detailed retry rules | [Object retry_rule](#object-retry_rule) |
---
### Object retry_rule
| Field | Type | Description | Characters |
|---------------|--------|-----------------------------------|------------|
| `first_retry` | object | Configuration for 1st retry | [Object retry_detail](#object-retry_detail) |
| `second_retry`| object | Configuration for 2nd retry | [Object retry_detail](#object-retry_detail) |
| `third_retry` | object | Configuration for 3rd retry | [Object retry_detail](#object-retry_detail) |
---
### Object retry_detail
| Field | Type | Description | Characters |
|-------|--------|---------------------------|------------|
| `day` | string | Retry day. | - |
| `time`| string | Retry time. | - |
---
### Object debtor_data
| Field | Type | Description | Characters |
|-------------------|--------|----------------------------|------------|
| `name` | string | Subscriber name. | 50 |
| `email` | string | Subscriber email. | 100 |
| `document_number` | string | CPF or CNPJ. | 14 |
| `address` | object | Subscriber address. | [Object address](#object-address) |
| `account_data` | object | Bank account data. | [Object account_data](#object-account_data) |
---
### Object address
| Field | Type | Description | Characters |
|---------------|--------|---------------------|------------|
| `city` | string | City. | - |
| `postal_code` | string | Postal code. | - |
| `uf` | string | State (abbreviation).| - |
| `street` | string | Street address. | - |
---
### Object account_data
| Field | Type | Description | Characters |
|-----------------|--------|----------------------------------|------------|
| `account_number`| string | Account number | - |
| `account_digit` | string | Account digit | - |
| `account_branch`| string | Branch | - |
| `ispb` | string | Financial institution ISPB | - |
---
### Object qr_code_data
| Field | Type | Description | Characters |
|------------------|--------|-------------------------------------------------|------------|
| `qr_code_key` | string | Generated QR Code identifier | - |
| `qr_code_url` | string | URL for QR Code visualization | - |
| `qr_code_image` | string | QR Code image (in Base64) | - |
---
### Object initial_payment_data
| Field | Type | Description | Characters |
|---------------------------|----------|------------------------------------------------------------------------------|------------|
| `amount` | number | Main amount of the initial charge in reais (R$) | - |
| `pix_key` | string | Destination PIX key for initial payment | 77 |
| `qr_code_type` | enum | QR Code type for initial charge. | [Enumerators qr_code_type](#enumerators-qr_code_type) |
| `additional_data` | array | List of additional information related to the charge | [Array of objects additional_data](#array-additional_data) |
| `fine_amount` | number | Fine amount in case of payment delay | - |
| `interest_amount` | number | Interest amount in case of payment delay | - |
| `expiration_date` | string | Initial charge expiration date (ISO 8601 format) | 10 |
| `max_payment_days` | integer | Maximum number of acceptance days after expiration | - |
| `rebate_amount` | number | Discount amount for early payment | - |
| `discounts` | array | List of additional discounts | - |
| `receiver_conciliation_id`| string | Payment conciliation identifier by the receiver | 35 |
| `transaction_data` | object | Transaction details related to the initial charge | [Object transaction_data](#object-transaction_data) |
---
### Array additional_data
| Field | Type | Description | Characters |
|--------------|---------|---------------------------------------------------------------|------------|
| `key_name` | string | Additional information name (e.g., "Interest and Fine") | 140 |
| `value` | string | Additional information value or description | 140 |
---
### Object transaction_data
| Field | Type | Description | Characters |
|---------------------|--------|----------------------------------------|------------|
| `transaction_key` | string | Unique transaction key | 36 |
| `pix_transfer_key` | string | PIX transfer identifier | 36 |
| `end_to_end_id` | string | PIX end-to-end identifier | 32 |
---
### Object pagination
| Field | Type | Description | Characters |
|------------------|---------|-------------------------------------|------------|
| `page` | integer | Returned page number. | - |
| `page_size` | integer | Number of items per page. | - |
| `number_of_pages`| integer | Total number of available pages. | - |
---
### Enumerators periodicity
| Enumerator | Description |
|--------------|-----------------------|
| `weekly` | Weekly recurrence |
| `monthly` | Monthly recurrence |
| `quarterly` | Quarterly recurrence |
| `semiannual` | Semiannual recurrence |
| `annual` | Annual recurrence |
---
### Enumerators journey_type
| Enumerator | Description |
|-----------------|---------------------------------------------------|
| `journey_one` | Direct notification in banking app |
| `journey_two` | QR Code experience for recurrent billing |
| `journey_three` | Instant payment + QR Code recurrence |
| `journey_four` | Recurrent opt-in from PIX operation |
---
### Enumerators settlement_date_type
| Enumerator | Description |
|-----------------|-------------------|
| `workdays` | Business days |
| `calendar_days` | Calendar days |
---
### Enumerators qr_code_type
| Enumerator | Description |
|-------------------|-------------------------------------------------------|
| `dynamic_instant` | Dynamic QR Code for instant payment |
| `dynamic_term` | Dynamic QR Code for payment with future due date |
STATUS 4XX
Response Error
```json
{
"title": "titulo",
"description": "description in English",
"translation": "descrição em português",
"code": "codigo"
}
```
| HTTP Code | QI Code `code` | Title `title` | Description (eng) `description` | Description (ptbr) `translation` |
|-------------|----------------------|-----------------------------------|----------------------------------------------------------------------------|-------------------------------------------------------------------|
| 400 | QIT000002 | Bad Request | Invalid request schema. | Erro no esquema da requisição. |
| 404 | APX000002 | Recurrence Not Found | Recurrence \{recurrence_key\} not found. | Recorrência \{recurrence_key\} não encontrada. |
---
# Account Recurrences Listing
URL: /en/documentation/baas/pix_automatico/recebedor/listar_recorrencias_de_uma_conta
## Request
ENDPOINT /account/ ACCOUNT_KEY /outgoing_recurrences
METHOD GET
### Query Params
| Field | Type | Description | Characters |
|-----------------------------|-------------|------------------------------------------------------------------------|------------|
| `outgoing_recurrence_status`| enumerator | Filters recurrences by status (`approved`, `pending`, `rejected`, `pending_confirmation`) | 30 |
| `page` | integer | Page number to be returned (pagination). | - |
| `page_size` | integer | Number of items per page (pagination). | - |
---
## Response
STATUS 200
Response Body
```json
{
"outgoing_recurrences": [
{
"request_control_key": "98fc62fd-b0a0-4604-9bea-475e91a9dc82",
"outgoing_recurrence_key": "8cb70dea-9fb0-4a68-9572-99a72849c8d6",
"outgoing_recurrence_status": "approved",
"periodicity": "monthly",
"journey_type": "journey_four",
"start_date": "2025-06-10",
"end_date": "2027-06-10",
"outgoing_recurrence_data": {
"minimum_recurrence_amount": 123.45,
"recurrence_amount": null,
"retry_configuration": {
"retry_allowed": true,
"retry_rule": {
"first_retry": {
"day": "1",
"time": "14:00"
},
"second_retry": {
"day": "3",
"time": "12:00"
},
"third_retry": {
"day": "4",
"time": "15:32"
}
}
},
"debtor_data": {
"name": "Sebastião",
"email": "sebastiao@test.com",
"document_number": "05431134850",
"address": {
"city": "São Paulo",
"postal_code": "123456-789",
"uf": "SP",
"street": "Av Paulista 123"
},
"account_data": {
"account_number": "123456",
"account_digit": "7",
"account_branch": "0001",
"ispb": "31872495"
}
},
"qr_code_data": {
"qr_code_key": "0f45cc3d-9bd1-4d68-a865-4cf477b5da45",
"qr_code_url": "urlqrcode.url",
"qr_code_image": "image_base64"
},
"initial_payment_data": {
"amount": 22.34,
"pix_key": "3d7d6a2b-f72f-44z7-bb20-79a94dff5645",
"qr_code_type": "dynamic_term",
"additional_data": [
{
"key_name": "Juros e Multa",
"value": "Juros 2 ao mes e multa de 1%"
}
],
"fine_amount": 3,
"interest_amount": 2,
"expiration_date": "2023-03-25",
"max_payment_days": 128,
"rebate_amount": 1,
"discounts": [],
"receiver_conciliation_id":"3d7d6a2bf72f44z7bb2079a94dff5645",
"transaction_data":{
"transaction_key":"4d7d6a2b-f72f-44z7-bb20-79a94dff5645",
"pix_transfer_key":"5d7d6a2b-f72f-44z7-bb20-79a94dff5645",
"end_to_end_id":"E32402502202303141907qlBAF1evdJ2"
}
},
"pix_message": "Conta de Luz Residencial nº123",
"settlement_date_type": "calendar_days"
}
}
],
"pagination": {
"page": 1,
"page_size": 25,
"number_of_pages": 4
}
}
```
### Response Body Params
| Field | Type | Description | Characters |
|------------------------|--------|-----------------------------------------------------------------------------------------|------------|
| `outgoing_recurrences` | array | List of automatic recurrence objects. | [Array outgoing_recurrences](#array-outgoing_recurrences) |
| `pagination` | object | Pagination object containing information about result pages. | [Object pagination](#object-pagination) |
---
### Array outgoing_recurrences
| Field | Type | Description | Characters |
|------------------------------|------------|-----------------------------------------------------------------------------------------|------------|
| `request_control_key` | uuidv4 | Unique key for request control. | 36 |
| `outgoing_recurrence_key` | uuidv4 | Automatic recurrence identifier. | 36 |
| `outgoing_recurrence_status` | string | Current status of the recurrence (`approved`, `pending`, `rejected`, etc.). | 30 |
| `periodicity` | enumerator | Recurrence periodicity. | [Enumerators periodicity](#enumerators-periodicity) |
| `journey_type` | enumerator | Automatic recurrence journey. | [Enumerators journey_type](#enumerators-journey_type) |
| `start_date` | string | Recurrence start date (ISO 8601 format, e.g., `2025-06-10`). | 10 |
| `end_date` | string | Recurrence end date (ISO 8601 format) or null, if indeterminate. | 10 or null |
| `outgoing_recurrence_data` | object | Object grouping subscription parameters and complementary data. | [Object outgoing_recurrence_data](#object-outgoing_recurrence_data) |
---
### Object outgoing_recurrence_data
| Field | Type | Description | Characters |
|-----------------------------|----------|----------------------------------------------------------------|------------|
| `minimum_recurrence_amount` | number | Minimum expected amount for variable amount recurrences | - |
| `recurrence_amount` | number | Recurrence amount (for fixed amount; null if variable) | - |
| `retry_configuration` | object | Configuration for attempts on incomplete recurrences | [Object retry_configuration](#object-retry_configuration) |
| `debtor_data` | object | Debtor (subscriber) data | [Object debtor_data](#object-debtor_data) |
| `qr_code_data` | object | QR Code data generated for payment (if any) | [Object qr_code_data](#object-qr_code_data) |
| `initial_payment_data` | object | Initial charge data | [Object initial_payment_data](#object-initial_payment_data) |
| `pix_message` | string | Message sent along with the PIX transaction | 140 |
| `settlement_date_type` | enumerator| Settlement date adjustment type | [Enumerators settlement_date_type](#enumerators-settlement_date_type) |
---
### Object retry_configuration
| Field | Type | Description | Characters |
|-----------------|---------|---------------------------------------------|------------|
| `retry_allowed` | boolean | Indicates if retries are enabled | - |
| `retry_rule` | object | Detailed retry rules | [Object retry_rule](#object-retry_rule) |
---
### Object retry_rule
| Field | Type | Description | Characters |
|---------------|--------|-----------------------------------|------------|
| `first_retry` | object | Configuration for 1st retry | [Object retry_detail](#object-retry_detail) |
| `second_retry`| object | Configuration for 2nd retry | [Object retry_detail](#object-retry_detail) |
| `third_retry` | object | Configuration for 3rd retry | [Object retry_detail](#object-retry_detail) |
---
### Object retry_detail
| Field | Type | Description | Characters |
|-------|--------|-------------------------|------------|
| `day` | string | Retry day. | - |
| `time`| string | Retry time. | - |
---
### Object debtor_data
| Field | Type | Description | Characters |
|-------------------|--------|------------------------|------------|
| `name` | string | Subscriber name. | 50 |
| `email` | string | Subscriber email. | 100 |
| `document_number` | string | CPF or CNPJ. | 14 |
| `address` | object | Subscriber address. | [Object address](#object-address) |
| `account_data` | object | Bank account data. | [Object account_data](#object-account_data) |
---
### Object address
| Field | Type | Description | Characters |
|---------------|--------|-------------------|------------|
| `city` | string | City. | - |
| `postal_code` | string | ZIP code. | - |
| `uf` | string | State (abbreviation). | - |
| `street` | string | Street address. | - |
---
### Object account_data
| Field | Type | Description | Characters |
|-----------------|--------|------------------------------|------------|
| `account_number`| string | Account number | - |
| `account_digit` | string | Account digit | - |
| `account_branch`| string | Branch | - |
| `ispb` | string | Financial institution ISPB| - |
---
### Object qr_code_data
| Field | Type | Description | Characters |
|------------------|--------|---------------------------------------------|------------|
| `qr_code_key` | string | Generated QR Code identifier | - |
| `qr_code_url` | string | URL for QR Code visualization | - |
| `qr_code_image` | string | QR Code image (in Base64) | - |
---
### Object initial_payment_data
| Field | Type | Description | Characters |
|---------------------------|----------|--------------------------------------------------------------------------|------------|
| `amount` | number | Main amount of the initial charge in reais (R$) | - |
| `pix_key` | string | Destination PIX key for initial payment | 77 |
| `qr_code_type` | enum | QR Code type for initial charge. | [Enumerators qr_code_type](#enumerators-qr_code_type) |
| `additional_data` | array | List of additional information related to the charge | [Array of objects additional_data](#array-additional_data) |
| `fine_amount` | number | Fine amount, if payment delay occurs | - |
| `interest_amount` | number | Interest amount, if payment delay occurs | - |
| `expiration_date` | string | Initial charge expiration date (ISO 8601 format) | 10 |
| `max_payment_days` | integer | Maximum number of acceptance days after expiration | - |
| `rebate_amount` | number | Discount amount for early payment | - |
| `discounts` | array | List of additional discounts | - |
| `receiver_conciliation_id`| string | Payment conciliation identifier by receiver | 35 |
| `transaction_data` | object | Transaction details related to the initial charge | [Object transaction_data](#object-transaction_data) |
---
### Array additional_data
| Field | Type | Description | Characters |
|--------------|---------|-----------------------------------------------------------|------------|
| `key_name` | string | Additional information name (e.g., "Juros e Multa") | 140 |
| `value` | string | Additional information value or description | 140 |
---
### Object transaction_data
| Field | Type | Description | Characters |
|---------------------|--------|----------------------------------------|------------|
| `transaction_key` | string | Unique transaction key | 36 |
| `pix_transfer_key` | string | PIX transfer identifier | 36 |
| `end_to_end_id` | string | PIX end-to-end identifier | 32 |
---
### Object pagination
| Field | Type | Description | Characters |
|------------------|---------|-------------------------------------|------------|
| `page` | integer | Returned page number. | - |
| `page_size` | integer | Number of items per page. | - |
| `number_of_pages`| integer | Total available pages. | - |
---
### Enumerators periodicity
| Enumerator | Description |
|--------------|-----------------------|
| `weekly` | Weekly recurrence |
| `monthly` | Monthly recurrence |
| `quarterly` | Quarterly recurrence|
| `semiannual` | Semiannual recurrence |
| `annual` | Annual recurrence |
---
### Enumerators journey_type
| Enumerator | Description |
|-----------------|----------------------------------------------|
| `journey_one` | Direct notification in banking app |
| `journey_two` | QR Code experience for recurring charge |
| `journey_three` | Instant payment + recurring QR Code |
| `journey_four` | Recurring opt-in from PIX operation |
---
### Enumerators settlement_date_type
| Enumerator | Description |
|-----------------|------------------|
| `workdays` | Business days |
| `calendar_days` | Calendar days |
---
### Enumerators qr_code_type
| Enumerator | Description |
|-------------------|---------------------------------------------------|
| `dynamic_instant` | Dynamic QR Code for instant payment |
| `dynamic_term` | Dynamic QR Code for payment with future due date |
STATUS 4XX
Response Error
```json
{
"title": "titulo",
"description": "description in English",
"translation": "descrição em português",
"code": "codigo"
}
```
| HTTP Code | QI Code `code` | Title `title` | Description (eng) `description` | Description (ptbr) `translation` |
|-------------|----------------------|-----------------------------------|----------------------------------------------------------------------------|--------------------------------------------------------------------|
| 400 | QIT000002 | Bad Request | Invalid request schema. | Erro no esquema da requisição. |
| 404 | APX000002 | Recurrence Not Found | Recurrence \{recurrence_key\} not found. | Recorrência \{recurrence_key\} não encontrada. |
---
# Scenario Simulation
URL: /en/documentation/baas/pix_automatico/recebedor/simulacao
Complete guide to simulate the receiver flow of the automatic-pix-api in sandbox environment. This guide includes both mock endpoints and real endpoints necessary for the complete test flow.
:::caution Important Prerequisites
Before executing any mock simulation, you **must** create a recurrence using one of the available authorization journeys. Mocks only simulate SPI responses, but the recurrence needs to exist in the system.
**Check the creation journeys:**
- [Journey 1 - Push Notification](./journey_one.md)
- [Journey 2 - QR Code (recurrence only)](./journey_two.md)
- [Journey 3 - QR Code (with first payment)](./journey_three.md)
- [Journey 4 - QR Code (with first payment and variable amounts)](./journey_four.md)
:::
{`
.pix-flow-container {
width: 100%;
max-width: 800px;
margin: 40px auto;
background-color: #f8fafc;
border-radius: 16px;
box-shadow: 0 10px 30px rgba(0, 0, 0, 0.1);
padding: 30px;
position: relative;
border: 1px solid #e5e7eb;
}
.pix-flow-header {
text-align: center;
margin-bottom: 30px;
border-bottom: 2px solid #e5e7eb;
padding-bottom: 20px;
position: relative;
}
.pix-flow-header h3 {
font-size: 24px;
font-weight: 700;
color: #1e40af;
text-transform: uppercase;
letter-spacing: 1px;
margin-bottom: 8px;
}
.pix-flow-header p {
font-size: 14px;
color: #64748b;
}
.status-indicator {
position: absolute;
top: 10px;
right: 10px;
display: flex;
align-items: center;
gap: 6px;
font-size: 12px;
color: #64748b;
}
.status-light {
width: 10px;
height: 10px;
border-radius: 50%;
background-color: #10b981;
animation: pulse-status 2s infinite;
}
@keyframes pulse-status {
0%, 100% { opacity: 1; box-shadow: 0 0 0 0 rgba(16, 185, 129, 0.7); }
50% { opacity: 0.8; box-shadow: 0 0 0 8px rgba(16, 185, 129, 0); }
}
.pix-flowchart {
display: flex;
flex-direction: column;
gap: 20px;
max-height: 800px;
overflow-y: auto;
padding-right: 10px;
}
.pix-flowchart::-webkit-scrollbar {
width: 8px;
}
.pix-flowchart::-webkit-scrollbar-track {
background: #f1f5f9;
border-radius: 10px;
}
.pix-flowchart::-webkit-scrollbar-thumb {
background-color: #cbd5e1;
border-radius: 10px;
}
.pix-flowchart::-webkit-scrollbar-thumb:hover {
background-color: #94a3b8;
}
.pix-step {
background-color: #ffffff;
border-radius: 12px;
padding: 18px;
position: relative;
border-left: 5px solid;
transition: all 0.3s ease;
cursor: pointer;
opacity: 0;
transform: translateX(-20px);
animation: fadeInStep 0.5s forwards;
display: flex;
flex-direction: column;
box-shadow: 0 2px 8px rgba(0, 0, 0, 0.08);
text-decoration: none;
color: inherit;
}
.pix-step:hover {
transform: translateY(-5px);
box-shadow: 0 10px 25px rgba(0, 0, 0, 0.15);
border-left-width: 6px;
}
.pix-step:visited {
color: inherit;
}
.pix-step.step-create { border-left-color: #3b82f6; }
.pix-step.step-approve { border-left-color: #1e293b; }
.pix-step.step-process { border-left-color: #1e40af; }
.pix-step.step-conciliate { border-left-color: #0f172a; }
.pix-step.step-update { border-left-color: #ec4899; }
.pix-step.step-attempts { border-left-color: #3b82f6; }
.pix-step-header {
display: flex;
justify-content: space-between;
align-items: center;
margin-bottom: 12px;
}
.pix-step-number {
width: 32px;
height: 32px;
border-radius: 50%;
background-color: #f1f5f9;
display: flex;
justify-content: center;
align-items: center;
font-size: 14px;
font-weight: 700;
flex-shrink: 0;
transition: all 0.3s ease;
}
.pix-step:hover .pix-step-number {
transform: scale(1.15);
box-shadow: 0 6px 15px rgba(0, 0, 0, 0.2);
}
.pix-step.step-create .pix-step-number { background-color: #3b82f6; color: #ffffff; }
.pix-step.step-approve .pix-step-number { background-color: #1e293b; color: #ffffff; }
.pix-step.step-process .pix-step-number { background-color: #1e40af; color: #ffffff; }
.pix-step.step-conciliate .pix-step-number { background-color: #0f172a; color: #ffffff; }
.pix-step.step-update .pix-step-number { background-color: #ec4899; color: #ffffff; }
.pix-step.step-attempts .pix-step-number { background-color: #3b82f6; color: #ffffff; }
.pix-step-title {
font-size: 16px;
font-weight: 700;
color: #0f172a;
flex-grow: 1;
margin-left: 12px;
}
.pix-step-type {
font-size: 11px;
background-color: #f1f5f9;
padding: 4px 10px;
border-radius: 6px;
font-weight: 600;
text-transform: uppercase;
letter-spacing: 0.5px;
}
.pix-step-type.mock { background-color: #dbeafe; color: #1e40af; }
.pix-step-type.real { background-color: #dcfce7; color: #16a34a; }
.pix-step-type.optional { background-color: #fef3c7; color: #d97706; }
.pix-step-content {
display: flex;
flex-direction: column;
gap: 12px;
max-height: 0;
overflow: hidden;
transition: max-height 0.4s ease;
margin-top: 8px;
}
.pix-step.active .pix-step-content {
max-height: 500px;
}
.pix-step-description {
font-size: 14px;
line-height: 1.6;
color: #475569;
}
.pix-step-info {
background-color: #eff6ff;
border-left: 3px solid #3b82f6;
padding: 10px 14px;
font-size: 13px;
color: #1e40af;
border-radius: 6px;
}
.pix-step-warning {
background-color: #fef3c7;
border-left: 3px solid #f59e0b;
padding: 10px 14px;
font-size: 13px;
color: #92400e;
border-radius: 6px;
}
.pix-connector {
height: 24px;
width: 3px;
background: linear-gradient(to bottom, #cbd5e1, #94a3b8);
margin: -12px auto;
position: relative;
z-index: 1;
border-radius: 2px;
}
.pix-connector::before {
content: '';
position: absolute;
bottom: 0;
left: 50%;
transform: translateX(-50%);
width: 0;
height: 0;
border-left: 6px solid transparent;
border-right: 6px solid transparent;
border-top: 8px solid #94a3b8;
}
.pix-branch-container {
margin-top: 30px;
padding-top: 0px;
}
.pix-branch-title {
text-align: center;
font-size: 18px;
font-weight: 700;
color: #0f172a;
margin-bottom: 24px;
}
.pix-branch-container {
position: relative;
}
.pix-branch-connectors {
position: absolute;
top: -25px;
left: 0;
right: 0;
height: 40px;
display: flex;
justify-content: space-between;
align-items: flex-start;
pointer-events: none;
z-index: 0;
}
.pix-branch-arrow {
width: 3px;
height: 105px;
position: relative;
opacity: 0.9;
}
.pix-branch-arrow::after {
content: '';
position: absolute;
bottom: 0;
left: 50%;
transform: translateX(-50%);
width: 0;
height: 0;
border-left: 6px solid transparent;
border-right: 6px solid transparent;
border-top: 10px solid;
}
.pix-branch-options {
display: grid;
grid-template-columns: 1fr 1fr;
gap: 20px;
}
.pix-branch-option {
background-color: #ffffff;
border-radius: 12px;
padding: 20px;
text-align: center;
transition: all 0.3s ease;
box-shadow: 0 2px 8px rgba(0, 0, 0, 0.08);
cursor: pointer;
text-decoration: none;
color: inherit;
}
.pix-branch-option:hover {
transform: translateY(-3px);
box-shadow: 0 8px 20px rgba(0, 0, 0, 0.12);
}
.branch-title-payment {
font-weight: 800;
font-size: 16px;
margin-bottom: 14px;
color: #1e40af;
}
.branch-title-rejection {
font-weight: 800;
font-size: 16px;
margin-bottom: 14px;
color: #ec4899;
}
.pix-branch-button {
padding: 14px 20px 5px 20px;
border-radius: 10px;
font-weight: 700;
font-size: 14px;
color: #ffffff;
border: none;
cursor: pointer;
width: 100%;
margin-top: 8px;
transition: all 0.3s ease;
text-decoration: none;
display: inline-block;
align-items: center;
justify-content: center;
}
.pix-branch-button:hover {
transform: scale(1.02);
}
.branch-button-payment {
background: linear-gradient(135deg, #1e3a8a 0%, #3b82f6 50%, #60a5fa 100%);
box-shadow: 0 4px 12px rgba(30, 64, 175, 0.3);
}
.branch-button-rejection {
background: linear-gradient(135deg, #9f1239 0%, #ec4899 50%, #f472b6 100%);
box-shadow: 0 4px 12px rgba(236, 72, 153, 0.3);
}
@keyframes fadeInStep {
to {
opacity: 1;
transform: translateX(0);
}
}
@media (max-width: 768px) {
.pix-flow-container {
padding: 20px;
}
.pix-flow-header h3 {
font-size: 20px;
}
.pix-step {
padding: 14px;
}
.pix-step-title {
font-size: 14px;
}
.pix-step-number {
width: 28px;
height: 28px;
font-size: 12px;
}
.pix-branch-options {
grid-template-columns: 1fr;
}
.status-indicator {
top: 5px;
right: 5px;
font-size: 10px;
}
}
`}
Complete Simulation Flow
End-to-end testing of Automatic PIX - Sandbox Environment
SANDBOX
1
Create Recurrence
REAL
Mandatory step before any simulation. Choose one of the four available journeys (Journey 1: Push Notification, Journeys 2-4: QR Code with different configurations). After creating, save the returned outgoing_recurrence_spi_id .
Available journeys: Journey 1 (Push), Journey 2 (QR Code - recurrence), Journey 3 (QR Code + first payment), Journey 4 (QR Code + payment + variable amounts)
2
Approve Recurrence
MOCK
Simulates the recurrence status updates that SPI will send to automatic-pix-api. Use the /mock/outgoing_recurrence/OUTGOING_RECURRENCE_SPI_ID endpoint to update status to pending_confirmation and then to approved .
Attention: In journeys 2, 3 and 4, you must also send account data ( account_data ) in the approval. In journeys 3 and 4, also include first payment information.
3
Process Payment Orders
MOCK
Simulates processing of payment orders through the /mock/process_payment_orders endpoint. This step automatically creates conciliation batches and sends the batch creation webhook to your configured URL.
What happens: Orders are created automatically, conciliation batches are created or updated based on reference_date and recurrence type, and creation webhook is triggered.
4
Query and Reconcile Orders
REAL
Real step (not a mock): Query the created conciliation batch and obtain the receiver_conciliation_id and payment_order_key . For variable_amount recurrences, you must update the payment order with the specific amount.
Important: This step is mandatory for variable_amount recurrences. Without the amount update, the order will not be processed. For fixed_amount , this step is not necessary.
5
Update Execution Date
MOCK
Updates the next_retry_execution_datetime of a payment order to the current date, allowing attempts processing to occur immediately. Use the /mock/payment_order/PAYMENT_ORDER_KEY/update_next_retry_execution_datetime endpoint.
Sandbox only. This step is necessary to advance the flow and allow immediate processing of payment attempts.
6
Process Payment Attempts
MOCK
Simulates processing of payment attempts through the /mock/process_payment_order_attempts endpoint. Creates necessary attempts for the automatic PIX flow, preparing the system to receive incoming PIX simulation or rejection.
Sandbox only. After this step, you can simulate PIX receipt (Step 7) or rejection (Step 8).
Result Simulations
Payment
7. Simulate Incoming PIX
Simulates successful payment receipt via PIX
Rejections
7. Simulate Rejection
Simulates rejection of a payment attempt
{`
if (typeof document !== 'undefined') {
document.addEventListener('DOMContentLoaded', function() {
const steps = document.querySelectorAll('.pix-step');
steps.forEach((step, index) => {
step.style.animationDelay = \`\${index * 0.15}s\`;
step.addEventListener('click', function(e) {
e.preventDefault();
const targetId = this.getAttribute('href');
// Toggle active state
const wasActive = this.classList.contains('active');
// Close all steps
steps.forEach(s => s.classList.remove('active'));
// If wasn't active, open it
if (!wasActive) {
this.classList.add('active');
// Scroll to section
if (targetId) {
const targetElement = document.querySelector(targetId);
if (targetElement) {
setTimeout(() => {
targetElement.scrollIntoView({ behavior: 'smooth', block: 'start' });
}, 300);
}
}
} else {
// If was active and clicked again, navigate to section
if (targetId) {
const targetElement = document.querySelector(targetId);
if (targetElement) {
targetElement.scrollIntoView({ behavior: 'smooth', block: 'start' });
}
}
}
});
});
// Auto-open first step after animation
setTimeout(() => {
if (steps.length > 0) {
steps[0].classList.add('active');
}
}, steps.length * 150 + 200);
});
}
`}
---
## Prerequisite: Create Recurrence
:::danger Mandatory
**This step is mandatory** before any mock simulation. Choose one of the recurrence creation journeys according to your needs.
:::
### Choose Your Journey
| Journey | Description | Link |
|---------|-------------|------|
| **Journey 1** | Push Notification - Authorization via notification | [Create Recurrence: Journey 1](./journey_one.md) |
| **Journey 2** | QR Code - Recurrence authorization only | [Create Recurrence: Journey 2](./journey_two.md) |
| **Journey 3** | QR Code - Recurrence + first payment | [Create Recurrence: Journey 3](./journey_three.md) |
| **Journey 4** | QR Code - Recurrence + first payment + variable amounts | [Create Recurrence: Journey 4](./journey_four.md) |
:::info Important Information
After creating the recurrence, save the returned `outgoing_recurrence_spi_id`. It will be needed for mock simulations.
:::
---
## Step 1: Recurrence Update Simulation
:::caution Prerequisites
**Before this step**, you must have:
1. Created a recurrence using one of the [creation journeys](#prerequisite-create-recurrence)
2. Obtained the `outgoing_recurrence_spi_id` from the created recurrence
:::
This endpoint simulates the recurrence status updates that SPI will send to automatic-pix-api during different receiver flow journeys.
### Request
ENDPOINT /mock/outgoing_recurrence/ OUTGOING_RECURRENCE_SPI_ID
METHOD PATCH
Request Body: Journey 1 - Request received by Payer PSP
```json
{
"outgoing_recurrence_status": "pending_confirmation"
}
```
Request Body: Journey 1 - Request confirmation received by Payer PSP
```json
{
"outgoing_recurrence_status": "approved"
}
```
Request Body: Journeys 2, 3 and 4 - Request received by Payer PSP
```json
{
"outgoing_recurrence_status": "pending_confirmation"
}
```
Request Body: Journey 2 - Request confirmation received by Payer PSP
```json
{
"outgoing_recurrence_status": "approved",
"account_data": {
"account_number": "123456",
"account_digit": "7",
"account_branch": "0001",
"ispb": "31872495"
}
}
```
Request Body: Journeys 3 and 4 - Request confirmation received by Payer PSP
```json
{
"outgoing_recurrence_status": "approved",
"account_data": {
"account_number": "123456",
"account_digit": "7",
"account_branch": "0001",
"ispb": "31872495"
},
"receiver_conciliation_id": "064b6563329047c59db6902725b8d31e",
"target_account_key": "23a4a1c8-9d82-4ebe-a90d-44fe8d839ec0",
"transaction_amount": 250
}
```
### Path Parameters
| Field | Type | Description | Max Char. |
|--------------------------------|--------|------------------------------------------------|-----------|
| **outgoing_recurrence_spi_id*** | string | SPI identifier of the outgoing recurrence | 50 |
### Request Body Object
| Field | Type | Description | Max Char. |
|-------------------------------|--------|-------------------------------------------------|-----------|
| **outgoing_recurrence_status*** | string | Status of the outgoing recurrence | 50 |
| **account_data** | object | Account data (journeys 2, 3 and 4 only) | - |
### account_data Object
| Field | Type | Description | Max Char. |
|---------------------|--------|------------------------------------------|-----------|
| **account_number*** | string | Account number | 20 |
| **account_digit*** | string | Account digit | 1 |
| **account_branch*** | string | Account branch | 6 |
| **ispb*** | string | ISPB code of the financial institution | 8 |
### outgoing_recurrence_status Enumerator
| Enumerator | Description |
|-------------------------|-------------------------------|
| **pending_confirmation** | Pending confirmation |
| **approved** | Approved |
:::info Journey Flows
- **Journey 1**: Status update only, no account data
- **Journey 2**: First status only, then status + account data (recurrence approval only)
- **Journeys 3 and 4**: First status only, then status + account data + first payment data
:::
:::tip Next Step
After approving the recurrence, proceed to [Step 3: Process Payment Orders](#step-3-process-payment-orders-simulation)
:::
---
## Step 2: Recurrence Cancellation Simulation (Optional)
:::caution Prerequisites
**Before this step**, you must have:
1. Created a recurrence
2. Approved the recurrence ([Step 1](#step-1-recurrence-update-simulation))
:::
This endpoint simulates the cancellation of an outgoing recurrence triggered by SPI.
### Request
ENDPOINT /mock/outgoing_recurrence/ OUTGOING_RECURRENCE_SPI_ID /cancel
METHOD PATCH
:::info No Payload
This endpoint has no request body (payload). Only the path parameter is required.
:::
### Path Parameters
| Field | Type | Description | Max Char. |
|--------------------------------|--------|------------------------------------------------|-----------|
| **outgoing_recurrence_spi_id*** | string | SPI identifier of the outgoing recurrence | 50 |
---
## Step 3: Process Payment Orders (Simulation)
:::caution Prerequisites
**Before this step**, you must have:
1. Created a recurrence
2. Approved the recurrence ([Step 1](#step-1-recurrence-update-simulation))
:::
This endpoint simulates the processing of payment orders which will consequently create conciliation batches and send the creation webhook for these batches.
### Request
ENDPOINT /mock/process_payment_orders
METHOD PATCH
:::info No Payload
This endpoint has no request body (payload). The simulation is executed automatically.
:::
:::info What happens in this step?
1. **Payment orders are created** automatically by the system
2. **Conciliation batch is created or updated** (`payment_order_conciliation_batch`)
- If an open batch already exists for the `reference_date` and for the recurrence type ('fixed_amount' or 'variable_amount'), the order is included in
---
# Automatic Pix Webhooks
URL: /en/documentation/baas/pix_automatico/recebedor/webhooks
Webhook notifications are essential for the proper processing of asynchronous events related to Automatic Pix, especially including authorizations and executions of recurring payments in different journeys.
:::danger Attention!
QI Tech webhooks should not be mapped in a restrictive manner.
Additional fields may be included in the webhook payloads returned by our APIs.
:::
## Recurrence Status Webhook
This webhook is intended to report status changes of authorizations and recurrence cycles of Automatic Pix, differentiating the types of journeys involved.
### Webhook Request Body
### Journey 1 – journey_one
Request Body: Journey 1
```json
{
"event_type": "baas.automatic_pix.outgoing_recurrence.status_change",
"origin_key": "8cb70dea-9fb0-4a68-9572-99a72849c8d6",
"data": {
"request_control_key": "98fc62fd-b0a0-4604-9bea-475e91a9dc82",
"outgoing_recurrence_key": "8cb70dea-9fb0-4a68-9572-99a72849c8d6",
"outgoing_recurrence_status": "approved",
"journey_type": "journey_one",
"outgoing_recurrence_data": {
"minimum_recurrence_amount": 123.45,
"recurrence_amount": null
},
"payment_conciliation_batch_key": "uuid"
}
}
```
### Journey 2 – journey_two
Request Body: Journey 2
```json
{
"event_type": "baas.automatic_pix.outgoing_recurrence.status_change",
"origin_key": "8cb70dea-9fb0-4a68-9572-99a72849c8d6",
"data": {
"request_control_key": "98fc62fd-b0a0-4604-9bea-475e91a9dc82",
"outgoing_recurrence_key": "8cb70dea-9fb0-4a68-9572-99a72849c8d6",
"outgoing_recurrence_status": "approved",
"journey_type": "journey_two",
"outgoing_recurrence_data": {
"minimum_recurrence_amount": 123.45,
"recurrence_amount": null
},
"payment_conciliation_batch_key": "uuid" or null
}
}
```
### Journey 3 – journey_three
Request Body: Journey 3
```json
{
"event_type": "baas.automatic_pix.outgoing_recurrence.status_change",
"origin_key": "8cb70dea-9fb0-4a68-9572-99a72849c8d6",
"data": {
"request_control_key": "98fc62fd-b0a0-4604-9bea-475e91a9dc82",
"outgoing_recurrence_key": "8cb70dea-9fb0-4a68-9572-99a72849c8d6",
"outgoing_recurrence_status": "approved",
"journey_type": "journey_three",
"outgoing_recurrence_data": {
"minimum_recurrence_amount": 123.45,
"recurrence_amount": null,
"qr_code_initial_payment_data": {
"receiver_conciliation_id": "id",
"transaction_data": {
"transaction_key": "uuid",
"pix_transfer_key": "uuid",
"end_to_end_id": "end_to_end"
}
},
"payment_conciliation_batch_key": "uuid" or null
}
}
}
```
### Journey 4 – journey_four
Request Body: Journey 4
```json
{
"event_type": "baas.automatic_pix.outgoing_recurrence.status_change",
"origin_key": "8cb70dea-9fb0-4a68-9572-99a72849c8d6",
"data": {
"request_control_key": "98fc62fd-b0a0-4604-9bea-475e91a9dc82",
"outgoing_recurrence_key": "8cb70dea-9fb0-4a68-9572-99a72849c8d6",
"outgoing_recurrence_status": "approved",
"journey_type": "journey_four",
"outgoing_recurrence_data": {
"minimum_recurrence_amount": 123.45,
"recurrence_amount": null
},
"qr_code_initial_payment_data": {
"receiver_conciliation_id": "id",
"transaction_data": {
"transaction_key": "uuid" or null,
"pix_transfer_key": "uuid" or null,
"end_to_end_id": "end_to_end" or null
}
},
"payment_conciliation_batch_key": "uuid" or null
}
}
```
:::caution Attention
When the payer user receives the notification, they can choose to schedule the Pix or make the transfer at that moment. If the payer makes the payment instantly, the `baas.automatic_pix.outgoing_recurrence.status_change` webhook will be sent with the information filled in, in case of scheduling the values will be `null`.
:::
### Webhook Body Params
| Field | Type | Description | Characters |
|-------------------------------------- |------------|---------------------------------------------------------------------------------------------------------------------------|------------|
| `event_type` * | string | Type of reported event (example: `baas.automatic_pix.outgoing_recurrence.status_change`). | 100 |
| `origin_key` * | string | Unique identifier of the event origin (UUID). | 36 |
| `data` * | Object | Main object containing the automatic recurrence details. | [Data Object](#data-object) |
---
### Data Object
| Field | Type | Description | Characters |
|-------------------------------------- |------------|-----------------------------------------------------------------------------------------------------|------------|
| `request_control_key` * | string | Unique request control key (UUID4). | 36 |
| `outgoing_recurrence_key` * | string | Unique identifier of the automatic recurrence (UUID). | 36 |
| `outgoing_recurrence_status` * | string | Status of the recurrence in question (ex: `approved`, `pending`, `rejected`, etc.) | 30 |
| `journey_type` * | enumerator | Journey corresponding to the Automatic Pix authorization (`journey_one`, `journey_two`, etc.). | [journey_type Enumerators](#journey_type-enumerators) |
| `outgoing_recurrence_data` * | Object | Object containing specific recurrence and journey information. | [outgoing_recurrence_data Object](#outgoing_recurrence_data-object) |
| `payment_conciliation_batch_key` | string | Grouping identifier for payment conciliation. May be null. | 36 or null |
| `qr_code_initial_payment_data` | Object | (Journey 3 and 4) Details of initial QR Code payment data, if any. | [qr_code_initial_payment_data Object](#qr_code_initial_payment_data-object) |
---
### outgoing_recurrence_data Object
| Field | Type | Description | Characters |
|----------------------------------|---------|------------------------------------------------------------------------------------------------- |------------|
| `minimum_recurrence_amount` | number | Minimum amount of the authorized recurrence. | - |
| `recurrence_amount` | number | Total amount of the recurrence (may be null if not applicable). | - |
| `qr_code_initial_payment_data` | Object | (Journey 3) Detailed data of the initial payment if QR Code is used. | [qr_code_initial_payment_data Object](#qr_code_initial_payment_data-object) |
| `payment_conciliation_batch_key` | string | Payment batch/conciliation identifier. | 36 |
---
### qr_code_initial_payment_data Object
| Field | Type | Description | Characters |
|---------------------------|---------|---------------------------------------------------------|------------|
| `receiver_conciliation_id`| string | Unique identifier of the receiver's conciliation. | - |
| `transaction_data` | Object | Transaction details associated with the initial QR code. | [transaction_data Object](#transaction_data-object) |
---
### transaction_data Object
| Field | Type | Description | Characters |
|---------------------|--------|---------------------------------------------|------------|
| `transaction_key` | string | Unique transaction key. | 36 |
| `pix_transfer_key` | string | Associated Pix transfer identifier. | 36 |
| `end_to_end_id` | string | Pix end-to-end identifier. | 32 |
---
### journey_type Enumerators
| Enumerator | Description |
|-----------------|----------------------------------------------|
| `journey_one` | Direct notification in banking app |
| `journey_two` | QR Code experience for recurring billing |
| `journey_three` | Instant payment + QR Code recurrence |
| `journey_four` | Recurring opt-in from Pix operation |
## Payment Order Status Webhook
This webhook is intended to report status changes of Automatic Pix payment orders, informing about cancellations, completed payments, and rejections.
### Webhook Request Body
### Status: Cancelled (cancelled)
Request Body: Cancelled Payment Order
```json
{
"event_type": "baas.automatic_pix.payment_order.status_change",
"origin_key": "8cb70dea-9fb0-4a68-9572-99a72849c8d6",
"data": {
"payment_order_key": "8cb70dea-9fb0-4a68-9572-99a72849c8d6",
"payment_order_spi_id": "RR2222222220240429njua7shf40k",
"outgoing_recurrence_key": "98fc62fd-b0a0-4604-9bea-475e91a9dc82",
"payment_order_status": "cancelled",
"receiver_conciliation_id": "cac0b5f7-4ee2-40f1-b2ad-16902506503d",
"transaction_amount": 125.53,
"payment_order_conciliation_batch_key": "21fc62fd-b0a0-4604-9bea-475e91a9dc82",
"transaction_key": "21fc62fd-b0a0-4604-9bea-475e91a9dc56",
"incoming_pix_transfer_key": "21fc62fd-b0a0-4604-9bea-475e91a9dc56"
}
}
```
### Status: Paid (paid)
Request Body: Paid Payment Order
```json
{
"event_type": "baas.automatic_pix.payment_order.status_change",
"origin_key": "8cb70dea-9fb0-4a68-9572-99a72849c8d6",
"data": {
"payment_order_key": "8cb70dea-9fb0-4a68-9572-99a72849c8d6",
"payment_order_spi_id": "RR2222222220240429njua7shf40k",
"outgoing_recurrence_key": "98fc62fd-b0a0-4604-9bea-475e91a9dc82",
"payment_order_status": "paid",
"receiver_conciliation_id": "cac0b5f7-4ee2-40f1-b2ad-16902506503d",
"transaction_amount": 125.53,
"payment_order_conciliation_batch_key": "21fc62fd-b0a0-4604-9bea-475e91a9dc82",
"transaction_key": "21fc62fd-b0a0-4604-9bea-475e91a9dc56",
"incoming_pix_transfer_key": "21fc62fd-b0a0-4604-9bea-475e91a9dc56",
"paid_at": "2021-10-22T20:30:23.459Z"
}
}
```
### Status: Rejected (rejected)
Request Body: Rejected Payment Order
```json
{
"event_type": "baas.automatic_pix.payment_order.status_change",
"origin_key": "8cb70dea-9fb0-4a68-9572-99a72849c8d6",
"data": {
"payment_order_key": "8cb70dea-9fb0-4a68-9572-99a72849c8d6",
"payment_order_spi_id": "RR2222222220240429njua7shf40k",
"outgoing_recurrence_key": "98fc62fd-b0a0-4604-9bea-475e91a9dc82",
"payment_order_status": "rejected",
"receiver_conciliation_id": "cac0b5f7-4ee2-40f1-b2ad-16902506503d",
"transaction_amount": 125.53,
"payment_order_conciliation_batch_key": "21fc62fd-b0a0-4604-9bea-475e91a9dc82"
}
}
```
:::info Information
Rejected payment orders are sent after the maximum number of attempts has been exhausted (if the recurrence allows retries). In this case, the `transaction_key` and `incoming_pix_transfer_key` fields are not included in the payload.
:::
### Webhook Body Params - Payment Order
| Field | Type | Description | Characters |
|-------------------------------------- |------------|---------------------------------------------------------------------------------------------------------------------------|------------|
| `event_type` * | string | Type of reported event (`baas.automatic_pix.payment_order.status_change`). | 100 |
| `origin_key` * | string | Unique identifier of the event origin (UUID of the payment order). | 36 |
| `data` * | Object | Main object containing the payment order details. | [Data Object](#data-object-payment-order) |
---
### Data Object (Payment Order)
| Field | Type | Description | Characters |
|-------------------------------------- |------------|-----------------------------------------------------------------------------------------------------|------------|
| `payment_order_key` * | string | Unique payment order key (UUID). | 36 |
| `payment_order_spi_id` * | string | SPI identifier of the payment order. | 29 |
| `outgoing_recurrence_key` * | string | Unique identifier of the associated automatic recurrence (UUID). | 36 |
| `payment_order_status` * | string | Payment order status (`cancelled`, `paid`, `rejected`). | 30 |
| `receiver_conciliation_id` * | string | Receiver conciliation identifier (UUID). | 36 |
| `transaction_amount` * | number | Payment order transaction amount. | - |
| `payment_order_conciliation_batch_key` * | string | Associated conciliation batch identifier (UUID). | 36 |
| `transaction_key` | string | Unique transaction key (present only in `cancelled` and `paid` status). | 36 |
| `incoming_pix_transfer_key` | string | Incoming PIX transfer identifier (present only in `cancelled` and `paid` status). | 36 |
| `paid_at` | string | Payment date and time (present only in `paid` status, ISO 8601 format). | - |
---
### payment_order_status Enumerators
| Enumerator | Description |
|-----------------|-------------------------------------------------------------------|
| `cancelled` | Payment order cancelled by payer or receiver |
| `paid` | Payment order successfully executed |
| `rejected` | Payment order rejected after exhausting retry attempts |
## Payment Order Attempt Status Webhook
This webhook is intended to report status changes of payment order execution attempts for Automatic Pix, especially informing about rejected attempts and rejection reasons.
### Webhook Request Body
### Status: Rejected (rejected)
Request Body: Rejected Payment Order Attempt
```json
{
"event_type": "baas.automatic_pix.payment_order_attempt.status_change",
"origin_key": "8cb70dea-9fb0-4a68-9572-99a72849c8d6",
"data": {
"request_control_key": "8cb70dea-9fb0-4a68-9572-99a72849c8d6",
"payment_order_key": "8cb70dea-9fb0-4a68-9572-99a72849c8d6",
"payment_order_attempt_key": "21fc62fd-b0a0-4604-9bea-475e91a9dc82",
"payment_order_status": "pending",
"payment_order_attempt_status": "rejected",
"transaction_amount": 125.53,
"reason": "Conta de destino inexistente",
"outgoing_recurrence_key": "98fc62fd-b0a0-4604-9bea-475e91a9dc82"
}
}
```
:::info Information
This webhook is sent whenever a payment order execution attempt is rejected by the SPI. The payment order may have new attempts depending on the recurrence configuration and the rejection reason. The `reason` field contains the description of the rejection reason based on the Bacen error code.
:::
### Webhook Body Params - Payment Order Attempt
| Field | Type | Description | Characters |
|-------------------------------------- |------------|---------------------------------------------------------------------------------------------------------------------------|------------|
| `event_type` * | string | Type of reported event (`baas.automatic_pix.payment_order_attempt.status_change`). | 100 |
| `origin_key` * | string | Unique identifier of the event origin (UUID of the payment order). | 36 |
| `data` * | Object | Main object containing the payment order attempt details. | [Data Object](#data-object-payment-order-attempt) |
---
### Data Object (Payment Order Attempt)
| Field | Type | Description | Characters |
|-------------------------------------- |------------|-----------------------------------------------------------------------------------------------------|------------|
| `request_control_key` * | string | Unique request control key (UUID of the payment order). | 36 |
| `payment_order_key` * | string | Unique key of the associated payment order (UUID). | 36 |
| `payment_order_attempt_key` * | string | Unique key of the payment attempt (UUID). | 36 |
| `payment_order_status` * | string | Current status of the payment order (`pending`, `accepted`, `cancelled`, etc.). | 30 |
| `payment_order_attempt_status` * | string | Payment attempt status (`rejected`). | 30 |
| `transaction_amount` * | number | Payment attempt transaction amount. | - |
| `reason` * | string | Reason for attempt rejection (error description based on Bacen code). | 200 |
| `outgoing_recurrence_key` * | string | Unique identifier of the associated automatic recurrence (UUID). | 36 |
---
### payment_order_attempt_status Enumerators
| Enumerator | Description |
|-----------------|---------------------------------------------------------------------|
| `rejected` | Payment attempt rejected by SPI due to specific error |
## Webhook for non-liquidated payment order attempt
Webhook intended to notify when a payment order attempt was accepted but was not liquidated within the expected timeframe.
### Webhook Request Body
Request Body: Non-liquidated payment order attempt
```json
{
"webhook_type": "baas.automatic_pix.payment_order_attempt.not_liquidated",
"webhook_datetime": "2025-10-22T21:15:00.000Z",
"data": {
"payment_order_key": "8cb70dea-9fb0-4a68-9572-99a72849c8d6",
"payment_order_spi_id": "RR2222222220240429njua7shf40k",
"outgoing_recurrence_key": "98fc62fd-b0a0-4604-9bea-475e91a9dc82",
"payment_order_status": "pending",
"receiver_conciliation_id": "cac0b5f7-4ee2-40f1-b2ad-16902506503d",
"transaction_amount": "125.53",
"payment_order_conciliation_batch_key": "21fc62fd-b0a0-4604-9bea-475e91a9dc82",
"payment_order_attempt_key": "21fc62fd-b0a0-4604-9bea-475e91a9dc83",
"payment_order_attempt_status": "not_liquidated",
"due_date": "2025-10-22",
"end_to_end_id": "E1234567890123456789012"
}
}
```
### Webhook Body Params
| Field | Type | Description | Max. Characters |
|--------------------------------------|-----------|----------------------------------------------------------------------------------------------------------|-----------------|
| `webhook_type` | string | An enumerator that defines the type of event being reported | 100 |
| `webhook_datetime` | string | Date and time of webhook sending | 20 |
| `payment_order_key` | uuid4 | Unique identifier of the payment order. | 36 |
| `payment_order_spi_id` | string | Payment order identifier in the SPI. | 50 |
| `outgoing_recurrence_key` | uuid4 | Unique identifier of the associated outgoing recurrence. | 36 |
| `payment_order_status` | string | Current status of the payment order. | [payment_order_status Enumerators](#payment_order_status-enumerators) |
| `receiver_conciliation_id` | string | Receiver conciliation identification. | 36 |
| `transaction_amount` | number | Payment order transaction amount. | - |
| `payment_order_conciliation_batch_key` | uuid4 | Unique identifier of the associated conciliation batch. | 36 |
| `payment_order_attempt_key` | uuid4 | Unique identifier of the payment order attempt. | 36 |
| `payment_order_attempt_status` | string | Status of the payment order attempt. | [payment_order_attempt_status Enumerators](#payment_order_attempt_status-enumerators) |
| `due_date` | string | Due date of the payment order attempt (YYYY-MM-DD format). | 10 |
| `end_to_end_id` | string | Idempotency key of a Pix transaction within the SPI. | 32 |
### payment_order_status Enumerators
| Enumerator | Description |
|-----------------------|----------------------------------------------------|
| `pending_conciliation`| Awaiting conciliation. |
| `pending` | Pending and awaiting payment. |
| `paid` | Successfully paid. |
| `rejected` | Rejected and will not be processed. |
| `cancelled` | Cancelled before payment. |
### payment_order_attempt_status Enumerators
| Enumerator | Description |
|-----------------|---------------------------------------------------------------------|
| `sent` | Payment attempt sent |
| `accepted` | Payment attempt accepted |
| `rejected` | Payment attempt rejected by SPI due to specific error |
| `not_liquidated`| Payment attempt accepted but not liquidated within expected timeframe |
---
# Approve transaction with Two-Factor Authentication
URL: /en/documentation/baas/pix/2fa_v2/aprovar_transacao_pix_2fa
## Request
ENDPOINT /account/ ACCOUNT_KEY /pix_transfer/ PIX_TRANSFER_KEY /validate_token
METHOD PUT
### Path Params
| Field | Type | Description | Characters |
|-------------------|--------|--------------------------------------------|------------|
| `account_key` | uuidv4 | Unique account identification key. | 36 |
| `pix_transfer_key`| uuidv4 | Unique identification key for the pix transaction. | 36 |
Request Body
```json
{
"token": "329adf"
}
```
### Body Params
| Field | Type | Description | Characters |
|----------|--------|--------------------------------------------------------|------------|
| `token` *| string | Authentication code sent to the account's transaction approver | 6 |
## Response
STATUS 201
Response Body: Transfer sent
```json
{
"request_control_key": "b6804f32-101e-4702-8fbc-c2dbc4c2caec",
"pix_transfer_key": "8cb70dea-9fb0-4a68-9572-99a72849c8d6",
"end_to_end_id": "E32402502202405081755SxyT2DDcVwc",
"pix_transfer_status": "sent",
"created_at": "2021-10-22T20:30:23.459Z"
}
```
STATUS 202
Response Body: Transfer pending
```json
{
"request_control_key": "b6804f32-101e-4702-8fbc-c2dbc4c2caec",
"pix_transfer_key": "8cb70dea-9fb0-4a68-9572-99a72849c8d6",
"end_to_end_id": "E32402502202405081755SxyT2DDcVwc",
"pix_transfer_status": "pending",
"created_at": "2021-10-22T20:30:23.459Z"
}
```
STATUS 4xx
Response Body: Transfer rejected
```json
{
"title": "titulo",
"description": "description in English",
"translation": "description in portuguese",
"code": "codigo",
"extra_fields": {
"pix_transfer_data": {
"request_control_key": "b6804f32-101e-4702-8fbc-c2dbc4c2caec",
"pix_transfer_key": "8cb70dea-9fb0-4a68-9572-99a72849c8d6",
"end_to_end_id": "E32402502202405081755SxyT2DDcVwc",
"pix_transfer_status": "rejected",
"created_at": "2021-10-22T20:30:23.459Z"
}
}
}
```
STATUS 4xx
Response Body: Error
```json
{
"title": "titulo",
"description": "description in English",
"translation": "description in portuguese",
"code": "codigo",
"extra_fields": {}
}
```
| HTTP Code `status` | QI Code `code` | Title `title` | Description (eng) `description` | Description (ptbr) `translation` |
|--------------------------|----------------------|----------------------------------------------------|-------------------------------------------------------------------------------------------------------------------------|------------------------------------------------------------------------------------------------------------------------|
| 400 | QIT000001 | Bad Request | Schema Error | Erro de Schema |
| 404 | PXT000023 | Outgoing PIX Transfer Not Found | Pix transfer key \{pix_transfer_key\} was not found | Transferência PIX de saída com chave \{pix_transfer_key\} não foi encontrada |
| 400 | PXT000175 | Invalid Status | Pix transfer not in pending_2fa_approval status | Pix transfer não está pendente de aprovação por two factor authentication |
| 400 | PXT000182 | Bad Request | The given Pix transfer is tied to a batch. It cannot be individually approved. Please approve batch | A Pix transfer enviada está ligada a um lote. Ela não pode ser individualmente aprovada. Por favor aprove o lote |
| 400 | PXT000174 | Error Sending Token | An error occurred while sending token and its being investigated | Um erro ocorreu ao enviar token e está sendo investigado |
| 400 | PXT000173 | Incorrect Token | Token sent does not match expected | Token enviado não condiz com, o esperado |
| 400 | PXT000172 | Token Expired | Token has expired. Resend token or recreate transfer | Token expirado. Reenvie token ou recrie a transferência |
| 400 | PXT000171 | Number of token validation attempts exceeded | The maximum number of failed token validation attempts has been reached | Número máximo de tentativas de validação de token atingida |
| 406 | PXT000103 | request_control_key must be a valid uuid v4 string | request_control_key was not accepted for not being a valid uuid v4 string | request_control_key não foi aceito por não ser uma palavra uuid v4 válida |
| 400 | PXT000048 | Bad Request | Emoji not allowed in pix message. | Emoji não é permitido na mensagem pix. |
| 400 | PXT000104 | Invalid Transaction Amount | Transaction amount of \{transaction_amount\} is not valid. It must be a positive value with at maximum 2 decimal places | O valor de transação \{transaction_amount\} não é válido. Deve ser um valor positivo com no máximo duas casas decimais |
| 404 | PXT000004 | Account not found | Account not found for: \{account_datum\} | Conta não encontrada para: \{account_datum\} |
| 400 | PXT000003 | Account is Closed | Account \{account_key\} is closed. | Conta \{account_key\} está fechada. |
| 422 | PXT000092 | Invalid Account Type | Pix is not yet implemented for non-checking or non-escrow account types | Transações Pix não estão implementadas para conta que não sejam escrow ou livres |
| 403 | PIT000001 | User is not allowed to do this transaction | | Usuário não tem autorização para fazer essa transação |
| 400 | PXT000010 | Account is Blocked | Account \{account_key\} is blocked. | Conta \{account_key\} está bloqueada. |
| 400 | PXT000003 | Account is Closed | Account \{account_key\} is closed. | Conta \{account_key\} está fechada. |
| 400 | PIT000003 | Bad Request | Insufficient account balance for transfer and fee amount. | Saldo de conta insuficiente para a transferência e a taxa. |
| 400 | PXT000118 | Requester is not Pix Participant | The requester sent an alias key but is not a indirect pix participant | O requisitante enviou uma alias key no entanto não é um participante do pix indireto |
| 404 | PXT000120 | Alias sent not found | Alias key attached to this account not found | Alias key vinculada à conta não encontrada |
| 406 | PXT000105 | Invalid end_to_end_id | The end_to_end_id sent \{end_to_end_id\} is not valid. | O end_to_end_id enviado \{end_to_end_id\} não é válido. |
| 400 | PXT000108 | Bad Request | Billing account closed or blocked | Conta de cobrança encerrada ou bloqueada |
| 400 | PXT000079 | Bad Request | Insufficient billing account balance for fee. | Saldo de conta de cobrança insuficiente para a taxa. |
| 400 | PIT000004 | Bad Request | Transaction amount is over limit. | O total da transferência é superior ao limite. |
| 404 | PIX000056 | Not Found | Pix key inquiry not found | Consulta de chave pix não encontrada |
| 404 | PXT000041 | Not Found | Qr Code not found | Qr Code não encontrado |
| 400 | PXT000053 | Bad Request | QrCode already paid | Qr Code já Pago |
| 400 | PXT000118 | Requester is not Pix Participant | The requester sent an alias key but is not a indirect pix participant | O requisitante enviou uma alias key no entanto não é um participante do pix indireto |
| 404 | PXT000120 | Alias sent not found | Alias key attached to this account not found | Alias key vinculada à conta não encontrada |
| 400 | PXT000115 | Bad Request | Insufficient account balance for transfer and fee amount. | Saldo de conta insuficiente para a transferência e a taxa |
| 400 | PXT000128 | Bad Request | Pix key \{pix_key\} sent does match inquiry pix key. Verify if end_to_end_id sent is correct | Chave Pix \{pix_key\} enviada não condiz com consulta. Verifique se end_to_end_id enviado está correto |
| 400 | PXT000109 | Bad Request | request_control_key \{request_control_key\} already in use | request_control_key \{request_control_key\} já utilizada |
| 400 | PXT000061 | Bad Request | End to end id invalid. A pix transfer with the end to end id \{end_to_end\} has already been registered! | End to end id inválido. Uma transação pix com o identificador único \{end_to_end\} já foi registrada! |
| 400 | PXT000129 | SPI Error message | Message rejected by SPI-ICOM | Mensagem rejeitada pela SPI-ICOM |
| 408 | PXT000130 | SPI Timeout Control | SPI Timeout Control | Controle de timeout no SPI |
| 400 | PXT000131 | Receiver Internal Error | Cancelled transaction due to receiver's internal error | Transação interrompida devido a erro no PSP do Recebedor |
| 400 | PXT000132 | Invalid Target Account Number | Target account number is invalid | Número da conta de destino é inexistente ou inválido |
| 400 | PXT000133 | Blocked Target Account | Target account is blocked. | A conta de destino encontra-se bloqueada. |
| 400 | PXT000134 | Closed Target Account | Target account is closed. | A conta de destino encontra-se encerrada. |
| 400 | PXT000135 | Unsupported Transaction | Unsupported transaction for given target account. | A conta de destino não suporta este tipo de transação. |
| 400 | PXT000136 | Invalid Participant | SPI participant is not PSP settler agent of payer nor receiver. | Participante direto do SPI não é liquidante do PSP do Pagador / Recebedor. |
| 400 | PXT000137 | Zero Value Payment Order | Zero value payment order. | Ordem de pagamento com valor zero. |
| 400 | PXT000138 | Insufficient Funds | Insufficient funds in PI account from payer. | Saldo insuficiente na conta PI do pagador. |
| 400 | PXT000139 | Return Value Too Great | Return value greater than corresponding payment order. | Valor de devolução acima do valor de pagamento correspondente. |
| 400 | PXT000140 | Invalid Transactions Number | Invalid transactions number. | Quantidade de transações inválida. |
| 400 | PXT000141 | Unrelated Beneficiary Document Number | Beneficiary document number is not that of target account owner. | CPF/CNPJ do usuário recebedor não é compatível com o titular da conta de destino. |
| 400 | PXT000142 | Invalid Beneficiary Document Number | Invalid beneficiary document number | CPF/CNPJ da conta de destino está incorreto. |
| 400 | PXT000143 | Incorrect Message Element | Incorrect message element. | Elemento da mensagem incorreto. |
| 403 | PXT000144 | Rejected Payment Order | Beneficiary's PSP has rejected payment order. | Ordem de pagamento foi rejeitada pelo banco recebedor. |
| 403 | PXT000145 | Unauthorized Payer | Signing participant is unauthorized to make a payment order for paying account. | Participante que assinou a mensagem não é autorizado a realizar a operação na conta PI debitada. |
| 400 | PXT000146 | Invalid Datetime | Invalid datetime for message delivery. | Data e Hora do envio da mensagem inválida. |
| 400 | PXT000147 | Generic Error | Error while processing payment (generic error). | Erro no processamento do pagamento (erro genérico). |
| 400 | PXT000148 | Bad Format Operation Identifier | Badly formatted operation's identifier. | Identificador da operação mal formatado. |
| 400 | PXT000149 | Invalid Payer ISPB | Invalid or non-existent payer's PSP ISPB number. | Número ISPB do PSP do Pagador é inválido ou inexistente. |
| 400 | PXT000150 | Invalid Beneficiary ISPB | Invalid or non-existent beneficiary's PSP ISPB number. | Número ISPB do banco recebedor é inválido ou inexistente. |
| 400 | PXT000151 | Incorrect Type | Incorrect type for target account. | Tipo incorreto para a conta transacional especificada. |
| 400 | PXT000152 | Repeated End-to-End ID Error | The end_to_end_id was already used | O end_to_end_id já foi utilizado |
| 400 | PXT000153 | Invalid Target Account Type | The target account type cannot receive PIX transactions | O tipo de conta destino não pode receber transações PIX |
| 400 | PXT000154 | Invalid ISPB | Invalid or non-existent ISPB number. | Número ISPB é inválido ou inexistente. |
| 400 | PXT000155 | Amount too Great | Amount too great for credited account. | Valor de pagamento/devolução acima do permitido para a conta de destino creditada. |
| 400 | PXT000156 | QR Code Rejected | QR Code rejected by beneficiary's PSP. | QR Code rejeitado pelo PSP do usuário recebedor. |
| 503 | PXT000157 | Bacen Service Unavailable Error | Could not send the message to ICOM after 3 retries | Não pode enviar a mensagem para a ICOM depois de 3 tentativas |
| 400 | PXT000158 | Invalid Amount | Paid amount diverges from expected amount of \{expected_amount\} | O valor do pagamento diverge do valor esperado de \{expected_amount\} |
| 400 | PXT000159 | QR code inactive | QR code is not active at the time of payment | QR code não está ativo no instante do pagamento |
---
# Introduction to Two-Factor Authentication
URL: /en/documentation/baas/pix/2fa_v2/introducao_a_transacao_pix_2fa
In this type of transaction, payment confirmation via a token sent to the person with approval powers for movements in the creditor account is required.
The request for a Pix transaction by integrator partners configured to use two-factor authentication is made similarly to what is described in [perform a Pix transaction](/documentation/baas_v2/pix/realizar_transferencia). The difference is the addition of the `tfa_info` object, containing information about the transfer approver and the means of contact, and the status of a successful request, which will always be **pending_2fa_approval**. The same applies to batch Pix transactions described in [perform batch Pix transaction](/documentation/baas_v2/pix/batch/solicitacao_de_transacao_em_lote_pix).
## Flow for a Pix Transaction with Authorization
A successful Pix transaction will follow the following process flow:
Perform the [Pix transaction request](/documentation/baas_v2/pix/2fa_v2/solicitacao_de_transacao_pix_2fa) and receive a synchronous response with status **pending_2fa_approval** and value of `pix_transfer_key`.
The indicated approver will receive a 6-digit `token` consisting of letters and digits.
The requester performs the [Pix transaction confirmation](/documentation/baas_v2/pix/2fa_v2/aprovar_transacao_pix_2fa) with the `pix_transfer_key` and the `token`.
The transfer will be completed synchronously or asynchronously, depending on the integrator partner's configuration.
## Observations
Each transaction has a maximum limit of 5 validation attempts for the `token`. When this limit is reached, the transaction will be automatically set to rejected (**rejected**) status.
Each `token` has a maximum duration of 5 minutes.
A transaction can have its `token` renewed and resent to the transfer approver. This process resets the 5-minute time but does not reset the invalid attempt counter. The previous `token` becomes invalid.
Once the transaction is approved, it will be completed in synchronous or asynchronous mode, depending on the integrator partner's configuration.
The notification event for sending the `token` to the approver is **baas.token_validation.pix_transfer.single**. It is possible to [customize](/documentation/notificacoes/template) the sent message.
The implemented `contact_type` for sending tokens are **sms** and **email**.
---
# Request the return of a received Pix
URL: /en/documentation/baas/pix/2fa_v2/solicitacao_de_devolucao_pix
A Pix refund can be made up to 90 days from its receipt.
## Request
ENDPOINT /account/ ACCOUNT_KEY /pix_transfer/ PIX_TRANSFER_KEY /reversal
METHOD POST
### Path Params
| Field | Type | Description | Characters |
|----------------------|--------|--------------------------------------------------------------------|------------|
| `account_key` * | uuidv4 | Unique account identification key. | 36 |
| `pix_transfer_key` * | uuidv4 | Unique identification key for the Pix transfer in the QI system. | 36 |
Request Body
```json
{
"request_control_key": "303393bf-8f2e-4ff0-b326-ee7ad612e8ca",
"reversal_amount": 147,
"reversal_reason": "client_request",
"reversal_message": "Mensagem Pix da Devolução",
"tfa_info": {
"approver_document_number": "98765432100",
"contact_type": "email"
}
}
```
### Request Params
| Field | Type | Description | Characters |
|-----------------------|--------|-------------------------------------------------------------------|--------------------------------------------|
| `request_control_key` * | uuidv4 | Uniqueness key for the request. | 36 |
| `reversal_amount` * | number | Refund amount. | 11 |
| `reversal_reason` * | string | Reason for the refund. | **[Enumerator reversal_reason](#enumerator-reversal_reason)** |
| `reversal_message` | string | Refund message. | 140 |
| `tfa_info` * | Object | Object containing the document of the account approver and the means of contact. | **[Object tfa_info](#object-tfa_info)** |
### Enumerator reversal_reason
| Enumerator | Description |
|-------------------|------------------------------------------------------|
| **client_request**| If requested by the account owner. |
| **reconciliation**| For reconciliation due to operational error. |
### Object tfa_info
| Field | Type | Description | Characters |
|----------------------------|--------|--------------------------------------------------------------------------------|------------|
| `approver_document_number` * | string | Document number of the account approver. | 11 |
| `contact_type` * | string | Means of contact with the account approver, can be **sms** or **email** | |
## Response
STATUS 202
Response Body: Reversal Requested
```json
{
"reversal_status": "pending_2fa_approval",
"end_to_end_id": "E32402502202405081755SxyT2DDcVwc",
"pix_transfer_key": "cdcf0d25-08a1-46e3-902a-6d7ca75e6c48",
"request_control_key": "7c5a1425-73eb-420e-b4fb-0ce3386c7d0c",
"created_at": "2021-10-22T20:30:23.459Z"
}
```
### Response Body
| Field | Type | Description | Characters |
|----------------------|-----------|-----------------------------------------------------------|------------------------------------------|
| `reversal_status` | enumerator| Enumerator for the reversal transaction status. | [Enumerator reversal_status](#enumerator-reversal_status) |
| `transfer_amount` | number | Amount of the reversal transfer. | 11 |
| `pix_transfer_key` | uuidv4 | Key of the executed pix transaction for the reversal. | 36 |
| `request_control_key`| uuidv4 | Unique identification key for the request used by the client. | 36 |
| `created_at` | string | Date and time of the reversal. | 10 |
### Enumerator reversal_status
| Enumerator | Description |
|------------------------------|--------------------------------------------------------|
| **sent** | Pix transfer successfully executed. |
| **pending** | Pix transfer pending. |
| **pending_2fa_approval** | Pix transfer pending two-factor approval. |
| **rejected** | Pix transfer rejected. |
STATUS 4xx
Response Body: Reversão Rejeitada
```json
{
"title": "titulo",
"description": "description in English",
"translation": "description in portuguese",
"code": "codigo",
"extra_fields": {
"pix_transfer_data": {
"request_control_key": "b6804f32-101e-4702-8fbc-c2dbc4c2caec",
"pix_transfer_key": "8cb70dea-9fb0-4a68-9572-99a72849c8d6",
"end_to_end_id": "E32402502202405081755SxyT2DDcVwc",
"pix_transfer_status": "rejected",
"created_at": "2021-10-22T20:30:23.459Z"
}
}
}
```
:::info Information
In addition to the errors previously listed for [Pix transfer](/documentation/baas_v2/pix/realizar_transferencia), a Pix refund can also return the errors listed below.
:::
| HTTP Code `status` | QI Code `code` | Title `title` | Description (eng) `description` | Description (ptbr) `translation` |
|--------------------------|----------------------|--------------------------------------|------------------------------------------------------------------------|-------------------------------------------------------------------------------------------|
| 400 | QIT000001 | Bad Request | Schema Error | Erro de Schema |
| 404 | PXT000018 | Reversal Original Transfer not Found | Reversal original pix transfer not found. | Transferência original da devolução não foi encontrada. |
| 400 | PXT000017 | Reversal Too Great | Reversal transfers sum amount surpasses that of original pix transfer. | A soma das transferências de devolução ultrapassam o valor da transferência pix original. |
| 400 | PXT000015 | Reversal date expired | Reversal original transaction is older than 90 days | A data de criação da transação original é mais antiga que 90 dias |
| 400 | PXT0000127 | Invalid Reversal Reason | Reversal reason \{reversal_reason\} is not valid | Razão de reversão \{reversal_reason\} não é válida |
---
# Request Token Resend for a Transaction
URL: /en/documentation/baas/pix/2fa_v2/solicitacao_de_reenvio_de_token
A new token will be generated and sent to the pix transaction approver. If the limit number of token validation attempts has been exceeded, the resend will not be allowed.
## Request
ENDPOINT /account/ ACCOUNT_KEY /pix_transfer/ PIX_TRANSFER_KEY /resend_token
METHOD PATCH
### Path Params
| Field | Type | Description | Characters |
|----------------------|--------|--------------------------------------------------------------------|------------|
| `account_key` * | uuidv4 | Unique account identification key. | 36 |
| `pix_transfer_key` * | uuidv4 | Unique identification key for the Pix transfer in the QI system. | 36 |
## Response
STATUS 202
Response Body: Transaction Requested
```json
{
"request_control_key": "b6804f32-101e-4702-8fbc-c2dbc4c2caec",
"pix_transfer_key": "8cb70dea-9fb0-4a68-9572-99a72849c8d6",
"end_to_end_id": "E32402502202405081755SxyT2DDcVwc",
"pix_transfer_status": "pending_2fa_approval",
"created_at": "2021-10-22T20:30:23.459Z"
}
```
STATUS 4xx
Response Body: Transfer rejected
```json
{
"title": "titulo",
"description": "description in English",
"translation": "descrição em portugues",
"code": "codigo",
"extra_fields": {
"pix_transfer_data": {
"request_control_key": "b6804f32-101e-4702-8fbc-c2dbc4c2caec",
"pix_transfer_key": "8cb70dea-9fb0-4a68-9572-99a72849c8d6",
"pix_transfer_status": "rejected",
"created_at": "2021-10-22T20:30:23.459Z"
}
}
}
```
| HTTP Code `status` | QI Code `code` | Title `title` | Description (eng) `description` | Description (ptbr) `translation` |
|--------------------------|----------------------|----------------------------------------------|-------------------------------------------------------------------------|------------------------------------------------------------------------------|
| 400 | QIT000001 | Bad Request | Schema Error | Erro de Schema |
| 404 | PXT000004 | Account not found | Account not found for: \{account_datum\} | Conta não encontrada para: \{account_datum\} |
| 404 | PXT000023 | Outgoing PIX Transfer Not Found | Pix transfer key \{pix_transfer_key\} was not found | Transferência PIX de saída com chave \{pix_transfer_key\} não foi encontrada |
| 400 | PXT000171 | Number of token validation attempts exceeded | The maximum number of failed token validation attempts has been reached | Número máximo de tentativas de validação de token atingida |
| 400 | PXT000175 | Invalid Status | Pix transfer not in pending_2fa_approval status | Pix transfer não está pendente de aprovação por two factor authentication |
| 400 | PXT000176 | Error Sending Token | An error occurred while resending token and its being investigated | Um erro ocorreu ao reenviar token e está sendo investigado |
---
# Request transaction with Two-Factor Authentication
URL: /en/documentation/baas/pix/2fa_v2/solicitacao_de_transacao_pix_2fa
## Request
ENDPOINT /account/ ACCOUNT_KEY /pix_transfer
METHOD POST
### Path Params
| Field | Type | Description | Characters |
|----------------|--------|-------------------------------------------|------------|
| `account_key` | uuidv4 | Unique account identification key. | 36 |
**Key**
Request Body: Pix Key Transfer
```json
{
"request_control_key": "b6804f32-101e-4702-8fbc-c2dbc4c2caec",
"pix_transfer_type": "key",
"target_pix_key": "target_pix_key@email.com",
"transaction_amount": 500.65,
"end_to_end_id": "E73856642202309201429bZKfklNlbwu",
"pix_message": "Ola Mundo",
"tfa_info": {
"approver_document_number": "98765432100",
"contact_type": "email"
}
}
```
### Body Params
| Field | Type | Description | Characters |
|-----------------------|-----------|-------------------------------------------------------------------------------------------------------------------------|--------------------------------------------|
| `request_control_key` * | uuidv4 | Unique identification key for the request used by the client in uuid v4 format. | 36 |
| `pix_transfer_type` * | enumerator| Type of the pix to be performed. For key transfer, it should be **key**. | **key** |
| `target_pix_key` * | string | Pix key of the account to which the transaction will be sent. | 100 |
| `transaction_amount` *| number | Transfer amount. | 10 |
| `end_to_end_id` * | string | Idempotency key for a Pix transaction within the SPI (Instant Payment System). This key is returned in Pix key queries. Should only be sent if `pix_transfer_type` is **key**, **static_qr_code**, or **dynamic_qr_code**. | 32 |
| `pix_message` | string | Message to be sent along with the Pix transfer. | 140 |
| `tfa_info` * | Object | Object containing the document of the account approver and the means of contact. | **[Object tfa_info](#object-tfa_info)** |
**Manual**
Request Body: Manual transfer
```json
{
"request_control_key": "b6804f32-101e-4702-8fbc-c2dbc4c2caec",
"pix_transfer_type": "manual",
"target_account": {
"account_branch": "0001",
"account_digit": "3",
"account_number": "12345678",
"owner_document_number": "32402502000135",
"owner_name": "Qi Tech",
"account_type": "checking_account",
"ispb": "32402502"
},
"transaction_amount": 500.65,
"pix_message": "Ola Mundo",
"tfa_info": {
"approver_document_number": "98765432100",
"contact_type": "email"
}
}
```
### Body Params
| Field | Type | Description | Characters |
|-----------------------|-----------|-------------------------------------------------------------------------------------------------------------------------|--------------------------------------------|
| `request_control_key` * | uuidv4 | Unique identification key for the request used by the client in uuid v4 format. | 36 |
| `pix_transfer_type` * | enumerator| Type of Pix transfer. | **manual** |
| `target_account` * | Object | Destination account - Should only be sent for transfers with `pix_transfer_type` of type **manual**. | **[Object target_account](#object-target_account)** |
| `transaction_amount` *| number | Transfer amount. | 10 |
| `pix_message` | string | Message to be sent along with the Pix transfer. | 140 |
| `tfa_info` * | Object | Object containing the document of the account approver and the means of contact. | **[Object tfa_info](#object-tfa_info)** |
### Object target_account
| Field | Type | Description | Characters |
|-------------------------|-----------|-------------------------------------------------------------------------------------------------------------------------|--------------------------------------------|
| `account_branch` * | string | Account branch. | 6 |
| `account_digit` * | string | Account digit. | 1 |
| `account_number` * | string | Account number. | 20 |
| `owner_document_number` * | string | CPF or CNPJ (numbers only) of the account holder. | 14 |
| `owner_name` * | string | Name of the account holder. | 150 |
| `account_type` * | enumerator| Account type. | **[Enumerator account_type](#enumerator-account_type)** |
| `ispb` * | string | Based on the CNPJ of the financial institution (8 digits). | 8 |
### Enumerator account_type
| Enumerator | Description |
|-----------------------|----------------------------|
| **checking_account** | Checking Account |
| **salary_account** | Salary Account |
| **saving_account** | Savings Account |
| **payment_account** | Payment Account |
**Qr Code**
Request Body: QR Code transfer
```json
{
"request_control_key": "b6804f32-101e-4702-8fbc-c2dbc4c2caec",
"pix_transfer_type": "static_qr_code",
"transaction_amount": 500.65,
"end_to_end_id": "E73856642202309201429bZKfklNlbwu",
"receiver_conciliation_id": "REC00000000000000000000009459463343",
"target_pix_key": "target_pix_key@email.com",
"pix_message": "Ola Mundo",
"tfa_info": {
"approver_document_number": "98765432100",
"contact_type": "email"
}
}
```
### Body Params
| Field | Type | Description | Characters |
|--------------------------|-----------|-------------------------------------------------------------------------------------------------------------------------|----------------------------------------------|
| `request_control_key` * | uuidv4 | Unique identification key for the request used by the client in uuid v4 format. | 36 |
| `pix_transfer_type` * | enumerator| Type of Pix transfer. | **static_qr_code** or **dynamic_qr_code** |
| `target_pix_key` * | string | Pix key of the account to which the transaction will be sent. | 100 |
| `receiver_conciliation_id` | string | Reconciliation ID of the receiver. | 35 |
| `transaction_amount` * | number | Transfer amount. | 10 |
| `end_to_end_id` * | string | Idempotency key for a Pix transaction within the SPI (Instant Payment System). This key is returned in Pix key queries. Should only be sent if `pix_transfer_type` is **key**, **static_qr_code**, or **dynamic_qr_code**. | 32 |
| `pix_message` | string | Message to be sent along with the Pix transfer. | 140 |
| `tfa_info` * | Object | Object containing the document of the account approver and the means of contact. | **[Object tfa_info](#object-tfa_info)** |
:::info Warning
The `end_to_end_id` is returned when [decoding the Pix QR Code](/documentation/pix/decodificar_qr_code), using the Pix Copy and Paste URI.
:::
### Object tfa_info
| Field | Type | Description | Characters |
|----------------------------|--------|--------------------------------------------------------------------------------|------------|
| `approver_document_number` * | string | Document number of the account approver. | 11 |
| `contact_type` * | string | Means of contact with the account approver, can be **sms** or **email** | |
:::danger Warning
The `end_to_end_id` from the query must have been made in the name of the account that will request the transaction!
:::
:::danger Warning
An `end_to_end_id` can only be used for a single transfer, regardless of whether the transfer was successful or not.
:::
## Response
STATUS 202
Response Body: Transaction Requested
```json
{
"request_control_key": "b6804f32-101e-4702-8fbc-c2dbc4c2caec",
"pix_transfer_key": "8cb70dea-9fb0-4a68-9572-99a72849c8d6",
"end_to_end_id": "E32402502202405081755SxyT2DDcVwc",
"pix_transfer_status": "pending_2fa_approval",
"created_at": "2021-10-22T20:30:23.459Z"
}
```
STATUS 4xx
Response Body: Transfer Rejected
```json
{
"title": "titulo",
"description": "description in English",
"translation": "description in portuguese",
"code": "codigo",
"extra_fields": {
"pix_transfer_data": {
"request_control_key": "b6804f32-101e-4702-8fbc-c2dbc4c2caec",
"pix_transfer_key": "8cb70dea-9fb0-4a68-9572-99a72849c8d6",
"end_to_end_id": "E32402502202405081755SxyT2DDcVwc",
"pix_transfer_status": "rejected",
"created_at": "2021-10-22T20:30:23.459Z"
}
}
}
```
STATUS 4xx
Response Body: Error
```json
{
"title": "titulo",
"description": "description in English",
"translation": "description in portuguese",
"code": "codigo",
"extra_fields": {}
}
```
| HTTP Code `status` | QI Code `code` | Title `title` | Description (eng) `description` | Description (ptbr) `translation` |
|--------------------------|----------------------|----------------------------------------------------|-------------------------------------------------------------------------------------------------------------------------|------------------------------------------------------------------------------------------------------------------------|
| 400 | QIT000001 | Bad Request | Schema Error | Erro de Schema |
| 400 | PXT000168 | No approver permission | Given document number does not belong to an approver for this account | Número de documento enviado não pertence a um aprovador da conta |
| 400 | PXT000169 | tfa_info is required | Client must send object tfa_info | Cliente deve enviar objeto tfa_info |
| 400 | PXT000170 | Error occurred while sending token | An unexpected error occurred while sending token | Um erro inexperado ocorreu ao tentar enviar token |
| 406 | PXT000103 | request_control_key must be a valid uuid v4 string | request_control_key was not accepted for not being a valid uuid v4 string | request_control_key não foi aceito por não ser uma palavra uuid v4 válida |
| 400 | PXT000048 | Bad Request | Emoji not allowed in pix message. | Emoji não é permitido na mensagem pix. |
| 400 | PXT000104 | Invalid Transaction Amount | Transaction amount of \{transaction_amount\} is not valid. It must be a positive value with at maximum 2 decimal places | O valor de transação \{transaction_amount\} não é válido. Deve ser um valor positivo com no máximo duas casas decimais |
| 404 | PXT000004 | Account not found | Account not found for: \{account_datum\} | Conta não encontrada para: \{account_datum\} |
| 400 | PXT000003 | Account is Closed | Account \{account_key\} is closed. | Conta \{account_key\} está fechada. |
| 422 | PXT000092 | Invalid Account Type | Pix is not yet implemented for non-checking or non-escrow account types | Transações Pix não estão implementadas para conta que não sejam escrow ou livres |
| 403 | PIT000001 | User is not allowed to do this transaction | | Usuário não tem autorização para fazer essa transação |
| 400 | PXT000010 | Account is Blocked | Account \{account_key\} is blocked. | Conta \{account_key\} está bloqueada. |
| 400 | PXT000003 | Account is Closed | Account \{account_key\} is closed. | Conta \{account_key\} está fechada. |
| 400 | PIT000003 | Bad Request | Insufficient account balance for transfer and fee amount. | Saldo de conta insuficiente para a transferência e a taxa. |
| 400 | PXT000118 | Requester is not Pix Participant | The requester sent an alias key but is not a indirect pix participant | O requisitante enviou uma alias key no entanto não é um participante do pix indireto |
| 404 | PXT000120 | Alias sent not found | Alias key attached to this account not found | Alias key vinculada à conta não encontrada |
| 406 | PXT000105 | Invalid end_to_end_id | The end_to_end_id sent \{end_to_end_id\} is not valid. | O end_to_end_id enviado \{end_to_end_id\} não é válido. |
| 400 | PXT000108 | Bad Request | Billing account closed or blocked | Conta de cobrança encerrada ou bloqueada |
| 400 | PXT000079 | Bad Request | Insufficient billing account balance for fee. | Saldo de conta de cobrança insuficiente para a taxa. |
| 400 | PIT000004 | Bad Request | Transaction amount is over limit. | O total da transferência é superior ao limite. |
| 404 | PIX000056 | Not Found | Pix key inquiry not found | Consulta de chave pix não encontrada |
| 404 | PXT000041 | Not Found | Qr Code not found | Qr Code não encontrado |
| 400 | PXT000053 | Bad Request | QrCode already paid | Qr Code já Pago |
| 400 | PXT000118 | Requester is not Pix Participant | The requester sent an alias key but is not a indirect pix participant | O requisitante enviou uma alias key no entanto não é um participante do pix indireto |
| 404 | PXT000120 | Alias sent not found | Alias key attached to this account not found | Alias key vinculada à conta não encontrada |
| 400 | PXT000115 | Bad Request | Insufficient account balance for transfer and fee amount. | Saldo de conta insuficiente para a transferência e a taxa |
| 400 | PXT000128 | Bad Request | Pix key \{pix_key\} sent does match inquiry pix key. Verify if end_to_end_id sent is correct | Chave Pix \{pix_key\} enviada não condiz com consulta. Verifique se end_to_end_id enviado está correto |
| 400 | PXT000109 | Bad Request | request_control_key \{request_control_key\} already in use | request_control_key \{request_control_key\} já utilizada |
| 400 | PXT000061 | Bad Request | End to end id invalid. A pix transfer with the end to end id \{end_to_end\} has already been registered! | End to end id inválido. Uma transação pix com o identificador único \{end_to_end\} já foi registrada! |
| 400 | PXT000129 | SPI Error message | Message rejected by SPI-ICOM | Mensagem rejeitada pela SPI-ICOM |
| 408 | PXT000130 | SPI Timeout Control | SPI Timeout Control | Controle de timeout no SPI |
| 400 | PXT000131 | Receiver Internal Error | Cancelled transaction due to receiver's internal error | Transação interrompida devido a erro no PSP do Recebedor |
| 400 | PXT000132 | Invalid Target Account Number | Target account number is invalid | Número da conta de destino é inexistente ou inválido |
| 400 | PXT000133 | Blocked Target Account | Target account is blocked. | A conta de destino encontra-se bloqueada. |
| 400 | PXT000134 | Closed Target Account | Target account is closed. | A conta de destino encontra-se encerrada. |
| 400 | PXT000135 | Unsupported Transaction | Unsupported transaction for given target account. | A conta de destino não suporta este tipo de transação. |
| 400 | PXT000136 | Invalid Participant | SPI participant is not PSP settler agent of payer nor receiver. | Participante direto do SPI não é liquidante do PSP do Pagador / Recebedor. |
| 400 | PXT000137 | Zero Value Payment Order | Zero value payment order. | Ordem de pagamento com valor zero. |
| 400 | PXT000138 | Insufficient Funds | Insufficient funds in PI account from payer. | Saldo insuficiente na conta PI do pagador. |
| 400 | PXT000139 | Return Value Too Great | Return value greater than corresponding payment order. | Valor de devolução acima do valor de pagamento correspondente. |
| 400 | PXT000140 | Invalid Transactions Number | Invalid transactions number. | Quantidade de transações inválida. |
| 400 | PXT000141 | Unrelated Beneficiary Document Number | Beneficiary document number is not that of target account owner. | CPF/CNPJ do usuário recebedor não é compatível com o titular da conta de destino. |
| 400 | PXT000142 | Invalid Beneficiary Document Number | Invalid beneficiary document number | CPF/CNPJ da conta de destino está incorreto. |
| 400 | PXT000143 | Incorrect Message Element | Incorrect message element. | Elemento da mensagem incorreto. |
| 403 | PXT000144 | Rejected Payment Order | Beneficiary's PSP has rejected payment order. | Ordem de pagamento foi rejeitada pelo banco recebedor. |
| 403 | PXT000145 | Unauthorized Payer | Signing participant is unauthorized to make a payment order for paying account. | Participante que assinou a mensagem não é autorizado a realizar a operação na conta PI debitada. |
| 400 | PXT000146 | Invalid Datetime | Invalid datetime for message delivery. | Data e Hora do envio da mensagem inválida. |
| 400 | PXT000147 | Generic Error | Error while processing payment (generic error). | Erro no processamento do pagamento (erro genérico). |
| 400 | PXT000148 | Bad Format Operation Identifier | Badly formatted operation's identifier. | Identificador da operação mal formatado. |
| 400 | PXT000149 | Invalid Payer ISPB | Invalid or non-existent payer's PSP ISPB number. | Número ISPB do PSP do Pagador é inválido ou inexistente. |
| 400 | PXT000150 | Invalid Beneficiary ISPB | Invalid or non-existent beneficiary's PSP ISPB number. | Número ISPB do banco recebedor é inválido ou inexistente. |
| 400 | PXT000151 | Incorrect Type | Incorrect type for target account. | Tipo incorreto para a conta transacional especificada. |
| 400 | PXT000152 | Repeated End-to-End ID Error | The end_to_end_id was already used | O end_to_end_id já foi utilizado |
| 400 | PXT000153 | Invalid Target Account Type | The target account type cannot receive PIX transactions | O tipo de conta destino não pode receber transações PIX |
| 400 | PXT000154 | Invalid ISPB | Invalid or non-existent ISPB number. | Número ISPB é inválido ou inexistente. |
| 400 | PXT000155 | Amount too Great | Amount too great for credited account. | Valor de pagamento/devolução acima do permitido para a conta de destino creditada. |
| 400 | PXT000156 | QR Code Rejected | QR Code rejected by beneficiary's PSP. | QR Code rejeitado pelo PSP do usuário recebedor. |
| 503 | PXT000157 | Bacen Service Unavailable Error | Could not send the message to ICOM after 3 retries | Não pode enviar a mensagem para a ICOM depois de 3 tentativas |
| 400 | PXT000158 | Invalid Amount | Paid amount diverges from expected amount of \{expected_amount\} | O valor do pagamento diverge do valor esperado de \{expected_amount\} |
| 400 | PXT000159 | QR code inactive | QR code is not active at the time of payment | QR code não está ativo no instante do pagamento |
---
# aprovacao_de_agendamento_2fa
URL: /en/documentation/baas/pix/agendamento/aprovacao_de_agendamento_2fa
---
# aprovacao_de_agendamento_em_lote_2fa
URL: /en/documentation/baas/pix/agendamento/batch/aprovacao_de_agendamento_em_lote_2fa
---
# Cancel batch Pix transaction scheduling
URL: /en/documentation/baas/pix/agendamento/batch/cancelamento_de_agendamento_em_lote
## Request
ENDPOINT /account/ ACCOUNT_KEY /pix_schedule_batch/ SCHEDULE_BATCH_KEY /cancel
METHOD PATCH
### Path Params
| Field | Type | Description | Characters |
|----------------------|--------|-----------------------------------------------------|------------|
| `account_key` | uuidv4 | Unique account identification key. | 36 |
| `schedule_batch_key` | uuidv4 | Unique batch schedule identification key. | 36 |
### Response
STATUS 200
Response Body: Schedule Cancelled
```json
{
"request_control_key": "b6804f32-101e-4702-8fbc-c2dbc4c2caec",
"schedule_batch_key": "f64b3fa7-d09d-4927-ad4f-b966df9fb153",
"schedule_batch_status": "cancelled",
"created_at": "2023-03-13T19:00:28.440Z"
}
```
STATUS 4xx
Response Body: Error
```json
{
"title": "titulo",
"description": "description in English",
"translation": "description in portuguese",
"code": "codigo",
"extra_fields": {}
}
```
| HTTP Code `status` | QI Code `code` | Title `title` | Description (eng) `description` | Description (ptbr) `translation` |
|--------------------------|----------------------|-----------------------------------------------------|--------------------------------------------------------------------------------------------------------------------------------------|---------------------------------------------------------------------------------------------------------------------------------------------|
| 400 | QIT000001 | Bad Request | schema error description | Schema Inválido |
| 404 | PSC000001 | Account not Found | Account was not found | Conta não encontrada |
| 403 | PSC000012 | User is not allowed to do this transaction | User is not allowed to do this transaction | Usuário não tem autorização para fazer essa transação |
| 404 | PSC000025 | PixSchedule not Found | PixSchedule was not found | PixSchedule não encontrada |
| 400 | PSC000027 | Bad Request | Action cannot be taken place as there is currently a pending transfer in progress | A ação não pôde ser completada como há uma transferência pendente |
| 404 | PSC000042 | Schedule Batch not Found | ScheduleBatch was not found | ScheduleBatch não encontrada |
| 400 | PSC000043 | Schedule Batch could not be canceled | ScheduleBatch could not be canceled due to current date being equal or after earliest schedule date. Cancel pix_schedules one by one | ScheduleBatch não pode ser cancelada devido a data atual ser superior ou igual à menor schedule_date. Cancele pix_schedules individualmente |
| 400 | PSC000044 | Bad Request | Schedule Batch cannot be cancelled in current status | Agendamento pix não pode ser cancelado no status atual |
---
# List Schedules of a Batch Schedule
URL: /en/documentation/baas/pix/agendamento/batch/consulta_de_agendamentos_de_um_lote
## Request
ENDPOINT /account/ ACCOUNT_KEY /pix_schedule_batch/ SCHEDULE_BATCH_KEY /pix_schedules
METHOD GET
### Path Params
| Field | Type | Description | Characters |
|--------------------|--------|--------------------------------------------------------|------------|
| `account_key` | uuidv4 | Unique account identification key. | 36 |
| `schedule_batch_key` | uuidv4 | Unique batch schedule identification key. | 36 |
### Query Params
| Field | Type | Description | Characters |
|----------------------|---------|---------------------------------------------------------------------|------------------------------|
| `request_control_key`| uuidv4 | Unique identification key for the request used by the client. | 36 |
| `schedule_status` | string | Schedule status. Can be sent as a list. | **[Enumerator schedule_status](#enumerator-schedule_status)** |
| `page` | integer | Requested page number. 1 by default. | |
| `page_size` | integer | Size of the requested page in the query. 30 by default and max value | Maximum value of 30 |
### Enumerator schedule_status
| Enumerator | Description |
|----------------------------|----------------------------------------------------------------------------------------------------|
| **scheduled** | Scheduled transaction |
| **sent** | Schedule completed and successfully sent. Final status. |
| **rejected** | Schedule rejected during creation or execution. Final status. |
| **cancelled** | Schedule canceled by customer request. Final status. |
| **pending_2fa_approval** | Pending two-factor authentication approval. |
| **pending_creation** | Schedule in the process of creation (Transitional state for batch scheduling). |
| **waiting_batch_approval** | Schedule created and linked to a batch awaiting two-factor authentication approval. |
### Response
STATUS 200
Response Body
```json
{
"data": [
{
"request_control_key": "b6804f32-101e-4702-8fbc-c2dbc4c2caec",
"schedule_key": "8cb70dea-9fb0-4a68-9572-99a72849c8d6",
"schedule_status": "scheduled",
"schedule_date": "2024-12-31",
"created_at": "2023-03-13T19:00:28.440Z"
},
{
"request_control_key": "bf6b0a4b-c7a5-446b-9dad-1ae10b25342a",
"schedule_key": "2479a5cd-079e-4d72-bf4e-16a695bda45e",
"schedule_status": "cancelled",
"schedule_date": "2024-12-31",
"created_at": "2023-03-13T19:00:28.440Z"
},
{
"request_control_key": "9d36c03e-2db7-4c90-87ed-6c9ddb3c03c7",
"schedule_key": "5d6b14b9-053f-408c-bcd7-61ecf9224f2c",
"schedule_status": "rejected",
"schedule_date": "2024-12-31",
"created_at": "2023-03-13T19:00:28.440Z"
}
],
"pagination": {
"current_page": 1,
"next_page": null,
"rows_per_page": 30
}
}
```
---
# List Scheduled Batches for an Account
URL: /en/documentation/baas/pix/agendamento/batch/consulta_de_agendamentos_em_lote_de_uma_conta
## Request
ENDPOINT /account/ ACCOUNT_KEY /pix_schedule_batches
MÉTODO GET
### Path Params
| Field | Type | Description | Characters |
|--------------- |--------|-----------------------------------------------|------------|
| `account_key` | uuidv4 | Unique account identification key. | 36 |
### Query Params
| Field | Type | Description | Characters |
|----------------------|---------|---------------------------------------------------------------------|-----------------|
| `request_control_key`| uuidv4 | Unique identification key for the request used by the client. | 36 |
| `schedule_batch_status` | string | Schedule batch status. Can be sent as a list. | 20 |
| `page` | integer | Requested page number. 1 by default. | |
| `page_size` | integer | Size of the requested page in the query. 30 by default and max value | Maximum value of 30 |
### Response
STATUS 200
Response Body
```json
{
"data": [
{
"request_control_key": "b6804f32-101e-4702-8fbc-c2dbc4c2caec",
"schedule_batch_key": "8cb70dea-9fb0-4a68-9572-99a72849c8d6",
"schedule_batch_status": "approved",
"created_at": "2021-10-22T20:30:23.459Z"
},
{
"request_control_key": "bf6b0a4b-c7a5-446b-9dad-1ae10b25342a",
"schedule_batch_key": "2479a5cd-079e-4d72-bf4e-16a695bda45e",
"schedule_batch_status": "cancelled",
"created_at": "2021-10-22T20:30:23.459Z"
},
{
"request_control_key": "9d36c03e-2db7-4c90-87ed-6c9ddb3c03c7",
"schedule_batch_key": "5d6b14b9-053f-408c-bcd7-61ecf9224f2c",
"schedule_batch_status": "rejected",
"created_at": "2021-10-22T20:30:23.459Z"
}
],
"pagination": {
"current_page": 1,
"next_page": null,
"rows_per_page": 30
}
}
```
# Query Scheduled Batch for an Account
## Request
ENDPOINT /account/ ACCOUNT_KEY /pix_schedule_batch/ SCHEDULE_BATCH_KEY
MÉTODO GET
### Path Params
| Field | Type | Description | Characters |
|------------------- |--------|--------------------------------------------------------|------------|
| `account_key` | uuidv4 | Unique account identification key. | 36 |
| `schedule_batch_key` | uuidv4 | Unique batch schedule identification key. | 36 |
### Response
STATUS 200
Response Body
```json
{
"request_control_key": "b6804f32-101e-4702-8fbc-c2dbc4c2caec",
"schedule_batch_key": "8cb70dea-9fb0-4a68-9572-99a72849c8d6",
"schedule_batch_status": "approved",
"created_at": "2021-10-22T20:30:23.459Z"
}
```
---
# Request batch Pix transaction scheduling
URL: /en/documentation/baas/pix/agendamento/batch/solicitacao_de_agendamento_em_lote
QI Tech offers the possibility to perform multiple scheduled pix transactions with a single call. In this system, schedules are made asynchronously. If a **http status 4xx** is returned on the initial call, none of the schedules will be executed. After the request, the integrator partner will receive a webhook for each **pix_schedule** rejected at the time of creation.
## Request
ENDPOINT /account/ ACCOUNT_KEY /pix_schedule_batch
METHOD POST
```json
{
"request_control_key": "6e4fc980-f8a1-4462-b6e2-d8a49f0ac055",
"pix_schedules": [
{
"request_control_key": "b6804f32-101e-4702-8fbc-c2dbc4c2caec",
"pix_transfer_type": "key",
"target_pix_key": "target_pix_key@email.com",
"transaction_amount": 500.65,
"end_to_end_id": "E73856642202309201429bZKfklNlbwu",
"pix_message": "Ola Mundo",
"schedule_date": "2024-12-01"
},
{
"request_control_key": "c6804f35-101e-4702-8fbc-c2dbc4c2caea",
"pix_transfer_type": "manual",
"target_account": {
"account_branch": "0001",
"account_digit": "3",
"account_number": "12345678",
"owner_document_number": "32402502000135",
"owner_name": "Qi Tech",
"account_type": "checking_account",
"ispb": "32402502"
},
"transaction_amount": 500.65,
"pix_message": "Ola Mundo",
"schedule_date": "2024-12-01"
},
{
"request_control_key": "a6804f42-101e-4702-8fbc-c2dbc4c2caed",
"pix_transfer_type": "static_qr_code",
"transaction_amount": 500.65,
"end_to_end_id": "E73856642202309201429bZKfklNlbwu",
"receiver_conciliation_id": "REC00000000000000000000009459463343",
"target_pix_key": "target_pix_key@email.com",
"pix_message": "Ola Mundo"
}
]
}
```
## Path Params
| Field | Type | Description | Characters |
|--------------- |--------|-----------------------------------------------|------------|
| `account_key` | uuidv4 | Unique account identification key. | 36 |
### Body Params
| Field | Type | Description | Characters |
|----------------------|--------|---------------------------------------------------------------------------------------|-------------------------------------------|
| `request_control_key` * | uuidv4 | Unique identification key for the request used by the client in uuid v4 format. | 36 |
| `pix_schedules` * | array | List of pix_schedule objects linked to the batch. | list of **[Object pix_schedule](#object-pix_schedule)** |
### Object pix_schedule
| Field | Type | Description | Characters |
|----------------------|-----------|-------------------------------------------------------------------------------------------------------------------------|--------------------------------------------|
| `request_control_key` * | uuidv4 | Unique identification key for the request used by the client in uuid v4 format. | 36 |
| `pix_transfer_type` * | enumerator| Type of Pix transfer. | **[Enumerator pix_transfer_type](#enumerator-pix_transfer_type)** |
| `target_pix_key` | string | Pix key of the account to which the transaction will be sent. | 100 |
| `receiver_conciliation_id` | string | Reconciliation ID of the receiver. | 35 |
| `target_account` * | Object | Destination account - Should only be sent for transfers with `pix_transfer_type` of type **manual**. | **[Object target_account](#object-target_account)** |
| `transaction_amount` *| number | Transfer amount. | 10 |
| `end_to_end_id` | string | Idempotency key for a Pix transaction within the SPI (Instant Payment System). This key is returned in Pix key queries. Should only be sent if `pix_transfer_type` is **key**, **static_qr_code**, or **dynamic_qr_code**. | 32 |
| `pix_message` | string | Message to be sent along with the Pix transfer. | 140 |
### Object target_account
| Field | Type | Description | Characters |
|-------------------------|-----------|-------------------------------------------------------------------------------------------------------------------------|--------------------------------------------|
| `account_branch` * | string | Account branch. | 6 |
| `account_digit` * | string | Account digit. | 1 |
| `account_number` * | string | Account number. | 20 |
| `owner_document_number` * | string | CPF or CNPJ (numbers only) of the account holder. | 14 |
| `owner_name` * | string | Name of the account holder. | 150 |
| `account_type` * | enumerator| Account type. | **[Enumerator account_type](#enumerator-account_type)** |
| `ispb` * | string | Based on the CNPJ of the financial institution (8 digits). | 8 |
### Enumerator account_type
| Enumerator | Description |
|-----------------------|----------------------------|
| **checking_account** | Checking Account |
| **salary_account** | Salary Account |
| **saving_account** | Savings Account |
| **payment_account** | Payment Account |
### Enumerator pix_transfer_type
| Enumerator | Description |
|------------------------|--------------------------------------------------------------------------------------|
| **manual** | Pix using destination account details. Must send `target_account`. |
| **key** | Pix using a pix key. Must send `target_pix_key`. Recommended to send `end_to_end_id` from the [pix key query](/documentation/pix_indireto/movimentacoes/consultar_chave_pix) if previously performed |
| **static_qr_code** | Pix using a static QR code. Must send the `end_to_end_id` returned in the [QR code decode](/documentation/pix/decodificar_qr_code) |
| **dynamic_qr_code** | Pix using a dynamic QR code. Must send the `end_to_end_id` returned in the [QR code decode](/documentation/pix/decodificar_qr_code) |
## Response
STATUS 201
Response Body: Batch Schedule Approved
```json
{
"request_control_key": "b6804f32-101e-4702-8fbc-c2dbc4c2caec",
"schedule_batch_key": "8cb70dea-9fb0-4a68-9572-99a72849c8d6",
"schedule_batch_status": "approved",
"created_at": "2021-10-22T20:30:23.459Z"
}
```
### Enumerador schedule_batch_status
| Enumerator | Description |
|------------------------|----------------------------------------------------------------------------|
| **created** | Batch schedule created |
| **approved** | Batch schedule approved |
| **rejected** | Batch schedule rejected |
| **pending_2fa_approval**| Batch schedule pending two-factor authentication approval |
STATUS 4xx
Response Body: Error
```json
{
"title": "titulo",
"description": "description in English",
"translation": "description in portuguese",
"code": "codigo",
"extra_fields": {}
}
```
| HTTP Code `status` | QI Code `code` | Title `title` | Description (eng) `description` | Description (ptbr) `translation` |
|--------------------------|----------------------|-----------------------------------------------------|---------------------------------------------------------------------------------------------------------------------------|-----------------------------------------------------------------------------------------------------------------------------------|
| 400 | QIT000001 | Bad Request | schema error description | Schema Inválido |
| 404 | PSC000001 | Account not Found | Account was not found | Conta não encontrada |
| 406 | PSC000002 | Invalid Uuid | key was not accepted for not being a valid uuid v4 string | key não foi aceito por não ser uma palavra uuid v4 válida |
| 400 | PSC000003 | Bad Request | pix_message can not be longer than 140 characters | pix_message não pode ser maior que 140 caracteres |
| 400 | PSC000004 | Bad Request | Emoji not allowed in pix message | Emoji não é permitido na mensagem pix |
| 406 | PSC000005 | Invalid Transaction Amount | Transaction amount of transaction_amount is not valid. It must be a positive value with at maximum 2 decimal places | O valor de transação transaction_amount não é válido. Deve ser um valor positivo com no máximo duas casas decimais |
| 406 | PSC000006 | Invalid end_to_end_id | The end_to_end_id sent end_to_end_id is not valid | O end_to_end_id enviado end_to_end_id não é válido |
| 400 | PSC000007 | Invalid date format | Dates must be sent using format YYYY-MM-DD | Datas devem ser enviadas no formato YYYY-MM-DD |
| 400 | PSC000008 | Invalid Schedule Date | Schedule date must be after current date for UTC-3 | Data de agendamento deve ser após a data atual em UTC-3 |
| 400 | PSC000009 | Account is Closed | Account is closed | Conta está fechada |
| 400 | PSC000010 | Account is Blocked | Account is blocked | Conta está bloqueada |
| 422 | PSC000011 | Invalid Account Type | Pix is not yet implemented for non-checking or non-escrow account types | Transações Pix não estão implementadas para conta que não sejam escrow ou livres |
| 403 | PSC000012 | User is not allowed to do this transaction | User is not allowed to do this transaction | Usuário não tem autorização para fazer essa transação |
| 400 | PSC000013 | Bad Request | For Manual Pix Transfer Type a target account must be provided | Para transação pix do tipo manual, uma conta destino deve ser fornecida |
| 404 | PSC000014 | Inquiry Not Found | Pix key inquiry was not found | Pesquisa de chave pix não encontrada |
| 400 | PSC000015 | Bad Request | Pix key sent does match inquiry pix key. Verify if end_to_end_id sent is correct | Chave Pix enviada não condiz com consulta. Verifique se end_to_end_id enviado está correto |
| 404 | PSC000016 | Account not found | Nonexistent account in destination financial institution | Conta inexistente na instituição financeira de destino |
| 400 | PSC000017 | Target Account and Source Account must be different | Target Account must not be the same as Source Account | A conta de destino não pode ser a mesma da conta de origem |
| 409 | PSC000018 | Bad Request | request_control_key request_control_key already in use | request_control_key request_control_key já utilizada |
| 400 | PSC000019 | Invalid Target | Account does not have permission to transfer to the given target account | A conta não possui permissão para realizar transferências para a conta enviada |
| 404 | PSC000020 | Decode Inquiry Not Found | QR Code decode inquiry not found | Pesquisa e decodificação de QR code não encontrada |
| 400 | PSC000021 | Bad Request | Receiver Conciliation Id sent does match decode inquiry receiver_conciliation_id. Verify if end_to_end_id sent is correct | Identificador de transação enviado não condiz com consulta. Verifique se end_to_end_id enviado está correto |
| 400 | PSC000022 | Bad Request | Dynamic Instant QR codes cannot be scheduled for payment | Pagamentos de vencimento instantâneo não podem ter pagamento agendado |
| 400 | PSC000023 | Bad Request | Schedule Date sent is after max payment date for target qr code | Data de agendamento enviada é após a data máxima de pagamento para o qr code enviado |
| 400 | PSC000024 | Bad Request | Pix transfer type sent does match decode inquiry qr code type. Verify if end_to_end_id sent is correct | Tipo de transação pix enviado enviado não condiz com tipo de qr code da consulta. Verifique se end_to_end_id enviado está correto |
| 400 | PSC000040 | Empty pix-schedule list received | A list of pix schedules must be provided | Uma lista de agendamentos pix deve ser fornecida |
| 409 | PSC000041 | Bad Request | One or more request_control_key already in use | Uma ou mais request_control_key já está sendo utilizada |
| 403 | PSC000045 | Requester not allowed to access this endpoint | Requester has no permission to perform pix transfers on this endpoint | Requester não possui permissão de realizar transações pix através deste endpoint |
---
# solicitacao_de_agendamento_em_lote_2fa
URL: /en/documentation/baas/pix/agendamento/batch/solicitacao_de_agendamento_em_lote_2fa
---
# solicitacao_de_reenvio_de_token_para_agendamento_em_lote_2fa
URL: /en/documentation/baas/pix/agendamento/batch/solicitacao_de_reenvio_de_token_para_agendamento_em_lote_2fa
---
# Cancel Pix transaction scheduling
URL: /en/documentation/baas/pix/agendamento/cancelamento_de_agendamento
## Request
ENDPOINT /account/ ACCOUNT_KEY /pix_schedule/ SCHEDULE_KEY /cancel
MÉTODO PATCH
### Path Params
| Field | Type | Description | Characters |
|----------------|--------|-----------------------------------------------|------------|
| `account_key` | uuidv4 | Unique account identification key. | 36 |
| `schedule_key` | uuidv4 | Unique schedule identification key. | 36 |
### Response
STATUS 200
Response Body: Schedule Cancelled
```json
{
"request_control_key": "b6804f32-101e-4702-8fbc-c2dbc4c2caec",
"schedule_key": "f64b3fa7-d09d-4927-ad4f-b966df9fb153",
"schedule_status": "cancelled",
"schedule_date": "2024-12-31",
"created_at": "2023-03-13T19:00:28.440Z"
}
```
STATUS 4xx
Response Body: Error
```json
{
"title": "titulo",
"description": "description in English",
"translation": "description in portuguese",
"code": "codigo",
"extra_fields": {}
}
```
| HTTP Code `status` | QI Code `code` | Title `title` | Description (eng) `description` | Description (ptbr) `translation` |
|--------------------------|----------------------|--------------------------------------------|-----------------------------------------------------------------------------------|---------------------------------------------------------------------------------------------|
| 400 | QIT000001 | Bad Request | schema error description | Schema Inválido |
| 404 | PSC000001 | Account not Found | Account was not found | Conta não encontrada |
| 403 | PSC000012 | User is not allowed to do this transaction | User is not allowed to do this transaction | Usuário não tem autorização para fazer essa transação |
| 404 | PSC000025 | PixSchedule not Found | PixSchedule was not found | PixSchedule não encontrada |
| 400 | PSC000027 | Bad Request | Action cannot be taken place as there is currently a pending transfer in progress | A ação não pôde ser completada como há uma transferência pendente |
| 400 | PSC000028 | Bad Request | Pix Schedule cannot be cancelled in current status | Agendamento pix não pode ser cancelado no status atual |
| 400 | PSC000029 | Bad Request | The given Pix Schedule is tied to a batch. It cannot be individually cancelled | O agendamento pix enviado está ligado a um lote. Ela não pode ser individualmente cancelada |
---
# Pix transaction scheduling inquiry
URL: /en/documentation/baas/pix/agendamento/consulta_de_agendamento
## Request
ENDPOINT /account/ ACCOUNT_KEY /pix_schedule/ SCHEDULE_KEY
MÉTODO GET
### Path Params
| Field | Type | Description | Characters |
|----------------|--------|-----------------------------------------------|------------|
| `account_key` | uuidv4 | Unique account identification key. | 36 |
| `schedule_key` | uuidv4 | Unique schedule identification key. | 36 |
### Response
STATUS 200
Response Body
```json
{
"created_at": "2024-07-10T16:17:28Z",
"pix_message": null,
"rejection_info": null,
"rejection_reason": null,
"request_control_key": "b8eb663e-10fe-4729-9db5-8f8c93de5001",
"schedule_date": "2024-07-10",
"schedule_key": "0c9091ab-079b-4a43-8b3d-d4ba36a23883",
"schedule_status": "sent",
"schedule_transfers": [
{
"created_at": "2024-07-10T16:19:33Z",
"end_to_end_id": "E3240250220240710161922sSHNf8BjI",
"pix_transfer_key": "427b70cd-73b0-45d1-bb4a-97f50f605022",
"pix_transfer_status": "sent"
}
],
"target_account": {
"account_branch": "0001",
"account_digit": "8",
"account_number": "1234567",
"account_type": "checking_account",
"ispb": "99999004",
"owner_document_number": "***91111***",
"owner_name": "Conta manual geral",
"owner_person_type": "natural",
"pix_key": null,
"receiver_conciliation_id": null
},
"transaction_amount": 2.0,
"updated_at": "2024-07-10T16:19:38Z"
}
```
---
# Consult Pix transaction scheduling for an account
URL: /en/documentation/baas/pix/agendamento/consulta_de_agendamentos_de_uma_conta
## Request
ENDPOINT /account/ ACCOUNT_KEY /pix_schedules
MÉTODO GET
### Path Params
| Field | Type | Description | Characters |
|----------------|--------|-----------------------------------------------|------------|
| `account_key` | uuidv4 | Unique account identification key. | 36 |
### Query Params
| Field | Type | Description | Characters |
|----------------------|---------|---------------------------------------------------------------------|------------------------------|
| `request_control_key`| uuidv4 | Unique identification key for the request used by the client. | 36 |
| `schedule_status` | string | Schedule status. Can be sent as a list. | **[Enumerator schedule_status](#enumerator-schedule_status)** |
| `page` | integer | Requested page number. 1 by default. | |
| `page_size` | integer | Size of the requested page in the query. 30 by default and max value | Maximum value of 30 |
### Enumerator schedule_status
| Enumerator | Description |
|----------------------------|----------------------------------------------------------------------------------------------------|
| **scheduled** | Scheduled transaction |
| **sent** | Schedule completed and successfully sent. Final status. |
| **rejected** | Schedule rejected during creation or execution. Final status. |
| **cancelled** | Schedule canceled by customer request. Final status. |
| **pending_2fa_approval** | Pending two-factor authentication approval. |
| **pending_creation** | Schedule in the process of creation (Transitional state for batch scheduling). |
| **waiting_batch_approval** | Schedule created and linked to a batch awaiting two-factor authentication approval. |
### Response
STATUS 200
Response Body
```json
{
"data": [
{
"request_control_key": "b6804f32-101e-4702-8fbc-c2dbc4c2caec",
"schedule_key": "8cb70dea-9fb0-4a68-9572-99a72849c8d6",
"schedule_status": "scheduled",
"schedule_date": "2024-12-31",
"created_at": "2023-03-13T19:00:28.440Z"
},
{
"request_control_key": "bf6b0a4b-c7a5-446b-9dad-1ae10b25342a",
"schedule_key": "2479a5cd-079e-4d72-bf4e-16a695bda45e",
"schedule_status": "cancelled",
"schedule_date": "2024-12-31",
"created_at": "2023-03-13T19:00:28.440Z"
},
{
"request_control_key": "9d36c03e-2db7-4c90-87ed-6c9ddb3c03c7",
"schedule_key": "5d6b14b9-053f-408c-bcd7-61ecf9224f2c",
"schedule_status": "rejected",
"schedule_date": "2024-12-31",
"created_at": "2023-03-13T19:00:28.440Z"
}
],
"pagination": {
"current_page": 1,
"next_page": null,
"rows_per_page": 30
}
}
```
---
# Tabela de Erros para Pix Schedule
URL: /en/documentation/baas/pix/agendamento/erros_de_agendamento
STATUS 4xx
Response Body: Error
```json
{
"title": "titulo",
"description": "description in English",
"translation": "descrição em portugues",
"code": "codigo",
"extra_fields": {}
}
```
| Código HTTP `status` | Código QI `code` | Título `title` | Descrição (eng) `description` | Descrição (ptbr) `translation` |
|--------------------------|----------------------|-----------------------------------------------------|--------------------------------------------------------------------------------------------------------------------------------------|---------------------------------------------------------------------------------------------------------------------------------------------|
| 400 | QIT000001 | Bad Request | schema error description | Schema Inválido |
| 404 | PSC000001 | Account not Found | Account was not found | Conta não encontrada |
| 406 | PSC000002 | Invalid Uuid | key was not accepted for not being a valid uuid v4 string | key não foi aceito por não ser uma palavra uuid v4 válida |
| 400 | PSC000003 | Bad Request | pix_message can not be longer than 140 characters | pix_message não pode ser maior que 140 caracteres |
| 400 | PSC000004 | Bad Request | Emoji not allowed in pix message | Emoji não é permitido na mensagem pix |
| 406 | PSC000005 | Invalid Transaction Amount | Transaction amount of transaction_amount is not valid. It must be a positive value with at maximum 2 decimal places | O valor de transação transaction_amount não é válido. Deve ser um valor positivo com no máximo duas casas decimais |
| 406 | PSC000006 | Invalid end_to_end_id | The end_to_end_id sent end_to_end_id is not valid | O end_to_end_id enviado end_to_end_id não é válido |
| 400 | PSC000007 | Invalid date format | Dates must be sent using format YYYY-MM-DD | Datas devem ser enviadas no formato YYYY-MM-DD |
| 400 | PSC000008 | Invalid Schedule Date | Schedule date must be after current date for UTC-3 | Data de agendamento deve ser após a data atual em UTC-3 |
| 400 | PSC000009 | Account is Closed | Account is closed | Conta está fechada |
| 400 | PSC000010 | Account is Blocked | Account is blocked | Conta está bloqueada |
| 422 | PSC000011 | Invalid Account Type | Pix is not yet implemented for non-checking or non-escrow account types | Transações Pix não estão implementadas para conta que não sejam escrow ou livres |
| 403 | PSC000012 | User is not allowed to do this transaction | User is not allowed to do this transaction | Usuário não tem autorização para fazer essa transação |
| 400 | PSC000013 | Bad Request | For Manual Pix Transfer Type a target account must be provided | Para transação pix do tipo manual, uma conta destino deve ser fornecida |
| 404 | PSC000014 | Inquiry Not Found | Pix key inquiry was not found | Pesquisa de chave pix não encontrada |
| 400 | PSC000015 | Bad Request | Pix key sent does match inquiry pix key. Verify if end_to_end_id sent is correct | Chave Pix enviada não condiz com consulta. Verifique se end_to_end_id enviado está correto |
| 404 | PSC000016 | Account not found | Nonexistent account in destination financial institution | Conta inexistente na instituição financeira de destino |
| 400 | PSC000017 | Target Account and Source Account must be different | Target Account must not be the same as Source Account | A conta de destino não pode ser a mesma da conta de origem |
| 409 | PSC000018 | Bad Request | request_control_key request_control_key already in use | request_control_key request_control_key já utilizada |
| 400 | PSC000019 | Invalid Target | Account does not have permission to transfer to the given target account | A conta não possui permissão para realizar transferências para a conta enviada |
| 404 | PSC000020 | Decode Inquiry Not Found | QR Code decode inquiry not found | Pesquisa e decodificação de QR code não encontrada |
| 400 | PSC000021 | Bad Request | Receiver Conciliation Id sent does match decode inquiry receiver_conciliation_id. Verify if end_to_end_id sent is correct | Identificador de transação enviado não condiz com consulta. Verifique se end_to_end_id enviado está correto |
| 400 | PSC000022 | Bad Request | Dynamic Instant QR codes cannot be scheduled for payment | Pagamentos de vencimento instantâneo não podem ter pagamento agendado |
| 400 | PSC000023 | Bad Request | Schedule Date sent is after max payment date for target qr code | Data de agendamento enviada é após a data máxima de pagamento para o qr code enviado |
| 400 | PSC000024 | Bad Request | Pix transfer type sent does match decode inquiry qr code type. Verify if end_to_end_id sent is correct | Tipo de transação pix enviado enviado não condiz com tipo de qr code da consulta. Verifique se end_to_end_id enviado está correto |
| 404 | PSC000025 | PixSchedule not Found | PixSchedule was not found | PixSchedule não encontrada |
| 400 | PSC000026 | Search Params Error | Invalid integer value for page or size querystring parameters | Valor inválido para parâmetros de página ou tamanho de página |
| 400 | PSC000027 | Bad Request | Action cannot be taken place as there is currently a pending transfer in progress | A ação não pôde ser completada como há uma transferência pendente |
| 400 | PSC000028 | Bad Request | Pix Schedule cannot be cancelled in current status | Agendamento pix não pode ser cancelado no status atual |
| 400 | PSC000029 | Bad Request | The given Pix Schedule is tied to a batch. It cannot be individually cancelled | O agendamento pix enviado está ligado a um lote. Ela não pode ser individualmente cancelada |
| 400 | PSC000030 | Bad Request | The maximum amount of pix transfer attempts has been reached | A máxima quantidade de retentativas de transação pix foi atingida |
| 400 | PSC000031 | Bad Request | An error occurred while attempting to run pix transfer | Um erro ocorreu ao tentar realizar a transação pix |
| 404 | PSC000032 | Pix Key Not Found | Pix key was not found | Chave pix não encontrada |
| 404 | PSC000033 | Account Missmatch | Target Account changed from schedule creation | A conta alvo foi alterada desde a criação do agendamento |
| 400 | PSC000034 | Pix Schedule Conciliation Error | The referenced PixSchedule could not be updated | O PixSchedule referenciado não pode ser atualizado |
| 400 | PSC000035 | Pix Schedule Transfer Conciliation Error | The referenced PixScheduleTransfer could not be updated | O PixScheduleTransfer referenciado não pode ser atualizado |
| 404 | PSC000036 | Person Not Found | Person not found | Pessoa não encontrada |
| 400 | PSC000040 | Empty pix-schedule list received | A list of pix schedules must be provided | Uma lista de agendamentos pix deve ser fornecida |
| 409 | PSC000041 | Bad Request | One or more request_control_key already in use | Uma ou mais request_control_key já está sendo utilizada |
| 404 | PSC000042 | Schedule Batch not Found | ScheduleBatch was not found | ScheduleBatch não encontrada |
| 400 | PSC000043 | Schedule Batch could not be canceled | ScheduleBatch could not be canceled due to current date being equal or after earliest schedule date. Cancel pix_schedules one by one | ScheduleBatch não pode ser cancelada devido a data atual ser superior ou igual à menor schedule_date. Cancele pix_schedules individualmente |
| 400 | PSC000044 | Bad Request | Schedule Batch cannot be cancelled in current status | Agendamento pix não pode ser cancelado no status atual |
| 403 | PSC000045 | Requester not allowed to access this endpoint | Requester has no permission to perform pix transfers on this endpoint | Requester não possui permissão de realizar transações pix através deste endpoint |
| 400 | PSC000046 | tfa_info is required | Client must send object tfa_info | Cliente deve enviar objeto tfa_info |
| 403 | PSC000047 | No approver permission | Given document number does not belong to an approver for this account | Número de documento enviado não pertence a um aprovador da conta |
| 400 | PSC000048 | Error occurred while sending token | An unexpected error occurred while sending token | Um erro inesperado ocorreu ao tentar enviar token |
| 400 | PSC000049 | Number of token validation attempts exceeded | The maximum number of failed token validation attempts has been reached | Número máximo de tentativas de validação de token atingida |
| 400 | PSC000050 | Token Expired | Token has expired. Resend token or recreate schedule | Token expirado. Reenvie token ou recrie a agendamento |
| 400 | PSC000051 | Error Sending Token | An error occurred while sending token and its being investigated | Um erro ocorreu ao enviar token e está sendo investigado |
| 400 | PSC000052 | Incorrect Token | Token sent does not match expected | Token enviado não condiz com o esperado |
| 400 | PSC000053 | Error Sending Token | An error occurred while resending token and its being investigated | Um erro ocorreu ao reenviar token e está sendo investigado |
| 400 | PSC000054 | Invalid Schedule Date | Schedule must be approved before the scheduled date | Agendamento deve ser aprovado em data anterior à programada para transação |
| 400 | PSC000055 | Bad Request | Schedule cannot be approved in current status | Agendamento pix não pode ser aprovado no status atual |
---
# Introduction
URL: /en/documentation/baas/pix/agendamento/introducao
Through the endpoints presented in this section, the integrator partner can schedule pix-type transactions. This feature allows you to create, list, and cancel schedules for a specific account.
## Notes
- The scheduling date follows Brasília time (BRT or UTC/GMT -03:00).
- Transactions will be attempted starting at 8 AM BRT.
- Transactions that fail due to insufficient balance will be retried in 1 hour, with a limit of 3 attempts.
- For **key**, **static_qr_code**, and **dynamic_qr_code** transactions, the Pix key will be re-verified before the transaction is completed to ensure that the destination account has not changed. If any discrepancy is detected, the schedule will be rejected (**rejected**).
- A webhook will be sent to the integrator partner informing the success or rejection of a schedule.
- It's not possible to schedule an instant **dynamic_qr_code**.
- Scheduled transfers consume your Pix transaction limit.
## Pix Schedule Status
| Enumerator | Description |
|----------------------------|----------------------------------------------------------------------------------------------------|
| **scheduled** | Scheduled transaction |
| **sent** | Schedule completed and successfully sent. Final status. |
| **rejected** | Schedule rejected during creation or execution. Final status. |
| **cancelled** | Schedule canceled by customer request. Final status. |
| **pending_2fa_approval** | Pending two-factor authentication approval. |
| **pending_creation** | Schedule in the process of creation (Transitional state for batch scheduling). |
| **waiting_batch_approval** | Schedule created and linked to a batch awaiting two-factor authentication approval. |
## Schedule Transfers
On the scheduled day, after verifying the consistency of the target account, the pix transaction will be attempted. At this point, a **pix_transfer** is generated and added to the `schedule_transfers` list. A maximum of 3 pix transactions will be attempted.
### Schedule Transfer Object
| Field | Type | Description | Characters |
|----------------------|--------|-----------------------------------------------------------------------------------------------|---------------------------------------------|
| `pix_transfer_key` | uuidv4 | Unique key for identifying the Pix transfer in the QI system. | 36 |
| `end_to_end_id` * | string | Idempotency key for a Pix transaction within the SPI (Instant Payment System). | 32 |
| `pix_transfer_status`| string | Transaction status. | [Enumerators pix_transfer_status](#enumerator-pix-transfer-status) |
| `created_at` | string | Timestamp of when the transaction was created. | 20 |
### Enumerator Pix Transfer Status
| Enumerator | Description |
|------------|--------------------------------------|
| **sent** | Transaction successfully sent. Final status. |
| **rejected**| Transaction rejected during execution. Final status. |
| **pending**| Transaction pending conclusion. Transitional state. |
---
# Introduction to Two-Factor Authentication
URL: /en/documentation/baas/pix/agendamento/introducao_a_agendamento_2fa
In this type of scheduling, confirmation of payment programming is required via token sent to the person with powers to approve transactions in the debtor account.
The PIX scheduling request by integrator partners configured to use two-factor authentication is performed similarly to what is described in [request PIX transaction scheduling](/documentation/baas/pix/agendamento/solicitacao_de_agendamento). The difference occurs in adding the `tfa_info` object, containing information about the transfer approver and the contact method, and the status of a successful request that will always be **pending_2fa_approval**.
The same applies to PIX batch transactions described in [perform PIX batch transaction](/documentation/baas/pix/batch/solicitacao_de_transacao_em_lote_pix).
## Flow for a PIX scheduling with authorization
The successful PIX scheduling will follow the following process flow:
Performing the [PIX transaction request](/documentation/baas/pix/agendamento/solicitacao_de_agendamento_2fa) and receiving a synchronous response with status **pending_2fa_approval** and `schedule_key` value.
The indicated approver will receive a 6-digit `token` composed of numbers.
The requester performs the [PIX transaction confirmation](/documentation/baas/pix/agendamento/aprovacao_de_agendamento_2fa) with the `schedule_key` and the `token`.
The scheduling will then be updated to status **scheduled**.
## Observations
Each scheduling has a maximum limit of 5 `token` validation attempts. When this limit is reached, the scheduling will be automatically set to rejected status (**rejected**).
Each `token` has a maximum duration of 5 minutes.
A scheduling can have its `token` renewed and resent to the transfer approver. This process restarts the 5-minute timer and does not restart the invalid attempts counter. The previous `token` becomes invalid.
The notification event for sending `token` to the approver is **baas.token_validation.pix_transfer.schedule.single**. It is possible to [customize](/documentation/notificacoes/template) the sent message.
The implemented token sending methods (`contact_type`) are via **sms** and **email**.
---
# Request Pix transaction scheduling
URL: /en/documentation/baas/pix/agendamento/solicitacao_de_agendamento
## Request
ENDPOINT /account/ ACCOUNT_KEY /pix_schedule
MÉTODO POST
### Path Params
| Field | Type | Description | Characters |
|----------------|--------|-------------------------------------------|------------|
| `account_key` | uuidv4 | Unique account identification key. | 36 |
**Key**
Request Body: Pix Key Scheduling
```json
{
"request_control_key": "b6804f32-101e-4702-8fbc-c2dbc4c2caec",
"pix_transfer_type": "key",
"target_pix_key": "target_pix_key@email.com",
"transaction_amount": 500.65,
"end_to_end_id": "E73856642202309201429bZKfklNlbwu",
"pix_message": "Ola Mundo",
"schedule_date": "2024-12-01"
}
```
### Body Params
| Field | Type | Description | Characters |
|-----------------------|-----------|-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|------------|
| `request_control_key` * | uuidv4 | Unique identification key for the request used by the client in uuid v4 format. | 36 |
| `pix_transfer_type` * | enumerator| Type of the pix to be performed. For key transfer, it should be **key**. | **key** |
| `target_pix_key` * | string | Pix key of the account to which the transaction will be sent. | 100 |
| `transaction_amount` *| number | Transfer amount. | 10 |
| `end_to_end_id` * | string | Idempotency key for a Pix transaction within the SPI (Instant Payment System). This key is returned in Pix key queries. Should only be sent if `pix_transfer_type` is **key**, **static_qr_code**, or **dynamic_qr_code**. | 32 |
| `pix_message` | string | Message to be sent along with the Pix transfer. | 140 |
| `schedule_date` * | string | Date when the transaction is to be performed. | 10 |
**Manual**
Request Body: Manual Transfer
```json
{
"request_control_key": "b6804f32-101e-4702-8fbc-c2dbc4c2caec",
"pix_transfer_type": "manual",
"target_account": {
"account_branch": "0001",
"account_digit": "3",
"account_number": "12345678",
"owner_document_number": "32402502000135",
"owner_name": "Qi Tech",
"account_type": "checking_account",
"ispb": "32402502"
},
"transaction_amount": 500.65,
"pix_message": "Ola Mundo",
"schedule_date": "2024-12-01"
}
```
### Body Params
| Field | Type | Description | Characters |
|-----------------------|-----------|--------------------------------------------------------------------------------------------------|--------------------------------------------------------|
| `request_control_key` * | uuidv4 | Unique identification key for the request used by the client in uuid v4 format. | 36 |
| `pix_transfer_type` * | enumerator| Type of Pix transfer. | **manual** |
| `target_account` * | Object | Destination account - Should only be sent for transfers with `pix_transfer_type` of type **manual**. | **[Object target_account](#object-target_account)** |
| `transaction_amount` *| number | Transfer amount. | 10 |
| `pix_message` | string | Message to be sent along with the Pix transfer. | 140 |
| `schedule_date` * | string | Date when the transaction is to be performed. | 10 |
### Object target_account
| Field | Type | Description | Characters |
|-------------------------|-----------|----------------------------------------------------------------------------------------------|--------------------------------------------------------|
| `account_branch` * | string | Account branch. | 6 |
| `account_digit` * | string | Account digit. | 1 |
| `account_number` * | string | Account number. | 20 |
| `owner_document_number` * | string | CPF or CNPJ (numbers only) of the account holder. | 14 |
| `owner_name` * | string | Name of the account holder. | 150 |
| `account_type` * | enumerator| Account type. | **[Enumerator account_type](#enumerator-account_type)** |
| `ispb` * | string | Based on the CNPJ of the financial institution (8 digits). | 8 |
### Enumerator account_type
| Enumerator | Description |
|-----------------------|----------------------------|
| **checking_account** | Checking Account |
| **salary_account** | Salary Account |
| **saving_account** | Savings Account |
| **payment_account** | Payment Account |
**Qr Code**
Request Body: QR Code Transfer
```json
{
"request_control_key": "b6804f32-101e-4702-8fbc-c2dbc4c2caec",
"pix_transfer_type": "static_qr_code",
"transaction_amount": 500.65,
"end_to_end_id": "E73856642202309201429bZKfklNlbwu",
"receiver_conciliation_id": "REC00000000000000000000009459463343",
"target_pix_key": "target_pix_key@email.com",
"pix_message": "Ola Mundo",
"tfa_info": {
"approver_document_number": "98765432100",
"contact_type": "email"
}
}
```
### Body Params
| Field | Type | Description | Characters |
|--------------------------|-----------|-------------------------------------------------------------------------------------------------------------------------|----------------------------------------------|
| `request_control_key` * | uuidv4 | Unique identification key for the request used by the client in uuid v4 format. | 36 |
| `pix_transfer_type` * | enumerator| Type of Pix transfer. | **static_qr_code** or **dynamic_qr_code** |
| `target_pix_key` * | string | Pix key of the account to which the transaction will be sent. | 100 |
| `receiver_conciliation_id` | string | Reconciliation ID of the receiver. | 35 |
| `transaction_amount` * | number | Transfer amount. | 10 |
| `end_to_end_id` * | string | Idempotency key for a Pix transaction within the SPI (Instant Payment System). This key is returned in Pix key queries. Should only be sent if `pix_transfer_type` is **key**, **static_qr_code**, or **dynamic_qr_code**. | 32 |
| `pix_message` | string | Message to be sent along with the Pix transfer. | 140 |
| `tfa_info` * | Object | Object containing the document of the account approver and the means of contact. | **[Object tfa_info](#object-tfa_info)** |
:::info Warning
The `end_to_end_id` is returned when [decoding the Pix QR Code](/documentation/pix/decodificar_qr_code), using the Pix Copy and Paste URI.
:::
:::danger Warning
The `end_to_end_id` from the query must have been made in the name of the account that will request the transaction!
:::
:::danger Warning
An `end_to_end_id` can only be used for a single transfer, regardless of whether the transfer was successful or not.
:::
## Response
STATUS 201
Response Body: Schedule Created
```json
{
"request_control_key": "b6804f32-101e-4702-8fbc-c2dbc4c2caec",
"schedule_key": "f64b3fa7-d09d-4927-ad4f-b966df9fb153",
"schedule_status": "scheduled",
"schedule_date": "2024-12-31",
"created_at": "2023-03-13T19:00:28.440Z"
}
```
STATUS 4xx
Response Body: Error
```json
{
"title": "titulo",
"description": "description in English",
"translation": "description in portuguese",
"code": "codigo",
"extra_fields": {}
}
```
| HTTP Code `status` | QI Code `code` | Title `title` | Description (eng) `description` | Description (ptbr) `translation` |
|--------------------------|----------------------|-----------------------------------------------------|--------------------------------------------------------------------------------------------------------------------------------------|---------------------------------------------------------------------------------------------------------------------------------------------|
| 400 | QIT000001 | Bad Request | schema error description | Schema Inválido |
| 404 | PSC000001 | Account not Found | Account was not found | Conta não encontrada |
| 406 | PSC000002 | Invalid Uuid | key was not accepted for not being a valid uuid v4 string | key não foi aceito por não ser uma string uuid v4 válida |
| 400 | PSC000003 | Bad Request | pix_message can not be longer than 140 characters | pix_message não pode ter mais de 140 caracteres |
| 400 | PSC000004 | Bad Request | Emoji not allowed in pix message | Emoji não é permitido na mensagem pix |
| 406 | PSC000005 | Invalid Transaction Amount | Transaction amount of transaction_amount is not valid. It must be a positive value with at maximum 2 decimal places | O valor de transação transaction_amount não é válido. Deve ser um valor positivo com no máximo duas casas decimais |
| 406 | PSC000006 | Invalid end_to_end_id | The end_to_end_id sent end_to_end_id is not valid | O end_to_end_id enviado end_to_end_id não é válido |
| 400 | PSC000007 | Invalid date format | Dates must be sent using format YYYY-MM-DD | Datas devem ser enviadas no formato YYYY-MM-DD |
| 400 | PSC000008 | Invalid Schedule Date | Schedule date must be after current date for UTC-3 | Data de agendamento deve ser após a data atual em UTC-3 |
| 400 | PSC000009 | Account is Closed | Account is closed | Conta está fechada |
| 400 | PSC000010 | Account is Blocked | Account is blocked | Conta está bloqueada |
| 422 | PSC000011 | Invalid Account Type | Pix is not yet implemented for non-checking or non-escrow account types | Transações Pix não estão implementadas para conta que não sejam escrow ou livres |
| 403 | PSC000012 | User is not allowed to do this transaction | User is not allowed to do this transaction | Usuário não tem autorização para fazer essa transação |
| 400 | PSC000013 | Bad Request | For Manual Pix Transfer Type a target account must be provided | Para transação pix do tipo manual, uma conta destino deve ser fornecida |
| 404 | PSC000014 | Inquiry Not Found | Pix key inquiry was not found | Pesquisa de chave pix não encontrada |
| 400 | PSC000015 | Bad Request | Pix key sent does match inquiry pix key. Verify if end_to_end_id sent is correct | Chave Pix enviada não condiz com consulta. Verifique se end_to_end_id enviado está correto |
| 404 | PSC000016 | Account not found | Nonexistent account in destination financial institution | Conta inexistente na instituição financeira de destino |
| 400 | PSC000017 | Target Account and Source Account must be different | Target Account must not be the same as Source Account | A conta de destino não pode ser a mesma da conta de origem |
| 409 | PSC000018 | Bad Request | request_control_key request_control_key already in use | request_control_key request_control_key já utilizada |
| 400 | PSC000019 | Invalid Target | Account does not have permission to transfer to the given target account | A conta não possui permissão para realizar transferências para a conta enviada |
| 404 | PSC000020 | Decode Inquiry Not Found | QR Code decode inquiry not found | Pesquisa e decodificação de QR code não encontrada |
| 400 | PSC000021 | Bad Request | Receiver Conciliation Id sent does match decode inquiry receiver_conciliation_id. Verify if end_to_end_id sent is correct | Identificador de transação enviado não condiz com consulta. Verifique se end_to_end_id enviado está correto |
| 400 | PSC000022 | Bad Request | Dynamic Instant QR codes cannot be scheduled for payment | Pagamentos de vencimento instantâneo não podem ter pagamento agendado |
| 400 | PSC000023 | Bad Request | Schedule Date sent is after max payment date for target qr code | Data de agendamento enviada é após a data máxima de pagamento para o qr code enviado |
| 400 | PSC000024 | Bad Request | Pix transfer type sent does match decode inquiry qr code type. Verify if end_to_end_id sent is correct | Tipo de transação pix enviado não condiz com o tipo de qr code da consulta. Verifique se end_to_end_id enviado está correto |
---
# solicitacao_de_agendamento_2fa
URL: /en/documentation/baas/pix/agendamento/solicitacao_de_agendamento_2fa
---
# solicitacao_de_reenvio_de_token_para_agendamento_2fa
URL: /en/documentation/baas/pix/agendamento/solicitacao_de_reenvio_de_token_para_agendamento_2fa
---
# Pix Schedule Completion Webhook
URL: /en/documentation/baas/pix/agendamento/webhook_de_conclusao_de_agendamento
After a Pix schedule is completed, a webhook will be sent to the integration partner with the result.
:::danger Warning!
QI Tech webhooks should not be mapped in a restrictive way. Additional fields may be included in the webhook payloads returned by our APIs.
:::
### Webhook Request Body
Request Body: Schedule Completed and Sent
```json
{
"webhook_type": "baas.pix_schedule.completed",
"webhook_datetime": "2021-10-22T20:30:23.459Z",
"data": {
"created_at": "2024-07-10T16:17:28Z",
"pix_message": null,
"rejection_info": null,
"rejection_reason": null,
"request_control_key": "b8eb663e-10fe-4729-9db5-8f8c93de5001",
"schedule_date": "2024-07-10",
"schedule_key": "0c9091ab-079b-4a43-8b3d-d4ba36a23883",
"schedule_status": "sent",
"schedule_transfers": [
{
"created_at": "2024-07-10T16:19:33Z",
"end_to_end_id": "E3240250220240710161922sSHNf8BjI",
"pix_transfer_key": "427b70cd-73b0-45d1-bb4a-97f50f605022",
"pix_transfer_status": "sent"
}
],
"target_account": {
"account_branch": "0001",
"account_digit": "8",
"account_number": "1234567",
"account_type": "checking_account",
"ispb": "99999004",
"owner_document_number": "***91111***",
"owner_name": "Conta manual geral",
"owner_person_type": "natural",
"pix_key": null,
"receiver_conciliation_id": null
},
"transaction_amount": 2.0,
"updated_at": "2024-07-10T16:19:38Z"
}
}
```
Request Body: Schedule Completed and Rejected
```json
{
"created_at": "2024-07-11T16:03:54Z",
"pix_message": null,
"rejection_info": {
"error_code": "PSC000030",
"error_description": "The maximum amount of pix transfer attempts has been reached",
"error_translation": "A maxima quantidade de retentativas de transacao pix foi atingida",
"rejection_reason": "max_tries_exceeded"
},
"rejection_reason": null,
"request_control_key": "b8eb663e-10fe-4729-9db5-8f8c93de0008",
"schedule_date": "2024-07-11",
"schedule_key": "8b262d82-3fc6-40f0-bfe5-bf18556ededb",
"schedule_status": "rejected",
"schedule_transfers": [
{
"created_at": "2024-07-11T16:04:21Z",
"end_to_end_id": "E32402502202407111604ffoPVrGebI0",
"pix_transfer_key": "c2c4e064-e684-450b-add5-07fb1efe8991",
"pix_transfer_status": "rejected"
},
{
"created_at": "2024-07-11T16:08:33Z",
"end_to_end_id": "E32402502202407111608TQ3C4vRPRPk",
"pix_transfer_key": "c30254db-86b2-4d8a-be01-29fa0d93ae92",
"pix_transfer_status": "rejected"
},
{
"created_at": "2024-07-11T16:09:20Z",
"end_to_end_id": "E32402502202407111609zSUQQOvmMV6",
"pix_transfer_key": "1a329248-fc39-4b49-9b95-8f1c1bb10c8b",
"pix_transfer_status": "rejected"
}
],
"target_account": {
"account_branch": "0001",
"account_digit": "8",
"account_number": "1234567",
"account_type": "checking_account",
"ispb": "99999004",
"owner_document_number": "***91111***",
"owner_name": "Conta manual geral",
"owner_person_type": "natural",
"pix_key": null,
"receiver_conciliation_id": null
},
"transaction_amount": 2.0,
"updated_at": "2024-07-11T16:09:21Z"
}
```
### Webhook Body Param
| Field | Type | Description | Max. Characters |
|-----------------------|--------|------------------------------------------------------------------------------------|--------------------------------------------------------------------|
| `webhook_type` | string | An enumerator that defines the type of event being reported | 23 |
| `webhook_datetime` | string | Date and time of webhook dispatch | 20 |
| `transaction_amount` | number | Transfer amount | 10 |
| `target_account` | object | Schedule destination account | **[target_account object](#objeto-target_account)** |
| `schedule_transfers` | array | List of transfer attempts performed by the schedule | list of **[schedule_transfer object](#schedule-transfer-object)** |
| `schedule_status` | string | Schedule status | **[schedule_status enumerator](#pix-schedule-status)** |
| `schedule_key` | string | Unique schedule identification key | 36 |
| `schedule_date` | string | Date on which the transaction will be performed | 10 |
| `request_control_key` | uuidv4 | Unique request identification key used by the client in uuid v4 format | 36 | |
| `rejection_info` | object | Object with information about the rejection event | |
| `rejection_reason` | string | Reason for rejection | **[rejection_reason enumerators](#enumeradores-rejection_reason)** |
| `pix_message` | string | Message to be sent along with the Pix transfer | 140 |
| `updated_at` | string | Date and time of the last schedule update | 20 |
| `created_at` | string | Schedule creation date and time | 20 |
## Pix Schedule Status
| Enumerator | Description |
|----------------------------|------------------------------------------------------------------------------------------------|
| **scheduled** | Scheduled transaction |
| **sent** | Schedule completed and sent successfully. Final state |
| **rejected** | Schedule rejected during creation or execution. Final state |
| **cancelled** | Schedule cancelled by client request. Final state |
| **pending_2fa_approval** | Pending approval by two-factor authentication |
| **pending_creation** | Schedule in creation process (Transitional state for batch scheduling) |
| **waiting_batch_approval** | Schedule created and linked to a batch awaiting approval by two-factor authentication |
### Schedule Transfer Object
| Field | Type | Description | Characters |
|-----------------------|--------|-------------------------------------------------------------------------------------------------|---------------------------------------------------------------------|
| `pix_transfer_key` | uuidv4 | Unique identification key of the Pix transfer in the QI system | 36 |
| `end_to_end_id` * | string | Idempotency key of a Pix transaction within SPI (Instant Payment System) | 32 |
| `pix_transfer_status` | string | Transaction status | [pix_transfer_status enumerators](#enumerador-pix-transfer-status) | |
| `created_at` | string | Transaction creation date and time | 20 |
### Pix Transfer Status Enumerator
| Enumerator | Description |
|--------------|------------------------------------------------------|
| **sent** | Transaction sent successfully. Final state |
| **rejected** | Transaction rejected during execution. Final state |
| **pending** | Transaction pending completion. Transitional state |
### target_account Object
| Field | Type | Description | Characters |
|-------------------------|------------|-------------------------------------------------------------------------------------------------|-------------------------------------------------------------------|
| `account_branch` | string | Account branch | 6 |
| `account_digit` | string | Account digit | 1 |
| `account_number` | string | Account number | 20 |
| `owner_document_number` | string | CPF or CNPJ (numbers only) of the account holder | 14 |
| `owner_name` | string | Account holder name | 150 |
| `owner_person_type` | enumerator | Identifier indicating whether the account owner is a natural or legal person | **[owner_person_type enumerator](#enumerador-owner_person_type)** | |
| `owner_name` | string | Account holder name | 150 |
| `account_type` | enumerator | Account type | **[account_type enumerator](#enumerador-account_type)** |
| `ispb` | string | Eight-digit code that identifies banks in the Central Bank reserve transfer system | 8 |
| `pix_key` | string | Schedule target pix key | 100 |
### owner_person_type Enumerator
| Enum | Description |
|-------------|--------------|
| **natural** | Natural person |
| **legal** | Legal person |
### account_type Enumerator
| Enumerator | Description |
|----------------------|---------------------|
| **checking_account** | Checking Account |
| **salary_account** | Salary Account |
| **saving_account** | Savings Account |
| **payment_account** | Payment Account |
### rejection_reason Enumerators
| Enumerator | Description |
|-----------------------------------------------------|---------------------------------------------------------------------------|
| `target_creation_error` | Error in schedule creation |
| `limit_date_for_approval_surpassed` | Approval deadline surpassed |
| `limit_date_for_batch_approval_surpassed` | Batch approval deadline surpassed |
| `max_tries_exceeded` | Maximum number of attempts exceeded |
| `rejection_by_transfer` | Rejection by transfer |
| `target_change` | Change in destination account |
| `invalid_pix_key` | Invalid Pix key |
| `max_token_validation_attempts_exceeded` | Maximum number of token validation attempts exceeded |
| `error_sending_token` | Error sending token |
| `max_token_validation_attempts_exceeded_for_batch` | Maximum number of token validation attempts for batch exceeded |
---
# Approve batch transaction with Two-Factor Authentication
URL: /en/documentation/baas/pix/batch/aprovar_transacao_em_lote_pix_2fa
## Request
ENDPOINT /account/ ACCOUNT_KEY /pix_transfer_batch/ PIX_TRANSFER_BATCH_KEY /validate_token
METHOD PUT
### Path Params
| Field | Type | Description | Characters |
|---------------------------|--------|---------------------------------------------------------------|------------|
| `account_key` | uuidv4 | Unique account identification key. | 36 |
| `pix_transfer_batch_key` | uuidv4 | Unique identification key for the pix batch transfer. | 36 |
## Authentication via Email and SMS
Request Body
```json
{
"token": "329adf"
}
```
## Authentication via Device
To approve and finalize device authentication, the request must be sent with an empty payload. Validation occurs internally, with no additional information required in the request body. Note that this endpoint should only be used after the [batch transaction request](./solicitacao_de_transacao_em_lote_pix_2fa.md) has been initiated.
Request Body
```json
{
}
```
### Body Params
| Field | Type | Description | Characters |
|----------|--------|--------------------------------------------------------------------------------------------------|------------|
| `token` | string | Authentication code sent to the account's transaction approver **required for TFA via SMS or email** | 6 |
## Response
STATUS 201
Response Body: Transfer sent
```json
{
"request_control_key": "b6804f32-101e-4702-8fbc-c2dbc4c2caec",
"pix_transfer_batch_key": "8cb70dea-9fb0-4a68-9572-99a72849c8d6",
"pix_transfer_batch_status": "approved"
}
```
STATUS 4xx
Response Body: Transfer rejected
```json
{
"title": "titulo",
"description": "description in English",
"translation": "description in portuguese",
"code": "codigo",
"extra_fields": {
"pix_transfer_batch_data": {
"request_control_key": "b6804f32-101e-4702-8fbc-c2dbc4c2caec",
"pix_transfer_batch_key": "8cb70dea-9fb0-4a68-9572-99a72849c8d6",
"pix_transfer_batch_status": "rejected"
}
}
}
```
STATUS 4xx
Response Body: Error
```json
{
"title": "titulo",
"description": "description in English",
"translation": "description in portuguese",
"code": "codigo",
"extra_fields": {}
}
```
| HTTP Code `status` | QI Code `code` | Title `title` | Description (eng) `description` | Description (ptbr) `translation` |
|--------------------------|----------------------|----------------------------------------------|----------------------------------------------------------------------------------------------------------|--------------------------------------------------------------------------------------|
| 404 | PXT000178 | Pix Transfer Batch not found | A pix_transfer_batch not found | Uma pix_transfer_batch não encontrada |
| 400 | PXT000180 | Invalid Status | Pix transfer Batch not in pending_2fa_approval status | Pix transfer em lote não está pendente de aprovação por autenticação de dois fatores |
| 400 | PXT000171 | Number of token validation attempts exceeded | The maximum number of failed token validation attempts has been reached | Número máximo de tentativas de validação de token atingida |
| 400 | PXT000172 | Token Expired | Token has expired. Resend token or recreate transferToken has expired. Resend token or recreate transfer | Token expirado. Reenvie token ou recrie a transferência |
| 400 | PXT000173 | Incorrect Token | Token sent does not match expected | Token enviado não condiz com, o esperado |
| 400 | PXT000189 | Token Required | A token is required for SMS or email validation. | Um token é necessário para validação via SMS ou email. |
---
# Introduction to Pix Batch Transaction
URL: /en/documentation/baas/pix/batch/introducao_a_transacao_em_lote_pix
QI Tech offers the possibility of performing multiple Pix transactions with a single call. In this system, transactions are carried out asynchronously. If an **http status 4xx** is returned in the initial call, none of the transactions will be executed. After the request, the integrator partner will receive a webhook for each transaction informing the final status of the attempt, which can be **rejected** or **sent**.
## Two-Factor Authentication
As with Pix transactions, integrator partners with two-factor authentication configuration must send the `tfa_info` object with contact information and token delivery details.
---
# List Transactions of a Batch in an Account
URL: /en/documentation/baas/pix/batch/listar_transacoes_de_um_lote_de_transacoes_pix
## Request
ENDPOINT /account/ ACCOUNT_KEY /pix_transfer_batch/ PIX_TRANSFER_BATCH_KEY /pix_transfers
METHOD GET
### Path Params
| Field | Type | Description | Characters |
|-------------------------|--------|---------------------------------------------------|------------|
| `account_key` | uuidv4 | Unique identification key of the account. | 36 |
| `pix_transfer_batch_key`| uuidv4 | Unique identification key of the batch transaction. | 36 |
### Query Params
| Field | Type | Description | Characters |
|-------------------------|---------|-------------------------------------------------------------------------|----------------------------------------------------|
| `request_control_key` | uuidv4 | Unique request identification key used by the client. | 36 |
| `pix_transfer_batch_status` | string | Status of the Pix transaction. | [Enumerator pix_transfer_status](#enumerator-pix_transfer_status) |
| `page` | integer | Requested page number. Default is 1 | |
| `page_size` | integer | Requested page size in the query. Default and maximum value is 30 | Maximum value of 30 |
### Enumerator pix_transfer_status
| Enumerator | Description |
|---------------------------|---------------------------------------------------------|
| **sent** | Pix transfer successfully completed. |
| **pending** | Pix transfer pending. |
| **pending_2fa_approval** | Pix transfer pending two-factor approval |
| **rejected** | Pix transfer rejected. |
### Response
STATUS 200
Response Body
```json
{
"data": [
{
"request_control_key": "b6804f32-101e-4702-8fbc-c2dbc4c2caec",
"pix_transfer_key": "8cb70dea-9fb0-4a68-9572-99a72849c8d6",
"end_to_end_id": "E32402502202405081755SxyT2DDcVwc",
"pix_transfer_status": "sent",
"created_at": "2021-10-22T20:30:23.459Z"
},
{
"request_control_key": "697c07c3-5398-48d2-a418-853323f85f97",
"pix_transfer_key": "e95eabdb-4520-4c3d-a76f-99cb5b64724b",
"end_to_end_id": "E32402502202405081755SxyT14Dtvwa",
"pix_transfer_status": "sent",
"created_at": "2021-10-22T20:30:23.459Z"
},
{
"request_control_key": "ca35c526-b5a0-40d7-8c56-8566c77a34f4",
"pix_transfer_key": "58d2fa9e-42ec-4779-b2fc-14ec98cbdca8",
"end_to_end_id": "E32402502202405081755SsbT7DDcVwb",
"pix_transfer_status": "rejected",
"created_at": "2021-10-22T20:30:23.459Z"
}
],
"pagination": {
"current_page": 1,
"rows_per_page": 30
}
}
```
---
# List Batch Transactions of an Account
URL: /en/documentation/baas/pix/batch/listar_transacoes_em_lote_pix_de_uma_conta
## Request
ENDPOINT /account/ ACCOUNT_KEY /pix_transfer_batches
METHOD GET
### Path Params
| Field | Type | Description | Characters |
|---------------|--------|----------------------------------------|------------|
| `account_key` | uuidv4 | Unique identification key of the account. | 36 |
### Query Params
| Field | Type | Description | Characters |
|-----------------------|--------|-------------------------------------------------------------------------|--------------------------|
| `request_control_key` | uuidv4 | Unique request identification key used by the client. | 36 |
| `date_from` | string | Start date. Format "YYYY-MM-DD" | |
| `date_to` | string | End date. Format "YYYY-MM-DD" | |
| `page` | integer| Requested page number. Default is 1 | |
| `page_size` | integer| Requested page size in the query. Default and maximum value is 30 | Maximum value of 30 |
### Response
STATUS 200
Response Body
```json
{
"data": [
{
"request_control_key": "b6804f32-101e-4702-8fbc-c2dbc4c2caec",
"pix_transfer_batch_key": "8cb70dea-9fb0-4a68-9572-99a72849c8d6",
"pix_transfer_batch_status": "approved"
},
{
"request_control_key": "939d1503-aa5a-49a6-ae3b-ff84122a6dd3",
"pix_transfer_batch_key": "03cf9181-0eb9-480e-8bb4-66a5a9a6410e",
"pix_transfer_batch_status": "rejected"
},
{
"request_control_key": "43a14f3a-b2af-4a0e-8a74-70af2fca74a9",
"pix_transfer_batch_key": "94ab9fad-9c65-4117-b9c3-a47b1269508f",
"pix_transfer_batch_status": "approved"
}
],
"pagination": {
"current_page": 1,
"rows_per_page": 30
}
}
```
# Consult Batch Transaction
## Request
ENDPOINT /account/ ACCOUNT_KEY /pix_transfer_batch/ PIX_TRANSFER_BATCH_KEY
METHOD GET
### Path Params
| Field | Type | Description | Characters |
|-------------------------|--------|---------------------------------------------------|------------|
| `account_key` | uuidv4 | Unique identification key of the account. | 36 |
| `pix_transfer_batch_key`| uuidv4 | Unique identification key of the batch transaction. | 36 |
### Response
STATUS 200
Response Body
```json
{
"request_control_key": "b6804f32-101e-4702-8fbc-c2dbc4c2caec",
"pix_transfer_batch_key": "8cb70dea-9fb0-4a68-9572-99a72849c8d6",
"pix_transfer_batch_status": "approved"
}
```
---
# Request token resend for a batch Pix transaction
URL: /en/documentation/baas/pix/batch/solicitacao_de_reenvio_de_token_para_lote
A new token will be generated and sent to the account's transaction approver. If the limit number of token validation attempts has been exceeded, the resend will not be allowed.
## Request
ENDPOINT /account/ ACCOUNT_KEY /pix_transfer/ PIX_TRANSFER_KEY /resend_token
METHOD PATCH
### Path Params
| Field | Type | Description | Characters |
|---------------------------|--------|--------------------------------------------|------------|
| `account_key` * | uuidv4 | Unique account identification key. | 36 |
| `pix_transfer_batch_key` *| uuidv4 | Unique identification key for the batch transfer. | 36 |
## Response
STATUS 202
Response Body: Transaction Requested
```json
{
"request_control_key": "b6804f32-101e-4702-8fbc-c2dbc4c2caec",
"pix_transfer_batch_key": "8cb70dea-9fb0-4a68-9572-99a72849c8d6",
"pix_transfer_status": "pending_2fa_approval"
}
```
STATUS 4xx
Response Body: Transfer rejected
```json
{
"title": "titulo",
"description": "description in English",
"translation": "description in portuguese",
"code": "codigo",
"extra_fields": {
"pix_transfer_data": {
"request_control_key": "b6804f32-101e-4702-8fbc-c2dbc4c2caec",
"pix_transfer_batch_key": "8cb70dea-9fb0-4a68-9572-99a72849c8d6",
"pix_transfer_status": "rejected"
}
}
}
```
| HTTP Code `status` | QI Code `code` | Title `title` | Description (eng) `description` | Description (ptbr) `translation` |
|--------------------------|----------------------|----------------------------------------------|----------------------------------------------------------------------------------------------------------|--------------------------------------------------------------------------------------|
| 400 | QIT000001 | Bad Request | Schema Error | Erro de Schema |
| 404 | PXT000004 | Account not found | Account not found for: \{account_datum\} | Conta não encontrada para: \{account_datum\} |
| 400 | PXT000176 | Error Sending Token | An error occurred while resending token and its being investigated | Um erro ocorreu ao reenviar token e está sendo investigado |
| 404 | PXT000178 | Pix Transfer Batch not found | A pix_transfer_batch not found | Uma pix_transfer_batch não encontrada |
| 400 | PXT000180 | Invalid Status | Pix transfer Batch not in pending_2fa_approval status | Pix transfer em lote não está pendente de aprovação por autenticação de dois fatores |
| 400 | PXT000171 | Number of token validation attempts exceeded | The maximum number of failed token validation attempts has been reached | Número máximo de tentativas de validação de token atingida |
| 400 | PXT000172 | Token Expired | Token has expired. Resend token or recreate transferToken has expired. Resend token or recreate transfer | Token expirado. Reenvie token ou recrie a transferência |
| 400 | PXT000173 | Incorrect Token | Token sent does not match expected | Token enviado não condiz com, o esperado |
---
# Perform Pix Batch Transaction
URL: /en/documentation/baas/pix/batch/solicitacao_de_transacao_em_lote_pix
QI Tech offers the possibility of performing multiple Pix transactions with a single call. In this system, transactions are carried out asynchronously. If an **http status 4xx** is returned in the initial call, none of the transactions will be executed. After the request, the integrator partner will receive a webhook for each transaction informing the final status of the attempt, which can be **rejected** or **sent**.
## Request
ENDPOINT /account/ ACCOUNT_KEY /pix_transfer_batch
METHOD POST
```json
{
"request_control_key": "6e4fc980-f8a1-4462-b6e2-d8a49f0ac055",
"pix_transfers": [
{
"request_control_key": "b6804f32-101e-4702-8fbc-c2dbc4c2caec",
"pix_transfer_type": "key",
"target_pix_key": "target_pix_key@email.com",
"transaction_amount": 500.65,
"end_to_end_id": "E73856642202309201429bZKfklNlbwu",
"pix_message": "Hello World!"
},
{
"request_control_key": "5fb20e2e-78e3-4ca7-bb36-515640ec2e78",
"pix_transfer_type": "manual",
"target_account": {
"account_branch": "0001",
"account_digit": "3",
"account_number": "12345678",
"owner_document_number": "32402502000135",
"owner_name": "Qi Tech",
"account_type": "checking_account",
"ispb": "32402502"
},
"transaction_amount": 500.65,
"pix_message": "Hello World!"
},
{
"request_control_key": "10ad6e08-1a4c-403c-8122-178b0acf1dfa",
"pix_transfer_type": "static_qr_code",
"transaction_amount": 500.65,
"end_to_end_id": "E73856642202309201429bZKfklNlbrb",
"receiver_conciliation_id": "REC00000000000000000000009459463343",
"target_pix_key": "target_pix_key@email.com",
"pix_message": "Hello World!"
}
]
}
```
## Path Params
| Field | Type | Description | Characters |
|---------------|--------|----------------------------------------|------------|
| `account_key` | uuidv4 | Unique identification key of the account. | 36 |
### Body Params
| Field | Type | Description | Characters |
|-------------------------|--------|-----------------------------------------------------------------------------------------------------|---------------------------------------------|
| `request_control_key` * | uuidv4 | Unique request identification key used by the client in uuid v4 format. | 36 |
| `pix_transfers` * | array | List of pix_transfer objects linked to the batch. | list of **[Object pix_transfer](#object-pix_transfer)** |
### Object pix_transfer
| Field | Type | Description | Characters |
|---------------------------|------------|----------------------------------------------------------------------------------------------------------------------------------|---------------------------------------------|
| `request_control_key` * | uuidv4 | Unique request identification key used by the client in uuid v4 format. | 36 |
| `pix_transfer_type` * | enumerator | Type of pix to be performed. | **[Enumerator pix_transfer_type](#enumerator-pix_transfer_type)** |
| `target_pix_key` | string | Pix key of the account to which the transaction will be sent. | 100 |
| `target_account` | Object | Destination account - Should only be sent in transfers with `pix_transfer_type` of type **manual**. | **[Object target_account](#object-target_account)** |
| `receiver_conciliation_id`| string | Receiver's conciliation identification. | 35 |
| `transaction_amount` * | number | Transfer amount. | 10 |
| `end_to_end_id` | string | Idempotency key of a Pix transaction within the SPI (Instant Payment System). This key is returned in the Pix key query. Should only be sent if the `pix_transfer_type` is **key**, **static_qr_code**, or **dynamic_qr_code** | 32 |
| `pix_message` | string | Message to be sent along with the Pix transfer. | 140 |
### Object target_account
| Field | Type | Description | Characters |
|----------------------------|------------|-------------------------------------------------------------------|---------------------------------------------|
| `account_branch` * | string | Branch of the account. | 6 |
| `account_digit` * | string | Account digit. | 1 |
| `account_number` * | string | Account number. | 20 |
| `owner_document_number` * | string | CPF or CNPJ (numbers only) of the account holder. | 14 |
| `owner_name` * | string | Name of the account holder. | 150 |
| `account_type` * | enumerator | Type of account. | **[Enumerator account_type](#enumerator-account_type)** |
| `ispb` * | string | Based on the financial institution's CNPJ (8 digits). | 8 |
### Enumerator account_type
| Enumerator | Description |
|-----------------------|---------------------|
| **checking_account** | Conta Corrente |
| **salary_account** | Conta Salário |
| **saving_account** | Conta Poupança |
| **payment_account** | Conta de Pagamentos|
### Enumerator pix_transfer_type
| Enumerator | Description |
|-----------------------|---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|
| **manual** | Pix using the destination account details. Required to send `target_account` |
| **key** | Pix using a pix key. Required to send `target_pix_key`. Recommended to send `end_to_end_id` from the [Pix key query](/documentation/pix_indireto/movimentacoes/consultar_chave_pix) if it has been performed |
| **static_qr_code** | Pix using a static QR code. Required to send the `end_to_end_id` returned in the [QR code decoding](/documentation/pix/decodificar_qr_code) |
| **dynamic_qr_code** | Pix using a dynamic QR code. Required to send the `end_to_end_id` returned in the [QR code decoding](/documentation/pix/decodificar_qr_code) |
## Response
STATUS 201
Response Body: Batch Transfer Approved
```json
{
"request_control_key": "b6804f32-101e-4702-8fbc-c2dbc4c2caec",
"pix_transfer_batch_key": "8cb70dea-9fb0-4a68-9572-99a72849c8d6",
"pix_transfer_batch_status": "approved"
}
```
### Enumerator pix_transfer_batch_status
| Enumerator | Description |
|---------------------------|--------------------------------------------------------------------------|
| **approved** | Batch transfer approved and transactions in execution process. |
| **rejected** | Batch transfer rejected |
| **pending_2fa_approval** | Batch transfer pending manual approval |
STATUS 4xx
Response Body: Transfer Rejected
```json
{
"title": "title",
"description": "description in English",
"translation": "description in Portuguese",
"code": "code",
"extra_fields": {
"pix_transfer_batch_data": {
"request_control_key": "b6804f32-101e-4702-8fbc-c2dbc4c2caec",
"pix_transfer_batch_key": "8cb70dea-9fb0-4a68-9572-99a72849c8d6",
"pix_transfer_batch_status": "rejected"
}
}
}
```
STATUS 4xx
Response Body: Error
```json
{
"title": "title",
"description": "description in English",
"translation": "description em Portuguese",
"code": "code",
"extra_fields": {}
}
```
:::info Information
The errors previously listed for [Pix transfer](/documentation/baas_v2/pix/realizar_transferencia) may be returned by this endpoint.
:::
---
# Perform batch Pix transaction with Two-Factor Authentication
URL: /en/documentation/baas/pix/batch/solicitacao_de_transacao_em_lote_pix_2fa
QI Tech offers the possibility to perform multiple Pix transactions with a single call. In this system, transactions are performed asynchronously. If a **http status 4xx** is returned on the initial call, none of the transactions will be executed. After the request, the integration partner will receive a webhook for each transaction informing the final status of the attempt, which can be **rejected** or **sent**.
In this type of transaction, payment confirmation via a token sent to the person with approval powers for movements in the creditor account is required.
The request for a Pix transaction by integration partners configured to use two-factor authentication is made similarly to what is described in [perform batch Pix transaction](/documentation/baas_v2/pix/batch/solicitacao_de_transacao_em_lote_pix).
The difference is the addition of the `tfa_info` object, containing information about the transfer approver and the means of contact, and the status of a successful request, which will always be **pending_2fa_approval**.
The notification event for sending the `token` to the approver is **baas.token_validation.pix_transfer.batch**. It is possible to [customize](/documentation/notificacoes/template) the sent message.
## Request
ENDPOINT /account/ ACCOUNT_KEY /pix_transfer_batch
METHOD POST
## Authentication via Email and SMS
Request Body: Batch Transfer with TFA via SMS or Email
```json
{
"request_control_key": "6e4fc980-f8a1-4462-b6e2-d8a49f0ac055",
"tfa_info": {
"approver_document_number": "98765432100",
"contact_type": "email"
},
"pix_transfers": [
{
"request_control_key": "b6804f32-101e-4702-8fbc-c2dbc4c2caec",
"pix_transfer_type": "key",
"target_pix_key": "target_pix_key@email.com",
"transaction_amount": 500.65,
"end_to_end_id": "E73856642202309201429bZKfklNlbwu",
"pix_message": "Ola Mundo"
},
{
"request_control_key": "5fb20e2e-78e3-4ca7-bb36-515640ec2e78",
"pix_transfer_type": "manual",
"target_account": {
"account_branch": "0001",
"account_digit": "3",
"account_number": "12345678",
"owner_document_number": "32402502000135",
"owner_name": "Qi Tech",
"account_type": "checking_account",
"ispb": "32402502"
},
"transaction_amount": 500.65,
"pix_message": "Ola Mundo"
},
{
"request_control_key": "10ad6e08-1a4c-403c-8122-178b0acf1dfa",
"pix_transfer_type": "static_qr_code",
"transaction_amount": 500.65,
"end_to_end_id": "E73856642202309201429bZKfklNlbrb",
"receiver_conciliation_id": "REC00000000000000000000009459463343",
"target_pix_key": "target_pix_key@email.com",
"pix_message": "Ola Mundo"
}
]
}
```
## Authentication via Device
In addition to the existing authentication methods via **sms** and **email**, it is possible to authenticate the transaction using a previously [registered device](/documentation/baas/dispositivo/create/solicitacao_cadastro_dispositivo). In this case, the `session_id` must be obtained in the **Device Scan** and sent in `tfa_info`.
Request Body: Batch Transfer with TFA via Device
```json
{
"request_control_key": "6e4fc980-f8a1-4462-b6e2-d8a49f0ac055",
"tfa_info": {
"approver_document_number": "98765432100",
"session_id": "b2f18d3a-67c2-4a7f-98e5-1d3f5c6b8a72",
"contact_type": "device"
},
"pix_transfers": [
{
"request_control_key": "b6804f32-101e-4702-8fbc-c2dbc4c2caec",
"pix_transfer_type": "key",
"target_pix_key": "target_pix_key@email.com",
"transaction_amount": 500.65,
"end_to_end_id": "E73856642202309201429bZKfklNlbwu",
"pix_message": "Ola Mundo"
},
{
"request_control_key": "5fb20e2e-78e3-4ca7-bb36-515640ec2e78",
"pix_transfer_type": "manual",
"target_account": {
"account_branch": "0001",
"account_digit": "3",
"account_number": "12345678",
"owner_document_number": "32402502000135",
"owner_name": "Qi Tech",
"account_type": "checking_account",
"ispb": "32402502"
},
"transaction_amount": 500.65,
"pix_message": "Ola Mundo"
},
{
"request_control_key": "10ad6e08-1a4c-403c-8122-178b0acf1dfa",
"pix_transfer_type": "static_qr_code",
"transaction_amount": 500.65,
"end_to_end_id": "E73856642202309201429bZKfklNlbrb",
"receiver_conciliation_id": "REC00000000000000000000009459463343",
"target_pix_key": "target_pix_key@email.com",
"pix_message": "Ola Mundo"
}
]
}
```
## Path Params
| Field | Type | Description | Characters |
|--------------- |--------|-------------------------------------------|------------|
| `account_key` | uuidv4 | Unique account identification key. | 36 |
### Body Params
| Field | Type | Description | Characters |
|----------------------|--------|---------------------------------------------------------------------------------------|-------------------------------------------|
| `request_control_key` * | uuidv4 | Unique identification key for the request used by the client in uuid v4 format. | 36 |
| `pix_transfers` * | array | List of pix_transfer objects linked to the batch. | list of **[Object pix_transfer](#object-pix_transfer)** |
| `tfa_info` * | Object | Object containing the document of the account approver and the means of contact. | **[Object tfa_info](#object-tfa_info)** |
### Object tfa_info
| Field | Type | Description | Characters |
|------------------------------|--------|-----------------------------------------------------------------------------------------------|------------|
| `approver_document_number` * | string | Document number of the account approver. | 11 |
| `session_id` | string | Unique device session identification key in UUID v4 format (required for device TFA). | 36 |
| `contact_type` * | string | Means of contact with the account approver, can be **sms**, **email** or **device** | |
### Object pix_transfer
| Field | Type | Description | Characters |
|----------------------|-----------|------------------------------------------------------------------------------------------------------------------------|--------------------------------------------|
| `request_control_key` * | uuidv4 | Unique identification key for the request used by the client in uuid v4 format. | 36 |
| `pix_transfer_type` * | enumerator| Type of the pix to be performed. | **[Enumerator pix_transfer_type](#enumerator-pix_transfer_type)** |
| `target_pix_key` | string | Pix key of the account to which the transaction will be sent. | 100 |
| `target_account` | Object | Destination account - Should only be sent for transfers with `pix_transfer_type` of type **manual**. | **[Object target_account](#object-target_account)** |
| `receiver_conciliation_id` | string | Reconciliation ID of the receiver. | 35 |
| `transaction_amount` *| number | Transfer amount. | 10 |
| `end_to_end_id` | string | Idempotency key for a Pix transaction within the SPI (Instant Payment System). This key is returned in Pix key queries. Should only be sent if `pix_transfer_type` is **key**, **static_qr_code**, or **dynamic_qr_code**. | 32 |
| `pix_message` | string | Message to be sent along with the Pix transfer. | 140 |
### Object target_account
| Field | Type | Description | Characters |
|-------------------------|-----------|-------------------------------------------------------------------------------------------------------------------------|--------------------------------------------|
| `account_branch` * | string | Account branch. | 6 |
| `account_digit` * | string | Account digit. | 1 |
| `account_number` * | string | Account number. | 20 |
| `owner_document_number` * | string | CPF or CNPJ (numbers only) of the account holder. | 14 |
| `owner_name` * | string | Name of the account holder. | 150 |
| `account_type` * | enumerator| Account type. | **[Enumerator account_type](#enumerator-account_type)** |
| `ispb` * | string | Based on the CNPJ of the financial institution (8 digits). | 8 |
### Enumerator account_type
| Enumerator | Description |
|-----------------------|----------------------------|
| **checking_account** | Checking Account |
| **salary_account** | Salary Account |
| **saving_account** | Savings Account |
| **payment_account** | Payment Account |
### Enumerator pix_transfer_type
| Enumerator | Description |
|------------------------|--------------------------------------------------------------------------------------|
| **manual** | Pix using destination account details. Must send `target_account`. |
| **key** | Pix using a pix key. Must send `target_pix_key`. Recommended to send `end_to_end_id` from the [pix key query](/documentation/pix_indireto/movimentacoes/consultar_chave_pix) if previously performed |
| **static_qr_code** | Pix using a static QR code. Must send the `end_to_end_id` returned in the [QR code decode](/documentation/pix/decodificar_qr_code) |
| **dynamic_qr_code** | Pix using a dynamic QR code. Must send the `end_to_end_id` returned in the [QR code decode](/documentation/pix/decodificar_qr_code) |
## Response
STATUS 201
Response Body: Batch Transfer Requested
```json
{
"request_control_key": "b6804f32-101e-4702-8fbc-c2dbc4c2caec",
"pix_transfer_batch_key": "8cb70dea-9fb0-4a68-9572-99a72849c8d6",
"pix_transfer_batch_status": "pending_2fa_approval"
}
```
### Enumerador pix_transfer_batch_status
| Enumerator | Description |
|--------------------------|-------------------------------------------------------------------|
| **approved** | Batch transfer approved and transactions in the process of execution. |
| **rejected** | Batch transfer rejected |
| **pending_2fa_approval** | Batch transfer pending manual approval |
STATUS 4xx
Response Body: Transfer rejected
```json
{
"title": "titulo",
"description": "description in English",
"translation": "description in portuguese",
"code": "codigo",
"extra_fields": {
"pix_transfer_batch_data": {
"request_control_key": "b6804f32-101e-4702-8fbc-c2dbc4c2caec",
"pix_transfer_batch_key": "8cb70dea-9fb0-4a68-9572-99a72849c8d6",
"pix_transfer_batch_status": "rejected"
}
}
}
```
STATUS 4xx
Response Body: Error
```json
{
"title": "titulo",
"description": "description in English",
"translation": "descrição em portugues",
"code": "codigo",
"extra_fields": {}
}
```
:::info Informação
Os erros anteriormente listados para [transferência Pix](/documentation/baas_v2/pix/realizar_transferencia) são
passiveis de serem retornados por este endpoint além dos erros listados abaixo.
:::
| HTTP Code `status` | QI Code `code` | Title `title` | Description (eng) `description` | Description (ptbr) `translation` |
|--------------------------|----------------------|------------------------------------|-----------------------------------------------------------------------|------------------------------------------------------------------|
| 400 | PXT000168 | No approver permission | Given document number does not belong to an approver for this account | Número de documento enviado não pertence a um aprovador da conta |
| 400 | PXT000169 | tfa_info is required | Client must send object tfa_info | Cliente deve enviar objeto tfa_info |
| 400 | PXT000170 | Error occurred while sending token | An unexpected error occurred while sending token | Um erro inexperado ocorreu ao tentar enviar token |
---
# Consult Pix Key Data at the Central Bank
URL: /en/documentation/baas/pix/consultar_chave_pix
## Request
ENDPOINT /pix_key/ PIX_KEY
METHOD GET
### Request Path Params
| Field | Type | Description | Characters |
|-------------|--------|--------------------------------|------------|
| `pix_key` * | string | Pix Key to be queried. | 77 |
:::info Types of Pix Key
The “pix_key” can be a CPF, CNPJ, Email, Mobile Number, or a Random Key (UUID), following these formats:
**CPF**: Integer number with 11 digits.
**CNPJ**: Integer number with 14 digits.
**Email**: Text containing at least one “@”.
**Mobile Number**: Text containing the following values: “+55” + “Cell Phone Area Code“ + “Cell Phone Number with a minimum of 8 and a maximum of 9 digits”. Example: “+5511987654321“.
**Random Key**: UUID4.
:::
### Request Query Params
| Field | Type | Description | Characters |
|--------------------|--------|----------------------------------------------------------------------------------------------------------------------------------------------|------------|
| `account_key` * | uuidv4 | Unique identification key of the account. | 36 |
| `document_number` | string | CPF/CNPJ of the Pix Key holder. By passing this parameter, the field `is_pix_key_owner` will be returned with a boolean value indicating whether the CPF/CNPJ provided matches the Pix Key holder's. | 14 or 11 |
:::info Usage of Query Tokens
To charge the Pix key query token from the account holder, it is mandatory to send the `account_key`.
If the account_key is not sent, the token will be charged from the document number of the integrator partner.
:::
## Response
STATUS 200
Response Body: Active Key
```json
{
"account_branch": "452",
"account_created_at": "2021-10-22T20:30.459Z",
"account_digit": "1",
"account_number": "370158",
"account_type": "checking_account",
"bank_code": "237",
"end_to_end_id": "E3240250220230404185631R0kjZnC6G",
"financial_institution": "BCO BRADESCO S.A.",
"is_pix_key_owner": false,
"ispb": "60746948",
"owner_masked_document_number": "***.141.857-**",
"owner_name": "Teste teste",
"owner_person_type": "legal",
"owner_trading_name": "Teste LTDA.",
"pix_key": "teste@gmail.com"
}
```
| Field | Type | Description | Max. Characters |
|-------------------------------|---------|--------------------------------------------------------------------------------------------------------------------------------------------------------------------------|-----------------|
| `account_branch` | string | Account branch linked to the Pix Key, without the check digit. | 4 |
| `account_created_at` | string | Account opening date linked to the Pix Key, provided by the custodian institution of the account. | 21 |
| `account_digit` | string | Check digit of the account linked to the Pix Key. | 1 |
| `account_number` | string | Account number linked to the Pix Key without the check digit. | 20 |
| `account_type` | enum | Definition of the account type of the Pix Key. | [Enumerators Account Type](#enumerators-account_type) |
| `bank_code` | string | Bank code of the Pix Key registrar. May be null for institutions that do not have a bank code. | 3 |
| `end_to_end_id` | string | Unique identifier of the Pix key query at Bacen. Must be sent in the Pix transfer so that the token consumed in the query can be recovered. | 32 |
| `financial_institution` | string | Name of the financial institution registering the Pix Key. | 200 |
| `is_pix_key_owner` | boolean | A boolean value will be returned if the `document_number` parameter is passed in the request. This field indicates whether the CPF/CNPJ provided in the `document_number` parameter matches the Pix Key holder. It will return null if the `document_number` parameter is not provided. | - |
| `ispb` | string | ISPB of the Participant holding the Pix Key. | 8 |
| `owner_masked_document_number`| string | Masked CPF number or CNPJ of the Pix Key holder. | 14 |
| `owner_name` | string | Name of the Pix Key holder. | 120 |
| `owner_person_type` | enum | Legal nature of the Pix Key holder. | [Enumerators Owner Person Type](#enumerators-owner_person_type) |
| `owner_trading_name` | string | Trade name of the Pix Key holder (only for `owner_person_type=legal`). | 100 |
| `pix_key` | string | Pix Key. | - |
### Enumerators account_type
| Enumerator | Description |
|---------------------|---------------------|
| `payment` | Conta de pagamento |
| `checking` | Conta de corrente |
| `savings` | Conta poupança |
| `saving` | Conta poupança |
| `salary` | Conta salário |
| `saving_account` | Conta poupança |
| `payment_account` | Conta de pagamento |
| `checking_account` | Conta de corrente |
| `salary_account` | Conta salário |
| `escrow` | Conta Vinculada |
:::info
Different enumerators can mean the same type of account due to the information returned by different institutions.
:::
### Enumerators owner_person_type
| Enumerator | Description |
|------------|-----------|
| `natural` | string |
| `legal` | string |
STATUS 4XX
Response Body
```json
{
"title": "titulo",
"description": "description in English",
"translation": "description in Portuguese",
"code": "code"
}
```
| HTTP Code | QI Code `code` | Title `title` | Description (eng) `Description` | Description (ptbr) `translation` |
|-------------|----------------------|----------------------------------|------------------------------------------------------------------------|--------------------------------------------------------------------------|
| 404 | PIX000017 | Pix Key Not Found | Pix key \{pix_key\} not found. | A chave pix \{pix_key\} não foi encontrada. |
| 403 | PIX000080 | Not enough permission | The selected agent doesn't have permission to access this resource. | O agente selecionado não tem permissão para acessar este recurso. |
| 429 | PIX000081 | Rate Limit Exceeded | Rate Limit Exceeded | Limite de requisições excedido |
| 404 | PIX000083 | Pix Key not found | Pix Key \{pix_key\} not found for Alias \{alias_key\} | Chave Pix \{pix_key\} não encontrada para o Alias \{alias_key\} |
| 400 | PIX000084 | Only one query param allowed | Only one query param allowed | Somente um parâmetro de consulta é permitido |
---
# Consult transfers
URL: /en/documentation/baas/pix/consultar_transferencias
## Consult Pix Transaction by pix_transfer_key
### Request
ENDPOINT /account/ ACCOUNT_KEY /pix_transfer/ PIX_TRANSFER_KEY / PIX_TRANSFER_DIRECTION
METHOD GET
### Path Params
| Field | Type | Description | Characters |
|----------------------------|------------|--------------------------------------------------------------|----------------------------------------------------------------------|
| `pix_transfer_direction` * | enumerator | Indicator of the transaction direction (inbound or outbound).| [Enumerators pix_transfer_direction](#enumerators-pix_transfer_direction) |
| `account_key` * | uuidv4 | Unique identification key of the QI account. | 36 |
| `pix_transfer_key` * | uuidv4 | Unique identification key of the Pix transfer. | 36 |
### Enumerators pix_transfer_direction
| Enumerator | Description |
|--------------|--------------------------------|
| **incoming** | Inbound Pix transfer |
| **outgoing** | Outbound Pix transfer |
### Response
STATUS 201
Response Body: Transfer Sent (outgoing)
```json
{
"request_control_key": "6e290347-330d-4b3a-8ebb-2ac217ad6eb3",
"pix_message": "Good sunshine!",
"pix_transfer_type": "manual",
"account_key": "fc6862c4-2b20-4057-8063-b8809866e494",
"updated_at": "2021-10-22T20:30:23.459Z",
"created_at": "2021-10-22T20:30:23.459Z",
"target_account": {
"account_branch": "0001",
"account_digit": "3",
"account_number": "12345678",
"owner_document_number": "***02502000***",
"owner_person_type": "legal",
"owner_name": "Qi Tech",
"account_type": "checking_account",
"ispb": "32402502",
"financial_institution_name": "QI SCD",
"pix_key": null
},
"receiver_conciliation_id": null,
"pix_transfer_key": "8cb70dea-9fb0-4a68-9572-99a72849c8d6",
"end_to_end_id": "E3240250220211022203051750897529",
"pix_transfer_status": "sent",
"transfer_amount": 126.97,
"fee_amount": 0.0,
"rejection_reason": null,
"reversals": [
{
"end_to_end_id": "D35713491202309182058jlqdBkkHSWU",
"transfer_amount": 0.01,
"reversal_reason": "client_request",
"pix_transfer_status": "received",
"pix_transfer_key": "423866cd-0f3f-4cdd-904b-0d2e33273afd",
"request_control_key": "7c5a1425-73eb-420e-b4fb-0ce3386c7d0a",
"created_at": "2021-10-23T20:30.459Z"
}
]
}
```
Response Body: Transfer Rejected (outgoing)
```json
{
"request_control_key": "6e290347-330d-4b3a-8ebb-2ac217ad6eb3",
"pix_message": "Good morning!",
"pix_transfer_type": "manual",
"account_key": "fc6862c4-2b20-4057-8063-b8809866e494",
"updated_at": "2021-10-22T20:30:23.459Z",
"created_at": "2021-10-22T20:30:23.459Z",
"target_account": {
"account_branch": "0001",
"account_digit": "3",
"account_number": "12345678",
"owner_document_number": "***02502000***",
"owner_person_type": "legal",
"owner_name": "Qi Tech",
"account_type": "checking_account",
"ispb": "32402502",
"pix_key": null
},
"receiver_conciliation_id": null,
"pix_transfer_key": "8cb70dea-9fb0-4a68-9572-99a72849c8d6",
"end_to_end_id": "E3240250220211022203051750897529",
"pix_transfer_status": "rejected",
"transfer_amount": 126.97,
"fee_amount": 0.0,
"error_code": "PXT000132",
"error_description": "Target account number is invalid.",
"error_translation": "Número da conta de destino é inexistente ou inválido.",
"reversals": []
}
```
Response Body: Refund Sent (outgoing)
```json
{
"request_control_key": "6e290347-330d-4b3a-8ebb-2ac217ad6eb3",
"pix_message": "Good morning",
"pix_transfer_type": "reversal",
"account_key": "fc6862c4-2b20-4057-8063-b8809866e494",
"updated_at": "2021-10-22T20:30:23.459Z",
"created_at": "2021-10-22T20:30:23.459Z",
"target_account": {
"account_branch": "0001",
"account_digit": "3",
"account_number": "12345678",
"owner_document_number": "***02502000***",
"owner_person_type": "legal",
"owner_name": "Qi Tech",
"account_type": "checking_account",
"ispb": "32402502",
"pix_key": null
},
"receiver_conciliation_id": null,
"pix_transfer_key": "8cb70dea-9fb0-4a68-9572-99a72849c8d6",
"end_to_end_id": "E3240250220211022203051750897529",
"pix_transfer_status": "sent",
"transfer_amount": 126.97,
"fee_amount": 0.0,
"rejection_reason": null,
"reversals": [],
"original_incoming_pix_transfer": "6e290347-330d-4b3a-8ebb-2ac217ad6eb3"
}
```
Response Body: Transfer Received (incoming)
```json
{
"request_control_key": "6e290347-330d-4b3a-8ebb-2ac217ad6eb3",
"pix_transfer_key": "8cb70dea-9fb0-4a68-9572-99a72849c8d6",
"account_key": "fc6862c4-2b20-4057-8063-b8809866e494",
"end_to_end_id": "E18236120202308111235s14fddf2801",
"pix_transfer_status": "received",
"receiver_conciliation_id": "745c28c780bc4822bbade86dd875d10b",
"transfer_amount": 126.97,
"fee_amount": 0.0,
"source_account": {
"account_branch": "0001",
"account_digit": "3",
"account_number": "12345678",
"owner_document_number": "***02502000***",
"owner_person_type": "legal",
"owner_name": "Qi Tech",
"account_type": "checking_account",
"ispb": "32402502"
},
"pix_transfer_type": "dynamic_qr_code",
"reversals": []
}
```
Response Body: Refund Received (incoming)
```json
{
"request_control_key": "6e290347-330d-4b3a-8ebb-2ac217ad6eb3",
"pix_transfer_key": "8cb70dea-9fb0-4a68-9572-99a72849c8d6",
"account_key": "fc6862c4-2b20-4057-8063-b8809866e494",
"end_to_end_id": "E18236120202308111235s14fddf2801",
"pix_transfer_status": "received",
"receiver_conciliation_id": "745c28c780bc4822bbade86dd875d10b",
"transfer_amount": 126.97,
"fee_amount": 0.0,
"source_account": {
"account_branch": "0001",
"account_digit": "3",
"account_number": "12345678",
"owner_document_number": "***02502000***",
"owner_person_type": "legal",
"owner_name": "Qi Tech",
"account_type": "checking_account",
"ispb": "32402502"
},
"pix_transfer_type": "reversal",
"reversals": [],
"original_outgoing_pix_transfer": "6e290347-330d-4b3a-8ebb-2ac217ad6eb3"
}
```
Response Body: Transfer Rejected (incoming)
```json
{
"request_control_key": "6e290347-330d-4b3a-8ebb-2ac217ad6eb3",
"pix_transfer_key": "8cb70dea-9fb0-4a68-9572-99a72849c8d6",
"account_key": "fc6862c4-2b20-4057-8063-b8809866e494",
"end_to_end_id": "E18236120202308111235s14fddf2801",
"pix_transfer_status": "rejected",
"receiver_conciliation_id": "745c28c780bc4822bbade86dd875d10b",
"transfer_amount": 126.97,
"fee_amount": 0.0,
"source_account": {
"account_branch": "0001",
"account_digit": "3",
"account_number": "12345678",
"owner_document_number": "***02502000***",
"owner_person_type": "legal",
"owner_name": "Qi Tech",
"account_type": "checking_account",
"ispb": "32402502"
},
"pix_transfer_type": "dynamic_qr_code",
"reversals": []
}
```
STATUS 4xx
Response Body: Error
```json
{
"title": "title",
"description": "description in English",
"translation": "description in Portuguese",
"code": "code",
"extra_fields": {}
}
```
| HTTP Code | QI Code `code` | Title `title` | Description (eng) `Description` | Description (ptbr) `translation` |
|-------------|--------------------------------|-------------------------------------------|-----------------------------------------------------|--------------------------------------------------------------------------|
| 400 | PXT000075 | Pix Transfer Key or End To End Not Provided | No pix transfer key or end to end id provided. | Não foram fornecidos uma pix transfer key ou end to end id. |
| 404 | PXT000023 | Outgoing PIX Transfer Not Found | Pix transfer key \{pix_transfer_key\} was not found | Transferência PIX de saída com chave \{pix_transfer_key\} não foi encontrada. |
| 403 | PIT000001 | User is not allowed to do this transaction | User is not allowed to do this transaction | Usuário não tem autorização para fazer essa transação |
---
# Error Table for Pix Transfer
URL: /en/documentation/baas/pix/erros_de_pix
STATUS 4xx
Response Body: Error
```json
{
"title": "titulo",
"description": "description in English",
"translation": "descrição em portugues",
"code": "codigo",
"extra_fields": {}
}
```
| HTTP Status Code | Error Code | Title | Description | Translation |
|------------------|------------|-------------------------------------------------------------------------|------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|
| 500 | QIT000500 | Internal Error | An internal error has occurred and its being investigated | Um erro interno aconteceu e está sendo investigado |
| 404 | QIT000404 | Bad Request | The requested resource could not be found but may be available in the future. Subsequent requests by the client are permissible | O recurso solicitado não pôde ser encontrado, mas pode estar disponível no futuro. Requests subsequentes do cliente são permitidos |
| 400 | QIT000400 | Bad Request | The server cannot or will not process the request due to an apparent client error (e.g., malformed request syntax, size too large, invalid request message framing, or deceptive request routing) | O servidor não pode ou não processará a requisição devido a um erro do cliente (por exemplo, sintaxe de requisição malformada, tamanho muito grande, enquadramento de mensagem de requisição inválida ou roteamento de requisição enganoso) |
| 753 | QIT000753 | Syntax Error | Malformed JSON. Could not decode the request body. The JSON was incorrect, empty or not encoded as UTF-8 | JSON malformado. Não foi possível decodificar o corpo da requisição. O JSON estava incorreto, vazio ou não foi codificado como UTF-8 |
| 400 | QIT000001 | Bad Request | (custom) | Payload Inválido |
| 403 | QIT000002 | Permission Validator Error | Request must be internal | Request deve ser interna |
| 403 | QIT000003 | Permission Validator Error | Request must be from a master user | Request deve ser de usuário master |
| 403 | PIT000001 | User is not allowed to do this transaction | User is not allowed to do this transaction | Usuário não tem autorização para fazer essa transação |
| 400 | PIT000003 | Bad Request | Insufficient account balance for transfer and fee amount | Saldo de conta insuficiente para a transação e a taxa |
| 400 | PIT000004 | Bad Request | Transaction amount is over limit | O total da transação é superior ao limite |
| 404 | PIX000056 | Not Found | Pix key inquiry not found | Consulta de chave pix não encontrada |
| 400 | PXT000002 | Person is not Account Owner | Person \{person_key\} is not account owner | A pessoa \{person_key\} não é dona da conta |
| 400 | PXT000003 | Account is Closed | Account \{account_key\} is closed | Conta \{account_key\} está fechada |
| 404 | PXT000004 | Account not found | Account not found for: \{account_datum\} | Conta não encontrada para: \{account_datum\} |
| 404 | PXT000005 | Account not found | Account not found for pix key: \{pix_key\} | Conta não encontrada para chave pix: \{pix_key\} |
| 400 | PXT000006 | Account not found | Account was not provided for this query | Chave de identificação da conta não foi fornecida |
| 403 | PXT000008 | Invalid Permission | Person \{person_key\} does not have administration roles for account \{account_key\} | Pessoa \{person_key\} não tem permissões de administrador para a conta \{account_key\} |
| 404 | PXT000009 | Person Not Found | Person with document number \{person_document_number\} not found | Pessoa com número de documento \{person_document_number\} não encontrada |
| 400 | PXT000010 | Account is Blocked | Account \{account_key\} is blocked | Conta \{account_key\} está bloqueada |
| 400 | PXT000011 | Account Type Mismatch | Given account type does not match one registered | O tipo de conta fornecido não condiz com o registrado |
| 400 | PXT000012 | Invalid Document Number | Given \{document_number\} document number is invalid | CPF/CNPJ \{document_number\} fornecido não é válido |
| 400 | PXT000013 | Account Validation Failure | Account validation for received end_to_end_id is not valid | Validação da conta para o end_to_end_id recebido não é válida |
| 400 | PXT000014 | Target Account mismatch | Received target account data doesn't match validated account | Dados da conta de destino recebida não corresponde à conta validada |
| 400 | PXT000015 | Reversal date expired | Reversal original transaction is older than 90 days | A data de criação da transação original é mais antiga que 90 dias |
| 400 | PXT000016 | Reversal Account Flow Mismatch | Reversal account flow does not match original pix transfer's | O fluxo de contas de destino e de origem não correspondem ao da transação original |
| 400 | PXT000017 | Reversal Too Great | Reversal transfers sum amount surpasses that of original pix transfer | A soma das transações de devolução ultrapassam o valor da transação pix original |
| 404 | PXT000018 | Reversal Original Transfer not Found | Reversal original pix transfer not found | Transferência original da devolução não foi encontrada |
| 400 | PXT000019 | Chargeback Validation Failure | Previously done validation values do match with incoming chargeback | Os valores da atual devolução não correspondem com aqueles das validação |
| 404 | PXT000020 | Incoming PIX Validation Not Found | No previously done validation was found for given end to end id | Não se encontrou validação anterior para o id ponta-a-ponta provido |
| 400 | PXT000021 | Incoming Validation Already Done | There's an existing validation for end to end id \{end_to_end_id\} | A validação para o id ponta a ponta \{end_to_end_id\} já foi feita |
| 400 | PXT000022 | Wrong ISPB | ISPB is different from 32402502 | ISPB é diferente de 32402502 |
| 404 | PXT000023 | Outgoing PIX Transfer Not Found | Pix transfer key \{pix_transfer_key\} was not found | Transferência PIX de saída com chave \{pix_transfer_key\} não foi encontrada |
| 400 | PXT000024 | PIX Transfer Not Pending Confirmation | Pix transfer \{pix_transfer_key\} is not pending confirmation | Transferência PIX \{pix_transfer_key\} não está aguardando confirmação |
| 400 | PXT000025 | Invalid pix transfer key | Pix transfer \{pix_transfer_key\} is not pending confirmation or does not exist | Transferência PIX \{pix_transfer_key\} não está aguardando confirmação ou não existe |
| 400 | PXT000025 | Outgoing PIX Transfer Beyond of Transaction Limit | Pix transfer value R$ \{transfer_amount\} beyond of transaction limit R$ \{transaction_limit\} | Transferência PIX valor R$ \{transfer_amount\} além do limite R$ \{transaction_limit\} |
| 400 | PXT000026 | Search Params Error | Invalid integer value for page or size querystring parameters | Valor inválido para parâmetros de página ou tamanho de página |
| 403 | PXT000027 | Invalid Permission | Selected Person does not have administration roles | Pessoa selecionada não tem credencial de administrador |
| 400 | PXT000028 | Account Key can not be null when search for config fees | Account key can not be null when search for config fees | A chave de conta não pode ser nula quando buscar por configurações de tarifa |
| 400 | PXT000029 | Invalid Value for Enumerator Type | Invalid value \{value\} used for enumerator type \{enumerator\} | Valor inválido \{value\} para o tipo de enumerador \{enumerator\} |
| 400 | PXT000030 | To update or delete a fee configuration must be provided a valid fee ID | To update or delete a fee configuration must be provided a valid fee ID. ID provided: \{identification\} | Para atualizar ou remover uma configuração de tarifa deve ser fornecido um ID válido. ID fornecido: \{identification\} |
| 400 | PXT000031 | Fee configuration already exists | Fee configuration already exists for \{person_owner_type\} account with: purpose= \{purpose\} and \{transfer_type\}. Please use update | Configuração de tarifa já existe para conta \{person_owner_type\} com: finalidade= \{purpose\} e \{transfer_type\}. Por favor utilize o update |
| 400 | PXT000032 | Unable To Delete Default Configuration | Unable To Delete Default Configuration. Please use update | Não é permitido deletar uma configuração default. Por favor utilize o update |
| 400 | PXT000033 | Target Account Must Not Be Source Account | Target Account Must Not Be Source Account | A conta de destino não pode ser a conta de origem |
| 400 | PXT000034 | Account Key Must Not Be Null | You Need To Define An Account Key To Create A Fee Configuration | É necessário definir uma chave de conta para definir uma configuração de tarifa para a mesma |
| 400 | PXT000035 | Limit configuration already exists | Limit configuration already exists for \{account_key\} account for period(s) \{existing_limit_periods\}. Please use update | Configuração de limite já existe para conta \{account_key\} para o período(s) \{existing_limit_periods\}. Por favor utilize o update |
| 400 | PXT000036 | No limit configuration found. Please set default configurations | No limit configuration found. Please set default configurations for \{person_type\} person | Não foi possível encontrar configurações de limite, favor utilizar configurações padrões para \{person_type\} |
| 404 | PXT000037 | Person Not Found | Person with key \{person_key\} not found | Pessoa com chave \{person_key\} não encontrada |
| 400 | PXT000038 | Not enough balance | Not enough balance to pay for incoming pix fee | Saldo insuficiente para pagar por tarifa de pix de entrada |
| 400 | PXT000039 | Invalid Batch Limit Configuration | Received \{counter_config\} wrong configuration(s) for accounts: \{account_keys\}. Configurations must be None or positive float | Recebido \{counter_config\} configuração(ões) erradas para contas: \{account_keys\}. Configurações devem ser None ou float positivo |
| 400 | PXT000040 | Bad Request | Amount limit must be null, positive float or int. Sent \{limit\} | Limite deve ser nulo, positivo inteiro ou decimal. Sent \{limit\} |
| 404 | PXT000041 | Not Found | Qr Code not found | Qr Code não encontrado |
| 400 | PXT000042 | Bad Request | There is no ISPB number for this Bank Code | Não existe código ISPB para esse Bank Code |
| 400 | PXT000043 | Bad Request | Invalid decimal amount, sent \{number\} | Valor decimal inválido, enviado \{number\} |
| 404 | PXT000044 | Not Found | Pix Key \{pix_key\} is not activated | Chave PIX \{pix_key\} não está ativada |
| 404 | PXT000045 | Not Found | QR Code Payment is invalid for Receiver Conciliation ID \{receiver_conciliation_id\} | Pagamento via QR Code é inválido para Cliente Recebedor \{receiver_conciliation_id\} |
| 403 | PXT000046 | Invalid Permission | Only Master can change resource configuration | Apenas o Administrador pode alterar as configurações do recurso |
| 400 | PXT000047 | Bad Request | \{field_name\} could not be larger than \{max_length\} characters | \{field_name\} não pode ser maior que \{max_length\} caracteres |
| 400 | PXT000048 | Bad Request | Emoji not allowed in pix message | Emoji não é permitido na mensagem pix |
| 400 | PXT000049 | Bad Request | When paying QR Code end_to_end_id could not be none | Ao pagar um QR Code o end_to_end_id não pode ser nulo |
| 400 | PXT000050 | Bad Request | Could not read QR Code type, please try to read qr_code again | Não foi possível ler o tipo de QR Code. Favor tente ler o qr_code outra vez |
| 400 | PXT000051 | Invalid Requester Configuration Info | The configuration \{configuration\} format sent is not valid | O formato enviado da configuração \{configuration\} não é válido |
| 400 | PXT000052 | Bad Request | Only Master QI Tech can change default limits configurations | Apenas o Master QI Tech pode alterar as configurações de limites padrões |
| 400 | PXT000053 | Bad Request | QrCode already paid | Qr Code já Pago |
| 400 | PXT000054 | Bad Request | Invalid Pix Key, sent \{pix_key\} | Chave pix inválida, enviado \{pix_key\} |
| 400 | PXT000055 | Pix error | Invalid Limit Type Sent | Tipo inválido de limite enviado |
| 400 | PXT000056 | Bad Request | Only Master QI Tech can handle limit events | Apenas o Master QI Tech pode alterar eventos de limites |
| 400 | PXT000057 | Bad Request | Invalid request_key or no request found, request_key sent \{request_key\} | Requisição inválida ou requisição não encontrada, requisição enviada \{request_key\} |
| 400 | PXT000058 | Bad Request | When limit request is rejected, rejected reason could not be null | Quando uma requisição de limite é rejeitada, o motivo não pode ser nulo |
| 400 | PXT000059 | Bad Request | Target document number is not account owner document number | O documento informado não é o mesmo da conta de destino |
| 400 | PXT000060 | Bad Request | Nonexistent account in destination bank | Conta inexistente no banco de destino |
| 409 | PXT000061 | Conflict | End to end id invalid. A pix transfer with the end to end id \{end_to_end\} has already been registered! | End to end id inválido. Uma transação pix com o identificador único \{end_to_end\} já foi registrada! |
| 409 | PXT000062 | Conflict | Missing fields detected on jd connector response: \{response\} | Campos faltantes detectados em resposta do JD connector: \{response\} |
| 409 | PXT000063 | Conflict | Unexpected response: \{response\} | Resposta inesperada: \{response\} |
| 400 | PXT000064 | Bad Request | For Manual Pix Transfer Type a target account must be provided | Para transação pix do tipo manual, uma conta destino deve ser fornecida |
| 400 | PXT000065 | Bad Request | Pix transfer sent was already rejected. Rejection_reason: \{error_description\} | Pix transfer já rejeitada. Motivo da rejeição: \{error_description_translated\} |
| 404 | PXT000067 | Pix Key is Unregistered | Pix key \{pix_key\} is not currently used | A chave pix \{pix_key\} não está sendo utilizada |
| 422 | PXT000068 | Pix Key is Unregistered | Pix key inquiry timeout. Please try again | Consulta de chave pix excedeu o tempo limite. Por favor tente novamente |
| 400 | PXT000069 | Error in Qr Code Payload Request | An error occurred while requesting the qr code payload to the registry institution | Um erro ocorreu durante a requisição do payload do qr code para a instituição de registro |
| 400 | PXT000070 | Invalid Qr Code Format | The Qr Code format is invalid, please enter a valid Qr Code | O formato do Qr Code é inválido, por favor insira um Qr Code válido |
| 400 | PXT000071 | Invalid Qr Code Type | The Qr Code payload given did not provide a proper Qr Code type | O payload de QR Code fornecido não contêm um tipo de Qr Code Válido |
| 422 | PXT000072 | Pending Transfer | The transaction (\{end_to_end_id\}) could not be completed and is pending confirmation | Não foi possível concluir a transação (\{end_to_end_id\}) e ela está pendente de confirmação |
| 404 | PXT000073 | Outgoing PIX Transfer Not Found | Pix transfer end to end id \{end_to_end_id\} was not found | Transferência PIX de saída com identificador único \{end_to_end_id\} não foi encontrada |
| 400 | PXT000074 | Invalid Transaction Status | Unable to update transaction status. The status \{status\} is invalid | Não foi possível atualizar o status da transação. O status \{status\} é invalido |
| 400 | PXT000075 | Pix Transfer Key or End To End Not Provided | No pix transfer key or end to end id provided | Não foram fornecidos uma pix transfer key ou end to end id |
| 404 | PXT000076 | Incoming PIX Transfer Not Found | Pix transfer key \{pix_transfer_key\} was not found | Transferência PIX de entrada com chave \{pix_transfer_key\} não foi encontrada |
| 400 | PXT000077 | Pix Transfer Receipt not allowed | Pix Transfer Receipt cannot be generated for rejected transfers | Recibo de transação pix não pode ser gerado para transações rejeitadas |
| 400 | PXT000078 | Pix Transfer Receipt not available | Receipt not available due to pix transfer currently being processed. Wait a few minutes and try again | Comprovante não disponível pois transação Pix está em processamento. Por favor, aguarde alguns minutos e tente novamente |
| 400 | PXT000079 | Bad Request | Insufficient billing account balance for fee | Saldo de conta de cobrança insuficiente para a taxa |
| 400 | PXT000080 | Bad Request | Could not complete the transaction and the transaction was rejected | Não foi possível concluir a transação e a transferência foi rejeitada |
| 400 | PXT000081 | Bad Request | Pix key not sent | Chave PIX não enviada |
| 400 | PXT000082 | Bad Request | The sent PIX key \{pix_key\} does not match the decoded PIX key | A chave PIX enviada \{pix_key\} não coincide com a chave PIX decodificada |
| 400 | PXT000083 | Bad Request | Pix rejected. | Pix rejeitado. |
| 404 | PXT000084 | Original Pix Transfer Was Not Found | Original Pix Transfer Was Not Found | A transação PIX original não foi encontrada |
| 403 | PXT000085 | Invalid Permission | User do not has sufficient permissions | Usuário não tem permissões suficientes |
| 400 | PXT000086 | Update Default Failed | To update default requester configuration send default as requester_key in url | Para alterar a configuracao de requester padrao, envie default como requester_key na url |
| 400 | PXT000087 | Amount limit not approved try a lower value | Amount limit for \{person_type\} person not approved, please try a lower value | Limite total não aprovado para pessoa \{person_type\}, por favor tente um menor |
| 400 | PXT000088 | Bad Request | Invalid account information when translating to account DTO | Informações da conta inválidas na tradução do DTO |
| 409 | PXT000089 | Incoming Pix not pending | Incoming Pix with pix transfer key \{pix_transfer_key\} is not pending | Transferência de Entrada PIX \{pix_transfer_key\} não está pendente |
| 503 | PXT000090 | Service Unavailable | Pix transfer is not available right now. Please wait or use TED service | Transferência Pix não esta disponível no momento. Favor aguardar ou utilizar TED |
| 400 | PXT000091 | Bad Request | System account has no limits. Account key \{account_key\} is system account | Contas de sistema não possuem limite. Chave de conta \{account_key\} é conta de sistema |
| 422 | PXT000092 | Invalid Account Type | Pix is not yet implemented for non-checking or non-escrow account types | Transações Pix não estão implementadas para conta que não sejam escrow ou livres |
| 400 | PXT000093 | Bad Request | Fee must be either fixed_amount or percentage | Tarifas fixas e percentuais são mutuamente exclusivas |
| 400 | PXT000094 | Bad Request | Failed to fetch transactions by origin key | Falha ao obter transações por origin key |
| 400 | PXT000095 | Unforeseen Error Scenario on Reprocess | Scenario: pix_transfer_key: \{pix_transfer_key\}, pix_status: \{pix_status\}, bacen_status: \{bacen_status\}, internal_tx: \{internal_tx\}, reverse_tx
---
# List Transfers of an Account
URL: /en/documentation/baas/pix/listar_transferencias
## Request
ENDPOINT /account/ ACCOUNT_KEY /pix_transfers
METHOD GET
### Path Params
| Field | Type | Description | Characters |
|-----------------|--------|------------------------------------------|------------|
| `account_key` * | uuidv4 | Unique identification key of the QI account. | 36 |
### Query Params
| Field | Type | Description | Characters |
|-------------------------- |------------|--------------------------------------------------------------------------------------------------------------- |----------------------------------------------------------------------|
| `pix_transfer_direction` | enumerator | Indicator of the transaction direction (inbound or outbound). If not sent, **outgoing** will be considered | [Enumerators pix_transfer_direction](#enumeradores-pix_transfer_direction) |
| `request_control_key` | uuidv4 | Unique request identification key used by the client. | 36 |
| `end_to_end_id` | string | Idempotency key of a Pix transaction | 32 |
| `transaction_key` | uuidv4 | Identification key of the account movement | 36 |
| `date_from` | string | Start date. Format "YYYY-MM-DD" | |
| `date_to` | string | End date. Format "YYYY-MM-DD" | |
| `page` | integer | Requested page number. Default is 1 | |
| `page_size` | integer | Requested page size in the query. Default and maximum value is 30 | Maximum value of 30 |
### Enumerators pix_transfer_direction
| Enumerator | Description |
|--------------|--------------------------------|
| **incoming** | Inbound Pix transfer |
| **outgoing** | Outbound Pix transfer |
## Response
STATUS 201
Response Body
```json
{
"data": [
{
"request_control_key": "6e290347-330d-4b3a-8ebb-2ac217ad6eb3",
"pix_message": "Guten tag!",
"pix_transfer_type": "manual",
"account_key": "fc6862c4-2b20-4057-8063-b8809866e494",
"updated_at": "2021-10-22T20:30:23.459Z",
"created_at": "2021-10-22T20:30:23.459Z",
"target_account": {
"account_branch": "0001",
"account_digit": "3",
"account_number": "12345678",
"owner_document_number": "***02502000***",
"owner_person_type": "legal",
"owner_name": "Qi Tech",
"account_type": "checking_account",
"ispb": "32402502",
"financial_institution_name": "QI SCD",
"pix_key": null
},
"receiver_conciliation_id": null,
"pix_transfer_key": "8cb70dea-9fb0-4a68-9572-99a72849c8d6",
"end_to_end_id": "E3240250220211022203051750897529",
"pix_transfer_status": "sent",
"transfer_amount": 126.97,
"fee_amount": 0.0,
"rejection_reason": null,
"reversals": [
{
"end_to_end_id": "D35713491202309182058jlqdBkkHSWU",
"transfer_amount": 0.01,
"reversal_reason": "client_request",
"pix_transfer_status": "received",
"pix_transfer_key": "423866cd-0f3f-4cdd-904b-0d2e33273afd",
"request_control_key": "7c5a1425-73eb-420e-b4fb-0ce3386c7d0a",
"created_at": "2021-10-23T20:30.459Z"
}
]
}
],
"pagination": {
"current_page": 1,
"rows_per_page": 30
}
}
```
Response Body: Error
```json
{
"title": "title",
"description": "description in English",
"translation": "description in Portuguese",
"code": "code",
"extra_fields": {}
}
```
| HTTP Code | QI Code `code` | Title `title` | Description (eng) `Description` | Description (ptbr) `translation` |
|-------------|----------------------|-------------------------------------------|-----------------------------------------------------|--------------------------------------------------------------------------|
| 400 | PXT000075 | Pix Transfer Key or End To End Not Provided | No pix transfer key or end to end id provided. | Não foram fornecidos uma pix transfer key ou end to end id. |
| 404 | PXT000023 | Outgoing PIX Transfer Not Found | Pix transfer key \{pix_transfer_key\} was not found | Transferência PIX de saída com chave \{pix_transfer_key\} não foi encontrada. |
| 403 | PIT000001 | User is not allowed to do this transaction | User is not allowed to do this transaction | Usuário não tem autorização para fazer essa transação |
---
# Perform Pix Transaction
URL: /en/documentation/baas/pix/realizar_transferencia
## Request
ENDPOINT /account/ ACCOUNT_KEY /pix_transfer
METHOD POST
## Path Params
| Field | Type | Description | Characters |
|---------------|--------|-----------------------------------|------------|
| `account_key` | uuidv4 | Unique account identification key | 36 |
## Key Pix Transaction
Request Body: Transaction by Key Pix
```json
{
"request_control_key": "b6804f32-101e-4702-8fbc-c2dbc4c2caec",
"pix_transfer_type": "key",
"target_pix_key": "target_pix_key@email.com",
"transaction_amount": 500.65,
"end_to_end_id": "E73856642202309201429bZKfklNlbwu",
"pix_message": "Hello World"
}
```
### Body Params
| Field | Type | Description | Characters |
|-------------------------|------------|----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|------------|
| `request_control_key` * | uuidv4 | Unique identification key for the client request in uuid v4 format. | 36 |
| `pix_transfer_type` * | enumerator | Pix transfer type of the transaction to be performed. In case of a key transfer the value must be **key**. | "key" |
| `target_pix_key` * | string | Pix key of the target account. | 100 |
| `transaction_amount` * | number | Transaction amount. | 10 |
| `end_to_end_id` * | string | Idempotency key used by the SPI (Instantaneous Payment System). This must be the same as the one returned by pix key inquiry request. It is mandatory for `pix_transfer_type` **key**, **static_qr_code** or **dynamic_qr_code** | 32 |
| `pix_message` | string | Message sent with the Pix transaction. | 140 |
## Manual Pix Transaction
Request Body: Manual Pix Transaction
```json
{
"request_control_key": "b6804f32-101e-4702-8fbc-c2dbc4c2caec",
"pix_transfer_type": "manual",
"target_account": {
"account_branch": "0001",
"account_digit": "3",
"account_number": "12345678",
"owner_document_number": "32402502000135",
"owner_name": "Qi Tech",
"account_type": "checking_account",
"ispb": "32402502"
},
"transaction_amount": 500.65,
"pix_message": "Hello World"
}
```
### Body Params
| Field | Type | Description | Characters |
|-------------------------|------------|---------------------------------------------------------------------|-----------------------------------------------------|
| `request_control_key` * | uuidv4 | Unique identification key for the client request in uuid v4 format. | 36 |
| `pix_transfer_type` * | enumerator | Pix transfer type of the transaction to be performed. | **manual** |
| `target_account` * | Object | Must only be sent if `pix_transfer_type` is **manual**. | **[Object target_account](#objeto-target_account)** | 10 |
| `transaction_amount` * | number | Transaction amount. | 10 |
| `pix_message` | string | Message sent with the Pix transaction. | 140 |
### Object target_account
| Field | Type | Description | Characters |
|---------------------------|------------|------------------------------------------------|---------------------------------------------------------|
| `account_branch` * | string | Account agency number. | 6 |
| `account_digit` * | string | Account digit. | 1 |
| `account_number` * | string | Account number. | 20 |
| `owner_document_number` * | string | CPF or CNPJ (only numbers) from account owner. | 14 |
| `owner_name` * | string | Account owner name. | 150 |
| `account_type`* | enumerator | Account Type. | **[Enumerator account_type](#enumerador-account_type)** |
| `ispb` * | string | Financial institution identification code | 8 |
### Enumerator account_type
| Enumerador | Description |
|----------------------|------------------|
| **checking_account** | Checking Account |
| **salary_account** | Salary Account |
| **saving_account** | Saving Account |
| **payment_account** | Payment account |
## QR Code Pix Transaction
The data used to perform a payment transaction with a Pix QR Code must be obtained through
the [decoding of the Pix QR Code](/documentation/pix/decodificar_qr_code), using the Pix Copy and Paste URI.
The `end_to_end_id` field must be the same value returned from the decoding of the Dynamic QR Code.
Insert to the `transaction_amount` field the same value returned in the `qr_code_data.amount` field from the
decoding of the Dynamic QR Code.
Change the `pix_transfer_type` field to **dynamic_term** for the payment request.
The `receiver_conciliation_id` field must be the same value returned from the decoding of the Dynamic QR Code.
Request Body: Qr Code Pix Transaction
```json
{
"request_control_key": "b6804f32-101e-4702-8fbc-c2dbc4c2caec",
"pix_transfer_type": "static_qr_code",
"transaction_amount": 500.65,
"end_to_end_id": "E73856642202309201429bZKfklNlbwu",
"receiver_conciliation_id": "REC00000000000000000000009459463343",
"target_pix_key": "target_pix_key@email.com",
"pix_message": "Hello World"
}
```
### Body Params
| Field | Type | Description | Characters |
|----------------------------|------------|------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|-------------------------------------------|
| `request_control_key` * | uuidv4 | Unique identification key for the client request in uuid v4 format. | 36 |
| `pix_transfer_type` * | enumerator | Pix transfer type of the transaction to be performed. | **static_qr_code** ou **dynamic_qr_code** |
| `target_pix_key` * | string | Targets pix key. | 100 |
| `receiver_conciliation_id` | string | Conciliation Identification code for receiver. | 35 |
| `transaction_amount` * | number | Transaction amount. | 10 |
| `end_to_end_id` * | string | Idempotency key used by the SPI (Instantaneous Payment System). This must be the same as the one returned by [pix key inquiry request](/documentation/pix/consultar_chave). It is mandatory for `pix_transfer_type` **key**, **static_qr_code** or **dynamic_qr_code** | 32 |
| `pix_message` | string | Message sent with the Pix transaction. | 140 |
:::danger Aviso
The `end_to_end_id` must be from an inquiry which has been done by the account to execute the transfer!
:::
:::danger Aviso
The `end_to_end_id` can only be used for a single transfer, whether successful or not.
:::
## Response
STATUS 201
Response Body: Transfer Sent
```json
{
"request_control_key": "b6804f32-101e-4702-8fbc-c2dbc4c2caec",
"pix_transfer_key": "8cb70dea-9fb0-4a68-9572-99a72849c8d6",
"pix_transfer_status": "sent",
"created_at": "2021-10-22T20:30:23.459Z"
}
```
STATUS 202
Response Body: Transfer Pending
```json
{
"request_control_key": "b6804f32-101e-4702-8fbc-c2dbc4c2caec",
"pix_transfer_key": "8cb70dea-9fb0-4a68-9572-99a72849c8d6",
"pix_transfer_status": "pending",
"created_at": "2021-10-22T20:30:23.459Z"
}
```
:::info Information
If **HTTP Status 202** is returned with **pending** as the value for the field `pix_transfer_status`, the Pix
Transaction must not be attempted again. A Webhook will be sent as soon as the transaction reaches its final status.
Alternatively, it is possible to verify the transfer status using [Pix Transaction Inquiry](#consultar-transação-pix).
:::
STATUS 4xx
Response Body: Transfer Rejected
```json
{
"title": "title",
"description": "description in English",
"translation": "descrição em portugues",
"code": "code",
"extra_fields": {
"pix_transfer_data": {
"request_control_key": "b6804f32-101e-4702-8fbc-c2dbc4c2caec",
"pix_transfer_key": "8cb70dea-9fb0-4a68-9572-99a72849c8d6",
"pix_transfer_status": "rejected",
"created_at": "2021-10-22T20:30:23.459Z"
}
}
}
```
STATUS 4xx
Response Body: Error
```json
{
"title": "titulo",
"description": "description in English",
"translation": "descrição em portugues",
"code": "codigo",
"extra_fields": {}
}
```
| HTTP Status `status` | Code QI `code` | Tittle `title` | Description (eng) `description` | Description (ptbr) `translation` |
|--------------------------|----------------------|----------------------------------------------------|-------------------------------------------------------------------------------------------------------------------------|------------------------------------------------------------------------------------------------------------------------|
| 400 | QIT000001 | Bad Request | Schema Error | Erro de Schema |
| 406 | PXT000103 | request_control_key must be a valid uuid v4 string | request_control_key was not accepted for not being a valid uuid v4 string | request_control_key não foi aceito por não ser uma palavra uuid v4 válida |
| 400 | PXT000048 | Bad Request | Emoji not allowed in pix message. | Emoji não é permitido na mensagem pix. |
| 400 | PXT000104 | Invalid Transaction Amount | Transaction amount of \{transaction_amount\} is not valid. It must be a positive value with at maximum 2 decimal places | O valor de transação \{transaction_amount\} não é válido. Deve ser um valor positivo com no máximo duas casas decimais |
| 404 | PXT000004 | Account not found | Account not found for: \{account_datum\} | Conta não encontrada para: \{account_datum\} |
| 400 | PXT000003 | Account is Closed | Account \{account_key\} is closed. | Conta \{account_key\} está fechada. |
| 422 | PXT000092 | Invalid Account Type | Pix is not yet implemented for non-checking or non-escrow account types | Transações Pix não estão implementadas para conta que não sejam escrow ou livres |
| 403 | PIT000001 | User is not allowed to do this transaction | | Usuário não tem autorização para fazer essa transação |
| 400 | PXT000010 | Account is Blocked | Account \{account_key\} is blocked. | Conta \{account_key\} está bloqueada. |
| 400 | PXT000003 | Account is Closed | Account \{account_key\} is closed. | Conta \{account_key\} está fechada. |
| 400 | PIT000003 | Bad Request | Insufficient account balance for transfer and fee amount. | Saldo de conta insuficiente para a transferência e a taxa. |
| 400 | PXT000118 | Requester is not Pix Participant | The requester sent an alias key but is not a indirect pix participant | O requisitante enviou uma alias key no entanto não é um participante do pix indireto |
| 404 | PXT000120 | Alias sent not found | Alias key attached to this account not found | Alias key vinculada à conta não encontrada |
| 406 | PXT000105 | Invalid end_to_end_id | The end_to_end_id sent \{end_to_end_id\} is not valid. | O end_to_end_id enviado \{end_to_end_id\} não é válido. |
| 400 | PXT000108 | Bad Request | Billing account closed or blocked | Conta de cobrança encerrada ou bloqueada |
| 400 | PXT000079 | Bad Request | Insufficient billing account balance for fee. | Saldo de conta de cobrança insuficiente para a taxa. |
| 400 | PIT000004 | Bad Request | Transaction amount is over limit. | O total da transferência é superior ao limite. |
| 404 | PIX000056 | Not Found | Pix key inquiry not found | Consulta de chave pix não encontrada |
| 404 | PXT000041 | Not Found | Qr Code not found | Qr Code não encontrado |
| 400 | PXT000053 | Bad Request | QrCode already paid | Qr Code já Pago |
| 400 | PXT000118 | Requester is not Pix Participant | The requester sent an alias key but is not a indirect pix participant | O requisitante enviou uma alias key no entanto não é um participante do pix indireto |
| 404 | PXT000120 | Alias sent not found | Alias key attached to this account not found | Alias key vinculada à conta não encontrada |
| 400 | PXT000115 | Bad Request | Insufficient account balance for transfer and fee amount. | Saldo de conta insuficiente para a transferência e a taxa |
| 400 | PXT000128 | Bad Request | Pix key \{pix_key\} sent does match inquiry pix key. Verify if end_to_end_id sent is correct | Chave Pix \{pix_key\} enviada não condiz com consulta. Verifique se end_to_end_id enviado está correto |
| 400 | PXT000109 | Bad Request | request_control_key \{request_control_key\} already in use | request_control_key \{request_control_key\} já utilizada |
| 400 | PXT000061 | Bad Request | End to end id invalid. A pix transfer with the end to end id \{end_to_end\} has already been registered! | End to end id inválido. Uma transação pix com o identificador único \{end_to_end\} já foi registrada! |
| 400 | PXT000129 | SPI Error message | Message rejected by SPI-ICOM | Mensagem rejeitada pela SPI-ICOM |
| 408 | PXT000130 | SPI Timeout Control | SPI Timeout Control | Controle de timeout no SPI |
| 400 | PXT000131 | Receiver Internal Error | Cancelled transaction due to receiver's internal error | Transação interrompida devido a erro no PSP do Recebedor |
| 400 | PXT000132 | Invalid Target Account Number | Target account number is invalid | Número da conta de destino é inexistente ou inválido |
| 400 | PXT000133 | Blocked Target Account | Target account is blocked. | A conta de destino encontra-se bloqueada. |
| 400 | PXT000134 | Closed Target Account | Target account is closed. | A conta de destino encontra-se encerrada. |
| 400 | PXT000135 | Unsupported Transaction | Unsupported transaction for given target account. | A conta de destino não suporta este tipo de transação. |
| 400 | PXT000136 | Invalid Participant | SPI participant is not PSP settler agent of payer nor receiver. | Participante direto do SPI não é liquidante do PSP do Pagador / Recebedor. |
| 400 | PXT000137 | Zero Value Payment Order | Zero value payment order. | Ordem de pagamento com valor zero. |
| 400 | PXT000138 | Insufficient Funds | Insufficient funds in PI account from payer. | Saldo insuficiente na conta PI do pagador. |
| 400 | PXT000139 | Return Value Too Great | Return value greater than corresponding payment order. | Valor de devolução acima do valor de pagamento correspondente. |
| 400 | PXT000140 | Invalid Transactions Number | Invalid transactions number. | Quantidade de transações inválida. |
| 400 | PXT000141 | Unrelated Beneficiary Document Number | Beneficiary document number is not that of target account owner. | CPF/CNPJ do usuário recebedor não é compatível com o titular da conta de destino. |
| 400 | PXT000142 | Invalid Beneficiary Document Number | Invalid beneficiary document number | CPF/CNPJ da conta de destino está incorreto. |
| 400 | PXT000143 | Incorrect Message Element | Incorrect message element. | Elemento da mensagem incorreto. |
| 403 | PXT000144 | Rejected Payment Order | Beneficiary's PSP has rejected payment order. | Ordem de pagamento foi rejeitada pelo banco recebedor. |
| 403 | PXT000145 | Unauthorized Payer | Signing participant is unauthorized to make a payment order for paying account. | Participante que assinou a mensagem não é autorizado a realizar a operação na conta PI debitada. |
| 400 | PXT000146 | Invalid Datetime | Invalid datetime for message delivery. | Data e Hora do envio da mensagem inválida. |
| 400 | PXT000147 | Generic Error | Error while processing payment (generic error). | Erro no processamento do pagamento (erro genérico). |
| 400 | PXT000148 | Bad Format Operation Identifier | Badly formatted operation's identifier. | Identificador da operação mal formatado. |
| 400 | PXT000149 | Invalid Payer ISPB | Invalid or non-existent payer's PSP ISPB number. | Número ISPB do PSP do Pagador é inválido ou inexistente. |
| 400 | PXT000150 | Invalid Beneficiary ISPB | Invalid or non-existent beneficiary's PSP ISPB number. | Número ISPB do banco recebedor é inválido ou inexistente. |
| 400 | PXT000151 | Incorrect Type | Incorrect type for target account. | Type incorreto para a conta transacional especificada. |
| 400 | PXT000152 | Repeated End-to-End ID Error | The end_to_end_id was already used | O end_to_end_id já foi utilizado |
| 400 | PXT000153 | Invalid Target Account Type | The target account type cannot receive PIX transactions | O tipo de conta destino não pode receber transações PIX |
| 400 | PXT000154 | Invalid ISPB | Invalid or non-existent ISPB number. | Número ISPB é inválido ou inexistente. |
| 400 | PXT000155 | Amount too Great | Amount too great for credited account. | Valor de pagamento/devolução acima do permitido para a conta de destino creditada. |
| 400 | PXT000156 | QR Code Rejected | QR Code rejected by beneficiary's PSP. | QR Code rejeitado pelo PSP do usuário recebedor. |
| 503 | PXT000157 | Bacen Service Unavailable Error | Could not send the message to ICOM after 3 retries | Não pode enviar a mensagem para a ICOM depois de 3 tentativas |
| 400 | PXT000158 | Invalid Amount | Paid amount diverges from expected amount of \{expected_amount\} | O valor do pagamento diverge do valor esperado de \{expected_amount\} |
| 400 | PXT000159 | QR code inactive | QR code is not active at the time of payment | QR code não está ativo no instante do pagamento|
---
# Request a refund for a received Pix
URL: /en/documentation/baas/pix/solicitar_devolucao
A refund for a Pix can be processed up to 90 days from its receipt.
## Request
ENDPOINT /account/ ACCOUNT_KEY /pix_transfer/ PIX_TRANSFER_KEY /reversal
METHOD POST
### Path Params
| Field | Type | Description | Characters |
|-------------------|--------|---------------------------------------------------------|------------|
| `account_key` * | uuidv4 | Unique identification key of the account. | 36 |
| `pix_transfer_key` * | uuidv4 | Unique identification key of the Pix transfer in the QI system. | 36 |
Request Body
```json
{
"request_control_key": "303393bf-8f2e-4ff0-b326-ee7ad612e8ca",
"reversal_amount": 147,
"reversal_reason": "client_request",
"reversal_message": "Refund Pix message"
}
```
### Request Body
| Field | Type | Description | Characters |
|-------------------------|--------|------------------------------------|-------------------------------------------------|
| `request_control_key` * | uuidv4 | Uniqueness key for the request. | 36 |
| `reversal_amount` * | number | Refund amount. | 11 |
| `reversal_reason` * | string | Reason for the refund. | **[Enumerator reversal_reason](#enumerator-reversal_reason)** |
| `reversal_message` | string | Refund message. | 140 |
### Enumerator reversal_reason
| Enumerator | Description |
|---------------------|-------------------------------------------------|
| **client_request** | When requested by the account owner. |
| **reconciliation** | For reconciliation due to operational error. |
## Response
STATUS 201
Response Body: Refund Sent
```json
{
"reversal_status": "sent",
"transaction_amount": 147,
"pix_transfer_key": "cdcf0d25-08a1-46e3-902a-6d7ca75e6c48",
"end_to_end_id": "E32402502202405081755SxyT2DDcVwc",
"request_control_key": "7c5a1425-73eb-420e-b4fb-0ce3386c7d0c",
"created_at": "2021-10-22T20:30:23.459Z"
}
```
STATUS 202
Response Body: Refund Pending
```json
{
"reversal_status": "pending",
"transaction_amount": 147,
"pix_transfer_key": "cdcf0d25-08a1-46e3-902a-6d7ca75e6c48",
"end_to_end_id": "E32402502202407112211Id9JbxoaiTf",
"request_control_key": "7c5a1425-73eb-420e-b4fb-0ce3386c7d0c",
"created_at": "2021-10-22T20:30:23.459Z"
}
```
:::info Information
If **HTTP Status 202** is returned with the `pix_transfer_status` field having the value **pending**, the Pix request should not be retried.
This transfer will be reprocessed. The transfer status needs to be checked through the [Pix Transfer Status Query](#consultar-transacao-pix).
:::
### Response Body
| Field | Type | Description | Characters |
|----------------------|------------|--------------------------------------------------------------|-------------------------------------------------|
| `reversal_status` | enumerator | Enumerator of the refund transaction status. | [Enumerator reversal_status](#enumerator-reversal_status) |
| `transfer_amount` | number | Refund transfer amount. | 11 |
| `pix_transfer_key` | uuidv4 | Key of the executed Pix refund transaction. | 36 |
| `end_to_end_id` | string | Idempotency key of a Pix transaction within the SPI (Instant Payment System) | 32 |
| `request_control_key`| uuidv4 | Unique identification key of the request used by the client. | 36 |
| `created_at` | string | Date and time of the refund. | 10 |
### Enumerator reversal_status
| Enumerator | Description |
|--------------|----------------------------------------------|
| **sent** | Pix transfer successfully completed. |
| **pending** | Pix transfer pending. |
| **rejected** | Pix transfer rejected. |
STATUS 4xx
Response Body: Refund Rejected
```json
{
"title": "title",
"description": "description in English",
"translation": "description in Portuguese",
"code": "code",
"extra_fields": {
"pix_transfer_data": {
"request_control_key": "b6804f32-101e-4702-8fbc-c2dbc4c2caec",
"pix_transfer_key": "8cb70dea-9fb0-4a68-9572-99a72849c8d6",
"end_to_end_id": "E32402502202407112211Id9JbxoaiTf",
"pix_transfer_status": "rejected",
"created_at": "2021-10-22T20:30:23.459Z"
}
}
}
```
:::info Information
In addition to the errors previously listed for [Pix transfer](/documentation/baas_v2/pix/realizar_transferencia), the refund of a Pix can also return the errors listed below.
:::
| HTTP Code `status` | QI Code `code` | Title `title` | Description (eng) `description` | Description (ptbr) `translation` |
|--------------------------|---------------------- |-------------------------------------- |------------------------------------------------------------------------|---------------------------------------------------------------------------------------------|
| 400 | QIT000001 | Bad Request | Schema Error | Erro de Schema |
| 404 | PXT000018 | Reversal Original Transfer not Found | Reversal original pix transfer not found. | Transferência original da devolução não foi encontrada. |
| 400 | PXT000017 | Reversal Too Great | Reversal transfers sum amount surpasses that of original pix transfer. | A soma das transferências de devolução ultrapassam o valor da transferência pix original. |
| 400 | PXT000015 | Reversal date expired | Reversal original transaction is older than 90 days | A data de criação da transação original é mais antiga que 90 dias |
| 400 | PXT0000127 | Invalid Reversal Reason | Reversal reason \{reversal_reason\} is not valid | Razão de reversão \{reversal_reason\} não é válida |
---
# Webhooks
URL: /en/documentation/baas/pix/webhooks
Since transfers occur asynchronously, it is highly important to correctly map and handle the webhooks sent.
:::danger Attention!
QI Tech webhooks should not be mapped restrictively.
Additional fields may be included in the webhook payloads returned from our APIs.
:::
## Webhook for Pending Transactions
Webhook intended to update the status of transfers that remained pending (status 202) in the [Pix transfer request](/documentation/baas_v2/pix/realizar_transferencia).
### Webhook Request Body
Request Body: Transaction Sent
```json
{
"webhook_type": "baas.pix_transfer.outgoing_pix",
"webhook_datetime": "2021-10-22T20:30:23.459Z",
"data": {
"request_control_key": "b6804f32-101e-4702-8fbc-c2dbc4c2caec",
"pix_transfer_key": "8cb70dea-9fb0-4a68-9572-99a72849c8d6",
"pix_transfer_status": "sent",
"created_at": "2021-10-22T20:30:23.459Z"
}
}
```
Request Body: Transaction Rejected
```json
{
"webhook_type": "baas.pix_transfer.outgoing_pix",
"webhook_datetime": "2021-10-22T20:30:23.459Z",
"data": {
"request_control_key": "b6804f32-101e-4702-8fbc-c2dbc4c2caec",
"pix_transfer_key": "8cb70dea-9fb0-4a68-9572-99a72849c8d6",
"pix_transfer_status": "rejected",
"created_at": "2021-10-22T20:30:23.459Z",
"error_code": "PXT000132",
"error_description": "Target account number is invalid.",
"error_translation": "Número da conta de destino é inexistente ou inválido.",
"error_short_description": null
}
}
```
### Webhook Body Param
| Field | Type | Description | Max. Characters |
|-----------------------|--------|---------------------------------------------------------|-----------------|
| `webhook_type` | string | An enumerator that defines the type of event being reported | 23 |
| `webhook_datetime` | string | Date and time the webhook was sent | 20 |
| `request_control_key` | string | UUID4 for query purposes about the request made. | 36 |
| `pix_transfer_key` | string | Identification key of the Pix transfer in the QI system | 36 |
| `pix_transfer_status` | string | Transaction status | 200 |
| `created_at` | string | Date and time the transaction was created | 20 |
[//]: # (Break here for new page -----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------)
## Webhook for incoming Pix
A webhook that will notify about Pix transactions that have arrived in an account.
### Webhook Request Body
Request Body: Pix Received
```json
{
"webhook_type": "baas.pix_transfer.incoming_pix",
"webhook_datetime": "2021-10-22T20:30:23.459Z",
"data": {
"pix_transfer_key": "8cb70dea-9fb0-4a68-9572-99a72849c8d6",
"end_to_end_id": "E18236120202308111235s14fddf2801",
"pix_transfer_status": "received",
"account_key": "7c5a1425-73eb-420e-b4fb-0ce3386c7d0c",
"receiver_conciliation_id": "745c28c780bc4822bbade86dd875d10b",
"transfer_amount": 126.97,
"fee_amount": 0.0,
"source_account": {
"account_branch": "0001",
"account_digit": "3",
"account_number": "12345678",
"owner_document_number": "***02502000***",
"owner_person_type": "legal",
"owner_name": "Qi Tech",
"account_type": "checking_account",
"ispb": "32402502"
},
"pix_transfer_type": "dynamic_qr_code",
"pix_message": "pix message received",
"created_at": "2021-10-22T20:30:23.459Z",
"reversals": []
}
}
```
### Webhook Body Param
| Field | Type | Description | Max. Characters |
|---------------------------|------------|-----------------------------------------------------------------------------|--------------------------------------------|
| `webhook_type` | string | An enumerator that defines the type of event being reported | 23 |
| `webhook_datetime` | string | Date and time the webhook was sent | 20 |
| `pix_transfer_type` | enumerator | Type of pix performed | **[Enumerator pix_transfer_type](#enumerator-pix_transfer_type)** |
| `target_pix_key` | string | Pix key of the account to which the transaction will be sent | 100 |
| `source_account` | Object | Destination account - Should only be sent in transactions of type "manual" | **[Object source_account](#object-source_account)** |
| `transfer_amount` | number | Transfer amount | 10 |
| `receiver_conciliation_id`| string | Receiver's conciliation identification | 35 |
| `end_to_end_id` | string | Idempotency key of a Pix transaction - should only be sent if the transfer type is "key" | 32 |
| `pix_message` | string | Message to be sent along with the Pix transfer | 140 |
| `fee_amount` | number | Transfer amount | 10 |
| `pix_transfer_status` | string | Pix transaction status | 10 |
| `account_key` | string | Unique identification key of the QI account | 36 |
| `pix_transfer_key` | string | Unique identification key of the Pix transfer | 36 |
### Enumerator pix_transfer_type
| Enumerator | Description |
|----------------------|---------------------------------------------|
| **manual** | Pix using the destination account details |
| **key** | Pix using a pix key |
| **static_qr_code** | Pix using a static QR code |
| **dynamic_qr_code** | Pix using a dynamic QR code |
| **reversal** | Pix refund |
### Object source_account
| Field | Type | Description | Characters |
|--------------------------|------------|-------------------------------------------------------------------|---------------------------------------------|
| `account_branch` * | string | Branch of the account | 6 |
| `account_digit` * | string | Account digit | 1 |
| `account_number` * | string | Account number | 20 |
| `owner_document_number` *| string | CPF or CNPJ (numbers only) of the account holder | 14 |
| `owner_name` | string | Name of the account holder | 150 |
| `account_type` * | enumerator | Type of account | **[Enumerator account_type](#enumerator-account_type)** |
| `ispb` * | string | Eight-digit code that identifies banks in the Central Bank's reserve transfer system | 8 |
### Enumerator account_type
| Enumerator | Description |
|-----------------------|---------------------|
| **checking_account** | Conta Corrente |
| **salary_account** | Conta Salário |
| **saving_account** | Conta Poupança |
| **payment_account** | Conta de Pagamentos|
[//]: # (Break here for new page -----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------)
## Webhook for Pix Refunds
A webhook that will notify about Pix refunds that have arrived in an account.
### Webhook Request Body
Request Body: Pix Received
```json
{
"webhook_type": "baas.pix_transfer.incoming_pix",
"webhook_datetime": "2021-10-22T20:30:23.459Z",
"data": {
"pix_transfer_key": "8cb70dea-9fb0-4a68-9572-99a72849c8d6",
"end_to_end_id": "E18236120202308111235s14fddf2801",
"pix_transfer_status": "received",
"account_key": "7c5a1425-73eb-420e-b4fb-0ce3386c7d0c",
"receiver_conciliation_id": "745c28c780bc4822bbade86dd875d10b",
"transfer_amount": 126.97,
"fee_amount": 0.0,
"source_account": {
"account_branch": "0001",
"account_digit": "3",
"account_number": "12345678",
"owner_document_number": "***02502000***",
"owner_person_type": "legal",
"owner_name": "Qi Tech",
"account_type": "checking_account",
"ispb": "32402502"
},
"pix_transfer_type": "reversal",
"pix_message": "pix message received",
"created_at": "2021-10-22T20:30:23.459Z",
"reversals": [],
"original_outgoing_pix_transfer": "b56862c4-2b20-4057-8063-b8809866e494"
}
}
```
### Webhook Body Param
| Field | Type | Description | Max. Characters |
|--------------------------------|------------|------------------------------------------------------------------------------------- |--------------------------------------------|
| `webhook_type` | string | An enumerator that defines the type of event being reported | 23 |
| `webhook_datetime` | string | Date and time the webhook was sent | 20 |
| `pix_transfer_type` | enumerator | Type of pix performed | **[Enumerator pix_transfer_type](#enumerator-pix_transfer_type)** |
| `target_pix_key` | string | Pix key of the account to which the transaction will be sent | 100 |
| `source_account` | Object | Destination account - Should only be sent in transactions of type "manual" | **[Object source_account](#object-source_account)** |
| `transfer_amount` | number | Transfer amount | 10 |
| `receiver_conciliation_id` | string | Receiver's conciliation identification | 35 |
| `end_to_end_id` | string | Idempotency key of a Pix transaction - should only be sent if the transfer type is "key" | 32 |
| `pix_message` | string | Message to be sent along with the Pix transfer | 140 |
| `fee_amount` | number | Transfer amount | 10 |
| `pix_transfer_status` | string | Pix transaction status | 10 |
| `account_key` | string | Unique identification key of the QI account | 36 |
| `pix_transfer_key` | string | Unique identification key of the Pix transfer | 36 |
| `original_outgoing_pix_transfer` | string | Unique identification key of the original outbound Pix transfer | 36 |
### Enumerator pix_transfer_type
| Enumerator | Description |
|----------------------|---------------------------------------------|
| **manual** | Pix using the destination account details |
| **key** | Pix using a pix key |
| **static_qr_code** | Pix using a static QR code |
| **dynamic_qr_code** | Pix using a dynamic QR code |
| **reversal** | Pix refund |
### Object source_account
| Field | Type | Description | Characters |
|--------------------------|------------|----------------------------------------------------------------|---------------------------------------------|
| `account_branch` | string | Branch of the account | 6 |
| `account_digit` | string | Account digit | 1 |
| `account_number` | string | Account number | 20 |
| `owner_document_number` | string | CPF or CNPJ (numbers only) of the account holder | 14 |
| `owner_name` | string | Name of the account holder | 150 |
| `account_type` | enumerator | Type of account | **[Enumerator account_type](#enumerator-account_type)** |
| `ispb` | string | Eight-digit code that identifies banks in the Central Bank's reserve transfer system | 8 |
### Enumerator account_type
| Enumerator | Description |
|-----------------------|---------------------|
| **checking_account** | Conta Corrente |
| **salary_account** | Conta Salário |
| **saving_account** | Conta Poupança |
| **payment_account** | Conta de Pagamentos|
---
# baas_configurando_webhooks
URL: /en/documentation/baas/primeiros_passos/baas_configurando_webhooks
---
# Configurar IP de Integração
URL: /en/documentation/baas/primeiros_passos/baas_configurar_ip_de_integracao
---
# baas_inicio
URL: /en/documentation/baas/primeiros_passos/baas_inicio
---
# baas_troca_de_chaves
URL: /en/documentation/baas/primeiros_passos/baas_troca_de_chaves
---
# baas_endpoints_de_teste
URL: /en/documentation/baas/primeiros_passos/teste_de_autenticacao/baas_endpoints_de_teste
---
# baas_possiveis_erros
URL: /en/documentation/baas/primeiros_passos/teste_de_autenticacao/baas_possiveis_erros
---
# baas_teste_de_autenticacao_completo
URL: /en/documentation/baas/primeiros_passos/teste_de_autenticacao/baas_teste_de_autenticacao_completo
---
# baas_teste_de_autenticacao_v2
URL: /en/documentation/baas/primeiros_passos/teste_de_autenticacao/baas_teste_de_autenticacao_v2
---
# baas_webhook_v2
URL: /en/documentation/baas/primeiros_passos/teste_de_autenticacao/baas_webhook_v2
---
# Approve TED with Two-Factor Authentication
URL: /en/documentation/baas/ted/2fa/aprovar_transacao_ted_2fa
## Request
ENDPOINT /account/ ACCOUNT_KEY /ted/ TED_KEY /validate_token
METHOD PUT
### Path Params
| Field | Type | Description | Characters |
|---------------|--------|-----------------------------------------------|------------|
| `account_key` | uuidv4 | Unique account identification key. | 36 |
| `ted_key` | uuidv4 | Unique TED transfer identification key | 36 |
## Email and SMS Authentication
Request Body
```json
{
"token": "329123"
}
```
## Device Authentication
To approve and finalize device authentication, the request must be sent with an empty payload. Validation occurs internally, without the need for additional information in the request body. It's important to note that this endpoint should only be used after the [transaction request](./realizar_transferencia_2fa.md) has been initiated.
Request Body
```json
{
}
```
## Body Params
| Field | Type | Description | Characters |
|-----------|--------|-----------------------------------------------------------------------|------------|
| `token` | string | Authentication code sent to the account movement approver **mandatory for TFA via SMS or email**| 6 |
## Response
STATUS 201
Response Body: Transfer Sent
```json
{
"request_control_key": "b6804f32-101e-4702-8fbc-c2dbc4c2caec",
"transaction_key": "46804f32-101e-4702-8fbc-c2dbc4c2caec",
"ted_key": "8cb70dea-9fb0-4a68-9572-99a72849c8d6",
"transaction_amount": 202.01,
"fee_amount": 10,
"ted_status": "sent",
"created_at": "2021-10-22T20:30:23.459Z"
}
```
STATUS 202
Response Body: Pending Transfer
```json
{
"request_control_key": "b6804f32-101e-4702-8fbc-c2dbc4c2caec",
"ted_key": "8cb70dea-9fb0-4a68-9572-99a72849c8d6",
"transaction_amount": 202.01,
"fee_amount": 10,
"ted_status": "pending",
"created_at": "2021-10-22T20:30:23.459Z"
}
```
STATUS 4xx
Response Body: Transfer Rejected
```json
{
"title": "titulo",
"description": "description in English",
"translation": "descrição em portugues",
"code": "codigo",
"extra_fields": {
"ted_data": {
"request_control_key": "b6804f32-101e-4702-8fbc-c2dbc4c2caec",
"ted_key": "8cb70dea-9fb0-4a68-9572-99a72849c8d6",
"transaction_amount": 202.01,
"fee_amount": 10,
"ted_status": "rejected",
"created_at": "2021-10-22T20:30:23.459Z"
}
}
}
```
STATUS 4xx
Response Body: Error
```json
{
"title": "titulo",
"description": "description in English",
"translation": "descrição em portugues",
"code": "codigo",
"extra_fields": {}
}
```
:::info Information
The errors previously listed for [perform TED](/documentation/baas/ted/realizar_transferencia) are
subject to being returned by this endpoint in addition to the errors listed below.
:::
| HTTP Code `status` | QI Code `code` | Title `title` | Description (eng) `description` | Description (ptbr) `translation` |
|--------------------------|----------------------|----------------------------------------------|-------------------------------------------------------------------------|---------------------------------------------------------------------|
| 400 | QIT000001 | Bad Request | Schema Error | Erro de Schema |
| 404 | TED000020 | Not Found | Ted was not found for the given parameters. | Ted não encontrada para os parâmetros fornecidos. |
| 404 | TED000086 | Invalid Status | Ted not in pending_2fa_approval status | Ted não está pendente de aprovação por autenticação de dois fatores |
| 400 | TED000082 | Number of token validation attempts exceeded | The maximum number of failed token validation attempts has been reached | Número máximo de tentativas de validação de token atingida |
| 400 | TED000084 | Incorrect Token | Token sent does not match expected | Token enviado não condiz com, o esperado |
| 400 | TED000083 | Token Expired | Token has expired. Resend token or recreate transfer | Token expirado. Reenvie token ou recrie a transferência |
| 400 | TED000110 | Token Required | A token is required for SMS or email validation. | Um token é necessário para validação via SMS ou email. |
---
# Perform TED with Two-Factor Authentication
URL: /en/documentation/baas/ted/2fa/realizar_transferencia_2fa
In this type of transaction, payment confirmation is required via token sent to the person with powers to approve account movements.
TED transaction requests by integrating partners configured to use two-factor authentication are performed similarly to what is described in [perform TED](/documentation/baas/ted/realizar_transferencia). The difference occurs in the addition of the `tfa_info` object, containing information about the transfer approver and the contact method, and the status of a successful request which will always be **pending_2fa_approval**.
## Request
ENDPOINT /account/ ACCOUNT_KEY /ted
METHOD POST
## Authentication via Email and SMS
Request Body
```json
{
"request_control_key": "0c3d2a3e-c121-464e-b5a4-8e69e0c17bbd",
"target_account": {
"account_branch": "0001",
"account_number": "92796",
"account_digit": "1",
"owner_document_number": "23599885000192",
"owner_name": "Titular da Conta",
"ispb": "12345678",
"account_type": "checking_account"
},
"transaction_amount": 8.86,
"tfa_info": {
"approver_document_number": "98765432100",
"contact_type": "email"
}
}
```
## Device Authentication
In addition to the existing authentication methods via **sms** and **email**, it is possible to authenticate the transaction using a [previously registered device](/documentation/baas/dispositivo/create/solicitacao_cadastro_dispositivo). In this case, the `session_id` must be obtained from the **Device Scan** and sent in the `tfa_info`.
Request Body
```json
{
"request_control_key": "0c3d2a3e-c121-464e-b5a4-8e69e0c17bbd",
"target_account": {
"account_branch": "0001",
"account_number": "92796",
"account_digit": "1",
"owner_document_number": "23599885000192",
"owner_name": "Titular da Conta",
"ispb": "12345678",
"account_type": "checking_account"
},
"transaction_amount": 8.86,
"tfa_info": {
"approver_document_number": "98765432100",
"session_id": "b2f18d3a-67c2-4a7f-98e5-1d3f5c6b8a72",
"contact_type": "device"
}
}
```
## Body Params
| Field | Type | Description | Characters |
|-------------------------|--------|--------------------------------------------------------------------------------------|-----------------------------------------------------|
| `request_control_key` * | string | Unique request identification key used by the client in uuid v4 format. | 36 |
| `target_account` * | object | Destination account | **[target_account Object](#target_account-object)** |
| `transaction_amount` * | float | Transfer amount | 10 |
| `tfa_info`* | object | Object containing the account approver's document and contact method. | **[tfa_info Object](#tfa_info-object)** |
## target_account Object
| Field | Type | Description | Characters |
|---------------------------|--------|-------------------------------------------------------|-----------------------------------------------------------|
| `account_branch` * | string | Branch. | 4 |
| `account_digit` * | string | Account digit | 1 |
| `account_number` * | string | Account number. | 20 |
| `owner_document_number` * | string | CPF or CNPJ (numbers only) of the account holder. | 14 |
| `owner_name` * | string | Account holder name. | 50 |
| `account_type`* | string | Account type. | **[account_type Enumerator](#account_type-enumerator)** |
| `ispb` * | string | Based on the financial institution's CNPJ (8 digits). | 8 |
## tfa_info Object
| Field | Type | Description | Characters |
|-----------------------------|--------|---------------------------------------------------------------------------------------|------------|
| `approver_document_number`* | string | Account approver's document number. | 11 |
| `session_id`| string | Unique device session identification key in UUID v4 format (required for TFA via device). | 36 |
| `contact_type`* | string | Contact method with the account approver, can be **sms**, **email** or **device** | |
## account_type Enumerator
| Enumerator | Translation |
|------------------------|-----------------------|
| **checking_account** | checking account |
| **deposit_account** | deposit account |
| **guaranteed_account** | guaranteed account |
| **investment_account** | investment account |
| **payment_account** | payment account |
| **saving_account** | savings account |
## Response
STATUS 202
Response Body
```json
{
"request_control_key": "0c3d2a3e-c121-464e-b5a4-8e69e0c17bbd",
"ted_key": "8cb70dea-9fb0-4a68-9572-99a72849c8d6",
"created_at": "2021-10-22T20:30:23.459Z",
"ted_status": "pending_2fa_approval",
"transaction_amount": 126.97,
"fee_amount": 0.0
}
```
STATUS 4xx
Response Body: Error
```json
{
"title": "titulo",
"description": "description in English",
"translation": "descrição em portugues",
"code": "codigo",
"extra_fields": {}
}
```
:::info Information
The errors previously listed for [perform TED](/documentation/baas/ted/realizar_transferencia) are
subject to being returned by this endpoint in addition to the errors listed below.
:::
| HTTP Code `status` | QI Code `code` | Title `title` | Description (eng) `description` | Description (ptbr) `translation` |
|--------------------------|----------------------|------------------------------------|-----------------------------------------------------------------------|------------------------------------------------------------------|
| 400 | TED000079 | No approver permission | Given document number does not belong to an approver for this account | Número de documento enviado não pertence a um aprovador da conta |
| 400 | TED000080 | tfa_info is required | Client must send object tfa_info | Cliente deve enviar objeto tfa_info |
| 400 | TED000081 | Error occurred while sending token | An unexpected error occurred while sending token | Um erro inexperado ocorreu ao tentar enviar token |
| 400 | TED0000109 | Session ID needed | A session_id must be provided token | Uma session_id deve ser fornecida |
---
# Request Token Resend for a Ted Transaction
URL: /en/documentation/baas/ted/2fa/solicitacao_de_reenvio_de_token
A new token will be generated and sent to the Ted transaction approver. If the token validation attempt limit has been exceeded, resending will not be allowed.
## Request
ENDPOINT /account/ ACCOUNT_KEY /ted/ TED_KEY /resend_token
METHOD PATCH
### Path Params
| Field | Type | Description | Characters |
|-----------------|--------|---------------------------------------------------|------------|
| `account_key` * | uuidv4 | Unique account identification key. | 36 |
| `ted_key` * | uuidv4 | Unique TED transfer identification key | 36 |
## Body Params
| Field | Type | Description | Characters |
|----------------|--------|-------------------------------------------------------------------------------------------|------------|
| `contact_type` | enumerator | Authentication token delivery method | **[contact_type enumerator](#contact_type-enumerator)** |
:::info Information
If no `contact_type` is sent, the token will be sent using the originally requested method.
:::
### contact_type Enumerator
| Enumerator | Description |
|------------|---------------------------------------------------|
| **sms** | Delivery via Text Message to mobile phone |
| **email** | Delivery via electronic mail |
## Response
STATUS 202
Response Body: Requested Transaction
```json
{
"request_control_key": "b6804f32-101e-4702-8fbc-c2dbc4c2caec",
"ted_key": "8cb70dea-9fb0-4a68-9572-99a72849c8d6",
"transaction_amount": 202.01,
"fee_amount": 10,
"ted_status": "pending_2fa_approval",
"created_at": "2021-10-22T20:30:23.459Z"
}
```
STATUS 4xx
Response Body: Rejected Transfer
```json
{
"title": "titulo",
"description": "description in English",
"translation": "descrição em portugues",
"code": "codigo",
"extra_fields": {
"ted_data": {
"request_control_key": "b6804f32-101e-4702-8fbc-c2dbc4c2caec",
"ted_key": "8cb70dea-9fb0-4a68-9572-99a72849c8d6",
"transaction_amount": 202.01,
"fee_amount": 10,
"ted_status": "rejected",
"created_at": "2021-10-22T20:30:23.459Z"
}
}
}
```
| HTTP Code `status` | QI Code `code` | Title `title` | Description (eng) `description` | Description (ptbr) `translation` |
|------------------------|--------------------|----------------------------------------------|-------------------------------------------------------------------------|---------------------------------------------------------------------------|
| 400 | QIT000001 | Bad Request | Schema Error | Erro de Schema |
| 404 | TED000009 | Account not found | Account not found for the given key: \{account_key\} | Conta não encontrada para a chave fornecida: \{account_ke\} |
| 404 | TED000020 | Not Found | Ted was not found for the given parameters. | Ted não encontrada para os parâmetros fornecidos. |
| 404 | TED000086 | Invalid Status | Ted not in pending_2fa_approval status | Ted não está pendente de aprovação por autenticação de dois fatores |
| 400 | TED000082 | Number of token validation attempts exceeded | The maximum number of failed token validation attempts has been reached | Número máximo de tentativas de validação de token atingida |
| 400 | TED000087 | Error Sending Token | An error occurred while resending token and its being investigated | Um erro ocorreu ao reenviar token e está sendo investigado |
---
# Approve Batch Transaction with Two-Factor Authentication
URL: /en/documentation/baas/ted/batch_2fa/aprovar_transacao_em_lote_ted_2fa
## Request
ENDPOINT /account/ ACCOUNT_KEY /ted_batch/ TED_BATCH_KEY /validate_token
METHOD PUT
### Path Params
| Field | Type | Description | Characters |
|-----------------|--------|----------------------------------------------------------|------------|
| `account_key` | uuidv4 | Unique account identification key. | 36 |
| `ted_batch_key` | uuidv4 | Unique identification key for the TED batch transaction. | 36 |
## Authentication via Email and SMS
Request Body
```json
{
"token": "329123"
}
```
## Authentication via Device
To approve and finalize device authentication, the request must be sent with an empty payload. Validation occurs internally, with no additional information required in the request body. Note that this endpoint should only be used after the [batch transaction request](./solicitacao_de_transacao_em_lote_ted_2fa.md) has been initiated.
Request Body
```json
{
}
```
## Body Params
| Field | Type | Description | Characters |
|----------|--------|----------------------------------------------------------------------------------------------------|------------|
| `token` | string | Authentication code sent to the account movement approver **required for TFA via SMS or email** | 6 |
## Response
STATUS 201
Response Body: Approved Batch
```json
{
"request_control_key": "b6804f32-101e-4702-8fbc-c2dbc4c2caec",
"ted_batch_key": "8cb70dea-9fb0-4a68-9572-99a72849c8d6",
"ted_batch_status": "approved"
}
```
STATUS 4xx
Response Body: Rejected Batch
```json
{
"title": "titulo",
"description": "description in English",
"translation": "descrição em portugues",
"code": "codigo",
"extra_fields": {
"ted_batch_data": {
"request_control_key": "b6804f32-101e-4702-8fbc-c2dbc4c2caec",
"ted_batch_key": "8cb70dea-9fb0-4a68-9572-99a72849c8d6",
"ted_batch_status": "rejected"
}
}
}
```
STATUS 4xx
Response Body: Error
```json
{
"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 (ptbr) `translation` |
|------------------------|--------------------|----------------------------------------------|----------------------------------------------------------------------------------------------------------|------------------------------------------------------------------------------|
| 400 | TED000082 | Number of token validation attempts exceeded | The maximum number of failed token validation attempts has been reached | Número máximo de tentativas de validação de token atingida |
| 400 | TED000083 | Token Expired | Token has expired. Resend token or recreate transferToken has expired. Resend token or recreate transfer | Token expirado. Reenvie token ou recrie a transferência |
| 400 | TED000084 | Incorrect Token | Token sent does not match expected | Token enviado não condiz com, o esperado |
| 404 | TED000101 | TedBatch not Found | Ted Batch was not found | TedBatch não encontrada |
| 400 | TED000102 | Invalid Status | Ted Batch not in pending_2fa_approval status | Lote de Ted não está pendente de aprovação por autenticação de dois fatores || 400 | TED000110 | Token Required | A token is required for SMS or email validation. | Um token é necessário para validação via SMS ou email. |
---
# Request Token Resend for a Batch TED Transaction
URL: /en/documentation/baas/ted/batch_2fa/solicitacao_de_reenvio_de_token_para_lote_ted
A new token will be generated and sent to the account movement approver. If the token validation attempt limit has been exceeded, resending will not be allowed.
## Request
ENDPOINT /account/ ACCOUNT_KEY /ted_batch/ TED_BATCH_KEY /resend_token
METHOD PATCH
### Path Params
| Field | Type | Description | Characters |
|-------------------|--------|-------------------------------------------|------------|
| `account_key` * | uuidv4 | Unique account identification key. | 36 |
| `ted_batch_key` * | uuidv4 | Unique batch transaction identification key. | 36 |
Request Body
```json
{
"contact_type": "sms"
}
```
## Body Params
| Field | Type | Description | Characters |
|----------------|------------|------------------------------------------|---------------------------------------------------------|
| `contact_type` | enumerator | Authentication token delivery method | **[contact_type Enumerator](#contact_type-enumerator)** |
:::info Information
If no `contact_type` is sent, the token will be sent in the originally requested format.
:::
### contact_type Enumerator
| Enumerator | Description |
|------------|------------------------------------------|
| **sms** | Sent via Text Message to mobile phone |
| **email** | Sent via electronic mail |
## Response
STATUS 202
Response Body: Requested Transaction
```json
{
"request_control_key": "b6804f32-101e-4702-8fbc-c2dbc4c2caec",
"ted_batch_key": "8cb70dea-9fb0-4a68-9572-99a72849c8d6",
"ted_status": "pending_2fa_approval"
}
```
STATUS 4xx
Response Body: Transfer Rejected
```json
{
"title": "titulo",
"description": "description in English",
"translation": "descrição em portugues",
"code": "codigo",
"extra_fields": {
"ted_data": {
"request_control_key": "b6804f32-101e-4702-8fbc-c2dbc4c2caec",
"ted_batch_key": "8cb70dea-9fb0-4a68-9572-99a72849c8d6",
"ted_status": "rejected"
}
}
}
```
| HTTP Code `status` | QI Code `code` | Title `title` | Description (eng) `description` | Description (ptbr) `translation` |
|------------------------|--------------------|----------------------------------------------|-------------------------------------------------------------------------|-----------------------------------------------------------------------------|
| 400 | QIT000001 | Bad Request | Schema Error | Erro de Schema |
| 404 | TED000009 | Account not found | Account not found for the given key: \{account_key\} | Conta não encontrada para a chave fornecida: \{account_ke\} |
| 404 | TED000020 | Not Found | Ted was not found for the given parameters. | Ted não encontrada para os parâmetros fornecidos. |
| 400 | TED000082 | Number of token validation attempts exceeded | The maximum number of failed token validation attempts has been reached | Número máximo de tentativas de validação de token atingida |
| 400 | TED000083 | Token Expired | Token has expired. Resend token or recreate transfer | Token expirado. Reenvie token ou recrie a transferência |
| 400 | TED000084 | Incorrect Token | Token sent does not match expected | Token enviado não condiz com, o esperado |
| 404 | TED000086 | Invalid Status | Ted not in pending_2fa_approval status | Ted não está pendente de aprovação por autenticação de dois fatores |
| 400 | TED000087 | Error Sending Token | An error occurred while resending token and its being investigated | Um erro ocorreu ao reenviar token e está sendo investigado |
| 404 | TED000101 | TedBatch not Found | Ted Batch was not found | TedBatch não encontrada |
| 400 | TED000102 | Invalid Status | Ted Batch not in pending_2fa_approval status | Lote de Ted não está pendente de aprovação por autenticação de dois fatores |
---
# Perform Batch Ted Transaction with Two-Factor Authentication
URL: /en/documentation/baas/ted/batch_2fa/solicitacao_de_transacao_em_lote_ted_2fa
QI Tech offers the possibility to perform multiple ted transactions with a single call. In this system, transactions
are performed asynchronously. If the initial call returns an **http status 4xx**, none of the
transactions will be performed. After the request, the integrating partner will receive a webhook for each transaction informing
the final status of the attempt, which can be **rejected** or **sent**.
In this type of transaction, payment confirmation is required via token sent to the person with authorization powers for
account movement in the crediting account.
The Ted transaction request by integrating partners configured to use two-factor authentication
is performed similarly to what is described
in [perform batch ted transaction](/documentation/baas/ted/batch/solicitacao_de_transacao_em_lote_ted). The difference
occurs in the addition of the `tfa_info` object, containing information about the transfer approver and the contact method, and the
status of a successful request which will always be **pending_2fa_approval**.
The notification event for sending the `token` to the approver is **baas.token_validation.ted.batch**. It is
possible to [customize](/documentation/notificacoes/template) the sent message.
## Request
ENDPOINT /account/ ACCOUNT_KEY /ted_batch
METHOD POST
## Authentication via Email and SMS
Request Body: Batch Transfer with TFA via SMS or Email
```json
{
"request_control_key": "6e4fc980-f8a1-4462-b6e2-d8a49f0ac055",
"tfa_info": {
"approver_document_number": "98765432100",
"contact_type": "email"
},
"teds": [
{
"request_control_key": "0c3d2a3e-c121-464e-b5a4-8e69e0c17bbd",
"target_account": {
"account_branch": "0001",
"account_number": "92796",
"account_digit": "1",
"owner_document_number": "23599885000192",
"owner_name": "Titular da Conta",
"ispb": "12345678",
"account_type": "checking_account"
},
"transaction_amount": 8.86
},
{
"request_control_key": "ff9f2a48-918c-4911-9371-a496e37dccfc",
"target_account": {
"account_branch": "0001",
"account_number": "92797",
"account_digit": "2",
"owner_document_number": "23599885000192",
"owner_name": "Titular da Conta",
"ispb": "12345678",
"account_type": "checking_account"
},
"transaction_amount": 10.00
}
]
}
```
## Authentication via Device
In addition to the existing authentication methods via **sms** and **email**, it is possible to authenticate the transaction using a previously [registered device](/documentation/baas/dispositivo/create/solicitacao_cadastro_dispositivo). In this case, the `session_id` must be obtained in the **Device Scan** and sent in `tfa_info`.
Request Body: Batch Transfer with TFA via Device
```json
{
"request_control_key": "6e4fc980-f8a1-4462-b6e2-d8a49f0ac055",
"tfa_info": {
"approver_document_number": "98765432100",
"session_id": "b2f18d3a-67c2-4a7f-98e5-1d3f5c6b8a72",
"contact_type": "device"
},
"teds": [
{
"request_control_key": "0c3d2a3e-c121-464e-b5a4-8e69e0c17bbd",
"target_account": {
"account_branch": "0001",
"account_number": "92796",
"account_digit": "1",
"owner_document_number": "23599885000192",
"owner_name": "Titular da Conta",
"ispb": "12345678",
"account_type": "checking_account"
},
"transaction_amount": 8.86
},
{
"request_control_key": "ff9f2a48-918c-4911-9371-a496e37dccfc",
"target_account": {
"account_branch": "0001",
"account_number": "92797",
"account_digit": "2",
"owner_document_number": "23599885000192",
"owner_name": "Titular da Conta",
"ispb": "12345678",
"account_type": "checking_account"
},
"transaction_amount": 10.00
}
]
}
```
## Path Params
| Field | Type | Description | Characters |
|---------------|--------|----------------------------------------|------------|
| `account_key` | uuidv4 | Unique account identification key. | 36 |
## Body Params
| Field | Type | Description | Characters |
|-------------------------|--------|------------------------------------------------------------------------------------|-----------------------------------------|
| `request_control_key` * | uuidv4 | Unique request identification key used by the client in uuid v4 format. | 36 |
| `teds` * | array | List of ted objects linked to the batch. | list of **[Ted Object](#ted-object)** |
| `tfa_info`* | Object | Object containing the document of the account approver and the contact method. | **[tfa_info Object](#tfa_info-object)** |
## tfa_info Object
| Field | Type | Description | Characters |
|------------------------------|--------|-----------------------------------------------------------------------------------------------|------------|
| `approver_document_number` * | string | Document number of the account approver. | 11 |
| `session_id` | string | Unique device session identification key in UUID v4 format (required for device TFA). | 36 |
| `contact_type` * | string | Contact method with the account approver, which can be **sms**, **email** or **device** | |
## Ted Object
| Field | Type | Description | Characters |
|-------------------------|--------|------------------------------------------------------------------------------------|-----------------------------------------------------|
| `request_control_key` * | string | Unique request identification key used by the client in uuid v4 format. | 36 |
| `target_account` * | object | Target account | **[target_account Object](#target_account-object)** |
| `transaction_amount` * | float | Transfer amount | 10 |
## target_account Object
| Field | Type | Description | Characters |
|---------------------------|--------|-----------------------------------------------------|---------------------------------------------------------|
| `account_branch` * | string | Branch. | 4 |
| `account_digit` * | string | Account digit | 1 |
| `account_number` * | string | Account number. | 20 |
| `owner_document_number` * | string | CPF or CNPJ (numbers only) of the account holder. | 14 |
| `owner_name` * | string | Name of the account holder. | 50 |
| `account_type`* | string | Account type. | **[account_type Enum](#account_type-enum)** |
| `ispb` * | string | Based on the financial institution's CNPJ (8 digits). | 8 |
## account_type Enum
| Enum | Translation |
|------------------------|-----------------------|
| **checking_account** | checking account |
| **deposit_account** | deposit account |
| **guaranteed_account** | guaranteed account |
| **investment_account** | investment account |
| **payment_account** | payment account |
| **saving_account** | savings account |
## Response
STATUS 202
Response Body: Batch Transfer Requested
```json
{
"request_control_key": "b6804f32-101e-4702-8fbc-c2dbc4c2caec",
"ted_batch_key": "8cb70dea-9fb0-4a68-9572-99a72849c8d6",
"ted_batch_status": "pending_2fa_approval"
}
```
### ted_batch_status Enum
| Enum | Description |
|--------------------------|----------------------------------------------------------------------------|
| **approved** | Batch transfer approved and transactions in execution process. |
| **rejected** | Batch transfer rejected |
| **pending_2fa_approval** | Batch scheduling pending approval by two-factor authentication |
| **cancelled** | Batch transfer cancelled |
STATUS 4xx
Response Body: Transfer Rejected
```json
{
"title": "titulo",
"description": "description in English",
"translation": "descrição em portugues",
"code": "codigo",
"extra_fields": {
"ted_batch_data": {
"request_control_key": "b6804f32-101e-4702-8fbc-c2dbc4c2caec",
"ted_batch_key": "8cb70dea-9fb0-4a68-9572-99a72849c8d6",
"ted_batch_status": "rejected"
}
}
}
```
STATUS 4xx
Response Body: Error
```json
{
"title": "titulo",
"description": "description in English",
"translation": "descrição em portugues",
"code": "codigo",
"extra_fields": {}
}
```
:::info Information
The errors previously listed for [Ted transfer](/documentation/baas/ted/solicitacao_de_transacao_em_lote_ted)
are
subject to being returned by this endpoint in addition to the errors listed below.
:::
| HTTP Code `status` | QI Code `code` | Title `title` | Description (eng) `description` | Description (ptbr) `translation` |
|--------------------------|----------------------|------------------------------------|-----------------------------------------------------------------------|------------------------------------------------------------------|
| 400 | TED000079 | No approver permission | Given document number does not belong to an approver for this account | Número de documento enviado não pertence a um aprovador da conta |
| 400 | TED000080 | tfa_info is required | Client must send object tfa_info | Cliente deve enviar objeto tfa_info |
| 400 | TED000081 | Error occurred while sending token | An unexpected error occurred while sending token | Um erro inexperado ocorreu ao tentar enviar token |
---
# Introduction to TED Batch Transactions
URL: /en/documentation/baas/ted/batch/introducao_a_transacao_em_lote_ted
QI Tech offers the possibility to perform multiple TED transactions with a single call. In this system, transactions
are performed asynchronously. If a **4xx http status** is returned in the initial call, none of the
transactions will be performed. After the request, the integrator partner will receive a webhook for each transaction informing
the final status of the attempt, which can be **rejected** or **sent**.
## Two-Factor Authentication
Just like in TED transactions, integrator partners with two-factor authentication configuration must send the
`tfa_info` object with contact information and token sending details.
---
# List TED Transactions from a Batch of an Account
URL: /en/documentation/baas/ted/batch/listar_transacoes_de_um_lote_de_transacoes_ted
## Request
ENDPOINT /account/ ACCOUNT_KEY /ted_batch/ TED_BATCH_KEY /teds
METHOD GET
### Path Params
| Field | Type | Description | Characters |
|-----------------|--------|---------------------------------------------------|------------|
| `account_key` | uuidv4 | Unique account identification key. | 36 |
| `ted_batch_key` | uuidv4 | Unique batch transaction identification key. | 36 |
### Query Params
| Field | Type | Description | Characters |
|-----------------------|---------|-------------------------------------------------------------------------|-----------------------------------------------------|
| `request_control_key` | uuidv4 | Unique request identification key used by the client. | 36 |
| `ted_status` | string | TED transaction status. Can be sent as a list. | **[ted_status Enumerator](#enumerador-ted_status)** |
| `date_from` | string | Start date. Format "YYYY-MM-DD" | 10 |
| `date_to` | string | End date. Format "YYYY-MM-DD" | 10 |
| `page` | integer | Requested page number. 1 by default | |
| `page_size` | integer | Requested page size in the query. 30 by default and maximum value | Maximum value of 30 |
## ted_status Enumerator
| Enumerator | Description |
|--------------|-----------------------------------------|
| **sent** | TED transfer completed successfully. |
| **pending** | TED transfer pending. |
| **rejected** | TED transfer rejected. |
| **returned** | TED transfer returned. |
### Response
STATUS 200
Response Body
```json
{
"data": [
{
"request_control_key": "b6804f32-101e-4702-8fbc-c2dbc4c2caec",
"ted_key": "8cb70dea-9fb0-4a68-9572-99a72849c8d6",
"ted_status": "sent"
},
{
"request_control_key": "697c07c3-5398-48d2-a418-853323f85f97",
"ted_key": "e95eabdb-4520-4c3d-a76f-99cb5b64724b",
"ted_status": "sent"
},
{
"request_control_key": "ca35c526-b5a0-40d7-8c56-8566c77a34f4",
"ted_key": "58d2fa9e-42ec-4779-b2fc-14ec98cbdca8",
"ted_status": "rejected"
}
],
"pagination": {
"current_page": 1,
"rows_per_page": 30
}
}
```
---
# List Batch Transactions from an Account
URL: /en/documentation/baas/ted/batch/listar_transacoes_em_lote_ted_de_uma_conta
## Request
ENDPOINT /account/ ACCOUNT_KEY /ted_batches
METHOD GET
### Path Params
| Field | Type | Description | Characters |
|---------------|--------|------------------------------------------|------------|
| `account_key` | uuidv4 | Unique account identification key. | 36 |
### Query Params
| Field | Type | Description | Characters |
|-----------------------|---------|--------------------------------------------------------------------------|-----------------------------------------------------------------|
| `request_control_key` | uuidv4 | Unique request identification key used by the client. | 36 |
| `ted_batch_status` | uuidv4 | TED batch transactions status. Can be sent as a list. | **[ted_batch_status Enumerator](#enumerator-ted_batch_status)** |
| `date_from` | string | Start date. Format "YYYY-MM-DD" | 10 |
| `date_to` | string | End date. Format "YYYY-MM-DD" | 10 |
| `page` | integer | Requested page number. Default is 1 | |
| `page_size` | integer | Requested page size for the query. Default is 30 and maximum value | Maximum value of 30 |
### Enumerator ted_batch_status
| Enumerator | Description |
|--------------------------|------------------------------------------------------------------------------------|
| **approved** | Batch transfer approved and transactions in execution process. |
| **rejected** | Batch transfer rejected |
| **pending_2fa_approval** | Batch scheduling pending approval by two-factor authentication |
| **cancelled** | Batch transfer cancelled |
### Response
STATUS 200
Response Body
```json
{
"data": [
{
"request_control_key": "b6804f32-101e-4702-8fbc-c2dbc4c2caec",
"ted_batch_key": "8cb70dea-9fb0-4a68-9572-99a72849c8d6",
"ted_batch_status": "approved"
},
{
"request_control_key": "939d1503-aa5a-49a6-ae3b-ff84122a6dd3",
"ted_batch_key": "03cf9181-0eb9-480e-8bb4-66a5a9a6410e",
"ted_batch_status": "rejected"
},
{
"request_control_key": "43a14f3a-b2af-4a0e-8a74-70af2fca74a9",
"ted_batch_key": "94ab9fad-9c65-4117-b9c3-a47b1269508f",
"ted_batch_status": "approved"
}
],
"pagination": {
"current_page": 1,
"next_page": null,
"rows_per_page": 30
}
}
```
---
# Perform Ted Transaction in Batch
URL: /en/documentation/baas/ted/batch/solicitacao_de_transacao_em_lote_ted
QI Tech offers the possibility to perform multiple ted transactions with a single call. In this system, transactions
are performed asynchronously. If an **http status 4xx** is returned in the initial call, none of the
transactions will be performed. After the request, the integrating partner will receive a webhook for each transaction informing
the final status of the attempt, which can be **rejected** or **sent**.
## Request
ENDPOINT /account/ ACCOUNT_KEY /ted_batch
METHOD POST
```json
{
"request_control_key": "6e4fc980-f8a1-4462-b6e2-d8a49f0ac055",
"teds": [
{
"request_control_key": "0c3d2a3e-c121-464e-b5a4-8e69e0c17bbd",
"target_account": {
"account_branch": "0001",
"account_number": "92796",
"account_digit": "1",
"owner_document_number": "23599885000192",
"owner_name": "Titular da Conta",
"ispb": "12345678",
"account_type": "checking_account"
},
"transaction_amount": 8.86
}
]
}
```
## Path Params
| Field | Type | Description | Characters |
|---------------|--------|-------------------------------------------------|------------|
| `account_key` | uuidv4 | Unique account identification key. | 36 |
## Body Params
| Field | Type | Description | Characters |
|-------------------------|--------|------------------------------------------------------------------------------------------|----------------------------------|
| `request_control_key` * | uuidv4 | Unique request identification key used by the client in uuid v4 format. | 36 |
| `teds` * | array | List of ted objects linked to the batch. | list of **[Ted object](#objeto-ted)** |
## Ted object
| Field | Type | Description | Characters |
|-------------------------|--------|------------------------------------------------------------------------------------------|-----------------------------------------------|
| `request_control_key` * | string | Unique request identification key used by the client in uuid v4 format. | 36 |
| `target_account` * | object | Destination account | **[target_account object](#objeto-target_account)** |
| `transaction_amount` * | float | Transfer amount | 10 |
## target_account object
| Field | Type | Description | Characters |
|---------------------------|--------|-----------------------------------------------------|---------------------------------------------------|
| `account_branch` * | string | Branch. | 4 |
| `account_digit` * | string | Account digit | 1 |
| `account_number` * | string | Account number. | 20 |
| `owner_document_number` * | string | CPF or CNPJ (numbers only) of the account holder. | 14 |
| `owner_name` * | string | Account holder name. | 50 |
| `account_type`* | string | Account type. | **[account_type enumerator](#enumerador-account_type)** |
| `ispb` * | string | Based on financial institution CNPJ (8 digits). | 8 |
## account_type enumerator
| Enumerator | Translation |
|------------------------|-----------------------|
| **checking_account** | checking account |
| **deposit_account** | deposit account |
| **guaranteed_account** | guaranteed account |
| **investment_account** | investment account |
| **payment_account** | payment account |
| **saving_account** | savings account |
## Response
STATUS 201
Response Body: Batch Transfer Approved
```json
{
"request_control_key": "b6804f32-101e-4702-8fbc-c2dbc4c2caec",
"ted_batch_key": "8cb70dea-9fb0-4a68-9572-99a72849c8d6",
"ted_batch_status": "approved"
}
```
### ted_batch_status enumerator
| Enumerator | Description |
|--------------------------|-----------------------------------------------------------------------------|
| **approved** | Batch transfer approved and transactions in execution process. |
| **rejected** | Batch transfer rejected |
| **pending_2fa_approval** | Batch scheduling pending approval by two-factor authentication |
| **cancelled** | Batch transfer cancelled |
STATUS 4xx
Response Body: Batch Rejected
```json
{
"title": "titulo",
"description": "description in English",
"translation": "descrição em portugues",
"code": "codigo",
"extra_fields": {
"ted_batch_data": {
"request_control_key": "b6804f32-101e-4702-8fbc-c2dbc4c2caec",
"ted_batch_key": "8cb70dea-9fb0-4a68-9572-99a72849c8d6",
"ted_batch_status": "rejected"
}
}
}
```
STATUS 4xx
Response Body: Error
```json
{
"title": "titulo",
"description": "description in English",
"translation": "descrição em portugues",
"code": "codigo",
"extra_fields": {}
}
```
:::info Information
The errors previously listed for [Ted transfer](/documentation/baas/ted/realizar_transferencia) are
liable to be returned by this endpoint.
:::
---
# Consult TED
URL: /en/documentation/baas/ted/consultar_ted
## Request
ENDPOINT /account/ ACCOUNT_KEY /ted/ TED_KEY / TED_DIRECTION
METHOD GET
## Request Path Params
| Field | Type | Description | Characters |
|-------------------|--------|--------------------------------------------------------------|-------------------------------------------------|
| `ted_direction` * | string | Filter to indicate whether a transaction is inbound or outbound. | **[Enum ted_direction](#enums-ted_direction)** |
| `account_key` * | uuidv4 | Unique identification key of the QI account. | 36 |
| `ted_key` * | uuidv4 | Unique identification key of the TED transfer. | 36 |
## Enumerators ted_direction
| Enumerator | Translation |
|------------|----------|
| incoming | entrada |
| outgoing | saída |
:::caution Attention
Viewing a transfer will only be permitted if the requester has permissions on the outgoing account for transactions with a ted_direction of outgoing, or has permissions on the incoming account for transactions with a ted_direction of incoming. Otherwise, a not found error will be returned.
:::
## Response
STATUS 200
Response Body: Rejected Transfer (outgoing)
```json
{
"request_control_key": "6e290347-330d-4b3a-8ebb-2ac217ad6eb3",
"ted_key": "8cb70dea-9fb0-4a68-9572-99a72849c8d6",
"account_key": "fc6862c4-2b20-4057-8063-b8809866e494",
"created_at": "2021-10-22T20:30:23.459Z",
"ted_status": "rejected",
"transaction_amount": 126.97,
"fee_amount": 0.0,
"target_account": {
"account_branch": "0001",
"account_digit": "6",
"account_number": "78340",
"ispb": "12345678",
"owner_document_number": "32402502000135",
"owner_name": "QI Tech"
},
"refusal_reason": {
"refusal_code": 1,
"enumerator": "conta_destinatario_encerrada",
"description": "Conta Destinatária do Crédito Encerrada"
}
}
```
Response Body: Transfer Sent (outgoing)
```json
{
"request_control_key": "6e290347-330d-4b3a-8ebb-2ac217ad6eb3",
"ted_key": "8cb70dea-9fb0-4a68-9572-99a72849c8d6",
"account_key": "fc6862c4-2b20-4057-8063-b8809866e494",
"created_at": "2021-10-22T20:30:23.459Z",
"ted_status": "sent",
"transaction_amount": 126.97,
"fee_amount": 0.0,
"target_account": {
"account_branch": "0001",
"account_digit": "6",
"account_number": "78340",
"ispb": "12345678",
"owner_document_number": "32402502000135",
"owner_name": "QI Tech"
},
"refusal_reason": {}
}
```
Response Body: Transfer Received (incoming)
```json
{
"request_control_key": "6e290347-330d-4b3a-8ebb-2ac217ad6eb3",
"ted_key": "8cb70dea-9fb0-4a68-9572-99a72849c8d6",
"account_key": "fc6862c4-2b20-4057-8063-b8809866e494",
"created_at": "2021-10-22T20:30:23.459Z",
"ted_status": "received",
"transaction_amount": 126.97,
"fee_amount": 0.0,
"source_account": {
"account_branch": "0001",
"account_digit": "6",
"account_number": "78340",
"ispb": "12345678",
"owner_document_number": "32402502000135",
"owner_name": "QI Tech"
},
"refusal_reason": {}
}
```
STATUS 4xx
Response Body: Error
```json
{
"title": "titulo",
"description": "description in English",
"translation": "description in Portuguese",
"code": "codigo",
"extra_fields": {}
}
```
| HTTP Code `status` | QI Code `code` | Title `title` | Description (eng) `description` | Description (ptbr) `translation` |
|------------------------|------------------------|--------------------------|-----------------------------------|------------------------------------------------------------------------|
| 404 | TED000XXX | Outgoing TED Not Found | Ted key \{ted_key\} was not found | Transferência Ted de saída com chave \{ted_key\} não foi encontrada. |
| 404 | TED000XXX | Incoming TED Not Found | Ted key \{ted_key\} was not found | Transferência Ted de entrada com chave \{ted_key\} não foi encontrada. |
---
# Tabela de Erros para Ted
URL: /en/documentation/baas/ted/erros_ted
STATUS 4xx
Response Body: Error
```json
{
"title": "titulo",
"description": "description in English",
"translation": "descrição em portugues",
"code": "codigo",
"extra_fields": {}
}
```
| Código HTTP `status` | Código QI `code` | Título `title` | Descrição (eng) `description` | Descrição (ptbr) `translation` |
|--------------------------|----------------------|-----------------------------------------------------|--------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|-----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|
| 400 | QIT000001 | Bad Request | schema error description | Schema Inválido |
| 500 | QIT000500 | Internal Error | An internal error has occurred and its being investigated. | Um erro interno aconteceu e está sendo investigado |
| 400 | TED000001 | Bad Request | Account already have a fee created | A conta já tem uma taxa criada |
| 400 | TED000002 | Bad Request | Fee not already created | Taxa ainda não criada |
| 403 | TED000003 | Unauthorized | This agent can not add a financial institution. | Este agente não pode adicionar uma instituição financeira. |
| 400 | TED000004 | Bad Request | The cockpit_key must be unique (error raised on commit: \{msg\}) | A cockpit_key deve ser exclusiva (erro gerado no commit: \{msg\}) |
| 400 | TED000005 | Bad Request | Event for the provided transaction_code not implemented | Evento para a transaction_code fornecida não implementado |
| 404 | TED000006 | Target account Not Found | Target account was not found for given parameters | Conta destino não encontrada para os parâmetros informados |
| 400 | TED000007 | Bad Request | A related_account_key must be provided | Uma chave related_account_key deve ser fornecida |
| 404 | TED000008 | Not Found | No related_account found | Nenhuma conta relacionada encontrada |
| 404 | TED000009 | Not Found | Account not found for the given key: \{account_key\} | Conta não encontrada para a chave fornecida: \{account_key\} |
| 400 | TED000010 | Bad Request | Account already registered | Conta já registrada |
| 400 | TED000011 | Bad Request | Wrong day/time for TED | Dia/hora incorretos para a TED |
| 400 | TED000012 | Bad Request | The target's length of the account + account_digit cannot be larger than 21 | O número de digitos na conta de destino + digito não pode ser maior que 21 |
| 400 | TED000013 | Bad Request | Unable to find source_account_key's account | Não foi possível encontrar a conta com source_account_key fornecido |
| 403 | TED000014 | Invalid target account | Invalid target account | Conta destino inválida |
| 400 | TED000015 | Bad Request | Account blocked or closed can not perform this action | A conta bloqueada ou fechada não pode executar esta ação |
| 400 | TED000016 | Bad Request | Hub account can not perform this action | A conta hub não pode executar esta ação |
| 403 | TED000017 | Unauthorized | Provided account does not have approval credential for the given person | A conta fornecida não possui credencial de aprovação para a pessoa especificada |
| 403 | TED000018 | Unauthorized | Provided account not owned by SELECTED_AGENT | Conta fornecida não pertencente ao SELECTED_AGENT |
| 400 | TED000019 | Bad Request | Scheduling not implemented yet | Agendamento ainda não implementado |
| 404 | TED000020 | Not Found | Ted was not found for the given parameters. | Ted não encontrada para os parâmetros fornecidos. |
| 400 | TED000021 | Bad Request | A ted_type must be provided | Um tipo de ted deve ser fornecido |
| 400 | TED000022 | Bad Request | Ted not found for the given IF Control Number | Ted não encontrada para o número de controle da IF fornecida |
| 422 | TED000023 | Bad Request | Unable to process message due to the current status (\{current_status\}). Messages of the type \{bacen_message_code\} are allowed to happen on teds with status \{allowed_status\}. [ted_type = \{type\}, key = \{key\}] | Não foi possível processar a mensagem devido ao status atual (\{current_status\}). Mensagens do tipo \{bacen_message_code\} podem ocorrer em teds com status \{allowed_status\}. [Ted_type = \{type\}, key = \{key\}] |
| 403 | TED000024 | Unauthorized | This agent can not add rules. | Este agente não pode adicionar regras. |
| 403 | TED000025 | Unauthorized | This agent can not add rules types. | Este agente não pode adicionar tipos de regras. |
| 400 | TED000026 | Bad Request | \{ted_rule_type_enum\} was not found among registered rules. | \{ted_rule_type_enum\} não encontrada dentro das regras registradas. |
| 400 | TED000027 | Bad Request | Mismatch between rule data and rule schema: \{message\} | Incompatibilidade entre os dados da regra e o esquema de regra: \{message\} |
| 400 | TED000028 | Bad Request | Both source_account_key and source_document_number are not null. At least one of them should be null. | Tanto a source_account_key quanto o source_document_number estão preenchidos. Pelo menos um dos dois deve ser nulo. |
| 422 | TED000029 | Unprocessable Entity | \{object_name\} has invalid type \{object_type\} | \{object_name\} possui tipo inválido \{object_type\} |
| 400 | TED000030 | Empty ted list received | A list of teds must be provided | Uma lista de transferências ted deve ser fornecida |
| 400 | TED000031 | Bad Request | ISPB number \{ispb\} does not exist or is inactive | ISPB \{ispb\} não existe ou está inativo |
| 404 | TED000032 | Not Found | Account limit request with key \{account_limit_request_key\} was not found. | Pedido de limite com chave \{account_limit_request_key\} não encontrado. |
| 400 | TED000033 | Bad Request | An account limit request with status \{status\} does not allow this operation. | Pedido de limite com chave \{status\} não permite essa operação |
| 400 | TED000034 | Bad Request | Account limit request \{account_limit_request_key\} is not approved then cannot be executed. | Pedido de limite \{account_limit_request_key\} não foi aprovado portanto não pode ser executado |
| 406 | TED000035 | Not Acceptable | It is not possible to request changes in limits for different accounts. | Não é possível realziar pedidos de mudanças de limites para contas diferentes. |
| 400 | TED000036 | Bad Request | Transfer rejected by the system | A transferência foi recusada pelo sistema |
| 400 | TED000037 | Bad Request | The account \{account_key\} already has a pending request for limit type \{account_limit_type\}. | A conta \{account_key\} ja possui um pedido do tipo \{account_limit_type\} pendente. |
| 409 | TED000038 | Conflict | Ted \{outgoing_ted_key\} is not pending analysis therefore cannot be updated. | Ted \{outgoing_ted_key\} não está pendente de análise portanto não pode ser atualizada. |
| 400 | TED000039 | Bad Request | Your centralized billing account is closed, please contact support. | Sua conta de tarifas centralizadas está fechada, favor entrar em contato com o suporte. |
| 400 | TED000040 | Bad Request | Your centralized billing account has insufficient funds, please contact support. | Sua conta de tarifas centralizadas não possui saldo sufciente, favor entrar em contato com o suporte. |
| 400 | TED000041 | Bad Request | Pending fraud analysis return | Retorno pendente da análise de fraude |
| 400 | TED000042 | Ted Direction Invalid | Ted Direction must be either outgoing or incoming | Ted Direction deve ser outgoing ou incoming |
| 400 | TED000043 | Ted Key needed | A ted_key must be provided | Uma ted_key deve ser fornecida |
| 400 | TED000044 | Invalid Timestamp Format sent | Given parameter is not in the correct format \{timestamp_format\} | Parametro enviado não está no formato correto \{timestamp_format\} |
| 400 | TED000045 | Search Params Error | Invalid integer value for page or size querystring parameters | Valor inválido para parâmetros de página ou tamanho de página |
| 400 | TED000046 | Invalid uuid v4 string sent | \{key\} was not accepted for not being a valid uuid v4 string | \{key\} não foi aceito por não ser uma palavra uuid v4 válida |
| 404 | TED000047 | Not found | Incoming Ted with key \{incoming_ted_key\} was not found. | Ted de entrada com chave \{incoming_ted_key\} não foi encontrado. |
| 400 | TED000048 | Bad Request | The status of the incoming ted is not approved. | O status do ted de entrada não é aprovado. |
| 400 | TED000049 | Bad Request | Invalid message type: \{message_type\} | Tipo de mensagem inválido: \{message_type\} |
| 400 | TED000050 | Bad Request | Refusal reason \{refusal_reason_enumerator\} not found | Motivo de recusa \{refusal_reason_enumerator\} não encontrado |
| 400 | TED000051 | Barcode payment Not implemented for this endpoint | Barcode payment Not implemented for this endpoint | Pagamento de código de barras não implementado para este endpoint |
| 400 | TED000052 | Invalid Source Subtype | Source Subtype \{source_subtype\} is invalid | Source Subtype \{source_subtype\} é inválido |
| 400 | TED000053 | Invalid Target Account Type | Target Account Type \{account_type\} is invalid | Tipo de conta destino \{account_type\} é inválido |
| 400 | TED000054 | Invalid Transaction Amount | Transaction Amount \{transaction_amount\} is invalid | Valor de transação \{transaction_amount\} é inválido |
| 400 | TED000055 | Invalid Observation | Observation sent is invalid | Observação enviada é inválida |
| 400 | TED000057 | Invalid Document Number | Given \{document_number\} document number is invalid | CPF/CNPJ \{document_number\} fornecido não é valido |
| 400 | TED000058 | Bad Request | Insufficient account balance for transfer and fee amount | Saldo de conta insuficiente para a transação e a taxa |
| 400 | TED000059 | Bad Request | Unmapped transaction error received | Erro transacional não mapeado recebido |
| 400 | TED000060 | Bad Request | Billing Account is closed | Conta centralizadora de pagamentos de tarifa fechada |
| 400 | TED000061 | Bad Request | Billing Account without necessary funds | Conta centralizadora de pagamentos sem saldo necessário |
| 400 | TED000062 | Bad Request | Error while performing outgoing ted refusal transfer | Erro ao realizar transferência ted de rejeição |
| 400 | TED000063 | Internal Error | Error while sending outgoing ted str. Ted_key: \{outgoing_ted_key\} | Erro ao enviar str de ted de saída. Ted_key: \{outgoing_ted_key\} |
| 409 | TED000064 | Bad Request | request_control_key \{request_control_key\} already in use | request_control_key \{request_control_key\} já utilizada |
| 400 | TED000065 | Bad Request | It has been identified by request_control_key that this request is already being processed | Foi identificado por request_control_key que está requisição está sendo processada |
| 400 | TED000067 | Error loading fees | Failed to load fees for account \{account_key\} | Falha ao carregar tarifas para conta \{account_key\} |
| 400 | TED000068 | Bad Request | Transfer rejected by th system | A transferência foi recusada pelo sistema |
| 404 | TED000069 | Account Not Found | Account was not found for given parameters | Conta não encontrada para os parâmetros informados |
| 400 | TED000070 | Bad Request | Insufficient account balance fee amount in billing account | Saldo de conta centralizadora insuficiente para taxa |
| 400 | TED000071 | Bad Request | Transaction cannot be made due to already blocked balance | Transação não pode ser feita pois saldo em conta bloqueado |
| 400 | TED000072 | Invalid target ispb | Target ispb must be external | ISPB de destino deve ser externo |
| 404 | TED000073 | Person Not Found | Person with key \{person_key\} not found | Pessoa com chave \{person_key\} não encontrada |
| 400 | TED000074 | Invalid caas_client_key | There caas_client_key is not valid | A caas_client_key enviada não é válida |
| 400 | TED000075 | Invalid Requester Configuration Info | The configuration \{configuration\} format sent is not valid | O formato enviado da configuração \{configuration\} não é válido |
| 404 | TED000076 | Requester Configuration not found | There is no Requester Configuration attributed to requester_key given | Não há Requester Configuration para a requester_key enviada |
| 400 | TED000077 | Bad Request | Requester Configuration already exists for \{requester_key\} | Requester Configuration já existe para o \{requester_key\} |
| 403 | TED000078 | Requester not allowed to access this endpoint | Requester has no permission to perform ted transfers on this endpoint | Requester não possui permissão de realizar transações ted através deste endpoint |
| 403 | TED000079 | No approver permission | Given document number does not belong to an approver for this account | Número de documento enviado não pertence a um aprovador da conta |
| 400 | TED000080 | tfa_info is required | Client must send object tfa_info | Cliente deve enviar objeto tfa_info |
| 400 | TED000081 | Error occurred while sending token | An unexpected error occurred while sending token | Um erro inexperado ocorreu ao tentar enviar token |
| 400 | TED000082 | Number of token validation attempts exceeded | The maximum number of failed token validation attempts has been reached | Número máximo de tentativas de validação de token atingida |
| 400 | TED000083 | Token Expired | Token has expired. Resend token or recreate transfer | Token expirado. Reenvie token ou recrie a transferência |
| 400 | TED000084 | Incorrect Token | Token sent does not match expected | Token enviado não condiz com, o esperado |
| 400 | TED000085 | Error Validating Token | An error occurred while validating token and it is being investigated | Um erro ocorreu ao validar token e está sendo investigado |
| 400 | TED000086 | Invalid Status | Ted not in pending_2fa_approval status | Ted não está pendente de aprovação por autenticação de dois fatores |
| 400 | TED000087 | Error Sending Token | An error occurred while resending token and its being investigated | Um erro ocorreu ao reenviar token e está sendo investigado |
| 403 | TED000088 | Bad Request | Could not complete the transaction and the transaction was rejected. Try again | Não foi possível concluir a transação e a transferência foi rejeitada. Tente novamente |
| 400 | TED000089 | Invalid Schedule Date | Schedule date must be after current date for UTC-3 | Data de agendamento deve ser após a data atual em UTC-3 |
| 400 | TED000090 | Invalid Schedule Date | Schedule date must be a workday | Data de agendamento deve ser um dia útil |
| 400 | TED000091 | Target Account and Source Account must be different | Target Account must not be the same as Source Account | A conta de destino não pode ser a mesma da conta de origem |
| 400 | TED000092 | Invalid reason code | Invalid reason code | Motivo inválido |
| 404 | TED000093 | TedSchedule not Found | TedSchedule was not found | TedSchedule não encontrada |
| 400 | TED000094 | Bad Request | Ted Schedule cannot be cancelled in current status | Agendamento Ted não pode ser cancelado no status atual |
| 400 | TED000095 | Bad Request | The given Ted Schedule is tied to a batch. It cannot be individually cancelled | O agendamento Ted enviado está ligado a um lote. Ela não pode ser individualmente cancelada |
| 400 | TED000096 | Bad Request | Action cannot be taken place as there is currently a pending transfer in progress | A ação não pôde ser completada como há uma transferência pendente |
| 400 | TED000098 | Bad Request | The outgoing ted was returned | A transferência ted de saída foi devolvida |
| 400 | TED000099 | Invalid Status | Ted Schedule not in pending_2fa_approval status | Agendamento Ted não está pendente de aprovação por autenticação de dois fatores |
| 400 | TED000100 | Invalid Schedule Date | Schedule must be approved before the scheduled date | Agendamento deve ser aprovado em data anterior à programada para transação |
| 404 | TED000101 | TedBatch not Found | TedBatch was not found | TedBatch não encontrada |
| 400 | TED000102 | Invalid Status | Ted Batch not in pending_2fa_approval status | Lote de Ted não está pendente de aprovação por autenticação de dois fatores |
| 404 | TED000103 | ScheduleBatch not Found | Ted Schedule Batch was not found | Agendamento de Ted em lote não encontrado |
| 400 | TED000104 | Invalid Status | Schedule Batch cannot be cancelled in current status | Lote de agendamento não pode ser cancelado no status atual |
| 400 | TED000105 | Schedule Batch could not be cancelled | ScheduleBatch could not be cancelled due to current date being equal or after earliest schedule date. Cancel schedules one by one | ScheduleBatch não pode ser cancelada devido a data atual ser superior ou igual à menor schedule_date. Cancele agendamentos individualmente |
| 400 | TED000106 | Invalid Status | ScheduleBatch not in pending_2fa_approval status | Lote Agendamentos de Ted não está pendente de aprovação por autenticação de dois fatores |
| 400 | TED000107 | Schedule Batch could not be approved | ScheduleBatch could not be approved due to current date being equal or after earliest schedule date. Rejecting batch | ScheduleBatch não pode ser aprovada devido a data atual ser superior ou igual à menor schedule_date. Rejeitando lote |
| 400 | TED000108 | Number of transfer attempts exceeded | The maximum number of failed transfer attempts has been reached | Número máximo de tentativas de transferência foi atingida |
---
# List TEDs
URL: /en/documentation/baas/ted/listar_teds
## Request
ENDPOINT /account/ ACCOUNT_KEY /teds
METHOD GET
## Path Params
| Field | Type | Description | Characters |
|-----------------|--------|------------------------------------------|------------|
| `account_key` * | uuidv4 | Unique identification key of the QI account. | 36 |
## Query Params
| Field | Type | Description | Characters |
|-----------------------|------------|----------------------------------------------------------------------------------------------------------------|--------------------------------------------------------------------------|
| `ted_direction` | enumerator | Indicator of the transaction direction (inbound or outbound). If not sent, **outgoing** will be considered | [Enums ted_transfer_direction](#enumerators-ted_transfer_direction) |
| `request_control_key` | uuidv4 | Unique request identification key used by the client. | 36 |
| `date_from` | string | Start date. Format "YYYY-MM-DD" | |
| `date_to` | string | End date. Format "YYYY-MM-DD" | |
| `page` | integer | Requested page number. Default is 1 | |
| `page_size` | integer | Requested page size in the query. Default and maximum value is 30 | Maximum value of 30 |
## Enumerators ted_transfer_direction
| Enumerator | Description |
|--------------|------------------------------|
| **incoming** | Inbound TED transfer |
| **outgoing** | Outbound TED transfer |
## Response
STATUS 201
Response Body
```json
{
"data": [
{
"request_control_key": "6e290347-330d-4b3a-8ebb-2ac217ad6eb3",
"ted_key": "8cb70dea-9fb0-4a68-9572-99a72849c8d6",
"account_key": "fc6862c4-2b20-4057-8063-b8809866e494",
"created_at": "2021-10-22T20:30:23.459Z",
"ted_status": "sent",
"transaction_amount": 126.97,
"fee_amount": 0.0,
"target_account": {
"account_branch": "0001",
"account_digit": "6",
"account_number": "78340",
"ispb": "12345678",
"owner_document_number": "32402502000135",
"owner_name": "QI Tech"
},
"refusal_reason": {}
}
],
"pagination": {
"current_page": 1,
"rows_per_page": 30
}
}
```
---
# Perform a TED transfer
URL: /en/documentation/baas/ted/realizar_transferencia
Receiving a TED transaction is not instantaneous in the national financial system. When performing a TED transaction in the QI system, an immediate response will be returned indicating error, rejection, or acceptance of the transfer. Even if a transfer has been marked as `sent`, the Receiving Financial Institution may refuse the incoming funds and return the amount. In this case, a new webhook with the status `rejected` will be sent, and the reason for the rejection will be returned in the `refusal_reason` field.
Debits in the source account of the transaction will be made immediately. This does not mean that the amount has been credited to the destination account due to the principles of TED transactions described above. If the sent transaction is rejected, the transaction amount will be credited back to the source account.
## Request
ENDPOINT /account/ ACCOUNT_KEY /ted
METHOD POST
Request Body
```json
{
"request_control_key": "0c3d2a3e-c121-464e-b5a4-8e69e0c17bbd",
"target_account": {
"account_branch": "0001",
"account_number": "92796",
"account_digit": "1",
"owner_document_number": "23599885000192",
"owner_name": "Account owner name",
"ispb": "12345678",
"account_type": "checking_account"
},
"transaction_amount": 8.86
}
```
## BODY PARAMS
| Field | Type | Description | Characters |
|-------------------------|--------|------------------------------------------------------------------------------------|-----------------------------------------------------|
| `request_control_key` * | string | Unique request identification key used by the client in uuid v4 format. | 36 |
| `target_account` * | object | Target account. | **[Object target_account](#object-target_account)** |
| `transaction_amount` * | float | Transaction amount. | 10 |
## Object target_account
| Field | Type | Description | Characters |
|---------------------------|--------|-----------------------------------------------------|-----------------------------------------------------------|
| `account_branch` * | string | Agency. | 4 |
| `account_digit` * | string | Account digit. | 1 |
| `account_number` * | string | Account number. | 20 |
| `owner_document_number` * | string | CPF or CNPJ (numbers only) of account owner. | 14 |
| `owner_name` * | string | Account owner name. | 50 |
| `account_type`* | string | Account type. | **[Enumerador account_type](#enumerador-account_type)** |
| `ispb` * | string | Based on the financial institution's CNPJ (8 digits). | 8 |
## Enumerator account_type
| Enumerator | Translation (PT-BR) |
|------------------------|-----------------------|
| **checking_account** | conta corrente |
| **deposit_account** | conta depósito |
| **guaranteed_account** | conta de garantia |
| **investment_account** | conta de investimento |
| **payment_account** | conta de pagamento |
| **saving_account** | conta poupança |
## Response
STATUS 201
Response Body
```json
{
"request_control_key": "0c3d2a3e-c121-464e-b5a4-8e69e0c17bbd",
"ted_key": "8cb70dea-9fb0-4a68-9572-99a72849c8d6",
"created_at": "2021-10-22T20:30:23.459Z",
"ted_status": "sent",
"transaction_amount": 126.97,
"fee_amount": 0.0
}
```
STATUS 4xx
Response Body: Error
```json
{
"title": "Error title",
"description": "description in English",
"translation": "description in Portuguese",
"code": "Code",
"extra_fields": {}
}
```
| HTTP Code `status` | QI Code `code` | Title `title` | Description (en) `description` | Description in Portuguese `translation` |
|--------------------------|----------------------|-----------------------------|-------------------------------------------------------------------------------------------------------------------------|------------------------------------------------------------------------------------------------------------------------|
| 400 | QIT000001 | Bad Request | Schema Error | Erro de Schema |
| 400 | TED000066 | InvalidUuid | request_control_key was not accepted for not being a valid uuid v4 string | request_control_key não foi aceito por não ser uma palavra uuid v4 válida |
| 400 | TED000011 | InvalidUuid | Wrong day/time for TED | Dia/hora incorretos para a TED |
| 400 | TED000055 | Invalid Observation | Observation sent is invalid | Observação enviada é inválida |
| 400 | TED000054 | Invalid Transaction Amount | Transaction amount of \{transaction_amount\} is not valid. It must be a positive value with at maximum 2 decimal places | O valor de transação \{transaction_amount\} não é válido. Deve ser um valor positivo com no máximo duas casas decimais |
| 400 | TED000012 | Bad Request | The target's length of the account + account_digit cannot be larger than 21 | O número de digitos na conta de destino + digito não pode ser maior que 21 |
| 400 | TED000053 | Invalid Target Account Type | Target Account Type \{account_type\} is invalid | Tipo de conta destino \{account_type\} é inválido |
| 400 | TED000031 | Bad Request | ISPB number \{ispb\} does not exist or is inactive | ISPB \{ispb\} não existe ou está inativo |
| 400 | TED000065 | Bad Request | It has been identified by request_control_key that this request is already being processed | Foi identificado por request_control_key que está requisição está sendo processada |
| 403 | TED000071 | Invalid target account | Invalid target account | Conta destino inválida |
| 400 | TED000058 | Bad Request | Insufficient account balance for transfer and fee amount | Saldo de conta insuficiente para a transação e a taxa |
| 400 | TED000070 | Bad Request | Insufficient account balance fee amount in billing account | Saldo de conta centralizadora insuficiente para taxa |
| 400 | TED000071 | Bad Request | Transaction cannot be made due to already blocked balance | Transação não pode ser feita pois saldo em conta bloqueado |
| 400 | TED000068 | Bad Request | Transfer rejected by the system | transferêancia foi recusada pelo sistema |
| 404 | TED000013 | Bad Request | Unable to find source_account_key's account | Não foi possível encontrar a conta com source_account_key fornecido |
| 400 | TED000015 | Bad Request | Account blocked or closed can not perform this action | A conta bloqueada ou fechada não pode executar esta ação |
| 400 | TED000016 | Bad Request | Hub account can not perform this action | A conta hub não pode executar esta ação |
| 403 | TED000017 | Unauthorized | Provided account does not have approval credential for the given person | A conta fornecida não possui credencial de aprovação para a pessoa especificada |
| 403 | TED000018 | Unauthorized | Provided account not owned by SELECTED_AGENT | Conta fornecida não pertencente ao SELECTED_AGENT |
| 400 | TED000060 | Bad Request | Billing Account is closed | Conta centralizadora de pagamentos de tarifa fechada |
| 400 | TED000061 | Bad Request | Billing Account without necessary funds | Conta centralizadora de pagamentos sem saldo necessário |
| 409 | TED000064 | Bad Request | request_control_key \{request_control_key\} already in use | request_control_key \{request_control_key\} já utilizada |
---
# Approve TED Transaction Scheduling with Two-Factor Authentication
URL: /en/documentation/baas/ted/schedule_2fa/aprovacao_de_agendamento_2fa
## Request
ENDPOINT /account/ ACCOUNT_KEY /ted_schedule/ SCHEDULE_KEY /validate_token
METHOD PUT
### Path Params
| Field | Type | Description | Characters |
|----------------|--------|---------------------------------------------|------------|
| `account_key` | uuidv4 | Unique account identification key. | 36 |
| `schedule_key` | uuidv4 | Unique scheduling identification key. | 36 |
## Authentication via Email and SMS
Request Body
```json
{
"token": "329123"
}
```
## Authentication via Device
To approve and finalize device authentication, the request must be sent with an empty payload. Validation occurs internally, with no additional information required in the request body. Note that this endpoint should only be used after the [scheduling request](./solicitacao_de_agendamento_2fa.md) has been initiated.
Request Body
```json
{
}
```
## Body Params
| Field | Type | Description | Characters |
|----------|--------|------------------------------------------------------------------------------------------------------|------------|
| `token` | string | Authentication code sent to the account's transaction approver **required for TFA via SMS or email** | 6 |
## Response
STATUS 201
Response Body: Scheduling Approved
```json
{
"request_control_key": "b6804f32-101e-4702-8fbc-c2dbc4c2caec",
"schedule_key": "f64b3fa7-d09d-4927-ad4f-b966df9fb153",
"schedule_status": "scheduled",
"schedule_date": "2024-12-31"
}
```
STATUS 4xx
Response Body: Error
```json
{
"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 (ptbr) `translation` |
|--------------------------|----------------------|----------------------------------------------|-----------------------------------------------------------------------------------|---------------------------------------------------------------------------------|
| 400 | QIT000001 | Bad Request | schema error description | Schema Inválido |
| 404 | TED000009 | Not Found | Account not found for the given key: \{account_key\} | Conta não encontrada para a chave fornecida: \{account_key\} |
| 403 | TED000018 | Unauthorized | Provided account not owned by SELECTED_AGENT | Conta fornecida não pertencente ao SELECTED_AGENT |
| 400 | TED000082 | Number of token validation attempts exceeded | The maximum number of failed token validation attempts has been reached | Número máximo de tentativas de validação de token atingida |
| 400 | TED000083 | Token Expired | Token has expired. Resend token or recreate transfer | Token expirado. Reenvie token ou recrie a transferência |
| 400 | TED000084 | Incorrect Token | Token sent does not match expected | Token enviado não condiz com, o esperado |
| 400 | TED000085 | Error Validating Token | An error occurred while validating token and it is being investigated | Um erro ocorreu ao validar token e está sendo investigado |
| 400 | TED000086 | Invalid Status | Ted not in pending_2fa_approval status | Ted não está pendente de aprovação por autenticação de dois fatores |
| 404 | TED000093 | TedSchedule not Found | TedSchedule was not found | TedSchedule não encontrada |
| 400 | TED000096 | Bad Request | Action cannot be taken place as there is currently a pending transfer in progress | A ação não pôde ser completada como há uma transferência pendente |
| 400 | TED000099 | Invalid Status | Ted Schedule not in pending_2fa_approval status | Agendamento Ted não está pendente de aprovação por autenticação de dois fatores |
| 400 | TED000100 | Invalid Schedule Date | Schedule must be approved before the scheduled date | Agendamento deve ser aprovado em data anterior à programada para transação || 400 | TED000110 | Token Required | A token is required for SMS or email validation. | Um token é necessário para validação via SMS ou email. |
---
# Introduction to Two-Factor Authentication
URL: /en/documentation/baas/ted/schedule_2fa/introducao_a_agendamento_2fa
In this type of scheduling, it is necessary to confirm the payment programming via token sent to the person with powers to approve account movements in the crediting account.
The TED scheduling request by integrating partners configured to use two-factor authentication is performed similarly to what is described in [request TED transaction scheduling](/documentation/baas/ted/schedule/solicitacao_de_agendamento). The difference occurs in the addition of the `tfa_info` object, containing information about the transfer approver and the contact method, and the status of a successful request which will always be **pending_2fa_approval**.
The same applies to TED batch scheduling described in [request TED transaction scheduling in batch](/documentation/baas/ted/schedule_batch/solicitacao_de_agendamento_em_lote).
## Flow for a TED scheduling with authorization
The successful TED scheduling will follow the following process flow:
Execution of the [TED transaction request](/documentation/baas/ted/schedule/solicitacao_de_agendamento_2fa) and receiving a synchronous response with **pending_2fa_approval** status and `schedule_key` value.
The indicated approver will receive a 6-digit `token` composed of numbers.
The requester performs the [TED transaction confirmation](/documentation/baas/ted/schedule/aprovacao_de_agendamento_2fa) with the `schedule_key` and the `token`.
The scheduling will then be updated to **scheduled** status.
## Observations
Each scheduling has a maximum limit of 5 `token` validation attempts. When this limit is reached, the scheduling will be automatically set to rejected status (**rejected**).
Each `token` has a maximum duration of 5 minutes.
A scheduling can have its `token` renewed and resent to the transfer approver. This process restarts the 5-minute timer and does not restart the invalid attempts counter. The previous `token` becomes invalid.
The notification event for sending the `token` to the approver is **baas.token_validation.ted.schedule.single**. It is possible to [customize](/documentation/notificacoes/template) the message sent.
The implemented token sending methods (`contact_type`) are by **sms** and **email**.
---
# Request TED Transaction Scheduling with Two-Factor Authentication
URL: /en/documentation/baas/ted/schedule_2fa/solicitacao_de_agendamento_2fa
## Request
ENDPOINT /account/ ACCOUNT_KEY /ted_schedule
METHOD POST
## Authentication via Email and SMS
Request Body: Scheduling with TFA via SMS or Email
```json
{
"request_control_key": "0c3d2a3e-c121-464e-b5a4-8e69e0c17bbd",
"target_account": {
"account_branch": "0001",
"account_number": "92796",
"account_digit": "1",
"owner_document_number": "23599885000192",
"owner_name": "Titular da Conta",
"ispb": "12345678",
"account_type": "checking_account"
},
"transaction_amount": 8.86,
"schedule_date": "2024-12-01",
"tfa_info": {
"approver_document_number": "98765432100",
"contact_type": "email"
}
}
```
## Authentication via Device
In addition to the existing authentication methods via **sms** and **email**, it is possible to authenticate the transaction using a previously [registered device](/documentation/baas/dispositivo/create/solicitacao_cadastro_dispositivo). In this case, the `session_id` must be obtained in the **Device Scan** and sent in `tfa_info`.
Request Body: Scheduling with TFA via Device
```json
{
"request_control_key": "0c3d2a3e-c121-464e-b5a4-8e69e0c17bbd",
"target_account": {
"account_branch": "0001",
"account_number": "92796",
"account_digit": "1",
"owner_document_number": "23599885000192",
"owner_name": "Titular da Conta",
"ispb": "12345678",
"account_type": "checking_account"
},
"transaction_amount": 8.86,
"schedule_date": "2024-12-01",
"tfa_info": {
"approver_document_number": "98765432100",
"session_id": "b2f18d3a-67c2-4a7f-98e5-1d3f5c6b8a72",
"contact_type": "device"
}
}
```
## Body Params
| Field | Type | Description | Characters |
|-------------------------|--------|------------------------------------------------------------------------------------|-----------------------------------------------------|
| `request_control_key` * | string | Unique request identification key used by the client in uuid v4 format. | 36 |
| `target_account` * | object | Target account | **[target_account Object](#target_account-object)** |
| `transaction_amount` * | float | Transfer amount | 10 |
| `schedule_date`* | string | Date when the transaction will be executed. | 10 |
| `tfa_info`* | Object | Object containing the account approver's document and contact method. | **[tfa_info Object](#tfa_info-object)** |
## tfa_info Object
| Field | Type | Description | Characters |
|------------------------------|--------|-----------------------------------------------------------------------------------------------|------------|
| `approver_document_number` * | string | Account approver's document number. | 11 |
| `session_id` | string | Unique device session identification key in UUID v4 format (required for device TFA). | 36 |
| `contact_type` * | string | Contact method for the account approver, can be **sms**, **email** or **device** | |
## target_account Object
| Field | Type | Description | Characters |
|---------------------------|--------|-----------------------------------------------------|---------------------------------------------------------|
| `account_branch` * | string | Branch. | 4 |
| `account_digit` * | string | Account digit | 1 |
| `account_number` * | string | Account number. | 20 |
| `owner_document_number` * | string | CPF or CNPJ (numbers only) of the account holder. | 14 |
| `owner_name` * | string | Account holder's name. | 50 |
| `account_type`* | string | Account type. | **[account_type Enumerator](#account_type-enumerator)** |
| `ispb` * | string | Based on the financial institution's CNPJ (8 digits). | 8 |
## account_type Enumerator
| Enumerator | Translation |
|------------------------|-----------------------|
| **checking_account** | checking account |
| **deposit_account** | deposit account |
| **guaranteed_account** | guaranteed account |
| **investment_account** | investment account |
| **payment_account** | payment account |
| **saving_account** | savings account |
## Response
STATUS 202
Response Body: Schedule Created
```json
{
"request_control_key": "b6804f32-101e-4702-8fbc-c2dbc4c2caec",
"schedule_key": "f64b3fa7-d09d-4927-ad4f-b966df9fb153",
"schedule_status": "pending_2fa_approval",
"schedule_date": "2024-12-31"
}
```
STATUS 4xx
Response Body: Error
```json
{
"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 (ptbr) `translation` |
|--------------------------|----------------------|-----------------------------------------------------|--------------------------------------------------------------------------------------------|------------------------------------------------------------------------------------|
| 400 | QIT000001 | Bad Request | schema error description | Schema Inválido |
| 404 | TED000006 | Target account Not Found | Target account was not found for given parameters | Conta destino não encontrada para os parâmetros informados |
| 404 | TED000009 | Not Found | Account not found for the given key: \{account_key\} | Conta não encontrada para a chave fornecida: \{account_key\} |
| 403 | TED000014 | Invalid target account | Invalid target account | Conta destino inválida |
| 400 | TED000015 | Bad Request | Account blocked or closed can not perform this action | A conta bloqueada ou fechada não pode executar esta ação |
| 400 | TED000016 | Bad Request | Hub account can not perform this action | A conta hub não pode executar esta ação |
| 403 | TED000018 | Unauthorized | Provided account not owned by SELECTED_AGENT | Conta fornecida não pertencente ao SELECTED_AGENT |
| 400 | TED000031 | Bad Request | ISPB number \{ispb\} does not exist or is inactive | ISPB \{ispb\} não existe ou está inativo |
| 400 | TED000044 | Invalid Timestamp Format sent | Given parameter is not in the correct format \{timestamp_format\} | Parametro enviado não está no formato correto \{timestamp_format\} |
| 400 | TED000046 | Invalid uuid v4 string sent | \{key\} was not accepted for not being a valid uuid v4 string | \{key\} não foi aceito por não ser uma palavra uuid v4 válida |
| 400 | TED000054 | Invalid Transaction Amount | Transaction Amount \{transaction_amount\} is invalid | Valor de transação \{transaction_amount\} é inválido |
| 400 | TED000057 | Invalid Document Number | Given \{document_number\} document number is invalid | CPF/CNPJ \{document_number\} fornecido não é valido |
| 409 | TED000064 | Bad Request | request_control_key \{request_control_key\} already in use | request_control_key \{request_control_key\} já utilizada |
| 400 | TED000065 | Bad Request | It has been identified by request_control_key that this request is already being processed | Foi identificado por request_control_key que está requisição está sendo processada |
| 403 | TED000079 | No approver permission | Given document number does not belong to an approver for this account | Número de documento enviado não pertence a um aprovador da conta |
| 400 | TED000080 | tfa_info is required | Client must send object tfa_info | Cliente deve enviar objeto tfa_info |
| 400 | TED000081 | Error occurred while sending token | An unexpected error occurred while sending token | Um erro inexperado ocorreu ao tentar enviar token |
| 400 | TED000089 | Invalid Schedule Date | Schedule date must be after current date for UTC-3 | Data de agendamento deve ser após a data atual em UTC-3 |
| 400 | TED000090 | Invalid Schedule Date | Schedule date must be a workday | Data de agendamento deve ser um dia útil |
| 400 | TED000091 | Target Account and Source Account must be different | Target Account must not be the same as Source Account | A conta de destino não pode ser a mesma da conta de origem |
---
# Request token resend for a schedule
URL: /en/documentation/baas/ted/schedule_2fa/solicitacao_de_reenvio_de_token_para_agendamento_2fa
A new token will be generated and sent to the ted schedule approver. If the maximum number of token validation attempts
has been exceeded, resending will not be allowed.
## Request
ENDPOINT /account/ ACCOUNT_KEY /ted_schedule/ SCHEDULE_KEY /resend_token
METHOD PATCH
### Path Params
| Field | Type | Description | Characters |
|----------------|--------|----------------------------------------------|------------|
| `account_key` | uuidv4 | Unique account identification key. | 36 |
| `schedule_key` | uuidv4 | Unique schedule identification key. | 36 |
## Body Params
| Field | Type | Description | Characters |
|----------------|------------|---------------------------------------------|---------------------------------------------------------|
| `contact_type` | enumerator | Authentication token delivery method | **[Enumerator contact_type](#enumerator-contact_type)** |
:::info Information
If no `contact_type` is sent, the token will be sent using the originally requested method.
:::
### Enumerator contact_type
| Enumerator | Description |
|------------|-----------------------------------------------|
| **sms** | Sent via Text Message to mobile phone |
| **email** | Sent via email |
## Response
STATUS 202
Response Body: Transaction Requested
```json
{
"request_control_key": "b6804f32-101e-4702-8fbc-c2dbc4c2caec",
"schedule_key": "f64b3fa7-d09d-4927-ad4f-b966df9fb153",
"schedule_status": "pending_2fa_approval",
"schedule_date": "2024-12-31"
}
```
STATUS 4xx
Response Body: Transfer Rejected
```json
{
"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 (ptbr) `translation` |
|--------------------------|----------------------|----------------------------------------------|-----------------------------------------------------------------------------------|---------------------------------------------------------------------------------|
| 400 | QIT000001 | Bad Request | schema error description | Schema Inválido |
| 404 | TED000009 | Not Found | Account not found for the given key: \{account_key\} | Conta não encontrada para a chave fornecida: \{account_key\} |
| 403 | TED000018 | Unauthorized | Provided account not owned by SELECTED_AGENT | Conta fornecida não pertencente ao SELECTED_AGENT |
| 400 | TED000082 | Number of token validation attempts exceeded | The maximum number of failed token validation attempts has been reached | Número máximo de tentativas de validação de token atingida |
| 400 | TED000086 | Invalid Status | Ted not in pending_2fa_approval status | Ted não está pendente de aprovação por autenticação de dois fatores |
| 400 | TED000087 | Error Sending Token | An error occurred while resending token and its being investigated | Um erro ocorreu ao reenviar token e está sendo investigado |
| 404 | TED000093 | TedSchedule not Found | TedSchedule was not found | TedSchedule não encontrada |
| 400 | TED000096 | Bad Request | Action cannot be taken place as there is currently a pending transfer in progress | A ação não pôde ser completada como há uma transferência pendente |
| 400 | TED000099 | Invalid Status | Ted Schedule not in pending_2fa_approval status | Agendamento Ted não está pendente de aprovação por autenticação de dois fatores |
| 400 | TED000100 | Invalid Schedule Date | Schedule must be approved before the scheduled date | Agendamento deve ser aprovado em data anterior à programada para transação |
---
# Approve TED Transaction Batch Schedule with Two-Factor Authentication
URL: /en/documentation/baas/ted/schedule_batch_2fa/aprovacao_de_agendamento_em_lote_2fa
## Request
ENDPOINT /account/ ACCOUNT_KEY /ted_schedule_batch/ SCHEDULE_BATCH_KEY /validate_token
METHOD PUT
### Path Params
| Field | Type | Description | Characters |
|----------------------|--------|------------------------------------------------------|------------|
| `account_key` | uuidv4 | Unique account identification key. | 36 |
| `schedule_batch_key` | uuidv4 | Unique batch schedule identification key. | 36 |
## Authentication via Email and SMS
Request Body
```json
{
"token": "329123"
}
```
## Authentication via Device
To approve and finalize device authentication, the request must be sent with an empty payload. Validation occurs internally, with no additional information required in the request body. Note that this endpoint should only be used after the [batch scheduling request](./solicitacao_de_agendamento_em_lote_2fa.md) has been initiated.
Request Body
```json
{
}
```
## Body Params
| Field | Type | Description | Characters |
|----------|--------|------------------------------------------------------------------------------------------------------|------------|
| `token` | string | Authentication code sent to the account transaction approver **required for TFA via SMS or email** | 6 |
## Response
STATUS 201
Response Body: Approved Batch Schedule
```json
{
"request_control_key": "b6804f32-101e-4702-8fbc-c2dbc4c2caec",
"schedule_batch_key": "f64b3fa7-d09d-4927-ad4f-b966df9fb153",
"schedule_batch_status": "approved",
"created_at": "2023-03-13T19:00:28.440Z"
}
```
STATUS 4xx
Response Body: Error
```json
{
"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 (ptbr) `translation` |
|------------------------|--------------------|----------------------------------------------|----------------------------------------------------------------------------------------------------------------------|----------------------------------------------------------------------------------------------------------------------|
| 400 | QIT000001 | Bad Request | schema error description | Schema Inválido |
| 404 | TED000009 | Not Found | Account not found for the given key: \{account_key\} | Conta não encontrada para a chave fornecida: \{account_key\} |
| 403 | TED000018 | Unauthorized | Provided account not owned by SELECTED_AGENT | Conta fornecida não pertencente ao SELECTED_AGENT |
| 400 | TED000082 | Number of token validation attempts exceeded | The maximum number of failed token validation attempts has been reached | Número máximo de tentativas de validação de token atingida |
| 400 | TED000083 | Token Expired | Token has expired. Resend token or recreate transfer | Token expirado. Reenvie token ou recrie a transferência |
| 400 | TED000084 | Incorrect Token | Token sent does not match expected | Token enviado não condiz com, o esperado |
| 400 | TED000085 | Error Validating Token | An error occurred while validating token and it is being investigated | Um erro ocorreu ao validar token e está sendo investigado |
| 400 | TED000102 | Invalid Status | Ted Batch not in pending_2fa_approval status | Lote de Ted não está pendente de aprovação por autenticação de dois fatores |
| 404 | TED000103 | ScheduleBatch not Found | Ted Schedule Batch was not found | Agendamento de Ted em lote não encontrado |
| 400 | TED000106 | Invalid Status | ScheduleBatch not in pending_2fa_approval status | Lote Agendamentos de Ted não está pendente de aprovação por autenticação de dois fatores |
| 400 | TED000107 | Schedule Batch could not be approved | ScheduleBatch could not be approved due to current date being equal or after earliest schedule date. Rejecting batch | ScheduleBatch não pode ser aprovada devido a data atual ser superior ou igual à menor schedule_date. Rejeitando lote || 400 | TED000110 | Token Required | A token is required for SMS or email validation. | Um token é necessário para validação via SMS ou email. |
---
# Request TED Batch Transaction Scheduling
URL: /en/documentation/baas/ted/schedule_batch_2fa/solicitacao_de_agendamento_em_lote_2fa
QI Tech offers the possibility to perform multiple scheduled TED transactions with a single call. If the initial call returns an HTTP status 4xx, none of the schedules will be performed.
In this type of scheduling, it is necessary to confirm the payment scheduling via token sent to the person with powers to approve account movements in the creditor account.
The request for batch TED scheduling by integrating partners configured to use two-factor authentication is performed similarly to what is described in [request batch TED transaction scheduling](/documentation/baas/ted/schedule/solicitacao_de_agendamento_em_lote).
The difference occurs in adding the `tfa_info` object, containing information about the transfer approver and the contact method, and the status of a successful request which will always be **pending_2fa_approval**.
The notification event for sending the `token` to the approver is **baas.token_validation.ted.schedule.batch**. It is possible to [customize](/documentation/notificacoes/template) the message sent.
## Request
ENDPOINT /account/ ACCOUNT_KEY /ted_schedule_batch
METHOD POST
## Authentication via Email and SMS
Request Body: Batch Scheduling with TFA via SMS or Email
```json
{
"request_control_key": "6e4fc980-f8a1-4462-b6e2-d8a49f0ac055",
"ted_schedules": [
{
"request_control_key": "0c3d2a3e-c121-464e-b5a4-8e69e0c17bbd",
"target_account": {
"account_branch": "0001",
"account_number": "92796",
"account_digit": "1",
"owner_document_number": "23599885000192",
"owner_name": "Titular da Conta",
"ispb": "12345678",
"account_type": "checking_account"
},
"transaction_amount": 8.86,
"schedule_date": "2024-12-01"
}
],
"tfa_info": {
"approver_document_number": "98765432100",
"contact_type": "email"
}
}
```
## Authentication via Device
In addition to the existing authentication methods via **sms** and **email**, it is possible to authenticate the transaction using a previously [registered device](/documentation/baas/dispositivo/create/solicitacao_cadastro_dispositivo). In this case, the `session_id` must be obtained in the **Device Scan** and sent in `tfa_info`.
Request Body: Batch Scheduling with TFA via Device
```json
{
"request_control_key": "6e4fc980-f8a1-4462-b6e2-d8a49f0ac055",
"ted_schedules": [
{
"request_control_key": "0c3d2a3e-c121-464e-b5a4-8e69e0c17bbd",
"target_account": {
"account_branch": "0001",
"account_number": "92796",
"account_digit": "1",
"owner_document_number": "23599885000192",
"owner_name": "Titular da Conta",
"ispb": "12345678",
"account_type": "checking_account"
},
"transaction_amount": 8.86,
"schedule_date": "2024-12-01"
}
],
"tfa_info": {
"approver_document_number": "98765432100",
"session_id": "b2f18d3a-67c2-4a7f-98e5-1d3f5c6b8a72",
"contact_type": "device"
}
}
```
## Path Params
| Field | Type | Description | Characters |
|---------------|--------|----------------------------------------|------------|
| `account_key` | uuidv4 | Unique account identification key. | 36 |
## Body Params
| Field | Type | Description | Characters |
|-------------------------|--------|-----------------------------------------------------------------------------------|----------------------------------------------------------|
| `request_control_key` * | uuidv4 | Unique request identification key used by the client in uuid v4 format. | 36 |
| `ted_schedules` * | array | List of ted_schedule objects linked to the batch. | list of **[ted_schedule Object](#ted_schedule-object)** |
| `tfa_info`* | Object | Object containing the account approver's document and contact method. | **[tfa_info Object](#tfa_info-object)** |
## tfa_info Object
| Field | Type | Description | Characters |
|------------------------------|--------|-----------------------------------------------------------------------------------------------|------------|
| `approver_document_number` * | string | Account approver's document number. | 11 |
| `session_id` | string | Unique device session identification key in UUID v4 format (required for device TFA). | 36 |
| `contact_type` * | string | Contact method with the account approver, can be **sms**, **email** or **device** | |
## ted_schedule Object
| Field | Type | Description | Characters |
|-------------------------|--------|-----------------------------------------------------------------------------------|---------------------------------------------------------|
| `request_control_key` * | string | Unique request identification key used by the client in uuid v4 format. | 36 |
| `target_account` * | object | Target account | **[target_account Object](#target_account-object)** |
| `transaction_amount` * | float | Transfer amount | 10 |
| `schedule_date`* | string | Date when the transaction should be performed. | 10 |
## target_account Object
| Field | Type | Description | Characters |
|---------------------------|--------|-----------------------------------------------------|---------------------------------------------------------|
| `account_branch` * | string | Branch. | 4 |
| `account_digit` * | string | Account digit | 1 |
| `account_number` * | string | Account number. | 20 |
| `owner_document_number` * | string | CPF or CNPJ (numbers only) of the account holder. | 14 |
| `owner_name` * | string | Account holder's name. | 50 |
| `account_type`* | string | Account type. | **[account_type Enumerator](#account_type-enumerator)** |
| `ispb` * | string | Based on financial institution's CNPJ (8 digits). | 8 |
## account_type Enumerator
| Enumerator | Translation |
|------------------------|-----------------------|
| **checking_account** | checking account |
| **deposit_account** | deposit account |
| **guaranteed_account** | guaranteed account |
| **investment_account** | investment account |
| **payment_account** | payment account |
| **saving_account** | savings account |
## Response
STATUS 202
Response Body: Batch Scheduling Requested
```json
{
"request_control_key": "b6804f32-101e-4702-8fbc-c2dbc4c2caec",
"schedule_batch_key": "8cb70dea-9fb0-4a68-9572-99a72849c8d6",
"schedule_batch_status": "pending_2fa_approval",
"created_at": "2021-10-22T20:30:23.459Z"
}
```
### schedule_batch_status Enumerator
| Enumerator | Description |
|--------------------------|----------------------------------------------------------|
| **created** | Batch scheduling created |
| **approved** | Batch scheduling approved |
| **rejected** | Batch scheduling rejected |
| **pending_2fa_approval** | Batch scheduling pending two-factor authentication approval |
STATUS 4xx
Response Body: Error
```json
{
"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 (ptbr) `translation` |
|--------------------------|----------------------|-----------------------------------------------------|--------------------------------------------------------------------------------------------|------------------------------------------------------------------------------------|
| 400 | QIT000001 | Bad Request | schema error description | Schema Inválido |
| 404 | TED000006 | Target account Not Found | Target account was not found for given parameters | Conta destino não encontrada para os parâmetros informados |
| 404 | TED000009 | Not Found | Account not found for the given key: \{account_key\} | Conta não encontrada para a chave fornecida: \{account_key\} |
| 403 | TED000014 | Invalid target account | Invalid target account | Conta destino inválida |
| 400 | TED000015 | Bad Request | Account blocked or closed can not perform this action | A conta bloqueada ou fechada não pode executar esta ação |
| 400 | TED000016 | Bad Request | Hub account can not perform this action | A conta hub não pode executar esta ação |
| 403 | TED000018 | Unauthorized | Provided account not owned by SELECTED_AGENT | Conta fornecida não pertencente ao SELECTED_AGENT |
| 400 | TED000031 | Bad Request | ISPB number \{ispb\} does not exist or is inactive | ISPB \{ispb\} não existe ou está inativo |
| 400 | TED000044 | Invalid Timestamp Format sent | Given parameter is not in the correct format \{timestamp_format\} | Parametro enviado não está no formato correto \{timestamp_format\} |
| 400 | TED000045 | Search Params Error | Invalid integer value for page or size querystring parameters | Valor inválido para parâmetros de página ou tamanho de página |
| 400 | TED000046 | Invalid uuid v4 string sent | \{key\} was not accepted for not being a valid uuid v4 string | \{key\} não foi aceito por não ser uma palavra uuid v4 válida |
| 400 | TED000054 | Invalid Transaction Amount | Transaction Amount \{transaction_amount\} is invalid | Valor de transação \{transaction_amount\} é inválido |
| 400 | TED000057 | Invalid Document Number | Given \{document_number\} document number is invalid | CPF/CNPJ \{document_number\} fornecido não é valido |
| 409 | TED000064 | Bad Request | request_control_key \{request_control_key\} already in use | request_control_key \{request_control_key\} já utilizada |
| 400 | TED000065 | Bad Request | It has been identified by request_control_key that this request is already being processed | Foi identificado por request_control_key que está requisição está sendo processada |
| 403 | TED000079 | No approver permission | Given document number does not belong to an approver for this account | Número de documento enviado não pertence a um aprovador da conta |
| 400 | TED000080 | tfa_info is required | Client must send object tfa_info | Cliente deve enviar objeto tfa_info |
| 400 | TED000081 | Error occurred while sending token | An unexpected error occurred while sending token | Um erro inexperado ocorreu ao tentar enviar token |
| 400 | TED000089 | Invalid Schedule Date | Schedule date must be after current date for UTC-3 | Data de agendamento deve ser após a data atual em UTC-3 |
| 400 | TED000090 | Invalid Schedule Date | Schedule date must be a workday | Data de agendamento deve ser um dia útil |
| 400 | TED000091 | Target Account and Source Account must be different | Target Account must not be the same as Source Account | A conta de destino não pode ser a mesma da conta de origem |
---
# Request Token Resend for a TED Batch Transaction Schedule
URL: /en/documentation/baas/ted/schedule_batch_2fa/solicitacao_de_reenvio_de_token_para_agendamento_em_lote_2fa
A new token will be generated and sent to the TED schedule approver. If the token validation attempt limit has been exceeded, resending will not be allowed.
## Request
ENDPOINT /account/ ACCOUNT_KEY /ted_schedule_batch/ SCHEDULE_BATCH_KEY /resend_token
METHOD PATCH
### Path Params
| Field | Type | Description | Characters |
|----------------------|--------|--------------------------------------------------|------------|
| `account_key` | uuidv4 | Unique account identification key. | 36 |
| `schedule_batch_key` | uuidv4 | Unique batch schedule identification key. | 36 |
## Body Params
| Field | Type | Description | Characters |
|----------------|------------|------------------------------------------|---------------------------------------------------------|
| `contact_type` | enumerator | Authentication token sending method | **[Enumerator contact_type](#enumerador-contact_type)** |
:::info Information
If no `contact_type` is sent, the token will be sent using the originally requested method.
:::
### Enumerator contact_type
| Enumerator | Description |
|------------|---------------------------------------------------|
| **sms** | Sending via Text Message to mobile phone |
| **email** | Sending via electronic mail |
## Response
STATUS 202
Response Body: Batch Schedule Requested
```json
{
"request_control_key": "b6804f32-101e-4702-8fbc-c2dbc4c2caec",
"schedule_batch_key": "8cb70dea-9fb0-4a68-9572-99a72849c8d6",
"schedule_batch_status": "pending_2fa_approval",
"created_at": "2021-10-22T20:30:23.459Z"
}
```
STATUS 4xx
Response Body: Transfer Rejected
```json
{
"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 (ptbr) `translation` |
|------------------------|--------------------|------------------------------------- |----------------------------------------------------------------------------------------------------------------------|----------------------------------------------------------------------------------------------------------------------|
| 400 | QIT000001 | Bad Request | schema error description | Schema Inválido |
| 404 | TED000009 | Not Found | Account not found for the given key: \{account_key\} | Conta não encontrada para a chave fornecida: \{account_key\} |
| 403 | TED000018 | Unauthorized | Provided account not owned by SELECTED_AGENT | Conta fornecida não pertencente ao SELECTED_AGENT |
| 400 | TED000087 | Error Sending Token | An error occurred while resending token and its being investigated | Um erro ocorreu ao reenviar token e está sendo investigado |
| 404 | TED000103 | ScheduleBatch not Found | Ted Schedule Batch was not found | Agendamento de Ted em lote não encontrado |
| 400 | TED000106 | Invalid Status | ScheduleBatch not in pending_2fa_approval status | Lote Agendamentos de Ted não está pendente de aprovação por autenticação de dois fatores |
| 400 | TED000107 | Schedule Batch could not be approved | ScheduleBatch could not be approved due to current date being equal or after earliest schedule date. Rejecting batch | ScheduleBatch não pode ser aprovada devido a data atual ser superior ou igual à menor schedule_date. Rejeitando lote |
---
# Cancel TED Batch Schedule Transaction
URL: /en/documentation/baas/ted/schedule_batch/cancelamento_de_agendamento_em_lote
## Request
ENDPOINT /account/ ACCOUNT_KEY /ted_schedule_batch/ SCHEDULE_BATCH_KEY /cancel
METHOD PATCH
### Path Params
| Field | Type | Description | Characters |
|----------------------|--------|------------------------------------------------|------------|
| `account_key` | uuidv4 | Unique account identification key. | 36 |
| `schedule_batch_key` | uuidv4 | Unique schedule batch identification key | 36 |
### Response
STATUS 200
Response Body: Cancelled Schedule
```json
{
"request_control_key": "b6804f32-101e-4702-8fbc-c2dbc4c2caec",
"schedule_batch_key": "f64b3fa7-d09d-4927-ad4f-b966df9fb153",
"schedule_batch_status": "cancelled",
"created_at": "2023-03-13T19:00:28.440Z"
}
```
STATUS 4xx
Response Body: Error
```json
{
"title": "titulo",
"description": "description in English",
"translation": "descrição em portugues",
"code": "codigo",
"extra_fields": {}
}
```
STATUS 4xx
Response Body: Error
```json
{
"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 (ptbr) `translation` |
|------------------------|--------------------|---------------------------------------|------------------------------------------------------------------------------------------------------------------------------------|---------------------------------------------------------------------------------------------------------------------------------------------|
| 400 | QIT000001 | Bad Request | schema error description | Schema Inválido |
| 404 | TED000009 | Not Found | Account not found for the given key: \{account_key\} | Conta não encontrada para a chave fornecida: \{account_key\} |
| 403 | TED000018 | Unauthorized | Provided account not owned by SELECTED_AGENT | Conta fornecida não pertencente ao SELECTED_AGENT |
| 400 | TED000096 | Bad Request | Action cannot be taken place as there is currently a pending transfer in progress | A ação não pôde ser completada como há uma transferência pendente |
| 404 | TED000101 | TedBatch not Found | TedBatch was not found | TedBatch não encontrada |
| 404 | TED000103 | ScheduleBatch not Found | Ted Schedule Batch was not found | Agendamento de Ted em lote não encontrado |
| 400 | TED000104 | Invalid Status | Schedule Batch cannot be cancelled in current status | Lote de agendamento não pode ser cancelado no status atual |
| 400 | TED000105 | Schedule Batch could not be cancelled | ScheduleBatch could not be cancelled due to current date being equal or after earliest schedule date. Cancel schedules one by one | ScheduleBatch não pode ser cancelada devido a data atual ser superior ou igual à menor schedule_date. Cancele agendamentos individualmente |
---
# List Schedules from a Schedule Batch
URL: /en/documentation/baas/ted/schedule_batch/listar_agendamentos_de_um_lote
## Request
ENDPOINT /account/ ACCOUNT_KEY /ted_schedule_batch/ SCHEDULE_BATCH_KEY /ted_schedules
METHOD GET
### Path Params
| Field | Type | Description | Characters |
|----------------------|--------|-------------------------------------------------------|------------|
| `account_key` | uuidv4 | Unique identifier key of the account. | 36 |
| `schedule_batch_key` | uuidv4 | Unique identifier key of the schedule batch. | 36 |
### Query Params
| Field | Type | Description | Characters |
|-----------------------|---------|-------------------------------------------------------------------------|---------------------------------------------------------------|
| `request_control_key` | uuidv4 | Unique identifier key of the request used by the client. | 36 |
| `schedule_status` | string | Status of the schedule. Can be sent as a list. | **[Enumerator schedule_status](#enumerador-schedule_status)** |
| `start_date` | string | Start date of the query | 10 |
| `end_date` | string | End date of the query | 10 |
| `page` | integer | Number of the requested page. 1 by default | |
| `page_size` | integer | Size of the requested page in the query. 30 by default and maximum value | Maximum value of 30 |
### Enumerator schedule_status
| Enumerator | Description |
|----------------------------|------------------------------------------------------------------------------------------------|
| **scheduled** | Transaction scheduled |
| **sent** | Schedule completed and sent successfully. Final state |
| **rejected** | Schedule rejected during creation or execution. Final state |
| **cancelled** | Schedule cancelled by client request. Final state |
| **pending_2fa_approval** | Pending approval by two-factor authentication |
| **pending_creation** | Schedule in creation process (Transitory state for batch scheduling) |
| **waiting_batch_approval** | Schedule created and linked to a batch awaiting approval by two-factor authentication |
### Response
STATUS 200
Response Body
```json
{
"data": [
{
"request_control_key": "b6804f32-101e-4702-8fbc-c2dbc4c2caec",
"schedule_key": "8cb70dea-9fb0-4a68-9572-99a72849c8d6",
"schedule_status": "scheduled",
"schedule_date": "2024-12-31",
"created_at": "2023-03-13T19:00:28.440Z"
},
{
"request_control_key": "bf6b0a4b-c7a5-446b-9dad-1ae10b25342a",
"schedule_key": "2479a5cd-079e-4d72-bf4e-16a695bda45e",
"schedule_status": "cancelled",
"schedule_date": "2024-12-31",
"created_at": "2023-03-13T19:00:28.440Z"
},
{
"request_control_key": "9d36c03e-2db7-4c90-87ed-6c9ddb3c03c7",
"schedule_key": "5d6b14b9-053f-408c-bcd7-61ecf9224f2c",
"schedule_status": "rejected",
"schedule_date": "2024-12-31",
"created_at": "2023-03-13T19:00:28.440Z"
}
],
"pagination": {
"current_page": 1,
"next_page": null,
"rows_per_page": 30
}
}
```
---
# List Account Schedule Batches
URL: /en/documentation/baas/ted/schedule_batch/listar_agendamentos_em_lote_de_uma_conta
## Request
ENDPOINT /account/ ACCOUNT_KEY /ted_schedule_batches
METHOD GET
### Path Params
| Field | Type | Description | Characters |
|---------------|--------|------------------------------------------|------------|
| `account_key` | uuidv4 | Unique account identification key. | 36 |
### Query Params
| Field | Type | Description | Characters |
|-------------------------|---------|-------------------------------------------------------------------------|---------------------------------------------------------------------------|
| `request_control_key` | uuidv4 | Unique request identification key used by the client. | 36 |
| `schedule_batch_status` | string | Schedule batch status. Can be sent as a list. | **[schedule_batch_status Enumerator](#enumerator-schedule_batch_status)** |
| `page` | integer | Requested page number. 1 by default | |
| `page_size` | integer | Size of the requested page in the query. 30 by default and maximum value | Maximum value of 30 |
### Enumerator schedule_batch_status
| Enumerator | Description |
|--------------------------|----------------------------------------------------------------------------|
| **created** | Schedule batch created |
| **approved** | Schedule batch approved |
| **rejected** | Schedule batch rejected |
| **pending_2fa_approval** | Schedule batch pending approval by two-factor authentication |
### Response
STATUS 200
Response Body
```json
{
"data": [
{
"request_control_key": "b6804f32-101e-4702-8fbc-c2dbc4c2caec",
"schedule_batch_key": "8cb70dea-9fb0-4a68-9572-99a72849c8d6",
"schedule_batch_status": "approved",
"created_at": "2021-10-22T20:30:23.459Z"
},
{
"request_control_key": "bf6b0a4b-c7a5-446b-9dad-1ae10b25342a",
"schedule_batch_key": "2479a5cd-079e-4d72-bf4e-16a695bda45e",
"schedule_batch_status": "cancelled",
"created_at": "2021-10-22T20:30:23.459Z"
},
{
"request_control_key": "9d36c03e-2db7-4c90-87ed-6c9ddb3c03c7",
"schedule_batch_key": "5d6b14b9-053f-408c-bcd7-61ecf9224f2c",
"schedule_batch_status": "rejected",
"created_at": "2021-10-22T20:30:23.459Z"
}
],
"pagination": {
"current_page": 1,
"next_page": null,
"rows_per_page": 30
}
}
```
---
# Request TED Transaction Batch Scheduling
URL: /en/documentation/baas/ted/schedule_batch/solicitacao_de_agendamento_em_lote
QI Tech offers the possibility to perform multiple scheduled TED transactions with a single call. If the initial call returns an **http status 4xx**, none of the schedules will be executed.
## Request
ENDPOINT /account/ ACCOUNT_KEY /ted_schedule_batch
METHOD POST
```json
{
"request_control_key": "6e4fc980-f8a1-4462-b6e2-d8a49f0ac055",
"ted_schedules": [
{
"request_control_key": "0c3d2a3e-c121-464e-b5a4-8e69e0c17bbd",
"target_account": {
"account_branch": "0001",
"account_number": "92796",
"account_digit": "1",
"owner_document_number": "23599885000192",
"owner_name": "Titular da Conta",
"ispb": "12345678",
"account_type": "checking_account"
},
"transaction_amount": 8.86,
"schedule_date": "2024-12-01"
}
]
}
```
## Path Params
| Field | Type | Description | Characters |
|---------------|--------|--------------------------------------|------------|
| `account_key` | uuidv4 | Unique account identification key. | 36 |
## Body Params
| Field | Type | Description | Characters |
|-------------------------|--------|------------------------------------------------------------------------------------|----------------------------------------------------------|
| `request_control_key` * | uuidv4 | Unique request identification key used by the client in uuid v4 format. | 36 |
| `ted_schedules` * | array | List of ted_schedule objects linked to the batch. | list of **[ted_schedule Object](#ted_schedule-object)** |
## ted_schedule Object
| Field | Type | Description | Characters |
|-------------------------|--------|------------------------------------------------------------------------------------|-----------------------------------------------------|
| `request_control_key` * | string | Unique request identification key used by the client in uuid v4 format. | 36 |
| `target_account` * | object | Target account | **[target_account Object](#target_account-object)** |
| `transaction_amount` * | float | Transfer amount | 10 |
| `schedule_date`* | string | Date when the transaction will be executed. | 10 |
## target_account Object
| Field | Type | Description | Characters |
|---------------------------|--------|-----------------------------------------------------|---------------------------------------------------------|
| `account_branch` * | string | Branch. | 4 |
| `account_digit` * | string | Account digit | 1 |
| `account_number` * | string | Account number. | 20 |
| `owner_document_number` * | string | CPF or CNPJ (numbers only) of the account holder. | 14 |
| `owner_name` * | string | Account holder's name. | 50 |
| `account_type`* | string | Account type. | **[account_type Enumerator](#account_type-enumerator)** |
| `ispb` * | string | Based on the financial institution's CNPJ (8 digits). | 8 |
## account_type Enumerator
| Enumerator | Translation |
|------------------------|-----------------------|
| **checking_account** | checking account |
| **deposit_account** | deposit account |
| **guaranteed_account** | guaranteed account |
| **investment_account** | investment account |
| **payment_account** | payment account |
| **saving_account** | savings account |
## Response
STATUS 201
Response Body: Approved Batch Scheduling
```json
{
"request_control_key": "b6804f32-101e-4702-8fbc-c2dbc4c2caec",
"schedule_batch_key": "8cb70dea-9fb0-4a68-9572-99a72849c8d6",
"schedule_batch_status": "approved",
"created_at": "2021-10-22T20:30:23.459Z"
}
```
### schedule_batch_status Enumerator
| Enumerator | Description |
|--------------------------|------------------------------------------------------------|
| **created** | Batch scheduling created |
| **approved** | Batch scheduling approved |
| **rejected** | Batch scheduling rejected |
| **pending_2fa_approval** | Batch scheduling pending two-factor authentication approval |
STATUS 4xx
Response Body: Error
```json
{
"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 (ptbr) `translation` |
|------------------------|--------------------|-----------------------------------------------------|--------------------------------------------------------------------------------------------|------------------------------------------------------------------------------------|
| 400 | QIT000001 | Bad Request | schema error description | Schema Inválido |
| 404 | TED000006 | Target account Not Found | Target account was not found for given parameters | Conta destino não encontrada para os parâmetros informados |
| 404 | TED000009 | Not Found | Account not found for the given key: \{account_key\} | Conta não encontrada para a chave fornecida: \{account_key\} |
| 403 | TED000014 | Invalid target account | Invalid target account | Conta destino inválida |
| 400 | TED000015 | Bad Request | Account blocked or closed can not perform this action | A conta bloqueada ou fechada não pode executar esta ação |
| 400 | TED000016 | Bad Request | Hub account can not perform this action | A conta hub não pode executar esta ação |
| 403 | TED000018 | Unauthorized | Provided account not owned by SELECTED_AGENT | Conta fornecida não pertencente ao SELECTED_AGENT |
| 400 | TED000031 | Bad Request | ISPB number \{ispb\} does not exist or is inactive | ISPB \{ispb\} não existe ou está inativo |
| 400 | TED000044 | Invalid Timestamp Format sent | Given parameter is not in the correct format \{timestamp_format\} | Parametro enviado não está no formato correto \{timestamp_format\} |
| 400 | TED000045 | Search Params Error | Invalid integer value for page or size querystring parameters | Valor inválido para parâmetros de página ou tamanho de página |
| 400 | TED000046 | Invalid uuid v4 string sent | \{key\} was not accepted for not being a valid uuid v4 string | \{key\} não foi aceito por não ser uma palavra uuid v4 válida |
| 400 | TED000054 | Invalid Transaction Amount | Transaction Amount \{transaction_amount\} is invalid | Valor de transação \{transaction_amount\} é inválido |
| 400 | TED000057 | Invalid Document Number | Given \{document_number\} document number is invalid | CPF/CNPJ \{document_number\} fornecido não é valido |
| 409 | TED000064 | Bad Request | request_control_key \{request_control_key\} already in use | request_control_key \{request_control_key\} já utilizada |
| 400 | TED000065 | Bad Request | It has been identified by request_control_key that this request is already being processed | Foi identificado por request_control_key que está requisição está sendo processada |
| 400 | TED000089 | Invalid Schedule Date | Schedule date must be after current date for UTC-3 | Data de agendamento deve ser após a data atual em UTC-3 |
| 400 | TED000090 | Invalid Schedule Date | Schedule date must be a workday | Data de agendamento deve ser um dia útil |
| 400 | TED000091 | Target Account and Source Account must be different | Target Account must not be the same as Source Account | A conta de destino não pode ser a mesma da conta de origem |
---
# Cancel TED Transaction Schedule
URL: /en/documentation/baas/ted/schedule/cancelamento_de_agendamento
## Request
ENDPOINT /account/ ACCOUNT_KEY /ted_schedule/ SCHEDULE_KEY /cancel
METHOD PATCH
### Path Params
| Field | Type | Description | Characters |
|----------------|--------|--------------------------------------------|------------|
| `account_key` | uuidv4 | Unique account identification key. | 36 |
| `schedule_key` | uuidv4 | Unique schedule identification key | 36 |
### Response
STATUS 200
Response Body: Schedule Cancelled
```json
{
"request_control_key": "b6804f32-101e-4702-8fbc-c2dbc4c2caec",
"schedule_key": "f64b3fa7-d09d-4927-ad4f-b966df9fb153",
"schedule_status": "cancelled",
"schedule_date": "2024-12-31"
}
```
STATUS 4xx
Response Body: Error
```json
{
"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 (ptbr) `translation` |
|--------------------------|----------------------|--------------------------------------|-----------------------------------------------------------------------------------|---------------------------------------------------------------------------------------------|
| 400 | QIT000001 | Bad Request | schema error description | Schema Inválido |
| 404 | TED000009 | Not Found | Account not found for the given key: \{account_key\} | Conta não encontrada para a chave fornecida: \{account_key\} |
| 403 | TED000018 | Unauthorized | Provided account not owned by SELECTED_AGENT | Conta fornecida não pertencente ao SELECTED_AGENT |
| 400 | TED000044 | Invalid Timestamp Format sent | Given parameter is not in the correct format \{timestamp_format\} | Parametro enviado não está no formato correto \{timestamp_format\} |
| 400 | TED000045 | Search Params Error | Invalid integer value for page or size querystring parameters | Valor inválido para parâmetros de página ou tamanho de página |
| 400 | TED000046 | Invalid uuid v4 string sent | \{key\} was not accepted for not being a valid uuid v4 string | \{key\} não foi aceito por não ser uma palavra uuid v4 válida |
| 404 | TED000093 | TedSchedule not Found | TedSchedule was not found | TedSchedule não encontrada |
| 400 | TED000094 | Bad Request | Ted Schedule cannot be cancelled in current status | Agendamento Ted não pode ser cancelado no status atual |
| 400 | TED000095 | Bad Request | The given Ted Schedule is tied to a batch. It cannot be individually cancelled | O agendamento Ted enviado está ligado a um lote. Ela não pode ser individualmente cancelada |
| 400 | TED000096 | Bad Request | Action cannot be taken place as there is currently a pending transfer in progress | A ação não pôde ser completada como há uma transferência pendente |
| 400 | TED000108 | Number of transfer attempts exceeded | The maximum number of failed transfer attempts has been reached | Número máximo de tentativas de transferência foi atingida |
---
# Query TED Transaction Schedule
URL: /en/documentation/baas/ted/schedule/consulta_de_agendamento
## Request
ENDPOINT /account/ ACCOUNT_KEY /ted_schedule/ SCHEDULE_KEY
METHOD GET
### Path Params
| Field | Type | Description | Characters |
|----------------|--------|---------------------------------------------|------------|
| `account_key` | uuidv4 | Unique account identification key. | 36 |
| `schedule_key` | uuidv4 | Unique schedule identification key | 36 |
### Response
STATUS 200
Response Body
```json
{
"request_control_key": "b8eb663e-10fe-4729-9db5-8f8c93de5001",
"schedule_key": "0c9091ab-079b-4a43-8b3d-d4ba36a23883",
"schedule_batch_key": null,
"schedule_status": "sent",
"target_account": {
"account_branch": "0001",
"account_digit": "8",
"account_number": "1234567",
"owner_document_number": "***91111***",
"owner_person_type": "natural",
"owner_name": "Conta manual geral",
"account_type": "checking_account",
"ispb": "99999004"
},
"transaction_amount": 2.0,
"rejection_info": null,
"schedule_date": "2024-07-10",
"updated_at": "2024-07-10T16:19:38Z",
"created_at": "2024-06-10T11:17:28Z",
"schedule_transfers": [
{
"request_control_key": "12723821-41d5-496b-b66c-fb7188f50fc1",
"ted_key": "91028dfa-43a2-4665-adf2-0bd4571f6f0d",
"created_at": "2024-07-10T16:19:38Z",
"ted_status": "sent",
"fee_amount": 2.00
}
]
}
```
---
# Introduction
URL: /en/documentation/baas/ted/schedule/introducao
Through the endpoints presented in this section, the integration partner can request the scheduling of ted type transactions. With this functionality it will be possible to create, list and cancel schedules for a specific account.
## Observations
- The scheduling date takes into account Brasília time (BRT or UTC/GMT -03:00)
- Transactions will be attempted starting at 8am BRT
- Transactions cannot be scheduled for holidays or weekends
- Transactions that have failed due to insufficient balance will be retried in 1 hour with a limit of 3 attempts
- A webhook will be sent to the integration partner informing the success or rejection of a schedule
## Ted Schedule Status
| Enumerator | Description |
|----------------------------|------------------------------------------------------------------------------------------------|
| **scheduled** | Scheduled transaction |
| **sent** | Schedule completed and sent successfully. Final state |
| **rejected** | Schedule rejected during creation or execution. Final state |
| **cancelled** | Schedule cancelled by client request. Final state |
| **pending_2fa_approval** | Pending approval by two-factor authentication |
| **waiting_batch_approval** | Schedule created and linked to a batch awaiting approval by two-factor authentication |
## Schedule Transfers
On the scheduling date, the ted transaction will be attempted. At this moment a **ted** is generated and it will be added to the `schedule_transfers` list. A maximum of 3 ted transactions will be attempted.
---
# List TED Transaction Schedules for an Account
URL: /en/documentation/baas/ted/schedule/listar_agendamentos_de_uma_conta
## Request
ENDPOINT /account/ ACCOUNT_KEY /ted_schedules
METHOD GET
### Path Params
| Field | Type | Description | Characters |
|---------------|--------|----------------------------------------|------------|
| `account_key` | uuidv4 | Unique account identification key. | 36 |
### Query Params
| Field | Type | Description | Characters |
|-----------------------|---------|-------------------------------------------------------------------------|---------------------------------------------------------------|
| `request_control_key` | uuidv4 | Unique request identification key used by the client. | 36 |
| `schedule_status` | string | Schedule status. Can be sent as a list. | **[schedule_status Enumerator](#schedule_status-enumerator)** |
| `page` | integer | Requested page number. Default is 1 | |
| `page_size` | integer | Size of the requested page in the query. Default is 30 and maximum | Maximum value of 30 |
### schedule_status Enumerator
| Enumerator | Description |
|----------------------------|------------------------------------------------------------------------------------------------|
| **scheduled** | Scheduled transaction |
| **sent** | Schedule completed and sent successfully. Final state |
| **rejected** | Schedule rejected during creation or execution. Final state |
| **cancelled** | Schedule cancelled by client request. Final state |
| **pending_2fa_approval** | Pending approval by two-factor authentication |
| **pending_creation** | Schedule in creation process (Transitional state for batch scheduling) |
| **waiting_batch_approval** | Schedule created and linked to a batch awaiting approval by two-factor authentication |
### Response
STATUS 200
Response Body
```json
{
"data": [
{
"request_control_key": "b6804f32-101e-4702-8fbc-c2dbc4c2caec",
"schedule_key": "8cb70dea-9fb0-4a68-9572-99a72849c8d6",
"schedule_status": "scheduled",
"schedule_date": "2024-12-31",
"created_at": "2023-03-13T19:00:28.440Z"
},
{
"request_control_key": "bf6b0a4b-c7a5-446b-9dad-1ae10b25342a",
"schedule_key": "2479a5cd-079e-4d72-bf4e-16a695bda45e",
"schedule_status": "cancelled",
"schedule_date": "2024-12-31",
"created_at": "2023-03-13T19:00:28.440Z"
},
{
"request_control_key": "9d36c03e-2db7-4c90-87ed-6c9ddb3c03c7",
"schedule_key": "5d6b14b9-053f-408c-bcd7-61ecf9224f2c",
"schedule_status": "rejected",
"schedule_date": "2024-12-31",
"created_at": "2023-03-13T19:00:28.440Z"
}
],
"pagination": {
"current_page": 1,
"next_page": null,
"rows_per_page": 30
}
}
```
---
# Request TED Transaction Scheduling
URL: /en/documentation/baas/ted/schedule/solicitacao_de_agendamento
## Request
ENDPOINT /account/ ACCOUNT_KEY /ted_schedule
METHOD POST
Request Body
```json
{
"request_control_key": "0c3d2a3e-c121-464e-b5a4-8e69e0c17bbd",
"target_account": {
"account_branch": "0001",
"account_number": "92796",
"account_digit": "1",
"owner_document_number": "23599885000192",
"owner_name": "Titular da Conta",
"ispb": "12345678",
"account_type": "checking_account"
},
"transaction_amount": 8.86,
"schedule_date": "2024-12-01"
}
```
### Path Params
| Field | Type | Description | Characters |
|---------------|--------|-------------------------------------------------|------------|
| `account_key` | uuidv4 | Unique account identification key. | 36 |
## Body Params
| Field | Type | Description | Characters |
|-------------------------|--------|--------------------------------------------------------------------------------------|------------------------------------------------------|
| `request_control_key` * | string | Unique request identification key used by the client in uuid v4 format. | 36 |
| `target_account` * | object | Target account | **[target_account Object](#target_account-object)** |
| `transaction_amount` * | float | Transfer amount | 10 |
| `schedule_date`* | string | Date when the transaction should be executed. | 10 |
## target_account Object
| Field | Type | Description | Characters |
|---------------------------|--------|--------------------------------------------------|----------------------------------------------------------|
| `account_branch` * | string | Branch. | 4 |
| `account_digit` * | string | Account digit | 1 |
| `account_number` * | string | Account number. | 20 |
| `owner_document_number` * | string | CPF or CNPJ (numbers only) of the account holder. | 14 |
| `owner_name` * | string | Account holder name. | 50 |
| `account_type`* | string | Account type. | **[account_type Enumerator](#account_type-enumerator)** |
| `ispb` * | string | Based on financial institution CNPJ (8 digits). | 8 |
## account_type Enumerator
| Enumerator | Translation |
|------------------------|-----------------------|
| **checking_account** | checking account |
| **deposit_account** | deposit account |
| **guaranteed_account** | guaranteed account |
| **investment_account** | investment account |
| **payment_account** | payment account |
| **saving_account** | savings account |
## Response
STATUS 201
Response Body: Schedule Created
```json
{
"request_control_key": "b6804f32-101e-4702-8fbc-c2dbc4c2caec",
"schedule_key": "f64b3fa7-d09d-4927-ad4f-b966df9fb153",
"schedule_status": "scheduled",
"schedule_date": "2024-12-31"
}
```
STATUS 4xx
Response Body: Error
```json
{
"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 (ptbr) `translation` |
|------------------------|--------------------|----------------------------------------------------|---------------------------------------------------------------------------------------------|-------------------------------------------------------------------------------------|
| 400 | QIT000001 | Bad Request | schema error description | Schema Inválido |
| 404 | TED000006 | Target account Not Found | Target account was not found for given parameters | Conta destino não encontrada para os parâmetros informados |
| 404 | TED000009 | Not Found | Account not found for the given key: \{account_key\} | Conta não encontrada para a chave fornecida: \{account_key\} |
| 403 | TED000014 | Invalid target account | Invalid target account | Conta destino inválida |
| 400 | TED000015 | Bad Request | Account blocked or closed can not perform this action | A conta bloqueada ou fechada não pode executar esta ação |
| 400 | TED000016 | Bad Request | Hub account can not perform this action | A conta hub não pode executar esta ação |
| 403 | TED000018 | Unauthorized | Provided account not owned by SELECTED_AGENT | Conta fornecida não pertencente ao SELECTED_AGENT |
| 400 | TED000031 | Bad Request | ISPB number \{ispb\} does not exist or is inactive | ISPB \{ispb\} não existe ou está inativo |
| 400 | TED000044 | Invalid Timestamp Format sent | Given parameter is not in the correct format \{timestamp_format\} | Parametro enviado não está no formato correto \{timestamp_format\} |
| 400 | TED000046 | Invalid uuid v4 string sent | \{key\} was not accepted for not being a valid uuid v4 string | \{key\} não foi aceito por não ser uma palavra uuid v4 válida |
| 400 | TED000054 | Invalid Transaction Amount | Transaction Amount \{transaction_amount\} is invalid | Valor de transação \{transaction_amount\} é inválido |
| 400 | TED000057 | Invalid Document Number | Given \{document_number\} document number is invalid | CPF/CNPJ \{document_number\} fornecido não é valido |
| 409 | TED000064 | Bad Request | request_control_key \{request_control_key\} already in use | request_control_key \{request_control_key\} já utilizada |
| 400 | TED000065 | Bad Request | It has been identified by request_control_key that this request is already being processed | Foi identificado por request_control_key que está requisição está sendo processada |
| 400 | TED000089 | Invalid Schedule Date | Schedule date must be after current date for UTC-3 | Data de agendamento deve ser após a data atual em UTC-3 |
| 400 | TED000090 | Invalid Schedule Date | Schedule date must be a workday | Data de agendamento deve ser um dia útil |
| 400 | TED000091 | Target Account and Source Account must be different | Target Account must not be the same as Source Account | A conta de destino não pode ser a mesma da conta de origem |
---
# TED Schedule Completion Webhook
URL: /en/documentation/baas/ted/schedule/webhook_de_conclusao_de_agendamento
After completing a TED schedule, a webhook will be sent to the integrating partner with the result.
:::danger Attention!
QI Tech webhooks should not be mapped in a restrictive way. Additional fields may be included in the webhook payloads returned by our APIs.
:::
### Webhook Request Body
Request Body: Schedule Completed and Sent
```json
{
"webhook_type": "baas.ted.ted_schedule.completed",
"webhook_datetime": "2021-10-22T20:30:23.459Z",
"data": {
"request_control_key": "b8eb663e-10fe-4729-9db5-8f8c93de5001",
"schedule_key": "0c9091ab-079b-4a43-8b3d-d4ba36a23883",
"schedule_batch_key": null,
"schedule_status": "sent",
"target_account": {
"account_branch": "0001",
"account_digit": "8",
"account_number": "1234567",
"owner_document_number": "***91111***",
"owner_person_type": "natural",
"owner_name": "Conta manual geral",
"account_type": "checking_account",
"ispb": "99999004"
},
"transaction_amount": 2.0,
"rejection_info": null,
"schedule_date": "2024-07-10",
"updated_at": "2024-07-10T16:19:38Z",
"created_at": "2024-06-10T11:17:28Z",
"schedule_transfers": [
{
"request_control_key": "12723821-41d5-496b-b66c-fb7188f50fc1",
"ted_key": "91028dfa-43a2-4665-adf2-0bd4571f6f0d",
"created_at": "2024-07-10T16:19:38Z",
"ted_status": "sent",
"fee_amount": 2.00
}
]
}
}
```
Request Body: Schedule Completed and Rejected
```json
{
"webhook_type": "baas.ted.ted_schedule.completed",
"webhook_datetime": "2021-10-22T20:30:23.459Z",
"data": {
"request_control_key": "b8eb663e-10fe-4729-9db5-8f8c93de5001",
"schedule_key": "0c9091ab-079b-4a43-8b3d-d4ba36a23883",
"schedule_batch_key": null,
"schedule_status": "sent",
"target_account": {
"account_branch": "0001",
"account_digit": "8",
"account_number": "1234567",
"owner_document_number": "***91111***",
"owner_person_type": "natural",
"owner_name": "Conta manual geral",
"account_type": "checking_account",
"ispb": "99999004"
},
"transaction_amount": 2.0,
"rejection_info": {
"error_code": "TED000103",
"error_description": "The maximum number of failed transfer attempts has been reached",
"error_translation": "Número máximo de tentativas de transferência foi atingida",
"rejection_reason": "max_tries_exceeded"
},
"schedule_date": "2024-07-10",
"updated_at": "2024-07-10T16:19:38Z",
"created_at": "2024-06-10T11:17:28Z",
"schedule_transfers": [
{
"ted_key": "907e38c5-5700-492f-a181-8f651317458b",
"created_at": "2024-07-10T16:19:38Z",
"ted_status": "rejected",
"fee_amount": 2.00
},
{
"ted_key": "356f8855-8f8d-4aaa-8e8c-1287e363d143",
"created_at": "2024-07-10T17:19:38Z",
"ted_status": "rejected",
"fee_amount": 2.00
},
{
"ted_key": "c51cc7ee-d966-4bbb-8405-4850b90b43f8",
"created_at": "2024-07-10T18:19:38Z",
"ted_status": "rejected",
"fee_amount": 2.00
}
]
}
}
```
### Webhook Body Param
| Field | Type | Description | Max. Characters |
|-----------------------|--------|----------------------------------------------------------------------------|--------------------------------------------------------------------|
| `webhook_type` | string | An enumerator that defines the type of event being reported | 23 |
| `webhook_datetime` | string | Date and time of the webhook sending | 20 |
| `request_control_key` | uuidv4 | Unique identification key for the request used by the client in uuid v4 format. | 36 | |
| `schedule_key` | string | Unique identification key for the schedule | 36 |
| `schedule_batch_key` | string | Unique identification key for the schedule batch | 36 |
| `schedule_status` | string | Status of the schedule | **[Enumerator schedule_status](#ted-schedule-status)** |
| `target_account` | object | Target account for the schedule | **[Object target_account](#target_account-object)** |
| `transaction_amount` | number | Transfer amount | 10 |
| `schedule_transfers` | array | List of transfer attempts made by the schedule | list of **[Object schedule_transfer](#schedule-transfer-object)** |
| `schedule_date` | string | Date when the transaction will be executed. | 10 |
| `rejection_info` | object | Object with information about the rejection event | |
| `updated_at` | string | Date and time of the last schedule update. | 20 |
| `created_at` | string | Date and time of schedule creation. | 20 |
## Ted Schedule Status
| Enumerator | Description |
|----------------------------|--------------------------------------------------------------------------------|
| **scheduled** | Transaction scheduled |
| **sent** | Schedule completed and sent successfully. Final state |
| **rejected** | Schedule rejected during creation or execution. Final state |
| **cancelled** | Schedule cancelled by client request. Final state |
| **pending_2fa_approval** | Pending approval by two-factor authentication |
| **waiting_batch_approval** | Schedule created and linked to a batch waiting for two-factor authentication approval |
### Schedule Transfer Object
| Field | Type | Description | Characters |
|--------------|--------|-------------------------------------------------------------|------------------------------------------------|
| `ted_key` | uuidv4 | Unique identification key for the TED transfer in QI system. | 36 |
| `ted_status` | string | Transaction status. | [Enumerator ted_status](#ted-status-enumerator) |
| `fee_amount` | number | Transfer amount | 10 |
| `created_at` | string | Date and time of transaction creation | 20 |
### Ted Status Enumerator
| Enumerator | Description |
|--------------|---------------------------------------------------|
| **sent** | Transaction sent successfully. Final state |
| **rejected** | Transaction rejected during execution. Final state |
| **pending** | Transaction pending completion. Transitory state |
### target_account Object
| Field | Type | Description | Characters |
|-------------------------|------------|------------------------------------------------------------------------------------------------------|-------------------------------------------------------------------|
| `account_branch` | string | Account branch | 6 |
| `account_digit` | string | Account digit | 1 |
| `account_number` | string | Account number | 20 |
| `owner_document_number` | string | CPF or CNPJ (numbers only) of the account holder | 14 |
| `owner_name` | string | Name of the account holder | 150 |
| `owner_person_type` | enumerator | Identifier whether the owner of the sent account is a natural or legal person | **[Enumerator owner_person_type](#owner_person_type-enumerator)** | |
| `owner_name` | string | Name of the account holder | 150 |
| `account_type` | enumerator | Type of account | **[Enumerator account_type](#account_type-enumerator)** |
| `ispb` | string | Eight-digit code that identifies banks in the Central Bank's reserve transfer system | 8 |
### owner_person_type Enumerator
| Enum | Description |
|-------------|--------------|
| **natural** | Natural person |
| **legal** | Legal person |
## account_type Enumerator
| Enumerator | Translation |
|------------------------|-----------------------|
| **checking_account** | checking account |
| **deposit_account** | deposit account |
| **guaranteed_account** | guarantee account |
| **investment_account** | investment account |
| **payment_account** | payment account |
| **saving_account** | savings account |
---
# Webhook after TED sending completion
URL: /en/documentation/baas/ted/webhooks
The webhook will notify if a TED transaction has been returned.
## Webhook Request Body
**Webhook Body: TED Rejected**
```json
{
"webhook_type": "baas.ted.outgoing_ted",
"webhook_datetime": "2021-10-22T20:30:23.459Z",
"data": {
"request_control_key": "6e290347-330d-4b3a-8ebb-2ac217ad6eb3",
"ted_key": "8cb70dea-9fb0-4a68-9572-99a72849c8d6",
"account_key": "fc6862c4-2b20-4057-8063-b8809866e494",
"created_at": "2021-10-22T20:30:23.459Z",
"ted_status": "sent",
"transaction_amount": 126.97,
"fee_amount": 0.0,
"target_account": {
"account_branch": "0001",
"account_digit": "6",
"account_number": "78340",
"ispb": "12345678",
"owner_document_number": "32402502000135",
"owner_name": "QI Tech"
},
"refusal_reason": {
"refusal_code": 1,
"enumerator": "conta_destinatario_encerrada",
"description": "Conta Destinatária do Crédito Encerrada"
}
}
}
```
**Webhook Body: TED Confirmed**
```json
{
"webhook_type": "baas.ted.outgoing_ted",
"webhook_datetime": "2021-10-22T20:30:23.459Z",
"data": {
"request_control_key": "6e290347-330d-4b3a-8ebb-2ac217ad6eb3",
"ted_key": "8cb70dea-9fb0-4a68-9572-99a72849c8d6",
"account_key": "fc6862c4-2b20-4057-8063-b8809866e494",
"created_at": "2021-10-22T20:30:23.459Z",
"ted_status": "confirmed",
"transaction_amount": 126.97,
"fee_amount": 0.0,
"target_account": {
"account_branch": "0001",
"account_digit": "6",
"account_number": "78340",
"ispb": "12345678",
"owner_document_number": "32402502000135",
"owner_name": "QI Tech"
},
"refusal_reason": null
}
}
```
## Webhook Body Param
| Field | Type | Description | Max. Characters |
|----------------------|--------|-----------------------------------------------------------------------------|-----------------------------------------------------|
| `webhook_type` | string | An enumerator that defines the type of event being reported | 23 |
| `webhook_datetime` | string | Date and time the webhook was sent | 20 |
| `request_control_key`| string | Unique request identification key used by the client in uuid v4 format | 36 |
| `ted_key` | string | Unique identification key of the TED transfer | 36 |
| `created_at` | string | Date and time the transaction was created | 24 |
| `ted_status` | string | Status of the TED transaction | **[Enumerator ted_status](#enumerator-ted_status)** |
| `transaction_amount` | number | Transfer amount | 10 |
| `fee_amount` | number | Fee amount charged by the transfer | 35 |
| `target_account` | Object | Destination account - Should only be sent in transactions of type "manual" | **[Object target_account](#object-target_account)** |
| `refusal_reason` | Object | Reason for refusal according to the Central Bank standard | **[Object refusal_reason](#object-refusal_reason)** |
## Enumerator ted_status
| Enumerator | Description |
|---------------|-----------------------------------------------|
| **sent** | TED transfer successfully sent. |
| **confirmed** | TED transfer successfully completed. |
| **pending** | TED transfer pending. |
| **rejected** | TED transfer rejected. |
| **returned** | TED transfer returned. |
## Object target_account
| Field | Type | Description | Characters |
|--------------------------|--------|----------------------------------------------------|-------------------------------------------------|
| `account_branch` * | string | Branch. | 4 |
| `account_digit` * | string | Account digit | 1 |
| `account_number` * | string | Account number. | 20 |
| `owner_document_number` *| string | CPF or CNPJ (numbers only) of the account holder. | 14 |
| `owner_name` * | string | Name of the account holder. | 50 |
| `account_type` * | string | Account type. | **[Enumerator account_type](#enumerator-account_type)** |
| `ispb` * | string | Based on the financial institution's CNPJ (8 digits). | 8 |
## Object refusal_reason
| Field | Type | Description | Characters |
|---------------|--------|---------------------------|------------|
| `bacen_code` *| string | Bacen refusal code | 3 |
| `enumerator` *| string | Bacen refusal enumerator | 100 |
| `description` *| string | Bacen refusal description | 100 |
## Enumerator account_type
| Enumerator | Translation |
|--------------------|-----------------------|
| checking_account | conta corrente |
| deposit_account | conta depósito |
| guaranteed_account | conta de garantia |
| investment_account | conta de investimento |
| payment_account | conta de pagamento |
| saving_account | conta poupança |
## Webhook after TED reception
The webhook will inform about the final status of the TED transaction.
## Webhook Request Body
**Request Body: TED Received**
```json
{
"webhook_type": "baas.ted.incoming_ted",
"webhook_datetime": "2021-10-22T20:30:23.459Z",
"data": {
"request_control_key": "6e290347-330d-4b3a-8ebb-2ac217ad6eb3",
"ted_key": "8cb70dea-9fb0-4a68-9572-99a72849c8d6",
"account_key": "fc6862c4-2b20-4057-8063-b8809866e494",
"created_at": "2021-10-22T20:30:23.459Z",
"ted_status": "received",
"transaction_amount": 126.97,
"fee_amount": 0.0,
"source_account": {
"account_branch": "0001",
"account_digit": "6",
"account_number": "78340",
"ispb": "12345678",
"owner_document_number": "32402502000135",
"owner_name": "QI Tech"
},
"refusal_reason": {}
}
}
```
## Webhook Body Param
| Field | Type | Description | Max. Characters |
|----------------------|--------|-----------------------------------------------------------------------------|-----------------------------------------------------|
| `webhook_type` | string | A enumerator that defines the type of event being reported | 23 |
| `webhook_datetime` | string | Date and time the webhook was sent | 20 |
| `ted_key` | string | Unique identification key of the TED transfer | 36 |
| `created_at` | string | Date and time the transaction was created | 100 |
| `ted_status` | string | Status of the TED transaction | **[Enumerator ted_status](#enumerator-ted_status)** |
| `transaction_amount` | number | Transfer amount | 10 |
| `fee_amount` | number | Fee amount charged by the transfer | 35 |
| `target_account` | Object | Destination account - Should only be sent in transactions of type "manual" | **[Object target_account](#object-target_account)** |
| `refusal_reason` | Object | Reason for refusal according to the Central Bank standard | **[Object refusal_reason](#object-refusal_reason)** |
## Enumerator ted_status
| Enumerator | Description |
|--------------|----------------------------------------------|
| **received** | TED transfer successfully received. |
| **pending** | TED transfer pending. |
| **rejected** | TED transfer rejected. |
## Object target_account
| Field | Type | Description | Characters |
|--------------------------|--------|-------------------------------------------------- |-------------------------------------------------|
| `account_branch` * | string | Branch. | 10 |
| `account_digit` * | string | Account digit | 10 |
| `account_number` * | string | Account number. | 10 |
| `owner_document_number` *| string | CPF or CNPJ (numbers only) of the account holder. | 14 |
| `owner_name` * | string | Name of the account holder. | 50 |
| `account_type`* | string | Account type. | **[Enumerator account_type](#enumerator-account_type)** |
| `ispb` * | string | Based on the financial institution's CNPJ (8 digits). | 8 |
## Object refusal_reason
| Field | Type | Description | Characters |
|-----------------|--------|---------------------------|------------|
| `bacen_code` * | string | Bacen refusal code | 3 |
| `enumerator` * | string | Bacen refusal enumerator | 100 |
| `description` * | string | Bacen refusal description | 100 |
## Enumerator account_type
| Enumerator | Translation |
|--------------------|-----------------------|
| checking_account | conta corrente |
| deposit_account | conta depósito |
| guaranteed_account | conta de garantia |
| investment_account | conta de investimento |
| payment_account | conta de pagamento |
| saving_account | conta poupança |
---
# baas_consulta_documents
URL: /en/documentation/baas/upload_de_documentos/baas_consulta_documents
---
# baas_upload_de_documentos
URL: /en/documentation/baas/upload_de_documentos/
---
# Approve Boleto Payment
URL: /en/documentation/boletos/2fa/realizar_pagamento_de_um_boleto
To make a Boleto payment, two calls are required:
1. Transfer validation token request: /baas/token_request
2. Transfer approval: /baas/movement_validation
:::info
The sent Token must be provided at the time of boleto payment approval, and the "***movement_payload***" must be the same as provided when the token was requested.
:::
## Request
METHOD POST
ENDPOINT /baas/movement_validation
Request Body
```json
{
"token": "358192",
"movement_payload": {
"resource_account_key": "6d30a0b1-cb90-4ceb-b1ea-5bd600cdf3c8",
"digitable_line": "32990001031000699926165000000201993810000003500"
}
}
```
## Body Params
| Field | Type | Description | Characters |
|---|---| ---| ---|
| `token` * | string | Authentication token | 6 |
| `agent_document_number` * | string | CPF of the user who will receive the token. (Numbers only) | 11 |
| `movement_payload` | Object | Payload containing transfer information | **[Object movement_payload](#object-movement_payload)** |
### Object movement_payload
| Field | Type | Description | Characters |
|---|---| ---| ---|
| `resource_account_key` * | uuidv4 | Unique identification key of the account that will make the payment | 36 |
| `digitable_line` * | string | Boleto digitable line | 47 |
## Response
STATUS 200
Response Body
```json
{
"movement_info": {
"origin": {
"account": "42863",
"branch": "0001",
"digit": "0",
"document": "73685224000239",
"name": "Empresa de Teste",
"financialInstitution": "QI Sociedade de Crédito Direto S.A."
},
"faceValue": "2185.0",
"amount": "2185.0",
"dueDate": "2024-04-18T03:00:00.000Z",
"type": "bank_slip_payment",
"digitableLine": "32990001031000699926165000000201993810000003500",
"barCode": "00191969000002185000000001120035240112154117",
"destination": {
"document": "05626796000106",
"guarantorName": null,
"name": "Beneficiário do Boleto",
"guarantorDocument": null,
"bank": "QI Sociedade de Crédito Direto S.A."
}
},
"account_key": "0000000-0000-0000-0000-000000000000",
"transaction_key": "0000000-0000-0000-0000-000000000000",
"movement_status": "approved",
"schedule_key": null,
"movement_amount": 2185,
"origin_key": null,
"transacted_at_br": "2024-04-18 09:50:38-03:00",
"requester_user_key": "0000000-0000-0000-0000-000000000000",
"requester_key": "0000000-0000-0000-0000-000000000000",
"movement_request_key": "0000000-0000-0000-0000-000000000000",
"movement_date": "2024-04-18",
"approval_feedback": true,
"movement_type": "bank_slip_payment",
"movement_data": {
"transaction_key": "0000000-0000-0000-0000-000000000000",
"resource_account_key": "0000000-0000-0000-0000-000000000000",
"digitable_line": "32990001031000699926165000000201993810000003500"
},
"transacted_at": "2024-04-18 12:50:38"
}
```
---
# Request Token for Boleto Payment
URL: /en/documentation/boletos/2fa/solicitar_token_para_pagamento
To make a Boleto payment, two calls are required:
1. Transfer validation token request: /baas/token_request
2. Transfer approval: /baas/movement_validation
## Request
- METHOD POST
- ENDPOINT /baas/token_request
Request Body
```json
{
"contact_type": "email",
"agent_document_number": "97564480084",
"movement_payload": {
"resource_account_key": "6d3089b1-cb90-4ceb-b1ea-5bd600cdf3c8",
"digitable_line": "32990001031000699926165000000201993810000003500"
}
}
```
## Body Params
| Field | Type | Description | Characters |
|---|---| ---| ---|
| `contact_type` * | string | Authentication token delivery method, can be via Email ("email") or SMS ("sms") | 10 |
| `agent_document_number` * | string | CPF of the user who will receive the token. (Numbers only) | 11 |
| `movement_payload` | Object | Payload containing transfer information | **[Object movement_payload](#object-movement_payload)** |
### Object movement_payload
| Field | Type | Description | Characters |
|---|---| ---| ---|
| `resource_account_key` * | uuidv4 | Unique identification key of the account that will make the payment | 36 |
| `digitable_line` * | string | Boleto digitable line | 47 |
## Response
STATUS 200
Response Body
```json
{}
```
---
# Create Wallet
URL: /en/documentation/boletos/carteira/criar_carteira
:::danger 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.
:::info 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**](/documentation/contas/consulta_de_tarifas).
:::
:::caution 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**](/documentation/boletos/v2/webhooks/carteira) about the result of such request.
:::
## Request
ENDPOINT /account/ ACCOUNT_KEY /requester_profile
METHOD POST
### Path parameters
| Field | Type | Description | Characters |
|-------------------------|--------|--------------------------------------------------------------|------------|
| `account_key` | uuidv4 | Unique account identification key, in uuid v4 format | 36 |
Request Body
```json
{
"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
| Field | Type | Description | Characters |
|----------------------------|---------|------------------------------------------------------------------------------------|------------|
| `request_control_key` * | uuidv4 | Unique request identification key used by the client in uuid v4 format | 36 |
| `configuration_data` * | object | Wallet default configurations | **[configuration_data Object](#configuration_data-object)** |
### configuration_data Object
| Field | Type | Description | Characters |
|----------------------------|---------|------------------------------------------------------------------------------------|------------|
| `max_payment_days` * | integer | Maximum calendar days the boleto will remain available for payment after due date (can be at most 365) | - |
| `write_off_settings` | object | Default discharge configuration | **[write_off_settings Object](#write_off_settings-object)** |
| `protest_settings` | object | Default protest configuration | **[protest_settings Object](#protest_settings-object)** |
| `bankruptcy_protest_settings` | object | Default bankruptcy protest configuration | **[bankruptcy_protest_settings Object](#bankruptcy_protest_settings-object)** |
| `fine_settings` | object | Default fine configuration | **[fine_settings Object](#fine_settings-object)** |
| `interest_settings` | object | Default interest configuration | **[interest_settings Object](#interest_settings-object)** |
| `qr_code_settings` | object | Default PIX QR Code configuration (for bolePix) | **[qr_code_settings Object](#qr_code_settings-object)** |
| `cnab_settings` | object | Default CNAB files configuration | **[cnab_settings Object](#cnab_settings-object)** |
### write_off_settings Object
| Field | Type | Description | Characters |
|---------------------------|---------|-----------------------------------------------------------------------------|------------|
| `days_to_write_off` * | integer | Days after due date for the boleto to be automatically discharged | - |
### protest_settings Object
| Field | Type | Description | Characters |
|---------------------------|---------|-----------------------------------------------------------------------------|------------|
| `days_to_protest` * | integer | Days after due date for the boleto to be automatically protested | - |
### bankruptcy_protest_settings Object
| Field | Type | Description | Characters |
|--------------------------------|---------|-----------------------------------------------------------------------------|-------------|
| `days_to_bankruptcy_protest` * | integer | Days after due date for a bankruptcy protest process to be automatically initiated | - |
### fine_settings Object
Option 1: absolute amount fine (`fine_type=absolute`)
| Field | Type | Description | Characters |
|---------------------------|---------|---------------------------------------------------------|-------------------------------------------------------------------------|
| `fine_type` * | string | Type of fine | **[fine_type Enumerators](#fine_type-enumerators)** |
| `fine_amount` * | float | Absolute amount of the fine | - |
| `days_to_fine` * | integer | Days after due date for the fine to be charged | - |
Option 2: percentage fine (`fine_type=percentage`)
| Field | Type | Description | Characters |
|---------------------------|---------|-----------------------------------------------------------|---------------------------------------|
| `fine_type` * | string | Type of fine | **[fine_type Enumerators](#fine_type-enumerators)** |
| `fine_percentage` * | integer | Percentage amount of the fine, from 1 to 100 | - |
| `days_to_fine` * | integer | Days after due date for the fine to be charged | - |
### fine_type Enumerators
| Enumerator | Description |
|--------------------|-----------------------|
| absolute | absolute amount |
| percentage | percentage amount |
### interest_settings Object
Option 1: interest using absolute amounts (`interest_type=calendar_days_daily_amount` or `interest_type=workdays_daily_amount`)
| Field | Type | Description | Characters |
|---------------------------|---------|-------------------------------------------------------------------------------------|------------------------------------------------------------------------------------------------|
| `interest_type` * | string | Type of interest | **[interest_type Enumerators](#interest_type-enumerators)** |
| `interest_amount` * | float | Amount to be charged per determined time unit (business days or calendar days) | - |
| `days_to_interest` * | integer | Days after due date to start charging interest | - |
Option 2: interest using percentage amounts (`interest_type=calendar_days_monthly_percentage`)
| Field | Type | Description | Characters |
|--------------------------|---------|---------------------------------------------------------------------------------------|----------------------------------------------------------------------------------------------------|
| `interest_type` * | string | Type of interest | **[interest_type Enumerators](#interest_type-enumerators)** |
| `interest_percentage` * | integer | Percentage to be charged per determined time unit (business days or calendar days) | - |
| `days_to_interest` * | integer | Days after due date to start charging interest | - |
### interest_type Enumerators
| Enumerator | Description |
|----------------------------------|----------------------------------------------------------------------|
| calendar_days_daily_amount | Daily amount over calendar days |
| workdays_daily_amount | Daily amount over business days |
| calendar_days_monthly_percentage | Interest percentage charged monthly, based on calendar days |
### qr_code_settings Object
| Field | Type | Description | Characters |
|----------------------------------|---------|-----------------------------------------------------------------------------|-------------|
| `pix_key` * | uuidv4 | Random type Pix key | 36 |
| `qr_code_on_discharge_enabled` * | boolean | Determines if QR Code information will appear in the return file (CNAB) | - |
:::info Information
The PIX copy and paste will be returned in the CNAB file at position 029 to 105.
:::
:::caution 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
| Field | Type | Description | Characters |
|----------------------------------|---------|-----------------------------------------------------------------------------|-------------|
| `default_bank` | string | Default bank layout for CNAB file processing | **[default_bank Enumerators](#default_bank-enumerators)** |
| `preferred_layout` | string | Preferred layout for CNAB files | **[preferred_layout Enumerators](#preferred_layout-enumerators)** |
### default_bank Enumerators
| Enumerator | Description |
|--------------------|-----------------------|
| santander | Santander Bank |
| itau | Itaú Bank |
| bradesco | Bradesco Bank |
| qi_scd | QI SCD |
### preferred_layout Enumerators
| Enumerator | Description |
|--------------------|-----------------------|
| 400 | CNAB 400 Layout |
| 240 | CNAB 240 Layout |
## Response
STATUS 202
Response Body
```json
{
"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
| Field | Type | Description | Characters |
|----------------------------|---------|------------------------------------------------------------------------------------|--------------------------------------------------------------|
| `requester_profile_key` * | uuidv4 | Unique wallet identification key in uuid v4 format | 36 |
| `requester_profile_code` * | string | Unique wallet identification code | 19 |
| `request_control_key` * | uuidv4 | Unique request identification key used by the client in uuid v4 format | 36 |
| `account_key` * | uuidv4 | Unique account identification key in uuid v4 format | 36 |
| `requester_profile_status` * | string | Wallet status | **[requester_profile_status Enumerators](#requester_profile_status-enumerators)** |
| `configuration_data` * | object | Wallet default configurations | **[configuration_data Object](#configuration_data-object)** |
### profile_status Enumerators
| Enumerator | Description |
|----------------------------------|----------------------------------------------------------------------|
| pending | Wallet accepted and pending confirmation |
## Error Response
STATUS 4xx
Response Body: Error
```json
{
"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` |
|--------------------------|----------------------|----------------------------------------------------|-------------------------------------------------------------------------------------------------------------------------|------------------------------------------------------------------------------------------------------------------------|
| 400 | QIT000001 | Bad Request | Schema Error | Schema Inválido |
| 404 | BKS000001 | Not Found | Person not found with key: {`person_key`}` | Pessoa não encontrada com a chave: {`person_key`}` |
| 404 | BKS000004 | Not Found | Pix key not found: `{pix_key}` | Chave pix não encontrada: `{pix_key}` |
| 403 | BKS000005 | Forbidden | User is not allowed to do this action | Usuário não tem autorização para fazer essa ação |
| 404 | BKS000006 | Not Found | The source account key was not found. | A chave da conta de origem não foi encontrada. |
| 400 | BKS000007 | Bad Request | It 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. |
| 400 | BKS000008 | Bad Request | The source account is closed. | A conta de origem está fechada. |
| 400 | BKS000009 | Bad Request | The source account is blocked. | A conta de origem está bloqueada. |
| 403 | BKS000010 | Forbidden | The pix key owner does not match the account owner. | O proprietário da chave pix não corresponde ao proprietário da conta. |
| 409 | BKS000014 | Conflict | Request control key already sent or duplicated sent: `{request_control_key}` | Chave de controle da requisição já utilizada ou enviada duplicada: `{request_control_key}` |
| 400 | BKS000047 | Bad Request | It 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. |
---
# Edit wallet
URL: /en/documentation/boletos/carteira/editar_carteira
Wallet editing overrides the default settings (`configuration_data`) of the bill wallet and all its child objects.
## Request
ENDPOINT /account/ ACCOUNT_KEY /requester_profile/ REQUESTER_PROFILE_KEY
METHOD PUT
### Path parameters
| Field | Type | Description | Characters |
|-------------------------|--------|--------------------------------------------------------------|------------|
| `account_key` | uuidv4 | Unique account identification key in uuid v4 format | 36 |
| `requester_profile_key` | uuidv4 | Unique wallet identification key in uuid v4 format | 36 |
Request Body
```json
{
"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": "248ebea3-9bdd-44b3-a8b9-7f2bd34cd7bf",
"qr_code_on_discharge_enabled": false
},
"cnab_settings": {
"default_bank": "qi_scd",
"preferred_layout": "400"
}
}
```
### Request Body Params
| Field | Type | Description | Characters |
|----------------------------|---------|------------------------------------------------------------------------------------|------------|
| `max_payment_days` * | integer | Maximum calendar days the bill will remain available for payment after due date (can be at most 365) | - |
| `write_off_settings` | object | Default write-off configuration | **[write_off_settings object](#write_off_settings-object)** |
| `protest_settings` | object | Default protest configuration | **[protest_settings object](#protest_settings-object)** |
| `bankruptcy_protest_settings` | object | Default bankruptcy protest configuration | **[bankruptcy_protest_settings object](#bankruptcy_protest_settings-object)** |
| `fine_settings` | object | Default fine configuration | **[fine_settings object](#fine_settings-object)** |
| `interest_settings` | object | Default interest configuration | **[interest_settings object](#interest_settings-object)** |
| `qr_code_settings` | object | Default PIX QR Code configuration (for bolePix) | **[qr_code_settings object](#qr_code_settings-object)** |
| `cnab_settings` | object | Default CNAB file configuration | **[cnab_settings object](#cnab_settings-object)** |
### write_off_settings object
| Field | Type | Description | Characters |
|---------------------------|---------|-----------------------------------------------------------------------------|------------|
| `days_to_write_off` * | integer | Days after due date for the bill to be automatically written off | - |
### protest_settings object
| Field | Type | Description | Characters |
|---------------------------|---------|-----------------------------------------------------------------------------|------------|
| `days_to_protest` * | integer | Days after due date for the bill to be automatically protested | - |
### bankruptcy_protest_settings object
| Field | Type | Description | Characters |
|--------------------------------|---------|-----------------------------------------------------------------------------|-------------|
| `days_to_bankruptcy_protest` * | integer | Days after due date for a bankruptcy protest process to be automatically started | - |
### fine_settings object
Option 1: absolute value fine (`fine_type=absolute`)
| Field | Type | Description | Characters |
|---------------------------|---------|---------------------------------------------------------|-------------------------------------------------------------------------|
| `fine_type` * | string | Fine type | **[fine_type enumerators](#fine_type-enumerators)** |
| `fine_amount` * | float | Fine absolute value | - |
| `days_to_fine` * | integer | Days after due date for the fine to be charged | - |
Option 2: percentage value fine (`fine_type=percentage`)
| Field | Type | Description | Characters |
|---------------------------|---------|-----------------------------------------------------------|---------------------------------------|
| `fine_type` * | string | Fine type | **[fine_type enumerators](#fine_type-enumerators)** |
| `fine_percentage` * | integer | Fine percentage value, from 1 to 100 | - |
| `days_to_fine` * | integer | Days after due date for the fine to be charged | - |
### fine_type enumerators
| Enumerator | Description |
|--------------------|-----------------------|
| absolute | absolute value |
| percentage | percentage value |
### interest_settings object
Option 1: interest using absolute values (`interest_type=calendar_days_daily_amount` or `interest_type=workdays_daily_amount`)
| Field | Type | Description | Characters |
|---------------------------|---------|-------------------------------------------------------------------------------------|------------------------------------------------------------------------------------------------|
| `interest_type` * | string | Interest type | **[interest_type enumerators](#interest_type-enumerators)** |
| `interest_amount` * | float | Amount to be charged per determined time unit (business days or calendar days) | - |
| `days_to_interest` * | integer | Days after due date to start charging interest | - |
Option 2: interest using percentage values (`interest_type=calendar_days_monthly_percentage`)
| Field | Type | Description | Characters |
|--------------------------|---------|---------------------------------------------------------------------------------------|----------------------------------------------------------------------------------------------------|
| `interest_type` * | string | Interest type | **[interest_type enumerators](#interest_type-enumerators)** |
| `interest_percentage` * | integer | Percentage to be charged per determined time unit (business days or calendar days) | - |
| `days_to_interest` * | integer | Days after due date to start charging interest | - |
### interest_type enumerators
| Enumerator | Description |
|----------------------------------|------------------------------------------------------------------|
| calendar_days_daily_amount | Daily amount on calendar days |
| workdays_daily_amount | Daily amount on business days |
| calendar_days_monthly_percentage | Monthly interest percentage charged based on calendar days |
### qr_code_settings object
| Field | Type | Description | Characters |
|----------------------------------|---------|-----------------------------------------------------------------------------|-------------|
| `pix_key` * | uuidv4 | Random type Pix key | 36 |
| `qr_code_on_discharge_enabled` * | boolean | Determines if QR Code information will appear in the return file (CNAB) | - |
:::info Information
The PIX copy and paste will be returned in the CNAB file at positions 029 to 105.
:::
:::caution Attention!
If the `qr_code_settings` object is sent in the request, this wallet will have bolePix generation as its default configuration . BolePix are bills whose payment is linked to a Pix QR Code. Therefore, the payer can make bill payments both using the bill's digital lines and by reading the linked Pix QR Codes. If payment is made via QR Code, financial settlement occurs instantly. Regarding notifications, two webhooks are sent: one at the time of the PIX transfer (payment notice, bill goes to `payment_notice` status); and another a few seconds or minutes later, after confirmation of discharge at CIP/Nuclea (paid, bill goes to `paid` status).
:::
### cnab_settings object
| Field | Type | Description | Characters |
|----------------------------------|---------|-----------------------------------------------------------------------------|-------------|
| `default_bank` | string | Default bank layout for CNAB file processing | **[default_bank enumerators](#default_bank-enumerators)** |
| `preferred_layout` | string | Preferred layout for CNAB files | **[preferred_layout enumerators](#preferred_layout-enumerators)** |
### default_bank enumerators
| Enumerator | Description |
|--------------------|-----------------------|
| santander | Banco Santander |
| itau | Banco Itaú |
| bradesco | Banco Bradesco |
| qi_scd | QI SCD |
### preferred_layout enumerators
| Enumerator | Description |
|--------------------|-----------------------|
| 400 | CNAB 400 Layout |
| 240 | CNAB 240 Layout |
## Response
STATUS 200
Response Body
```json
{
"requester_profile_key": "c92e8666-e310-4a72-b15e-753525684ae2",
"requester_profile_code": "329-48-2628-2625918",
"request_control_key": "727a5f00-1f86-4a7a-9aa5-c45cf8a2394c",
"account_key": "e0089187-ab08-42c0-82f2-259d40726117",
"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": "248ebea3-9bdd-44b3-a8b9-7f2bd34cd7bf",
"qr_code_on_discharge_enabled": false
},
"cnab_settings": {
"default_bank": "qi_scd",
"preferred_layout": "400"
}
}
}
```
### Response Body Params
| Field | Type | Description | Characters |
|----------------------------|---------|------------------------------------------------------------------------------------|--------------------------------------------------------------|
| `requester_profile_key` * | uuidv4 | Unique wallet identification key in uuid v4 format | 36 |
| `requester_profile_code` * | string | Unique wallet identification code | 19 |
| `request_control_key` * | uuidv4 | Unique request identification key used by the client in uuid v4 format | 36 |
| `account_key` * | uuidv4 | Unique account identification key in uuid v4 format | 36 |
| `requester_profile_status` * | string | Wallet status | **[requester_profile_status enumerators](#requester_profile_status-enumerators)** |
| `configuration_data` * | object | Default wallet configurations | **[configuration_data object](#configuration_data-object)** |
### profile_status enumerators
| Enumerator | Description |
|----------------------------------|------------------------------------------------------------------|
| pending | Wallet accepted and pending confirmation |
| opened | Wallet opened |
## Error Response
STATUS 4xx
Response Body: Error
```json
{
"title": "titulo",
"description": "description in English",
"translation": "descrição em portugues",
"code": "codigo",
"extra_fields": {}
}
```
| HTTP Status `status` | QI Code `code` | Title `title` | Description (eng) `description` | Description (pt-br) `translation` |
|--------------------------|----------------------|----------------------------------------------------|-------------------------------------------------------------------------------------------------------------------------|------------------------------------------------------------------------------------------------------------------------|
| 400 | QIT000001 | Bad Request | Schema Error | Schema Inválido |
| 404 | BKS000001 | Not Found | Person not found with key: {`person_key`}` | Pessoa não encontrada com a chave: {`person_key`}` |
| 404 | BKS000004 | Not Found | Pix key not found: `{pix_key}` | Chave pix não encontrada: `{pix_key}` |
| 403 | BKS000005 | Forbidden | User is not allowed to do this action | Usuário não tem autorização para fazer essa ação |
| 404 | BKS000006 | Not Found | The source account key was not found. | A chave da conta de origem não foi encontrada. |
| 400 | BKS000007 | Bad Request | It 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. |
| 400 | BKS000008 | Bad Request | The source account is closed. | A conta de origem está fechada. |
| 400 | BKS000009 | Bad Request | The source account is blocked. | A conta de origem está bloqueada. |
| 403 | BKS000010 | Forbidden | The pix key owner does not match the account owner. | O proprietário da chave pix não corresponde ao proprietário da conta. |
| 409 | BKS000014 | Conflict | Request control key already sent or duplicated sent: `{request_control_key}` | Chave de controle da requisição já utilizada ou enviada duplicada: `{request_control_key}` |
| 400 | BKS000047 | Bad Request | It 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. |
---
# List Account Wallets
URL: /en/documentation/boletos/carteira/listar_carteiras
The wallet listing will return all bank slip wallets for the account that match the query parameters sent in the request.
## Request
ENDPOINT /account/ ACCOUNT_KEY /requester_profiles
METHOD GET
### Path parameters
| Field | Type | Description | Characters |
|-------------------------|--------|--------------------------------------------------------------|------------|
| `account_key` | uuidv4 | Unique account identification key, in uuid v4 format | 36 |
### Query parameters
| Field | Type | Description | Characters |
|--------------------------|--------|---------------------------------------------------------------------------|------------|
| `request_control_key` | uuidv4 | Unique request identification key, in uuid v4 format | 36 |
| `requester_profile_key` | uuidv4 | Unique bank slip wallet identification key, in uuid v4 format | 36 |
| `requester_profile_code` | string | Unique wallet identification code | 19 |
| `page` | integer| Page number | - |
| `page_size` | integer| Page size | - |
## Response
STATUS 200
Response Body
```json
{
"data": [
{
"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"
}
}
}
],
"pagination": {
"current_page": 1,
"rows_per_page": 100
}
}
```
### Response Body Parameters
| Field | Type | Description | Characters |
|----------------|--------------|-----------------------------------|-----------------------------------------------------------|
| `data` * | object array | Bank slip wallets | **[requester_profile Object](#requester_profile-object)** |
| `pagination` * | object | Pagination information | **[pagination Object](#pagination-object)** |
### requester_profile Object
| Field | Type | Description | Characters |
|----------------------------|---------|------------------------------------------------------------------------------------|--------------------------------------------------------------|
| `requester_profile_key` * | uuidv4 | Unique wallet identification key in uuid v4 format | 36 |
| `requester_profile_code` * | string | Unique wallet identification code | 19 |
| `request_control_key` * | uuidv4 | Unique request identification key used by the client in uuid v4 format | 36 |
| `account_key` * | uuidv4 | Unique account identification key in uuid v4 format | 36 |
| `requester_profile_status` * | string | Wallet status | **[requester_profile_status Enumerators](#requester_profile_status-enumerators)** |
| `configuration_data` * | object | Wallet default settings | **[configuration_data Object](#configuration_data-object)** |
### requester_profile_status Enumerators
| Enumerator | Description |
|----------------------------------|------------------------------------------------------------------|
| pending | Accepted wallet pending confirmation |
| opened | Open wallet |
### pagination Object
| Field | Type | Description | Characters |
|----------------------------|---------|--------------------------------------------------------------|------------|
| `current_page` * | integer | Current page | - |
| `rows_per_page` * | integer | Items per page | - |
### configuration_data Object
| Field | Type | Description | Characters |
|----------------------------|---------|------------------------------------------------------------------------------------|------------|
| `max_payment_days` * | integer | Maximum calendar days the bank slip will be available for payment after due date (maximum 365) | - |
| `write_off_settings` | object | Default write-off configuration | **[write_off_settings Object](#write_off_settings-object)** |
| `protest_settings` | object | Default protest configuration | **[protest_settings Object](#protest_settings-object)** |
| `bankruptcy_protest_settings` | object | Default bankruptcy protest configuration | **[bankruptcy_protest_settings Object](#bankruptcy_protest_settings-object)** |
| `fine_settings` | object | Default fine configuration | **[fine_setings Object](#fine_settings-object)** |
| `interest_settings` | object | Default interest configuration | **[interest_settings Object](#interest_settings-object)** |
| `qr_code_settings` | object | Default PIX QR Code configuration (for bolePix) | **[qr_code_settings Object](#qr_code_settings-object)** |
| `cnab_settings` | object | Default CNAB file configuration | **[cnab_settings Object](#cnab_settings-object)** |
### write_off_settings Object
| Field | Type | Description | Characters |
|---------------------------|---------|-----------------------------------------------------------------------------|------------|
| `days_to_write_off` * | integer | Days after due date for the bank slip to be automatically written off | - |
### protest_settings Object
| Field | Type | Description | Characters |
|---------------------------|---------|-----------------------------------------------------------------------------|------------|
| `days_to_protest` * | integer | Days after due date for the bank slip to be automatically protested | - |
### bankruptcy_protest_settings Object
| Field | Type | Description | Characters |
|--------------------------------|---------|-----------------------------------------------------------------------------|-------------|
| `days_to_bankruptcy_protest` * | integer | Days after due date to automatically start a bankruptcy protest process | - |
### fine_settings Object
Option 1: absolute value fine (`fine_type=absolute`)
| Field | Type | Description | Characters |
|---------------------------|---------|---------------------------------------------------------|-------------------------------------------------------------------------|
| `fine_type` * | string | Fine type | **[fine_type Enumerators](#fine_type-enumerators)** |
| `fine_amount` * | float | Absolute value of the fine | - |
| `days_to_fine` * | integer | Days after due date for the fine to be charged | - |
Option 2: percentage value fine (`fine_type=percentage`)
| Field | Type | Description | Characters |
|---------------------------|---------|-----------------------------------------------------------|---------------------------------------|
| `fine_type` * | string | Fine type | **[fine_type Enumerators](#fine_type-enumerators)** |
| `fine_percentage` * | integer | Percentage value of the fine, from 1 to 100 | - |
| `days_to_fine` * | integer | Days after due date for the fine to be charged | - |
### fine_type Enumerators
| Enumerator | Description |
|--------------------|-----------------------|
| absolute | absolute value |
| percentage | percentage value |
### interest_settings Object
Option 1: interest using absolute values (`interest_type=calendar_days_daily_amount` or `interest_type=workdays_daily_amount`)
| Field | Type | Description | Characters |
|---------------------------|---------|-------------------------------------------------------------------------------------|------------------------------------------------------------------------------------------------|
| `interest_type` * | string | Interest type | **[interest_type Enumerators](#interest_type-enumerators)** |
| `interest_amount` * | float | Amount to be charged per time unit (business or calendar days) | - |
| `days_to_interest` * | integer | Days after due date to start charging interest | - |
Option 2: interest using percentage values (`interest_type=calendar_days_monthly_percentage`)
| Field | Type | Description | Characters |
|--------------------------|---------|---------------------------------------------------------------------------------------|----------------------------------------------------------------------------------------------------|
| `interest_type` * | string | Interest type | **[interest_type Enumerators](#interest_type-enumerators)** |
| `interest_percentage` * | integer | Percentage to be charged per time unit (business or calendar days) | - |
| `days_to_interest` * | integer | Days after due date to start charging interest | - |
### interest_type Enumerators
| Enumerator | Description |
|----------------------------------|------------------------------------------------------------------|
| calendar_days_daily_amount | Daily amount over calendar days |
| workdays_daily_amount | Daily amount over business days |
| calendar_days_monthly_percentage | Monthly interest percentage charged based on calendar days |
### qr_code_settings Object
| Field | Type | Description | Characters |
|----------------------------------|---------|-----------------------------------------------------------------------------|-------------|
| `pix_key` * | uuidv4 | Random type PIX key | 36 |
| `qr_code_on_discharge_enabled` * | boolean | Determines if QR Code information will appear in the return file (CNAB) | - |
### cnab_settings Object
| Field | Type | Description | Characters |
|----------------------------------|---------|-----------------------------------------------------------------------------|-------------|
| `default_bank` | string | Default bank layout for CNAB file processing | **[default_bank Enumerators](#default_bank-enumerators)** |
| `preferred_layout` | string | Preferred layout for CNAB files | **[preferred_layout Enumerators](#preferred_layout-enumerators)** |
### default_bank Enumerators
| Enumerator | Description |
|--------------------|-----------------------|
| santander | Santander Bank |
| itau | Itaú Bank |
| bradesco | Bradesco Bank |
| qi_scd | QI SCD |
### preferred_layout Enumerators
| Enumerator | Description |
|--------------------|-----------------------|
| 400 | CNAB 400 Layout |
| 240 | CNAB 240 Layout |
## Error Response
STATUS 4xx
Response Body: Error
```json
{
"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 (ptbr) `translation` |
|--------------------------|----------------------|----------------------------------------------------|-------------------------------------------------------------------------------------------------------------------------|------------------------------------------------------------------------------------------------------------------------|
| 400 | QIT000001 | Bad Request | Schema Error | Schema Inválido |
| 404 | BKS000006 | Not Found | The source account key was not found. | A chave da conta de origem não foi encontrada. |
| 400 | BKS000007 | Bad Request | It 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. |
| 400 | BKS000008 | Bad Request | The source account is closed. | A conta de origem está fechada. |
| 400 | BKS000009 | Bad Request | The source account is blocked. | A conta de origem está bloqueada. |
| 400 | BKS000012 | Bad Request | Invalid integer value for page or size query string parameters. | Valor inválido para parâmetros de página ou tamanho de página. |
| 404 | BKS000013 | Not Found | Requester profile not found | Carteira não encontrada |
| 400 | BKS000025 | Bad Request | Invalid bank slip status. | Status de boleto inválido. |
---
# Query temporary file
URL: /en/documentation/boletos/cnab/consulta_por_chave
Querying a temporary CNAB file using its key returns detailed information about it, such as the number of occurrences that have already been processed and possible errors found in the file.
## Request
ENDPOINT /account/ ACCOUNT_KEY /requester_profile/ REQUESTER_PROFILE_KEY /temporary_cnab_file/ TEMPORARY_CNAB_FILE_KEY
METHOD GET
### Path parameters
| Field | Type | Description | Characters |
|-------------------------|--------|--------------------------------------------------------------|------------|
| `account_key` | uuidv4 | Unique account identification key in uuid v4 format | 36 |
| `requester_profile_key` | uuidv4 | Unique wallet identification key in uuid v4 format | 36 |
| `temporary_cnab_file_key` | uuidv4 | Unique temporary CNAB file identification key in uuid v4 format | 36 |
## Response
STATUS 200
Response Body: Accepted file (no errors)
```json
{
"temporary_cnab_file_key": "fa4f094d-8475-4828-9105-99756914e14f",
"temporary_cnab_file_name": "240827463_t.REM",
"temporary_cnab_file_status": "read",
"occurrence_quantity": 6,
"total_processed_occurrences": 6,
"created_at": "2024-08-28T15:09:30Z"
}
```
Response Body: Rejected file (with errors)
```json
{
"temporary_cnab_file_key": "c16baa13-0969-46a7-a85f-6f975d266d9f",
"temporary_cnab_file_name": "240905623.REM",
"temporary_cnab_file_status": "rejected",
"occurrence_quantity": 0,
"total_processed_occurrences": 0,
"created_at": "2024-09-10T15:59:25Z",
"error_data": [
{
"code": "BKS000063",
"title": "Bad Request",
"description": "Invalid file code.",
"translation": "Codigo de arquivo invalido.",
"extra_fields": {
"details": "Invalid file code. Expected: '1'. Got: '0'.",
"file_line": 1,
"details_pt_br": "Código de arquivo inválido. Esperado: '1'. Recebido: '0'.",
"cnab_file_name": "240905623.REM",
"cnab_inline_end_position": 2,
"cnab_inline_start_position": 2
}
},
{
"code": "BKS000069",
"title": "Bad Request",
"description": "Invalid beneficiary account: beneficiary account is not the one that the requester profiles belongs to.",
"translation": "Conta do beneficiario invalida: a conta do beneficiario nao e aquela a qual a carteira de boletos pertence.",
"extra_fields": {
"details": "Invalid beneficiary account header on header. Expected: '1927400'. Got: '3;53179'.",
"file_line": 1,
"details_pt_br": "Conta do beneficiário inválida no header. Esperado: '1927400'. Recebido: '3;53179'.",
"cnab_file_name": "240905623.REM",
"cnab_inline_end_position": 46,
"cnab_inline_start_position": 40
}
},
{
"code": "BKS000064",
"title": "Bad Request",
"description": "Invalid bank code (014).",
"translation": "Codigo do banco invalido (014).",
"extra_fields": {
"details": "Invalid bank code. Expected: '329'. Got: '014'",
"bank_code": "014",
"details_pt_br": "Código do banco inválido. Esperado: '329'. Recebido: '014'",
"cnab_file_name": "240905623.REM"
}
},
{
"code": "BKS000056",
"title": "Bad Request",
"description": "Invalid record sequence.",
"translation": "Sequencia invalida de registros.",
"extra_fields": {
"cnab_line": 1,
"cnab_file_name": "240905623.REM"
}
},
{
"code": "BKS000056",
"title": "Bad Request",
"description": "Invalid record sequence.",
"translation": "Sequencia invalida de registros.",
"extra_fields": {
"cnab_line": 2,
"cnab_file_name": "240905623.REM"
}
},
{
"code": "BKS000086",
"title": "Bad Request",
"description": "File missing trailler record.",
"translation": "Arquivo sem registro trailler.",
"extra_fields": {
"file_line": 3,
"cnab_file_name": "240905623.REM"
}
}
]
}
```
### Response Body Params
| Field | Type | Description | Characters |
|----------------------------|---------|------------------------------------------------------------------------------------|--------------------------------------------------|
| `temporary_cnab_file_key` *| uuidv4 | Unique temporary CNAB file identification key in uuid v4 format | 36 |
| `temporary_cnab_file_name` *| uuidv4 | File name | 100 |
| `temporary_cnab_file_status` *| string | Temporary CNAB file status | **[temporary_cnab_file_status Enumerators](#enumeradores-temporary_cnab_file_status)** |
| `occurrence_quantity` * | integer | Number of occurrences in the file | - |
| `total_processed_occurrences` *| integer | Number of occurrences already processed | - |
| `error_data` | object array | Error objects found in the file, in JSON format, following the same pattern returned by the APIs | **[error_data Object](#objeto-error_data)** |
| `created_at` * | string | Timestamp of when the file was created in the database, in ISO Zulu format | 20 |
### Enumeradores temporary_cnab_file_status
| Enumerator | Description |
|------------------------------|------------------------------------------------------------------------------|
| uploaded | upload successful, but file has not yet started being processed |
| processing | file being read |
| read | file read and accepted |
| rejected | file read and rejected due to syntactic error |
### Objeto error_data
| Field | Type | Description | Characters |
|----------------------------|---------|------------------------------------------------------------------------------------|--------------------------------------------------|
| `code` * | string | Error code | 9 |
| `title` * | string | Error title | 100 |
| `description` * | string | Error description in English | 100 |
| `translation` * | integer | Translation of error description | 100 |
| `extra_fields` | object | Additional information about the error | - |
:::danger Important
The fields returned in the `extra_fields` object serve to provide additional information about the error and may vary. Therefore, they should not be mapped in a restrictive manner.
:::
## Error Response
STATUS 4xx
Response Body: Error
```json
{
"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 (ptbr) `translation` |
|--------------------------|----------------------|----------------------------------------------------|-------------------------------------------------------------------------------------------------------------------------|------------------------------------------------------------------------------------------------------------------------|
| 400 | QIT000001 | Bad Request | Schema Error | Schema Inválido |
| 404 | BKS000006 | Not Found | The source account key was not found. | A chave da conta de origem não foi encontrada. |
| 400 | BKS000007 | Bad Request | It 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. |
| 400 | BKS000008 | Bad Request | The source account is closed. | A conta de origem está fechada. |
| 400 | BKS000009 | Bad Request | The source account is blocked. | A conta de origem está bloqueada. |
| 404 | BKS000013 | Not Found | Requester profile not found | Carteira não encontrada |
| 404 | BKS000054 | Not Found | Remittance not found with key: `{temporary_cnab_file_key}` | Remessa não encontrada com a chave: `{temporary_cnab_file_key}` |
---
# Remittance files (CNAB) - Introduction
URL: /en/documentation/boletos/cnab/introducao
:::info
The file transmitted in this call must follow the QI Tech Collection File Layout standard with 400 positions.
Here is the link to download the manual: [Layout de Cobrança - QI Tech versão 2.1.](https://storage.googleapis.com/live-doc-api/public_samples/Layout%20de%20Cobran%C3%A7a%20-%20QI%20Tech%20v2.1.pdf)
:::
Remittance files (CNAB) offer the possibility to send multiple boleto record instructions, along with other types of instructions (extension, discount, cancellation, etc.), for different boletos, in a single file. When sending instructions such as those mentioned (extension, discount, etc.) for existing boletos, the boleto is identified by the portfolio code (`requester_profile_code`) and by our number (`our_number`).
When uploading a CNAB file, if the request is successful (response code `202`), a temporary CNAB file (`TemporaryCNABFile`) will be created. It is possible to check the file processing status --- as well as possible errors, both in the file itself and in its occurrences ---, using the endpoints for [**temporary CNAB file query**](/documentation/boletos/cnab/consulta_por_chave) and [**its occurrences**](/documentation/boletos/cnab/listar_ocorrencias_temporarias).
The file will be rejected if any syntactic error is found. However, it is read entirely, or until a limit of 100 errors is reached, so that all errors can be returned and corrected in a more practical and efficient manner.
While the file is being read, temporary occurrences are created, which will only be processed if it is accepted. That is, if the file is rejected (status `rejected`), all its occurrences will also be . Furthermore, if the file is rejected, no more temporary occurrences are created for it. Therefore, it is common for rejected file entries to have fewer occurrences than the number of occurrences sent in the file.
On the other hand, when the file is completely read and accepted (status `read`), the creation of definitive occurrences begins, which will be the instructions that will actually take effect. If a temporary occurrence shows the status `rejected`, it means that some semantic error was found in it --- that is, some error in its content. In this case, there will be an `error_data` object along with it, which provides details about the reason for rejection. In contrast, if it shows the status `processed`, it means that the definitive occurrence has already been created and sent to CIP/Nuclea. More details about each of these entities are provided in the subsequent pages for querying files and temporary occurrences.
:::tip Credit Split via CNAB
To inform [**credit split**](/documentation/boletos/instrucoes/rateio_de_credito) (split payment) in CNAB files:
- **QI SCD (CNAB400 - QI Tech v2.1 layout):** detail record with `identificacao_registro = 3`. Full details in the **[Layout de Cobrança - QI Tech v2.1](https://storage.googleapis.com/live-doc-api/public_samples/Layout%20de%20Cobran%C3%A7a%20-%20QI%20Tech%20v2.1.pdf)**.
- **Bradesco (CNAB400 and CNAB240):** detail record type `3`.
- **Itaú (CNAB400 and CNAB240):** detail record type `4`.
- **Santander:** does not support credit split via CNAB. Use the REST endpoint [**Credit Split Update**](/documentation/boletos/instrucoes/rateio_de_credito) or include `split_payment_data` in the issuance via API.
**How to map N recipients:** Each split record fits up to **3 additional accounts** (account number + check digit + percentage). For more than 3 recipients, add **multiple split records in sequence** after the bank slip's main record — they are accumulated in the same occurrence. Example: 7 accounts = 3 records (3 + 3 + 1).
**Restrictions (all banks):**
- Only **percentage**-based calculation is supported (`calculation code = 2`).
- The sum of percentages (beneficiary + splits) must be exactly **100**.
- Total recipient limit follows the same as the REST API (up to 10 additional accounts).
- The `beneficiary_max_amount` field (split with maximum beneficiary amount and surplus directed to the first rule) is **REST API exclusive**. It is not supported via CNAB. For this scenario, use the REST endpoint for [**issuance**](/documentation/boletos/emissao/emissao_boleto_unico_padrao) or for [**credit split update**](/documentation/boletos/instrucoes/rateio_de_credito).
:::
---
# List temporary remittance files
URL: /en/documentation/boletos/cnab/listar_arquivos_temporarios
The listing of temporary CNAB files will return all temporary CNAB files from the wallet that match the query parameters sent in the request.
## Request
ENDPOINT /account/ ACCOUNT_KEY /requester_profile/ REQUESTER_PROFILE_KEY /temporary_cnab_file
METHOD GET
### Path parameters
| Field | Type | Description | Characters |
|-------------------------|--------|--------------------------------------------------------------|------------|
| `account_key` | uuidv4 | Unique account identification key, in uuid v4 format | 36 |
| `requester_profile_key` | uuidv4 | Unique wallet identification key, in uuid v4 format | 36 |
### Query parameters
| Field | Type | Description | Characters |
|-------------------------|--------|--------------------------------------------------------------|-------------------------|
| `temporary_cnab_file_status` | string | Status of the temporary CNAB file | **[temporary_cnab_file_status enumerators](#temporary_cnab_file_status-enumerators)** |
| `page` | integer| Page number | - |
| `page_size` | integer| Page size | - |
### temporary_cnab_file_status enumerators
| Enumerator | Description |
|------------------------------|------------------------------------------------------------------------------|
| uploaded | upload completed successfully, but file processing has not started yet |
| processing | file being read |
| read | file read and accepted |
| rejected | file read and rejected due to syntactic error |
## Response
STATUS 200
Response Body
```json
{
"data": [
{
"temporary_cnab_file_key": "a6db5f8b-1ed7-4d13-9cbf-f3c4275e3ca3",
"temporary_cnab_file_name": "240903573.REM",
"temporary_cnab_file_status": "processing",
"occurrence_quantity": null,
"created_at": "2024-09-07T15:44:01Z"
},
{
"temporary_cnab_file_key": "2351c4ae-9a01-4675-86e4-099a30dafa42",
"temporary_cnab_file_name": "240904603.REM",
"temporary_cnab_file_status": "rejected",
"occurrence_quantity": 0,
"created_at": "2024-09-06T12:35:50Z"
},
{
"temporary_cnab_file_key": "fa4f094d-8475-4828-9105-99756914e14f",
"temporary_cnab_file_name": "240827463_t.REM",
"temporary_cnab_file_status": "read",
"occurrence_quantity": 10424,
"created_at": "2024-08-28T15:09:30Z"
},
{
"temporary_cnab_file_key": "e99cea6d-0d1c-4ec3-a2c6-bc603aede7c6",
"temporary_cnab_file_name": "240827443_t.REM",
"temporary_cnab_file_status": "read",
"occurrence_quantity": 542,
"created_at": "2024-08-27T20:07:11Z"
},
{
"temporary_cnab_file_key": "2351c4ae-9a01-4675-86e4-099a30dafa42",
"temporary_cnab_file_name": "240812604.REM",
"temporary_cnab_file_status": "rejected",
"occurrence_quantity": 0,
"created_at": "2024-08-12T12:52:13Z"
}
],
"pagination": {
"current_page": 1,
"rows_per_page": 100
}
}
```
### Response Body Params
| Field | Type | Description | Characters |
|------------------|--------------|---------------------------------------|---------------------------------------------|
| `data` * | object array | Temporary CNAB files | **[temporary_cnab_file object](#temporary_cnab_file-object)** |
| `pagination` * | object | Pagination information | **[pagination object](#pagination-object)** |
### temporary_cnab_file object
| Field | Type | Description | Characters |
|----------------------------|---------|------------------------------------------------------------------------------------|--------------------------------------------------|
| `temporary_cnab_file_key` *| uuidv4 | Unique identification key for the temporary CNAB file in uuid v4 format | 36 |
| `temporary_cnab_file_name` *| uuidv4 | File name | 100 |
| `temporary_cnab_file_status` *| string | Status of the temporary CNAB file | **[temporary_cnab_file_status enumerators](#temporary_cnab_file_status-enumerators)** |
| `occurrence_quantity` * | integer | Number of occurrences in the file | - |
| `created_at` * | string | Timestamp of file creation time in the database, in ISO Zulu format | 20 |
### pagination object
| Field | Type | Description | Characters |
|----------------------------|---------|------------------------------------------------------------------------------------|--------------------------------------------------------------|
| `current_page` * | integer | Current page | - |
| `rows_per_page` * | integer | Items per page | - |
## Error Response
STATUS 4xx
Response Body: Error
```json
{
"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` |
|--------------------------|----------------------|----------------------------------------------------|-------------------------------------------------------------------------------------------------------------------------|------------------------------------------------------------------------------------------------------------------------|
| 403 | BKS000005 | Forbidden | User is not allowed to do this action | Usuário não tem autorização para fazer essa ação |
| 404 | BKS000006 | Not Found | The source account key was not found. | A chave da conta de origem não foi encontrada. |
| 400 | BKS000007 | Bad Request | It 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. |
| 400 | BKS000008 | Bad Request | The source account is closed. | A conta de origem está fechada. |
| 400 | BKS000009 | Bad Request | The source account is blocked. | A conta de origem está bloqueada. |
| 400 | BKS000012 | Bad Request | Invalid integer value for page or size query string parameters. | Valor inválido para parâmetros de página ou tamanho de página. |
| 404 | BKS000013 | Not Found | Requester profile not found | Carteira não encontrada |
---
# List temporary occurrences
URL: /en/documentation/boletos/cnab/listar_ocorrencias_temporarias
The listing of temporary occurrences will return all temporary occurrences from a given CNAB file.
:::info
When a CNAB file is rejected due to syntactic error, temporary occurrences related to it are no longer created, since they would all be rejected because the file was rejected. Therefore, when the file is rejected, it is possible that the number of temporary occurrences related to the file is less than the number of occurrences sent in it.
:::
## Request
ENDPOINT /account/ ACCOUNT_KEY /requester_profile/ REQUESTER_PROFILE_KEY /temporary_cnab_file / TEMPORARY_CNAB_FILE_KEY /occurrences
METHOD GET
### Path parameters
| Field | Type | Description | Characters |
|-------------------------|--------|--------------------------------------------------------------|------------|
| `account_key` | uuidv4 | Unique account identification key, in uuid v4 format | 36 |
| `requester_profile_key` | uuidv4 | Unique wallet identification key, in uuid v4 format | 36 |
### Query parameters
| Field | Type | Description | Characters |
|-------------------------|--------|--------------------------------------------------------------|-------------------------|
| `occurrence_status` | string | Temporary occurrence status | **[occurrence_status enumerators](#enumeradores-temporary_cnab_file_status)** |
| `occurrence_type` | string | Temporary occurrence type | **[occurrence_type enumerators](#enumeradores-temporary_cnab_file_type)** |
| `page` | integer| Page number | - |
| `page_size` | integer| Page size | - |
### occurrence_status enumerators
| Enumerator | Description |
|------------------------------|------------------------------------------------------------------------------|
| pending | occurrence has not been processed yet |
| processed | occurrence processed successfully |
| rejected | occurrence processed and rejected due to semantic error |
### occurrence_type enumerators
| Enumerator | Description |
|--------------------------------------|------------------------------------------------------------------------------|
| registration | bank slip registration |
| write_off | bank slip write-off |
| rebate | bank slip amount rebate |
| cancel_rebate | rebate cancellation |
| extension | payment date extension |
| protest_request | protest request |
| bankruptcy_protest_request | bankruptcy protest request |
| protest_cancel_and_write_off_request | protest request cancellation and bank slip write-off |
| protest_cancel_request | protest request cancellation |
| bank_slip_edit | edit other bank slip data |
## Response
STATUS 200
Response Body
```json
{
"data": [
{
"occurrence_key": "191f2220-1465-47d7-8c81-67d8f59f5af2",
"occurrence_status": "rejected",
"occurrence_type": "registration",
"occurrence_our_number": 12455,
"error_data": {
"code": "BKS000069",
"title": "Bad Request",
"description": "Invalid beneficiary account: beneficiary account is not the one that the requester profiles belongs to.",
"translation": "Conta do beneficiario invalida: a conta do beneficiario nao e aquela a qual a carteira de boletos pertence.",
"extra_fields": {
"account_digit": "4",
"account_branch": "0001",
"account_number": "1927400"
}
}
},
{
"occurrence_key": "adc0ce54-9e69-45ec-9220-fbfe0e3ba103",
"occurrence_status": "rejected",
"occurrence_type": "registration",
"occurrence_our_number": 12453,
"error_data": {
"code": "BKS000069",
"title": "Bad Request",
"description": "Invalid beneficiary account: beneficiary account is not the one that the requester profiles belongs to.",
"translation": "Conta do beneficiario invalida: a conta do beneficiario nao e aquela a qual a carteira de boletos pertence.",
"extra_fields": {
"account_digit": "4",
"account_branch": "0001",
"account_number": "1927400"
}
}
},
{
"occurrence_key": "0521c4db-b243-4599-af2f-c288a299948a",
"occurrence_status": "rejected",
"occurrence_type": "registration",
"occurrence_our_number": 12452,
"error_data": {
"code": "BKS000069",
"title": "Bad Request",
"description": "Invalid beneficiary account: beneficiary account is not the one that the requester profiles belongs to.",
"translation": "Conta do beneficiario invalida: a conta do beneficiario nao e aquela a qual a carteira de boletos pertence.",
"extra_fields": {
"account_digit": "4",
"account_branch": "0001",
"account_number": "1927400"
}
}
},
{
"occurrence_key": "f0875275-dea0-4e93-a665-a24e921d0a95",
"occurrence_status": "rejected",
"occurrence_type": "registration",
"occurrence_our_number": 12451,
"error_data": {
"code": "BKS000069",
"title": "Bad Request",
"description": "Invalid beneficiary account: beneficiary account is not the one that the requester profiles belongs to.",
"translation": "Conta do beneficiario invalida: a conta do beneficiario nao e aquela a qual a carteira de boletos pertence.",
"extra_fields": {
"account_digit": "4",
"account_branch": "0001",
"account_number": "1927400"
}
}
},
{
"occurrence_key": "98ac54d9-0b3c-45a6-86e1-4b79d25f6364",
"occurrence_status": "rejected",
"occurrence_type": "registration",
"occurrence_our_number": 12450,
"error_data": {
"code": "BKS000069",
"title": "Bad Request",
"description": "Invalid beneficiary account: beneficiary account is not the one that the requester profiles belongs to.",
"translation": "Conta do beneficiario invalida: a conta do beneficiario nao e aquela a qual a carteira de boletos pertence.",
"extra_fields": {
"account_digit": "4",
"account_branch": "0001",
"account_number": "1927400"
}
}
},
{
"occurrence_key": "dd2c8d76-d663-4dbb-9c8b-84a627156147",
"occurrence_status": "rejected",
"occurrence_type": "registration",
"occurrence_our_number": 12449,
"error_data": {
"code": "BKS000069",
"title": "Bad Request",
"description": "Invalid beneficiary account: beneficiary account is not the one that the requester profiles belongs to.",
"translation": "Conta do beneficiario invalida: a conta do beneficiario nao e aquela a qual a carteira de boletos pertence.",
"extra_fields": {
"account_digit": "4",
"account_branch": "0001",
"account_number": "1927400"
}
}
}
],
"pagination": {
"current_page": 1,
"rows_per_page": 100
}
}
```
### Response Body Params
| Field | Type | Description | Characters |
|------------------|--------------|---------------------------------------|---------------------------------------------|
| `data` * | object array | Temporary occurrences | **[temporary_occurrence object](#objeto-temporary_occurrence)** |
| `pagination` * | object | Pagination information | **[pagination object](#objeto-pagination)** |
### temporary_cnab_file object
| Field | Type | Description | Characters |
|----------------------------|---------|------------------------------------------------------------------------------------|--------------------------------------------------|
| `occurrence_key` *| uuidv4 | Unique temporary occurrence identification key in uuid v4 format | 36 |
| `occurrence_status` * | string | Temporary occurrence status | **[temporary_occurrence_status enumerators](#enumeradores-temporary_occurrence_status)** |
| `occurrence_type` * | string | Temporary occurrence type | **[occurrence_type enumerators](#enumeradores-occurrence_type)** |
| `occurrence_our_number` * | integer | Number of occurrences in the file | - |
| `error_data` | object | Error objects found in the file, in JSON format, in the same pattern returned by the APIs | **[error_data object](#objeto-error_data)** |
### pagination object
| Field | Type | Description | Characters |
|----------------------------|---------|------------------------------------------------------------------------------------|--------------------------------------------------------------|
| `current_page` * | integer | Current page | - |
| `rows_per_page` * | integer | Items per page | - |
### error_data object
| Field | Type | Description | Characters |
|----------------------------|---------|------------------------------------------------------------------------------------|--------------------------------------------------|
| `code` * | string | Error code | 9 |
| `title` * | string | Error title | 100 |
| `description` * | string | Error description, in English | 100 |
| `translation` * | integer | Error description translation | 100 |
| `extra_fields` | object | Additional information about the error | - |
:::danger Important
The fields returned in the `extra_fields` object serve to provide additional information about the error and may vary. Therefore, they should not be mapped in a restrictive manner.
:::
## Error Response
STATUS 4xx
Response Body: Error
```json
{
"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` |
|--------------------------|----------------------|----------------------------------------------------|-------------------------------------------------------------------------------------------------------------------------|------------------------------------------------------------------------------------------------------------------------|
| 403 | BKS000005 | Forbidden | User is not allowed to do this action | Usuário não tem autorização para fazer essa ação |
| 404 | BKS000006 | Not Found | The source account key was not found. | A chave da conta de origem não foi encontrada. |
| 400 | BKS000007 | Bad Request | It 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. |
| 400 | BKS000008 | Bad Request | The source account is closed. | A conta de origem está fechada. |
| 400 | BKS000009 | Bad Request | The source account is blocked. | A conta de origem está bloqueada. |
| 400 | BKS000012 | Bad Request | Invalid integer value for page or size query string parameters. | Valor inválido para parâmetros de página ou tamanho de página. |
| 404 | BKS000013 | Not Found | Requester profile not found | Carteira não encontrada |
| 404 | BKS000054 | Not Found | Remittance not found with key: `{temporary_cnab_file_key}` | Remessa não encontrada com a chave: `{temporary_cnab_file_key}` |
---
# Upload CNAB file
URL: /en/documentation/boletos/cnab/upload_de_arquivo_remessa
:::caution Attention!
The call must be authenticated following the standard described in the [**Document upload**](/documentation/upload_de_documentos) section.
:::
CNAB files offer the possibility of sending multiple boleto record instructions, along with other types of instructions (extension, discount, cancellation, etc.), for different boletos, in a single file. When sending instructions like those mentioned (extension, discount, etc.) for existing boletos, the boleto is identified by the requester profile code (`requester_profile_code`) and our number (`our_number`).
:::info
When uploading a CNAB file, if the request is successful (response code `202`), a temporary CNAB file (`TemporaryCNABFile`) will be created. It is possible to check the file processing status --- as well as possible errors, both in the file itself and in its occurrences ---, using the [**temporary CNAB file query**](/documentation/boletos/cnab/consulta_por_chave) and [**its occurrences**](/documentation/boletos/cnab/listar_ocorrencias_temporarias) endpoints.
:::
## Request
ENDPOINT /account/ ACCOUNT_KEY /requester_profile/ REQUESTER_PROFILE_KEY /cnab_file
METHOD POST
### Path parameters
| Field | Type | Description | Characters |
|-------------------------|--------|--------------------------------------------------------------|------------|
| `account_key` | uuidv4 | Unique account identification key, in uuid v4 format | 36 |
| `requester_profile_key` | uuidv4 | Unique requester profile identification key, in uuid v4 format | 36 |
## Request Body Params
The following data should be sent as form-data in the request body:
| Field | Type | Description | Characters |
|-------------------------|--------|--------------------------------------------------------------|------------|
| `file` * | file | CNAB file following the standard established by QI Tech | - |
## Response
STATUS 202
Response Body
```json
{
"temporary_cnab_file_key": "f14e9bac-94ed-4eb1-87b4-7fd7b7a2d280",
"temporary_cnab_file_status": "accepted"
}
```
### Response Body Params
| Field | Type | Description | Characters |
|--------------------------------|---------|-----------------------------------------------------------------|----------------------------|
| `temporary_cnab_file_key` * | uuidv4 | Unique CNAB file identification key in uuid v4 format | 36 |
| `temporary_cnab_file_status` * | string | CNAB file status | **[temporary_cnab_file_status Enumerators](#enumeradores-cnab_file_status)** |
### temporary_cnab_file_status Enumerators
| Enumerator | Description |
|------------|---------------------------------------------------------------------------|
| uploaded | Upload successful, but file has not yet started being processed |
| processing | File being read |
| read | File read and accepted |
| rejected | File read and rejected (all file occurrences are rejected) |
## Error Response
STATUS 4xx
Response Body: Error
```json
{
"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 (ptbr) `translation` |
|--------------------------|----------------------|----------------------------------------------------|-------------------------------------------------------------------------------------------------------------------------|------------------------------------------------------------------------------------------------------------------------|
| 400 | QIT000001 | Bad Request | Schema Error | Schema Inválido |
| 404 | BKS000006 | Not Found | The source account key was not found. | A chave da conta de origem não foi encontrada. |
| 400 | BKS000007 | Bad Request | It 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. |
| 400 | BKS000008 | Bad Request | The source account is closed. | A conta de origem está fechada. |
| 400 | BKS000009 | Bad Request | The source account is blocked. | A conta de origem está bloqueada. |
| 404 | BKS000013 | Not Found | Requester profile not found | Carteira não encontrada |
| 400 | BKS000022 | Bad Request | Requester profile is not opened. | Carteira não está aberta. |
| 409 | BKS000053 | Conflict | CNAB file already received: '``' | Arquivo CNAB já recebido: '``' |
---
# Query bank slip by key
URL: /en/documentation/boletos/consulta/consulta_por_chave
Querying a bank slip using its key returns detailed information about it, such as all the instructions related to that bank slip.
## Request
ENDPOINT /account/ ACCOUNT_KEY /requester_profile/ REQUESTER_PROFILE_KEY /bank_slip/ BANK_SLIP_KEY
METHOD GET
### Path parameters
| Field | Type | Description | Characters |
|-------------------------|--------|--------------------------------------------------------------|------------|
| `account_key` | uuidv4 | Unique account identification key, in uuid v4 format | 36 |
| `requester_profile_key` | uuidv4 | Unique wallet identification key, in uuid v4 format | 36 |
| `bank_slip_key` | uuidv4 | Unique bank slip identification key, in uuid v4 format | 36 |
## Response
STATUS 200
Response Body
```json
{
"bank_slip_key": "4c2fa514-a44d-40f2-8d57-c0caf1b9165a",
"request_control_key": "0dcb3182-4d7e-4526-8f92-c15cdbc51bad",
"our_number": 26652176735,
"document_number": "DOC4561237",
"amount": "5000.00",
"rebate_amount": "0.00",
"expiration": "2024-07-12",
"barcode": "32994978900005000000001546128483498231955340",
"digitable_line": "32990001524612848349582319553408497890000500000",
"bank_teller_instructions": "Confirm payment",
"protest_data": {
"days_to_protest": 7
},
"bankruptcy_protest_data": {
"days_to_bankruptcy_protest": 14
},
"max_payment_days": 45,
"fine_data": {
"fine_type": "absolute",
"fine_amount": 100.0,
"days_to_fine": 10
},
"interest_data": {
"interest_type": "workdays_daily_amount",
"interest_amount": 10.0,
"days_to_interest": 2
},
"discounts_data": [
{
"discount_type": "absolute",
"discount_amount": 50.0,
"discount_number": 1,
"discount_limit_date": "2024-07-12"
}
],
"payer_data": {
"name": "Global Tech",
"address": {
"city": "Innovation City",
"state": "SP",
"number": "202",
"street": "101 High St.",
"complement": "Building A",
"postal_code": "57099999",
"neighborhood": "Tech Park"
},
"person_type": "legal",
"document_number": "12345678000195"
},
"guarantor_data": {
"name": "Jane Doe",
"address": {
"city": "Peaceful Town",
"state": "RJ",
"number": "303",
"street": "202 Elm St.",
"complement": "House 1",
"postal_code": "57099999",
"neighborhood": "Quiet Neighborhood"
},
"person_type": "natural",
"document_number": "23456789012"
},
"qr_code_data": {
"qr_code_key": "58bd3558-f214-4e83-9c88-1ac4c93db214",
"pix_key": "f9b05a58-9dcf-49cb-bc7f-99c5b3f1fdcb",
"receiver_conciliation_id": "a3861b53f5414b0ba6c9f800d7374474",
"url": "00020126890014br.gov.bcb.pix2567qrcode-h.dev.qitech.app/bacen/cobv/a3861b53f5414b0ba6c9f800d73744745204000053039865802BR5922BeatrizCoutodeCarvalho6012SAOJOSEDORIO61081501410062070503***6304ED95",
"image": "/9j/4AAQSkZJRgABAQAAAQABAAD/2wBDAAgGBgcGBQgHBwcJCQgKDBQNDAsLDBkSEw8UHRofHh0aHBwgJC4nICIsIxwcKDcpLDAxNDQ0Hyc5PTgyPC4zNDL/wAALCAD0APQBAREA/8QAHwAAAQUBAQEBAQEAAAAAAAAAAAECAwQFBgcICQoL/8QAtRAAAgEDAwIEAwUFBAQAAAF9AQIDAAQRBRIhMUEGE1FhByJxFDKBkaEII0KxwRVS0fAkM2JyggkKFhcYGRolJicoKSo0NTY3ODk6Q0RFRkdISUpTVFVWV1hZWmNkZWZnaGlqc3R1dnd4eXqDhIWGh4iJipKTlJWWl5iZmqKjpKWmp6ipqrKztLW2t7i5usLDxMXGx8jJytLT1NXW19jZ2uHi4+Tl5ufo6erx8vP09fb3+Pn6/9oACAEBAAA/APf6KKKKKKKKKKKKKKKKKKKKKKKKKKKKKKKKKKKKKKKKKKKKKKKKKKKKKKKKKKKKKKK+QPhl8Mv+Fjf2p/xN/wCz/sHlf8u3m79+/wD21xjZ79a7/wD4Zl/6m7/ym/8A22j/AIZl/wCpu/8AKb/9to/Zl/5mn/t0/wDa1H7TX/Mrf9vf/tGj9mX/AJmn/t0/9rVwHwy+Jv8Awrn+1P8AiUf2h9v8r/l58rZs3/7DZzv9ule//DL4Zf8ACuf7U/4m/wDaH2/yv+Xbytmzf/ttnO/26V5//wAMy/8AU3f+U3/7bR+01/zK3/b3/wC0a9A+JvxN/wCFc/2X/wASj+0Pt/m/8vPlbNmz/YbOd/t0o+JvxN/4Vz/Zf/Eo/tD7f5v/AC8+Vs2bP9hs53+3SvAPhl8Mv+Fjf2p/xN/7P+weV/y7ebv37/8AbXGNnv1r3/4m/E3/AIVz/Zf/ABKP7Q+3+b/y8+Vs2bP9hs53+3Sj4m/DL/hY39l/8Tf+z/sHm/8ALt5u/fs/21xjZ79a8A+Jvwy/4Vz/AGX/AMTf+0Pt/m/8u3lbNmz/AG2znf7dK+v6+QPib8Tf+Fjf2X/xKP7P+web/wAvPm79+z/YXGNnv1rv/wBpr/mVv+3v/wBo16B8Tfhl/wALG/sv/ib/ANn/AGDzf+Xbzd+/Z/trjGz3615//wAm5/8AUw/27/26eR5H/fzdu872xt7544D4ZfE3/hXP9qf8Sj+0Pt/lf8vPlbNm/wD2Gznf7dK+v6+QPhl8Mv8AhY39qf8AE3/s/wCweV/y7ebv37/9tcY2e/Wu/wD+GZf+pu/8pv8A9to/4Zl/6m7/AMpv/wBto/Zl/wCZp/7dP/a1fQFFFFfP/wCzL/zNP/bp/wC1q8Ar3/8AZl/5mn/t0/8Aa1H7Mv8AzNP/AG6f+1q4D4ZfDL/hY39qf8Tf+z/sHlf8u3m79+//AG1xjZ79a9/+GXxN/wCFjf2p/wASj+z/ALB5X/Lz5u/fv/2FxjZ79a8A+GXwy/4WN/an/E3/ALP+weV/y7ebv37/APbXGNnv1r6/rz/4ZfE3/hY39qf8Sj+z/sHlf8vPm79+/wD2FxjZ79a8A+Jvwy/4Vz/Zf/E3/tD7f5v/AC7eVs2bP9ts53+3Svf/AIZfE3/hY39qf8Sj+z/sHlf8vPm79+//AGFxjZ79a9Arz/4ZfDL/AIVz/an/ABN/7Q+3+V/y7eVs2b/9ts53+3SvP/2mv+ZW/wC3v/2jXAfE34m/8LG/sv8A4lH9n/YPN/5efN379n+wuMbPfrX1/XyB8Tfhl/wrn+y/+Jv/AGh9v83/AJdvK2bNn+22c7/bpX1/Xn/xN+GX/Cxv7L/4m/8AZ/2Dzf8Al283fv2f7a4xs9+tHxN+Jv8Awrn+y/8AiUf2h9v83/l58rZs2f7DZzv9uleAfDL4m/8ACuf7U/4lH9ofb/K/5efK2bN/+w2c7/bpXf8A/Jxn/Uvf2F/29+f5/wD3727fJ987u2OfQPhl8Tf+Fjf2p/xKP7P+weV/y8+bv37/APYXGNnv1rz/APZl/wCZp/7dP/a1eAV7/wDsy/8AM0/9un/taj9mX/maf+3T/wBrV9AUUUV8/wD7Mv8AzNP/AG6f+1qP+GZf+pu/8pv/ANtr0D4ZfDL/AIVz/an/ABN/7Q+3+V/y7eVs2b/9ts53+3SvP/2Zf+Zp/wC3T/2tXAfDL4Zf8LG/tT/ib/2f9g8r/l283fv3/wC2uMbPfrXf/sy/8zT/ANun/taj/hmX/qbv/Kb/APbaP2Zf+Zp/7dP/AGtR/wAm5/8AUw/27/26eR5H/fzdu872xt754P8Ak3P/AKmH+3f+3TyPI/7+bt3ne2NvfPB/w01/1KP/AJUv/tVH/Juf/Uw/27/26eR5H/fzdu872xt7544D4ZfDL/hY39qf8Tf+z/sHlf8ALt5u/fv/ANtcY2e/Wu//AOGZf+pu/wDKb/8Aba8Ar6/+GXxN/wCFjf2p/wASj+z/ALB5X/Lz5u/fv/2FxjZ79a8A+Jvwy/4Vz/Zf/E3/ALQ+3+b/AMu3lbNmz/bbOd/t0r3/AOGXxN/4WN/an/Eo/s/7B5X/AC8+bv37/wDYXGNnv1rz/wD4Zl/6m7/ym/8A22vQPhl8Tf8AhY39qf8AEo/s/wCweV/y8+bv37/9hcY2e/WvP/8AhmX/AKm7/wApv/22j9mX/maf+3T/ANrV9AV8/wD7Mv8AzNP/AG6f+1qP+GZf+pu/8pv/ANtr0D4ZfDL/AIVz/an/ABN/7Q+3+V/y7eVs2b/9ts53+3SvP/2Zf+Zp/wC3T/2tX0BRRRXz/wD8My/9Td/5Tf8A7bR/wzL/ANTd/wCU3/7bR/wzL/1N3/lN/wDttegfDL4Zf8K5/tT/AIm/9ofb/K/5dvK2bN/+22c7/bpXgHwy+Jv/AArn+1P+JR/aH2/yv+Xnytmzf/sNnO/26V7/APDL4Zf8K5/tT/ib/wBofb/K/wCXbytmzf8A7bZzv9ulHwy+GX/Cuf7U/wCJv/aH2/yv+Xbytmzf/ttnO/26UfDL4Zf8K5/tT/ib/wBofb/K/wCXbytmzf8A7bZzv9ulef8A/Juf/Uw/27/26eR5H/fzdu872xt7549A+GXwy/4Vz/an/E3/ALQ+3+V/y7eVs2b/APbbOd/t0o+GXwy/4Vz/AGp/xN/7Q+3+V/y7eVs2b/8AbbOd/t0rz/8AZl/5mn/t0/8Aa1H7Mv8AzNP/AG6f+1q9A+GXwy/4Vz/an/E3/tD7f5X/AC7eVs2b/wDbbOd/t0rwD4ZfE3/hXP8Aan/Eo/tD7f5X/Lz5WzZv/wBhs53+3Sj4ZfE3/hXP9qf8Sj+0Pt/lf8vPlbNm/wD2Gznf7dK7/wD5Nz/6mH+3f+3TyPI/7+bt3ne2NvfPHoHwy+GX/Cuf7U/4m/8AaH2/yv8Al28rZs3/AO22c7/bpR8Mvhl/wrn+1P8Aib/2h9v8r/l28rZs3/7bZzv9ulef/wDJuf8A1MP9u/8Abp5Hkf8Afzdu872xt754P2Zf+Zp/7dP/AGtXoHwy+GX/AArn+1P+Jv8A2h9v8r/l28rZs3/7bZzv9ulHwy+GX/Cuf7U/4m/9ofb/ACv+Xbytmzf/ALbZzv8AbpXn/wDwzL/1N3/lN/8AttH/AAzL/wBTd/5Tf/ttH/DMv/U3f+U3/wC216B8Mvhl/wAK5/tT/ib/ANofb/K/5dvK2bN/+22c7/bpXoFFFFfIHwy+Jv8Awrn+1P8AiUf2h9v8r/l58rZs3/7DZzv9ulHxN+GX/Cuf7L/4m/8AaH2/zf8Al28rZs2f7bZzv9ulef19f/DL4Zf8K5/tT/ib/wBofb/K/wCXbytmzf8A7bZzv9ulef8A7TX/ADK3/b3/AO0a+gK+QPib8Mv+Fc/2X/xN/wC0Pt/m/wDLt5WzZs/22znf7dK8/r6/+GXxN/4WN/an/Eo/s/7B5X/Lz5u/fv8A9hcY2e/Wj4m/E3/hXP8AZf8AxKP7Q+3+b/y8+Vs2bP8AYbOd/t0rwD4ZfDL/AIWN/an/ABN/7P8AsHlf8u3m79+//bXGNnv1r3/4ZfE3/hY39qf8Sj+z/sHlf8vPm79+/wD2FxjZ79a8A+GXwy/4WN/an/E3/s/7B5X/AC7ebv37/wDbXGNnv1o+Jvwy/wCFc/2X/wATf+0Pt/m/8u3lbNmz/bbOd/t0r3/4ZfDL/hXP9qf8Tf8AtD7f5X/Lt5WzZv8A9ts53+3SvP8A/k4z/qXv7C/7e/P8/wD797dvk++d3bHJ/wAMy/8AU3f+U3/7bX0BXz/+01/zK3/b3/7Ro/5Nz/6mH+3f+3TyPI/7+bt3ne2NvfPHoHwy+Jv/AAsb+1P+JR/Z/wBg8r/l583fv3/7C4xs9+teAfDL4Zf8LG/tT/ib/wBn/YPK/wCXbzd+/f8A7a4xs9+td/8A8m5/9TD/AG7/ANunkeR/383bvO9sbe+eD/hmX/qbv/Kb/wDba8Ar6/8Ahl8Mv+Fc/wBqf8Tf+0Pt/lf8u3lbNm//AG2znf7dKPhl8Tf+Fjf2p/xKP7P+weV/y8+bv37/APYXGNnv1r0CiiivP/hl8Mv+Fc/2p/xN/wC0Pt/lf8u3lbNm/wD22znf7dK8/wD+Gmv+pR/8qX/2qj/hmX/qbv8Aym//AG2j/hmX/qbv/Kb/APba9A+JvxN/4Vz/AGX/AMSj+0Pt/m/8vPlbNmz/AGGznf7dK8//AOGZf+pu/wDKb/8Aba9A+Jvwy/4WN/Zf/E3/ALP+web/AMu3m79+z/bXGNnv1o+Jvwy/4WN/Zf8AxN/7P+web/y7ebv37P8AbXGNnv1rz/8A4aa/6lH/AMqX/wBqr6Ar4Ar3/wD5OM/6l7+wv+3vz/P/AO/e3b5Pvnd2xyfsy/8AM0/9un/tauA+Jvwy/wCFc/2X/wATf+0Pt/m/8u3lbNmz/bbOd/t0rv8A/hmX/qbv/Kb/APbaP+Gmv+pR/wDKl/8Aaq4D4m/E3/hY39l/8Sj+z/sHm/8ALz5u/fs/2FxjZ79a7/8A5Nz/AOph/t3/ALdPI8j/AL+bt3ne2NvfPHoHwy+GX/Cuf7U/4m/9ofb/ACv+Xbytmzf/ALbZzv8AbpXn/wDybn/1MP8Abv8A26eR5H/fzdu872xt7544D4m/E3/hY39l/wDEo/s/7B5v/Lz5u/fs/wBhcY2e/Wvr+vn/APZl/wCZp/7dP/a1H7Mv/M0/9un/ALWo/wCTc/8AqYf7d/7dPI8j/v5u3ed7Y2988H7TX/Mrf9vf/tGvoCiiiivn/wDaa/5lb/t7/wDaNH/DTX/Uo/8AlS/+1V6B8Tfib/wrn+y/+JR/aH2/zf8Al58rZs2f7DZzv9ulef8A/DMv/U3f+U3/AO21wHxN+Jv/AAsb+y/+JR/Z/wBg83/l583fv2f7C4xs9+tef17/APsy/wDM0/8Abp/7WrgPhl8Mv+Fjf2p/xN/7P+weV/y7ebv37/8AbXGNnv1rv/2Zf+Zp/wC3T/2tR+01/wAyt/29/wDtGj/k4z/qXv7C/wC3vz/P/wC/e3b5Pvnd2xz9AV8//wDDMv8A1N3/AJTf/ttcB8Tfhl/wrn+y/wDib/2h9v8AN/5dvK2bNn+22c7/AG6V3/8AycZ/1L39hf8Ab35/n/8Afvbt8n3zu7Y5P2Zf+Zp/7dP/AGtR/wAm5/8AUw/27/26eR5H/fzdu872xt7549A+GXxN/wCFjf2p/wASj+z/ALB5X/Lz5u/fv/2FxjZ79a8A+GXwy/4WN/an/E3/ALP+weV/y7ebv37/APbXGNnv1r3/AOGXwy/4Vz/an/E3/tD7f5X/AC7eVs2b/wDbbOd/t0o+JvxN/wCFc/2X/wASj+0Pt/m/8vPlbNmz/YbOd/t0rz//AIaa/wCpR/8AKl/9qo/4Zl/6m7/ym/8A22vQPhl8Mv8AhXP9qf8AE3/tD7f5X/Lt5WzZv/22znf7dKPhl8Tf+Fjf2p/xKP7P+weV/wAvPm79+/8A2FxjZ79a8A+Jvwy/4Vz/AGX/AMTf+0Pt/m/8u3lbNmz/AG2znf7dK9/+GXxN/wCFjf2p/wASj+z/ALB5X/Lz5u/fv/2FxjZ79a9Aooor5/8A+Gmv+pR/8qX/ANqr6Ar5A+GXxN/4Vz/an/Eo/tD7f5X/AC8+Vs2b/wDYbOd/t0rv/wDk3P8A6mH+3f8At08jyP8Av5u3ed7Y2988H/Juf/Uw/wBu/wDbp5Hkf9/N27zvbG3vng/4aa/6lH/ypf8A2quA+JvxN/4WN/Zf/Eo/s/7B5v8Ay8+bv37P9hcY2e/Wvf8A4ZfDL/hXP9qf8Tf+0Pt/lf8ALt5WzZv/ANts53+3SvP/ANmX/maf+3T/ANrUf8My/wDU3f8AlN/+216B8Mvib/wsb+1P+JR/Z/2Dyv8Al583fv3/AOwuMbPfrXn/APycZ/1L39hf9vfn+f8A9+9u3yffO7tjk/4aa/6lH/ypf/aq9A+GXwy/4Vz/AGp/xN/7Q+3+V/y7eVs2b/8AbbOd/t0rwD4m/E3/AIWN/Zf/ABKP7P8AsHm/8vPm79+z/YXGNnv1r3/4ZfDL/hXP9qf8Tf8AtD7f5X/Lt5WzZv8A9ts53+3SvP8A/hpr/qUf/Kl/9qrgPhl8Tf8AhXP9qf8AEo/tD7f5X/Lz5WzZv/2Gznf7dK7/AP4Zl/6m7/ym/wD22j9mX/maf+3T/wBrUf8AJxn/AFL39hf9vfn+f/3727fJ987u2OT/AIaa/wCpR/8AKl/9qr0D4m/DL/hY39l/8Tf+z/sHm/8ALt5u/fs/21xjZ79a8/8A+GZf+pu/8pv/ANtr0D4ZfDL/AIVz/an/ABN/7Q+3+V/y7eVs2b/9ts53+3SvAPib8Mv+Fc/2X/xN/wC0Pt/m/wDLt5WzZs/22znf7dK7/wDZl/5mn/t0/wDa1fQFFFFef/DL4m/8LG/tT/iUf2f9g8r/AJefN379/wDsLjGz3614B8Tfhl/wrn+y/wDib/2h9v8AN/5dvK2bNn+22c7/AG6UfDL4m/8ACuf7U/4lH9ofb/K/5efK2bN/+w2c7/bpXf8A/DMv/U3f+U3/AO20f8nGf9S9/YX/AG9+f5//AH727fJ987u2OeA+GXwy/wCFjf2p/wATf+z/ALB5X/Lt5u/fv/21xjZ79a7/AP4aa/6lH/ypf/aq4D4m/DL/AIVz/Zf/ABN/7Q+3+b/y7eVs2bP9ts53+3Su/wD2Zf8Amaf+3T/2tXAfDL4Zf8LG/tT/AIm/9n/YPK/5dvN379/+2uMbPfrR8Tfib/wsb+y/+JR/Z/2Dzf8Al583fv2f7C4xs9+tHwy+GX/Cxv7U/wCJv/Z/2Dyv+Xbzd+/f/trjGz3615/X1/8ADL4Zf8K5/tT/AIm/9ofb/K/5dvK2bN/+22c7/bpXgHwy+Jv/AArn+1P+JR/aH2/yv+Xnytmzf/sNnO/26UfE34m/8LG/sv8A4lH9n/YPN/5efN379n+wuMbPfrXf/tNf8yt/29/+0aP+TjP+pe/sL/t78/z/APv3t2+T753dscn7Mv8AzNP/AG6f+1q4D4ZfDL/hY39qf8Tf+z/sHlf8u3m79+//AG1xjZ79a+v68/8Ahl8Tf+Fjf2p/xKP7P+weV/y8+bv37/8AYXGNnv1rz/8A5Nz/AOph/t3/ALdPI8j/AL+bt3ne2NvfPHoHxN+Jv/Cuf7L/AOJR/aH2/wA3/l58rZs2f7DZzv8AbpXgHwy+GX/Cxv7U/wCJv/Z/2Dyv+Xbzd+/f/trjGz360fDL4Zf8LG/tT/ib/wBn/YPK/wCXbzd+/f8A7a4xs9+tfX9FFFFfIHxN+GX/AArn+y/+Jv8A2h9v83/l28rZs2f7bZzv9uld/wD8m5/9TD/bv/bp5Hkf9/N27zvbG3vnjgPhl8Tf+Fc/2p/xKP7Q+3+V/wAvPlbNm/8A2Gznf7dKPib8Mv8AhXP9l/8AE3/tD7f5v/Lt5WzZs/22znf7dK7/AP5OM/6l7+wv+3vz/P8A+/e3b5Pvnd2xz6B8Mvib/wALG/tT/iUf2f8AYPK/5efN379/+wuMbPfrXyBX1/8AE34m/wDCuf7L/wCJR/aH2/zf+XnytmzZ/sNnO/26UfDL4m/8LG/tT/iUf2f9g8r/AJefN379/wDsLjGz3615/wDsy/8AM0/9un/taj/k3P8A6mH+3f8At08jyP8Av5u3ed7Y2988eAV9f/DL4m/8LG/tT/iUf2f9g8r/AJefN379/wDsLjGz3614B8Tfib/wsb+y/wDiUf2f9g83/l583fv2f7C4xs9+td/+01/zK3/b3/7Rr6Ar5/8A+TjP+pe/sL/t78/z/wDv3t2+T753dsc+gfDL4Zf8K5/tT/ib/wBofb/K/wCXbytmzf8A7bZzv9ulef8A/DMv/U3f+U3/AO21wHwy+GX/AAsb+1P+Jv8A2f8AYPK/5dvN379/+2uMbPfrXf8A/Jxn/Uvf2F/29+f5/wD3727fJ987u2OfQPib8Tf+Fc/2X/xKP7Q+3+b/AMvPlbNmz/YbOd/t0rz/AP5Nz/6mH+3f+3TyPI/7+bt3ne2NvfPB/wAm5/8AUw/27/26eR5H/fzdu872xt754+gK+QPhl8Mv+Fjf2p/xN/7P+weV/wAu3m79+/8A21xjZ79a+v6KKKK8/wDib8Tf+Fc/2X/xKP7Q+3+b/wAvPlbNmz/YbOd/t0rz/wDaa/5lb/t7/wDaNH7Mv/M0/wDbp/7Wo/5Nz/6mH+3f+3TyPI/7+bt3ne2NvfPB/wAMy/8AU3f+U3/7bXoHwy+GX/Cuf7U/4m/9ofb/ACv+Xbytmzf/ALbZzv8AbpR8Mvib/wALG/tT/iUf2f8AYPK/5efN379/+wuMbPfrXn//AA01/wBSj/5Uv/tVH/DMv/U3f+U3/wC21wHxN+Jv/Cxv7L/4lH9n/YPN/wCXnzd+/Z/sLjGz360fDL4m/wDCuf7U/wCJR/aH2/yv+Xnytmzf/sNnO/26UfE34Zf8K5/sv/ib/wBofb/N/wCXbytmzZ/ttnO/26V3/wDycZ/1L39hf9vfn+f/AN+9u3yffO7tjk/5OM/6l7+wv+3vz/P/AO/e3b5Pvnd2xz6B8Mvhl/wrn+1P+Jv/AGh9v8r/AJdvK2bN/wDttnO/26V4B8Tfib/wsb+y/wDiUf2f9g83/l583fv2f7C4xs9+tHxN+Jv/AAsb+y/+JR/Z/wBg83/l583fv2f7C4xs9+tHxN+GX/Cuf7L/AOJv/aH2/wA3/l28rZs2f7bZzv8AbpXv/wAMvhl/wrn+1P8Aib/2h9v8r/l28rZs3/7bZzv9ulHxN+GX/Cxv7L/4m/8AZ/2Dzf8Al283fv2f7a4xs9+tHxN+GX/Cxv7L/wCJv/Z/2Dzf+Xbzd+/Z/trjGz3614B8Mvhl/wALG/tT/ib/ANn/AGDyv+Xbzd+/f/trjGz3613/APybn/1MP9u/9unkeR/383bvO9sbe+ePoCvn/wD4Zl/6m7/ym/8A22j9pr/mVv8At7/9o0fsy/8AM0/9un/tavoCiiivn/8A4Zl/6m7/AMpv/wBtr6Ar5/8A2Zf+Zp/7dP8A2tR/wzL/ANTd/wCU3/7bR/ycZ/1L39hf9vfn+f8A9+9u3yffO7tjk/Zl/wCZp/7dP/a1H/Juf/Uw/wBu/wDbp5Hkf9/N27zvbG3vng/5Nz/6mH+3f+3TyPI/7+bt3ne2NvfPHoHxN+GX/Cxv7L/4m/8AZ/2Dzf8Al283fv2f7a4xs9+teAfE34Zf8K5/sv8A4m/9ofb/ADf+XbytmzZ/ttnO/wBulHxN+Jv/AAsb+y/+JR/Z/wBg83/l583fv2f7C4xs9+td/wD8NNf9Sj/5Uv8A7VXoHwy+GX/Cuf7U/wCJv/aH2/yv+Xbytmzf/ttnO/26V5//AMNNf9Sj/wCVL/7VR/ybn/1MP9u/9unkeR/383bvO9sbe+ePoCvn/wD5OM/6l7+wv+3vz/P/AO/e3b5Pvnd2xzwHwy+GX/Cxv7U/4m/9n/YPK/5dvN379/8AtrjGz3617/8ADL4Zf8K5/tT/AIm/9ofb/K/5dvK2bN/+22c7/bpXn/8AwzL/ANTd/wCU3/7bXgFe/wD/AA01/wBSj/5Uv/tVegfDL4Zf8K5/tT/ib/2h9v8AK/5dvK2bN/8AttnO/wBulef/APDMv/U3f+U3/wC216B8Mvhl/wAK5/tT/ib/ANofb/K/5dvK2bN/+22c7/bpR8Mvhl/wrn+1P+Jv/aH2/wAr/l28rZs3/wC22c7/AG6V6BRRRRXyB8Tfib/wsb+y/wDiUf2f9g83/l583fv2f7C4xs9+tHwy+GX/AAsb+1P+Jv8A2f8AYPK/5dvN379/+2uMbPfrR8Mvhl/wsb+1P+Jv/Z/2Dyv+Xbzd+/f/ALa4xs9+td//AMMy/wDU3f8AlN/+21wHwy+GX/Cxv7U/4m/9n/YPK/5dvN379/8AtrjGz3617/8ADL4Zf8K5/tT/AIm/9ofb/K/5dvK2bN/+22c7/bpXgHwy+GX/AAsb+1P+Jv8A2f8AYPK/5dvN379/+2uMbPfrR8Tfib/wsb+y/wDiUf2f9g83/l583fv2f7C4xs9+td//AMNNf9Sj/wCVL/7VR/ybn/1MP9u/9unkeR/383bvO9sbe+eD/hpr/qUf/Kl/9qo/4aa/6lH/AMqX/wBqrgPhl8Mv+Fjf2p/xN/7P+weV/wAu3m79+/8A21xjZ79a7/8A4Zl/6m7/AMpv/wBtrgPhl8Tf+Fc/2p/xKP7Q+3+V/wAvPlbNm/8A2Gznf7dK8/r6/wDhl8Tf+Fjf2p/xKP7P+weV/wAvPm79+/8A2FxjZ79aPhl8Mv8AhXP9qf8AE3/tD7f5X/Lt5WzZv/22znf7dK8//wCGmv8AqUf/ACpf/aqP+GZf+pu/8pv/ANtrgPib8Mv+Fc/2X/xN/wC0Pt/m/wDLt5WzZs/22znf7dKPib8Mv+Fc/wBl/wDE3/tD7f5v/Lt5WzZs/wBts53+3Sj4ZfDL/hY39qf8Tf8As/7B5X/Lt5u/fv8A9tcY2e/Wu/8A+GZf+pu/8pv/ANto/Zl/5mn/ALdP/a1cB8Tfhl/wrn+y/wDib/2h9v8AN/5dvK2bNn+22c7/AG6V7/8ADL4m/wDCxv7U/wCJR/Z/2Dyv+Xnzd+/f/sLjGz3616BRRRXyB8Tfhl/wrn+y/wDib/2h9v8AN/5dvK2bNn+22c7/AG6V7/8ADL4Zf8K5/tT/AIm/9ofb/K/5dvK2bN/+22c7/bpXn/7Mv/M0/wDbp/7Wr0D4ZfDL/hXP9qf8Tf8AtD7f5X/Lt5WzZv8A9ts53+3SvAPhl8Mv+Fjf2p/xN/7P+weV/wAu3m79+/8A21xjZ79a7/8Aaa/5lb/t7/8AaNH/AA01/wBSj/5Uv/tVcB8Mvib/AMK5/tT/AIlH9ofb/K/5efK2bN/+w2c7/bpXv/xN+Jv/AArn+y/+JR/aH2/zf+XnytmzZ/sNnO/26V4B8Tfib/wsb+y/+JR/Z/2Dzf8Al583fv2f7C4xs9+td/8AtNf8yt/29/8AtGuA+Jvwy/4Vz/Zf/E3/ALQ+3+b/AMu3lbNmz/bbOd/t0rv/ANmX/maf+3T/ANrV6B8Mvhl/wrn+1P8Aib/2h9v8r/l28rZs3/7bZzv9uleAfDL4m/8ACuf7U/4lH9ofb/K/5efK2bN/+w2c7/bpXf8A7Mv/ADNP/bp/7Wr0D4m/DL/hY39l/wDE3/s/7B5v/Lt5u/fs/wBtcY2e/WvAPib8Mv8AhXP9l/8AE3/tD7f5v/Lt5WzZs/22znf7dK9/+Jvwy/4WN/Zf/E3/ALP+web/AMu3m79+z/bXGNnv1rwD4ZfDL/hY39qf8Tf+z/sHlf8ALt5u/fv/ANtcY2e/Wvf/AIZfE3/hY39qf8Sj+z/sHlf8vPm79+//AGFxjZ79a9Ar5/8A2Zf+Zp/7dP8A2tXoHwy+GX/Cuf7U/wCJv/aH2/yv+Xbytmzf/ttnO/26V5/+zL/zNP8A26f+1q+gK8/+GXxN/wCFjf2p/wASj+z/ALB5X/Lz5u/fv/2FxjZ79a9Aooor5/8A+Gmv+pR/8qX/ANqo/wCTc/8AqYf7d/7dPI8j/v5u3ed7Y2988cB8Mvhl/wALG/tT/ib/ANn/AGDyv+Xbzd+/f/trjGz3613/APwzL/1N3/lN/wDttcB8Tfhl/wAK5/sv/ib/ANofb/N/5dvK2bNn+22c7/bpR8Tfhl/wrn+y/wDib/2h9v8AN/5dvK2bNn+22c7/AG6UfDL4m/8ACuf7U/4lH9ofb/K/5efK2bN/+w2c7/bpXf8A7Mv/ADNP/bp/7Wo/Zl/5mn/t0/8Aa1H/AAzL/wBTd/5Tf/ttH/DMv/U3f+U3/wC20f8ADTX/AFKP/lS/+1V4BXv/APwzL/1N3/lN/wDttegfDL4Zf8K5/tT/AIm/9ofb/K/5dvK2bN/+22c7/bpXgHwy+GX/AAsb+1P+Jv8A2f8AYPK/5dvN379/+2uMbPfrR8Tfhl/wrn+y/wDib/2h9v8AN/5dvK2bNn+22c7/AG6V9f15/wDDL4Zf8K5/tT/ib/2h9v8AK/5dvK2bN/8AttnO/wBulHxN+GX/AAsb+y/+Jv8A2f8AYPN/5dvN379n+2uMbPfrR8Tfhl/wsb+y/wDib/2f9g83/l283fv2f7a4xs9+teAfDL4Zf8LG/tT/AIm/9n/YPK/5dvN379/+2uMbPfrXf/8ADMv/AFN3/lN/+21wHwy+GX/Cxv7U/wCJv/Z/2Dyv+Xbzd+/f/trjGz3615/X1/8ADL4Zf8K5/tT/AIm/9ofb/K/5dvK2bN/+22c7/bpXn/7Mv/M0/wDbp/7Wr6Aooor5/wD+Gmv+pR/8qX/2quA+GXwy/wCFjf2p/wATf+z/ALB5X/Lt5u/fv/21xjZ79aPhl8Mv+Fjf2p/xN/7P+weV/wAu3m79+/8A21xjZ79a7/8A5Nz/AOph/t3/ALdPI8j/AL+bt3ne2NvfPB/w01/1KP8A5Uv/ALVXoHxN+Jv/AArn+y/+JR/aH2/zf+XnytmzZ/sNnO/26V5//wANNf8AUo/+VL/7VR/w01/1KP8A5Uv/ALVR/wAm5/8AUw/27/26eR5H/fzdu872xt7549A+Jvwy/wCFjf2X/wATf+z/ALB5v/Lt5u/fs/21xjZ79a8//wCGmv8AqUf/ACpf/aqP+TjP+pe/sL/t78/z/wDv3t2+T753dscn/Jxn/Uvf2F/29+f5/wD3727fJ987u2OeA+GXxN/4Vz/an/Eo/tD7f5X/AC8+Vs2b/wDYbOd/t0rv/wBpr/mVv+3v/wBo1wHxN+Jv/Cxv7L/4lH9n/YPN/wCXnzd+/Z/sLjGz360fDL4m/wDCuf7U/wCJR/aH2/yv+Xnytmzf/sNnO/26V7/8Tfib/wAK5/sv/iUf2h9v83/l58rZs2f7DZzv9ulHwy+GX/Cuf7U/4m/9ofb/ACv+Xbytmzf/ALbZzv8AbpXyBXv/APycZ/1L39hf9vfn+f8A9+9u3yffO7tjngPib8Tf+Fjf2X/xKP7P+web/wAvPm79+z/YXGNnv1o+Jvwy/wCFc/2X/wATf+0Pt/m/8u3lbNmz/bbOd/t0r3/4ZfDL/hXP9qf8Tf8AtD7f5X/Lt5WzZv8A9ts53+3SvP8A/hmX/qbv/Kb/APbaP2mv+ZW/7e//AGjX0BRRRRXz/wDsy/8AM0/9un/tavQPib8Mv+Fjf2X/AMTf+z/sHm/8u3m79+z/AG1xjZ79a8//AGmv+ZW/7e//AGjXAfE34Zf8K5/sv/ib/wBofb/N/wCXbytmzZ/ttnO/26V9f18//tNf8yt/29/+0a+gK8/+GXwy/wCFc/2p/wATf+0Pt/lf8u3lbNm//bbOd/t0rwD4m/DL/hXP9l/8Tf8AtD7f5v8Ay7eVs2bP9ts53+3Sj4ZfDL/hY39qf8Tf+z/sHlf8u3m79+//AG1xjZ79a8/r3/8A5OM/6l7+wv8At78/z/8Av3t2+T753dscn/DMv/U3f+U3/wC20f8AJuf/AFMP9u/9unkeR/383bvO9sbe+eOA+GXwy/4WN/an/E3/ALP+weV/y7ebv37/APbXGNnv1o+GXxN/4Vz/AGp/xKP7Q+3+V/y8+Vs2b/8AYbOd/t0o+JvxN/4WN/Zf/Eo/s/7B5v8Ay8+bv37P9hcY2e/Wvf8A4ZfE3/hY39qf8Sj+z/sHlf8ALz5u/fv/ANhcY2e/WvkCvr/4m/E3/hXP9l/8Sj+0Pt/m/wDLz5WzZs/2Gznf7dK8/wD2mv8AmVv+3v8A9o1wHwy+GX/Cxv7U/wCJv/Z/2Dyv+Xbzd+/f/trjGz3617/8Tfhl/wALG/sv/ib/ANn/AGDzf+Xbzd+/Z/trjGz360fE34Zf8LG/sv8A4m/9n/YPN/5dvN379n+2uMbPfrXn/wDw01/1KP8A5Uv/ALVR/wAm5/8AUw/27/26eR5H/fzdu872xt754P2Zf+Zp/wC3T/2tX0BRRRXwBXoHxN+GX/Cuf7L/AOJv/aH2/wA3/l28rZs2f7bZzv8AbpR8Mvib/wAK5/tT/iUf2h9v8r/l58rZs3/7DZzv9ule/wDwy+GX/Cuf7U/4m/8AaH2/yv8Al28rZs3/AO22c7/bpXn/AO01/wAyt/29/wDtGuA+JvxN/wCFjf2X/wASj+z/ALB5v/Lz5u/fs/2FxjZ79aPib8Tf+Fjf2X/xKP7P+web/wAvPm79+z/YXGNnv1o+JvxN/wCFjf2X/wASj+z/ALB5v/Lz5u/fs/2FxjZ79aPhl8Mv+Fjf2p/xN/7P+weV/wAu3m79+/8A21xjZ79a9/8Aib8Mv+Fjf2X/AMTf+z/sHm/8u3m79+z/AG1xjZ79a9Arz/4m/E3/AIVz/Zf/ABKP7Q+3+b/y8+Vs2bP9hs53+3SvkCvf/wBpr/mVv+3v/wBo16B8Tfhl/wALG/sv/ib/ANn/AGDzf+Xbzd+/Z/trjGz3615/+zL/AMzT/wBun/tauA+GXxN/4Vz/AGp/xKP7Q+3+V/y8+Vs2b/8AYbOd/t0o+GXxN/4Vz/an/Eo/tD7f5X/Lz5WzZv8A9hs53+3Svr+vn/8AZl/5mn/t0/8Aa1egfDL4m/8ACxv7U/4lH9n/AGDyv+Xnzd+/f/sLjGz3615//wANNf8AUo/+VL/7VR/wzL/1N3/lN/8AttegfDL4m/8ACxv7U/4lH9n/AGDyv+Xnzd+/f/sLjGz3615//wAnGf8AUvf2F/29+f5//fvbt8n3zu7Y59A+Jvwy/wCFjf2X/wATf+z/ALB5v/Lt5u/fs/21xjZ79aPhl8Mv+Fc/2p/xN/7Q+3+V/wAu3lbNm/8A22znf7dK9Aooorz/AOJvwy/4WN/Zf/E3/s/7B5v/AC7ebv37P9tcY2e/Wj4ZfE3/AIWN/an/ABKP7P8AsHlf8vPm79+//YXGNnv1r0CvkD4m/DL/AIVz/Zf/ABN/7Q+3+b/y7eVs2bP9ts53+3SvP6+v/hl8Tf8AhY39qf8AEo/s/wCweV/y8+bv37/9hcY2e/WvAPib8Mv+Fc/2X/xN/wC0Pt/m/wDLt5WzZs/22znf7dK7/wDaa/5lb/t7/wDaNH7TX/Mrf9vf/tGj/k4z/qXv7C/7e/P8/wD797dvk++d3bHJ+01/zK3/AG9/+0a4D4m/E3/hY39l/wDEo/s/7B5v/Lz5u/fs/wBhcY2e/Wu//wCTc/8AqYf7d/7dPI8j/v5u3ed7Y2988cB8Tfib/wALG/sv/iUf2f8AYPN/5efN379n+wuMbPfrXv8A8Tfib/wrn+y/+JR/aH2/zf8Al58rZs2f7DZzv9uleAfDL4Zf8LG/tT/ib/2f9g8r/l283fv3/wC2uMbPfrR8Mvhl/wALG/tT/ib/ANn/AGDyv+Xbzd+/f/trjGz360fE34m/8LG/sv8A4lH9n/YPN/5efN379n+wuMbPfrXf/sy/8zT/ANun/tauA+Jvwy/4Vz/Zf/E3/tD7f5v/AC7eVs2bP9ts53+3Svf/AIm/E3/hXP8AZf8AxKP7Q+3+b/y8+Vs2bP8AYbOd/t0rz/8AZl/5mn/t0/8Aa1H/ACbn/wBTD/bv/bp5Hkf9/N27zvbG3vnj6Ar5A+JvxN/4WN/Zf/Eo/s/7B5v/AC8+bv37P9hcY2e/WvP69/8A2Zf+Zp/7dP8A2tX0BRRRXwBXoHwy+GX/AAsb+1P+Jv8A2f8AYPK/5dvN379/+2uMbPfrXn9e/wD/AAzL/wBTd/5Tf/ttH/DTX/Uo/wDlS/8AtVH7TX/Mrf8Ab3/7RrgPhl8Mv+Fjf2p/xN/7P+weV/y7ebv37/8AbXGNnv1rv/8Ak4z/AKl7+wv+3vz/AD/+/e3b5Pvnd2xz6B8Tfib/AMK5/sv/AIlH9ofb/N/5efK2bNn+w2c7/bpXn/8Aybn/ANTD/bv/AG6eR5H/AH83bvO9sbe+ePQPib8Mv+Fjf2X/AMTf+z/sHm/8u3m79+z/AG1xjZ79aPib8Tf+Fc/2X/xKP7Q+3+b/AMvPlbNmz/YbOd/t0o+Jvwy/4WN/Zf8AxN/7P+web/y7ebv37P8AbXGNnv1rz/8A5OM/6l7+wv8At78/z/8Av3t2+T753dscn/Juf/Uw/wBu/wDbp5Hkf9/N27zvbG3vnj6Ar5//AGZf+Zp/7dP/AGtXoHwy+Jv/AAsb+1P+JR/Z/wBg8r/l583fv3/7C4xs9+tef/8ADMv/AFN3/lN/+21wHxN+GX/Cuf7L/wCJv/aH2/zf+XbytmzZ/ttnO/26V7/8Tfib/wAK5/sv/iUf2h9v83/l58rZs2f7DZzv9ulef/8ADTX/AFKP/lS/+1VwHwy+Jv8Awrn+1P8AiUf2h9v8r/l58rZs3/7DZzv9uld//wAnGf8AUvf2F/29+f5//fvbt8n3zu7Y59A+GXwy/wCFc/2p/wATf+0Pt/lf8u3lbNm//bbOd/t0rz//AJOM/wCpe/sL/t78/wA//v3t2+T753dsc/QFFFFFef8Awy+Jv/Cxv7U/4lH9n/YPK/5efN379/8AsLjGz3615/8AtNf8yt/29/8AtGuA+GXxN/4Vz/an/Eo/tD7f5X/Lz5WzZv8A9hs53+3Su/8A+Tc/+ph/t3/t08jyP+/m7d53tjb3zwf8m5/9TD/bv/bp5Hkf9/N27zvbG3vng/4Zl/6m7/ym/wD22j9mX/maf+3T/wBrUf8AJxn/AFL39hf9vfn+f/3727fJ987u2OfoCvn/AP5OM/6l7+wv+3vz/P8A+/e3b5Pvnd2xyf8ADMv/AFN3/lN/+20ftNf8yt/29/8AtGvQPhl8Tf8AhY39qf8AEo/s/wCweV/y8+bv37/9hcY2e/WvP/8Ahpr/AKlH/wAqX/2quA+Jvwy/4Vz/AGX/AMTf+0Pt/m/8u3lbNmz/AG2znf7dKPib8Tf+Fjf2X/xKP7P+web/AMvPm79+z/YXGNnv1r3/AOJvwy/4WN/Zf/E3/s/7B5v/AC7ebv37P9tcY2e/WvP/APhmX/qbv/Kb/wDbaP8Ak3P/AKmH+3f+3TyPI/7+bt3ne2NvfPB/w01/1KP/AJUv/tVegfDL4Zf8K5/tT/ib/wBofb/K/wCXbytmzf8A7bZzv9ulHwy+GX/Cuf7U/wCJv/aH2/yv+Xbytmzf/ttnO/26V4B8Mvib/wAK5/tT/iUf2h9v8r/l58rZs3/7DZzv9ule/wDxN+GX/Cxv7L/4m/8AZ/2Dzf8Al283fv2f7a4xs9+tfIFfX/xN+GX/AAsb+y/+Jv8A2f8AYPN/5dvN379n+2uMbPfrR8Mvib/wsb+1P+JR/Z/2Dyv+Xnzd+/f/ALC4xs9+tegUUUV8gfE34Zf8K5/sv/ib/wBofb/N/wCXbytmzZ/ttnO/26V3/wDycZ/1L39hf9vfn+f/AN+9u3yffO7tjk/4Zl/6m7/ym/8A22j/AIZl/wCpu/8AKb/9trgPib8Mv+Fc/wBl/wDE3/tD7f5v/Lt5WzZs/wBts53+3Sj4ZfDL/hY39qf8Tf8As/7B5X/Lt5u/fv8A9tcY2e/Wu/8A+GZf+pu/8pv/ANtr0D4ZfE3/AIWN/an/ABKP7P8AsHlf8vPm79+//YXGNnv1r5Ar3/8A5OM/6l7+wv8At78/z/8Av3t2+T753dsc+gfDL4Zf8K5/tT/ib/2h9v8AK/5dvK2bN/8AttnO/wBulef/APDTX/Uo/wDlS/8AtVegfDL4Zf8ACuf7U/4m/wDaH2/yv+Xbytmzf/ttnO/26UfDL4Zf8K5/tT/ib/2h9v8AK/5dvK2bN/8AttnO/wBulHwy+GX/AArn+1P+Jv8A2h9v8r/l28rZs3/7bZzv9ulHwy+Jv/Cxv7U/4lH9n/YPK/5efN379/8AsLjGz3614B8Tfib/AMLG/sv/AIlH9n/YPN/5efN379n+wuMbPfrXf/8ADMv/AFN3/lN/+216B8Tfhl/wsb+y/wDib/2f9g83/l283fv2f7a4xs9+tef/ALTX/Mrf9vf/ALRo/wCTjP8AqXv7C/7e/P8AP/797dvk++d3bHJ/w01/1KP/AJUv/tVH/DMv/U3f+U3/AO20f8nGf9S9/YX/AG9+f5//AH727fJ987u2OT/hmX/qbv8Aym//AG2vAK+v/hl8Tf8AhY39qf8AEo/s/wCweV/y8+bv37/9hcY2e/WvQKKKKK8/+Jvwy/4WN/Zf/E3/ALP+web/AMu3m79+z/bXGNnv1r0Cvn//AIZl/wCpu/8AKb/9to/Zl/5mn/t0/wDa1fQFfIHxN+GX/Cuf7L/4m/8AaH2/zf8Al28rZs2f7bZzv9ule/8Awy+GX/Cuf7U/4m/9ofb/ACv+Xbytmzf/ALbZzv8AbpR8Mvib/wALG/tT/iUf2f8AYPK/5efN379/+wuMbPfrXgHxN+Jv/Cxv7L/4lH9n/YPN/wCXnzd+/Z/sLjGz3613/wC01/zK3/b3/wC0a4D4ZfE3/hXP9qf8Sj+0Pt/lf8vPlbNm/wD2Gznf7dKPhl8Mv+Fjf2p/xN/7P+weV/y7ebv37/8AbXGNnv1rv/8AhmX/AKm7/wApv/22j9mX/maf+3T/ANrUf8My/wDU3f8AlN/+20f8nGf9S9/YX/b35/n/APfvbt8n3zu7Y59A+GXwy/4Vz/an/E3/ALQ+3+V/y7eVs2b/APbbOd/t0rz/APZl/wCZp/7dP/a1H/DMv/U3f+U3/wC216B8Tfib/wAK5/sv/iUf2h9v83/l58rZs2f7DZzv9ulef/sy/wDM0/8Abp/7WrgPhl8Mv+Fjf2p/xN/7P+weV/y7ebv37/8AbXGNnv1rv/8AhmX/AKm7/wApv/22j9mX/maf+3T/ANrUf8m5/wDUw/27/wBunkeR/wB/N27zvbG3vnj0D4ZfE3/hY39qf8Sj+z/sHlf8vPm79+//AGFxjZ79a9Aooor5A+GXwy/4WN/an/E3/s/7B5X/AC7ebv37/wDbXGNnv1rv/wDhmX/qbv8Aym//AG2j/hmX/qbv/Kb/APbaP2Zf+Zp/7dP/AGtR/wANNf8AUo/+VL/7VXoHwy+GX/Cuf7U/4m/9ofb/ACv+Xbytmzf/ALbZzv8AbpXgHwy+GX/Cxv7U/wCJv/Z/2Dyv+Xbzd+/f/trjGz3613//ACbn/wBTD/bv/bp5Hkf9/N27zvbG3vnjwCvr/wCJvxN/4Vz/AGX/AMSj+0Pt/m/8vPlbNmz/AGGznf7dK8//AOTc/wDqYf7d/wC3TyPI/wC/m7d53tjb3zwfsy/8zT/26f8Ataj9mX/maf8At0/9rV6B8Mvhl/wrn+1P+Jv/AGh9v8r/AJdvK2bN/wDttnO/26V4B8Mvib/wrn+1P+JR/aH2/wAr/l58rZs3/wCw2c7/AG6V7/8ADL4m/wDCxv7U/wCJR/Z/2Dyv+Xnzd+/f/sLjGz3615/+01/zK3/b3/7Ro/5Nz/6mH+3f+3TyPI/7+bt3ne2NvfPB/wAm5/8AUw/27/26eR5H/fzdu872xt7544D4ZfE3/hXP9qf8Sj+0Pt/lf8vPlbNm/wD2Gznf7dKPhl8Mv+Fjf2p/xN/7P+weV/y7ebv37/8AbXGNnv1rv/8Ak4z/AKl7+wv+3vz/AD/+/e3b5Pvnd2xyfsy/8zT/ANun/tavQPhl8Mv+Fc/2p/xN/wC0Pt/lf8u3lbNm/wD22znf7dK8/wD2Zf8Amaf+3T/2tX0BXn/wy+Jv/Cxv7U/4lH9n/YPK/wCXnzd+/f8A7C4xs9+tegUUUV8//sy/8zT/ANun/tavAK9//Zl/5mn/ALdP/a1H7Mv/ADNP/bp/7WrgPhl8Tf8AhXP9qf8AEo/tD7f5X/Lz5WzZv/2Gznf7dK9/+JvxN/4Vz/Zf/Eo/tD7f5v8Ay8+Vs2bP9hs53+3Sj4ZfDL/hXP8Aan/E3/tD7f5X/Lt5WzZv/wBts53+3Sj4m/E3/hXP9l/8Sj+0Pt/m/wDLz5WzZs/2Gznf7dK8/wD+Tc/+ph/t3/t08jyP+/m7d53tjb3zx9AV8/8A/Juf/Uw/27/26eR5H/fzdu872xt754P+Tc/+ph/t3/t08jyP+/m7d53tjb3zx4BXoHwy+GX/AAsb+1P+Jv8A2f8AYPK/5dvN379/+2uMbPfrXf8A/DMv/U3f+U3/AO216B8Tfhl/wsb+y/8Aib/2f9g83/l283fv2f7a4xs9+tef/wDDMv8A1N3/AJTf/ttegfE34m/8K5/sv/iUf2h9v83/AJefK2bNn+w2c7/bpR8Tfib/AMK5/sv/AIlH9ofb/N/5efK2bNn+w2c7/bpXn/8Aybn/ANTD/bv/AG6eR5H/AH83bvO9sbe+ePQPhl8Tf+Fjf2p/xKP7P+weV/y8+bv37/8AYXGNnv1rz/8AZl/5mn/t0/8Aa1eAV7//AMMy/wDU3f8AlN/+21wHxN+GX/Cuf7L/AOJv/aH2/wA3/l28rZs2f7bZzv8AbpR8Mvhl/wALG/tT/ib/ANn/AGDyv+Xbzd+/f/trjGz3619f0UUUV8//ALMv/M0/9un/ALWo/wCGZf8Aqbv/ACm//ba9A+GXwy/4Vz/an/E3/tD7f5X/AC7eVs2b/wDbbOd/t0rz/wDZl/5mn/t0/wDa1H/Juf8A1MP9u/8Abp5Hkf8Afzdu872xt7549A+Jvwy/4WN/Zf8AxN/7P+web/y7ebv37P8AbXGNnv1o+JvxN/4Vz/Zf/Eo/tD7f5v8Ay8+Vs2bP9hs53+3SvAPhl8Tf+Fc/2p/xKP7Q+3+V/wAvPlbNm/8A2Gznf7dKPhl8Mv8AhY39qf8AE3/s/wCweV/y7ebv37/9tcY2e/Wj4ZfDL/hY39qf8Tf+z/sHlf8ALt5u/fv/ANtcY2e/WvP6+v8A4ZfDL/hXP9qf8Tf+0Pt/lf8ALt5WzZv/ANts53+3Sj4ZfDL/AIVz/an/ABN/7Q+3+V/y7eVs2b/9ts53+3SvkCvQPhl8Mv8AhY39qf8AE3/s/wCweV/y7ebv37/9tcY2e/Wj4ZfE3/hXP9qf8Sj+0Pt/lf8ALz5WzZv/ANhs53+3SvP6K9//AOTc/wDqYf7d/wC3TyPI/wC/m7d53tjb3zwf8My/9Td/5Tf/ALbR/wAnGf8AUvf2F/29+f5//fvbt8n3zu7Y5+gK+f8A9pr/AJlb/t7/APaNeAV6B8Tfhl/wrn+y/wDib/2h9v8AN/5dvK2bNn+22c7/AG6V7/8AE34m/wDCuf7L/wCJR/aH2/zf+XnytmzZ/sNnO/26V6BRRRRXz/8A8My/9Td/5Tf/ALbR/wAMy/8AU3f+U3/7bR/wzL/1N3/lN/8AttegfDL4Zf8ACuf7U/4m/wDaH2/yv+Xbytmzf/ttnO/26V5//wAMy/8AU3f+U3/7bXoHxN+GX/Cxv7L/AOJv/Z/2Dzf+Xbzd+/Z/trjGz360fE34Zf8ACxv7L/4m/wDZ/wBg83/l283fv2f7a4xs9+tegV8//wDDMv8A1N3/AJTf/ttfQFfP/wDwzL/1N3/lN/8AttfQFfP/APwzL/1N3/lN/wDttfQFef8Awy+GX/Cuf7U/4m/9ofb/ACv+Xbytmzf/ALbZzv8AbpR8Mvhl/wAK5/tT/ib/ANofb/K/5dvK2bN/+22c7/bpXoFFef8Awy+GX/Cuf7U/4m/9ofb/ACv+Xbytmzf/ALbZzv8AbpR8Mvhl/wAK5/tT/ib/ANofb/K/5dvK2bN/+22c7/bpR8Tfhl/wsb+y/wDib/2f9g83/l283fv2f7a4xs9+tHwy+GX/AArn+1P+Jv8A2h9v8r/l28rZs3/7bZzv9ulHwy+GX/Cuf7U/4m/9ofb/ACv+Xbytmzf/ALbZzv8AbpR8Mvhl/wAK5/tT/ib/ANofb/K/5dvK2bN/+22c7/bpR8Mvhl/wrn+1P+Jv/aH2/wAr/l28rZs3/wC22c7/AG6UfDL4Zf8ACuf7U/4m/wDaH2/yv+Xbytmzf/ttnO/26V6BRRRRRRRRRRRRRRRRRRRRRRRRRRRRRRRRRRRRRRRRRRRRRRRRRRRRRRRRRRRRRRRRX//Z"
},
"payment_notice_data": {
"payment_method": "account_debit",
"payment_origin": "internet",
"payment_notice_date": "2024-07-01"
},
"payment_data": {
"paid_amount": 850.0,
"paid_rebate_amount": 200.0,
"paid_discount_amount": 0.0,
"paid_fine_amount": 0.0,
"paid_interest_amount": 50.0,
"payment_method": "account_debit",
"payment_origin": "internet",
"payment_credit_date": "2024-07-02",
"payment_date": "2024-07-01",
"payment_bank": {
"code": "341",
"ispb": 60701190,
"name": "ITAU UNIBANCO S.A."
},
"payment_branch": "0216"
},
"bank_slip_status": "registered",
"occurrences": [
{
"request_control_key": "0dcb3182-4d7e-4526-8f92-c15cdbc51bad",
"occurrence_key": "ec67408c-a149-418a-b89b-b9c9d3b6c403",
"occurrence_type": "registration",
"occurrence_status": "confirmed",
"created_at": "2024-06-23T09:15:32Z"
},
{
"request_control_key": "9618c632-7f4d-490b-8817-2bb72ec1e84a",
"occurrence_key": "70d3e632-644d-499f-baac-f65f21fb8574",
"occurrence_type": "rebate",
"occurrence_status": "confirmed",
"created_at": "2024-06-26T12:36:04Z"
},
{
"request_control_key": "c2b2ba59-9c37-488d-823d-2c3bfc1e9108",
"occurrence_key": "dbdd513c-e918-4d17-b194-b5ae3d979988",
"occurrence_type": "cancel_rebate",
"occurrence_status": "confirmed",
"created_at": "2024-06-26T12:53:47Z"
}
]
}
```
### Response Body Params
| Field | Type | Description | Characters |
|----------------------------|---------|------------------------------------------------------------------------------------|--------------------------------------------------|
| `bank_slip_key ` * | uuidv4 | Unique bank slip identification key, in uuid v4 format | 36 |
| `request_control_key` * | uuidv4 | Unique identification key of the request used by the client, in uuid v4 format | 36 |
| `our_number` * | integer | Unique bank slip identification number within the wallet | 11 |
| `bank_slip_status` * | string | Bank slip status | **[bank_slip_status Enumerators](#enumeradores-bank_slip_status)** |
| `protest_status` * | string | Notary office protest status of the bank slip | **[protest_status Enumerators](#enumeradores-protest_status)** |
| `document_number` * | string | Bank slip identification number | 10 |
| `amount` * | float | Base amount of the bank slip | - |
| `expiration` * | string | Due date | 10 |
| `barcode` * | string | Bank slip barcode | 44 |
| `digitable_line` * | string | Bank slip digitable line | 47 |
| `bank_teller_instructions` | string | Additional registration instructions that will appear on the bank slip PDF | 320 |
| `rebate_amount` | float | Bank slip rebate amount, which will be applied on top of the base amount | - |
| `max_payment_days` * | integer | Maximum number of calendar days the bank slip will remain available for payment, after the due date (max 365) | - |
| `write_off_data` | object | Write-off settings | **[write_off_data Object](#objeto-write_off_settings)** |
| `protest_data` | object | Protest settings | **[protest_data Object](#objeto-protest_settings)** |
| `bankruptcy_protest_data` | object | Bankruptcy protest settings | **[bankruptcy_protest_data Object](#objeto-bankruptcy_protest_settings)** |
| `fine_data` | object | Fine settings | **[fine_data Object](#objeto-fine_settings)** |
| `interest_data` | object | Interest settings | **[interest_data Object](#objeto-interest_settings)** |
| `discounts_data` | object array | Discounts | **[discount Object](#objeto-discounts_data)** |
| `payer_data` * | object | Payer data | **[payer_data Object](#objetos-payer_data-e-guarantor_data)** |
| `guarantor_data` * | object | Guarantor data | **[guarantor_data Object](#objetos-payer_data-e-guarantor_data)** |
| `qr_code_data` | object | QR Code data | **[qr_code_data Object](#objeto-qr_code_data)** |
| `payment_notice_data` | object or array | Payment notice data | **[payment_notice_data Object or array](#objeto-ou-array-payment_notice_data)** |
| `payment_data` | object or array | Payment data | **[payment_data Object or array](#objeto-ou-array-payment_data)** |
| `guarantor_data` | object | Guarantor data | **[guarantor_data Object](#objetos-payer_data-e-guarantor_data)** |
| `occurrences` | object array | Instructions related to the bank slip | **[bank_slip_occurrence Object](#objeto-bank_slip_occurrence)** |
:::info Information
The `amount` field is the base amount of the bank slip, i.e., it does not include the fine, interest, rebate, or discounts.
:::
### bank_slip_status Enumerators {#enumeradores-bank_slip_status}
| Enumerator | Description |
|------------------------------|--------------------------------------------------------------------------------|
| accepted | Accepted and sent to Nuclea/CIP for analysis |
| rejected | Registration rejected by Nuclea/CIP |
| payment_notice | Payment notice (bank slip paid but payment not yet settled) |
| notary_office_payment_notice | Notary office payment notice (bank slip paid but payment not yet settled) |
| registered | Registration confirmed by Nuclea/CIP |
| payment_blocked | Blocked for payment (in protest flow) |
| paid | Paid |
| written_off | Written off |
### protest_status Enumerators {#enumeradores-protest_status}
| Enumerator | Description |
|------------------------------|--------------------------------------------------------------------------------|
| not_protested | Bank slip with no protest flow initiated |
| protest_requested | Notary office protest requested |
| notary_office_entry | Bank slip at the notary office, in the three-day grace period |
| protest_cancel_requested | Protest withdrawal requested |
| notary_office_exit | Bank slip left the notary office |
| protested | Bank slip protested |
| paid_at_notary_office | Paid at the notary office |
| judicially_suspended | Protest judicially suspended |
| protest_remove_requested | Protest removal requested |
### write_off_data Object {#objeto-write_off_settings}
| Field | Type | Description | Characters |
|---------------------------|---------|-----------------------------------------------------------------------------|------------|
| `days_to_write_off` * | integer | Days, after the due date, for the bank slip to be automatically written off | - |
### protest_data Object {#objeto-protest_settings}
| Field | Type | Description | Characters |
|---------------------------|---------|-----------------------------------------------------------------------------|------------|
| `days_to_protest` * | integer | Days, after the due date, for the bank slip to be automatically protested | - |
### bankruptcy_protest_data Object {#objeto-bankruptcy_protest_settings}
| Field | Type | Description | Characters |
|--------------------------------|---------|-----------------------------------------------------------------------------|------------|
| `days_to_bankruptcy_protest` * | integer | Days, after the due date, for the bank slip to be automatically protested | - |
### fine_data Object {#objeto-fine_settings}
Option 1: fine as an absolute amount (`fine_type=absolute`)
| Field | Type | Description | Characters |
|---------------------------|---------|---------------------------------------------------------|-------------------------------------------------------------------------|
| `fine_type` * | string | Fine type | **[fine_type Enumerators](#enumeradores-fine_type)** |
| `fine_amount` * | float | Absolute fine amount | - |
| `days_to_fine` * | integer | Days, after the due date, for the fine to be charged | - |
Option 2: fine as a percentage (`fine_type=percentage`)
| Field | Type | Description | Characters |
|---------------------------|---------|-----------------------------------------------------------|---------------------------------------|
| `fine_type` * | string | Fine type | **[fine_type Enumerators](#enumeradores-fine_type)** |
| `fine_percentage` * | integer | Fine percentage, from 1 to 100 | - |
| `days_to_fine` * | integer | Days, after the due date, for the fine to be charged | - |
### fine_type Enumerators {#enumeradores-fine_type}
| Enumerator | Description |
|--------------------|-----------------------|
| absolute | absolute amount |
| percentage | percentage |
### interest_data Object {#objeto-interest_settings}
Option 1: interest using absolute amounts (`interest_type=calendar_days_daily_amount` or `interest_type=workdays_daily_amount`)
| Field | Type | Description | Characters |
|---------------------------|---------|-------------------------------------------------------------------------------------|------------------------------------------------------------------------------------------------|
| `interest_type` * | string | Interest type | **[interest_type Enumerators](#enumeradores-interest_type)** |
| `interest_amount` * | float | Amount to be charged per defined unit of time (workdays or calendar days) | - |
| `days_to_interest` * | integer | Days, after the due date, for interest to start being charged | - |
Option 2: interest using percentages (`interest_type=calendar_days_monthly_percentage`)
| Field | Type | Description | Characters |
|--------------------------|---------|---------------------------------------------------------------------------------------|----------------------------------------------------------------------------------------------------|
| `interest_type` * | string | Interest type | **[interest_type Enumerators](#enumeradores-interest_type)** |
| `interest_percentage` * | integer | Percentage to be charged per defined unit of time (workdays or calendar days) | - |
| `days_to_interest` * | integer | Days, after the due date, for interest to start being charged | - |
### interest_type Enumerators {#enumeradores-interest_type}
| Enumerator | Description |
|----------------------------------|----------------------------------------------------------------------|
| calendar_days_daily_amount | Daily amount over calendar days |
| workdays_daily_amount | Daily amount over workdays |
| calendar_days_monthly_percentage | Interest percentage charged monthly, based on calendar days |
### discount Object {#objeto-discounts_data}
Option 1: discounts using absolute amounts (`discount_type in ["absolute", "anticipation_calendar_days_daily_amount", "anticipation_workdays_daily_amount"]`)
| Field | Type | Description | Characters |
|---------------------------|---------|-----------------------------------------------------|-----------------------------------------------------------|
| `discount_amount` * | float | Absolute discount amount per unit of time | - |
| `discount_number` * | integer | Discount number | - |
| `discount_type` * | string | Discount settings using absolute amounts | **[discount_type Enumerator](#enumeradores-discount_type)** | |
| `discount_limit_date` * | string | Deadline date for applying the discount | 10 |
Option 2: discounts using percentages (`discount_type in ["percentage", "anticipation_calendar_days_daily_percentage", "anticipation_workdays_daily_percentage"]`)
| Field | Type | Description | Characters |
|---------------------------|---------|-----------------------------------------------------|-----------------------------------------------------------|
| `discount_percentage` * | float | Discount percentage per unit of time | - |
| `discount_number` * | integer | Discount number | - |
| `discount_type` * | string | Discount settings using percentages | **[discount_type Enumerator](#enumeradores-discount_type)** | |
| `discount_limit_date` * | string | Deadline date for applying the discount | 10 |
:::caution Warning!
A bank slip can have up to three discounts, and all discounts must be of the same type , i.e., they must have the same `discount_type`. Discounts must be numbered from 1 to 3, in ascending order and necessarily starting at 1. That is, if two discounts are sent in the request, they must necessarily be numbered 1 and 2.
:::
### discount_type Enumerators {#enumeradores-discount_type}
| Enumerator | Description |
|---------------------------------------------|--------------------------------------------------------------------------|
| absolute | Fixed amount |
| anticipation_calendar_days_daily_amount | Daily early-payment discount amount, over calendar days |
| anticipation_workdays_daily_amount | Daily early-payment discount amount, over workdays |
| percentage | Fixed percentage |
| anticipation_calendar_days_daily_percentage | Monthly early-payment discount percentage, based on calendar days |
| anticipation_workdays_daily_percentage | Annual early-payment discount percentage, based on workdays |
### payer_data and guarantor_data Objects {#objetos-payer_data-e-guarantor_data}
| Field | Type | Description | Characters|
|---------------------------|--------|-------------------------------------|-----------------------------------------------------------|
| `name` * | string | Full name | 100 |
| `document_number` * | string | Document number (CPF/CNPJ) | 11 or 14 |
| `person_type` * | string | Person type (natural or legal) | **[person_type Enumerators](#enumeradores-person_type)** |
| `contact` | object | Contact information | **[contact Object](#objeto-contact)** |
| `address` | object | Address | **[address Object](#objeto-address)** |
### person_type Enumerators {#enumeradores-person_type}
| Enumerator | Description |
|--------------------|-----------------------|
| natural | natural person |
| legal | legal entity |
### contact Object {#objeto-contact}
| Field | Type | Description | Characters |
|---------------------------|--------|-----------------------------------|------------------------------------|
| `email` | string | Contact email | 320 |
| `phone` | object | Contact phone | **[phone Object](#objeto-phone)** |
### phone Object {#objeto-phone}
| Field | Type | Description | Characters |
|---------------------------------|--------|----------------------------------------------|------------|
| `international_dial_code` * | string | International dialing code (DDI) | 3 |
| `area_code` * | string | Area code (DDD) | 2 |
| `number` * | string | Phone number | 9 |
### address Object {#objeto-address}
| Field | Type | Description | Characters |
|---------------------------|--------|----------------------------------------------|------------|
| `street` * | string | Street | 500 |
| `number` * | string | Number | 6 |
| `complement` | string | Complement | 500 |
| `neighborhood` * | string | Neighborhood | 100 |
| `postal_code` * | string | Postal code | 8 |
| `city` * | string | City | 100 |
| `state` * | string | State (UF) | **[state Enumerator](#enumeradores-state)** |
### state Enumerators {#enumeradores-state}
| Enumerator | Description |
|--------------------|-----------------------|
| AC | Acre |
| AL | Alagoas |
| AM | Amazonas |
| AP | Amapá |
| BA | Bahia |
| CE | Ceará |
| DF | Federal District |
| ES | Espírito Santo |
| GO | Goiás |
| MA | Maranhão |
| MG | Minas Gerais |
| MS | Mato Grosso do Sul |
| MT | Mato Grosso |
| PA | Pará |
| PB | Paraíba |
| PE | Pernambuco |
| PI | Piauí |
| PR | Paraná |
| RJ | Rio de Janeiro |
| RN | Rio Grande do Norte |
| RO | Rondônia |
| RR | Roraima |
| RS | Rio Grande do Sul |
| SC | Santa Catarina |
| SE | Sergipe |
| SP | São Paulo |
| TO | Tocantins |
| EX | Exception |
### qr_code_data Object {#objeto-qr_code_data}
| Field | Type | Description | Characters |
|----------------------------|--------|-------------------------------------------------------|-------------------------|
| `qr_code_key` | uuidv4 | Unique QR Code identification key | 36 |
| `pix_key` | uuidv4 | PIX key linked to the QR Code | 36 |
| `receiver_conciliation_id` | uuidv4 | QR Code conciliation identifier | 36 |
| `url` | string | QR Code URL (Pix Copy and Paste) | - |
| `image` | string | base64 of the QR Code URL (Pix Copy and Paste) | - |
### payment_notice_data Object or array {#objeto-ou-array-payment_notice_data}
:::caution Warning!
The `payment_notice_data` field is returned as an **object** for bank slips without partial payment settings. For bank slips with partial payment settings, it is returned as an **array of objects**, since there may be multiple payments.
In addition, if the bank slip is paid via **QR Code**, this field will not be returned, since settlement occurs on the payment day.
:::
| Field | Type | Description | Characters |
|---------------------------|---------|-------------------------------------------------------------------------------------|------------------------------------------------------------------------------------------------|
| `payment_method` | string | Payment method | **[payment_method Enumerators](#enumeradores-payment_method)** |
| `payment_origin` | string | Payment origin | **[payment_origin Enumerators](#enumeradores-payment_origin)** |
| `payment_notice_date` | string | Payment notice date | 10
### payment_data Object or array {#objeto-ou-array-payment_data}
:::caution Warning!
The `payment_data` field is returned as an **object** for bank slips without partial payment settings. For bank slips with partial payment settings, it is returned as an **array of objects**, since there may be multiple payments.
:::
| Field | Type | Description | Characters |
|---------------------------|---------|-------------------------------------------------------------------------------------|------------------------------------------------------------------------------------------------|
| `paid_amount` | float | Payment amount | - |
| `paid_rebate_amount` | float | Paid rebate amount | - |
| `paid_discount_amount` | float | Paid discount amount | - |
| `paid_fine_amount` | float | Paid fine amount | -
| `paid_interest_amount` | float | Paid interest amount | -
| `payment_method` | string | Payment method | **[payment_method Enumerators](#enumeradores-payment_method)** |
| `payment_origin` | string | Payment origin | **[payment_origin Enumerators](#enumeradores-payment_origin)** |
| `payment_credit_date` | string | Payment credit date | 10
| `payment_bank` | object | Bank where the bank slip was paid. Returned only after the bank slip is paid | **[payment_bank Object](#objeto-payment_bank)** |
| `payment_branch` | string | Branch where the bank slip was paid. Returned only after the bank slip is paid | -
:::info Information
The `payment_bank` and `payment_branch` fields are only returned once the bank slip has been paid, i.e., when a confirmed payment occurrence exists. While the bank slip is unpaid, these fields will not be present in the response.
:::
### payment_bank Object {#objeto-payment_bank}
| Field | Type | Description | Characters |
|--------|---------|--------------------------------------------|------------|
| `code` | string | Bank clearing code (3 digits) | 3 |
| `ispb` | integer | Bank ISPB | 8 |
| `name` | string | Bank name | - |
### payment_method Enumerators {#enumeradores-payment_method}
| Enumerator | Description |
|--------------------|-----------------------------------------|
| cash | Cash |
| account_debit | Account debit |
| credit_card | Credit card |
| check | Check |
### payment_origin Enumerators
| Enumerator | Description |
|--------------------|-----------------------------------------|
| cash | Cash |
| account_debit | Account debit |
| credit_card | Credit card |
| check | Check |
### payment_origin Enumerators {#enumeradores-payment_origin}
| Enumerator | Description |
|----------------------|------------------------------------------|
| phisical_cashier | Branches - traditional locations |
| taa | Self-service terminal |
| internet | Internet (home/office bank) |
| corban | Banking correspondent |
| call_center | Call center |
| eletronic_file | Electronic file |
| dda | DDA |
| digital_correspondent| Digital correspondent |
| qr_code | Payment via Pix QR Code |
### bank_slip_occurrence Object {#objeto-bank_slip_occurrence}
| Field | Type | Description | Characters |
|-------------------------|--------|-----------------------------------------------------------------------------------|------------|
| `request_control_key` * | uuidv4 | Unique identification key of the request used by the client, in uuid v4 format | 36 |
| `occurrence_key` * | uuidv4 | Unique bank slip identification key, in uuid v4 format | 36 |
| `occurrence_type` * | string | Occurrence type | **[occurrence_type Enumerator](#enumeradores-occurrence_type)** |
| `occurrence_status` * | string | Occurrence status | **[occurrence_status Enumerator](#enumeradores-occurrence_status)** |
| `created_at` * | string | Date, in ISO format (UTC - "YYYY-MM-DDTHH:MM:SSZ"), the occurrence was created | 20 |
### occurrence_type Enumerators {#enumeradores-occurrence_type}
| Enumerator | Description |
|--------------------|-----------------------------------------|
| registration | Registration occurrence |
| write_off | Write-off request occurrence |
| rebate | Rebate addition occurrence |
| cancel_rebate | Rebate cancellation occurrence |
| discount | Discount change occurrence |
| fine | Fine change occurrence |
| interest | Interest change occurrence |
| extension | Extension occurrence |
| bank_slip_edit | Occurrence of changes to other bank slip data |
| payment_notice | Payment notice occurrence |
| payment | Payment settlement occurrence |
| protest_request | Protest request occurrence |
| protest_request | Bankruptcy protest request occurrence |
### occurrence_status Enumerators {#enumeradores-occurrence_status}
| Enumerator | Description |
|--------------------|-----------------------------------------|
| pending | Sent to Nuclea/CIP for analysis |
| rejected | Rejected |
| confirmed | Confirmed |
## Error Response
STATUS 4xx
Response Body: Error
```json
{
"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 (ptbr) `translation` |
|--------------------------|----------------------|----------------------------------------------------|-------------------------------------------------------------------------------------------------------------------------|------------------------------------------------------------------------------------------------------------------------|
| 400 | QIT000001 | Bad Request | Schema Error | Schema Inválido |
| 404 | BKS000006 | Not Found | The source account key was not found. | A chave da conta de origem não foi encontrada. |
| 400 | BKS000007 | Bad Request | It 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. |
| 400 | BKS000008 | Bad Request | The source account is closed. | A conta de origem está fechada. |
| 400 | BKS000009 | Bad Request | The source account is blocked. | A conta de origem está bloqueada. |
| 404 | BKS000013 | Not Found | Requester profile not found | Carteira não encontrada |
| 400 | BKS000022 | Bad Request | Requester profile is not opened. | Carteira não está aberta. |
| 404 | BKS000029 | Not Found | Bank slip not found for the given key (`{bank_slip_key}`). | Boleto não encontrado para a chave fornecida (`{bank_slip_key}`). |
---
# List Bank Slips
URL: /en/documentation/boletos/consulta/listar_boletos
The bank slip listing will return all bank slips from the wallet that fit the query parameters sent in the request.
## Request
ENDPOINT /account/ ACCOUNT_KEY /requester_profile/ REQUESTER_PROFILE_KEY /bank_slips
METHOD GET
### Path parameters
| Field | Type | Description | Characters |
|-------------------------|--------|--------------------------------------------------------------|------------|
| `account_key` | uuidv4 | Unique account identification key, in uuid v4 format | 36 |
| `requester_profile_key` | uuidv4 | Unique wallet identification key, in uuid v4 format | 36 |
### Query parameters
| Field | Type | Description | Characters |
|-------------------------|--------|--------------------------------------------------------------|-------------------------|
| `request_control_key` | uuidv4 | Unique request identification key, in uuid v4 format | 36 |
| `bank_slip_key` | uuidv4 | Unique bank slip identification key, in uuid v4 format | 36 |
| `bank_slip_status` | string | Bank slip status | **[bank_slip_status Enumerators](#enumeradores-bank_slip_status)** |
| `page` | integer| Page number | - |
| `page_size` | integer| Page size | - |
| `from_date` | string | Initial registration date (format "YYYY-MM-DD") | 10 |
| `to_date` | string | Final registration date (format "YYYY-MM-DD") | 10 |
### Enumeradores bank_slip_status
| Enumerator | Description |
|------------------------------|--------------------------------------------------------------------------------|
| accepted | Accepted and sent to Nuclea/CIP for analysis |
| rejected | Registration rejected by Nuclea/CIP |
| payment_notice | Payment notice (bank slip paid but payment not yet settled) |
| notary_office_payment_notice | Notary office payment notice (bank slip paid but payment not yet settled) |
| registered | Registration confirmed by Nuclea/CIP |
| payment_blocked | Blocked for payment (in protest flow) |
| paid | Paid |
| written_off | Written off |
## Response
STATUS 200
Response Body
```json
{
"data": [
{
"bank_slip_key": "b58ce415-5428-45c4-8e33-b2df0d3ab6e8",
"request_control_key": "53529224-330d-44b5-9f4d-59d55bc3cb8c",
"our_number": 24384760943,
"document_number": "DOC4561237",
"amount": "8000.00",
"rebate_amount": "200.00",
"expiration": "2024-07-13",
"barcode": "32994978900005000000001594438621284040114400",
"digitable_line": "32990001529443862128940401144007497890000500000",
"bank_teller_instructions": "Confirm payment",
"protest_data": {
"days_to_protest": 7
},
"bankruptcy_protest_data": {
"days_to_bankruptcy_protest": 14
},
"max_payment_days": 45,
"fine_data": {
"fine_type": "absolute",
"fine_amount": 100.0,
"days_to_fine": 10
},
"interest_data": {
"interest_type": "workdays_daily_amount",
"interest_amount": 5.0,
"days_to_interest": 10
},
"discounts_data": [
{
"discount_type": "anticipation_workdays_daily_percentage",
"discount_number": 1,
"discount_limit_date": "2024-07-13",
"discount_percentage": 10
}
],
"payer_data": {
"name": "Country Tech",
"address": {
"city": "Innovation City",
"state": "RS",
"number": "202",
"street": "101 High St.",
"complement": "Building A",
"postal_code": "57099999",
"neighborhood": "Tech Park"
},
"person_type": "legal",
"document_number": "12345678000195"
},
"guarantor_data": {
"name": "Jamie Doe",
"address": {
"city": "Peaceful Town",
"state": "MG",
"number": "303",
"street": "202 Elm St.",
"complement": "House 1",
"postal_code": "57099999",
"neighborhood": "Quiet Neighborhood"
},
"person_type": "natural",
"document_number": "98765432100"
},
"bank_slip_status": "paid",
"payment_data": {
"paid_amount": 8000.0,
"payment_credit_date": "2024-07-15",
"payment_date": "2024-07-14"
}
}
],
"pagination": {
"current_page": 1,
"rows_per_page": 100
}
}
```
### Response Body Params
| Field | Type | Description | Characters |
|------------------|--------------|---------------------------------------|---------------------------------------------|
| `data` * | object array | Bank slips | **[bank_slip Object](#objeto-bank_slip)** |
| `pagination` * | object | Pagination information | **[pagination Object](#objeto-pagination)** |
### Objeto bank_slip
| Field | Type | Description | Characters |
|----------------------------|---------|------------------------------------------------------------------------------------|--------------------------------------------------|
| `bank_slip_key ` * | uuidv4 | Unique bank slip identification key in uuid v4 format | 36 |
| `request_control_key` * | uuidv4 | Unique request identification key used by the client in uuid v4 format | 36 |
| `our_number` * | integer | Unique identification number of the bank slip within the wallet | 11 |
| `bank_slip_status` * | string | Bank slip status | **[bank_slip_status Enumerators](#enumeradores-bank_slip_status)** |
| `protest_status` * | string | Bank slip protest status at notary office | **[protest_status Enumerators](#enumeradores-protest_status)** |
| `document_number` * | string | Bank slip identification number | 10 |
| `amount` * | float | Bank slip base amount | - |
| `expiration` * | string | Due date | 10 |
| `barcode` * | string | Bank slip barcode | 44 |
| `digitable_line` * | string | Bank slip digitable line | 47 |
| `bank_teller_instructions` | string | Additional registration instructions, which will appear on the bank slip PDF | 320 |
| `rebate_amount` | float | Bank slip rebate amount, which will be applied on top of the base amount | - |
| `max_payment_days` * | integer | Maximum calendar days the bank slip will remain available for payment after due date (can be at most 365) | - |
| `write_off_data` | object | Write-off configuration | **[write_off_data Object](#objeto-write_off_settings)** |
| `protest_data` | object | Protest configuration | **[protest_data Object](#objeto-protest_settings)** |
| `bankruptcy_protest_data` | object | Bankruptcy protest configuration | **[bankruptcy_protest_data Object](#objeto-bankruptcy_protest_settings)** |
| `fine_data` | object | Fine configuration | **[fine_data Object](#objeto-fine_settings)** |
| `interest_data` | object | Interest configuration | **[interest_data Object](#objeto-interest_settings)** |
| `discounts_data` | object array | Discounts | **[discount Object](#objeto-discounts_data)** |
| `payer_data` * | object | Payer data | **[payer_data Object](#objetos-payer_data-e-guarantor_data)** |
| `guarantor_data` * | object | Guarantor data | **[guarantor_data Object](#objetos-payer_data-e-guarantor_data)** |
### Objeto pagination
| Field | Type | Description | Characters |
|----------------------------|---------|------------------------------------------------------------------------------------|--------------------------------------------------------------|
| `current_page` * | integer | Current page | - |
| `rows_per_page` * | integer | Items per page | - |
### Enumeradores protest_status
| Enumerator | Description |
|------------------------------|--------------------------------------------------------------------------------|
| not_protested | Bank slip without protest flow initiated |
| protest_requested | Notary office protest requested |
| notary_office_entry | Bank slip at notary office, in three-day period |
| protest_cancel_requested | Protest withdrawal requested |
| notary_office_exit | Bank slip left notary office |
| protested | Bank slip protested |
| paid_at_notary_office | Paid at notary office |
| judicially_suspended | Protest judicially suspended |
| protest_remove_requested | Protest removal requested |
### Objeto write_off_data
| Field | Type | Description | Characters |
|---------------------------|---------|-----------------------------------------------------------------------------|------------|
| `days_to_write_off` * | integer | Days after due date for the bank slip to be automatically written off | - |
### Objeto protest_data
| Field | Type | Description | Characters |
|---------------------------|---------|-----------------------------------------------------------------------------|------------|
| `days_to_protest` * | integer | Days after due date for the bank slip to be automatically protested | - |
### Objeto bankruptcy_protest_data
| Field | Type | Description | Characters |
|--------------------------------|---------|-----------------------------------------------------------------------------|------------|
| `days_to_bankruptcy_protest` * | integer | Days after due date for the bank slip to be automatically protested | - |
### Objeto fine_data
Option 1: fine in absolute value (`fine_type=absolute`)
| Field | Type | Description | Characters |
|---------------------------|---------|---------------------------------------------------------|-------------------------------------------------------------------------|
| `fine_type` * | string | Fine type | **[fine_type Enumerators](#enumeradores-fine_type)** |
| `fine_amount` * | float | Fine absolute value | - |
| `days_to_fine` * | integer | Days after due date for the fine to be charged | - |
Option 2: fine in percentage value (`fine_type=percentage`)
| Field | Type | Description | Characters |
|---------------------------|---------|-----------------------------------------------------------|---------------------------------------|
| `fine_type` * | string | Fine type | **[fine_type Enumerators](#enumeradores-fine_type)** |
| `fine_percentage` * | integer | Fine percentage value, from 1 to 100 | - |
| `days_to_fine` * | integer | Days after due date for the fine to be charged | - |
### Enumeradores fine_type
| Enumerator | Description |
|--------------------|-----------------------|
| absolute | absolute value |
| percentage | percentage value |
### Objeto interest_data
Option 1: interest using absolute values (`interest_type=calendar_days_daily_amount` or `interest_type=workdays_daily_amount`)
| Field | Type | Description | Characters |
|---------------------------|---------|-------------------------------------------------------------------------------------|------------------------------------------------------------------------------------------------|
| `interest_type` * | string | Interest type | **[interest_type Enumerators](#enumeradores-interest_type)** |
| `interest_amount` * | float | Amount to be charged per determined time unit (workdays or calendar days) | - |
| `days_to_interest` * | integer | Days after due date to start charging interest | - |
Option 2: interest using percentage values (`interest_type=calendar_days_monthly_percentage`)
| Field | Type | Description | Characters |
|--------------------------|---------|---------------------------------------------------------------------------------------|----------------------------------------------------------------------------------------------------|
| `interest_type` * | string | Interest type | **[interest_type Enumerators](#enumeradores-interest_type)** |
| `interest_percentage` * | integer | Percentage to be charged per determined time unit (workdays or calendar days) | - |
| `days_to_interest` * | integer | Days after due date to start charging interest | - |
### Enumeradores interest_type
| Enumerator | Description |
|----------------------------------|----------------------------------------------------------------------|
| calendar_days_daily_amount | Daily amount on calendar days |
| workdays_daily_amount | Daily amount on workdays |
| calendar_days_monthly_percentage | Monthly interest percentage charged, based on calendar days |
### Objeto discount
Option 1: discounts using absolute values (`discount_type in ["absolute", "anticipation_calendar_days_daily_amount", "anticipation_workdays_daily_amount"]`)
| Field | Type | Description | Characters |
|---------------------------|---------|-----------------------------------------------------|-----------------------------------------------------------|
| `discount_amount` * | float | Absolute discount value per time unit | - |
| `discount_number` * | integer | Discount number | - |
| `discount_type` * | string | Discount configuration in absolute values | **[discount_type Enumerator](#enumeradores-discount_type)** | |
| `discount_limit_date` * | string | Limit date for discount application | 10 |
Option 2: discounts using percentage values (`discount_type in ["percentage", "anticipation_calendar_days_daily_percentage", "anticipation_workdays_daily_percentage"]`)
| Field | Type | Description | Characters |
|---------------------------|---------|-----------------------------------------------------|-----------------------------------------------------------|
| `discount_percentage` * | float | Percentage discount value per time unit | - |
| `discount_number` * | integer | Discount number | - |
| `discount_type` * | string | Discount configuration in percentage values | **[discount_type Enumerator](#enumeradores-discount_type)** | |
| `discount_limit_date` * | string | Limit date for discount application | 10 |
:::caution Attention!
The bank slip can have up to three discounts, and all discounts must be of the same type , that is, they must have the same `discount_type`. Discounts must be numbered from 1 to 3, incrementally and starting necessarily at 1. That is, if two discounts are sent in the request, they must necessarily be numbered 1 and 2.
:::
### Enumeradores discount_type
| Enumerator | Description |
|---------------------------------------------|--------------------------------------------------------------------------|
| absolute | Fixed value |
| anticipation_calendar_days_daily_amount | Daily anticipation discount value, on calendar days |
| anticipation_workdays_daily_amount | Daily anticipation discount value, on workdays |
| percentage | Fixed percentage |
| anticipation_calendar_days_daily_percentage | Monthly anticipation discount percentage, based on calendar days |
| anticipation_workdays_daily_percentage | Annual anticipation discount percentage, based on workdays |
### Objetos payer_data e guarantor_data
| Field | Type | Description | Characters|
|---------------------------|--------|-------------------------------------|-----------------------------------------------------------|
| `name` * | string | Full name | 100 |
| `document_number` * | string | Document number (CPF/CNPJ) | 11 or 14 |
| `person_type` * | string | Person type (natural or legal) | **[person_type Enumerators](#enumeradores-person_type)** |
| `contact` | object | Contact information | **[contact Object](#objeto-contact)** |
| `address` | object | Address | **[address Object](#objeto-address)** |
### Enumeradores person_type
| Enumerator | Description |
|--------------------|-----------------------|
| natural | natural person |
| legal | legal person |
### Objeto contact
| Field | Type | Description | Characters |
|---------------------------|--------|-----------------------------------|------------------------------------|
| `email` | string | Contact email | 320 |
| `phone` | object | Contact phone | **[phone Object](#objeto-phone)** |
### Objeto phone
| Field | Type | Description | Characters |
|---------------------------------|--------|----------------------------------------------|------------|
| `international_dial_code` * | string | International dialing code | 3 |
| `area_code` * | string | Area code | 2 |
| `number` * | string | Number | 9 |
### Objeto address
| Field | Type | Description | Characters |
|---------------------------|--------|----------------------------------------------|------------|
| `street` * | string | Street | 500 |
| `number` * | string | Number | 6 |
| `complement` | string | Complement | 500 |
| `neighborhood` * | string | Neighborhood | 100 |
| `postal_code` * | string | Postal code | 8 |
| `city` * | string | City | 100 |
| `state` * | string | State | **[state Enumerator](#enumeradores-state)** |
### Enumeradores state
| Enumerator | Description |
|--------------------|-----------------------|
| AC | Acre |
| AL | Alagoas |
| AM | Amazonas |
| AP | Amapá |
| BA | Bahia |
| CE | Ceará |
| DF | Distrito federal |
| ES | Espírito Santo |
| GO | Goiás |
| MA | Maranhão |
| MG | Minas Gerais |
| MS | Mato Grosso do Sul |
| MT | Mato Grosso |
| PA | Pará |
| PB | Paraíba |
| PE | Pernambuco |
| PI | Piauí |
| PR | Paraná |
| RJ | Rio de Janeiro |
| RN | Rio Grande do Norte |
| RO | Rondônia |
| RR | Roraima |
| RS | Rio Grande do Sul |
| SC | Santa Catarina |
| SE | Sergipe |
| SP | São Paulo |
| TO | Tocantins |
| EX | Exception |
## Error Response
STATUS 4xx
Response Body: Error
```json
{
"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` |
|--------------------------|----------------------|----------------------------------------------------|-------------------------------------------------------------------------------------------------------------------------|------------------------------------------------------------------------------------------------------------------------|
| 403 | BKS000005 | Forbidden | User is not allowed to do this action | Usuário não tem autorização para fazer essa ação |
| 404 | BKS000006 | Not Found | The source account key was not found. | A chave da conta de origem não foi encontrada. |
| 400 | BKS000007 | Bad Request | It 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. |
| 400 | BKS000008 | Bad Request | The source account is closed. | A conta de origem está fechada. |
| 400 | BKS000009 | Bad Request | The source account is blocked. | A conta de origem está bloqueada. |
| 400 | BKS000012 | Bad Request | Invalid integer value for page or size query string parameters. | Valor inválido para parâmetros de página ou tamanho de página. |
| 404 | BKS000013 | Not Found | Requester profile not found | Carteira não encontrada |
---
# Bank slip wallet inquiry
URL: /en/documentation/boletos/consultar_v1/consulta_de_carteira
## Request
ENDPOINT /bank_slip/requester_profiles
METHOD GET
## Response
STATUS 200
Response Body
```json
{
"requester_profile_codes": [
"329-09-0001-1467576",
"329-09-0001-5747500",
"329-09-0001-2730579",
"329-09-0001-2359934"
]
}
```
---
# Query return file
URL: /en/documentation/boletos/consultar_v1/consultar_arquivo_retorno
:::info Warning
To ensure that the return file for the current day has updated information, verify that the day's information has been reconciled through polling as shown in [Return file reconciliation routine](/documentation/boletos/consultar/rotina_de_conciliacao_de_arquivo_retorno)
:::
## Request
ENDPOINT /bank_slip/requester_profile/ REQUESTER_PROFILE_CODE /cnab_files
METHOD GET
### Path params
| Field | Type | Description | Characters |
|----------------------------|--------|---------------------------------|------------|
| `requester_profile_code` * | string | Collection portfolio code. | 10 |
### Query params
| Field | Type | Description | Characters |
|---------------|--------|------------------------------------|---------------------------------------------|
| `cnab_type` * | enum | File Type | **[Enumerators](#enumerators-cnab_type)** |
| `from` * | string | Start of the period to be analyzed.| 10 |
| `to` * | string | End of the period to be analyzed. | 10 |
### Enumerators cnab_type
| Field | Description |
|---------------------|----------------|
| requester_discharge | Return file |
## Response
STATUS 200
Response Body
```json
{
"data": [
{
"cnab_key": "47361262-0853-4c51-9c2a-5284e0d8a5e1",
"company_code": null,
"created_at": "2020-05-06T11:04:25",
"downloads": [],
"file_size": "None",
"filename": "CNAB.RET",
"line_length": "400",
"remitter_key": "ab871cc8-8369-4b72-95f1-b074b30c7208",
"requester_profile_code": "329-01-0001-0000002",
"type": {
"created_at": "2019-03-12T12:59:32",
"enumerator": "requester_discharge",
"translation_path": "bank_slip.CNABFileType.requester_discharge"
},
"url": "https://linkparadownload.com/CNAB.RET",
"version": "11"
}
],
"pagination": {
"current_page": 1,
"next_page": null,
"rows_per_page": 100,
"total_pages": 1,
"total_rows": 1
}
}
```
STATUS 400
Response Body
```json
{
"data": "{\"title\": \"Bad Request\", \"description\": \"Invalid request body.\", \"translation\": \"Corpo da requisição inválido.\", \"extra_fields\": {}, \"code\": \"LEG000069\"}"
}
```
---
# Query bank slip
URL: /en/documentation/boletos/consultar_v1/consultar_boleto
## Request
ENDPOINT /bank_slip/ BANK_SLIP_KEY
METHOD GET
### Path params
| Field | Type | Description | Characters |
|---|---|---|---|
| `bank_slip_key` *| string | Bank slip identification key | uuid key |
## Response
STATUS 200
Response Body
```json
{
"amount": 3,
"asset_type": {
"created_at": "2019-02-01T16:44:11",
"enumerator": "invoice",
"translation_path": "bank_slip.AssetType.invoice"
},
"automatic_bankruptcy_protest": true,
"automatic_protest": false,
"automatic_write_off": false,
"bank_slip_file": [],
"bank_slip_key": "96b32f1a-c2bd-41a4-b4b1-a169235be68b",
"bank_slip_status": {
"created_at": "2019-02-01T16:44:07",
"enumerator": "registered",
"translation_path": "bank_slip.BankSlipStatus.registered"
},
"bank_teller_instructions": "Não aceitar após vencimento",
"barcode": "32991918600000900000001090000000000457475000",
"beneficiary_account_branch": "0001",
"beneficiary_account_digit": "5",
"beneficiary_account_key": "7cc3b1f7-8015-4073-8471-a3ba57e34975",
"beneficiary_account_number": "5747500",
"beneficiary_document_number": "12345678905",
"beneficiary_key": "b91195e3-0cf4-4fed-90cf-7f5bef29c2f0",
"beneficiary_name": "Greg Brown",
"billing_account_key": "7cc3b1f7-8015-4073-8471-a3ba57e34975",
"business_date_expiration": "2020-06-01",
"created_at": "2020-05-15T21:00:25",
"days_before_fine": null,
"days_before_interest": null,
"days_to_bankruptcy_protest": 1,
"days_to_protest": null,
"days_to_write_off": null,
"digitable_line": "32990001039000000000104574750008191860000090000",
"discount_limit_date": null,
"discount_value": null,
"discounts": [],
"document_number": "123456/01",
"expenses": [
{
"amount": 3.9,
"created_at": "2022-11-19T10:42:47",
"expense_key": "6f21f308-f6c6-4198-a8bc-bc0e853bb8b5",
"paid": true,
"reason": {
"created_at": "2019-02-14T17:30:50",
"reason_code": "Tarifa de registro",
"translation_en_us": "Registration Fee",
"translation_pt_br": "Tarifa de registro"
},
"subject": {
"created_at": "2019-02-14T17:30:43",
"enumerator": "requester",
"translation_path": "bank_slip.AssetType.requester"
},
"subject_account_key": "9223d7ae-320a-411c-8ff4-861e054da4d4",
"updated_at": "2022-11-19T10:46:31"
}
],
"expiration": "2020-06-01",
"fine_percentage": 0.1,
"guarantor_address": null,
"guarantor_city": null,
"guarantor_document": null,
"guarantor_name": null,
"guarantor_person_type": null,
"guarantor_postal_code": "00000000",
"guarantor_state": null,
"has_protest_pending_feedback": false,
"historical_our_number": 2,
"institution_registration_date": null,
"interest_daily_value": 0.34,
"lock_origin_type": null,
"max_payment_days": 180,
"nfe_key": null,
"nfe_url": null,
"notary_office_number": null,
"notary_office_protocol": null,
"notification": [],
"occurrences": [
{
"agent_type": "integration",
"automatic_bankruptcy_protest": null,
"automatic_protest": null,
"automatic_write_off": null,
"created_at": "2020-05-15T21:00:25",
"discount_amount": null,
"discounts": [],
"fine_percentage": 2,
"interest_daily_value": 0.34,
"iof_amount": null,
"new_bank_slip_status": {
"created_at": "2019-02-14T17:30:39",
"enumerator": "registered",
"translation_path": "bank_slip.BankSlipStatus.registered"
},
"new_due_date": "2020-06-01",
"new_protest_status": {
"created_at": "2019-02-01T16:44:08",
"enumerator": "not_protested",
"translation_path": "bank_slip.ProtestStatus.not_protested"
},
"notary_office_number": null,
"notary_office_protocol": null,
"notification": [],
"occurrence_expenses": null,
"occurrence_feedback": {
"created_at": "2019-02-14T17:30:46",
"enumerator": "confirmed",
"translation_path": "bank_slip.OccurrenceFeedback.confirmed"
},
"occurrence_key": "c3ab3e01-f198-4e7e-9e01-7a8091b8bd72",
"occurrence_reasons": [],
"occurrence_type": {
"created_at": "2019-02-01T16:44:14",
"enumerator": "registration",
"translation_path": "bank_slip.OccurrenceType.registration"
},
"old_bank_slip_status": {
"created_at": "2019-02-01T16:44:07",
"enumerator": "accepted",
"translation_path": "bank_slip.BankSlipStatus.accepted"
},
"old_due_date": null,
"old_protest_status": null,
"paid_amount": null,
"paid_fine_amount": null,
"paid_interest_amount": null,
"payer_address": null,
"payer_postal_code": null,
"payment_bank": null,
"payment_branch": null,
"payment_credit_date": null,
"payment_method": null,
"payment_origin": null,
"protest_confirmation": null,
"protest_distribution_cost": null,
"protest_electronic_cost": null,
"protest_emolument": null,
"protest_expenses": null,
"protest_other_expenses": null,
"protocol_date": null,
"protocol_region": null,
"rebate_amount": null,
"registration_institution_occurrence_date": "2020-05-15",
"registration_institution_occurrence_event": [
{
"cnab_file": {
"cnab_key": "abfc9fba-28fb-4e75-afcb-f4647d7031bc",
"company_code": null,
"created_at": "2020-05-15T21:00:22",
"downloads": [],
"file_size": "None",
"filename": null,
"line_length": null,
"remitter_key": "b91195e3-0cf4-4fed-90cf-7f5bef29c2f0",
"requester_profile_code": null,
"type": {
"created_at": "2019-02-01T16:44:17",
"enumerator": "api_instruction",
"translation_path": "bank_slip.CNABFileType.api_instruction"
},
"url": null,
"version": null
},
"cnab_file_occurrence_order": 1,
"created_at": "2020-05-15T21:00:25",
"new_status": {
"created_at": "2019-02-01T16:44:15",
"enumerator": "waiting_submission",
"translation_path": "bank_slip.RegistrationInstitutionOccurrenceStatus.waiting_submission"
},
"old_status": null
}
],
"registration_institution_occurrence_status": {
"created_at": "2019-02-01T16:44:15",
"enumerator": "waiting_submission",
"translation_path": "bank_slip.RegistrationInstitutionOccurrenceStatus.waiting_submission"
},
"requester_occurrence_event": [
{
"cnab_file": {
"cnab_key": "abfc9fba-28fb-4e75-afcb-f4647d7031bc",
"company_code": null,
"created_at": "2020-05-15T21:00:22",
"downloads": [],
"file_size": "None",
"filename": null,
"line_length": null,
"remitter_key": "b91195e3-0cf4-4fed-90cf-7f5bef29c2f0",
"requester_profile_code": null,
"type": {
"created_at": "2019-02-01T16:44:17",
"enumerator": "api_instruction",
"translation_path": "bank_slip.CNABFileType.api_instruction"
},
"url": null,
"version": null
},
"cnab_file_occurrence_order": 1,
"created_at": "2020-05-15T21:00:25",
"new_status": {
"created_at": "2019-02-01T16:44:16",
"enumerator": "confirmed",
"translation_path": "bank_slip.RequesterOccurrenceStatus.confirmed"
},
"old_status": {
"created_at": "2019-02-01T16:44:16",
"enumerator": "accepted",
"translation_path": "bank_slip.RequesterOccurrenceStatus.accepted"
}
}
],
"requester_occurrence_status": {
"created_at": "2019-02-01T16:44:16",
"enumerator": "confirmed",
"translation_path": "bank_slip.RequesterOccurrenceStatus.confirmed"
},
"selected_user_agent": null
}
],
"original_expiration": "2022-12-01",
"our_number": 2,
"paid_amount": null,
"paid_fine_amount": null,
"paid_interest_amount": null,
"participant_control_number": null,
"payer_account_digit": null,
"payer_account_number": null,
"payer_account_type": null,
"payer_address": "Rua Carlos Tampaio, 112",
"payer_bank": null,
"payer_branch_digit": null,
"payer_branch_number": null,
"payer_document": "45508922008",
"payer_name": "John Nobody",
"payer_person_type": {
"created_at": "2019-02-01T16:44:09",
"enumerator": "natural",
"translation_path": "bank_slip.PersonType.natural"
},
"payer_postal_code": "00000000",
"payment_date": null,
"printing_policy": {
"created_at": "2019-02-01T16:44:10",
"enumerator": "no_printing",
"translation_path": "bank_slip.PrintingPolicy.no_printing"
},
"protest_status": {
"created_at": "2019-02-01T16:44:08",
"enumerator": "not_protested",
"translation_path": "bank_slip.ProtestStatus.not_protested"
},
"protocol_date": null,
"protocol_region": null,
"qr_code": null,
"rebate_amount": null,
"reference_requester_profile_code": null,
"registration_institution": {
"created_at": "2020-03-26T19:36:16",
"enumerator": "qi_scd",
"febraban_code": "329",
"remittance_sequence": 72,
"settlement_resource_account_key": "3e46d266-4fdb-4fd2-b87a-3e3de366afd4"
},
"requester_profile": 1,
"requester_profile_code": "329-01-0001-0067049",
"requester_registration_date": "2020-05-15",
"settlement_account_key": "9223d7ae-320a-411c-8ff4-861e054da4d4",
"settlements": [],
"tags": null
}
```
STATUS 400
Response Body
```json
{
{"title": "Bad Request", "description": "Invalid request body.", "translation": "Corpo da requisição inválido.", "extra_fields": {}, "code": "LEG000069"}
}
```
---
# Issue PDF
URL: /en/documentation/boletos/consultar_v1/emitir_pdf
## Request
ENDPOINT /bank_slip/2-way/ BANK_SLIP_KEY
METHOD GET
### Path params
| Field | Type | Description | Characters |
|---|---|---|---|
| `BANK_SLIP_KEY` *| string | Bank slip identification key. | 10 |
## Response
STATUS 200
Response Body
```json
[
{
"barcode": "32998827300000003000001010000000000200670490",
"created_at": "2020-05-19T18:46:41",
"digitable_line": "32990001031000000000902006704908882730000000300",
"url": "https://linkparadownload.com/arquivo.pdf"
}
]
```
STATUS 400
Response Body
```json
{ }
```
---
# Francesinha
URL: /en/documentation/boletos/consultar_v1/francesinha
## Request
- ENDPOINT /bank_slip/little_french
- METHOD GET
### Body params
| Field | Type | Description | Characters |
|---|---|---|---|
| `requester_profile_code` *| string | Wallet code. | 10 |
| `date` | date | Date for report generation, if null, the report date will be TODAY (Format YYYY-MM-DD). | 10 |
## Response
status: 200
Body.json
The francesinha response body will be an excel file encoded in base64.
status: 400
Body.json
```json
{ }
```
---
# List bank slips
URL: /en/documentation/boletos/consultar_v1/listar_boletos
## Request
ENDPOINT /bank_slip/person/ BENEFICIARY_KEY
METHOD GET
:::caution **Warning**
Note that in both examples the bank_slip_file list is empty. This means there is no pdf file for this bank slip. If the client wants a PDF copy of the bank slip, we will explain how to do it in the next steps.
:::
### Path params
| Field | Type | Description | Characters |
|---|---|---|---|
| `beneficiary_key` *| string | Beneficiary identification key | uuid key |
### Query params
| Field | Type | Description | Characters |
|---|---|---|---|
| `payer_document` | string | Payer document number | - |
| `bank_slip_status` | enum | Bank slip status. | **[Enumerators](#enumerators-bank_slip_status)** |
| `requester_profile` | string | Bank slip portfolio number| - |
| `protest_status` | enum | Protest status. | **[Enumerators](#enumerators-protest_status)** |
| `from` | date | Bank slip creation start date. | 10 |
| `to` | date | Bank slip creation end date. | 10 |
| `number_search` | string | Our number (our_number) or document number (document_number). | - |
| `page` | integer | Page to be queried >= 1. | - |
| `page_size` | integer | Maximum number of returned records \<\= 100. | - |
### Enumerators bank_slip_status
| Field | Description |
|---|---|
| accepted | Bank slip in queue for registration |
| rejected | Bank slip rejected |
| registered | Bank slip registered (available for payment) |
| payment_notice | Bank slip paid - but without financial settlement |
| notary_office_payment_notice | rejected |
| paid | Bank slip paid - written off with financial settlement. |
| written_off | Bank slip written off without financial settlement. |
### Enumerators protest_status
| Field | Description |
|---|---|
| accepted | Bank slip in queue for registration |
## Response
STATUS 200
Response Body
```json
{
"data": [
{
"amount": 3,
"asset_type": {
"created_at": "2019-02-01T16:44:11",
"enumerator": "invoice",
"translation_path": "bank_slip.AssetType.invoice"
},
"automatic_bankruptcy_protest": true,
"automatic_protest": false,
"automatic_write_off": false,
"bank_slip_file": [],
"bank_slip_key": "96b32f1a-c2bd-41a4-b4b1-a169235be68b",
"bank_slip_status": {
"created_at": "2019-02-01T16:44:07",
"enumerator": "accepted",
"translation_path": "bank_slip.BankSlipStatus.accepted"
},
"bank_teller_instructions": "Não aceitar após vencimento",
"beneficiary_account_branch": "0001",
"beneficiary_account_key": "7cc3b1f7-8015-4073-8471-a3ba57e34975",
"beneficiary_account_number": "67049",
"beneficiary_document_number": "12345678905",
"beneficiary_key": "b91195e3-0cf4-4fed-90cf-7f5bef29c2f0",
"beneficiary_name": "Greg Brown",
"billing_account_key": "7cc3b1f7-8015-4073-8471-a3ba57e34975",
"business_date_expiration": "2020-06-01",
"created_at": "2020-05-15T21:00:25",
"days_before_fine": null,
"days_before_interest": null,
"days_to_bankruptcy_protest": 1,
"days_to_protest": null,
"days_to_write_off": null,
"discount_limit_date": null,
"discount_value": null,
"document_number": "123456/01",
"expenses": [],
"expiration": "2020-06-01",
"fine_percentage": 0.1,
"guarantor_address": null,
"guarantor_city": null,
"guarantor_document": null,
"guarantor_name": null,
"guarantor_person_type": null,
"guarantor_postal_code": "00000000",
"guarantor_state": null,
"historical_our_number": 2,
"institution_registration_date": null,
"interest_daily_value": 0.34,
"lock_origin_type": null,
"nfe_key": null,
"nfe_url": null,
"occurrences": [
{
"created_at": "2020-05-15T21:00:25",
"discount_amount": null,
"discount_limit_date": null,
"iof_amount": null,
"new_bank_slip_status": null,
"new_due_date": "2020-06-01",
"new_protest_status": {
"created_at": "2019-02-01T16:44:08",
"enumerator": "not_protested",
"translation_path": "bank_slip.ProtestStatus.not_protested"
},
"notary_office_number": null,
"notary_office_protocol": null,
"occurrence_expenses": null,
"occurrence_feedback": null,
"occurrence_key": "c3ab3e01-f198-4e7e-9e01-7a8091b8bd72",
"occurrence_reasons": [],
"occurrence_type": {
"created_at": "2019-02-01T16:44:14",
"enumerator": "registration",
"translation_path": "bank_slip.OccurrenceType.registration"
},
"old_bank_slip_status": {
"created_at": "2019-02-01T16:44:07",
"enumerator": "accepted",
"translation_path": "bank_slip.BankSlipStatus.accepted"
},
"old_due_date": null,
"old_protest_status": null,
"paid_amount": null,
"paid_fine_amount": null,
"paid_interest_amount": null,
"payment_bank": null,
"payment_branch": null,
"payment_credit_date": null,
"payment_method": null,
"payment_origin": null,
"protest_confirmation": null,
"protest_expenses": null,
"rebate_amount": null,
"registration_institution_occurrence_date": "2020-05-15",
"registration_institution_occurrence_event": [
{
"cnab_file": {
"cnab_key": "abfc9fba-28fb-4e75-afcb-f4647d7031bc",
"company_code": null,
"created_at": "2020-05-15T21:00:22",
"downloads": [],
"file_size": "None",
"filename": null,
"line_length": null,
"remitter_key": "b91195e3-0cf4-4fed-90cf-7f5bef29c2f0",
"requester_profile_code": null,
"type": {
"created_at": "2019-02-01T16:44:17",
"enumerator": "api_instruction",
"translation_path": "bank_slip.CNABFileType.api_instruction"
},
"url": null,
"version": null
},
"cnab_file_occurrence_order": 1,
"created_at": "2020-05-15T21:00:25",
"new_status": {
"created_at": "2019-02-01T16:44:15",
"enumerator": "waiting_submission",
"translation_path": "bank_slip.RegistrationInstitutionOccurrenceStatus.waiting_submission"
},
"old_status": null
}
],
"registration_institution_occurrence_status": {
"created_at": "2019-02-01T16:44:15",
"enumerator": "waiting_submission",
"translation_path": "bank_slip.RegistrationInstitutionOccurrenceStatus.waiting_submission"
},
"requester_occurrence_event": [
{
"cnab_file": {
"cnab_key": "abfc9fba-28fb-4e75-afcb-f4647d7031bc",
"company_code": null,
"created_at": "2020-05-15T21:00:22",
"downloads": [],
"file_size": "None",
"filename": null,
"line_length": null,
"remitter_key": "b91195e3-0cf4-4fed-90cf-7f5bef29c2f0",
"requester_profile_code": null,
"type": {
"created_at": "2019-02-01T16:44:17",
"enumerator": "api_instruction",
"translation_path": "bank_slip.CNABFileType.api_instruction"
},
"url": null,
"version": null
},
"cnab_file_occurrence_order": 1,
"created_at": "2020-05-15T21:00:25",
"new_status": {
"created_at": "2019-02-01T16:44:16",
"enumerator": "accepted",
"translation_path": "bank_slip.RequesterOccurrenceStatus.accepted"
},
"old_status": null
}
],
"requester_occurrence_status": {
"created_at": "2019-02-01T16:44:16",
"enumerator": "accepted",
"translation_path": "bank_slip.RequesterOccurrenceStatus.accepted"
}
}
],
"our_number": 2,
"paid_amount": null,
"paid_fine_amount": null,
"paid_interest_amount": null,
"participant_control_number": null,
"payer_account_digit": null,
"payer_account_number": null,
"payer_account_type": null,
"payer_address": "Rua Carlos Tampaio, 112",
"payer_bank": null,
"payer_branch_digit": null,
"payer_branch_number": null,
"payer_document": "45508922008",
"payer_name": "John Nobody",
"payer_person_type": {
"created_at": "2019-02-01T16:44:09",
"enumerator": "natural",
"translation_path": "bank_slip.PersonType.natural"
},
"payer_postal_code": "00000000",
"payment_date": null,
"printing_policy": {
"created_at": "2019-02-01T16:44:10",
"enumerator": "no_printing",
"translation_path": "bank_slip.PrintingPolicy.no_printing"
},
"protest_status": {
"created_at": "2019-02-01T16:44:08",
"enumerator": "not_protested",
"translation_path": "bank_slip.ProtestStatus.not_protested"
},
"rebate_amount": null,
"registration_institution": {
"created_at": "2020-03-26T19:36:16",
"enumerator": "qi_scd",
"febraban_code": "329",
"remittance_sequence": 72,
"settlement_resource_account_key": "3e46d266-4fdb-4fd2-b87a-3e3de366afd4"
},
"requester_profile": 1,
"requester_profile_code": "329-01-0001-0067049",
"requester_registration_date": "2020-05-15"
}
],
"pagination": {
"current_page": 1,
"next_page": null,
"rows_per_page": 100,
},
"totals": {
"delayed_bank_slip_amount": 0,
"delayed_bank_slip_number": 0,
"due_bank_slip_amount": 3,
"due_bank_slip_number": 2,
"paid_bank_slip_amount": 0,
"paid_bank_slip_number": 0,
"total_bank_slip_amount": 3,
"total_bank_slip_number": 1,
"written_off_bank_slip_amount": 0,
"written_off_bank_slip_number": 0
}
}
```
STATUS 400
Response Body
```json
{
{"title": "Bad Request", "description": "Invalid request body.", "translation": "Corpo da requisição inválido.", "extra_fields": {}, "code": "LEG000069"}
}
```
:::danger General Observations:
- The maximum page size (page_size) is 100.
- If the number of records returned on the current page is less than page_size, the next_page attribute will be null.
:::
---
# Daily position report in Excel
URL: /en/documentation/boletos/consultar_v1/posicao_diaria_excel
## Request
ENDPOINT /bank_slip/duplicates_balance_excel
METHOD GET
:::caution Attention
The response body of this request will be an Excel file encoded in base64.
:::
### Query params
| Field | Type | Description | Characters |
|---|---|---|---|
| `beneficiary_key` | string | Beneficiary identification key (required if there is no requester_profile_code). | uuid key |
| `requester_profile_code` | string | Wallet code (required if there is no beneficiary_key). | 10 |
| `expiration_date` | date | Maximum expiration date (Format YYYY-MM-DD). | 10 |
## Response
STATUS 200
Response Body
```json
O body de resposta desta request será um arquivo excel encodado em base64.
```
STATUS 400
Response Body
```json
{
"data": "{\"title\": \"Bad Request\", \"description\": \"Invalid request body.\", \"translation\": \"Corpo da requisição inválido.\", \"extra_fields\": {}, \"code\": \"LEG000069\"}"
}
```
---
# Daily position report in JSON
URL: /en/documentation/boletos/consultar_v1/posicao_diaria_json
## Request
ENDPOINT /bank_slip/duplicates_balance
METHOD GET
### Query params
| Field | Type | Description | Characters |
|---|---|---|---|
| `beneficiary_key` | string | Beneficiary identification key (required if there is no requester_profile_code). | 10 |
| `requester_profile_code` | string | Wallet code (required if there is no beneficiary_key). | 10 |
| `expiration_date` | date | Maximum expiration date (Format YYYY-MM-DD). | 10 |
## Response
STATUS 200
Response Body
```json
{
"expire_after_90_days": 0,
"expire_between_31_and_60_days": 0,
"expire_between_61_and_90_days": 0,
"expire_in_30_days": 0,
"expired": 3,
"expired_in_notary_office": 0,
"expired_not_in_notary_office": 0,
"paid": 0,
"paid_after_due_date": 2,
"paid_before_due_date": 0,
"paid_on_due_date": 0,
"to_expire": 0,
"unpaid": 0
}
```
STATUS 400
Response Body
```json
{
"data": "{\"title\": \"Bad Request\", \"description\": \"Invalid request body.\", \"translation\": \"Corpo da requisição inválido.\", \"extra_fields\": {}, \"code\": \"LEG000069\"}"
}
```
---
# Return file reconciliation routine
URL: /en/documentation/boletos/consultar_v1/rotina_de_conciliacao_de_arquivo_retorno
Daily reconciliation of returns occurs for bank slips. To ensure that the day's data is updated,
use the endpoint specified on this page to verify if the return files are available for
consultation. We recommend that polling be done at a frequency no greater than one request every 2 minutes.
## Request
ENDPOINT /bank_slip/cnab_discharge_status
METHOD GET
## Response
STATUS 200
Response Body: Routine completed
```json
{
"discharge_ready": true
}
```
Response Body: Routine pending
```json
{
"discharge_ready": false
}
```
---
# Solicitar 2ª via de boleto
URL: /en/documentation/boletos/consultar_v1/segunda_via_de_boleto
## Request
ENDPOINT /bank_slip/2-way/ BANK_SLIP_KEY
MÉTODO POST
### Path parameters
| Campo | Tipo | Descrição | Caracteres |
|-------------------------|--------|--------------------------------------------------------------|------------|
| `bank_slip_key` | uuidv4 | Chave única de identificação do boleto, no formato uuid v4 | 36 |
## Response
STATUS 200
Response Body
```json
{
"amount": 3,
"asset_type": {
"created_at": "2019-02-01T16:44:11",
"enumerator": "invoice",
"translation_path": "bank_slip.AssetType.invoice"
},
"automatic_bankruptcy_protest": true,
"automatic_protest": false,
"automatic_write_off": false,
"bank_slip_file": [
{
"barcode": "32998827300000003000001010000000000200670490",
"created_at": "2020-05-19T18:46:41",
"digitable_line": "32990001031000000000902006704908882730000000300",
"url": "https://linkparadownload.com/arquivo.pdf"
}
],
"bank_slip_key": "96b32f1a-c2bd-41a4-b4b1-a169235be68b",
"bank_slip_status": {
"created_at": "2019-02-01T16:44:07",
"enumerator": "accepted",
"translation_path": "bank_slip.BankSlipStatus.accepted"
},
"bank_teller_instructions": "Boleto Teste",
"beneficiary_account_branch": "0001",
"beneficiary_account_key": "7cc3b1f7-8015-4073-8471-a3ba57e34975",
"beneficiary_account_number": "67049",
"beneficiary_document_number": "12345678905",
"beneficiary_key": "b91195e3-0cf4-4fed-90cf-7f5bef29c2f0",
"beneficiary_name": "Greg Brown",
"billing_account_key": "7cc3b1f7-8015-4073-8471-a3ba57e34975",
"business_date_expiration": "2020-06-01",
"created_at": "2020-05-15T21:00:25",
"days_before_fine": null,
"days_before_interest": null,
"days_to_bankruptcy_protest": 1,
"days_to_protest": null,
"days_to_write_off": null,
"discount_limit_date": null,
"discount_value": null,
"document_number": "Parcela 1",
"expenses": [],
"expiration": "2020-06-01",
"fine_percentage": 0.1,
"guarantor_address": null,
"guarantor_city": null,
"guarantor_document": null,
"guarantor_name": null,
"guarantor_person_type": null,
"guarantor_postal_code": "00000000",
"guarantor_state": null,
"historical_our_number": 2,
"institution_registration_date": null,
"interest_daily_value": 0.34,
"lock_origin_type": null,
"nfe_key": null,
"nfe_url": null,
"occurrences": [
{
"created_at": "2020-05-15T21:00:25",
"discount_amount": null,
"discount_limit_date": null,
"iof_amount": null,
"new_bank_slip_status": null,
"new_due_date": "2020-06-01",
"new_protest_status": {
"created_at": "2019-02-01T16:44:08",
"enumerator": "not_protested",
"translation_path": "bank_slip.ProtestStatus.not_protested"
},
"notary_office_number": null,
"notary_office_protocol": null,
"occurrence_expenses": null,
"occurrence_feedback": null,
"occurrence_key": "c3ab3e01-f198-4e7e-9e01-7a8091b8bd72",
"occurrence_reasons": [],
"occurrence_type": {
"created_at": "2019-02-01T16:44:14",
"enumerator": "registration",
"translation_path": "bank_slip.OccurrenceType.registration"
},
"old_bank_slip_status": {
"created_at": "2019-02-01T16:44:07",
"enumerator": "accepted",
"translation_path": "bank_slip.BankSlipStatus.accepted"
},
"old_due_date": null,
"old_protest_status": null,
"paid_amount": null,
"paid_fine_amount": null,
"paid_interest_amount": null,
"payment_bank": null,
"payment_branch": null,
"payment_credit_date": null,
"payment_method": null,
"payment_origin": null,
"protest_confirmation": null,
"protest_expenses": null,
"rebate_amount": null,
"registration_institution_occurrence_date": "2020-05-15",
"registration_institution_occurrence_event": [
{
"cnab_file": {
"cnab_key": "abfc9fba-28fb-4e75-afcb-f4647d7031bc",
"company_code": null,
"created_at": "2020-05-15T21:00:22",
"downloads": [],
"file_size": "None",
"filename": null,
"line_length": null,
"remitter_key": "b91195e3-0cf4-4fed-90cf-7f5bef29c2f0",
"requester_profile_code": null,
"type": {
"created_at": "2019-02-01T16:44:17",
"enumerator": "api_instruction",
"translation_path": "bank_slip.CNABFileType.api_instruction"
},
"url": null,
"version": null
},
"cnab_file_occurrence_order": 1,
"created_at": "2020-05-15T21:00:25",
"new_status": {
"created_at": "2019-02-01T16:44:15",
"enumerator": "waiting_submission",
"translation_path": "bank_slip.RegistrationInstitutionOccurrenceStatus.waiting_submission"
},
"old_status": null
}
],
"registration_institution_occurrence_status": {
"created_at": "2019-02-01T16:44:15",
"enumerator": "waiting_submission",
"translation_path": "bank_slip.RegistrationInstitutionOccurrenceStatus.waiting_submission"
},
"requester_occurrence_event": [
{
"cnab_file": {
"cnab_key": "abfc9fba-28fb-4e75-afcb-f4647d7031bc",
"company_code": null,
"created_at": "2020-05-15T21:00:22",
"downloads": [],
"file_size": "None",
"filename": null,
"line_length": null,
"remitter_key": "b91195e3-0cf4-4fed-90cf-7f5bef29c2f0",
"requester_profile_code": null,
"type": {
"created_at": "2019-02-01T16:44:17",
"enumerator": "api_instruction",
"translation_path": "bank_slip.CNABFileType.api_instruction"
},
"url": null,
"version": null
},
"cnab_file_occurrence_order": 1,
"created_at": "2020-05-15T21:00:25",
"new_status": {
"created_at": "2019-02-01T16:44:16",
"enumerator": "accepted",
"translation_path": "bank_slip.RequesterOccurrenceStatus.accepted"
},
"old_status": null
}
],
"requester_occurrence_status": {
"created_at": "2019-02-01T16:44:16",
"enumerator": "accepted",
"translation_path": "bank_slip.RequesterOccurrenceStatus.accepted"
}
}
],
"our_number": 2,
"paid_amount": null,
"paid_fine_amount": null,
"paid_interest_amount": null,
"participant_control_number": null,
"payer_account_digit": null,
"payer_account_number": null,
"payer_account_type": null,
"payer_address": "Rua Carlos tampaio, 204",
"payer_bank": null,
"payer_branch_digit": null,
"payer_branch_number": null,
"payer_document": "41651732825",
"payer_name": "Beatriz Couto",
"payer_person_type": {
"created_at": "2019-02-01T16:44:09",
"enumerator": "natural",
"translation_path": "bank_slip.PersonType.natural"
},
"payer_postal_code": "00000000",
"payment_date": null,
"printing_policy": {
"created_at": "2019-02-01T16:44:10",
"enumerator": "no_printing",
"translation_path": "bank_slip.PrintingPolicy.no_printing"
},
"protest_status": {
"created_at": "2019-02-01T16:44:08",
"enumerator": "not_protested",
"translation_path": "bank_slip.ProtestStatus.not_protested"
},
"rebate_amount": null,
"registration_institution": {
"created_at": "2020-03-26T19:36:16",
"enumerator": "qi_scd",
"febraban_code": "329",
"remittance_sequence": 72,
"settlement_resource_account_key": "3e46d266-4fdb-4fd2-b87a-3e3de366afd4"
},
"requester_profile": 1,
"requester_profile_code": "329-01-0001-0067049",
"requester_registration_date": "2020-05-15"
}{
"amount": 3,
"asset_type": {
"created_at": "2019-02-01T16:44:11",
"enumerator": "invoice",
"translation_path": "bank_slip.AssetType.invoice"
},
"automatic_bankruptcy_protest": true,
"automatic_protest": false,
"automatic_write_off": false,
"bank_slip_file": [
{
"barcode": "32998827300000003000001010000000000200670490",
"created_at": "2020-05-19T18:46:41",
"digitable_line": "32990001031000000000902006704908882730000000300",
"url": "https://linkparadownload.com/arquivo.pdf"
}
],
"bank_slip_key": "96b32f1a-c2bd-41a4-b4b1-a169235be68b",
"bank_slip_status": {
"created_at": "2019-02-01T16:44:07",
"enumerator": "accepted",
"translation_path": "bank_slip.BankSlipStatus.accepted"
},
"bank_teller_instructions": "Boleto Teste",
"beneficiary_account_branch": "0001",
"beneficiary_account_key": "7cc3b1f7-8015-4073-8471-a3ba57e34975",
"beneficiary_account_number": "67049",
"beneficiary_document_number": "12345678905",
"beneficiary_key": "b91195e3-0cf4-4fed-90cf-7f5bef29c2f0",
"beneficiary_name": "Greg Brown",
"billing_account_key": "7cc3b1f7-8015-4073-8471-a3ba57e34975",
"business_date_expiration": "2020-06-01",
"created_at": "2020-05-15T21:00:25",
"days_before_fine": null,
"days_before_interest": null,
"days_to_bankruptcy_protest": 1,
"days_to_protest": null,
"days_to_write_off": null,
"discount_limit_date": null,
"discount_value": null,
"document_number": "Parcela 1",
"expenses": [],
"expiration": "2020-06-01",
"fine_percentage": 0.1,
"guarantor_address": null,
"guarantor_city": null,
"guarantor_document": null,
"guarantor_name": null,
"guarantor_person_type": null,
"guarantor_postal_code": "00000000",
"guarantor_state": null,
"historical_our_number": 2,
"institution_registration_date": null,
"interest_daily_value": 0.34,
"lock_origin_type": null,
"nfe_key": null,
"nfe_url": null,
"occurrences": [
{
"created_at": "2020-05-15T21:00:25",
"discount_amount": null,
"discount_limit_date": null,
"iof_amount": null,
"new_bank_slip_status": null,
"new_due_date": "2020-06-01",
"new_protest_status": {
"created_at": "2019-02-01T16:44:08",
"enumerator": "not_protested",
"translation_path": "bank_slip.ProtestStatus.not_protested"
},
"notary_office_number": null,
"notary_office_protocol": null,
"occurrence_expenses": null,
"occurrence_feedback": null,
"occurrence_key": "c3ab3e01-f198-4e7e-9e01-7a8091b8bd72",
"occurrence_reasons": [],
"occurrence_type": {
"created_at": "2019-02-01T16:44:14",
"enumerator": "registration",
"translation_path": "bank_slip.OccurrenceType.registration"
},
"old_bank_slip_status": {
"created_at": "2019-02-01T16:44:07",
"enumerator": "accepted",
"translation_path": "bank_slip.BankSlipStatus.accepted"
},
"old_due_date": null,
"old_protest_status": null,
"paid_amount": null,
"paid_fine_amount": null,
"paid_interest_amount": null,
"payment_bank": null,
"payment_branch": null,
"payment_credit_date": null,
"payment_method": null,
"payment_origin": null,
"protest_confirmation": null,
"protest_expenses": null,
"rebate_amount": null,
"registration_institution_occurrence_date": "2020-05-15",
"registration_institution_occurrence_event": [
{
"cnab_file": {
"cnab_key": "abfc9fba-28fb-4e75-afcb-f4647d7031bc",
"company_code": null,
"created_at": "2020-05-15T21:00:22",
"downloads": [],
"file_size": "None",
"filename": null,
"line_length": null,
"remitter_key": "b91195e3-0cf4-4fed-90cf-7f5bef29c2f0",
"requester_profile_code": null,
"type": {
"created_at": "2019-02-01T16:44:17",
"enumerator": "api_instruction",
"translation_path": "bank_slip.CNABFileType.api_instruction"
},
"url": null,
"version": null
},
"cnab_file_occurrence_order": 1,
"created_at": "2020-05-15T21:00:25",
"new_status": {
"created_at": "2019-02-01T16:44:15",
"enumerator": "waiting_submission",
"translation_path": "bank_slip.RegistrationInstitutionOccurrenceStatus.waiting_submission"
},
"old_status": null
}
],
"registration_institution_occurrence_status": {
"created_at": "2019-02-01T16:44:15",
"enumerator": "waiting_submission",
"translation_path": "bank_slip.RegistrationInstitutionOccurrenceStatus.waiting_submission"
},
"requester_occurrence_event": [
{
"cnab_file": {
"cnab_key": "abfc9fba-28fb-4e75-afcb-f4647d7031bc",
"company_code": null,
"created_at": "2020-05-15T21:00:22",
"downloads": [],
"file_size": "None",
"filename": null,
"line_length": null,
"remitter_key": "b91195e3-0cf4-4fed-90cf-7f5bef29c2f0",
"requester_profile_code": null,
"type": {
"created_at": "2019-02-01T16:44:17",
"enumerator": "api_instruction",
"translation_path": "bank_slip.CNABFileType.api_instruction"
},
"url": null,
"version": null
},
"cnab_file_occurrence_order": 1,
"created_at": "2020-05-15T21:00:25",
"new_status": {
"created_at": "2019-02-01T16:44:16",
"enumerator": "accepted",
"translation_path": "bank_slip.RequesterOccurrenceStatus.accepted"
},
"old_status": null
}
],
"requester_occurrence_status": {
"created_at": "2019-02-01T16:44:16",
"enumerator": "accepted",
"translation_path": "bank_slip.RequesterOccurrenceStatus.accepted"
}
}
],
"our_number": 2,
"paid_amount": null,
"paid_fine_amount": null,
"paid_interest_amount": null,
"participant_control_number": null,
"payer_account_digit": null,
"payer_account_number": null,
"payer_account_type": null,
"payer_address": "Rua Carlos tampaio, 204",
"payer_bank": null,
"payer_branch_digit": null,
"payer_branch_number": null,
"payer_document": "41651732825",
"payer_name": "Beatriz Couto",
"payer_person_type": {
"created_at": "2019-02-01T16:44:09",
"enumerator": "natural",
"translation_path": "bank_slip.PersonType.natural"
},
"payer_postal_code": "00000000",
"payment_date": null,
"printing_policy": {
"created_at": "2019-02-01T16:44:10",
"enumerator": "no_printing",
"translation_path": "bank_slip.PrintingPolicy.no_printing"
},
"protest_status": {
"created_at": "2019-02-01T16:44:08",
"enumerator": "not_protested",
"translation_path": "bank_slip.ProtestStatus.not_protested"
},
"rebate_amount": null,
"registration_institution": {
"created_at": "2020-03-26T19:36:16",
"enumerator": "qi_scd",
"febraban_code": "329",
"remittance_sequence": 72,
"settlement_resource_account_key": "3e46d266-4fdb-4fd2-b87a-3e3de366afd4"
},
"requester_profile": 1,
"requester_profile_code": "329-01-0001-0067049",
"requester_registration_date": "2020-05-15"
}{
"amount": 3,
"asset_type": {
"created_at": "2019-02-01T16:44:11",
"enumerator": "invoice",
"translation_path": "bank_slip.AssetType.invoice"
},
"automatic_bankruptcy_protest": true,
"automatic_protest": false,
"automatic_write_off": false,
"bank_slip_file": [
{
"barcode": "32998827300000003000001010000000000200670490",
"created_at": "2020-05-19T18:46:41",
"digitable_line": "32990001031000000000902006704908882730000000300",
"url": "https://linkparadownload.com/arquivo.pdf"
}
],
"bank_slip_key": "96b32f1a-c2bd-41a4-b4b1-a169235be68b",
"bank_slip_status": {
"created_at": "2019-02-01T16:44:07",
"enumerator": "accepted",
"translation_path": "bank_slip.BankSlipStatus.accepted"
},
"bank_teller_instructions": "Boleto Teste",
"beneficiary_account_branch": "0001",
"beneficiary_account_key": "7cc3b1f7-8015-4073-8471-a3ba57e34975",
"beneficiary_account_number": "67049",
"beneficiary_document_number": "12345678905",
"beneficiary_key": "b91195e3-0cf4-4fed-90cf-7f5bef29c2f0",
"beneficiary_name": "Greg Brown",
"billing_account_key": "7cc3b1f7-8015-4073-8471-a3ba57e34975",
"business_date_expiration": "2020-06-01",
"created_at": "2020-05-15T21:00:25",
"days_before_fine": null,
"days_before_interest": null,
"days_to_bankruptcy_protest": 1,
"days_to_protest": null,
"days_to_write_off": null,
"discount_limit_date": null,
"discount_value": null,
"document_number": "Parcela 1",
"expenses": [],
"expiration": "2020-06-01",
"fine_percentage": 0.1,
"guarantor_address": null,
"guarantor_city": null,
"guarantor_document": null,
"guarantor_name": null,
"guarantor_person_type": null,
"guarantor_postal_code": "00000000",
"guarantor_state": null,
"historical_our_number": 2,
"institution_registration_date": null,
"interest_daily_value": 0.34,
"lock_origin_type": null,
"nfe_key": null,
"nfe_url": null,
"occurrences": [
{
"created_at": "2020-05-15T21:00:25",
"discount_amount": null,
"discount_limit_date": null,
"iof_amount": null,
"new_bank_slip_status": null,
"new_due_date": "2020-06-01",
"new_protest_status": {
"created_at": "2019-02-01T16:44:08",
"enumerator": "not_protested",
"translation_path": "bank_slip.ProtestStatus.not_protested"
},
"notary_office_number": null,
"notary_office_protocol": null,
"occurrence_expenses": null,
"occurrence_feedback": null,
"occurrence_key": "c3ab3e01-f198-4e7e-9e01-7a8091b8bd72",
"occurrence_reasons": [],
"occurrence_type": {
"created_at": "2019-02-01T16:44:14",
"enumerator": "registration",
"translation_path": "bank_slip.OccurrenceType.registration"
},
"old_bank_slip_status": {
"created_at": "2019-02-01T16:44:07",
"enumerator": "accepted",
"translation_path": "bank_slip.BankSlipStatus.accepted"
},
"old_due_date": null,
"old_protest_status": null,
"paid_amount": null,
"paid_fine_amount": null,
"paid_interest_amount": null,
"payment_bank": null,
"payment_branch": null,
"payment_credit_date": null,
"payment_method": null,
"payment_origin": null,
"protest_confirmation": null,
"protest_expenses": null,
"rebate_amount": null,
"registration_institution_occurrence_date": "2020-05-15",
"registration_institution_occurrence_event": [
{
"cnab_file": {
"cnab_key": "abfc9fba-28fb-4e75-afcb-f4647d7031bc",
"company_code": null,
"created_at": "2020-05-15T21:00:22",
"downloads": [],
"file_size": "None",
"filename": null,
"line_length": null,
"remitter_key": "b91195e3-0cf4-4fed-90cf-7f5bef29c2f0",
"requester_profile_code": null,
"type": {
"created_at": "2019-02-01T16:44:17",
"enumerator": "api_instruction",
"translation_path": "bank_slip.CNABFileType.api_instruction"
},
"url": null,
"version": null
},
"cnab_file_occurrence_order": 1,
"created_at": "2020-05-15T21:00:25",
"new_status": {
"created_at": "2019-02-01T16:44:15",
"enumerator": "waiting_submission",
"translation_path": "bank_slip.RegistrationInstitutionOccurrenceStatus.waiting_submission"
},
"old_status": null
}
],
"registration_institution_occurrence_status": {
"created_at": "2019-02-01T16:44:15",
"enumerator": "waiting_submission",
"translation_path": "bank_slip.RegistrationInstitutionOccurrenceStatus.waiting_submission"
},
"requester_occurrence_event": [
{
"cnab_file": {
"cnab_key": "abfc9fba-28fb-4e75-afcb-f4647d7031bc",
"company_code": null,
"created_at": "2020-05-15T21:00:22",
"downloads": [],
"file_size": "None",
"filename": null,
"line_length": null,
"remitter_key": "b91195e3-0cf4-4fed-90cf-7f5bef29c2f0",
"requester_profile_code": null,
"type": {
"created_at": "2019-02-01T16:44:17",
"enumerator": "api_instruction",
"translation_path": "bank_slip.CNABFileType.api_instruction"
},
"url": null,
"version": null
},
"cnab_file_occurrence_order": 1,
"created_at": "2020-05-15T21:00:25",
"new_status": {
"created_at": "2019-02-01T16:44:16",
"enumerator": "accepted",
"translation_path": "bank_slip.RequesterOccurrenceStatus.accepted"
},
"old_status": null
}
],
"requester_occurrence_status": {
"created_at": "2019-02-01T16:44:16",
"enumerator": "accepted",
"translation_path": "bank_slip.RequesterOccurrenceStatus.accepted"
}
}
],
"our_number": 2,
"paid_amount": null,
"paid_fine_amount": null,
"paid_interest_amount": null,
"participant_control_number": null,
"payer_account_digit": null,
"payer_account_number": null,
"payer_account_type": null,
"payer_address": "Rua Carlos tampaio, 204",
"payer_bank": null,
"payer_branch_digit": null,
"payer_branch_number": null,
"payer_document": "41651732825",
"payer_name": "Beatriz Couto",
"payer_person_type": {
"created_at": "2019-02-01T16:44:09",
"enumerator": "natural",
"translation_path": "bank_slip.PersonType.natural"
},
"payer_postal_code": "00000000",
"payment_date": null,
"printing_policy": {
"created_at": "2019-02-01T16:44:10",
"enumerator": "no_printing",
"translation_path": "bank_slip.PrintingPolicy.no_printing"
},
"protest_status": {
"created_at": "2019-02-01T16:44:08",
"enumerator": "not_protested",
"translation_path": "bank_slip.ProtestStatus.not_protested"
},
"rebate_amount": null,
"registration_institution": {
"created_at": "2020-03-26T19:36:16",
"enumerator": "qi_scd",
"febraban_code": "329",
"remittance_sequence": 72,
"settlement_resource_account_key": "3e46d266-4fdb-4fd2-b87a-3e3de366afd4"
},
"requester_profile": 1,
"requester_profile_code": "329-01-0001-0067049",
"requester_registration_date": "2020-05-15"
}{
"amount": 3,
"asset_type": {
"created_at": "2019-02-01T16:44:11",
"enumerator": "invoice",
"translation_path": "bank_slip.AssetType.invoice"
},
"automatic_bankruptcy_protest": true,
"automatic_protest": false,
"automatic_write_off": false,
"bank_slip_file": [
{
"barcode": "32998827300000003000001010000000000200670490",
"created_at": "2020-05-19T18:46:41",
"digitable_line": "32990001031000000000902006704908882730000000300",
"url": "https://linkparadownload.com/arquivo.pdf"
}
],
"bank_slip_key": "96b32f1a-c2bd-41a4-b4b1-a169235be68b",
"bank_slip_status": {
"created_at": "2019-02-01T16:44:07",
"enumerator": "accepted",
"translation_path": "bank_slip.BankSlipStatus.accepted"
},
"bank_teller_instructions": "Boleto Teste",
"beneficiary_account_branch": "0001",
"beneficiary_account_key": "7cc3b1f7-8015-4073-8471-a3ba57e34975",
"beneficiary_account_number": "67049",
"beneficiary_document_number": "12345678905",
"beneficiary_key": "b91195e3-0cf4-4fed-90cf-7f5bef29c2f0",
"beneficiary_name": "Greg Brown",
"billing_account_key": "7cc3b1f7-8015-4073-8471-a3ba57e34975",
"business_date_expiration": "2020-06-01",
"created_at": "2020-05-15T21:00:25",
"days_before_fine": null,
"days_before_interest": null,
"days_to_bankruptcy_protest": 1,
"days_to_protest": null,
"days_to_write_off": null,
"discount_limit_date": null,
"discount_value": null,
"document_number": "Parcela 1",
"expenses": [],
"expiration": "2020-06-01",
"fine_percentage": 0.1,
"guarantor_address": null,
"guarantor_city": null,
"guarantor_document": null,
"guarantor_name": null,
"guarantor_person_type": null,
"guarantor_postal_code": "00000000",
"guarantor_state": null,
"historical_our_number": 2,
"institution_registration_date": null,
"interest_daily_value": 0.34,
"lock_origin_type": null,
"nfe_key": null,
"nfe_url": null,
"occurrences": [
{
"created_at": "2020-05-15T21:00:25",
"discount_amount": null,
"discount_limit_date": null,
"iof_amount": null,
"new_bank_slip_status": null,
"new_due_date": "2020-06-01",
"new_protest_status": {
"created_at": "2019-02-01T16:44:08",
"enumerator": "not_protested",
"translation_path": "bank_slip.ProtestStatus.not_protested"
},
"notary_office_number": null,
"notary_office_protocol": null,
"occurrence_expenses": null,
"occurrence_feedback": null,
"occurrence_key": "c3ab3e01-f198-4e7e-9e01-7a8091b8bd72",
"occurrence_reasons": [],
"occurrence_type": {
"created_at": "2019-02-01T16:44:14",
"enumerator": "registration",
"translation_path": "bank_slip.OccurrenceType.registration"
},
"old_bank_slip_status": {
"created_at": "2019-02-01T16:44:07",
"enumerator": "accepted",
"translation_path": "bank_slip.BankSlipStatus.accepted"
},
"old_due_date": null,
"old_protest_status": null,
"paid_amount": null,
"paid_fine_amount": null,
"paid_interest_amount": null,
"payment_bank": null,
"payment_branch": null,
"payment_credit_date": null,
"payment_method": null,
"payment_origin": null,
"protest_confirmation": null,
"protest_expenses": null,
"rebate_amount": null,
"registration_institution_occurrence_date": "2020-05-15",
"registration_institution_occurrence_event": [
{
"cnab_file": {
"cnab_key": "abfc9fba-28fb-4e75-afcb-f4647d7031bc",
"company_code": null,
"created_at": "2020-05-15T21:00:22",
"downloads": [],
"file_size": "None",
"filename": null,
"line_length": null,
"remitter_key": "b91195e3-0cf4-4fed-90cf-7f5bef29c2f0",
"requester_profile_code": null,
"type": {
"created_at": "2019-02-01T16:44:17",
"enumerator": "api_instruction",
"translation_path": "bank_slip.CNABFileType.api_instruction"
},
"url": null,
"version": null
},
"cnab_file_occurrence_order": 1,
"created_at": "2020-05-15T21:00:25",
"new_status": {
"created_at": "2019-02-01T16:44:15",
"enumerator": "waiting_submission",
"translation_path": "bank_slip.RegistrationInstitutionOccurrenceStatus.waiting_submission"
},
"old_status": null
}
],
"registration_institution_occurrence_status": {
"created_at": "2019-02-01T16:44:15",
"enumerator": "waiting_submission",
"translation_path": "bank_slip.RegistrationInstitutionOccurrenceStatus.waiting_submission"
},
"requester_occurrence_event": [
{
"cnab_file": {
"cnab_key": "abfc9fba-28fb-4e75-afcb-f4647d7031bc",
"company_code": null,
"created_at": "2020-05-15T21:00:22",
"downloads": [],
"file_size": "None",
"filename": null,
"line_length": null,
"remitter_key": "b91195e3-0cf4-4fed-90cf-7f5bef29c2f0",
"requester_profile_code": null,
"type": {
"created_at": "2019-02-01T16:44:17",
"enumerator": "api_instruction",
"translation_path": "bank_slip.CNABFileType.api_instruction"
},
"url": null,
"version": null
},
"cnab_file_occurrence_order": 1,
"created_at": "2020-05-15T21:00:25",
"new_status": {
"created_at": "2019-02-01T16:44:16",
"enumerator": "accepted",
"translation_path": "bank_slip.RequesterOccurrenceStatus.accepted"
},
"old_status": null
}
],
"requester_occurrence_status": {
"created_at": "2019-02-01T16:44:16",
"enumerator": "accepted",
"translation_path": "bank_slip.RequesterOccurrenceStatus.accepted"
}
}
],
"our_number": 2,
"paid_amount": null,
"paid_fine_amount": null,
"paid_interest_amount": null,
"participant_control_number": null,
"payer_account_digit": null,
"payer_account_number": null,
"payer_account_type": null,
"payer_address": "Rua Carlos tampaio, 204",
"payer_bank": null,
"payer_branch_digit": null,
"payer_branch_number": null,
"payer_document": "41651732825",
"payer_name": "Beatriz Couto",
"payer_person_type": {
"created_at": "2019-02-01T16:44:09",
"enumerator": "natural",
"translation_path": "bank_slip.PersonType.natural"
},
"payer_postal_code": "00000000",
"payment_date": null,
"printing_policy": {
"created_at": "2019-02-01T16:44:10",
"enumerator": "no_printing",
"translation_path": "bank_slip.PrintingPolicy.no_printing"
},
"protest_status": {
"created_at": "2019-02-01T16:44:08",
"enumerator": "not_protested",
"translation_path": "bank_slip.ProtestStatus.not_protested"
},
"rebate_amount": null,
"registration_institution": {
"created_at": "2020-03-26T19:36:16",
"enumerator": "qi_scd",
"febraban_code": "329",
"remittance_sequence": 72,
"settlement_resource_account_key": "3e46d266-4fdb-4fd2-b87a-3e3de366afd4"
},
"requester_profile": 1,
"requester_profile_code": "329-01-0001-0067049",
"requester_registration_date": "2020-05-15"
}{
"amount": 3,
"asset_type": {
"created_at": "2019-02-01T16:44:11",
"enumerator": "invoice",
"translation_path": "bank_slip.AssetType.invoice"
},
"automatic_bankruptcy_protest": true,
"automatic_protest": false,
"automatic_write_off": false,
"bank_slip_file": [
{
"barcode": "32998827300000003000001010000000000200670490",
"created_at": "2020-05-19T18:46:41",
"digitable_line": "32990001031000000000902006704908882730000000300",
"url": "https://linkparadownload.com/arquivo.pdf"
}
],
"bank_slip_key": "96b32f1a-c2bd-41a4-b4b1-a169235be68b",
"bank_slip_status": {
"created_at": "2019-02-01T16:44:07",
"enumerator": "accepted",
"translation_path": "bank_slip.BankSlipStatus.accepted"
},
"bank_teller_instructions": "Boleto Teste",
"beneficiary_account_branch": "0001",
"beneficiary_account_key": "7cc3b1f7-8015-4073-8471-a3ba57e34975",
"beneficiary_account_number": "67049",
"beneficiary_document_number": "12345678905",
"beneficiary_key": "b91195e3-0cf4-4fed-90cf-7f5bef29c2f0",
"beneficiary_name": "Greg Brown",
"billing_account_key": "7cc3b1f7-8015-4073-8471-a3ba57e34975",
"business_date_expiration": "2020-06-01",
"created_at": "2020-05-15T21:00:25",
"days_before_fine": null,
"days_before_interest": null,
"days_to_bankruptcy_protest": 1,
"days_to_protest": null,
"days_to_write_off": null,
"discount_limit_date": null,
"discount_value": null,
"document_number": "Parcela 1",
"expenses": [],
"expiration": "2020-06-01",
"fine_percentage": 0.1,
"guarantor_address": null,
"guarantor_city": null,
"guarantor_document": null,
"guarantor_name": null,
"guarantor_person_type": null,
"guarantor_postal_code": "00000000",
"guarantor_state": null,
"historical_our_number": 2,
"institution_registration_date": null,
"interest_daily_value": 0.34,
"lock_origin_type": null,
"nfe_key": null,
"nfe_url": null,
"occurrences": [
{
"created_at": "2020-05-15T21:00:25",
"discount_amount": null,
"discount_limit_date": null,
"iof_amount": null,
"new_bank_slip_status": null,
"new_due_date": "2020-06-01",
"new_protest_status": {
"created_at": "2019-02-01T16:44:08",
"enumerator": "not_protested",
"translation_path": "bank_slip.ProtestStatus.not_protested"
},
"notary_office_number": null,
"notary_office_protocol": null,
"occurrence_expenses": null,
"occurrence_feedback": null,
"occurrence_key": "c3ab3e01-f198-4e7e-9e01-7a8091b8bd72",
"occurrence_reasons": [],
"occurrence_type": {
"created_at": "2019-02-01T16:44:14",
"enumerator": "registration",
"translation_path": "bank_slip.OccurrenceType.registration"
},
"old_bank_slip_status": {
"created_at": "2019-02-01T16:44:07",
"enumerator": "accepted",
"translation_path": "bank_slip.BankSlipStatus.accepted"
},
"old_due_date": null,
"old_protest_status": null,
"paid_amount": null,
"paid_fine_amount": null,
"paid_interest_amount": null,
"payment_bank": null,
"payment_branch": null,
"payment_credit_date": null,
"payment_method": null,
"payment_origin": null,
"protest_confirmation": null,
"protest_expenses": null,
"rebate_amount": null,
"registration_institution_occurrence_date": "2020-05-15",
"registration_institution_occurrence_event": [
{
"cnab_file": {
"cnab_key": "abfc9fba-28fb-4e75-afcb-f4647d7031bc",
"company_code": null,
"created_at": "2020-05-15T21:00:22",
"downloads": [],
"file_size": "None",
"filename": null,
"line_length": null,
"remitter_key": "b91195e3-0cf4-4fed-90cf-7f5bef29c2f0",
"requester_profile_code": null,
"type": {
"created_at": "2019-02-01T16:44:17",
"enumerator": "api_instruction",
"translation_path": "bank_slip.CNABFileType.api_instruction"
},
"url": null,
"version": null
},
"cnab_file_occurrence_order": 1,
"created_at": "2020-05-15T21:00:25",
"new_status": {
"created_at": "2019-02-01T16:44:15",
"enumerator": "waiting_submission",
"translation_path": "bank_slip.RegistrationInstitutionOccurrenceStatus.waiting_submission"
},
"old_status": null
}
],
"registration_institution_occurrence_status": {
"created_at": "2019-02-01T16:44:15",
"enumerator": "waiting_submission",
"translation_path": "bank_slip.RegistrationInstitutionOccurrenceStatus.waiting_submission"
},
"requester_occurrence_event": [
{
"cnab_file": {
"cnab_key": "abfc9fba-28fb-4e75-afcb-f4647d7031bc",
"company_code": null,
"created_at": "2020-05-15T21:00:22",
"downloads": [],
"file_size": "None",
"filename": null,
"line_length": null,
"remitter_key": "b91195e3-0cf4-4fed-90cf-7f5bef29c2f0",
"requester_profile_code": null,
"type": {
"created_at": "2019-02-01T16:44:17",
"enumerator": "api_instruction",
"translation_path": "bank_slip.CNABFileType.api_instruction"
},
"url": null,
"version": null
},
"cnab_file_occurrence_order": 1,
"created_at": "2020-05-15T21:00:25",
"new_status": {
"created_at": "2019-02-01T16:44:16",
"enumerator": "accepted",
"translation_path": "bank_slip.RequesterOccurrenceStatus.accepted"
},
"old_status": null
}
],
"requester_occurrence_status": {
"created_at": "2019-02-01T16:44:16",
"enumerator": "accepted",
"translation_path": "bank_slip.RequesterOccurrenceStatus.accepted"
}
}
],
"our_number": 2,
"paid_amount": null,
"paid_fine_amount": null,
"paid_interest_amount": null,
"participant_control_number": null,
"payer_account_digit": null,
"payer_account_number": null,
"payer_account_type": null,
"payer_address": "Rua Carlos tampaio, 204",
"payer_bank": null,
"payer_branch_digit": null,
"payer_branch_number": null,
"payer_document": "41651732825",
"payer_name": "Beatriz Couto",
"payer_person_type": {
"created_at": "2019-02-01T16:44:09",
"enumerator": "natural",
"translation_path": "bank_slip.PersonType.natural"
},
"payer_postal_code": "00000000",
"payment_date": null,
"printing_policy": {
"created_at": "2019-02-01T16:44:10",
"enumerator": "no_printing",
"translation_path": "bank_slip.PrintingPolicy.no_printing"
},
"protest_status": {
"created_at": "2019-02-01T16:44:08",
"enumerator": "not_protested",
"translation_path": "bank_slip.ProtestStatus.not_protested"
},
"rebate_amount": null,
"registration_institution": {
"created_at": "2020-03-26T19:36:16",
"enumerator": "qi_scd",
"febraban_code": "329",
"remittance_sequence": 72,
"settlement_resource_account_key": "3e46d266-4fdb-4fd2-b87a-3e3de366afd4"
},
"requester_profile": 1,
"requester_profile_code": "329-01-0001-0067049",
"requester_registration_date": "2020-05-15"
}{
"amount": 3,
"asset_type": {
"created_at": "2019-02-01T16:44:11",
"enumerator": "invoice",
"translation_path": "bank_slip.AssetType.invoice"
},
"automatic_bankruptcy_protest": true,
"automatic_protest": false,
"automatic_write_off": false,
"bank_slip_file": [
{
"barcode": "32998827300000003000001010000000000200670490",
"created_at": "2020-05-19T18:46:41",
"digitable_line": "32990001031000000000902006704908882730000000300",
"url": "https://linkparadownload.com/arquivo.pdf"
}
],
"bank_slip_key": "96b32f1a-c2bd-41a4-b4b1-a169235be68b",
"bank_slip_status": {
"created_at": "2019-02-01T16:44:07",
"enumerator": "accepted",
"translation_path": "bank_slip.BankSlipStatus.accepted"
},
"bank_teller_instructions": "Boleto Teste",
"beneficiary_account_branch": "0001",
"beneficiary_account_key": "7cc3b1f7-8015-4073-8471-a3ba57e34975",
"beneficiary_account_number": "67049",
"beneficiary_document_number": "12345678905",
"beneficiary_key": "b91195e3-0cf4-4fed-90cf-7f5bef29c2f0",
"beneficiary_name": "Greg Brown",
"billing_account_key": "7cc3b1f7-8015-4073-8471-a3ba57e34975",
"business_date_expiration": "2020-06-01",
"created_at": "2020-05-15T21:00:25",
"days_before_fine": null,
"days_before_interest": null,
"days_to_bankruptcy_protest": 1,
"days_to_protest": null,
"days_to_write_off": null,
"discount_limit_date": null,
"discount_value": null,
"document_number": "Parcela 1",
"expenses": [],
"expiration": "2020-06-01",
"fine_percentage": 0.1,
"guarantor_address": null,
"guarantor_city": null,
"guarantor_document": null,
"guarantor_name": null,
"guarantor_person_type": null,
"guarantor_postal_code": "00000000",
"guarantor_state": null,
"historical_our_number": 2,
"institution_registration_date": null,
"interest_daily_value": 0.34,
"lock_origin_type": null,
"nfe_key": null,
"nfe_url": null,
"occurrences": [
{
"created_at": "2020-05-15T21:00:25",
"discount_amount": null,
"discount_limit_date": null,
"iof_amount": null,
"new_bank_slip_status": null,
"new_due_date": "2020-06-01",
"new_protest_status": {
"created_at": "2019-02-01T16:44:08",
"enumerator": "not_protested",
"translation_path": "bank_slip.ProtestStatus.not_protested"
},
"notary_office_number": null,
"notary_office_protocol": null,
"occurrence_expenses": null,
"occurrence_feedback": null,
"occurrence_key": "c3ab3e01-f198-4e7e-9e01-7a8091b8bd72",
"occurrence_reasons": [],
"occurrence_type": {
"created_at": "2019-02-01T16:44:14",
"enumerator": "registration",
"translation_path": "bank_slip.OccurrenceType.registration"
},
"old_bank_slip_status": {
"created_at": "2019-02-01T16:44:07",
"enumerator": "accepted",
"translation_path": "bank_slip.BankSlipStatus.accepted"
},
"old_due_date": null,
"old_protest_status": null,
"paid_amount": null,
"paid_fine_amount": null,
"paid_interest_amount": null,
"payment_bank": null,
"payment_branch": null,
"payment_credit_date": null,
"payment_method": null,
"payment_origin": null,
"protest_confirmation": null,
"protest_expenses": null,
"rebate_amount": null,
"registration_institution_occurrence_date": "2020-05-15",
"registration_institution_occurrence_event": [
{
"cnab_file": {
"cnab_key": "abfc9fba-28fb-4e75-afcb-f4647d7031bc",
"company_code": null,
"created_at": "2020-05-15T21:00:22",
"downloads": [],
"file_size": "None",
"filename": null,
"line_length": null,
"remitter_key": "b91195e3-0cf4-4fed-90cf-7f5bef29c2f0",
"requester_profile_code": null,
"type": {
"created_at": "2019-02-01T16:44:17",
"enumerator": "api_instruction",
"translation_path": "bank_slip.CNABFileType.api_instruction"
},
"url": null,
"version": null
},
"cnab_file_occurrence_order": 1,
"created_at": "2020-05-15T21:00:25",
"new_status": {
"created_at": "2019-02-01T16:44:15",
"enumerator": "waiting_submission",
"translation_path": "bank_slip.RegistrationInstitutionOccurrenceStatus.waiting_submission"
},
"old_status": null
}
],
"registration_institution_occurrence_status": {
"created_at": "2019-02-01T16:44:15",
"enumerator": "waiting_submission",
"translation_path": "bank_slip.RegistrationInstitutionOccurrenceStatus.waiting_submission"
},
"requester_occurrence_event": [
{
"cnab_file": {
"cnab_key": "abfc9fba-28fb-4e75-afcb-f4647d7031bc",
"company_code": null,
"created_at": "2020-05-15T21:00:22",
"downloads": [],
"file_size": "None",
"filename": null,
"line_length": null,
"remitter_key": "b91195e3-0cf4-4fed-90cf-7f5bef29c2f0",
"requester_profile_code": null,
"type": {
"created_at": "2019-02-01T16:44:17",
"enumerator": "api_instruction",
"translation_path": "bank_slip.CNABFileType.api_instruction"
},
"url": null,
"version": null
},
"cnab_file_occurrence_order": 1,
"created_at": "2020-05-15T21:00:25",
"new_status": {
"created_at": "2019-02-01T16:44:16",
"enumerator": "accepted",
"translation_path": "bank_slip.RequesterOccurrenceStatus.accepted"
},
"old_status": null
}
],
"requester_occurrence_status": {
"created_at": "2019-02-01T16:44:16",
"enumerator": "accepted",
"translation_path": "bank_slip.RequesterOccurrenceStatus.accepted"
}
}
],
"our_number": 2,
"paid_amount": null,
"paid_fine_amount": null,
"paid_interest_amount": null,
"participant_control_number": null,
"payer_account_digit": null,
"payer_account_number": null,
"payer_account_type": null,
"payer_address": "Rua Carlos tampaio, 204",
"payer_bank": null,
"payer_branch_digit": null,
"payer_branch_number": null,
"payer_document": "41651732825",
"payer_name": "Beatriz Couto",
"payer_person_type": {
"created_at": "2019-02-01T16:44:09",
"enumerator": "natural",
"translation_path": "bank_slip.PersonType.natural"
},
"payer_postal_code": "00000000",
"payment_date": null,
"printing_policy": {
"created_at": "2019-02-01T16:44:10",
"enumerator": "no_printing",
"translation_path": "bank_slip.PrintingPolicy.no_printing"
},
"protest_status": {
"created_at": "2019-02-01T16:44:08",
"enumerator": "not_protested",
"translation_path": "bank_slip.ProtestStatus.not_protested"
},
"rebate_amount": null,
"registration_institution": {
"created_at": "2020-03-26T19:36:16",
"enumerator": "qi_scd",
"febraban_code": "329",
"remittance_sequence": 72,
"settlement_resource_account_key": "3e46d266-4fdb-4fd2-b87a-3e3de366afd4"
},
"requester_profile": 1,
"requester_profile_code": "329-01-0001-0067049",
"requester_registration_date": "2020-05-15"
}{
"amount": 3,
"asset_type": {
"created_at": "2019-02-01T16:44:11",
"enumerator": "invoice",
"translation_path": "bank_slip.AssetType.invoice"
},
"automatic_bankruptcy_protest": true,
"automatic_protest": false,
"automatic_write_off": false,
"bank_slip_file": [
{
"barcode": "32998827300000003000001010000000000200670490",
"created_at": "2020-05-19T18:46:41",
"digitable_line": "32990001031000000000902006704908882730000000300",
"url": "https://linkparadownload.com/arquivo.pdf"
}
],
"bank_slip_key": "96b32f1a-c2bd-41a4-b4b1-a169235be68b",
"bank_slip_status": {
"created_at": "2019-02-01T16:44:07",
"enumerator": "accepted",
"translation_path": "bank_slip.BankSlipStatus.accepted"
},
"bank_teller_instructions": "Boleto Teste",
"beneficiary_account_branch": "0001",
"beneficiary_account_key": "7cc3b1f7-8015-4073-8471-a3ba57e34975",
"beneficiary_account_number": "67049",
"beneficiary_document_number": "12345678905",
"beneficiary_key": "b91195e3-0cf4-4fed-90cf-7f5bef29c2f0",
"beneficiary_name": "Greg Brown",
"billing_account_key": "7cc3b1f7-8015-4073-8471-a3ba57e34975",
"business_date_expiration": "2020-06-01",
"created_at": "2020-05-15T21:00:25",
"days_before_fine": null,
"days_before_interest": null,
"days_to_bankruptcy_protest": 1,
"days_to_protest": null,
"days_to_write_off": null,
"discount_limit_date": null,
"discount_value": null,
"document_number": "Parcela 1",
"expenses": [],
"expiration": "2020-06-01",
"fine_percentage": 0.1,
"guarantor_address": null,
"guarantor_city": null,
"guarantor_document": null,
"guarantor_name": null,
"guarantor_person_type": null,
"guarantor_postal_code": "00000000",
"guarantor_state": null,
"historical_our_number": 2,
"institution_registration_date": null,
"interest_daily_value": 0.34,
"lock_origin_type": null,
"nfe_key": null,
"nfe_url": null,
"occurrences": [
{
"created_at": "2020-05-15T21:00:25",
"discount_amount": null,
"discount_limit_date": null,
"iof_amount": null,
"new_bank_slip_status": null,
"new_due_date": "2020-06-01",
"new_protest_status": {
"created_at": "2019-02-01T16:44:08",
"enumerator": "not_protested",
"translation_path": "bank_slip.ProtestStatus.not_protested"
},
"notary_office_number": null,
"notary_office_protocol": null,
"occurrence_expenses": null,
"occurrence_feedback": null,
"occurrence_key": "c3ab3e01-f198-4e7e-9e01-7a8091b8bd72",
"occurrence_reasons": [],
"occurrence_type": {
"created_at": "2019-02-01T16:44:14",
"enumerator": "registration",
"translation_path": "bank_slip.OccurrenceType.registration"
},
"old_bank_slip_status": {
"created_at": "2019-02-01T16:44:07",
"enumerator": "accepted",
"translation_path": "bank_slip.BankSlipStatus.accepted"
},
"old_due_date": null,
"old_protest_status": null,
"paid_amount": null,
"paid_fine_amount": null,
"paid_interest_amount": null,
"payment_bank": null,
"payment_branch": null,
"payment_credit_date": null,
"payment_method": null,
"payment_origin": null,
"protest_confirmation": null,
"protest_expenses": null,
"rebate_amount": null,
"registration_institution_occurrence_date": "2020-05-15",
"registration_institution_occurrence_event": [
{
"cnab_file": {
"cnab_key": "abfc9fba-28fb-4e75-afcb-f4647d7031bc",
"company_code": null,
"created_at": "2020-05-15T21:00:22",
"downloads": [],
"file_size": "None",
"filename": null,
"line_length": null,
"remitter_key": "b91195e3-0cf4-4fed-90cf-7f5bef29c2f0",
"requester_profile_code": null,
"type": {
"created_at": "2019-02-01T16:44:17",
"enumerator": "api_instruction",
"translation_path": "bank_slip.CNABFileType.api_instruction"
},
"url": null,
"version": null
},
"cnab_file_occurrence_order": 1,
"created_at": "2020-05-15T21:00:25",
"new_status": {
"created_at": "2019-02-01T16:44:15",
"enumerator": "waiting_submission",
"translation_path": "bank_slip.RegistrationInstitutionOccurrenceStatus.waiting_submission"
},
"old_status": null
}
],
"registration_institution_occurrence_status": {
"created_at": "2019-02-01T16:44:15",
"enumerator": "waiting_submission",
"translation_path": "bank_slip.RegistrationInstitutionOccurrenceStatus.waiting_submission"
},
"requester_occurrence_event": [
{
"cnab_file": {
"cnab_key": "abfc9fba-28fb-4e75-afcb-f4647d7031bc",
"company_code": null,
"created_at": "2020-05-15T21:00:22",
"downloads": [],
"file_size": "None",
"filename": null,
"line_length": null,
"remitter_key": "b91195e3-0cf4-4fed-90cf-7f5bef29c2f0",
"requester_profile_code": null,
"type": {
"created_at": "2019-02-01T16:44:17",
"enumerator": "api_instruction",
"translation_path": "bank_slip.CNABFileType.api_instruction"
},
"url": null,
"version": null
},
"cnab_file_occurrence_order": 1,
"created_at": "2020-05-15T21:00:25",
"new_status": {
"created_at": "2019-02-01T16:44:16",
"enumerator": "accepted",
"translation_path": "bank_slip.RequesterOccurrenceStatus.accepted"
},
"old_status": null
}
],
"requester_occurrence_status": {
"created_at": "2019-02-01T16:44:16",
"enumerator": "accepted",
"translation_path": "bank_slip.RequesterOccurrenceStatus.accepted"
}
}
],
"our_number": 2,
"paid_amount": null,
"paid_fine_amount": null,
"paid_interest_amount": null,
"participant_control_number": null,
"payer_account_digit": null,
"payer_account_number": null,
"payer_account_type": null,
"payer_address": "Rua Carlos tampaio, 204",
"payer_bank": null,
"payer_branch_digit": null,
"payer_branch_number": null,
"payer_document": "41651732825",
"payer_name": "Beatriz Couto",
"payer_person_type": {
"created_at": "2019-02-01T16:44:09",
"enumerator": "natural",
"translation_path": "bank_slip.PersonType.natural"
},
"payer_postal_code": "00000000",
"payment_date": null,
"printing_policy": {
"created_at": "2019-02-01T16:44:10",
"enumerator": "no_printing",
"translation_path": "bank_slip.PrintingPolicy.no_printing"
},
"protest_status": {
"created_at": "2019-02-01T16:44:08",
"enumerator": "not_protested",
"translation_path": "bank_slip.ProtestStatus.not_protested"
},
"rebate_amount": null,
"registration_institution": {
"created_at": "2020-03-26T19:36:16",
"enumerator": "qi_scd",
"febraban_code": "329",
"remittance_sequence": 72,
"settlement_resource_account_key": "3e46d266-4fdb-4fd2-b87a-3e3de366afd4"
},
"requester_profile": 1,
"requester_profile_code": "329-01-0001-0067049",
"requester_registration_date": "2020-05-15"
}{
"amount": 3,
"asset_type": {
"created_at": "2019-02-01T16:44:11",
"enumerator": "invoice",
"translation_path": "bank_slip.AssetType.invoice"
},
"automatic_bankruptcy_protest": true,
"automatic_protest": false,
"automatic_write_off": false,
"bank_slip_file": [
{
"barcode": "32998827300000003000001010000000000200670490",
"created_at": "2020-05-19T18:46:41",
"digitable_line": "32990001031000000000902006704908882730000000300",
"url": "https://linkparadownload.com/arquivo.pdf"
}
],
"bank_slip_key": "96b32f1a-c2bd-41a4-b4b1-a169235be68b",
"bank_slip_status": {
"created_at": "2019-02-01T16:44:07",
"enumerator": "accepted",
"translation_path": "bank_slip.BankSlipStatus.accepted"
},
"bank_teller_instructions": "Boleto Teste",
"beneficiary_account_branch": "0001",
"beneficiary_account_key": "7cc3b1f7-8015-4073-8471-a3ba57e34975",
"beneficiary_account_number": "67049",
"beneficiary_document_number": "12345678905",
"beneficiary_key": "b91195e3-0cf4-4fed-90cf-7f5bef29c2f0",
"beneficiary_name": "Greg Brown",
"billing_account_key": "7cc3b1f7-8015-4073-8471-a3ba57e34975",
"business_date_expiration": "2020-06-01",
"created_at": "2020-05-15T21:00:25",
"days_before_fine": null,
"days_before_interest": null,
"days_to_bankruptcy_protest": 1,
"days_to_protest": null,
"days_to_write_off": null,
"discount_limit_date": null,
"discount_value": null,
"document_number": "Parcela 1",
"expenses": [],
"expiration": "2020-06-01",
"fine_percentage": 0.1,
"guarantor_address": null,
"guarantor_city": null,
"guarantor_document": null,
"guarantor_name": null,
"guarantor_person_type": null,
"guarantor_postal_code": "00000000",
"guarantor_state": null,
"historical_our_number": 2,
"institution_registration_date": null,
"interest_daily_value": 0.34,
"lock_origin_type": null,
"nfe_key": null,
"nfe_url": null,
"occurrences": [
{
"created_at": "2020-05-15T21:00:25",
"discount_amount": null,
"discount_limit_date": null,
"iof_amount": null,
"new_bank_slip_status": null,
"new_due_date": "2020-06-01",
"new_protest_status": {
"created_at": "2019-02-01T16:44:08",
"enumerator": "not_protested",
"translation_path": "bank_slip.ProtestStatus.not_protested"
},
"notary_office_number": null,
"notary_office_protocol": null,
"occurrence_expenses": null,
"occurrence_feedback": null,
"occurrence_key": "c3ab3e01-f198-4e7e-9e01-7a8091b8bd72",
"occurrence_reasons": [],
"occurrence_type": {
"created_at": "2019-02-01T16:44:14",
"enumerator": "registration",
"translation_path": "bank_slip.OccurrenceType.registration"
},
"old_bank_slip_status": {
"created_at": "2019-02-01T16:44:07",
"enumerator": "accepted",
"translation_path": "bank_slip.BankSlipStatus.accepted"
},
"old_due_date": null,
"old_protest_status": null,
"paid_amount": null,
"paid_fine_amount": null,
"paid_interest_amount": null,
"payment_bank": null,
"payment_branch": null,
"payment_credit_date": null,
"payment_method": null,
"payment_origin": null,
"protest_confirmation": null,
"protest_expenses": null,
"rebate_amount": null,
"registration_institution_occurrence_date": "2020-05-15",
"registration_institution_occurrence_event": [
{
"cnab_file": {
"cnab_key": "abfc9fba-28fb-4e75-afcb-f4647d7031bc",
"company_code": null,
"created_at": "2020-05-15T21:00:22",
"downloads": [],
"file_size": "None",
"filename": null,
"line_length": null,
"remitter_key": "b91195e3-0cf4-4fed-90cf-7f5bef29c2f0",
"requester_profile_code": null,
"type": {
"created_at": "2019-02-01T16:44:17",
"enumerator": "api_instruction",
"translation_path": "bank_slip.CNABFileType.api_instruction"
},
"url": null,
"version": null
},
"cnab_file_occurrence_order": 1,
"created_at": "2020-05-15T21:00:25",
"new_status": {
"created_at": "2019-02-01T16:44:15",
"enumerator": "waiting_submission",
"translation_path": "bank_slip.RegistrationInstitutionOccurrenceStatus.waiting_submission"
},
"old_status": null
}
],
"registration_institution_occurrence_status": {
"created_at": "2019-02-01T16:44:15",
"enumerator": "waiting_submission",
"translation_path": "bank_slip.RegistrationInstitutionOccurrenceStatus.waiting_submission"
},
"requester_occurrence_event": [
{
"cnab_file": {
"cnab_key": "abfc9fba-28fb-4e75-afcb-f4647d7031bc",
"company_code": null,
"created_at": "2020-05-15T21:00:22",
"downloads": [],
"file_size": "None",
"filename": null,
"line_length": null,
"remitter_key": "b91195e3-0cf4-4fed-90cf-7f5bef29c2f0",
"requester_profile_code": null,
"type": {
"created_at": "2019-02-01T16:44:17",
"enumerator": "api_instruction",
"translation_path": "bank_slip.CNABFileType.api_instruction"
},
"url": null,
"version": null
},
"cnab_file_occurrence_order": 1,
"created_at": "2020-05-15T21:00:25",
"new_status": {
"created_at": "2019-02-01T16:44:16",
"enumerator": "accepted",
"translation_path": "bank_slip.RequesterOccurrenceStatus.accepted"
},
"old_status": null
}
],
"requester_occurrence_status": {
"created_at": "2019-02-01T16:44:16",
"enumerator": "accepted",
"translation_path": "bank_slip.RequesterOccurrenceStatus.accepted"
}
}
],
"our_number": 2,
"paid_amount": null,
"paid_fine_amount": null,
"paid_interest_amount": null,
"participant_control_number": null,
"payer_account_digit": null,
"payer_account_number": null,
"payer_account_type": null,
"payer_address": "Rua Carlos tampaio, 204",
"payer_bank": null,
"payer_branch_digit": null,
"payer_branch_number": null,
"payer_document": "41651732825",
"payer_name": "Beatriz Couto",
"payer_person_type": {
"created_at": "2019-02-01T16:44:09",
"enumerator": "natural",
"translation_path": "bank_slip.PersonType.natural"
},
"payer_postal_code": "00000000",
"payment_date": null,
"printing_policy": {
"created_at": "2019-02-01T16:44:10",
"enumerator": "no_printing",
"translation_path": "bank_slip.PrintingPolicy.no_printing"
},
"protest_status": {
"created_at": "2019-02-01T16:44:08",
"enumerator": "not_protested",
"translation_path": "bank_slip.ProtestStatus.not_protested"
},
"rebate_amount": null,
"registration_institution": {
"created_at": "2020-03-26T19:36:16",
"enumerator": "qi_scd",
"febraban_code": "329",
"remittance_sequence": 72,
"settlement_resource_account_key": "3e46d266-4fdb-4fd2-b87a-3e3de366afd4"
},
"requester_profile": 1,
"requester_profile_code": "329-01-0001-0067049",
"requester_registration_date": "2020-05-15"
}
```
STATUS 400
Response Body
```json
{
{"title": "Bad Request", "description": "Invalid request body.", "translation": "Corpo da requisição inválido.", "extra_fields": {}, "code": "LEG000069"}
}
```
---
# Emissão de boleto único (instantânea)
URL: /en/documentation/boletos/emissao/emissao_boleto_unico_instantanea
:::danger Importante
Para registrar bolePix, é necessário que exista uma chave Pix aleatória ativa na conta em que os boletos serão registrados.
:::
No caso do registro de boleto único de forma instantânea, a resposta da requisição de criação (resposta síncrona) já retorna o boleto registrado (ou não, para casos de rejeição). O tempo de confirmação/rejeição da Nuclea/CIP, a respeito do registro do boleto, está incluso no tempo de resposta desse endpoint.
## Request
ENDPOINT /account/ ACCOUNT_KEY /requester_profile/ REQUESTER_PROFILE_KEY /bank_slip/instant
MÉTODO POST
### Path parameters
| Campo | Tipo | Descrição | Caracteres |
|-------------------------|--------|--------------------------------------------------------------|------------|
| `account_key` | uuidv4 | Chave única de identificação da conta, no formato uuid v4 | 36 |
| `requester_profile_key` | uuidv4 | Chave única de identificação da carteira, no formato uuid v4 | 36 |
Request Body
```json
{
"request_control_key": "0d496b4d-01f6-48cd-8ec9-9ead1e43f156",
"our_number": 123456789,
"document_number": "DOC4561237",
"amount": 5000.00,
"expiration": "2025-01-01",
"bank_teller_instructions": "Confirm payment",
"protest_data": {"days_to_protest": 7},
"bankruptcy_protest_data": {"days_to_bankruptcy_protest": 14},
"max_payment_days": 45,
"fine_data": {"fine_type": "absolute", "fine_amount": 100.00, "days_to_fine": 10},
"interest_data": {
"interest_type": "workdays_daily_amount",
"interest_amount": 10.00,
"days_to_interest": 2,
},
"financial_instrument_type": "digital_commercial_invoice",
"write_off_data": {"days_to_write_off": 365},
"rebate_amount": 200.00,
"discounts_data": [
{
"discount_amount": 50.00,
"discount_number": 1,
"discount_type": "absolute",
"discount_limit_date": "2024-12-01",
}
],
"payer_data": {
"name": "Global Tech",
"contact": {
"email": "finance@globaltech.com",
"phone": {"country_code": "055", "area_code": "11", "number": "987654321"},
},
"address": {
"street": "101 High St.",
"neighborhood": "Tech Park",
"number": "202",
"postal_code": "01001000",
"city": "Innovation City",
"state": "SP",
"complement": "Building A",
},
"document_number": "12345678000195",
"person_type": "legal",
},
"guarantor_data": {
"name": "Jane Doe",
"contact": {
"email": "jane.doe@qitech.com.br",
"phone": {"country_code": "055", "area_code": "11", "number": "999999999"},
},
"address": {
"street": "202 Elm St.",
"neighborhood": "Quiet Neighborhood",
"number": "303",
"postal_code": "01001000",
"city": "Peaceful Town",
"state": "RJ",
"complement": "House 1",
},
"document_number": "23456789012",
"person_type": "natural",
},
"pix_key": "06797774-e050-419e-a91a-c64c919b52c7",
"notification": {
"document_number": "12345678000195",
"name": "Global Tech",
"email": "finance@globaltech.com",
"phone": {"country_code": "055", "area_code": "11", "number": "987654321"},
"send_2_way": true,
"send_before_due_date": false,
"send_after_due_date": false,
"send_on_protest": false
}
}
```
### Request Body Params
| Campo | Tipo | Descrição | Caracteres |
|----------------------------|---------|------------------------------------------------------------------------------------|--------------------------------------------------|
| `request_control_key` * | uuidv4 | Chave única de identificação da request utilizada pelo cliente no formato uuid v4 | 36 |
| `our_number` | integer | Número único de identificação do boleto junto à carteira. Pode ser enviado pelo cliente e, caso não seja, a QI Tech irá gerar um | 11 |
| `document_number` | string | Número de identificação do boleto. Pode ser o número da nota fiscal eletrônica | 10 |
| `participant_control_number` | string | Nº Controle do Participante |
25 |
| `amount` * | float | Valor base do boleto | - |
| `expiration` * | string | Data de vencimento | 10 |
| `bank_teller_instructions` | string | Observações ao pagador do boleto. Aceita no máximo 320 caracteres, distribuídos em até 7 linhas. Cada linha pode conter no máximo 90 caracteres. Caso uma linha ultrapasse 90 caracteres, o texto será automaticamente quebrado em uma nova linha | 320 |
| `rebate_amount` | float | Valor de abatimento do boleto, que será aplicado em cima do valor base | - |
| `max_payment_days` | integer | Máximo de dias corridos que o boleto ficará disponível para pagamento, após o vencimento (pode ser no máximo 365) | - |
| `financial_instrument_type` | string | Tipo de espécie do boleto | **[Enumeradores financial_instrument_type](#enumeradores-financial_instrument_type)** |
| `partial_payment_data` | object | Configurações de pagamento parcial | **[Objeto partial_payment_data](#objeto-partial_payment_data)** |
| `write_off_data` | object | Configuração de baixa | **[Objeto write_off_data](#objeto-write_off_settings)** |
| `protest_data` | object | Configuração de protesto | **[Objeto protest_data](#objeto-protest_settings)** |
| `bankruptcy_protest_data` | object | Configuração de protesto falimentar | **[Objeto bankruptcy_protest_data](#objeto-bankruptcy_protest_settings)** |
| `fine_data` | object | Configuração de multa | **[Objeto fine_data](#objeto-fine_settings)** |
| `interest_data` | object | Configuração de juros | **[Objeto interest_data](#objeto-interest_settings)** |
| `discounts_data` | object array | Descontos | **[Objeto discount](#objeto-discounts_data)** |
| `payer_data` * | object | Dados do pagador | **[Objeto payer_data](#objetos-payer_data-e-guarantor_data)** |
| `guarantor_data` | object | Dados do sacador avalista | **[Objeto guarantor_data](#objetos-payer_data-e-guarantor_data)** |
| `pix_key` | uuidv4 | Chave pix do tipo aleatória | 36 |
:::info BolePix
Caso o parâmetro `pix_key`, opcional, seja enviado na request, será gerado um bolePix. BolePix é um boleto cujo pagamento é vinculado a um QR Code Pix. Sendo assim, o pagador pode realizar o pagamento do boleto tanto utilizando a linha digitável do mesmo, quanto através da leitura do QR Code Pix vinculado. Caso o pagamento seja feito via QR Code, a liquidação financeira se dá instantaneamente, enquanto os retornos bancários e webhooks envolvidos na liquidação serão gerados assim como é feito para um boleto comum.
Importante: para registrar um bolePix, é necessário que exista uma chave Pix aleatória ativa na conta em que boleto será registrado.
:::
:::tip Configurações Padrão da Carteira
Caso cada um dos campos `max_payment_days`, `write_off_data`, `protest_data`, `bankruptcy_protest_data`, `fine_data`, `interest_data` e `pix_key` não sejam enviados na request e a carteira possua configurações padrão (i.e. `max_payment_days`, `write_off_settings`, `protest_settings`, `bankruptcy_protest_settings`, `fine_settings`, `interest_settings` e `qr_code_settings`, respectivamente, no `configuration_data` do `requester_profile`), serão utilizadas tais configurações padrão para a emissão do título.
:::
:::caution Limitações e Restrições
- **Boletos de Pagamento Parcial:** Não é permitido o pagamento via QR Code Pix. Portanto, não é permitido enviar a `pix_key` no registro, nem ter uma configuração padrão de geração de bolePix para a carteira.
- **Boletos de Cartão de Crédito:** Não é necessário nem permitido enviar informações rebate, desconto, multa e juros. Isso se deve ao padrão do mercado, onde muitas Instituições Financeiras não aceitam o pagamento de boletos de cartão de crédito que contenham essas informações. A carteira também não pode ter essas configurações definidas como padrão. Sendo assim boletos desse tipo podem ser pagos parcialmente mesmo após o vencimento, sem incidência de juros, multas, descontos ou abatimentos na fatura corrente. Para aplicar esses valores é necessário incluí-los na próxima fatura, seja através da [ocorrência de edição de valor](/documentation/boletos/instrucoes/valor) do boleto ou emitindo um novo boleto que inclua esses valores. É possível enviar `amount = 0` para boletos deste tipo.
**Importante:** Boletos do tipo `credit_card` são obrigatoriamente de pagamento parcial, sendo assim é necessário fornecer as informações de `partial_payment_data` ou ter essa configuração padrão na carteira. Caso o campo `financial_instrument_type` não seja enviado, o valor padrão será `digital_commercial_invoice`.
:::
:::tip Recomendações de Carteiras
- **Carteira para Boletos Padrão:** Mantenha as configurações padrão para multas, juros e protesto
- **Carteira para Boletos de Pagamento Parcial:** Sem configuração de Pix e com regras específicas para pagamento parcial
- **Carteira para Boletos de Cartão de Crédito:** Sem configurações de multa, juros, desconto ou rebate
Criar carteiras específicas garante que as configurações padrão sejam adequadas para cada tipo de boleto e evita conflitos nas regras de negócio.
:::
:::info Máquina de Estados
A máquina de status para boletos de pagamento parcial possui algumas diferenças. Para mais detalhes, consulte a [introdução](/documentation/boletos/introducao) , onde há uma explicação sobre como aplicar a incidência de juros e multas no boleto seguindo as boas práticas do mercado.
:::
### Enumeradores financial_instrument_type
| Enumerador | Descrição |
|-------------|----------------------------------|
| digital_commercial_invoice | DMI Duplicata Mercantil Indicação |
| credit_card | Cartão de Crédito |
| check | CH Cheque |
| digital_commercial | DM Duplicata Mercantil |
| digital_service_invoice | Duplicata de Serviço |
| digital_service_invoice_indication | DSI Duplicata de Serviço Indicação |
| digital_rural_invoice | DR Duplicata Rural |
| bill_of_exchange | LC Letra de Câmbio |
| commercial_credit_note | NCC Nota de Crédito Comercial |
| export_credit_note | NCE Nota de Crédito Exportação |
| industrial_credit_note | NCI Nota de Crédito Industrial |
| rural_credit_note | NCR Nota de Crédito Rural |
| promissory_note | NP Nota Promissória |
| rural_promissory_note | NPR Nota Promissória Rural |
| mercantile_triplicate | TM Triplicata Mercantil |
| service_triplicate | TS Triplicata de Serviço |
| insurance_note | NS Nota de Seguro |
| receipt | RC Recibo |
| printed_bank_slip | FAT Bloqueto |
| debit_note | ND Nota de Débito |
| insurance_policy | AP Apólice de Seguro |
| school_monthly_fee | ME Mensalidade Escolar |
| consortium_installment | PC Parcela de Consórcio |
| invoice | NF Nota Fiscal |
| debt_document | DD Documento de Dívida |
| rural_product_certificate | Cédula de Produto Rural |
| warrant | Warrant |
| state_active_debt | Dívida Ativa de Estado |
| municipal_active_debt | Dívida Ativa de Município |
| federal_active_debt | Dívida Ativa da União |
| condominium_charges | Encargos condominiais |
| proposal_bank_slip | Boleto proposta |
| deposit_and_contribution_bank_slip | Boleto de Depósito e Aporte |
| others | Outros |
### Objeto partial_payment_data
| Campo | Tipo | Descrição | Caracteres |
|-----------------------------------|---------|---------------------------------------------------------------------------|------------|
| `partial_payment_minimum_type` * | string | Tipo de valor mínimo para pagamento parcial | **[Enumeradores partial_payment_type](#enumeradores-partial_payment_type)** |
| `partial_payment_minimum_percentage` | float | Percentual mínimo permitido para o pagamento parcial | - |
| `partial_payment_minimum_amount` | float | Valor mínimo permitido para o pagamento parcial | - |
| `partial_payment_maximum_type` | string | Tipo de valor máximo para pagamento parcial | **[Enumeradores partial_payment_type](#enumeradores-partial_payment_type)** |
| `partial_payment_maximum_percentage` | float | Percentual máximo permitido para o pagamento parcial | - |
| `partial_payment_maximum_amount` | float | Valor máximo permitido para o pagamento parcial | - |
| `partial_payment_quantity` * | integer | Quantidade de pagamentos parciais permitidos | - |
:::caution Atenção!
De acordo com o valor enviado nos campos `partial_payment_minimum_type` e `partial_payment_maximum_type`, é necessário enviar o `partial_payment_minimum_amount` ou `partial_payment_minimum_percentage`, e o `partial_payment_maximum_amount` ou `partial_payment_maximum_percentage` correspondente.
:::
### Enumeradores partial_payment_type
| Enumerador | Descrição |
|-------------|----------------------------------|
| absolute | Valor absoluto |
| percentage | Percentual |
### Objeto write_off_data
| Campo | Tipo | Descrição | Caracteres |
|---------------------------|---------|-----------------------------------------------------------------------------|------------|
| `days_to_write_off` * | integer | Dias, após o vencimento, para que o boleto seja baixado automaticamente | - |
### Objeto protest_data
| Campo | Tipo | Descrição | Caracteres |
|---------------------------|---------|-----------------------------------------------------------------------------|------------|
| `days_to_protest` * | integer | Dias, após o vencimento, para que o boleto seja protestado automaticamente | - |
### Objeto bankruptcy_protest_data
| Campo | Tipo | Descrição | Caracteres |
|--------------------------------|---------|-----------------------------------------------------------------------------|------------|
| `days_to_bankruptcy_protest` * | integer | Dias, após o vencimento, para que o boleto seja protestado automaticamente | - |
### Objeto fine_data
Opção 1: multa em valor absoluto (`fine_type=absolute`)
| Campo | Tipo | Descrição | Caracteres |
|---------------------------|---------|---------------------------------------------------------|-------------------------------------------------------------------------|
| `fine_type` * | string | Tipo da multa | **[Enumeradores fine_type](#enumeradores-fine_type)** |
| `fine_amount` * | float | Valor absoluto da multa | - |
| `days_to_fine` * | integer | Dias, após o vencimento, para que a multa seja cobrada | - |
Opção 2: multa em valor percentual (`fine_type=percentage`)
| Campo | Tipo | Descrição | Caracteres |
|---------------------------|---------|-----------------------------------------------------------|---------------------------------------|
| `fine_type` * | string | Tipo da multa | **[Enumeradores fine_type](#enumeradores-fine_type)** |
| `fine_percentage` * | integer | Valor percentual da multa, de 1 a 100 | - |
| `days_to_fine` * | integer | Dias, após o vencimento, para que a multa seja cobrada | - |
### Enumeradores fine_type
| Enumerador | Descrição |
|--------------------|-----------------------|
| absolute | valor absoluto |
| percentage | valor percentual |
### Objeto interest_data
Opção 1: juros utilizando valores absolutos (`interest_type=calendar_days_daily_amount` ou `interest_type=workdays_daily_amount`)
| Campo | Tipo | Descrição | Caracteres |
|---------------------------|---------|-------------------------------------------------------------------------------------|------------------------------------------------------------------------------------------------|
| `interest_type` * | string | Tipo de juros | **[Enumeradores interest_type](#enumeradores-interest_type)** |
| `interest_amount` * | float | Valor a ser cobrado por unidade de tempo determinada (dias úteis ou corridos) | - |
| `days_to_interest` * | integer | Dias, após o vencimento, para que comece a cobrar os juros | - |
Opção 2: juros utilizando valores percentuais (`interest_type=calendar_days_monthly_percentage`)
| Campo | Tipo | Descrição | Caracteres |
|--------------------------|---------|---------------------------------------------------------------------------------------|----------------------------------------------------------------------------------------------------|
| `interest_type` * | string | Tipo de juros | **[Enumeradores interest_type](#enumeradores-interest_type)** |
| `interest_percentage` * | integer | Porcentagem a ser cobrada por unidade de tempo determinada (dias úteis ou corridos) | - |
| `days_to_interest` * | integer | Dias, após o vencimento, para que comece a cobrar os juros | - |
### Enumeradores interest_type
| Enumerador | Descrição |
|----------------------------------|----------------------------------------------------------------------|
| calendar_days_daily_amount | Valor diário sobre dias corridos |
| workdays_daily_amount | Valor diário sobre dias úteis |
| calendar_days_monthly_percentage | Porcentagem de juros cobrados mensalmente, com base em dias corridos |
### Objeto discount
Opção 1: descontos utilizando valores absolutos (`discount_type in ["absolute", "anticipation_calendar_days_daily_amount", "anticipation_workdays_daily_amount"]`)
| Campo | Tipo | Descrição | Caracteres |
|---------------------------|---------|-----------------------------------------------------|-----------------------------------------------------------|
| `discount_amount` * | float | Valor absoluto de desconto por unidade de tempo | - |
| `discount_number` * | integer | Número do desconto | - |
| `discount_type` * | string | Configuração do desconto em valores absolutos | **[Enumerador discount_type](#enumeradores-discount_type)** | |
| `discount_limit_date` * | string | Data limite para aplicação do desconto | 10 |
Opção 2: descontos utilizando valores percentuais (`discount_type in ["percentage", "anticipation_calendar_days_daily_percentage", "anticipation_workdays_daily_percentage"]`)
| Campo | Tipo | Descrição | Caracteres |
|---------------------------|---------|-----------------------------------------------------|-----------------------------------------------------------|
| `discount_percentage` * | float | Valor percentual de desconto por unidade de tempo | - |
| `discount_number` * | integer | Número do desconto | - |
| `discount_type` * | string | Configuração do desconto em valores percentuais | **[Enumerador discount_type](#enumeradores-discount_type)** | |
| `discount_limit_date` * | string | Data limite para aplicação do desconto | 10 |
:::caution Atenção!
O boleto pode ter até três descontos, sendo que os descontos devem ser todos do mesmo tipo , isto é, devem ter o mesmo `discount_type`. Os descontos devem ser numerados de 1 a 3, de maneira crescente e começando necessariamente em 1. Ou seja, caso sejam enviados dois descontos na requisição, devem necessariamente ser numerados com 1 e 2.
:::
### Enumeradores discount_type
| Enumerador | Descrição |
|---------------------------------------------|--------------------------------------------------------------------------|
| absolute | Valor fixo |
| anticipation_calendar_days_daily_amount | Valor diário de desconto de antecipação, sobre dias corridos |
| anticipation_workdays_daily_amount | Valor diário de desconto de antecipação, sobre dias úteis |
| percentage | Porcentagem fixa |
| anticipation_calendar_days_daily_percentage | Porcentagem mensal de desconto de antecipação, com base em dias corridos |
| anticipation_workdays_daily_percentage | Porcentagem anual de desconto de antecipação, com base em dias úteis |
### Objetos payer_data e guarantor_data
| Campo | Tipo | Descrição | Caracteres|
|---------------------------|--------|-------------------------------------|-----------------------------------------------------------|
| `name` * | string | Nome completo | 100 |
| `document_number` * | string | Número do documento (CPF/CNPJ) | 11 ou 14 |
| `person_type` * | string | Tipo da pessoa (física ou jurídica) | **[Enumeradores person_type](#enumeradores-person_type)** |
| `contact` | object | Informações de contato | **[Objeto contact](#objeto-contact)** |
| `address` | object | Endereço | **[Objeto address](#objeto-address)** |
### Enumeradores person_type
| Enumerador | Descrição |
|--------------------|-----------------------|
| natural | pessoa física |
| legal | pessoa jurídica |
### Objeto contact
| Campo | Tipo | Descrição | Caracteres |
|---------------------------|--------|-----------------------------------|------------------------------------|
| `email` | string | E-mail de contato | 320 |
| `phone` | object | Telefone de contato | **[Objeto phone](#objeto-phone)** |
### Objeto phone
| Campo | Tipo | Descrição | Caracteres |
|---------------------------------|--------|----------------------------------------------|------------|
| `country_code` * | string | Código DDI (Discagem Direta Internacional) | 3 |
| `area_code` * | string | Código DDD (Discagem Direta à Distância) | 2 |
| `number` * | string | Complemento | 9 |
### Objeto address
| Campo | Tipo | Descrição | Caracteres |
|---------------------------|--------|----------------------------------------------|------------|
| `street` * | string | Logradouro | 500 |
| `number` * | string | Número | 6 |
| `complement` | string | Complemento | 500 |
| `neighborhood` * | string | Bairro | 100 |
| `postal_code` * | string | CEP | 8 |
| `city` * | string | Cidade | 100 |
| `state` * | string | Estado (UF) | **[Enumerador state](#enumeradores-state)** |
### Enumeradores state
| Enumerador | Descrição |
|--------------------|-----------------------|
| AC | Acre |
| AL | Alagoas |
| AM | Amazonas |
| AP | Amapá |
| BA | Bahia |
| CE | Ceará |
| DF | Distrito federal |
| ES | Espírito Santo |
| GO | Goiás |
| MA | Maranhão |
| MG | Minas Gerais |
| MS | Mato Grosso do Sul |
| MT | Mato Grosso |
| PA | Pará |
| PB | Paraíba |
| PE | Pernambuco |
| PI | Piauí |
| PR | Paraná |
| RJ | Rio de Janeiro |
| RN | Rio Grande do Norte |
| RO | Rondônia |
| RR | Roraima |
| RS | Rio Grande do Sul |
| SC | Santa Catarina |
| SE | Sergipe |
| SP | São Paulo |
| TO | Tocantins |
| EX | Exceção |
### Objeto notification
| Campo | Tipo | Descrição | Caracteres |
|---------------------------|---------|-----------------------------------------------------------------------------------------|------------|
| `document_number` * | string | Número do documento de quem receberá as notificações (CPF/CNPJ) | 11 ou 14 |
| `name` * | string | Nome de quem receberá as notificações | 100 |
| `email` | string | E-mail para o qual serão enviadas as notificações | 320 |
| `phone` | object | Telefone de contato para o qual serão enviadas as notificações | **[Objeto phone](#objeto-phone)** |
| `send_2_way` * | boolean | Enviar segunda via | - |
| `send_before_due_date` * | boolean | Enviar notificação ao pagador antes da data de vencimento | - |
| `send_after_due_date` * | boolean | Enviar notificação ao pagador quando o boleto vencer | - |
| `send_on_protest` * | boolean | Enviar notificação ao entrar em fluxo de protesto | - |
## Response
STATUS 201
Response Body: Boleto registrado
```json
{
"request_control_key": "6e290347-330d-4b3a-8ebb-2ac217ad6eb3",
"bank_slip_key": "8cb70dea-9fb0-4a68-9572-99a72849c8d6",
"bank_slip_status": "registered",
"our_number": 92580722204,
"barcode": "32998995900000892812147469258072220406456140",
"digitable_line": "32992147466925807222704064561402899590000089281",
"qr_code_data": {
"qr_code_key": "bc5cb30c-8f98-4273-b405-3546da1d8d7a",
"pix_key": "06797774-e050-419e-a91a-c64c919b52c7",
"receiver_conciliation_id": "01GVGV9NXBCY287Z6CJ4S0ENW9",
"url": "00020126830014br.gov.bcb.pix2561qrcode.qitech.app/bacen/cobv/58fd5103a8e64bbbab2fd49b0bd580145204000053039865802BR5925GONNFUNDODEINVESTIMENTOEM6012RiodeJaneiro6107226401262070503***6304EA0D",
"image": "/9j/4AAQSkZJRgABAQAAAQABAAD/2wBDAAgGBgcGBQgHBwcJCQgKDBQNDAsLDBkSEw8UHRofHh0aHBwgJC4nICIsIxwcKDcpLDAxNDQ0Hyc5PTgyPC4zNDL/wAALCAD0APQBAREA/8QAHwAAAQUBAQEBAQEAAAAAAAAAAAECAwQFBgcICQoL/8QAtRAAAgEDAwIEAwUFBAQAAAF9AQIDAAQRBRIhMUEGE1FhByJxFDKBkaEII0KxwRVS0fAkM2JyggkKFhcYGRolJicoKSo0NTY3ODk6Q0RFRkdISUpTVFVWV1hZWmNkZWZnaGlqc3R1dnd4eXqDhIWGh4iJipKTlJWWl5iZmqKjpKWmp6ipqrKztLW2t7i5usLDxMXGx8jJytLT1NXW19jZ2uHi4+Tl5ufo6erx8vP09fb3+Pn6/9oACAEBAAA/APf6KKKKKKKKKKKKKKKKKKKKKKKKKKKKKKKKKKKKKKKKKKKKKKKKKKKKKKKKKKKKKKK+QPhl8Mv+Fjf2p/xN/wCz/sHlf8u3m79+/wD21xjZ79a7/wD4Zl/6m7/ym/8A22j/AIZl/wCpu/8AKb/9to/Zl/5mn/t0/wDa1egfE34Zf8LG/sv/AIm/9n/YPN/5dvN379n+2uMbPfrXgHwy+GX/AAsb+1P+Jv8A2f8AYPK/5dvN379/+2uMbPfrR8Tfib/wsb+y/wDiUf2f9g83/l583fv2f7C4xs9+td//AMm5/wDUw/27/wBunkeR/wB/N27zvbG3vnjwCvr/AOJvxN/4Vz/Zf/Eo/tD7f5v/AC8+Vs2bP9hs53+3SvkCvf8A9mX/AJmn/t0/9rUf8m5/9TD/AG7/ANunkeR/383bvO9sbe+ePQPhl8Mv+Fc/2p/xN/7Q+3+V/wAu3lbNm/8A22znf7dK8A+GXxN/4Vz/AGp/xKP7Q+3+V/y8+Vs2b/8AYbOd/t0o+GXxN/4Vz/an/Eo/tD7f5X/Lz5WzZv8A9hs53+3Svf8A4m/DL/hY39l/8Tf+z/sHm/8ALt5u/fs/21xjZ79a8/8A+GZf+pu/8pv/ANtr0D4ZfE3/AIWN/an/ABKP7P8AsHlf8vPm79+//YXGNnv1rwD4ZfE3/hXP9qf8Sj+0Pt/lf8vPlbNm/wD2Gznf7dK7/wD4aa/6lH/ypf8A2quA+GXxN/4Vz/an/Eo/tD7f5X/Lz5WzZv8A9hs53+3Svr+vkD4ZfDL/AIWN/an/ABN/7P8AsHlf8u3m79+//bXGNnv1rv8A/hmX/qbv/Kb/APbaP+GZf+pu/wDKb/8AbaP2Zf8Amaf+3T/2tX0BRRRXz/8Asy/8zT/26f8AtavAK9//AGZf+Zp/7dP/AGtR+zL/AMzT/wBun/tavQPib8Mv+Fjf2X/xN/7P+web/wAu3m79+z/bXGNnv1rz/wDZl/5mn/t0/wDa1cB8Mvib/wAK5/tT/iUf2h9v8r/l58rZs3/7DZzv9ule/wDwy+Jv/Cxv7U/4lH9n/YPK/wCXnzd+/f8A7C4xs9+teAfE34Zf8K5/sv8A4m/9ofb/ADf+XbytmzZ/ttnO/wBule//ABN+Jv8Awrn+y/8AiUf2h9v83/l58rZs2f7DZzv9uleAfDL4Zf8ACxv7U/4m/wDZ/wBg8r/l283fv3/7a4xs9+tHxN+GX/Cuf7L/AOJv/aH2/wA3/l28rZs2f7bZzv8AbpXv/wAMvhl/wrn+1P8Aib/2h9v8r/l28rZs3/7bZzv9ulef/tNf8yt/29/+0a9A+GXxN/4WN/an/Eo/s/7B5X/Lz5u/fv8A9hcY2e/WvP8A/k3P/qYf7d/7dPI8j/v5u3ed7Y2988cB8Tfhl/wrn+y/+Jv/AGh9v83/AJdvK2bNn+22c7/bpXf/APDTX/Uo/wDlS/8AtVcB8Tfhl/wrn+y/+Jv/AGh9v83/AJdvK2bNn+22c7/bpX1/Xz//AMm5/wDUw/27/wBunkeR/wB/N27zvbG3vng/5OM/6l7+wv8At78/z/8Av3t2+T753dsc+gfDL4m/8LG/tT/iUf2f9g8r/l583fv3/wCwuMbPfrXn/wCzL/zNP/bp/wC1q8Ar3/8AZl/5mn/t0/8Aa1H7Mv8AzNP/AG6f+1q+gKKKK+f/ANmX/maf+3T/ANrUf8My/wDU3f8AlN/+216B8Mvhl/wrn+1P+Jv/AGh9v8r/AJdvK2bN/wDttnO/26V5/wDsy/8AM0/9un/taj/k4z/qXv7C/wC3vz/P/wC/e3b5Pvnd2xyf8nGf9S9/YX/b35/n/wDfvbt8n3zu7Y5P2mv+ZW/7e/8A2jR+zL/zNP8A26f+1qP+Tc/+ph/t3/t08jyP+/m7d53tjb3zx4BXv/7TX/Mrf9vf/tGj/k3P/qYf7d/7dPI8j/v5u3ed7Y2988cB8Mvhl/wsb+1P+Jv/AGf9g8r/AJdvN379/wDtrjGz3613/wDwzL/1N3/lN/8AttH7Mv8AzNP/AG6f+1q4D4m/DL/hXP8AZf8AxN/7Q+3+b/y7eVs2bP8AbbOd/t0rv/8Ahpr/AKlH/wAqX/2qj/k4z/qXv7C/7e/P8/8A797dvk++d3bHJ/ybn/1MP9u/9unkeR/383bvO9sbe+ePQPhl8Mv+Fc/2p/xN/wC0Pt/lf8u3lbNm/wD22znf7dKPib8Mv+Fjf2X/AMTf+z/sHm/8u3m79+z/AG1xjZ79a8//AGZf+Zp/7dP/AGtX0BXz/wDsy/8AM0/9un/taj/hmX/qbv8Aym//AG2vQPhl8Mv+Fc/2p/xN/wC0Pt/lf8u3lbNm/wD22znf7dK8/wD2Zf8Amaf+3T/2tX0BRRRXz/8A8My/9Td/5Tf/ALbR/wAMy/8AU3f+U3/7bR/wzL/1N3/lN/8AttegfDL4Zf8ACuf7U/4m/wDaH2/yv+Xbytmzf/ttnO/26V5//wAm5/8AUw/27/26eR5H/fzdu872xt7549A+GXwy/wCFc/2p/wATf+0Pt/lf8u3lbNm//bbOd/t0rz/9mX/maf8At0/9rVwHwy+Jv/Cuf7U/4lH9ofb/ACv+Xnytmzf/ALDZzv8AbpR8Mvib/wAK5/tT/iUf2h9v8r/l58rZs3/7DZzv9ulHwy+Jv/Cuf7U/4lH9ofb/ACv+Xnytmzf/ALDZzv8AbpXf/sy/8zT/ANun/tavQPhl8Mv+Fc/2p/xN/wC0Pt/lf8u3lbNm/wD22znf7dK8/wD2Zf8Amaf+3T/2tXoHwy+GX/Cuf7U/4m/9ofb/ACv+Xbytmzf/ALbZzv8AbpXgHwy+Jv8Awrn+1P8AiUf2h9v8r/l58rZs3/7DZzv9uld/+zL/AMzT/wBun/tavQPhl8Mv+Fc/2p/xN/7Q+3+V/wAu3lbNm/8A22znf7dK8A+GXxN/4Vz/AGp/xKP7Q+3+V/y8+Vs2b/8AYbOd/t0o+GXxN/4Vz/an/Eo/tD7f5X/Lz5WzZv8A9hs53+3Su/8A2Zf+Zp/7dP8A2tR/ybn/ANTD/bv/AG6eR5H/AH83bvO9sbe+eD9mX/maf+3T/wBrUfsy/wDM0/8Abp/7Wo/4Zl/6m7/ym/8A22j/AIZl/wCpu/8AKb/9to/4Zl/6m7/ym/8A22vQPhl8Mv8AhXP9qf8AE3/tD7f5X/Lt5WzZv/22znf7dK9Aooor5/8A2Zf+Zp/7dP8A2tXAfE34m/8ACxv7L/4lH9n/AGDzf+Xnzd+/Z/sLjGz360fE34m/8LG/sv8A4lH9n/YPN/5efN379n+wuMbPfrXv/wAMvhl/wrn+1P8Aib/2h9v8r/l28rZs3/7bZzv9ulfIFFegfDL4m/8ACuf7U/4lH9ofb/K/5efK2bN/+w2c7/bpXf8A7TX/ADK3/b3/AO0a9A+GXxN/4WN/an/Eo/s/7B5X/Lz5u/fv/wBhcY2e/WvAPib8Mv8AhXP9l/8AE3/tD7f5v/Lt5WzZs/22znf7dKPib8Mv+Fc/2X/xN/7Q+3+b/wAu3lbNmz/bbOd/t0rv/wBmX/maf+3T/wBrVwHxN+GX/Cuf7L/4m/8AaH2/zf8Al28rZs2f7bZzv9ulHxN+GX/Cuf7L/wCJv/aH2/zf+XbytmzZ/ttnO/26V3//AAzL/wBTd/5Tf/ttH7TX/Mrf9vf/ALRrgPhl8Tf+Fc/2p/xKP7Q+3+V/y8+Vs2b/APYbOd/t0o+Jvwy/4Vz/AGX/AMTf+0Pt/m/8u3lbNmz/AG2znf7dK7//AJOM/wCpe/sL/t78/wA//v3t2+T753dscn/Juf8A1MP9u/8Abp5Hkf8Afzdu872xt7548Ar3/wD5Nz/6mH+3f+3TyPI/7+bt3ne2NvfPHAfE34Zf8K5/sv8A4m/9ofb/ADf+XbytmzZ/ttnO/wBuld/+01/zK3/b3/7Rr6Aorz/4ZfE3/hY39qf8Sj+z/sHlf8vPm79+/wD2FxjZ79a9Aooor5A+Jvwy/wCFc/2X/wATf+0Pt/m/8u3lbNmz/bbOd/t0o+JvxN/4WN/Zf/Eo/s/7B5v/AC8+bv37P9hcY2e/Wu//AGmv+ZW/7e//AGjXoHwy+GX/AArn+1P+Jv8A2h9v8r/l28rZs3/7bZzv9ulHwy+Jv/Cxv7U/4lH9n/YPK/5efN379/8AsLjGz3615/8A8nGf9S9/YX/b35/n/wDfvbt8n3zu7Y5+gK+QPib8Tf8AhY39l/8AEo/s/wCweb/y8+bv37P9hcY2e/Wvf/hl8Tf+Fjf2p/xKP7P+weV/y8+bv37/APYXGNnv1rz/AP4aa/6lH/ypf/aq9A+Jvwy/4WN/Zf8AxN/7P+web/y7ebv37P8AbXGNnv1r0CvkD4m/DL/hXP8AZf8AxN/7Q+3+b/y7eVs2bP8AbbOd/t0rv/8Ahpr/AKlH/wAqX/2qj/hmX/qbv/Kb/wDbaP8Ak3P/AKmH+3f+3TyPI/7+bt3ne2NvfPHoHxN+Jv8Awrn+y/8AiUf2h9v83/l58rZs2f7DZzv9ulHwy+GX/Cuf7U/4m/8AaH2/yv8Al28rZs3/AO22c7/bpXn/AO01/wAyt/29/wDtGj/hpr/qUf8Aypf/AGqj/k4z/qXv7C/7e/P8/wD797dvk++d3bHJ/wANNf8AUo/+VL/7VXAfE34Zf8K5/sv/AIm/9ofb/N/5dvK2bNn+22c7/bpR8Mvib/wrn+1P+JR/aH2/yv8Al58rZs3/AOw2c7/bpR8Mvhl/wsb+1P8Aib/2f9g8r/l283fv3/7a4xs9+tHwy+Jv/Cuf7U/4lH9ofb/K/wCXnytmzf8A7DZzv9ulfX9FFFFfP/8AwzL/ANTd/wCU3/7bXoHwy+GX/Cuf7U/4m/8AaH2/yv8Al28rZs3/AO22c7/bpXgHwy+GX/Cxv7U/4m/9n/YPK/5dvN379/8AtrjGz3613/8AwzL/ANTd/wCU3/7bR/w01/1KP/lS/wDtVegfDL4Zf8K5/tT/AIm/9ofb/K/5dvK2bN/+22c7/bpR8Mvib/wsb+1P+JR/Z/2Dyv8Al583fv3/AOwuMbPfrR8Mvhl/wrn+1P8Aib/2h9v8r/l28rZs3/7bZzv9uleAfE34Zf8ACuf7L/4m/wDaH2/zf+XbytmzZ/ttnO/26V3/AO01/wAyt/29/wDtGuA+GXwy/wCFjf2p/wATf+z/ALB5X/Lt5u/fv/21xjZ79a9/+Jvwy/4WN/Zf/E3/ALP+web/AMu3m79+z/bXGNnv1rwD4m/DL/hXP9l/8Tf+0Pt/m/8ALt5WzZs/22znf7dK9/8Aib8Tf+Fc/wBl/wDEo/tD7f5v/Lz5WzZs/wBhs53+3SvP/wBpr/mVv+3v/wBo0f8AJuf/AFMP9u/9unkeR/383bvO9sbe+eD9mX/maf8At0/9rV4BXoHwy+Jv/Cuf7U/4lH9ofb/K/wCXnytmzf8A7DZzv9uld/8A8m5/9TD/AG7/ANunkeR/383bvO9sbe+eOA+GXxN/4Vz/AGp/xKP7Q+3+V/y8+Vs2b/8AYbOd/t0rv/8Ak3P/AKmH+3f+3TyPI/7+bt3ne2NvfPHoHxN+GX/Cxv7L/wCJv/Z/2Dzf+Xbzd+/Z/trjGz3614B8Mvib/wAK5/tT/iUf2h9v8r/l58rZs3/7DZzv9ule/wDxN+Jv/Cuf7L/4lH9ofb/N/wCXnytmzZ/sNnO/26UfE34m/wDCuf7L/wCJR/aH2/zf+XnytmzZ/sNnO/26V5/+zL/zNP8A26f+1q+gKKKK+f8A/k3P/qYf7d/7dPI8j/v5u3ed7Y2988H/ACbn/wBTD/bv/bp5Hkf9/N27zvbG3vnjgPib8Mv+Fc/2X/xN/wC0Pt/m/wDLt5WzZs/22znf7dK9/wDhl8Mv+Fc/2p/xN/7Q+3+V/wAu3lbNm/8A22znf7dKPib8Mv8AhY39l/8AE3/s/wCweb/y7ebv37P9tcY2e/WvAPib8Mv+Fc/2X/xN/wC0Pt/m/wDLt5WzZs/22znf7dK8/r3/APaa/wCZW/7e/wD2jXAfDL4m/wDCuf7U/wCJR/aH2/yv+Xnytmzf/sNnO/26V7/8Mvhl/wAK5/tT/ib/ANofb/K/5dvK2bN/+22c7/bpXn//AA01/wBSj/5Uv/tVegfE34m/8K5/sv8A4lH9ofb/ADf+XnytmzZ/sNnO/wBulHxN+Jv/AArn+y/+JR/aH2/zf+XnytmzZ/sNnO/26V5/+01/zK3/AG9/+0aP2Zf+Zp/7dP8A2tR+zL/zNP8A26f+1qP+TjP+pe/sL/t78/z/APv3t2+T753dsc+AV7/+zL/zNP8A26f+1q9A+GXwy/4Vz/an/E3/ALQ+3+V/y7eVs2b/APbbOd/t0rwD4ZfDL/hY39qf8Tf+z/sHlf8ALt5u/fv/ANtcY2e/Wvf/AIm/E3/hXP8AZf8AxKP7Q+3+b/y8+Vs2bP8AYbOd/t0rwD4m/DL/AIVz/Zf/ABN/7Q+3+b/y7eVs2bP9ts53+3Su/wD2mv8AmVv+3v8A9o1wHwy+Jv8Awrn+1P8AiUf2h9v8r/l58rZs3/7DZzv9ulHxN+GX/Cuf7L/4m/8AaH2/zf8Al28rZs2f7bZzv9ule/8Awy+GX/Cuf7U/4m/9ofb/ACv+Xbytmzf/ALbZzv8AbpXoFFFFfIHwy+GX/Cxv7U/4m/8AZ/2Dyv8Al283fv3/AO2uMbPfrXf/APDMv/U3f+U3/wC20f8AJxn/AFL39hf9vfn+f/3727fJ987u2OfQPhl8Mv8AhXP9qf8AE3/tD7f5X/Lt5WzZv/22znf7dK8//wCGmv8AqUf/ACpf/aq8Ar3/AP4aa/6lH/ypf/aq9A+GXwy/4Vz/AGp/xN/7Q+3+V/y7eVs2b/8AbbOd/t0rwD4m/DL/AIVz/Zf/ABN/7Q+3+b/y7eVs2bP9ts53+3Svf/ib8Mv+Fjf2X/xN/wCz/sHm/wDLt5u/fs/21xjZ79a8/wD+TjP+pe/sL/t78/z/APv3t2+T753dsc+gfDL4m/8ACxv7U/4lH9n/AGDyv+Xnzd+/f/sLjGz360fDL4Zf8K5/tT/ib/2h9v8AK/5dvK2bN/8AttnO/wBulef/APJxn/Uvf2F/29+f5/8A3727fJ987u2OT/hpr/qUf/Kl/wDaqP2mv+ZW/wC3v/2jR+zL/wAzT/26f+1q8Ar3/wD4Zl/6m7/ym/8A22vQPhl8Tf8AhY39qf8AEo/s/wCweV/y8+bv37/9hcY2e/Wj4m/E3/hXP9l/8Sj+0Pt/m/8ALz5WzZs/2Gznf7dKPib8Mv8AhY39l/8AE3/s/wCweb/y7ebv37P9tcY2e/Wj4ZfE3/hY39qf8Sj+z/sHlf8ALz5u/fv/ANhcY2e/Wj4ZfDL/AIVz/an/ABN/7Q+3+V/y7eVs2b/9ts53+3SvQK+f/wDk4z/qXv7C/wC3vz/P/wC/e3b5Pvnd2xz9AUUUUV5/8Mvhl/wrn+1P+Jv/AGh9v8r/AJdvK2bN/wDttnO/26V5/wD8m5/9TD/bv/bp5Hkf9/N27zvbG3vnjwCvQPib8Mv+Fc/2X/xN/wC0Pt/m/wDLt5WzZs/22znf7dK7/wD5Nz/6mH+3f+3TyPI/7+bt3ne2NvfPHAfDL4m/8K5/tT/iUf2h9v8AK/5efK2bN/8AsNnO/wBulHwy+GX/AAsb+1P+Jv8A2f8AYPK/5dvN379/+2uMbPfrXf8A7TX/ADK3/b3/AO0a4D4m/DL/AIVz/Zf/ABN/7Q+3+b/y7eVs2bP9ts53+3Sj4ZfDL/hY39qf8Tf+z/sHlf8ALt5u/fv/ANtcY2e/Wu//AGmv+ZW/7e//AGjXoHxN+GX/AAsb+y/+Jv8A2f8AYPN/5dvN379n+2uMbPfrXoFfIHwy+Jv/AArn+1P+JR/aH2/yv+Xnytmzf/sNnO/26UfDL4Zf8LG/tT/ib/2f9g8r/l283fv3/wC2uMbPfrXf/wDDTX/Uo/8AlS/+1Ufsy/8AM0/9un/tavAK9A+GXwy/4WN/an/E3/s/7B5X/Lt5u/fv/wBtcY2e/Wu//wCGmv8AqUf/ACpf/aq4D4ZfE3/hXP8Aan/Eo/tD7f5X/Lz5WzZv/wBhs53+3Su//wCTjP8AqXv7C/7e/P8AP/797dvk++d3bHPoHxN+Jv8Awrn+y/8AiUf2h9v83/l58rZs2f7DZzv9ulHxN+Jv/Cuf7L/4lH9ofb/N/wCXnytmzZ/sNnO/26UfDL4m/wDCxv7U/wCJR/Z/2Dyv+Xnzd+/f/sLjGz360fE34m/8K5/sv/iUf2h9v83/AJefK2bNn+w2c7/bpR8Mvib/AMLG/tT/AIlH9n/YPK/5efN379/+wuMbPfrXoFFFFfIHwy+Jv/Cuf7U/4lH9ofb/ACv+Xnytmzf/ALDZzv8AbpX1/XwBXoHxN+GX/Cuf7L/4m/8AaH2/zf8Al28rZs2f7bZzv9ule/8Awy+Jv/Cxv7U/4lH9n/YPK/5efN379/8AsLjGz360fE34m/8ACuf7L/4lH9ofb/N/5efK2bNn+w2c7/bpR8Mvhl/wrn+1P+Jv/aH2/wAr/l28rZs3/wC22c7/AG6V5/8Asy/8zT/26f8AtauA+JvxN/4WN/Zf/Eo/s/7B5v8Ay8+bv37P9hcY2e/Wvf8A4m/E3/hXP9l/8Sj+0Pt/m/8ALz5WzZs/2Gznf7dK8A+JvxN/4WN/Zf8AxKP7P+web/y8+bv37P8AYXGNnv1r3/4m/E3/AIVz/Zf/ABKP7Q+3+b/y8+Vs2bP9hs53+3SvP/8Ak3P/AKmH+3f+3TyPI/7+bt3ne2NvfPB/w01/1KP/AJUv/tVegfE34m/8K5/sv/iUf2h9v83/AJefK2bNn+w2c7/bpXn/AO01/wAyt/29/wDtGj/hpr/qUf8Aypf/AGqvoCvkD4ZfE3/hXP8Aan/Eo/tD7f5X/Lz5WzZv/wBhs53+3Svf/ib8Tf8AhXP9l/8AEo/tD7f5v/Lz5WzZs/2Gznf7dK8//wCGZf8Aqbv/ACm//baP2mv+ZW/7e/8A2jR/ybn/ANTD/bv/AG6eR5H/AH83bvO9sbe+ePQPib8Tf+Fc/wBl/wDEo/tD7f5v/Lz5WzZs/wBhs53+3SvAPhl8Tf8AhXP9qf8AEo/tD7f5X/Lz5WzZv/2Gznf7dK9/+GXxN/4WN/an/Eo/s/7B5X/Lz5u/fv8A9hcY2e/Wj4ZfE3/hY39qf8Sj+z/sHlf8vPm79+//AGFxjZ79a9Aoooor5/8A2Zf+Zp/7dP8A2tR/wzL/ANTd/wCU3/7bR/ybn/1MP9u/9unkeR/383bvO9sbe+ePQPib8Tf+Fc/2X/xKP7Q+3+b/AMvPlbNmz/YbOd/t0o+JvxN/4Vz/AGX/AMSj+0Pt/m/8vPlbNmz/AGGznf7dK8A+Jvwy/wCFc/2X/wATf+0Pt/m/8u3lbNmz/bbOd/t0r3/4m/DL/hY39l/8Tf8As/7B5v8Ay7ebv37P9tcY2e/Wj4m/E3/hXP8AZf8AxKP7Q+3+b/y8+Vs2bP8AYbOd/t0r5Ar0D4ZfE3/hXP8Aan/Eo/tD7f5X/Lz5WzZv/wBhs53+3Su//wCGmv8AqUf/ACpf/aq4D4ZfE3/hXP8Aan/Eo/tD7f5X/Lz5WzZv/wBhs53+3Su//aa/5lb/ALe//aNcB8Mvhl/wsb+1P+Jv/Z/2Dyv+Xbzd+/f/ALa4xs9+tHxN+Jv/AAsb+y/+JR/Z/wBg83/l583fv2f7C4xs9+te/wDwy+GX/Cuf7U/4m/8AaH2/yv8Al28rZs3/AO22c7/bpXgHwy+GX/Cxv7U/4m/9n/YPK/5dvN379/8AtrjGz360fE34Zf8ACuf7L/4m/wDaH2/zf+XbytmzZ/ttnO/26V5/Xv8A+01/zK3/AG9/+0a4D4ZfDL/hY39qf8Tf+z/sHlf8u3m79+//AG1xjZ79a9/+GXxN/wCFjf2p/wASj+z/ALB5X/Lz5u/fv/2FxjZ79aPhl8Mv+Fc/2p/xN/7Q+3+V/wAu3lbNm/8A22znf7dK+QK9/wD2Zf8Amaf+3T/2tX0BRRRRXyB8Tfhl/wAK5/sv/ib/ANofb/N/5dvK2bNn+22c7/bpXf8A/DTX/Uo/+VL/AO1VwHwy+GX/AAsb+1P+Jv8A2f8AYPK/5dvN379/+2uMbPfrXf8A/DMv/U3f+U3/AO21wHwy+Jv/AArn+1P+JR/aH2/yv+Xnytmzf/sNnO/26UfDL4m/8K5/tT/iUf2h9v8AK/5efK2bN/8AsNnO/wBule//ABN+Jv8Awrn+y/8AiUf2h9v83/l58rZs2f7DZzv9uleAfE34m/8ACxv7L/4lH9n/AGDzf+Xnzd+/Z/sLjGz3615/XoHxN+Jv/Cxv7L/4lH9n/YPN/wCXnzd+/Z/sLjGz3613/wC01/zK3/b3/wC0a9A+GXwy/wCFc/2p/wATf+0Pt/lf8u3lbNm//bbOd/t0rwD4ZfDL/hY39qf8Tf8As/7B5X/Lt5u/fv8A9tcY2e/Wu/8A+GZf+pu/8pv/ANtrgPhl8Mv+Fjf2p/xN/wCz/sHlf8u3m79+/wD21xjZ79a8/r0D4ZfDL/hY39qf8Tf+z/sHlf8ALt5u/fv/ANtcY2e/Wj4m/E3/AIWN/Zf/ABKP7P8AsHm/8vPm79+z/YXGNnv1rv8A/hpr/qUf/Kl/9qr0D4m/DL/hY39l/wDE3/s/7B5v/Lt5u/fs/wBtcY2e/WvP/wBmX/maf+3T/wBrV6B8Mvib/wALG/tT/iUf2f8AYPK/5efN379/+wuMbPfrXgHwy+GX/Cxv7U/4m/8AZ/2Dyv8Al283fv3/AO2uMbPfrXf/APDMv/U3f+U3/wC20fsy/wDM0/8Abp/7WrgPib8Mv+Fc/wBl/wDE3/tD7f5v/Lt5WzZs/wBts53+3Svf/hl8Mv8AhXP9qf8AE3/tD7f5X/Lt5WzZv/22znf7dK9Aooorz/4m/DL/AIWN/Zf/ABN/7P8AsHm/8u3m79+z/bXGNnv1rwD4ZfE3/hXP9qf8Sj+0Pt/lf8vPlbNm/wD2Gznf7dK7/wDZl/5mn/t0/wDa1egfDL4Zf8K5/tT/AIm/9ofb/K/5dvK2bN/+22c7/bpXgHwy+GX/AAsb+1P+Jv8A2f8AYPK/5dvN379/+2uMbPfrR8Tfhl/wrn+y/wDib/2h9v8AN/5dvK2bNn+22c7/AG6V3/7TX/Mrf9vf/tGuA+GXxN/4Vz/an/Eo/tD7f5X/AC8+Vs2b/wDYbOd/t0o+Jvwy/wCFc/2X/wATf+0Pt/m/8u3lbNmz/bbOd/t0r6/rz/4ZfDL/AIVz/an/ABN/7Q+3+V/y7eVs2b/9ts53+3Sj4ZfDL/hXP9qf8Tf+0Pt/lf8ALt5WzZv/ANts53+3SvP/ANmX/maf+3T/ANrV6B8Mvhl/wrn+1P8Aib/2h9v8r/l28rZs3/7bZzv9uleAfDL4m/8ACuf7U/4lH9ofb/K/5efK2bN/+w2c7/bpX1/RRXyB8Tfib/wsb+y/+JR/Z/2Dzf8Al583fv2f7C4xs9+td/8A8m5/9TD/AG7/ANunkeR/383bvO9sbe+ePAK+v/ib8Tf+Fc/2X/xKP7Q+3+b/AMvPlbNmz/YbOd/t0rz/APZl/wCZp/7dP/a1egfDL4Zf8K5/tT/ib/2h9v8AK/5dvK2bN/8AttnO/wBuleAfDL4m/wDCuf7U/wCJR/aH2/yv+Xnytmzf/sNnO/26V7/8Tfhl/wALG/sv/ib/ANn/AGDzf+Xbzd+/Z/trjGz3615/+zL/AMzT/wBun/tavoCiiivP/ib8Tf8AhXP9l/8AEo/tD7f5v/Lz5WzZs/2Gznf7dK8//wCTc/8AqYf7d/7dPI8j/v5u3ed7Y2988H/DMv8A1N3/AJTf/ttH/DMv/U3f+U3/AO214BXv/wDwzL/1N3/lN/8AttH/AA01/wBSj/5Uv/tVH/DMv/U3f+U3/wC214BXoHwy+GX/AAsb+1P+Jv8A2f8AYPK/5dvN379/+2uMbPfrXf8A7Mv/ADNP/bp/7Wr0D4ZfE3/hY39qf8Sj+z/sHlf8vPm79+//AGFxjZ79a8//AOGZf+pu/wDKb/8Aba4D4ZfDL/hY39qf8Tf+z/sHlf8ALt5u/fv/ANtcY2e/Wj4ZfDL/AIWN/an/ABN/7P8AsHlf8u3m79+//bXGNnv1r3/4m/DL/hY39l/8Tf8As/7B5v8Ay7ebv37P9tcY2e/WvP8A9mX/AJmn/t0/9rV9AV8//wDDMv8A1N3/AJTf/ttH/Jxn/Uvf2F/29+f5/wD3727fJ987u2OfQPib8Mv+Fjf2X/xN/wCz/sHm/wDLt5u/fs/21xjZ79a9Ar5A+Jvwy/4Vz/Zf/E3/ALQ+3+b/AMu3lbNmz/bbOd/t0o+Jvwy/4Vz/AGX/AMTf+0Pt/m/8u3lbNmz/AG2znf7dK9/+GXwy/wCFc/2p/wATf+0Pt/lf8u3lbNm//bbOd/t0rz//AJOM/wCpe/sL/t78/wA//v3t2+T753dscn7Mv/M0/wDbp/7Wr6Aooorz/wCGXwy/4Vz/AGp/xN/7Q+3+V/y7eVs2b/8AbbOd/t0rz/8A4Zl/6m7/AMpv/wBto/Zl/wCZp/7dP/a1H/Juf/Uw/wBu/wDbp5Hkf9/N27zvbG3vng/Zl/5mn/t0/wDa1H/Juf8A1MP9u/8Abp5Hkf8Afzdu872xt7544D4ZfDL/AIWN/an/ABN/7P8AsHlf8u3m79+//bXGNnv1o+GXwy/4WN/an/E3/s/7B5X/AC7ebv37/wDbXGNnv1o+JvxN/wCFjf2X/wASj+z/ALB5v/Lz5u/fs/2FxjZ79aPhl8Mv+Fjf2p/xN/7P+weV/wAu3m79+/8A21xjZ79a7/8A5OM/6l7+wv8At78/z/8Av3t2+T753dsc8B8Mvib/AMK5/tT/AIlH9ofb/K/5efK2bN/+w2c7/bpXv/xN+GX/AAsb+y/+Jv8A2f8AYPN/5dvN379n+2uMbPfrXn//AA01/wBSj/5Uv/tVegfDL4m/8LG/tT/iUf2f9g8r/l583fv3/wCwuMbPfrXn/wCzL/zNP/bp/wC1q4D4ZfE3/hXP9qf8Sj+0Pt/lf8vPlbNm/wD2Gznf7dKPib8Mv+Fc/wBl/wDE3/tD7f5v/Lt5WzZs/wBts53+3Su//Zl/5mn/ALdP/a1fQFef/E34Zf8ACxv7L/4m/wDZ/wBg83/l283fv2f7a4xs9+tef/8ADTX/AFKP/lS/+1VwHxN+GX/Cuf7L/wCJv/aH2/zf+XbytmzZ/ttnO/26V5/Xv/8AwzL/ANTd/wCU3/7bR/ybn/1MP9u/9unkeR/383bvO9sbe+eD9mX/AJmn/t0/9rV9AUUUV8AUV7//AMnGf9S9/YX/AG9+f5//AH727fJ987u2OfQPhl8Mv+Fc/wBqf8Tf+0Pt/lf8u3lbNm//AG2znf7dK8A+Jvwy/wCFc/2X/wATf+0Pt/m/8u3lbNmz/bbOd/t0rv8A9pr/AJlb/t7/APaNH/DMv/U3f+U3/wC20f8ADMv/AFN3/lN/+216B8Mvhl/wrn+1P+Jv/aH2/wAr/l28rZs3/wC22c7/AG6V5/8A8nGf9S9/YX/b35/n/wDfvbt8n3zu7Y59A+Jvwy/4WN/Zf/E3/s/7B5v/AC7ebv37P9tcY2e/WvQK+QPib8Tf+Fjf2X/xKP7P+web/wAvPm79+z/YXGNnv1o+Jvwy/wCFc/2X/wATf+0Pt/m/8u3lbNmz/bbOd/t0r3/4m/DL/hY39l/8Tf8As/7B5v8Ay7ebv37P9tcY2e/Wj4ZfE3/hY39qf8Sj+z/sHlf8vPm79+//AGFxjZ79a8//AOTjP+pe/sL/ALe/P8//AL97dvk++d3bHPoHxN+Jv/Cuf7L/AOJR/aH2/wA3/l58rZs2f7DZzv8AbpR8Mvhl/wAK5/tT/ib/ANofb/K/5dvK2bN/+22c7/bpXgHxN+GX/Cuf7L/4m/8AaH2/zf8Al28rZs2f7bZzv9uld/8A8My/9Td/5Tf/ALbXoHxN+Jv/AArn+y/+JR/aH2/zf+XnytmzZ/sNnO/26V5/+zL/AMzT/wBun/taj/k3P/qYf7d/7dPI8j/v5u3ed7Y2988fQFfP/wDybn/1MP8Abv8A26eR5H/fzdu872xt754+gKKKKK+AK+v/AIZfE3/hY39qf8Sj+z/sHlf8vPm79+//AGFxjZ79aPhl8Tf+Fjf2p/xKP7P+weV/y8+bv37/APYXGNnv1rwD4m/DL/hXP9l/8Tf+0Pt/m/8ALt5WzZs/22znf7dK9/8Ahl8Mv+Fc/wBqf8Tf+0Pt/lf8u3lbNm//AG2znf7dK8//AOGZf+pu/wDKb/8Aba8Ar6/+Jvwy/wCFjf2X/wATf+z/ALB5v/Lt5u/fs/21xjZ79aPib8Mv+Fjf2X/xN/7P+web/wAu3m79+z/bXGNnv1rz/wD4Zl/6m7/ym/8A22j/AJNz/wCph/t3/t08jyP+/m7d53tjb3zx6B8Mvhl/wrn+1P8Aib/2h9v8r/l28rZs3/7bZzv9ulHwy+GX/Cuf7U/4m/8AaH2/yv8Al28rZs3/AO22c7/bpXgHwy+Jv/Cuf7U/4lH9ofb/ACv+Xnytmzf/ALDZzv8AbpXv/wAMvib/AMLG/tT/AIlH9n/YPK/5efN379/+wuMbPfrXgHxN+GX/AArn+y/+Jv8A2h9v83/l28rZs2f7bZzv9uld/wD8NNf9Sj/5Uv8A7VX0BXyB8Mvhl/wsb+1P+Jv/AGf9g8r/AJdvN379/wDtrjGz3619f18//wDDTX/Uo/8AlS/+1V6B8Tfhl/wsb+y/+Jv/AGf9g83/AJdvN379n+2uMbPfrR8Mvib/AMLG/tT/AIlH9n/YPK/5efN379/+wuMbPfrR8Mvib/wsb+1P+JR/Z/2Dyv8Al583fv3/AOwuMbPfrR8Tfhl/wsb+y/8Aib/2f9g83/l283fv2f7a4xs9+tef/sy/8zT/ANun/taj9mX/AJmn/t0/9rV9AUUUV8//ALTX/Mrf9vf/ALRo/wCGZf8Aqbv/ACm//ba+gK+f/wDk3P8A6mH+3f8At08jyP8Av5u3ed7Y2988eAUV7/8A8NNf9Sj/AOVL/wC1Uf8AJuf/AFMP9u/9unkeR/383bvO9sbe+ePQPib8Mv8AhY39l/8AE3/s/wCweb/y7ebv37P9tcY2e/WvP/8Ak4z/AKl7+wv+3vz/AD/+/e3b5Pvnd2xzwHwy+Jv/AArn+1P+JR/aH2/yv+Xnytmzf/sNnO/26UfDL4Zf8LG/tT/ib/2f9g8r/l283fv3/wC2uMbPfrXv/wATfib/AMK5/sv/AIlH9ofb/N/5efK2bNn+w2c7/bpXn/7Mv/M0/wDbp/7Wr0D4ZfDL/hXP9qf8Tf8AtD7f5X/Lt5WzZv8A9ts53+3Sj4ZfDL/hXP8Aan/E3/tD7f5X/Lt5WzZv/wBts53+3SvAPib8Mv8AhXP9l/8AE3/tD7f5v/Lt5WzZs/22znf7dKPhl8Mv+Fjf2p/xN/7P+weV/wAu3m79+/8A21xjZ79a7/8AZl/5mn/t0/8Aa1cB8Mvib/wrn+1P+JR/aH2/yv8Al58rZs3/AOw2c7/bpR8Mvib/AMK5/tT/AIlH9ofb/K/5efK2bN/+w2c7/bpXf/8AJuf/AFMP9u/9unkeR/383bvO9sbe+eOA+Jvwy/4Vz/Zf/E3/ALQ+3+b/AMu3lbNmz/bbOd/t0o+GXxN/4Vz/AGp/xKP7Q+3+V/y8+Vs2b/8AYbOd/t0rv/8Ak3P/AKmH+3f+3TyPI/7+bt3ne2NvfPB/w01/1KP/AJUv/tVegfDL4m/8LG/tT/iUf2f9g8r/AJefN379/wDsLjGz3616BRRRRXyB8Tfhl/wrn+y/+Jv/AGh9v83/AJdvK2bNn+22c7/bpR8Mvib/AMK5/tT/AIlH9ofb/K/5efK2bN/+w2c7/bpXv/wy+GX/AArn+1P+Jv8A2h9v8r/l28rZs3/7bZzv9ulHxN+GX/Cxv7L/AOJv/Z/2Dzf+Xbzd+/Z/trjGz3615/8A8My/9Td/5Tf/ALbXoHxN+Jv/AArn+y/+JR/aH2/zf+XnytmzZ/sNnO/26V4B8Mvhl/wsb+1P+Jv/AGf9g8r/AJdvN379/wDtrjGz3617/wDDL4m/8LG/tT/iUf2f9g8r/l583fv3/wCwuMbPfrXgHxN+Jv8Awsb+y/8AiUf2f9g83/l583fv2f7C4xs9+te//DL4m/8ACxv7U/4lH9n/AGDyv+Xnzd+/f/sLjGz3614B8Tfhl/wrn+y/+Jv/AGh9v83/AJdvK2bNn+22c7/bpXv/AMTfhl/wsb+y/wDib/2f9g83/l283fv2f7a4xs9+tegV5/8AE34Zf8LG/sv/AIm/9n/YPN/5dvN379n+2uMbPfrR8Tfib/wrn+y/+JR/aH2/zf8Al58rZs2f7DZzv9ulef8A/Jxn/Uvf2F/29+f5/wD3727fJ987u2OfAK9A+GXxN/4Vz/an/Eo/tD7f5X/Lz5WzZv8A9hs53+3Svf8A4m/E3/hXP9l/8Sj+0Pt/m/8ALz5WzZs/2Gznf7dKPhl8Mv8AhXP9qf8AE3/tD7f5X/Lt5WzZv/22znf7dK9Ar5A+JvxN/wCFjf2X/wASj+z/ALB5v/Lz5u/fs/2FxjZ79aPhl8Mv+Fjf2p/xN/7P+weV/wAu3m79+/8A21xjZ79a9/8Aib8Tf+Fc/wBl/wDEo/tD7f5v/Lz5WzZs/wBhs53+3SvQK8/+GXwy/wCFc/2p/wATf+0Pt/lf8u3lbNm//bbOd/t0r0CiiivkD4ZfE3/hXP8Aan/Eo/tD7f5X/Lz5WzZv/wBhs53+3Su//wCGZf8Aqbv/ACm//ba+gK8/+GXwy/4Vz/an/E3/ALQ+3+V/y7eVs2b/APbbOd/t0rz/AP4Zl/6m7/ym/wD22vQPib8Tf+Fc/wBl/wDEo/tD7f5v/Lz5WzZs/wBhs53+3SvQK8/+Jvwy/wCFjf2X/wATf+z/ALB5v/Lt5u/fs/21xjZ79a8//Zl/5mn/ALdP/a1cB8Tfib/wsb+y/wDiUf2f9g83/l583fv2f7C4xs9+te//AAy+GX/Cuf7U/wCJv/aH2/yv+Xbytmzf/ttnO/26UfE34m/8K5/sv/iUf2h9v83/AJefK2bNn+w2c7/bpR8Tfhl/wsb+y/8Aib/2f9g83/l283fv2f7a4xs9+tef/wDJuf8A1MP9u/8Abp5Hkf8Afzdu872xt754P+TjP+pe/sL/ALe/P8//AL97dvk++d3bHPoHwy+GX/Cuf7U/4m/9ofb/ACv+Xbytmzf/ALbZzv8AbpR8Mvhl/wAK5/tT/ib/ANofb/K/5dvK2bN/+22c7/bpXn//AAzL/wBTd/5Tf/tteAUV9f8AxN+Jv/Cuf7L/AOJR/aH2/wA3/l58rZs2f7DZzv8AbpXgHxN+Jv8Awsb+y/8AiUf2f9g83/l583fv2f7C4xs9+tfX9FfIHwy+Jv8Awrn+1P8AiUf2h9v8r/l58rZs3/7DZzv9ulHwy+Jv/Cuf7U/4lH9ofb/K/wCXnytmzf8A7DZzv9ule/8Awy+Jv/Cxv7U/4lH9n/YPK/5efN379/8AsLjGz3616BRRRXyB8Tfhl/wrn+y/+Jv/AGh9v83/AJdvK2bNn+22c7/bpXf/APJxn/Uvf2F/29+f5/8A3727fJ987u2OT/hmX/qbv/Kb/wDbaP8Ak3P/AKmH+3f+3TyPI/7+bt3ne2NvfPB/wzL/ANTd/wCU3/7bR+01/wAyt/29/wDtGj9mX/maf+3T/wBrV6B8Mvhl/wAK5/tT/ib/ANofb/K/5dvK2bN/+22c7/bpXn//AAzL/wBTd/5Tf/ttH/Juf/Uw/wBu/wDbp5Hkf9/N27zvbG3vnjgPhl8Mv+Fjf2p/xN/7P+weV/y7ebv37/8AbXGNnv1r3/4ZfDL/AIVz/an/ABN/7Q+3+V/y7eVs2b/9ts53+3SvP/2Zf+Zp/wC3T/2tXoHxN+GX/Cxv7L/4m/8AZ/2Dzf8Al283fv2f7a4xs9+tef8A/Jxn/Uvf2F/29+f5/wD3727fJ987u2OfQPib8Mv+Fjf2X/xN/wCz/sHm/wDLt5u/fs/21xjZ79a8/wD+Gmv+pR/8qX/2quA+JvxN/wCFjf2X/wASj+z/ALB5v/Lz5u/fs/2FxjZ79a9/+Jvwy/4WN/Zf/E3/ALP+web/AMu3m79+z/bXGNnv1rwD4m/DL/hXP9l/8Tf+0Pt/m/8ALt5WzZs/22znf7dKPib8Mv8AhXP9l/8AE3/tD7f5v/Lt5WzZs/22znf7dK9/+JvxN/4Vz/Zf/Eo/tD7f5v8Ay8+Vs2bP9hs53+3SvP8A9pr/AJlb/t7/APaNH/Juf/Uw/wBu/wDbp5Hkf9/N27zvbG3vng/Zl/5mn/t0/wDa1eAV7/8Asy/8zT/26f8AtavoCiiiivP/AIm/DL/hY39l/wDE3/s/7B5v/Lt5u/fs/wBtcY2e/WvQK8/+GXwy/wCFc/2p/wATf+0Pt/lf8u3lbNm//bbOd/t0o+GXxN/4WN/an/Eo/s/7B5X/AC8+bv37/wDYXGNnv1o+Jvwy/wCFjf2X/wATf+z/ALB5v/Lt5u/fs/21xjZ79a8//aa/5lb/ALe//aNH/Jxn/Uvf2F/29+f5/wD3727fJ987u2OfAK9//wCTjP8AqXv7C/7e/P8AP/797dvk++d3bHJ/w01/1KP/AJUv/tVH/DMv/U3f+U3/AO21wHwy+GX/AAsb+1P+Jv8A2f8AYPK/5dvN379/+2uMbPfrXf8A/DMv/U3f+U3/AO214BXv/wC01/zK3/b3/wC0aP8Ak4z/AKl7+wv+3vz/AD/+/e3b5Pvnd2xyftNf8yt/29/+0a4D4ZfE3/hXP9qf8Sj+0Pt/lf8ALz5WzZv/ANhs53+3Svf/AIZfDL/hXP8Aan/E3/tD7f5X/Lt5WzZv/wBts53+3SvAPhl8Mv8AhY39qf8AE3/s/wCweV/y7ebv37/9tcY2e/Wu/wD+Tc/+ph/t3/t08jyP+/m7d53tjb3zxwHwy+GX/Cxv7U/4m/8AZ/2Dyv8Al283fv3/AO2uMbPfrXf/APDMv/U3f+U3/wC21wHwy+Jv/Cuf7U/4lH9ofb/K/wCXnytmzf8A7DZzv9ule/8AxN+Jv/Cuf7L/AOJR/aH2/wA3/l58rZs2f7DZzv8AbpR8Mvib/wALG/tT/iUf2f8AYPK/5efN379/+wuMbPfrXoFFFFfIHwy+GX/Cxv7U/wCJv/Z/2Dyv+Xbzd+/f/trjGz3613//AAzL/wBTd/5Tf/ttH/DMv/U3f+U3/wC20fsy/wDM0/8Abp/7Wo/5OM/6l7+wv+3vz/P/AO/e3b5Pvnd2xyf8NNf9Sj/5Uv8A7VXAfDL4m/8ACuf7U/4lH9ofb/K/5efK2bN/+w2c7/bpR8Mvhl/wsb+1P+Jv/Z/2Dyv+Xbzd+/f/ALa4xs9+td//AMNNf9Sj/wCVL/7VR/ybn/1MP9u/9unkeR/383bvO9sbe+ePAK9//Zl/5mn/ALdP/a1H7Mv/ADNP/bp/7Wr0D4ZfDL/hXP8Aan/E3/tD7f5X/Lt5WzZv/wBts53+3SvAPhl8Mv8AhY39qf8AE3/s/wCweV/y7ebv37/9tcY2e/WvP69//Zl/5mn/ALdP/a1H7Mv/ADNP/bp/7Wo/aa/5lb/t7/8AaNegfDL4m/8ACxv7U/4lH9n/AGDyv+Xnzd+/f/sLjGz3615/+zL/AMzT/wBun/taj/k3P/qYf7d/7dPI8j/v5u3ed7Y2988H7Mv/ADNP/bp/7Wr0D4ZfDL/hXP8Aan/E3/tD7f5X/Lt5WzZv/wBts53+3SvkCvQPhl8Mv+Fjf2p/xN/7P+weV/y7ebv37/8AbXGNnv1r3/4ZfE3/AIWN/an/ABKP7P8AsHlf8vPm79+//YXGNnv1r0Ciiivn/wDZl/5mn/t0/wDa1eAV7/8Asy/8zT/26f8Ataj9mX/maf8At0/9rUf8nGf9S9/YX/b35/n/APfvbt8n3zu7Y59A+GXxN/4WN/an/Eo/s/7B5X/Lz5u/fv8A9hcY2e/WvP8A/hpr/qUf/Kl/9qrgPhl8Mv8AhY39qf8AE3/s/wCweV/y7ebv37/9tcY2e/WvP6+v/hl8Mv8AhXP9qf8AE3/tD7f5X/Lt5WzZv/22znf7dK8//aa/5lb/ALe//aNegfDL4m/8LG/tT/iUf2f9g8r/AJefN379/wDsLjGz3615/wD8My/9Td/5Tf8A7bR/wzL/ANTd/wCU3/7bXAfDL4Zf8LG/tT/ib/2f9g8r/l283fv3/wC2uMbPfrXv/wATfhl/wsb+y/8Aib/2f9g83/l283fv2f7a4xs9+tHwy+Jv/Cxv7U/4lH9n/YPK/wCXnzd+/f8A7C4xs9+tef8A/Juf/Uw/27/26eR5H/fzdu872xt7544D4m/DL/hXP9l/8Tf+0Pt/m/8ALt5WzZs/22znf7dK7/8A5Nz/AOph/t3/ALdPI8j/AL+bt3ne2NvfPHAfDL4m/wDCuf7U/wCJR/aH2/yv+Xnytmzf/sNnO/26V7/8Mvhl/wAK5/tT/ib/ANofb/K/5dvK2bN/+22c7/bpXgHxN+GX/Cuf7L/4m/8AaH2/zf8Al28rZs2f7bZzv9ulef0V9f8Awy+Jv/Cxv7U/4lH9n/YPK/5efN379/8AsLjGz3615/8Asy/8zT/26f8AtavoCiiivn/9mX/maf8At0/9rUf8My/9Td/5Tf8A7bXoHwy+GX/Cuf7U/wCJv/aH2/yv+Xbytmzf/ttnO/26V5/+zL/zNP8A26f+1q9A+Jvwy/4WN/Zf/E3/ALP+web/AMu3m79+z/bXGNnv1r0CvgCvr/4m/DL/AIWN/Zf/ABN/7P8AsHm/8u3m79+z/bXGNnv1o+JvxN/4Vz/Zf/Eo/tD7f5v/AC8+Vs2bP9hs53+3Sj4ZfDL/AIVz/an/ABN/7Q+3+V/y7eVs2b/9ts53+3SvP/2mv+ZW/wC3v/2jR/wzL/1N3/lN/wDttcB8Mvib/wAK5/tT/iUf2h9v8r/l58rZs3/7DZzv9ule/wDwy+GX/Cuf7U/4m/8AaH2/yv8Al28rZs3/AO22c7/bpR8Tfib/AMK5/sv/AIlH9ofb/N/5efK2bNn+w2c7/bpR8Tfhl/wsb+y/+Jv/AGf9g83/AJdvN379n+2uMbPfrXgHwy+Jv/Cuf7U/4lH9ofb/ACv+Xnytmzf/ALDZzv8AbpR8Mvhl/wALG/tT/ib/ANn/AGDyv+Xbzd+/f/trjGz3617/APDL4Zf8K5/tT/ib/wBofb/K/wCXbytmzf8A7bZzv9ulef8A/DMv/U3f+U3/AO21wHwy+Jv/AArn+1P+JR/aH2/yv+Xnytmzf/sNnO/26V3/AO01/wAyt/29/wDtGuA+GXxN/wCFc/2p/wASj+0Pt/lf8vPlbNm//YbOd/t0r3/4m/E3/hXP9l/8Sj+0Pt/m/wDLz5WzZs/2Gznf7dK8/wD2Zf8Amaf+3T/2tXAfE34Zf8K5/sv/AIm/9ofb/N/5dvK2bNn+22c7/bpXv/wy+GX/AArn+1P+Jv8A2h9v8r/l28rZs3/7bZzv9ulegUUUV8//APDMv/U3f+U3/wC20f8ADMv/AFN3/lN/+20f8My/9Td/5Tf/ALbXoHwy+GX/AArn+1P+Jv8A2h9v8r/l28rZs3/7bZzv9ulef/8ADMv/AFN3/lN/+20f8My/9Td/5Tf/ALbR/wAMy/8AU3f+U3/7bX0BXn/xN+GX/Cxv7L/4m/8AZ/2Dzf8Al283fv2f7a4xs9+tef8A/DMv/U3f+U3/AO216B8Mvhl/wrn+1P8Aib/2h9v8r/l28rZs3/7bZzv9ulHxN+GX/Cxv7L/4m/8AZ/2Dzf8Al283fv2f7a4xs9+tHwy+GX/Cuf7U/wCJv/aH2/yv+Xbytmzf/ttnO/26V6BXn/xN+GX/AAsb+y/+Jv8A2f8AYPN/5dvN379n+2uMbPfrR8Mvhl/wrn+1P+Jv/aH2/wAr/l28rZs3/wC22c7/AG6V5/8A8My/9Td/5Tf/ALbXoHwy+GX/AArn+1P+Jv8A2h9v8r/l28rZs3/7bZzv9ulef/8ADMv/AFN3/lN/+20f8My/9Td/5Tf/ALbXoHxN+GX/AAsb+y/+Jv8A2f8AYPN/5dvN379n+2uMbPfrR8Mvhl/wrn+1P+Jv/aH2/wAr/l28rZs3/wC22c7/AG6UfE34Zf8ACxv7L/4m/wDZ/wBg83/l283fv2f7a4xs9+tegV5/8Mvhl/wrn+1P+Jv/AGh9v8r/AJdvK2bN/wDttnO/26UfE34Zf8LG/sv/AIm/9n/YPN/5dvN379n+2uMbPfrXoFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFf/2Q=="
}
}
```
STATUS 202
Response Body: Boleto pendente de registro
```json
{
"request_control_key": "f14e9bac-94ed-4eb1-87b4-7fd7b7a2d280",
"bank_slip_key": "e8599844-5cad-40b4-8716-cb4770d415b4",
"bank_slip_status": "accepted"
}
```
:::info Informação
Caso seja retornado **HTTP Status 202** com o campo `bank_slip_status` com valor `accepted`, a emissão não deve ser retentada.
Esta emissão será processada assincronamente. É necessário verificar o status do boleto por meio
da consulta de boleto, ou aguardar o recebimento do webhook de confirmação descrito na [página de webhooks](/documentation/boletos/v2/webhooks/boleto).
:::
### Response Body Params
| Campo | Tipo | Descrição | Caracteres |
|-------------------------|--------|-----------------------------------------------------------------------------------|------------|
| `request_control_key` * | uuidv4 | Chave única de identificação da request utilizada pelo cliente no formato uuid v4 | 36 |
| `bank_slip_key` * | uuidv4 | Chave única de identificação do boleto no formato uuid v4 | 36 |
| `bank_slip_status` * | string | Status do boleto | **[Enumeradores bank_slip_status](#enumeradores-bank_slip_status)** |
| `our_number` * | integer| Número único de identificação do boleto junto à carteira | 11 |
| `barcode` * | string | Código de barras do boleto | 44 |
| `digitable_line` * | string | Linha digitável do boleto | 47 |
| `qr_code_data` | object | Dados do QR Code | **[Objeto qr_code_data](#objeto-qr_code_data)** |
| `created_at` * | string | Data, no formato ISO (UTC - "YYYY-MM-DDTHH:MM:SSZ"), da criação da ocorrência | 20 |
### Enumeradores bank_slip_status
| Enumerador | Descrição |
|--------------------|-----------------------------------------|
| accepted | Boleto aceito mas ainda não registrado |
| registered | Boleto registrado |
### Objeto qr_code_data
| Campo | Tipo | Descrição | Caracteres |
|----------------------------|--------|-------------------------------------------------------|-------------------------|
| `qr_code_key` | uuidv4 | Chave única de identificação do QR Code | 36 |
| `pix_key` | uuidv4 | Chave PIX vinculada ao QR Code | 36 |
| `receiver_conciliation_id` | uuidv4 | Identificador de conciliação do QR Code | 36 |
| `url` | string | URL (Pix Copia e Cola) do QR Code | - |
| `image` | string | base64 da URL (Pix Copia e Cola) do QR Code | - |
## Error Response
STATUS 4xx
Response Body: Error
```json
{
"title": "titulo",
"description": "description in English",
"translation": "descrição em portugues",
"code": "codigo",
"extra_fields": {}
}
```
| Código HTTP `status` | Código QI `code` | Título `title` | Descrição (eng) `description` | Descrição (pt-br) `translation` |
|--------------------------|----------------------|----------------------------------------------------|-------------------------------------------------------------------------------------------------------------------------|------------------------------------------------------------------------------------------------------------------------|
| 400 | QIT000001 | Bad Request | Schema Error | Schema Inválido |
| 404 | BKS000004 | Not Found | Pix key not found: `{pix_key}` | Chave pix não encontrada: `{pix_key}` |
| 403 | BKS000005 | Forbidden | User is not allowed to do this action | Usuário não tem autorização para fazer essa ação |
| 404 | BKS000006 | Not Found | The source account key was not found. | A chave da conta de origem não foi encontrada. |
| 400 | BKS000007 | Bad Request | It 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. |
| 400 | BKS000008 | Bad Request | The source account is closed. | A conta de origem está fechada. |
| 400 | BKS000009 | Bad Request | The source account is blocked. | A conta de origem está bloqueada. |
| 403 | BKS000010 | Forbidden | The pix key owner does not match the account owner. | O proprietário da chave pix não corresponde ao proprietário da conta. |
| 404 | BKS000013 | Not Found | Requester profile not found | Carteira não encontrada |
| 409 | BKS000014 | Conflict | Request control key already sent or duplicated sent: `{request_control_key}` | Chave de controle da requisição já utilizada ou enviada duplicada: `{request_control_key}` |
| 400 | BKS000016 | Bad Request | Expiration date must be greater than the current date and have a maximum of 3650 days from the current date. | A data de vencimento deve ser maior que a data atual e possuir no máximo 3650 dias corridos a partir da data atual. |
| 409 | BKS000017 | Conflict | Our number already used or duplicated sent: `{our_number}` | Nosso número já utilizado ou enviado duplicado: `{our_number}` |
| 400 | BKS000018 | Bad Request | The discount dates must be less than the expiration date and increasing. | A data dos descontos devem ser menores que a de expiração e crescentes. |
| 400 | BKS000019 | Bad Request | Payer address is required for protest. | Endereço do pagador é obrigatório para protesto. |
| 500 | BKS000021 | Internal Server Error | Error while trying to generate QR Code. | Erro ao tentar gerar QR Code de pagamento. |
| 400 | BKS000022 | Bad Request | Requester profile is not opened. | Carteira não está aberta. |
| 400 | BKS000023 | Bad Request | The amount must be greater than zero. | O valor deve ser maior que zero. |
| 400 | BKS000024 | Bad Request | Error while registering bank slip. | Erro ao registrar boleto. |
| 400 | BKS000026 | Bad Request | Guarantor address is required for protest. | Endereço do sacador é obrigatório para protesto. |
| 404 | BKS000028 | Not Found | Notary office attended region not found for postal code: `{postal_code}` | Região de cartório não encontrada para o CEP: `{postal_code}` |
| 400 | BKS000043 | Bad Request | Invalid discount numbering. Discounts must be numbered in ascending order and start on 1. | Numeração dos descontos inválida. Os descontos devem ser numerados em ordem crescente e começar em 1. |
| 400 | BKS000045 | Bad Request | Rebate amount can not be equal or greater than the bank slip amount. | O valor do rebate não pode ser igual ou maior do que o valor do boleto. |
| 400 | BKS000047 | Bad Request | It 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. |
| 400 | BKS000125 | Bad Request | Partial payment data is required for this bank slip species type. | Os dados de pagamento parcial são obrigatórios para o tipo de boleto fornecido. |
| 400 | BKS000128 | Bad Request | QR code payment is not allowed for partial payment. | Pagamento via QR code não é permitido para pagamento parcial. |
| 400 | BKS000128 | Bad Request | QR code payment is not allowed for partial payment. | Pagamento via QR code não é permitido para pagamento parcial. |
| 400 | BKS000131 | Bad Request | Rebate amount is not allowed for this bank slip species type. | O valor de abatimento não é permitido para o tipo de boleto fornecido. |
| 400 | BKS000132 | Bad Request | Discount data is not allowed for this bank slip species type. | Os dados de desconto não são permitidos para o tipo de boleto fornecido. |
| 400 | BKS000133 | Bad Request | Fine data is not allowed for this bank slip species type. | Os dados de multa não são permitidos para o tipo de boleto fornecido. |
| 400 | BKS000134 | Bad Request | Interest data is not allowed for this bank slip species type. | Os dados de juros não são permitidos para o tipo de boleto fornecido. |
| 400 | BKS000136 | Bad Request | Only credit card financial instrument type can have zero amount. | Apenas o tipo de instrumento financeiro cartão de crédito pode ter valor zero. |
---
# Emissão de boleto único (padrão)
URL: /en/documentation/boletos/emissao/emissao_boleto_unico_padrao
:::danger Importante
Para registrar bolePix, é necessário que exista uma chave Pix aleatória ativa na conta em que os boletos serão registrados.
:::
No fluxo padrão de registro de boleto, caso a requisição seja bem sucedida, a resposta retorna um boleto com o status `accepted` (o boleto foi aceito pela QI Tech). Após a confirmação/rejeição da Nuclea/CIP, o boleto passa para o status `registered` ou `rejected`.
:::caution Atenção!
Como trata-se de um registro assíncrono, o solicitante é notificado via [**webhook**](/documentation/boletos/v2/webhooks/boleto) assim que o boleto mudar de status de `accepted` para `registered` ou `rejected`.
:::
## Request
ENDPOINT /account/ ACCOUNT_KEY /requester_profile/ REQUESTER_PROFILE_KEY /bank_slip
MÉTODO POST
### Path parameters
| Campo | Tipo | Descrição | Caracteres |
|-------------------------|--------|--------------------------------------------------------------|------------|
| `account_key` | uuidv4 | Chave única de identificação da conta, no formato uuid v4 | 36 |
| `requester_profile_key` | uuidv4 | Chave única de identificação da carteira, no formato uuid v4 | 36 |
Request Body
```json
{
"request_control_key": "0d496b4d-01f6-48cd-8ec9-9ead1e43f156",
"our_number": 123456789,
"document_number": "DOC4561237",
"amount": 5000.00,
"expiration": "2025-01-01",
"bank_teller_instructions": "Confirm payment",
"protest_data": {"days_to_protest": 7},
"bankruptcy_protest_data": {"days_to_bankruptcy_protest": 14},
"max_payment_days": 45,
"fine_data": {"fine_type": "absolute", "fine_amount": 100.00, "days_to_fine": 10},
"interest_data": {
"interest_type": "workdays_daily_amount",
"interest_amount": 10.00,
"days_to_interest": 2,
},
"financial_instrument_type": "digital_commercial_invoice",
"write_off_data": {"days_to_write_off": 365},
"rebate_amount": 200.00,
"discounts_data": [
{
"discount_amount": 50.00,
"discount_number": 1,
"discount_type": "absolute",
"discount_limit_date": "2024-12-01",
}
],
"payer_data": {
"name": "Global Tech",
"contact": {
"email": "finance@globaltech.com",
"phone": {"country_code": "055", "area_code": "11", "number": "987654321"},
},
"address": {
"street": "101 High St.",
"neighborhood": "Tech Park",
"number": "202",
"postal_code": "01001000",
"city": "Innovation City",
"state": "SP",
"complement": "Building A",
},
"document_number": "12345678000195",
"person_type": "legal",
},
"guarantor_data": {
"name": "Jane Doe",
"contact": {
"email": "jane.doe@qitech.com.br",
"phone": {"country_code": "055", "area_code": "11", "number": "999999999"},
},
"address": {
"street": "202 Elm St.",
"neighborhood": "Quiet Neighborhood",
"number": "303",
"postal_code": "01001000",
"city": "Peaceful Town",
"state": "RJ",
"complement": "House 1",
},
"document_number": "23456789012",
"person_type": "natural",
},
"pix_key": "4d25d8fc-0074-42bb-b0a4-dd12b1cd0e98",
"notification": {
"document_number": "12345678000195",
"name": "Global Tech",
"email": "finance@globaltech.com",
"phone": {"country_code": "055", "area_code": "11", "number": "987654321"},
"send_2_way": true,
"send_before_due_date": false,
"send_after_due_date": false,
"send_on_protest": false
},
"split_payment_data": {
"beneficiary_settlement_percentage": 70,
"split_payment_rules": [
{
"percentage": 20,
"document_number": "12345678901",
"account_owner_name": "John Smith",
"account_number": "1234567",
"account_digit": "8"
},
{
"percentage": 10,
"document_number": "10987654321",
"account_owner_name": "Mary Johnson",
"account_number": "7654321",
"account_digit": "0"
}
]
}
}
```
### Request Body
| Campo | Tipo | Descrição | Caracteres |
|----------------------------|---------|------------------------------------------------------------------------------------|--------------------------------------------------|
| `request_control_key` * | uuidv4 | Chave única de identificação da request utilizada pelo cliente no formato uuid v4 | 36 |
| `our_number` | integer | Número único de identificação do boleto junto à carteira. Pode ser enviado pelo cliente e, caso não seja, a QI Tech irá gerar um | 11 |
| `document_number` | string | Número de identificação do boleto. Pode ser o número da nota fiscal eletrônica | 10 |
| `participant_control_number` | string | Nº Controle do Participante |25 |
| `amount` * | float | Valor base do boleto | - |
| `expiration` * | string | Data de vencimento | 10 |
| `bank_teller_instructions` | string | Observações ao pagador do boleto. Aceita no máximo 320 caracteres, distribuídos em até 7 linhas. Cada linha pode conter no máximo 90 caracteres. Caso uma linha ultrapasse 90 caracteres, o texto será automaticamente quebrado em uma nova linha | 320 |
| `rebate_amount` | float | Valor de abatimento do boleto, que será aplicado em cima do valor base | - |
| `max_payment_days` | integer | Máximo de dias corridos que o boleto ficará disponível para pagamento, após o vencimento (pode ser no máximo 365) | - |
| `financial_instrument_type` | string | Tipo de espécie do boleto | **[Enumeradores financial_instrument_type](#enumeradores-financial_instrument_type)** |
| `partial_payment_data` | object | Configurações de pagamento parcial | **[Objeto partial_payment_data](#objeto-partial_payment_data)** |
| `write_off_data` | object | Configuração de baixa | **[Objeto write_off_data](#objeto-write_off_settings)** |
| `protest_data` | object | Configuração de protesto | **[Objeto protest_data](#objeto-protest_settings)** |
| `bankruptcy_protest_data` | object | Configuração de protesto falimentar | **[Objeto bankruptcy_protest_data](#objeto-bankruptcy_protest_settings)** |
| `fine_data` | object | Configuração de multa | **[Objeto fine_data](#objeto-fine_settings)** |
| `interest_data` | object | Configuração de juros | **[Objeto interest_data](#objeto-interest_settings)** |
| `discounts_data` | object array | Descontos | **[Objeto discount](#objeto-discounts_data)** |
| `payer_data` * | object | Dados do pagador | **[Objeto payer_data](#objetos-payer_data-e-guarantor_data)** |
| `guarantor_data` | object | Dados do sacador avalista | **[Objeto guarantor_data](#objetos-payer_data-e-guarantor_data)** |
| `pix_key` | uuidv4 | Chave pix do tipo aleatória | 36 |
| `notification` | object | Configurações de notificação do pagador | **[Objeto notification](#objeto-notification)** |
| `split_payment_data` | object | Credit split (split payment) settings of the bank slip | **[split_payment_data Object](#objeto-split_payment_data)** |
:::info BolePix
Caso o parâmetro `pix_key`, opcional, seja enviado na request, será gerado um bolePix. BolePix é um boleto cujo pagamento é vinculado a um QR Code Pix. Sendo assim, o pagador pode realizar o pagamento do boleto tanto utilizando a linha digitável do mesmo, quanto através da leitura do QR Code Pix vinculado. Caso o pagamento seja feito via QR Code, a liquidação financeira se dá instantaneamente, enquanto os retornos bancários e webhooks envolvidos na liquidação serão gerados assim como é feito para um boleto comum.
Importante: para registrar um bolePix, é necessário que exista uma chave Pix aleatória ativa na conta em que boleto será registrado.
:::
:::tip Configurações Padrão da Carteira
Caso cada um dos campos `max_payment_days`, `write_off_data`, `protest_data`, `bankruptcy_protest_data`, `fine_data`, `interest_data` e `pix_key` não sejam enviados na request e a carteira possua configurações padrão (i.e. `max_payment_days`, `write_off_settings`, `protest_settings`, `bankruptcy_protest_settings`, `fine_settings`, `interest_settings` e `qr_code_settings`, respectivamente, no `configuration_data` do `requester_profile`), serão utilizadas tais configurações padrão para a emissão do título.
:::
:::caution Limitações e Restrições
- **Boletos de Pagamento Parcial:** Não é permitido o pagamento via QR Code Pix. Portanto, não é permitido enviar a `pix_key` no registro, nem ter uma configuração padrão de geração de bolePix para a carteira.
- **Boletos de Cartão de Crédito:** Não é necessário nem permitido enviar informações rebate, desconto, multa e juros. Isso se deve ao padrão do mercado, onde muitas Instituições Financeiras não aceitam o pagamento de boletos de cartão de crédito que contenham essas informações. A carteira também não pode ter essas configurações definidas como padrão. Sendo assim boletos desse tipo podem ser pagos parcialmente mesmo após o vencimento, sem incidência de juros, multas, descontos ou abatimentos na fatura corrente. Para aplicar esses valores é necessário incluí-los na próxima fatura, seja através da [ocorrência de edição de valor](/documentation/boletos/instrucoes/valor) do boleto ou emitindo um novo boleto que inclua esses valores. É possível enviar `amount = 0` para boletos deste tipo.
**Importante:** Boletos do tipo `credit_card` são obrigatoriamente de pagamento parcial, sendo assim é necessário fornecer as informações de `partial_payment_data` ou ter essa configuração padrão na carteira. Caso o campo `financial_instrument_type` não seja enviado, o valor padrão será `digital_commercial_invoice`.
:::
:::tip Recomendações de Carteiras
- **Carteira para Boletos Padrão:** Mantenha as configurações padrão para multas, juros e protesto
- **Carteira para Boletos de Pagamento Parcial:** Sem configuração de Pix e com regras específicas para pagamento parcial
- **Carteira para Boletos de Cartão de Crédito:** Sem configurações de multa, juros, desconto ou rebate
Criar carteiras específicas garante que as configurações padrão sejam adequadas para cada tipo de boleto e evita conflitos nas regras de negócio.
:::
:::info Máquina de Estados
A máquina de status para boletos de pagamento parcial possui algumas diferenças. Para mais detalhes, consulte a [introdução](/documentation/boletos/introducao) , onde há uma explicação sobre como aplicar a incidência de juros e multas no boleto seguindo as boas práticas do mercado.
:::
### Enumeradores financial_instrument_type
| Enumerador | Descrição |
|-------------|----------------------------------|
| digital_commercial_invoice | DMI Duplicata Mercantil Indicação |
| credit_card | Cartão de Crédito |
| check | CH Cheque |
| digital_commercial | DM Duplicata Mercantil |
| digital_service_invoice | Duplicata de Serviço |
| digital_service_invoice_indication | DSI Duplicata de Serviço Indicação |
| digital_rural_invoice | DR Duplicata Rural |
| bill_of_exchange | LC Letra de Câmbio |
| commercial_credit_note | NCC Nota de Crédito Comercial |
| export_credit_note | NCE Nota de Crédito Exportação |
| industrial_credit_note | NCI Nota de Crédito Industrial |
| rural_credit_note | NCR Nota de Crédito Rural |
| promissory_note | NP Nota Promissória |
| rural_promissory_note | NPR Nota Promissória Rural |
| mercantile_triplicate | TM Triplicata Mercantil |
| service_triplicate | TS Triplicata de Serviço |
| insurance_note | NS Nota de Seguro |
| receipt | RC Recibo |
| printed_bank_slip | FAT Bloqueto |
| debit_note | ND Nota de Débito |
| insurance_policy | AP Apólice de Seguro |
| school_monthly_fee | ME Mensalidade Escolar |
| consortium_installment | PC Parcela de Consórcio |
| invoice | NF Nota Fiscal |
| debt_document | DD Documento de Dívida |
| rural_product_certificate | Cédula de Produto Rural |
| warrant | Warrant |
| state_active_debt | Dívida Ativa de Estado |
| municipal_active_debt | Dívida Ativa de Município |
| federal_active_debt | Dívida Ativa da União |
| condominium_charges | Encargos condominiais |
| proposal_bank_slip | Boleto proposta |
| deposit_and_contribution_bank_slip | Boleto de Depósito e Aporte |
| others | Outros |
### Objeto split_payment_data
Allows configuring the **credit split** (split payment) of the bank slip, distributing the settled amount between the bank slip's beneficiary and up to 10 additional accounts. The destination accounts must be open and registered with QI Tech, and the sum of percentages (beneficiary + rules) must be exactly 100.
| Field | Type | Description | Characters |
|----------------------------------------|--------------|----------------------------------------------------------------------------------------------------------|------------|
| `beneficiary_settlement_percentage` * | float | Percentage of the settled amount allocated to the bank slip's beneficiary. Accepts values from 0 to 100. | - |
| `beneficiary_max_amount` | float | Maximum amount the beneficiary receives at settlement. When the paid amount exceeds this limit, the surplus is fully directed to the first rule of the `split_payment_rules` array. Accepts values greater than 0 and less than or equal to the bank slip amount. | - |
| `split_payment_rules` * | object array | List of split rules. Minimum 1, maximum 10 rules. | **[split_payment_rule Object](#objeto-split_payment_rule)** |
#### Objeto split_payment_rule
| Field | Type | Description | Characters |
|------------------------|---------|------------------------------------------------------------------------------------------------------|------------|
| `percentage` * | float | Percentage of the settled amount allocated to this account. Accepts values from 0 to 100. Use `0` when this rule is meant exclusively to receive the surplus from `beneficiary_max_amount`. | - |
| `document_number` * | string | CPF/CNPJ of the destination account holder. | 11 or 14 |
| `account_owner_name` * | string | Name of the destination account holder. | 100 |
| `account_number` * | string | Destination account number. | 20 |
| `account_digit` * | string | Destination account check digit. | 2 |
:::caution Attention!
- The sum of `beneficiary_settlement_percentage` and the percentages in each item of `split_payment_rules` must be exactly **100**.
- The `document_number` must be unique across rules and different from the beneficiary.
- The split applies to all settlement flows of the bank slip (SILOC, STR, notary office and Pix QR Code).
- `beneficiary_max_amount`, when provided, must be greater than 0 and less than or equal to the bank slip amount. It is required whenever any rule has `percentage = 0`.
- Only **one** rule per bank slip may have `percentage = 0` (the surplus recipient).
- After issuance, you can update the split via the [**credit split update endpoint**](/documentation/boletos/instrucoes/rateio_de_credito), as long as the bank slip is in `registered` status and has not yet been paid.
:::
:::tip Use case: directing late fees and interest to a separate account
To have the beneficiary always receive the bank slip's face value while a different account receives the interest/late fees on overdue payments, configure `beneficiary_settlement_percentage = 100` + `beneficiary_max_amount = ` + a single rule with `percentage = 0` pointing to the surplus recipient account. See the full walkthrough in [**Credit Split Update**](/documentation/boletos/instrucoes/rateio_de_credito#use-case-directing-late-fees-and-interest-to-a-separate-account).
:::
### Objeto partial_payment_data
| Campo | Tipo | Descrição | Caracteres |
|-----------------------------------|---------|---------------------------------------------------------------------------|------------|
| `partial_payment_minimum_type` * | string | Tipo de valor mínimo para pagamento parcial | **[Enumeradores partial_payment_type](#enumeradores-partial_payment_type)** |
| `partial_payment_minimum_percentage` | float | Percentual mínimo permitido para o pagamento parcial | - |
| `partial_payment_minimum_amount` | float | Valor mínimo permitido para o pagamento parcial | - |
| `partial_payment_maximum_type` | string | Tipo de valor máximo para pagamento parcial | **[Enumeradores partial_payment_type](#enumeradores-partial_payment_type)** |
| `partial_payment_maximum_percentage` | float | Percentual máximo permitido para o pagamento parcial | - |
| `partial_payment_maximum_amount` | float | Valor máximo permitido para o pagamento parcial | - |
| `partial_payment_quantity` * | integer | Quantidade de pagamentos parciais permitidos | - |
:::caution Atenção!
De acordo com o valor enviado nos campos `partial_payment_minimum_type` e `partial_payment_maximum_type`, é necessário enviar o `partial_payment_minimum_amount` ou `partial_payment_minimum_percentage`, e o `partial_payment_maximum_amount` ou `partial_payment_maximum_percentage` correspondente.
:::
### Enumeradores partial_payment_type
| Enumerador | Descrição |
|-------------|----------------------------------|
| absolute | Valor absoluto |
| percentage | Percentual |
### Objeto write_off_data
| Campo | Tipo | Descrição | Caracteres |
|---------------------------|---------|-----------------------------------------------------------------------------|------------|
| `days_to_write_off` * | integer | Dias, após o vencimento, para que o boleto seja baixado automaticamente | - |
### Objeto protest_data
| Campo | Tipo | Descrição | Caracteres |
|---------------------------|---------|-----------------------------------------------------------------------------|------------|
| `days_to_protest` * | integer | Dias, após o vencimento, para que o boleto seja protestado automaticamente | - |
### Objeto bankruptcy_protest_data
| Campo | Tipo | Descrição | Caracteres |
|--------------------------------|---------|-----------------------------------------------------------------------------|------------|
| `days_to_bankruptcy_protest` * | integer | Dias, após o vencimento, para que o boleto seja protestado automaticamente | - |
### Objeto fine_data
Opção 1: multa em valor absoluto (`fine_type=absolute`)
| Campo | Tipo | Descrição | Caracteres |
|---------------------------|---------|---------------------------------------------------------|-------------------------------------------------------------------------|
| `fine_type` * | string | Tipo da multa | **[Enumeradores fine_type](#enumeradores-fine_type)** |
| `fine_amount` * | float | Valor absoluto da multa | - |
| `days_to_fine` * | integer | Dias, após o vencimento, para que a multa seja cobrada | - |
Opção 2: multa em valor percentual (`fine_type=percentage`)
| Campo | Tipo | Descrição | Caracteres |
|---------------------------|---------|-----------------------------------------------------------|---------------------------------------|
| `fine_type` * | string | Tipo da multa | **[Enumeradores fine_type](#enumeradores-fine_type)** |
| `fine_percentage` * | integer | Valor percentual da multa, de 1 a 100 | - |
| `days_to_fine` * | integer | Dias, após o vencimento, para que a multa seja cobrada | - |
### Enumeradores fine_type
| Enumerador | Descrição |
|--------------------|-----------------------|
| absolute | valor absoluto |
| percentage | valor percentual |
### Objeto interest_data
Opção 1: juros utilizando valores absolutos (`interest_type=calendar_days_daily_amount` ou `interest_type=workdays_daily_amount`)
| Campo | Tipo | Descrição | Caracteres |
|---------------------------|---------|-------------------------------------------------------------------------------------|------------------------------------------------------------------------------------------------|
| `interest_type` * | string | Tipo de juros | **[Enumeradores interest_type](#enumeradores-interest_type)** |
| `interest_amount` * | float | Valor a ser cobrado por unidade de tempo determinada (dias úteis ou corridos) | - |
| `days_to_interest` * | integer | Dias, após o vencimento, para que comece a cobrar os juros | - |
Opção 2: juros utilizando valores percentuais (`interest_type=calendar_days_monthly_percentage`)
| Campo | Tipo | Descrição | Caracteres |
|--------------------------|---------|---------------------------------------------------------------------------------------|----------------------------------------------------------------------------------------------------|
| `interest_type` * | string | Tipo de juros | **[Enumeradores interest_type](#enumeradores-interest_type)** |
| `interest_percentage` * | integer | Porcentagem a ser cobrada por unidade de tempo determinada (dias úteis ou corridos) | - |
| `days_to_interest` * | integer | Dias, após o vencimento, para que comece a cobrar os juros | - |
### Enumeradores interest_type
| Enumerador | Descrição |
|----------------------------------|----------------------------------------------------------------------|
| calendar_days_daily_amount | Valor diário sobre dias corridos |
| workdays_daily_amount | Valor diário sobre dias úteis |
| calendar_days_monthly_percentage | Porcentagem de juros cobrados mensalmente, com base em dias corridos |
### Objeto discount
Opção 1: descontos utilizando valores absolutos (`discount_type in ["absolute", "anticipation_calendar_days_daily_amount", "anticipation_workdays_daily_amount"]`)
| Campo | Tipo | Descrição | Caracteres |
|---------------------------|---------|-----------------------------------------------------|-----------------------------------------------------------|
| `discount_amount` * | float | Valor absoluto de desconto por unidade de tempo | - |
| `discount_number` * | integer | Número do desconto | - |
| `discount_type` * | string | Configuração do desconto em valores absolutos | **[Enumerador discount_type](#enumeradores-discount_type)** | |
| `discount_limit_date` * | string | Data limite para aplicação do desconto | 10 |
Opção 2: descontos utilizando valores percentuais (`discount_type in ["percentage", "anticipation_calendar_days_daily_percentage", "anticipation_workdays_daily_percentage"]`)
| Campo | Tipo | Descrição | Caracteres |
|---------------------------|---------|-----------------------------------------------------|-----------------------------------------------------------|
| `discount_percentage` * | float | Valor percentual de desconto por unidade de tempo | - |
| `discount_number` * | integer | Número do desconto | - |
| `discount_type` * | string | Configuração do desconto em valores percentuais | **[Enumerador discount_type](#enumeradores-discount_type)** | |
| `discount_limit_date` * | string | Data limite para aplicação do desconto | 10 |
:::caution Atenção!
O boleto pode ter até três descontos, sendo que os descontos devem ser todos do mesmo tipo , isto é, devem ter o mesmo `discount_type`. Os descontos devem ser numerados de 1 a 3, de maneira crescente e começando necessariamente em 1. Ou seja, caso sejam enviados dois descontos na requisição, devem necessariamente ser numerados com 1 e 2.
:::
### Enumeradores discount_type
| Enumerador | Descrição |
|---------------------------------------------|--------------------------------------------------------------------------|
| absolute | Valor fixo |
| anticipation_calendar_days_daily_amount | Valor diário de desconto de antecipação, sobre dias corridos |
| anticipation_workdays_daily_amount | Valor diário de desconto de antecipação, sobre dias úteis |
| percentage | Porcentagem fixa |
| anticipation_calendar_days_daily_percentage | Porcentagem mensal de desconto de antecipação, com base em dias corridos |
| anticipation_workdays_daily_percentage | Porcentagem anual de desconto de antecipação, com base em dias úteis |
### Objetos payer_data e guarantor_data
| Campo | Tipo | Descrição | Caracteres|
|---------------------------|--------|-------------------------------------|-----------------------------------------------------------|
| `name` * | string | Nome completo | 100 |
| `document_number` * | string | Número do documento (CPF/CNPJ) | 11 ou 14 |
| `person_type` * | string | Tipo da pessoa (física ou jurídica) | **[Enumeradores person_type](#enumeradores-person_type)** |
| `contact` | object | Informações de contato | **[Objeto contact](#objeto-contact)** |
| `address` | object | Endereço | **[Objeto address](#objeto-address)** |
### Enumeradores person_type
| Enumerador | Descrição |
|--------------------|-----------------------|
| natural | pessoa física |
| legal | pessoa jurídica |
### Objeto contact
| Campo | Tipo | Descrição | Caracteres |
|---------------------------|--------|-----------------------------------|------------------------------------|
| `email` | string | E-mail de contato | 320 |
| `phone` | object | Telefone de contato | **[Objeto phone](#objeto-phone)** |
### Objeto phone
| Campo | Tipo | Descrição | Caracteres |
|---------------------------------|--------|----------------------------------------------|------------|
| `country_code` * | string | Código DDI (Discagem Direta Internacional) | 3 |
| `area_code` * | string | Código DDD (Discagem Direta à Distância) | 2 |
| `number` * | string | Complemento | 9 |
### Objeto address
| Campo | Tipo | Descrição | Caracteres |
|---------------------------|--------|----------------------------------------------|------------|
| `street` * | string | Logradouro | 500 |
| `number` * | string | Número | 6 |
| `complement` | string | Complemento | 500 |
| `neighborhood` * | string | Bairro | 100 |
| `postal_code` * | string | CEP | 8 |
| `city` * | string | Cidade | 100 |
| `state` * | string | Estado (UF) | **[Enumerador state](#enumeradores-state)** |
### Enumeradores state
| Enumerador | Descrição |
|--------------------|-----------------------|
| AC | Acre |
| AL | Alagoas |
| AM | Amazonas |
| AP | Amapá |
| BA | Bahia |
| CE | Ceará |
| DF | Distrito federal |
| ES | Espírito Santo |
| GO | Goiás |
| MA | Maranhão |
| MG | Minas Gerais |
| MS | Mato Grosso do Sul |
| MT | Mato Grosso |
| PA | Pará |
| PB | Paraíba |
| PE | Pernambuco |
| PI | Piauí |
| PR | Paraná |
| RJ | Rio de Janeiro |
| RN | Rio Grande do Norte |
| RO | Rondônia |
| RR | Roraima |
| RS | Rio Grande do Sul |
| SC | Santa Catarina |
| SE | Sergipe |
| SP | São Paulo |
| TO | Tocantins |
| EX | Exceção |
### Objeto notification
| Campo | Tipo | Descrição | Caracteres |
|---------------------------|---------|-----------------------------------------------------------------------------------------|------------|
| `document_number` * | string | Número do documento de quem receberá as notificações (CPF/CNPJ) | 11 ou 14 |
| `name` * | string | Nome de quem receberá as notificações | 100 |
| `email` | string | E-mail para o qual serão enviadas as notificações | 320 |
| `phone` | object | Telefone de contato para o qual serão enviadas as notificações | **[Objeto phone](#objeto-phone)** |
| `send_2_way` * | boolean | Enviar segunda via | - |
| `send_before_due_date` * | boolean | Enviar notificação ao pagador antes da data de vencimento | - |
| `send_after_due_date` * | boolean | Enviar notificação ao pagador quando o boleto vencer | - |
| `send_on_protest` * | boolean | Enviar notificação ao entrar em fluxo de protesto | - |
## Response
STATUS 202
Response Body
```json
{
"request_control_key": "0d496b4d-01f6-48cd-8ec9-9ead1e43f156",
"bank_slip_key": "8cb70dea-9fb0-4a68-9572-99a72849c8d6",
"bank_slip_status": "accepted",
"our_number": 67215548222,
"barcode": "32995995900000892811606496721554822228569790",
"digitable_line": "32991606429672155482022285697904599590000089281",
"qr_code_data": {
"qr_code_key": "a92b180a-4aa5-47c2-8a71-4e7bbb074410",
"pix_key": "4d25d8fc-0074-42bb-b0a4-dd12b1cd0e98",
"receiver_conciliation_id": "01GVGV9NXBCY287Z6CJ4S0ENW9",
"url": "00020126830014br.gov.bcb.pix2561qrcode.qitech.app/bacen/cobv/58fd5103a8e64bbbab2fd49b0bd580145204000053039865802BR5925GONNFUNDODEINVESTIMENTOEM6012RiodeJaneiro6107226401262070503***6304EA0D",
"image": "/9j/4AAQSkZJRgABAQAAAQABAAD/2wBDAAgGBgcGBQgHBwcJCQgKDBQNDAsLDBkSEw8UHRofHh0aHBwgJC4nICIsIxwcKDcpLDAxNDQ0Hyc5PTgyPC4zNDL/wAALCAD0APQBAREA/8QAHwAAAQUBAQEBAQEAAAAAAAAAAAECAwQFBgcICQoL/8QAtRAAAgEDAwIEAwUFBAQAAAF9AQIDAAQRBRIhMUEGE1FhByJxFDKBkaEII0KxwRVS0fAkM2JyggkKFhcYGRolJicoKSo0NTY3ODk6Q0RFRkdISUpTVFVWV1hZWmNkZWZnaGlqc3R1dnd4eXqDhIWGh4iJipKTlJWWl5iZmqKjpKWmp6ipqrKztLW2t7i5usLDxMXGx8jJytLT1NXW19jZ2uHi4+Tl5ufo6erx8vP09fb3+Pn6/9oACAEBAAA/APf6KKKKKKKKKKKKKKKKKKKKKKKKKKKKKKKKKKKKKKKKKKKKKKKKKKKKKKKKKKKKKKK+QPhl8Mv+Fjf2p/xN/wCz/sHlf8u3m79+/wD21xjZ79a7/wD4Zl/6m7/ym/8A22j/AIZl/wCpu/8AKb/9to/Zl/5mn/t0/wDa1egfE34Zf8LG/sv/AIm/9n/YPN/5dvN379n+2uMbPfrXgHwy+GX/AAsb+1P+Jv8A2f8AYPK/5dvN379/+2uMbPfrR8Tfib/wsb+y/wDiUf2f9g83/l583fv2f7C4xs9+td//AMm5/wDUw/27/wBunkeR/wB/N27zvbG3vnjwCvr/AOJvxN/4Vz/Zf/Eo/tD7f5v/AC8+Vs2bP9hs53+3SvkCvf8A9mX/AJmn/t0/9rUf8m5/9TD/AG7/ANunkeR/383bvO9sbe+ePQPhl8Mv+Fc/2p/xN/7Q+3+V/wAu3lbNm/8A22znf7dK8A+GXxN/4Vz/AGp/xKP7Q+3+V/y8+Vs2b/8AYbOd/t0o+GXxN/4Vz/an/Eo/tD7f5X/Lz5WzZv8A9hs53+3Svf8A4m/DL/hY39l/8Tf+z/sHm/8ALt5u/fs/21xjZ79a8/8A+GZf+pu/8pv/ANtr0D4ZfE3/AIWN/an/ABKP7P8AsHlf8vPm79+//YXGNnv1rwD4ZfE3/hXP9qf8Sj+0Pt/lf8vPlbNm/wD2Gznf7dK7/wD4aa/6lH/ypf8A2quA+GXxN/4Vz/an/Eo/tD7f5X/Lz5WzZv8A9hs53+3Svr+vkD4ZfDL/AIWN/an/ABN/7P8AsHlf8u3m79+//bXGNnv1rv8A/hmX/qbv/Kb/APbaP+GZf+pu/wDKb/8AbaP2Zf8Amaf+3T/2tX0BRRRXz/8Asy/8zT/26f8AtavAK9//AGZf+Zp/7dP/AGtR+zL/AMzT/wBun/tavQPib8Mv+Fjf2X/xN/7P+web/wAu3m79+z/bXGNnv1rz/wDZl/5mn/t0/wDa1cB8Mvib/wAK5/tT/iUf2h9v8r/l58rZs3/7DZzv9ule/wDwy+Jv/Cxv7U/4lH9n/YPK/wCXnzd+/f8A7C4xs9+teAfE34Zf8K5/sv8A4m/9ofb/ADf+XbytmzZ/ttnO/wBule//ABN+Jv8Awrn+y/8AiUf2h9v83/l58rZs2f7DZzv9uleAfDL4Zf8ACxv7U/4m/wDZ/wBg8r/l283fv3/7a4xs9+tHxN+GX/Cuf7L/AOJv/aH2/wA3/l28rZs2f7bZzv8AbpXv/wAMvhl/wrn+1P8Aib/2h9v8r/l28rZs3/7bZzv9ulef/tNf8yt/29/+0a9A+GXxN/4WN/an/Eo/s/7B5X/Lz5u/fv8A9hcY2e/WvP8A/k3P/qYf7d/7dPI8j/v5u3ed7Y2988cB8Tfhl/wrn+y/+Jv/AGh9v83/AJdvK2bNn+22c7/bpXf/APDTX/Uo/wDlS/8AtVcB8Tfhl/wrn+y/+Jv/AGh9v83/AJdvK2bNn+22c7/bpX1/Xz//AMm5/wDUw/27/wBunkeR/wB/N27zvbG3vng/5OM/6l7+wv8At78/z/8Av3t2+T753dsc+gfDL4m/8LG/tT/iUf2f9g8r/l583fv3/wCwuMbPfrXn/wCzL/zNP/bp/wC1q8Ar3/8AZl/5mn/t0/8Aa1H7Mv8AzNP/AG6f+1q+gKKKK+f/ANmX/maf+3T/ANrUf8My/wDU3f8AlN/+216B8Mvhl/wrn+1P+Jv/AGh9v8r/AJdvK2bN/wDttnO/26V5/wDsy/8AM0/9un/taj/k4z/qXv7C/wC3vz/P/wC/e3b5Pvnd2xyf8nGf9S9/YX/b35/n/wDfvbt8n3zu7Y5P2mv+ZW/7e/8A2jR+zL/zNP8A26f+1qP+Tc/+ph/t3/t08jyP+/m7d53tjb3zx4BXv/7TX/Mrf9vf/tGj/k3P/qYf7d/7dPI8j/v5u3ed7Y2988cB8Mvhl/wsb+1P+Jv/AGf9g8r/AJdvN379/wDtrjGz3613/wDwzL/1N3/lN/8AttH7Mv8AzNP/AG6f+1q4D4m/DL/hXP8AZf8AxN/7Q+3+b/y7eVs2bP8AbbOd/t0rv/8Ahpr/AKlH/wAqX/2qj/k4z/qXv7C/7e/P8/8A797dvk++d3bHJ/ybn/1MP9u/9unkeR/383bvO9sbe+ePQPhl8Mv+Fc/2p/xN/wC0Pt/lf8u3lbNm/wD22znf7dKPib8Mv+Fjf2X/AMTf+z/sHm/8u3m79+z/AG1xjZ79a8//AGZf+Zp/7dP/AGtX0BXz/wDsy/8AM0/9un/taj/hmX/qbv8Aym//AG2vQPhl8Mv+Fc/2p/xN/wC0Pt/lf8u3lbNm/wD22znf7dK8/wD2Zf8Amaf+3T/2tX0BRRRXz/8A8My/9Td/5Tf/ALbR/wAMy/8AU3f+U3/7bR/wzL/1N3/lN/8AttegfDL4Zf8ACuf7U/4m/wDaH2/yv+Xbytmzf/ttnO/26V5//wAm5/8AUw/27/26eR5H/fzdu872xt7549A+GXwy/wCFc/2p/wATf+0Pt/lf8u3lbNm//bbOd/t0rz/9mX/maf8At0/9rVwHwy+Jv/Cuf7U/4lH9ofb/ACv+Xnytmzf/ALDZzv8AbpR8Mvib/wAK5/tT/iUf2h9v8r/l58rZs3/7DZzv9ulHwy+Jv/Cuf7U/4lH9ofb/ACv+Xnytmzf/ALDZzv8AbpXf/sy/8zT/ANun/tavQPhl8Mv+Fc/2p/xN/wC0Pt/lf8u3lbNm/wD22znf7dK8/wD2Zf8Amaf+3T/2tXoHwy+GX/Cuf7U/4m/9ofb/ACv+Xbytmzf/ALbZzv8AbpXgHwy+Jv8Awrn+1P8AiUf2h9v8r/l58rZs3/7DZzv9uld/+zL/AMzT/wBun/tavQPhl8Mv+Fc/2p/xN/7Q+3+V/wAu3lbNm/8A22znf7dK8A+GXxN/4Vz/AGp/xKP7Q+3+V/y8+Vs2b/8AYbOd/t0o+GXxN/4Vz/an/Eo/tD7f5X/Lz5WzZv8A9hs53+3Su/8A2Zf+Zp/7dP8A2tR/ybn/ANTD/bv/AG6eR5H/AH83bvO9sbe+eD9mX/maf+3T/wBrUfsy/wDM0/8Abp/7Wo/4Zl/6m7/ym/8A22j/AIZl/wCpu/8AKb/9to/4Zl/6m7/ym/8A22vQPhl8Mv8AhXP9qf8AE3/tD7f5X/Lt5WzZv/22znf7dK9Aooor5/8A2Zf+Zp/7dP8A2tXAfE34m/8ACxv7L/4lH9n/AGDzf+Xnzd+/Z/sLjGz360fE34m/8LG/sv8A4lH9n/YPN/5efN379n+wuMbPfrXv/wAMvhl/wrn+1P8Aib/2h9v8r/l28rZs3/7bZzv9ulfIFFegfDL4m/8ACuf7U/4lH9ofb/K/5efK2bN/+w2c7/bpXf8A7TX/ADK3/b3/AO0a9A+GXxN/4WN/an/Eo/s/7B5X/Lz5u/fv/wBhcY2e/WvAPib8Mv8AhXP9l/8AE3/tD7f5v/Lt5WzZs/22znf7dKPib8Mv+Fc/2X/xN/7Q+3+b/wAu3lbNmz/bbOd/t0rv/wBmX/maf+3T/wBrVwHxN+GX/Cuf7L/4m/8AaH2/zf8Al28rZs2f7bZzv9ulHxN+GX/Cuf7L/wCJv/aH2/zf+XbytmzZ/ttnO/26V3//AAzL/wBTd/5Tf/ttH7TX/Mrf9vf/ALRrgPhl8Tf+Fc/2p/xKP7Q+3+V/y8+Vs2b/APYbOd/t0o+Jvwy/4Vz/AGX/AMTf+0Pt/m/8u3lbNmz/AG2znf7dK7//AJOM/wCpe/sL/t78/wA//v3t2+T753dscn/Juf8A1MP9u/8Abp5Hkf8Afzdu872xt7548Ar3/wD5Nz/6mH+3f+3TyPI/7+bt3ne2NvfPHAfE34Zf8K5/sv8A4m/9ofb/ADf+XbytmzZ/ttnO/wBuld/+01/zK3/b3/7Rr6Aorz/4ZfE3/hY39qf8Sj+z/sHlf8vPm79+/wD2FxjZ79a9Aooor5A+Jvwy/wCFc/2X/wATf+0Pt/m/8u3lbNmz/bbOd/t0o+JvxN/4WN/Zf/Eo/s/7B5v/AC8+bv37P9hcY2e/Wu//AGmv+ZW/7e//AGjXoHwy+GX/AArn+1P+Jv8A2h9v8r/l28rZs3/7bZzv9ulHwy+Jv/Cxv7U/4lH9n/YPK/5efN379/8AsLjGz3615/8A8nGf9S9/YX/b35/n/wDfvbt8n3zu7Y5+gK+QPib8Tf8AhY39l/8AEo/s/wCweb/y8+bv37P9hcY2e/Wvf/hl8Tf+Fjf2p/xKP7P+weV/y8+bv37/APYXGNnv1rz/AP4aa/6lH/ypf/aq9A+Jvwy/4WN/Zf8AxN/7P+web/y7ebv37P8AbXGNnv1r0CvkD4m/DL/hXP8AZf8AxN/7Q+3+b/y7eVs2bP8AbbOd/t0rv/8Ahpr/AKlH/wAqX/2qj/hmX/qbv/Kb/wDbaP8Ak3P/AKmH+3f+3TyPI/7+bt3ne2NvfPHoHxN+Jv8Awrn+y/8AiUf2h9v83/l58rZs2f7DZzv9ulHwy+GX/Cuf7U/4m/8AaH2/yv8Al28rZs3/AO22c7/bpXn/AO01/wAyt/29/wDtGj/hpr/qUf8Aypf/AGqj/k4z/qXv7C/7e/P8/wD797dvk++d3bHJ/wANNf8AUo/+VL/7VXAfE34Zf8K5/sv/AIm/9ofb/N/5dvK2bNn+22c7/bpR8Mvib/wrn+1P+JR/aH2/yv8Al58rZs3/AOw2c7/bpR8Mvhl/wsb+1P8Aib/2f9g8r/l283fv3/7a4xs9+tHwy+Jv/Cuf7U/4lH9ofb/K/wCXnytmzf8A7DZzv9ulfX9FFFFfP/8AwzL/ANTd/wCU3/7bXoHwy+GX/Cuf7U/4m/8AaH2/yv8Al28rZs3/AO22c7/bpXgHwy+GX/Cxv7U/4m/9n/YPK/5dvN379/8AtrjGz3613/8AwzL/ANTd/wCU3/7bR/w01/1KP/lS/wDtVegfDL4Zf8K5/tT/AIm/9ofb/K/5dvK2bN/+22c7/bpR8Mvib/wsb+1P+JR/Z/2Dyv8Al583fv3/AOwuMbPfrR8Mvhl/wrn+1P8Aib/2h9v8r/l28rZs3/7bZzv9uleAfE34Zf8ACuf7L/4m/wDaH2/zf+XbytmzZ/ttnO/26V3/AO01/wAyt/29/wDtGuA+GXwy/wCFjf2p/wATf+z/ALB5X/Lt5u/fv/21xjZ79a9/+Jvwy/4WN/Zf/E3/ALP+web/AMu3m79+z/bXGNnv1rwD4m/DL/hXP9l/8Tf+0Pt/m/8ALt5WzZs/22znf7dK9/8Aib8Tf+Fc/wBl/wDEo/tD7f5v/Lz5WzZs/wBhs53+3SvP/wBpr/mVv+3v/wBo0f8AJuf/AFMP9u/9unkeR/383bvO9sbe+eD9mX/maf8At0/9rV4BXoHwy+Jv/Cuf7U/4lH9ofb/K/wCXnytmzf8A7DZzv9uld/8A8m5/9TD/AG7/ANunkeR/383bvO9sbe+eOA+GXxN/4Vz/AGp/xKP7Q+3+V/y8+Vs2b/8AYbOd/t0rv/8Ak3P/AKmH+3f+3TyPI/7+bt3ne2NvfPHoHxN+GX/Cxv7L/wCJv/Z/2Dzf+Xbzd+/Z/trjGz3614B8Mvib/wAK5/tT/iUf2h9v8r/l58rZs3/7DZzv9ule/wDxN+Jv/Cuf7L/4lH9ofb/N/wCXnytmzZ/sNnO/26UfE34m/wDCuf7L/wCJR/aH2/zf+XnytmzZ/sNnO/26V5/+zL/zNP8A26f+1q+gKKKK+f8A/k3P/qYf7d/7dPI8j/v5u3ed7Y2988H/ACbn/wBTD/bv/bp5Hkf9/N27zvbG3vnjgPib8Mv+Fc/2X/xN/wC0Pt/m/wDLt5WzZs/22znf7dK9/wDhl8Mv+Fc/2p/xN/7Q+3+V/wAu3lbNm/8A22znf7dKPib8Mv8AhY39l/8AE3/s/wCweb/y7ebv37P9tcY2e/WvAPib8Mv+Fc/2X/xN/wC0Pt/m/wDLt5WzZs/22znf7dK8/r3/APaa/wCZW/7e/wD2jXAfDL4m/wDCuf7U/wCJR/aH2/yv+Xnytmzf/sNnO/26V7/8Mvhl/wAK5/tT/ib/ANofb/K/5dvK2bN/+22c7/bpXn//AA01/wBSj/5Uv/tVegfE34m/8K5/sv8A4lH9ofb/ADf+XnytmzZ/sNnO/wBulHxN+Jv/AArn+y/+JR/aH2/zf+XnytmzZ/sNnO/26V5/+01/zK3/AG9/+0aP2Zf+Zp/7dP8A2tR+zL/zNP8A26f+1qP+TjP+pe/sL/t78/z/APv3t2+T753dsc+AV7/+zL/zNP8A26f+1q9A+GXwy/4Vz/an/E3/ALQ+3+V/y7eVs2b/APbbOd/t0rwD4ZfDL/hY39qf8Tf+z/sHlf8ALt5u/fv/ANtcY2e/Wvf/AIm/E3/hXP8AZf8AxKP7Q+3+b/y8+Vs2bP8AYbOd/t0rwD4m/DL/AIVz/Zf/ABN/7Q+3+b/y7eVs2bP9ts53+3Su/wD2mv8AmVv+3v8A9o1wHwy+Jv8Awrn+1P8AiUf2h9v8r/l58rZs3/7DZzv9ulHxN+GX/Cuf7L/4m/8AaH2/zf8Al28rZs2f7bZzv9ule/8Awy+GX/Cuf7U/4m/9ofb/ACv+Xbytmzf/ALbZzv8AbpXoFFFFfIHwy+GX/Cxv7U/4m/8AZ/2Dyv8Al283fv3/AO2uMbPfrXf/APDMv/U3f+U3/wC20f8AJxn/AFL39hf9vfn+f/3727fJ987u2OfQPhl8Mv8AhXP9qf8AE3/tD7f5X/Lt5WzZv/22znf7dK8//wCGmv8AqUf/ACpf/aq8Ar3/AP4aa/6lH/ypf/aq9A+GXwy/4Vz/AGp/xN/7Q+3+V/y7eVs2b/8AbbOd/t0rwD4m/DL/AIVz/Zf/ABN/7Q+3+b/y7eVs2bP9ts53+3Svf/ib8Mv+Fjf2X/xN/wCz/sHm/wDLt5u/fs/21xjZ79a8/wD+TjP+pe/sL/t78/z/APv3t2+T753dsc+gfDL4m/8ACxv7U/4lH9n/AGDyv+Xnzd+/f/sLjGz360fDL4Zf8K5/tT/ib/2h9v8AK/5dvK2bN/8AttnO/wBulef/APJxn/Uvf2F/29+f5/8A3727fJ987u2OT/hpr/qUf/Kl/wDaqP2mv+ZW/wC3v/2jR+zL/wAzT/26f+1q8Ar3/wD4Zl/6m7/ym/8A22vQPhl8Tf8AhY39qf8AEo/s/wCweV/y8+bv37/9hcY2e/Wj4m/E3/hXP9l/8Sj+0Pt/m/8ALz5WzZs/2Gznf7dKPib8Mv8AhY39l/8AE3/s/wCweb/y7ebv37P9tcY2e/Wj4ZfE3/hY39qf8Sj+z/sHlf8ALz5u/fv/ANhcY2e/Wj4ZfDL/AIVz/an/ABN/7Q+3+V/y7eVs2b/9ts53+3SvQK+f/wDk4z/qXv7C/wC3vz/P/wC/e3b5Pvnd2xz9AUUUUV5/8Mvhl/wrn+1P+Jv/AGh9v8r/AJdvK2bN/wDttnO/26V5/wD8m5/9TD/bv/bp5Hkf9/N27zvbG3vnjwCvQPib8Mv+Fc/2X/xN/wC0Pt/m/wDLt5WzZs/22znf7dK7/wD5Nz/6mH+3f+3TyPI/7+bt3ne2NvfPHAfDL4m/8K5/tT/iUf2h9v8AK/5efK2bN/8AsNnO/wBulHwy+GX/AAsb+1P+Jv8A2f8AYPK/5dvN379/+2uMbPfrXf8A7TX/ADK3/b3/AO0a4D4m/DL/AIVz/Zf/ABN/7Q+3+b/y7eVs2bP9ts53+3Sj4ZfDL/hY39qf8Tf+z/sHlf8ALt5u/fv/ANtcY2e/Wu//AGmv+ZW/7e//AGjXoHxN+GX/AAsb+y/+Jv8A2f8AYPN/5dvN379n+2uMbPfrXoFfIHwy+Jv/AArn+1P+JR/aH2/yv+Xnytmzf/sNnO/26UfDL4Zf8LG/tT/ib/2f9g8r/l283fv3/wC2uMbPfrXf/wDDTX/Uo/8AlS/+1Ufsy/8AM0/9un/tavAK9A+GXwy/4WN/an/E3/s/7B5X/Lt5u/fv/wBtcY2e/Wu//wCGmv8AqUf/ACpf/aq4D4ZfE3/hXP8Aan/Eo/tD7f5X/Lz5WzZv/wBhs53+3Su//wCTjP8AqXv7C/7e/P8AP/797dvk++d3bHPoHxN+Jv8Awrn+y/8AiUf2h9v83/l58rZs2f7DZzv9ulHxN+Jv/Cuf7L/4lH9ofb/N/wCXnytmzZ/sNnO/26UfDL4m/wDCxv7U/wCJR/Z/2Dyv+Xnzd+/f/sLjGz360fE34m/8K5/sv/iUf2h9v83/AJefK2bNn+w2c7/bpR8Mvib/AMLG/tT/AIlH9n/YPK/5efN379/+wuMbPfrXoFFFFfIHwy+Jv/Cuf7U/4lH9ofb/ACv+Xnytmzf/ALDZzv8AbpX1/XwBXoHxN+GX/Cuf7L/4m/8AaH2/zf8Al28rZs2f7bZzv9ule/8Awy+Jv/Cxv7U/4lH9n/YPK/5efN379/8AsLjGz360fE34m/8ACuf7L/4lH9ofb/N/5efK2bNn+w2c7/bpR8Mvhl/wrn+1P+Jv/aH2/wAr/l28rZs3/wC22c7/AG6V5/8Asy/8zT/26f8AtauA+JvxN/4WN/Zf/Eo/s/7B5v8Ay8+bv37P9hcY2e/Wvf8A4m/E3/hXP9l/8Sj+0Pt/m/8ALz5WzZs/2Gznf7dK8A+JvxN/4WN/Zf8AxKP7P+web/y8+bv37P8AYXGNnv1r3/4m/E3/AIVz/Zf/ABKP7Q+3+b/y8+Vs2bP9hs53+3SvP/8Ak3P/AKmH+3f+3TyPI/7+bt3ne2NvfPB/w01/1KP/AJUv/tVegfE34m/8K5/sv/iUf2h9v83/AJefK2bNn+w2c7/bpXn/AO01/wAyt/29/wDtGj/hpr/qUf8Aypf/AGqvoCvkD4ZfE3/hXP8Aan/Eo/tD7f5X/Lz5WzZv/wBhs53+3Svf/ib8Tf8AhXP9l/8AEo/tD7f5v/Lz5WzZs/2Gznf7dK8//wCGZf8Aqbv/ACm//baP2mv+ZW/7e/8A2jR/ybn/ANTD/bv/AG6eR5H/AH83bvO9sbe+ePQPib8Tf+Fc/wBl/wDEo/tD7f5v/Lz5WzZs/wBhs53+3SvAPhl8Tf8AhXP9qf8AEo/tD7f5X/Lz5WzZv/2Gznf7dK9/+GXxN/4WN/an/Eo/s/7B5X/Lz5u/fv8A9hcY2e/Wj4ZfE3/hY39qf8Sj+z/sHlf8vPm79+//AGFxjZ79a9Aoooor5/8A2Zf+Zp/7dP8A2tR/wzL/ANTd/wCU3/7bR/ybn/1MP9u/9unkeR/383bvO9sbe+ePQPib8Tf+Fc/2X/xKP7Q+3+b/AMvPlbNmz/YbOd/t0o+JvxN/4Vz/AGX/AMSj+0Pt/m/8vPlbNmz/AGGznf7dK8A+Jvwy/wCFc/2X/wATf+0Pt/m/8u3lbNmz/bbOd/t0r3/4m/DL/hY39l/8Tf8As/7B5v8Ay7ebv37P9tcY2e/Wj4m/E3/hXP8AZf8AxKP7Q+3+b/y8+Vs2bP8AYbOd/t0r5Ar0D4ZfE3/hXP8Aan/Eo/tD7f5X/Lz5WzZv/wBhs53+3Su//wCGmv8AqUf/ACpf/aq4D4ZfE3/hXP8Aan/Eo/tD7f5X/Lz5WzZv/wBhs53+3Su//aa/5lb/ALe//aNcB8Mvhl/wsb+1P+Jv/Z/2Dyv+Xbzd+/f/ALa4xs9+tHxN+Jv/AAsb+y/+JR/Z/wBg83/l583fv2f7C4xs9+te/wDwy+GX/Cuf7U/4m/8AaH2/yv8Al28rZs3/AO22c7/bpXgHwy+GX/Cxv7U/4m/9n/YPK/5dvN379/8AtrjGz360fE34Zf8ACuf7L/4m/wDaH2/zf+XbytmzZ/ttnO/26V5/Xv8A+01/zK3/AG9/+0a4D4ZfDL/hY39qf8Tf+z/sHlf8u3m79+//AG1xjZ79a9/+GXxN/wCFjf2p/wASj+z/ALB5X/Lz5u/fv/2FxjZ79aPhl8Mv+Fc/2p/xN/7Q+3+V/wAu3lbNm/8A22znf7dK+QK9/wD2Zf8Amaf+3T/2tX0BRRRRXyB8Tfhl/wAK5/sv/ib/ANofb/N/5dvK2bNn+22c7/bpXf8A/DTX/Uo/+VL/AO1VwHwy+GX/AAsb+1P+Jv8A2f8AYPK/5dvN379/+2uMbPfrXf8A/DMv/U3f+U3/AO21wHwy+Jv/AArn+1P+JR/aH2/yv+Xnytmzf/sNnO/26UfDL4m/8K5/tT/iUf2h9v8AK/5efK2bN/8AsNnO/wBule//ABN+Jv8Awrn+y/8AiUf2h9v83/l58rZs2f7DZzv9uleAfE34m/8ACxv7L/4lH9n/AGDzf+Xnzd+/Z/sLjGz3615/XoHxN+Jv/Cxv7L/4lH9n/YPN/wCXnzd+/Z/sLjGz3613/wC01/zK3/b3/wC0a9A+GXwy/wCFc/2p/wATf+0Pt/lf8u3lbNm//bbOd/t0rwD4ZfDL/hY39qf8Tf8As/7B5X/Lt5u/fv8A9tcY2e/Wu/8A+GZf+pu/8pv/ANtrgPhl8Mv+Fjf2p/xN/wCz/sHlf8u3m79+/wD21xjZ79a8/r0D4ZfDL/hY39qf8Tf+z/sHlf8ALt5u/fv/ANtcY2e/Wj4m/E3/AIWN/Zf/ABKP7P8AsHm/8vPm79+z/YXGNnv1rv8A/hpr/qUf/Kl/9qr0D4m/DL/hY39l/wDE3/s/7B5v/Lt5u/fs/wBtcY2e/WvP/wBmX/maf+3T/wBrV6B8Mvib/wALG/tT/iUf2f8AYPK/5efN379/+wuMbPfrXgHwy+GX/Cxv7U/4m/8AZ/2Dyv8Al283fv3/AO2uMbPfrXf/APDMv/U3f+U3/wC20fsy/wDM0/8Abp/7WrgPib8Mv+Fc/wBl/wDE3/tD7f5v/Lt5WzZs/wBts53+3Svf/hl8Mv8AhXP9qf8AE3/tD7f5X/Lt5WzZv/22znf7dK9Aooorz/4m/DL/AIWN/Zf/ABN/7P8AsHm/8u3m79+z/bXGNnv1rwD4ZfE3/hXP9qf8Sj+0Pt/lf8vPlbNm/wD2Gznf7dK7/wDZl/5mn/t0/wDa1egfDL4Zf8K5/tT/AIm/9ofb/K/5dvK2bN/+22c7/bpXgHwy+GX/AAsb+1P+Jv8A2f8AYPK/5dvN379/+2uMbPfrR8Tfhl/wrn+y/wDib/2h9v8AN/5dvK2bNn+22c7/AG6V3/7TX/Mrf9vf/tGuA+GXxN/4Vz/an/Eo/tD7f5X/AC8+Vs2b/wDYbOd/t0o+Jvwy/wCFc/2X/wATf+0Pt/m/8u3lbNmz/bbOd/t0r6/rz/4ZfDL/AIVz/an/ABN/7Q+3+V/y7eVs2b/9ts53+3Sj4ZfDL/hXP9qf8Tf+0Pt/lf8ALt5WzZv/ANts53+3SvP/ANmX/maf+3T/ANrV6B8Mvhl/wrn+1P8Aib/2h9v8r/l28rZs3/7bZzv9uleAfDL4m/8ACuf7U/4lH9ofb/K/5efK2bN/+w2c7/bpX1/RRXyB8Tfib/wsb+y/+JR/Z/2Dzf8Al583fv2f7C4xs9+td/8A8m5/9TD/AG7/ANunkeR/383bvO9sbe+ePAK+v/ib8Tf+Fc/2X/xKP7Q+3+b/AMvPlbNmz/YbOd/t0rz/APZl/wCZp/7dP/a1egfDL4Zf8K5/tT/ib/2h9v8AK/5dvK2bN/8AttnO/wBuleAfDL4m/wDCuf7U/wCJR/aH2/yv+Xnytmzf/sNnO/26V7/8Tfhl/wALG/sv/ib/ANn/AGDzf+Xbzd+/Z/trjGz3615/+zL/AMzT/wBun/tavoCiiivP/ib8Tf8AhXP9l/8AEo/tD7f5v/Lz5WzZs/2Gznf7dK8//wCTc/8AqYf7d/7dPI8j/v5u3ed7Y2988H/DMv8A1N3/AJTf/ttH/DMv/U3f+U3/AO214BXv/wDwzL/1N3/lN/8AttH/AA01/wBSj/5Uv/tVH/DMv/U3f+U3/wC214BXoHwy+GX/AAsb+1P+Jv8A2f8AYPK/5dvN379/+2uMbPfrXf8A7Mv/ADNP/bp/7Wr0D4ZfE3/hY39qf8Sj+z/sHlf8vPm79+//AGFxjZ79a8//AOGZf+pu/wDKb/8Aba4D4ZfDL/hY39qf8Tf+z/sHlf8ALt5u/fv/ANtcY2e/Wj4ZfDL/AIWN/an/ABN/7P8AsHlf8u3m79+//bXGNnv1r3/4m/DL/hY39l/8Tf8As/7B5v8Ay7ebv37P9tcY2e/WvP8A9mX/AJmn/t0/9rV9AV8//wDDMv8A1N3/AJTf/ttH/Jxn/Uvf2F/29+f5/wD3727fJ987u2OfQPib8Mv+Fjf2X/xN/wCz/sHm/wDLt5u/fs/21xjZ79a9Ar5A+Jvwy/4Vz/Zf/E3/ALQ+3+b/AMu3lbNmz/bbOd/t0o+Jvwy/4Vz/AGX/AMTf+0Pt/m/8u3lbNmz/AG2znf7dK9/+GXwy/wCFc/2p/wATf+0Pt/lf8u3lbNm//bbOd/t0rz//AJOM/wCpe/sL/t78/wA//v3t2+T753dscn7Mv/M0/wDbp/7Wr6Aooorz/wCGXwy/4Vz/AGp/xN/7Q+3+V/y7eVs2b/8AbbOd/t0rz/8A4Zl/6m7/AMpv/wBto/Zl/wCZp/7dP/a1H/Juf/Uw/wBu/wDbp5Hkf9/N27zvbG3vng/Zl/5mn/t0/wDa1H/Juf8A1MP9u/8Abp5Hkf8Afzdu872xt7544D4ZfDL/AIWN/an/ABN/7P8AsHlf8u3m79+//bXGNnv1o+GXwy/4WN/an/E3/s/7B5X/AC7ebv37/wDbXGNnv1o+JvxN/wCFjf2X/wASj+z/ALB5v/Lz5u/fs/2FxjZ79aPhl8Mv+Fjf2p/xN/7P+weV/wAu3m79+/8A21xjZ79a7/8A5OM/6l7+wv8At78/z/8Av3t2+T753dsc8B8Mvib/AMK5/tT/AIlH9ofb/K/5efK2bN/+w2c7/bpXv/xN+GX/AAsb+y/+Jv8A2f8AYPN/5dvN379n+2uMbPfrXn//AA01/wBSj/5Uv/tVegfDL4m/8LG/tT/iUf2f9g8r/l583fv3/wCwuMbPfrXn/wCzL/zNP/bp/wC1q4D4ZfE3/hXP9qf8Sj+0Pt/lf8vPlbNm/wD2Gznf7dKPib8Mv+Fc/wBl/wDE3/tD7f5v/Lt5WzZs/wBts53+3Su//Zl/5mn/ALdP/a1fQFef/E34Zf8ACxv7L/4m/wDZ/wBg83/l283fv2f7a4xs9+tef/8ADTX/AFKP/lS/+1VwHxN+GX/Cuf7L/wCJv/aH2/zf+XbytmzZ/ttnO/26V5/Xv/8AwzL/ANTd/wCU3/7bR/ybn/1MP9u/9unkeR/383bvO9sbe+eD9mX/AJmn/t0/9rV9AUUUV8AUV7//AMnGf9S9/YX/AG9+f5//AH727fJ987u2OfQPhl8Mv+Fc/wBqf8Tf+0Pt/lf8u3lbNm//AG2znf7dK8A+Jvwy/wCFc/2X/wATf+0Pt/m/8u3lbNmz/bbOd/t0rv8A9pr/AJlb/t7/APaNH/DMv/U3f+U3/wC20f8ADMv/AFN3/lN/+216B8Mvhl/wrn+1P+Jv/aH2/wAr/l28rZs3/wC22c7/AG6V5/8A8nGf9S9/YX/b35/n/wDfvbt8n3zu7Y59A+Jvwy/4WN/Zf/E3/s/7B5v/AC7ebv37P9tcY2e/WvQK+QPib8Tf+Fjf2X/xKP7P+web/wAvPm79+z/YXGNnv1o+Jvwy/wCFc/2X/wATf+0Pt/m/8u3lbNmz/bbOd/t0r3/4m/DL/hY39l/8Tf8As/7B5v8Ay7ebv37P9tcY2e/Wj4ZfE3/hY39qf8Sj+z/sHlf8vPm79+//AGFxjZ79a8//AOTjP+pe/sL/ALe/P8//AL97dvk++d3bHPoHxN+Jv/Cuf7L/AOJR/aH2/wA3/l58rZs2f7DZzv8AbpR8Mvhl/wAK5/tT/ib/ANofb/K/5dvK2bN/+22c7/bpXgHxN+GX/Cuf7L/4m/8AaH2/zf8Al28rZs2f7bZzv9uld/8A8My/9Td/5Tf/ALbXoHxN+Jv/AArn+y/+JR/aH2/zf+XnytmzZ/sNnO/26V5/+zL/AMzT/wBun/taj/k3P/qYf7d/7dPI8j/v5u3ed7Y2988fQFfP/wDybn/1MP8Abv8A26eR5H/fzdu872xt754+gKKKKK+AK+v/AIZfE3/hY39qf8Sj+z/sHlf8vPm79+//AGFxjZ79aPhl8Tf+Fjf2p/xKP7P+weV/y8+bv37/APYXGNnv1rwD4m/DL/hXP9l/8Tf+0Pt/m/8ALt5WzZs/22znf7dK9/8Ahl8Mv+Fc/wBqf8Tf+0Pt/lf8u3lbNm//AG2znf7dK8//AOGZf+pu/wDKb/8Aba8Ar6/+Jvwy/wCFjf2X/wATf+z/ALB5v/Lt5u/fs/21xjZ79aPib8Mv+Fjf2X/xN/7P+web/wAu3m79+z/bXGNnv1rz/wD4Zl/6m7/ym/8A22j/AJNz/wCph/t3/t08jyP+/m7d53tjb3zx6B8Mvhl/wrn+1P8Aib/2h9v8r/l28rZs3/7bZzv9ulHwy+GX/Cuf7U/4m/8AaH2/yv8Al28rZs3/AO22c7/bpXgHwy+Jv/Cuf7U/4lH9ofb/ACv+Xnytmzf/ALDZzv8AbpXv/wAMvib/AMLG/tT/AIlH9n/YPK/5efN379/+wuMbPfrXgHxN+GX/AArn+y/+Jv8A2h9v83/l28rZs2f7bZzv9uld/wD8NNf9Sj/5Uv8A7VX0BXyB8Mvhl/wsb+1P+Jv/AGf9g8r/AJdvN379/wDtrjGz3619f18//wDDTX/Uo/8AlS/+1V6B8Tfhl/wsb+y/+Jv/AGf9g83/AJdvN379n+2uMbPfrR8Mvib/AMLG/tT/AIlH9n/YPK/5efN379/+wuMbPfrR8Mvib/wsb+1P+JR/Z/2Dyv8Al583fv3/AOwuMbPfrR8Tfhl/wsb+y/8Aib/2f9g83/l283fv2f7a4xs9+tef/sy/8zT/ANun/taj9mX/AJmn/t0/9rV9AUUUV8//ALTX/Mrf9vf/ALRo/wCGZf8Aqbv/ACm//ba+gK+f/wDk3P8A6mH+3f8At08jyP8Av5u3ed7Y2988eAUV7/8A8NNf9Sj/AOVL/wC1Uf8AJuf/AFMP9u/9unkeR/383bvO9sbe+ePQPib8Mv8AhY39l/8AE3/s/wCweb/y7ebv37P9tcY2e/WvP/8Ak4z/AKl7+wv+3vz/AD/+/e3b5Pvnd2xzwHwy+Jv/AArn+1P+JR/aH2/yv+Xnytmzf/sNnO/26UfDL4Zf8LG/tT/ib/2f9g8r/l283fv3/wC2uMbPfrXv/wATfib/AMK5/sv/AIlH9ofb/N/5efK2bNn+w2c7/bpXn/7Mv/M0/wDbp/7Wr0D4ZfDL/hXP9qf8Tf8AtD7f5X/Lt5WzZv8A9ts53+3Sj4ZfDL/hXP8Aan/E3/tD7f5X/Lt5WzZv/wBts53+3SvAPib8Mv8AhXP9l/8AE3/tD7f5v/Lt5WzZs/22znf7dKPhl8Mv+Fjf2p/xN/7P+weV/wAu3m79+/8A21xjZ79a7/8AZl/5mn/t0/8Aa1cB8Mvib/wrn+1P+JR/aH2/yv8Al58rZs3/AOw2c7/bpR8Mvib/AMK5/tT/AIlH9ofb/K/5efK2bN/+w2c7/bpXf/8AJuf/AFMP9u/9unkeR/383bvO9sbe+eOA+Jvwy/4Vz/Zf/E3/ALQ+3+b/AMu3lbNmz/bbOd/t0o+GXxN/4Vz/AGp/xKP7Q+3+V/y8+Vs2b/8AYbOd/t0rv/8Ak3P/AKmH+3f+3TyPI/7+bt3ne2NvfPB/w01/1KP/AJUv/tVegfDL4m/8LG/tT/iUf2f9g8r/AJefN379/wDsLjGz3616BRRRRXyB8Tfhl/wrn+y/+Jv/AGh9v83/AJdvK2bNn+22c7/bpR8Mvib/AMK5/tT/AIlH9ofb/K/5efK2bN/+w2c7/bpXv/wy+GX/AArn+1P+Jv8A2h9v8r/l28rZs3/7bZzv9ulHxN+GX/Cxv7L/AOJv/Z/2Dzf+Xbzd+/Z/trjGz3615/8A8My/9Td/5Tf/ALbXoHxN+Jv/AArn+y/+JR/aH2/zf+XnytmzZ/sNnO/26V4B8Mvhl/wsb+1P+Jv/AGf9g8r/AJdvN379/wDtrjGz3617/wDDL4m/8LG/tT/iUf2f9g8r/l583fv3/wCwuMbPfrXgHxN+Jv8Awsb+y/8AiUf2f9g83/l583fv2f7C4xs9+te//DL4m/8ACxv7U/4lH9n/AGDyv+Xnzd+/f/sLjGz3614B8Tfhl/wrn+y/+Jv/AGh9v83/AJdvK2bNn+22c7/bpXv/AMTfhl/wsb+y/wDib/2f9g83/l283fv2f7a4xs9+tegV5/8AE34Zf8LG/sv/AIm/9n/YPN/5dvN379n+2uMbPfrR8Tfib/wrn+y/+JR/aH2/zf8Al58rZs2f7DZzv9ulef8A/Jxn/Uvf2F/29+f5/wD3727fJ987u2OfAK9A+GXxN/4Vz/an/Eo/tD7f5X/Lz5WzZv8A9hs53+3Svf8A4m/E3/hXP9l/8Sj+0Pt/m/8ALz5WzZs/2Gznf7dKPhl8Mv8AhXP9qf8AE3/tD7f5X/Lt5WzZv/22znf7dK9Ar5A+JvxN/wCFjf2X/wASj+z/ALB5v/Lz5u/fs/2FxjZ79aPhl8Mv+Fjf2p/xN/7P+weV/wAu3m79+/8A21xjZ79a9/8Aib8Tf+Fc/wBl/wDEo/tD7f5v/Lz5WzZs/wBhs53+3SvQK8/+GXwy/wCFc/2p/wATf+0Pt/lf8u3lbNm//bbOd/t0r0CiiivkD4ZfE3/hXP8Aan/Eo/tD7f5X/Lz5WzZv/wBhs53+3Su//wCGZf8Aqbv/ACm//ba+gK8/+GXwy/4Vz/an/E3/ALQ+3+V/y7eVs2b/APbbOd/t0rz/AP4Zl/6m7/ym/wD22vQPib8Tf+Fc/wBl/wDEo/tD7f5v/Lz5WzZs/wBhs53+3SvQK8/+Jvwy/wCFjf2X/wATf+z/ALB5v/Lt5u/fs/21xjZ79a8//Zl/5mn/ALdP/a1cB8Tfib/wsb+y/wDiUf2f9g83/l583fv2f7C4xs9+te//AAy+GX/Cuf7U/wCJv/aH2/yv+Xbytmzf/ttnO/26UfE34m/8K5/sv/iUf2h9v83/AJefK2bNn+w2c7/bpR8Tfhl/wsb+y/8Aib/2f9g83/l283fv2f7a4xs9+tef/wDJuf8A1MP9u/8Abp5Hkf8Afzdu872xt754P+TjP+pe/sL/ALe/P8//AL97dvk++d3bHPoHwy+GX/Cuf7U/4m/9ofb/ACv+Xbytmzf/ALbZzv8AbpR8Mvhl/wAK5/tT/ib/ANofb/K/5dvK2bN/+22c7/bpXn//AAzL/wBTd/5Tf/tteAUV9f8AxN+Jv/Cuf7L/AOJR/aH2/wA3/l58rZs2f7DZzv8AbpXgHxN+Jv8Awsb+y/8AiUf2f9g83/l583fv2f7C4xs9+tfX9FfIHwy+Jv8Awrn+1P8AiUf2h9v8r/l58rZs3/7DZzv9ulHwy+Jv/Cuf7U/4lH9ofb/K/wCXnytmzf8A7DZzv9ule/8Awy+Jv/Cxv7U/4lH9n/YPK/5efN379/8AsLjGz3616BRRRXyB8Tfhl/wrn+y/+Jv/AGh9v83/AJdvK2bNn+22c7/bpXf/APJxn/Uvf2F/29+f5/8A3727fJ987u2OT/hmX/qbv/Kb/wDbaP8Ak3P/AKmH+3f+3TyPI/7+bt3ne2NvfPB/wzL/ANTd/wCU3/7bR+01/wAyt/29/wDtGj9mX/maf+3T/wBrV6B8Mvhl/wAK5/tT/ib/ANofb/K/5dvK2bN/+22c7/bpXn//AAzL/wBTd/5Tf/ttH/Juf/Uw/wBu/wDbp5Hkf9/N27zvbG3vnjgPhl8Mv+Fjf2p/xN/7P+weV/y7ebv37/8AbXGNnv1r3/4ZfDL/AIVz/an/ABN/7Q+3+V/y7eVs2b/9ts53+3SvP/2Zf+Zp/wC3T/2tXoHxN+GX/Cxv7L/4m/8AZ/2Dzf8Al283fv2f7a4xs9+tef8A/Jxn/Uvf2F/29+f5/wD3727fJ987u2OfQPib8Mv+Fjf2X/xN/wCz/sHm/wDLt5u/fs/21xjZ79a8/wD+Gmv+pR/8qX/2quA+JvxN/wCFjf2X/wASj+z/ALB5v/Lz5u/fs/2FxjZ79a9/+Jvwy/4WN/Zf/E3/ALP+web/AMu3m79+z/bXGNnv1rwD4m/DL/hXP9l/8Tf+0Pt/m/8ALt5WzZs/22znf7dKPib8Mv8AhXP9l/8AE3/tD7f5v/Lt5WzZs/22znf7dK9/+JvxN/4Vz/Zf/Eo/tD7f5v8Ay8+Vs2bP9hs53+3SvP8A9pr/AJlb/t7/APaNH/Juf/Uw/wBu/wDbp5Hkf9/N27zvbG3vng/Zl/5mn/t0/wDa1eAV7/8Asy/8zT/26f8AtavoCiiiivP/AIm/DL/hY39l/wDE3/s/7B5v/Lt5u/fs/wBtcY2e/WvQK8/+GXwy/wCFc/2p/wATf+0Pt/lf8u3lbNm//bbOd/t0o+GXxN/4WN/an/Eo/s/7B5X/AC8+bv37/wDYXGNnv1o+Jvwy/wCFjf2X/wATf+z/ALB5v/Lt5u/fs/21xjZ79a8//aa/5lb/ALe//aNH/Jxn/Uvf2F/29+f5/wD3727fJ987u2OfAK9//wCTjP8AqXv7C/7e/P8AP/797dvk++d3bHJ/w01/1KP/AJUv/tVH/DMv/U3f+U3/AO21wHwy+GX/AAsb+1P+Jv8A2f8AYPK/5dvN379/+2uMbPfrXf8A/DMv/U3f+U3/AO214BXv/wC01/zK3/b3/wC0aP8Ak4z/AKl7+wv+3vz/AD/+/e3b5Pvnd2xyftNf8yt/29/+0a4D4ZfE3/hXP9qf8Sj+0Pt/lf8ALz5WzZv/ANhs53+3Svf/AIZfDL/hXP8Aan/E3/tD7f5X/Lt5WzZv/wBts53+3SvAPhl8Mv8AhY39qf8AE3/s/wCweV/y7ebv37/9tcY2e/Wu/wD+Tc/+ph/t3/t08jyP+/m7d53tjb3zxwHwy+GX/Cxv7U/4m/8AZ/2Dyv8Al283fv3/AO2uMbPfrXf/APDMv/U3f+U3/wC21wHwy+Jv/Cuf7U/4lH9ofb/K/wCXnytmzf8A7DZzv9ule/8AxN+Jv/Cuf7L/AOJR/aH2/wA3/l58rZs2f7DZzv8AbpR8Mvib/wALG/tT/iUf2f8AYPK/5efN379/+wuMbPfrXoFFFFfIHwy+GX/Cxv7U/wCJv/Z/2Dyv+Xbzd+/f/trjGz3613//AAzL/wBTd/5Tf/ttH/DMv/U3f+U3/wC20fsy/wDM0/8Abp/7Wo/5OM/6l7+wv+3vz/P/AO/e3b5Pvnd2xyf8NNf9Sj/5Uv8A7VXAfDL4m/8ACuf7U/4lH9ofb/K/5efK2bN/+w2c7/bpR8Mvhl/wsb+1P+Jv/Z/2Dyv+Xbzd+/f/ALa4xs9+td//AMNNf9Sj/wCVL/7VR/ybn/1MP9u/9unkeR/383bvO9sbe+ePAK9//Zl/5mn/ALdP/a1H7Mv/ADNP/bp/7Wr0D4ZfDL/hXP8Aan/E3/tD7f5X/Lt5WzZv/wBts53+3SvAPhl8Mv8AhY39qf8AE3/s/wCweV/y7ebv37/9tcY2e/WvP69//Zl/5mn/ALdP/a1H7Mv/ADNP/bp/7Wo/aa/5lb/t7/8AaNegfDL4m/8ACxv7U/4lH9n/AGDyv+Xnzd+/f/sLjGz3615/+zL/AMzT/wBun/taj/k3P/qYf7d/7dPI8j/v5u3ed7Y2988H7Mv/ADNP/bp/7Wr0D4ZfDL/hXP8Aan/E3/tD7f5X/Lt5WzZv/wBts53+3SvkCvQPhl8Mv+Fjf2p/xN/7P+weV/y7ebv37/8AbXGNnv1r3/4ZfE3/AIWN/an/ABKP7P8AsHlf8vPm79+//YXGNnv1r0Ciiivn/wDZl/5mn/t0/wDa1eAV7/8Asy/8zT/26f8Ataj9mX/maf8At0/9rUf8nGf9S9/YX/b35/n/APfvbt8n3zu7Y59A+GXxN/4WN/an/Eo/s/7B5X/Lz5u/fv8A9hcY2e/WvP8A/hpr/qUf/Kl/9qrgPhl8Mv8AhY39qf8AE3/s/wCweV/y7ebv37/9tcY2e/WvP6+v/hl8Mv8AhXP9qf8AE3/tD7f5X/Lt5WzZv/22znf7dK8//aa/5lb/ALe//aNegfDL4m/8LG/tT/iUf2f9g8r/AJefN379/wDsLjGz3615/wD8My/9Td/5Tf8A7bR/wzL/ANTd/wCU3/7bXAfDL4Zf8LG/tT/ib/2f9g8r/l283fv3/wC2uMbPfrXv/wATfhl/wsb+y/8Aib/2f9g83/l283fv2f7a4xs9+tHwy+Jv/Cxv7U/4lH9n/YPK/wCXnzd+/f8A7C4xs9+tef8A/Juf/Uw/27/26eR5H/fzdu872xt7544D4m/DL/hXP9l/8Tf+0Pt/m/8ALt5WzZs/22znf7dK7/8A5Nz/AOph/t3/ALdPI8j/AL+bt3ne2NvfPHAfDL4m/wDCuf7U/wCJR/aH2/yv+Xnytmzf/sNnO/26V7/8Mvhl/wAK5/tT/ib/ANofb/K/5dvK2bN/+22c7/bpXgHxN+GX/Cuf7L/4m/8AaH2/zf8Al28rZs2f7bZzv9ulef0V9f8Awy+Jv/Cxv7U/4lH9n/YPK/5efN379/8AsLjGz3615/8Asy/8zT/26f8AtavoCiiivn/9mX/maf8At0/9rUf8My/9Td/5Tf8A7bXoHwy+GX/Cuf7U/wCJv/aH2/yv+Xbytmzf/ttnO/26V5/+zL/zNP8A26f+1q9A+Jvwy/4WN/Zf/E3/ALP+web/AMu3m79+z/bXGNnv1r0CvgCvr/4m/DL/AIWN/Zf/ABN/7P8AsHm/8u3m79+z/bXGNnv1o+JvxN/4Vz/Zf/Eo/tD7f5v/AC8+Vs2bP9hs53+3Sj4ZfDL/AIVz/an/ABN/7Q+3+V/y7eVs2b/9ts53+3SvP/2mv+ZW/wC3v/2jR/wzL/1N3/lN/wDttcB8Mvib/wAK5/tT/iUf2h9v8r/l58rZs3/7DZzv9ule/wDwy+GX/Cuf7U/4m/8AaH2/yv8Al28rZs3/AO22c7/bpR8Tfib/AMK5/sv/AIlH9ofb/N/5efK2bNn+w2c7/bpR8Tfhl/wsb+y/+Jv/AGf9g83/AJdvN379n+2uMbPfrXgHwy+Jv/Cuf7U/4lH9ofb/ACv+Xnytmzf/ALDZzv8AbpR8Mvhl/wALG/tT/ib/ANn/AGDyv+Xbzd+/f/trjGz3617/APDL4Zf8K5/tT/ib/wBofb/K/wCXbytmzf8A7bZzv9ulef8A/DMv/U3f+U3/AO21wHwy+Jv/AArn+1P+JR/aH2/yv+Xnytmzf/sNnO/26V3/AO01/wAyt/29/wDtGuA+GXxN/wCFc/2p/wASj+0Pt/lf8vPlbNm//YbOd/t0r3/4m/E3/hXP9l/8Sj+0Pt/m/wDLz5WzZs/2Gznf7dK8/wD2Zf8Amaf+3T/2tXAfE34Zf8K5/sv/AIm/9ofb/N/5dvK2bNn+22c7/bpXv/wy+GX/AArn+1P+Jv8A2h9v8r/l28rZs3/7bZzv9ulegUUUV8//APDMv/U3f+U3/wC20f8ADMv/AFN3/lN/+20f8My/9Td/5Tf/ALbXoHwy+GX/AArn+1P+Jv8A2h9v8r/l28rZs3/7bZzv9ulef/8ADMv/AFN3/lN/+20f8My/9Td/5Tf/ALbR/wAMy/8AU3f+U3/7bX0BXn/xN+GX/Cxv7L/4m/8AZ/2Dzf8Al283fv2f7a4xs9+tef8A/DMv/U3f+U3/AO216B8Mvhl/wrn+1P8Aib/2h9v8r/l28rZs3/7bZzv9ulHxN+GX/Cxv7L/4m/8AZ/2Dzf8Al283fv2f7a4xs9+tHwy+GX/Cuf7U/wCJv/aH2/yv+Xbytmzf/ttnO/26V6BXn/xN+GX/AAsb+y/+Jv8A2f8AYPN/5dvN379n+2uMbPfrR8Mvhl/wrn+1P+Jv/aH2/wAr/l28rZs3/wC22c7/AG6V5/8A8My/9Td/5Tf/ALbXoHwy+GX/AArn+1P+Jv8A2h9v8r/l28rZs3/7bZzv9ulef/8ADMv/AFN3/lN/+20f8My/9Td/5Tf/ALbXoHxN+GX/AAsb+y/+Jv8A2f8AYPN/5dvN379n+2uMbPfrR8Mvhl/wrn+1P+Jv/aH2/wAr/l28rZs3/wC22c7/AG6UfE34Zf8ACxv7L/4m/wDZ/wBg83/l283fv2f7a4xs9+tegV5/8Mvhl/wrn+1P+Jv/AGh9v8r/AJdvK2bN/wDttnO/26UfE34Zf8LG/sv/AIm/9n/YPN/5dvN379n+2uMbPfrXoFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFf/2Q=="
}
}
```
### Response Body Params
| Campo | Tipo | Descrição | Caracteres |
|-------------------------|--------|-----------------------------------------------------------------------------------|------------|
| `request_control_key` * | uuidv4 | Chave única de identificação da request utilizada pelo cliente no formato uuid v4 | 36 |
| `bank_slip_key` * | uuidv4 | Chave única de identificação do boleto no formato uuid v4 | 36 |
| `bank_slip_status` * | string | Status do boleto | **[Enumeradores bank_slip_status](#enumeradores-bank_slip_status)** |
| `our_number` * | integer| Número único de identificação do boleto junto à carteira | 11 |
| `barcode` * | string | Código de barras do boleto | 44 |
| `digitable_line` * | string | Linha digitável do boleto | 47 |
| `qr_code_data` | object | Dados do QR Code | **[Objeto qr_code_data](#objeto-qr_code_data)** |
| `created_at` * | string | Data, no formato ISO (UTC - "YYYY-MM-DDTHH:MM:SSZ"), da criação da ocorrência | 20 |
### Enumeradores bank_slip_status
| Enumerador | Descrição |
|--------------------|-----------------------------------------|
| accepted | Boleto aceito mas ainda não registrado |
### Objeto qr_code_data
| Campo | Tipo | Descrição | Caracteres |
|----------------------------|--------|-------------------------------------------------------|-------------------------|
| `qr_code_key` | uuidv4 | Chave única de identificação do QR Code | 36 |
| `pix_key` | uuidv4 | Chave PIX vinculada ao QR Code | 36 |
| `receiver_conciliation_id` | uuidv4 | Identificador de conciliação do QR Code | 36 |
| `url` | string | URL (Pix Copia e Cola) do QR Code | - |
| `image` | string | base64 da URL (Pix Copia e Cola) do QR Code | - |
## Error Response
STATUS 4xx
Response Body: Error
```json
{
"title": "titulo",
"description": "description in English",
"translation": "descrição em portugues",
"code": "codigo",
"extra_fields": {}
}
```
| Código HTTP `status` | Código QI `code` | Título `title` | Descrição (eng) `description` | Descrição (pt-br) `translation` |
|--------------------------|----------------------|----------------------------------------------------|-------------------------------------------------------------------------------------------------------------------------|------------------------------------------------------------------------------------------------------------------------|
| 400 | QIT000001 | Bad Request | Schema Error | Schema Inválido |
| 404 | BKS000004 | Not Found | Pix key not found: `{pix_key}` | Chave pix não encontrada: `{pix_key}` |
| 403 | BKS000005 | Forbidden | User is not allowed to do this action | Usuário não tem autorização para fazer essa ação |
| 404 | BKS000006 | Not Found | The source account key was not found. | A chave da conta de origem não foi encontrada. |
| 400 | BKS000007 | Bad Request | It 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. |
| 400 | BKS000008 | Bad Request | The source account is closed. | A conta de origem está fechada. |
| 400 | BKS000009 | Bad Request | The source account is blocked. | A conta de origem está bloqueada. |
| 403 | BKS000010 | Forbidden | The pix key owner does not match the account owner. | O proprietário da chave pix não corresponde ao proprietário da conta. |
| 404 | BKS000013 | Not Found | Requester profile not found | Carteira não encontrada |
| 409 | BKS000014 | Conflict | Request control key already sent or duplicated sent: `{request_control_key}` | Chave de controle da requisição já utilizada ou enviada duplicada: `{request_control_key}` |
| 400 | BKS000016 | Bad Request | Expiration date must be greater than the current date and have a maximum of 3650 days from the current date. | A data de vencimento deve ser maior que a data atual e possuir no máximo 3650 dias corridos a partir da data atual. |
| 409 | BKS000017 | Conflict | Our number already used or duplicated sent: `{our_number}` | Nosso número já utilizado ou enviado duplicado: `{our_number}` |
| 400 | BKS000018 | Bad Request | The discount dates must be less than the expiration date and increasing. | A data dos descontos devem ser menores que a de expiração e crescentes. |
| 400 | BKS000019 | Bad Request | Payer address is required for protest. | Endereço do pagador é obrigatório para protesto. |
| 500 | BKS000021 | Internal Server Error | Error while trying to generate QR Code. | Erro ao tentar gerar QR Code de pagamento. |
| 400 | BKS000022 | Bad Request | Requester profile is not opened. | Carteira não está aberta. |
| 400 | BKS000026 | Bad Request | Guarantor address is required for protest. | Endereço do sacador é obrigatório para protesto. |
| 404 | BKS000028 | Not Found | Notary office attended region not found for postal code: `{postal_code}` | Região de cartório não encontrada para o CEP: `{postal_code}` |
| 400 | BKS000043 | Bad Request | Invalid discount numbering. Discounts must be numbered in ascending order and start on 1. | Numeração dos descontos inválida. Os descontos devem ser numerados em ordem crescente e começar em 1. |
| 400 | BKS000045 | Bad Request | Rebate amount can not be equal or greater than the bank slip amount. | O valor do rebate não pode ser igual ou maior do que o valor do boleto. |
| 400 | BKS000047 | Bad Request | It 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. |
| 400 | BKS000125 | Bad Request | Partial payment data is required for this bank slip species type. | Os dados de pagamento parcial são obrigatórios para o tipo de boleto fornecido. |
| 400 | BKS000128 | Bad Request | QR code payment is not allowed for partial payment. | Pagamento via QR code não é permitido para pagamento parcial. |
| 400 | BKS000128 | Bad Request | QR code payment is not allowed for partial payment. | Pagamento via QR code não é permitido para pagamento parcial. |
| 400 | BKS000131 | Bad Request | Rebate amount is not allowed for this bank slip species type. | O valor de abatimento não é permitido para o tipo de boleto fornecido. |
| 400 | BKS000132 | Bad Request | Discount data is not allowed for this bank slip species type. | Os dados de desconto não são permitidos para o tipo de boleto fornecido. |
| 400 | BKS000133 | Bad Request | Fine data is not allowed for this bank slip species type. | Os dados de multa não são permitidos para o tipo de boleto fornecido. |
| 400 | BKS000134 | Bad Request | Interest data is not allowed for this bank slip species type. | Os dados de juros não são permitidos para o tipo de boleto fornecido. |
| 400 | BKS000136 | Bad Request | Only credit card financial instrument type can have zero amount. | Apenas o tipo de instrumento financeiro cartão de crédito pode ter valor zero. |
---
# Emissão de boletos em lote
URL: /en/documentation/boletos/emissao/emissao_em_lote
:::danger Importante
Para registrar bolePix, é necessário que exista uma chave Pix aleatória ativa na conta em que os boletos serão registrados.
:::
A emissão de boletos em lote é feita somente de maneira assíncrona. Caso um dos boletos falhe na validação das informações fornecidas, nenhum dos boletos será registrado nessa mesma requisição.
:::caution Atenção!
Como tratam-se de um registros assíncronos, o solicitante é notificado via [**webhook**](/documentation/boletos/v2/webhooks/boleto) assim que cada um dos boletos mudar de status de `accepted` para `registered` ou `rejected`.
:::
## Request
ENDPOINT /account/ ACCOUNT_KEY /requester_profile/ REQUESTER_PROFILE_KEY /bank_slip/batch
MÉTODO POST
### Path parameters
| Campo | Tipo | Descrição | Caracteres |
|-------------------------|--------|--------------------------------------------------------------|------------|
| `account_key` | uuidv4 | Chave única de identificação da conta, no formato uuid v4 | 36 |
| `requester_profile_key` | uuidv4 | Chave única de identificação da carteira, no formato uuid v4 | 36 |
Request Body
```json
{
"bank_slips": [
{
"request_control_key": "c86d8902-a5ae-4d1f-8872-e6fea1268aab",
"our_number": 123456789,
"document_number": "DOC4561237",
"amount": 5000.00,
"expiration": "2025-01-01",
"bank_teller_instructions": "Confirm payment",
"protest_data": {"days_to_protest": 7},
"bankruptcy_protest_data": {"days_to_bankruptcy_protest": 14},
"max_payment_days": 45,
"fine_data": {"fine_type": "absolute", "fine_amount": 100.00, "days_to_fine": 10},
"interest_data": {
"interest_type": "workdays_daily_amount",
"interest_amount": 10.00,
"days_to_interest": 2,
},
"financial_instrument_type": "digital_commercial_invoice",
"write_off_data": {"days_to_write_off": 365},
"rebate_amount": 200.00,
"discounts_data": [
{
"discount_amount": 50.00,
"discount_number": 1,
"discount_type": "absolute",
"discount_limit_date": "2025-01-01",
}
],
"payer_data": {
"name": "Global Tech",
"contact": {
"email": "finance@globaltech.com",
"phone": {"country_code": "055", "area_code": "11", "number": "987654321"},
},
"address": {
"street": "101 High St.",
"neighborhood": "Tech Park",
"number": "202",
"postal_code": "49069234",
"city": "Innovation City",
"state": "SP",
"complement": "Building A",
},
"document_number": "12345678000195",
"person_type": "legal",
},
"guarantor_data": {
"name": "Jane Doe",
"contact": {
"email": "jane.doe@qitech.com.br",
"phone": {"country_code": "055", "area_code": "11", "number": "999999999"},
},
"address": {
"street": "202 Elm St.",
"neighborhood": "Quiet Neighborhood",
"number": "303",
"postal_code": "35700854",
"city": "Peaceful Town",
"state": "RJ",
"complement": "House 1",
},
"document_number": "23456789012",
"person_type": "natural",
},
"pix_key": "78252991-d26d-4d6b-8c50-be3233ffabf7",
"notification": {
"document_number": "12345678000195",
"name": "Global Tech",
"email": "finance@globaltech.com",
"phone": {"country_code": "055", "area_code": "11", "number": "987654321"},
"send_2_way": true,
"send_before_due_date": true,
"send_after_due_date": true,
"send_on_protest": true
}
},
{
"request_control_key": "b3a428fd-58ee-4d6f-8872-633874ebf5e2",
"our_number": 987654321,
"document_number": "DOC4561237",
"amount": 5000.00,
"expiration": "2025-01-01",
"bank_teller_instructions": "Confirm payment",
"protest_data": {"days_to_protest": 7},
"bankruptcy_protest_data": {"days_to_bankruptcy_protest": 14},
"max_payment_days": 45,
"fine_data": {"fine_type": "absolute", "fine_amount": 100.00, "days_to_fine": 10},
"interest_data": {
"interest_type": "workdays_daily_amount",
"interest_amount": 10.00,
"days_to_interest": 2
},
"financial_instrument_type": "digital_commercial_invoice",
"write_off_data": {"days_to_write_off": 365},
"rebate_amount": 200.00,
"discounts_data": [
{
"discount_amount": 50.00,
"discount_number": 1,
"discount_type": "absolute",
"discount_limit_date": "2025-01-01"
}
],
"payer_data": {
"name": "Global Tech",
"contact": {
"email": "finance@globaltech.com",
"phone": {"country_code": "055", "area_code": "11", "number": "987654321"},
},
"address": {
"street": "101 High St.",
"neighborhood": "Tech Park",
"number": "202",
"postal_code": "79071231",
"city": "Innovation City",
"state": "SP",
"complement": "Building A"
},
"document_number": "12345678000195",
"person_type": "legal"
},
"guarantor_data": {
"name": "Jane Doe",
"contact": {
"email": "jane.doe@qitech.com.br",
"phone": {"country_code": "055", "area_code": "11", "number": "999999999"},
},
"address": {
"street": "202 Elm St.",
"neighborhood": "Quiet Neighborhood",
"number": "303",
"postal_code": "65066380",
"city": "Peaceful Town",
"state": "RJ",
"complement": "House 1"
},
"document_number": "23456789012",
"person_type": "natural"
}
}
]
}
```
### Request Body Params
| Campo | Tipo | Descrição | Caracteres |
|------------------|---------------|---------------------------------------|-------------------------------------------|
| `bank_slips` * | Array de **[Objeto bank_slip](#objeto-bank_slip)** | Lista de boletos a serem registrados | - |
### Objeto bank_slip
| Campo | Tipo | Descrição | Caracteres |
|----------------------------|---------|------------------------------------------------------------------------------------|--------------------------------------------------|
| `request_control_key` * | uuidv4 | Chave única de identificação da request utilizada pelo cliente no formato uuid v4 | 36 |
| `our_number` | integer | Número único de identificação do boleto junto à carteira. Pode ser enviado pelo cliente e, caso não seja, a QI Tech irá gerar um | 11 |
| `document_number` | string | Número de identificação do boleto | 10 |
| `participant_control_number` | string | Nº Controle do Participante |
25 |
| `amount` * | float | Valor base do boleto | - |
| `expiration` * | string | Data de vencimento | 10 |
| `bank_teller_instructions` | string | Instruções adicionais de registro, que constarão no PDF do boleto. Aceita no máximo 320 caracteres, distribuídos em até 7 linhas. Cada linha pode conter no máximo 90 caracteres. Caso uma linha ultrapasse 90 caracteres, o texto será automaticamente quebrado em uma nova linha | 320 |
| `rebate_amount` | float | Valor de abatimento do boleto, que será aplicado em cima do valor base | - |
| `max_payment_days` | integer | Máximo de dias corridos que o boleto ficará disponível para pagamento, após o vencimento (pode ser no máximo 365) | - |
| `financial_instrument_type` | string | Tipo de espécie do boleto | **[Enumeradores financial_instrument_type](#enumeradores-financial_instrument_type)** |
| `partial_payment_data` | object | Configurações de pagamento parcial | **[Objeto partial_payment_data](#objeto-partial_payment_data)** |
| `write_off_data` | object | Configuração de baixa | **[Objeto write_off_data](#objeto-write_off_settings)** |
| `protest_data` | object | Configuração de protesto | **[Objeto protest_data](#objeto-protest_settings)** |
| `bankruptcy_protest_data` | object | Configuração de protesto falimentar | **[Objeto bankruptcy_protest_data](#objeto-bankruptcy_protest_settings)** |
| `fine_data` | object | Configuração de multa | **[Objeto fine_data](#objeto-fine_settings)** |
| `interest_data` | object | Configuração de juros | **[Objeto interest_data](#objeto-interest_settings)** |
| `discounts_data` | object array | Descontos | **[Objeto discount](#objeto-discounts_data)** |
| `payer_data` * | object | Dados do pagador | **[Objeto payer_data](#objetos-payer_data-e-guarantor_data)** |
| `guarantor_data` | object | Dados do sacador avalista | **[Objeto guarantor_data](#objetos-payer_data-e-guarantor_data)** |
| `pix_key` | uuidv4 | Chave pix do tipo aleatória | 36 |
:::info BolePix
Caso o parâmetro `pix_key`, opcional, seja enviado na request, será gerado um bolePix. BolePix é um boleto cujo pagamento é vinculado a um QR Code Pix. Sendo assim, o pagador pode realizar o pagamento do boleto tanto utilizando a linha digitável do mesmo, quanto através da leitura do QR Code Pix vinculado. Caso o pagamento seja feito via QR Code, a liquidação financeira se dá instantaneamente, enquanto os retornos bancários e webhooks envolvidos na liquidação serão gerados assim como é feito para um boleto comum.
Importante: para registrar um bolePix, é necessário que exista uma chave Pix aleatória ativa na conta em que boleto será registrado.
:::
:::tip Configurações Padrão da Carteira
Caso cada um dos campos `max_payment_days`, `write_off_data`, `protest_data`, `bankruptcy_protest_data`, `fine_data`, `interest_data` e `pix_key` não sejam enviados na request e a carteira possua configurações padrão (i.e. `max_payment_days`, `write_off_settings`, `protest_settings`, `bankruptcy_protest_settings`, `fine_settings`, `interest_settings` e `qr_code_settings`, respectivamente, no `configuration_data` do `requester_profile`), serão utilizadas tais configurações padrão para a emissão do título.
:::
:::caution Limitações e Restrições
- **Boletos de Pagamento Parcial:** Não é permitido o pagamento via QR Code Pix. Portanto, não é permitido enviar a `pix_key` no registro, nem ter uma configuração padrão de geração de bolePix para a carteira.
- **Boletos de Cartão de Crédito:** Não é necessário nem permitido enviar informações rebate, desconto, multa e juros. Isso se deve ao padrão do mercado, onde muitas Instituições Financeiras não aceitam o pagamento de boletos de cartão de crédito que contenham essas informações. A carteira também não pode ter essas configurações definidas como padrão. Sendo assim boletos desse tipo podem ser pagos parcialmente mesmo após o vencimento, sem incidência de juros, multas, descontos ou abatimentos na fatura corrente. Para aplicar esses valores é necessário incluí-los na próxima fatura, seja através da [ocorrência de edição de valor](/documentation/boletos/instrucoes/valor) do boleto ou emitindo um novo boleto que inclua esses valores. É possível enviar `amount = 0` para boletos deste tipo.
**Importante:** Boletos do tipo `credit_card` são obrigatoriamente de pagamento parcial, sendo assim é necessário fornecer as informações de `partial_payment_data` ou ter essa configuração padrão na carteira. Caso o campo `financial_instrument_type` não seja enviado, o valor padrão será `digital_commercial_invoice`.
:::
:::tip Recomendações de Carteiras
- **Carteira para Boletos Padrão:** Mantenha as configurações padrão para multas, juros e protesto
- **Carteira para Boletos de Pagamento Parcial:** Sem configuração de Pix e com regras específicas para pagamento parcial
- **Carteira para Boletos de Cartão de Crédito:** Sem configurações de multa, juros, desconto ou rebate
Criar carteiras específicas garante que as configurações padrão sejam adequadas para cada tipo de boleto e evita conflitos nas regras de negócio.
:::
:::info Máquina de Estados
A máquina de status para boletos de pagamento parcial possui algumas diferenças. Para mais detalhes, consulte a [introdução](/documentation/boletos/introducao) , onde há uma explicação sobre como aplicar a incidência de juros e multas no boleto seguindo as boas práticas do mercado.
:::
### Enumeradores financial_instrument_type
| Enumerador | Descrição |
|-------------|----------------------------------|
| digital_commercial_invoice | DMI Duplicata Mercantil Indicação |
| credit_card | Cartão de Crédito |
| check | CH Cheque |
| digital_commercial | DM Duplicata Mercantil |
| digital_service_invoice | Duplicata de Serviço |
| digital_service_invoice_indication | DSI Duplicata de Serviço Indicação |
| digital_rural_invoice | DR Duplicata Rural |
| bill_of_exchange | LC Letra de Câmbio |
| commercial_credit_note | NCC Nota de Crédito Comercial |
| export_credit_note | NCE Nota de Crédito Exportação |
| industrial_credit_note | NCI Nota de Crédito Industrial |
| rural_credit_note | NCR Nota de Crédito Rural |
| promissory_note | NP Nota Promissória |
| rural_promissory_note | NPR Nota Promissória Rural |
| mercantile_triplicate | TM Triplicata Mercantil |
| service_triplicate | TS Triplicata de Serviço |
| insurance_note | NS Nota de Seguro |
| receipt | RC Recibo |
| printed_bank_slip | FAT Bloqueto |
| debit_note | ND Nota de Débito |
| insurance_policy | AP Apólice de Seguro |
| school_monthly_fee | ME Mensalidade Escolar |
| consortium_installment | PC Parcela de Consórcio |
| invoice | NF Nota Fiscal |
| debt_document | DD Documento de Dívida |
| rural_product_certificate | Cédula de Produto Rural |
| warrant | Warrant |
| state_active_debt | Dívida Ativa de Estado |
| municipal_active_debt | Dívida Ativa de Município |
| federal_active_debt | Dívida Ativa da União |
| condominium_charges | Encargos condominiais |
| proposal_bank_slip | Boleto proposta |
| deposit_and_contribution_bank_slip | Boleto de Depósito e Aporte |
| others | Outros |
### Objeto partial_payment_data
| Campo | Tipo | Descrição | Caracteres |
|-----------------------------------|---------|---------------------------------------------------------------------------|------------|
| `partial_payment_minimum_type` * | string | Tipo de valor mínimo para pagamento parcial | **[Enumeradores partial_payment_type](#enumeradores-partial_payment_type)** |
| `partial_payment_minimum_percentage` | float | Percentual mínimo permitido para o pagamento parcial | - |
| `partial_payment_minimum_amount` | float | Valor mínimo permitido para o pagamento parcial | - |
| `partial_payment_maximum_type` | string | Tipo de valor máximo para pagamento parcial | **[Enumeradores partial_payment_type](#enumeradores-partial_payment_type)** |
| `partial_payment_maximum_percentage` | float | Percentual máximo permitido para o pagamento parcial | - |
| `partial_payment_maximum_amount` | float | Valor máximo permitido para o pagamento parcial | - |
| `partial_payment_quantity` * | integer | Quantidade de pagamentos parciais permitidos | - |
:::caution Atenção!
De acordo com o valor enviado nos campos `partial_payment_minimum_type` e `partial_payment_maximum_type`, é necessário enviar o `partial_payment_minimum_amount` ou `partial_payment_minimum_percentage`, e o `partial_payment_maximum_amount` ou `partial_payment_maximum_percentage` correspondente.
:::
### Enumeradores partial_payment_type
| Enumerador | Descrição |
|-------------|----------------------------------|
| absolute | Valor absoluto |
| percentage | Percentual |
### Objeto write_off_data
| Campo | Tipo | Descrição | Caracteres |
|---------------------------|---------|-----------------------------------------------------------------------------|------------|
| `days_to_write_off` * | integer | Dias, após o vencimento, para que o boleto seja baixado automaticamente | - |
### Objeto protest_data
| Campo | Tipo | Descrição | Caracteres |
|---------------------------|---------|-----------------------------------------------------------------------------|------------|
| `days_to_protest` * | integer | Dias, após o vencimento, para que o boleto seja protestado automaticamente | - |
### Objeto bankruptcy_protest_data
| Campo | Tipo | Descrição | Caracteres |
|--------------------------------|---------|-----------------------------------------------------------------------------|------------|
| `days_to_bankruptcy_protest` * | integer | Dias, após o vencimento, para que o boleto seja protestado automaticamente | - |
### Objeto fine_data
Opção 1: multa em valor absoluto (`fine_type=absolute`)
| Campo | Tipo | Descrição | Caracteres |
|---------------------------|---------|---------------------------------------------------------|-------------------------------------------------------------------------|
| `fine_type` * | string | Tipo da multa | **[Enumeradores fine_type](#enumeradores-fine_type)** |
| `fine_amount` * | float | Valor absoluto da multa | - |
| `days_to_fine` * | integer | Dias, após o vencimento, para que a multa seja cobrada | - |
Opção 2: multa em valor percentual (`fine_type=percentage`)
| Campo | Tipo | Descrição | Caracteres |
|---------------------------|---------|-----------------------------------------------------------|---------------------------------------|
| `fine_type` * | string | Tipo da multa | **[Enumeradores fine_type](#enumeradores-fine_type)** |
| `fine_percentage` * | integer | Valor percentual da multa, de 1 a 100 | - |
| `days_to_fine` * | integer | Dias, após o vencimento, para que a multa seja cobrada | - |
### Enumeradores fine_type
| Enumerador | Descrição |
|--------------------|-----------------------|
| absolute | valor absoluto |
| percentage | valor percentual |
### Objeto interest_data
Opção 1: juros utilizando valores absolutos (`interest_type=calendar_days_daily_amount` ou `interest_type=workdays_daily_amount`)
| Campo | Tipo | Descrição | Caracteres |
|---------------------------|---------|-------------------------------------------------------------------------------------|------------------------------------------------------------------------------------------------|
| `interest_type` * | string | Tipo de juros | **[Enumeradores interest_type](#enumeradores-interest_type)** |
| `interest_amount` * | float | Valor a ser cobrado por unidade de tempo determinada (dias úteis ou corridos) | - |
| `days_to_interest` * | integer | Dias, após o vencimento, para que comece a cobrar os juros | - |
Opção 2: juros utilizando valores percentuais (`interest_type=calendar_days_monthly_percentage`)
| Campo | Tipo | Descrição | Caracteres |
|--------------------------|---------|---------------------------------------------------------------------------------------|----------------------------------------------------------------------------------------------------|
| `interest_type` * | string | Tipo de juros | **[Enumeradores interest_type](#enumeradores-interest_type)** |
| `interest_percentage` * | integer | Porcentagem a ser cobrada por unidade de tempo determinada (dias úteis ou corridos) | - |
| `days_to_interest` * | integer | Dias, após o vencimento, para que comece a cobrar os juros | - |
### Enumeradores interest_type
| Enumerador | Descrição |
|----------------------------------|----------------------------------------------------------------------|
| calendar_days_daily_amount | Valor diário sobre dias corridos |
| workdays_daily_amount | Valor diário sobre dias úteis |
| calendar_days_monthly_percentage | Porcentagem de juros cobrados mensalmente, com base em dias corridos |
### Objeto discount
Opção 1: descontos utilizando valores absolutos (`discount_type in ["absolute", "anticipation_calendar_days_daily_amount", "anticipation_workdays_daily_amount"]`)
| Campo | Tipo | Descrição | Caracteres |
|---------------------------|---------|-----------------------------------------------------|-----------------------------------------------------------|
| `discount_amount` * | float | Valor absoluto de desconto por unidade de tempo | - |
| `discount_number` * | integer | Número do desconto | - |
| `discount_type` * | string | Configuração do desconto em valores absolutos | **[Enumerador discount_type](#enumeradores-discount_type)** | |
| `discount_limit_date` * | string | Data limite para aplicação do desconto | 10 |
Opção 2: descontos utilizando valores percentuais (`discount_type in ["percentage", "anticipation_calendar_days_daily_percentage", "anticipation_workdays_daily_percentage"]`)
| Campo | Tipo | Descrição | Caracteres |
|---------------------------|---------|-----------------------------------------------------|-----------------------------------------------------------|
| `discount_percentage` * | float | Valor percentual de desconto por unidade de tempo | - |
| `discount_number` * | integer | Número do desconto | - |
| `discount_type` * | string | Configuração do desconto em valores percentuais | **[Enumerador discount_type](#enumeradores-discount_type)** | |
| `discount_limit_date` * | string | Data limite para aplicação do desconto | 10 |
:::caution Atenção!
O boleto pode ter até três descontos, sendo que os descontos devem ser todos do mesmo tipo , isto é, devem ter o mesmo `discount_type`. Os descontos devem ser numerados de 1 a 3, de maneira crescente e começando necessariamente em 1. Ou seja, caso sejam enviados dois descontos na requisição, devem necessariamente ser numerados com 1 e 2.
:::
### Enumeradores discount_type
| Enumerador | Descrição |
|---------------------------------------------|--------------------------------------------------------------------------|
| absolute | Valor fixo |
| anticipation_calendar_days_daily_amount | Valor diário de desconto de antecipação, sobre dias corridos |
| anticipation_workdays_daily_amount | Valor diário de desconto de antecipação, sobre dias úteis |
| percentage | Porcentagem fixa |
| anticipation_calendar_days_daily_percentage | Porcentagem mensal de desconto de antecipação, com base em dias corridos |
| anticipation_workdays_daily_percentage | Porcentagem anual de desconto de antecipação, com base em dias úteis |
### Objetos payer_data e guarantor_data
| Campo | Tipo | Descrição | Caracteres|
|---------------------------|--------|-------------------------------------|-----------------------------------------------------------|
| `name` * | string | Nome completo | 100 |
| `document_number` * | string | Número do documento (CPF/CNPJ) | 11 ou 14 |
| `person_type` * | string | Tipo da pessoa (física ou jurídica) | **[Enumeradores person_type](#enumeradores-person_type)** |
| `contact` | object | Informações de contato | **[Objeto contact](#objeto-contact)** |
| `address` | object | Endereço | **[Objeto address](#objeto-address)** |
### Enumeradores person_type
| Enumerador | Descrição |
|--------------------|-----------------------|
| natural | pessoa física |
| legal | pessoa jurídica |
### Objeto contact
| Campo | Tipo | Descrição | Caracteres |
|---------------------------|--------|-----------------------------------|------------------------------------|
| `email` | string | E-mail de contato | 320 |
| `phone` | object | Telefone de contato | **[Objeto phone](#objeto-phone)** |
### Objeto phone
| Campo | Tipo | Descrição | Caracteres |
|---------------------------------|--------|----------------------------------------------|------------|
| `country_code` * | string | Código DDI (Discagem Direta Internacional) | 3 |
| `area_code` * | string | Código DDD (Discagem Direta à Distância) | 2 |
| `number` * | string | Complemento | 9 |
### Objeto address
| Campo | Tipo | Descrição | Caracteres |
|---------------------------|--------|----------------------------------------------|------------|
| `street` * | string | Logradouro | 500 |
| `number` * | string | Número | 6 |
| `complement` | string | Complemento | 500 |
| `neighborhood` * | string | Bairro | 100 |
| `postal_code` * | string | CEP | 8 |
| `city` * | string | Cidade | 100 |
| `state` * | string | Estado (UF) | **[Enumerador state](#enumeradores-state)** |
### Enumeradores state
| Enumerador | Descrição |
|--------------------|-----------------------|
| AC | Acre |
| AL | Alagoas |
| AM | Amazonas |
| AP | Amapá |
| BA | Bahia |
| CE | Ceará |
| DF | Distrito federal |
| ES | Espírito Santo |
| GO | Goiás |
| MA | Maranhão |
| MG | Minas Gerais |
| MS | Mato Grosso do Sul |
| MT | Mato Grosso |
| PA | Pará |
| PB | Paraíba |
| PE | Pernambuco |
| PI | Piauí |
| PR | Paraná |
| RJ | Rio de Janeiro |
| RN | Rio Grande do Norte |
| RO | Rondônia |
| RR | Roraima |
| RS | Rio Grande do Sul |
| SC | Santa Catarina |
| SE | Sergipe |
| SP | São Paulo |
| TO | Tocantins |
| EX | Exceção |
### Objeto notification
| Campo | Tipo | Descrição | Caracteres |
|---------------------------|---------|-----------------------------------------------------------------------------------------|------------|
| `document_number` * | string | Número do documento de quem receberá as notificações (CPF/CNPJ) | 11 ou 14 |
| `name` * | string | Nome de quem receberá as notificações | 100 |
| `email` | string | E-mail para o qual serão enviadas as notificações | 320 |
| `phone` | object | Telefone de contato para o qual serão enviadas as notificações | **[Objeto phone](#objeto-phone)** |
| `send_2_way` * | boolean | Enviar segunda via | - |
| `send_before_due_date` * | boolean | Enviar notificação ao pagador antes da data de vencimento | - |
| `send_after_due_date` * | boolean | Enviar notificação ao pagador quando o boleto vencer | - |
| `send_on_protest` * | boolean | Enviar notificação ao entrar em fluxo de protesto | - |
## Response
STATUS 202
Response Body
```json
{
"bank_slips": [
{
"request_control_key": "c86d8902-a5ae-4d1f-8872-e6fea1268aab",
"bank_slip_key": "053c7074-c55c-49aa-b94d-629e8d2424cf",
"bank_slip_status": "accepted",
"our_number": 123456789,
"barcode": "32992995900000892814549111682910713279164650",
"digitable_line": "32994549121168291071332791646501299590000089281",
"qr_code_data": {
"qr_code_key": "0a6ffa83-63ec-438f-95be-76e1ab8329e5",
"pix_key": "78252991-d26d-4d6b-8c50-be3233ffabf7",
"receiver_conciliation_id": "01GVGV9NXBCY287Z6CJ4S0ENW9",
"url": "00020126830014br.gov.bcb.pix2561qrcode.qitech.app/bacen/cobv/58fd5103a8e64bbbab2fd49b0bd580145204000053039865802BR5925GONNFUNDODEINVESTIMENTOEM6012RiodeJaneiro6107226401262070503***6304EA0D",
"image": "/9j/4AAQSkZJRgABAQAAAQABAAD/2wBDAAgGBgcGBQgHBwcJCQgKDBQNDAsLDBkSEw8UHRofHh0aHBwgJC4nICIsIxwcKDcpLDAxNDQ0Hyc5PTgyPC4zNDL/wAALCAD0APQBAREA/8QAHwAAAQUBAQEBAQEAAAAAAAAAAAECAwQFBgcICQoL/8QAtRAAAgEDAwIEAwUFBAQAAAF9AQIDAAQRBRIhMUEGE1FhByJxFDKBkaEII0KxwRVS0fAkM2JyggkKFhcYGRolJicoKSo0NTY3ODk6Q0RFRkdISUpTVFVWV1hZWmNkZWZnaGlqc3R1dnd4eXqDhIWGh4iJipKTlJWWl5iZmqKjpKWmp6ipqrKztLW2t7i5usLDxMXGx8jJytLT1NXW19jZ2uHi4+Tl5ufo6erx8vP09fb3+Pn6/9oACAEBAAA/APf6KKKKKKKKKKKKKKKKKKKKKKKKKKKKKKKKKKKKKKKKKKKKKKKKKKKKKKKKKKKKKKK+QPhl8Mv+Fjf2p/xN/wCz/sHlf8u3m79+/wD21xjZ79a7/wD4Zl/6m7/ym/8A22j/AIZl/wCpu/8AKb/9to/Zl/5mn/t0/wDa1egfE34Zf8LG/sv/AIm/9n/YPN/5dvN379n+2uMbPfrXgHwy+GX/AAsb+1P+Jv8A2f8AYPK/5dvN379/+2uMbPfrR8Tfib/wsb+y/wDiUf2f9g83/l583fv2f7C4xs9+td//AMm5/wDUw/27/wBunkeR/wB/N27zvbG3vnjwCvr/AOJvxN/4Vz/Zf/Eo/tD7f5v/AC8+Vs2bP9hs53+3SvkCvf8A9mX/AJmn/t0/9rUf8m5/9TD/AG7/ANunkeR/383bvO9sbe+ePQPhl8Mv+Fc/2p/xN/7Q+3+V/wAu3lbNm/8A22znf7dK8A+GXxN/4Vz/AGp/xKP7Q+3+V/y8+Vs2b/8AYbOd/t0o+GXxN/4Vz/an/Eo/tD7f5X/Lz5WzZv8A9hs53+3Svf8A4m/DL/hY39l/8Tf+z/sHm/8ALt5u/fs/21xjZ79a8/8A+GZf+pu/8pv/ANtr0D4ZfE3/AIWN/an/ABKP7P8AsHlf8vPm79+//YXGNnv1rwD4ZfE3/hXP9qf8Sj+0Pt/lf8vPlbNm/wD2Gznf7dK7/wD4aa/6lH/ypf8A2quA+GXxN/4Vz/an/Eo/tD7f5X/Lz5WzZv8A9hs53+3Svr+vkD4ZfDL/AIWN/an/ABN/7P8AsHlf8u3m79+//bXGNnv1rv8A/hmX/qbv/Kb/APbaP+GZf+pu/wDKb/8AbaP2Zf8Amaf+3T/2tX0BRRRXz/8Asy/8zT/26f8AtavAK9//AGZf+Zp/7dP/AGtR+zL/AMzT/wBun/tavQPib8Mv+Fjf2X/xN/7P+web/wAu3m79+z/bXGNnv1rz/wDZl/5mn/t0/wDa1cB8Mvib/wAK5/tT/iUf2h9v8r/l58rZs3/7DZzv9ule/wDwy+Jv/Cxv7U/4lH9n/YPK/wCXnzd+/f8A7C4xs9+teAfE34Zf8K5/sv8A4m/9ofb/ADf+XbytmzZ/ttnO/wBule//ABN+Jv8Awrn+y/8AiUf2h9v83/l58rZs2f7DZzv9uleAfDL4Zf8ACxv7U/4m/wDZ/wBg8r/l283fv3/7a4xs9+tHxN+GX/Cuf7L/AOJv/aH2/wA3/l28rZs2f7bZzv8AbpXv/wAMvhl/wrn+1P8Aib/2h9v8r/l28rZs3/7bZzv9ulef/tNf8yt/29/+0a9A+GXxN/4WN/an/Eo/s/7B5X/Lz5u/fv8A9hcY2e/WvP8A/k3P/qYf7d/7dPI8j/v5u3ed7Y2988cB8Tfhl/wrn+y/+Jv/AGh9v83/AJdvK2bNn+22c7/bpXf/APDTX/Uo/wDlS/8AtVcB8Tfhl/wrn+y/+Jv/AGh9v83/AJdvK2bNn+22c7/bpX1/Xz//AMm5/wDUw/27/wBunkeR/wB/N27zvbG3vng/5OM/6l7+wv8At78/z/8Av3t2+T753dsc+gfDL4m/8LG/tT/iUf2f9g8r/l583fv3/wCwuMbPfrXn/wCzL/zNP/bp/wC1q8Ar3/8AZl/5mn/t0/8Aa1H7Mv8AzNP/AG6f+1q+gKKKK+f/ANmX/maf+3T/ANrUf8My/wDU3f8AlN/+216B8Mvhl/wrn+1P+Jv/AGh9v8r/AJdvK2bN/wDttnO/26V5/wDsy/8AM0/9un/taj/k4z/qXv7C/wC3vz/P/wC/e3b5Pvnd2xyf8nGf9S9/YX/b35/n/wDfvbt8n3zu7Y5P2mv+ZW/7e/8A2jR+zL/zNP8A26f+1qP+Tc/+ph/t3/t08jyP+/m7d53tjb3zx4BXv/7TX/Mrf9vf/tGj/k3P/qYf7d/7dPI8j/v5u3ed7Y2988cB8Mvhl/wsb+1P+Jv/AGf9g8r/AJdvN379/wDtrjGz3613/wDwzL/1N3/lN/8AttH7Mv8AzNP/AG6f+1q4D4m/DL/hXP8AZf8AxN/7Q+3+b/y7eVs2bP8AbbOd/t0rv/8Ahpr/AKlH/wAqX/2qj/k4z/qXv7C/7e/P8/8A797dvk++d3bHJ/ybn/1MP9u/9unkeR/383bvO9sbe+ePQPhl8Mv+Fc/2p/xN/wC0Pt/lf8u3lbNm/wD22znf7dKPib8Mv+Fjf2X/AMTf+z/sHm/8u3m79+z/AG1xjZ79a8//AGZf+Zp/7dP/AGtX0BXz/wDsy/8AM0/9un/taj/hmX/qbv8Aym//AG2vQPhl8Mv+Fc/2p/xN/wC0Pt/lf8u3lbNm/wD22znf7dK8/wD2Zf8Amaf+3T/2tX0BRRRXz/8A8My/9Td/5Tf/ALbR/wAMy/8AU3f+U3/7bR/wzL/1N3/lN/8AttegfDL4Zf8ACuf7U/4m/wDaH2/yv+Xbytmzf/ttnO/26V5//wAm5/8AUw/27/26eR5H/fzdu872xt7549A+GXwy/wCFc/2p/wATf+0Pt/lf8u3lbNm//bbOd/t0rz/9mX/maf8At0/9rVwHwy+Jv/Cuf7U/4lH9ofb/ACv+Xnytmzf/ALDZzv8AbpR8Mvib/wAK5/tT/iUf2h9v8r/l58rZs3/7DZzv9ulHwy+Jv/Cuf7U/4lH9ofb/ACv+Xnytmzf/ALDZzv8AbpXf/sy/8zT/ANun/tavQPhl8Mv+Fc/2p/xN/wC0Pt/lf8u3lbNm/wD22znf7dK8/wD2Zf8Amaf+3T/2tXoHwy+GX/Cuf7U/4m/9ofb/ACv+Xbytmzf/ALbZzv8AbpXgHwy+Jv8Awrn+1P8AiUf2h9v8r/l58rZs3/7DZzv9uld/+zL/AMzT/wBun/tavQPhl8Mv+Fc/2p/xN/7Q+3+V/wAu3lbNm/8A22znf7dK8A+GXxN/4Vz/AGp/xKP7Q+3+V/y8+Vs2b/8AYbOd/t0o+GXxN/4Vz/an/Eo/tD7f5X/Lz5WzZv8A9hs53+3Su/8A2Zf+Zp/7dP8A2tR/ybn/ANTD/bv/AG6eR5H/AH83bvO9sbe+eD9mX/maf+3T/wBrUfsy/wDM0/8Abp/7Wo/4Zl/6m7/ym/8A22j/AIZl/wCpu/8AKb/9to/4Zl/6m7/ym/8A22vQPhl8Mv8AhXP9qf8AE3/tD7f5X/Lt5WzZv/22znf7dK9Aooor5/8A2Zf+Zp/7dP8A2tXAfE34m/8ACxv7L/4lH9n/AGDzf+Xnzd+/Z/sLjGz360fE34m/8LG/sv8A4lH9n/YPN/5efN379n+wuMbPfrXv/wAMvhl/wrn+1P8Aib/2h9v8r/l28rZs3/7bZzv9ulfIFFegfDL4m/8ACuf7U/4lH9ofb/K/5efK2bN/+w2c7/bpXf8A7TX/ADK3/b3/AO0a9A+GXxN/4WN/an/Eo/s/7B5X/Lz5u/fv/wBhcY2e/WvAPib8Mv8AhXP9l/8AE3/tD7f5v/Lt5WzZs/22znf7dKPib8Mv+Fc/2X/xN/7Q+3+b/wAu3lbNmz/bbOd/t0rv/wBmX/maf+3T/wBrVwHxN+GX/Cuf7L/4m/8AaH2/zf8Al28rZs2f7bZzv9ulHxN+GX/Cuf7L/wCJv/aH2/zf+XbytmzZ/ttnO/26V3//AAzL/wBTd/5Tf/ttH7TX/Mrf9vf/ALRrgPhl8Tf+Fc/2p/xKP7Q+3+V/y8+Vs2b/APYbOd/t0o+Jvwy/4Vz/AGX/AMTf+0Pt/m/8u3lbNmz/AG2znf7dK7//AJOM/wCpe/sL/t78/wA//v3t2+T753dscn/Juf8A1MP9u/8Abp5Hkf8Afzdu872xt7548Ar3/wD5Nz/6mH+3f+3TyPI/7+bt3ne2NvfPHAfE34Zf8K5/sv8A4m/9ofb/ADf+XbytmzZ/ttnO/wBuld/+01/zK3/b3/7Rr6Aorz/4ZfE3/hY39qf8Sj+z/sHlf8vPm79+/wD2FxjZ79a9Aooor5A+Jvwy/wCFc/2X/wATf+0Pt/m/8u3lbNmz/bbOd/t0o+JvxN/4WN/Zf/Eo/s/7B5v/AC8+bv37P9hcY2e/Wu//AGmv+ZW/7e//AGjXoHwy+GX/AArn+1P+Jv8A2h9v8r/l28rZs3/7bZzv9ulHwy+Jv/Cxv7U/4lH9n/YPK/5efN379/8AsLjGz3615/8A8nGf9S9/YX/b35/n/wDfvbt8n3zu7Y5+gK+QPib8Tf8AhY39l/8AEo/s/wCweb/y8+bv37P9hcY2e/Wvf/hl8Tf+Fjf2p/xKP7P+weV/y8+bv37/APYXGNnv1rz/AP4aa/6lH/ypf/aq9A+Jvwy/4WN/Zf8AxN/7P+web/y7ebv37P8AbXGNnv1r0CvkD4m/DL/hXP8AZf8AxN/7Q+3+b/y7eVs2bP8AbbOd/t0rv/8Ahpr/AKlH/wAqX/2qj/hmX/qbv/Kb/wDbaP8Ak3P/AKmH+3f+3TyPI/7+bt3ne2NvfPHoHxN+Jv8Awrn+y/8AiUf2h9v83/l58rZs2f7DZzv9ulHwy+GX/Cuf7U/4m/8AaH2/yv8Al28rZs3/AO22c7/bpXn/AO01/wAyt/29/wDtGj/hpr/qUf8Aypf/AGqj/k4z/qXv7C/7e/P8/wD797dvk++d3bHJ/wANNf8AUo/+VL/7VXAfE34Zf8K5/sv/AIm/9ofb/N/5dvK2bNn+22c7/bpR8Mvib/wrn+1P+JR/aH2/yv8Al58rZs3/AOw2c7/bpR8Mvhl/wsb+1P8Aib/2f9g8r/l283fv3/7a4xs9+tHwy+Jv/Cuf7U/4lH9ofb/K/wCXnytmzf8A7DZzv9ulfX9FFFFfP/8AwzL/ANTd/wCU3/7bXoHwy+GX/Cuf7U/4m/8AaH2/yv8Al28rZs3/AO22c7/bpXgHwy+GX/Cxv7U/4m/9n/YPK/5dvN379/8AtrjGz3613/8AwzL/ANTd/wCU3/7bR/w01/1KP/lS/wDtVegfDL4Zf8K5/tT/AIm/9ofb/K/5dvK2bN/+22c7/bpR8Mvib/wsb+1P+JR/Z/2Dyv8Al583fv3/AOwuMbPfrR8Mvhl/wrn+1P8Aib/2h9v8r/l28rZs3/7bZzv9uleAfE34Zf8ACuf7L/4m/wDaH2/zf+XbytmzZ/ttnO/26V3/AO01/wAyt/29/wDtGuA+GXwy/wCFjf2p/wATf+z/ALB5X/Lt5u/fv/21xjZ79a9/+Jvwy/4WN/Zf/E3/ALP+web/AMu3m79+z/bXGNnv1rwD4m/DL/hXP9l/8Tf+0Pt/m/8ALt5WzZs/22znf7dK9/8Aib8Tf+Fc/wBl/wDEo/tD7f5v/Lz5WzZs/wBhs53+3SvP/wBpr/mVv+3v/wBo0f8AJuf/AFMP9u/9unkeR/383bvO9sbe+eD9mX/maf8At0/9rV4BXoHwy+Jv/Cuf7U/4lH9ofb/K/wCXnytmzf8A7DZzv9uld/8A8m5/9TD/AG7/ANunkeR/383bvO9sbe+eOA+GXxN/4Vz/AGp/xKP7Q+3+V/y8+Vs2b/8AYbOd/t0rv/8Ak3P/AKmH+3f+3TyPI/7+bt3ne2NvfPHoHxN+GX/Cxv7L/wCJv/Z/2Dzf+Xbzd+/Z/trjGz3614B8Mvib/wAK5/tT/iUf2h9v8r/l58rZs3/7DZzv9ule/wDxN+Jv/Cuf7L/4lH9ofb/N/wCXnytmzZ/sNnO/26UfE34m/wDCuf7L/wCJR/aH2/zf+XnytmzZ/sNnO/26V5/+zL/zNP8A26f+1q+gKKKK+f8A/k3P/qYf7d/7dPI8j/v5u3ed7Y2988H/ACbn/wBTD/bv/bp5Hkf9/N27zvbG3vnjgPib8Mv+Fc/2X/xN/wC0Pt/m/wDLt5WzZs/22znf7dK9/wDhl8Mv+Fc/2p/xN/7Q+3+V/wAu3lbNm/8A22znf7dKPib8Mv8AhY39l/8AE3/s/wCweb/y7ebv37P9tcY2e/WvAPib8Mv+Fc/2X/xN/wC0Pt/m/wDLt5WzZs/22znf7dK8/r3/APaa/wCZW/7e/wD2jXAfDL4m/wDCuf7U/wCJR/aH2/yv+Xnytmzf/sNnO/26V7/8Mvhl/wAK5/tT/ib/ANofb/K/5dvK2bN/+22c7/bpXn//AA01/wBSj/5Uv/tVegfE34m/8K5/sv8A4lH9ofb/ADf+XnytmzZ/sNnO/wBulHxN+Jv/AArn+y/+JR/aH2/zf+XnytmzZ/sNnO/26V5/+01/zK3/AG9/+0aP2Zf+Zp/7dP8A2tR+zL/zNP8A26f+1qP+TjP+pe/sL/t78/z/APv3t2+T753dsc+AV7/+zL/zNP8A26f+1q9A+GXwy/4Vz/an/E3/ALQ+3+V/y7eVs2b/APbbOd/t0rwD4ZfDL/hY39qf8Tf+z/sHlf8ALt5u/fv/ANtcY2e/Wvf/AIm/E3/hXP8AZf8AxKP7Q+3+b/y8+Vs2bP8AYbOd/t0rwD4m/DL/AIVz/Zf/ABN/7Q+3+b/y7eVs2bP9ts53+3Su/wD2mv8AmVv+3v8A9o1wHwy+Jv8Awrn+1P8AiUf2h9v8r/l58rZs3/7DZzv9ulHxN+GX/Cuf7L/4m/8AaH2/zf8Al28rZs2f7bZzv9ule/8Awy+GX/Cuf7U/4m/9ofb/ACv+Xbytmzf/ALbZzv8AbpXoFFFFfIHwy+GX/Cxv7U/4m/8AZ/2Dyv8Al283fv3/AO2uMbPfrXf/APDMv/U3f+U3/wC20f8AJxn/AFL39hf9vfn+f/3727fJ987u2OfQPhl8Mv8AhXP9qf8AE3/tD7f5X/Lt5WzZv/22znf7dK8//wCGmv8AqUf/ACpf/aq8Ar3/AP4aa/6lH/ypf/aq9A+GXwy/4Vz/AGp/xN/7Q+3+V/y7eVs2b/8AbbOd/t0rwD4m/DL/AIVz/Zf/ABN/7Q+3+b/y7eVs2bP9ts53+3Svf/ib8Mv+Fjf2X/xN/wCz/sHm/wDLt5u/fs/21xjZ79a8/wD+TjP+pe/sL/t78/z/APv3t2+T753dsc+gfDL4m/8ACxv7U/4lH9n/AGDyv+Xnzd+/f/sLjGz360fDL4Zf8K5/tT/ib/2h9v8AK/5dvK2bN/8AttnO/wBulef/APJxn/Uvf2F/29+f5/8A3727fJ987u2OT/hpr/qUf/Kl/wDaqP2mv+ZW/wC3v/2jR+zL/wAzT/26f+1q8Ar3/wD4Zl/6m7/ym/8A22vQPhl8Tf8AhY39qf8AEo/s/wCweV/y8+bv37/9hcY2e/Wj4m/E3/hXP9l/8Sj+0Pt/m/8ALz5WzZs/2Gznf7dKPib8Mv8AhY39l/8AE3/s/wCweb/y7ebv37P9tcY2e/Wj4ZfE3/hY39qf8Sj+z/sHlf8ALz5u/fv/ANhcY2e/Wj4ZfDL/AIVz/an/ABN/7Q+3+V/y7eVs2b/9ts53+3SvQK+f/wDk4z/qXv7C/wC3vz/P/wC/e3b5Pvnd2xz9AUUUUV5/8Mvhl/wrn+1P+Jv/AGh9v8r/AJdvK2bN/wDttnO/26V5/wD8m5/9TD/bv/bp5Hkf9/N27zvbG3vnjwCvQPib8Mv+Fc/2X/xN/wC0Pt/m/wDLt5WzZs/22znf7dK7/wD5Nz/6mH+3f+3TyPI/7+bt3ne2NvfPHAfDL4m/8K5/tT/iUf2h9v8AK/5efK2bN/8AsNnO/wBulHwy+GX/AAsb+1P+Jv8A2f8AYPK/5dvN379/+2uMbPfrXf8A7TX/ADK3/b3/AO0a4D4m/DL/AIVz/Zf/ABN/7Q+3+b/y7eVs2bP9ts53+3Sj4ZfDL/hY39qf8Tf+z/sHlf8ALt5u/fv/ANtcY2e/Wu//AGmv+ZW/7e//AGjXoHxN+GX/AAsb+y/+Jv8A2f8AYPN/5dvN379n+2uMbPfrXoFfIHwy+Jv/AArn+1P+JR/aH2/yv+Xnytmzf/sNnO/26UfDL4Zf8LG/tT/ib/2f9g8r/l283fv3/wC2uMbPfrXf/wDDTX/Uo/8AlS/+1Ufsy/8AM0/9un/tavAK9A+GXwy/4WN/an/E3/s/7B5X/Lt5u/fv/wBtcY2e/Wu//wCGmv8AqUf/ACpf/aq4D4ZfE3/hXP8Aan/Eo/tD7f5X/Lz5WzZv/wBhs53+3Su//wCTjP8AqXv7C/7e/P8AP/797dvk++d3bHPoHxN+Jv8Awrn+y/8AiUf2h9v83/l58rZs2f7DZzv9ulHxN+Jv/Cuf7L/4lH9ofb/N/wCXnytmzZ/sNnO/26UfDL4m/wDCxv7U/wCJR/Z/2Dyv+Xnzd+/f/sLjGz360fE34m/8K5/sv/iUf2h9v83/AJefK2bNn+w2c7/bpR8Mvib/AMLG/tT/AIlH9n/YPK/5efN379/+wuMbPfrXoFFFFfIHwy+Jv/Cuf7U/4lH9ofb/ACv+Xnytmzf/ALDZzv8AbpX1/XwBXoHxN+GX/Cuf7L/4m/8AaH2/zf8Al28rZs2f7bZzv9ule/8Awy+Jv/Cxv7U/4lH9n/YPK/5efN379/8AsLjGz360fE34m/8ACuf7L/4lH9ofb/N/5efK2bNn+w2c7/bpR8Mvhl/wrn+1P+Jv/aH2/wAr/l28rZs3/wC22c7/AG6V5/8Asy/8zT/26f8AtauA+JvxN/4WN/Zf/Eo/s/7B5v8Ay8+bv37P9hcY2e/Wvf8A4m/E3/hXP9l/8Sj+0Pt/m/8ALz5WzZs/2Gznf7dK8A+JvxN/4WN/Zf8AxKP7P+web/y8+bv37P8AYXGNnv1r3/4m/E3/AIVz/Zf/ABKP7Q+3+b/y8+Vs2bP9hs53+3SvP/8Ak3P/AKmH+3f+3TyPI/7+bt3ne2NvfPB/w01/1KP/AJUv/tVegfE34m/8K5/sv/iUf2h9v83/AJefK2bNn+w2c7/bpXn/AO01/wAyt/29/wDtGj/hpr/qUf8Aypf/AGqvoCvkD4ZfE3/hXP8Aan/Eo/tD7f5X/Lz5WzZv/wBhs53+3Svf/ib8Tf8AhXP9l/8AEo/tD7f5v/Lz5WzZs/2Gznf7dK8//wCGZf8Aqbv/ACm//baP2mv+ZW/7e/8A2jR/ybn/ANTD/bv/AG6eR5H/AH83bvO9sbe+ePQPib8Tf+Fc/wBl/wDEo/tD7f5v/Lz5WzZs/wBhs53+3SvAPhl8Tf8AhXP9qf8AEo/tD7f5X/Lz5WzZv/2Gznf7dK9/+GXxN/4WN/an/Eo/s/7B5X/Lz5u/fv8A9hcY2e/Wj4ZfE3/hY39qf8Sj+z/sHlf8vPm79+//AGFxjZ79a9Aoooor5/8A2Zf+Zp/7dP8A2tR/wzL/ANTd/wCU3/7bR/ybn/1MP9u/9unkeR/383bvO9sbe+ePQPib8Tf+Fc/2X/xKP7Q+3+b/AMvPlbNmz/YbOd/t0o+JvxN/4Vz/AGX/AMSj+0Pt/m/8vPlbNmz/AGGznf7dK8A+Jvwy/wCFc/2X/wATf+0Pt/m/8u3lbNmz/bbOd/t0r3/4m/DL/hY39l/8Tf8As/7B5v8Ay7ebv37P9tcY2e/Wj4m/E3/hXP8AZf8AxKP7Q+3+b/y8+Vs2bP8AYbOd/t0r5Ar0D4ZfE3/hXP8Aan/Eo/tD7f5X/Lz5WzZv/wBhs53+3Su//wCGmv8AqUf/ACpf/aq4D4ZfE3/hXP8Aan/Eo/tD7f5X/Lz5WzZv/wBhs53+3Su//aa/5lb/ALe//aNcB8Mvhl/wsb+1P+Jv/Z/2Dyv+Xbzd+/f/ALa4xs9+tHxN+Jv/AAsb+y/+JR/Z/wBg83/l583fv2f7C4xs9+te/wDwy+GX/Cuf7U/4m/8AaH2/yv8Al28rZs3/AO22c7/bpXgHwy+GX/Cxv7U/4m/9n/YPK/5dvN379/8AtrjGz360fE34Zf8ACuf7L/4m/wDaH2/zf+XbytmzZ/ttnO/26V5/Xv8A+01/zK3/AG9/+0a4D4ZfDL/hY39qf8Tf+z/sHlf8u3m79+//AG1xjZ79a9/+GXxN/wCFjf2p/wASj+z/ALB5X/Lz5u/fv/2FxjZ79aPhl8Mv+Fc/2p/xN/7Q+3+V/wAu3lbNm/8A22znf7dK+QK9/wD2Zf8Amaf+3T/2tX0BRRRRXyB8Tfhl/wAK5/sv/ib/ANofb/N/5dvK2bNn+22c7/bpXf8A/DTX/Uo/+VL/AO1VwHwy+GX/AAsb+1P+Jv8A2f8AYPK/5dvN379/+2uMbPfrXf8A/DMv/U3f+U3/AO21wHwy+Jv/AArn+1P+JR/aH2/yv+Xnytmzf/sNnO/26UfDL4m/8K5/tT/iUf2h9v8AK/5efK2bN/8AsNnO/wBule//ABN+Jv8Awrn+y/8AiUf2h9v83/l58rZs2f7DZzv9uleAfE34m/8ACxv7L/4lH9n/AGDzf+Xnzd+/Z/sLjGz3615/XoHxN+Jv/Cxv7L/4lH9n/YPN/wCXnzd+/Z/sLjGz3613/wC01/zK3/b3/wC0a9A+GXwy/wCFc/2p/wATf+0Pt/lf8u3lbNm//bbOd/t0rwD4ZfDL/hY39qf8Tf8As/7B5X/Lt5u/fv8A9tcY2e/Wu/8A+GZf+pu/8pv/ANtrgPhl8Mv+Fjf2p/xN/wCz/sHlf8u3m79+/wD21xjZ79a8/r0D4ZfDL/hY39qf8Tf+z/sHlf8ALt5u/fv/ANtcY2e/Wj4m/E3/AIWN/Zf/ABKP7P8AsHm/8vPm79+z/YXGNnv1rv8A/hpr/qUf/Kl/9qr0D4m/DL/hY39l/wDE3/s/7B5v/Lt5u/fs/wBtcY2e/WvP/wBmX/maf+3T/wBrV6B8Mvib/wALG/tT/iUf2f8AYPK/5efN379/+wuMbPfrXgHwy+GX/Cxv7U/4m/8AZ/2Dyv8Al283fv3/AO2uMbPfrXf/APDMv/U3f+U3/wC20fsy/wDM0/8Abp/7WrgPib8Mv+Fc/wBl/wDE3/tD7f5v/Lt5WzZs/wBts53+3Svf/hl8Mv8AhXP9qf8AE3/tD7f5X/Lt5WzZv/22znf7dK9Aooorz/4m/DL/AIWN/Zf/ABN/7P8AsHm/8u3m79+z/bXGNnv1rwD4ZfE3/hXP9qf8Sj+0Pt/lf8vPlbNm/wD2Gznf7dK7/wDZl/5mn/t0/wDa1egfDL4Zf8K5/tT/AIm/9ofb/K/5dvK2bN/+22c7/bpXgHwy+GX/AAsb+1P+Jv8A2f8AYPK/5dvN379/+2uMbPfrR8Tfhl/wrn+y/wDib/2h9v8AN/5dvK2bNn+22c7/AG6V3/7TX/Mrf9vf/tGuA+GXxN/4Vz/an/Eo/tD7f5X/AC8+Vs2b/wDYbOd/t0o+Jvwy/wCFc/2X/wATf+0Pt/m/8u3lbNmz/bbOd/t0r6/rz/4ZfDL/AIVz/an/ABN/7Q+3+V/y7eVs2b/9ts53+3Sj4ZfDL/hXP9qf8Tf+0Pt/lf8ALt5WzZv/ANts53+3SvP/ANmX/maf+3T/ANrV6B8Mvhl/wrn+1P8Aib/2h9v8r/l28rZs3/7bZzv9uleAfDL4m/8ACuf7U/4lH9ofb/K/5efK2bN/+w2c7/bpX1/RRXyB8Tfib/wsb+y/+JR/Z/2Dzf8Al583fv2f7C4xs9+td/8A8m5/9TD/AG7/ANunkeR/383bvO9sbe+ePAK+v/ib8Tf+Fc/2X/xKP7Q+3+b/AMvPlbNmz/YbOd/t0rz/APZl/wCZp/7dP/a1egfDL4Zf8K5/tT/ib/2h9v8AK/5dvK2bN/8AttnO/wBuleAfDL4m/wDCuf7U/wCJR/aH2/yv+Xnytmzf/sNnO/26V7/8Tfhl/wALG/sv/ib/ANn/AGDzf+Xbzd+/Z/trjGz3615/+zL/AMzT/wBun/tavoCiiivP/ib8Tf8AhXP9l/8AEo/tD7f5v/Lz5WzZs/2Gznf7dK8//wCTc/8AqYf7d/7dPI8j/v5u3ed7Y2988H/DMv8A1N3/AJTf/ttH/DMv/U3f+U3/AO214BXv/wDwzL/1N3/lN/8AttH/AA01/wBSj/5Uv/tVH/DMv/U3f+U3/wC214BXoHwy+GX/AAsb+1P+Jv8A2f8AYPK/5dvN379/+2uMbPfrXf8A7Mv/ADNP/bp/7Wr0D4ZfE3/hY39qf8Sj+z/sHlf8vPm79+//AGFxjZ79a8//AOGZf+pu/wDKb/8Aba4D4ZfDL/hY39qf8Tf+z/sHlf8ALt5u/fv/ANtcY2e/Wj4ZfDL/AIWN/an/ABN/7P8AsHlf8u3m79+//bXGNnv1r3/4m/DL/hY39l/8Tf8As/7B5v8Ay7ebv37P9tcY2e/WvP8A9mX/AJmn/t0/9rV9AV8//wDDMv8A1N3/AJTf/ttH/Jxn/Uvf2F/29+f5/wD3727fJ987u2OfQPib8Mv+Fjf2X/xN/wCz/sHm/wDLt5u/fs/21xjZ79a9Ar5A+Jvwy/4Vz/Zf/E3/ALQ+3+b/AMu3lbNmz/bbOd/t0o+Jvwy/4Vz/AGX/AMTf+0Pt/m/8u3lbNmz/AG2znf7dK9/+GXwy/wCFc/2p/wATf+0Pt/lf8u3lbNm//bbOd/t0rz//AJOM/wCpe/sL/t78/wA//v3t2+T753dscn7Mv/M0/wDbp/7Wr6Aooorz/wCGXwy/4Vz/AGp/xN/7Q+3+V/y7eVs2b/8AbbOd/t0rz/8A4Zl/6m7/AMpv/wBto/Zl/wCZp/7dP/a1H/Juf/Uw/wBu/wDbp5Hkf9/N27zvbG3vng/Zl/5mn/t0/wDa1H/Juf8A1MP9u/8Abp5Hkf8Afzdu872xt7544D4ZfDL/AIWN/an/ABN/7P8AsHlf8u3m79+//bXGNnv1o+GXwy/4WN/an/E3/s/7B5X/AC7ebv37/wDbXGNnv1o+JvxN/wCFjf2X/wASj+z/ALB5v/Lz5u/fs/2FxjZ79aPhl8Mv+Fjf2p/xN/7P+weV/wAu3m79+/8A21xjZ79a7/8A5OM/6l7+wv8At78/z/8Av3t2+T753dsc8B8Mvib/AMK5/tT/AIlH9ofb/K/5efK2bN/+w2c7/bpXv/xN+GX/AAsb+y/+Jv8A2f8AYPN/5dvN379n+2uMbPfrXn//AA01/wBSj/5Uv/tVegfDL4m/8LG/tT/iUf2f9g8r/l583fv3/wCwuMbPfrXn/wCzL/zNP/bp/wC1q4D4ZfE3/hXP9qf8Sj+0Pt/lf8vPlbNm/wD2Gznf7dKPib8Mv+Fc/wBl/wDE3/tD7f5v/Lt5WzZs/wBts53+3Su//Zl/5mn/ALdP/a1fQFef/E34Zf8ACxv7L/4m/wDZ/wBg83/l283fv2f7a4xs9+tef/8ADTX/AFKP/lS/+1VwHxN+GX/Cuf7L/wCJv/aH2/zf+XbytmzZ/ttnO/26V5/Xv/8AwzL/ANTd/wCU3/7bR/ybn/1MP9u/9unkeR/383bvO9sbe+eD9mX/AJmn/t0/9rV9AUUUV8AUV7//AMnGf9S9/YX/AG9+f5//AH727fJ987u2OfQPhl8Mv+Fc/wBqf8Tf+0Pt/lf8u3lbNm//AG2znf7dK8A+Jvwy/wCFc/2X/wATf+0Pt/m/8u3lbNmz/bbOd/t0rv8A9pr/AJlb/t7/APaNH/DMv/U3f+U3/wC20f8ADMv/AFN3/lN/+216B8Mvhl/wrn+1P+Jv/aH2/wAr/l28rZs3/wC22c7/AG6V5/8A8nGf9S9/YX/b35/n/wDfvbt8n3zu7Y59A+Jvwy/4WN/Zf/E3/s/7B5v/AC7ebv37P9tcY2e/WvQK+QPib8Tf+Fjf2X/xKP7P+web/wAvPm79+z/YXGNnv1o+Jvwy/wCFc/2X/wATf+0Pt/m/8u3lbNmz/bbOd/t0r3/4m/DL/hY39l/8Tf8As/7B5v8Ay7ebv37P9tcY2e/Wj4ZfE3/hY39qf8Sj+z/sHlf8vPm79+//AGFxjZ79a8//AOTjP+pe/sL/ALe/P8//AL97dvk++d3bHPoHxN+Jv/Cuf7L/AOJR/aH2/wA3/l58rZs2f7DZzv8AbpR8Mvhl/wAK5/tT/ib/ANofb/K/5dvK2bN/+22c7/bpXgHxN+GX/Cuf7L/4m/8AaH2/zf8Al28rZs2f7bZzv9uld/8A8My/9Td/5Tf/ALbXoHxN+Jv/AArn+y/+JR/aH2/zf+XnytmzZ/sNnO/26V5/+zL/AMzT/wBun/taj/k3P/qYf7d/7dPI8j/v5u3ed7Y2988fQFfP/wDybn/1MP8Abv8A26eR5H/fzdu872xt754+gKKKKK+AK+v/AIZfE3/hY39qf8Sj+z/sHlf8vPm79+//AGFxjZ79aPhl8Tf+Fjf2p/xKP7P+weV/y8+bv37/APYXGNnv1rwD4m/DL/hXP9l/8Tf+0Pt/m/8ALt5WzZs/22znf7dK9/8Ahl8Mv+Fc/wBqf8Tf+0Pt/lf8u3lbNm//AG2znf7dK8//AOGZf+pu/wDKb/8Aba8Ar6/+Jvwy/wCFjf2X/wATf+z/ALB5v/Lt5u/fs/21xjZ79aPib8Mv+Fjf2X/xN/7P+web/wAu3m79+z/bXGNnv1rz/wD4Zl/6m7/ym/8A22j/AJNz/wCph/t3/t08jyP+/m7d53tjb3zx6B8Mvhl/wrn+1P8Aib/2h9v8r/l28rZs3/7bZzv9ulHwy+GX/Cuf7U/4m/8AaH2/yv8Al28rZs3/AO22c7/bpXgHwy+Jv/Cuf7U/4lH9ofb/ACv+Xnytmzf/ALDZzv8AbpXv/wAMvib/AMLG/tT/AIlH9n/YPK/5efN379/+wuMbPfrXgHxN+GX/AArn+y/+Jv8A2h9v83/l28rZs2f7bZzv9uld/wD8NNf9Sj/5Uv8A7VX0BXyB8Mvhl/wsb+1P+Jv/AGf9g8r/AJdvN379/wDtrjGz3619f18//wDDTX/Uo/8AlS/+1V6B8Tfhl/wsb+y/+Jv/AGf9g83/AJdvN379n+2uMbPfrR8Mvib/AMLG/tT/AIlH9n/YPK/5efN379/+wuMbPfrR8Mvib/wsb+1P+JR/Z/2Dyv8Al583fv3/AOwuMbPfrR8Tfhl/wsb+y/8Aib/2f9g83/l283fv2f7a4xs9+tef/sy/8zT/ANun/taj9mX/AJmn/t0/9rV9AUUUV8//ALTX/Mrf9vf/ALRo/wCGZf8Aqbv/ACm//ba+gK+f/wDk3P8A6mH+3f8At08jyP8Av5u3ed7Y2988eAUV7/8A8NNf9Sj/AOVL/wC1Uf8AJuf/AFMP9u/9unkeR/383bvO9sbe+ePQPib8Mv8AhY39l/8AE3/s/wCweb/y7ebv37P9tcY2e/WvP/8Ak4z/AKl7+wv+3vz/AD/+/e3b5Pvnd2xzwHwy+Jv/AArn+1P+JR/aH2/yv+Xnytmzf/sNnO/26UfDL4Zf8LG/tT/ib/2f9g8r/l283fv3/wC2uMbPfrXv/wATfib/AMK5/sv/AIlH9ofb/N/5efK2bNn+w2c7/bpXn/7Mv/M0/wDbp/7Wr0D4ZfDL/hXP9qf8Tf8AtD7f5X/Lt5WzZv8A9ts53+3Sj4ZfDL/hXP8Aan/E3/tD7f5X/Lt5WzZv/wBts53+3SvAPib8Mv8AhXP9l/8AE3/tD7f5v/Lt5WzZs/22znf7dKPhl8Mv+Fjf2p/xN/7P+weV/wAu3m79+/8A21xjZ79a7/8AZl/5mn/t0/8Aa1cB8Mvib/wrn+1P+JR/aH2/yv8Al58rZs3/AOw2c7/bpR8Mvib/AMK5/tT/AIlH9ofb/K/5efK2bN/+w2c7/bpXf/8AJuf/AFMP9u/9unkeR/383bvO9sbe+eOA+Jvwy/4Vz/Zf/E3/ALQ+3+b/AMu3lbNmz/bbOd/t0o+GXxN/4Vz/AGp/xKP7Q+3+V/y8+Vs2b/8AYbOd/t0rv/8Ak3P/AKmH+3f+3TyPI/7+bt3ne2NvfPB/w01/1KP/AJUv/tVegfDL4m/8LG/tT/iUf2f9g8r/AJefN379/wDsLjGz3616BRRRRXyB8Tfhl/wrn+y/+Jv/AGh9v83/AJdvK2bNn+22c7/bpR8Mvib/AMK5/tT/AIlH9ofb/K/5efK2bN/+w2c7/bpXv/wy+GX/AArn+1P+Jv8A2h9v8r/l28rZs3/7bZzv9ulHxN+GX/Cxv7L/AOJv/Z/2Dzf+Xbzd+/Z/trjGz3615/8A8My/9Td/5Tf/ALbXoHxN+Jv/AArn+y/+JR/aH2/zf+XnytmzZ/sNnO/26V4B8Mvhl/wsb+1P+Jv/AGf9g8r/AJdvN379/wDtrjGz3617/wDDL4m/8LG/tT/iUf2f9g8r/l583fv3/wCwuMbPfrXgHxN+Jv8Awsb+y/8AiUf2f9g83/l583fv2f7C4xs9+te//DL4m/8ACxv7U/4lH9n/AGDyv+Xnzd+/f/sLjGz3614B8Tfhl/wrn+y/+Jv/AGh9v83/AJdvK2bNn+22c7/bpXv/AMTfhl/wsb+y/wDib/2f9g83/l283fv2f7a4xs9+tegV5/8AE34Zf8LG/sv/AIm/9n/YPN/5dvN379n+2uMbPfrR8Tfib/wrn+y/+JR/aH2/zf8Al58rZs2f7DZzv9ulef8A/Jxn/Uvf2F/29+f5/wD3727fJ987u2OfAK9A+GXxN/4Vz/an/Eo/tD7f5X/Lz5WzZv8A9hs53+3Svf8A4m/E3/hXP9l/8Sj+0Pt/m/8ALz5WzZs/2Gznf7dKPhl8Mv8AhXP9qf8AE3/tD7f5X/Lt5WzZv/22znf7dK9Ar5A+JvxN/wCFjf2X/wASj+z/ALB5v/Lz5u/fs/2FxjZ79aPhl8Mv+Fjf2p/xN/7P+weV/wAu3m79+/8A21xjZ79a9/8Aib8Tf+Fc/wBl/wDEo/tD7f5v/Lz5WzZs/wBhs53+3SvQK8/+GXwy/wCFc/2p/wATf+0Pt/lf8u3lbNm//bbOd/t0r0CiiivkD4ZfE3/hXP8Aan/Eo/tD7f5X/Lz5WzZv/wBhs53+3Su//wCGZf8Aqbv/ACm//ba+gK8/+GXwy/4Vz/an/E3/ALQ+3+V/y7eVs2b/APbbOd/t0rz/AP4Zl/6m7/ym/wD22vQPib8Tf+Fc/wBl/wDEo/tD7f5v/Lz5WzZs/wBhs53+3SvQK8/+Jvwy/wCFjf2X/wATf+z/ALB5v/Lt5u/fs/21xjZ79a8//Zl/5mn/ALdP/a1cB8Tfib/wsb+y/wDiUf2f9g83/l583fv2f7C4xs9+te//AAy+GX/Cuf7U/wCJv/aH2/yv+Xbytmzf/ttnO/26UfE34m/8K5/sv/iUf2h9v83/AJefK2bNn+w2c7/bpR8Tfhl/wsb+y/8Aib/2f9g83/l283fv2f7a4xs9+tef/wDJuf8A1MP9u/8Abp5Hkf8Afzdu872xt754P+TjP+pe/sL/ALe/P8//AL97dvk++d3bHPoHwy+GX/Cuf7U/4m/9ofb/ACv+Xbytmzf/ALbZzv8AbpR8Mvhl/wAK5/tT/ib/ANofb/K/5dvK2bN/+22c7/bpXn//AAzL/wBTd/5Tf/tteAUV9f8AxN+Jv/Cuf7L/AOJR/aH2/wA3/l58rZs2f7DZzv8AbpXgHxN+Jv8Awsb+y/8AiUf2f9g83/l583fv2f7C4xs9+tfX9FfIHwy+Jv8Awrn+1P8AiUf2h9v8r/l58rZs3/7DZzv9ulHwy+Jv/Cuf7U/4lH9ofb/K/wCXnytmzf8A7DZzv9ule/8Awy+Jv/Cxv7U/4lH9n/YPK/5efN379/8AsLjGz3616BRRRXyB8Tfhl/wrn+y/+Jv/AGh9v83/AJdvK2bNn+22c7/bpXf/APJxn/Uvf2F/29+f5/8A3727fJ987u2OT/hmX/qbv/Kb/wDbaP8Ak3P/AKmH+3f+3TyPI/7+bt3ne2NvfPB/wzL/ANTd/wCU3/7bR+01/wAyt/29/wDtGj9mX/maf+3T/wBrV6B8Mvhl/wAK5/tT/ib/ANofb/K/5dvK2bN/+22c7/bpXn//AAzL/wBTd/5Tf/ttH/Juf/Uw/wBu/wDbp5Hkf9/N27zvbG3vnjgPhl8Mv+Fjf2p/xN/7P+weV/y7ebv37/8AbXGNnv1r3/4ZfDL/AIVz/an/ABN/7Q+3+V/y7eVs2b/9ts53+3SvP/2Zf+Zp/wC3T/2tXoHxN+GX/Cxv7L/4m/8AZ/2Dzf8Al283fv2f7a4xs9+tef8A/Jxn/Uvf2F/29+f5/wD3727fJ987u2OfQPib8Mv+Fjf2X/xN/wCz/sHm/wDLt5u/fs/21xjZ79a8/wD+Gmv+pR/8qX/2quA+JvxN/wCFjf2X/wASj+z/ALB5v/Lz5u/fs/2FxjZ79a9/+Jvwy/4WN/Zf/E3/ALP+web/AMu3m79+z/bXGNnv1rwD4m/DL/hXP9l/8Tf+0Pt/m/8ALt5WzZs/22znf7dKPib8Mv8AhXP9l/8AE3/tD7f5v/Lt5WzZs/22znf7dK9/+JvxN/4Vz/Zf/Eo/tD7f5v8Ay8+Vs2bP9hs53+3SvP8A9pr/AJlb/t7/APaNH/Juf/Uw/wBu/wDbp5Hkf9/N27zvbG3vng/Zl/5mn/t0/wDa1eAV7/8Asy/8zT/26f8AtavoCiiiivP/AIm/DL/hY39l/wDE3/s/7B5v/Lt5u/fs/wBtcY2e/WvQK8/+GXwy/wCFc/2p/wATf+0Pt/lf8u3lbNm//bbOd/t0o+GXxN/4WN/an/Eo/s/7B5X/AC8+bv37/wDYXGNnv1o+Jvwy/wCFjf2X/wATf+z/ALB5v/Lt5u/fs/21xjZ79a8//aa/5lb/ALe//aNH/Jxn/Uvf2F/29+f5/wD3727fJ987u2OfAK9//wCTjP8AqXv7C/7e/P8AP/797dvk++d3bHJ/w01/1KP/AJUv/tVH/DMv/U3f+U3/AO21wHwy+GX/AAsb+1P+Jv8A2f8AYPK/5dvN379/+2uMbPfrXf8A/DMv/U3f+U3/AO214BXv/wC01/zK3/b3/wC0aP8Ak4z/AKl7+wv+3vz/AD/+/e3b5Pvnd2xyftNf8yt/29/+0a4D4ZfE3/hXP9qf8Sj+0Pt/lf8ALz5WzZv/ANhs53+3Svf/AIZfDL/hXP8Aan/E3/tD7f5X/Lt5WzZv/wBts53+3SvAPhl8Mv8AhY39qf8AE3/s/wCweV/y7ebv37/9tcY2e/Wu/wD+Tc/+ph/t3/t08jyP+/m7d53tjb3zxwHwy+GX/Cxv7U/4m/8AZ/2Dyv8Al283fv3/AO2uMbPfrXf/APDMv/U3f+U3/wC21wHwy+Jv/Cuf7U/4lH9ofb/K/wCXnytmzf8A7DZzv9ule/8AxN+Jv/Cuf7L/AOJR/aH2/wA3/l58rZs2f7DZzv8AbpR8Mvib/wALG/tT/iUf2f8AYPK/5efN379/+wuMbPfrXoFFFFfIHwy+GX/Cxv7U/wCJv/Z/2Dyv+Xbzd+/f/trjGz3613//AAzL/wBTd/5Tf/ttH/DMv/U3f+U3/wC20fsy/wDM0/8Abp/7Wo/5OM/6l7+wv+3vz/P/AO/e3b5Pvnd2xyf8NNf9Sj/5Uv8A7VXAfDL4m/8ACuf7U/4lH9ofb/K/5efK2bN/+w2c7/bpR8Mvhl/wsb+1P+Jv/Z/2Dyv+Xbzd+/f/ALa4xs9+td//AMNNf9Sj/wCVL/7VR/ybn/1MP9u/9unkeR/383bvO9sbe+ePAK9//Zl/5mn/ALdP/a1H7Mv/ADNP/bp/7Wr0D4ZfDL/hXP8Aan/E3/tD7f5X/Lt5WzZv/wBts53+3SvAPhl8Mv8AhY39qf8AE3/s/wCweV/y7ebv37/9tcY2e/WvP69//Zl/5mn/ALdP/a1H7Mv/ADNP/bp/7Wo/aa/5lb/t7/8AaNegfDL4m/8ACxv7U/4lH9n/AGDyv+Xnzd+/f/sLjGz3615/+zL/AMzT/wBun/taj/k3P/qYf7d/7dPI8j/v5u3ed7Y2988H7Mv/ADNP/bp/7Wr0D4ZfDL/hXP8Aan/E3/tD7f5X/Lt5WzZv/wBts53+3SvkCvQPhl8Mv+Fjf2p/xN/7P+weV/y7ebv37/8AbXGNnv1r3/4ZfE3/AIWN/an/ABKP7P8AsHlf8vPm79+//YXGNnv1r0Ciiivn/wDZl/5mn/t0/wDa1eAV7/8Asy/8zT/26f8Ataj9mX/maf8At0/9rUf8nGf9S9/YX/b35/n/APfvbt8n3zu7Y59A+GXxN/4WN/an/Eo/s/7B5X/Lz5u/fv8A9hcY2e/WvP8A/hpr/qUf/Kl/9qrgPhl8Mv8AhY39qf8AE3/s/wCweV/y7ebv37/9tcY2e/WvP6+v/hl8Mv8AhXP9qf8AE3/tD7f5X/Lt5WzZv/22znf7dK8//aa/5lb/ALe//aNegfDL4m/8LG/tT/iUf2f9g8r/AJefN379/wDsLjGz3615/wD8My/9Td/5Tf8A7bR/wzL/ANTd/wCU3/7bXAfDL4Zf8LG/tT/ib/2f9g8r/l283fv3/wC2uMbPfrXv/wATfhl/wsb+y/8Aib/2f9g83/l283fv2f7a4xs9+tHwy+Jv/Cxv7U/4lH9n/YPK/wCXnzd+/f8A7C4xs9+tef8A/Juf/Uw/27/26eR5H/fzdu872xt7544D4m/DL/hXP9l/8Tf+0Pt/m/8ALt5WzZs/22znf7dK7/8A5Nz/AOph/t3/ALdPI8j/AL+bt3ne2NvfPHAfDL4m/wDCuf7U/wCJR/aH2/yv+Xnytmzf/sNnO/26V7/8Mvhl/wAK5/tT/ib/ANofb/K/5dvK2bN/+22c7/bpXgHxN+GX/Cuf7L/4m/8AaH2/zf8Al28rZs2f7bZzv9ulef0V9f8Awy+Jv/Cxv7U/4lH9n/YPK/5efN379/8AsLjGz3615/8Asy/8zT/26f8AtavoCiiivn/9mX/maf8At0/9rUf8My/9Td/5Tf8A7bXoHwy+GX/Cuf7U/wCJv/aH2/yv+Xbytmzf/ttnO/26V5/+zL/zNP8A26f+1q9A+Jvwy/4WN/Zf/E3/ALP+web/AMu3m79+z/bXGNnv1r0CvgCvr/4m/DL/AIWN/Zf/ABN/7P8AsHm/8u3m79+z/bXGNnv1o+JvxN/4Vz/Zf/Eo/tD7f5v/AC8+Vs2bP9hs53+3Sj4ZfDL/AIVz/an/ABN/7Q+3+V/y7eVs2b/9ts53+3SvP/2mv+ZW/wC3v/2jR/wzL/1N3/lN/wDttcB8Mvib/wAK5/tT/iUf2h9v8r/l58rZs3/7DZzv9ule/wDwy+GX/Cuf7U/4m/8AaH2/yv8Al28rZs3/AO22c7/bpR8Tfib/AMK5/sv/AIlH9ofb/N/5efK2bNn+w2c7/bpR8Tfhl/wsb+y/+Jv/AGf9g83/AJdvN379n+2uMbPfrXgHwy+Jv/Cuf7U/4lH9ofb/ACv+Xnytmzf/ALDZzv8AbpR8Mvhl/wALG/tT/ib/ANn/AGDyv+Xbzd+/f/trjGz3617/APDL4Zf8K5/tT/ib/wBofb/K/wCXbytmzf8A7bZzv9ulef8A/DMv/U3f+U3/AO21wHwy+Jv/AArn+1P+JR/aH2/yv+Xnytmzf/sNnO/26V3/AO01/wAyt/29/wDtGuA+GXxN/wCFc/2p/wASj+0Pt/lf8vPlbNm//YbOd/t0r3/4m/E3/hXP9l/8Sj+0Pt/m/wDLz5WzZs/2Gznf7dK8/wD2Zf8Amaf+3T/2tXAfE34Zf8K5/sv/AIm/9ofb/N/5dvK2bNn+22c7/bpXv/wy+GX/AArn+1P+Jv8A2h9v8r/l28rZs3/7bZzv9ulegUUUV8//APDMv/U3f+U3/wC20f8ADMv/AFN3/lN/+20f8My/9Td/5Tf/ALbXoHwy+GX/AArn+1P+Jv8A2h9v8r/l28rZs3/7bZzv9ulef/8ADMv/AFN3/lN/+20f8My/9Td/5Tf/ALbR/wAMy/8AU3f+U3/7bX0BXn/xN+GX/Cxv7L/4m/8AZ/2Dzf8Al283fv2f7a4xs9+tef8A/DMv/U3f+U3/AO216B8Mvhl/wrn+1P8Aib/2h9v8r/l28rZs3/7bZzv9ulHxN+GX/Cxv7L/4m/8AZ/2Dzf8Al283fv2f7a4xs9+tHwy+GX/Cuf7U/wCJv/aH2/yv+Xbytmzf/ttnO/26V6BXn/xN+GX/AAsb+y/+Jv8A2f8AYPN/5dvN379n+2uMbPfrR8Mvhl/wrn+1P+Jv/aH2/wAr/l28rZs3/wC22c7/AG6V5/8A8My/9Td/5Tf/ALbXoHwy+GX/AArn+1P+Jv8A2h9v8r/l28rZs3/7bZzv9ulef/8ADMv/AFN3/lN/+20f8My/9Td/5Tf/ALbXoHxN+GX/AAsb+y/+Jv8A2f8AYPN/5dvN379n+2uMbPfrR8Mvhl/wrn+1P+Jv/aH2/wAr/l28rZs3/wC22c7/AG6UfE34Zf8ACxv7L/4m/wDZ/wBg83/l283fv2f7a4xs9+tegV5/8Mvhl/wrn+1P+Jv/AGh9v8r/AJdvK2bN/wDttnO/26UfE34Zf8LG/sv/AIm/9n/YPN/5dvN379n+2uMbPfrXoFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFf/2Q=="
}
},
{
"request_control_key": "b3a428fd-58ee-4d6f-8872-633874ebf5e2",
"bank_slip_key": "4056f1f1-a6ea-4162-8bac-b1ce2546a9bf",
"bank_slip_status": "accepted",
"our_number": 987654321,
"barcode": "",
"digitable_line":
}
]
}
```
STATUS 4xx
### Response Body Params
| Campo | Tipo | Descrição | Caracteres |
|----------------------------|---------|------------------------------------------------------------------------------------|--------------------------------------------------|
| `bank_slips` | Array de **[Objeto bank_slip_response](#objeto-bank_slip_response)** | Descontos | - |
### Objeto bank_slip_response
| Campo | Tipo | Descrição | Caracteres |
|-------------------------|--------|-----------------------------------------------------------------------------------|------------|
| `request_control_key` * | uuidv4 | Chave única de identificação da request utilizada pelo cliente no formato uuid v4 | 36 |
| `bank_slip_key` * | uuidv4 | Chave única de identificação do boleto no formato uuid v4 | 36 |
| `bank_slip_status` * | string | Status do boleto | **[Enumeradores bank_slip_status](#enumeradores-bank_slip_status)** |
| `our_number` * | integer| Número único de identificação do boleto junto à carteira | 11 |
| `barcode` * | string | Código de barras do boleto | 44 |
| `digitable_line` * | string | Linha digitável do boleto | 47 |
| `qr_code_data` | object | Dados do QR Code | **[Objeto qr_code_data](#objeto-qr_code_data)** |
| `created_at` * | string | Data, no formato ISO (UTC - "YYYY-MM-DDTHH:MM:SSZ"), da criação da ocorrência | 20 |
### Enumeradores bank_slip_status
| Enumerador | Descrição |
|--------------------|-----------------------------------------|
| accepted | Boleto aceito mas ainda não registrado |
### Objeto qr_code_data
| Campo | Tipo | Descrição | Caracteres |
|----------------------------|--------|-------------------------------------------------------|-------------------------|
| `qr_code_key` | uuidv4 | Chave única de identificação do QR Code | 36 |
| `pix_key` | uuidv4 | Chave PIX vinculada ao QR Code | 36 |
| `receiver_conciliation_id` | uuidv4 | Identificador de conciliação do QR Code | 36 |
| `url` | string | URL (Pix Copia e Cola) do QR Code | - |
| `image` | string | base64 da URL (Pix Copia e Cola) do QR Code | - |
## Error Response
Response Body: Error
```json
{
"title": "titulo",
"description": "description in English",
"translation": "descrição em portugues",
"code": "codigo",
"extra_fields": {}
}
```
| Código HTTP `status` | Código QI `code` | Título `title` | Descrição (eng) `description` | Descrição (pt-br) `translation` |
|--------------------------|----------------------|----------------------------------------------------|-------------------------------------------------------------------------------------------------------------------------|------------------------------------------------------------------------------------------------------------------------|
| 400 | QIT000001 | Bad Request | Schema Error | Schema Inválido |
| 404 | BKS000004 | Not Found | Pix key not found: `{pix_key}` | Chave pix não encontrada: `{pix_key}` |
| 403 | BKS000005 | Forbidden | User is not allowed to do this action | Usuário não tem autorização para fazer essa ação |
| 404 | BKS000006 | Not Found | The source account key was not found. | A chave da conta de origem não foi encontrada. |
| 400 | BKS000007 | Bad Request | It 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. |
| 400 | BKS000008 | Bad Request | The source account is closed. | A conta de origem está fechada. |
| 400 | BKS000009 | Bad Request | The source account is blocked. | A conta de origem está bloqueada. |
| 403 | BKS000010 | Forbidden | The pix key owner does not match the account owner. | O proprietário da chave pix não corresponde ao proprietário da conta. |
| 404 | BKS000013 | Not Found | Requester profile not found | Carteira não encontrada |
| 409 | BKS000014 | Conflict | Request control key already sent or duplicated sent: `{request_control_key}` | Chave de controle da requisição já utilizada ou enviada duplicada: `{request_control_key}` |
| 400 | BKS000016 | Bad Request | Expiration date must be greater than the current date and have a maximum of 3650 days from the current date. | A data de vencimento deve ser maior que a data atual e possuir no máximo 3650 dias corridos a partir da data atual. |
| 409 | BKS000017 | Conflict | Our number already used or duplicated sent: `{our_number}` | Nosso número já utilizado ou enviado duplicado: `{our_number}` |
| 400 | BKS000018 | Bad Request | The discount dates must be less than the expiration date and increasing. | A data dos descontos devem ser menores que a de expiração e crescentes. |
| 400 | BKS000019 | Bad Request | Payer address is required for protest. | Endereço do pagador é obrigatório para protesto. |
| 500 | BKS000021 | Internal Server Error | Error while trying to generate QR Code. | Erro ao tentar gerar QR Code de pagamento. |
| 400 | BKS000022 | Bad Request | Requester profile is not opened. | Carteira não está aberta. |
| 400 | BKS000026 | Bad Request | Guarantor address is required for protest. | Endereço do sacador é obrigatório para protesto. |
| 404 | BKS000028 | Not Found | Notary office attended region not found for postal code: `{postal_code}` | Região de cartório não encontrada para o CEP: `{postal_code}` |
| 400 | BKS000043 | Bad Request | Invalid discount numbering. Discounts must be numbered in ascending order and start on 1. | Numeração dos descontos inválida. Os descontos devem ser numerados em ordem crescente e começar em 1. |
| 400 | BKS000045 | Bad Request | Rebate amount can not be equal or greater than the bank slip amount. | O valor do rebate não pode ser igual ou maior do que o valor do boleto. |
| 400 | BKS000047 | Bad Request | It 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. |
| 400 | BKS000125 | Bad Request | Partial payment data is required for this bank slip species type. | Os dados de pagamento parcial são obrigatórios para o tipo de boleto fornecido. |
| 400 | BKS000128 | Bad Request | QR code payment is not allowed for partial payment. | Pagamento via QR code não é permitido para pagamento parcial. |
| 400 | BKS000128 | Bad Request | QR code payment is not allowed for partial payment. | Pagamento via QR code não é permitido para pagamento parcial. |
| 400 | BKS000131 | Bad Request | Rebate amount is not allowed for this bank slip species type. | O valor de abatimento não é permitido para o tipo de boleto fornecido. |
| 400 | BKS000132 | Bad Request | Discount data is not allowed for this bank slip species type. | Os dados de desconto não são permitidos para o tipo de boleto fornecido. |
| 400 | BKS000133 | Bad Request | Fine data is not allowed for this bank slip species type. | Os dados de multa não são permitidos para o tipo de boleto fornecido. |
| 400 | BKS000134 | Bad Request | Interest data is not allowed for this bank slip species type. | Os dados de juros não são permitidos para o tipo de boleto fornecido. |
| 400 | BKS000136 | Bad Request | Only credit card financial instrument type can have zero amount. | Apenas o tipo de instrumento financeiro cartão de crédito pode ter valor zero. |
---
# Rebate cancellation
URL: /en/documentation/boletos/instrucoes/abatimento/cancelar_abatimento
Canceling a rebate means canceling the existing rebate for the bank slip. The cancellation must be performed if there is interest in removing the rebate or creating a new one.
:::caution Attention!
If there is any pending rebate cancellation request awaiting confirmation, or there is no active rebate, it is not possible to request the cancellation of a rebate.
Note: the rebate amount (`rebate_amount`) sent in the bank slip registration counts as an active rebate (if it is greater than R$0.00).
:::
## Request
ENDPOINT /account/ ACCOUNT_KEY /requester_profile/ REQUESTER_PROFILE_KEY /bank_slip/ BANK_SLIP_KEY /cancel_rebate
METHOD POST
### Path parameters
| Field | Type | Description | Characters |
|-------------------------|--------|--------------------------------------------------------------|------------|
| `account_key` | uuidv4 | Unique account identification key, in uuid v4 format | 36 |
| `requester_profile_key` | uuidv4 | Unique wallet identification key, in uuid v4 format | 36 |
| `bank_slip_key` | uuidv4 | Unique bank slip identification key, in uuid v4 format | 36 |
Request Body
```json
{
"request_control_key": "86864aec-a6c8-462e-8460-b05ef5a1eb62"
}
```
### Request Body Params
| Field | Type | Description | Characters |
|----------------------------|---------|------------------------------------------------------------------------------------|------------|
| `request_control_key` * | uuidv4 | Unique request identification key used by the client in uuid v4 format | 36 |
## Response
STATUS 202
Response Body
```json
{
"occurrence_key": "539cefc8-382e-4fef-80e1-978a3a178a5c",
"bank_slip_key": "d402e91a-32ac-4428-8357-d71824b113b5"
}
```
### Response Body Params
| Field | Type | Description | Characters |
|--------------------|--------|-----------------------------------------------------------------------------------|------------|
| `occurrence_key` * | uuidv4 | Unique occurrence (instruction) identification key in uuid v4 format | 36 |
| `bank_slip_key` * | uuidv4 | Unique bank slip identification key in uuid v4 format | 36 |
### Error Response
STATUS 4xx
Response Body: Error
```json
{
"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` |
|--------------------------|----------------------|----------------------------------------------------|-------------------------------------------------------------------------------------------------------------------------|------------------------------------------------------------------------------------------------------------------------|
| 400 | QIT000001 | Bad Request | Schema Error | Schema Inválido |
| 404 | BKS000006 | Not Found | The source account key was not found. | A chave da conta de origem não foi encontrada. |
| 400 | BKS000007 | Bad Request | It 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. |
| 400 | BKS000008 | Bad Request | The source account is closed. | A conta de origem está fechada. |
| 400 | BKS000009 | Bad Request | The source account is blocked. | A conta de origem está bloqueada. |
| 404 | BKS000013 | Not Found | Requester profile not found | Carteira não encontrada |
| 409 | BKS000014 | Conflict | Request control key already sent or duplicated sent: `` | Chave de controle da requisição já utilizada ou enviada duplicada: `` |
| 400 | BKS000022 | Bad Request | Requester profile is not opened. | Carteira não está aberta. |
| 404 | BKS000029 | Not Found | Bank slip not found for the given key (`{bank_slip_key}`). | Boleto não encontrado para a chave fornecida (`{bank_slip_key}`). |
| 400 | BKS000031 | Bad Request | Bank slip must have an active rebate. | O boleto deve possuir um rebate ativo. |
| 400 | BKS000032 | Bad Request | Bank slip must be in 'registered' status. | O boleto deve possuir o status 'registered'. |
| 409 | BKS000034 | Bad Request | There is already a pending cancel rebate occurrence for this bank slip. | Já existe uma ocorrência de cancelamento de rebate pendente para este boleto. |
---
# Create Rebate
URL: /en/documentation/boletos/instrucoes/abatimento/criar_abatimento
Creating a rebate for the bank slip means reducing part of the base value of the title to decrease the final amount.
:::caution Attention!
If there is any pending rebate request waiting for confirmation, or any active rebate, creating a new rebate is not allowed. If there is an active rebate and you want to change it, a rebate cancellation request must be sent first. Once it is confirmed, it is possible to create another rebate.
Note: the rebate amount (`rebate_amount`) sent in the bank slip registration does not count as a pending rebate request, but counts as an active rebate request.
:::
## Request
ENDPOINT /account/ ACCOUNT_KEY /requester_profile/ REQUESTER_PROFILE_KEY /bank_slip/ BANK_SLIP_KEY /rebate
METHOD POST
### Path parameters
| Field | Type | Description | Characters |
|-------------------------|--------|--------------------------------------------------------------|------------|
| `account_key` | uuidv4 | Unique account identification key, in uuid v4 format | 36 |
| `requester_profile_key` | uuidv4 | Unique wallet identification key, in uuid v4 format | 36 |
| `bank_slip_key` | uuidv4 | Unique bank slip identification key, in uuid v4 format | 36 |
Request Body
```json
{
"request_control_key": "d66b807a-25fa-4e21-b198-9beb221a29ce",
"rebate_amount": 150.00
}
```
### Request Body Params
| Field | Type | Description | Characters |
|---------------------------|---------|------------------------------------------------------------------------------------|------------|
| `request_control_key` * | uuidv4 | Unique request identification key used by the client in uuid v4 format | 36 |
| `rebate_amount` * | float | Absolute rebate amount | - |
## Response
STATUS 202
Response Body
```json
{
"occurrence_key": "7f01165b-fdd0-4f59-b231-42170ea90131",
"bank_slip_key": "dad779c1-5e1c-422e-9f36-c704916a87cf"
}
```
### Response Body Params
| Field | Type | Description | Characters |
|-------------------|--------|-----------------------------------------------------------------------------------|------------|
| `occurrence_key` *| uuidv4 | Unique occurrence (instruction) identification key in uuid v4 format | 36 |
| `bank_slip_key` * | uuidv4 | Unique bank slip identification key in uuid v4 format | 36 |
### Error Response
STATUS 4xx
Response Body: Error
```json
{
"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` |
|--------------------------|----------------------|----------------------------------------------------|-------------------------------------------------------------------------------------------------------------------------|------------------------------------------------------------------------------------------------------------------------|
| 400 | QIT000001 | Bad Request | Schema Error | Schema Inválido |
| 404 | BKS000006 | Not Found | The source account key was not found. | A chave da conta de origem não foi encontrada. |
| 400 | BKS000007 | Bad Request | It 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. |
| 400 | BKS000008 | Bad Request | The source account is closed. | A conta de origem está fechada. |
| 400 | BKS000009 | Bad Request | The source account is blocked. | A conta de origem está bloqueada. |
| 404 | BKS000013 | Not Found | Requester profile not found | Carteira não encontrada |
| 409 | BKS000014 | Conflict | Request control key already sent or duplicated sent: `` | Chave de controle da requisição já utilizada ou enviada duplicada: `` |
| 400 | BKS000022 | Bad Request | Requester profile is not opened. | Carteira não está aberta. |
| 404 | BKS000029 | Not Found | Bank slip not found for the given key (`{bank_slip_key}`). | Boleto não encontrado para a chave fornecida (`{bank_slip_key}`). |
| 409 | BKS000030 | Conflict | There is already a pending rebate occurrence for this bank slip. | Já existe uma ocorrência de rebate pendente para este boleto. |
| 400 | BKS000032 | Bad Request | Bank slip must be in 'registered' status. | O boleto deve possuir o status 'registered'. |
| 409 | BKS000033 | Conflict | This bank slip already has an active rebate. You must send a 'cancel_rebate' occurrence before trying to create another one. one. | Este boleto já possui um rebate ativo. Você deve mandar uma ocorrência do tipo 'cancel_rebate' antes de tentar criar outro. |
| 400 | BKS000045 | Bad Request | Rebate amount can not be equal or greater than the bank slip amount. | O valor do rebate não pode ser igual ou maior do que o valor do boleto. |
---
# Write-off
URL: /en/documentation/boletos/instrucoes/baixa
When a bank slip is written off, it becomes unavailable for payment. In other words, the bank slip is "canceled".
:::caution Attention!
If there is any write-off request pending confirmation, creating a new request is not allowed.
:::
## Request
ENDPOINT /account/ ACCOUNT_KEY /requester_profile/ REQUESTER_PROFILE_KEY /bank_slip/ BANK_SLIP_KEY /write_off
METHOD POST
### Path parameters
| Field | Type | Description | Characters |
|-------------------------|--------|----------------------------------------------------------------|------------|
| `account_key` | uuidv4 | Unique account identification key, in uuid v4 format | 36 |
| `requester_profile_key` | uuidv4 | Unique wallet identification key, in uuid v4 format | 36 |
| `bank_slip_key` | uuidv4 | Unique bank slip identification key, in uuid v4 format | 36 |
Request Body
```json
{
"request_control_key": "614a451d-3b82-460e-bcc0-2caf3dde711f"
}
```
### Request Body Params
| Field | Type | Description | Characters |
|----------------------------|---------|--------------------------------------------------------------------------------------|------------|
| `request_control_key` * | uuidv4 | Unique request identification key used by the client in uuid v4 format | 36 |
## Response
STATUS 202
Response Body
```json
{
"occurrence_key": "2552bd64-950b-437e-a53a-a133ffea03d7",
"bank_slip_key": "960f78d4-4426-4762-98da-3ce3713ae0a5"
}
```
### Response Body Params
| Field | Type | Description | Characters |
|--------------------|--------|-------------------------------------------------------------------------------------|------------|
| `occurrence_key` * | uuidv4 | Unique occurrence (instruction) identification key in uuid v4 format | 36 |
| `bank_slip_key` * | uuidv4 | Unique bank slip identification key in uuid v4 format | 36 |
### Error Response
STATUS 4xx
Response Body: Error
```json
{
"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` |
|--------------------------|----------------------|----------------------------------------------------|-------------------------------------------------------------------------------------------------------------------------|------------------------------------------------------------------------------------------------------------------------|
| 400 | QIT000001 | Bad Request | Schema Error | Schema Inválido |
| 404 | BKS000006 | Not Found | The source account key was not found. | A chave da conta de origem não foi encontrada. |
| 400 | BKS000007 | Bad Request | It 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. |
| 400 | BKS000008 | Bad Request | The source account is closed. | A conta de origem está fechada. |
| 400 | BKS000009 | Bad Request | The source account is blocked. | A conta de origem está bloqueada. |
| 404 | BKS000013 | Not Found | Requester profile not found | Carteira não encontrada |
| 409 | BKS000014 | Conflict | Request control key already sent or duplicated sent: `` | Chave de controle da requisição já utilizada ou enviada duplicada: `` |
| 400 | BKS000022 | Bad Request | Requester profile is not opened. | Carteira não está aberta. |
| 404 | BKS000029 | Not Found | Bank slip not found for the given key (`{bank_slip_key}`). | Boleto não encontrado para a chave fornecida (`{bank_slip_key}`). |
| 400 | BKS000032 | Bad Request | Bank slip must be in 'registered' status. | O boleto deve possuir o status 'registered'. |
| 409 | BKS000049 | Conflict | There is already a pending write off occurrence for this bank slip. Please, wait for the confirmation of this occurrence before sending another one. one. | Já existe uma ocorrência de baixa pendente para este boleto. Por favor, aguarde a confirmação dessa ocorrência antes de enviar outra. |
---
# Discount
URL: /en/documentation/boletos/instrucoes/desconto
The discount instruction is used to apply discounts with various calculation rule possibilities. If discounts already exist for the bank slip in question, and a discount instruction is accepted, the previously existing discounts will be overwritten.
:::caution Attention!
If there is any pending discount addition request awaiting confirmation, creating a new request is not allowed.
:::
## Request
ENDPOINT /account/ ACCOUNT_KEY /requester_profile/ REQUESTER_PROFILE_KEY /bank_slip/ BANK_SLIP_KEY /discount
METHOD POST
### Path parameters
| Field | Type | Description | Characters |
|-------------------------|--------|----------------------------------------------------------|------------|
| `account_key` | uuidv4 | Unique account identification key, in uuid v4 format | 36 |
| `requester_profile_key` | uuidv4 | Unique wallet identification key, in uuid v4 format | 36 |
| `bank_slip_key` | uuidv4 | Unique bank slip identification key, in uuid v4 format | 36 |
Request Body
```json
{
"request_control_key": "2e2f0053-a988-40c7-ad17-41c4c4da861e",
"discounts_data": [
{
"discount_type": "anticipation_workdays_daily_percentage",
"discount_percentage": 2,
"discount_number": 1,
"discount_limit_date": "2024-12-01"
},
{
"discount_type": "anticipation_workdays_daily_percentage",
"discount_percentage": 1,
"discount_number": 2,
"discount_limit_date": "2025-01-02"
}
]
}
```
### Request Body Params
| Field | Type | Description | Characters |
|----------------------------|---------|------------------------------------------------------------------------------------|------------|
| `request_control_key` * | uuidv4 | Unique request identification key used by the client in uuid v4 format | 36 |
| `discounts_data` | object array | Discounts | **[discount object](#discount-object)** |
### discount object
Option 1: discounts using absolute values (`discount_type in ["absolute", "anticipation_calendar_days_daily_amount", "anticipation_workdays_daily_amount"]`)
| Field | Type | Description | Characters |
|---------------------------|---------|-----------------------------------------------------|-----------------------------------------------------------|
| `discount_amount` * | float | Absolute discount value per time unit | - |
| `discount_number` * | integer | Discount number | - |
| `discount_type` * | string | Discount configuration in absolute values | **[discount_type enumerator](#discount_type-enumerators)** |
| `discount_limit_date` * | string | Discount application limit date | 10 |
Option 2: discounts using percentage values (`discount_type in ["percentage", "anticipation_calendar_days_daily_percentage", "anticipation_workdays_daily_percentage"]`)
| Field | Type | Description | Characters |
|---------------------------|---------|-----------------------------------------------------|-----------------------------------------------------------|
| `discount_percentage` * | float | Percentage discount value per time unit | - |
| `discount_number` * | integer | Discount number | - |
| `discount_type` * | string | Discount configuration in percentage values | **[discount_type enumerator](#discount_type-enumerators)** |
| `discount_limit_date` * | string | Discount application limit date | 10 |
:::caution Attention!
The bank slip can have up to three discounts, and all discounts must be of the same type , that is, they must have the same `discount_type`. Discounts must be numbered from 1 to 3, in ascending order and necessarily starting at 1. That is, if two discounts are sent in the request, they must necessarily be numbered 1 and 2.
:::
### discount_type enumerators
| Enumerator | Description |
|---------------------------------------------|----------------------------------------------------------------------|
| absolute | Fixed value |
| anticipation_calendar_days_daily_amount | Daily anticipation discount amount, over calendar days |
| anticipation_workdays_daily_amount | Daily anticipation discount amount, over business days |
| percentage | Fixed percentage |
| anticipation_calendar_days_daily_percentage | Monthly anticipation discount percentage, based on calendar days |
| anticipation_workdays_daily_percentage | Annual anticipation discount percentage, based on business days |
## Response
STATUS 202
Response Body
```json
{
"occurrence_key": "aaf64135-6bd8-4d49-be6f-e8f884b20ee7",
"bank_slip_key": "470cfcae-159b-4de4-ad22-2d3b2dd717f7"
}
```
### Response Body Params
| Field | Type | Description | Characters |
|--------------------|--------|---------------------------------------------------------------------------|------------|
| `occurrence_key` * | uuidv4 | Unique occurrence (instruction) identification key in uuid v4 format | 36 |
| `bank_slip_key` * | uuidv4 | Unique bank slip identification key in uuid v4 format | 36 |
### Error Response
STATUS 4xx
Response Body: Error
```json
{
"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` |
|--------------------------|----------------------|----------------------------------------------------|-------------------------------------------------------------------------------------------------------------------------|------------------------------------------------------------------------------------------------------------------------|
| 400 | QIT000001 | Bad Request | Schema Error | Schema Inválido |
| 404 | BKS000006 | Not Found | The source account key was not found. | A chave da conta de origem não foi encontrada. |
| 400 | BKS000007 | Bad Request | It 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. |
| 400 | BKS000008 | Bad Request | The source account is closed. | A conta de origem está fechada. |
| 400 | BKS000009 | Bad Request | The source account is blocked. | A conta de origem está bloqueada. |
| 404 | BKS000013 | Not Found | Requester profile not found | Carteira não encontrada |
| 409 | BKS000014 | Conflict | Request control key already sent or duplicated sent: `` | Chave de controle da requisição já utilizada ou enviada duplicada: `` |
| 400 | BKS000018 | Bad Request | The discount dates must be less than the expiration date and increasing. | A data dos descontos devem ser menores que a de expiração e crescentes. |
| 400 | BKS000022 | Bad Request | Requester profile is not opened. | Carteira não está aberta. |
| 404 | BKS000029 | Not Found | Bank slip not found for the given key (`{bank_slip_key}`). | Boleto não encontrado para a chave fornecida (`{bank_slip_key}`). |
| 400 | BKS000032 | Bad Request | Bank slip must be in 'registered' status. | O boleto deve possuir o status 'registered'. |
| 400 | BKS000043 | Bad Request | Invalid discount numbering. Discounts must be numbered in ascending order and start on 1. | Numeração dos descontos inválida. Os descontos devem ser numerados em ordem crescente e começar em 1. |
| 400 | BKS000046 | Bad Request | Invalid discount type. All types in the discount list must be the same. | Tipo de desconto inválido. Todos os tipos da lista de descontos devem ser iguais. |
| 409 | BKS000048 | Conflict | There is already a pending discount occurrence for this bank slip. Please, wait for the confirmation of this occurrence before sending another one. | Já existe uma ocorrência de desconto pendente para este boleto. Por favor, aguarde a confirmação dessa ocorrência antes de enviar outra. |
---
# Edit
URL: /en/documentation/boletos/instrucoes/edicao
The edit instruction serves to modify configurable data of the bank slip after its issuance, such as automatic write-off settings, protest, bankruptcy protest, and payer data. This instruction allows updating multiple aspects of the bank slip in a single request.
:::caution Attention!
The bank slip must be in 'registered' status for it to be editable. At least one of the data fields (`write_off_data`, `protest_data`, `bankruptcy_protest_data` or `payer_data`) must be provided along with the `request_control_key`.
:::
## Request
ENDPOINT /account/ ACCOUNT_KEY /requester_profile/ REQUESTER_PROFILE_KEY /bank_slip/ BANK_SLIP_KEY /bank_slip_edit
METHOD POST
### Path parameters
| Field | Type | Description | Characters |
|-------------------------|--------|---------------------------------------------------------------|------------|
| `account_key` | uuidv4 | Unique account identification key, in uuid v4 format | 36 |
| `requester_profile_key` | uuidv4 | Unique wallet identification key, in uuid v4 format | 36 |
| `bank_slip_key` | uuidv4 | Unique bank slip identification key, in uuid v4 format | 36 |
Request Body
```json
{
"request_control_key": "c4dd443a-6e2f-4261-8f28-adfa4c0d4c5b",
"write_off_data": {"days_to_write_off": 365},
"protest_data": {"days_to_protest": 7},
"bankruptcy_protest_data": {"days_to_bankruptcy_protest": 14},
"payer_data": {
"contact": {
"email": "finance@globaltech.com",
"phone": {"international_dial_code": "055", "area_code": "11", "number": "987654321"},
},
"address": {
"street": "101 High St.",
"neighborhood": "Tech Park",
"number": "202",
"postal_code": "01001000",
"city": "Innovation City",
"state": "SP",
"complement": "Building A",
},
},
}
```
### Request Body Params
| Field | Type | Description | Characters |
|----------------------------|---------|------------------------------------------------------------------------------------|------------|
| `request_control_key` * | uuidv4 | Unique request identification key used by the client in uuid v4 format | 36 |
| `write_off_data` | object | Automatic write-off settings (null to remove) | **[write_off_data Object](#write_off_data-object)** |
| `protest_data` | object | Protest settings (null to remove) | **[protest_data Object](#protest_data-object)** |
| `bankruptcy_protest_data` | object | Bankruptcy protest settings (null to remove) | **[bankruptcy_protest_data Object](#bankruptcy_protest_data-object)** |
| `payer_data` | object | Payer data (`address` null or `contact` null to remove) | **[payer_data Object](#payer_data-object)** |
:::info Note
At least one of the data fields (`write_off_data`, `protest_data`, `bankruptcy_protest_data` or `payer_data`) must be provided in the request.
:::
### write_off_data Object
| Field | Type | Description | Characters |
|---------------------------|---------|---------------------------------------------------------------------------------|------------|
| `days_to_write_off` * | integer | Days, after due date, for the bank slip to be automatically written off | - |
### protest_data Object
| Field | Type | Description | Characters |
|---------------------------|---------|---------------------------------------------------------------------------------|------------|
| `days_to_protest` * | integer | Days, after due date, for the bank slip to be automatically protested | - |
### bankruptcy_protest_data Object
| Field | Type | Description | Characters |
|--------------------------------|---------|---------------------------------------------------------------------------------|-------------|
| `days_to_bankruptcy_protest` * | integer | Days, after due date, for the bank slip to be automatically protested | - |
### payer_data Object
| Field | Type | Description | Characters|
|---------------------------|--------|----------------------------------------------------------------|-----------|
| `contact` | object | Contact information | **[contact Object](#contact-object)** |
| `address` | object | Address | **[address Object](#address-object)** |
### contact Object
| Field | Type | Description | Characters |
|---------------------------|--------|-----------------------------------|------------------------------------|
| `email` | string | Contact email | 320 |
| `phone` | object | Contact phone | **[phone Object](#phone-object)** |
### phone Object
| Field | Type | Description | Characters |
|---------------------------------|--------|--------------------------------------------------|------------|
| `international_dial_code` * | string | International Direct Dialing Code | 3 |
| `area_code` * | string | Area Code | 2 |
| `number` * | string | Number | 9 |
### address Object
| Field | Type | Description | Characters |
|---------------------------|--------|--------------------------------------------------|------------|
| `street` * | string | Street | 500 |
| `number` * | string | Number | 6 |
| `complement` | string | Complement | 500 |
| `neighborhood` * | string | Neighborhood | 100 |
| `postal_code` * | string | Postal Code | 8 |
| `city` * | string | City | 100 |
| `state` * | string | State | **[state Enumerator](#state-enumerators)** |
### state Enumerators
| Enumerator | Description |
|--------------------|-----------------------|
| AC | Acre |
| AL | Alagoas |
| AM | Amazonas |
| AP | Amapá |
| BA | Bahia |
| CE | Ceará |
| DF | Distrito federal |
| ES | Espírito Santo |
| GO | Goiás |
| MA | Maranhão |
| MG | Minas Gerais |
| MS | Mato Grosso do Sul |
| MT | Mato Grosso |
| PA | Pará |
| PB | Paraíba |
| PE | Pernambuco |
| PI | Piauí |
| PR | Paraná |
| RJ | Rio de Janeiro |
| RN | Rio Grande do Norte |
| RO | Rondônia |
| RR | Roraima |
| RS | Rio Grande do Sul |
| SC | Santa Catarina |
| SE | Sergipe |
| SP | São Paulo |
| TO | Tocantins |
| EX | Exception |
## Response
STATUS 200
Response Body
```json
{
"occurrence_key": "5a745b65-9a2c-44eb-b43e-c80ef5429d94",
"bank_slip_key": "fdafdffa-cbd4-4f3c-8e3d-990428305161"
}
```
### Response Body Params
| Field | Type | Description | Characters |
|--------------------|--------|-----------------------------------------------------------------------------------|------------|
| `occurrence_key` * | uuidv4 | Unique occurrence (instruction) identification key in uuid v4 format | 36 |
| `bank_slip_key` * | uuidv4 | Unique bank slip identification key in uuid v4 format | 36 |
### Error Response
STATUS 4xx
Response Body: Error
```json
{
"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` |
|------------------------|--------------------|----------------------------------------------------|-------------------------------------------------------------------------------------------------------------------------|------------------------------------------------------------------------------------------------------------------------|
| 400 | QIT000001 | Bad Request | Schema Error | Schema Inválido |
| 404 | BKS000006 | Not Found | The source account key was not found. | A chave da conta de origem não foi encontrada. |
| 400 | BKS000007 | Bad Request | It 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. |
| 400 | BKS000008 | Bad Request | The source account is closed. | A conta de origem está fechada. |
| 400 | BKS000009 | Bad Request | The source account is blocked. | A conta de origem está bloqueada. |
| 404 | BKS000013 | Not Found | Requester profile not found | Carteira não encontrada |
| 409 | BKS000014 | Conflict | Request control key already sent or duplicated sent: `` | Chave de controle da requisição já utilizada ou enviada duplicada: `` |
| 400 | BKS000022 | Bad Request | Requester profile is not opened. | Carteira não está aberta. |
| 404 | BKS000029 | Not Found | Bank slip not found for the given key (`{bank_slip_key}`). | Boleto não encontrado para a chave fornecida (`{bank_slip_key}`). |
| 400 | BKS000032 | Bad Request | Bank slip must be in 'registered' status. | O boleto deve possuir o status 'registered'. |
---
# Extension
URL: /en/documentation/boletos/instrucoes/extensao
The extension request serves to extend the due date of the bank slip.
:::caution Attention!
If there is any extension request pending confirmation, creating a new request is not allowed.
:::
## Request
ENDPOINT /account/ ACCOUNT_KEY /requester_profile/ REQUESTER_PROFILE_KEY /bank_slip/ BANK_SLIP_KEY /extension
METHOD POST
### Path parameters
| Field | Type | Description | Characters |
|-------------------------|--------|--------------------------------------------------------------|------------|
| `account_key` | uuidv4 | Unique account identification key, in uuid v4 format | 36 |
| `requester_profile_key` | uuidv4 | Unique wallet identification key, in uuid v4 format | 36 |
| `bank_slip_key` | uuidv4 | Unique bank slip identification key, in uuid v4 format | 36 |
Request Body
```json
{
"request_control_key": "2e2f0053-a988-40c7-ad17-41c4c4da861e",
"new_expiration_date": "2025-01-01"
}
```
### Request Body Params
| Field | Type | Description | Characters |
|----------------------------|---------|------------------------------------------------------------------------------------|------------|
| `request_control_key` * | uuidv4 | Unique request identification key used by the client in uuid v4 format | 36 |
| `new_expiration_date` * | string | New expiration date, in "YYYY-MM-DD" format | 10 |
## Response
STATUS 202
Response Body
```json
{
"occurrence_key": "6f2eb385-898f-4fa3-96df-80a76a30ad01",
"bank_slip_key": "0d462dda-7412-444f-ace9-375e4ab43c2f"
}
```
### Response Body Params
| Field | Type | Description | Characters |
|--------------------|--------|-----------------------------------------------------------------------------------|------------|
| `occurrence_key` * | uuidv4 | Unique occurrence (instruction) identification key in uuid v4 format | 36 |
| `bank_slip_key` * | uuidv4 | Unique bank slip identification key in uuid v4 format | 36 |
### Error Response
STATUS 4xx
Response Body: Error
```json
{
"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` |
|--------------------------|----------------------|----------------------------------------------------|-------------------------------------------------------------------------------------------------------------------------|------------------------------------------------------------------------------------------------------------------------|
| 400 | QIT000001 | Bad Request | Schema Error | Schema Inválido |
| 404 | BKS000006 | Not Found | The source account key was not found. | A chave da conta de origem não foi encontrada. |
| 400 | BKS000007 | Bad Request | It 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. |
| 400 | BKS000008 | Bad Request | The source account is closed. | A conta de origem está fechada. |
| 400 | BKS000009 | Bad Request | The source account is blocked. | A conta de origem está bloqueada. |
| 404 | BKS000013 | Not Found | Requester profile not found | Carteira não encontrada |
| 409 | BKS000014 | Conflict | Request control key already sent or duplicated sent: `` | Chave de controle da requisição já utilizada ou enviada duplicada: `` |
| 400 | BKS000022 | Bad Request | Requester profile is not opened. | Carteira não está aberta. |
| 404 | BKS000029 | Not Found | Bank slip not found for the given key (`{bank_slip_key}`). | Boleto não encontrado para a chave fornecida (`{bank_slip_key}`). |
| 400 | BKS000032 | Bad Request | Bank slip must be in 'registered' status. | O boleto deve possuir o status 'registered'. |
| 400 | BKS000041 | Bad Request | The new expiration date must be greater than the current expiration date. | A nova data de expiração deve ser posterior à data de expiração atual. |
| 409 | BKS000042 | Conflict | There is already a pending extension occurrence for this bank slip. Please, wait for the confirmation of this occurrence before sending another one. | Já existe uma ocorrência de extensão pendente para este boleto. Por favor, aguarde a confirmação dessa ocorrência antes de enviar outra. |
---
# Interest
URL: /en/documentation/boletos/instrucoes/juros
The interest instruction is used to configure the interest that will be applied if the bank slip is paid after the due date. If there is already an interest configuration for the bank slip in question, and an interest instruction is accepted, the previously existing configuration will be overwritten.
:::caution Attention!
If there is any pending interest instruction awaiting confirmation, sending a new instruction is not allowed.
:::
## Request
ENDPOINT /account/ ACCOUNT_KEY /requester_profile/ REQUESTER_PROFILE_KEY /bank_slip/ BANK_SLIP_KEY /interest
METHOD POST
### Path parameters
| Field | Type | Description | Characters |
|-------------------------|--------|----------------------------------------------------------------|------------|
| `account_key` | uuidv4 | Unique account identification key in uuid v4 format | 36 |
| `requester_profile_key` | uuidv4 | Unique wallet identification key in uuid v4 format | 36 |
| `bank_slip_key` | uuidv4 | Unique bank slip identification key in uuid v4 format | 36 |
Request Body
```json
{
"request_control_key": "c4dd443a-6e2f-4261-8f28-adfa4c0d4c5b",
"interest_data": {
"interest_type": "calendar_days_daily_amount",
"interest_amount": 50.00,
"days_to_interest": 5
}
}
```
### Request Body Params
| Field | Type | Description | Characters |
|----------------------------|---------|-----------------------------------------------------------------------------------|------------|
| `request_control_key` * | uuidv4 | Unique request identification key used by the client in uuid v4 format | 36 |
| `interest_data` | object | Interest configurations | **[interest_data Object](#interest_data-object)** |
### interest_data Object
Option 1: interest using absolute values (`interest_type=calendar_days_daily_amount` or `interest_type=workdays_daily_amount`)
| Field | Type | Description | Characters |
|---------------------------|---------|-------------------------------------------------------------------------------------|------------------------------------------------------------------------------------------------|
| `interest_type` * | string | Interest type | **[interest_type Enumerators](#interest_type-enumerators)** |
| `interest_amount` * | float | Amount to be charged per determined time unit (working days or calendar days) | - |
| `days_to_interest` * | integer | Days after due date for interest to start being charged | - |
Option 2: interest using percentage values (`interest_type=calendar_days_monthly_percentage`)
| Field | Type | Description | Characters |
|--------------------------|---------|---------------------------------------------------------------------------------------|----------------------------------------------------------------------------------------------------|
| `interest_type` * | string | Interest type | **[interest_type Enumerators](#interest_type-enumerators)** |
| `interest_percentage` * | integer | Percentage to be charged per determined time unit (working days or calendar days) | - |
| `days_to_interest` * | integer | Days after due date for interest to start being charged | - |
### interest_type Enumerators
| Enumerator | Description |
|----------------------------------|------------------------------------------------------------------|
| calendar_days_daily_amount | Daily amount on calendar days |
| workdays_daily_amount | Daily amount on working days |
| calendar_days_monthly_percentage | Monthly interest percentage charged based on calendar days |
## Response
STATUS 202
Response Body
```json
{
"occurrence_key": "5a745b65-9a2c-44eb-b43e-c80ef5429d94",
"bank_slip_key": "fdafdffa-cbd4-4f3c-8e3d-990428305161"
}
```
### Response Body Params
| Field | Type | Description | Characters |
|--------------------|--------|-----------------------------------------------------------------------------------|------------|
| `occurrence_key` * | uuidv4 | Unique occurrence (instruction) identification key in uuid v4 format | 36 |
| `bank_slip_key` * | uuidv4 | Unique bank slip identification key in uuid v4 format | 36 |
### Error Response
STATUS 4xx
Response Body: Error
```json
{
"title": "titulo",
"description": "description in English",
"translation": "descrição em portugues",
"code": "codigo",
"extra_fields": {}
}
```
| HTTP Status `status` | QI Code `code` | Title `title` | Description (eng) `description` | Description (pt-br) `translation` |
|--------------------------|----------------------|----------------------------------------------------|-------------------------------------------------------------------------------------------------------------------------|------------------------------------------------------------------------------------------------------------------------|
| 400 | QIT000001 | Bad Request | Schema Error | Schema Inválido |
| 404 | BKS000006 | Not Found | The source account key was not found. | A chave da conta de origem não foi encontrada. |
| 400 | BKS000007 | Bad Request | It 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. |
| 400 | BKS000008 | Bad Request | The source account is closed. | A conta de origem está fechada. |
| 400 | BKS000009 | Bad Request | The source account is blocked. | A conta de origem está bloqueada. |
| 404 | BKS000013 | Not Found | Requester profile not found | Carteira não encontrada |
| 409 | BKS000014 | Conflict | Request control key already sent or duplicated sent: `` | Chave de controle da requisição já utilizada ou enviada duplicada: `` |
| 400 | BKS000018 | Bad Request | The discount dates must be less than the expiration date and increasing. | A data dos descontos devem ser menores que a de expiração e crescentes. |
| 400 | BKS000022 | Bad Request | Requester profile is not opened. | Carteira não está aberta. |
| 404 | BKS000029 | Not Found | Bank slip not found for the given key (`{bank_slip_key}`). | Boleto não encontrado para a chave fornecida (`{bank_slip_key}`). |
| 400 | BKS000032 | Bad Request | Bank slip must be in 'registered' status. | O boleto deve possuir o status 'registered'. |
| 409 | BKS000051 | Conflict | There is already a pending interest occurrence for this bank slip. Please, wait for the confirmation of this occurrence before sending another one. | Já existe uma ocorrência de juros pendente para este boleto. Por favor, aguarde a confirmação dessa ocorrência antes de enviar outra. |
---
# Query instruction batch
URL: /en/documentation/boletos/instrucoes/lote/consultar_lote_de_instrucoes
Returns the detail of a previously created batch, with the list of generated occurrences and the individual status of each one, along with basic data of the related bank slip.
## Request
ENDPOINT /v2/bank_slip/account/ ACCOUNT_KEY /requester_profile/ REQUESTER_PROFILE_KEY /occurrence_batches/ BATCH_KEY /results
METHOD GET
### Path parameters
| Field | Type | Description | Characters |
|-------------------------|--------|------------------------------------------------------------|------------|
| `account_key` | uuidv4 | Unique account identification key, in uuid v4 format | 36 |
| `requester_profile_key` | uuidv4 | Unique wallet identification key, in uuid v4 format | 36 |
| `batch_key` | uuidv4 | Batch key (returned by the create POST) | 36 |
## Response
STATUS 200
Response Body
```json
{
"batch_key": "f2d3e1b9-4a5c-46e7-8f12-9a8b7c6d5e4f",
"requester_profile_key": "8217da98-3e26-4ca5-8b86-698bfa50b0df",
"occurrence_type": "extension",
"occurrence_quantity": 2,
"accepted_quantity": 2,
"created_at": "2026-06-09T17:08:33Z",
"items": [
{
"bank_slip_key": "960f78d4-4426-4762-98da-3ce3713ae0a5",
"occurrence_key": "2552bd64-950b-437e-a53a-a133ffea03d7",
"request_control_key": "c86d8902-a5ae-4d1f-8872-e6fea1268aab",
"occurrence_type": "extension",
"payer_name": "Global Tech",
"payer_document": "12345678000195",
"amount": 5000.00,
"our_number": "123456789",
"requester_occurrence_status": "accepted",
"registration_institution_occurrence_status": "submitted",
"created_at": "2026-06-09T17:08:33Z"
}
]
}
```
### Response Body Params
| Field | Type | Description |
|---------------------------|---------|------------------------------------------------------------------------------------------|
| `batch_key` * | uuidv4 | Batch key |
| `requester_profile_key` * | uuidv4 | Key of the wallet that owns the batch |
| `occurrence_type` * | string | Instruction type of the batch |
| `occurrence_quantity` * | integer | Total number of items sent in the batch |
| `accepted_quantity` * | integer | Number of items accepted in the batch |
| `created_at` * | string | UTC creation date/time of the batch (ISO 8601 with `Z` suffix) |
| `items` * | array | List of occurrences generated by the batch. See **[item object](#item-object)** |
### item object
| Field | Type | Description |
|------------------------------------------------|---------|------------------------------------------------------------------------------------------|
| `bank_slip_key` * | uuidv4 | Bank slip key of the occurrence |
| `occurrence_key` * | uuidv4 | Unique key of the created occurrence |
| `request_control_key` * | string | Item's client-provided control key |
| `occurrence_type` * | string | Instruction type |
| `payer_name` | string | Bank slip payer name |
| `payer_document` | string | Payer document |
| `amount` | float | Bank slip base amount |
| `our_number` | string | Bank slip "our number" |
| `requester_occurrence_status` | string | Occurrence status from the requester's perspective (e.g. `accepted`, `rejected`) |
| `registration_institution_occurrence_status` | string | Occurrence status at the registration institution (e.g. `submitted`, `confirmed`) |
| `created_at` * | string | UTC creation date/time of the occurrence (ISO 8601 with `Z` suffix) |
### Error Response
STATUS 4xx
Response Body: Error
```json
{
"title": "title",
"description": "description in English",
"translation": "descrição em português",
"code": "code",
"extra_fields": {}
}
```
| HTTP code `status` | QI code `code` | Title `title` | Description (eng) `description` | Description (pt-br) `translation` |
|------------------------|--------------------|--------------------|------------------------------------------------------------------|--------------------------------------------------------------------|
| 404 | BKS000013 | Not Found | Requester profile not found | Carteira não encontrada |
:::caution Attention!
When the `batch_key` does not exist or does not belong to the informed `requester_profile_key`, the API returns the same `BKS000013` ("Requester profile not found"). Check whether the `batch_key` was created under the wallet used in the query.
:::
---
# Create instruction batch
URL: /en/documentation/boletos/instrucoes/lote/criar_lote_de_instrucoes
Allows sending, in a single request, multiple instructions of the same type (write-off, rebate, extension, protest, etc.) over distinct bank slips. QI Tech validates the whole batch and either accepts every item or processes none.
- If **any** item fails semantic validation, **no** items in the batch are processed. The error response details, per rejected item, the reason for rejection.
- If every item passes, the occurrences are created and processed individually, asynchronously. The requester is notified via [**webhook**](/documentation/boletos/v2/webhooks/boleto) as each occurrence changes status.
:::info Idempotency
The batch-level `request_control_key` guarantees idempotency: resending the same key returns the batch already created, without duplication.
Each item also has its own `request_control_key` and is individually idempotent. Resending an item with a `request_control_key` already used makes the entire batch be rejected.
:::
:::caution Attention!
This operation is only available for wallets registered with the **QI SCD** registration institution.
:::
## Request
ENDPOINT /v2/bank_slip/account/ ACCOUNT_KEY /requester_profile/ REQUESTER_PROFILE_KEY /occurrence_batches
METHOD POST
### Path parameters
| Field | Type | Description | Characters |
|-------------------------|--------|------------------------------------------------------------|------------|
| `account_key` | uuidv4 | Unique account identification key, in uuid v4 format | 36 |
| `requester_profile_key` | uuidv4 | Unique wallet identification key, in uuid v4 format | 36 |
Request Body
```json
{
"request_control_key": "614a451d-3b82-460e-bcc0-2caf3dde711f",
"occurrence_type": "extension",
"items": [
{
"bank_slip_key": "960f78d4-4426-4762-98da-3ce3713ae0a5",
"request_control_key": "c86d8902-a5ae-4d1f-8872-e6fea1268aab",
"new_due_date": "2026-08-15"
},
{
"bank_slip_key": "5e3a1b2c-7d9f-4e88-9012-3a4b5c6d7e8f",
"request_control_key": "b3a428fd-58ee-4d6f-8872-633874ebf5e2",
"new_due_date": "2026-08-20"
}
]
}
```
### Request Body Params
| Field | Type | Description | Characters |
|-------------------------|-----------------------------------------------|-----------------------------------------------------------------------------------|------------|
| `request_control_key` * | string | Unique batch key, defined by the client. Ensures batch idempotency | 1–64 |
| `occurrence_type` * | string | Instruction type applied to every item. See **[occurrence_type enumerators](#occurrence_type-enumerators)** | - |
| `items` * | Array of **[item object](#item-object)** | List of instructions (minimum 1, maximum 10000) | - |
### occurrence_type enumerators
| Enumerator | Description |
|--------------------------|-------------------------------------------------------------------|
| `extension` | Due-date extension — requires `new_due_date` on each item |
| `rebate` | Apply rebate — requires `rebate_amount` on each item |
| `cancel_rebate` | Cancel a previously applied rebate |
| `write_off` | Write off the bank slip |
| `protest_request` | Protest request |
| `protest_cancel_request` | Withdraw a pending protest request |
| `protest_remove_request` | Remove (cancel) a registered protest |
### item object
| Field | Type | Description | Characters |
|-------------------------|----------|-----------------------------------------------------------------------------------|------------|
| `bank_slip_key` * | uuidv4 | Key of the bank slip the instruction will be applied to | 36 |
| `request_control_key` * | string | Unique item key, defined by the client. Ensures per-item idempotency | 1–64 |
| `new_due_date` | string | New due date (`YYYY-MM-DD`). Required when `occurrence_type=extension` | 10 |
| `rebate_amount` | float | Rebate amount. Required when `occurrence_type=rebate` | - |
## Response
STATUS 201
Response Body
```json
{
"batch_key": "f2d3e1b9-4a5c-46e7-8f12-9a8b7c6d5e4f",
"occurrence_quantity": 2,
"accepted_quantity": 2,
"semantic_errors": []
}
```
### Response Body Params
| Field | Type | Description | Characters |
|-------------------------|---------|---------------------------------------------------------------------------------------------|------------|
| `batch_key` * | uuidv4 | Unique batch key. Use it to query the batch detail | 36 |
| `occurrence_quantity` * | integer | Total number of items sent in the batch | - |
| `accepted_quantity` * | integer | Number of items accepted in the batch | - |
| `semantic_errors` * | array | Empty array on success. On semantic rejection, see **[Error Response](#error-response)** | - |
### Error Response
STATUS 4xx
Response Body: Error
```json
{
"title": "title",
"description": "description in English",
"translation": "descrição em português",
"code": "code",
"extra_fields": {}
}
```
On semantic rejection (`BLP000112`), the `reasons` field of the response details every rejected item:
Response Body: Semantic rejection
```json
{
"title": "Unprocessable Entity",
"description": "Rejected Remittance",
"translation": "Remessa Rejeitada",
"code": "BLP000112",
"reasons": [
{
"occurrence_sequence": "0",
"bank_slip_key": "960f78d4-4426-4762-98da-3ce3713ae0a5",
"request_control_key": "c86d8902-a5ae-4d1f-8872-e6fea1268aab",
"errors": [
{
"reason_code": "15",
"translation_pt_br": "Boleto não encontrado",
"translation_en_us": "Bank slip not found",
"created_at": "2026-06-09T17:08:33"
}
]
}
]
}
```
### `reasons[]` object fields
| Field | Type | Description |
|-----------------------------|---------|--------------------------------------------------------------------------------------|
| `occurrence_sequence` * | string | Item position in the request's `items` array (starting at `"0"`) |
| `bank_slip_key` * | uuidv4 | Bank slip key of the rejected item |
| `request_control_key` * | string | Item's client-provided control key |
| `errors` * | array | List of rejection reasons (an item may have multiple) |
| `errors[].reason_code` * | string | Rejection reason code (Febraban standard) |
| `errors[].translation_pt_br`| string | Portuguese description of the reason |
| `errors[].translation_en_us`| string | English description of the reason |
| `errors[].created_at` | string | Catalog registration date of the reason |
### Error codes
| HTTP code `status` | QI code `code` | Title `title` | Description (eng) `description` | Description (pt-br) `translation` |
|------------------------|--------------------|----------------------|---------------------------------------------------------------------------------------------|----------------------------------------------------------------------------------------------|
| 400 | QIT000001 | Bad Request | Schema Error | Schema Inválido |
| 400 | BKS000141 | Bad Request | Bank slip registration is restricted to QI SCD. | Registro de boleto permitido apenas para QI SCD. |
| 404 | BKS000013 | Not Found | Requester profile not found | Carteira não encontrada |
| 409 | BKS000014 | Conflict | Request control key already sent or duplicated sent: `` | Chave de controle da requisição já utilizada ou enviada duplicada: `` |
| 422 | BLP000112 | Unprocessable Entity | Rejected Remittance | Remessa Rejeitada |
---
# List instruction batches
URL: /en/documentation/boletos/instrucoes/lote/listar_lotes_de_instrucoes
Lists, with pagination, the instruction batches created for a wallet, with optional filters by instruction type and date range.
## Request
ENDPOINT /v2/bank_slip/account/ ACCOUNT_KEY /requester_profile/ REQUESTER_PROFILE_KEY /occurrence_batches
METHOD GET
### Path parameters
| Field | Type | Description | Characters |
|-------------------------|--------|------------------------------------------------------------|------------|
| `account_key` | uuidv4 | Unique account identification key, in uuid v4 format | 36 |
| `requester_profile_key` | uuidv4 | Unique wallet identification key, in uuid v4 format | 36 |
### Query Parameters
| Field | Type | Description |
|-------------------|---------|----------------------------------------------------------------------------------------------|
| `page` | integer | Query page (default `1`) |
| `page_size` | integer | Number of batches per page (default `20`, max `100`) |
| `occurrence_type` | string | Filter by instruction type. Accepts the same enumerators as the create POST |
| `from_date` | string | Start date, inclusive, in `YYYY-MM-DD` format. Filters over the batch's `created_at` |
| `to_date` | string | End date, inclusive, in `YYYY-MM-DD` format. Filters over the batch's `created_at` |
## Response
STATUS 200
Response Body
```json
{
"data": [
{
"batch_key": "f2d3e1b9-4a5c-46e7-8f12-9a8b7c6d5e4f",
"request_control_key": "614a451d-3b82-460e-bcc0-2caf3dde711f",
"requester_profile_key": "8217da98-3e26-4ca5-8b86-698bfa50b0df",
"occurrence_type": "extension",
"occurrence_quantity": 14,
"accepted_quantity": 14,
"created_at": "2026-06-09T17:08:33Z"
}
],
"pagination": {
"page": 1,
"page_size": 20,
"total": 1
}
}
```
### Response Body Params
| Field | Type | Description |
|----------------------------------|---------|--------------------------------------------------------------------------|
| `data` * | array | List of batches on the current page |
| `data[].batch_key` * | uuidv4 | Batch key |
| `data[].request_control_key` * | string | Client-provided control key from batch creation |
| `data[].requester_profile_key` * | uuidv4 | Key of the wallet that owns the batch |
| `data[].occurrence_type` * | string | Instruction type of the batch |
| `data[].occurrence_quantity` * | integer | Total number of items sent in the batch |
| `data[].accepted_quantity` * | integer | Number of items accepted in the batch |
| `data[].created_at` * | string | UTC creation date/time of the batch (ISO 8601 with `Z` suffix) |
| `pagination` * | object | Pagination metadata |
| `pagination.page` * | integer | Current page |
| `pagination.page_size` * | integer | Page size |
| `pagination.total` * | integer | Total number of batches matching the filters |
### Error Response
STATUS 4xx
| HTTP code `status` | QI code `code` | Title `title` | Description (eng) `description` | Description (pt-br) `translation` |
|------------------------|--------------------|--------------------|-------------------------------------|---------------------------------------|
| 400 | QIT000001 | Bad Request | Schema Error | Schema Inválido |
| 404 | BKS000013 | Not Found | Requester profile not found | Carteira não encontrada |
---
# Fine
URL: /en/documentation/boletos/instrucoes/multa
The fine instruction is used to configure the fine that will be applied if the bank slip is paid after the due date. If a fine configuration already exists for the bank slip in question, and a fine instruction is accepted, the previously existing configuration will be overwritten.
:::caution Attention!
If there is any fine instruction pending confirmation, sending a new instruction is not allowed.
:::
## Request
ENDPOINT /account/ ACCOUNT_KEY /requester_profile/ REQUESTER_PROFILE_KEY /bank_slip/ BANK_SLIP_KEY /fine
MÉTODO POST
### Path parameters
| Field | Type | Description | Characters |
|-------------------------|--------|--------------------------------------------------------------|------------|
| `account_key` | uuidv4 | Unique account identification key, in uuid v4 format | 36 |
| `requester_profile_key` | uuidv4 | Unique wallet identification key, in uuid v4 format | 36 |
| `bank_slip_key` | uuidv4 | Unique bank slip identification key, in uuid v4 format | 36 |
Request Body
```json
{
"request_control_key": "c4dd443a-6e2f-4261-8f28-adfa4c0d4c5b",
"fine_data": {
"fine_type": "absolute",
"fine_amount": 50.00,
"days_to_fine": 5
}
}
```
### Request Body Params
| Field | Type | Description | Characters |
|----------------------------|---------|------------------------------------------------------------------------------------|------------|
| `request_control_key` * | uuidv4 | Unique request identification key used by the client in uuid v4 format | 36 |
| `interest_data` | object | Fine configurations | **[fine_data Object](#fine_data-object)** |
### fine_data Object
Option 1: absolute value fine (`fine_type=absolute`)
| Field | Type | Description | Characters |
|---------------------------|---------|---------------------------------------------------------|-------------------------------------------------------------------------|
| `fine_type` * | string | Fine type | **[fine_type Enumerators](#fine_type-enumerators)** |
| `fine_amount` * | float | Absolute fine amount | - |
| `days_to_fine` * | integer | Days after due date for the fine to be charged | - |
Option 2: percentage value fine (`fine_type=percentage`)
| Field | Type | Description | Characters |
|---------------------------|---------|-----------------------------------------------------------|---------------------------------------|
| `fine_type` * | string | Fine type | **[fine_type Enumerators](#fine_type-enumerators)** |
| `fine_percentage` * | integer | Percentage fine amount, from 1 to 100 | - |
| `days_to_fine` * | integer | Days after due date for the fine to be charged | - |
### fine_type Enumerators
| Enumerator | Description |
|--------------------|-----------------------|
| absolute | absolute value |
| percentage | percentage value |
## Response
STATUS 202
Response Body
```json
{
"occurrence_key": "aaf64135-6bd8-4d49-be6f-e8f884b20ee7",
"bank_slip_key": "470cfcae-159b-4de4-ad22-2d3b2dd717f7"
}
```
### Response Body Params
| Field | Type | Description | Characters |
|--------------------|--------|-----------------------------------------------------------------------------------|------------|
| `occurrence_key` * | uuidv4 | Unique occurrence (instruction) identification key in uuid v4 format | 36 |
| `bank_slip_key` * | uuidv4 | Unique bank slip identification key in uuid v4 format | 36 |
### Error Response
STATUS 4xx
Response Body: Error
```json
{
"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` |
|--------------------------|----------------------|----------------------------------------------------|-------------------------------------------------------------------------------------------------------------------------|------------------------------------------------------------------------------------------------------------------------|
| 400 | QIT000001 | Bad Request | Schema Error | Schema Inválido |
| 404 | BKS000006 | Not Found | The source account key was not found. | A chave da conta de origem não foi encontrada. |
| 400 | BKS000007 | Bad Request | It 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. |
| 400 | BKS000008 | Bad Request | The source account is closed. | A conta de origem está fechada. |
| 400 | BKS000009 | Bad Request | The source account is blocked. | A conta de origem está bloqueada. |
| 404 | BKS000013 | Not Found | Requester profile not found | Carteira não encontrada |
| 409 | BKS000014 | Conflict | Request control key already sent or duplicated sent: `` | Chave de controle da requisição já utilizada ou enviada duplicada: `` |
| 400 | BKS000018 | Bad Request | The discount dates must be less than the expiration date and increasing. | A data dos descontos devem ser menores que a de expiração e crescentes. |
| 400 | BKS000022 | Bad Request | Requester profile is not opened. | Carteira não está aberta. |
| 404 | BKS000029 | Not Found | Bank slip not found for the given key (`{bank_slip_key}`). | Boleto não encontrado para a chave fornecida (`{bank_slip_key}`). |
| 400 | BKS000032 | Bad Request | Bank slip must be in 'registered' status. | O boleto deve possuir o status 'registered'. |
| 409 | BKS000050 | Conflict | There is already a pending fine occurrence for this bank slip. Please, wait for the confirmation of this occurrence before sending another one. | Já existe uma ocorrência de multa pendente para este boleto. Por favor, aguarde a confirmação dessa ocorrência antes de enviar outra. |
---
# Partial Payment
URL: /en/documentation/boletos/instrucoes/pagamento_parcial
The partial payment instruction allows editing partial payment configurations for a bank slip, as long as the bank slip has already been registered with partial payment active. If there is already a partial payment configuration for the bank slip in question, and a new instruction is accepted, the previously existing configuration will be overwritten.
:::caution Attention!
If there is any partial payment instruction pending confirmation, it is not allowed to send a new instruction.
:::
## Request
ENDPOINT /account/ ACCOUNT_KEY /requester_profile/ REQUESTER_PROFILE_KEY /bank_slip/ BANK_SLIP_KEY /partial_payment
METHOD POST
### Path parameters
| Field | Type | Description | Characters |
|-------------------------|--------|--------------------------------------------------------------|------------|
| `account_key` | uuidv4 | Unique account identification key, in uuid v4 format | 36 |
| `requester_profile_key` | uuidv4 | Unique wallet identification key, in uuid v4 format | 36 |
| `bank_slip_key` | uuidv4 | Unique bank slip identification key, in uuid v4 format | 36 |
Request Body
```json
{
"request_control_key": "01234567-89ab-cdef-0123-456789abcdef",
"partial_payment_data": {
"partial_payment_minimum_type": "absolute",
"partial_payment_minimum_amount": 50.00,
"partial_payment_maximum_type": "absolute",
"partial_payment_maximum_amount": 1000.00,
"partial_payment_quantity": 3
}
}
```
### Request Body Params
| Field | Type | Description | Characters |
|----------------------------|---------|------------------------------------------------------------------------------------|------------|
| `request_control_key` * | uuidv4 | Unique request identification key used by the client in uuid v4 format | 36 |
| `partial_payment_data` * | object | Partial payment configurations | **[partial_payment_data Object](#partial_payment_data-object)** |
### partial_payment_data Object
| Field | Type | Description | Characters |
|-----------------------------------|---------|---------------------------------------------------------------------------|------------|
| `partial_payment_minimum_type` * | string | Minimum value type for partial payment | **[partial_payment_type Enumerators](#partial_payment_type-enumerators)** |
| `partial_payment_minimum_percentage` | float | Minimum percentage allowed for partial payment | - |
| `partial_payment_minimum_amount` | float | Minimum amount allowed for partial payment | - |
| `partial_payment_maximum_type` | string | Maximum value type for partial payment | **[partial_payment_type Enumerators](#partial_payment_type-enumerators)** |
| `partial_payment_maximum_percentage` | float | Maximum percentage allowed for partial payment | - |
| `partial_payment_maximum_amount` | float | Maximum amount allowed for partial payment | - |
| `partial_payment_quantity` * | integer | Number of partial payments allowed | - |
:::caution Attention!
According to the value sent in the `partial_payment_minimum_type` and `partial_payment_maximum_type` fields, it is necessary to send the corresponding `partial_payment_minimum_amount` or `partial_payment_minimum_percentage`, and the `partial_payment_maximum_amount` or `partial_payment_maximum_percentage`.
:::
### partial_payment_type Enumerators
| Enumerator | Description |
|-------------|----------------------------------|
| absolute | Absolute value |
| percentage | Percentage |
## Response
STATUS 202
Response Body
```json
{
"occurrence_key": "5a745b65-9a2c-44eb-b43e-c80ef5429d94",
"bank_slip_key": "fdafdffa-cbd4-4f3c-8e3d-990428305161"
}
```
### Response Body Params
| Field | Type | Description | Characters |
|--------------------|--------|-----------------------------------------------------------------------------------|------------|
| `occurrence_key` * | uuidv4 | Unique occurrence (instruction) identification key in uuid v4 format | 36 |
| `bank_slip_key` * | uuidv4 | Unique bank slip identification key in uuid v4 format | 36 |
### Error Response
STATUS 4xx
Response Body: Error
```json
{
"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` |
|--------------------------|----------------------|----------------------------------------------------|-------------------------------------------------------------------------------------------------------------------------|------------------------------------------------------------------------------------------------------------------------|
| 400 | QIT000001 | Bad Request | Schema Error | Schema Inválido |
| 404 | BKS000006 | Not Found | The source account key was not found. | A chave da conta de origem não foi encontrada. |
| 400 | BKS000007 | Bad Request | It 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. |
| 400 | BKS000008 | Bad Request | The source account is closed. | A conta de origem está fechada. |
| 400 | BKS000009 | Bad Request | The source account is blocked. | A conta de origem está bloqueada. |
| 404 | BKS000013 | Not Found | Requester profile not found | Carteira não encontrada |
| 409 | BKS000014 | Conflict | Request control key already sent or duplicated sent: `` | Chave de controle da requisição já utilizada ou enviada duplicada: `` |
| 400 | BKS000022 | Bad Request | Requester profile is not opened. | Carteira não está aberta. |
| 404 | BKS000029 | Not Found | Bank slip not found for the given key (`{bank_slip_key}`). | Boleto não encontrado para a chave fornecida (`{bank_slip_key}`). |
| 400 | BKS000032 | Bad Request | Bank slip must be in 'registered' status. | O boleto deve possuir o status 'registered'. |
| 409 | BKS000126 | Conflict | There is already a pending partial payment occurrence for this bank slip. Please, wait for the confirmation of this occurrence before sending another one. | Já existe uma ocorrência de pagamento parcial pendente para este boleto. Por favor, aguarde a confirmação dessa ocorrência antes de enviar outra. |
| 400 | BKS000127 | Bad Request | Partial payment data is not set for this bank slip. | Os dados de pagamento parcial não estão configurados para este boleto. |
---
# Protest instrument query
URL: /en/documentation/boletos/instrucoes/protesto/consulta_instrumento_de_protesto
The protest instrument is an official document issued by the protest registry office, which proves the execution of the collection process. It is issued after the protest is registered, if the debtor has not paid the debt after being notified.
:::caution Attention!
It is only possible to query the protest instrument of the title after it has been effectively protested (`protest_status` has the value `protested`).
:::
## Request
ENDPOINT /account/ ACCOUNT_KEY /requester_profile/ REQUESTER_PROFILE_KEY /bank_slip/ BANK_SLIP_KEY /protest_instrument
METHOD GET
### Path parameters
| Field | Type | Description | Characters |
|-------------------------|--------|--------------------------------------------------------------|------------|
| `account_key` | uuidv4 | Unique account identification key, in uuid v4 format | 36 |
| `requester_profile_key` | uuidv4 | Unique wallet identification key, in uuid v4 format | 36 |
| `bank_slip_key` | uuidv4 | Unique bank slip identification key, in uuid v4 format | 36 |
## Response
STATUS 200
Response Body
```json
{
"bank_slip_key": "bc34e9b1-42e4-4f17-bfc0-c88f29d5230e",
"file_url": "https://storage.googleapis.com/live-bank-slip-api/protest_instrument/bc34e9b1-42e4-4f17-bfc0-c88f29d5230e.pdf"
}
```
### Response Body Params
| Field | Type | Description | Characters |
|----------------------------|---------|------------------------------------------------------------------------------------|--------------------------------------------------|
| `bank_slip_key` * | uuidv4 | Unique bank slip identification key in uuid v4 format | 36 |
| `file_url` * | string | File URL, in PDF format, containing the protest instrument document | - |
## Error Response
STATUS 4xx
Response Body: Error
```json
{
"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 (ptbr) `translation` |
|--------------------------|----------------------|----------------------------------------------------|-------------------------------------------------------------------------------------------------------------------------|------------------------------------------------------------------------------------------------------------------------|
| 400 | QIT000001 | Bad Request | Schema Error | Schema Inválido |
| 404 | BKS000006 | Not Found | The source account key was not found. | A chave da conta de origem não foi encontrada. |
| 400 | BKS000007 | Bad Request | It 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. |
| 400 | BKS000008 | Bad Request | The source account is closed. | A conta de origem está fechada. |
| 400 | BKS000009 | Bad Request | The source account is blocked. | A conta de origem está bloqueada. |
| 404 | BKS000013 | Not Found | Requester profile not found | Carteira não encontrada |
| 404 | BKS000029 | Not Found | Bank slip not found for the given key (`{bank_slip_key}`). | Boleto não encontrado para a chave fornecida (`{bank_slip_key}`). |
| 400 | BKS000081 | Bad Request | The protest instrument will be available only after bank slip's protest confirmation. | O instrumento de protesto só estará disponível após a confirmação do protesto do título. |
| 500 | BKS000105 | Internal Server Error | Could not fetch protest instrument for the given 'bank_slip_key' at this moment. Please, try again later. | Não foi possível recuperar o instrumento de protesto para a chave ('bank_slip_key') fornecida. Por favor, tente novamente mais tarde. |
| 404 | BKS000106 | Not Found | No protest found for the given bank slip. | Nenhum protesto foi encontrado para o boleto fornecido. |
---
# Query protest by key
URL: /en/documentation/boletos/instrucoes/protesto/consulta_por_chave
Querying a protest using its key returns detailed information about it.
## Request
ENDPOINT /account/ ACCOUNT_KEY /requester_profile/ REQUESTER_PROFILE_KEY /protest/ BANK_SLIP_KEY
METHOD GET
### Path parameters
| Field | Type | Description | Characters |
|-------------------------|--------|--------------------------------------------------------------|------------|
| `account_key` | uuidv4 | Unique account identification key in uuid v4 format | 36 |
| `requester_profile_key` | uuidv4 | Unique wallet identification key in uuid v4 format | 36 |
| `bank_slip_key` | uuidv4 | Unique bank slip identification key in uuid v4 format | 36 |
## Response
STATUS 200
Response Body
```json
{
"protest_key": "bc34e9b1-42e4-4f17-bfc0-c88f29d5230e",
"request_control_key": "59515878-50e9-466b-b40d-1aac3939c3fd",
"protest_status": "protested",
"bank_slip_key": "7d3d262b-9b55-44cd-8355-2f00d5b1d142",
"requester_profile_code": "329-09-0001-1467576",
"protest_type": "protest",
"protocol_number": "0000672016",
"protocol_date": "2012-12-16",
"notary_office": {
"city": "VITORIA",
"uf": "ES"
}
}
```
### Response Body Params
| Field | Type | Description | Characters |
|----------------------------|---------|------------------------------------------------------------------------------------|--------------------------------------------------|
| `protest_key ` * | uuidv4 | Unique protest identification key in uuid v4 format | 36 |
| `request_control_key` * | uuidv4 | Unique identification key of the request used by the client in uuid v4 format | 36 |
| `protest_status` * | string | Protest status | **[protest_status Enumerators](#protest_status-enumerators)** |
| `bank_slip_key` * | uuidv4 | Unique bank slip identification key in uuid v4 format | 36 |
| `requester_profile_code` * | string | Unique wallet identification code | 10 |
| `protest_type` * | string | Protest type | **[protest_type Enumerators](#protest_type-enumerators)** |
| `protocol_number` | string | Protocol number | 10 |
| `protocol_date` | string | Protocol date (format "YYYY-MM-DD") | 10 |
| `notary_office` | object | Protest notary office data | **[notary_office Object](#notary_office-object)** |
### protest_status Enumerators
| Enumerator | Description |
|------------------------------|--------------------------------------------------------------------------------|
| accepted | Accepted but not yet sent to the protest notary offices |
| submitted | Sent to the notary office |
| cancellation_requested | Protest suspension requested |
| cancelled | Submission cancelled or protest suspended |
| rejected | Protest request rejected |
| at_notary_office | At the protest notary office, in the three-day period |
| paid_at_notary_office | Title paid at the notary office |
| protested | Title protested and settled |
| removal_requested | Title already protested, with cancellation requested |
| removed | Protest cancelled |
### protest_type Enumerators
| Enumerator | Description |
|------------------------------|--------------------------------------------------------------------------------|
| protest | Common protest |
| bankruptcy_protest | Bankruptcy protest |
### notary_office Object
| Field | Type | Description | Characters |
|----------------------------|---------|------------------------------------------------------------------------------------|--------------------------------------------------|
| `city` * | string | Protest notary office city | - |
| `uf` * | string | Protest notary office state (UF) | 2 |
## Error Response
STATUS 4xx
Response Body: Error
```json
{
"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 (ptbr) `translation` |
|--------------------------|----------------------|----------------------------------------------------|-------------------------------------------------------------------------------------------------------------------------|------------------------------------------------------------------------------------------------------------------------|
| 400 | QIT000001 | Bad Request | Schema Error | Schema Inválido |
| 404 | BKS000006 | Not Found | The source account key was not found. | A chave da conta de origem não foi encontrada. |
| 400 | BKS000007 | Bad Request | It 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. |
| 400 | BKS000008 | Bad Request | The source account is closed. | A conta de origem está fechada. |
| 400 | BKS000009 | Bad Request | The source account is blocked. | A conta de origem está bloqueada. |
| 404 | BKS000013 | Not Found | Requester profile not found | Carteira não encontrada |
| 404 | BKS000029 | Not Found | Bank slip not found for the given key (`{bank_slip_key}`). | Boleto não encontrado para a chave fornecida (`{bank_slip_key}`). |
| 404 | BKS000106 | Not Found | No protest found for the given bank slip. | Nenhum protesto foi encontrado para o boleto fornecido. |
---
# Protest withdrawal (protest stoppage)
URL: /en/documentation/boletos/instrucoes/protesto/desistencia_de_protesto
It is possible to withdraw a protest request by sending a `protest_cancel_request` instruction.
:::caution Attention!
The `protest_cancel_request` occurrence, by itself, does not cancel the bank slip. If the exit from the notary office is caused by a `protest_cancel_request` occurrence, another `notary_office_exit` occurrence is created, which is sent to CIP/Nuclea to unblock the bank slip for payment. Once it is confirmed, the bank slip can be paid again via the typeable line. If it is desired that the bank slip be canceled after the protest withdrawal, the ideal is to send a [**protest withdrawal and bank slip cancellation**](/documentation/boletos/instrucoes/protesto/desistencia_de_protesto_e_baixa_do_boleto) instruction.
:::
## Request
ENDPOINT /account/ ACCOUNT_KEY /requester_profile/ REQUESTER_PROFILE_KEY /bank_slip/ BANK_SLIP_KEY /protest_cancel_request
METHOD POST
### Path parameters
| Field | Type | Description | Characters |
|-------------------------|--------|--------------------------------------------------------------|------------|
| `account_key` | uuidv4 | Unique account identification key, in uuid v4 format | 36 |
| `requester_profile_key` | uuidv4 | Unique wallet identification key, in uuid v4 format | 36 |
| `bank_slip_key` | uuidv4 | Unique bank slip identification key, in uuid v4 format | 36 |
Request Body
```json
{
"request_control_key": "614a451d-3b82-460e-bcc0-2caf3dde711f"
}
```
### Request Body Params
| Field | Type | Description | Characters |
|----------------------------|---------|------------------------------------------------------------------------------------|------------|
| `request_control_key` * | uuidv4 | Unique request identification key used by the client in uuid v4 format | 36 |
## Response
STATUS 202
Response Body
```json
{
"occurrence_key": "2552bd64-950b-437e-a53a-a133ffea03d7",
"bank_slip_key": "960f78d4-4426-4762-98da-3ce3713ae0a5"
}
```
### Response Body Params
| Field | Type | Description | Characters |
|--------------------|--------|-----------------------------------------------------------------------------------|------------|
| `occurrence_key` * | uuidv4 | Unique occurrence (instruction) identification key in uuid v4 format | 36 |
| `bank_slip_key` * | uuidv4 | Unique bank slip identification key in uuid v4 format | 36 |
### Error Response
STATUS 4xx
Response Body: Error
```json
{
"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` |
|--------------------------|----------------------|----------------------------------------------------|-------------------------------------------------------------------------------------------------------------------------|------------------------------------------------------------------------------------------------------------------------|
| 400 | QIT000001 | Bad Request | Schema Error | Schema Inválido |
| 404 | BKS000006 | Not Found | The source account key was not found. | A chave da conta de origem não foi encontrada. |
| 400 | BKS000007 | Bad Request | It 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. |
| 400 | BKS000008 | Bad Request | The source account is closed. | A conta de origem está fechada. |
| 400 | BKS000009 | Bad Request | The source account is blocked. | A conta de origem está bloqueada. |
| 404 | BKS000013 | Not Found | Requester profile not found | Carteira não encontrada |
| 409 | BKS000014 | Conflict | Request control key already sent or duplicated sent: `` | Chave de controle da requisição já utilizada ou enviada duplicada: `` |
| 400 | BKS000019 | Bad Request | Payer address is required for protest. | Endereço do pagador é obrigatório para protesto. |
| 400 | BKS000022 | Bad Request | Requester profile is not opened. | Carteira não está aberta. |
| 404 | BKS000029 | Not Found | Bank slip not found for the given key (`{bank_slip_key}`). | Boleto não encontrado para a chave fornecida (`{bank_slip_key}`). |
| 400 | BKS000032 | Bad Request | Bank slip must be in 'registered' status. | O boleto deve possuir o status 'registered'. |
| 400 | BKS000076 | Bad Request | Bank slip must have an ongoing protest request. | O boleto deve ter um pedido de protesto em vigência. |
| 400 | BKS000077 | Bad Request | Invalid bank slip protest status to cancel protest request. | Status de protesto do boleto inválido para desistir do pedido de protesto. |
---
# Protest withdrawal (stay) and bank slip write-off
URL: /en/documentation/boletos/instrucoes/protesto/desistencia_de_protesto_e_baixa_do_boleto
Another way to withdraw a protest request is by sending a `protest_cancel_and_write_off_request` instruction.
:::caution Warning!
The `protest_cancel_and_write_off_request` instruction also writes off the bank slip in CIP/Nuclea. As soon as it is confirmed, a `write_off` occurrence is automatically created and sent to Nuclea.
:::
## Request
ENDPOINT /account/ ACCOUNT_KEY /requester_profile/ REQUESTER_PROFILE_KEY /bank_slip/ BANK_SLIP_KEY /protest_cancel_and_write_off_request
METHOD POST
### Path parameters
| Field | Type | Description | Characters |
|-------------------------|--------|----------------------------------------------------------------|------------|
| `account_key` | uuidv4 | Unique account identification key, in uuid v4 format | 36 |
| `requester_profile_key` | uuidv4 | Unique wallet identification key, in uuid v4 format | 36 |
| `bank_slip_key` | uuidv4 | Unique bank slip identification key, in uuid v4 format | 36 |
Request Body
```json
{
"request_control_key": "614a451d-3b82-460e-bcc0-2caf3dde711f"
}
```
### Request Body Params
| Field | Type | Description | Characters |
|----------------------------|---------|------------------------------------------------------------------------------------|------------|
| `request_control_key` * | uuidv4 | Unique request identification key used by the client in uuid v4 format | 36 |
## Response
STATUS 202
Response Body
```json
{
"occurrence_key": "2552bd64-950b-437e-a53a-a133ffea03d7",
"bank_slip_key": "960f78d4-4426-4762-98da-3ce3713ae0a5"
}
```
### Response Body Params
| Field | Type | Description | Characters |
|--------------------|--------|-----------------------------------------------------------------------------------|------------|
| `occurrence_key` * | uuidv4 | Unique occurrence (instruction) identification key in uuid v4 format | 36 |
| `bank_slip_key` * | uuidv4 | Unique bank slip identification key in uuid v4 format | 36 |
### Error Response
STATUS 4xx
Response Body: Error
```json
{
"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` |
|--------------------------|----------------------|----------------------------------------------------|-------------------------------------------------------------------------------------------------------------------------|------------------------------------------------------------------------------------------------------------------------|
| 400 | QIT000001 | Bad Request | Schema Error | Schema Inválido |
| 404 | BKS000006 | Not Found | The source account key was not found. | A chave da conta de origem não foi encontrada. |
| 400 | BKS000007 | Bad Request | It 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. |
| 400 | BKS000008 | Bad Request | The source account is closed. | A conta de origem está fechada. |
| 400 | BKS000009 | Bad Request | The source account is blocked. | A conta de origem está bloqueada. |
| 404 | BKS000013 | Not Found | Requester profile not found | Carteira não encontrada |
| 409 | BKS000014 | Conflict | Request control key already sent or duplicated sent: `` | Chave de controle da requisição já utilizada ou enviada duplicada: `` |
| 400 | BKS000019 | Bad Request | Payer address is required for protest. | Endereço do pagador é obrigatório para protesto. |
| 400 | BKS000022 | Bad Request | Requester profile is not opened. | Carteira não está aberta. |
| 404 | BKS000029 | Not Found | Bank slip not found for the given key (`{bank_slip_key}`). | Boleto não encontrado para a chave fornecida (`{bank_slip_key}`). |
| 400 | BKS000032 | Bad Request | Bank slip must be in 'registered' status. | O boleto deve possuir o status 'registered'. |
| 400 | BKS000076 | Bad Request | Bank slip must have an ongoing protest request. | O boleto deve ter um pedido de protesto em vigência. |
| 400 | BKS000077 | Bad Request | Invalid bank slip protest status to cancel protest request. | Status de protesto do boleto inválido para desistir do pedido de protesto. |
---
# Introduction
URL: /en/documentation/boletos/instrucoes/protesto/introducao
## Notary office protest
A notary office protest request can be made after the boleto's due date, and serves to have the payer notified to pay the bill at the notary office. If they fail to do so, a public record of default is made in their name, in addition to having their name included in credit protection agencies, such as Serasa.
## Protest flow
### Protest request
The protest flow for a boleto is initiated with a protest request : an instruction of type `protest_request`. From the moment the protest request is accepted by CIP/Nuclea (the `protest_request` instruction is confirmed), the boleto becomes blocked for payment, which means the payer can only pay it at the notary office. Additionally, a `notary_office_entry` occurrence is also created, which refers to sending the protest request to the notary office. Protest request remittances are sent daily to notary offices at 9 AM, therefore, if protest request instructions are received after this time, they are only sent to notary offices the following day.
On subsequent days, the notary office must confirm the entry of the bill into the notary office (the `notary_office_entry` occurrence is confirmed) and, with this, the triduum period begins. The triduum is the 3 business day period for the payer to pay the boleto at the notary office, and if they fail to do so, the bill will be protested. If the bill is paid at the notary office, a `notary_office_payment_notice` type occurrence is created for the boleto in question and it is settled the following day. In this latter case, a `payment_write_off` instruction is also automatically generated, so that the boleto is written off with CIP/Nuclea.
If the triduum period ends and the boleto is not paid and there is no withdrawal from the protest, the boleto is protested. At this moment, a `protest_write_off` instruction is generated to write off the boleto at CIP/Nuclea, and the bill's life cycle ends.
### Withdrawal (suspension) of protest request
If issues regarding the bill are resolved directly between the payer and the drawer guarantor, until the boleto is actually protested (that is, until the last day of the triduum), it is possible to send a `protest_cancel_request` instruction, which withdraws the protest request; or a `protest_cancel_and_write_off_request` instruction, which withdraws the protest request and also writes off the boleto at CIP/Nuclea. It's worth noting that the `protest_cancel_request` occurrence, by itself, does not write off the boleto. If the exit from the notary office is caused by a `protest_cancel_request` type occurrence, another `notary_office_exit` occurrence is created, which is sent to CIP/Nuclea to unblock the boleto for payment. As soon as it is confirmed, the boleto can again be paid via the typed line. On the other hand, if the exit from the notary office is caused by a `protest_cancel_and_write_off_request` type occurrence, a `write_off` occurrence is automatically created, which writes off the boleto at CIP/Nuclea.
### Removal (cancellation) of protest request
If the pending issue between the payer and drawer guarantor is resolved after the boleto has already been protested, it is possible to send a `protest_remove_request` type instruction, which removes the public default record and any record, linked to this boleto, that has tarnished the payer's name. If the occurrence is confirmed (accepted by the notary office), the protest is removed and no more instructions are created for this boleto, since it is already written off at CIP/Nuclea.
---
# List protests
URL: /en/documentation/boletos/instrucoes/protesto/listar_protestos
The protest listing will return all protests in notary offices for bank slips from the wallet that match the query parameters sent in the request.
## Request
ENDPOINT /account/ ACCOUNT_KEY /requester_profile/ REQUESTER_PROFILE_KEY /protests
METHOD GET
### Path parameters
| Field | Type | Description | Characters |
|-------------------------|--------|--------------------------------------------------------------|------------|
| `account_key` | uuidv4 | Unique account identification key, in uuid v4 format | 36 |
| `requester_profile_key` | uuidv4 | Unique wallet identification key, in uuid v4 format | 36 |
### Query parameters
| Field | Type | Description | Characters |
|-------------------------|--------|--------------------------------------------------------------|-------------------------|
| `protest_key` | uuidv4 | Unique protest identification key, in uuid v4 format | 36 |
| `request_control_key` | uuidv4 | Unique request identification key, in uuid v4 format | 36 |
| `protest_status` | string | Protest status | **[protest_status enumerators](#enumeradores-protest_status)** |
| `bank_slip_key` | uuidv4 | Unique bank slip identification key, in uuid v4 format | 36 |
| `protocol_number` | string | Protocol number | 36 |
| `protocol_date` | string | Protocol date (format "YYYY-MM-DD") | 10 |
| `page_size` | integer| Page size | - |
| `from_date` | string | Start date (format "YYYY-MM-DD") | 10 |
| `to_date` | string | End date (format "YYYY-MM-DD") | 10 |
### protest_status enumerators
| Enumerator | Description |
|------------------------------|--------------------------------------------------------------------------------|
| accepted | Accepted, but not yet sent to the protest notary offices |
| submitted | Sent to notary office |
| cancellation_requested | Protest suspension requested |
| cancelled | Sending cancelled, or protest suspended |
| rejected | Protest request rejected |
| at_notary_office | At protest notary office, in triduum period |
| paid_at_notary_office | Title paid at notary office |
| protested | Title protested and settled |
| removal_requested | Title already protested, with cancellation requested |
| removed | Protest cancelled |
## Response
STATUS 200
Response Body
```json
{
"data": [
{
"protest_key": "ad44278d-7cf1-4ac7-9545-410649a47dde",
"request_control_key": "7e40ebab-f00c-4dbf-88be-ff34434ab358",
"protest_status": "protested",
"bank_slip_key": "7bf086ac-f520-4498-abd4-5a7d2173fd1c",
"requester_profile_code": "329-09-0001-1467576",
"protest_type": "protest",
"protocol_number": "0000000004",
"protocol_date": "2024-11-27",
"notary_office": {
"city": "SAO PAULO",
"uf": "SP"
}
},
{
"protest_key": "0087f425-5e54-4b4c-ab17-a57bc80f223a",
"request_control_key": "c413cedc-78ac-4deb-ace8-d94d4e98197c",
"protest_status": "at_notary_office",
"bank_slip_key": "e345c0b3-012b-4a4b-9d6b-6981f40b1a7c",
"requester_profile_code": "329-09-0001-1467576",
"protest_type": "protest",
"protocol_number": "0000000016",
"protocol_date": "2024-12-10",
"notary_office": {
"city": "RIO DE JANEIRO",
"uf": "RJ"
}
},
{
"protest_key": "bc34e9b1-42e4-4f17-bfc0-c88f29d5230e",
"request_control_key": "59515878-50e9-466b-b40d-1aac3939c3fd",
"protest_status": "accepted",
"bank_slip_key": "7d3d262b-9b55-44cd-8355-2f00d5b1d142",
"requester_profile_code": "329-09-0001-1467576",
"protest_type": "protest"
}
],
"pagination": {
"current_page": 1,
"rows_per_page": 100
}
}
```
### Response Body Params
| Field | Type | Description | Characters |
|------------------|--------------|---------------------------------------|---------------------------------------------|
| `data` * | object array | Protests | **[protest object](#objeto-protest)** |
| `pagination` * | object | Pagination information | **[pagination object](#objeto-pagination)** |
### protest object
| Field | Type | Description | Characters |
|----------------------------|---------|------------------------------------------------------------------------------------|--------------------------------------------------|
| `protest_key ` * | uuidv4 | Unique protest identification key in uuid v4 format | 36 |
| `request_control_key` * | uuidv4 | Unique request identification key used by the client in uuid v4 format | 36 |
| `protest_status` * | string | Protest status | **[protest_status enumerators](#enumeradores-protest_status)** |
| `bank_slip_key` * | uuidv4 | Unique bank slip identification key in uuid v4 format | 36 |
| `requester_profile_code` * | string | Unique wallet identification code | 10 |
| `protest_type` * | string | Protest type | **[protest_type enumerators](#enumeradores-protest_type)** |
| `protocol_number` | string | Protocol number | 10 |
| `protocol_date` | string | Protocol date (format "YYYY-MM-DD") | 10 |
| `notary_office` | object | Protest notary office data | **[notary_office object](#objeto-notary_office)** |
### pagination object
| Field | Type | Description | Characters |
|----------------------------|---------|------------------------------------------------------------------------------------|--------------------------------------------------------------|
| `current_page` * | integer | Current page | - |
| `rows_per_page` * | integer | Items per page | - |
### protest_type enumerators
| Enumerator | Description |
|------------------------------|--------------------------------------------------------------------------------|
| protest | Common protest |
| bankruptcy_protest | Bankruptcy protest |
### protest_status enumerators
| Enumerator | Description |
|------------------------------|--------------------------------------------------------------------------------|
| accepted | Accepted, but not yet sent to the protest notary offices |
| submitted | Sent to notary office |
| cancellation_requested | Protest suspension requested |
| cancelled | Sending cancelled, or protest suspended |
| rejected | Protest request rejected |
| at_notary_office | At protest notary office, in triduum period |
| paid_at_notary_office | Title paid at notary office |
| protested | Title protested and settled |
| removal_requested | Title already protested, with cancellation requested |
| removed | Protest cancelled |
### notary_office object
| Field | Type | Description | Characters |
|----------------------------|---------|------------------------------------------------------------------------------------|--------------------------------------------------|
| `city` * | string | Protest notary office city | - |
| `uf` * | string | Protest notary office state (UF) | 2 |
## Error Response
STATUS 4xx
Response Body: Error
```json
{
"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` |
|--------------------------|----------------------|----------------------------------------------------|-------------------------------------------------------------------------------------------------------------------------|------------------------------------------------------------------------------------------------------------------------|
| 403 | BKS000005 | Forbidden | User is not allowed to do this action | Usuário não tem autorização para fazer essa ação |
| 404 | BKS000006 | Not Found | The source account key was not found. | A chave da conta de origem não foi encontrada. |
| 400 | BKS000007 | Bad Request | It 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. |
| 400 | BKS000008 | Bad Request | The source account is closed. | A conta de origem está fechada. |
| 400 | BKS000009 | Bad Request | The source account is blocked. | A conta de origem está bloqueada. |
| 400 | BKS000012 | Bad Request | Invalid integer value for page or size query string parameters. | Valor inválido para parâmetros de página ou tamanho de página. |
| 404 | BKS000013 | Not Found | Requester profile not found | Carteira não encontrada |
---
# Protest request
URL: /en/documentation/boletos/instrucoes/protesto/pedido_de_protesto
A protest request at a notary office can be made after the due date of the bank slip, and serves to have the payer notified to pay the instrument at the notary office. If they do not do so, a public record is made in their name of the default, in addition to having their name included in credit protection agencies, such as Serasa.
:::caution Attention!
To send a protest request, it is mandatory that the payer's address is present on the bank slip. If it is not, it is possible to send an instruction to edit the bank slip. Furthermore, if a bank slip is in the protest flow, sending a new request is not permitted.
:::
## Request
ENDPOINT /account/ ACCOUNT_KEY /requester_profile/ REQUESTER_PROFILE_KEY /bank_slip/ BANK_SLIP_KEY /protest_request
METHOD POST
### Path parameters
| Field | Type | Description | Characters |
|-------------------------|--------|--------------------------------------------------------------|------------|
| `account_key` | uuidv4 | Unique account identification key, in uuid v4 format | 36 |
| `requester_profile_key` | uuidv4 | Unique wallet identification key, in uuid v4 format | 36 |
| `bank_slip_key` | uuidv4 | Unique bank slip identification key, in uuid v4 format | 36 |
Request Body
```json
{
"request_control_key": "614a451d-3b82-460e-bcc0-2caf3dde711f",
"protest_type": "protest"
}
```
### Request Body Params
| Field | Type | Description | Characters |
|----------------------------|---------|------------------------------------------------------------------------------------|------------|
| `request_control_key` * | uuidv4 | Unique request identification key used by the client in uuid v4 format | 36 |
| `protest_type` * | string | Type of protest (common or bankruptcy) | **[Enumerators protest_type](#enumerators-protest_type)** |
### Enumerators protest_type
| Enumerator | Description |
|---------------------------------------------|--------------------------------------------------------------------------|
| protest | Common protest |
| bankruptcy_protest | Bankruptcy protest |
## Response
STATUS 202
Response Body
```json
{
"occurrence_key": "2552bd64-950b-437e-a53a-a133ffea03d7",
"bank_slip_key": "960f78d4-4426-4762-98da-3ce3713ae0a5"
}
```
### Response Body Params
| Field | Type | Description | Characters |
|--------------------|--------|-----------------------------------------------------------------------------------|------------|
| `occurrence_key` * | uuidv4 | Unique occurrence (instruction) identification key in uuid v4 format | 36 |
| `bank_slip_key` * | uuidv4 | Unique bank slip identification key in uuid v4 format | 36 |
### Error Response
STATUS 4xx
Response Body: Error
```json
{
"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` |
|--------------------------|----------------------|----------------------------------------------------|-------------------------------------------------------------------------------------------------------------------------|------------------------------------------------------------------------------------------------------------------------|
| 400 | QIT000001 | Bad Request | Schema Error | Schema Inválido |
| 404 | BKS000006 | Not Found | The source account key was not found. | A chave da conta de origem não foi encontrada. |
| 400 | BKS000007 | Bad Request | It 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. |
| 400 | BKS000008 | Bad Request | The source account is closed. | A conta de origem está fechada. |
| 400 | BKS000009 | Bad Request | The source account is blocked. | A conta de origem está bloqueada. |
| 404 | BKS000013 | Not Found | Requester profile not found | Carteira não encontrada |
| 409 | BKS000014 | Conflict | Request control key already sent or duplicated sent: `` | Chave de controle da requisição já utilizada ou enviada duplicada: `` |
| 400 | BKS000019 | Bad Request | Payer address is required for protest. | Endereço do pagador é obrigatório para protesto. |
| 400 | BKS000022 | Bad Request | Requester profile is not opened. | Carteira não está aberta. |
| 404 | BKS000028 | Not Found | Notary office attended region not found for postal code: `` | Região de cartório não encontrada para o CEP: `` |
| 404 | BKS000029 | Not Found | Bank slip not found for the given key (`{bank_slip_key}`). | Boleto não encontrado para a chave fornecida (`{bank_slip_key}`). |
| 400 | BKS000032 | Bad Request | Bank slip must be in 'registered' status. | O boleto deve possuir o status 'registered'. |
| 409 | BKS000075 | Conflict | An open protest request already exists for the given 'bank_slip_key'. | Já existe um pedido de protesto em aberto para a 'bank_slip_key' fornecida. |
| 400 | BKS000080 | Bad Request | A protest request can only be sent after bank slip's business expiration date. | Um pedido de protesto só pode ser enviado após o dia útil de expiração do boleto. |
---
# Protest Removal
URL: /en/documentation/boletos/instrucoes/protesto/sustacao_de_protesto
If the dispute between the payer and drawer guarantor is resolved after the bank slip has already been protested, it is possible to send an instruction of type `protest_remove_request`, which removes the public record of default and any record, linked to this bank slip, that has tainted the payer's name.
:::caution Attention!
If the occurrence is confirmed (accepted by the notary office), the protest is removed and no further instructions are created for this bank slip, since it is already settled in CIP/Nuclea.
:::
## Request
ENDPOINT /account/ ACCOUNT_KEY /requester_profile/ REQUESTER_PROFILE_KEY /bank_slip/ BANK_SLIP_KEY /protest_remove_request
METHOD POST
### Path parameters
| Field | Type | Description | Characters |
|-------------------------|--------|--------------------------------------------------------------|------------|
| `account_key` | uuidv4 | Unique account identification key, in uuid v4 format | 36 |
| `requester_profile_key` | uuidv4 | Unique wallet identification key, in uuid v4 format | 36 |
| `bank_slip_key` | uuidv4 | Unique bank slip identification key, in uuid v4 format | 36 |
Request Body
```json
{
"request_control_key": "614a451d-3b82-460e-bcc0-2caf3dde711f"
}
```
### Request Body Params
| Field | Type | Description | Characters |
|----------------------------|---------|------------------------------------------------------------------------------------|------------|
| `request_control_key` * | uuidv4 | Unique request identification key used by the client in uuid v4 format | 36 |
## Response
STATUS 202
Response Body
```json
{
"occurrence_key": "2552bd64-950b-437e-a53a-a133ffea03d7",
"bank_slip_key": "960f78d4-4426-4762-98da-3ce3713ae0a5"
}
```
### Response Body Params
| Field | Type | Description | Characters |
|--------------------|--------|-----------------------------------------------------------------------------------|------------|
| `occurrence_key` * | uuidv4 | Unique occurrence (instruction) identification key in uuid v4 format | 36 |
| `bank_slip_key` * | uuidv4 | Unique bank slip identification key in uuid v4 format | 36 |
### Error Response
STATUS 4xx
Response Body: Error
```json
{
"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` |
|--------------------------|----------------------|----------------------------------------------------|-------------------------------------------------------------------------------------------------------------------------|------------------------------------------------------------------------------------------------------------------------|
| 400 | QIT000001 | Bad Request | Schema Error | Schema Inválido |
| 404 | BKS000006 | Not Found | The source account key was not found. | A chave da conta de origem não foi encontrada. |
| 400 | BKS000007 | Bad Request | It 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. |
| 400 | BKS000008 | Bad Request | The source account is closed. | A conta de origem está fechada. |
| 400 | BKS000009 | Bad Request | The source account is blocked. | A conta de origem está bloqueada. |
| 404 | BKS000013 | Not Found | Requester profile not found | Carteira não encontrada |
| 409 | BKS000014 | Conflict | Request control key already sent or duplicated sent: `` | Chave de controle da requisição já utilizada ou enviada duplicada: `` |
| 400 | BKS000019 | Bad Request | Payer address is required for protest. | Endereço do pagador é obrigatório para protesto. |
| 400 | BKS000022 | Bad Request | Requester profile is not opened. | Carteira não está aberta. |
| 404 | BKS000029 | Not Found | Bank slip not found for the given key (`{bank_slip_key}`). | Boleto não encontrado para a chave fornecida (`{bank_slip_key}`). |
| 400 | BKS000032 | Bad Request | Bank slip must be in 'registered' status. | O boleto deve possuir o status 'registered'. |
| 400 | BKS000076 | Bad Request | Bank slip must have an ongoing protest request. | O boleto deve ter um pedido de protesto em vigência. |
| 400 | BKS000078 | Bad Request | Bank slip's protest_status must be 'protested' to send a protest remove request. | Status de protesto (protest_status) do boleto deve ser 'protested' para enviar um pedido de remoção de protesto. |
---
# Credit Split Update
URL: /en/documentation/boletos/instrucoes/rateio_de_credito
This endpoint allows updating the **credit split** (split payment) of a previously issued bank slip. The new rules fully replace the existing ones and apply to the next settlement of the bank slip.
:::caution Attention!
- The bank slip must be in `registered` status and not yet paid.
- The sum of `beneficiary_settlement_percentage` and the percentages in each item of `split_payment_rules` must be exactly **100**.
- The payload **replaces** all existing split rules (it is not incremental).
- The split applies to all settlement flows of the bank slip (SILOC, STR, notary office and Pix QR Code), including bank slips with QR Code already issued — in this case, the rules are also automatically updated on the QR Code.
- The accounts in the split rules must be open and registered with QI Tech (QI Tech will look them up by the `document_number`, `account_number` and `account_digit` provided).
:::
## Request
ENDPOINT /v2/bank_slip/account/ ACCOUNT_KEY /requester_profile/ REQUESTER_PROFILE_KEY /bank_slip/ BANK_SLIP_KEY /split_payment
METHOD PUT
### Path parameters
| Field | Type | Description | Characters |
|-------------------------|--------|------------------------------------------------------------------------|------------|
| `account_key` | uuidv4 | Unique identification key of the account in which the bank slip was issued | 36 |
| `requester_profile_key` | uuidv4 | Unique identification key of the wallet | 36 |
| `bank_slip_key` | uuidv4 | Unique identification key of the bank slip | 36 |
Request Body
```json
{
"beneficiary_settlement_percentage": 70,
"split_payment_rules": [
{
"percentage": 20,
"document_number": "12345678901",
"account_owner_name": "John Smith",
"account_number": "1234567",
"account_digit": "8"
},
{
"percentage": 10,
"document_number": "10987654321",
"account_owner_name": "Mary Johnson",
"account_number": "7654321",
"account_digit": "0"
}
]
}
```
### Request Body Params
| Field | Type | Description | Characters |
|----------------------------------------|--------------|----------------------------------------------------------------------------------------------------------|------------|
| `beneficiary_settlement_percentage` * | float | Percentage of the settled amount allocated to the bank slip's beneficiary. Accepts values from 0 to 100. | - |
| `beneficiary_max_amount` | float | Maximum amount the beneficiary receives at settlement. When the paid amount exceeds this limit, the surplus is fully directed to the first rule of the `split_payment_rules` array. Accepts values greater than 0 and less than or equal to the bank slip amount. | - |
| `split_payment_rules` * | object array | List of split rules. Minimum 1, maximum 10 rules. | **[split_payment_rule Object](#objeto-split_payment_rule)** |
### Objeto split_payment_rule
| Field | Type | Description | Characters |
|------------------------|---------|------------------------------------------------------------------------------------------------------|------------|
| `percentage` * | float | Percentage of the settled amount allocated to this account. Accepts values from 0 to 100. Use `0` when this rule is meant exclusively to receive the surplus from `beneficiary_max_amount`. | - |
| `document_number` * | string | CPF/CNPJ of the destination account holder. | 11 or 14 |
| `account_owner_name` * | string | Name of the destination account holder. | 100 |
| `account_number` * | string | Destination account number. | 20 |
| `account_digit` * | string | Destination account check digit. | 2 |
## Use case: directing late fees and interest to a separate account
> **How can I configure the split so that interest and late fees that exceed the bank slip's face value are directed to a different account?**
This scenario is common for platforms that issue bank slips on behalf of third parties (schools, condominiums, marketplaces), where the bank slip's owner should always receive the face value and the platform receives the additional interest/late fee in case of overdue payment.
It is configured by combining `beneficiary_max_amount` with a split rule with `percentage = 0`:
```json
{
"beneficiary_settlement_percentage": 100,
"beneficiary_max_amount": 1000.00,
"split_payment_rules": [
{
"percentage": 0,
"document_number": "12345678000199",
"account_owner_name": "Billing Platform",
"account_number": "1234567",
"account_digit": "8"
}
]
}
```
**How the calculation works** considering a bank slip of R$ 1,000.00:
| Scenario | Paid amount | Beneficiary receives | Platform receives |
|---|---|---|---|
| Paid on time | R$ 1,000.00 | R$ 1,000.00 | R$ 0.00 (no settlement generated) |
| Paid late (with R$ 100.00 interest/fee) | R$ 1,100.00 | R$ 1,000.00 | R$ 100.00 |
| Partial late payment | R$ 950.00 | R$ 950.00 | R$ 0.00 |
The rule is: the beneficiary receives **at most** `beneficiary_max_amount`; any amount paid above this is fully directed to the **first** rule in `split_payment_rules`.
:::caution Attention!
- `beneficiary_max_amount` must be greater than 0 and less than or equal to the bank slip amount (`amount`).
- When any rule has `percentage = 0`, the `beneficiary_max_amount` field is required.
- Only **one** rule in `split_payment_rules` may have `percentage = 0` per bank slip (the surplus recipient).
:::
## Response
STATUS 204
Response Body
```json
{}
```
## Error Response
STATUS 4xx
Response Body: Error
```json
{
"title": "title",
"description": "description in English",
"translation": "descrição em portugues",
"code": "code",
"extra_fields": {}
}
```
| HTTP Code `status` | QI Code `code` | Title `title` | Description (eng) `description` | Description (pt-br) `translation` |
|------------------------|--------------------|---------------------------|----------------------------------------------------------------------------------------------|-----------------------------------------------------------------------------------------------------------|
| 400 | QIT000001 | Bad Request | Schema Error | Schema Inválido |
| 404 | BKS000029 | Not Found | Bank slip not found for the given key (`{bank_slip_key}`). | Boleto não encontrado para a chave fornecida (`{bank_slip_key}`). |
| 400 | BKS000032 | Bad Request | Bank slip must be in 'registered' status. | O boleto deve possuir o status 'registered'. |
| 422 | BKS000157 | Unprocessable Entity | Could not find an account matching the provided split payment account data. | Não foi possível encontrar uma conta com os dados informados na regra de split payment. |
| 400 | BKS000158 | Bad Request | The beneficiary_max_amount must be greater than 0 and not greater than the bank slip amount. | O beneficiary_max_amount deve ser maior que 0 e não pode ser maior que o valor do boleto. |
| 400 | BKS000159 | Bad Request | Split payment rules with percentage equal to 0 require beneficiary_max_amount to be set. | Regras de split payment com percentual igual a 0 exigem o campo beneficiary_max_amount preenchido. |
| 400 | BKS000160 | Bad Request | Only one split payment rule with percentage equal to 0 is allowed. | É permitido apenas uma regra de split payment com percentual igual a 0. |
---
# Amount
URL: /en/documentation/boletos/instrucoes/valor
The amount instruction allows changing the value of a bank slip, provided the bank slip has already been registered. If there is already a pending amount instruction awaiting confirmation for the bank slip in question, sending a new instruction is not allowed.
:::caution Attention!
If there is any amount instruction pending confirmation, sending a new instruction is not allowed.
:::
## Request
ENDPOINT /account/ ACCOUNT_KEY /requester_profile/ REQUESTER_PROFILE_KEY /bank_slip/ BANK_SLIP_KEY /amount
METHOD POST
### Path parameters
| Field | Type | Description | Characters |
|-------------------------|--------|----------------------------------------------------------------|------------|
| `account_key` | uuidv4 | Unique account identification key, in uuid v4 format | 36 |
| `requester_profile_key` | uuidv4 | Unique wallet identification key, in uuid v4 format | 36 |
| `bank_slip_key` | uuidv4 | Unique bank slip identification key, in uuid v4 format | 36 |
Request Body
```json
{
"request_control_key": "01234567-89ab-cdef-0123-456789abcdef",
"amount": 150.50
}
```
### Request Body Params
| Field | Type | Description | Characters |
|----------------------------|---------|------------------------------------------------------------------------------------|------------|
| `request_control_key` * | uuidv4 | Unique request identification key used by the client in uuid v4 format | 36 |
| `amount` * | number | New bank slip amount (must be different from the current amount) | - |
:::caution Attention!
The amount must be different from the current bank slip amount and must have at most 2 decimal places.
:::
## Response
STATUS 202
Response Body
```json
{
"occurrence_key": "5a745b65-9a2c-44eb-b43e-c80ef5429d94",
"bank_slip_key": "fdafdffa-cbd4-4f3c-8e3d-990428305161"
}
```
### Response Body Params
| Field | Type | Description | Characters |
|--------------------|--------|-----------------------------------------------------------------------------------|------------|
| `occurrence_key` * | uuidv4 | Unique occurrence (instruction) identification key in uuid v4 format | 36 |
| `bank_slip_key` * | uuidv4 | Unique bank slip identification key in uuid v4 format | 36 |
### Error Response
STATUS 4xx
Response Body: Error
```json
{
"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` |
|--------------------------|----------------------|----------------------------------------------------|-------------------------------------------------------------------------------------------------------------------------|------------------------------------------------------------------------------------------------------------------------|
| 400 | QIT000001 | Bad Request | Schema Error | Schema Inválido |
| 404 | BKS000006 | Not Found | The source account key was not found. | A chave da conta de origem não foi encontrada. |
| 400 | BKS000007 | Bad Request | It 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. |
| 400 | BKS000008 | Bad Request | The source account is closed. | A conta de origem está fechada. |
| 400 | BKS000009 | Bad Request | The source account is blocked. | A conta de origem está bloqueada. |
| 404 | BKS000013 | Not Found | Requester profile not found | Carteira não encontrada |
| 409 | BKS000014 | Conflict | Request control key already sent or duplicated sent: `` | Chave de controle da requisição já utilizada ou enviada duplicada: `` |
| 400 | BKS000022 | Bad Request | Requester profile is not opened. | Carteira não está aberta. |
| 404 | BKS000029 | Not Found | Bank slip not found for the given key (`{bank_slip_key}`). | Boleto não encontrado para a chave fornecida (`{bank_slip_key}`). |
| 400 | BKS000032 | Bad Request | Bank slip must be in 'registered' status. | O boleto deve possuir o status 'registered'. |
| 409 | BKS000135 | Conflict | An amount occurrence already exists for this bank slip. | Já existe uma ocorrência de valor para este boleto. |
| 400 | BKS000136 | Bad Request | Only credit card financial instrument type can have zero amount. | Apenas o tipo de instrumento financeiro cartão de crédito pode ter valor zero. |
| 400 | BKS000137 | Bad Request | Amount must be different from bank slip amount. | O valor deve ser diferente do valor do boleto. |
---
# Introduction
URL: /en/documentation/boletos/introducao
The billing wallet is the service that allows the issuance of bank slips. There are various types of wallets, and each one defines how slips will be generated, the costs, settlement fees, credited account, and various configurations that will enable the bank to perform the correct billing. During the account opening at QI Tech, a wallet within QI and a wallet at Bradesco, with QI Tech's global billing configurations, are automatically available to the client.
Moreover, if the client is interested in the registration or modification of a wallet with different configurations from the global configuration, they can request the service from our team.
## How does slip issuance work?
QI Tech's APIs allow the abstraction of the life cycle of a slip through a state machine, where we have the following statuses:
### Registration Request
- accepted: Slip issuance request has entered the registration queue;
- rejected: Slip issuance request rejected, when the registration request contains a semantic error that prevents registration.
### Registration Completed
- registered: Slip registered and available for payment.
### Payment Notification
- payment_notice: Slip payment notice, this notification is sent when the slip is paid, but financial settlement has not yet occurred.
- notary_office_payment_notice: Slip payment notice, this notification is sent when the slip is paid at a notary office, but financial settlement has not yet occurred.
### Settlement
- paid: Slip paid - settled with financial settlement.
- written_off: Slip written off without financial settlement.
---
# List settlement groups
URL: /en/documentation/boletos/liquidacao/listar_grupos_de_liquidacao
:::info Information
In our system, settlement groups are a way to reconcile transactions with settled bank slips. This process (settlement) describes the transfer of a paid bank slip amount to the account that should receive this payment. In summary, whenever QI receives information that a bank slip has been paid by another bank or, in the case of protested bank slips, by the notary office, a settlement is created for that specific bank slip. Subsequently, **settlement groups** are created, which represent batches of settlements grouped by type.
At a later moment, the payment transaction for this settlement group is made to the client's account. The **transaction_key** of this transaction is then saved for reconciliation purposes, so you can see all the bank slips that were settled in a specific transaction. For example, if you have five R$ 5.00 bank slips each, where one was paid via notary office, one was paid via QR Code PIX and the other three were paid using the typed line or barcode by another bank, five settlements will be created for these bank slips. Then, these settlements will be grouped into three settlement groups: one of R$ 15.00 with the three bank slips paid using the typed line or barcode, for which a single transaction will be made, another of R$ 5.00 for the bank slip paid via QR Code PIX and the last one also of R$ 5.00 with the bank slip paid via notary office.
:::
The settlement groups listing will return all settlement groups of the account that fit the query parameters sent in the request.
## Request
ENDPOINT /account/ ACCOUNT_KEY /bank_slip_settlement_groups
METHOD GET
### Path parameters
| Field | Type | Description | Characters |
|-------------------------|--------|--------------------------------------------------------------|------------|
| `account_key` | uuidv4 | Unique account identification key | 36 |
### Query parameters
| Field | Type | Description | Characters |
|-------------------------|--------|--------------------------------------------------------------|-------------------------|
| `bank_slip_settlement_group_key` | uuidv4 | Unique settlement group identification key | 36 |
| `transaction_key` | uuidv4 | Unique settlement group transaction identification key | 36 |
| `bank_slip_settlement_group_status` | string | Settlement group status | **[Enumerators bank_slip_settlement_group_status](#enumerators-bank_slip_settlement_group_status)** |
| `date_from` | string | Start date. Format "YYYY-MM-DD". |
| `date_to` | string | End date. Format "YYYY-MM-DD". |
| `page` | integer| Page number | - |
| `page_size` | integer| Page size | - |
## Response
STATUS 200
Response Body
```json
{
"data": [
{
"bank_slip_settlement_group_key": "5ba0b0cf-ac4a-4c91-819d-d6c46d70e3ab",
"account_key": "96015228-4905-42fc-bda6-e70e0e552b6b",
"transaction_key": "6704d927-9e0d-411d-8c44-c377c0c56637",
"amount": 1069.24,
"bank_slip_settlement_group_type": "notary_office",
"bank_slip_settlement_group_status": "settled",
"bank_slip_settlement_quantity": 1
},
{
"bank_slip_settlement_group_key": "feda6069-c0cf-4148-b881-a475737330ab",
"account_key": "96015228-4905-42fc-bda6-e70e0e552b6b",
"transaction_key": "00d557de-78ca-4871-b254-2852499660e2",
"amount": 2400.0,
"bank_slip_settlement_group_type": "siloc",
"bank_slip_settlement_group_status": "settled",
"bank_slip_settlement_quantity": 303
},
{
"bank_slip_settlement_group_key": "5493030c-ba1c-44de-9e85-5aaee0afe46d",
"account_key": "96015228-4905-42fc-bda6-e70e0e552b6b",
"transaction_key": "b42c4d0a-8060-41d7-bd00-17889cc76485",
"amount": 250.0,
"bank_slip_settlement_group_type": "siloc",
"bank_slip_settlement_group_status": "settled",
"bank_slip_settlement_quantity": 50
},
{
"bank_slip_settlement_group_key": "f33c087d-cbae-47a9-bd5a-e6a8ecc04ed2",
"account_key": "96015228-4905-42fc-bda6-e70e0e552b6b",
"transaction_key": "6ee57aea-b589-4dff-9555-200c34380154",
"amount": 4024800.0,
"bank_slip_settlement_group_type": "str",
"bank_slip_settlement_group_status": "settled",
"bank_slip_settlement_quantity": 16
},
{
"bank_slip_settlement_group_key": "27b9b2b7-549e-406e-9f41-c71e0cb08b00",
"account_key": "96015228-4905-42fc-bda6-e70e0e552b6b",
"transaction_key": "36aa7a00-6741-41d5-99e9-ce620fed5823",
"amount": 300.0,
"bank_slip_settlement_group_type": "split_payment",
"bank_slip_settlement_group_status": "settled",
"bank_slip_settlement_quantity": 1,
"settlement_date": "2026-04-23"
}
],
"pagination": {
"current_page": 1,
"rows_per_page": 100
}
}
```
### Response Body Params
| Field | Type | Description | Characters |
|------------------|--------------|---------------------------------------|---------------------------------------------|
| `data` | object array | Bank slips | **[Object bank_slip_settlement_group](#object-bank_slip_settlement_group)** |
| `pagination` | object | Pagination information | **[Object pagination](#object-pagination)** |
### Object bank_slip_settlement_group
| Field | Type | Description | Characters |
|----------------------------|---------|------------------------------------------------------------------------------------|--------------------------------------------------|
| `bank_slip_settlement_group_key ` | uuidv4 | Unique bank slip identification key in uuid v4 format | 36 |
| `account_key` | uuidv4 | Unique account identification key | 36 |
| `transaction_key` | uuidv4 | Unique settlement group transaction identification key | 36 |
| `amount` | float | Total settled amount | -
| `bank_slip_settlement_group_type` | string | Settlement group type | **[Enumerators bank_slip_settlement_group_type](#enumerators-bank_slip_settlement_group_type)** |
| `bank_slip_settlement_group_status` | string | Settlement group status | **[Enumerators bank_slip_settlement_group_status](#enumerators-bank_slip_settlement_group_status)** |
| `bank_slip_settlement_quantity` | integer | Number of settlements in the group | - |
### Object pagination
| Field | Type | Description | Characters |
|----------------------------|---------|------------------------------------------------------------------------------------|--------------------------------------------------------------|
| `current_page` | integer | Current page | - |
| `rows_per_page` | integer | Items per page | - |
### Enumerators bank_slip_settlement_group_type
| Enumerator | Description |
|------------------------------|------------------------------------------------------------------------------|
| siloc | for payment of securities (security value less than R$ 250,000) |
| qr_code | for payment of securities made via QR Code |
| str | for payment of VR securities (security value greater than R$ 250,000) |
| notary_office | for payment of securities made via notary office |
| split_payment | settlement group destined to a recipient account from the bank slip's [**credit split**](/documentation/boletos/instrucoes/rateio_de_credito) |
:::tip Bank slips with credit split
When a bank slip has a [**credit split**](/documentation/boletos/instrucoes/rateio_de_credito) configured, payment generates one settlement group per recipient:
- The group for the **bank slip's beneficiary** keeps the original settlement flow type (`siloc`, `qr_code`, `str` or `notary_office`).
- The groups for the **split recipient accounts** are created with the `split_payment` type.
Each account involved (beneficiary and recipients) can list its own settlement group by calling this endpoint with its own `account_key` — this way, recipients can reconcile exactly how much they received from each bank slip.
:::
### Enumerators bank_slip_settlement_group_status
| Enumerator | Description |
|------------------------------|------------------------------------------------------------------------------|
| pending | settlement group created but transaction not performed |
| settled | settlement group created and transaction performed |
## Error Response
STATUS 4xx
Response Body: Error
```json
{
"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` |
|--------------------------|----------------------|----------------------------------------------------|-------------------------------------------------------------------------------------------------------------------------|------------------------------------------------------------------------------------------------------------------------|
| 400 | QIT000001 | Bad Request | Schema Error | Schema Inválido |
| 404 | BKS000006 | Not Found | The source account key was not found. | A chave da conta de origem não foi encontrada. |
| 400 | BKS000007 | Bad Request | It 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. |
| 400 | BKS000008 | Bad Request | The source account is closed. | A conta de origem está fechada. |
| 400 | BKS000009 | Bad Request | The source account is blocked. | A conta de origem está bloqueada. |
| 400 | BKS000095 | Bad Request | Invalid bank slip settlement group status. | Status de grupo de liquidação de boleto inválido. |
---
# List Settlements
URL: /en/documentation/boletos/liquidacao/listar_liquidacoes
:::info Information
In our system, **settlements** describe the transfer of value from a paid bank slip to the account that should receive that payment. In summary, whenever QI receives information that a bank slip has been paid by another bank or, in the case of protested bank slips, by the notary office, a settlement is created for that specific bank slip. Subsequently, settlement groups are created to which they will always be linked, representing batches of settlements grouped by type.
At a later moment, a payment transaction is performed for this settlement group to the client's account. The **transaction_key** of this transaction is then saved for reconciliation purposes, so you can see all bank slips that were settled in a specific transaction. For example, if you have five bank slips of R$ 5.00 each, where one was paid via notary office, one was paid via PIX QR Code, and the other three were paid using the barcode or typed line by another bank, five settlements will be created for these bank slips. Then, these settlements will be grouped into three settlement groups: one of R$ 15.00 with the three bank slips paid using the barcode or typed line, for which a single transaction will be performed, another of R$ 5.00 for the bank slip paid via PIX QR Code, and the last one also of R$ 5.00 with the bank slip paid via notary office.
:::
The settlement listing will return all settlements from the settlement group sent in the request.
## Request
ENDPOINT /account/ ACCOUNT_KEY /bank_slip_settlement_group/ BANK_SLIP_SETTLEMENT_GROUP_KEY /bank_slip_settlements
METHOD GET
### Path parameters
| Field | Type | Description | Characters |
|-------------------------|--------|--------------------------------------------------------------|------------|
| `account_key` | uuidv4 | Unique account identification key | 36 |
| `bank_slip_settlement_group_key` | uuidv4 | Unique settlement group identification key |
## Response
STATUS 200
Response Body
```json
{
"data": [
{
"settlement_key": "388eac3a-4138-421c-86af-f6fe3d1a9419",
"amount": 4800.0,
"account_key": "96015228-4905-42fc-bda6-e70e0e552b6b",
"bank_slip_key": "d39e243b-8532-4006-9ffd-17607d5d1620",
"barcode": "32991981000275000002269450000000043200779790"
},
{
"settlement_key": "c3d7c62e-73fa-473f-b5a2-82e9b8a7f9bb",
"amount": 1.0,
"account_key": "96015228-4905-42fc-bda6-e70e0e552b6b",
"bank_slip_key": "3088ffdd-dec0-4fa3-8643-995d6809a2e6",
"barcode": "32999980300000001000001370000000000100828480"
}
],
"pagination": {
"current_page": 1,
"rows_per_page": 100
}
}
```
### Response Body Params
| Field | Type | Description | Characters |
|------------------|--------------|---------------------------------------|---------------------------------------------|
| `data` | object array | Bank slips | **[bank_slip_settlement object](#bank_slip_settlement-object)** |
| `pagination` | object | Pagination information | **[pagination object](#pagination-object)** |
### bank_slip_settlement object
| Field | Type | Description | Characters |
|----------------------------|---------|------------------------------------------------------------------------------------|--------------------------------------------------|
| `settlement_key ` | uuidv4 | Unique settlement identification key | 36 |
| `account_key` | uuidv4 | Unique account identification key | 36 |
| `amount` | float | Settled amount | -
| `bank_slip_key ` | uuidv4 | Unique bank slip identification key in uuid v4 format |
| `barcode` | string | Bank slip barcode |
### pagination object
| Field | Type | Description | Characters |
|----------------------------|---------|------------------------------------------------------------------------------------|--------------------------------------------------------------|
| `current_page` | integer | Current page | - |
| `rows_per_page` | integer | Items per page | - |
## Error Response
STATUS 4xx
Response Body: Error
```json
{
"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` |
|--------------------------|----------------------|----------------------------------------------------|-------------------------------------------------------------------------------------------------------------------------|------------------------------------------------------------------------------------------------------------------------|
| 400 | QIT000001 | Bad Request | Schema Error | Schema Inválido |
| 404 | BKS000006 | Not Found | The source account key was not found. | A chave da conta de origem não foi encontrada. |
| 400 | BKS000007 | Bad Request | It 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. |
| 400 | BKS000008 | Bad Request | The source account is closed. | A conta de origem está fechada. |
| 400 | BKS000009 | Bad Request | The source account is blocked. | A conta de origem está bloqueada. |
| 400 | BKS000012 | Bad Request | Invalid integer value for page or size query string parameters. | Valor inválido para parâmetros de página ou tamanho de página. |
| 404 | BKS000093 | Bad Request | Settlement group not found for the given key. | Grupo de liquidação não encontrado para a chave fornecida. |
---
# Scenario simulation
URL: /en/documentation/boletos/liquidacao/simulacao_de_cenarios_de_liquidacao
This page describes how to simulate the execution of actions performed by external agents to test the bank slip settlement flow. These simulations are useful for homologation and integration testing.
:::info Information
There is no return payload (response body) in these requests. They simulate external actions and return only the HTTP status.
:::
## 1 - Payment notice simulation
Simulates a bank slip payment notice, changing its status to `payment_notice`.
ENDPOINT /mock/bank_slip/payment_notice
METHOD POST
Request Body
```json
{
"bank_slip_key": "0d00b0e2-af11-472f-11f0-11f3330bae33",
"paid_amount": 12.0,
"payment_method": "cash",
"payment_type": "full_interbank"
}
```
### Request Body Object
| Field | Type | Description | Max. Chars. |
|----------------------------------|---------|----------------------------------------------------------------------|--------------|
| **bank_slip_key*** | string | Bank slip unique key | 36 |
| **paid_amount** | float | Payment amount. If not provided, uses the original bank slip value | - |
| **payment_method** | string | Payment method used | - |
| **payment_type** | string | Interbank payment type | - |
### payment_method Enumerators
| Enumerator | Description |
|-----------------|------------------------------|
| `cash` | Cash |
| `account_debit` | Account debit |
| `credit_card` | Credit card |
| `check` | Check |
### payment_type Enumerators
| Enumerator | Description |
|-------------------------|------------------------------|
| `full_interbank` | Full interbank payment |
| `partial_interbank` | Partial interbank payment |
:::tip Behavior
- If `paid_amount` is not provided, the original bank slip value will be used
- If `payment_type` is not provided, it will be considered as full payment (`full_interbank`)
- The simulation creates a payment notice occurrence
- The bank slip will be moved to `payment_notice` status after simulation
- **Important**: For `partial_interbank`, the bank slip status is not changed. This option is used to simulate cases of partial payment bank slips, as explained in the [introduction](/documentation/boletos/introducao)
:::
## 2 - Bank slip settlement simulation
Simulates payment and financial settlement of a bank slip, changing its status to `paid`.
ENDPOINT /mock/bank_slip/settlement
METHOD POST
Request Body
```json
{
"bank_slip_key": "0d00b0e2-af11-472f-11f0-11f3330bae33",
"paid_amount": 12.0,
"payment_method": "cash"
}
```
### Request Body Object
| Field | Type | Description | Max. Chars. |
|----------------------------------|---------|----------------------------------------------------------------------|--------------|
| **bank_slip_key*** | string | Bank slip unique key | 36 |
| **paid_amount** | float | Settlement payment amount. If not provided, uses the original bank slip value | - |
| **payment_method** | string | Payment method used | - |
### payment_method Enumerators
| Enumerator | Description |
|-----------------|------------------------------|
| `cash` | Cash |
| `account_debit` | Account debit |
| `credit_card` | Credit card |
| `check` | Check |
:::tip Behavior
- If `paid_amount` is not provided, the original bank slip value will be used
- The simulation creates a payment occurrence with code 65 (payment) by default
- The bank slip will be moved to `paid` status after simulation
:::
---
# Approve Boleto Payment
URL: /en/documentation/boletos/pagamento/aprovar_pagamento
## Request
ENDPOINT /bank_slip/payment_approval
METHOD POST
**body.json**
```json
{
"operation_key": "0e241203-8c6b-4e0a-ac42-e0d2a2fc2d37",
"feedback": True
}
```
### Body params
| Field | Type | Description | Characters |
|---|---|---|---|
| `operation_key` *| string | Key delivered when the payment was created (key parameter from the response). | uuid |
| `feedback` | string | Boolean for transfer approval or rejection: "true" or "false". | - |
## Response
STATUS 200
Response Body
```json
{
"data": {
"error_list": [],
"successful_feedback_list": [
{
"account_key": "21af482f-b8ac-48dd-8f9a-ea23429d28be",
"approval_feedback": true,
"movement_amount": 10.0,
"movement_data": {
"digitable_line": "09990001029100010009895007444201283400000001000",
"resource_account_key": "21af482f-b8ac-48dd-8f9a-ea23429d28be"
},
"movement_date": "2020-08-06",
"movement_info": null,
"movement_request_key": "c154b5bf-66ac-4b37-b365-a4c05e68785b",
"movement_status": "approved",
"movement_type": "bank_slip_payment",
"requester_key": "ba99b7f1-3db6-4a63-a386-ba2c7f31e784"
}
]
},
"event_datetime": "2020-08-06 19:23:00",
"key": "9a1eedb3-da45-418c-89e9-28459d4c51ed",
"status": "ok",
"webhook_type": "bank_slip_payment_approval"
}
```
STATUS 400
Response Body
```json
{
"data": "{\"title\": \"Bad Request\", \"description\": \"Invalid request body.\", \"translation\": \"Corpo da requisição inválido.\", \"extra_fields\": {}, \"code\": \"LEG000069\"}"
}
```
---
# Consultar linha digitável de boleto
URL: /en/documentation/boletos/pagamento/consulta_linha_digitavel
## Request
ENDPOINT /bank_slip/payment
MÉTODO GET
### Query params
| Campo | Tipo | Descrição | Caracteres |
|---|---|---|---|
| `digitable_line` *| string | Linha digitável do boleto. | 48 |
## Response
STATUS 200
Response Body
```json
{
"barcode": "31893833500000835480005050500512130021164946",
"beneficiary_bank_code": "318",
"beneficiary_document_number": "61902722000126",
"beneficiary_legal_name": "Sport Club Corinthians Paulista",
"beneficiary_person_type": "legal",
"calculated_internally": true,
"calculation_date": "2020-08-05",
"calculation_model": 1,
"digitable_line": "31890005025050051213700211649462383350000083548",
"discount_amount": "0",
"expiration_date": "2020-08-02",
"expired_as_of_payment_date": true,
"expired_as_of_today": true,
"factual_expiration_date": "2020-08-03",
"fine_amount": "16.71",
"guarantor_document": null,
"guarantor_name": null,
"interest_amount": "0",
"max_payment_date": "2020-08-08",
"nominal_amount": "835.48",
"payer_document_number": "15676407883",
"payer_legal_name": "LUCIANO RENATO MOREIRA",
"payer_person_type": "natural",
"payment_date": "2020-08-05",
"rebate_amount": "0.0",
"total_amount": "852.19",
"valid_payment_amount": true,
"valid_payment_calculation": true,
"valid_payment_time_frame": true
}
```
STATUS 400
Response Body
```json
{
"code": "BLP000142",
"title": "Bad Request",
"description": "This digitable line is out of minimum or maximum length.",
"translation": "Esta linha digitável está fora do comprimento mínimo ou máximo.",
"extra_fields": {}
}
```
STATUS 400
Response Body
```json
{
"code": "BLP000141",
"title": "Bad Request",
"http_status": 400,
"description": "The given digitable_line must have only numbers.",
"translation": "A linha digit\u00e1vel fornecida deve conter somente n\u00fameros.",
"extra_fields": {}
}
```
STATUS 400
Response Body
```json
{
"code": "BLP000012",
"title": "Bad Request",
"http_status": 400,
"description": "Missing mandatory parameter: digitable_line",
"translation": "Par\u00e2metro obrigat\u00f3rio ausente: digitable_line",
"extra_fields": {}
}
```
STATUS 422
Response Body
```json
{
"code": "IPP000014",
"title": "Invalid Barcode",
"http_status": 422,
"description": "Invalid barcode",
"translation": "O Código de barras é inválido",
"extra_fields": {}
}
```
STATUS 422
Response Body
```json
{
"code": "IPP000022",
"title": "Unprocessable Entity",
"http_status": 422,
"description": "Covenant not accepted",
"translation": "Convênio não aceito",
"extra_fields": {}
}
```
STATUS 422
Response Body
```json
{
"code": "IPP000023",
"title": "Unprocessable Entity",
"http_status": 422,
"description": "Max retries exceeded, while trying to complete payment.",
"translation": "Número máximo de tentativas excedido, ao tentar concluir o pagamento.",
"extra_fields": {}
}
```
STATUS 422
Response Body
```json
{
"code": "IPP000017",
"title": "Unprocessable Entity",
"http_status": 422,
"description": "The tax collection is overdue",
"translation": "A arrecadação está vencida",
"extra_fields": {}
}
```
### Response Params
| Campo | Tipo | Descrição | Caracteres |
| --- | -- |--------------------------------------------------------------------| --- |
|`barcode`| string | Código de barras do boleto. | 44 |
|`beneficiary_bank_code`| string | Código de bancário do banco que registrou o boleto. | 3 |
|`beneficiary_document_number`| string | CPF/CNPJ do beneficiário (recebedor) do boleto. Também é o CPF/CNPJ do titular da conta onde o boleto foi registrado. | 14 |
|`beneficiary_legal_name`| string | Nome do beneficiário (recebedor) do boleto. Também é o nome do titular da conta onde o boleto foi registrado. | - |
|`beneficiary_person_type`| enum | Natureza Jurídica do beneficiário (recebedor) do boleto. Também é a natureza jurídica do titular da conta onde o boleto foi registrado. | [Enumerador person_type](#enumeradores-person_type) |
|`calculated_internally`| boolean | Indica se o calculo foi realizado pela QI Tech ou não. | - |
|`calculation_date`| string | Data de referência do calculo de multa e juros do boleto. | 10 |
|`calculation_model`| int | Modelo de calculo utilizado no calculo de multa e juros do boleto. Este campo é informado pelo banco que registrou o boleto. | [Códigos calculation_model](#codigos-calculation_model) |
|`digitable_line`| uuid | Linha digitável do boleto. | 47 |
|`discount_amount`| string | Valor do desconto de pontualidade do boleto. | - |
|`expiration_date`| string | Data de vencimento do boleto. | 10 |
|`expired_as_of_payment_date`| boolean | Informa se o boleto estará vencido na data de agendamento do pagamento (Campo pode ser ignorado). | 10 |
|`expired_as_of_today`| string | Informa se o boleto esta vencido na data de hoje. | 10 |
|`factual_expiration_date`| string | Data de vencimento do boleto em dia útil. Por exemplo, se o boleto tiver vencimento em `2023-12-16` este campo terá o valor informado `2023-12-18`. | 10 |
|`fine_amount`| string | Valor calculado de multa do boleto. | - |
|`guarantor_document`| string | CPF/CNPJ do sacador avalista do boleto. | 14 |
|`guarantor_name`| string | Nome do sacador avalista do boleto. | - |
|`interest_amount`| string | Valor de juros calculado após o vencimento do boleto. | - |
|`max_payment_date`| string | Data limite de pagamento do boleto. | 10 |
|`nominal_amount`| string | Valor original do boleto. | - |
|`payer_document_number`| string | CPF/CNPJ do pagador do boleto. | 14 |
|`payer_legal_name`| string | Nome do pagador do boleto. | 14 |
|`payer_person_type`| enum | Natureza jurídcia do pagador do boleto. | [Enumerador person_type](#enumeradores-person_type) |
|`payment_date`| string | Data do pagamento do boleto. | 10 |
|`rebate_amount`| string | Valor de abatimento no boleto. | - |
|`total_amount`| string | Valor do total do boleto (com juros, multa, abatimento e desconto). | - |
|`valid_payment_amount`| boolean | Informa se o valor de pagamento é válido (será sempre `true`). | - |
|`valid_payment_calculation` | boolean | Informa se o valor calculado pelo banco registrador do boleto é válido (quando o `calculation_model` for `2` ou `3`). | - |
|`valid_payment_time_frame` | boolean | Informa se a data de agendamento do pagamento é menor que a data máxima para pagamento do boleto. | - |
### Enumeradores person_type
| Enumerador | Descrição |
| --- | -- |
| `natural` | Pessoa física |
| `legal` | Pessoa jurídica |
### Códigos calculation_model
| Enumerador | Descrição |
| --- | -- |
| 1 | Instituição pagadora do boleto calcula os valores de juros e multa do boleto (Caso seja informado no boleto consultado, o campo `calculated_internally` será retornado como `true`). |
| 2 | Instituição que registrou o boleto calcula os valores de juros e multa. Após a data de vencimento do boleto, a instituição atualiza os valores diariamente na base centralizada de boleto. |
| 3 | Instituição que registrou o boleto calcula o valor do boleto. A instituição atualiza o valor do boleto diariamente na base centralizada de boleto. |
## Ambiente de Sandbox
### Boletos de convênio/tributos
Os boletos de convênio/tributos são emitidos por órgãos governamentais, como prefeituras, governos estaduais ou federais, para a cobrança de impostos, taxas, contribuições sociais, multas, e outros valores devidos ao governo.
Em nosso ambiente de sandbox, disponibilizamos linhas digitáveis mockadas para a simulação de pagamentos bem-sucedidos e testes de cenários de erro.
### Cenários de sucesso
| Linha digitável |
|---|
| 828300000007411100972013905080001546763201900028 |
| 838000000009235700481007241345219112001474229880 |
| 848000000006308600802021201071261517689002201070 |
| 858200000015000000643025703477209504800448091020 |
### Cenários de erro
| Linha digitável | Código de erro |
|---|---|
| 858500000037350000643217212883260006147448091022 | IPP000014 |
### Boleto bancário
Um boleto bancário, também conhecido como boleto ou bloqueto, é um documento muito usado no Brasil para pagar por produtos ou serviços. Com um boleto, a pessoa ou empresa que o emite pode receber o dinheiro que está sendo cobrado do pagador.
Em nosso ambiente de sandbox, disponibilizamos linhas digitáveis mockadas para a simulação de pagamentos bem-sucedidos.
### Cenários de sucesso
| Linha digitável |
|---|
| 32990001039000210987502864982109595090000063958 |
| 32990001039000000006836762871105695090000010000 |
| 32990001031000699960099000000200195070000025527 |
| 32990001039000000000103194237800895060001000000 |
| 32990001031000699960095000000208497790000030990 |
---
# Realizar pagamento de boleto
URL: /en/documentation/boletos/pagamento/realizar_pagamento
### Request
ENDPOINT /bank_slip/payment
METHOD POST
Request Body
```json
{
"digitable_line": "42297034020000453753620034706323183380000005000",
"resource_account_key": "21af482f-b8ac-48dd-8f9a-ea23429d28be",
"payment_date": "2020-08-05"
}
```
#### Body params
| Field | Type | Description | Characters |
|---|---|---|---|
| `digitable_line` *| string | Boleto digitable line. | 10 |
| `resource_account_key` *| string | Key of the account to be used. | 10 |
| `payment_date` | date | Date for payment execution. If not sent, the date will be today. | 10 |
:::info Information
To view accepted payment covenants, [click here](https://storage.googleapis.com/live-doc-api/public_samples/active_covenants.xlsx).
:::
### Response
STATUS 200
Response Body: Payment through a free account
```json
{
"data": {
"digitable_line": "09990001029100010009895007444201283400000001000",
"resource_account_key": "21af482f-b8ac-48dd-8f9a-ea23429d28be"
},
"event_datetime": "2020-08-06 19:22:06",
"key": "e7719f95-a31d-4171-ae83-2d8b3d419dc2",
"status": "success",
"webhook_type": "bank_slip_payment"
}
```
STATUS 200
Response Body: Payment through an escrow account
```json
{
"data": {
"digitable_line": "09990001029100010009895007444201283400000001000",
"resource_account_key": "21af482f-b8ac-48dd-8f9a-ea23429d28be"
},
"event_datetime": "2020-08-06 19:22:06",
"key": "e7719f95-a31d-4171-ae83-2d8b3d419dc2",
"status": "waiting_approval",
"webhook_type": "bank_slip_payment"
}
```
STATUS 400
Response Body
```json
{
"code": "LEG000069"
"title": "Bad Request",
"description": "Invalid request body.",
"translation": "Corpo da requisição inválido.",
"extra_fields": {}
}
```
STATUS 423 - Payment outside operating hours
Response Body
```json
{
"code": "BLP000024",
"title": "Locked",
"http_status": 423,
"description": "Operation window closed. System available from {OPENING_TIME} to {CLOSING_TIME}",
"translation": "Opera\u00e7\u00e3o encerrada. Sistema dispon\u00edvel de {OPENING_TIME} a {CLOSING_TIME}",
"extra_fields": {
"next_available_datetime": "2023-08-13T18:00:00.000Z"
}
}
```
STATUS 400
Response Body
```json
{
"code": "IPP000015",
"title": "Bad Request",
"http_status": 400,
"description": "Invalid amount",
"translation": "O valor inserido é inválido",
"extra_fields": {}
}
```
STATUS 422
Response Body
```json
{
"code": "IPP000013",
"title": "Incompatible Payment Value",
"http_status": 422,
"description": "The input amount does not match tax collection value",
"translation": "O valor do pagamento é diferente da arrecadação",
"extra_fields": {}
}
```
STATUS 422
Response Body
```json
{
"code": "IPP000012",
"title": "Tax Collection Already Paid",
"http_status": 422,
"description": "This tax collection is already paid",
"translation": "A arrecadação já foi paga",
"extra_fields": {}
}
```
STATUS 422
Response Body
```json
{
"code": "IPP000017",
"title": "Unprocessable Entity",
"http_status": 422,
"description": "The tax collection is overdue",
"translation": "A arrecadação está vencida",
"extra_fields": {}
}
```
STATUS 422
Response Body
```json
{
"code": "IPP000023",
"title": "Unprocessable Entity",
"http_status": 422,
"description": "Max retries exceeded, while trying to complete payment.",
"translation": "Número máximo de tentativas excedido, ao tentar concluir o pagamento.",
"extra_fields": {}
}
```
STATUS 422
Response Body
```json
{
"code": "IPP000024",
"title": "Unprocessable Entity",
"http_status": 422,
"description": "Error while processing payment output. Try again.",
"translation": "Erro ao processar a saída do pagamento. Tente novamente.",
"extra_fields": {}
}
```
STATUS 422
Response Body
```json
{
"code": "IPP000025",
"title": "Unprocessable Entity",
"http_status": 422,
"description": "Outside of covenant payment hours.",
"translation": "Fora do horário de pagamento do convênio.",
"extra_fields": {}
}
```
## Sandbox Environment
### Covenant/Tax Boletos
Covenant/tax boletos are issued by government agencies, such as city halls, state or federal governments, to collect taxes, fees, social contributions, fines, and other amounts owed to the government.
In our sandbox environment, we provide mocked digitable lines for simulating successful payments and error scenario testing.
#### Success Scenarios
| Digitable line |
|---|
| 828300000007411100972013905080001546763201900028 |
| 838000000009235700481007241345219112001474229880 |
| 848000000006308600802021201071261517689002201070 |
| 858200000015000000643025703477209504800448091020 |
#### Error Scenarios
| Digitable line | Error code |
|---|---|
| 858900000034050002701002700011434710592720230733 | IPP000015 |
| 858400000000750002701007700011434710592720230733 | IPP000013 |
| 858800000040450004322322120716192390688090088931 | IPP000012 |
| 858900000000350004322326120716192390688090083760 | IPP000014 |
### Bank Slip (Boleto bancário)
A bank slip (boleto bancário), also known as boleto or bloqueto, is a document widely used in Brazil to pay for products or services. With a boleto, the issuer or company can receive the amount owed from the payer.
In our sandbox environment, we provide mocked digitable lines for simulating successful payments.
#### Success Scenarios
| Digitable line |
|---|
| 32990001039000210987502864982109595090000063958 |
| 32990001039000000006836762871105695090000010000 |
| 32990001031000699960099000000200195070000025527 |
| 32990001039000000000103194237800895060001000000 |
| 32990001031000699960095000000208497790000030990 |
---
# Bank Slip Settlement Account Redirection
URL: /en/documentation/boletos/redirecionamento_de_conta_de_liquidacao
This endpoint will be used to change the settlement account of a bank slip registered in QI Tech.
:::caution Attention!
- The bank slip remains registered in the original account, which must remain open while there are bank slips registered in it;
- Webhooks will continue to be sent to the integrating partner of the original account;
:::
## Request
ENDPOINT /account/ ACCOUNT_KEY /requester_profile/ REQUESTER_PROFILE_KEY /bank_slip/ BANK_SLIP_KEY /settlement_account
METHOD PATCH
### Path parameters
| Field | Type | Description | Characters |
|-------------------------|--------|----------------------------------------------------------------|------------|
| `account_key` | uuidv4 | Unique identification key of the account in which the bank slip was issued | 36 |
| `requester_profile_key` | uuidv4 | Unique identification key of the wallet| 36 |
| `bank_slip_key` | uuidv4 | Unique identification key of the bank slip | 36 |
Request Body
```json
{
"settlement_account_key": "614a451d-3b82-460e-bcc0-2caf3dde711f"
}
```
### Request Body Params
| Field | Type | Description | Characters |
|------------------------------|---------|--------------------------------------------------------|------------|
| `settlement_account_key` * | uuidv4 | Unique key that identifies the new settlement account | 36 |
## Response
STATUS 204
Response Body
```json
{}
```
### Error Response
STATUS 4xx
Response Body: Error
```json
{
"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` |
|--------------------------|----------------------|--------------------|----------------------------------------------------------------------------------------------------|-----------------------------------------------------------------------------------------------------------|
| 400 | QIT000001 | Bad Request | Schema Error | Schema Inválido |
| 404 | BKS000025 | Not Found | The source account key was not found. | A chave da conta de origem não foi encontrada. |
| 400 | BKS000007 | Bad Request | It 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. |
| 400 | BKS000008 | Bad Request | The source account is closed. | A conta de origem está fechada. |
| 400 | BKS000009 | Bad Request | The source account is blocked. | A conta de origem está bloqueada. |
| 404 | BKS000013 | Not Found | Requester profile not found | Carteira não encontrada |
| 400 | BKS000022 | Bad Request | Requester profile is not opened. | Carteira não está aberta. |
| 404 | BKS000029 | Not Found | Bank slip not found for the given key (`{bank_slip_key}`). | Boleto não encontrado para a chave fornecida (`{bank_slip_key}`). | |
| 400 | BKS000032 | Bad Request | Bank slip must be in 'registered' status. | O boleto deve possuir o status 'registered'. |
| 400 | BKS000052 | Bad Request | Invalid account status. | Status da conta inválido. |
---
# List discharge files
URL: /en/documentation/boletos/retorno/listar_arquivos_retorno
:::info
The files provided in the URLs returned by this endpoint follow the QI Tech Return File Layout standard with 400 positions.
Download the manual here: [Layout de Cobrança - QI Tech versão 2.1.](https://storage.googleapis.com/live-doc-api/public_samples/Layout%20de%20Cobran%C3%A7a%20-%20QI%20Tech%20v2.1.pdf)
:::
Discharge files are used for reconciliation. Each Transaction Record line (Type 1) refers to an instruction (whether for issuance, extension, discount, etc.) that was confirmed or rejected by CIP/Nuclea on the previous day.
## Request
ENDPOINT /account/ ACCOUNT_KEY /requester_profile/ REQUESTER_PROFILE_KEY /discharge_files
METHOD GET
### Path parameters
| Field | Type | Description | Characters |
|-------------------------|--------|--------------------------------------------------------------|------------|
| `account_key` | uuidv4 | Unique account identification key | 36 |
| `requester_profile_key` | uuidv4 | Unique wallet identification key, in uuid v4 format | 36 |
### Query parameters
| Field | Type | Description | Characters |
|-------------------------|--------|--------------------------------------------------------------|-------------------------|
| `discharge_file_key` | uuidv4 | Unique discharge file identification key, in uuid v4 format | 36 |
| `page` | integer| Page number | - |
| `page_size` | integer| Page size | - |
| `from_date` | string| Start date (format "YYYY-MM-DD") | 10 |
| `to_date` | string| End date (format "YYYY-MM-DD") | 10 |
## Response
STATUS 200
Response Body
```json
{
"data": [
{
"discharge_file_key": "f1a8fe59-29cd-49e5-8d18-55194869b45c",
"discharge_file_name": "CB15102401.RET",
"discharge_file_url": "https://storage.googleapis.com/local-bank-slip-api/2024/61a746ca-05bf-429d-99c3-3fba0f9fbea7/329-20-7336-3073959/discharge/CB15102401.RET",
"reference_date": "2024-10-15"
}
],
"pagination": {
"current_page": 1,
"rows_per_page": 100
}
}
```
### Response Body Params
| Field | Type | Description | Characters |
|------------------|--------------|---------------------------------------|---------------------------------------------|
| `data` | object array | Discharge files | **[discharge_file object](#discharge_file-object)** |
| `pagination` | object | Pagination information | **[pagination object](#pagination-object)** |
### discharge_file object
| Field | Type | Description | Characters |
|----------------------------|---------|------------------------------------------------------------------------------------|--------------------------------------------------|
| `discharge_file_key ` | uuidv4 | Unique discharge file identification key in uuid v4 format | 36 |
| `discharge_file_name` | string | Discharge file name | - |
| `discharge_file_url` | string | Discharge file URL | - |
| `reference_date` | string | Discharge file reference date in YYYY-MM-DD format | 10 |
### pagination object
| Field | Type | Description | Characters |
|----------------------------|---------|------------------------------------------------------------------------------------|--------------------------------------------------------------|
| `current_page` | integer | Current page | - |
| `rows_per_page` | integer | Items per page | - |
## Error Response
STATUS 4xx
Response Body: Error
```json
{
"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` |
|--------------------------|----------------------|----------------------------------------------------|-------------------------------------------------------------------------------------------------------------------------|------------------------------------------------------------------------------------------------------------------------|
| 400 | QIT000001 | Bad Request | Schema Error | Schema Inválido |
| 403 | BKS000005 | Forbidden | User is not allowed to do this action | Usuário não tem autorização para fazer essa ação |
| 404 | BKS000006 | Not Found | The source account key was not found. | A chave da conta de origem não foi encontrada. |
| 400 | BKS000007 | Bad Request | It 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. |
| 400 | BKS000012 | Bad Request | Invalid integer value for page or size query string parameters. | Valor inválido para parâmetros de página ou tamanho de página. |
| 404 | BKS000013 | Not Found | Requester profile not found | Carteira não encontrada |
| 400 | BKS000052 | Bad Request | Invalid account status. | Status da conta inválido. |
---
# BolePix Issuance
URL: /en/documentation/boletos/v1/emissao/emissao_de_um_bolepix
:::caution Attention
Before registering a bolePix, it is necessary that an active Random Pix Key exists in the account where the bank slip will be registered.
:::
At QI Tech, it is possible to issue a bank slip linked to a Pix QR Code.
This way, the payer can make the payment of the bank slip through the typable line of the registered bank slip or through reading the Pix QR Code linked to this bank slip.
In cases where the payer makes the payment through reading the Pix QR Code, the financial settlement of the payment will be instantaneous, with bank returns as well as webhooks regarding the settlement of this bank slip being generated in the same way as a common bank slip.
## Request
ENDPOINT /multibank_instruction
METHOD POST
Request Body
```json
{
"occurrences": [{
"amount": 1000,
"automatic_bankruptcy_protest": false,
"bank_teller_instructions": "Não pagar após vencimento.",
"beneficiary_account_key": "8a35e639-8420-4f6c-9647-c2515e5381ef",
"beneficiary_key": "3c866e34-23fe-46c2-a8b0-e39ca4348923",
"days_to_bankruptcy_protest": 0,
"document_number": "123456/01",
"expiration": "2020-06-01",
"fine_percentage": "3",
"interest_daily_value": "0.34",
"occurrence_type": "registration",
"payer_address": "Rua Carlos Sampaio, 123",
"payer_document": "41184562067",
"payer_name": "João Ninguem",
"payer_person_type": "natural",
"payer_postal_code_root": "15800",
"payer_postal_code_suffix": "020",
"printing_policy": "no_printing",
"registration_institution_enumerator": "qi_scd",
"requester_profile": "09",
"requester_profile_code": "329-09-0001-0000002",
"pix_key": "1684629c-d52a-4941-92f5-410907316129"
}]
}
```
### Query params
| Field | Type | Description | Characters |
|---|---|-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|------------|
| `use_multi_process` | boolean | Indicates whether the processing of registration occurrences will be sent for queue processing or if they will be processed sequentially. If this parameter is set to `true`, it is mandatory to send our bank number `our_number` in the registration occurrence payload. | - |
### Body params
| Field | Type | Description | Characters |
|---|---|---|---|
| `occurrences` * | array of objects | List of occurrences to be processed. | **[Occurrences object](#occurrences-object)** |
### Occurrences object
| Field | Type | Description | Characters |
|--------------------------------------|------------------|---------------------------------------------------------------------------------------------------------------------------------------------------------|-------------------------------------------------|
| `amount` * | double | Bank slip amount. | - |
| `automatic_bankruptcy_protest` | boolean | Automatic protest configuration. | - |
| `bank_teller_instructions` | string | Teller instructions (Bank slip message/observations). | - |
| `beneficiary_account_key` | string | Beneficiary account key. | - |
| `beneficiary_key` | string | Beneficiary key. | - |
| `days_to_bankruptcy_protest` | int | Number of days for automatic bankruptcy protest submission. | - |
| `document_number` | string | Document number. | - |
| `expiration` * | string | Due date. | - |
| `fine_percentage` | string | Fine percentage | - |
| `interest_daily_value` | string | Daily interest value in reais | - |
| `occurrence_type` * | string | Occurrence type. | - |
| `payer_address` | string | Payer address. | - |
| `payer_document` * | string | Payer document (CPF or CNPJ). | - |
| `payer_name` * | string | Payer name. | - |
| `payer_person_type` * | string | Payer person type. | - |
| `payer_postal_code_root` | string | The first five digits of the ZIP code. | - |
| `payer_postal_code_suffix` | string | The last three digits of the ZIP code. | - |
| `printing_policy` | string | Bank slip printing policy | - |
| `registration_institution_enumerator` * | string | Will always be `qi_scd`. | `qi_scd` |
| `requester_profile` * | string | Portfolio number. | 02 |
| `requester_profile_code` * | string | Portfolio code composed as follows: "329-portfolio-agency-7_digit_account". NOTE: QI Tech's default collection portfolio is number "09". | - |
| `notification` | object | Portfolio number. | **[Notification object](#notification-object)** |
| `discounts` | object | List of objects with discount information. | **[Discounts object](#discounts-object)** |
| `guarantor_name` | string | Guarantor name. | - |
| `guarantor_document_root` | string | Guarantor CNPJ base. | - |
| `guarantor_document_subsidiary` | string | Parent or subsidiary CNPJ information. | - |
| `guarantor_document_digit` | string | CNPJ verification digit. | - |
| `pix_key` * | string | Pix key where the Pix QR Code linked to the bolePix will be registered. | 100 |
:::info "***pix_key***" Field
The "***pix_key***" can be a **CPF**, **CNPJ**, **Email**, **Phone** or a **Random Key** (UUID), following these formats:
**CPF:** Integer number with 11 digits.
**CNPJ:** Integer number with 14 digits.
**Email:** Text containing at least one "@".
**Phone:** Text containing the following values: "+55" + "Phone area code" + "Integer phone number with minimum 8 and maximum 9 digits". Ex: "+5511987654321".
**Random Key:** UUID.
:::
### Notification object
| Field | Type | Description | Characters |
|---|---|---|---|
| `document_number` * | string | Document number of the user who will receive the notification. | - |
| `email` * | string | Email of the user who will receive the notification. | - |
| `name` * | string | Name of the user who will receive the notification.| - |
| `phone` * | object | Object containing phone information of the user who will receive the notification. | **[Phone object](#phone-object)** |
| `send_2_way` * | boolean | Send duplicate copy issuance notifications. | true/false |
| `send_after_due_date` * | boolean | Send notifications after the bank slip due date. | true/false |
| `send_before_due_date` * | boolean | Send notifications before the bank slip due date. | true/false |
| `send_on_protest` * | boolean | Send protest notifications. | true/false|
### Phone object
| Field | Description | Example | Max Characters |
| --- | --- | --- | --- |
|`country_code` | string | Phone DDI code (https://ddi.guiamais.com.br/) | 3 |
| `area_code` | string | Phone DDD code (https://ddd.guiamais.com.br/) | 2 |
| `number` | string |Phone number (numbers only) | 10 |
### Discounts object
| Field | Description | Example | Max Characters |
| --- | --- | --- | --- |
|`discount_value` | float | Discount value.| 3 |
| `discount_number` | int32 | Order in which the discount should be applied. | 2 |
| `discount_limit_date` | date | Discount limit date. | 10 |
## Response
STATUS 200
Response Body
```json
{
"bank_slips": [
{
"amount": "649.73",
"bank_slip_key": "4bc636d0-1e41-4ce6-801c-475814bf4dcf",
"bank_slip_status": "accepted",
"barcode": "32991916500000649730001090000699935200347340",
"beneficiary_account_key": "1c977186-9167-4ef1-b27d-08483429f74c",
"beneficiary_key": "f01d4877-b1cc-4f4a-a8f9-952c2cef9ca8",
"digitable_line": "32990001039000069993552003473403191650000064973",
"expiration": "2022-11-10",
"nfe_key": null,
"nfe_url": null,
"our_number": 6999352,
"participant_control_number": null,
"payer_postal_code": "38050000",
"protest_status": "not_protested",
"qr_code": {
"pix_key": "9de04466-0b02-4263-9c28-9cdc0fb638bb",
"qr_code_key": "881979cb-1c15-4dea-a05e-316caae22f5e",
"qr_code_url": "00020126970014br.gov.bcb.pix2575qrcode-h.sandbox.qitech.app/bacen/cobv/881979cb-1c15-4dea-a05e-316caae22f5e5204000053039865802BR5925LOTEAMENTO RESIDENCIAL PO6014PORTO NACIONAL61087750000062070503***630414B8"
}
}
],
"file_info": {
"beneficiary_code": null,
"beneficiary_name": null,
"file_sequence_id": null,
"file_type_identifier": null,
"file_type_literal": null,
"service_code": null,
"service_literal": null,
"wrote_at": null
},
"occurrence_stats": {
"bank_slip_edit": 0,
"bankruptcy_protest_request": 0,
"cancel_rebate": 0,
"extension": 0,
"notary_office_entry": 0,
"notary_office_exit": 0,
"notary_office_payment": 0,
"notification": 0,
"payment": 0,
"payment_notice": 0,
"payment_write_off": 0,
"protest_cancel_and_write_off_request": 0,
"protest_cancel_request": 0,
"protest_remove_request": 0,
"protest_request": 0,
"rebate": 0,
"registration": 1,
"write_off": 0
},
"semantic_errors": []
}
```
STATUS 400
Response Body
```json
{
"data": "{\"title\": \"Bad Request\", \"description\": \"Invalid request body.\", \"translation\": \"Corpo da requisição inválido.\", \"extra_fields\": {}, \"code\": \"LEG000069\"}"
}
```
### Response Params
| Field | Type | Description | Characters |
| --- | -- |--------------------------------------------------------------------| --- |
|`bank_slips` | list | List with information of registered bank slips if the `use_multi_process` parameter is set to `false`. | [Bank Slip Object](#bank_slip-object) |
| `file_info` | list | File information. | [File Info Object](#file-info-object) |
| `occurrence_stats` | object | File information. | [File Info Object](#file-info-object) |
| `semantic_errors` | list | List of errors in processing each bank slip. Will be returned if there is any processing error and if the `use_multi_process` parameter is set to `false`. | [Semantic Error Object](#semantic-error-object) |
### Bank_slip object
| Field | Type | Description | Characters |
| --- | -- |--------------------------------------------------------------------| --- |
|`amount` | float | Bank slip amount. | - |
|`bank_slip_key` | uuid | Unique identification key of the bank slip at QI Tech. | 36 |
|`bank_slip_status` | enum | Unique identification key of the bank slip at QI Tech. | [Bank_slip_status Enumerators](#bank_slip_status-enumerators) |
|`barcode` | string | Bank slip barcode. | 44 |
|`beneficiary_account_key` | uuid | Unique identification key of the account where the bank slip was registered. | 36 |
|`beneficiary_key` | uuid | Unique identification key of the account holder where the bank slip was registered. | 36 |
|`digitable_line` | uuid | Bank slip typable line. | 47 |
|`expiration` | string | Bank slip due date. | 10 |
|`nfe_key` | string | Unique identification key of the electronic invoice. | - |
|`nfe_url` | string | Electronic invoice URL. | - |
|`our_number` | int | Our bank number. It is a sequential identification number of this bank slip in relation to the account (collection portfolio) where it was registered. Its value can be provided in the bank slip registration request. If not provided, QI Tech will generate a value for this field (being an incremental value, ex: 1st bank slip registered in the account will have an `our_number` value of 1, the 16th bank slip registered in the account will have an `our_number` value of 16). | -
|`participant_control_number` | string | Participant control number. | 10 |
|`payer_postal_code` | string | Bank slip payer ZIP code. | 8 |
|`protest_status` | string | Bank slip protest status, if protest has been requested. | [Protest_status Enumerators](#protest_status-enumerators) |
|`qr_code` | object | Object with information of the Pix QR Code linked to the bank slip. | [Qr_code object](#qr_code-object) |
### Qr_code object
| Field | Type | Description | Characters |
| --- | -- |--------------------------------------------------------------------| --- |
|`pix_key` | string | Pix key where the Pix QR Code linked to the bank slip was registered. | 100 |
|`qr_code_key` | uuid | Unique identification key of the Pix QR Code linked to the bank slip. | 36 |
|`qr_code_url` | uuid | Copy and Paste Pix URL of the Pix QR Code linked to the bank slip. | 36 |
### Bank_slip_status enumerators
| Enumerator | Description |
| --- | -- |
| `accepted` | Bank slip accepted for processing |
| `registered` | Bank slip registration completed in the bank slip registration chamber |
| `paid` | Bank slip payment amount was credited to the beneficiary's account |
| `written_off` | Bank slip written off (bank slip is no longer payable) |
| `rejected` | Bank slip registration rejected by the bank slip registration chamber |
| `payment_notice` | Notice that bank slip payment was processed at the paying bank (but settlement to the beneficiary's account has not yet occurred) |
| `notary_office_payment_notice` | Notice that payment of a protested bank slip was processed at the paying bank (but the notary office has not yet transferred the payment and settlement to the beneficiary's account has not yet occurred) |
### Protest_status enumerators
| Enumerator | Description |
| --- | -- |
| `not_protested` | Bank slip has no protest request. |
| `protest_requested` | Bank slip with protest request being processed by QI Tech. |
| `notary_office_entry` | Bank slip protest request was accepted by the notary office. |
| `protest_cancel_requested` | Protest cancellation request being processed by QI Tech. |
| `notary_office_exit` | Bank slip protest was withdrawn from the notary office. |
| `protested` | Protest was confirmed by the notary office and the bank slip is protested. |
| `paid_at_notary_office` | Notary office identified the bank slip protest payment and is processing the payment transfer to QI Tech. |
| `judicially_suspended` | Judicially suspended protest. |
| `protest_remove_requested` | Protest removal request was accepted by the notary office. |
---
# Boleto issuance via CNAB
URL: /en/documentation/boletos/v1/emissao/emissao_via_cnab
## Request
ENDPOINT /multibank_cnab
METHOD POST
:::caution Attention!
The call must be authenticated following the standard described in the AUTHENTICATION AND SECURITY section. With the following considerations:
**1 -** The ContentMD5 variable value must be the MD5 Hash of the binary file to be sent;
**2 -** The file binary must be sent in the request body as FormData using the string "file" as key and the file to be sent as value. (This content is not encrypted);
:::
:::info
The file transmitted in this call must follow the QI Tech Collection File Layout standard with 400 positions.
Link to download the manual: [Collection Layout - QI Tech version 2.1.](https://storage.googleapis.com/live-doc-api/public_samples/Layout%20de%20Cobran%C3%A7a%20-%20QI%20Tech%20v2.1.pdf)
:::
STATUS 200
Response Body
```json
{
"cnab_file": {
"cnab_key": "52ff2ea1-a17f-4476-8eb8-617ddd16a81e",
"company_code": null,
"created_at": "2020-04-17T21:41:09",
"downloads": [
{
"cnab_file_id": 0,
"created_at": "2020-04-17T21:41:09",
"document_number": "41184562067",
"name": "João Ninguem",
"person_key": "string"
}
],
"file_size": "None",
"filename": "1905200807.REM",
"line_length": 400,
"remitter_key": "329",
"requester_profile_code": "329-01-0001-0000002",
"type": "requester_remittance",
"url": "https://google.com",
"version": "1"
},
"file_info": {
"bank_warning_number": 244,
"beneficiary_code": "1234567",
"beneficiary_name": "QI SOCIEDADE DE CREDITO DIRETO",
"credit_date": 190520,
"file_type_identifier": 1,
"file_type_literal": "REMESSA",
"service_code": 1,
"service_literal": "COBRANCA",
"wrote_at": 180520
},
"occurrence_list": [
{
"amount": "1399.67",
"asset_type": "invoice",
"automatic_bankruptcy_protest": true,
"automatic_protest": false,
"automatic_write_off": false,
"bank_teller_instructions": "SOMAR OS ENCARGOS PERTINENTES",
"beneficiary_account_branch": 1,
"beneficiary_account_number": 1273,
"beneficiary_account_number_digit": "1",
"cnab_file_occurrence_order": 1,
"days_before_fine": 0,
"days_before_interest": 0,
"days_to_bankruptcy_protest": 10,
"days_to_protest": 0,
"days_to_write_off": 0,
"discount_limit_date": "2020-05-14 00:00:00",
"discount_value": "0.00",
"document_number": "0198874/01",
"expiration": "2020-06-18 00:00:00",
"fine_percentage": "2.00",
"guarantor_address": "AVENIDA DAS AMERICAS, 1321",
"guarantor_city": "FAZENDA RIO GRANDE",
"guarantor_document_digit": 86,
"guarantor_document_root": 80550452,
"guarantor_document_subsidiary": 1,
"guarantor_name": "PLASTILIT PRODUTOS PLASTICOS DO PARANA S.A.",
"guarantor_postal_code_root": 83820,
"guarantor_postal_code_suffix": 23,
"guarantor_state": "PR",
"interest_daily_value": "4.67",
"messages": [
{"SOMAR OS ENCARGOS PERTINENTES"}
]
"occurrence_cnab_line": 2,
"occurrence_feedback": null,
"occurrence_sequence": "0",
"occurrence_type": "registration",
"origin_type": "remittance",
"our_number": 109001065,
"our_number_digit": "1",
"participant_control_number": "700000004167313",
"payer_address": "AVENIDA 7 DE SETEMBRO, N. 1043",
"payer_document": "77900454000143",
"payer_name": "ARLINDO RAGAZZON ME",
"payer_person_type": "legal",
"payer_postal_code_root": 89874,
"payer_postal_code_suffix": 0,
"printing_policy": "no_printing",
"rebate_amount": "0.00",
"registration_institution_enumerator": "bradesco",
"registration_institution_febraban_code": "237",
"requester_key": "64d3bafa-2205-43ca-b6a7-2827aefe3ebc",
"requester_profile": 19,
"requester_profile_code": "237-19-0001-0001273",
"requester_registration_date": "2020-05-18 00:00:00",
}
]
}
```
STATUS 400
Response Body
```json
{
"data": "{\"title\": \"Bad Request\", \"description\": \"Invalid request body.\", \"translation\": \"Corpo da requisição inválido.\", \"extra_fields\": {}, \"code\": \"LEG000069\"}"
}
```
---
# Bank slip issuance via JSON
URL: /en/documentation/boletos/v1/emissao/emissao_via_json
## Request
ENDPOINT /multibank_instruction
METHOD POST
Request Body
```json
{
"occurrences": [
{
"amount": 1000,
"automatic_bankruptcy_protest": false,
"bank_teller_instructions": "Não pagar após vencimento.",
"beneficiary_account_key": "8a35e639-8420-4f6c-9647-c2515e5381ef",
"beneficiary_key": "3c866e34-23fe-46c2-a8b0-e39ca4348923",
"days_to_bankruptcy_protest": 0,
"document_number": "123456/01",
"expiration": "2020-06-01",
"fine_percentage": "3",
"interest_daily_value": "0.34",
"occurrence_type": "registration",
"payer_address": "Rua Carlos Sampaio, 123",
"payer_document": "41184562067",
"payer_name": "João Ninguem",
"payer_person_type": "natural",
"payer_postal_code_root": "15800",
"payer_postal_code_suffix": "020",
"printing_policy": "no_printing",
"registration_institution_enumerator": "qi_scd",
"requester_profile": "09",
"requester_profile_code": "329-09-0001-0000002"
}
]
}
```
:::danger Warning!
If the payer's address information for the bank slip is not provided, it will not be possible to protest the bank slip in case of non-payment.
:::
### Query params
| Field | Type | Description | Characters |
|---|---|-------------------------------------------------------------------------------------------|---------------|
| `use_multi_process` | boolean | Indicates whether the registration occurrence processing will be sent to queue processing or will be processed sequentially. If this parameter is set to `true`, it is mandatory to send our banking number `our_number` in the registration occurrence payload. | - |
### Body params
| Field | Type | Description | Characters |
|---|---|---|---|
| `occurrences` * | array of objects | List of occurrences to be processed. | **[Occurrences object](#occurrences-object)** |
### Occurrences object
| Field | Type | Description | Characters |
|--------------------------------------|------------------|---------------------------------------------------------------------------------------------------------------------------------------------------------|-------------------------------------------------|
| `amount` * | double | Bank slip amount. | - |
| `automatic_bankruptcy_protest` | boolean | Automatic protest configuration. | - |
| `bank_teller_instructions` | string | Teller instructions (Bank slip message/observations). | - |
| `beneficiary_account_key` | string | Beneficiary account key. | - |
| `beneficiary_key` | string | Beneficiary key. | - |
| `days_to_bankruptcy_protest` | int | Number of days for automatic bankruptcy protest submission. | - |
| `document_number` | string | Document number. | - |
| `expiration` * | string | Due date. | - |
| `fine_percentage` | string | Fine percentage | - |
| `interest_daily_value` | string | Daily interest value in reais | - |
| `occurrence_type` * | string | Occurrence type. | - |
| `payer_address` | string | Payer address. | - |
| `payer_document` * | string | Payer document (CPF or CNPJ). | - |
| `payer_name` * | string | Payer name. | - |
| `payer_person_type` * | string | Payer person type. | - |
| `payer_postal_code_root` | string | The first five digits of the postal code. | - |
| `payer_postal_code_suffix` | string | The last three digits of the postal code. | - |
| `printing_policy` | string | Bank slip printing policy | - |
| `registration_institution_enumerator` * | string | Will always be `qi_scd`. | `qi_scd` |
| `requester_profile` * | string | Portfolio number. | 02 |
| `requester_profile_code` * | string | Portfolio code composed as follows: "329-portfolio-agency-account_with_7_digits". NOTE: QI Tech's default collection portfolio is number "09". | - |
| `notification` | object | Portfolio number. | **[Notification object](#notification-object)** |
| `discounts` | object | List of objects with discount information. | **[Discounts object](#discounts-object)** |
| `guarantor_name` | string | Guarantor name. | - |
| `guarantor_document_root` | string | Guarantor CNPJ base. | - |
| `guarantor_document_subsidiary` | string | Head office or branch CNPJ information. | - |
| `guarantor_document_digit` | string | CNPJ check digit. | - |
### Notification object
| Field | Type | Description | Characters |
|---|---|---|---|
| `document_number` * | string | Document number of the user who will receive the notification. | - |
| `email` * | string | Email of the user who will receive the notification. | - |
| `name` * | string | Name of the user who will receive the notification.| - |
| `phone` * | object | Object containing phone information of the user who will receive the notification. | **[Phone object](#phone-object)** |
| `send_2_way` * | boolean | Send second copy issuance notifications. | true/false |
| `send_after_due_date` * | boolean | Send notifications after bank slip due date. | true/false |
| `send_before_due_date` * | boolean | Send notifications before bank slip due date. | true/false |
| `send_on_protest` * | boolean | Send protest notifications. | true/false|
### Phone object
| Field | Type | Description | Characters |
| --- | --- | --- | --- |
|`country_code` | string | Phone country code (https://ddi.guiamais.com.br/) | 3 |
| `area_code` | string | Phone area code (https://ddd.guiamais.com.br/) | 2 |
| `number` | string |Phone number (numbers only) | 10 |
### Discounts object
| Field | Type | Description | Characters |
| --- | --- |-----------------------------------------|------------|
|`discount_value` | float | Discount value. | - |
| `discount_number` | int | Order in which the discount should be applied. | - |
| `discount_limit_date` | date | Discount application limit date. | 10 |
## Response
STATUS 200
Response Body
```json
{
"bank_slips": [
{
"amount": "649.73",
"bank_slip_key": "4bc636d0-1e41-4ce6-801c-475814bf4dcf",
"bank_slip_status": "accepted",
"barcode": "32991916500000649730001090000699935200347340",
"beneficiary_account_key": "1c977186-9167-4ef1-b27d-08483429f74c",
"beneficiary_key": "f01d4877-b1cc-4f4a-a8f9-952c2cef9ca8",
"digitable_line": "32990001039000069993552003473403191650000064973",
"expiration": "2022-11-10",
"nfe_key": null,
"nfe_url": null,
"our_number": 6999352,
"participant_control_number": null,
"payer_postal_code": "38050000",
"protest_status": "not_protested"
}
],
"file_info": {
"beneficiary_code": null,
"beneficiary_name": null,
"file_sequence_id": null,
"file_type_identifier": null,
"file_type_literal": null,
"service_code": null,
"service_literal": null,
"wrote_at": null
},
"occurrence_stats": {
"bank_slip_edit": 0,
"bankruptcy_protest_request": 0,
"cancel_rebate": 0,
"extension": 0,
"notary_office_entry": 0,
"notary_office_exit": 0,
"notary_office_payment": 0,
"notification": 0,
"payment": 0,
"payment_notice": 0,
"payment_write_off": 0,
"protest_cancel_and_write_off_request": 0,
"protest_cancel_request": 0,
"protest_remove_request": 0,
"protest_request": 0,
"rebate": 0,
"registration": 1,
"write_off": 0
},
"semantic_errors": []
}
```
STATUS 400
Response Body
```json
{
"data": "{\"title\": \"Bad Request\", \"description\": \"Invalid request body.\", \"translation\": \"Corpo da requisição inválido.\", \"extra_fields\": {}, \"code\": \"LEG000069\"}",
"title": "Bad Request",
"description": "Invalid request body.",
"translation": "Corpo da requisição inválido.",
"extra_fields": {},
"code": "LEG000069"
}
```
### Response Params
| Field | Type | Description | Characters |
| --- | -- |--------------------------------------------------------------------| --- |
|`bank_slips` | list | List with information of registered bank slips when the `use_multi_process` parameter is set to `false`. | [Bank Slip Object](#bank_slip-object) |
| `file_info` | list | File information. | [File Info Object](#file-info-object) |
| `occurrence_stats` | object | File information. | [File Info Object](#file-info-object) |
| `semantic_errors` | list | List of errors in processing each bank slip. Will be returned if there are any processing errors and when the `use_multi_process` parameter is set to `false`. | [Semantic Error Object](#semantic-error-object) |
### bank_slip object
| Field | Type | Description | Characters |
| --- | -- |--------------------------------------------------------------------| --- |
|`amount` | float | Bank slip amount. | - |
|`bank_slip_key` | uuid | Unique identification key for the bank slip at QI Tech. | 36 |
|`bank_slip_status` | enum | Unique identification key for the bank slip at QI Tech. | [bank_slip_status enumerators](#bank_slip_status-enumerators) |
|`barcode` | string | Bank slip barcode. | 44 |
|`beneficiary_account_key` | uuid | Unique identification key for the account where the bank slip was registered. | 36 |
|`beneficiary_key` | uuid | Unique identification key for the account holder where the bank slip was registered. | 36 |
|`digitable_line` | uuid | Bank slip digitable line. | 47 |
|`expiration` | string | Bank slip due date. | 10 |
|`nfe_key` | string | Electronic invoice unique identification key. | - |
|`nfe_url` | string | Electronic invoice URL. | - |
|`our_number` | int | Our banking number. It is a sequential identification number for this bank slip in relation to the account (collection portfolio) where it was registered. Its value can be provided in the bank slip registration request. If not provided, QI Tech will generate a value for this field (being an incremental value, e.g.: 1st bank slip registered in the account will have `our_number` value of 1, the 16th bank slip registered in the account will have `our_number` value of 16). | -
|`participant_control_number` | string | Participant control number. | 10 |
|`payer_postal_code` | string | Bank slip payer postal code. | 8 |
|`protest_status` | string | Bank slip protest status, if protest was requested. | [protest_status enumerators](#protest_status-enumerators) |
### bank_slip_status enumerators
| Enumerator | Description |
| --- | -- |
| `accepted` | Bank slip accepted for processing |
| `registered` | Bank slip registration was completed in the bank slip registration chamber |
| `paid` | Bank slip payment amount was credited to the beneficiary's account |
| `written_off` | Bank slip written off (bank slip is no longer payable) |
| `rejected` | Bank slip registration rejected by the bank slip registration chamber |
| `payment_notice` | Notice that bank slip payment was processed at the paying bank (but settlement to the beneficiary's account has not yet occurred) |
| `notary_office_payment_notice` | Notice that payment of a protested bank slip was processed at the paying bank (but the notary office has not yet transferred the payment and settlement to the beneficiary's account has not yet occurred) |
### protest_status enumerators
| Enumerator | Description |
| --- | -- |
| `not_protested` | Bank slip has no protest request. |
| `protest_requested` | Bank slip with protest request being processed by QI Tech. |
| `notary_office_entry` | Bank slip protest request was accepted by the notary office. |
| `protest_cancel_requested` | Protest cancellation request being processed by QI Tech. |
| `notary_office_exit` | Bank slip protest was removed from the notary office. |
| `protested` | Protest was confirmed by the notary office and the bank slip is protested. |
| `paid_at_notary_office` | Notary office identified the protest payment and is processing the payment transfer to QI Tech. |
| `judicially_suspended` | Judicially suspended protest. |
| `protest_remove_requested` | Protest removal request was accepted by the notary office. |
---
# Send bank slip instruction
URL: /en/documentation/boletos/v1/enviar_instrucao_de_boleto
## Send Bank Slip Instruction
To request a bank slip instruction, simply make the issuance request with the "occurrence_type" as follows:
| Value | Description |
|---|---|
| `registration` | Register a new bank slip. |
| `bank_slip_edit` | Edit payer information of an existing bank slip. |
| `extension` | Extension of the due date of an existing bank slip. |
| `write_off` | Write-off without financial impact of a bank slip. |
| `rebate` | Payment rebate. |
| `cancel_rebate` | Cancel payment rebate. |
| `bank_slip_edit` | Edit an existing bank slip (Discount, Address, Fine/interest). |
| `protest_request` | Protest bank slip. |
| `bankruptcy_protest_request` | Bankruptcy Protest. |
| `protest_remove_request` | Cancel Protest. |
| `protest_cancel_request` | Suspend Protest without Write-off. |
| `protest_cancel_and_write_off_request` | Suspend Protest with Write-off. |
**Request examples**
### Extension
To request this instruction, the bank slip must be registered and must be payable.
Request Body
```json
{
"occurrences": [
{
"occurrence_type": "extension",
"requester_profile_code": "329-01-0001-0000001",
"our_number": 1000000,
"expiration": "2022-06-15"
}
]
}
```
### Write-off
To request this instruction, the bank slip must be registered.
Request Body
```json
{
"occurrences": [
{
"occurrence_type": "write_off",
"requester_profile_code": "329-01-0001-0000001",
"our_number": 1000000
}
]
}
```
### Rebate
To request this instruction, the bank slip cannot be overdue.
Request Body
```json
{
"occurrences": [
{
"occurrence_type": "rebate",
"our_number": 1000000,
"rebate_amount": 10,
"requester_profile_code": "329-01-0001-0000001"
}
]
}
```
### Cancel rebate
To request this instruction, the bank slip must have an active rebate and cannot be overdue.
Request Body
```json
{
"occurrences": [
{
"our_number": 1000000008,
"occurrence_type": "cancel_rebate",
"requester_profile_code": "329-01-0001-0000001",
"bank_slip_key": "ce9b6834-4c6c-423a-a337-b9815a462ae5"
}
]
}
```
### Discount
To request this instruction, the bank slip cannot be overdue/written off.
Request Body
```json
{
"occurrences": [
{
"our_number": 1000000008,
"occurrence_type": "bank_slip_edit",
"requester_profile_code": "329-01-0001-0000001",
"registration_institution_enumerator": "qi_scd",
"discounts": [
{
"discount_number": 1,
"discount_limit_date": "2022-06-14",
"discount_value": 10
}
]
}
]
}
```
### Add/Edit Address
To request this instruction, the bank slip must be registered and be payable.
Request Body
```json
{
"occurrences": [
{
"our_number": 1000000008,
"occurrence_type": "bank_slip_edit",
"requester_profile_code": "329-01-0001-0000001",
"payer_address": "Rua dos Alfeneiros, 4, Little Whinging - Surrey, City, SP",
"payer_postal_code_root": "17057",
"payer_postal_code_suffix": "770"
}
]
}
```
### Edit Fine/Interest
To request this instruction, the bank slip must be registered and be payable.
Request Body
```json
{
"occurrences": [
{
"our_number": 1000000008,
"occurrence_type": "bank_slip_edit",
"requester_profile_code": "329-01-0001-0000001",
"fine_percentage": 1,
"interest_daily_value": 0.33
}
]
}
```
### Protest
To request this instruction, the bank slip must be overdue and must have the payer's address data.
Request Body
```json
{
"occurrences": [
{
"our_number": 1000000002,
"occurrence_type": "protest_request",
"requester_profile_code": "329-01-0001-0000001"
}
]
}
```
### Bankruptcy Protest
To request this instruction, the bank slip must be overdue and must have the payer's address data.
Request Body
```json
{
"occurrences": [
{
"our_number": 1000000002,
"occurrence_type": "bankruptcy_protest_request",
"requester_profile_code": "329-01-0001-0000001"
}
]
}
```
### Cancel protest
To request this instruction, the bank slip must be protested.
Request Body
```json
{
"occurrences": [
{
"our_number": 1000000002,
"occurrence_type": "protest_remove_request",
"requester_profile_code": "329-01-0001-0000001"
}
]
}
```
### Cancel automatic protest
To request this instruction, the bank slip must be registered with this option active.
Request Body
```json
{
"occurrences": [
{
"our_number": 1000000002,
"occurrence_type": "bank_slip_edit",
"requester_profile_code": "329-01-0001-0000001",
"automatic_bankruptcy_protest": false,
"automatic_protest": false
}
]
}
```
### Suspend protest without write-off
To request this instruction, the bank slip must be protested.
Request Body
```json
{
"occurrences": [
{
"our_number": 1000000002,
"occurrence_type": "protest_cancel_request",
"requester_profile_code": "329-01-0001-0000001"
}
]
}
```
### Cancel automatic protest
To request this instruction, the bank slip must be protested.
Request Body
```json
{
"occurrences": [
{
"our_number": 1000000002,
"occurrence_type": "protest_cancel_and_write_off_request",
"requester_profile_code": "329-01-0001-0000001"
}
]
}
```
## Response example
The response varies for each type of instruction, usually resulting in changes to the occurrence_stats fields, in the key of each instruction.
In the semantic_errors field, a list is returned with objects of each occurrence with their respective errors (example below).
Request Body
```json
{
"file_info": {
"beneficiary_code": null,
"beneficiary_name": null,
"file_sequence_id": null,
"file_type_identifier": null,
"file_type_literal": null,
"service_code": null,
"service_literal": null,
"wrote_at": null
},
"occurrence_stats": {
"bank_slip_edit": 0,
"bankruptcy_protest_request": 0,
"cancel_rebate": 0,
"extension": 0,
"notary_office_entry": 0,
"notary_office_exit": 0,
"notary_office_payment": 0,
"notification": 0,
"payment": 0,
"payment_notice": 0,
"payment_write_off": 0,
"protest_cancel_and_write_off_request": 0,
"protest_cancel_request": 0,
"protest_remove_request": 0,
"protest_request": 0,
"rebate": 0,
"registration": 0,
"write_off": 1
},
"semantic_errors": [
{
"0": {
"errors": [
{
"created_at": "2019-03-12T12:59:32",
"reason_code": "CEP Inválido",
"translation_en_us": "Invalid Postal Code",
"translation_pt_br": "CEP Inválido"
}
],
"our_number": 1000000000,
"participant_control_number": null
}
}
]
}
```
---
# Introduction
URL: /en/documentation/boletos/v1/introducao
Payment slip portfolio is a service that allows the issuance of bank payment slips. There are several types of portfolios and each one defines how their payment slips will be generated, the costs, settlement rate, account to be credited, and various configurations that will allow the bank to make the correct charge. During account opening at QI Tech, a portfolio within QI and a portfolio at Bradesco are automatically made available to the client, with QI Tech's global payment collection configurations.
Additionally, if the client is interested in registering or modifying a portfolio with configurations different from the global configuration, they can request the service from our team.
## How does payment slip issuance work?
QI Tech's APIs allow abstraction of a payment slip's lifecycle through a state machine, where we have the following statuses:
## Registration request
- accepted: Payment slip issuance request entered the registration queue;
- rejected: Payment slip issuance request rejected, when the payment slip registration request contains a semantic error that prevents registration.
## Registration completed
registered: Payment slip registered and available for payment.
## Payment notification
- payment_notice: Payment slip payment notice, this notification is sent when the payment slip is paid, but financial settlement does not yet exist.
- notary_office_payment_notice: Payment slip payment notice, this notification is sent when the payment slip is paid at a notary office, but financial settlement does not yet exist.
## Settlement
- paid: Payment slip paid - cleared with financial settlement.
- written_off: Payment slip cleared without financial settlement.
---
# Bank Slip Webhooks
URL: /en/documentation/boletos/webhooks/boleto
:::danger Warning!
QI Tech webhooks should not be mapped in a restrictive way.
Additional fields may be included in the webhook payloads returned in our APIs.
:::
:::info Webhook Resending
You can query and resend webhooks following the detailed instructions in the documentation: [Webhook Resending](/documentation/notificacoes/reenvio_de_notificacoes).
:::
## Introduction
Throughout the bank slip lifecycle within our system, webhooks will be sent with the following bank slip status (`bank_slip_status`):
| Enumerator | Translation | Description |
|-------------------------------|--------------------------------|------------------------------------------------------------------------------------------------|
| registered | registered | Bank slip registered and available for payment |
| rejected | rejected | Bank slip issuance request rejected due to validation errors |
| payment_notice | payment notice | Bank slip payment notice (bank slip paid but payment not yet settled) |
| notary_office_payment_notice | notary office payment notice | Notary office bank slip payment notice (bank slip paid but payment not yet settled) |
| paid | paid | Bank slip paid and financially settled |
| written_off | written off | Bank slip written off (can no longer be paid) and without financial settlement |
| payment_blocked | payment blocked | Payment blocked due to protest flow |
And webhooks are sent whenever occurrences of the following types are confirmed (`occurrence_type`):
| Enumerator | Translation | Description |
|-------------------------------|--------------------------------|------------------------------------------------------------------------------|
| registration | registration | Bank slip registration |
| rebate | rebate | Rebate of part of the title base value |
| cancel_rebate | rebate cancellation | Cancellation of existing rebate |
| extension | extension | Extension of title expiration date |
| write_off | write off | Bank slip write off |
| protest_write_off | protest write off | Bank slip write off due to notary office protest |
| payment_write_off | payment write off | Bank slip write off due to payment |
| discount | discount | Discount changes |
| fine | fine | Fine changes |
| interest | interest | Interest changes |
| protest_request | protest request | Notary office protest request |
| bankruptcy_protest_request | bankruptcy protest request | Notary office bankruptcy protest request |
| notary_office_entry | notary office entry | Title entry into notary office occurrence |
| protest_cancel_request | protest request withdrawal | Current protest request withdrawal |
| protest_remove_request | protest suspension | Title protest suspension |
| notary_office_exit | notary office exit | Title exit from notary office occurrence |
| payment_notice | payment notice | Bank slip payment notice (bank slip paid but payment not yet settled) |
| notary_office_payment_notice | notary office payment notice | Notary office bank slip payment notice (bank slip paid but payment not yet settled) |
| payment | payment | Notification that the bank slip was paid and written off |
:::info Information
The timeout for our webhook response is 10 seconds.
:::
## Examples
----
### Registration
Webhook Body: accepted occurrence
```json
{
"webhook_type": "baas.bank_slip.occurrence",
"webhook_datetime": "2024-08-13T21:35:55.679Z",
"data": {
"bank_slip_key": "11b13b2c-4204-41b3-8596-2ee7ecbde38c",
"bank_slip_status": "registered",
"occurrence_key": "9077cc0b-5bbd-4432-888e-6bf6384c250a",
"occurrence_type": "registration",
"occurrence_status": "confirmed"
}
}
```
Webhook Body: rejected occurrence
```json
{
"webhook_type": "baas.bank_slip.occurrence",
"webhook_datetime": "2024-08-13T21:35:55.679Z",
"data": {
"bank_slip_key": "ae783ed7-b892-4e48-8480-b045e3b492f5",
"bank_slip_status": "rejected",
"occurrence_key": "db04719d-4370-4f3f-82b7-d72d3db2f39e",
"occurrence_type": "registration",
"occurrence_status": "rejected"
}
}
```
### Rebate/rebate cancellation
Webhook Body: rebate
```json
{
"webhook_type": "baas.bank_slip.occurrence",
"webhook_datetime": "2024-08-13T21:35:55.679Z",
"data": {
"bank_slip_key": "11b13b2c-4204-41b3-8596-2ee7ecbde38c",
"bank_slip_status": "registered",
"occurrence_key": "db04719d-4370-4f3f-82b7-d72d3db2f39e",
"occurrence_type": "rebate",
"occurrence_status": "confirmed"
}
}
```
Webhook Body: rebate cancellation
```json
{
"webhook_type": "baas.bank_slip.occurrence",
"webhook_datetime": "2024-08-13T21:35:55.679Z",
"data": {
"bank_slip_key": "11b13b2c-4204-41b3-8596-2ee7ecbde38c",
"bank_slip_status": "registered",
"occurrence_key": "db04719d-4370-4f3f-82b7-d72d3db2f39e",
"occurrence_type": "cancel_rebate",
"occurrence_status": "confirmed"
}
}
```
### Extension
Webhook Body
```json
{
"webhook_type": "baas.bank_slip.occurrence",
"webhook_datetime": "2024-08-13T21:35:55.679Z",
"data": {
"bank_slip_key": "11b13b2c-4204-41b3-8596-2ee7ecbde38c",
"bank_slip_status": "registered",
"occurrence_key": "db04719d-4370-4f3f-82b7-d72d3db2f39e",
"occurrence_type": "extension",
"occurrence_status": "confirmed"
}
}
```
### Discount
Webhook Body
```json
{
"webhook_type": "baas.bank_slip.occurrence",
"webhook_datetime": "2024-08-13T21:35:55.679Z",
"data": {
"bank_slip_key": "a8df1c2e-77ff-49ea-9e7a-8fd536a6e357",
"bank_slip_status": "registered",
"occurrence_key": "db04719d-4370-4f3f-82b7-d72d3db2f39e",
"occurrence_type": "discount",
"occurrence_status": "confirmed"
}
}
```
### Interest
Webhook Body
```json
{
"webhook_type": "baas.bank_slip.occurrence",
"webhook_datetime": "2024-08-13T21:35:55.679Z",
"data": {
"bank_slip_key": "69f3f345-07c5-4c80-a8dd-51054afdad01",
"bank_slip_status": "registered",
"occurrence_key": "8550e47a-7554-455c-bdd8-cf0c048a277c",
"occurrence_type": "interest",
"occurrence_status": "confirmed"
}
}
```
### Fine
Webhook Body
```json
{
"webhook_type": "baas.bank_slip.occurrence",
"webhook_datetime": "2024-08-13T21:35:55.679Z",
"data": {
"bank_slip_key": "97e6edab-b793-4eb6-a1a7-0a27e1d5c73e",
"bank_slip_status": "registered",
"occurrence_key": "47b06bdb-c006-47a7-81f2-7aac7fff823b",
"occurrence_type": "fine",
"occurrence_status": "confirmed"
}
}
```
### Write Off
The `occurrence_reason` field is optional and is sent when the bank provides the reason for the write-off. It contains the reason code and name provided by the financial institution.
Webhook Body: without reason
```json
{
"webhook_type": "baas.bank_slip.occurrence",
"webhook_datetime": "2024-08-13T21:35:55.679Z",
"data": {
"bank_slip_key": "45c21054-57fd-4d28-8d5a-0cdc5cb29670",
"bank_slip_status": "written_off",
"occurrence_key": "0b92bd47-fae5-46c0-8c40-e5aebc9ecd28",
"occurrence_type": "write_off",
"occurrence_status": "confirmed"
}
}
```
Webhook Body: with reason
```json
{
"webhook_type": "baas.bank_slip.occurrence",
"webhook_datetime": "2026-05-04T21:12:07.877Z",
"data": {
"bank_slip_key": "25add0b0-cb2d-4be4-8f22-4305a4dd9793",
"bank_slip_status": "written_off",
"occurrence_key": "ca71f446-be05-47cc-b470-234e4806344c",
"occurrence_type": "write_off",
"occurrence_status": "confirmed",
"occurrence_reason": {
"bank_reason_code": "16",
"bank_reason_name": "Título Baixado pelo Banco por decurso de Prazo"
}
}
}
```
### Protest Write Off
Webhook Body
```json
{
"webhook_type": "baas.bank_slip.occurrence",
"webhook_datetime": "2024-10-25T18:05:01.395Z",
"data": {
"bank_slip_key": "7182639f-dea5-46c6-99c6-af0d94d772cb",
"bank_slip_status": "written_off",
"occurrence_key": "93380917-beee-4f3e-af01-6c24e140d53d",
"occurrence_type": "protest_write_off",
"occurrence_status": "confirmed"
}
}
```
### Payment Write Off
Webhook Body
```json
{
"webhook_type": "baas.bank_slip.occurrence",
"webhook_datetime": "2024-10-18T18:02:15.152Z",
"data": {
"bank_slip_key": "40d6a1bc-cfed-4444-a901-e02ecc169ce5",
"bank_slip_status": "written_off",
"occurrence_key": "78221daa-945f-485b-b39c-97ef0e251afe",
"occurrence_type": "payment_write_off",
"occurrence_status": "confirmed"
}
}
```
### Protest Request
Webhook Body
```json
{
"webhook_type": "baas.bank_slip.occurrence",
"webhook_datetime": "2024-10-16T20:54:13.013Z",
"data": {
"bank_slip_key": "f03c5fec-b31c-402a-b832-80da8a493653",
"bank_slip_status": "payment_blocked",
"occurrence_key": "304958f6-cdf2-4fb1-b8f3-5482030bf0eb",
"occurrence_type": "protest_request",
"occurrence_status": "confirmed"
}
}
```
### Bankruptcy Protest Request
Webhook Body
```json
{
"webhook_type": "baas.bank_slip.occurrence",
"webhook_datetime": "2024-10-16T20:54:13.013Z",
"data": {
"bank_slip_key": "21aeefb4-4fa1-4e32-b2bb-32a7486128f0",
"bank_slip_status": "payment_blocked",
"occurrence_key": "11a7e9e8-4667-471b-bc3f-2f65f77e22e9",
"occurrence_type": "bankruptcy_protest_request",
"occurrence_status": "confirmed"
}
}
```
### Notary Office Entry
Webhook Body
```json
{
"webhook_type": "baas.bank_slip.occurrence",
"webhook_datetime": "2024-10-17T18:00:48.341Z",
"data": {
"bank_slip_key": "5bc4c1d4-d51b-4b0b-b308-81850d04e523",
"bank_slip_status": "payment_blocked",
"occurrence_key": "159e6e3f-fce5-4362-829e-1595fc14d66c",
"occurrence_type": "notary_office_entry",
"occurrence_status": "confirmed"
}
}
```
### Protest Cancellation
Webhook Body
```json
{
"webhook_type": "baas.bank_slip.occurrence",
"webhook_datetime": "2024-10-23T18:00:52.374Z",
"data": {
"bank_slip_key": "96d2a896-f2da-484c-8d40-20fabbde15ee",
"bank_slip_status": "registered",
"occurrence_key": "2505fedf-0061-478b-b45e-8420b755ebbb",
"occurrence_type": "protest_cancel_request",
"occurrence_status": "confirmed"
}
}
```
### Protest Suspension
Webhook Body
```json
{
"webhook_type": "baas.bank_slip.occurrence",
"webhook_datetime": "2024-10-30T18:01:00.452Z",
"data": {
"bank_slip_key": "878d462e-be4e-40bd-b797-b831fef87f48",
"bank_slip_status": "written_off",
"occurrence_key": "cb08785d-0a4d-41f4-a64c-bafe730b175b",
"occurrence_type": "protest_remove_request",
"occurrence_status": "confirmed"
}
}
```
### Notary Office Exit
Webhook Body
```json
{
"webhook_type": "baas.bank_slip.occurrence",
"webhook_datetime": "2024-11-01T18:01:01.949Z",
"data": {
"bank_slip_key": "79d07a3d-3953-4195-a2e2-bbbf10635f27",
"bank_slip_status": "registered",
"occurrence_key": "c703b04c-7334-40fe-bf8d-b43bd991dbab",
"occurrence_type": "notary_office_exit",
"occurrence_status": "confirmed"
}
}
```
### Payment Notice
First webhook: bank slip was paid, but not yet settled
Webhook Body
```json
{
"webhook_type": "baas.bank_slip.payment_notice",
"webhook_datetime": "2024-08-13T21:35:55.679Z",
"data": {
"bank_slip_key": "db04719d-4370-4f3f-82b7-d72d3db2f39e",
"bank_slip_status": "payment_notice",
"occurrence_key": "d0341ad7-aa87-4dad-929b-38c8c9218f23",
"occurrence_type": "payment_notice",
"occurrence_status": "confirmed"
}
}
```
### Notary Office Payment Notice
First webhook: bank slip was paid at notary office, but not yet settled
Webhook Body
```json
{
"webhook_type": "baas.bank_slip.notary_office_payment_notice",
"webhook_datetime": "2024-10-16T18:00:43.621Z",
"data": {
"bank_slip_key": "05f2b81b-b241-4e72-9b2c-7312257a0284",
"bank_slip_status": "notary_office_payment_notice",
"occurrence_key": "3ecab7b1-c991-4d91-8d71-08a34eec1d7d",
"occurrence_type": "notary_office_payment_notice",
"occurrence_status": "confirmed"
}
}
```
### Payment
Webhook Body
```json
{
"webhook_type": "baas.bank_slip.payment",
"webhook_datetime": "2024-08-13T21:35:55.679Z",
"data": {
"bank_slip_key": "db04719d-4370-4f3f-82b7-d72d3db2f39e",
"bank_slip_status": "paid",
"occurrence_key": "db04719d-4370-4f3f-82b7-d72d3db2f39e",
"occurrence_type": "payment",
"occurrence_status": "confirmed",
"paid_amount": 850.0,
"paid_rebate_amount": 200.0,
"paid_discount_amount": 0.0,
"paid_fine_amount": 0.0,
"paid_interest_amount": 50.0,
"payment_method": "account_debit",
"payment_origin": "qr_code",
"payment_credit_date": "2024-07-02",
"payment_bank": {
"code": "341",
"ispb": 60701190,
"name": "ITAU UNIBANCO S.A."
},
"payment_branch": "0216"
}
}
```
:::info Information
The `payment_bank` and `payment_branch` fields indicate the bank and branch where the bank slip was paid. They are only populated when this information is received upon payment settlement; if the paying bank is not identified, `payment_bank` is returned as `null`.
:::
### payment_method Enumerators
| Enumerator | Description |
|--------------------|-----------------------------------------|
| cash | Cash |
| account_debit | Account debit |
| credit_card | Credit card |
| check | Check |
### payment_origin Enumerators
| Enumerator | Description |
|----------------------|------------------------------------------|
| phisical_cashier | Branches - Traditional posts |
| taa | Self-service terminal |
| internet | Internet (home/office bank) |
| corban | Banking correspondent |
| call_center | Call center |
| eletronic_file | Electronic file |
| dda | DDA |
| digital_correspondent| Digital correspondent |
| qr_code | Pix QR Code payment |
---
# Bank slip wallet webhooks
URL: /en/documentation/boletos/webhooks/carteira
:::danger Warning!
QI Tech webhooks should not be mapped in a restrictive manner.
Additional fields may be included in the webhook payloads returned by our APIs.
:::
:::info Webhook Resending
You can check and resend webhooks following the detailed instructions in the documentation: [Webhook Resending](/documentation/notificacoes/reenvio_de_notificacoes).
:::
## Introduction
After creating a wallet (`requester_profile`) within our system, webhooks will be sent with the following status:
| Enumerator | Translation | Description |
|-------------------------------|------------------------|------------------------------------------------------------|
| opened | open | Bank slip wallet opened and ready to register bank slips |
:::info Information
The timeout for our webhook responses is 10 seconds.
:::
## Examples
----
### Opening confirmation
Webhook Body
```json
{
"webhook_type": "baas.bank_slip.requester_profile",
"webhook_datetime": "2024-08-13T21:35:55.679Z",
"data": {
"requester_profile_key": "fd86d9b1-2a5e-4e03-9a59-a043c7632c97",
"request_control_key": "0868a24b-4a69-4138-ac4d-ecaeddf0005f",
"requester_profile_code": "329-04-2338-2625918",
"requester_profile_status": "opened"
}
}
```
---
# Settlement webhooks
URL: /en/documentation/boletos/webhooks/liquidacao
:::danger Attention!
QI Tech webhooks should not be mapped in a restrictive manner.
Additional fields may be included in the webhook payloads returned by our APIs.
:::
:::info Webhook Resending
You can check and resend webhooks following the detailed instructions in the documentation: [Webhook Resending](/documentation/notificacoes/reenvio_de_notificacoes).
:::
## Introduction
In our system, settlement groups are a way to reconcile transactions with settled bank slips. This process (settlement) describes the transfer of value from a paid bank slip to the account that should receive this payment. In summary, whenever QI receives information that a bank slip has been paid by another bank or, in the case of protested bank slips, by the notary office, a settlement is created for that specific bank slip. Subsequently, **settlement groups** are created, which represent batches of settlements grouped by type.
At a later time, the payment transaction for this settlement group is made to the client's account. The **transaction_key** of this transaction is then saved for reconciliation purposes, so you can see all the bank slips that were settled in a specific transaction. For example, if you have five bank slips of R$ 5.00 each, where one was paid via notary office, one was paid via QR Code PIX and the other three were paid using the payment line or barcode by another bank, five settlements will be created for these bank slips. Then, these settlements will be grouped into three settlement groups: one of R$ 15.00 with the three bank slips paid using the payment line or barcode, for which a single transaction will be made, another of R$ 5.00 for the bank slip paid via QR Code PIX and the last one also of R$ 5.00 with the bank slip paid via notary office.
:::info Information
The timeout for response from our webhooks is 10 seconds.
:::
## Examples
----
### Settlement group
Webhook Body
```json
{
"webhook_type": "baas.bank_slip.bank_slip_settlement_group",
"webhook_datetime": "2024-08-13T21:35:55.679Z",
"data": {
"bank_slip_settlement_group_key": "87e6687b-d02b-45dc-b5b8-b51e16ec0a03",
"amount": 1,
"bank_slip_settlement_group_type": "siloc",
"bank_slip_settlement_group_status": "settled",
"transaction_key": "fc60a57e-c6ac-4e39-a3cf-2dc3c491dac6"
}
}
```
### bank_slip_settlement_group_type enumerators
| Enumerator | Description |
|------------------------------|------------------------------------------------------------------------------|
| siloc | for payment of securities (security value less than R$ 250,000) |
| qr_code | for payment of securities made via QR Code |
| str | for payment of VR securities (security value greater than R$ 250,000) |
| notary_office | for payment of securities made via notary office |
### bank_slip_settlement_group_status enumerators
| Enumerator | Description |
|------------------------------|------------------------------------------------------------------------------|
| pending | settlement group created but transaction was not executed |
| settled | settlement group created and transaction executed |
---
# Return file Webhooks
URL: /en/documentation/boletos/webhooks/retorno
Return files are used for reconciliation. In them, each Transaction Record line (Type 1) refers to an instruction (whether issuance, extension, discount, etc.) that was confirmed or rejected by CIP/Nuclea on the previous day.
:::danger Attention!
QI Tech webhooks should not be mapped in a restrictive manner.
Additional fields may be included in the webhook payloads returned in our APIs.
:::
:::info Webhook Resending
You can consult and resend webhooks by following the detailed instructions in the documentation: [Webhook Resending](/documentation/notificacoes/reenvio_de_notificacoes).
:::
:::info Information
The timeout for our webhook response is 10 seconds.
:::
## Examples
----
### Return file
Webhook Body
```json
{
"webhook_type": "baas.bank_slip.discharge_file",
"webhook_datetime": "2024-08-13T21:35:55.679Z",
"data": {
"discharge_file_key": "f1a8fe59-29cd-49e5-8d18-55194869b45c",
"reference_date": "2024-10-15",
"requester_profile_key": "fc60a57e-c6ac-4e39-a3cf-2dc3c491dac6",
"discharge_file_url": "https://storage.googleapis.com/local-bank-slip-api/2024/61a746ca-05bf-429d-99c3-3fba0f9fbea7/329-20-7336-3073959/discharge/CB15102401.RET",
"cnab_bank": "qi_scd",
"cnab_layout": "400",
}
}
```
:::info Supported Banks
Currently, the return file webhook supports the following banks:
- Bradesco (bradesco)
- Itaú (itau)
- QI SCD (qi_scd)
- Santander (santander)
:::
:::info Supported Layouts
Currently, the return file webhook supports the following CNAB layouts:
- CNAB 400 (400)
:::
---
# Authentication
URL: /en/documentation/caas/account_event/authentication
> To authenticate a call, use the following code:
```shell
# No shell, você somente precisa adicionar o header adequado em cada requisição.
curl "api_endpoint_here"
-H "Authorization: EXAMPLE-OF-API-KEY"
```
> Replace the API Key 'EXAMPLE-OF-API-KEY' with your own key, which can be obtained through our support team..
We use an API Key to grant access to our API. It has likely already been sent to you via email. If you haven't received your key yet, please send an email to suporte.caas@qitech.com.br .
Our API expects to receive the API Key in every request sent to our server within a header as shown below:
`Authorization: EXAMPLE-OF-API-KEY`
:::info **Attention**
You must replace EXAMPLE-OF-API-KEY with your actual key, which must be obtained through our support team.
:::
---
# Device Validation Object
URL: /en/documentation/caas/account_event/device_validation
Device validation via unique identification must be performed through the Device Validation Event Type endpoint. The data sent must be the information generated in the Device Registration API, along with a Device Scan session ID. In other words, to perform a device validation, the application must use the SDK to generate a unique identifier, and the device must be registered so it can be identified later
### Status Dynamics - **analysis_status**
The **analysis_status** field indicates the decision status of the fraud engine and follows a very simple state machine:
* automatically_approved
* automatically_reproved
* in_manual_analysis
* manually_approved
* manually_reproved
* pending
## Device Validation Object Definition
Request Body
```json
{
"id": "12345678",
"account_id": "12345678",
"person_id": "12345678",
"session_id": "12345678",
"event_date": "2019-12-11T11:37:15.12-03:00"
}
```
All information exchanges for a validation use the following definition for this object. In some cases, to simplify implementation and reduce data flow between parties, certain information may be omitted.
Name | Type | Description
:----: | :----: | ---------
id | string | Event identifier. **It is essential that this number is unique for each request** *(required)*
account_id | string | Identifier of the account registered in the device registration system. To perform more than one analysis for the same registration, simply use the same account_id across different analyses. *(required)*
person_id | string | Identifier of the user associated with the account registered in the device registration system. To perform more than one analysis for the same registration, simply use the same person_id across different analyses. *(required)*
session_id | string | Identifier of the Device Scan analysis session. *(required)*
face_recognition_key | string | Identifier of the image generated in the SDK for facial identification.
event_date | datetime | Event date and time *(required)*
## Submit a Device Validation
Request Body
```json
{
"id": "12345",
...
}
```
Response Body
```json
{
"id": "12345",
"analysis_status": "automatically_approved",
"reason": "rule_decision_enum"
}
```
To perform a Device validation, simply send a Device Validation type object to the following endpoint:
`POST https://api.caas.qitech.app/account_event/event_type/device_validation/event`
---
# HTTP Status Codes
URL: /en/documentation/caas/account_event/http_status
All QI Tech APIs follow the standard HTTP return status codes as defined in RFC 7231 :
Status HTTP | Meaning | Description
---------- | ------- | ---------------------------------
400 | Bad Request | The request sent contains formatting errors. Typically, we provide an explanation of the error within the message body.
401 | Unauthorized | There was an authentication issue. Verify if the API Key is correct and placed in the proper header, as described in the authentication section .
403 | Forbidden | The accessed endpoint is for internal use and is not available for this API Key.
404 | Not Found | The requested data was not found using the provided key. This status is also returned when an invalid endpoint is requested.
405 | Method Not Allowed | The HTTP method used is not applicable to the specified endpoint.
406 | Not Acceptable | The data sent in the request body is invalid. Generally, this means the submitted data is not a valid JSON.
409 | Conflict | The request ID corresponds to an ID that has already been processed. This status is returned in the case of duplicate requests sent to the server.
500 | Internal Server Error | We encountered a problem processing this request. When this error occurs, our specialists are automatically notified and begin analysis and resolution immediately.
503 | Service Unavailable | You have encountered an infrastructure unavailability, whether planned or unplanned, on our servers.
---
# Introduction
URL: /en/documentation/caas/account_event/introduction
Welcome to QI Tech's Account Event API! This API provides access to monitoring services and event rules within your platform's accounts.
While this API can be used for device validation alongside the Device Scan and Device Registration APIs, it is also versatile enough for other validations such as:
* Logins.
* Screen access.
* Password changes.
* Registration data updates.
* Pre-transaction validations.
* Liveness Validation.
You can use our API to access endpoints for evaluating the following event types:
* **Device Validation** - Used for validating a device's unique identification.
* **Pre Pix Transaction** - Used for the pre-validation of Pix transactions.
* **Registration Data Validation** - Used for validating registration data.
Different event types can be implemented depending on your system's specific needs.
On the side, you can view the API implementation using curl. These examples serve as a guide for you to adapt the code to your preferred programming language.
## Having trouble?
Having Trouble?
We aren't a company that hides behind an API! Get in touch with our support team and we will respond as quickly as possible. Feel free to call us if you need an immediate answer!
### We Love Feedback
Even if you have already solved your problem or if it was something simple (like a typo or a minor organizational issue), please send us an email. This helps us make our documentation more practical so the next person doesn't have to face the same hurdles you did!
## Environments
We provide two environments for our clients. The base URLs for the APIs are:
* Production - `https://api.caas.qitech.app/account_event/`
* Sandbox - `https://api.sandbox.caas.qitech.app/account_event/`
:::danger Important Notice!
Real personal or corporate data must not be used in QI Tech's Sandbox environments.
:::
In the Sandbox environment, submitted analyses are not billed and are responded to according to the rules configured for the event.
## HTTPS Only
For security reasons, all communication with QI Tech APIs must be performed via HTTPS. To prevent accidental HTTP calls, our server only makes port 443 available with TLS 1.2 communication. Calls made using other protocols will be automatically denied.
---
# Pre-PIX Transaction
URL: /en/documentation/caas/account_event/pre_pix_transaction
The moment a payer intends to initiate a payment, the transaction data can be previously evaluated by our server. This allows for a preliminary risk analysis based on that specific dataset.
## Pre-Pix Transaction Object Definition
Request Body
```json
{
"id": "082373263",
"transaction_direction": "received",
"client": {
"id": "123456",
"document_number": "056.966.649-03",
"name": "Francisco Oliveira Benedetti",
"type": "natural_person",
"address": {
"street": "Avenida 13",
"number": "704",
"neighbourhood": "Centro",
"city": "Ituiutaba",
"uf": "MG",
"complement": "Apt 1101",
"postal_code": "38300-140"
},
"phone": {
"international_dial_code": "55",
"area_code": "16",
"number": "981610077",
"type": "mobile"
},
"sales_channel": "inbound_sales",
"segment": "Personalité"
},
"amount": 13725,
"dict_key": {
"key_type": "cpf",
"key_value": "09991222669",
"assignment_date": "2020-01-15T18:00:00-03:00"
},
"face_recognition_key": "ef39e206-13d5-48de-b368-6c3bbc6f0222",
"source_account": {
"participant": "17315359",
"branch": "0000",
"account_number": "10442",
"account_digit": "6",
"owner": {
"type": "legal_person",
"document_number": "07.487.735/0001-69",
"name": "Gioconda Pizzaria e Rotisseria LTDA."
},
"account_type": "CACC",
"opening_date": "2020-01-15T18:00:00-03:00"
},
"destination_account": {
"participant": "60701190",
"branch": "3675",
"account_number": "10442",
"account_digit": "6",
"owner": {
"type": "natural_person",
"document_number": "056.966.649-03",
"name": "Francisco Oliveira Benedetti"
},
"account_type": "SLRY",
"opening_date": "2020-01-15T18:00:00-03:00"
},
"destination_statistics": {
"person":{
"settlements":{
"d90":4,
"m12":67,
"m60":618
},
"application_frauds":{
"d90":0,
"m12":4,
"m60":9
},
"mule_accounts":{
"d90":0,
"m12":0,
"m60":0
},
"scammer_accounts":{
"d90":0,
"m12":0,
"m60":0
},
"other_frauds":{
"d90":0,
"m12":0,
"m60":0
},
"unknown_frauds":{
"d90":0,
"m12":0,
"m60":0
},
"total_frauds_transaction_amount":{
"d90":0,
"m12":0,
"m60":0
},
"distinct_fraud_reporters":{
"d90":0,
"m12":0,
"m60":0
},
"open_reports":0,
"open_reports_distinct_reporters":0,
"rejected_reports":{
"d90":0,
"m12":0,
"m60":0
},
"registered_accounts":0
},
"owner":{
"settlements":{
"d90":0,
"m12":0,
"m60":0
},
"application_frauds":{
"d90":0,
"m12":0,
"m60":0
},
"mule_accounts":{
"d90":0,
"m12":0,
"m60":0
},
"scammer_accounts":{
"d90":0,
"m12":0,
"m60":0
},
"other_frauds":{
"d90":0,
"m12":0,
"m60":0
},
"unknown_frauds":{
"d90":0,
"m12":0,
"m60":0
},
"total_frauds_transaction_amount":{
"d90":0,
"m12":0,
"m60":0
},
"distinct_fraud_reporters":{
"d90":0,
"m12":0,
"m60":0
},
"open_reports":0,
"open_reports_distinct_reporters":0,
"registered_accounts":0
},
"key":{
"settlements":{
"d90":0,
"m12":0,
"m60":0
},
"application_frauds":{
"d90":0,
"m12":0,
"m60":0
},
"mule_accounts":{
"d90":0,
"m12":0,
"m60":0
},
"scammer_accounts":{
"d90":0,
"m12":0,
"m60":0
},
"other_frauds":{
"d90":0,
"m12":0,
"m60":0
},
"unknown_frauds":{
"d90":0,
"m12":0,
"m60":0
},
"total_frauds_transaction_amount":{
"d90":0,
"m12":0,
"m60":0
},
"distinct_fraud_reporters":{
"d90":0,
"m12":0,
"m60":0
},
"open_reports":0,
"open_reports_distinct_reporters":0,
"rejected_reports":{
"d90":0,
"m12":0,
"m60":0
},
"distinct_accounts":{
"d90":0,
"m12":0,
"m60":0
}
}
},
"source": {
"channel": "internet_banking",
"platform": "android",
"ip": "198.185.065.098",
"session_id": "7839jdqd9a8wd9"
},
"event_date": "2019-12-11T11:37:15.12-03:00"
}
```
A transaction must be sent to the API before being forwarded to the processing system in order to perform a preliminary fraud validation.
The transaction status represents the decision returned by the model for that transaction. The following statuses are used in the **analysis_status** flag:
* `automatically_approved`
* `automatically_reproved`
* `automatically_challenged`
* `pending`
The meanings of each decision returned in the analysis_status flag are listed below:
status | description
:----: | ---------
automatically_approved | It is recommended that this transaction be approved.
automatically_reproved | It is recommended that this transaction be rejected.
automatically_challenged | QI Tech's algorithms recommend that this transaction be challenged.
pending | The transaction is currently being processed.
name | type | description
:----: | :----: | ---------
id | string | Payment identifier in the client's system. **It is essential that this number is unique for each payment process** *(required)*
transaction_direction | enumerador | Type of registered transaction. Defines whether the client is receiving or sending money. *(required)*
client | *client* | Object representing client data, whether they are the payer or the receiver. *(required)*
amount | inteiro | The payment amount in cents — as described in the "Standards" section. *(required)*
pix_modality | string | Type of registered transaction. Indicates if it represents a transfer, change, or withdrawal.
dict_key | *dict_key* | Object representing the DICT link key data used by the client in the transaction.
face_recognition_key | string | Facial recognition key, if facial recognition was performed via our API.
source_account | *source_account* | Object representing the data of the debited account. *(required)*
destination_account | *destination_account* | Object representing the data of the credited account. *(required)*
destination_statistics | *destination_statistics* | Object representing the transaction and fraud history of the credited account from the Central Bank's (BACEN) DICT API.
source | *source* | Source object describing information from the application used to send the payment.
event_date | datetime | The start date and time of the transaction, including timezone. *(required)*
The following enumerators are available for *transaction_direction*: `sent` and `received`.
The following enumerators are available for *pix_modality*: `transacation`, `change` and `withdraw`.
## Submit a Pre-Transaction
Request Body
```json
{
"id": "12345",
...
}
```
Response Body
```json
{
"id": "12345",
"analysis_status": "automatically_approved",
"reason": "rule_decision_enum",
"reason_desciption": "description da regra"
}
```
To perform a pre-transaction evaluation, simply send a Transaction type object to the following endpoint:
`POST https://api.caas.qitech.app/account_event/event_type/pre_pix_transaction`
## Challenge Flow
After the analysis is executed, it is possible for the decision to be a "challenge," requiring the user to perform a new action on your platform. This flow can be used, for example, to request 2FA, such as facial analysis, from the user.
## Execution Flow Step-by-Step
**1.** The event is submitted for analysis and will return the status *automatically_challenged*.
Request Body
```json
{
"id": "082373263",
...
"event_date": "2019-12-11T11:37:15.12-03:00"
}
```
Response Body
```json
{
"id": "082373263",
"analysis_status": "automatically_challenge"
...
}
```
**2.** After the initial analysis request returns a challenge *analysis_status*, a new request can be sent with the result of the client's process once finalized. This request must use the same event_id as the previous request, and the current status must be *automatically_challenged*. The possible statuses for this update are:
* `approved_by_client`
* `reproved_by_client`
`PATCH https://api.caas.qitech.app/account_event/event_type/pre_pix_transaction/{event_id}`
Request Body: Submission with additional information
```json
{
"analysis_status": "approved_by_client"
}
````
Response Body
```json
{
"id": "082373263",
"analysis_status": "approved_by_client"
...
}
```
Make sure to use the same event_id used in your first analysis.
---
# Retrieve an Account Event
URL: /en/documentation/caas/account_event/query_registration
To retrieve a specific account event, simply perform a GET request. The response will return the most up-to-date JSON for the event in question. If the identifier is not associated with any object, an HTTP Status 404 is returned.
## Possible events:
- device_validation
- pre_pix_transaction
- registration_data_validation
`GET https://api.caas.qitech.app/event_type/{event_name}/event/{event_id}`
```shell
curl "https://api.caas.qitech.app/event_type/device_validation/event/12345678"
-H "Authorization: EXAMPLE-OF-API-KEY"
```
---
# Standards
URL: /en/documentation/caas/account_event/standards
To facilitate integration and ensure information integrity, a set of standards has been defined and is followed throughout the API.
## Monetary Values
> Examples:
```
10000
12345
98741
1223
1
0
```
The APIs assume that all monetary values sent are in Brazilian Reais (BRL). Values must be sent as integers in cents.
## Date and Time with Timezone
> Examples:
```
2019-10-15T22:35:12.232-03:00
2018-05-01T13:32:11.297+00:00
2019-05-01T00:00:00.000+00:00
```
Represented according to ISO 8601. In this case, the timezone is placed immediately after the time and should represent the offset of the location where that data is valid.
The mask used for validation is as follows:
`YYYY-MM-ddThh:mm:ss.sss±hh:mm`
## Date and Time without Timezone
> Examples:
```
2019-10-15T22:35:12
2018-05-01T13:32:11
2019-05-01T00:00:00
```
Represented according to ISO 8601. Data that is independent of a timezone should be sent without it, always in UTC, with the letter "Z" indicating that the data is in UTC. Therefore, the following format will be validated:
`YYYY-MM-ddThh:mm:ss.sssZ`
## Data
> Alguns exemplos
```
2019-10-15
2019-01-01
2017-03-20
```
For fields that receive only the date without any time information, it must be sent in the following format:
`YYYY-MM-dd`
## Documents
Since document numbers vary significantly and many contain non-numeric characters, all document numbers are defined as strings. Another reason to define them as strings is to prevent leading zeros from disappearing. Documents specified on this page have a well-defined mask and are subject to validation. Other documents, such as RG (Identity Card), will not be validated due to their lack of standardization.
## CPF
> Examples of valid CPFs against the defined mask:
```
123.456.789-12
321.987.543-23
111.283.333-00
```
> Examples of invalid CPFs against the defined mask:
```
8.577.477-8
08.104.627/0001-23
123.456.789-1
23.456.789-01
```
The CPF is always defined as a string and will be validated against the mask:
`###.###.###-##`
## CNPJ
> Examples of invalid CNPJs against the defined mask:
```
08.104.627/0001-02
01.079.210/0114-67
32.402.502/0001-35
```
> Examples of invalid CNPJs against the defined mask:
```
8.577.477-8
123.456.789-12
321.987.543-23
32.402.502/0001-3
032.402.502/0001-3
```
The CNPJ is always defined as a string and will be validated against the mask:
`##.###.###/####-##`
## IP Address
> Examples of valid IPs against the defined mask:
```
201.81.161.86
201.081.161.86
201.81.161.086
201.81.0.1
```
> Examples of invalid IPs:
```
201.81..86
358.81.161.86
201.81.161
```
IP addresses must always be sent in IPv4 format. Leading zeros are optional and must follow this mask:
`###.###.###.###`
---
# Status Dynamics
URL: /en/documentation/caas/account_event/status_dynamics
The analysis process consists of sending an event (such as Device Validation) to the appropriate endpoint and waiting for a response.
Once QI Tech completes the event analysis, it will return a response containing a status for that analysis. The **analysis_status** field represents the outcome of the event analysis performed by QI Tech.
### **analysis_status**
As previously described, QI Tech has eight **analysis_status** values that indicate the decision-making status of the account event engine. It follows a straightforward state machine:
| analysis_status | Description |
| :---: | --- |
| **automatically_approved** | QI Tech's algorithms recommend that this event be approved. |
| **automatically_reproved** | QI Tech's algorithms recommend that this event be rejected. |
| **automatically_challenge** | QI Tech's algorithms recommend that the user take an action to provide more information for the analysis. |
| **in_manual_analysis** | QI Tech's algorithms have flagged this event for manual review. |
| **manually_approved** | After manual review, the analyst decided to approve the event. |
| **manually_reproved** | After manual review, the analyst decided to reject the event. |
| **in_queue** | The event is being processed asynchronously. The outcome will be sent via Webhook. |
| **pending** | Queries are taking longer than expected; this event has entered an automated analysis queue and will be answered via Webhook. |
| **not_analysed** | The event was sent with the analysis flag set to false, meaning our systems will not provide a recommendation. |
---
# Account Creation
URL: /en/documentation/caas/account_monitoring/account_registration
The Account Monitoring Product is divided into Individual Accounts (Natural Person) and Corporate Accounts (Legal Person). An Individual Account may contain only natural persons, while a Corporate Account may contain both legal entities and natural persons. To create an account, simply send an object of type _Account_ to one of the following endpoints:
- Individual Account (Natural Person)
`POST https://api.caas.qitech.app/account_monitoring/natural_person_account`
> Example
```json
{
"account_id": "5ce7fab5-8165-44a5-9b89-bb2d6d61e4f4",
"registration_date": "2019-12-20T15:23:12"
}
```
- Corporate Account (Legal Person)
`POST https://api.caas.qitech.app/account_monitoring/legal_person_account`
> Example
```json
{
"account_id": "5ce7fab5-8165-44a5-9b89-bb2d6d61e4f4",
"registration_date": "2019-12-20T15:23:12"
}
```
All information exchanges related to an account registration use the following object definition. In some cases, to simplify the implementation and reduce data flow between parties, some information may be omitted.
name | type | description
:----: | :----: | ---------
account_id | string | Unique account identifier. **This value must be unique for each request**
registration_date | string (ISO 8601) | Account registration date and time.
## Account Deactivation and Reactivation
To deactivate an account within the Account Monitoring product, send a request to the following endpoint with the payload below, setting the `new_account_status` field to `deactivated`:
- Individual Account (Natural Person)
`PATCH https://api.caas.qitech.app/account_monitoring/natural_person_account/{account_id}`
> Example
```json
{
"new_account_status": "deactivated"
}
```
- Corporate Account (Legal Person)
`PATCH https://api.caas.qitech.app/account_monitoring/legal_person_account/{account_id}`
> Example
```json
{
"new_account_status": "deactivated"
}
```
This will deactivate the account and interrupt its monitoring. To reactivate an account — and consequently resume its monitoring — send a request to the same endpoint, now setting `new_account_status` to `active`:
- Individual Account (Natural Person)
`PATCH https://api.caas.qitech.app/account_monitoring/natural_person_account/{account_id}`
> Example
```json
{
"new_account_status": "active"
}
```
- Corporate Account (Legal Person)
`PATCH https://api.caas.qitech.app/account_monitoring/legal_person_account/{account_id}`
> Example
```json
{
"new_account_status": "active"
}
```
When an account is reactivated, the monitoring intervals for all account topics are reset. For example, if all topics are monitored every 24 hours, after reactivation the updates will occur 24 hours after the account is reactivated.
---
# authentication
URL: /en/documentation/caas/account_monitoring/authentication
## Authentication
> To authenticate a request, use the following code:
```shell
# In the shell, you only need to add the appropriate header to each request
curl "api_endpoint_here"
-H "Authorization: EXAMPLE_API_KEY"
```
> Replace the API key `EXAMPLE_API_KEY` with the key provided by our support team.
We use an API Key to allow access to our API. It was most likely already sent to you by email. If you have not yet received your key, please send an email to suporte.caas@qitech.com.br .
Our API expects the API Key to be sent in all requests to our server using a header like the one below:
`Authorization: EXAMPLE_API_KEY`
:::info **Attention**
You must replace EXAMPLE_API_KEY with the API Key provided by the support team.
:::
---
# HTTP Status
URL: /en/documentation/caas/account_monitoring/http_status
All QI Tech APIs use the following standardization for HTTP response status codes, in accordance with RFC 7231 :
HTTP Status | Meaning | Description
---------- | ------- | ---------------------------------
400 | Bad Request | The request sent contains a formatting error. In most cases, we return an explanation in the response body indicating where the error is.
401 | Unauthorized | There was an authentication issue. Please verify that the API Key is correct and sent in the proper header, according to the Authentication section.
403 | Forbidden | The accessed endpoint is for internal use and is not available for this API Key.
404 | Not Found | The requested data was not found using the provided key. This status is also returned when an invalid endpoint is requested.
405 | Method Not Allowed | The HTTP method used does not apply to the accessed endpoint.
406 | Not Acceptable | The data sent in the request body is invalid. In general, this means the payload is not a valid JSON.
409 | Conflict | The request ID corresponds to an ID that has already been processed. This status is returned in the case of duplicate requests sent to the server.
500 | Internal Server Error | We encountered an issue while processing this request. When this error occurs, our specialists are automatically notified and immediately begin analysis and resolution.
503 | Service Unavailable | You have encountered a planned or unplanned infrastructure outage of our servers.
---
# Introduction
URL: /en/documentation/caas/account_monitoring/introduction
Welcome to the QI Tech Account Monitoring API! You can use our API to monitor accounts and individuals across several monitoring topics, respecting fully customizable monitoring intervals according to the client’s demands and needs. Today, the product supports the following monitoring topics:
- For Individuals (Natural Persons);
- OFAC List – Sanctions List from the Office of Foreign Assets Control
- UNSC List – Sanctions List from the United Nations Security Council
- IBAMA List – Environmental Penalties List from the Brazilian Institute of Environment and Renewable Natural Resources
- PEP List – Politically Exposed Persons List
- Federal Revenue Status – Registration status with the Brazilian Federal Revenue Service
- For Legal Entities (Companies);
- OFAC List – Sanctions List from the Office of Foreign Assets Control
- UNSC List – Sanctions List from the United Nations Security Council
- IBAMA List – Environmental Penalties List from the Brazilian Institute of Environment and Renewable Natural Resources
- CEIS List – Registry of Ineligible and Suspended Companies
- CNEP List – National Registry of Punished Companies
- Federal Revenue Status – Registration status with the Brazilian Federal Revenue Service
Please note that monitoring intervals are defined per monitoring topic and per type of monitored entity. For example, the OFAC List can be monitored every 10 days for Individuals and every 30 days for Legal Entities.
The monitoring interval for each topic follows the ISO 8601 standard and can be any of the intervals listed below, or a combination of them:
### Days, Weeks, Months, and Years
| Notation | Meaning |
|----------|---------|
| `"P1D"` | 1 day |
| `"P7D"` | 7 days |
| `"P1W"` | 1 week |
| `"P1M"` | 1 month |
| `"P1Y"` | 1 year |
---
### Hours, Minutes, and Seconds
| Notation | Meaning |
|-----------------|----------------------------------|
| `"PT1H"` | 1 hour |
| `"PT30M"` | 30 minutes |
| `"PT45S"` | 45 seconds |
| `"PT2H30M"` | 2 hours and 30 minutes |
| `"PT1H15M10S"` | 1 hour, 15 minutes, and 10 seconds |
---
### Custom Examples
| Notation | Meaning |
|---------------------|---------------------------------------------|
| `"P1DT12H"` | 1 day and 12 hours |
| `"P2W3DT4H30M"` | 2 weeks, 3 days, 4 hours, and 30 minutes |
Below, you can see an example implementation of the API using curl. These examples can be adapted to the programming language of your choice.
## Problems?
We are not a company that hides behind an API! Contact our support team and we will respond as quickly as possible. Feel free to call us if you need a faster response!
### We Love Feedback
Even if you have already solved your issue or if it is very simple (even a typo or a formatting issue that you already understood), send us an email. This helps us make the documentation more practical so the next person doesn’t have to go through the same pain you did!
## Environments
We provide two environments for our clients. The base URLs for the APIs are:
* Production – `https://api.caas.qitech.app/account_monitoring/`
* Sandbox – `https://api.sandbox.caas.qitech.app/account_monitoring/`
In the Sandbox environment, submitted analyses are not charged and are answered according to predefined rules.
## HTTPS Only
For security reasons, all communication with QI Tech APIs must be performed using HTTPS. To prevent HTTP calls due to inattention or other reasons, this server only exposes port 443 with TLS 1.2 communication. Requests made using other protocols will be automatically denied.
## Authentication
> To authenticate a request, use the following code:
```shell
curl "api_endpoint_here" \
-H "Authorization: EXAMPLE_API_KEY"
---
# Person Creation
URL: /en/documentation/caas/account_monitoring/person_registration
To create people for their respective accounts, segregation between the
natural_person_account and legal_person_account endpoints must be maintained.
To request the creation of a person for an account, simply send a Person object to one of the
following endpoints, respecting the segregation defined during account creation.
## Individual Account (Natural Person)
### Natural Person Creation
`POST https://api.caas.qitech.app/account_monitoring/natural_person_account/{account_id}/natural_person`
> Example
```json
{
"id": "cc2f97ba-08c8-4a91-8d0d-49313a6c1245",
"registration_date": "2024-11-04T13:37:00Z",
"data": {
"name": "John Doe",
"document_number": "123.456.789-09",
"birthdate": "2000-07-13"
}
}
```
### Legal Person Account
- Natural Person Creation
`POST https://api.caas.qitech.app/account_monitoring/legal_person_account/{account_id}/natural_person`
> Example
```json
{
"id": "cc2f97ba-08c8-4a91-8d0d-49313a6c1245",
"registration_date": "2024-11-04T13:37:00Z",
"data": {
"name": "John Doe",
"document_number": "123.456.789-09",
"birthdate": "2000-07-13"
}
}
```
The birthdate field is mandatory only for accounts that have status monitoring
with the Brazilian Federal Revenue Service. It is required to query individuals
under 18 years old.
- Legal Person Creation
`POST https://api.caas.qitech.app/account_monitoring/legal_person_account/{account_id}/legal_person`
> Example
```json
{
"id": "cc2f97ba-08c8-4a91-8d0d-49313a6c1245",
"registration_date": "2024-11-04T13:37:00Z",
"data": {
"name": "Empresa das Tampas",
"document_number": "12.482.243/0001-34"
}
}
```
## Person Deactivation and Reactivation
The deactivation and reactivation of people follows the same logic used for accounts, using the endpoints below.
### Natural Person Account
- Natural Person
`PATCH https://api.caas.qitech.app/account_monitoring/natural_person_account/{account_id}/natural_person`
> Example
```json
{
"new_person_status" : "deactivated"
}
```
### Legal Person Account
- Natural Person
`PATCH https://api.caas.qitech.app/account_monitoring/legal_person_account/{account_id}/natural_person`
> Example
```json
{
"new_person_status" : "deactivated"
}
```
- Legal Person
`PATCH https://api.caas.qitech.app/account_monitoring/legal_person_account/{account_id}/legal_person`
> Example
```json
{
"new_person_status" : "deactivated"
}
```
To reactivate previously deactivated people, the operation is the same as the one used to deactivate people, but sending new_person_status as active to the following endpoints:
### Natural Person Account
- Natural Person
`PATCH https://api.caas.qitech.app/account_monitoring/natural_person_account/{account_id}/natural_person`
> Example
```json
{
"new_person_status" : "active"
}
```
### Legal Person Account
- Natural Person
`PATCH https://api.caas.qitech.app/account_monitoring/legal_person_account/{account_id}/natural_person`
> Example
```json
{
"new_person_status" : "active"
}
```
- Legal Person
`PATCH https://api.caas.qitech.app/account_monitoring/legal_person_account/{account_id}/legal_person`
> Example
```json
{
"new_person_status" : "active"
}
```
---
# Standards
URL: /en/documentation/caas/account_monitoring/standards
To facilitate integration and ensure data integrity, some standards have been defined and are followed throughout the entire API.
## Date and Time with Time Zone
> Some examples:
```
2019-10-15T22:35:12-03:00
2018-05-01T13:32:11+00:00
2019-05-01T00:00:00+00:00
```
It is represented according to ISO 8601. In this case, the time zone is placed right after the time and must represent the time zone of the location where that data is valid. For example, if a rental is scheduled to start at 09:30 at Brasília airport, the time sent must be represented as 09:30-03:00. If the rental is scheduled to start at 09:30 in Manaus, it must be represented as 09:30-04:00.
The validation mask used is the following:
`YYYY-MM-ddThh:mm:ss±hh:mm`
## Date and Time without Time Zone
> Some examples:
```
2019-10-15T22:35:12Z
2018-05-01T13:32:11Z
2019-05-01T00:00:00Z
```
It is represented according to ISO 8601. Data that does not depend on a time zone must be sent without it, always in UTC, with the letter `Z` indicating that the data is in UTC. Therefore, the following format will be validated:
`YYYY-MM-ddThh:mm:ssZ`
## Date
> Some examples:
```
2019-10-15
2019-01-01
2017-03-20
```
For fields that accept only a date, such as a birthdate, only the date should be sent, without any time, using the following format:
`YYYY-MM-dd`
## Documents
Since document numbers can vary greatly and many of them contain non-numeric characters, all document numbers are defined as strings. Another important reason to define them as strings is to prevent leading zeros from being lost. Documents listed on this page have a well-defined mask and will be subject to validation. Other documents, such as RG, due to their lack of standardization, will not be validated.
## CPF
> Examples of CPFs valid against the defined mask:
```
123.456.789-12
321.987.543-23
111.283.333-00
```
> Examples of CPFs invalid against the defined mask:
```
8.577.477-8
08.104.627/0001-23
123.456.789-1
23.456.789-01
```
The CPF is always defined as a string and will be validated against the mask:
`###.###.###-##`
## CNPJ
> Examples of CNPJs valid against the defined mask:
```
08.104.627/0001-02
01.079.210/0114-67
32.402.502/0001-35
```
> Examples of CNPJs invalid against the defined mask:
```
8.577.477-8
123.456.789-12
321.987.543-23
32.402.502/0001-3
032.402.502/0001-3
```
The CNPJ is always defined as a string and will be validated against the mask:
`##.###.###/####-##`
---
# Webhook
URL: /en/documentation/caas/account_monitoring/webhook
Updates to monitoring topics will be notified through webhook deliveries. To enable this, it is necessary to configure—through the [support](mailto:suporte.caas@qitech.com.br) team—an endpoint address where we will send update notifications, as well as a *signature_key* that will be used to sign the request. It is important to note that all webhook deliveries will be sent to a single endpoint.
:::info **Attention**
For security reasons, all Webhook requests will only be made to endpoints served over HTTPS.
:::
## Signature
> Example of signature calculation in Python
```python
hmac_obj = hmac.new(
signature_key.encode('utf-8'),
(url + method + payload).encode('utf-8'),
hashlib.sha1
)
return hmac_obj.hexdigest()
```
To ensure that the request received at the webhook endpoint originates from our servers, an HMAC signature is sent in the *Signature* header, similarly to the authentication process.
After calculating the expected signature value on the server side, it is necessary to compare the calculated signature with the one received. If the signatures match, it means that the request originated from our servers and can be trusted.
## Event Update Webhook
Request Body
```json
{
"person_type" : "natural_person",
"account_type" : "natural_person_account",
"person_id" : "22f5d028-0ce7-46f7-9b63-e7e38171b485",
"account_id" : "e49ac344-f941-4668-9afb-a52ce4e5754a",
"monitoring_topic" : "OFAC",
"event" : "entered"
}
```
Below is the meaning of each field:
| Name | Type | Description |
|:-----------------:|:------:|-----------------------------------------------------------------------------|
| person_type | string | Person type (`natural_person` or `legal_person`). |
| account_type | string | Account type (`natural_person_account` or `legal_person_account`). |
| person_id | string | Unique identifier of the person, provided in the creation request. |
| account_id | string | Unique identifier of the account, provided in the creation request. |
| monitoring_topic | string | Monitoring topic in which the change occurred. |
| event | string | Type of event that occurred, such as `"entered"` or `"exited"` for restrictive list topics. |
The monitoring topic update request follows the format above and notifies a change in the status of one of the monitoring topics within the account. The HTTP method used is PUT, and the endpoint URL may also contain the event ID, depending on the client's needs. It is important to note that the request body is sent as UTF-8 encoded text.
## Retries
The notification is considered successfully delivered when an HTTP 200 status is returned. If delivery fails, up to 7 retry attempts will be made with the following intervals, until a 200 response is received or all attempts are exhausted:
* 10 seconds
* 40 seconds
* 160 seconds
* 640 seconds
* 2560 seconds
* 10240 seconds
* 40960 seconds
---
# Session Creation
URL: /en/documentation/caas/auth_session_manager/auth_session
The authentication session object is an entity that represents the user's authentication flow. Through this element, you can manage the registration information collection process.
## Authentication Session Object Definition
Request Body
```json
{
"id": "12345678",
"document_number": "111.111.111-11",
"settings": {
"steps": [
{
"step": "device_scan"
},
{
"step":"face_recognition",
},
{
"step":"personal_document",
"show_success_screen": true,
"show_introduction_screen": true,
"document_templates":[
"rg",
"cnh",
"cnh_digital"
]
}
],
"session_expiration_time_in_minutes": 120,
"token_expiration_seconds": 3600,
"open_mode": "iframe"
}
}
```
All information exchanges for a session use the following definition for this object:
name | type | description
:----: | :----: | ---------
id | string | Session identifier. **It is essential that this number be unique for each session** *(required)*
document_number | string | CPF of the individual being registered, with dots and hyphens, according to the standard. *(required)*
settings | object | Object with the custom settings for the authentication session. If not sent, the company's default configuration will be used.
## settings object
The settings object contains the `steps` field which defines the sequence of authentication steps and their respective configurations. The accepted steps are:
* device_scan
* face_recognition
* personal_document
The following fields are also accepted:
name | type | description
:----: | :----: | ---------
session_expiration_time_in_minutes | integer | Session expiration date. After this date, the session will not be valid.
token_expiration_seconds | integer | Session token expiration time in seconds. (must be between 1 and 172800, maximum 48 hours. Default value is 1800)
open_mode | string | Defines the session opening mode, for the message and buttons of the completion flow. (must be: "iframe" or "link").
### device_scan
The device_scan step indicates the execution of device information collection. **Has no additional configurations**
### face_recognition
The face_recognition step indicates the execution of the liveness proof flow collection through facial biometrics. **Has no additional configurations**
### personal_document
The personal_document step indicates the execution of the OCR flow collection for document reading.
name | type | description
:----: | :----: | ---------
document_templates | array | List of documents that can be collected in the registration flow. *(required)*
show_success_screen | boolean | Defines whether the success screen is shown in the document capture flow. Default value `true`.
show_introduction_screen | boolean | Defines whether the introduction screen is shown in the document capture flow. Default value `true`.
Accepted `document_templates` values:
Name | Type | Description
---- | ---- | ---------
cnh | string | Capture of physical driver's license (CNH) FRONT and BACK (**closed**), in two steps
rg | string | Capture of physical ID card (RG) FRONT and BACK (**closed**), in two steps
cnh_digital | string | Submission of **digital** driver's license (pdf)
passport | string | Submission of Passport FRONT and BACK (**closed**), in two steps.
rne | string | Submission of National Registry of Foreigners FRONT and BACK (**closed**), in two steps.
crnm | string | Submission of National Migration Registry Card FRONT and BACK (**closed**), in two steps.
ctps | string | Submission of Work and Social Security Card FRONT and BACK (**closed**), in two steps.
others | string | Submission of any document **exempt from validation** FRONT and BACK (**closed**), in two steps.
## Submit an Auth Session
Request Body
```json
{
"id": "12345",
...
}
```
Response Body
```json
{
"id": "12345678",
"status": "pending",
"expiration_date": "2025-12-11T11:37:15.12-03:00",
"settings": {
...
},
"auth_session_hash": "1cFL1vM",
"step": "device_scan",
"auth_session_url": "https://auth-session.production.caas.qitech.app/s/1cFL1vM/t/fc0bae39-1c41-4bc2-a5a1-39a7ca01121b",
"token": "fc0bae39-1c41-4bc2-a5a1-39a7ca01121b",
"token_expiration_date": "2025-12-10T11:37:15.12-03:00",
}
```
To create a session, simply send an Auth Session object to the following endpoint:
`POST https://api.caas.qitech.app/auth_session_manager/auth_session`
---
# Authentication
URL: /en/documentation/caas/auth_session_manager/authentication
> To authenticate a call, use the following code:
```shell
# In the shell, you only need to add the appropriate header to each request
curl "api_endpoint_here"
-H "Authorization: EXAMPLE-OF-API-KEY"
```
> Replace the API Key 'EXAMPLE-OF-API-KEY' with your key, which should be obtained from our support team.
We use an API Key to allow access to our API. It has probably already been sent to you by email. If you have not yet received your key, send an email to suporte.caas@qitech.com.br .
Our API expects to receive the API Key in all requests to our server in a header like the one below:
`Authorization: EXAMPLE-OF-API-KEY`
:::info **Attention**
You must replace EXAMPLE-OF-API-KEY with your key, which should be obtained from our support team.
:::
---
# HTTP Status
URL: /en/documentation/caas/auth_session_manager/http_status
All QI Tech APIs use the following standardization for HTTP response status codes, in accordance with RFC 7231 :
Status HTTP | Meaning | Description
---------- | ------- | ---------------------------------
400 | Bad Request | The request sent has a formatting error. In most cases, we return an explanation in the response body indicating where the error is.
401 | Unauthorized | There was an authentication problem; verify that the API Key is correct and in the correct header, as described in the Authentication section.
403 | Forbidden | The endpoint accessed is for internal use and is not available for this API Key.
404 | Not Found | The requested data was not found using the key provided. This status is also returned when an invalid endpoint is requested.
405 | Method Not Allowed | The HTTP method used does not apply to the endpoint used.
406 | Not Acceptable | The data sent in the request body is invalid. In general, this means the data sent is not valid JSON.
409 | Conflict | The request id matches an id that was already processed previously. This status is returned in the case of duplicate requests sent to the server.
500 | Internal Server Error | We had a problem processing this request; when we encounter this error our specialists are automatically notified and begin analysis and resolution immediately.
503 | Service Unavailable | You have encountered an outage, planned or not, of our server infrastructure.
---
# Introduction
URL: /en/documentation/caas/auth_session_manager/introduction
Welcome to the QI Tech Authentication Session Management API! This API was designed to control the complete user KYC flow!
This service organizes the authentication process, enabling the creation of KYC registration sessions with customized flows and use of other QI Tech authentication services:
* Device Scan
* Face Recognition
* OCR
This way, it is possible to start the registration information collection flow through the link returned by the API. Once started, the web page will be responsible for guiding the user through the KYC steps defined in that session.
Furthermore, by being directly integrated with the other services described above, it is able to collect the information necessary to complete the authentication flow. With this information, it will be possible to perform the desired analysis on other QI Tech services, such as individual registration or a pre-transactional analysis, for example.
## Problems?
We are not a company that hides behind an API! Contact our support and we will respond as quickly as possible. Feel free to call us if you want a quick response!
### We Love Feedback
Even if you have already resolved your issue or if it is very simple (even a typo or inadequate organization that you have noticed), send us an email so we can make the documentation increasingly more practical and the next person won't have to suffer the same pains you did!
## Environments
We have two environments for our clients. The base URLs for the APIs are:
* Production - `https://api.caas.qitech.app/auth_session_manager/`
* Sandbox - `https://api.sandbox.caas.qitech.app/auth_session_manager/`
:::danger Important Notice!
Real data from individuals and/or legal entities must not be used in QI Tech's Sandbox environments.
:::
In the Sandbox environment, submitted analyses are not charged and are responded to according to the rule configured for the event.
## HTTPS Only
For security reasons, all communication with QI Tech APIs must be carried out using HTTPS. To ensure that, due to inattention or any other reason, no HTTP calls occur, this server only makes port 443 available with TLS 1.2 communication. Calls made using other protocols will be automatically denied.
---
# Session Management
URL: /en/documentation/caas/auth_session_manager/retrieve_session
When creating an authentication session, simply use the generated link to start the user registration flow. This can be done by sending the link or using it directly on your website, with tools such as `iframe`.
## Response object
The response object from creating and retrieving an `auth_session` contains the following information:
Response Body
```json
{
"id": "12345678",
"status": "pending",
"expiration_date": "2025-12-11T11:37:15.12-03:00",
"step_data": {
"face_recognition": {
"image_key": "65441d8d-015a-4a0f-97b6-b7d4fc5619b7",
"event_date": "2025-12-11T11:37:15.12-03:00"
},
"personal_document": {
"document_template": "rg",
"ocr_keys": [
"e13c71d0-ae0e-48e2-8c42-26f997412039",
"3991b716-0980-409f-8e33-e3a8dd9a671c"
],
"event_date": "2025-12-11T11:37:15.12-03:00"
},
"device_scan": {
"session_id": "4d450227-c77c-4487-830b-42dcd127798a",
"event_date": "2025-12-11T11:37:15.12-03:00"
}
},
"settings": {
...
},
"auth_session_hash": "1cFL1vM",
"step": "device_scan",
"auth_session_url": "https://auth-session.production.caas.qitech.app/s/1cFL1vM/t/fc0bae39-1c41-4bc2-a5a1-39a7ca01121b",
"token": "fc0aaa39-1c21-1bc1-a5a1-39a7ca01121b",
"token_expiration_date": "2025-12-10T11:37:15.12-03:00",
}
```
This object is returned by the session retrieval endpoint:
`GET https://api.caas.qitech.app/auth_session_manager/auth_session/{id}`
Response fields description:
name | type | description
:----: | :----: | ---------
id | string | Session ID.
status | string | Session status.
expiration_date | date | Session expiration date. After this date, the session is invalidated.
step_data | object | Object containing the session event results.
settings | object | Session configuration object.
auth_session_hash | string | Session identification hash.
step | string | User's current step.
auth_session_url | string | URL used to collect registration information.
token | string | Session authentication token.
token_expiration_date | date | Expiration date of the temporary authentication token. Default set to 2 hours after session creation.
### Status
Possible status values:
* pending
* completed
* expired
### step_data object
Object containing the data collected from each step.
:::info Information
If the step is not listed in the session settings, it will not be present as a field in the `step_data` object
:::
`face_recognition`
Name | Type | Description
---- | ---- | ---------
image_key | string | Identification key for the face_recognition step.
event_date | date | Step completion date.
`personal_document`
Name | Type | Description
---- | ---- | ---------
document_template | string | Template selected by the user at document collection time.
ocr_keys | list | List of identification keys for each collected document.
event_date | date | Step completion date.
`device_scan`
Name | Type | Description
---- | ---- | ---------
session_id | string | Identification key for the device scan step.
event_date | date | Step completion date.
## Web flow authentication
To ensure greater security for the application, we return a temporary token for the web page. You can retrieve the token or generate a new one through the endpoint:
`POST https://api.caas.qitech.app/auth_session_manager/auth_session/{id}/token`
Request Body
```json
{
"token_expiration_seconds": 3600
}
```
The token object has only one optional field:
Name | Type | Description
---- | ---- | ---------
token_expiration_seconds | integer | Session token expiration time in seconds. (must be between 1 and 172800, maximum 48 hours. Default value is 1800)
Response Body
```json
{
"id": "12345678",
"token": "e7e99a40-0b26-4bb9-a068-9fa4886eeef3",
"token_expiration_date": "2025-12-10T13:37:15.12-03:00",
}
```
Thus, if the token has expired, you can continue with the authentication session by generating a new token.
# Webhook
Session completion will be notified via webhook. To do so, it is necessary to configure, through the [support](mailto:suporte.caas@qitech.com.br) team, an endpoint address where we will send the notifications and also a *signature_key* that will be used to sign the request. It is worth noting that all webhook deliveries will be sent to a single endpoint.
:::info **Attention**
For security reasons, all Webhook requests will only be made to endpoints served over HTTPS.
:::
## Communication with the web page
The web page can be integrated through a tool called `iframe`. In the following way:
```html
```
> ⚠️ **Required Configuration**
>
> For the iframe to work correctly in **production** (`auth-session.caas.qitech.app`) and **sandbox** (`auth-session.sandbox.caas.qitech.app`), it is necessary to configure the following Permissions-Policy header:
>
> **Configuration with specific URLs (recommended):**
> ```json
> {
> "key": "Permissions-Policy",
> "value": "geolocation=(self \"https://auth-session.caas.qitech.app\" \"https://auth-session.sandbox.caas.qitech.app\"), microphone=(self \"https://auth-session.caas.qitech.app\" \"https://auth-session.sandbox.caas.qitech.app\"), camera=(self \"https://auth-session.caas.qitech.app\" \"https://auth-session.sandbox.caas.qitech.app\"), fullscreen=(self \"https://auth-session.caas.qitech.app\" \"https://auth-session.sandbox.caas.qitech.app\")"
> }
> ```
>
> **Alternative configuration (less restrictive):**
> ```json
> {
> "key": "Permissions-Policy",
> "value": "geolocation=*, microphone=*, camera=*, fullscreen=()"
> }
> ```
>
> This configuration must be applied on the server that hosts the page containing the iframe to ensure that the necessary permissions are granted.
If the link is called in this way, the web page will send return messages to the page that requested it. The possible return messages are:
* success
* canceled
* invalid_token
* expired
Which can be accessed in the following way:
```javascript
window.addEventListener("message", (event) => {
if (event.data === "canceled") {
//close iframe
}
if (event.data === "invalid_token") {
//close iframe
}
if (event.data === "success") {
//close iframe
}
if (event.data === "expired") {
//close iframe
}
});
```
## Flow completion
This service will manage the authentication data collection flow, which can be used in other services. For more information on how to use the returned keys in other products, see the individual registration analysis example [Registration Analysis](https://docs.qitech.com.br/documentation/caas/onboarding/query_registration)
---
# authentication
URL: /en/documentation/caas/banking/authentication
## Authentication
> To authenticate a call, use the following code:
```shell
# In the shell, you only need to add the appropriate header to each request
curl "api_endpoint_here"
-H "Authorization: EXAMPLE_API_KEY"
```
> Replace the API key 'EXAMPLE_API_KEY' with the key acquired from our support.
We use an API Key to allow access to our API. It has likely already been sent to you by email. If you have not yet received your key, send an email to suporte.caas@qitech.com.br .
Our API expects to receive the API Key in all requests to our server in a header like the one below:
`Authorization: EXAMPLE_API_KEY`
:::info **Attention**
You must replace EXAMPLE_API_KEY with the API Key received from support.
:::
---
# Bankslip
URL: /en/documentation/caas/banking/bankslips
At the moment a user makes or receives a bankslip payment, the payment data must be sent to QI Tech. In this way, it will be possible to perform an analysis of the risk involved in that operation using the data.
## Bankslip Object Definition
Request Body
```json
{
"id": "082373263",
"bankslip_direction": "received",
"document_amount": 13725,
"discount_amount": 1000,
"other_deduction_amount": 0,
"interest_amount": 254,
"amount": 12979,
"bankslip_payment_date": "2020-10-07T15:06:25-03:00",
"bankslip_due_date": "2020-10-07",
"bankslip_issuing_date": "2020-10-07",
"description": "BOLETO PARA PAGAMENTO DA MENSALIDADE DE SETEMBRO",
"face_recognition_key": "ef39e206-13d5-48de-b368-6c3bbc6f0222",
"validation_key": "69a59de3-0198-4a26-933a-c1de624c147d",
"payer": {
"id": "182373263",
"type": "legal_person",
"document_number": "07.487.735/0001-69",
"name": "Gioconda Pizzaria e Rotisseria LTDA.",
"address": {
"street": "Avenida 13",
"number": "704",
"neighbourhood": "Centro",
"city": "Ituiutaba",
"uf": "MG",
"complement": "Apt 1101",
"postal_code": "38300-140"
},
"phone": {
"international_dial_code": "55",
"area_code": "16",
"number": "981610077",
"type": "mobile"
},
"email": "mailto@qitech.com.br",
"account": {
"participant": "60701190",
"branch": "3675",
"account_number": "13212",
"account_digit": "5",
"account_type": "CACC"
},
"sales_channel": "inbound_sales",
"segment": "Personalité"
},
"recipient": {
"id": "282373263",
"type": "legal_person",
"document_number": "056.966.649-03",
"name": "Francisco Oliveira Benedetti",
"address": {
"street": "Avenida 13",
"number": "704",
"neighbourhood": "Centro",
"city": "Ituiutaba",
"uf": "MG",
"complement": "Apt 1101",
"postal_code": "38300-140"
},
"phone": {
"international_dial_code": "55",
"area_code": "16",
"number": "981610077",
"type": "mobile"
},
"account": {
"participant": "60701190",
"branch": "3675",
"account_number": "10552",
"account_digit": "6",
"account_type": "CACC"
}
},
"final_recipient": {
"id": "382373263",
"type": "legal_person",
"document_number": "056.966.649-03",
"name": "Francisco Oliveira Benedetti",
"address": {
"street": "Avenida 13",
"number": "704",
"neighbourhood": "Centro",
"city": "Ituiutaba",
"uf": "MG",
"complement": "Apt 1101",
"postal_code": "38300-140"
},
"phone": {
"international_dial_code": "55",
"area_code": "16",
"number": "981610077",
"type": "mobile"
},
"account": {
"participant": "60701190",
"branch": "3675",
"account_number": "10442",
"account_digit": "6",
"account_type": "CACC"
}
},
"source": {
"channel": "internet_banking",
"platform": "android",
"ip": "198.185.056.098",
"session_id": "7839jdqd9a8wd9"
}
}
```
A bankslip payment must be sent to the API before being forwarded to the processing system in order to perform a prior fraud validation.
The payment status represents the decision returned by the model regarding that bankslip. The following statuses are used in the **analysis_status** flag:
* `automatically_approved`
* `automatically_reproved`
* `in_manual_analysis`
* `pending`
Below are the meanings of each decision returned in the analysis_status flag:
status | description
:----: | ---------
automatically_approved | It is recommended that this bankslip payment be approved.
automatically_reproved | It is recommended that this bankslip payment be reproved.
in_manual_analysis | It is recommended that this bankslip payment be analyzed manually.
pending | The bankslip payment is being processed.
name | type | description
:----: | :----: | ---------
id | string | Transaction identifier in the client's system. **It is essential that this number is unique for each bankslip payment**
bankslip_direction | enumerator | Bankslip payment modality. Defines whether the client is payer or the receiver of the bankslip operation
document_amount | integer | Document amount in cents - as described in the "Standards" section.
discount_amount | integer | Discount or abatement amount applied to the document value in cents - as described in the "Standards" section.
other_deduction_amount | integer | Value of other deductions applied to the document value in cents - as described in the "Standards" section.
interest_amount | integer | Value of fines, late fees, or interest applied to the document value in cents - as described in the "Standards" section.
amount | integer | Final amount paid on the bankslip - as described in the "Standards" section.
bankslip_payment_date | datetime | The date and time of the bankslip payment, with time zone.
bankslip_due_date | date | Bankslip due date according to standardization.
bankslip_issuing_date | date | Bankslip issuance date according to standardization.
description | string | Description or remarks field of the bankslip.
face_recognition_key | string | Facial recognition key, if facial recognition was performed by our facial recognition API.
validation_key | string | Validation key, if any client validation test was performed in our validation API.
payer | *bankslip_payer* | Object representing the individual (natural person) or legal entity that paid the bankslip.
recipient | *bankslip_recipient* | Object representing the individual (natural person) or legal entity beneficiary of the bankslip.
final_recipient | *bankslip_recipient* | Object representing the individual (natural person) or legal entity final beneficiary of the bankslip.
source | *source* | Source type object describing information coming from the application used for the bankslip payment.
The following enumerators exist for *bankslip_direction*: `payed` and `received`.
## Send a BankSlip Payment
Request Body
```json
{
"id": "12345",
...
}
```
Response Body
```json
{
"bankslip_key": "13d680ef-4b72-4cb2-a63d-cf3d790abaaf",
"status": "automatically_approved",
"reason": "rule_decision_enum"
}
```
To perform the evaluation of a bankslip payment, simply send a BankSlip object to the following endpoint:
`POST https://api.caas.qitech.app/bankslip/bankslip`
## Retrieve a BankSlip Payment
Response Body
```json
{
"id": "082373263",
"bankslip_direction": "received",
...
}
```
To retrieve data from a bankslip payment, simply send a request to the following endpoint:
`GET https://api.caas.qitech.app/bankslip/bankslip/{bankslip_id}`
Where *bankslip_id* is the transaction identifier in the client's system used when sending the bankslip.
## Update a BankSlip Payment
Request Body
```json
{
"bankslip_status": "completed",
"event_date": "2020-10-07T15:06:25-03:00"
}
```
Response Body
```json
{
"bankslip_key": "13d680ef-4b72-4cb2-a63d-cf3d790abaaf",
"bankslip_status": "completed"
}
```
After a bankslip payment is created and analyzed, it will be sent to the clearing house to be processed. Thus, it is necessary to report the payment status updates when it is sent, via the endpoint:
`PUT https://api.caas.qitech.app/bankslip/bankslip/{bankslip_id}`
In this way, it is guaranteed that our database is updated and we are able to identify bankslip payments that are actually susceptible to fraud.
---
# Bill Payment
URL: /en/documentation/caas/banking/bill_payments
When a user performs a bill payment, the payment details must be sent to QI Tech. This enables a risk analysis of the operation using the provided data.
## Bill Payment Object Definition
Request Body
```json
{
"id": "082373263",
"amount": 12979,
"bill_payment_date": "2020-10-07T15:06:25-03:00",
"bill_due_date": "2020-10-07",
"bill_issuing_date": "2020-10-07",
"service_description": "CONTA DE ELETRICIDADE ENEL",
"face_recognition_key": "ef39e206-13d5-48de-b368-6c3bbc6f0222",
"validation_key": "69a59de3-0198-4a26-933a-c1de624c147d",
"company": {
"id": "451673263",
"provided_service": "eletricity",
"name" : "Enel",
"legal_name": "Eletropaulo Metropolitana Eletricidade de São Paulo S.A.",
"document_number": "61.695.227/0001-93",
"address": {
"street": "Av. Dr. Marcos Penteado de Ulhôa Rodrigues",
"number": "939",
"neighbourhood": "Sítio Tamboré",
"city": "Barueri",
"uf": "SP",
"complement": "Loja 1 e 2",
"postal_code": "06460-040"
}
},
"payer": {
"id": "182373263",
"type": "legal_person",
"document_number": "07.487.735/0001-69",
"name": "Gioconda Pizzaria e Rotisseria LTDA.",
"email": "gioconda_pizza@bol.com.br",
"address": {
"street": "Avenida 13",
"number": "704",
"neighbourhood": "Centro",
"city": "Ituiutaba",
"uf": "MG",
"complement": "Apt 1101",
"postal_code": "38300-140"
},
"phone": {
"international_dial_code": "55",
"area_code": "16",
"number": "981610077",
"type": "mobile"
},
"account": {
"participant": "60701190",
"branch": "3675",
"account_number": "13212",
"account_digit": "5",
"account_type": "CACC"
},
"sales_channel": "inbound_sales",
"segment": "Personalité"
},
"source": {
"channel": "internet_banking",
"platform": "android",
"ip": "198.185.105.098",
"session_id": "7839jdqd9a8wd9"
}
}
```
A bill payment must be submitted to the API for preliminary fraud validation before being forwarded to the processing system.
The payment status represents the decision returned by the model regarding that bill. The following statuses are used in the **analysis_status** flag:
* `automatically_approved`
* `automatically_reproved`
* `in_manual_analysis`
* `pending`
Below are the meanings of each decision returned in the analysis_status flag:
status | description
:----: | ---------
automatically_approved | It is recommended that this bill payment be approved.
automatically_reproved | It is recommended that this bill payment be reproved.
in_manual_analysis | It is recommended that this bill payment be analyzed manually.
pending | The bill payment is being processed.
name | type | description
:----: | :----: | ---------
id | string | Transaction identifier in the client's system. **It is essential that this number is unique for each bill payment**
document_amount | integer | Document amount in cents - as described in the "Standards" section.
other_deduction_amount | integer | Value of other deductions applied to the document value in cents - as described in the "Standards" section.
interest_amount | integer | Value of fines, late fees, or interest applied to the document value in cents - as described in the "Standards" section.
amount | integer | Final amount paid on the bill - as described in the "Standards" section.
bill_payment_date | datetime | The date and time of the bill payment, with time zone.
bill_due_date | date | Bill due date according to standardization.
description | string | Description or remarks field of the bill.
face_recognition_key | string | Facial recognition key, if facial recognition was performed by our facial recognition API.
validation_key | string | Validation key, if any client validation test was performed in our validation API.
client | *client* | Object representing the client's data, whether they are paying or receiving the payment.
company | *company* | Object representing the utility company or service provider related to that bill.
payer | *bill_payer* | Object representing the individual (natural person) or legal entity that paid the bill.
recipient | *bill_client* | Object representing the individual (natural person) or legal entity for whom the bill was issued.
source | *source* | Source type object describing information coming from the application used for the bill payment.
## Send a Bill Payment
Request Body
```json
{
"id": "12345",
...
}
```
Response Body
```json
{
"bill_payment_key": "13d680ef-4b72-4cb2-a63d-cf3d790abaaf",
"status": "automatically_approved",
"reason": "rule_decision_enum"
}
```
To perform the evaluation of a bill payment, simply send a BillPayment object to the following endpoint:
`POST https://api.caas.qitech.app/bill_payment/bill_payment`
## Retrieve a Bill Payment
Response Body
```json
{
"id": "082373263",
"amount": 12979,
...
}
```
To retrieve data from a bill payment, simply send a request to the following endpoint:
`GET https://api.caas.qitech.app/bill_payment/bill_payment/{bill_payment_id}`
Where *bill_payment_id* is the transaction identifier in the client's system used when sending the bill payment.
## Update a Bill Payment
Request Body
```json
{
"bill_payment_status": "completed",
"event_date": "2020-10-07T15:06:25-03:00"
}
```
Response Body
```json
{
"bill_payment_key": "13d680ef-4b72-4cb2-a63d-cf3d790abaaf",
"bill_payment_status": "completed"
}
```
After a bill payment is created and analyzed, it is sent to the clearing house for processing. Therefore, you must report payment status updates via the endpoint:
`PUT https://api.caas.qitech.app/bill_payment/bill_payment/{bill_payment_id}`
This ensures that our database remains updated, allowing us to accurately identify payments that are genuinely susceptible to fraud.
---
# Deposits
URL: /en/documentation/caas/banking/deposits/introduction
At the moment a user performs a deposit, the deposit data must be sent to QI Tech. This enables a fraud risk and Anti-Money Laundering analysis of the operation based on that dataset.
## Deposit Object Definition
Request Body
```json
{
"id": "082373263",
"amount": 12979,
"deposit_date": "2020-10-07T15:06:25-03:00",
"client": {
"id": "182373263",
"type": "natural_person",
"document_number": "123.456.789-10",
"name": "Benedito Calixto de Jesus",
"email": "benedito@test.com",
"address": {
"street": "Rua José Wasth Rodrigues",
"number": "243",
"neighbourhood": "Vila Maria",
"city": "São Paulo",
"uf": "SP",
"complement": "Apartamento 14B",
"postal_code": "02121-010"
},
"phone": {
"international_dial_code": "55",
"area_code": "11",
"number": "998861708",
"type": "mobile"
},
"sales_channel": "inbound_sales",
"segment": "Personalité"
},
"destination_account": {
"participant": "17315359",
"branch": "0000",
"account_number": "10442",
"account_digit": "6",
"account_type": "CACC",
"opening_date": "2020-01-15T18:00:00-03:00"
},
"terminal": {
"id": "1234566",
"latitude": -45.2753548,
"longitude": -15.24587,
"address": {
"street": "Av. Eng. Luis Carlos Berrini",
"number": "105",
"neighbourhood": "Brooklin",
"city": "São Paulo",
"uf": "SP",
"complement": "Cj 303",
"postal_code": "04501-140"
},
"type": "atm"
},
"authentication": {
"used_password": true,
"used_card": true,
"used_fingerprint": true,
"typed_account_number": false
}
}
```
A deposit must be sent to the API for preliminary fraud validation before being forwarded to the processing system.
The deposit status represents the decision returned by the model regarding that account. The following statuses are used in the **analysis_status** flag:
* `automatically_approved`
* `automatically_reproved`
Below are the meanings of each decision returned in the analysis_status flag:
status | description
:----: | ---------
automatically_approved | It is recommended that this deposit be approved.
automatically_reproved | It is recommended that this deposit be reproved.
name | type | description
:----: | :----: | ---------
id | string | Deposit identifier in the client's system. **It is essential that this number is unique for each deposit**
amount | integer | Deposit amount in cents - as described in the "Standards" section.
deposit_date | datetime | Date and time of the deposit execution - as described in the "Standards" section.
client | *client* | Object containing the data of the client holding the source account.
destination_account | *account* | Object determining the destination account of the funds to be deposited.
terminal | *terminal* | Object containing the data of the terminal where the deposit is being performed.
authentication | *authentication* | Object containing the authentication information.
## Deposit Objects
### Terminal Object
Request Body
```json
{
"id": "1234566",
"latitude": -45.2753548,
"longitude": -15.24587,
"address": {
"street": "Av. Eng. Luis Carlos Berrini",
"number": "105",
"neighbourhood": "Brooklin",
"city": "São Paulo",
"uf": "SP",
"complement": "Cj 303",
"postal_code": "04501-140"
},
"type": "atm"
}
```
Object representing the terminal that was used for the deposit.
name | type | description
:----: | :----: | ---------
id | string | Terminal identifier in the client's system.
latitude | number | Latitude, in degrees, of the terminal's location.
longitude | number | Longitude, in degrees, of the terminal's location.
address | *address* | Terminal address.
type | enum | Terminal type, possible values: "atm", "counter".
### Authentication Object
Request Body
```json
{
"used_password": true,
"used_card": true,
"used_fingerprint": true,
"typed_account_number": false
}
```
Object defining the authentication parameters used at the time of deposit.
name | type | description
:----: | :----: | -----------
used_password | boolean | Determines if the user used a password.
used_card | boolean | Determines if the user has the card present during authentication.
used_card_chip_and_pin | boolean | Determines if the user used the card's chip and PIN.
used_card_magnetic_stripe | boolean | Determines if the user used the card's magnetic stripe.
used_fingerprint | boolean | Determines if the user used a fingerprint.
typed_account_number | boolean | Determines if the user typed the account data.
## Send a Deposit
Request Body
```json
{
"id": "12345",
...
}
```
Response Body
```json
{
"id": "082373263",
"analysis_status": "automatically_approved",
"reason": "2019-10-01T10:37:25-03:00"
}
```
To perform the evaluation of a deposit, simply send a deposit object to the following endpoint:
`POST https://api.caas.qitech.app/deposit/deposit`
## Retrieve a Deposit
Response Body
```json
{
"id": "082373263",
"analysis_status": "automatically_approved",
"reason": "2019-10-01T10:37:25-03:00"
}
```
To retrieve data from a deposit, simply send a request to the following endpoint:
`GET https://api.caas.qitech.app/deposit/deposit/{deposit_id}`
Where *deposit_id* is the transaction identifier in the client's system used when sending the deposit.
## Update a Deposit
Request Body
```json
{
"deposit_status": "completed",
"event_date": "2020-10-07T15:06:25-03:00"
}
```
Response Body
```json
{
"id": "082373263",
"deposit_status": "completed"
}
```
After a deposit is created and analyzed, the money will be made available to the user. This process may be interrupted by some other business rule. Thus, it is necessary to report deposit status updates when it is finalized, via the endpoint:
`PUT https://api.caas.qitech.app/deposit/deposit/{deposit_id}`
This ensures that our database remains updated, allowing us to accurately identify deposits that are genuinely susceptible to fraud.
---
# HTTP Status
URL: /en/documentation/caas/banking/http_status
All QI Tech APIs use the following standardization for HTTP return statuses, complying with RFC 7231 :
HTTP Status | Meaning | Description
---------- | ------- | ---------------------------------
400 | Bad Request | The sent request contains a formatting error. In most cases, we return an explanation of the error in the message body.
401 | Unauthorized | There was an authentication problem; check if the API Key is correct and in the correct header, according to the Authentication section.
403 | Forbidden | The accessed endpoint is for internal use and is not available for this API Key.
404 | Not Found | The requested data was not found using the provided key. This status is also returned when an invalid endpoint is requested.
405 | Method Not Allowed | The HTTP method used does not apply to the endpoint used.
406 | Not Acceptable | The data sent in the request body is invalid. In general, this means the data sent is not valid JSON.
409 | Conflict | The request ID corresponds to an ID already processed. This status is returned in the case of duplicate requests sent to the server.
500 | Internal Server Error | We had a problem processing this request; when this error is encountered, our specialists are automatically notified and start to work on a solution immediately.
503 | Service Unavailable | You have encountered an unavailability, whether planned or unplanned, of our server infrastructure.
---
# Introduction
URL: /en/documentation/caas/banking/introduction
Welcome to the QI Tech Banking API! This API grants access to fraud prevention functionality for bank operations and digital accounts, such as analyzing transfers, bill payments, and bankslip (boleto) payments.
Below, you can see the API implementation using cUrl. This provides examples that you can adapt to your preferred programming language.
## Problems?
We are not a company that hides behind an API! Contact our support team, and we will respond as quickly as possible. Feel free to call us if you need a quick answer!
### We Love Feedback
Even if you have already solved your problem or if it is very simple (even a typo or improper organization you noticed), send us an email. This helps us make the documentation increasingly practical so the next person won't have to go through the same struggles you did!
## Environments
We have two environments for our clients. The base URLs for the APIs are:
* Production - `https://api.caas.qitech.app/`
* Sandbox - `https://api.sandbox.caas.qitech.app/`
:::danger Important Warning!
Real data of individuals (natural persons) and/or legal entities must not be used in the QI Tech Sandbox environments.
:::
## Sandbox Environment Analysis
In the Sandbox environment, analyses are not charged and are responded to according to simplified rules.
In the case of *wire_transfers*, *bankslips*, *bill_payments*, and *pix*, the response provided will be based on the operation value (*amount*) sent in the request:
minimum | maximum | decision
------- | ------- | -------
16000 | - | Automatically Contested*
10000 | 15999 | Automatically Approved
6000 | 9999 | Forwarded for Manual Analysis
0 | 5999 | Automatically Reproved
\* Automatically Contested is available only for the *pix* service.
In the case of *withdrawal* and *deposit*, the response provided will be based on the operation value (*amount*) sent in the request:
minimum | maximum | decision
------- | ------- | -------
10000 | - | Automatically Approved
0 | 9999 | Automatically Reproved
In the case of DICT operations, the response provided will be based on the DICT link key (*dict_key*) sent in the request:
Key in Dict | decision
:----------: | -------
"Approve_dict_key" | Automatically Approved
Any other string | Forwarded for Manual Analysis
"Reprove_dict_key" | Automatically Reproved
## HTTPS Only
For security reasons, all communication with QI Tech APIs must be performed using HTTPS communication. To prevent HTTP calls from being made due to inattention or other reasons, this server only makes port 443 available with TLS 1.2 communication. Calls made using other protocols will be automatically denied.
## Workflows - Transfers
The transfer analysis flow is initiated in two situations:
- A transfer is being made by the PSP user
- A transfer is being received by the PSP user
In both cases, a call to the *wire_transfer* endpoint must be made, and the possible resulting statuses are:
enumerator | description
:--------: | ---------
automatically_approved | Automatically Approved
automatically_reproved | Automatically Reproved
in_manual_analysis | Forwarded for Manual Analysis
pending | The bank transfer object is being processed.
If the transfer is forwarded for manual analysis, an analyst must approve or reject the transfer. At this moment, a Webhook can be generated to notify the PSP of the status change, or the PSP may track the transfer via Polling. In both cases, the following statuses may be returned:
enumerator | description
:--------: | ---------
manually_approved | Manually Approved
manually_reproved | Manually Reproved
## Workflows - Bankslips
The Bankslip analysis flow is initiated in two situations:
- A bankslip payment is being made by the PSP user
- A bankslip payment is being received by the PSP user
In both cases, a call to the *bankslip* endpoint must be made, and the possible resulting statuses are:
enumerator | description
:--------: | ---------
automatically_approved | Automatically Approved
automatically_reproved | Automatically Reproved
in_manual_analysis | Forwarded for Manual Analysis
pending | The bankslip object is being processed.
If the bankslip payment is forwarded for manual analysis, an analyst must approve or reject the payment. At this moment, a Webhook may be generated to notify the PSP of the status change, or the PSP may track the payment via Polling. In both cases, the following statuses may be returned:
enumerator | description
:--------: | ---------
manually_approved | Manually Approved
manually_reproved | Manually Reproved
## Workflows - Bill Payments
The Bill Payment analysis flow is initiated when:
- A bill payment is being made by the PSP user
In this case, a call to the *bill_payment* endpoint must be made, and the possible resulting statuses are:
enumerator | description
:--------: | ---------
automatically_approved | Automatically Approved
automatically_reproved | Automatically Reproved
in_manual_analysis | Forwarded for Manual Analysis
pending | The bill payment object is being processed.
If the bill payment is forwarded for manual analysis, an analyst must approve or reject the payment. At this moment, a Webhook may be generated to notify the PSP of the status change, or the PSP may track the payment via Polling. In both cases, the following statuses may be returned:
enumerator | description
:--------: | ---------
manually_approved | Manually Approved
manually_reproved | Manually Reproved
## Workflows - Withdrawals
The Withdrawal analysis flow is initiated in the following situation:
- A withdrawal is being made by the PSP user
In this case, a call to the *withdrawal* endpoint must be made, and the possible resulting statuses are:
enumerator | description
:--------: | ---------
automatically_approved | Automatically Approved
automatically_reproved | Automatically Reproved
If the withdrawal is forwarded for manual analysis, an analyst must approve or reject the withdrawal. At this moment, a Webhook may be generated to notify the PSP of the status change, or the PSP may track the payment via Polling. In both cases, the following statuses may be returned:
enumerator | description
:--------: | ---------
manually_approved | Manually Approved
manually_reproved | Manually Reproved
## Workflows - PIX Transaction
The PIX payment flow is initiated in two situations:
- A payment being made by the PSP user integrated with QI Tech
- A payment being received from another PSP
In both cases, a call to the payment endpoint must be made, and the possible resulting statuses are:
enumerator | description
:--------: | ---------
automatically_approved | Automatically Approved
automatically_reproved | Automatically Reproved
in_manual_analysis | Forwarded for Manual Analysis
If the payment is forwarded for manual analysis, an analyst must approve or reject the payment. At this moment, a Webhook may be generated to notify the PSP of the status change, or the PSP may track the payment via Polling. In both cases, the following statuses may be returned:
enumerator | description
:--------: | ---------
manually_approved | Manually Approved
manually_reproved | Manually Reproved
## Workflows - DICT Changes
The DICT alteration flow is initiated in two situations:
- The PSP user integrated with QI Tech requests a registration/change/portability/claim to the PSP integrated with QI Tech
- A portability/claim is received by the PSP integrated with QI Tech
For registrations initiated by the PSP user, the key validation flow must be executed before the alteration in DICT, using QI Tech's validation APIs. If the validation is performed by the PSP itself, this information can also be sent in the request to QI Tech.
To start the process in these two moments, the PSP integrated with QI Tech must make a call to the appropriate endpoint, which will respond with one of the following statuses:
enumerator | description
:--------: | ---------
automatically_approved | Automatically Approved
automatically_reproved | Automatically Reproved
in_manual_analysis | Forwarded for Manual Analysis
If the alteration is forwarded for manual analysis, an analyst must approve or reject the alteration. At this moment, a Webhook may be generated to notify the PSP of the status change, or the PSP may track the alteration via Polling. In both cases, the following statuses may be returned:
enumerator | description
:--------: | ---------
manually_approved | Manually Approved
manually_reproved | Manually Reproved
## Authentication
> To authenticate a call, use the following code:
```shell
# In the shell, you only need to add the appropriate header to each request
curl "api_endpoint_here"
-H "Authorization: EXAMPLE_API_KEY"
```
> Replace the API key 'EXAMPLE_API_KEY' with the key acquired from our support.
We use an API Key to allow access to our API. It has likely already been sent to you by email. If you have not yet received your key, send an email to suporte.caas@qitech.com.br .
Our API expects to receive the API Key in all requests to our server in a header like the one below:
`Authorization: EXAMPLE_API_KEY`
:::info **Attention**
You must replace EXAMPLE_API_KEY with the API Key received from support.
:::
---
# Shared Objects
URL: /en/documentation/caas/banking/objects
A significant portion of data is shared among different account events. The definitions of these objects can be easily located below.
## Client Object
Request Body
```json
{
"id": "123456",
"type": "natural_person",
"document_number": "023.456.789-01",
"name": "John Payer",
"email": "john@payer.com",
"address": {
"street": "Av. Eng. Luis Carlos Berrini",
"number": "105",
"neighbourhood": "Brooklin",
"city": "São Paulo",
"uf": "SP",
"complement": "Cj 303",
"postal_code": "04501-140"
},
"phone": {
"international_dial_code": "55",
"area_code": "11",
"number": "998861708",
"type": "mobile"
},
"sales_channel": "inbound_sales",
"segment": "Personalité"
}
```
Object representing the account holder's data.
name | type | description
:----: | :----: | ---------
type | enum *(mandatory)* | Client type: "natural_person" or "legal_person"
document_number | string *(mandatory)* | Document number, in accordance with the standardization section.
name | string *(mandatory)* | Client name.
email | string | Client email.
address | *address* | Client address data.
phone | *phone* | Client phone data.
sales_channel | enum *(mandatory)*| Channel through which the client registered.
segment | string *(mandatory)*| Client segment within the institution (e.g., premium, gold).
The following enumerators exist for phone type: `inbound_sales`, `app`, `website`, `call_center`, and `branch`.
## Address Object
Request Body
```json
{
"street": "Rua do Teste",
"number": "111",
"neighbourhood": "Bairro do Exemplo",
"city": "Aparecida de Goiânia",
"uf": "GO",
"complement": "Térreo",
"postal_code": "00000-000",
"country": "BRA"
}
```
The *address* object is used to represent addresses throughout the API. Addresses within Brazilian territory are represented as follows:
name | type | description
---- | :----: | ---------
street | string *(mandatory)* | Street name, including the public place type, avoiding abbreviations if possible.
number | string *(mandatory)* | Property number, including letters if applicable.
neighbourhood | string *(mandatory)*| Neighborhood, without abbreviations. **e.g.: Santa Felicidade**
city | string *(mandatory)*| Full city name, without abbreviations.
uf | string *(mandatory)* | The federative unit (state), with two uppercase letters. **e.g.: SP**
complement | string | Any supplements to locate the property. **e.g.: Apartamento 101, Conjunto 12**
postal_code | string *(mandatory)* | The locality's postal code, including the hyphen.
country | string *(mandatory)* | ISO 3166-1 alpha-3 code of the address country.
For addresses where the country is not Brazil ("BRA"), the postal_code and federative unit may be filled in freely.
## Phone Object
Request Body
```json
{
"international_dial_code": "1",
"area_code": "11",
"number": "999999999",
"type": "mobile"
}
```
A *phone* object represents a telephone number, inside or outside Brazil, and its classification. For this, the fields are:
name | type | description
---- | :----: | ---------
international_dial_code | string *(mandatory)* | International dialing code, without zero or +, numbers only.
area_code | string *(mandatory)* | Area code, without zero, numbers only.
number | string *(mandatory)* | Phone number, without the hyphen.
type | enum *(mandatory)* | Number type: mobile, residential, commercial, etc.
The following enumerators exist for phone type: `residential`, `commercial`, and `mobile`.
## Account Object
Request Body
```json
{
"participant": "17315359",
"branch": "0000",
"account_number": "10442",
"account_digit": "6",
"account_type": "CACC",
"opening_date": "2020-01-15T18:00:00-03:00"
}
```
Object representing an account's data.
name | type | description
:----: | :----: | ---------
participant | string *(mandatory)* | ISPB of the institution holding the account.
branch | string *(mandatory)* | Account Branch.
account_number | string *(mandatory)* | Account Number without the digit.
account_digit | string *(mandatory)* | Account digit.
account_type | enum *(mandatory)* | Source account type, possible values: "CACC", "SLRY", and "SVGS".
opening_date | datetime | Account opening date.
## Source Object
Request Body
```json
{
"channel": "app",
"platform": "android",
"ip":"255.201.26.1",
"session_id": "54b8e3cf-15de-41e5-9305-0ecf059d6e2a"
}
```
The source object represents the set of information regarding the platform used by the user to perform the operation. The fields are:
name | type | description
:----: | :----: | ---------
channel | string | Channel used by the user to perform the operation, e.g., internet banking, app.
platform | string | Platform used by the application.
ip | string | IP collected from the device.
session_id | string | Unique session identifier, used to cross-reference the Device Scan with the event in question.
## Dict Key Object
Request Body
```json
{
"key_type": "cpf",
"key_value": "09991222669",
"assignment_date": "2020-01-15T18:00:00-03:00"
}
```
The **dict_key** object is used to represent the client's DICT link key data, whether they are the receiver or the payer of the transaction. The fields of this object are:
name | type | description
:----: | :----: | ---------
key_type | string *(mandatory)* | Enumerator containing the DICT link key type.
key_value | string | Contains the link key registered in DICT.
assignment_date | datetime | Date the link key was registered in DICT.
The enumerators for the *key_type* field are the same as those defined in the DICT API: `cpf`, `cnpj`, `email`, `phone`, and `evp`.
## Destination Statistics Object
Request Body
```json
{
"account":{
"settlements":{
"d3":4,
"d30":67,
"m6":618
},
"rejected":{
"d3":4,
"d30":67,
"m6":618
},
"reported_frauds":{
"d3":0,
"d30":0,
"m6":0
},
"reported_aml_cft":{
"d3":0,
"d30":0,
"m6":0
},
"confirmed_frauds":{
"d3":0,
"d30":0,
"m6":0
},
"confirmed_aml_cft":{
"d3":0,
"d30":0,
"m6":0
}
},
"owner":{
"settlements":{
"d3":6,
"d30":88,
"m6":996
},
"rejected":{
"d3":4,
"d30":67,
"m6":618
},
"reported_frauds":{
"d3":0,
"d30":0,
"m6":0
},
"reported_aml_cft":{
"d3":0,
"d30":0,
"m6":0
},
"confirmed_frauds":{
"d3":0,
"d30":0,
"m6":0
},
"confirmed_aml_cft":{
"d3":0,
"d30":0,
"m6":0
}
},
"key":{
"settlements":{
"d3":3,
"d30":51,
"m6":312
},
"rejected":{
"d3":4,
"d30":67,
"m6":618
},
"reported_frauds":{
"d3":0,
"d30":0,
"m6":0
},
"reported_aml_cft":{
"d3":0,
"d30":0,
"m6":0
},
"confirmed_frauds":{
"d3":0,
"d30":0,
"m6":0
},
"confirmed_aml_cft":{
"d3":0,
"d30":0,
"m6":0
}
}
}
```
To evaluate the fraud risk of a transaction with greater precision, it is necessary to provide the transactional and fraud history of the payee via the *Destination Statistics* object. Such data can be obtained by querying the payee's link key in the DICT database. The Central Bank of Brazil (BACEN) requires that this data be used in the transaction fraud evaluation.
name | type | description
:----: | :----: | ---------
account | *account* *(mandatory)* | Object containing the transactional and fraud history of the payee's account.
owner | *owner* *(mandatory)* | Object containing the transactional and fraud history associated with the payee's document.
key | *key* *(mandatory)* | Object containing the transactional and fraud history associated with the key provided by the payee.
Where each of the objects defined above possesses the same fields:
name | type | description
:----: | :----: | ---------
settlements | *settlements* *(mandatory)* | Object containing the transactional history.
rejected | *rejected* *(optional)* | Object containing the history of rejected operations.
reported_frauds | *reported_frauds* *(mandatory)* | Object containing the history of fraud reports.
reported_aml_cft | *reported_aml_cft* *(optional)* | Object containing the history of AML/CFT reports.
confirmed_frauds | *confirmed_frauds* *(mandatory)* | Object containing the history of confirmed fraud reports.
confirmed_aml_cft | *confirmed_aml_cft* *(optional)* | Object containing the history of confirmed AML/CFT reports.
Where each of these objects contains the fields **d3**, **d30**, and **m6**, containing the number of occurrences in the last 3 days, 30 days, and 6 months, which are mandatory fields, respectively. Just as defined by the BCB DICT API.
---
# PIX Dict Operation
URL: /en/documentation/caas/banking/pix_dict_operations
At the moment a user initiates a change in DICT, the data must be sent to our server so that we can perform an analysis of the risk involved in that dataset.
## Dict Operation Object Definition
Request Body
```json
{
"id": "f58e8a19-429d-4e36-a010-ed00a323c2c5",
"dict_key": {
"key_type": "phone",
"key_value": "16981610077",
"assignment_date": "2020-01-15T18:00:00-03:00"
},
"dict_operation_direction": "claimer",
"dict_operation_reason": "user_requested",
"dict_operation_creation_date": "2020-10-14T18:00:00-03:00",
"dict_operation_type": "claim_portability",
"client": {
"id": "123456",
"document_number": "099.912.226-69",
"name": "João Jorge da Silva",
"type": "natural_person",
"address": {
"street": "Avenida 13",
"number": "704",
"neighbourhood": "Centro",
"city": "Ituiutaba",
"uf": "MG",
"complement": "Apt 1101",
"postal_code": "38300-140"
},
"phone": {
"international_dial_code": "55",
"area_code": "65",
"number": "988961210",
"type": "mobile"
},
"sales_channel": "inbound_sales",
"segment": "Personalité"
},
"source_account": {
"participant": "04184779",
"branch": "0001",
"account_number": "1122",
"account_digit": "6",
"owner": {
"type": "legal_person",
"document_number": "94.948.708/0001-12",
"name": "Irmão Soares Ferragista LTDA."
},
"account_type": "CACC",
"opening_date": "2020-01-15T18:00:00-03:00"
},
"destination_account": {
"participant": "00000000",
"branch": "3675",
"account_number": "10442",
"account_digit": "6",
"owner": {
"type": "natural_person",
"document_number": "099.912.226-69",
"name": "João Jorge da Silva"
},
"account_type": "SLRY",
"opening_date": "2020-01-15T18:00:00-03:00"
},
"destination_statistics": {
"account":{
"settlements":{
"d3":12,
"d30":65,
"m6":344
},
"rejected":{
"d3":4,
"d30":67,
"m6":618
},
"reported_frauds":{
"d3":0,
"d30":0,
"m6":0
},
"reported_aml_cft":{
"d3":0,
"d30":0,
"m6":0
},
"confirmed_frauds":{
"d3":0,
"d30":0,
"m6":0
},
"confirmed_aml_cft":{
"d3":0,
"d30":0,
"m6":0
}
},
"owner":{
"settlements":{
"d3":4,
"d30":12,
"m6":88
},
"rejected":{
"d3":4,
"d30":67,
"m6":618
},
"reported_frauds":{
"d3":0,
"d30":0,
"m6":0
},
"reported_aml_cft":{
"d3":0,
"d30":0,
"m6":0
},
"confirmed_frauds":{
"d3":0,
"d30":0,
"m6":0
},
"confirmed_aml_cft":{
"d3":0,
"d30":0,
"m6":0
}
},
"key":{
"settlements":{
"d3":1,
"d30":6,
"m6":12
},
"rejected":{
"d3":4,
"d30":67,
"m6":618
},
"reported_frauds":{
"d3":0,
"d30":0,
"m6":0
},
"reported_aml_cft":{
"d3":0,
"d30":0,
"m6":0
},
"confirmed_frauds":{
"d3":0,
"d30":0,
"m6":0
},
"confirmed_aml_cft":{
"d3":0,
"d30":0,
"m6":0
}
}
},
"source": {
"channel": "internet_banking",
"platform": "android",
"ip": "198.185.065-98",
"session_id": "7839jdqd9a8wd9"
}
}
```
A Dict Operation must be submitted to the API for preliminary registration fraud validation before being forwarded to the BCB processing system.
The analysis status of the Dict Operation represents the decision returned by the model regarding that operation. The following statuses are used in the **analysis_status** flag:
* `automatically_approved`
* `automatically_reproved`
* `in_manual_analysis`
* `pending`
Below are the meanings of each decision returned in the analysis_status flag:
status | description
:----: | ---------
automatically_approved | It is recommended that this operation be approved.
automatically_reproved | It is recommended that this operation be reproved.
in_manual_analysis | It is recommended that the operation be analyzed manually by an analyst.
pending | The operation is being processed.
name | type | description
:----: | :----: | ---------
id | string | Operation identifier in the client's system. **It is essential that this number is unique for each authorization process**
client | *client* | Object representing the client's data, whether they are the donor or the claimer.
transaction_date | datetime | The transaction start date and time, with time zone.
dict_key | *dict_key* | Object representing the DICT link key data used by the client in the transaction.
dict_key_type | enumerator | DICT link key type.
dict_operation_direction| enumerator | Operation direction in DICT, i.e., whether a key is being donated or claimed.
dict_operation_reason | enumerador | The reason why the Dict Operation is being performed.
dict_operation_creation_date | datetime | Date of the operation in DICT.
dict_operation_type | enumerador | Type of operation in DICT.
source_account | *source_account* | Object representing the data of the account that is donating the link key.
destination_account | *destination_account* | Object representing the data of the account that is receiving the link key.
destination_statistics | *destination_statistics* | Object representing the transaction and fraud history of the account receiving the link key.
source | *source* | Source type object describing the information coming from the application used to send the registration.
The *dict_key_type* field accepts the same enumerators defined in the DICT API: `cpf`, `cnpj`, `email`, `phone`, and `evp`.
The *dict_operation_direction* field accepts the enumerators: `donor` and `claimer`.
The *dict_operation_type* field accepts the enumerators `registration`, `claim_ownership`, and `claim_portability`.
These being all types of DICT operations defined by the BCB.
## Send a Dict Operation
Request Body
```json
{
"id": "f58e8a19-429d-4e36-a010-ed00a323c2c5",
...
}
```
Response Body
```json
{
"dict_operation_key": "7f85e162-5a7d-41fa-a578-69df6f3df958",
"status": "automatically_approved"
}
```
To perform the evaluation of an operation, simply send a Dict Operation object to the following endpoint:
`POST https://api.caas.qitech.app/pix/dict_operation`
## Retrieve a Dict Operation
Response Body
```json
{
"id": "f58e8a19-429d-4e36-a010-ed00a323c2c5",
...
}
```
To retrieve a Dict Operation, simply send a request to the following endpoint:
`GET https://api.caas.qitech.app/pix/dict_operation/{dict_operation_id}`
Where *dict_operation_id* is the operation identifier sent to us at the time of its registration, in the "id" field.
The Dict Operation object associated with the provided key will then be returned.
## Update a Dict Operation
Request Body
```json
{
"dict_operation_status": "cancelled_by_client",
"reason": "user_requested",
"event_date": "2020-10-07T15:06:25-03:00"
}
```
A Dict Operation goes through several phases with the BCB before completion. Thus, it is necessary to report all operation status updates via the endpoint:
`PUT https://api.caas.qitech.app/pix/dict_operation/{dict_operation_id}`
This ensures that our database is updated and always consistent with the BCB database.
Some operations in DICT require that the reason for the operation be submitted along with the data. For these cases, it is necessary to provide the *reason* field in the submission object, containing the same enumerator provided to the BCB system.
These are:
enumerator | description
:--------: | ---------
user_requested | The operation was requested by the client.
account_closure | The operation was initiated due to the client's account closure.
branch_transfer | The operation was requested due to the client's branch change.
entry_inactivity | The operation was requested due to inactivity in the client's account.
reconciliation | The operation was requested following a reconciliation process.
default_operation | The operation was requested by a default action of the participant.
fraud | The operation was requested due to fraud linked to the client's account.
The phases of a DICT operation accepted by the *dict_operation_status* field are:
enumerator | description
:--------: | ---------
created | The dict_operation was created but has not yet been analyzed.
reproved | The dict_operation was reproved in the analysis and will not be sent to the BCB.
waiting_resolution | The dict_operation was sent to the BCB and is awaiting resolution.
cancelled_by_client | The dict_operation was cancelled by the client.
cancelled_by_counterpart | The dict_operation was cancelled by the other party of the operation.
confirmed | The dict_operation was confirmed by the other party of the operation.
completed | The dict_operation was completed and added to the BCB database.
---
# PIX Infraction Report
URL: /en/documentation/caas/banking/pix_infraction_reports
## Infraction Report Object Definition
Request Body
```json
{
"infraction_report_type": "compliance",
"infraction_report_details": "Cliente realizou várias compras de valor alto em estabelecimentos comerciais cuja atividade econômica é de alto risco de lavagem de dinheiro. Após uma investigação minuciosa, decidiu-se realizar o report ao COAF e bloquear o saldo em conta até que a origem do dinheiro seja esclarecida. ",
"infraction_report_creator": "external",
"infraction_report_date": "2020-10-14T00:25:42-03:00",
"infraction_report_status": "received",
"infraction_report_events": [
{
"new_status": "received",
"event_date": "2020-10-14T00:25:42-03:00"
}
]
}
```
If suspicious behavior is detected by either party in a transaction, an Infraction Report can be created to report the suspicion. This report is then analyzed by the counterparty and may be confirmed or rejected. Following the standard established by the BCB, an Infraction Report must contain the following fields:
name | type | description
:----: | :----: | ---------
infraction_report_type | enumerator | Enumerator defining the type of suspicious activity present in the transaction.
infraction_report_details | string | Details regarding the circumstances that led the creator of the Infraction Report to believe there might be an infraction associated with the transaction.
infraction_report_creator | enumerator | Enumerator defining who created the Infraction Report.
infraction_report_date | datetime | Date of the incident.
The *infraction_report_type* field may contain the enumerators: `fraud` and `compliance`.
The *infraction_report_creator* field may contain the enumerators: `client` and `external`.
## Send an Infraction Report
Request Body
```json
{
"infraction_report_type": "compliance",
"infraction_report_details": "Cliente realizou várias compras de valor alto em estabelecimentos comerciais cuja atividade econômica é de alto risco de lavagem de dinheiro. Após uma investigação minuciosa, decidiu-se realizar o report ao COAF e bloquear o saldo em conta até que a origem do dinheiro seja esclarecida. ",
"infraction_report_creator": "external",
"infraction_report_date": "2020-10-14T00:25:42-03:00"
}
```
Response Body
```json
{
"infraction_report_key": "7f85e162-5a7d-41fa-a578-69df6f3df958",
"infraction_report_status": "received"
}
```
To send an Infraction Report, simply send a request to the endpoint:
`POST https://api.caas.qitech.app/pix/transaction/{transaction_id}/infraction_report`
Where *transaction_id* is the transaction identifier sent to us at the time of its registration, in the "id" field.
## Retrieve an Infraction Report
Response Body
```json
{
"infraction_report_type": "compliance",
"infraction_report_details": "Cliente realizou várias compras de valor alto em estabelecimentos comerciais cuja atividade econômica é de alto risco de lavagem de dinheiro. Após uma investigação minuciosa, decidiu-se realizar o report ao COAF e bloquear o saldo em conta até que a origem do dinheiro seja esclarecida. ",
"infraction_report_creator": "external",
"infraction_report_date": "2020-10-14T00:25:42-03:00",
"infraction_report_status": "received",
"infraction_report_events": [
{
"new_status": "received",
"event_date": "2020-10-14T00:25:42-03:00"
}
],
"transaction_data": {
"transaction_direction": "received",
"id": "082373263",
...
}
}
```
To retrieve an Infraction Report, simply send a request to the following endpoint:
`GET https://api.caas.qitech.app/pix/transaction/{transaction_id}/infraction_report/{infraction_report_key}`
The Infraction Report object associated with the provided *transaction_id* and matching the *infraction_report_key* will then be returned.
## Update an Infraction Report
Request Body
```json
{
"infraction_report_status": "acknowledged",
"event_date": "2020-10-07T15:06:25-03:00"
}
```
An Infraction Report goes through several phases with the BCB before completion. Therefore, all Infraction Report status updates must be reported via the endpoint:
`PUT https://api.caas.qitech.app/pix/transaction/{transaction_id}/infraction_report/{infraction_report_key}`
---
# PIX Transaction
URL: /en/documentation/caas/banking/pix_transactions
At the moment a payer initiates or receives a payment, the transaction data must be sent to our server. This enables a risk analysis of the transaction based on that dataset.
## PIX Transaction Object Definition
Request Body
```json
{
"transaction_direction": "received",
"id": "082373263",
"client": {
"id": "123456",
"document_number": "056.966.649-03",
"name": "Francisco Oliveira Benedetti",
"type": "natural_person",
"address": {
"street": "Avenida 13",
"number": "704",
"neighbourhood": "Centro",
"city": "Ituiutaba",
"uf": "MG",
"complement": "Apt 1101",
"postal_code": "38300-140"
},
"email": "mailto@qitech.com.br",
"phone": {
"international_dial_code": "55",
"area_code": "16",
"number": "981610077",
"type": "mobile"
},
"sales_channel": "inbound_sales",
"segment": "Personalité"
},
"amount": 13725,
"transaction_date": "2020-10-07T15:06:25-03:00",
"dict_key": {
"key_type": "cpf",
"key_value": "09991222669",
"assignment_date": "2020-01-15T18:00:00-03:00"
},
"capture_method": "static_qr_code",
"face_recognition_key": "ef39e206-13d5-48de-b368-6c3bbc6f0222",
"validation_key": "69a59de3-0198-4a26-933a-c1de624c147d",
"source_account": {
"participant": "17315359",
"branch": "0000",
"account_number": "10442",
"account_digit": "6",
"owner": {
"type": "legal_person",
"document_number": "07.487.735/0001-69",
"name": "Gioconda Pizzaria e Rotisseria LTDA."
},
"account_type": "CACC",
"opening_date": "2020-01-15T18:00:00-03:00"
},
"destination_account": {
"participant": "60701190",
"branch": "3675",
"account_number": "10442",
"account_digit": "6",
"owner": {
"type": "natural_person",
"document_number": "056.966.649-03",
"name": "Francisco Oliveira Benedetti"
},
"account_type": "SLRY",
"opening_date": "2020-01-15T18:00:00-03:00"
},
"destination_statistics": {
"person":{
"settlements":{
"d90":4,
"m12":67,
"m60":618
},
"application_frauds":{
"d90":0,
"m12":4,
"m60":9
},
"mule_accounts":{
"d90":0,
"m12":0,
"m60":0
},
"scammer_accounts":{
"d90":0,
"m12":0,
"m60":0
},
"other_frauds":{
"d90":0,
"m12":0,
"m60":0
},
"unknown_frauds":{
"d90":0,
"m12":0,
"m60":0
},
"total_frauds_transaction_amount":{
"d90":0,
"m12":0,
"m60":0
},
"distinct_fraud_reporters":{
"d90":0,
"m12":0,
"m60":0
},
"open_reports":0,
"open_reports_distinct_reporters":0,
"rejected_reports":{
"d90":0,
"m12":0,
"m60":0
},
"registered_accounts":0
},
"owner":{
"settlements":{
"d90":0,
"m12":0,
"m60":0
},
"application_frauds":{
"d90":0,
"m12":0,
"m60":0
},
"mule_accounts":{
"d90":0,
"m12":0,
"m60":0
},
"scammer_accounts":{
"d90":0,
"m12":0,
"m60":0
},
"other_frauds":{
"d90":0,
"m12":0,
"m60":0
},
"unknown_frauds":{
"d90":0,
"m12":0,
"m60":0
},
"total_frauds_transaction_amount":{
"d90":0,
"m12":0,
"m60":0
},
"distinct_fraud_reporters":{
"d90":0,
"m12":0,
"m60":0
},
"open_reports":0,
"open_reports_distinct_reporters":0,
"registered_accounts":0
},
"key":{
"settlements":{
"d90":0,
"m12":0,
"m60":0
},
"application_frauds":{
"d90":0,
"m12":0,
"m60":0
},
"mule_accounts":{
"d90":0,
"m12":0,
"m60":0
},
"scammer_accounts":{
"d90":0,
"m12":0,
"m60":0
},
"other_frauds":{
"d90":0,
"m12":0,
"m60":0
},
"unknown_frauds":{
"d90":0,
"m12":0,
"m60":0
},
"total_frauds_transaction_amount":{
"d90":0,
"m12":0,
"m60":0
},
"distinct_fraud_reporters":{
"d90":0,
"m12":0,
"m60":0
},
"open_reports":0,
"open_reports_distinct_reporters":0,
"rejected_reports":{
"d90":0,
"m12":0,
"m60":0
},
"distinct_accounts":{
"d90":0,
"m12":0,
"m60":0
}
}
},
"source": {
"channel": "internet_banking",
"platform": "android",
"ip": "198.185.065.098",
"session_id": "7839jdqd9a8wd9"
}
}
```
A transaction must be sent to the API for prior fraud validation before being forwarded to the processing system.
The transaction status represents the decision returned by the model regarding that transaction. The following statuses are used in the **analysis_status** flag:
* `automatically_approved`
* `automatically_reproved`
* `in_manual_analysis`
* `pending`
Below are the meanings of each decision returned in the analysis_status flag:
status | description
:----: | ---------
automatically_approved | It is recommended that this transaction be approved.
automatically_reproved | It is recommended that this transaction be reproved.
approved_by_time | The transaction was approved due to manual analysis time expiration.
reproved_by_time | The transaction was reproved due to manual analysis time expiration.
in_manual_analysis | It is recommended that the transaction be analyzed manually by an analyst.
pending | The transaction is being processed.
name | type | description
:----: | :----: | ---------
transaction_direction | enumerator | Registered transaction type. Defines whether the client is receiving or sending money. *(mandatory)*
id | string | Payment identifier in the client's system. **It is essential that this number is unique for each payment process** *(mandatory)*
client | *client* | Object representing the client's data, whether they are the payer or the receiver. *(mandatory)*
amount | integer | The payment amount in cents - as described in the "Standards" section. *(mandatory)*
pix_modality | string | Registered transaction type. Indicates if it represents a transfer, change (troco), or withdrawal.
transaction_date | datetime | The transaction start date and time, with time zone. *(mandatory)*
dict_key | *dict_key* | Object representing the DICT link key data used by the client in the transaction.
capture_method | enumerator | Method used for payment initiation, whether via static or dynamic QR Code, data entry, or DICT key. *(mandatory)*
face_recognition_key | string | Facial recognition key, if facial recognition was performed by our facial recognition API.
validation_key | string | Validation key, if any client validation test was performed in our validation API.
source_account | *source_account* | Object representing the debited account data. *(mandatory)*
destination_account | *destination_account* | Object representing the credited account data. *(mandatory)*
destination_statistics | *destination_statistics* | Object representing the transaction and fraud history of the credited account originating from the BACEN DICT API. *(mandatory)*
source | *source* | Source type object describing information coming from the application used for sending the payment.
The following enumerators exist for *transaction_direction*: `sent` and `received`.
The following enumerators exist for *pix_modality*: `transaction`, `change`, and `withdraw`.
The following enumerators exist for *capture_method*: `static_qr_code`, `dynamic_qr_code`, `offline_qr_code`, `typed`.
## Send a Transaction
Request Body
```json
{
"id": "12345",
...
}
```
Response Body
```json
{
"transaction_key": "13d680ef-4b72-4cb2-a63d-cf3d790abaaf",
"analysis_status": "automatically_approved",
"reason": "rule_decision_enum"
}
```
To perform the evaluation of a transaction, simply send a Transaction object to the following endpoint:
`POST https://api.caas.qitech.app/pix/transaction`
## Retrieve a Transaction
Response Body
```json
{
"transaction_direction": "received",
"id": "082373263",
...
}
```
To retrieve data from a transaction, simply send a request to the following endpoint:
`GET https://api.caas.qitech.app/pix/transaction/{transaction_id}`
Where *transaction_id* is the transaction identifier sent to us at the time of its registration, in the "id" field.
## Update a Transaction
Request Body
```json
{
"transaction_status": "sent",
"event_date": "2020-10-07T15:06:25-03:00"
}
```
After a transaction is created and analyzed, it must be sent to the BCB (Central Bank) for processing. Therefore, it is necessary to report transaction status updates when it is sent to the BCB via the endpoint:
`PUT https://api.caas.qitech.app/pix/transaction/{transaction_id}`
This ensures that our database is updated and always consistent with the BCB database.
## Unsuccessful Transaction
Request Body
```json
{
"transaction_status": "cancelled",
"reason": "refused_by_counterpart",
"event_date": "2020-10-07T15:06:25-03:00"
}
```
If a transaction, for any reason, has not been completed (i.e., balance debited from the source account and credited to the destination account), the transaction can be updated to the `cancelled` status, with the cancellation reason, so that it is possible to identify fraud profiles related to incomplete transactions. The cancelled status can only be used on transactions that still have the `created` status, since the `sent` status is used in cases where the transaction was completed.
`PUT https://api.caas.qitech.app/pix/transaction/{transaction_id}`
The following reasons are currently accepted by the API. If you see the need to frame the cancellation reason in another reason, please contact suporte.caas@qitech.com.br.
reason | description
:----: | ---------
insufficient_balance | The client does not have sufficient account balance to perform the transaction.
fraud_prevention | The transaction was cancelled because it was not approved in the antifraud system.
system_block | A system block prevented transaction execution, for example, cancelled/inactive account or limit reached.
invalid_destination | The counterparty institution did not accept the transaction because the destination account does not exist.
refused_by_counterpart | The counterparty institution rejected the transaction.
system_error | The transaction was cancelled because there was an error in the institution's own system.
invalid_authentication | The transaction was cancelled because the client failed an authentication flow.
---
# Standards
URL: /en/documentation/caas/banking/standards
To facilitate integration and ensure information integrity, some standards have been defined that are followed throughout the API.
## Monetary Values
> Examples:
```
10000
12345
98741
1223
1
0
```
Values must be sent as integers in cents.
## Date and Time with Time Zone
> Some examples:
```
2019-10-15T22:35:12-03:00
2018-05-01T13:32:11+00:00
2019-05-01T00:00:00+00:00
```
It is represented according to ISO 8601. In this case, the time zone is placed immediately after the time and must represent the time zone of the location where that data will be valid. For example, if a rental is scheduled to start at 09:30 at Brasília airport, the time sent must be represented as 09:30-03:00; if the rental is scheduled to start at 09:30 in Manaus, it must be represented as 09:30-04:00.
The mask used for validation is as follows:
`YYYY-MM-ddThh:mm:ss±hh:mm`
## Date and Time without Time Zone
> Some examples:
```
2019-10-15T22:35:12Z
2018-05-01T13:32:11Z
2019-05-01T00:00:00Z
```
It is represented according to ISO 8601. Data that is independent of time zones must be sent without it, always in UTC, with the letter Z indicating that this data is in UTC. The following format, therefore, will be validated:
`YYYY-MM-ddThh:mm:ssZ`
## Date
> Some examples:
```
2019-10-15
2019-01-01
2017-03-20
```
In the case of fields that receive only a date, a date of birth for example, only the date, without any time, must be sent in the following format:
`YYYY-MM-dd`
---
# Webhook
URL: /en/documentation/caas/banking/webhook
Updates in fraud status (for events that are forwarded for manual analysis or responded to as Pending) are notified via Webhook. To do so, it is necessary, through the [support](mailto:suporte.caas@qitech.com.br) team, to configure an endpoint address where we will notify updates, as well as a *signature_key* that will be used to sign the request.
The client may also use the [polling](https://en.wikipedia.org/wiki/Polling_(computer_science)) technique. In this case, simply do not configure the webhook endpoint and use the retrieval endpoints to proceed with polling.
:::info **Attention**
For security reasons, all Webhook requests will only be performed on endpoints served via HTTPS.
:::
## Signature
> Example of signature calculation in Python
```python
hmac_obj = hmac.new(signature_key.encode('utf-8'), (url + method + payload).encode('utf-8'), hashlib.sha1)
return hmac_obj.hexdigest()
```
To ensure that the request received at the webhook endpoint originates from our servers, an HMAC signature is sent in the *Signature* Header, similar to the authentication process.
After calculating the expected signature value on the server side, it is necessary to compare the calculated signature with the sent one. If the signatures match, this means the request originated from our servers and is trustworthy.
## Event Update Webhook
Request Body
```json
{
"id": "123456",
"analysis_status": "automatically_approved",
"event_date": "2019-10-01T10:37:25-03:00"
}
```
The event analysis status update request has the format above and notifies of changes in fraud status. The method used is PUT, and the endpoint address may also contain the event ID, according to the client's needs. It is important to highlight that the request body is sent as UTF-8 encoded text.
Examples of event update endpoints:
* https://clientapi.com.br/\{event\}
* https://clientapi.com.br/admin/\{event\}/123456
The \{event\} field, located in the request URL, can assume the following values, depending on the event being notified:
* bill_payment
* bankslip
* wire_transfer
* withdrawal
* pix
The event_date field indicates the date and time the notification was created and may be in the past if previous notification attempts failed.
## Retries
The notification is considered completed when it receives an HTTP Status 200 response. If notifications fail, 7 retries will be made, with the following intervals, until a 200 is returned or the attempts are exhausted:
* 10 seconds
* 40 seconds
* 160 seconds
* 640 seconds
* 2560 seconds
* 10240 seconds
* 40960 seconds
---
# Wire Transfers
URL: /en/documentation/caas/banking/wire_transfers
At the moment a user makes or receives a wire transfer, the wire transfer data must be sent to QI Tech. This enables a risk analysis of the transaction based on that dataset.
## Wire Transfer Object Definition
Request Body
```json
{
"id": "082373263",
"wire_transfer_direction": "received",
"wire_transfer_type": "ted",
"amount": 13725,
"wire_transfer_date": "2020-10-07T15:06:25-03:00",
"face_recognition_key": "ef39e206-13d5-48de-b368-6c3bbc6f0222",
"validation_key": "69a59de3-0198-4a26-933a-c1de624c147d",
"client": {
"type": "natural_person",
"id": "123456",
"document_number": "056.966.649-03",
"name": "Francisco Oliveira Benedetti",
"address": {
"street": "Avenida 13",
"number": "704",
"neighbourhood": "Centro",
"city": "Ituiutaba",
"uf": "MG",
"complement": "Apt 1101",
"postal_code": "38300-140"
},
"phone": {
"international_dial_code": "55",
"area_code": "16",
"number": "981610077",
"type": "mobile"
},
"email": "mailto@qitech.com.br",
"sales_channel": "inbound_sales",
"segment": "Personalité"
},
"source_account": {
"participant": "17315359",
"branch": "0000",
"account_number": "10442",
"account_digit": "6",
"owner": {
"type": "legal_person",
"document_number": "07.487.735/0001-69",
"name": "Gioconda Pizzaria e Rotisseria LTDA."
},
"account_type": "CACC",
"opening_date": "2020-01-15T18:00:00-03:00"
},
"destination_account": {
"participant": "60701190",
"branch": "3675",
"account_number": "10442",
"account_digit": "6",
"owner": {
"type": "natural_person",
"document_number": "056.966.649-03",
"name": "Francisco Oliveira Benedetti"
},
"account_type": "SLRY",
"opening_date": "2020-01-15T18:00:00-03:00"
},
"source": {
"channel": "internet_banking",
"platform": "android",
"ip": "198.185.065.098",
"session_id": "7839jdqd9a8wd9"
}
}
```
A wire transfer must be sent to the API for preliminary fraud validation before being forwarded to the processing system.
The wire transfer status represents the decision returned by the model regarding that wire transfer. The following statuses are used in the **analysis_status** flag:
* `automatically_approved`
* `automatically_reproved`
* `in_manual_analysis`
* `pending`
Below are the meanings of each decision returned in the analysis_status flag:
status | description
:----: | ---------
automatically_approved | It is recommended that this wire transfer be approved.
automatically_reproved | It is recommended that this wire transfer be reproved.
in_manual_analysis | It is recommended that the wire transfer be analyzed manually by an analyst.
pending | The wire transfer is being processed.
name | type | description
:----: | :----: | ---------
id | string | Transaction identifier in the client's system. **It is essential that this number is unique for each wire transfer**
wire_transfer_direction | enumerator | Registered wire transfer modality. Defines whether the client is receiving or sending money.
wire_transfer_type | enumerator | Type of wire transfer performed, which can be a TED, a DOC, or an internal transfer between accounts of the same institution.
amount | integer | The wire transfer amount in cents - as described in the "Standards" section.
wire_transfer_date | datetime | The wire transfer start date and time, with time zone.
face_recognition_key | string | Facial recognition key, if facial recognition was performed by our facial recognition API.
validation_key | string | Validation key, if any client validation test was performed in our validation API.
client | *client* | Object representing the client's data, whether they are the client making the wire transfer or the receiver.
source_account | *source_account* | Object representing the debited account data.
destination_account | *destination_account* | Object representing the credited account data.
source | *source* | Source type object describing information coming from the application used for sending the wire transfer.
The following enumerators exist for *wire_transfer_direction*: `sent` and `received`.
The following enumerators exist for *wire_transfer_type*: `ted`, `doc`, `internal_transfer`.
## Send a Wire Transfer
Request Body
```json
{
"id": "12345",
...
}
```
Response Body
```json
{
"wire_transfer_key": "13d680ef-4b72-4cb2-a63d-cf3d790abaaf",
"status": "automatically_approved",
"reason": "rule_decision_enum"
}
```
To perform the evaluation of a wire transfer, simply send a Wire Transfer object to the following endpoint:
`POST https://api.caas.qitech.app/wire_transfer/wire_transfer`
## Retrieve a Wire Transfer
Response Body
```json
{
"id": "082373263",
"wire_transfer_direction": "received",
...
}
```
To retrieve data from a wire transfer, simply send a request to the following endpoint:
`GET https://api.caas.qitech.app/wire_transfer/wire_transfer/{wire_transfer_id}`
Where *wire_transfer_id* is the transaction identifier in the client's system used when sending the wire transfer.
## Update a Wire Transfer
Request Body
```json
{
"wire_transfer_status": "completed",
"event_date": "2020-10-07T15:06:25-03:00"
}
```
Response Body
```json
{
"wire_transfer_key": "13d680ef-4b72-4cb2-a63d-cf3d790abaaf",
"wire_transfer_status": "completed"
}
```
After a wire transfer is created and analyzed, it is sent to the clearing house for processing. Thus, it is necessary to report wire transfer status updates when it is sent, via the endpoint:
`PUT https://api.caas.qitech.app/wire_transfer/wire_transfer/{wire_transfer_id}`
This ensures that our database remains updated, allowing us to accurately identify wire transfers that are genuinely susceptible to fraud.
---
# Withdrawals
URL: /en/documentation/caas/banking/withdrawals
At the moment a user performs a withdrawal, the withdrawal data must be sent to QI Tech. This enables a risk analysis of the operation based on that dataset.
## Withdrawal Object Definition
Request Body
```json
{
"id": "082373263",
"amount": 12979,
"withdrawal_date": "2020-10-07T15:06:25-03:00",
"service_description": "SAQUE EM CAIXA 24H",
"source_account": {
"participant": "17315359",
"branch": "0000",
"account_number": "10442",
"account_digit": "6",
"account_type": "CACC",
"opening_date": "2020-01-15T18:00:00-03:00"
},
"client": {
"id": "182373263",
"type": "natural_person",
"document_number": "023.456.789-01",
"name": "John Payer",
"email": "john@payer.com",
"address": {
"street": "Av. Eng. Luis Carlos Berrini",
"number": "105",
"neighbourhood": "Brooklin",
"city": "São Paulo",
"uf": "SP",
"complement": "Cj 303",
"postal_code": "04501-140"
},
"phone": {
"international_dial_code": "55",
"area_code": "11",
"number": "998861708",
"type": "mobile"
},
"sales_channel": "inbound_sales",
"segment": "Personalité"
},
"terminal": {
"id": "1234566",
"latitude": -45.2753548,
"longitude": -15.24587,
"address": {
"street": "Av. Eng. Luis Carlos Berrini",
"number": "105",
"neighbourhood": "Brooklin",
"city": "São Paulo",
"uf": "SP",
"complement": "Cj 303",
"postal_code": "04501-140"
},
"type": "atm"
},
"authentication": {
"used_password": true,
"used_card": true,
"used_fingerprint": true,
"typed_account_number": false
}
}
```
A withdrawal must be sent to the API for preliminary fraud validation before being forwarded to the processing system.
The withdrawal status represents the decision returned by the model regarding that account. The following statuses are used in the **analysis_status** flag:
* `automatically_approved`
* `automatically_reproved`
Below are the meanings of each decision returned in the analysis_status flag:
status | description
:----: | ---------
automatically_approved | It is recommended that this withdrawal be approved.
automatically_reproved | It is recommended that this withdrawal be reproved.
name | type | description
:----: | :----: | ---------
id | string | Withdrawal identifier in the client's system. **It is essential that this number is unique for each withdrawal**
amount | integer | Withdrawal amount in cents - as described in the "Standards" section.
withdrawal_date | datetime | Date and time of the withdrawal execution - as described in the "Standards" section.
source_account | *account* | Object determining the source account of the funds to be withdrawn.
client | *client* | Object containing the data of the client holding the source account.
terminal | *terminal* | Object containing the data of the terminal where the withdrawal is being performed.
authentication | *authentication* | Object containing the authentication information.
## Withdrawal Objects
### Terminal Object
Request Body
```json
{
"id": "1234566",
"latitude": -45.2753548,
"longitude": -15.24587,
"address": {
"street": "Av. Eng. Luis Carlos Berrini",
"number": "105",
"neighbourhood": "Brooklin",
"city": "São Paulo",
"uf": "SP",
"complement": "Cj 303",
"postal_code": "04501-140"
},
"type": "atm"
}
```
Object representing the terminal that was used for the withdrawal.
name | type | description
:----: | :----: | ---------
id | string | Terminal identifier in the client's system.
latitude | number | Latitude, in degrees, of the terminal's location.
longitude | number | Longitude, in degrees, of the terminal's location.
address | *address* | Terminal address.
type | enum | Terminal type, possible values: "atm", "counter".
### Authentication Object
Request Body
```json
{
"used_password": true,
"used_card": true,
"used_fingerprint": true,
"typed_account_number": false
}
```
Object defining the authentication parameters used at the time of withdrawal.
name | type | description
:----: | :----: | -----------
used_password | boolean | Determines if the user used a password.
used_card | boolean | Determines if the user has the card present during authentication.
used_card_chip_and_pin | boolean | Determines if the user used the card's chip and PIN.
used_card_magnetic_stripe | boolean | Determines if the user used the card's magnetic stripe.
used_fingerprint | boolean | Determines if the user used a fingerprint.
typed_account_number | boolean | Determines if the user typed the account data.
## Send a Withdrawal
Request Body
```json
{
"id": "12345",
...
}
```
Response Body
```json
{
"withdrawal_key": "13d680ef-4b72-4cb2-a63d-cf3d790abaaf",
"status": "automatically_approved",
"reason": "rule_decision_enum"
}
```
To perform the evaluation of a withdrawal, simply send a withdrawal object to the following endpoint:
`POST https://api.caas.qitech.app/withdrawal/withdrawal`
## Retrieve a Withdrawal
Request Body
```json
{
"id": "082373263",
"amount": 12979,
...
}
```
To retrieve data from a withdrawal, simply send a request to the following endpoint:
`GET https://api.caas.qitech.app/withdrawal/withdrawal/{withdrawal_id}`
Where *withdrawal_id* is the transaction identifier in the client's system used when sending the withdrawal.
## Update a Withdrawal
Request Body
```json
{
"withdrawal_status": "completed",
"event_date": "2020-10-07T15:06:25-03:00"
}
```
Response Body
```json
{
"withdrawal_key": "13d680ef-4b72-4cb2-a63d-cf3d790abaaf",
"withdrawal_status": "completed"
}
```
After a withdrawal is created and analyzed, the money will be made available to the user. This process may be interrupted by some other business rule. Thus, it is necessary to report withdrawal status updates when it is finalized, via the endpoint:
`PUT https://api.caas.qitech.app/withdrawal/withdrawal/{withdrawal_id}`
This ensures that our database remains updated, allowing us to accurately identify withdrawals that are genuinely susceptible to fraud.
---
# Status HTTP
URL: /en/documentation/caas/car_rental/http_status
Todas as APIs da QI Tech utilizam a seguinte padronização nos status HTTP de retorno, de acordo com o [RFC 7231](https://tools.ietf.org/html/rfc7231):
| Status HTTP | Significado | Descrição |
| ---------- | ------- | --------------------------------- |
| 400 | Bad Request | A requisição enviada possui algum erro de formatação. Na maioria dos casos, retornamos no corpo da mensagem uma explicação de onde está o erro. |
| 401 | Unauthorized | Houve algum problema na autenticação, verifique se a API Key está correta e no header correto, de acordo com a seção Autenticação. |
| 403 | Forbidden | O endpoint acessado é de uso interno e não está disponível para esta API Key. |
| 404 | Not Found | O dado requisitado não foi encontrado usando a chave utilizada. Este status também é retornado quando um endpoint inválido é requisitado. |
| 405 | Method Not Allowed | O método HTTP utilizado não se aplica ao endpoint utilizado. |
| 406 | Not Acceptable | Os dados enviados no corpo da requisição são inválidos. Em geral, isso significa que os dados enviados não são um JSON válido. |
| 409 | Conflict | O id da requisição corresponde a um id já processado anteriormente. Este status é retornado no caso de requisições duplicadas enviadas ao servidor. |
| 500 | Internal Server Error | Tivemos um problema para processar esta requisição, ao encontrarmos esse erro nossos especialistas são automaticamente notificados e iniciam a análise e solução imediatamente. |
| 503 | Service Unavailable | Você se deparou com uma indisponibilidade, planejada ou não, de infraestrutura dos nossos servidores. |
---
# Imagens
URL: /en/documentation/caas/car_rental/image
Em várias situações é necessário enviar imagens para a nossa API, a fim de realizar operações de OCR, FaceMatch e validação de documentos. Para tanto, é preciso inicialmente realizar o upload da imagem para depois enviá-la para análise.
Ao enviar uma imagem utilizando o endpoint /image uma GUID (Globally Unique Identifier) é retornada. Este valor deverá ser utilizado nas chamadas subsequentes para referenciar esta imagem.
:::warning
O tamanho máximo de uma imagem aceita é de 10MB.
:::
:::warning
Neste momento, somente imagens com formato jpg são aceitas.
:::
## Envio
Exemplo de envio utilizando o cUrl:
```shell
curl -F "data=@path/to/local/file" \
-H "Authorization: TESTETESTETESTE" \
-H "DocumentNumber: 000.000.000-00" \
"https://api.caas.qitech.app/car_rental/image?type=face"
```
Exemplo de retorno:
```json
{
"image_key": "f1c0d2e1-f950-4360-896d-36588e443fc9",
"file_name": "05696664903.jpg",
"file_size": 47407,
"width_px": 0,
"height_px": 0,
"type": "face",
"created_at": "2020-07-29T18:40:57Z"
}
```
Para enviar uma imagem, basta realizar o envio da imagem no formato .jpg em `multipart/form-data` com uma requisição POST no endpoint:
`POST https://api.caas.qitech.app/car_rental/image?type=$type`
Onde $type é a classificação da imagem e deve ser enviado conforme um dos seguintes enumeradores (Caso a imagem sendo enviada não se enquadre em nenhuma das classificações, entrar em contato com o [suporte](mailto:suporte.caas@qitech.com.br) para que providenciem a adição):
- `face`
- `driver_license`
- `id`
- `contract`
Após o envio, será retornado um objeto JSON com a GUID que aponta para a imagem que foi enviada.
## Análise da Imagem para App
Ao utilizar a api_key do App, o resultado contará com um valor adicional, chamado de `result` que pode receber os seguintes valores:
- `registration_approved`
- `registration_reproved`
Que indica se o cadastro da foto foi aprovado ou reprovado.
Neste momento, a qualidade da foto também é avaliada, podendo receber um resultado 400, conforme descrito no próximo item.
Exemplo de retorno para o App:
```json
{
"image_key": "f1c0d2e1-f950-4360-896d-36588e443fc9",
"file_name": "05696664903.jpg",
"file_size": 47407,
"width_px": 0,
"height_px": 0,
"type": "face",
"result": "registration_approved",
"created_at": "2020-07-29T18:40:57Z"
}
```
## Validação de qualidade da imagem
Exemplo de retorno em caso de imagem inválida:
```json
{
"title": "image_quality",
"description": "A imagem enviada não possui uma face"
}
```
Ao realizar um post no endpoint de imagem, caso a imagem não seja suficiente para validação, um HTTP Status Code 400 será retornado, como pode ser visto no exemplo acima.
O valor do campo description é a mensagem que explica o motivo da imagem ser inválida.
:::info
Existem outros motivos pelos quais retornaremos 400 (Todos relacionados a dados inválidos). Somente os retornos com title "image_quality" são resultantes da validação de qualidade da imagem e portanto devem ser repassados ao usuário.
:::
## Recuperação dos Arquivos
Leitura de imagem:
```shell
curl "https://api.caas.qitech.app/car_rental/image/{image_key}/file" \
-H "Authorization: TESTETESTETESTE"
```
Após o envio de uma imagem para a API, é possível recuperá-la por meio de uma requisição GET adequadamente autenticada no endpoint:
`GET https://api.caas.qitech.app/car_rental/image/{image_key}/file`
Onde image_key é o valor retornado durante o envio da imagem.
## Recuperação dos meta-dados do arquivo
Leitura de meta dados:
```shell
curl "https://api.caas.qitech.app/car_rental/image/{image_key}" \
-H "Authorization: TESTETESTETESTE"
```
Após o envio de uma imagem para a API, é possível recuperar os meta-dados da imagem utilizando o endpoint:
`GET https://api.caas.qitech.app/car_rental/image/{image_key}`
Onde image_key é o valor retornado durante o envio da imagem.
---
# Introdução
URL: /en/documentation/caas/car_rental/introduction
Bem vindo à API de Prevenção a Fraudes em aluguel de veículos da QI Tech! Você pode utilizar a nossa API para acessar os endpoints, a fim de receber a resposta de um contrato de aluguel, além de utilizar para atualizar a situação de um contrato.
## Problemas?
Nós não somos uma companhia que se esconde atrás de uma API! Entre em contato com o nosso [suporte](mailto:suporte.caas@qitech.com.br) e nós responderemos o mais rápido possível. Fique à vontade para nos ligar caso deseje uma resposta rápida!
### Adoramos Feedback
Mesmo que você já tenha resolvido o seu problema ou que ele seja muito simples (Até mesmo um typo ou uma organização inadequada que você já entendeu), envie-nos um e-mail, assim nós tornamos a documentação cada vez mais prática e a próxima pessoa não vai precisar sofrer as dores que você sofreu!
## Ambientes
Possuímos dois ambientes para os nossos clientes. A URL base das APIs são:
- Produção - `https://api.caas.qitech.app/car_rental/`
- Sandbox - `https://api.sandbox.caas.qitech.app/car_rental/`
No ambiente de Sandbox, as análises enviadas não são cobradas e são respondidas de acordo com a seguinte regra **baseada no valor total do aluguel**:
| Mínimo | Máximo | Decisão |
| ------ | ------ | ------- |
| 10000 | -- | Pendente (Em análise Manual) - Sem Decisão da Mesa |
| 8000 | 9999 | Aprovado Automaticamente |
| 6000 | 7999 | Reprovado Automaticamente |
| 5000 | 5999 | Derivado para Análise Manual - Com aprovação posterior |
| 4000 | 4999 | Derivado para Análise Manual - Com reprovação posterior |
| 3000 | 3999 | Derivado para Análise Manual - Com Desafio Manual |
| 0 | 2999 | Pendente (Em análise Manual) - Sem Decisão da Mesa |
As análises de upgrade em ambiente de Sandbox seguirão as decisões de análise abaixo:
| Grupos | upgrade_status |
| ------ | -------------- |
| ('C', 'CX', 'SV', 'SU') | 'automatically_approved' |
| ('IE', 'J', 'SG') | 'automatically_reproved' |
## Somente HTTPS
Por questão de segurança, toda a comunicação com as APIs da QI Tech devem ser realizadas utilizando a comunicação HTTPS. Para garantir que, por desatenção ou qualquer outro motivo, não ocorram chamadas HTTP, este servidor somente disponibiliza a porta 443 com comunicação TLS 1.2. Chamadas realizadas utilizando outros protocolos serão automaticamente negadas.
## Autenticação
```shell
# No shell, você somente precisa adicionar o header adequado em cada requisição
curl "api_endpoint_here"
-H "Authorization: API-KEY-EXAMPLE"
```
:::info
Substitua a API key `API-KEY-EXAMPLE` com a sua chave adquirida com o nosso suporte.
:::
Utilizamos uma API Key para permitir acesso a nossa API. Ela provavelmente já foi enviada por e-mail para você. Caso você ainda não tenha recebido a sua chave, envie um e-mail para [suporte.caas@qitech.com.br](mailto:suporte.caas@qitech.com.br).
Nossa API espera receber a API Key em todas as requisições ao nosso servidor em um header como o abaixo:
`Authorization: API-KEY-EXAMPLE`
:::note
Você deve substituir `API-KEY-EXAMPLE` com a API Key recebida do suporte.
:::
---
# Troca de Mensagens
URL: /en/documentation/caas/car_rental/messages
Para a troca de mensagens entre a mesa de análise manual e o atendente da loja, são disponibilizados dois endpoints:
- `POST https://api.caas.qitech.app/car_rental/rental_agreement/{rental_agreement_id}/message`
- `GET https://api.caas.qitech.app/car_rental/rental_agreement/{rental_agreement_id}/messages`
Todas as mensagens são vinculadas a uma análise, utilizando o id enviado no momento do envio da análise.
## Envio de Mensagem
Para que seja realizado o envio de uma mensagem, é necessário realizar a requisição utilizando o método POST no endpoint message, com uma payload que possui os seguintes campos:
| nome | tipo | descrição |
| ---- | :----: | --------- |
| author_document_number | string | CPF formatado de quem está enviando a mensagem |
| author_name | string | Nome de quem está enviando a mensagem |
| message | string | Mensagem sendo enviada |
Exemplo de payload para envio de uma mensagem:
```json
{
"author_name": "John Sample",
"author_document_number": "000.000.000-00",
"message": "Alerta de fraude"
}
```
## Recebimento de Mensagens
Para que as mensagens possam ser exibidas para o atendente, basta realizar a recuperação das mensagens trocadas por meio do endpoint de GET. O endpoint pode receber um query parameter chamado `only_messages_to_show`, que ao receber o valor `true` retorna somente as mensagens que devem ser exibidas na tela do atendente.
Os dados do autor somente são devolvidos quando a mensagem foi produzida por um ser humano.
Retorno no endpoint de recuperação de mensagens:
```json
[
{
"author_name": "John Sample",
"author_document_number": "000.000.000-00",
"source": "analysis_screen",
"message": "Análise finalizada",
"message_date": "2019-11-05T13:34:12-03:00"
},
{...}
]
```
---
# Shared Objects
URL: /en/documentation/caas/car_rental/objects
A good part of the data is shared between Reservation and RentalAgreement. Below you can easily find the definitions of these objects.
## *reservation* Object
```json
{
"id": "0",
"channel": "reservation_central",
"reservation_date": "2020-03-31T08:15:00-03:00",
"sales_channel" : "PARCERIA TELEFONICA"
}
```
The *reservation* object is used in the *rental_agreement* endpoint to represent the reservation that originated the rental to be analyzed. This field is required so that a rental_agreement can be linked to the reservation. It is represented as follows:
| name | type | description |
| ---- | :----: | --------- |
| id | integer | Identifier of the reservation that originated the rental. |
| channel | enum | Channel through which the reservation for this rental was made. |
| reservation_date | DateTime | Date and time, with time zone, when the reservation for this rental was made. |
| sales_channel | string | Sales channel through which the reservation was made (e.g.: PARCERIA MASTERCARD). |
The following enumerators exist for the *channel* field: `walkin`, `reservation_central`, `app`, `website_mobile`, `website_desktop`, `partnerships` and `third_parties`.
## *car* Object
```json
{
"model_group": "C",
"upgrade_model_group": "SV",
"group_description": "Sedan Médio 1.4",
"rental_daily_price": 48496
}
```
The *car* object represents a vehicle that is being reserved (*reservation* endpoint) or picked up (*rental_agreement* endpoint). The data sent is:
| name | type | description |
| ---- | :----: | --------- |
| **model_group** | string | The vehicle group, in uppercase letters. *(required)* |
| upgrade_model_group | string | The vehicle group of the upgrade, in uppercase letters. |
| group_description | string | A description of the vehicle group. |
| rental_daily_price | integer | The daily rate charged. |
## *client* Object
The *client* object represents the data of the customer who is making the reservation or picking up the vehicle.
### *client (v1)* Object
The "v1" example represents the sample payload **before the migration of the main scoring to the reservation**. For both reservations and rental_agreements.
```json
{
"type": "natural_person",
"document_number": "123.456.789-00",
"name": "John Sample",
"gender": "female",
"birthdate": "2001-01-15",
"mother_name": "Mary Sample",
"email": "john.sample@sample.com.br",
"allowed_information_on_email": true,
"face_picture": "c77d1925-0e72-4634-8393-395dbbce498d",
"additional_pictures": [
"718b8caa-8ef5-446c-b101-2dbf6c7e401f",
"9c67f365-1427-4889-b963-d3729d437ff3",
"8006f82c-3a80-4371-914e-e88c91507711",
"42c6909e-51aa-4b6d-972f-f4684a047993",
"b7a88947-96bd-4557-81e9-a69a3c84f428"
],
"total_rents": 6,
"fidelity_points": 1200,
"documents": {
"rg": {
"document_number": "00000000",
"issuer": "SSP"
},
"cnh": {
"document_number": "000000000",
"security_code": "00000",
"first_issuance": "2015-07-20",
"expiration_date": "2030-07-26",
"state": "SP"
}
},
"residential_address": {
"street": "Av Brigadeiro Faria Lima",
"number": "2391",
"neighborhood": "Jardins",
"city": "SÃO PAULO",
"uf": "SP",
"complement": "",
"postal_code": "00000-000"
},
"commercial_address": {
"street": "Av Brigadeiro Faria Lima",
"number": "2391",
"neighborhood": "Jardins",
"city": "SÃO PAULO",
"uf": "SP",
"complement": "",
"postal_code": "00000-000"
},
"phones": [
{
"international_dial_code": "55",
"area_code": "11",
"number": "00000-0000",
"type": "mobile"
},
{
"international_dial_code": "55",
"area_code": "11",
"number": "00000-0000",
"type": "residential"
}
]
}
```
| name | type | description |
| ---- | :----: | --------- |
| **type** | enum | Enumerator that defines the client type. *(required)* |
| **document_number** | string | The client's CPF or Passport. *(required)* |
| **name** | string | The client's full name. *(required)* |
| **gender** | enum | The client's gender. *(required)* |
| birthdate | date | The client's date of birth. |
| mother_name | string | The full name of the client's mother. |
| **email** | string | The email provided by the client. *(required)* |
| **allowed_information_on_email** | boolean | Flag indicating whether the client allowed marketing emails to be sent at registration. *(required)* |
| face_picture | GUID | GUID of the previously uploaded image whose content is a picture of the client's face. |
| additional_pictures | List of GUIDs | List of GUIDs of the additional images uploaded of the clients' faces and documents. |
| total_rents | integer | Total number of rentals of the client. |
| fidelity_points | integer | Number of loyalty points of the client. |
| **documents** | *documents* | Object containing the details of the client's documents. *(required)* |
| residential_address | *address* | The client's residential address. |
| commercial_address | *address* | The client's commercial address. |
| **phones** | List of *phone* | List of the client's phone numbers. *(required)* |
The following enumerators exist for the *type* field: `natural_person`, `legal_person`, `replacement`, `fleet`, `uber`, `enterprise` and `agencia`.
The following enumerators exist for the *gender* field: `male`, `female` and `undefined`.
### *client (v2)* Object
This section concerns the information required for the fraud analysis flow primarily on the reservation.
The "client (v2)" object example represents the sample payload **after the migration of the main scoring to the reservation**. For both reservations and rental_agreements.
```json
{
"type": "natural_person",
"document_number": "123.456.789-00",
"name": "John Sample",
"gender": "female",
"birthdate": "2001-01-15",
"mother_name": "Mary Sample",
"email": "john.sample@sample.com.br",
"allowed_information_on_email": true,
"face_picture": "c77d1925-0e72-4634-8393-395dbbce498d",
"additional_pictures": [
"718b8caa-8ef5-446c-b101-2dbf6c7e401f",
"9c67f365-1427-4889-b963-d3729d437ff3",
"8006f82c-3a80-4371-914e-e88c91507711",
"42c6909e-51aa-4b6d-972f-f4684a047993",
"b7a88947-96bd-4557-81e9-a69a3c84f428"
],
"total_rents": 6,
"fidelity_points": 1200,
"documents": {
"rg": {
"document_number": "00000000",
"issuer": "SSP"
},
"cnh": {
"document_number": "000000000",
"security_code": "00000",
"first_issuance": "2015-07-20",
"expiration_date": "2030-07-26",
"state": "SP"
}
},
"residential_address": {
"street": "Av Brigadeiro Faria Lima",
"number": "2391",
"neighborhood": "Jardins",
"city": "SÃO PAULO",
"uf": "SP",
"complement": "",
"postal_code": "00000-000"
},
"commercial_address": {
"street": "Av Brigadeiro Faria Lima",
"number": "2391",
"neighborhood": "Jardins",
"city": "SÃO PAULO",
"uf": "SP",
"complement": "",
"postal_code": "00000-000"
},
"phones": [
{
"international_dial_code": "55",
"area_code": "11",
"number": "00000-0000",
"type": "mobile"
},
{
"international_dial_code": "55",
"area_code": "11",
"number": "00000-0000",
"type": "residential"
}
]
}
```
| name | type | description |
| ---- | :----: | --------- |
| **type** | enum | Enumerator that defines the client type. - expected types: "natural_person", "legal_person", "replacement", "fleet", "uber", "agencia", "uber_semanal" *(required)* |
| **document_number** | string | The client's CPF or Passport. *(required)* |
| name | string | The client's full name. |
| **gender** | enum | The client's gender. *(required)* |
| birthdate | date | The client's date of birth. |
| mother_name | string | The full name of the client's mother. |
| email | string | The email provided by the client. |
| allowed_information_on_email | boolean | Flag indicating whether the client allowed marketing emails to be sent at registration. *(required)* |
| face_picture | GUID | GUID of the previously uploaded image whose content is a picture of the client's face. |
| additional_pictures | List of GUIDs | List of GUIDs of the additional images uploaded of the clients' faces and documents. |
| total_rents | integer | Total number of rentals of the client. |
| fidelity_points | integer | Number of loyalty points of the client. |
| **documents** | *documents* | Object containing the details of the client's documents. *(required)* |
| residential_address | *address* | The client's residential address. |
| commercial_address | *address* | The client's commercial address. |
| **phones** | List of *phone* | List of the client's phone numbers. *(required)* |
The following enumerators exist for the *type* field: `natural_person`, `legal_person`, `replacement`, `fleet`, `uber`, `enterprise` and `agencia`.
The following enumerators exist for the *gender* field: `male`, `female` and `undefined`.
## *participant* Object
The *participant* object represents a person involved in the rental who is not the main renter, that is, an **additional driver** or the **financial manager**. It is the definition used both in the `additional_drivers` list and in the `financial_manager` field of a RentalAgreement.
Its structure is the same as the *client* object, so the same serialization implementation can be reused.
:::note
Every participant sent goes through the same fraud analysis applied to the main renter, but the result of these analyses **does not change the fraud_status** of the RentalAgreement.
:::
```json
{
"type": "natural_person",
"segment": "ota",
"document_number": "987.654.321-00",
"name": "Jane Sample",
"gender": "female",
"birthdate": "1998-05-22",
"mother_name": "Mary Sample",
"email": "jane.sample@sample.com.br",
"allowed_information_on_email": true,
"face_picture": "e3b0c442-98fc-1c14-9afb-f4c8996fb924",
"additional_pictures": [
"718b8caa-8ef5-446c-b101-2dbf6c7e401f"
],
"total_rents": 2,
"fidelity_points": 0,
"documents": {
"rg": {
"document_number": "00000000",
"issuer": "SSP"
},
"cnh": {
"document_number": "000000000",
"security_code": "00000",
"first_issuance": "2018-03-10",
"expiration_date": "2028-03-10",
"state": "SP"
}
},
"residential_address": {
"street": "Av Brigadeiro Faria Lima",
"number": "2391",
"neighborhood": "Jardins",
"city": "SÃO PAULO",
"uf": "SP",
"complement": "",
"postal_code": "00000-000",
"country": "BRA"
},
"phones": [
{
"international_dial_code": "55",
"area_code": "11",
"number": "00000-0000",
"type": "mobile"
}
]
}
```
| name | type | description |
| ---- | :----: | --------- |
| **type** | enum | Enumerator that defines the participant type. *(required)* |
| segment | string | Segment the participant belongs to. |
| **document_number** | string | The participant's CPF, CNPJ or Passport. *(required)* |
| **name** | string | The participant's full name. *(required)* |
| **gender** | enum | The participant's gender. *(required)* |
| birthdate | date | The participant's date of birth. |
| mother_name | string | The full name of the participant's mother. |
| **email** | string | The email provided by the participant. *(required)* |
| **allowed_information_on_email** | boolean | Flag indicating whether the participant allowed marketing emails to be sent at registration. *(required)* |
| face_picture | GUID | GUID of the previously uploaded image whose content is a picture of the participant's face. |
| additional_pictures | List of GUIDs | List of GUIDs of the additional images uploaded of the participant's face and documents. |
| total_rents | integer | Total number of rentals of the participant. |
| fidelity_points | integer | Number of loyalty points of the participant. |
| **documents** | *documents* | Object containing the details of the participant's documents. *(required)* |
| residential_address | *address* | The participant's residential address. |
| commercial_address | *address* | The participant's commercial address. |
| **phones** | List of *phone* | List of the participant's phone numbers. *(required)* |
The following enumerators exist for the *type* field: `natural_person`, `legal_person`, `replacement`, `fleet`, `uber`, `enterprise`, `agencia` and `uber_semanal`.
The following enumerators exist for the *gender* field: `male`, `female` and `undefined`.
## *billing* Object
```json
{
"name": "Agência AAA",
"document_number": "00.000.000/0001-00",
"voucher_type":"ABCD75",
"voucher_description": "Pagamento pela Agência"
}
```
The *billing* object is used to represent who is responsible for paying the rental, and it is represented as follows:
| name | type | description |
| ---- | :----: | --------- |
| name | string | Name of the person or company responsible for paying the rental. |
| document_number | string | CPF, CNPJ or Passport of the person or company responsible for paying the rental. |
| voucher_type | string | Alphanumeric code that represents the type of voucher used. |
| voucher_description | string | Description of the type of voucher used. |
## *address* Object
```json
{
"street": "Rua do Exemplo",
"number": "111",
"neighborhood": "Bairro do Teste",
"city": "Aparecida de Goiânia",
"uf": "GO",
"complement": "",
"postal_code": "00000-000"
}
```
The *address* object is used to represent addresses across the entire API. Addresses within Brazilian territory are represented as follows:
| name | type | description |
| ---- | :----: | --------- |
| street | string | Street of the address, including the street type, avoiding abbreviations whenever possible. |
| number | string | Number of the property, including letters if it has any. |
| neighborhood | string | Neighborhood, without abbreviations. **e.g.: Santa Felicidade** |
| city | string | Full name of the city, without abbreviations. |
| uf | string | The federative unit, with two uppercase letters. **e.g.: SP** |
| complement | string | Any complements that help locate the property. **e.g.: Apartamento 101, Conjunto 12** |
| postal_code | string | The postal code of the location, including the hyphen. |
| country | string | ISO 3166-1 alpha-3 code of the address country. |
For addresses whose country is not Brazil ("BRA"), the postal_code and the federative unit may be filled in freely.
## *documents* Object
The *documents* object is used to represent the details of the document data provided by the client. The object is represented as follows:
| name | type | description |
| ---- | :----: | --------- |
| rg | *rg* | Object describing the information of the client's RG (Brazilian ID card). |
| cnh | *cnh* | Object describing the information of the client's CNH (Brazilian driver's license). |
| foreign_document | *foreign_document* | Object describing the information of the client's foreign document. |
## *rg* Object
The *rg* object is used to represent the details of the RG data provided by the client. The object is represented as follows:
| name | type | description |
| ---- | :----: | --------- |
| document_number | string | Number of the client's RG. |
| issuer | string | Issuing authority and state of issuance of the client's RG. |
## *cnh* Object
The *cnh* object is used to represent the details of the driver's license data provided by the client. The object is represented as follows:
| name | type | description |
| ---- | :----: | --------- |
| document_number | string | Registration number of the client's driver's license. |
| security_code | string | Security code of the client's driver's license. |
| first_issuance | date | Date of the first issuance of the client's driver's license. |
| expiration_date | string | Expiration date of the client's driver's license. |
| state | string | State of issuance of the client's driver's license. |
## *foreign_document* Object
The *foreign_document* object is used to represent the foreign document provided by the client. The object is represented as follows:
| name | type | description |
| ---- | :----: | --------- |
| document_number | string | Number of the client's foreign document. |
| document_type | enum | Type of the foreign document. Accepts the values `passport` and `other`. |
| issuer_country | string | ISO 3166-1 alpha-3 code of the country that issued the document. |
## *phone* Object
```json
{
"international_dial_code": "1",
"area_code": "11",
"number": "99999-9999",
"type": "mobile"
}
```
A phone object represents a phone number, inside or outside Brazil, and its classification. Its fields are:
| name | type | description |
| ---- | :----: | --------- |
| **international_dial_code** | string | International dialing code, without zero or +, digits only. *(required)* |
| **area_code** | string | Area code, without zero, digits only. *(required)* |
| **number** | string | Phone number, without the hyphen. *(required)* |
| **type** | enum | Type of number: mobile, residential, commercial, etc. *(required)* |
The following enumerators exist for the phone type: `residential`, `commercial`, `mobile`.
## *coverage* Object
```json
{
"description": "S/ PROTEÇÃO AMERICAN PLATINUM",
"price": 0
}
```
A coverage object is related to a coverage purchased by the renter.
| name | type | description |
| :----: | :----: | --------- |
| **description** | string | Description of the purchased coverage. *(required)* |
| **price** | integer | Daily price of the coverage. *(required)* |
---
# Envio de Resultado Quiz
URL: /en/documentation/caas/car_rental/quiz
Para o envio do resultado Quiz, para que apareça na interface gráfica, o seguinte endpoint deve ser utilizado:
`POST https://api.caas.qitech.app/car_rental/rental_agreement/{rental_agreement_id}/quiz_result`
O resultado do quiz é vinculado a uma análise, utilizando o id enviado no momento do envio da análise.
## Envio do Quiz
Para que seja enviado o resultado do Quiz, é necessário realizar a requisição utilizando o método POST no endpoint quiz_result, com uma payload que possui os seguintes campos:
| nome | tipo | descrição |
| ---- | :----: | --------- |
| score | number | Valor numérico do score do Quiz |
| result_enum | string | Enumerador do resultado do quiz: `low_risk`, `medium_risk`, `high_risk` |
| result_description | string | Descrição do resultado do quiz: "Baixo Risco", "Médio Risco", "Alto Risco" e outros |
Exemplo de payload para envio do resultado do Quiz:
```json
{
"score": 950,
"result_enum": "low_risk",
"result_description": "Baixo Risco"
}
```
---
# RentalAgreement-v1
URL: /en/documentation/caas/car_rental/rental_agreement
When picking up a vehicle at the store, the renter starts their anti-fraud process. The data sent must be the final data, which will not be changed. This is important to guarantee two things:
- Consistency of the data in the Anti-fraud database
- A realistic risk assessment
The analysis process consists of sending a RentalAgreement to the appropriate endpoint and waiting for the response. There are eight possible results, returned in the **fraud_status** flag:
| Result | Description |
| :---------: | --------- |
| Automatically Approved | We recommend that this rental be approved |
| Automatically Denied | We recommend that this rental be rejected |
| Sent to manual analysis | Our rules or models are not confident about the decision and decided to send this rental to manual analysis. |
| Manually Approved | After manual analysis, the analyst chose to approve the rental |
| Manually Rejected | After manual analysis, the analyst chose to reject the rental |
| Manually Challenged | After manual analysis, the analyst informs the store that the driver's license and/or the selfie are incorrect and/or of low quality |
| Pending | The queries are taking longer than expected, this rental entered an automatic analysis queue and will be answered through a Webhook |
| Not analyzed | The request was sent with the analysis flag set to false, which means our systems must not return a decision |
### Status Dynamics
When retrieving a RentalAgreement object, the statuses are available. In addition to the statuses, a history of changes is also returned so that it can be consulted in the future. These changes are called events and carry, besides the new status, the modification dates.
### Status Dynamics - **car_status**
The **car_status** status related to a RentalAgreement indicates the situation of the car related to this rental, that is, whether the car was returned or not. The following enumerators exist for this status:
- `rented`
- `returned`
- `recovered`
- `written_off`
### Status Dynamics - **fraud_status**
The **fraud_status** status indicates the status of the fraud engine's decision and has a fairly simple state machine:
- `created`
- `automatically_approved`
- `automatically_reproved`
- `in_manual_analysis`
- `manually_approved`
- `manually_reproved`
- `manually_challenged`
- `pending`
- `not_analyzed`
In addition, upgrade_status has the same enumerators.
### Additional drivers and financial manager
Besides the main renter, sent in `client`, a RentalAgreement may carry other people involved in the rental:
- **Additional drivers** (`additional_drivers`): list of people authorized to drive the vehicle besides the main renter.
- **Financial manager** (`financial_manager`): individual or company designated as responsible for paying the rental. There is at most one financial manager per rental.
Both fields use the *participant* object definition, whose structure is identical to the *client* object.
Every participant sent goes through the **same anti-fraud queries and analyses** applied to the main renter, so this data also feeds the Anti-fraud database. The individual result of each participant is returned in the analysis response, as described in [Send a RentalAgreement](#send-a-rentalagreement). However, this result **does not change the fraud_status of the RentalAgreement**, which is still determined by the assessment of the main renter.
Both fields are optional and may be omitted when there are no participants besides the main renter.
## Object Definition
```json
{
"id": "bca6268e-918a-4658-9161-a10b00a631ab",
"rental_agreement_code" : "12345678",
"rental_agreement_date": "2020-03-31T10:30:00-03:00",
"car_rental_estimated_final_date": "2020-04-01T10:28:00-03:00",
"reservation": {
"id": "0",
"channel": "reservation_central",
"reservation_date": "2020-03-31T08:15:00-03:00",
"sales_channel" : "PARCERIA TELEFONICA"
},
"rental_store": "SAOP",
"rental_store_group": "GSP",
"rental_store_type": "LOJA DE RUA",
"devolution_store": "SAOP",
"risky_antecedence": true,
"car": {
"model_group": "AM",
"upgrade_model_group": "SV",
"rental_daily_price" : 48496,
"risky_model_group": true,
"risky_upgrade_model_group": true
},
"client": {
"type": "natural_person",
"segment": "ota",
"document_number": "123.456.789-00",
"name": "John Sample",
"gender": "female",
"birthdate": "2001-01-15",
"mother_name": "Mary Sample",
"email": "john.sample@sample.com.br",
"allowed_information_on_email": true,
"face_picture": "c77d1925-0e72-4634-8393-395dbbce498d",
"additional_pictures": [
"718b8caa-8ef5-446c-b101-2dbf6c7e401f",
"9c67f365-1427-4889-b963-d3729d437ff3",
"8006f82c-3a80-4371-914e-e88c91507711",
"42c6909e-51aa-4b6d-972f-f4684a047993",
"b7a88947-96bd-4557-81e9-a69a3c84f428"
],
"total_rents": 6,
"fidelity_points": 1200,
"documents": {
"rg": {
"document_number": "00000000",
"issuer": "SSP"
},
"cnh": {
"document_number": "000000000",
"security_code": "00000",
"first_issuance": "2015-07-20",
"expiration_date": "2030-07-26",
"state": "SP"
}
},
"residential_address": {
"street": "Av Brigadeiro Faria Lima",
"number": "2391",
"neighborhood": "Jardins",
"city": "SÃO PAULO",
"uf": "SP",
"complement": "",
"postal_code": "00000-000"
},
"commercial_address": {
"street": "Av Brigadeiro Faria Lima",
"number": "2391",
"neighborhood": "Jardins",
"city": "SÃO PAULO",
"uf": "SP",
"complement": "",
"postal_code": "00000-000"
},
"phones": [
{
"international_dial_code": "55",
"area_code": "11",
"number": "00000-0000",
"type": "mobile"
},
{
"international_dial_code": "55",
"area_code": "11",
"number": "00000-0000",
"type": "residential"
}
]
},
"additional_drivers": [
{
"type": "natural_person",
"document_number": "987.654.321-00",
"name": "Jane Sample",
"gender": "female",
"email": "jane.sample@sample.com.br",
"allowed_information_on_email": true,
"face_picture": "e3b0c442-98fc-1c14-9afb-f4c8996fb924",
"documents": {
"cnh": {
"document_number": "000000000",
"security_code": "00000",
"first_issuance": "2018-03-10",
"expiration_date": "2028-03-10",
"state": "SP"
}
},
"phones": [
{
"international_dial_code": "55",
"area_code": "11",
"number": "00000-0000",
"type": "mobile"
}
]
}
],
"financial_manager": {
"type": "legal_person",
"document_number": "00.000.000/0001-00",
"name": "Empresa Sample LTDA",
"gender": "undefined",
"email": "financeiro@sample.com.br",
"allowed_information_on_email": false,
"documents": {},
"phones": [
{
"international_dial_code": "55",
"area_code": "11",
"number": "00000-0000",
"type": "commercial"
}
]
},
"coverages": [
{
"description": "S/ PROTEÇÃO AMERICAN PLATINUM",
"price": 0
},
{
"description": "PROTEÇÃO OCUPANTES E TERCEIROS",
"price": 1668
}
],
"billing": {
"name": "Agência AAA",
"document_number": "00.000.000/0001-00",
"voucher_type": "ABCD75",
"voucher_description": "Pagamento pela agência"
},
"fare_name": "Mensal",
"rental_price": 43300,
"extra_hours": 0,
"extra_hours_price": 0,
"discount": 0,
"prepayment_discount": 100,
"extra_kms": 0,
"extra_kms_price": 0,
"third_party_coverage_price": 1490,
"coverage_price": 0,
"additional_driver_price": 1000,
"driver_service_price": 1000,
"additional_expenses": 1000,
"devolution_fee": 0,
"administration_fee": 5374,
"discount_partial_coverage": 50,
"free_day_discount": 20000,
"final_price": 50165,
"pre_authorization_amount": 0,
"coverage_deductible_amount": 0,
"upgrade_reason": "granted"
}
```
All information exchanges of a RentalAgreement use the following definition for this object. In some cases, to make the implementation easier and reduce the data flow between the parties, some information may be omitted.
| name | type | description |
| :----: | :----: | --------- |
| **id** | string | Identifier of the analysis request in the client's system. **It is essential that this number be unique for each rental.** *(required)* |
| **rental_agreement_code** | string | Identifier of the RentalAgreement in the client's system. *(required)* |
| **rental_agreement_date** | DateTime | Date and time, with time zone, of the vehicle pickup for the rental that is taking place. *(required)* |
| **car_rental_estimated_final_date** | DateTime | Date and time, with time zone, of when the car is expected to be returned. *(required)* |
| **reservation** | *reservation* | Object that carries the properties of the reservation that originated this rental. *(required)* |
| **rental_store** | *store* | Store where the car is being picked up. *(required)* |
| rental_store_group | *store* | Branch of the store where the car is being picked up. |
| rental_store_type | *store* | Type of the store where the car will be picked up. |
| **devolution_store** | *store* | Store where the car will be returned; it may or may not be the same pickup store. *(required)* |
| **car** | *car* | Car that is being picked up - it is important that this value be, in fact, the car being picked up. *(required)* |
| **client** | *client* | Object that carries the information of the client who is picking up the vehicle. *(required)* |
| additional_drivers | List of *participant* | List of the additional drivers authorized to drive the vehicle in this rental. |
| financial_manager | *participant* | Individual or company designated as the financial manager of this rental. |
| **coverages** | List of *coverage* | List of coverage objects describing the insurance coverages purchased by the client. *(required)* |
| **billing** | *billing* | Object describing the details of the person or company responsible for paying the rental. *(required)* |
| **rental_price** | integer | Rental price, in cents. *(required)* |
| **extra_hours** | integer | Number of extra hours purchased. *(required)* |
| **extra_hours_price** | integer | Price of the extra hours purchased, in cents. *(required)* |
| **discount** | integer | Discount granted for any reason, in cents. *(required)* |
| **prepayment_discount** | integer | Discount for advance payment. |
| **extra_kms** | integer | Number of extra kilometers purchased. *(required)* |
| **extra_kms_price** | integer | Price of the extra kilometers purchased, in cents. *(required)* |
| **third_party_coverage_price** | integer | Price of the third-party insurance, in cents. *(required)* |
| **coverage_price** | integer | Price of the insurance purchased, in cents. *(required)* |
| additional_driver_price | integer | Total price of the additional driver(s) purchased, in cents. |
| driver_service_price | integer | Total price of the driver service purchased, in cents. |
| additional_expenses | integer | Additional expenses, in cents. |
| **devolution_fee** | integer | Price of the return fee, in cents. *(required)* |
| **administration_fee** | integer | Price of the administration fee, in cents. *(required)* |
| **discount_partial_coverage** | integer | Partial protection discount, in cents. |
| **free_day_discount** | integer | Free Day discount, in cents. |
| **final_price** | integer | Final price of the rental, in cents. *(required)* |
| pre_authorization_amount | integer | Pre-authorization amount, in cents. |
| **coverage_deductible_amount** | integer | Deductible amount of the coverage, in cents. *(required)* |
| upgrade_reason | enum | Type of upgrade (Granted or Bought) - Accepts the values `granted` and `bought` respectively. |
## Send a RentalAgreement
Request example:
```json
{
"id": "bca6268e-918a-4658-9161-a10b00a631ab",
...
}
```
Response example:
```json
{
"id": "bca6268e-918a-4658-9161-a10b00a631ab",
"fraud_status": "automatically_approved",
"financial_manager": {
"fraud_status": "automatically_approved"
},
"additional_drivers": [
{
"id": "1111111",
"fraud_status": "automatically_approved"
}
],
"pre_authorization_amount": 100000,
"block_document_number": true,
"upgrade_status": "automatically_approved",
"highest_allowed_car_group": "SV",
"score": 870
}
```
If the rental was sent with additional drivers and/or a financial manager, the individual analysis result of each of them is also returned:
| name | type | description |
| ---- | :----: | --------- |
| financial_manager.fraud_status | enum | Result of the anti-fraud analysis of the financial manager. Uses the same enumerators as the RentalAgreement **fraud_status**. |
| additional_drivers[].id | string | Identifier of the additional driver analyzed. |
| additional_drivers[].fraud_status | enum | Result of the anti-fraud analysis of that additional driver. Uses the same enumerators as the RentalAgreement **fraud_status**. |
:::note
These statuses are informative and independent: a rejected additional driver or financial manager **does not change** the RentalAgreement **fraud_status**. It is up to the rental company to decide what to do with the rejected participant, such as refusing to include that driver in the rental.
:::
To assess a rental, simply send a RentalAgreement object to the following endpoint with the flag set appropriately:
`POST https://api.caas.qitech.app/car_rental/rental_agreement?analyze=true`
Besides the status of the response, the desired pre-authorization amount is also returned, if there is one. If no pre-authorization increase is identified, the returned value is null and must not be used.
The highest group that can be provided in that RA is made available in the `highest_allowed_car_group` variable. This value is configured in the RA assessment rule.
The *analyze* parameter exists to prevent transactions that do not need to be analyzed from going through the fraud engines, polluting the database. The default value of this parameter is **true**, so that only rentals explicitly removed from the analysis will not be analyzed.
## Update the status of a RentalAgreement
Request body - When a car rental is effected:
```json
{
"car_status": "rented",
"event_date": "2019-11-05T13:34:12-03:00"
}
```
Request body - On the return of a car without incidents:
```json
{
"car_status": "returned",
"event_date": "2019-11-05T13:34:12-03:00"
}
```
Request body - On the return of a car recovered after a theft:
```json
{
"car_status": "recovered",
"incident": "theft",
"event_date": "2019-11-05T13:34:12-03:00"
}
```
Request body - Write-off with confirmed fraud:
```json
{
"car_status": "written_off",
"incident": "misappropriation",
"event_date": "2019-11-05T13:34:12-03:00"
}
```
To guarantee the feedback loop of the rules and of the implemented artificial intelligence model, it is necessary to inform the system when cars are rented, returned, or written off due to fraud. To do so, requests with the PUT method must be used, passing as a reference the id sent when creating the *rental_agreement*, authenticated as usual:
`PUT https://api.caas.qitech.app/car_rental/rental_agreement/{rental_agreement_id}`
If the new status is *written_off*, the following values can be used in the **incident** field, sent in the request body, which indicates the type of incident of the rental:
| Enumerator | Description |
| --------- | ----------- |
| theft | RAs that suffered a theft |
| misappropriation | RAs that were classified as misappropriation |
## Update the vehicle of a RentalAgreement
Request body - Updating a vehicle in the rental:
```json
{
"car_plate": "ABC1B34",
"car_model": "Chevrolet Onix",
"model_group": "B",
"event_date": "2020-10-15T13:34:12-03:00"
}
```
To guarantee the consistency between fraud occurrences and rentals and to guarantee the retraining of the score model, it is necessary to inform the system of the data of each car when it is linked to the rental. To do so, requests with the POST method must be used, passing as a reference the id sent when creating the *rental_agreement*, authenticated as usual:
`POST https://api.caas.qitech.app/car_rental/rental_agreement/{rental_agreement_id}/car`
The data of the vehicle being linked to that rental must be sent in the request body:
| name | type | description |
| ---- | :----: | --------- |
| car_plate | string | License plate of the vehicle. |
| car_model | string | Model of the vehicle, including its make and model (e.g.: Jeep Renegade). |
| model_group | string | The group of the vehicle, in uppercase letters. |
| event_date | DateTime | Date and time, with time zone, of the moment when the car was associated with the rental. |
## Retrieve a RentalAgreement
In order to retrieve a specific RentalAgreement, simply make a GET request. The returned result is the most up-to-date json of the RentalAgreement in question. If this identifier is not related to any object, HTTP Status 404 is returned.
`GET https://api.caas.qitech.app/car_rental/rental_agreements/{rental_agreement_id}`
```shell
curl "https://api.caas.qitech.app/car_rental/rental_agreements/{rental_agreement_id}"
-H "Authorization: TESTETESTETESTE"
```
## Search RentalAgreements
Response - a list of RentalAgreement objects:
```json
[
{
"id": "bca6268e-918a-4658-9161-a10b00a631ab",
...
},
{
"id": "13a91409-9793-49b6-8583-9ba575075831",
...
}
]
```
If it is necessary to search for a RentalAgreement, a GET with query parameters can be used. The returned result is a JSON representing a list of RentalAgreements. If no object is found with the parameters sent, HTTP Status 200 is returned with an empty list in the response body.
`GET https://api.caas.qitech.app/car_rental/rental_agreements?initial_date=2019-10-01&final_date=2019-10-05&page_number=2&page_rows=20`
The following parameters can be used to search for RentalAgreement objects:
| Parameter | Default | Description |
| --------- | ----------- | -------------- |
| initial_date | null | First date that must be returned based on the rental_agreement_date field |
| final_date | null | Last date that must be returned based on the rental_agreement_date field |
| store_code | null | Code of the store from which the results must be returned |
| page_number | 1 | Number of the desired results page |
| page_rows | 50 | Maximum number of objects to be returned in a query |
---
# RentalAgreement-v2
URL: /en/documentation/caas/car_rental/rental_agreement_v2
Esta seção diz respeito ao fluxo de análise de fraude com a scoragem principal ocorrendo na reserva.
Ao realizar a retirada de um veículo na loja, o locatário dá início ao seu processo de anti-fraude. Os dados enviados deverão ser os dados finais, que não serão alterados. Isto é importante para garantir dois pontos:
- Consistência dos dados na base de dados do Antifraude
- Avaliação realista do risco
O processo de análise consiste em enviar um RentalAgreement no endpoint adequado e esperar a resposta. Existem oito resultados possíveis, devolvido na flag **fraud_status**:
| Resultado | Descrição |
| :---------: | --------- |
| Aprovado Automaticamente | Recomenda-se que este aluguel seja aprovado |
| Negado Automaticamente | Recomenda-se que este aluguel seja reprovado |
| Derivado para análise manual | Nossas regras ou modelos não estão confiantes da decisão e decidiram enviar este aluguel para a análise manual. |
| Aprovado Manualmente | Após análise manual, o analista escolheu aprovar o aluguel |
| Reprovado Manualmente | Após análise manual, o analista escolheu reprovar o aluguel |
| Desafiado Manualmente | Após análise manual, o analista retorna para a loja que a CNH e/ou Selfie estão incorretas e/ou com baixa qualidade |
| Pendente | As consultas estão demorando mais do que o esperado, este aluguel entrou em uma fila de análise automática e será respondido por meio de Webhook |
| Não analisado | A consulta foi enviada com a flag de análise falsa, o que significa que nossos sistemas não deverão retornar parecer |
### Dinâmica dos Status
Ao recuperar um objeto do tipo RentalAgreement os status estão disponíveis. Além dos status, um histórico de modificações também são retornados para que possa ser consultado no futuro. Estas modificações são entituladas events e possuem, além do novo status, as datas de modificação.
### Dinâmica dos Status - **car_status**
O status **car_status** relacionado a um RentalAgreement indica a situação do carro relacionado a este aluguel, isto é, se o carro foi devolvido ou não. Os seguintes enumeradores existem para este status:
- `rented`
- `returned`
- `recovered`
- `written_off`
### Dinâmica dos Status - **fraud_status**
O status **fraud_status** indica o status da decisão do motor de fraude e possui uma máquina de estados bastante simples:
- `created`
- `automatically_approved`
- `automatically_reproved`
- `in_manual_analysis`
- `manually_approved`
- `manually_reproved`
- `manually_challenged`
- `pending`
- `not_analyzed`
Além disso, o upgrade_status também possui os mesmos enumeradores.
## Definição do Objeto
```json
{
"id": "bca6268e-918a-4658-9161-a10b00a631ab",
"rental_agreement_code" : "12345678",
"rental_agreement_date": "2020-03-31T10:30:00-03:00",
"car_rental_estimated_final_date": "2020-04-01T10:28:00-03:00",
"reservation": {
"id": "0",
"channel": "reservation_central",
"reservation_date": "2020-03-31T08:15:00-03:00",
"sales_channel" : "PARCERIA TELEFONICA"
},
"rental_store": "SAOP",
"rental_store_group": "GSP",
"rental_store_type": "LOJA DE RUA",
"devolution_store": "SAOP",
"risky_antecedence": true,
"car": {
"model_group": "AM",
"upgrade_model_group": "SV",
"rental_daily_price" : 48496,
"risky_model_group": true,
"risky_upgrade_model_group": true
},
"client": {
"type": "natural_person",
"segment": "ota",
"document_number": "123.456.789-00",
"name": "John Sample",
"gender": "female",
"birthdate": "2001-01-15",
"mother_name": "Mary Sample",
"email": "john.sample@sample.com.br",
"allowed_information_on_email": true,
"face_picture": "c77d1925-0e72-4634-8393-395dbbce498d",
"additional_pictures": [
"718b8caa-8ef5-446c-b101-2dbf6c7e401f",
"9c67f365-1427-4889-b963-d3729d437ff3",
"8006f82c-3a80-4371-914e-e88c91507711",
"42c6909e-51aa-4b6d-972f-f4684a047993",
"b7a88947-96bd-4557-81e9-a69a3c84f428"
],
"total_rents": 6,
"fidelity_points": 1200,
"documents": {
"rg": {
"document_number": "00000000",
"issuer": "SSP"
},
"cnh": {
"document_number": "000000000",
"security_code": "00000",
"first_issuance": "2015-07-20",
"expiration_date": "2030-07-26",
"state": "SP"
}
},
"residential_address": {
"street": "Av Brigadeiro Faria Lima",
"number": "2391",
"neighborhood": "Jardins",
"city": "SÃO PAULO",
"uf": "SP",
"complement": "",
"postal_code": "00000-000"
},
"commercial_address": {
"street": "Av Brigadeiro Faria Lima",
"number": "2391",
"neighborhood": "Jardins",
"city": "SÃO PAULO",
"uf": "SP",
"complement": "",
"postal_code": "00000-000"
},
"phones": [
{
"international_dial_code": "55",
"area_code": "11",
"number": "00000-0000",
"type": "mobile"
},
{
"international_dial_code": "55",
"area_code": "11",
"number": "00000-0000",
"type": "residential"
}
]
},
"coverages": [
{
"description": "S/ PROTEÇÃO AMERICAN PLATINUM",
"price": 0
},
{
"description": "PROTEÇÃO OCUPANTES E TERCEIROS",
"price": 1668
}
],
"billing": {
"name": "Agência AAA",
"document_number": "00.000.000/0001-00",
"voucher_type": "ABCD75",
"voucher_description": "Pagamento pela agência"
},
"fare_name": "Mensal",
"rental_price": 43300,
"extra_hours": 0,
"extra_hours_price": 0,
"discount": 0,
"prepayment_discount": 100,
"extra_kms": 0,
"extra_kms_price": 0,
"third_party_coverage_price": 1490,
"coverage_price": 0,
"additional_driver_price": 1000,
"driver_service_price": 1000,
"additional_expenses": 1000,
"devolution_fee": 0,
"administration_fee": 5374,
"discount_partial_coverage": 50,
"free_day_discount": 20000,
"final_price": 50165,
"pre_authorization_amount": 0,
"coverage_deductible_amount": 0,
"upgrade_reason": "granted"
}
```
Todas as trocas de informação de um RentalAgreement utilizam a seguinte definição para este objeto. Em alguns casos, para facilitar a implementação e diminuir o fluxo de dados entre as partes, algumas informações poderão ser omitidas.
| nome | tipo | descrição |
| :----: | :----: | --------- |
| **id** | string | Identificador da requisição de análise no sistema do cliente. **É essencial que este número seja único para cada aluguel.** *(obrigatório)* |
| **rental_agreement_code** | string | Identificador do RentalAgreement no sistema do cliente. *(obrigatório)* |
| **rental_agreement_date** | DateTime | Data e Hora com fuso-horário da retirada do veículo do aluguel que está ocorrendo. *(obrigatório)* |
| **car_rental_estimated_final_date** | DateTime | Data e Hora com fuso-horário de quando o carro deve ser resolvido. *(obrigatório)* |
| **reservation** | *reservation* | Objeto que carrega as propriedades da reserva que deu origem a esse aluguel. *(obrigatório)* |
| **rental_store** | *store* | Loja onde o carro está sendo retirado. *(obrigatório)* |
| rental_store_group | *store* | Filial da loja onde o carro está sendo retirado |
| rental_store_type | *store* | Tipo da loja onde o carro será retirado |
| **devolution_store** | *store* | Loja onde o carro será devolvido, pode ou não ser a mesma loja de retirada. *(obrigatório)* |
| **car** | *car* | Carro que está sendo retirado - é importante que este valor seja, de fato, o carro sendo retirado. *(obrigatório)* |
| **client** | *client* | Objeto que carrega as informações do cliente que está retirando o veículo. *(obrigatório)* |
| **coverages** | List of *coverage* | Lista de objetos coverage que descrevem as coberturas de seguro contratadas pelo cliente. *(obrigatório)* |
| **billing** | *billing* | Objeto que descreve os detalhes da pessoa ou empresa responsável pelo pagamento do aluguel. *(obrigatório)* |
| **rental_price** | integer | Preço do aluguel, em centavos. *(obrigatório)* |
| **extra_hours** | integer | Quantidade de horas extras contratadas. *(obrigatório)* |
| **extra_hours_price** | integer | Preço das horas extras contratadas, em centavos. *(obrigatório)* |
| **discount** | inteiro | Desconto concedido por quaisquer motivos, em centavos. *(obrigatório)* |
| **prepayment_discount** | inteiro | Desconto por pagamento antecipado. |
| **extra_kms** | integer | Quantidade de kilômetros extras contratados. *(obrigatório)* |
| **extra_kms_price** | integer | Preço de kilômetros extras contratados, em centavos. *(obrigatório)* |
| **third_party_coverage_price** | integer | Preço do seguro de terceiros, em centavos. *(obrigatório)* |
| **coverage_price** | integer | Preço do seguro contratado, em centavos. *(obrigatório)* |
| additional_driver_price | integer | Preço total do(s) motoristas adicionais contratados, em centavos. |
| driver_service_price | integer | Preço total do serviço de motorista contratado, em centavos. |
| additional_expenses | integer | Despesas adicionais, em centavos |
| **devolution_fee** | integer | Preço da taxa de devolução, em centavos. *(obrigatório)* |
| **administration_fee** | integer | Preço da taxa de administração, em centavos. *(obrigatório)* |
| **discount_partial_coverage** | integer | Desconto de proteção parcial, em centavos. |
| **free_day_discount** | integer | Desconto de Free Day, em centavos. |
| **final_price** | integer | Preço final do aluguel, em centavos. *(obrigatório)* |
| pre_authorization_amount | integer | Valor da pré-autorização, em centavos. |
| **coverage_deductible_amount** | integer | Valor dedutível da cobertura, em centavos. *(obrigatório)* |
| upgrade_reason | enum | Tipo de upgrade (Concedido ou Comprado) - Aceita os valores `granted` e `bought` respectivamente |
## Enviar um RentalAgreement
Exemplo de Request:
```json
{
"id": "bca6268e-918a-4658-9161-a10b00a631ab",
...
}
```
Exemplo de Retorno:
```json
{
"id": "bca6268e-918a-4658-9161-a10b00a631ab",
"fraud_status": "automatically_approved",
"pre_authorization_amount": 100000,
"block_document_number": true,
"upgrade_status": "automatically_approved",
"highest_allowed_car_group": "SV",
"score": 870
}
```
Para realizar a avaliação de um aluguel, basta enviar um objeto do tipo RentalAgreement ao seguinte endpoint com a flag setada adequadamente:
`POST https://api.caas.qitech.app/car_rental/rental_agreement?analyze=true`
Além do status do retorno, também é retornado, caso haja, o valor da pré autorização desejada. Caso nenhuma majoração de pré autorização seja identificada, o valor retornado é nulo e não deve ser utilizado.
O grupo máximo que pode ser fornecido naquele RA é disponibilizado na variável `highest_allowed_car_group`. Este valor é configurado na regra de avaliação do RA.
O parâmetro *analyze* existe para evitar que transações que não precisam ser analisadas passem pelos motores de fraude, sujando a base de dados. O valor padrão deste parâmetro é **true**, de maneira que somente alugueis que forem explícitamente retirados da análise não serão analisados.
## Atualizar o status de um RentalAgreement
Corpo da requisição - Na efetivação de um aluguel de um carro:
```json
{
"car_status": "rented",
"event_date": "2019-11-05T13:34:12-03:00"
}
```
Corpo da requisição - Na devolução sem incidentes de um carro:
```json
{
"car_status": "returned",
"event_date": "2019-11-05T13:34:12-03:00"
}
```
Corpo da requisição - Na devolução mediante recuperação por roubo:
```json
{
"car_status": "recovered",
"incident": "theft",
"event_date": "2019-11-05T13:34:12-03:00"
}
```
Corpo da requisição - Write-off com fraude confirmada:
```json
{
"car_status": "written_off",
"incident": "misappropriation",
"event_date": "2019-11-05T13:34:12-03:00"
}
```
Para garantir a retroalimentação das regras e do modelo de inteligência artificial implementado, é necessário informar ao sistema quando os carros são alugados, devolvidos, ou quando são jogados a perda por fraude. Para isso, requisições com o método PUT devem ser utilizadas, passando-se como referência o id enviado na criação do *rental_agreement*, autenticadas normalmente:
`PUT https://api.caas.qitech.app/car_rental/rental_agreement/{rental_agreement_id}`
Caso o novo status seja *written_off*, os seguintes valores podem ser utilizados no campo **incident**, enviado no body da requisição, que indica o tipo de incidente do aluguel:
| Enumerador | Descrição |
| --------- | ----------- |
| theft | RAs que sofreram um roubo |
| misappropriation | RAs que foram classificados como apropriação indébita |
## Atualizar o veículo de um RentalAgreement
Corpo da requisição - Atualização de um veículo no aluguel:
```json
{
"car_plate": "ABC1B34",
"car_model": "Chevrolet Onix",
"model_group": "B",
"event_date": "2020-10-15T13:34:12-03:00"
}
```
Para garantir a consistência entre as ocorrências de fraude e os aluguéis e garantir o retreinamento do modelo de score, é necessário informar ao sistema os dados de cada carro quando ele é atrelado ao aluguel. Para isso, requisições com o método POST devem ser utilizadas, passando-se como referência o id enviado na criação do *rental_agreement*, autenticadas normalmente:
`POST https://api.caas.qitech.app/car_rental/rental_agreement/{rental_agreement_id}/car`
No body da requisição devem ser enviados os dados do veículo que está sendo atrelado àquele aluguel:
| nome | tipo | descrição |
| ---- | :----: | --------- |
| car_plate | string | Placa do veículo. |
| car_model | string | Modelo do veículo, incluindo sua marca e modelo (ex.: Jeep Renegade). |
| model_group | string | O grupo do veículo, em letras maiúsculas. |
| event_date | DateTime | Data e Hora com fuso-horário do momento em que ocorreu a associação do carro ao aluguel. |
## Recuperar um RentalAgreement
A fim de recuperar um RentalAgreement específico, basta realizar uma requisição GET. O resultado retornado é o json mais atualizado do RentalAgreement em questão. Caso este identificador não esteja relacionado a nenhum objeto, o HTTP Status 404 é retornado.
`GET https://api.caas.qitech.app/car_rental/rental_agreements/{rental_agreement_id}`
```shell
curl "https://api.caas.qitech.app/car_rental/rental_agreements/{rental_agreement_id}"
-H "Authorization: TESTETESTETESTE"
```
## Buscar RentalAgreements
Retorno - uma lista de objetos RentalAgreement:
```json
[
{
"id": "bca6268e-918a-4658-9161-a10b00a631ab",
...
},
{
"id": "13a91409-9793-49b6-8583-9ba575075831",
...
}
]
```
Caso seja necessário buscar um RentalAgreement, um GET com parâmetros de query poderá ser utilizado. O resultado retornado é um JSON que representa uma lista de RentalAgreements. Caso nenhum objeto seja encontrado com os parâmetros enviados, o HTTP Status 200 é retornado com uma lista vazia no corpo da resposta.
`GET https://api.caas.qitech.app/car_rental/rental_agreements?initial_date=2019-10-01&final_date=2019-10-05&page_number=2&page_rows=20`
Os seguintes parâmetros podem ser utilizados para buscar objetos de RentalAgreement:
| Parâmetro | Padrão | Descrição |
| --------- | ----------- | -------------- |
| initial_date | null | Primeira data que deve ser retornada a partir do campo rental_agreement_date |
| final_date | null | Última data que deve ser retornada a partir do campo rental_agreement_date |
| store_code | null | Código da loja de onde os resultados devem ser retornados |
| page_number | 1 | Número da página de resultados desejada |
| page_rows | 50 | Número de objetos máximo a ser retornados em uma consulta |
---
# Reservation-v1
URL: /en/documentation/caas/car_rental/reservation
Ao realizar a reserva de um veículo, o locatário dá início ao seu processo de anti-fraude. Os dados enviados deverão ser os dados finais da reserva, que não serão alterados. Isto é importante para garantir dois pontos:
- Consistência dos dados na base de dados do Antifraude
- Avaliação realista do risco
O processo de análise consiste em enviar uma Reservation no endpoint adequado e esperar a resposta. Existem oito resultados possíveis, devolvido na flag **fraud_status**:
| Resultado | Descrição |
| :---------: | --------- |
| Aprovado Automaticamente | Recomenda-se que este aluguel seja aprovado |
| Negado Automaticamente | Recomenda-se que este aluguel seja reprovado |
| Derivado para análise manual | Nossas regras ou modelos não estão confiantes da decisão e decidiram enviar este aluguel para a análise manual. |
| Aprovado Manualmente | Após análise manual, o analista escolheu aprovar o aluguel |
| Reprovado Manualmente | Após análise manual, o analista escolheu reprovar o aluguel |
| Desafiado Manualmente | Após análise manual, o analista retorna para a loja que a CNH e/ou Selfie estão incorretas e/ou com baixa qualidade |
| Pendente | As consultas estão demorando mais do que o esperado, este aluguel entrou em uma fila de análise automática e será respondido por meio de Webhook |
| Não analisado | A consulta foi enviada com a flag de análise falsa, o que significa que nossos sistemas não deverão retornar parecer |
### Dinâmica dos Status
Ao recuperar um objeto do tipo Reservation os status estão disponíveis. Além dos status, um histórico de modificações também são retornados para que possa ser consultado no futuro. Estas modificações são entituladas events e possuem, além do novo status, as datas de modificação.
### Dinâmica dos Status - **fraud_status**
O status **fraud_status** indica o status da decisão do motor de fraude e possui uma máquina de estados bastante simples:
- `created`
- `automatically_approved`
- `automatically_reproved`
- `in_manual_analysis`
- `manually_approved`
- `manually_reproved`
- `pending`
- `not_analyzed`
## Definição do Objeto
```json
{
"id": "bca6268e-918a-4658-9161-a10b00a631ab",
"reservation_code": "211034324",
"reservation_date": "2020-03-31T08:15:00-03:00",
"rental_agreement_date": "2020-03-31T10:30:00-03:00",
"car_rental_estimated_final_date": "2020-04-01T10:28:00-03:00",
"channel": "reservation_central",
"sales_channel" : "PARCERIA TELEFONICA",
"rental_store": "SAOP",
"rental_store_group": "GSP",
"rental_store_type": "LOJA DE RUA",
"devolution_store": "SAOP",
"car": {
"model_group": "SV",
"rental_daily_price" : 48496
},
"client": {
"type": "natural_person",
"segment": "ota",
"document_number": "123.456.789-00",
"name": "John Sample",
"gender": "female",
"birthdate": "2001-01-15",
"mother_name": "Mary Sample",
"email": "john.sample@sample.com.br",
"allowed_information_on_email": true,
"face_picture": "c77d1925-0e72-4634-8393-395dbbce498d",
"additional_pictures": [
"718b8caa-8ef5-446c-b101-2dbf6c7e401f",
"9c67f365-1427-4889-b963-d3729d437ff3",
"8006f82c-3a80-4371-914e-e88c91507711",
"42c6909e-51aa-4b6d-972f-f4684a047993",
"b7a88947-96bd-4557-81e9-a69a3c84f428"
],
"documents": {
"rg": {
"document_number": "00000000",
"issuer": "SSP"
},
"cnh": {
"document_number": "000000000",
"security_code": "00000",
"first_issuance": "2015-07-20",
"expiration_date": "2030-07-26",
"state": "SP"
}
},
"residential_address": {
"street": "Av Brigadeiro Faria Lima",
"number": "2391",
"neighborhood": "Jardins",
"city": "SÃO PAULO",
"uf": "SP",
"complement": "",
"postal_code": "00000-000"
},
"commercial_address": {
"street": "Av Brigadeiro Faria Lima",
"number": "2391",
"neighborhood": "Jardins",
"city": "SÃO PAULO",
"uf": "SP",
"complement": "",
"postal_code": "00000-000"
},
"phones": [
{
"international_dial_code": "55",
"area_code": "11",
"number": "00000-0000",
"type": "mobile"
},
{
"international_dial_code": "55",
"area_code": "11",
"number": "00000-0000",
"type": "residential"
}
]
},
"coverages": [
{
"description": "S/ PROTEÇÃO AMERICAN PLATINUM",
"price": 0
},
{
"description": "PROTEÇÃO OCUPANTES E TERCEIROS",
"price": 1668
}
],
"billing": {
"name": "Agência AAA",
"document_number": "00.000.000/0001-00",
"voucher_type": "ABCD75",
"voucher_description": "Pagamento pela agência"
},
"rental_price": 43300,
"extra_hours": 0,
"extra_hours_price": 0,
"discount": 0,
"prepayment_discount": 100,
"extra_kms": 0,
"extra_kms_price": 0,
"third_party_coverage_price": 1490,
"coverage_price": 0,
"additional_driver_price": 1000,
"driver_service_price": 1000,
"additional_expenses": 1000,
"devolution_fee": 0,
"administration_fee": 5374,
"discount_partial_coverage": 50,
"final_price": 50165,
"pre_authorization_amount": 0,
"coverage_deductible_amount": 0
}
```
Todas as trocas de informação de uma Reservation utilizam a seguinte definição para este objeto. Em alguns casos, para facilitar a implementação e diminuir o fluxo de dados entre as partes, algumas informações poderão ser omitidas.
| nome | tipo | descrição |
| :----: | :----: | --------- |
| **id** | string | Identificador da requisição de análise no sistema do cliente. **É essencial que este número seja único para cada análise.** *(obrigatório)* |
| reservation_code | string | Identificador da Reserva no sistema do cliente. - Este campo é opcional e pode ser definido utilizando o método PUT |
| **reservation_date** | DateTime | Data e Hora com fuso-horário do momento em que ocorreu a reserva para este aluguel. *(obrigatório)* |
| **rental_agreement_date** | DateTime | Data e Hora com fuso-horário da retirada do veículo do aluguel. *(obrigatório)* |
| **car_rental_estimated_final_date** | DateTime | Data e Hora com fuso-horário de quando o carro deve ser resolvido. *(obrigatório)* |
| **rental_store** | *store* | Loja onde o carro será retirado. *(obrigatório)* |
| rental_store_group | *store* | Filial da loja onde o carro será retirado |
| rental_store_type | *store* | Tipo da loja onde o carro será retirado |
| **devolution_store** | *store* | Loja onde o carro será devolvido, pode ou não ser a mesma loja de retirada. *(obrigatório)* |
| reservation_channel | string | Canal pelo qual foi feito a reserva para este aluguel. |
| **sales_channel** | string | Canal de vendas pelo qual a reserva foi realizada (ex.: PARCERIA MASTERCARD). *(obrigatório)* |
| **car** | *car* | Carro que será retirado. *(obrigatório)* |
| **client** | *client* | Objeto que carrega as informações do cliente que fará a retirada do veículo. *(obrigatório)* |
| **coverages** | List of *coverage* | Lista de objetos coverage que descrevem as coberturas de seguro contratadas pelo cliente. *(obrigatório)* |
| billing | *billing* | Objeto que descreve os detalhes da pessoa ou empresa responsável pelo pagamento do aluguel. |
| **rental_price** | integer | Preço do aluguel, em centavos. *(obrigatório)* |
| **extra_hours** | integer | Quantidade de horas extras contratadas. *(obrigatório)* |
| **extra_hours_price** | integer | Preço das horas extras contratadas, em centavos. *(obrigatório)* |
| **discount** | inteiro | Desconto concedido por quaisquer motivos, em centavos. *(obrigatório)* |
| **prepayment_discount** | inteiro | Desconto por pagamento antecipado. *(obrigatório)* |
| **extra_kms** | integer | Quantidade de kilômetros extras contratados. *(obrigatório)* |
| **extra_kms_price** | integer | Preço de kilômetros extras contratados, em centavos. *(obrigatório)* |
| **third_party_coverage_price** | integer | Preço do seguro de terceiros, em centavos. *(obrigatório)* |
| coverage_price | integer | Preço do seguro contratado, em centavos. |
| **additional_driver_price** | integer | Preço total do(s) motoristas adicionais contratados, em centavos. *(obrigatório)* |
| **driver_service_price** | integer | Preço total do serviço de motorista contratado, em centavos. *(obrigatório)* |
| **additional_expenses** | integer | Despesas adicionais, em centavos. *(obrigatório)* |
| **devolution_fee** | integer | Preço da taxa de devolução, em centavos. *(obrigatório)* |
| **administration_fee** | integer | Preço da taxa de administração, em centavos. *(obrigatório)* |
| **discount_partial_coverage** | integer | Desconto de proteção parcial, em centavos. *(obrigatório)* |
| **final_price** | integer | Preço final do aluguel, em centavos. *(obrigatório)* |
| **pre_authorization_amount** | integer | Valor da pré-autorização, em centavos. *(obrigatório)* |
| **coverage_deductible_amount** | integer | Valor dedutível da cobertura, em centavos. *(obrigatório)* |
## Enviar uma Reserva
Exemplo de Request:
```json
{
"id": "bca6268e-918a-4658-9161-a10b00a631ab",
...
}
```
Exemplo de Retorno:
```json
{
"reservation_key": "bca6268e-918a-4658-9161-a10b00a631ab",
"fraud_status": "automatically_approved",
"pre_authorization_amount": 10000
}
```
Para realizar a avaliação de uma reserva, basta enviar um objeto do tipo Reservation ao seguinte endpoint:
`POST https://api.caas.qitech.app/car_rental/reservation`
Além do status do retorno, também é retornado, caso haja, o valor da pré autorização desejada. Caso nenhuma majoração de pré autorização seja identificada, o valor retornado é nulo e não deve ser utilizado.
## Definir o código de uma Reserva
A QI Tech possibilita a definição do código da reserva após a análise inicial. Isto é útil em alguns fluxos operacionais. Nestes casos, basta realizar um PUT no endpoint a seguir, com o código da reserva definido no corpo:
`PUT https://api.caas.qitech.app/car_rental/reservation/{reservation_id}`
:::note
Caso o código da reserva tenha sido definido anteriormente, na requisição de POST ou utilizando um PUT, não é possível redefinir o código da reserva. Neste caso, a API retornará 409 - Conflito.
:::
```json
{
"reservation_code": "123456789"
}
```
## Recuperar uma Reserva
A fim de recuperar uma Reserva específica, basta realizar uma requisição GET. O resultado retornado é o json mais atualizado da Reserva em questão. Caso este identificador não esteja relacionado a nenhum objeto, o HTTP Status 404 é retornado.
`GET https://api.caas.qitech.app/car_rental/reservation/{reservation_id}`
```shell
curl "https://api.caas.qitech.app/car_rental/reservation/{reservation_id}"
-H "Authorization: TESTETESTETESTE"
```
---
# Reservation-v2
URL: /en/documentation/caas/car_rental/reservation_v2
Esta seção diz respeito às informações necessárias para o fluxo de análise de fraude primariamente na reserva.
Ao realizar a reserva de um veículo, o locatário dá início ao seu processo de anti-fraude. Os dados enviados deverão ser os dados finais da reserva, que não serão alterados. Isto é importante para garantir dois pontos:
- Consistência dos dados na base de dados do Antifraude
- Avaliação realista do risco
O processo de análise consiste em enviar uma Reservation no endpoint adequado e esperar a resposta. Existem oito resultados possíveis, devolvido na flag **fraud_status**:
| Resultado | Descrição |
| :---------: | --------- |
| Aprovado Automaticamente | Recomenda-se que este aluguel seja aprovado |
| Negado Automaticamente | Recomenda-se que este aluguel seja reprovado |
| Derivado para análise manual | Nossas regras ou modelos não estão confiantes da decisão e decidiram enviar este aluguel para a análise manual. |
| Aprovado Manualmente | Após análise manual, o analista escolheu aprovar o aluguel |
| Reprovado Manualmente | Após análise manual, o analista escolheu reprovar o aluguel |
| Desafiado Manualmente | Após análise manual, o analista retorna para a loja que a CNH e/ou Selfie estão incorretas e/ou com baixa qualidade |
| Pendente | As consultas estão demorando mais do que o esperado, este aluguel entrou em uma fila de análise automática e será respondido por meio de Webhook |
| Não analisado | A consulta foi enviada com a flag de análise falsa, o que significa que nossos sistemas não deverão retornar parecer |
### Dinâmica dos Status
Ao recuperar um objeto do tipo Reservation os status estão disponíveis. Além dos status, um histórico de modificações também são retornados para que possa ser consultado no futuro. Estas modificações são entituladas events e possuem, além do novo status, as datas de modificação.
### Dinâmica dos Status - **fraud_status**
O status **fraud_status** indica o status da decisão do motor de fraude e possui uma máquina de estados bastante simples:
- `created`
- `automatically_approved`
- `automatically_reproved`
- `in_manual_analysis`
- `manually_approved`
- `manually_reproved`
- `pending`
- `not_analyzed`
## Definição do Objeto
```json
{
"id": "bca6268e-918a-4658-9161-a10b00a631ab",
"reservation_code": "211034324",
"reservation_date": "2024-03-19T10:30:00-03:00",
"rental_agreement_date": "2024-03-25T10:30:00-03:00",
"car_rental_estimated_final_date": "2024-03-30T10:28:00-03:00",
"channel": "reservation_central",
"sales_channel" : "PARCERIA TELEFONICA",
"rental_store": "SAOP",
"rental_store_group": "GSP",
"rental_store_type": "LOJA DE RUA",
"devolution_store": "SAOP",
"risky_antecedence": true,
"car": {
"model_group": "SV",
"rental_daily_price" : 48496
},
"client": {
"type": "natural_person",
"segment": "ota",
"document_number": "123.456.789-00",
"name": "John Sample",
"gender": "female",
"birthdate": "2001-01-15",
"mother_name": "Mary Sample",
"email": "john.sample@sample.com.br",
"allowed_information_on_email": true,
"face_picture": "c77d1925-0e72-4634-8393-395dbbce498d",
"additional_pictures": [
"718b8caa-8ef5-446c-b101-2dbf6c7e401f",
"9c67f365-1427-4889-b963-d3729d437ff3",
"8006f82c-3a80-4371-914e-e88c91507711",
"42c6909e-51aa-4b6d-972f-f4684a047993",
"b7a88947-96bd-4557-81e9-a69a3c84f428"
],
"total_rents": 6,
"fidelity_points": 1200,
"documents": {
"rg": {
"document_number": "00000000",
"issuer": "SSP"
},
"cnh": {
"document_number": "000000000",
"security_code": "00000",
"first_issuance": "2015-07-20",
"expiration_date": "2030-07-26",
"state": "SP"
}
},
"residential_address": {
"street": "Av Brigadeiro Faria Lima",
"number": "2391",
"neighborhood": "Jardins",
"city": "SÃO PAULO",
"uf": "SP",
"complement": "",
"postal_code": "00000-000"
},
"commercial_address": {
"street": "Av Brigadeiro Faria Lima",
"number": "2391",
"neighborhood": "Jardins",
"city": "SÃO PAULO",
"uf": "SP",
"complement": "",
"postal_code": "00000-000"
},
"phones": [
{
"international_dial_code": "55",
"area_code": "11",
"number": "00000-0000",
"type": "mobile"
},
{
"international_dial_code": "55",
"area_code": "11",
"number": "00000-0000",
"type": "residential"
}
]
},
"coverages": [
{
"description": "S/ PROTEÇÃO AMERICAN PLATINUM",
"price": 0
},
{
"description": "PROTEÇÃO OCUPANTES E TERCEIROS",
"price": 1668
}
],
"billing": {
"name": "Agência AAA",
"document_number": "00.000.000/0001-00",
"voucher_type": "ABCD75",
"voucher_description": "Pagamento pela agência"
},
"fare_name": "MENSAL - 2000KM - PRÓ-RATA",
"rental_price": 43300,
"extra_hours": 0,
"extra_hours_price": 0,
"discount": 0,
"prepayment_discount": 100,
"extra_kms": 0,
"extra_kms_price": 0,
"third_party_coverage_price": 1490,
"coverage_price": 0,
"additional_driver_price": 1000,
"driver_service_price": 1000,
"additional_expenses": 1000,
"devolution_fee": 0,
"administration_fee": 5374,
"discount_partial_coverage": 50,
"final_price": 50165,
"pre_authorization_amount": 0,
"coverage_deductible_amount": 0
}
```
Todas as trocas de informação de uma Reservation utilizam a seguinte definição para este objeto. Em alguns casos, para facilitar a implementação e diminuir o fluxo de dados entre as partes, algumas informações poderão ser omitidas.
| nome | tipo | descrição |
| :----: | :----: | --------- |
| **id** | string | Identificador da requisição de análise no sistema do cliente. **É essencial que este número seja único para cada análise.** *(obrigatório)* |
| reservation_code | string | Identificador da Reserva no sistema do cliente. - Este campo é opcional e pode ser definido utilizando o método PUT. |
| **reservation_date** | DateTime | Data e Hora com fuso-horário do momento em que ocorreu a reserva para este aluguel. *(obrigatório)* |
| **car_rental_estimated_final_date** | DateTime | Data e Hora com fuso-horário de quando o carro deve ser resolvido. *(obrigatório)* |
| **rental_store** | *store* | Loja onde o carro será retirado. *(obrigatório)* |
| rental_store_group | *store* | Filial da loja onde o carro será retirado |
| rental_store_type | *store* | Tipo da loja onde o carro será retirado |
| **devolution_store** | *store* | Loja onde o carro será devolvido, pode ou não ser a mesma loja de retirada. *(obrigatório)* |
| reservation_channel | string | Canal pelo qual foi feito a reserva para este aluguel. |
| **sales_channel** | string | Canal de vendas pelo qual a reserva foi realizada (ex.: PARCERIA MASTERCARD). *(obrigatório)* |
| **car** | *car* | Objeto que carrega as informações do veículo sendo reservado. *(obrigatório)* |
| **client** | *client* | Objeto que carrega as informações do cliente que fará a retirada do veículo. *(obrigatório)* |
| **coverages** | List of *coverage* | Lista de objetos coverage que descrevem as coberturas de seguro contratadas pelo cliente. *(obrigatório)* |
| **billing** | *billing* | Objeto que descreve os detalhes da pessoa ou empresa responsável pelo pagamento do aluguel. *(obrigatório)* |
| **rental_price** | integer | Preço do aluguel, em centavos. *(obrigatório)* |
| **extra_hours** | integer | Quantidade de horas extras contratadas. *(obrigatório)* |
| **extra_hours_price** | integer | Preço das horas extras contratadas, em centavos. *(obrigatório)* |
| **discount** | inteiro | Desconto concedido por quaisquer motivos, em centavos. *(obrigatório)* |
| **prepayment_discount** | inteiro | Desconto por pagamento antecipado. *(obrigatório)* |
| **extra_kms** | integer | Quantidade de kilômetros extras contratados. *(obrigatório)* |
| **extra_kms_price** | integer | Preço de kilômetros extras contratados, em centavos. *(obrigatório)* |
| **third_party_coverage_price** | integer | Preço do seguro de terceiros, em centavos. *(obrigatório)* |
| coverage_price | integer | Preço do seguro contratado, em centavos. |
| **additional_driver_price** | integer | Preço total do(s) motoristas adicionais contratados, em centavos. *(obrigatório)* |
| **driver_service_price** | integer | Preço total do serviço de motorista contratado, em centavos. *(obrigatório)* |
| **additional_expenses** | integer | Despesas adicionais, em centavos. *(obrigatório)* |
| **devolution_fee** | integer | Preço da taxa de devolução, em centavos. *(obrigatório)* |
| **administration_fee** | integer | Preço da taxa de administração, em centavos. *(obrigatório)* |
| **discount_partial_coverage** | integer | Desconto de proteção parcial, em centavos. *(obrigatório)* |
| **final_price** | integer | Preço final do aluguel, em centavos. *(obrigatório)* |
| **pre_authorization_amount** | integer | Valor da pré-autorização, em centavos. *(obrigatório)* |
| **coverage_deductible_amount** | integer | Valor dedutível da cobertura, em centavos. *(obrigatório)* |
## Enviar uma Reserva
Exemplo de Request:
```json
{
"id": "bca6268e-918a-4658-9161-a10b00a631ab",
"reservation_code": "211034324",
...
}
```
Exemplo de Retorno:
```json
{
"reservation_key": "bca6268e-918a-4658-9161-a10b00a631ab",
"fraud_status": "automatically_approved",
"pre_authorization_amount": 10000
}
```
Para realizar a avaliação de uma reserva, basta enviar um objeto do tipo Reservation ao seguinte endpoint:
`POST https://api.caas.qitech.app/car_rental/reservation`
Além do status do retorno, também é retornado, caso haja, o valor da pré autorização desejada. Caso nenhuma majoração de pré autorização seja identificada, o valor retornado é nulo e não deve ser utilizado.
## Definir o código de uma Reserva
A QI Tech possibilita a definição do código da reserva após a análise inicial. Isto é útil em alguns fluxos operacionais. Nestes casos, basta realizar um PUT no endpoint a seguir, com o código da reserva definido no corpo:
`PUT https://api.caas.qitech.app/car_rental/reservation/{reservation_id}`
:::note
Caso o código da reserva tenha sido definido anteriormente, na requisição de POST ou utilizando um PUT, não é possível redefinir o código da reserva. Neste caso, a API retornará 409 - Conflito.
:::
```json
{
"reservation_code": "123456789"
}
```
## Recuperar uma Reserva
A fim de recuperar uma Reserva específica, basta realizar uma requisição GET. O resultado retornado é o json mais atualizado da Reserva em questão. Caso este identificador não esteja relacionado a nenhum objeto, o HTTP Status 404 é retornado.
`GET https://api.caas.qitech.app/car_rental/reservation/{reservation_id}`
```shell
curl "https://api.caas.qitech.app/car_rental/reservation/{reservation_id}"
-H "Authorization: TESTETESTETESTE"
```
---
# Padrões
URL: /en/documentation/caas/car_rental/standards
Para facilitar a integração e garantir a integridade da informação, foram definidos alguns padrões que são seguidos em toda a API.
## Valores Monetários
Exemplos:
```
10000
12345
98741
1223
1
0
```
As APIs assumem que todos os valores monetários enviados são em Reais Brasileiros. Os valores devem ser enviados como inteiro em centavos.
## Data e Hora com Fuso Horário
Alguns exemplos:
```
2019-10-15T22:35:12-03:00
2018-05-01T13:32:11+00:00
2019-05-01T00:00:00+00:00
```
É representada conforme a ISO 8601. Neste caso, o fuso-horário é colocado logo após o horário e deve representar o fuso do local onde aquele dado será válido. Por exemplo, se um aluguel estiver marcado para começar às 09:30 no aeroporto de Brasília, o horário enviado deverá ser representado por 09:30-03:00, se o aluguel estiver marcado para começar às 09:30 em Manaus, deverá ser representado por 09:30-04:00.
A máscara utilizada para validação é a seguinte:
`YYYY-MM-ddThh:mm:ss±hh:mm`
## Data e Hora sem Fuso Horário
Alguns exemplos:
```
2019-10-15T22:35:12Z
2018-05-01T13:32:11Z
2019-05-01T00:00:00Z
```
É representada conforme a ISO 8601. Dados que independem de fuso-horário deverão ser enviados sem ele, sempre em UTC, com a letra Z indicando que este dado está em UTC. O seguinte formato, portanto, será validado:
`YYYY-MM-ddThh:mm:ssZ`
## Data
Alguns exemplos:
```
2019-10-15
2019-01-01
2017-03-20
```
No caso de campos que recebem somente data, uma data de nascimento, por exemplo, somente a data, sem nenhum horário deve ser enviada com o seguinte formato:
`YYYY-MM-dd`
## Documentos
Uma vez que os números de documento são bastante variados e muitos deles possuem caracteres que não se enquadram como numéricos, definem-se todos os números de documento como string. Outro bom motivo para defini-los como string é evitar que os zeros à esquerda desapareçam. Documentos previstos nesta página possuem uma máscara bem definida e estarão sujeitos a validação. O restante dos documentos, como RG, dada sua falta de padronização, não serão validados.
## CPF
Exemplos de CPFs válidos contra a máscara definida:
```
123.456.789-12
321.987.543-23
111.283.333-00
```
Exemplos de CPFs inválidos contra a máscara definida:
```
8.577.477-8
08.104.627/0001-23
123.456.789-1
23.456.789-01
```
O CPF é sempre definido como uma string e será validado contra a máscara:
`###.###.###-##`
## CNPJ
Exemplos de CNPJs válidos contra a máscara definida:
```
08.104.627/0001-02
01.079.210/0114-67
32.402.502/0001-35
```
Exemplos de CNPJs inválidos contra a máscara definida:
```
8.577.477-8
123.456.789-12
321.987.543-23
32.402.502/0001-3
032.402.502/0001-3
```
O CNPJ é sempre definido como uma string e será validado contra a máscara:
`##.###.###/####-##`
---
# Webhook
URL: /en/documentation/caas/car_rental/webhook
Atualizações no status de fraude (Para RentalAgreements que sejam derivados para análise manual ou que sejam respondidos como Pendente), são notificados por meio de Webhook. Para tanto, é necessário, por meio da equipe do [suporte](mailto:suporte.caas@qitech.com.br), configurar um endereço do endpoint por onde vamos notificar as atualizações e também um *secret_token* que será utilizado para assinar a requisição.
O cliente pode, apesar de não recomendável, também utilizar a técnica de [polling](https://en.wikipedia.org/wiki/Polling_(computer_science)). Neste caso, basta não configurar o endpoint de webhook e utilizar os endpoints de recuperação de RentalAgreement para proceder com o polling.
## Assinatura
Exemplo de cálculo de assinatura em Python:
```python
hmac_obj = hmac.new(
signature_key.encode('utf-8'),
(endpoint + method + payload).encode('utf-8'),
hashlib.sha1
)
return hmac_obj.hexdigest()
```
Para garantir que a requisição recebida no endpoint do webhook parte dos nossos servidores, uma assinatura HMAC é enviada no Header Signature, semelhante ao processo de autenticação.
Após realizar o cálculo do valor esperado da assinatura do lado do servidor, é necessário comparar a assinatura calculada com a enviada. Caso as assinaturas sejam compatíveis, isso significa que a requisição partiu dos nossos servidores e que é confiável.
## Requisição
Exemplo de requisição:
```json
{
"rental_agreement_id": "123456",
"fraud_status": "automatically_approved",
"upgrade_status": "automatically_approved",
"event_date": "2019-10-01T10:37:25-03:00"
}
```
A requisição possui o formato acima e notifica a mudança no status de fraude.
## Retentativas
A notificação é considerada realizada quando recebe como resposta um HTTP Status 200. Caso as notificações falhem, serão feitas retentativas, com os seguintes intervalos, até que um 200 seja retornado ou as tentativas terminem:
- 10 segundos
- 30 segundos
- 60 segundos
- 120 segundos
- 120 segundos
- 3600 segundos
- 7200 segundos
- 36000 segundos
---
# Cardholder Alerts
URL: /en/documentation/caas/card_issuance/alerts
Alerts generated by the antifraud tool are notified via Webhook. To do so, it is necessary to configure an endpoint address through which we will send the notifications, as well as a *secret_token* that will be used to sign the request. This configuration must be done through our [support team](mailto:suporte.caas@qitech.com.br).
In this notification we will send information about the generated alerts, as well as which cardholder they refer to, so that the client can take action—for example, sending a *push notification* to the cardholder.
## Request
Request Body
```json
{
"alert_key": "123456",
"cardholder_id": "ef47bc3f-61ac-4b85-ad67-0cfa3a422201",
"company_name": "Cliente 1",
"irregularity_type" : "fraud",
"risk_level": "critical"
}
```
The request has the format above and notifies the opening of a new alert for a Cardholder — identified by *cardholder_id*.
## Webhook Signature
> Example of signature calculation in Python
```python
hmac_obj = hmac.new(signature_key.encode('utf-8'), (endpoint + method + payload).encode('utf-8'), hashlib.sha1)
return hmac_obj.hexdigest()
```
To ensure that the request received at the webhook endpoint comes from our servers, an HMAC signature is sent in the Signature header, similar to the authentication process.
After calculating the expected signature value on the server side, you must compare the calculated signature with the one sent. If the signatures match, this means that the request came from our servers and is trustworthy.
## Retries
The notification is considered successful when it receives an HTTP Status 200 as response. If the notifications fail, 5 retries will be made with the following intervals until a 200 is returned or the attempts are exhausted:
* 30 seconds
* 60 seconds
* 120 seconds
* 240 seconds
* 360 seconds
---
# Authentication
URL: /en/documentation/caas/card_issuance/authentication
> To authenticate a request, use the following code:
```shell
# In the shell, you only need to add the appropriate header to each request
curl "api_endpoint_here"
-H "Authorization: EXAMPLE-OF-API-KEY"
```
> Replace the API Key 'EXAMPLE-OF-API-KEY' with your own key, which should be obtained from our support team.
We use an API Key to grant access to our API. It was likely sent to you by email. If you haven't received your key yet, please send an email to suporte.caas@qitech.com.br .
Our API expects to receive the API Key in all requests to our server in a header like the one below:
`Authorization: EXAMPLE-OF-API-KEY`
:::info **Attention**
You must replace EXAMPLE-OF-API-KEY with your own key, which should be obtained from our support team.
:::
---
# HTTP Status Codes
URL: /en/documentation/caas/card_issuance/http_status
All QI Tech APIs follow the standard HTTP status codes as defined in the [RFC 7231](https://tools.ietf.org/html/rfc7231):
HTTP Status | Meaning | Description
----------- | ------- | ---------------------------------
400 | Bad Request | The request sent contains a formatting error. In most cases, we return a message body explaining where the error is.
401 | Unauthorized | There was a problem with authentication. Check if the API Key is correct and placed in the proper header, as explained in the [Authentication](https://docs.qitech.com.br/en/documentation/caas/card_issuance/authentication/index.html) section.
403 | Forbidden | The accessed endpoint is for internal use and not available for this API Key.
404 | Not Found | The requested data could not be found using the provided key. This status is also returned when an invalid endpoint is requested.
405 | Method Not Allowed | The HTTP method used is not supported by the requested endpoint.
406 | Not Acceptable | The data sent in the request body is invalid. Usually, this means the payload is not valid JSON.
409 | Conflict | The request ID corresponds to an ID that has already been processed. This status is returned in case of duplicate requests.
500 | Internal Server Error | We encountered an issue while processing the request. When this happens, our specialists are automatically notified and begin investigating immediately.
503 | Service Unavailable | You encountered an infrastructure outage, whether planned or unplanned, on our servers.
---
# Introduction
URL: /en/documentation/caas/card_issuance/introduction
Welcome to QI Tech's Card Issuance Fraud Prevention API! You can use our API to access the endpoints to receive the response of a transaction, as well as to update the status of a transaction.
:::info **Attention**
Please note that this API is intended for card issuers — that is, companies that issue the card to the cardholder so they can transact. Its purpose is to perform all security analysis on your client's transactions, preventing fraud and other types of incidents (such as transactions resulting from robberies).
:::
Below, you can see the API implementation using cURL. This gives you examples that you can adapt to the programming language of your choice.
## Issues?
We're not a company that hides behind an API! Reach out to our support team and we'll get back to you as soon as possible. Feel free to give us a call if you want a quicker answer!
### We love feedbacks
Even if you've already solved your issue or it is something simple (like a typo or a small organizational detail), feel free to send us an email. That way, we can keep improving our documentation and help the next person avoid the same difficulties you faced!
## Environments
We provide two environments for our clients. The base URLs for the APIs are:
* Production - `https://api.caas.qitech.app/card_issuance/`
* Sandbox - `https://api.sandbox.caas.qitech.app/card_issuance/`
:::danger Important Warning!
Real personal or company data must not be used in QI Tech's Sandbox environments.
:::
In the Sandbox environment, submitted analyses are not charged and are responded to according to predefined rules.
For transaction analysis, the following rule is applied based on the transaction amount:
Minimum | Maximum | Decision
------ | ------ | -------
10000 | - | automatically_approved
0 | 9999 | automatically_declined
## Only HTTPS
For security reasons, all communication with QI Tech's APIs must be conducted over HTTPS. To ensure that no HTTP calls are made, whether by oversight or any other reason, this server only makes port 443 available with TLS 1.2 communication. Requests using other protocols will be automatically rejected.
## Authentication
> To authenticate a request, use the following code:
```shell
# In the shell, you only need to add the appropriate header to each request
curl "api_endpoint_here"
-H "Authorization: EXAMPLE-OF-API-KEY"
```
> Replace the API Key 'EXAMPLE-OF-API-KEY' with your own key, which should be obtained from our support team.
We use an API Key to grant access to our API. It was likely sent to you by email. If you haven't received your key yet, please send an email to suporte.caas@qitech.com.br .
Our API expects to receive the API Key in all requests to our server in a header like the one below:
`Authorization: EXAMPLE-OF-API-KEY`
:::info **Attention**
You must replace EXAMPLE-OF-API-KEY with your own key, which should be obtained from our support team.
:::
---
# Standards
URL: /en/documentation/caas/card_issuance/standards
To simplify integration and ensure data integrity, some standards have been defined and are followed throughout the API.
## Monetary Values
> Examples:
```
10000
12345
98741
1223
1
0
```
Values must be sent as integers in cents.
## Date and Time with Timezone
> Some examples:
```
2019-10-15T22:35:12-03:00
2018-05-01T13:32:11+00:00
2019-05-01T00:00:00+00:00
```
It is represented according to the ISO 8601 standard. In this case, the timezone is placed immediately after the time and should represent the timezone of the location where that data will be valid. For example, if a rental is scheduled to start at 09:30 at Brasília airport, the time sent should be represented as 09:30-03:00; if the rental is scheduled to start at 09:30 in Manaus, it should be represented as 09:30-04:00.
The validation mask is as follows:
`YYYY-MM-ddThh:mm:ss±hh:mm`
## Date and Time without Timezone
> Some examples:
```
2019-10-15T22:35:12Z
2018-05-01T13:32:11Z
2019-05-01T00:00:00Z
```
It is represented according to the ISO 8601 standard. Data that is independent of timezones should be sent without one, always in UTC, using the letter Z to indicate that the data is in UTC. Therefore, the following format will be validated:
`YYYY-MM-ddThh:mm:ssZ`
## Date
> Some examples:
```
2019-10-15
2019-01-01
2017-03-20
```
For fields that only receive a date—such as a birthdate—only the date, without any time, should be sent in the following format:
`YYYY-MM-dd`
---
# Transaction
URL: /en/documentation/caas/card_issuance/transaction
When the cardholder initiates a transaction, the data must be sent to our server so that we can perform a risk analysis on that set of data.
## Object Definition
Request Body
```json
{
"id": "678",
"cardholder_id": "b812da2e-e6be-4712-8e57-6f3f2791625b",
"group_id" : "8507884b-c30f-4b45-951c-f0bf366926fc",
"amount": 13725,
"currency": "BRL",
"brl_converted_amount": 13725,
"installments": 6,
"authorization_date": "2019-11-10T13:25:42.123-03:00",
"authorization_type": "authorization",
"transaction_type": "credit",
"pan_entry_mode": "chip",
"pin_sent": true,
"source_account": "saving_account",
"location": {
"latitude": -45.2753548,
"longitude": -15.24587
},
"terminal": {
"id": "123456",
"country_code": "BRA",
"terminal_type": "2",
"pin_entry_capability": true,
"magnetic_stripe_capability": true,
"contactless_capability": false,
"chip_capability": true
},
"merchant": {
"acquirer_id": "250",
"merchant_id": "123456",
"name": "VASP LINHAS AEREAS",
"street" : "RUA CMDTE X, 127",
"city" : "SAO PAULO, SP",
"region": "BRA",
"postal_code": "04570-140",
"mcc": "3036"
},
"card": {
"brand": "visa",
"category": "black",
"issuing_date": "2019-10-08T07:13:12.333-03:00",
"unblock_date": "2019-10-12T07:13:12.333-03:00",
"expiration_date": "2019-12-31",
"bin": "498406",
"last4": "1234",
"total_credit_limit": 2500000,
"used_credit_limit": 732625,
"issuer_country_code": "BRA"
},
"transaction_status" : "authorized",
"response_code": "05"
}
```
A transaction must be sent to the API before the transaction is authorized and can be used to make the decision to generate (or not) an authorization code. The data sent can also be used to generate alerts based on the cardholder's transaction history, so that if there is behavior different from expected, the alert triggers an appropriate action to mitigate the impact of the transactions.
The fraud statuses (**fraud_status** and **transaction_status**) represent, respectively, the decision returned by the model for that transaction and whether the transaction was completed, cancelled, or became a dispute.
The following statuses are used in **transaction_status**:
* `not_authorized`
* `authorized`
* `cleared`
* `cancelled`
* `partially_cancelled`
* `chargeback`
* `partial_chargeback`
The following statuses are used in **fraud_status**:
* `automatically_approved`
* `automatically_declined`
* `not_analyzed`
Below are the meanings of each decision returned in the **fraud_status** field:
Result | Description
:---------: | ---------
automatically_approved | This transaction is recommended to be approved
automatically_declined | This transaction is recommended to be declined
not_analyzed | The request was sent with the analysis flag set to false, meaning our systems should not return a decision
name | type | description |
:----: | :----: | ---------
id | string | *(required)* Transaction identifier in the client's system. **It is essential that this number be unique for each authorization process**
cardholder_id | string | *(required)* Cardholder identifier in the client's system — as registered in the Onboarding API
group_id | string | *(optional)* Identifier of which group or category that user belongs to within the client's system
amount | integer | *(required)* The transaction amount — as described in the "Standards" section
currency | string | *(required)* The currency used in the transaction — ISO 4217 and ApplicationCurrencyCode from 8583
brl_converted_amount | integer | *(required)* The transaction amount converted to Brazilian Reais — as described in the "Standards" section
installments | integer | *(required)* The number of installments used in the transaction
authorization_date | datetime | *(required)* The date and time when the transaction started, with timezone
authorization_type | enumerator | *(required)* Authorization or pre-authorization transaction?
transaction_type | enumerator | *(required)* Credit, Debit or Voucher
pan_entry_mode | enumerator | *(required)* PAN entry mode — Chip, Keyed, Magnetic Stripe, Fallback, Contactless—Field from ISO 8583 (DE 22 - Sub Field 1)
pin_sent | boolean | *(required)* Was a PIN entered at the terminal? — Field from entry_mode in ISO 8583
source_account | enumerator | *(optional)* Whether the transaction amount should be taken from the bill, checking account or savings—Field from Processing Code in ISO 8583
location.latitude | number | *(optional)* The latitude where the transaction occurred—if there is a linked mobile device or another means of capturing the location
location.longitude | number | *(optional)* The longitude where the transaction occurred
terminal.id | string | *(optional)* The terminal identifier sent by the acquirer in the authentication messaging
terminal.country_code | string | *(required)* The country code of the terminal, sent in the authorization message per ISO 3166-1 alpha-3, field from Terminal Country Code in ISO 8583
terminal.terminal_type | string | *(required)* The terminal type as received in the authorization messaging — Field from TerminalType in ISO 8583
terminal.pin_entry_capability | boolean | *(required)* Is it possible to enter the card PIN at the terminal? — Field from TerminalPINEntryCapability in ISO 8583
terminal.magnetic_stripe_capability | boolean | *(optional)* Can the terminal read magnetic stripe? — Field TerminalPANEntryCapability (DE 123) in ISO 8583
terminal.contactless_capability | boolean | *(optional)* Can the terminal initiate contactless transactions? — Field TerminalPANEntryCapability (DE 123) in ISO 8583
terminal.chip_capability | boolean |*(required)* Can the terminal initiate transactions using the EMV chip? — Field TerminalPANEntryCapability (DE 123) in ISO 8583
merchant.acquirer_id | string | *(required)* The acquirer identifier as per authorization messaging — Field Acquirer Identifier (DE 32) in ISO 8583
merchant.merchant_id | string | *(required)* The merchant identifier at the acquirer as per authorization messaging — Field Merchant Identifier in ISO 8583
merchant.name | string | *(optional)* The merchant name according to authorization messaging—Field Merchant Name in ISO 8583
merchant.street | string | *(optional)* The street address of the merchant — Field Card Acceptor Street Address
merchant.city | string | *(optional)* The city of the merchant's address — Field Card Acceptor City
merchant.region | string | *(optional)* The region of the merchant's address — Field Card Acceptor Region Code
merchant.postal_code | string | *(optional)* The postal code of the merchant's address — Field Card Acceptor Postal Code
merchant.mcc | string | *(required)* Merchant Category Code, according to ISO 18245 and ISO 8583
card.brand | enumerator | *(required)* The card brand (visa, mastercard, elo...)
card.category | enumerator | *(required)* The card category (classic, gold, platinum, black, infinite, corporate)
card.issuing_date | datetime | *(required)* The date and time when the card was issued, with timezone
card.unblock_date | datetime | *(optional)* The date and time when the card was unblocked by the cardholder, with timezone
card.expiration_date | date | *(required)* The card expiration date (last day of the month)
card.bin | string | *(required)* The BIN of the card being used
card.last4 | string | *(required)* The last four digits of the card, used to identify the card within the issuer
card.total_credit_limit | number | *(optional)* The total credit limit granted to the cardholder. If the card is prepaid, the existing credit balance on the card
card.used_credit_limit | number | *(optional)* The amount of limit already used (before the transaction in question)
card.issuer_country_code | string | *(required)* The issuer country per ISO 3166-1 alpha-3
transaction_status | enumerator | *(optional)* The transaction status, when sent with ***analyze=false*** flag and authorization decision has already been made.
response_code | enumerator | *(optional)* The transaction response code per the Response Code field in ISO 8583, when sent with ***analyze=false*** flag and authorization decision has already been made.
## Enumerators
The enumerators of the card transaction object are authorization_type, transaction_type, pan_entry_mode, source_account, brand and category. The possible values for each can be seen below:
## authorization_type
enumerator | meaning
---------- | -----------
authorization | A purchase authorization — MTI x1xx (DMS) and x2xx (SMS)
pre_authorization | A pre-authorization to reserve limit on the card (Hotel, Vehicle Rental, Equipment Rental, Fuel Machines) — MTI x1xx (DMS) and Transaction Type (first 2 digits of Processing Code) "60"
reversal | A cancellation authorization (to release limit on the card and subsequently proceed with Clearing/BASE II) — MTI x4xx
## transaction_type
enumerator | meaning
---------- | ----------
credit | A transaction made on the credit function
debit | A transaction made on the debit function
prepaid | A transaction made on the prepaid function
## pan_entry_mode
enumerator | ISO 8583 | meaning
---------- | -------- | -----------
unknown | 00 | PAN entry mode unknown.
typed | 01 | PAN entered manually (keyed).
bar_code | 03 | PAN entered by barcode reader
ocr | 04 | PAN entered by OCR (Optical Character Recognition)
chip | 05 | PAN entered by card with integrated circuit (Chip)
track_1 | 06 | PAN entered by Track 1 of the magnetic stripe card
contactless | 07 | PAN entered by Contactless EMV
fallback_typed | 79 | An attempt was made to use the card or stripe reader on the device and the card but the transaction could not be processed with that information (possibly a device or card issue), so the PAN was keyed. In some cases the acquirer is not certified to use CHIP or stripe and sends this code.
fallback_magnetic_stripe | 80 | An attempt was made to use the device's card reader and the card but the transaction could not be processed with that information (possibly a device or card issue), so the card's magnetic stripe was used.
ecommerce | 81 | E-commerce / card-not-present transaction
magnetic_stripe | 90 | Magnetic stripe transaction (Card has no chip or device has no reader/is not certified)
Other PAN_ENTRY_MODE values exist; however, they are generally not used.
## source_account
enumerator | ISO 8583 | meaning
---------- | -------- | -----------
default | 00 | Default or unspecified
saving_account | 10 | Savings account
checking_account | 20 | Checking account
credit_facility | 30 | Bill
universal_account | 40 | Universal Account
investment_account | 50 | Investment account
electronic_purse | 60 | Balance stored on the card chip (Electronic Purse)
## brand
enumerator | meaning
---------- | -----------
visa | Visa
mastercard | MasterCard
diners_club | Diners Club
elo | Elo
american_express | American Express
## category
enumerator | meaning
---------- | -----------
classic | Classic
gold | Gold
platinum | Platinum
black | Black/Infinite
travel | Travel
corporate | Corporate/Business
prepaid | Prepaid
## terminal_type
enumerator | meaning
---------- | -----------
0 | Unknown
1 | No terminal used
2 | Magnetic stripe reader
3 | Bar code (reserved for future use)
4 | Optical Character Recognition (reserved for future use)
5 | Magnetic stripe reader and EMV specification compatible integrated circuit card (ICC) reader
6 | Key entry only
7 | Magnetic stripe reader and key entry
8 | Magnetic stripe reader and key entry and EMV-compatible ICC reader
9 | EMV compatible ICC reader
## Send a Transaction
Request Body
```json
{
"id": "12345",
...
}
```
Response Body
```json
{
"id": "12345",
"fraud_status": "automatically_approved"
}
```
To evaluate a transaction, simply send a Transaction object to the following endpoint with the flag set appropriately:
`POST https://api.caas.qitech.app/card_issuance/transaction?analyze=true`
The *analyze* parameter exists to prevent transactions that do not need to be analyzed from going through the fraud engines and polluting the database. The default value of this parameter is **true**, so only transactions explicitly marked will not be analyzed.
## Update the status of a Transaction
Request Body: When authorizing a transaction
```json
{
"transaction_status": "authorized",
"response_code": "05"
}
```
Request Body: When partially cancelling a transaction
```json
{
"transaction_status": "partially_cancelled",
"partial_amount" : 3000,
"response_code": "05"
}
```
To ensure feedback to the rules and the implemented artificial intelligence model, it is necessary to inform the system when transactions are cancelled. For this, requests with the PUT method must be used, authenticated as usual:
`PUT https://api.caas.qitech.app/card_issuance/transaction/123456`
## Retrieve a Transaction
To retrieve a specific Transaction, simply make a GET request. The result returned is the most up-to-date JSON of the Transaction in question. If this identifier is not linked to any object, HTTP Status 404 is returned.
`GET https://api.caas.qitech.app/card_issuance/transaction/12345678`
```shell
curl "https://api.caas.qitech.app/card_issuance/transaction/12345678"
-H "Authorization: EXAMPLE-OF-API-KEY"
```
> The command above returns the JSON that represents a Transaction object.
## Search Transactions
Response Body: List of Transaction objects.
```json
[
{
"id": "12345",
...
},
{
"id": "12345",
...
}
]
```
If you need to search for Transactions, a GET with query parameters can be used. The result returned is a JSON representing a list of Transactions. If no object is found with the parameters sent, HTTP Status 200 is returned with an empty list in the response body.
`GET https://api.caas.qitech.app/card_issuance/transactions?initial_date=2019-10-01&final_date=2019-10-05&page_number=2&page_rows=20`
The following parameters can be used for the search:
Parameter | Default | Description
--------- | ----------- | --------------
initial_date | null | First date to be returned from the transaction_date field
final_date | null | Last date to be returned from the transaction_date field
cardholder_id | null | Cardholder identifier at the issuer
page_number | 0 | Page number of desired results, starting at zero
page_rows | 50 | Maximum number of objects to be returned in a query
---
# authentication
URL: /en/documentation/caas/card_order/authentication
## Autenticação
> Para autenticar uma chamada, utilize o código seguinte:
```shell
# No shell, você somente precisa adicionar o header adequado em cada requisição
curl "api_endpoint_here"
-H "Authorization: EXAMPLE_API_KEY"
```
> Substitua a API key 'EXAMPLE_API_KEY' com a sua chave adquirida com o nosso suporte.
Utilizamos uma API Key para permitir acesso a nossa API. Ela provavelmente já foi enviada por e-mail para você. Caso você ainda não tenha recebido a sua chave, envie um e-mail para suporte.caas@qitech.com.br .
Nossa API espera receber a API Key em todas as requisições ao nosso servidor em um header como o abaixo:
`Authorization: EXAMPLE_API_KEY`
:::info **Atenção**
Você deve substituir EXAMPLE_API_KEY com a API Key recebida do suporte.
:::
---
# Status HTTP
URL: /en/documentation/caas/card_order/http_status
Todas as APIs da QI Tech utilizam a seguinte padronização nos status HTTP de retorno, de acordo com o RFC 7231 :
Status HTTP | Significado | Descrição
---------- | ------- | ---------------------------------
400 | Bad Request | A requisição enviada possui algum erro de formatação. Na maioria dos casos, retornamos no corpo da mensagem uma explicação de onde está o erro.
401 | Unauthorized | Houve algum problema na autenticação, verifique se a API Key está correta e no header correto, de acordo com a seção Autenticação .
403 | Forbidden | O endpoint acessado é de uso interno e não está disponível para esta API Key.
404 | Not Found | O dado requisitado não foi encontrado usando a chave utilizada. Este status também é retornado quando um endpoint inválido é requisitado.
405 | Method Not Allowed | O método HTTP utilizado não se aplica ao endpoint utilizado.
406 | Not Acceptable | Os dados enviados no corpo da requisição são inválidos. Em geral, isso significa que os dados enviados não são um JSON válido.
409 | Conflict | O id da requisição corresponde a um id já processado anteriormente. Este status é retornado no caso de requisições duplicadas enviadas ao servidor.
500 | Internal Server Error | Tivemos um problema para processar esta requisição, ao encontrarmos esse erro nossos especialistas são automaticamente notificados e iniciam a análise e solução imediatamente.
503 | Service Unavailable | Você se deparou com uma indisponibilidade, planejada ou não, de infraestrutura dos nossos servidores.
---
# Introduction
URL: /en/documentation/caas/card_order/introduction
Welcome to QI Tech’s Card Transaction Fraud Prevention API! You can use our API to access the endpoints in order to receive the response of a transaction, and send transactions to QI Tech so that it can generate alerts for fraudulent users or fraudulent sellers, as well as use it to update the status of a transaction.
:::info **Attention**
Attention, this API is intended for merchants that receive card-not-present transactions, which are subject to fraud chargebacks, meaning companies that sell through applications or websites and receive payments via credit or debit card
:::
Below, you can see the API implementation using cURL. This provides examples that you can properly adapt to the programming language of your choice.
## Issues?
We’re not a company that hides behind an API! Reach out to our suport team and we’ll get back to you as soon as possible. Feel free to give us a call if you want a quicker answer!
### We love feedbacks
Even if you’ve already solved your issue or it is something simple (like a typo or a small organizational detail), feel free to send us an email. That way, we can keep improving our documentation and help the next person avoid the same difficulties you faced!
## Environments
We provide two environments for our clients. The base URLs for the APIs are:
* Production - `https://api.caas.qitech.app/card_order/`
* Sandbox - `https://api.sandbox.caas.qitech.app/card_order/`
In the Sandbox environment, analyses are not charged and return predefined responses.
For transaction analysis in the Sandbox environment, the decision is based on the transaction amount:
Minimum | Maximum | Decision
------ | ------ | -------
0 | 1000 | Automatically Approved
1001 | 2000 | Referred for Manual Review - Later Approved
2001 | 3000 | Referred for Manual Review - Later Rejected
3001 | 4000 | Automatically Rejected
4001 | 5000 | Not Analyzed
5001 | - | Pending
## Only HTTPS
For security reasons, all communication with QI Tech's APIs must be conducted over HTTPS. To ensure that no HTTP calls are made, whether by oversight or any other reason, this server only makes port 443 available with TLS 1.2 communication. Requests using other protocols will be automatically rejected.
## Authentication
> To authenticate a request, use the following code:
```shell
# In the shell, you only need to add the appropriate header to each request
curl "api_endpoint_here"
-H "Authorization: EXAMPLE_API_KEY"
```
> Replace the API key 'EXAMPLE-OF-API-KEY' with your key acquired from our support team.
We use an API Key to allow access to our API. It has probably already been sent to you by email. If you have not yet received your key, please send an email to suporte.caas@qitech.com.br .
Our API expects to receive the API Key in all requests to our server in a header like the one below:
`Authorization: EXAMPLE_API_KEY`
:::info **Attention**
You must replace EXAMPLE_API_KEY with the API Key received from support.
:::
---
# Objetos
URL: /en/documentation/caas/card_order/objects
## Objeto *address*
Request Body
```json
{
"street": "Rua do Exemplo, 111",
"neighborhood": "Bairro do Teste",
"city": "Aparecida de Goiânia",
"uf": "GO",
"complement": "",
"postal_code": "00000-000",
"country": "BRA"
}
```
O objeto *address* é utilizado para representar endereços em toda a API, endereços no território brasileiro são representados da seguinte maneira:
nome | tipo | descrição
---- | :----: | ---------
street | string | *(obrigatório)* Rua do endereço, incluindo o logradouro, evitando, se possível, abreviações.
number | string | Número do imóvel, incluindo letras caso possua.
neighborhood | string | *(obrigatório)* Bairro, sem abreviações. **e.g.: Santa Felicidade**
city | string | *(obrigatório)* Nome completo da cidade, sem abreviações
uf | string | *(obrigatório)* A unidade federativa, com duas letras maiúsculas. **e.g.: SP**
complement | string | Quaisquer complementos para localizar o imóvel. **e.g.: Apartamento 101, Conjunto 12**
postal_code | string | *(obrigatório)* O código postal da localidade, contendo o hífen.
country | string | *(obrigatório)* Código ISO 3166-1 alfa-3 do país do endereço.
No caso dos endereços cujo país não seja Brasil ("BRA"), o postal_code e a unidade federativa poderão ser preenchidos livremente.
## Objeto *payment*
Request Body
```json
{
"total_amount": 10000,
"shipping_amount": 500,
"currency": "BRL",
"is_recurrence": false,
"transactions": [ . . . ]
}
```
Um pagamento é representado pelo objeto *payment*, que possui os seguintes campos:
nome | tipo | descrição
---- | :----: | ---------
total_amount | inteiro | *(obrigatório)* Valor monetário total pago
shipping_amount | inteiro | Valor do frete cobrado para entrega
currency | Enumerador | *(obrigatório)* Moeda de pagamento de acordo com a ISO 4217
is_recurrence | boolean | *(obrigatório)* Caso este seja um pagamento de recorrência, indicar true nesta flag
transactions | Array de Transaction | *(obrigatório)* Lista de transações que foram realizadas para o pagamento do pedido (Pagamento com múltiplos cartões)
## Objeto *transaction* - Cartão de Crédito
Request Body
```json
{
"id": "124234",
"amount": 10000,
"bin": "123456",
"last_4": "1234",
"cardholder_name": "JOHN SAMPLE",
"card_fingerprint": "e3b0c44298fc1c149afbf4c8996fb92427ae41e4649b934ca495991b7852b855",
"expiration_date": "2020-11",
"installments": 6,
"processor": "stone",
"payment_type": "credit"
}
```
Uma transação é representada pelo objeto *transaction*, que possui os seguintes campos:
nome | tipo | descrição
---- | :----: | ---------
id | string | *(obrigatório)* Um identificador no sistema do cliente da transação, deve ser único por pedido
amount | integer | *(obrigatório)* Valor monetário que representa o valor pago
bin | string | *(obrigatório)* BIN do cartão utilizado no pagamento
last4 | string | *(obrigatório)* Quatro últimos dígitos do cartão utilizado no pagamento
cardholder_name | string | *(obrigatório)* Nome do portador, como está escrito no cartão
card_fingerprint | string | *(obrigatório)* Identificador do cartão no sistema do cliente ("Token")
expiration_date | string | Data de vencimento definida pelo cartão (YYYY-DD)
installments | integer | *(obrigatório)* Número de parcelas do pagamento
processor | enumerador | *(obrigatório)* Adquirente ou subadquirente responsável pelo processamento da transação
payment_type | enumerador | *(obrigatório)* Tipo de meio de pagamento
status | enumerador | Opcional - Último status da transação no momento do envio para a QI Tech - Útil para envio de transações não autorizadas
Enumeradores disponíveis para processor:
* cielo
* rede
* stone
* getnet
* adyen
* global_payments
* pagseguro
## Objeto *transaction* - PIX
Request Body
```json
{
"id": "124234",
"amount": 10000,
"payment_type": "pix"
}
```
Uma transação é representada pelo objeto *transaction*, que possui os seguintes campos:
nome | tipo | descrição
---- | :----: | ---------
id | string | *(obrigatório)* Um identificador no sistema do cliente da transação, deve ser único por pedido
amount | integer | *(obrigatório)* Valor monetário que representa o valor pago
payment_type | enumerador | *(obrigatório)* Tipo de meio de pagamento
## Objeto *dict_key*
Request Body
```json
{
"key_type": "cpf",
"key_value": "09991222669"
}
```
O objeto **dict_key** é utilizado para representar os dados da chave de vínculo no DICT do cliente, seja ele o recebedor ou o pagador da transação. Os campos desse objeto são:
nome | tipo | descrição
:----: | :----: | ---------
key_type | string | Enumerador que contém o tipo da chave de vinculo no DICT.
key_value | string | Contém a chave de vínculo cadastrada no DICT.
Os enumeradores para o campo *key_type* são os mesmos definidos na API do DICT: `cpf`,`cnpj`,`email`,`phone` e `evp`.
## Objeto *account*
Request Body
```json
{
"participant": "17315359",
"branch": "0000",
"account_number": "10442",
"account_digit": "6",
"account_type": "CACC"
}
```
Objeto que representa os dados de uma conta.
nome | tipo | descrição
:----: | :----: | ---------
participant | string | ISPB da instituição detentora da conta
branch | string | Agência da Conta
account_number | string | Número da Conta sem o dígito
account_digit | string | Dígito da conta
account_type | enum | Tipo da conta de origem, possíveis valores: "CACC", "SLRY" e "SVGS"
## Objeto *phone*
Request Body
```json
{
"international_dial_code": "1",
"area_code": "11",
"number": "999999999",
"type": "mobile",
"validated": false
}
```
Um objeto phone representa um número telefônico, dentro ou fora do Brasil e sua classificação. Para isso, os campos são:
nome | tipo | descrição
---- | :----: | ---------
international_dial_code | string | *(obrigatório)* Código de discagem internacional, sem zero ou +, somente números
area_code | string | *(obrigatório)* Código de área, sem zero, somente números
number | string | *(obrigatório)* Número do telefone, sem o hífen
type | enum | *(obrigatório)* Tipo de número: celular, residencial, comercial, etc.
validated | booleano | Caso o número de telefone tenha sido validado (SMS ou Ligação), enviar true neste campo
Existem os seguintes enumeradores para tipo de telefone: `residential`, `commercial`, `mobile`
## Objeto *seller*
Request Body
```json
{
"id": "COD",
"name": "Restaurante do Aeroporto de Congonhas",
"type": "legal_person",
"document_number": "00.000.000/0001-00",
"email": "seller@gmail.com",
"registration_date": "2019-12-20T15:23:12-03:00",
"url": "https://www.qitech.com.br",
"phone": {
"international_dial_code": "1",
"area_code": "11",
"number": "999999999",
"type": "mobile"
},
"address": {
"street": "Rua do Exemplo",
"neighborhood": "Bairro do Teste",
"city": "Aparecida de Goiânia",
"number": "1000",
"uf": "GO",
"complement": "Térreo",
"postal_code": "00000-000"
}
}
```
O objeto *seller* representa uma loja ou vendedor que realiza a venda ou entrega do pedido. Os dados a serem enviados podem ser vistos abaixo:
nome | tipo | descrição
---- | :----: | ---------
id | string | *(obrigatório)* O código identificador da loja (Ou vendedor em MarketPlace) no cliente
name | string | *(obrigatório)* O nome da loja (Ou vendedor em MarketPlace)
type | enum | Enumerador que representa se o seller é uma pessoa física ou pessoa jurídica
document_number | string | *(obrigatório)* O CNPJ ou CPF do seller
url | string | Endereço para a página do seller na plataforma
email | string | O e-mail do seller
registration_date | date | *(obrigatório)* A data de cadastro do seller
phone | *phone* | O telefone do seller
address | *address* | *(obrigatório)* O endereço da loja, caso seja uma loja física
Enumeradores de type:
* `natural_person`
* `legal_person`
## Objeto *customer*
Request Body
```json
{
"id": "5ce7fab5-8165-44a5-9b89-bb2d6d61e4f4",
"name": "Mary Sample",
"gender": "female",
"document_number": "000.000.000-00",
"registration_date": "2019-12-20T15:23:12Z",
"email": "test@sample.com",
"birthdate": "1990-01-02",
"address": { . . . },
"phone": { . . . }
}
```
O objeto customer representa os dados de quem realizou a compra do pedido, com o próprio cartão de crédito. Ele é composto por:
nome | tipo | descrição
---- | :----: | ---------
id | string | *(obrigatório)* Um identificador único do comprador ou usuário
name | string | *(obrigatório)* Nome completo
gender | enum | O gênero do customer, de acordo com a lista de enumeradores.
document_number | string | *(obrigatório)* O CPF, formatado adequadamente
registration_date | date | A data quando o usuário se cadastrou no sistema do cliente
email | string | *(obrigatório)* O e-mail do usuário
birthdate | date | A data de nascimento do customer
address | *address* | *(obrigatório)* O endereço residencial do comprador/usuário
phone | *phone* | *(obrigatório)* O telefone colhidos do comprador/usuário
Enumeradores de gênero:
* `male`
* `female`
## Objeto *device*
Request Body
```json
{
"session_id": "595c46c1-b8c2-449d-8a86-6aeba2e5b0da",
"platform": "android",
"browser": "chrome",
"ip": "243.178.100.37"
}
```
O objeto device descreve dados do dispositivo usado para realizar a compra. Os seguintes dados são passados:
nome | tipo | descrição
---- | :----: | ---------
session_id | string | *(obrigatório)* O identificador da sessão, repassada também no device scan
platform | enumerador | Enumerador do sistema operacional em uso
browser | enumerador | Enumerador do browser em uso (Ou aplicativo)
ip | string | O ip de origem da compra, de acordo com a padronização desta documentação. **Atenção, IPs iniciados em 10.* , 172.16.* e 192.168.* em geral são internos e portanto não são aplicáveis para prevenção a fraudes**
Enumeradores de plataforma:
* `android`
* `ios`
* `windows`
* `linux`
Enumeradores de browser:
* `firefox`
* `chrome`
* `safari`
* `app`
---
# Order
URL: /en/documentation/caas/card_order/order
Antes de realizar a entrega/envio de um produto ou a liberação de créditos para o seu cliente ou seller, você deve enviar os dados do pedido para a nossa API para que possamos lhe responder a nossa recomendação com relação a fraude. É muito importante que os dados enviados sejam os dados finais, que não serão alterados. Isto é muito importante para garantir dois pontos:
* Consistência dos dados na base de dados do Antifraude
* Avaliação realista do risco
O processo de análise consiste em enviar uma Order no endpoint adequado e esperar a resposta. Existem quatro resultados possíveis, devolvido na flag **analysis_status**:
Resultado | Descrição
:---------: | ---------
Aprovado Automaticamente | Recomenda-se que este pedido seja aprovado
Negado Automaticamente | Recomenda-se que este pedido seja reprovado
Derivado para análise manual | Nossas regras ou modelos não estão confiantes da decisão e decidiram enviar este pedido para a análise manual.
Aprovado Manualmente | Após análise manual, o analista escolheu aprovar o pedido
Reprovado Manualmente | Após análise manual, o analista escolheu reprovar o pedido
Pendente | As consultas estão demorando mais do que o esperado, este pedido entrou em uma fila de análise automática e será respondido por meio de Webhook
Não analisado | A consulta foi enviada com a flag de análise falsa, ou trata-se de uma análise exclusivamente para geração de alertas, o que significa que nossos sistemas não deverão retornar recomendação na resposta da Order
:::info **Atenção**
Caso o seu modelo de negócio demande, o motor da QI Tech pode ser configurado para que nenhum pedido seja derivado para análise manual, e nem para o estado Pendente. Assim, o seu usuário poderá receber imediatamente a confirmação da transação.
:::
### Dinâmica dos Status
Ao recuperar um objeto do tipo Order os status estão disponíveis. Além dos status, um histórico de modificações também são retornados para que possa ser consultado no futuro. Estas modificações são entituladas events e possuem, além do novo status, as datas de modificação.
### Dinâmica dos Status - **payment_status**
O status **payment_status** relacionado a um Pedido indica a situação do pagamento relacionado a este pedido, isto é, se a transação foi efetivamente aprovada, se foi cancelada ou se recebeu um chargeback de fraude. Os seguintes status de pagamento estão disponíveis:
* open
* not_authorized
* authorized
* captured
* cancelled
* chargeback
:::info **Atenção**
É de suma importância que o status de pagamento seja enviado para a QI Tech pois ele é utilizado como base para treinamento dos nossos modelos. No caso de chargeback, é muito importante que o reason_code seja enviado corretamente, como será explicado em seguida.
:::
### Dinâmica dos Status - **analysis_status**
O status **analysis_status** indica o status da decisão do motor de fraude e possui uma máquina de estados bastante simples:
* created
* automatically_approved
* automatically_reproved
* in_manual_analysis
* manually_approved
* manually_reproved
* pending
* not_analyzed
## Definição do Objeto
Request Body
```json
{
"id": "12345678",
"is_one_dollar_auth": false,
"seller": {
"id": "COD",
"name": "Restaurante do Aeroporto de Congonhas",
"type": "legal_person",
"document_number": "00.000.000/0001-00",
"email": "seller@gmail.com",
"registration_date": "2019-12-20T15:23:12-03:00",
"url": "https://www.qitech.com.br",
"phone": {
"international_dial_code": "1",
"area_code": "11",
"number": "999999999",
"type": "mobile",
"validated": true
},
"address": {
"street": "Rua do Exemplo",
"neighborhood": "Bairro do Teste",
"city": "Aparecida de Goiânia",
"number": "1000",
"uf": "GO",
"complement": "Térreo",
"postal_code": "00000-000",
"country": "BRA"
}
},
"payment": {
"total_amount": 10000,
"shipping_amount": 500,
"currency": "BRL",
"is_recurrence": false,
"transactions": [{
"id": "124234",
"amount": 8000,
"bin": "123456",
"last_4": "1234",
"cardholder_name": "JOHN SAMPLE",
"card_fingerprint": "e3b0c44298fc1c149afbf4c8996fb92427ae41e4649b934ca495991b7852b855",
"expiration_date": "2020-11",
"installments": 6,
"processor": "stone",
"payment_type": "credit",
"status": "not_authorized"
}]
},
"shipping": {
"name": "Mary Sample",
"gender": "female",
"document_number": "000.000.000-00",
"birthdate": "1990-01-02",
"email": "test@sample.com",
"address": {
"street": "Rua do Exemplo, 123",
"neighborhood": "Bairro do Teste",
"city": "Aparecida de Goiânia",
"number": "1000",
"uf": "GO",
"complement": "",
"postal_code": "00000-000",
"country": "BRA"
},
"phone": {
"international_dial_code": "1",
"area_code": "11",
"number": "999999999",
"type": "mobile",
"validated": true
},
"scheduled_date": "2020-01-10",
"shipping_method": "regular"
},
"customer": {
"id": "5ce7fab5-8165-44a5-9b89-bb2d6d61e4f4",
"name": "Mary Sample",
"gender": "female",
"document_number": "000.000.000-00",
"registration_date": "2019-12-20T15:23:12-03:00",
"email": "test@sample.com",
"birthdate": "1990-01-02",
"address": {
"street": "Rua do Exemplo, 123",
"neighborhood": "Bairro do Teste",
"city": "Aparecida de Goiânia",
"number": "1000",
"uf": "GO",
"complement": "",
"postal_code": "00000-000",
"country": "BRA"
},
"phone": {
"international_dial_code": "1",
"area_code": "11",
"number": "999999999",
"type": "mobile",
"validated": true
}
},
"device": {
"session_id": "595c46c1-b8c2-449d-8a86-6aeba2e5b0da",
"platform": "android",
"browser": "chrome",
"ip": "243.178.100.37"
},
"products": [{
"product_code": "latte-machiatto-30",
"name": "Latte Machiatto 30cl",
"description": "Latte Machiatto 30cl para levar, leite integral",
"sku": "1234",
"quantity": 2,
"unit_cost": 5000
}],
"order_date": "2020-01-03T15:35:12.454-03:00"
}
```
Todas as trocas de informação de um pedido utilizam a seguinte definição para este objeto. Em alguns casos, para facilitar a implementação e diminuir o fluxo de dados entre as partes, algumas informações poderão ser omitidas.
nome | tipo | descrição
:----: |:--------------------------------------:| ---------
id | string | Identificador do pedido no sistema do cliente. **É essencial que este valor seja único para cada pedido** (Obrigatório)
is_one_dollar_auth | booleano | Se esta for uma transação somente para validação do cartão, enviar com essa flag true (Obrigatório)
seller | Objeto Seller | Os dados da loja onde a venda está sendo realizada. No caso de um market place, são os dados do vendedor. No caso de um aplicativo, são os dados da loja de retirada (Obrigatório)
payment | Objeto Payment | Dados do pagamento do pedido (Obrigatório)
customer | Objeto Customer | Dados do cliente/usuário (Obrigatório)
shipping | Objeto Shipping | Dados da entrega do pedido - Deve ser preenchido em casos de produtos de entrega física
device | Objeto Device | Dados do aparelho/navegador onde o pedido é realizado
products | Array de Product | Os produtos sendo comprados (Obrigatório)
order_date | Data Hora | Data e hora de realização do pedido (Obrigatório)
## Enviar um Pedido
Request Body
```json
{
"id": "12345",
...
}
```
Response Body
```json
{
"id": "12345",
"analysis_status": "automatically_approved"
}
```
Para realizar a avaliação de um pedido, basta enviar um objeto do tipo Order ao seguinte endpoint:
`POST https://api.caas.qitech.app/card_order/order`
## Atualizar o status de um Pedido
Request Body
```json
{
"transaction_status": "chargeback"
}
```
Para garantir a retroalimentação das regras e do modelo de inteligência artificial implementado, é necessário informar ao sistema quando as transações são autorizadas, capturadas, canceladas ou recebem chargeback. Para isso, requisições com o método PUT devem ser utilizadas, autenticadas normalmente:
`PUT https://api.caas.qitech.app/card_order/order/12345678/transaction/124234`
Existem os seguintes enumeradores para *transaction_status*: `open`, `not_authorized`, `authorized`, `captured`, `cancelled`, `chargeback`
## Recuperar um Pedido
A fim de recuperar um Pedido específico, basta realizar uma requisição GET. O resultado retornado é o json mais atualizado do Pedido em questão. Caso este identificador não esteja relacionado a nenhum objeto, o HTTP Status 404 é retornado.
`GET https://api.caas.qitech.app/card_order/order/12345678`
```shell
curl "https://api.caas.qitech.app/card_order/order/12345678"
-H "Authorization: EXAMPLE_API_KEY"
```
> O comando acima retorna o JSON que representa um objeto de CardOrder.
## Buscar CardOrders
Response Body
```json
[
{
"id": "12345",
...
},
{
"id": "12345",
...
}
]
```
> Retorna um JSON que representa uma lista de objetos CardOrder.
Caso seja necessário buscar um CardOrder, um GET com parâmetros de query poderá ser utilizado. O resultado retornado é um JSON que representa uma lista de CardOrders. Caso nenhum objeto seja encontrado com os parâmetros enviados, o HTTP Status 200 é retornado com uma lista vazia no corpo da resposta.
`GET https://api.caas.qitech.app/card_order/order?initial_date=2019-10-01&final_date=2019-10-05&page_number=2&page_rows=20`
Os seguintes parâmetros podem ser utilizados para buscar objetos de CardOrder:
Parâmetro | Padrão | Descrição
--------- | ----------- | --------------
initial_date | null | Primeira data que deve ser retornada a partir do campo order_date
final_date | null | Última data que deve ser retornada a partir do campo order_date
page_number | 1 | Número da página de resultados desejada
page_rows | 50 | Número de objetos máximo a ser retornados em uma consulta
---
# Padrões
URL: /en/documentation/caas/card_order/standards
Para facilitar a integração e garantir a integridade da informação, foram definidos alguns padrões que são seguidos em toda a API.
## Valores Monetários
> Exemplos:
```
10000
12345
98741
1223
1
0
```
As APIs assumem que todos os valores monetários enviados são em Reais Brasileiros. Os valores devem ser enviados como inteiro em centavos.
## Data e Hora com Fuso Horário
> Alguns exemplos:
```
2019-10-15T22:35:12-03:00
2018-05-01T13:32:11+00:00
2019-05-01T00:00:00+00:00
```
É representada conforme a ISO 8601. Neste caso, o fuso-horário é colocado logo após o horário e deve representar o fuso do local onde aquele dado será valido. Por exemplo, se um aluguel estiver marcado para começar às 09:30 no aeroporto de Brasília, o horário enviado deverá ser representado por 09:30-03:00, se o aluguel estiver marcado para começar às 09:30 em Manaus, deverá ser representado por 09:30-04:00.
A máscara utilizada para validação é a seguinte:
`YYYY-MM-ddThh:mm:ss±hh:mm`
## Data e Hora sem Fuso Horario
> Alguns exemplos:
```
2019-10-15T22:35:12Z
2018-05-01T13:32:11Z
2019-05-01T00:00:00Z
```
É representada conforme a ISO 8601. Dados que independem de fuso-horário deverão ser enviados sem ele, sempre em UTC, com a letra Z indicando que este dado está em UTC. O seguinte formato, portanto, será validado:
`YYYY-MM-ddThh:mm:ssZ`
## Data
> Alguns exemplos
```
2019-10-15
2019-01-01
2017-03-20
```
No caso de campos que recebem somente data, uma data de nascimento, por exemplo, somente a data, sem nenhum horário deve ser enviada com o seguinte formato:
`YYYY-MM-dd`
## Documentos
Uma vez que os números de documento são bastante variados e muitos deles possuem caracteres que não se enquadram como numéricos, definem-se todos os números de documento como string. Outro bom motivo para definí-los como string é evitar que os zeros à esquerda desapareçam. Documentos previstos nesta página possuem uma máscara bem definida e estarão sujeitos a validação. O restante dos documentos, como RG, dada sua falta de padronização, não serão validados.
## CPF
> Exemplos de CPFs válidos contra a máscara definida:
```
123.456.789-12
321.987.543-23
111.283.333-00
```
> Exemplos de CPFs inválidos contra a máscara definida:
```
8.577.477-8
08.104.627/0001-23
123.456.789-1
23.456.789-01
```
O CPF é sempre definido como uma string e será validado conta a máscara:
`###.###.###-##`
## CNPJ
> Exemplos de CNPJs válidos contra a máscara definida:
```
08.104.627/0001-02
01.079.210/0114-67
32.402.502/0001-35
```
> Exemplos de CNPJs inválidos contra a máscara definida:
```
8.577.477-8
123.456.789-12
321.987.543-23
32.402.502/0001-3
032.402.502/0001-3
```
O CNPJ é sempre definido como uma string e será validado conta a máscara:
`##.###.###/####-##`
## IP
> Exemplos de IPs válidos contra a máscara definida:
```
201.81.161.86
201.081.161.86
201.81.161.086
201.81.0.1
```
> Exemplos de IPs inválidos:
```
201.81..86
358.81.161.86
201.81.161
```
IPs deverão ser enviados sempre em IPv4, zeros à esquerda poderão ou não ser enviados, respeitando a seguinte máscara:
`###.###.###.###`
---
# Webhook
URL: /en/documentation/caas/card_order/webhook
Atualizações no status de fraude (Para Orders que sejam derivados para análise manual ou que sejam respondidos como Pendente) e para Sellers bloqueados, são notificados por meio de Webhook. Para tanto, é necessário, por meio da equipe do [suporte](mailto:suporte.caas@qitech.com.br), configurar um endereço do endpoint por onde vamos notificar as atualizações e também uma *signature_key* que será utilizada para assinar a requisição.
No caso da atualização do status do pedido, o cliente pode também utilizar a técnica de [polling](https://en.wikipedia.org/wiki/Polling_(computer_science)). Neste caso, basta não configurar o endpoint de webhook e utilizar os endpoints de recuperação de Order para proceder com o polling.
:::info **Atenção**
Por questões de segurança, todas as requisições de Webhook serão somente realizadas em endpoints servidos por HTTPS.
:::
## Assinatura
> Exemplo de cálculo de assinatura em Python
```python
hmac_obj = hmac.new(signature_key.encode('utf-8'), (url + method + payload).encode('utf-8'), hashlib.sha1)
return hmac_obj.hexdigest()
```
Para garantir que a requisição recebida no endpoint do webhook parte dos nossos servidores, uma assinatura HMAC é enviada no Header *Signature*, de maneira semelhante ao processo de autenticação.
Após realizar o cálculo do valor esperado da assinatura do lado do servidor, é necessário comparar a assinatura calculada com a enviada. Caso as assinaturas sejam compatíveis, isso significa que a requisição partiu dos nossos servidores e que é confiável.
## Webhook de Atualização de Order
Request Body
```json
{
"order_id": "123456",
"fraud_status": "automatically_approved",
"event_date": "2019-10-01T10:37:25-03:00"
}
```
A requisição de atualização do status de análise de uma order possui o formato acima e notifica a mudança no status de fraude. O método utilizado é um PUT e o endereço do endpoint pode conter também o id do pedido, de acordo com a necessidade do cliente. É importante ressaltar que o corpo da requisição é enviado como texto codificado em UTF-8.
Exemplos de endpoints para atualização de pedido:
* https://apidocliente.com.br/order
* https://apidocliente.com.br/admin/order/1214
O campo event_date indica a data e hora em que a notificação foi criada e pode estar no passado caso envios de notificação anteriores tenham falhado.
## Webhook de Atualização de Seller
> Exemplo de requisição de bloqueio de liquidação
Request Body
```json
{
"document_number": "000.000.000-00",
"settlement_status": "blocked",
"event_date": "2019-10-01T10:37:25-03:00"
}
```
> Exemplo de requisição de bloqueio transacional
Request Body
```json
{
"document_number": "000.000.000-00",
"transactional_status": "blocked",
"event_date": "2019-10-01T10:37:25-03:00"
}
```
Caso o bloqueio ou desbloqueio de um seller seja necessário, o sistema da QI Tech realizará uma requisição com o formato acima. O método utilizado é um PUT realizado em um endpoint configurável e pode conter, a critério do cliente, o número do documento no endereço do endpoint.
:::info **Atenção**
É a presença do campo settlement_status ou do campo transactional_status que determina o tipo de bloqueio ou desbloqueio que deve ser realizado no seller.
:::
Exemplos de endpoints para atualização de seller:
* https://apidocliente.com.br/seller
* https://apidocliente.com.br/admin/seller/000.000.000-00
Os seguintes status de liquidação podem ser notificados:
enumerador | descrição
---- | ---------:
blocked | A liquidação do seller deve ser bloqueada
unblocked | A liquidação do seller deve ser liberada
O campo event_date indica a data e hora em que a notificação foi criada e pode estar no passado caso envios de notificação anteriores tenham falhado.
## Retentativas
A notificação é considerada realizada quando recebe como resposta um HTTP Status 200. Caso as notificações falhem, serão feitas 7 retentativas, com os seguintes intervalos, até que um 200 seja retornado ou as tentativas terminem:
* 10 segundos
* 40 segundos
* 160 segundos
* 640 segundos
* 2560 segundos
* 10240 segundos
* 40960 segundos
---
# authentication
URL: /en/documentation/caas/credit_analysis/authentication
## Autenticação
> Para autenticar uma chamada, utilize o código seguinte:
```shell
# No shell, você somente precisa adicionar o header adequado em cada requisição
curl "api_endpoint_here"
-H "Authorization: EXAMPLE-OF-API-KEY"
```
> Substitua a API key 'EXAMPLE-OF-API-KEY' com a sua chave adquirida com o nosso suporte.
Utilizamos uma API Key para permitir acesso a nossa API. Ela provavelmente já foi enviada por e-mail para você. Caso você ainda não tenha recebido a sua chave, envie um e-mail para suporte.caas@qitech.com.br .
Nossa API espera receber a API Key em todas as requisições ao nosso servidor em um header como o abaixo:
`Authorization: EXAMPLE-OF-API-KEY`
:::info **Atenção**
Você deve substituir EXAMPLE-OF-API-KEY com a API Key recebida do suporte.
:::
---
# Challenge Flow
URL: /en/documentation/caas/credit_analysis/challenge_flow
After executing a credit analysis, it's possible that the decision challenges the user to perform a new action on your platform. This flow can be used, for example, to request proof of income from a user whose approval or denial is not yet certain.
With this flow, you can configure a rule in which the decision challenges your customer to submit additional information to the system, such as a payslip photo or any other relevant data, and once collected, use this additional information to run a new rule for re-evaluating the user.
There are two ways to use this flow: one is automated, and the other is the result of a manual decision by an analyst. For the first, the returned *analysis_status* will be *automatically_challenged*, and for the second, it will be *manually_challenged*. The flow is described below.
## Step-by-step of the Flow Execution
**1.** A proposal is submitted for analysis (see section Credit Analysis - Natural Person or Credit Analysis - Legal Person ), and it will return the status *automatically_challenged* or *in_manual_analysis*.
Request Body
```json
{
"id": "12345",
"registration_id":"12345",
"credit_request_date": "2021-03-31T10:30:00-03:00",
"credit_type": "clean",
"name": "Victor Silva Barbosa",
"document_number": "199.208.915-92",
...
}
```
Response Body
```json
{
"id": "12345",
"analysis_status": "automatically_challenge"
}
```
If the request returns the status *in_manual_analysis* in the response, the analyst can, through the dashboard, challenge the user. In this case, the status sent in the webhook request will be *manually_challenged*.
Response Body
```json
{
"id": "12345",
"analysis_status": "manually_challenged"
}
```
**2.** After the first analysis request has returned one of the two challenge *analysis_status* values, a new request must be sent with the additional information collected from the customer, such as a new uploaded document image. This request must contain the same *registration_id* as the previous request, since this field will be used by the platform to identify that both requests refer to the same user, as well as to link the additional information collected from the customer.
Request Body: Submission with additional information
```json
{
"id": "67890",
"registration_id":"12345",
"credit_request_date": "2021-03-31T10:30:00-03:00",
"credit_type": "clean",
"name": "Victor Silva Barbosa",
"document_number": "199.208.915-92",
"documents": {
"cnh": {
"ocr_key":"a5cf9c8f-2f66-4490-a7db-8a5bc70c1b76"
}
}
...
}
```
Response Body
```json
{
"id": "12345",
"analysis_status": "automatically_approved"
}
```
Ensure that you use the same registration_id used in your first analysis.
---
# Retrieve a Credit Analysis
URL: /en/documentation/caas/credit_analysis/get_credit_analysis
To retrieve a specific Credit Analysis, simply make a GET request. The response will return the most up-to-date JSON of the analysis in question. If the identifier is not linked to any object, an HTTP 404 Status will be returned.
* **Natural Person:**
`GET https://api.caas.qitech.app/credit_analysis/natural_person/12345678`
* **Legal Person:**
`GET https://api.caas.qitech.app/credit_analysis/legal_person/12345678`
```shell
curl "https://api.caas.qitech.app/credit_analysis/natural_person/12345678"
-H "Authorization: EXAMPLE-OF-API-KEY"
```
> The curl above returns the JSON that represents a Natural Person object.
```shell
curl "https://api.caas.qitech.app/credit_analysis/legal_person/12345678"
-H "Authorization: EXAMPLE-OF-API-KEY"
```
> The curl above returns the JSON that represents Legal Person object.
---
# HTTP Status Codes
URL: /en/documentation/caas/credit_analysis/http_status
All QI Tech APIs follow the standard HTTP status codes as defined in the [RFC 7231](https://tools.ietf.org/html/rfc7231):
HTTP Status | Meaning | Description
----------- | ------- | ---------------------------------
400 | Bad Request | The request sent contains a formatting error. In most cases, we return a message body explaining where the error is.
401 | Unauthorized | There was a problem with authentication. Check if the API Key is correct and placed in the proper header, as explained in the [Authentication](#authentication) section.
403 | Forbidden | The accessed endpoint is for internal use and not available for this API Key.
404 | Not Found | The requested data could not be found using the provided key. This status is also returned when an invalid endpoint is requested.
405 | Method Not Allowed | The HTTP method used is not supported by the requested endpoint.
406 | Not Acceptable | The data sent in the request body is invalid. Usually, this means the payload is not valid JSON.
409 | Conflict | The request ID corresponds to an ID that has already been processed. This status is returned in case of duplicate requests.
500 | Internal Server Error | We encountered an issue while processing the request. When this happens, our specialists are automatically notified and begin investigating immediately.
503 | Service Unavailable | You encountered an infrastructure outage, whether planned or unplanned, on our servers.
---
# Imagens
URL: /en/documentation/caas/credit_analysis/image
Em várias situações é necessário enviar imagens para a nossa API, a fim de realizar operações de OCR, FaceMatch e validação de documentos. Para tanto, é preciso inicialmente realizar o upload da imagem para depois enviá-la para análise.
Ao enviar uma imagem utilizando o endpoint /image uma GUID (Globally Unique Identifier) é retornada. Este valor deverá ser utilizado nas chamadas subsequentes para referenciar esta imagem.
O tamanho máximo de uma imagem aceita é de 10MB.
Neste momento, somente imagens com formato jpeg são aceitas.
## Envio
> Exemplo de envio utilizando o cUrl
```shell
curl -F "data=@path/to/local/file" \
-H "Authorization: EXAMPLE-OF-API-KEY" \
"https://api.caas.qitech.app/image?type=face"
```
Response Body
```json
{
"image_id": "f4b5337a-7b50-406e-8c8e-7d0e77b5aa02",
"image_size": "134232",
"image_dimensions": "630x230"
}
```
Para enviar uma imagem, basta realizar o envio da imagem no formato .jpeg em `multipart/form-data` com uma requisição POST no endpoint:
`https://api.caas.qitech.app/api/image?type=$type`
Onde $type é a classificação da imagem e deve ser enviado conforme um dos seguintes enumeradores (Caso a imagem sendo enviada não se enquadre em nenhuma das classificações, entrar em contato com o [suporte](mailto:suporte.caas@qitech.com.br) para que providenciem a adição):
* face
* driver_license
* id
* contract
Após o envio, será retornado um objeto JSON com a GUID que aponta para a imagem que foi enviada.
## Recuperação dos Arquivos
> Leitura de imagem
```shell
curl "https://api.caas.qitech.app/api/image/f4b5337a-7b50-406e-8c8e-7d0e77b5aa02/file" \
-H "Authorization: EXAMPLE-OF-API-KEY"
```
Após o envio de uma imagem para a API, é possível recuperá-la por meio de uma requisição GET adequadamente autenticada no endpoint:
`https://api.caas.qitech.app/api/image/{image_key}/file`
Onde image_key é o valor retornado durante o envio da imagem.
## Recuperação dos meta-dados do arquivo
> Leitura de meta dados
```shell
curl "https://api.caas.qitech.app/api/image/f4b5337a-7b50-406e-8c8e-7d0e77b5aa02" \
-H "Authorization: EXAMPLE-OF-API-KEY"
```
Após o envio de uma imagem para a API, é possível recuperar os meta-dados da imagem utilizando o endpoint:
`https://api.caas.qitech.app/api/image/{image_key}`
Onde image_key é o valor retornado durante o envio da imagem.
---
# Introduction
URL: /en/documentation/caas/credit_analysis/introduction
Welcome to QI Tech's Credit Analysis API! You can use our API to access endpoints in order to perform a credit analysis, as well as update the status of a granted credit.
:::info **Attention**
Please note that this API is intended for companies that offer credit to individuals (Natural Persons) and small businesses (Legal Persons). Its purpose is to conduct a full credit assessment of your client's operations, based on the data you provide, data from bureaus and external sources, and QI Tech's datalake, in order to make the risk-return profile of each operation clear.
This API is designed for individuals and small businesses. It is not suited for assessing the credit risk of large corporations, which require deeper knowledge of their operations and the markets in which they operate.
:::
## Issues?
We’re not a company that hides behind an API! Reach out to our support team and we’ll get back to you as soon as possible. Feel free to give us a call if you want a quicker answer!
### We love feedbacks
Even if you’ve already solved your issue or it is something simple (like a typo or a small organizational detail), feel free to send us an email. That way, we can keep improving our documentation and help the next person avoid the same difficulties you faced!
## Environments
We provide two environments for our clients. The base URLs for our APIs are:
* Production – `https://api.caas.qitech.app/credit_analysis/`
* Sandbox – `https://api.sandbox.caas.qitech.app/credit_analysis/`
In the Sandbox environment, analyses are not charged and return predefined responses with fictitious data. Its sole purpose is to simulate the production environment and support clients during integration.
For credit analysis in the Sandbox environment, the decision is based on the total credit amount (`financial.amount`) according to the table below:
Minimum | Maximum | Decision
--------|---------|---------
10001 | - | Rejected
8001 | 10000 | Manual Analysis – A manual rejection webhook is sent after 1 minute
6001 | 8000 | Manual Analysis – A manual approval webhook is sent after 1 minute
4001 | 6000 | Awaiting Data – An automatic approval webhook is sent after 1 minute
2001 | 4000 | Pending
0 | 2000 | Approved
## HTTPS Only
For security reasons, all communication with QI Tech's APIs must be conducted using HTTPS. To ensure that no HTTP calls are made by mistake or for any other reason, this server only makes port 443 available with TLS 1.2 communication. Requests made using other protocols will be automatically denied.
## Authentication
> To authenticate a request, use the following code:
```shell
# In the shell, you only need to add the appropriate header to each request
curl "api_endpoint_here"
-H "Authorization: EXAMPLE-OF-API-KEY"
```
> Replace the API key 'EXAMPLE-OF-API-KEY' with your key acquired from our support team.
We use an API Key to allow access to our API. It has probably already been sent to you by email. If you have not yet received your key, please send an email to suporte.caas@qitech.com.br .
Our API expects to receive the API Key in all requests to our server in a header like the one below:
`Authorization: EXAMPLE-OF-API-KEY`
:::info Attention
You must replace EXAMPLE-OF-API-KEY with the API Key received from support.
:::
---
# Credit Analysis - Legal Entity
URL: /en/documentation/caas/credit_analysis/legal_person
To perform the credit analysis of a legal entity, use the Legal Person endpoint.
At the time a legal entity credit analysis is performed, the following data must be sent to our server.
## Legal Person Object Definition
Request Body
```json
{
"id": "12345678",
"credit_request_date": "2021-03-31T10:30:00-03:00",
"credit_type": "student_loan",
"legal_name": "QI Tech Tecnologia LTDA",
"trading_name": "QI Tech",
"document_number": "35.472.523/0001-15",
"constitution_date": "2019-11-11",
"constitution_type": "llc",
"email": "suporte.caas@qitech.com.br",
"monthly_revenue": 50000000,
"client_category": "Premium User",
"client_since": "2021-02-11",
"address": {
"country": "BRA",
"street": "Av. Brigadeiro Faria Lima",
"number": "2391",
"neighborhood": "Jardim Paulistano",
"city": "São Paulo",
"uf": "SP",
"postal_code": "01452-905"
},
"phones": [
{
"international_dial_code": "55",
"area_code": "11",
"number": "32234611",
"type": "residential"
}
],
"shareholders": [
{
"name": "Anna Pinto Azevedo",
"document_number": "261.026.462-31",
"birthdate": "1972-08-22",
"email": "annapintoazevedo@sample.com",
"nationality": "BRA",
"mother_name": "Beatrice Rodrigues Pinto",
"father_name": "Luís Azevedo",
"monthly_income": 800000,
"declared_assets": 18600000,
"occupation": "law",
"gender": "female",
"address": {
"country": "BRA",
"street": "Rua Derviche Djouki",
"number": "598",
"complement": "Ap 857",
"neighborhood": "Chora Menino",
"city": "São Paulo",
"uf": "SP",
"postal_code": "02463-080"
},
"phones": [
{
"international_dial_code": "55",
"area_code": "11",
"number": "55988644",
"type": "mobile"
}
]
}
],
"guarantors": [
{
"name": "Melissa Lima Melo",
"document_number": "677.498.846-61",
"birthdate": "1960-11-21",
"email": "exemplo2@sample.com",
"nationality": "BRA",
"mother_name": "Raíssa Lima",
"father_name": "Ronaldo Melo",
"monthly_income": 800000,
"declared_assets": 18600000,
"occupation": "law",
"gender": "female",
"address": {
"country": "BRA",
"street": "Rua Castro Alves",
"number": "100",
"complement": "Ap 202",
"neighborhood": "Parque Estrela Dalva I",
"city": "Luziânia",
"uf": "GO",
"postal_code": "72804-050"
},
"phones": [
{
"international_dial_code": "55",
"area_code": "11",
"number": "21158745",
"type": "residential"
}
]
}
],
"financial": {
"amount": 100000,
"currency": "BRL",
"interest_type": "cdi_plus",
"annual_interest_rate": 2.32,
"cdi_percentage": 100,
"number_of_installments": 4
},
"warrants": [
{
"warrant_type": "real_estate",
"address": {
"country": "BRA",
"street": "Rua Curitiba",
"number": "150",
"complement": "Bl 3 apt 122",
"neighborhood": "Paraíso",
"city": "São Paulo",
"uf": "SP",
"postal_code": "04005-030"
},
"property_type": "house",
"estimated_value": 100000000,
"forced_selling_value": 60000000
}
],
"source": {
"channel": "website",
"ip": "132.23.161.75",
"session_id": "2bb684f9-6c00-4993-bcd7-18b9eccd7c9d"
},
"scr_parameters" : {
...
}
}
```
A credit analysis must be submitted to the API before disbursement and can be used to decide whether or not to grant credit. The submitted data may also, upon agreement with the client, be used for fraud prevention.
The objects used in the composition of the **CreditProposal** object and not defined in this section are available in the [Shared Objects](#objects) section.
| name | type | description |
| :--------------------------------------: | :------------: | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| id | string | Identifier of the credit proposal in your system. **It is essential that this number is unique for each credit analysis process** |
| registration_id | string | Identifier of the registration in the client’s system. Used to perform more than one analysis related to the same registration |
| credit_request_date | datetime | The date and time when the credit was requested by the applicant |
| credit_type | enum | Type of credit being granted. Currently supported: **clean**, **student_loan**, **credit_card_limit** |
| legal_name | string | Company’s legal name |
| trading_name | string | Company’s trade name |
| document_number | string | The CNPJ, formatted according to the pattern established in this documentation |
| monthly_revenue | integer | Gross monthly revenue in cents |
| client_category | string | Customer category according to your platform’s classification or loyalty program |
| client_since | date | Service start date for this customer |
| constitution_date | date | The company's incorporation date, according to the commercial registry |
| constitution_type | enum | Company’s incorporation type: **LLC**, **corp** |
| email | string | The company representative’s email |
| address | _Address_ | Company headquarters address |
| phones | list of _Phones_ | Collected phone numbers of the company |
| shareholders | list of _NaturalPerson_ | Company shareholders, in natural person model (**NaturalPerson** object) |
| guarantors | list of _Person_ | Operation guarantors, either natural (**NaturalPerson**) or legal (**LegalPerson**) |
| financial.amount | integer | Total amount being requested by the applicant, which will be disbursed in case of approval |
| financial.currency | enum | Currency unit for the total amount: **BRL**, **USD**, **EUR** |
| interest_type | enum | Debt indexer to be used: **cdi_plus**, **cdi_percentage**, **price**, **pre_fixed** |
| annual_interest_rate | number | The fixed part of the interest rate, expressed annually as a percentage |
| cdi_percentage | number | The CDI (post-fixed) percentage to be charged |
| number_of_installments | integer | Number of installments |
| warrants | _Warrant_ | Real guarantee data offered in the operation. Must be agreed upon before going live. Currently accepted types: **real_estate** |
| source | _Source_ | Credit sales channel. Currently accepted values: **website** and **app** |
| scr_parameters | _ScrParameters_ | Object with the necessary information to use SCR data in credit analysis |
## Submit a Credit Proposal - Legal Person
Request Body
```json
{
"id": "12345678",
...
}
```
Response Body
```json
{
"id": "12345678",
"analysis_status": "automatically_approved",
"reason": "rule_decision_enum"
}
```
To evaluate a credit proposal, simply send an object of type **LegalPerson** to the following endpoint:
`POST https://api.caas.qitech.app/credit_analysis/legal_person`
---
# Credit Analysis - Natural Person
URL: /en/documentation/caas/credit_analysis/natural_person
To perform a credit analysis for a natural person, use the NaturalPerson endpoint.
When a natural person credit analysis is done, the following data must be sent to our server.
## Natural Person Object Definition
Request Body
```json
{
"id": "12345678",
"registration_id":"444",
"credit_request_date": "2021-03-31T10:30:00-03:00",
"credit_type": "student_loan",
"name": "Victor Silva Barbosa",
"document_number": "199.208.915-92",
"birthdate": "1990-01-01",
"email": "exemplo@sample.com",
"nationality": "BRA",
"gender": "male",
"mother_name": "Ana Barbosa",
"father_name": "João Silva",
"monthly_income": 30000,
"declared_assets": 7500000,
"occupation": "pedagogy",
"address": {
"country": "BRA",
"street": "Rua Curitiba",
"number": "150",
"complement": "Bl 3 apt 122",
"neighborhood": "Paraíso",
"city": "São Paulo",
"uf": "SP",
"postal_code": "04005-030"
},
"phones": [
{
"international_dial_code": "55",
"area_code": "11",
"number": "32234611",
"type": "residential"
}
],
"guarantors": [
{
"name": "Melissa Lima Melo",
"document_number": "677.498.846-61",
"birthdate": "1960-11-21",
"email": "exemplo2@sample.com",
"nationality": "BRA",
"mother_name": "Raíssa Lima",
"father_name": "Ronaldo Melo",
"monthly_income": 800000,
"declared_assets": 18600000,
"occupation": "law",
"gender": "female",
"address": {
"country": "BRA",
"street": "Rua Castro Alves",
"number": "100",
"complement": "Ap 202",
"neighborhood": "Parque Estrela Dalva I",
"city": "Luziânia",
"uf": "GO",
"postal_code": "72804-050"
},
"phones": [
{
"international_dial_code": "55",
"area_code": "11",
"number": "21158745",
"type": "residential"
}
]
}
],
"financial": {
"amount": 100000,
"currency": "BRL",
"interest_type": "cdi_plus",
"annual_interest_rate": 2.32,
"cdi_percentage": 100,
"number_of_installments": 4
},
"warrants": [
{
"warrant_type": "real_estate",
"address": {
"country": "BRA",
"street": "Rua Curitiba",
"number": "150",
"complement": "Bl 3 apt 122",
"neighborhood": "Paraíso",
"city": "São Paulo",
"uf": "SP",
"postal_code": "04005-030"
},
"property_type": "house",
"estimated_value": 100000000,
"forced_selling_value": 60000000
}
],
"source": {
"channel": "website",
"ip": "145.25.145.32",
"session_id": "bec256b3-5265-4dcb-bc55-2e4fb43983e0"
},
"scr_parameters" : {
...
}
}
```
A credit analysis must be submitted to the API before disbursement and can be used to decide whether or not to grant credit. The submitted data can also, by agreement with the client, be used for fraud prevention purposes.
The objects used in the composition of the **CreditProposal** object and not defined in this section are available in the [Shared Objects](#objects) section.
| name | type | description |
| :--------------------------------------: | :------------: | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| id | string | Credit proposal identifier in your system. **This number must be unique for each credit analysis process** *(required)* |
| registration_id | string | Identifier of the registration in the client’s system. Use the same registration_id for multiple analyses referring to the same registration |
| credit_request_date | datetime | The date and time when the credit was requested by the applicant *(required)* |
| credit_type | enum | Type of credit being granted. Currently supported: **clean**, **student_loan**, **credit_card_limit** |
| name | string | Full name of the individual being registered |
| document_number | string | CPF of the individual being registered, with dots and hyphens, according to formatting standards *(required)* |
| birthdate | date | Date of birth of the individual according to the formatting standard |
| gender | enum | Gender of the individual: 'male', 'female' or 'undefined' |
| nationality | string | Nationality of the individual, in ISO 3166-1 alpha-3 format |
| mother_name | string | Full name of the mother |
| father_name | string | Full name of the father |
| monthly_income | integer | Gross monthly income in cents |
| declared_assets | integer | Declared assets in cents |
| client_category | string | Client category according to your platform classification or loyalty program |
| client_since | date | Service start date for this client |
| occupation | string | Profession of the individual being registered |
| email | string | The person's email address |
| documents | Document | Objects of type CNH and RG |
| address | _Address_ | Object of type Address describing the individual’s residence |
| phones | List of _Phones_ | List of Phone objects containing the individual’s phone numbers |
| guarantors | List of _Person_ | Guarantors of the operation, either individuals (**NaturalPerson**) or legal entities (**LegalPerson**) |
| financial.amount | integer | Total amount requested by the applicant, which will be disbursed upon approval, in cents |
| financial.currency | enum | Currency unit of the total amount: **BRL**, **USD**, **EUR** |
| interest_type | enum | Debt index to be used: **cdi_plus**, **cdi_percentage**, **price**, **pre_fixed** |
| annual_interest_rate | number | Pre-fixed interest rate percentage per year |
| cdi_percentage | number | CDI percentage (post-fixed) of the interest to be charged |
| number_of_installments | integer | Number of installments |
| warrants | _Warrant_ | Real guarantees offered in the operation. Must be agreed upon before going live. Currently accepted types: **real_estate** |
| source | _Source_ | Credit sales channel. Currently accepted: **website** and **app** |
| scr_parameters | _ScrParameters_ | Object with the necessary information for using SCR data in the credit analysis
:::info **Attention**
The scr_parameters property is only required if the client has contracted and wishes to use the SCR consultation in the credit analysis.
:::
## Submit a Credit Proposal – Natural Person
Request Body
```json
{
"id": "12345678",
...
}
```
Response Body
```json
{
"id": "12345678",
"analysis_status": "automatically_approved",
"reason": "rule_decision_enum"
}
```
To perform the evaluation of a credit proposal, simply send an object of type **NaturalPerson** to the following endpoint:
`POST https://api.caas.qitech.app/credit_analysis/natural_person`
---
# Shared Objects
URL: /en/documentation/caas/credit_analysis/objects
Below are the definitions of other objects used throughout the documentation.
## _Address_ Object
Request Body
```json
{
"street": "Rua do Exemplo",
"number": "111" ,
"neighborhood": "Bairro do Teste",
"city": "Aparecida de Goiânia",
"uf": "GO",
"complement": "Apt 903",
"postal_code": "00000-000"
}
```
The `_Address_` object is used to represent addresses throughout the API. Addresses located within Brazilian territory are represented as follows:
| name | type | description |
| ------------- | :-----: | ------------------------------------------------------------------------------------------------ |
| street | string | Street name, including full address line, avoiding abbreviations if possible *(required)*. |
| number | string | Property number, including letters if applicable *(required)*. |
| neighborhood | string | Neighborhood, without abbreviations *(required)*. **e.g.: Santa Felicidade** |
| city | string | Full city name, without abbreviations *(required)*. |
| uf | string | Federal unit, two uppercase letters *(required)*. **e.g.: SP** |
| complement | string | Any additional details to help locate the property. **e.g.: Apartment 101, Unit 12** |
| postal_code | string | Postal code including hyphen *(required)*. |
| country | string | ISO 3166-1 alpha-3 country code *(required)*. |
For addresses where the country is not Brazil ("BRA"), the `postal_code` and `uf` fields may be filled in freely.
## _Phone_ Object
Request Body
```json
{
"international_dial_code": "1",
"area_code": "11",
"number": "999999999",
"type": "mobile"
}
```
A _Phone_ object represents a telephone number, either inside or outside Brazil, along with its classification. The fields are as follows:
| name | type | description |
|------------------------|:-------:|-----------------------------------------------------------------------------|
| international_dial_code | string | International dialing code, without zero or +, numbers only *(required)*. |
| area_code | string | Area code, without leading zero, numbers only *(required)*. |
| number | string | Phone number, without hyphen *(required)*. |
| type | enum | Type of number: mobile, residential, commercial, etc. |
The following enumerators are available for phone type: `residential`, `commercial`, `mobile`
## _cnh_ Object
Request Body
```json
{
"register_number": "05163811694",
"issuer_state": "PR",
"first_issuance_date":"2011-03-21",
"issuance_date":"2016-06-29",
"expiration_date":"2021-06-25",
"category": "AB",
"validation_type":"zaig_sdk",
"ocr_key":"a5cf9c8f-2f66-4490-a7db-8a5bc70c1b76"
}
```
The *cnh* object is used to represent driver’s licenses (CNHs) throughout the API, including information on whether any validation method was used. They are represented as follows:
name | type | description
---- | :----: | ----------
register_number | string | Registration number of the registered CNH.
issuer_state | enum | Enumerator for the state where the CNH was issued.
first_issuance_date | date | Date of first issuance.
issuance_date | date | Date of issuance.
expiration_date | date | Expiration date.
category | enum | CNH category in uppercase letters.
validation_type | enum | Type of validation used during the document registration.
ocr_key | guid | ID returned by QI Tech’s document validation API.
The following enumerators exist for *validation_type*: `zaig_api` and `zaig_sdk`.
## *rg* Object
Request Body
```json
{
"number": "4.366.477-8",
"issuer": "II",
"issuer_state": "PR",
"issuance_date":"2002-01-12",
"validation_type":"zaig_sdk",
"ocr_front_key":"a5cf9c8f-2f66-4490-a7db-8a5bc70c1b76",
"ocr_back_key":"a5cf9c8f-2f66-4490-a7db-8a5bc70c1b76"
}
```
The *rg* object is used to represent identity documents (RGs) throughout the API, including information on whether any validation method was used. They are represented as follows:
name | type | description
---- | :----: | ----------
number | string | Registered document number, including formatting (dots, hyphens, slashes, etc.).
issuer | string | Issuing authority of the document (abbreviation, e.g.: II, SESP...).
issuer_state | enum | State (UF) where the document was issued.
issuance_date | date | Date the document was issued.
validation_type | enum | Type of validation used during the document registration.
ocr_key | guid | ID returned by QI Tech’s document validation API.
The following enumerators exist for *validation_type*: `zaig_api` and `zaig_sdk`.
## _NaturalPerson_ Object
Request Body
```json
{
"name": "Melissa Lima Melo",
"document_number": "677.498.846-61",
"birthdate": "1960-11-21",
"email": "exemplo2@sample.com",
"nationality": "BRA",
"gender": "female",
"mother_name": "Raíssa Lima",
"father_name": "Ronaldo Melo",
"monthly_income": 800000,
"declared_assets": 18600000,
"occupation": "law",
"address": {
"country": "BRA",
"street": "Rua Castro Alves",
"number": "100",
"complement": "Ap 202",
"neighborhood": "Parque Estrela Dalva I",
"city": "Luziânia",
"state": "GO",
"postal_code": "72804-050"
},
"phones": [
{
"international_dial_code": "55",
"area_code": "11",
"number": "21158745",
"type": "residential"
}
]
}
```
The _NaturalPerson_ object represents the data of an individual who may be the borrower, a guarantor, or a shareholder of a borrowing company. It consists of:
| name | type | description |
| ---------------- | :--------------: | ------------------------------------------------------------------------------------------------ |
| name | string | Full name *(required)*. |
| document_number | string | CPF, properly formatted *(required)*. |
| birthdate | date | Person's date of birth. |
| email | string | Person's email. |
| gender | enum | Person's gender, according to the enumerated values. |
| address | _Address_ | Person's residential address. |
| phones | list of _Phone_ | Person's phone numbers. |
Gender enumerators:
- `male`
- `female`
- `undefined`
## _LegalPerson_ Object
Request Body
```json
{
"legal_name": "QI Tech Tecnologia LTDA",
"trading_name": "QI Tech",
"document_number": "35.472.523/0001-15",
"constitution_date": "1990-01-01",
"constitution_type": "llc",
"email": "exemplo@sample.com",
"address": { ... },
"phones": [ { ... } ],
"shareholders": [ { ... }]
}
```
The _LegalPerson_ object represents the data of a company that is either taking out credit or acting as a guarantor. It consists of:
| name | type | description |
| ----------------- | :---------------------: | -------------------------------------------------------------------------------- |
| legal_name | string | Company’s legal name *(required)*. |
| trading_name | string | Trade name |
| document_number | string | CNPJ, formatted according to the pattern defined in this documentation *(required)*. |
| constitution_date | date | Company’s incorporation date, as per the Board of Trade |
| constitution_type | enumerator | Type of company incorporation: **LLC**, **corp** |
| email | string | Email of the company's representative |
| address | _Address_ | Company’s headquarters address |
| phones | list of _Phone_ | List of phone numbers collected from the company |
| shareholders | list of _NaturalPerson_ | Company's shareholders, modeled as individuals (**NaturalPerson** object) |
## _Source_ Object
Request Body: Credit requests made through the company's own website
```json
{
"channel": "website",
"ip": "201.81.161.86",
"session_id": "b8da64db-e8f8-47fc-8d8e-11ce26da499f"
}
```
Request Body: Credit requests made through the company's own mobile app
```json
{
"channel": "app",
"platform": "android",
"ip": "201.81.161.86",
"session_id": "b8da64db-e8f8-47fc-8d8e-11ce26da499f"
}
```
The `source` object represents the channel where the credit request was made.
**Attention:** If the desired sales channel does not fit into any of these categories, please contact the support team .
## _Warrant_ Object
> For credit analyses that include any type of collateral, the `warrant` object can be used to inform our API. Currently, only real estate guarantees are accepted. If another type of guarantee is required, please contact our support team .
Request Body
```json
{
"warrant_type": "real_estate",
"address": { ... },
"property_type": "house",
"estimated_value": 100000000,
"forced_selling_value": 60000000
}
```
For the **real_estate** guarantee type, the object consists of the following fields:
| name | type | description |
| -------------------- | :------: | -------------------------------------------------------------------------------------------------------------------------- |
| warrant_type | enum | Defines the type of guarantee. Currently, only **real_estate** is supported. |
| address | _Address_ | Address object representing the property used as collateral |
| property_type | enum | Type of property. Currently supported: **house**, **commercial_building**, **office**, **apartment** |
| estimated_value | integer | Estimated market value of the property |
| forced_selling_value | integer | Estimated forced sale value of the property |
Warning: If the desired guarantee does not fall into any of these categories, please contact the support team .
## _ScrParameters_ Object
Request Body
```json
{
"scr_parameters": {
"signers": [
{
"document_number": "111.222.333-44",
"name": "Felipe Marques da Silva",
"email": "felipe.silva@qitech.com.br",
"phone": {
"number": "991722315",
"area_code": "16",
"international_dial_code": "55"
}
}
],
"signature_evidence": {
"ip_address": "179.104.42.245",
"session_id": "ddb1d063-4fdf-4330-af9c-3316e9142ff3",
"access_token": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9eyJzdWIiOiIxMjM0NTY3ODkwIiwibmFtZSI6IkpvaG4gRG9lIiwiaWF0IjoxNTE2MjM5MDIyfQSflKxwRJSMeKKF2QT4fwpMeJf36PO6yJV_adQssw5d",
"additional_data": {
...
},
"signed_term": {
"raw_text": "Lorem ipsum dolor sit amet, consectetur adipiscing elit. Maecenas elementum erat et tempus dapibus. Donec eu sapien tortor. Pellentesque
et tortor eget erat pulvinar mattis. Pellentesque habitant morbi tristique senectus et netus et malesuada fames ac turpis egestas. Proin ornare diam arcu, sit amet auctor lorem varius quis. Ut pretium venenatis magna sed ultrices. Donec quis tortor odi."
}
}
}
}
```
| name | type | description |
| -------------------- | :------: | --------------------------------------------------------------------------------------------------------------------------- |
| signers | List of _Signer_ | List of individuals who will or have signed the consent authorization for SCR consultation. This object should only be sent in the case of credit analyses for legal entities. |
| signature_evidence | _SignatureEvidence_ | Object for sending the information collected at the time of consent authorization when the authorization is requested on the client's platform. |
## *Signer* Object
Request Body
```json
{
"document_number": "111.222.333-44",
"name": "Felipe Marques da Silva",
"email": "felipe.silva@qitech.com.br",
"phone": {
"number": "991722315",
"area_code": "16",
"international_dial_code": "55"
}
}
```
| name | type | description |
| ------------------ | :-----: | ---------------------------------- |
| document_number | string | Signer's document number. |
| name | string | Signer's full name. |
| email | string | Signer's email address. |
| phone | _Phone_ | Signer's phone number. |
## *Signature_Evidence* Object
Request Body
```json
{
"signature_evidence": {
"ip_address": "179.104.42.245",
"session_id": "ddb1d063-4fdf-4330-af9c-3316e9142ff3",
"access_token": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9eyJzdWIiOiIxMjM0NTY3ODkwIiwibmFtZSI6IkpvaG4gRG9lIiwiaWF0IjoxNTE2MjM5MDIyfQSflKxwRJSMeKKF2QT4fwpMeJf36PO6yJV_adQssw5d",
"additional_data": {
...
},
"signed_term": {
"raw_text": "Lorem ipsum dolor sit amet, consectetur adipiscing elit. Maecenas elementum erat et tempus dapibus. Donec eu sapien tortor. Pellentesque
et tortor eget erat pulvinar mattis. Pellentesque habitant morbi tristique senectus et netus et malesuada fames ac turpis egestas. Proin ornare diam arcu, sit amet auctor lorem varius quis. Ut pretium venenatis magna sed ultrices. Donec quis tortor odi."
}
}
}
```
| name | type | description |
| ---------------- | :-----: | -------------------------------------------------------------------------------------------------------------------------------------------- |
| ip_address | string | Signer's IP address. |
| session_id | string | User session identifier on your platform; must allow audit of the Opt-In performed using this identifier. |
| access_token | string | Identifier of the user logged into your platform; should support auditing of the user's registration based on this identifier. |
| additional_data | object | Configurable JSON object to include any extra data the partner considers relevant to enhance credibility/authenticity of the signature. |
| signed_term | _SignedTerm_ | Object containing information about the consent term being used. |
## *SignedTerm* Object
Request Body
```json
{
"raw_text": "Lorem ipsum dolor sit amet, consectetur adipiscing elit. Maecenas elementum erat et tempus dapibus. Donec eu sapien tortor. Pellentesque et tortor eget erat pulvinar mattis. Pellentesque habitant morbi tristique senectus et netus et malesuada fames ac turpis egestas. Proin ornare diam arcu, sit amet auctor lorem varius quis. Ut pretium venenatis magna sed ultrices. Donec quis tortor odi."
}
```
| name | type | description |
| -------- | :----: | ---------------------------------------- |
| raw_text | string | Plain text of the term being signed. |
---
# Credit Information System Data (SCR - BACEN)
URL: /en/documentation/caas/credit_analysis/scr
If contracted by the client, it's possible to use the data available from the SCR (Brazilian Central Bank’s Credit Information System) for individuals or legal entities during the credit analysis process. To use SCR data, it is essential that the consulted party's consent is collected. This consent can either be collected by QI Tech or by the client, and this affects both the consent flow and the required data to be sent to the API, as described below:
**1. Consent collected by QI Tech** – If you choose to have QI Tech collect consent, a link for electronic signature will be sent directly to the consulted party via email. Once the user signs and completes the process, SCR data automatically becomes available for use. To use this flow, the integration must include the personal data of the end-user who will sign the consent.
**2. Consent collected by the client** – You may collect the signed consent term within your own environment or credit pipeline (this may be done via signed document or an opt-in checkbox). To use this method, the consent term must be approved by QI Tech's legal team, and it's necessary to send information that audibly proves consent for accessing SCR data through the *scr_parameters* object.
> **Attention:** All configurations for accessing SCR data—including which flow will be used—must be agreed upon during product onboarding for this feature to be available.
## Consent Collection via QI Tech – Natural Person
In the case of a natural person, to have QI Tech send the consent request, simply include the consulted individual's personal information in the CreditProposal object. QI Tech will then send the consent request via email, and once authorization is complete, the consultation will be performed automatically and the results made available for credit analysis.
> **Important:** The following fields are **required** for SCR consent collection by QI Tech for natural persons: document_number , name , email , and the phone object.
## Consent Collection via QI Tech – Legal Person
Request Body
```json
{
"id": "32199d0s",
"legal_name": "QI CAAS LTDA",
"trading_name": "QI Tech",
...
"scr_parameters": {
"signers": [
{
"document_number": "372.989.950-30",
"name": "Felipe Marques da Silva",
"email": "felipe.silva@qitech.com.br",
"phone": {
"number": "991722315",
"area_code": "16",
"international_dial_code": "55"
}
},
{
"document_number": "440.896.050-08",
"name": "Claudio Mattos",
"email": "claudiomattos@sample.com",
"phone": {
"number": "991722315",
"area_code": "16",
"international_dial_code": "55"
}
}
]
}
}
```
In the case of a legal entity, for QI Tech to send the consent request, it is necessary to include the additional scr_parameters object in the credit analysis request. Within this object, you must provide a list of the company's legal representatives to whom the electronic signature requests will be sent via email. This list should be included under the signers property. After all legal representatives have signed, QI Tech will perform the consultation and make the results available for credit analysis. Above is an example of the scr_parameters object for the described case.
## Consent Collection by the Client – Natural Person
Request Body
```json
{
"id": "678",
"credit_request_date": "2021-03-31T10:30:00-03:00",
"credit_type": "student_loan",
"name": "Victor Silva Barbosa",
"document_number": "199.208.915-92",
...
"scr_parameters": {
"signature_evidence": {
"ip_address": "179.104.42.245",
"session_id": "ddb1d063-4fdf-4330-af9c-3316e9142ff3",
"access_token": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9eyJzdWIiOiIxMjM0NTY3ODkwIiwibmFtZSI6IkpvaG4gRG9lIiwiaWF0IjoxNTE2MjM5MDIyfQSflKxwRJSMeKKF2QT4fwpMeJf36PO6yJV_adQssw5d",
"additional_data": {
...
},
"signed_term": {
"raw_text": "Lorem ipsum dolor sit amet, consectetur adipiscing elit. Maecenas elementum erat et tempus dapibus. Donec eu sapien tortor. Pellentesque et tortor eget erat pulvinar mattis. Pellentesque habitant morbi tristique senectus et netus et malesuada fames ac turpis egestas. Proin ornare diam arcu, sit amet auctor lorem varius quis. Ut pretium venenatis magna sed ultrices. Donec quis tortor odi."
}
}
}
}
```
In the case of a natural person, when consent is collected by the client, it is necessary to include the additional scr_parameters object in the analysis request. Within this object, it is necessary to add information to prove that the individual being analyzed authorized the consultation. This information must be provided in the signature_evidence property. Above is an example of the scr_parameters object for the described case.
## Consent Collection by the Client – Legal Entity
Request Body
```json
{
"id": "678",
"credit_request_date": "2021-03-31T10:30:00-03:00",
"credit_type": "student_loan",
"name": "Victor Silva Barbosa",
"document_number": "199.208.915-92",
...
"scr_parameters": {
"signers": [
{
"document_number": "372.989.950-30",
"name": "Felipe Marques da Silva",
"email": "felipe.silva@qitech.com.br",
"phone": {
"number": "991722315",
"area_code": "16",
"international_dial_code": "55"
}
},
{
"document_number": "440.896.050-08",
"name": "Claudio Mattos",
"email": "claudiomattos@sample.com",
"phone": {
"number": "991722315",
"area_code": "16",
"international_dial_code": "55"
}
}
],
"signature_evidence": {
"ip_address": "179.104.42.245",
"session_id": "ddb1d063-4fdf-4330-af9c-3316e9142ff3",
"access_token": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9eyJzdWIiOiIxMjM0NTY3ODkwIiwibmFtZSI6IkpvaG4gRG9lIiwiaWF0IjoxNTE2MjM5MDIyfQSflKxwRJSMeKKF2QT4fwpMeJf36PO6yJV_adQssw5d",
"additional_data": {
...
},
"signed_term": {
"raw_text": "Lorem ipsum dolor sit amet, consectetur adipiscing elit. Maecenas elementum erat et tempus dapibus. Donec eu sapien tortor. Pellentesque et tortor eget erat pulvinar mattis. Pellentesque habitant morbi tristique senectus et netus et malesuada fames ac turpis egestas. Proin ornare diam arcu, sit amet auctor lorem varius quis. Ut pretium venenatis magna sed ultrices. Donec quis tortor odi."
}
}
}
}
```
In the case of a legal entity, when consent is collected by the client, it is necessary to include the additional scr_parameters object in the analysis request. Within this object, it is necessary to add information to prove that the analyzed entity authorized the consultation, as well as include the list of legal representatives of the company who authorized the consultation. The authorization details must be provided in the signature_evidence property, and the list of individuals who authorized the consultation must be provided in the signers property. Above is an example of the scr_parameters object for the described case.
---
# Standards
URL: /en/documentation/caas/credit_analysis/standards
To simplify integration and ensure data integrity, some standards have been defined and are followed throughout the API.
## Monetary Values
> Examples:
```
10000
12345
98741
1223
1
0
```
The APIs assume that all monetary values sent are in Brazilian Reais. Values must be sent as integers in cents.
## Date and Time with Timezone
> Some examples:
```
2019-10-15T22:35:12.232-03:00
2018-05-01T13:32:11.297+00:00
2019-05-01T00:00:00.000+00:00
```
It is represented according to the ISO 8601 standard. In this case, the timezone is placed immediately after the time and should represent the timezone of the location where that data will be valid.
The validation mask is as follows:
`YYYY-MM-ddThh:mm:ss.sss±hh:mm`
## Date and Time without Timezone
> Some examples:
```
2019-10-15T22:35:12
2018-05-01T13:32:11
2019-05-01T00:00:00
```
It is represented according to the ISO 8601 standard. Data that is independent of timezones should be sent without one, always in UTC, using the letter Z to indicate that the data is in UTC. Therefore, the following format will be validated:
`YYYY-MM-ddThh:mm:ss.sssZ`
## Date
> Some examples:
```
2019-10-15
2019-01-01
2017-03-20
```
For fields that only receive a date—such as a birthdate—only the date, without any time, should be sent in the following format:
`YYYY-MM-dd`
## Documents
Since document numbers vary widely and many include non-numeric characters, all document numbers are defined as strings. Another important reason to treat them as strings is to preserve leading zeros. Documents mentioned on this page follow a strict mask and will be validated accordingly. Other documents, like RG, due to their lack of standardization, will not be validated.
## CPF
> Examples of valid CPFs based on the defined mask:
```
123.456.789-12
321.987.543-23
111.283.333-00
```
> Examples of invalid CPFs based on the defined mask:
```
8.577.477-8
08.104.627/0001-23
123.456.789-1
23.456.789-01
```
CPF is always defined as a string and will be validated against the following mask:
`###.###.###-##`
## CNPJ
> Examples of valid CNPJs based on the defined mask:
```
08.104.627/0001-02
01.079.210/0114-67
32.402.502/0001-35
```
> Examples of invalid CNPJs based on the defined mask:
```
8.577.477-8
123.456.789-12
321.987.543-23
32.402.502/0001-3
032.402.502/0001-3
```
CNPJ is always defined as a string and will be validated against the following mask:
`##.###.###/####-##`
## IP
> Examples of valid IPs based on the defined mask:
```
201.81.161.86
201.081.161.86
201.81.161.086
201.81.0.1
```
> Examples of invalid IPs:
```
201.81..86
358.81.161.86
201.81.161
```
IPs must always be sent in IPv4 format. Leading zeros are optional, as long as the following mask is respected:
`###.###.###.###`
---
# Status Dynamics
URL: /en/documentation/caas/credit_analysis/status_dynamics
The credit analysis process consists of sending a request, either for a **NaturalPerson** or a **LegalPerson**, to the appropriate endpoint and waiting the response.
After QI Tech completes the credit analysis, it returns a response containing a status related to the evaluation. This status is called **analysis_status**, which represents the outcome of the credit analysis performed by QI Tech.
In addition to **analysis_status**, QI Tech also provides **credit_proposal_status**, which represents the current status of the credit being analyzed throughout its lifecycle on your platform.
## **analysis_status**
As mentioned before, QI Tech defines seven **analysis_status** values that indicate the decision status of the credit evaluation. These follow a relatively simple state machine:
analysis_status | Description
:---------: | ---------
automatically_approved | QI Tech's algorithms recommend that this registration be approved
automatically_reproved | QI Tech's algorithms recommend that this registration be rejected
in_manual_analysis | QI Tech's algorithms sent this registration for manual analysis
manually_approved | After manual analysis, the analyst decided to approve the registration
manually_reproved | After manual analysis, the analyst decided to reject the registration
waiting_for_data | The credit analysis is waiting for a response from a bureau or data provider and will be returned via Webhook
automatically_challenged | QI Tech's algorithms recommend that this registration be challenged
manually_challenged | After manual analysis, the analyst decided to challenge the registration
pending | The credit analysis is taking longer than expected; this registration has entered an automatic analysis queue and will be returned via Webhook
:::info **Attention**
You must replace EXAMPLE-OF-API-KEY with the API Key received from support.
:::
## **credit_proposal_status**
The **credit_proposal_status** indicates the status of the customer's credit operation, that is, the status of the credit proposal in your company or platform. The following enumerators exist for this status:
credit_proposal_status | Description
:---------: | ---------
created | The credit proposal was created in your platform
disbursed | The credit proposal was disbursed in your platform
paid | The customer has fully paid the credit
defaulted | The customer is in default on your platform
---
# Update the Status of a Credit Analysis
URL: /en/documentation/caas/credit_analysis/update_credit_analysis
Request Body: To mark the credit as disbursed
```json
{
"credit_proposal_status": "disbursed",
"event_date": "2021-11-05T13:34:12-03:00"
}
```
To ensure feedback for the rules and the implemented AI model, it is necessary to inform the system when operations are carried out. For this, PUT requests should be used and authenticated:
* **Natural Person:**
`PUT https://api.caas.qitech.app/credit_analysis/natural_person/12345678`
* **Legal Person:**
`PUT https://api.caas.qitech.app/credit_analysis/legal_person/12345678`
---
# Webhook
URL: /en/documentation/caas/credit_analysis/webhook
Status updates (for registrations that are sent for manual analysis or returned as Pending) are notified via Webhook. To enable this, you must configure an endpoint URL through the [support team](mailto:suporte.caas@qitech.com.br), where we will send update notifications, as well as a *secret_token* used to sign the request.
Although not recommended, the client may alternatively use the [polling](https://en.wikipedia.org/wiki/Polling_(computer_science)) technique. In this case, simply do not configure the webhook endpoint and use the record retrieval endpoints to proceed with polling.
## Signature
> Example of signature calculation in Python
```python
hmac_obj = hmac.new(signature_key.encode('utf-8'), (endpoint + method + payload).encode('utf-8'), hashlib.sha1)
return hmac_obj.hexdigest()
```
To ensure that the request received on the webhook endpoint originates from our servers, an HMAC signature is sent in the Header Signature, similar to the authentication process.
After calculating the expected signature value on your server, you must compare the calculated signature with the one sent. If the signatures match, it means the request came from our servers and is trustworthy.
## Request
```bash
curl --location 'YOUR-ENDPOINT-HERE' \
--header 'Signature: CALCULATED-HASH-HMAC' \
--data '{"natural_person_id": "538509", "analysis_status": "manually_approved", "event_date": "2024-11-13T17:52:50Z", "reason": "manually_approved"}'
```
The request follows the format above and notifies the status change. It is important to note that the request uses the HTTP POST method and the request body is sent as UTF-8 encoded string.
## Retry Attempts
A notification is considered successfully delivered when it receives an HTTP Status 200 as a response. If the notification fails, 5 retry attempts will be made with the following intervals, until a 200 is returned or all attempts are exhausted:
* 30 seconds
* 60 seconds
* 120 seconds
* 240 seconds
* 360 seconds
---
# Account Object
URL: /en/documentation/caas/device_manager/account
The account is an organizational entity that allows for device registration. This API was designed to comply with [BACEN Regulation 491](https://www.bcb.gov.br/estabilidadefinanceira/exibenormativo?tipo=Instru%C3%A7%C3%A3o%20Normativa%20BCB&numero=491); therefore, account data must follow a standard regarding information defined by the Central Bank, but any other necessary fields may be added to the account data.
## Account Object Definition
Request Body
```json
{
"account_id": "12345678",
"account_type": "natural_person",
"registration_date": "2019-12-11T11:37:15.12-03:00",
"account_data": {
"account_number": "12345678",
"agency_number": "1234"
...
}
}
All information exchanges regarding an account use the following definition for this object. In some cases, to facilitate implementation and reduce data flow between parties, some information may be omitted.
name | type | description
:----: | :----: | ---------
account_id | string | Account identifier. It is essential that this number be unique for each account. *(mandatory)*
account_type | string | Identifier of the account type registered in the device registration system. Accounts can be of the natural person type `natural_person` or legal person type `legal_person` .*(mandatory)*
registration_date | datetime | Date and time of the account registration, with timezone. *(mandatory)*
account_data | object | object that may contain any account data, but if it contains the account number `account_number` and agency `agency_number`, both must be of the string type.
## Send an Account
Request Body
```json
{
"account_id": "12345",
...
}
```
Response Body
```json
{
"account_id": "12345678",
"account_type": "natural_person",
"registration_date": "2019-12-11T11:37:15.12-03:00",
"account_data": {
"account_number": "12345678",
"agency_number": "1234"
...
}
}
```
To create an account, simply send an Account type object to the following endpoint:
`POST https://api.caas.qitech.app/device_manager/account`
---
# Authentication
URL: /en/documentation/caas/device_manager/authentication
> To authenticate a request, use the following code:
```shell
# Add the authorization header to the request
curl "api_endpoint_here"
-H "Authorization: EXAMPLE-OF-API-KEY"
```
> Note: Replace 'EXAMPLE-OF-API-KEY' with your access key.
Access to the API is controlled via an API Key. If you have not received your key yet, please request it by sending an email to suporte.caas@qitech.com.br .
The API Key must be included in the header of all requests to the server, following the pattern below:
`Authorization: EXAMPLE-OF-API-KEY`
:::info **Attention**
Remember to replace EXAMPLE-OF-API-KEY with the actual key obtained from our support team.
:::
---
# Device Object
URL: /en/documentation/caas/device_manager/device_registration
Device registration with unique identification must be performed via the Device endpoint. For the registration to be effective, the use of **Device Scan** is required so that the device identification is recorded for future recognition.
### Status Dynamics - **status**
The **status** field indicates the current situation of the device. The following statuses are available:
* registered
* not_registered
* deactivated
### Status Dynamics - **analysis_status**
The **analysis_status** field indicates the decision status of the fraud engine and follows this state flow:
* automatically_approved
* automatically_reproved
* pending
## Device Object Definition
Request Body
```json
{
"device_id": "12345678",
"session_id": "12345678",
"face_recognition_key": "12345678",
"document_number": "111.111.111-11",
"mfa_status": "approved",
"registration_date": "2019-12-11T11:37:15.12-03:00"
}
```
All information exchanges regarding a registration use the following definition for this object. In some cases, to facilitate implementation and reduce data flow between parties, some information may be omitted.
name | type | description
:----: | :----: | ---------
device_id | string | Device identifier. **It is essential that this number be unique for each device** *(mandatory)*
session_id | string | Session identifier in Device Scan. *(mandatory)*
face_recognition_key | string | Image identifier for facial biometrics if the product is contracted as registration 2FA.
document_number | string | User document for face validation. It should only be sent if not informed during the *Person object* registration.
mfa_status | string | Registration MFA status, which can be one of the following values: *approved* *reproved*
registration_date | datetime | The start date and time of the registration, with timezone. *(mandatory)*
:::warning Attention
The `document_number` field is necessary for face validation in the database; therefore, if it was not provided during user registration, it is mandatory. It must never differ from the one registered in the Person object.
:::
## Register a Device
Request Body
```json
{
"device_id": "12345",
...
}
```
Response Body
```json
{
"device_id": "12345",
"status": "registered",
"analysis_status": "automatically_approved",
"reason": "rule_decision_enum",
"reason_description": "Descrição da regra"
}
```
To register a Device, simply send a Device type object to the following endpoint:
`POST https://api.caas.qitech.app/device_manager/account/{account_id}/person/{person_id}/device`
---
# HTTP Status
URL: /en/documentation/caas/device_manager/http_status
All QI Tech APIs use the following standardization for HTTP return status codes, in accordance with RFC 7231 :
HTTP Status | Meaning | Description
---------- | ------- | ---------------------------------
400 | Bad Request | The request sent contains a formatting error. Usually, we return an explanation of the error in the message body.
401 | Unauthorized | There was an authentication problem. Check if the API Key is correct and in the correct header, as per the Authentication section.
403 | Forbidden | The accessed endpoint is for internal use and is not available for this API Key.
404 | Not Found | The requested data was not found using the provided key. This status is also returned when an invalid endpoint is requested.
405 | Method Not Allowed | The HTTP method used is not supported by this endpoint.
406 | Not Acceptable | The data sent in the request body is invalid. In general, this means the data sent is not valid JSON.
409 | Conflict | The request ID corresponds to an ID that has already been processed. This status is returned in the case of duplicate requests sent to the server.
500 | Internal Server Error | We encountered a problem processing this request. When this error occurs, our specialists are automatically notified and begin analysis and resolution immediately.
503 | Service Unavailable | Indicates an infrastructure unavailability, whether planned or unplanned, on our servers.
---
# Introduction
URL: /en/documentation/caas/device_manager/introduction
Welcome to the QI Tech Device Registration API! This API was designed to comply with [BACEN Regulation 491](https://www.bcb.gov.br/estabilidadefinanceira/exibenormativo?tipo=Instru%C3%A7%C3%A3o%20Normativa%20BCB&numero=491). Together with Device Scan, it is capable of generating a unique identification for each device.
This API manages the device identification process, enabling future validation of the same device. This flow is structured through the following entities:
* Account
* Person
* Device
You can use our API to create and retrieve device registrations using the following service:
* **Device Registration** - used to associate a device with a person. Through this registration, it will be possible to perform device validations for future access by this same person.
## Environments
We have two environments for our clients. The base URLs for the APIs are:
* Production - `https://api.caas.qitech.app/device_manager/`
* Sandbox - `https://api.sandbox.caas.qitech.app/device_manager/`
:::danger Important Notice!
Real data of natural and/or legal persons must not be used in QI Tech Sandbox environments.
:::
In the Sandbox environment, submitted analyses are not charged and are responded to according to the rule configured for the event.
## HTTPS Only
For security reasons, all communication with QI Tech APIs must be performed using the HTTPS protocol. To ensure data security, this server only makes port 443 available with TLS 1.2 communication. Calls made using other protocols will be automatically denied.
## Need Help?
We value close contact with our partners. Contact our support and we will respond as quickly as possible.
### We Love Feedback
Your feedback is essential for the evolution of our documentation. If you find any inconsistency, typo, or have suggestions for improvement, send us an email. This way, we make integration increasingly practical for all developers.
---
# Person Object
URL: /en/documentation/caas/device_manager/person
An account may have more than one user accessing it; therefore, each user must have their own registration to segregate actions in joint accounts. The information cited below must follow the established standards, but any fields may be added to the account data if necessary.
## Person Object Definition
Request Body
```json
{
"person_id": "12345678",
"document_number": "111.111.111-11",
"registration_date": "2019-12-11T11:37:15.12-03:00",
"person_data": {
"name": "Joao da Silva",
"email": "person@email.com",
"phone": {
"number": "999999999",
"international_dial_code": "55",
"area_code": "11"
}
}
}
```
All information exchanges regarding a person use the following definition for this object. In some cases, to facilitate implementation and reduce data flow between parties, some information may be omitted.
nome | tipo | descrição
:----: | :----: | ---------
person_id | string | Person identifier. **It is essential that this number be unique for each person** *(mandatory)*
document_number | string | Document number, which can be CPF or CNPJ with punctuation.
registration_date | datetime | Date and time of the person's registration associated with the account, with timezone. *(mandatory)*
person_data | object | Object that may contain any data regarding the person. However, if it contains the name `name`, email `email`, and phone `phone` (with phone being an object containing `number`, `international_dial_code`, and `area_code`), all cited objects must be of the string type.
## Create a Person
Request Body
```json
{
"person_id": "12345678",
...
}
```
Response Body
```json
{
"person_id": "12345678",
"document_number": "111.111.111-11",
"registration_date": "2019-12-11T11:37:15.12-03:00",
"person_data": {
"name": "Joao da Silva",
"email": "person@email.com",
"phone": {
"number": "999999999",
"international_dial_code": "55",
"area_code": "11"
}
}
}
```
To create a person, simply send a Person type object to the following endpoint:
`POST https://api.caas.qitech.app/device_manager/account/{account_id}/person`
---
# Consult and Deactivate Entities
URL: /en/documentation/caas/device_manager/query_registration
## Retrieve specific Device
To retrieve a specific Device, simply perform a GET request. The returned result is the most up-to-date JSON of the Device in question. If this identifier is not related to any object, HTTP Status 404 is returned.
`GET https://api.caas.qitech.app/device_manager/account/{account_id}/person/{person_id}/device/{device_id}`
```shell
curl "[https://api.caas.qitech.app/device_manager/account/](https://api.caas.qitech.app/device_manager/account/){account_id}/person/{person_id}/device/{device_id}"
-H "Authorization: EXAMPLE-OF-API-KEY"
```
## List Devices
To retrieve multiple devices, simply perform a GET request. The returned result is a JSON with a list of basic information for all of a user's devices.
`GET https://api.caas.qitech.app/device_manager/account/{account_id}/person/{person_id}/devices`
```shell
curl "https://api.caas.qitech.app/device_manager/account/{account_id}/person/{person_id}/devices"
-H "Authorization: EXAMPLE-OF-API-KEY"
```
## Deactivate specific Device
To deactivate a specific Device, simply perform a DELETE request. If this identifier is not related to any object, HTTP Status 404 is returned. Once a device is deactivated, it can no longer be validated.
`DELETE https://api.caas.qitech.app/device_manager/account/{account_id}/person/{person_id}/device/{device_id}`
```shell
curl -X DELETE "https://api.caas.qitech.app/device_manager/account/{account_id}/person/{person_id}/device/{device_id}" \
-H "Authorization: EXAMPLE-OF-API-KEY"
```
## Retrieve specific Account
Allows retrieving data for an account by its identifier. Returns the account details, or 404 if it does not exist.
`GET https://api.caas.qitech.app/device_manager/account/{account_id}`
```shell
curl "https://api.caas.qitech.app/device_manager/account/{account_id}" \
-H "Authorization: EXAMPLE-OF-API-KEY"
```
## Retrieve specific Person
Allows retrieving data for a specific person within an account. Returns the updated person data, or 404 if it does not exist.
`GET https://api.caas.qitech.app/device_manager/account/{account_id}/person/{person_id}`
```shell
curl "https://api.caas.qitech.app/device_manager/account/{account_id}/person/{person_id}" \
-H "Authorization: EXAMPLE-OF-API-KEY"
```
---
## Deactivate Account
Performs the deactivation of an account. Once deactivated, the account can no longer be used for registering or validating devices.
`DELETE https://api.caas.qitech.app/device_manager/account/{account_id}`
```shell
curl -X DELETE "https://api.caas.qitech.app/device_manager/account/{account_id}" \
-H "Authorization: EXAMPLE-OF-API-KEY"
```
## Deactivate Person
Performs the deactivation of a person within an account. Once deactivated, the person can no longer register or validate devices.
`DELETE https://api.caas.qitech.app/device_manager/account/{account_id}/person/{person_id}`
```shell
curl -X DELETE "https://api.caas.qitech.app/device_manager/account/{account_id}/person/{person_id}" \
-H "Authorization: EXAMPLE-OF-API-KEY"
```
---
# Standards
URL: /en/documentation/caas/device_manager/standards
To facilitate integration and ensure information integrity, several standards have been defined and are followed throughout the API.
## Monetary Values
> Examples:
```
10000
12345
98741
1223
1
0
```
The APIs assume that all monetary values sent are in Brazilian Reais. Values must be sent as integers representing cents.
## Date and Time with Timezone
> Some examples:
```
2019-10-15T22:35:12.232-03:00
2018-05-01T13:32:11.297+00:00
2019-05-01T00:00:00.000+00:00
```
It is represented according to ISO 8601. In this case, the timezone is placed immediately after the time and must represent the timezone of the location where that data will be valid.
The mask used for validation is as follows:
`YYYY-MM-ddThh:mm:ss.sss±hh:mm`
## Date and Time without Timezone
> Some examples:
```
2019-10-15T22:35:12
2018-05-01T13:32:11
2019-05-01T00:00:00
```
It is represented according to ISO 8601. Data that is independent of timezone must be sent with a Z at the end, indicating UTC. The following format will be validated:
`YYYY-MM-ddThh:mm:ss.sssZ`
## Date
> Some examples:
```
2019-10-15
2019-01-01
2017-03-20
```
In the case of fields that receive only the date, without any time, it must be sent in the following format:
`YYYY-MM-dd`
## Documents
Since document numbers are quite varied and many of them contain characters that do not qualify as numeric, all document numbers are defined as strings. Another good reason to define them as strings is to prevent leading zeros from disappearing. Documents provided on this page have a well-defined mask and will be subject to validation. The remaining documents, such as RG (General Registration), given their lack of standardization, will not be validated.
## CPF
> Examples of valid CPFs against the defined mask:
```
123.456.789-12
321.987.543-23
111.283.333-00
```
> Examples of invalid CPFs against the defined mask:
```
8.577.477-8
08.104.627/0001-23
123.456.789-1
23.456.789-01
```
The CPF is always defined as a string and will be validated against the mask:
`###.###.###-##`
## CNPJ
> Examples of valid CNPJs against the defined mask:
```
08.104.627/0001-02
01.079.210/0114-67
32.402.502/0001-35
```
> Examples of invalid CNPJs against the defined mask:
```
8.577.477-8
123.456.789-12
321.987.543-23
32.402.502/0001-3
032.402.502/0001-3
```
The CNPJ is always defined as a string and will be validated against the mask:
`##.###.###/####-##`
## IP
> Examples of valid IPs against the defined mask:
```
201.81.161.86
201.081.161.86
201.81.161.086
201.81.0.1
```
> Examples of invalid IPs:
```
201.81..86
358.81.161.86
201.81.161
```
IPs must always be sent in IPv4; leading zeros may or may not be sent, respecting the following mask:
`###.###.###.###`
---
# Status Dynamics
URL: /en/documentation/caas/device_manager/status_dynamics
The analysis process consists of sending an event, such as Device Validation, to the appropriate endpoint and waiting for the response.
After QI Tech performs the event analysis, it will return a response with a status referring to the analysis. The **analysis_status** field represents the result of the event analysis performed by QI Tech.
### **analysis_status**
As previously described, QI Tech has three **analysis_status** values that indicate the decision status of the analysis engine and operates according to the following state machine:
analysis_status | Description
:---------: | ---------
automatically_approved | QI Tech algorithms recommend that this event be approved.
automatically_reproved | QI Tech algorithms recommend that this event be rejected.
pending | Queries are taking longer than expected. This event has been queued for automatic analysis and will be processed as soon as possible.
---
# Library Compatibility
URL: /en/documentation/caas/device_scan/android/compatibility
| Setting | Minimum Version |
|------------|--------------|
|minSdkVersion|21|
---
# The DeviceScan Object
URL: /en/documentation/caas/device_scan/android/device_scan_object
To use DeviceScanSDK, you must instantiate the DeviceScan class. This instance receives currentContext and can be configured with token/session, environment, and an optional callback (notifier).
:::danger Important Reminder!
Starting from version 5.0.0, the authentication system was updated to use a temporary **token** instead of **mobileToken**.
:::
## Versão 5.0.0+
| Parameter | Purpose | Required |
|------------|--------------|--------------|
|currentContext|The application context, used to access required data. |Yes.|
|token (via .setToken(this.token))| Temporary authentication token that identifies that the collected data comes from your application. The token is obtained by making a request to the Device Scan API. |Yes.|
|sessionId (via .setSessionId(this.sessionId))|Session identifier from which the collected data originates. |Yes.|
|notifier (via .setNotifier(this.deviceScanNotifier))|An instance of `DeviceScanNotifier`. Works as a callback, returning the delivery status (success or failure). |No.|
|sandbox (via .setSandboxEnvironment())|Configures the library to send data to the `sandbox` environment. If not set, requests are sent to `production`. |No.|
**Default environment**: if `setSandboxEnvironment()` is not called, requests are sent to `production`.
## Earlier Versions (up to 4.x)
| Parameter | Purpose | Required |
|------------|--------------|--------------|
|currentContext|The application context, used to access required data. |Yes.|
|mobileToken (via .setMobileToken(this.mobileToken))|Customer key that identifies that the collected data comes from your application. If you have not yet received your **mobile-token**, contact support at: suporte.caas@qitech.com.br.|Yes.|
|sessionId (via .setSessionId(this.sessionId))|Session identifier from which the collected data originates. |Yes.|
|notifier (via .setNotifier(this.deviceScanNotifier))|An instance of `DeviceScanNotifier`. Works as a callback, returning the delivery status (success or failure).|No.|
|sandbox (via .setSandboxEnvironment())|Configures the library to send data to the `sandbox` environment. If not set, requests are sent to `production. |No.|
## Quick Summary (Migration)
- 5.0.0+: use a temporary `token` (`setToken(this.token)`)
- < 5.0.0: use `mobileToken` (`setMobileToken(this.mobileToken)`)
- In both: `currentContext` and `sessionId` are required. `notifier` and `sandbox` are optional.
---
# Implementation
URL: /en/documentation/caas/device_scan/android/example
:::danger Aviso Importante!
Starting from version 5.0.0, the authentication system has been updated to use a dynamic **token** instead of **mobileToken**. Before configuring the SDK, you must generate a temporary **token** through a server-to-server request to our Device Scan API.
:::
```java
package com.example.zaig_device_scan_sdk_test_app;
import androidx.appcompat.app.AppCompatActivity;
import android.os.Bundle;
import android.util.Log;
import android.view.View;
import com.qitech.android.devicescan.DeviceScan;
import com.qitech.android.devicescan.DeviceScanNotifier;
import java.util.ArrayList;
public class MainActivity extends AppCompatActivity {
private DeviceScan deviceScan;
private DeviceScanNotifier deviceScanNotifier;
@Override
protected void onCreate(Bundle savedInstanceState) {
super.onCreate(savedInstanceState);
setContentView(R.layout.activity_main);
deviceScanNotifier = new DeviceScanNotifier(this);
}
public void sendDeviceScan(View view) {
try{
deviceScan = new DeviceScan.Builder(this.getApplicationContext())
.setToken(this.token)
.setSessionId(this.sessionId)
.setNotifier(this.deviceScanNotifier)
.setSandboxEnvironment()
.build();
}catch (Exception ex) {
Log.e("DeviceScan Error", "There was an error collecting DeviceScan data: " + ex.toString());
}
}
@Override
public void onRequestPermissionsResult(int requestCode, String[] permissions, int[] grantResults){
try{
deviceScan.collectData(this.documentNumber,
this.eventId,
this.eventType);
}catch (Exception ex) {
Log.e("DeviceScan Error", "There was an error collecting DeviceScan data: " + ex.toString());
}
}
private class ScanNotifier implements DeviceScanNotifier {
AppCompatActivity activity;
public ScanNotifier (AppCompatActivity myActivity){
// This method is customizable and can be used to store the Activity, which is used to operate the UI
this.activity = myActivity;
}
public void onSuccess(){
Log.i("DeviceScan", "DeviceScan successfully submitted");
runOnUiThread(new Runnable() {
@Override
public void run() {
// Add here any UI changes that are required after the device scan is sent successfully
}
});
}
public void onError(){
Log.i("DeviceScan", "DeviceScan submission failed");
runOnUiThread(new Runnable() {
@Override
public void run() {
// Add here any UI changes that are required after the device scan is sent successfully
}
});
}
}
}
```
To use the Android device scan SDK, the following steps are required:
* Add the required permissions to the application's manifest;
* Import the library into the application project;
* When starting the application, instantiate the library, passing the appropriate parameters in its constructor, including the Notifier, responsible for providing the operation callback with the result;
* Use the Activity’s `onRequestPermissionsResult` function to be notified of whether the required permissions were approved or not;
* Request permissions from the user. Internet access permission is mandatory for the library to work;
* Once you are notified of whether permissions were approved or not, collect and send the data using the `collectData` method.
---
# Hybrid Solutions
URL: /en/documentation/caas/device_scan/android/hybrid_solutions
In addition to offering native integration in Java, our SDKs are also compatible with several cross-platform frameworks. This is made possible through the integration of native plugins tailored to each framework. By leveraging each solution’s native layer, it is possible to incorporate our native Android SDK.
Some of the most widely used cross-platform technologies include React Native ([Native Modules](https://reactnative.dev/docs/turbo-native-modules-introduction)), Cordova ([Plugin Development Guide](https://cordova.apache.org/docs/en/latest/guide/hybrid/plugins/index.html)), Ionic ([Native](https://ionicframework.com/docs/v3/native/)), Unity ([Native Plug-in para Android](https://docs.unity3d.com/Manual/PluginsForAndroid.html)), Xamarin ([Native Libraries](https://learn.microsoft.com/en-us/xamarin/android/platform/native-libraries)), Appcelerator, Phonegap and Node.
To simplify the integration process with our native solutions, we provide plugins for the React Native and Flutter frameworks. If you’re interested, we can provide the documentation and an integration example in our private repositories. For the other cross-platform technologies, we also have a few examples showing how to implement this bridge with the native code. Feel free to contact our support suporte.caas@qitech.com.br to request access.
---
# Information Gathering
URL: /en/documentation/caas/device_scan/android/information_gathering
To trigger data collection and submission, you must (after obtaining the user’s permissions) call the `collectData`. method. In addition to capturing device information, this method is intended to map the customer journey within the application. For this reason, it also accepts the `eventId` and `eventType` fields. The method takes the following parameters:
name | type | definition
---- | ---- | ---------
documentNumber | String | The user’s document number, if available (CPF/CNPJ without dots, dashes, or slashes)
eventId | String | An identifier for the event being reported
eventType | String | An enumerated value that defines the type of event being reported. Take care to ensure that very similar events are reported with the same enum value, so that intelligence can be built on top of this data.
After the data collection call, one of the two methods on the `DeviceScanNotifier` instance passed into the `DeviceScan` constructor will be called: `onSuccess` if all goes as expected, or `onError` if an error occurs.
---
# Introduction
URL: /en/documentation/caas/device_scan/android/introduction
Welcome to the QI Tech Android Device Scan integration manual! You should use our SDK to collect device information and user behavior data in your application and, in doing so, improve the accuracy of decision-making.
## Having Issues?
We’re not a company that hides behind an API. Get in touch with our [support](mailto:suporte.caas@qitech.com.br) and we’ll respond as quickly as possible. Feel free to call us if you need a faster response!
### We love Feedback
Even if you’ve already solved your issue, or if it’s very simple (even a typo or a poorly organized section), please send us an email. This helps us make the documentation more and more practical, so the next person won’t have to go through the same pain.
## Environments
We provide two environments for our customers. The selection is made through an enum passed into the SDK constructor. Currently, the following environments are available:
* Produção - `production`
* Sandbox - `sandbox`
:::danger Important Note!
Real personal and/or business data must not be used in QI Tech’s Sandbox environments.
:::
---
# Native Integration
URL: /en/documentation/caas/device_scan/android/native_java
To import our SDKs, you must make changes to the project and app build.gradle files.
## Adding it to the Project
Add the URL of our Maven repository to the project’s build.gradle (in Android Studio, this file appears as “Project: \{project_name\}”), as shown below:
```java
buildscript {
...
}
allprojects {
repositories {
...
maven { url 'https://sdks.qitech.com.br/' }
}
}
```
## Adding it to the App
Next, add the library you want to import to the app’s build.gradle (in Android Studio, this file appears as **“Module: \{project_name\}.app”**), including the dependency below:
```java
dependencies {
...
implementation 'com.qitech.android:devicescan:v6.0.0'
}
```
:::warning
Since **April 2025**, new Google Play policies require **Android API Level 35** for apps to be published or updated on the Google Play Store. Therefore, we strongly recommend using **targetSdkVersion 35** at minimum.
:::
:::info
Using **targetSdkVersion 35** implies using **compileSdkVersion 35**, which in turn triggers some minimum **requirements** for Android ecosystem tools:
* compileSdkVersion 35 --> AGP 8.6.0
* AGP 8.6.0 --> Gradle 8.7
* AGP 8.6.0 --> Java 17 (JDK 17)
* AGP 8.6.0 --> Kotlin 2+
:::
## Manifest File
To use the SDK, you must add the following configuration to your application’s AndroidManifest.xml:
```java
```
You must also add at least the Internet permission, which is used to send the collected data to QI Tech’s servers:
` `
The list of permissions must be adjusted according to your needs.
---
# Permissions
URL: /en/documentation/caas/device_scan/android/permissions
The SDK collects device data according to the permissions available at the time of collection: the more permissions your app requests and the user grants, the more information can be collected.
:::info **Atenção**
The INTERNET permission is required so the SDK can send information to QI Tech’s servers.
:::
## Permissions used by the SDK
Na versão atual do SDK, as permissões abaixo podem ser utilizadas, caso estejam disponíveis:
| Permissão | Função | Obrigatória |
|------------|--------------|--------------|
|INTERNET|Sends information to QI Tech’s servers.| Yes. |
|BLUETOOTH|Collects information about Bluetooth hardware.| No. |
|BLUETOOTH_CONNECT|Collects Bluetooth connection information.| No. |
|READ_CONTACTS|Reads the contacts list.| No. |
|ACCESS_COARSE_LOCATION|Accesses network information (cell tower, carrier, etc.) and derives location through it (less accurate).| No. |
|ACCESS_FINE_LOCATION|Accesses GPS location (more accurate).| No. |
|READ_PHONE_STATE|Network, SIM, IMEI, and other telephony-related information.| No. |
|QUERY_ALL_PACKAGES|Information about installed apps on the device (required for devices running Android 11 or higher).| No. |
:::info **Important**
Our SDK does not request the permissions listed above. Therefore, to ensure a more complete device scan, we recommend requesting and obtaining these permissions before calling the device scan.
:::
:::info **Attention**
The QUERY_ALL_PACKAGES permission may cause friction with Google Play during app release. To address this, you can provide a justification for requesting this permission.
:::
---
# Authentication
URL: /en/documentation/caas/device_scan/api/authentication
:::danger Aviso Importante!
Starting from version 5.0.0 of the iOS and Android SDKs, the authentication system has been updated to use a temporary token instead of mobileToken.
:::
We use an API Key to allow access to our API. It was likely sent to you by email. If you haven’t received your key yet, email suporte.caas@qitech.com.br .
## Temporary authentication token
Before configuring the SDK, you must generate a temporary token by making a server-to-server request to our API.
### Generate token
```bash
curl -X POST "https://d.viewpkg.com/device_scan/token" \
-H "Authorization: EXAMPLE_API_KEY" \
-H "Content-Type: application/json" \
-d '{ "session_id": "unique_session_identifier" }'
```
**Endpoints**
| Environment | URL |
|----------|-----|
| Sandbox | https://d.sandbox.viewpkg.com/device_scan/token |
| Produção | https://d.viewpkg.com/device_scan/token |
**Request Details**
| Field | Type | Required | Description|
|-------|------|------------|---------|
| session_id | string | Yes | Unique session identifier generated by your system (e.g., UUID). |
**Request Body**
```json
{
"session_id": "unique_session_identifier" (Obrigatório)
}
```
**Response Body**
A successful response will include the `token` field.
```json
{
"token": "eyJzdWIiOiIxMjM0NTY3ODkwIiwibmFtZSI6..."
}
```
:::info Attention
You must replace EXAMPLE_API_KEY with the API Key provided by support.
:::
---
# Library Compatibility
URL: /en/documentation/caas/device_scan/flutter/compatibility
| Setting | Minimum version |
|------------|--------------|
|Flutter|3.3.0|
|Dart SDK|3.2.3|
|iOS|15.5|
|minSdkVersion (Android)|23|
---
# The QitechDeviceScan object
URL: /en/documentation/caas/device_scan/flutter/device_scan_object
:::danger Important Note!
As of version 1.0.0, the authentication system has been updated to use a temporary **token** instead of **mobileToken**. The token is obtained by making a server-to-server request to the Device Scan API.
:::
## Request
To use the Device Scan plugin, you must call the `startDeviceScan` method, which has the following parameters:
## Version 1.0.0+
| Parameter | Type | Purpose | Required |
|------------|--------------|--------------|--------------|
|token|String|Temporary authentication token obtained by making a request to the Device Scan API. Must be generated using the same `sessionId` passed to this method.|Yes.|
|environment|CaaSEnvironment|Enum used to configure the runtime environment as `sandbox` or `production`.|Yes.|
|sessionId|String|Key that identifies the session from which the collected data originates. **Must be sent in lowercase.**|Yes.|
|eventType|String|An enum that defines the type of event being reported — care is requested so that very similar events are reported with the same enum, so that intelligence can be built on top of this data.|Yes.|
|eventId|String|An identifier of the event being reported.|Yes.|
|documentNumber|String?|The user's document number, if available. (CPF/CNPJ without dots, dashes, and slash). Can be omitted.|No.|
## Previous Versions (up to 0.x)
| Parameter | Type | Purpose | Required |
|------------|--------------|--------------|--------------|
|mobileToken|String|Customer key that identifies that the collected data comes from your application. If you have not yet received your mobile-token, contact support.|Yes.|
|environment|CaaSEnvironment|Enum used to configure the runtime environment as `sandbox` or `production`.|Yes.|
|sessionId|String|Key that identifies the session from which the collected data originates. **Must be sent in lowercase.**|Yes.|
|eventType|String|An enum that defines the type of event being reported — care is requested so that very similar events are reported with the same enum, so that intelligence can be built on top of this data.|Yes.|
|eventId|String|An identifier of the event being reported.|Yes.|
|documentNumber|String?|The user's document number, if available. (CPF/CNPJ without dots, dashes, and slash). Can be omitted.|No.|
## Quick Reference (Migration)
- 1.0.0+: use temporary `token` obtained via API (`token: token`)
- '`)
- In both: `environment`, `sessionId`, `eventType`, and `eventId` are required. `documentNumber` is optional.
## Return value
The method returns a String to indicate success or failure during information collection:
### Success
```javascript
Success collecting device scan data
```
### Error
```javascript
Device Scan fail. Check token, environment and permissions
```
---
# Implementation
URL: /en/documentation/caas/device_scan/flutter/example
## Prerequisite for startDeviceScan
The `startDeviceScan` method requires a `token`. This token is temporary and must be generated on your backend by making a server-to-server request to our API before you call the SDK method.
**Endpoint Details:**
- **Method:** POST
- **Path:** `/device_scan/token`
- **Sandbox URL:** `https://d.sandbox.viewpkg.com/device_scan/token`
- **Production URL:** `https://d.viewpkg.com/device_scan/token`
**Headers:**
```json
{
"Authorization": "YOUR_DEVICE_SCAN_API_KEY"
}
```
**Body:**
```json
{
"session_id": "unique_session_id"
}
```
The successful response from this API will contain the `token` that you must pass to the `startDeviceScan` method.
:::note
The device scan method can be executed asynchronously. Therefore, there is no need to block the main thread to wait for this method to resolve. The user can interact normally with the app while the device scan is being processed in the background.
:::
:::note
We recommend that the device scan method is executed as early as possible. Since it may need more time to collect all data, this early call is recommended so that the most complete device information is extracted.
:::
---
```dart
import 'dart:convert';
import 'dart:io';
import 'package:http/http.dart' as http;
import 'package:qitech_device_scan/qitech_device_scan.dart';
final _qitechDeviceScanPlugin = QitechDeviceScan();
// Step 1: Generate the temporary token via a server-to-server request
Future fetchDeviceScanToken(String sessionId) async {
final response = await http.post(
Uri.parse(''),
headers: {
HttpHeaders.authorizationHeader: '',
HttpHeaders.contentTypeHeader: 'application/json',
},
body: jsonEncode({'session_id': sessionId}),
);
if (response.statusCode == 200) {
final data = jsonDecode(response.body);
return data['token'] as String?;
}
return null;
}
// Step 2: Initialize the SDK with the obtained token
final sessionId = '';
final token = await fetchDeviceScanToken(sessionId);
if (token == null) {
print('Failed to fetch device scan token');
return;
}
final result = await _qitechDeviceScanPlugin.startDeviceScan(
token: token,
environment: CaaSEnvironment.sandbox,
sessionId: sessionId,
eventType: '',
eventId: '',
);
print('Device Scan result: $result');
```
## Flutter Setup
To use the device scan plugin, the following steps are required:
### Installation
First, run the following command to install the plugin:
```bash
flutter pub add qitech_device_scan
```
The command should install the latest version, which can be checked in your `pubspec.yaml` file:
```yaml
dependencies:
qitech_device_scan: ^1.0.0
http: ^1.0.0
```
### Import
Now, just import the package to start using it:
```dart
import 'package:qitech_device_scan/qitech_device_scan.dart';
```
## Android Setup
Add the Qi Tech Android repository reference in your `build.gradle` file:
```gradle
allprojects {
repositories {
maven { url 'https://sdks.qitech.com.br/' }
...
}
}
```
Initialize the AdMob service by adding the following code to your `AndroidManifest.xml`:
```xml
```
If you do not have an ADMOB_APP_ID, contact suporte.caas@qitech.com.br .
## iOS Setup
Add the Qi Tech iOS repository reference in your `Podfile`:
```ruby
source 'https://cdn.cocoapods.org/'
source 'https://github.com/QITechSDKs/iOS.git'
```
Install dependencies directly via CocoaPods:
```bash
cd ios
pod install
```
or via Flutter:
```bash
flutter build ios
```
---
# Introduction
URL: /en/documentation/caas/device_scan/flutter/introduction
Welcome to the QI Tech Device Scan integration manual for Flutter! You should use our Plugin to collect information from the phone and user behavior in your application, thus improving the accuracy of decisions.
## Having issues?
We are not a company that hides behind an API! Contact our [support](mailto:suporte.caas@qitech.com.br) and we will respond as quickly as possible. Feel free to call us if you want a quick response!
## We love feedback
Even if you have already solved your problem or if it is very simple (even a typo or poor organization that you already understood), send us an email—this way we make the documentation more and more practical and the next person won’t have to suffer the pains you suffered!
## Environments
We have two environments for our customers. The selection is made through an enum passed as a parameter in the plugin call. At the moment, the following environments are available:
* Production - `production`
* Sandbox - `sandbox`
:::danger Important Note!
Real personal and/or business data must not be used in QI Tech’s Sandbox environments.
:::
---
# Permissions
URL: /en/documentation/caas/device_scan/flutter/permissions
The plugin collects the user’s device data according to the permissions available at the time of collection: the more permissions your application requires and the user grants, the more information is collected from the user’s device.
:::info **Attention**
The INTERNET permission is required so the SDK can send information to QI Tech’s servers.
:::
## Permissions used by the plugin
:::info **Important**
Our plugin does not request the permissions described. Therefore, to ensure a more complete device scan, we recommend obtaining these permissions before calling the device scan.
:::
### Android
For the Android platform, the following permissions are used if available:
| Permission | Purpose | Required |
| ---------------------- | --------------------------------------------------------------------------------------------------- | -------- |
| INTERNET | Required to send information to QI Tech’s servers. | Yes. |
| BLUETOOTH | Captures Bluetooth hardware information. | No. |
| BLUETOOTH_CONNECT | Captures Bluetooth connection information. | No. |
| READ_CONTACTS | Reads the contacts list. | No. |
| ACCESS_COARSE_LOCATION | Accesses network information (cell tower, carrier...) and location via this method (less accurate). | No. |
| ACCESS_FINE_LOCATION | Accesses location via GPS (more accurate). | No. |
| READ_PHONE_STATE | Network, SIM, IMEI, and other telephony-related information. | No. |
| QUERY_ALL_PACKAGES | Information about installed apps on the device. Required for Android 11+ devices. | No. |
:::info **Attention**
The QUERY_ALL_PACKAGES permission may cause friction with Google Play during app release. To address this, you can describe the reason for requesting the permission.
:::
### iOS
For the iOS platform, the following permissions are used if available:
* location - Captures device geolocation data
#### Info.plist file
The first step to enable permissions for the plugin is to configure the permission in the app’s Info.plist file, using the following line of code for each desired permission:
* location - Captures device geolocation data:
` NSLocationWhenInUseUsageDescription `
` Add the message you want to show the user when iOS requests permission to access geolocation `
:::info **Attention**
To improve the user experience when requesting permissions, you should customize the message shown in the permission request pop-up as described above.
:::
---
# The QITechIosDeviceScan object
URL: /en/documentation/caas/device_scan/ios/device_scan_object
To use QI Tech’s iOS DeviceScan, you must import the QITechIosDeviceScan framework and then instantiate the QITechIosDeviceScan class, which has the following constructor parameters:
:::danger Important Note!
Starting from version 5.0.0, the authentication system was updated to use a temporary **token**instead of **mobileToken**.
:::
## Version 5.0.0+
| name | type | description |
| ----------- | ------ | ---- |
| environment | String | An environment enum where the application is running — `sandbox` or `production`. If a different value is sent, an exception will be thrown. **required**|
| token| String | Authentication token that identifies that the collected data comes from your application. Obtained through a request to the Device Scan API. **required**|
| sessionId | String | Session identifier (**must be the same used to generate the token**) which will also be sent at the moment of the event evaluation (Transaction, Onboarding, for example), to correlate the device scan data with the event to be evaluated. **required** |
## Previous versions
| name | type | description |
| ----------- | ------ | --- |
| environment | String | An environment enum where the application is running — `sandbox` or `production`. If a different value is sent, an exception will be thrown. **required** |
| mobileToken | String | Customer key sent by QI Tech support that identifies that the collected data comes from your application. For security reasons, if this key is incorrect, QI Tech servers will receive the call but will not process it. **required** |
| sessionId | String | Session identifier, which will also be sent at the moment of the event evaluation (Transaction, Onboarding, for example), to correlate the device scan data with the event to be evaluated. **required**|
---
# Implementation
URL: /en/documentation/caas/device_scan/ios/example
:::danger Important Note!
Starting from version 5.0.0, the authentication system was updated to use a dynamic **token** instead of **mobileToken**. Before configuring the SDK, you must generate a temporary **token** through a server-to-server request to our Device Scan API.
:::
```swift
import UIKit
import QITechIosDeviceScan
class ViewController: UIViewController {
var qitechDeviceScan : QITechIosDeviceScan?
override func viewDidLoad() {
super.viewDidLoad()
self.setupDeviceScan()
}
func setupDeviceScan() -> Void
{
// The environment can be 'sandbox' ou 'production'
let environment = "sandbox"
// MobileToken is the key sent to you by QI Tech. Each environment requires a different MobileToken.
let token = "TEMPORARY_TOKEN_FROM_DEVICE_SCAN_API"
// You must send the same session id in the moment of using the device scan and event analysis. It must be a key that uniquely identifies each user session in the app
let sessionId = "62715840-068a-4ded-a4e2-a1ec83f857d4"
do{
self.qitechDeviceScan = try QITechIosDeviceScan(environment: environment, token: token, sessionId: sessionId)
}
catch{
print ("Error found when instantiating QITech's DeviceScan")
}
let permissions = ["location"]
do{
try self.qitechDeviceScan?.requestPermissions(permissions: permissions)
}
catch{
print ("Error found when requesting QITech's DeviceScan's permissions")
}
}
func onSuccess()
{
// Do something if QI Tech DeviceScan's collectData method succesfully collected device data
}
func onError()
{
// Do something if QI Tech DeviceScan's collectData method found any error when collecting device data
}
func collectQITechDeviceScanData()
{
// If you have your customer's document number (CPF or CNPJ without dots, hyphen or slash), you must sent it to QI Tech
let documentNumber = "12345678900"
// EventType must represent with type of interation the user had with your app on the moment that collectData method was called
let eventType = "login"
// EventId is your code that identifies the event sent to QI Tech
let eventId = "7038632032"
do{
try self.qitechDeviceScan?.collectData(documentNumber: documentNumber, eventId: eventId, eventType: eventType, onSuccessHandler: self.onSuccess, onErrorHandler: self.onError)
}
catch{
print("Error found when collecting QITech's DeviceScan data")
}
}
}
```
To use the iOS Device Scan SDK, the following steps are required:
* Add the required permissions to the Info.plist file
* Add the framework to the app project
* When the app starts, instantiate the library with the appropriate parameters
* If your app has not yet requested the permissions from the user, request them through the `requestPermissions` function of the previously instantiated object
* Collect and send the data using the `collectData` method
---
# Hybrid solutions
URL: /en/documentation/caas/device_scan/ios/hybrid_solutions
In addition to offering native integration in Swift, our SDKs are also compatible with several hybrid frameworks. This is possible through the integration of native plugins specific to each of these frameworks. By leveraging each solution’s native system, it is possible to incorporate our native SDK in the iOS environment.
Some of the most widely used hybrid technologies include React Native ([Native Modules](https://reactnative.dev/docs/turbo-native-modules-introduction)), Cordova ([Plugin Development Guide](https://cordova.apache.org/docs/en/latest/guide/hybrid/plugins/index.html)), Ionic ([Native](https://ionicframework.com/docs/v3/native/)), Unity ([Native Plug-in para Android](https://docs.unity3d.com/Manual/PluginsForAndroid.html)), Xamarin ([Native Libraries](https://learn.microsoft.com/en-us/xamarin/android/platform/native-libraries)), Appcelerator, Phonegap and Node.
To simplify the integration process with our native solutions, we provide plugins for the React Native and Flutter frameworks. If you’re interested, we provide the documentation and an integration example in our private repositories. For the other hybrid technologies, we have a few examples of how to implement this bridge to the native code. Feel free to contact our support to request access.
---
# Information gathering
URL: /en/documentation/caas/device_scan/ios/information_gathering
To trigger data collection and submission, you must call the `collectData` method. In addition to capturing device information, the method aims to map the customer journey within the application. For this reason, the method also accepts the `eventId` and `eventType` fields. Another important point is that the method sends the information to QI Tech’s server via an asynchronous HTTP request, and therefore the success or error notification for the request is handled through Completion Handlers. The method has the following parameters:
| name | type | description |
| ---------------- | -------------- | ----------- |
| documentNumber | String | The user’s document number, if available. (CPF/CNPJ without dots, dashes, and slash)|
| eventId | String | An identifier of the event being reported|
| eventType | String | An enum that defines the type of event being reported (Example: 'login') — Take care to ensure that very similar events are reported with the same enum, so that intelligence can be built on top of this data |
| onSuccessHandler | func() ‑> Void | Function that will be called if the data is successfully sent to QI Tech’s server **required**|
| onErrorHandler | func() ‑> Void | Function that will be called if there is an error sending the data to QI Tech’s server **required**|
---
# Introduction
URL: /en/documentation/caas/device_scan/ios/introduction
Welcome to the QI Tech iOS Device Scan integration manual! You should use our SDK to collect device information and user behavior data in your application and, in doing so, improve the accuracy of decision-making.
## Having Issues?
We’re not a company that hides behind an API. Get in touch with our [support](mailto:suporte.caas@qitech.com.br) and we’ll respond as quickly as possible. Feel free to call us if you need a faster response!
### We love Feedback
Even if you’ve already solved your issue, or if it’s very simple (even a typo or a poorly organized section), please send us an email. This helps us make the documentation more and more practical, so the next person won’t have to go through the same pain.
## Environments
We provide two environments for our customers. The selection is made through an enum passed into the SDK constructor. Currently, the following environments are available:
* Produção - `production`
* Sandbox - `sandbox`
:::danger Important Note!
Real personal and/or business data must not be used in QI Tech’s Sandbox environments.
:::
---
# Native integration
URL: /en/documentation/caas/device_scan/ios/native_swift
## Remotely
> Starting the installation
```shell
pod init
```
Our SDK can be imported using CocoaPods.
SDK | Current version
---- | -----
QITechIosDeviceScan | `pod 'QITechIosDeviceScan', '~> 6.0.0'`
:::info iOS Minimum Deployment Target
15.5
:::
To start the installation, run the command shown above in the root folder of your project.
> Adding the source to the Podfile
```ruby
source 'https://github.com/QITechSDKs/iOS.git'
```
The next step is to add QI Tech’s source to the `Podfile`.
> Adding the pod to the Podfile
```ruby
pod 'QITechIosDeviceScan', '~> '
```
Finally, add the `pod` name following the format above.
:::danger Attention:
Architecture change (v5.0.0+) Starting from version 5.0.0, the SDK started being distributed exclusively in static form. In your Podfile, you must use the configuration :linkage => :static.
:::
> Podfile example (Version 5.0.0 or higher)
```ruby
source 'https://github.com/QITechSDKs/iOS.git'
target 'ExampleApp' do
use_frameworks! :linkage => :static
pod 'QITechIosDeviceScan', '~> 6.0.0'
end
post_install do |installer|
installer.pods_project.targets.each do |target|
if ['DatadogCore', 'DatadogInternal', 'DatadogCrashReporting', 'DatadogLogs'].include?(target.name)
target.build_configurations.each do |config|
config.build_settings['IPHONEOS_DEPLOYMENT_TARGET'] = '15.5'
config.build_settings['BUILD_LIBRARY_FOR_DISTRIBUTION'] = 'YES'
end
end
end
end
```
> Podfile example (Previous versions)
```ruby
source 'https://github.com/QITechSDKs/iOS.git'
target 'ExampleApp' do
use_frameworks!
pod 'QITechIosDeviceScan', '~> 2.0.0'
end
post_install do |installer|
installer.pods_project.targets.each do |target|
if ['DatadogCore', 'DatadogInternal', 'DatadogCrashReporting', 'DatadogLogs'].include?(target.name)
target.build_configurations.each do |config|
config.build_settings['IPHONEOS_DEPLOYMENT_TARGET'] = '15.5'
config.build_settings['BUILD_LIBRARY_FOR_DISTRIBUTION'] = 'YES'
end
end
end
end
```
:::info **Attention**
You must enable module stability for the Datadog monitoring dependency to avoid potential compilation issues across different Swift versions. Therefore, add the block described in the post_install section of your Podfile (or include it in the existing post_install block if you already have one).
:::
:::warning Attention
When integrating dependencies on iOS, you may need to use static linkage for some libraries and dynamic linkage for others. This setup is relevant to ensure compatibility, avoid build errors, and optimize project performance.
:::
### Hybrid linkage of dependencies (if needed)
The need for hybrid linkage arises because some libraries have specific requirements: some need static linkage to avoid internal conflicts and symbol duplication, while other dependencies may need dynamic linkage because they are designed for modularity and sharing across projects.
Differences between static and dynamic linkage
* Static (static_framework): The library code is embedded directly into the final binary, reducing runtime loading time and eliminating external dependencies at execution time.
* Dynamic (dynamic_framework): The library is loaded at runtime as a separate file. This reduces the final binary size and makes independent updates/modifications easier.
> Configuring hybrid linkage in the Podfile
```ruby
...
use_frameworks! :linkage => :dynamic # SETTING THE DEFAULT LINKAGE MODE TO DYNAMIC
...
static_frameworks = ['framework_1', 'framework_2', ...] # INCLUDE ALL DEPENDENCIES THAT MUST BE LINKED STATICALY
pre_install do |installer|
installer.pod_targets.each do |pod|
if static_frameworks.include?(pod.name)
def pod.static_framework?;
true
end
def pod.build_type;
Pod::BuildType.static_framework
end
end
end
end
```
> Installing dependencies
```shell
pod install
```
Finally, run `pod install` to download and install the dependencies.
---
# Permissions
URL: /en/documentation/caas/device_scan/ios/permissions
The SDK collects device data and, according to how the iOS operating system works, it requires specific permissions for each piece of data to be collected. In order to provide a customized experience for users of an application that has the SDK embedded, we implemented a mechanism that uses the parameters passed by the developer to request permissions from the user, following this flow:
* The permissions sent as parameters to the `requestPermissions` method, as Strings, are requested from the user — unless they have already been requested previously.
* The user, through a dialog provided by the operating system itself, is asked about the permissions considered necessary by the framework.
* The permissions are then granted or denied and, when the `collectData` method is called, it will collect only the data for which permission was granted.
:::info **Attention**
If your app has already requested the required permissions, you do not need to call `requestPermissions` again; the SDK will inherit the permissions requested by the app.
:::
## Permissions used by the SDK
In the current SDK version, the following permissions are used if available:
* location - Captures device geolocation data
## Info.plist file
The first step to enable permissions for the SDK is to configure the permission in the app’s Info.plist file, using the following line of code for each desired permission:
* location - Captures device geolocation data:
` NSLocationWhenInUseUsageDescription `
` Add the message you want to display to the user when iOS requests permission to access geolocation `
:::info **Attention**
To improve the user experience when requesting permissions, you should customize the message shown in the permission request pop-up as described above.
:::
---
# Desktop Device Scan
URL: /en/documentation/caas/device_scan/web/desktop
This is the **Desktop Device Scan**, our complementary *white-label* module for the **Web Device Scan**. You can use our program to collect deep device information and also detect the presence of malicious software.
This software was developed to comply with [BCB Normative Instruction No. 491](https://www.bcb.gov.br/estabilidadefinanceira/exibenormativo?tipo=Instru%C3%A7%C3%A3o%20Normativa%20BCB&numero=491). ogether with Web Device Scan, it is able to generate a unique and reliable identification for each device.
:::warning Attention
Our application is *White Label*! You can use your own logos in the installer, as well as customize the executable name and the displayed messages, making the experience friendlier for your user.
:::
## Usage
In this step-by-step guide, you will find details on how to use the program together with the library, as well as a JavaScript implementation example. This will give you the tools you need to adapt the solution to your use case.
```html
```
When using the `deviceScan.setDesktop(true)` flag, the Web SDK will try to detect whether the installed application is present. If it is not installed or if it has issues, you may receive one of the following errors:
| Error | Description |
| --------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| **Timeout in Secure App** | The application is present but is not responding correctly. Reinstall the application to fix the issue. |
| **Invalid desktop data** | The application was modified or corrupted. Reinstall the application to restore integrity. |
| **Desktop App Not Present** | The application is not installed. Provide the download link supplied by QI Tech to the user. |
| **Unexpected App Error** | An unexpected error occurred while communicating with the application. If the problem persists after reinstalling, contact support: support. |
## Supported Operating Systems
**Desktop Device Scan** is available for the main modern operating systems, offering native compatibility and optimized performance on each platform.
Windows 10/11 x64
macOS Intel (x86_64)
macOS Apple Silicon (M1/M2/M3)
---
# The DeviceScan object
URL: /en/documentation/caas/device_scan/web/device_scan_object
To use the device scan service, you must instantiate the DeviceScan class, which has the following constructor parameters:
| Parameter | Purpose | Required |
| ----------------------- | ------------------------------------ | -------- |
| `.setSandbox()` | If this parameter is used in the constructor, the library will be configured to send data to the `sandbox` environment. If omitted, requests are sent to the `production` environment. | No. |
| `.setGeoLocation(true)` | If this parameter is set to `true`, the library will request permission to collect GPS data. If omitted or set to `false`, geolocation information will not be extracted. | No. |
:::info **Attention**
If the user denies access to location data, the library will run normally, but without collecting that information.
:::
## The deviceScan.info() function
To run the user data analysis function, you must send the following parameters to the library. They will identify your company and the user session to which the information belongs. In addition, the event_id and event_type arguments, although optional, help us identify the user’s navigation pattern on your page and therefore prevent fraud even more effectively.
Below are the details for each argument:
| Name | Type | Description|
| ---------- | ------ | ----------------------------------- |
| web_token | String | Customer key that identifies that the collected data comes from your application. If you have not yet received your web-token, contact support. **required** |
| session_id | String | Key that identifies the session from which the collected data originates. **required**|
| event_id | String | An identifier for the event being reported|
| event_type | String | An enum that defines the type of event being reported — Care is requested so that very similar events are reported with the same enum, so that intelligence can be built on top of this data.|
## Implementation example
A simple implementation example is shown below:
```html
html>