# QI Tech — Banking-as-a-Service › Indirect Pix
Documentação da QI Tech em texto corrido, para colar em um LLM.
Fonte: https://docs.qitech.com.br
60 página(s).
Índice:
- Creating a PIX key for an Alias (/en/documentation/pix_indireto/chaves_pix/criacao_de_chaves)
- Pix Key deletion for an Alias (/en/documentation/pix_indireto/chaves_pix/deletar_chaves)
- Introduction to PIX key management for an Alias (/en/documentation/pix_indireto/chaves_pix/introducao_chaves_pix)
- Pix Keys listing for an Alias (/en/documentation/pix_indireto/chaves_pix/listar_chaves)
- Cancel Refund Request (/en/documentation/pix_indireto/devolucao/cancelar_devolucao)
- Consult Return Request (/en/documentation/pix_indireto/devolucao/consultar_devolucao)
- Open Refund Request (/en/documentation/pix_indireto/devolucao/criar_devolucao)
- Close Refund Request (/en/documentation/pix_indireto/devolucao/fechar_devolucao)
- List Refund Requests (/en/documentation/pix_indireto/devolucao/listar_solicitacoes)
- Introduction to the Refund Flow (/en/documentation/pix_indireto/devolucao/maquina_estados)
- Scenario Simulation (/en/documentation/pix_indireto/devolucao/simulacao_de_cenarios)
- Receive Refund Request (/en/documentation/pix_indireto/devolucao/webhooks_devolucao)
- Consult an Alias Entity (/en/documentation/pix_indireto/gerenciamento_de_alias/consultar_alias)
- Consult Alias by Request Control Key (/en/documentation/pix_indireto/gerenciamento_de_alias/consultar_request_control_key)
- Creating an Alias Entity (/en/documentation/pix_indireto/gerenciamento_de_alias/criacao_de_alias)
- Deletion of an Alias Entity (/en/documentation/pix_indireto/gerenciamento_de_alias/deletar_alias)
- Introduction to Alias Entity (/en/documentation/pix_indireto/gerenciamento_de_alias/introducao_alias)
- Alias Listing (/en/documentation/pix_indireto/gerenciamento_de_alias/listagem_de_alias)
- Introduction (/en/documentation/pix_indireto/introducao)
- Mocked Pix keys in the sandbox environment (/en/documentation/pix_indireto/movimentacoes/chaves_pix_mockadas)
- Pix Key Lookup (/en/documentation/pix_indireto/movimentacoes/consultar_chave_pix)
- Consult Pix transaction (/en/documentation/pix_indireto/movimentacoes/consultar_pix)
- Pix Refund (/en/documentation/pix_indireto/movimentacoes/devolucao_pix)
- Introduction to PIX Transactions (/en/documentation/pix_indireto/movimentacoes/introducao_movimentacoes)
- Scenario Simulation (/en/documentation/pix_indireto/movimentacoes/simulacao)
- Execute Asynchronous Transfer to Manual Pix (/en/documentation/pix_indireto/movimentacoes/transacao_async/transacao_pix_manual)
- Execute Asynchronous Transfer via Pix Key (/en/documentation/pix_indireto/movimentacoes/transacao_async/transacao_pix_normal)
- Perform Asynchronous Transfer to Pix QR Code (/en/documentation/pix_indireto/movimentacoes/transacao_async/transacao_pix_qr_code)
- Transaction by Pix Key (/en/documentation/pix_indireto/movimentacoes/transacao/transacao_pix_chave_sync)
- Manual Transaction (/en/documentation/pix_indireto/movimentacoes/transacao/transacao_pix_manual_sync)
- Transaction by QR Code (/en/documentation/pix_indireto/movimentacoes/transacao/transacao_pix_qr_code_sync)
- Webhook for Pix Refunds (/en/documentation/pix_indireto/movimentacoes/webhook/webhook_devolucao_outgoing_pix)
- Webhook for Incoming Pix (/en/documentation/pix_indireto/movimentacoes/webhook/webhook_incoming_pix)
- Webhook for Pending Transactions (/en/documentation/pix_indireto/movimentacoes/webhook/webhook_transacao)
- Cancel a Portability Request (/en/documentation/pix_indireto/portabilidade/cancelar_pedido_de_portabilidade)
- Complete a Portability Request (/en/documentation/pix_indireto/portabilidade/completar_pedido_de_portabilidade)
- Confirm a Portability Request (/en/documentation/pix_indireto/portabilidade/confirmar_pedido_de_portabilidade)
- Consult Portability Requests (/en/documentation/pix_indireto/portabilidade/consultar_pedido_de_portabilidade)
- Portability Request creation (/en/documentation/pix_indireto/portabilidade/criar_pedido_de_portabilidade)
- Introduction to Portability Requests (/en/documentation/pix_indireto/portabilidade/introducao_portabilidade)
- Consult Portability Requests for an Alias (/en/documentation/pix_indireto/portabilidade/listar_pedidos_de_portabilidade_de_um_alias)
- Portability Update Webhook (/en/documentation/pix_indireto/portabilidade/webhook/webhook_atualizacao_do_pedido_de_portabilidade)
- Portability Request Received Webhook (/en/documentation/pix_indireto/portabilidade/webhook/webhook_receber_registro_externo_de_portabilidade)
- Consult QR Code (/en/documentation/pix_indireto/qr_code/consultar_qr_code)
- Create Dynamic PIX QR Code with Due Date (/en/documentation/pix_indireto/qr_code/Criar QR Code/criar_qr_code_dinamico_com_vencimento)
- Create Dynamic PIX QR Code for Immediate Payment (/en/documentation/pix_indireto/qr_code/Criar QR Code/criar_qr_code_dinamico_imediato)
- Create Static PIX QR Code (/en/documentation/pix_indireto/qr_code/Criar QR Code/criar_qr_code_estatico)
- List QR Codes of an alias (/en/documentation/pix_indireto/qr_code/decodificar_qr_code)
- Update/Deactivate a PIX QR Code (/en/documentation/pix_indireto/qr_code/desativar_qr_code)
- Introduction to PIX QR Code (/en/documentation/pix_indireto/qr_code/introducao_qr_code)
- List QR Codes of an alias (/en/documentation/pix_indireto/qr_code/listar_alias_qr_codes)
- Webhook for Incoming PIX Payment of QR Code (/en/documentation/pix_indireto/qr_code/webhook_incoming_pix)
- Cancel Infraction Report (/en/documentation/pix_indireto/relato_de_infracao/cancelar_relato_infracao)
- Consult Infraction Report (/en/documentation/pix_indireto/relato_de_infracao/consultar_relato_infracao)
- Open Infraction Report (/en/documentation/pix_indireto/relato_de_infracao/criar_relato_infracao)
- Close Infraction Report (/en/documentation/pix_indireto/relato_de_infracao/fechar_relato_infracao)
- List Infraction Reports (/en/documentation/pix_indireto/relato_de_infracao/listar_relatos)
- Introduction to the Infraction Report Flow (/en/documentation/pix_indireto/relato_de_infracao/maquina_estados)
- Scenario Simulation (/en/documentation/pix_indireto/relato_de_infracao/simulacao_de_cenarios)
- Receive Infraction Report (/en/documentation/pix_indireto/relato_de_infracao/webhooks_relato_infracao)
---
# Creating a PIX key for an Alias
URL: /en/documentation/pix_indireto/chaves_pix/criacao_de_chaves
## Request
ENDPOINT /account/ ACCOUNT_KEY /alias/ ALIAS_KEY /pix_key
METHOD POST
**Request Body - 'random_key' type key**
```json
{
"request_control_key": "3d3d0083-ac71-46f0-8a90-c00a157a4893",
"pix_key_type": "random_key"
}
```
**Request Body - CPF type key**
```json
{
"request_control_key": "3d3d0083-ac71-46f0-8a90-c00a157a4893",
"pix_key_type": "cpf",
"pix_key": "67824450007"
}
```
### Request Path Params
| Field | Type | Description | Characters |
|---------------|--------|-----------------------|------------|
| `account_key` | uuidv4 | Unique account key. | 36 |
| `alias_key` | uuidv4 | Unique alias key. | 36 |
### Request Body Params
| Field | Type | Description | Max. Characters |
|-------------------------|--------|---------------------------------------------------------------------------------|-----------------|
| `request_control_key` * | string | UUID4 for querying purposes about the made request. | 36 |
| `pix_key_type` * | string | Definition of the type of key to be created. Possible values: 'cpf', 'cnpj', 'email', 'phone_number', 'random_key' | 10 |
| `pix_key` | string | PIX key value to be created. Should not be sent for 'random_key' type cases. | 10 |
:::info PIX Key Types
The `pix_key` sent in the request can be a CPF, CNPJ, email or mobile phone, following these formats:
**CPF**: Integer number with 11 digits.
**CNPJ**: Integer number with 14 digits.
**Email**: Text containing at least one "@".
**Mobile phone**: Text containing the following values: "+55" + "mobile area code" + "Mobile phone integer number with minimum 8
and maximum 9 digits". Ex: "+5511987654321".
:::
## Response
STATUS 200
Response Body
```json
{
"pix_key": "asra-4cd6-4c04-9651-1c0a2c30d7dd",
"pix_key_status": "active",
"created_at": "2021-12-06T21:16:11.001Z",
"pix_key_type": "random_key"
}
```
### Response Body Params
| Field | Type | Description | Max. Characters |
|-------------------------|--------|---------------------------------------------------------------------------------|-----------------|
| `pix_key` | string | Created PIX key value. | 200 |
| `pix_key_status` | string | PIX key activation status. Can be "active","inactive" or "pending" | 8 |
| `created_at` | datetime Zulu | Request creation date. | 20 |
:::info PIX Key Types
The `pix_key` sent in the request response can be a CPF, CNPJ, email, mobile phone or random key, following these formats:
**CPF**: Integer number with 11 digits.
**CNPJ**: Integer number with 14 digits.
**Email**: Text containing at least one "@".
**Mobile phone**: Text containing the following values: "+55" + "mobile area code" + "Mobile phone integer number with minimum 8
and maximum 9 digits". Ex: "+5511987654321".
**Random key**: UUIDV4.
:::
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 | PIX000080 | Not enough permission | The selected agent is not an Pix Indirect Participant | O agente selecionado não é um Participante Indireto do Pix |
| 404 | PIX000082 | Alias not found | Alias \{alias_key\} not found | Alias \{alias_key\} não encontrado |
---
# Pix Key deletion for an Alias
URL: /en/documentation/pix_indireto/chaves_pix/deletar_chaves
## Request
ENDPOINT /account/ ACCOUNT_KEY /alias/ ALIAS_KEY /pix_key/ PIX_KEY
METHOD DELETE
Request Body
```json
{}
```
### Path Params
| Field | Type | Description | Characters |
|--------------|--------|------------------------------|------------|
| `account_key`| uuidv4 | Unique account key. | 36 |
| `alias_key` | uuidv4 | Unique alias key. | 36 |
| `pix_key` | string | PIX key to be deleted. | 200 |
## Response
STATUS 200
Response Body
```json
{}
```
STATUS 4XX
Response Body: Error
```json
{
"title": "titulo",
"description": "description in English",
"translation": "description in portuguese",
"code": "codigo",
"extra_fields": {}
}
```
| HTTP Code | QI Code
`code` | Title
`title` | Description (eng)
`Description` | Description (ptbr)
`translation` |
|-------------|----------------------|-----------------------|-----------------------------------------------------------------|--------------------------------------------------------------|
| 403 | PIX000080 | Not enough permission | The selected agent is not an Pix Indirect Participant | O agente selecionado não é um Participante Indireto do Pix |
| 404 | PIX000082 | Alias not found | Alias \{alias_key\} not found | Alias \{alias_key\} não encontrado |
| 400 | PIX000087 | Pix key type | Only pix key type random_key is currently implemented for alias | Random_key é o único tipo atualmente implementado para alias |
| 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\} |
---
# Introduction to PIX key management for an Alias
URL: /en/documentation/pix_indireto/chaves_pix/introducao_chaves_pix
After the Indirect Participant has registered an Alias for their account opened at QI Tech, they can register a PIX key for this Alias which, in practice, represents the Indirect Participant's client.
Since the Indirect Participant has already registered the Alias, they simply need to indicate to QI Tech that they wish to open a PIX key for a specific Alias, which has a unique key that is provided when the Indirect Participant registers an Alias.
:::info Information
Everything described in this introduction section is also detailed in the following sections regarding how the Indirect Participant should handle it via API.
:::
---
# Pix Keys listing for an Alias
URL: /en/documentation/pix_indireto/chaves_pix/listar_chaves
## Request
ENDPOINT /account/ ACCOUNT_KEY /alias/ ALIAS_KEY /pix_key
METHOD GET
### Path Params
| Field | Type | Description | Characters |
|--------------|--------|----------------------|------------|
| `account_key`| string | Unique account key. | 36 |
| `alias_key` | string | Unique alias key. | 36 |
:::info Pix Key Types
The “pix_key” is of the type Random Key (UUID4), following this format:
Random Key: UUID4.
:::
### Query Params
| Field | Type | Description | Characters |
|---------------|---------|---------------------------------------|------------|
| `page_number` | integer | Current page being queried. | - |
| `page_size` | integer | Number of results per page. | - |
## Response
STATUS 200
Response Body: Key active
```json
{
"data": [
{
"pix_key": "ecdb1790-667f-42ab-b319-fbc838a04672",
"pix_key_type": "random_key",
"pix_key_status": "active",
"created_at": "2021-10-22T20:30:23.459Z"
},
{
"pix_key": "f5eb52c1-5247-4de3-9982-f4f0ee9edad4",
"pix_key_type": "random_key",
"pix_key_status": "active",
"created_at": "2021-12-06T21:16:12.123Z"
}
],
"pagination": {
"current_page": 1,
"next_page": null,
"rows_per_page": 10
}
}
```
### Response Body Params
| Field | Type | Description | Max. Characters |
|------------------|---------------|--------------------------------------------------------|-----------------|
| `pix_key` | string | PIX key. | 77 |
| `pix_key_type` | string | Type of the PIX key. Can be "random_key" | 10 |
| `pix_key_status` | string | Activation status of the PIX key. Can be "active", "inactive" or "pending" | 8 |
| `created_at` | datetime Zulu | Date of creation of the request. | 20 |
STATUS 4XX
Response Body: Error
```json
{
"title": "titulo",
"description": "description in English",
"translation": "description in portuguese",
"code": "codigo",
"extra_fields": {}
}
```
| HTTP Code | QI Code
`code` | Title
`title` | Description (eng)
`Description` | Description (ptbr)
`translation` |
|-------------|----------------------|--------------------------|-------------------------------------------------------|----------------------------------------------------------------|
| 403 | PIX000080 | Not enough permission | The selected agent is not an Pix Indirect Participant | O agente selecionado não é um Participante Indireto do Pix |
| 404 | PIX000082 | Alias not found | Alias \{alias_key\} not found | Alias \{alias_key\} não encontrado |
| 400 | PIX000088 | Page size too large | Requested page size above limit of \{max_page_size\} | Tamanho de página requerido acima do limite de \{max_page_size\} |
| 400 | PIX000089 | Invalid value for params | Page Size and Page Number must be integers | age Size e Page Number devem ser números inteiros |
---
# Cancel Refund Request
URL: /en/documentation/pix_indireto/devolucao/cancelar_devolucao
The Indirect Participant can cancel a refund request if necessary.
Only the Participant (Direct or Indirect) who created the refund request can cancel it.
To cancel, the status must be OPEN
:::danger IMPORTANT
The Central Bank of Brazil requires that, within a period of 1 day from the receipt of the Refund Request by the Indirect Participant, the Refund must be closed .
If there is a delay on the part of the Indirect Participant, QI Tech will close the Refund Request with the status of totally_accepted to ensure the institution is not penalized by the Central Bank of Brazil.
:::
## Request
ENDPOINT /pix/refund_request/ REFUND_REQUEST_KEY
METHOD PATCH
**Request Body**
```json
{
"refund_request_status": "cancelled",
"request_control_key": "e09aba97-0051-4c18-b645-1cb3c2581c34"
}
```
### Path Params
| Field | Type | Description | Characters |
|----------------------|--------|--------------------------|------------|
| `refund_request_key` * | string | UUID4 of the already created refund. | 36 |
### Body Params
| Field | Type | Description | Characters |
|---------------------------|--------|----------------------------------------------------------|------------|
| `refund_request_status` * | string | Status of the refund update. | 36 |
| `request_control_key` * | uuidv4 | UUID4 for querying about the made request. | 36 |
## Response
STATUS 200
**Response Body**
```json
{
"refund_request_key": "47633091-7d44-4d10-9d00-1f937104e537",
"pix_transfer_key": "2bcbfd65-8660-4cb0-8ae4-4c4b327b32be",
"end_to_end_id": "E73856642202407011350E8cnA3Ae7r3",
"requested_amount": 10,
"refund_request_status": "cancelled",
"refund_request_type": "operational_flaw",
"infraction_report_key": null,
"refund_request_details": "Foi identificada uma fraude na transação.",
"requesting_participant": "73856642",
"contested_participant": "99999999",
"analysis_result": null,
"analysis_details": null,
"reject_reason": null,
"refund_transfer_key": null,
"refunded_amount": 0.00,
"refund_request_direction": "outgoing",
"created_at": "2024-07-01T13:50:30Z"
}
```
### Body Params
| Field | Type | Description | Characters |
|-----------------------------|--------|---------------------------------------------------------------------------|------------|
| `pix_transfer_key`* | string | Unique identifier of the PIX transaction. | 36 |
| `refund_request_key`* | string | Unique identifier of the refund request. | 36 |
| `infraction_report_key`* | string | Unique identifier of the infraction related to the refund. Only when the type is FRAUD | 36 |
| `refund_request_type` | enum | Type of refund request. | **[Enumerators refund_request_type](#enumeradores-refund_request_type)** |
| `requested_amount`* | float | Refund amount | - |
| `refund_request_status`* | enum | Status. | **[Enumerators refund_request_status](#enumeradores-refund_request_status)** |
| `contested_participant`* | string | ISPB of the Credited Participant (Contested). | 8 |
| `requesting_participant`* | string | ISPB of the Debited Participant (Requesting, who is requesting the refund).| 8 |
| `refund_request_details`* | string | Details about the refund request. | - |
| `analysis_result`* | enum | Result of the refund closure analysis. | **[Enumerators analysis_result](#enumeradores-analysis_result)** |
| `analysis_details`* | string | Details of the refund closure analysis. | - |
| `reject_reason`* | string | Reason for rejecting the refund, if it is closed with REJECTED. | **[Enumerators reject_reason](#enumeradores-reject_reason)** |
| `refund_transfer_key`* | string | pix_transfer_key of the refund transaction, if it is closed with acceptance. | - |
| `refunded_amount`* | float | Amount refunded in the refund transaction. | - |
| `refund_request_direction`* | string | Direction of the refund request. | **[Enumerators refund_request_direction](#enumeradores-refund_request_direction)** |
| `created_at` * | string | Refund Request creation date | 24 |
### Enumerators refund_request_status
| Field | Description |
|-------------|-----------------------------------------------------------------------------|
| `open` | Refund Request was created and is open at BACEN. |
| `cancelled` | Refund Request is cancelled at BACEN |
| `closed` | Refund Request is closed at BACEN |
### Enumerators refund_request_type
| Field | Description |
|-------------------|-----------------------------------------------------------|
| `fraud` | Refund Request originating from fraud. |
| `operational_flaw`| Refund Request originating from an internal error. |
### Enumerators analysis_result
| Field | Description |
|--------------------|------------------------------------------------------------|
| `totally_accepted` | Refund Request was fully accepted. |
| `partially_accepted` | Refund Request was partially accepted. |
| `rejected` | Refund Request was rejected. |
### Enumerators reject_reason
| Field | Description |
|-----------------|--------------------------------------------------------------|
| `no_balance` | Account does not have sufficient balance for the refund. |
| `account_closure` | Account is closed, so the refund cannot be processed |
| `other` | Other reason |
### Enumerators refund_request_direction
| Field | Description |
|-------------|------------------------------------------------------------|
| `outgoing` | Participant is the originator of the refund request. |
| `incoming` | Participant is the target of the refund request. |
---
# Consult Return Request
URL: /en/documentation/pix_indireto/devolucao/consultar_devolucao
If the Indirect Participant wishes to query the information of a Refund Request, the route below allows it.
:::danger IMPORTANT
The Central Bank of Brazil requires that, within a period of 1 day from the receipt of the Refund Request by the Indirect Participant, the Refund must be closed .
If there is a delay on the part of the Indirect Participant, QI Tech will close the Refund Request with the status of totally_accepted to ensure the institution is not penalized by the Central Bank of Brazil.
:::
## Request
ENDPOINT /pix/refund_request/ REFUND_REQUEST_KEY
METHOD GET
### Path Params
| Field | Type | Description | Characters |
|----------------------|--------|-----------------------|------------|
| `refund_request_key` | string | UUID4 of the refund. | 36 |
## Response
STATUS 200
**Response Body**
```json
{
"refund_request_key": "47633091-7d44-4d10-9d00-1f937104e537",
"pix_transfer_key": "2bcbfd65-8660-4cb0-8ae4-4c4b327b32be",
"end_to_end_id": "E73856642202407011350E8cnA3Ae7r3",
"requested_amount": 10,
"refund_request_status": "closed",
"refund_request_type": "operational_flaw",
"infraction_report_key": null,
"refund_request_details": "Foi identificada uma fraude na transação.",
"requesting_participant": "73856642",
"contested_participant": "99999999",
"analysis_result": "rejected",
"analysis_details": null,
"reject_reason": "account_closure",
"refund_transfer_key": null,
"refunded_amount": 0.00,
"refund_request_direction": "outgoing",
"created_at": "2024-07-01T13:50:30Z",
"refund_events": [
{
"event_type": "open",
"event_details": "Solicitação de Devolução criada pelo participante indireto",
"created_at": "2024-07-01T13:50:30Z"
},
{
"event_type": "closed",
"event_details": "Requisição de devolução fechado pela outra instituição financeira, com status REJEITADO",
"created_at": "2024-07-01T14:02:55Z"
}
]
}
```
### Body Params
| Field | Type | Description | Characters |
|-----------------------------|--------|---------------------------------------------------------------------------|------------|
| `pix_transfer_key`* | string | Unique identifier of the PIX transaction. | 36 |
| `refund_request_key`* | string | Unique identifier of the refund request. | 36 |
| `infraction_report_key`* | string | Unique identifier of the infraction related to the refund. Only when the type is FRAUD | 36 |
| `refund_request_type` | enum | Type of refund request. | **[Enumerators refund_request_type](#enumeradores-refund_request_type)** |
| `requested_amount`* | float | Refund amount | - |
| `refund_request_status`* | enum | Status. | **[Enumerators refund_request_status](#enumeradores-refund_request_status)** |
| `contested_participant`* | string | ISPB of the Credited Participant (Contested). | 8 |
| `requesting_participant`* | string | ISPB of the Debited Participant (Requesting, who is requesting the refund). | 8 |
| `refund_request_details`* | string | Details about the refund request. | - |
| `analysis_result`* | enum | Result of the refund closure analysis. | **[Enumerators analysis_result](#enumeradores-analysis_result)** |
| `analysis_details`* | string | Details of the refund closure analysis. | - |
| `reject_reason`* | string | Reason for rejecting the refund, if it is closed with REJECTED. | **[Enumerators reject_reason](#enumeradores-reject_reason)** |
| `refund_transfer_key`* | string | pix_transfer_key of the refund transaction, if it is closed with acceptance. | - |
| `refunded_amount`* | float | Amount refunded in the refund transaction. | - |
| `refund_events`* | object | Object for refund request events. | **[Objects refund_events](#objects-refund-events)** |
| `refund_request_direction`* | string | Direction of the refund request. | **[Enumerators refund_request_direction](#enumeradores-refund_request_direction)** |
| `created_at` * | string | Refund Request creation date | 24 |
### Enumerators refund_request_status
| Field | Description |
|-------------|-----------------------------------------------------------------------------|
| `open` | Refund Request was created and is open at BACEN. |
| `cancelled` | Refund Request is cancelled at BACEN |
| `closed` | Refund Request is closed at BACEN |
### Enumerators refund_request_type
| Field | Description |
|-------------------|-----------------------------------------------------------|
| `fraud` | Refund Request originating from fraud. |
| `operational_flaw`| Refund Request originating from an internal error. |
### Enumerators analysis_result
| Field | Description |
|--------------------|------------------------------------------------------------|
| `totally_accepted` | Refund Request was fully accepted. |
| `partially_accepted` | Refund Request was partially accepted. |
| `rejected` | Refund Request was rejected. |
### Enumerators reject_reason
| Field | Description |
|-----------------|--------------------------------------------------------------|
| `no_balance` | Account does not have sufficient balance for the refund. |
| `account_closure` | Account is closed, so the refund cannot be processed |
| `other` | Other reason. |
### Enumerators refund_request_direction
| Field | Description |
|-------------|------------------------------------------------------------|
| `outgoing` | Participant is the originator of the refund request. |
| `incoming` | Participant is the target of the refund request. |
### Objects refund_events
| Field | Description |
|-------------------|-----------------------------------------------------------------------------------|
| `event_type` | Type of the refund event. **[Enumerators refund_request_status](#enumeradores-refund_request_status)** |
| `event_details` | Details about the event. |
| `created_at` | Event creation date. |
---
# Open Refund Request
URL: /en/documentation/pix_indireto/devolucao/criar_devolucao
The Refund Request is another functionality present in the MED, defined by BACEN.
The main objective is to facilitate the refund of a PIX transaction made. The Refund Request can be generated either by an operational error or by an infraction . In the latter case, there is an Infraction Report for a PIX transaction that is already closed and accepted .
:::caution **Attention**
To understand the Refund Request flow, it is necessary to know which ENDPOINTS the Indirect Participant who created the refund can use.
When the Indirect Participant creates a Refund Request, they can (if necessary) cancel the request if it was generated improperly.
When the Indirect Participant receives a Refund Request, they must respond by informing the result of the request analysis.
Both cited flows will be described in the following sections.
It is noted that if the Indirect Participant opens the request, they are contesting another Participant. In the opposite flow, the Indirect Participant is the contested .
:::
:::danger IMPORTANT
The Central Bank of Brazil requires that, within a period of 1 day from the receipt of the Refund Request by the Indirect Participant, the Refund must be closed .
If there is a delay on the part of the Indirect Participant, QI Tech will close the Refund Request with the status of totally_accepted to ensure the institution is not penalized by the Central Bank of Brazil.
:::
## Request
ENDPOINT /pix/refund_request
METHOD POST
**Request Body**
```json
{
"pix_transfer_key": "a39mn71j-1dc7-4df0-8472-233624706e08",
"request_control_key":"df3ae07e-1dc7-4df0-8472-233624706e08",
"amount": 200.00,
"refund_request_details": "transação fraudada",
"refund_request_type": "fraud"
}
```
### Body Params
| Field | Type | Description | Characters |
|-------------------------|--------|-----------------------------------------------------------------------------------|------------|
| `pix_transfer_key` * | string | Unique identifier of the PIX transaction. | 36 |
| `request_control_key` * | uuidv4 | UUID4 for querying about the made request. | 36 |
| `amount` | float | Refund amount. If not provided, the original transaction amount will be used. | 19 |
| `refund_request_details`| string | Details about the refund request to be created | Less or equal 2000 |
| `refund_request_type` * | enum | Can be (fraud/operational_flaw) | **[Enumerators refund_request_type](#enumeradores-refund_request_type)** |
### Enumerators refund_request_type
| Field | Type | Description |
|----------------------|--------|----------------------------------------------------------------------|
| **fraud** | enum | Refund request due to fraud |
| **operational_flaw** | enum | Refund request due to operational error |
## Response
STATUS
200
**Response Body**
```json
{
"refund_request_key": "47633091-7d44-4d10-9d00-1f937104e537",
"pix_transfer_key": "2bcbfd65-8660-4cb0-8ae4-4c4b327b32be",
"end_to_end_id": "E73856642202407011350E8cnA3Ae7r3",
"requested_amount": 200.00,
"refund_request_status": "open",
"refund_request_type": "operational_flaw",
"infraction_report_key": null,
"refund_request_details": "Foi identificada uma fraude na transação.",
"requesting_participant": "73856642",
"contested_participant": "99999999",
"analysis_result": null,
"analysis_details": null,
"reject_reason": null,
"refund_transfer_key": null,
"refunded_amount": 0.00,
"refund_request_direction": "outgoing",
"created_at": "2024-07-01T13:50:30Z"
}
```
:::info Information
If the "refund_request_type" field is "fraud", QI Tech will provide, in the response, the infraction_report_key that has already been closed and accepted.
:::
### Body Params
| Field | Type | Description | Characters |
|-----------------------------|--------|---------------------------------------------------------------------------|------------|
| `pix_transfer_key`* | string | Unique identifier of the PIX transaction. | 36 |
| `refund_request_key`* | string | Unique identifier of the refund request. | 36 |
| `infraction_report_key`* | string | Unique identifier of the infraction related to the refund. Only when the type is FRAUD | 36 |
| `refund_request_type` | enum | Type of refund request. | **[Enumerators refund_request_type](#enumeradores-refund_request_type)** |
| `requested_amount`* | float | Refund amount | - |
| `refund_request_status`* | enum | Status. | **[Enumerators refund_request_status](#enumeradores-refund_request_status)** |
| `contested_participant`* | string | ISPB of the Credited Participant (Contested). | 8 |
| `requesting_participant`* | string | ISPB of the Debited Participant (Requesting, who is requesting the refund). | 8 |
| `refund_request_details`* | string | Details about the refund request. | - |
| `analysis_result`* | enum | Result of the refund closure analysis. | **[Enumerators analysis_result](#enumeradores-analysis_result)** |
| `analysis_details`* | string | Details of the refund closure analysis. | - |
| `reject_reason`* | string | Reason for rejecting the refund, if it is closed with REJECTED. | **[Enumerators reject_reason](#enumeradores-reject_reason)** |
| `refund_transfer_key`* | string | pix_transfer_key of the refund transaction, if it is closed with acceptance. | - |
| `refunded_amount`* | float | Amount refunded in the refund transaction. | - |
| `refund_request_direction`* | string | Direction of the refund request. | **[Enumerators refund_request_direction](#enumeradores-refund_request_direction)** |
| `created_at` * | string | Refund Request creation date | 24 |
### Enumerators refund_request_status
| Field | Description |
|-------------|------------------------------------------------------------------|
| `open` | Refund Request was created and is open at BACEN.|
| `cancelled` | Refund Request is cancelled at BACEN |
| `closed` | Refund Request is closed at BACEN |
### Enumerators refund_request_type
| Field | Description |
|-------------------|-----------------------------------------------------------|
| `fraud` | Refund Request originating from fraud. |
| `operational_flaw`| Refund Request originating from an internal error. |
### Enumerators analysis_result
| Field | Description |
|--------------------|------------------------------------------------------------------|
| `totally_accepted` | Refund Request was fully accepted. |
| `partially_accepted` | Refund Request was partially accepted. |
| `rejected` | Refund Request was rejected. |
### Enumerators reject_reason
| Field | Description |
|-----------------|--------------------------------------------------------------|
| `no_balance` | Account does not have sufficient balance for the refund. |
| `account_closure` | Account is closed, so the refund cannot be processed |
| `other` | Other reason. |
### Enumerators refund_request_direction
| Field | Description |
|-------------|------------------------------------------------------------|
| `outgoing` | Participant is the originator of the refund request. |
| `incoming` | Participant is the target of the refund request. |
---
# Close Refund Request
URL: /en/documentation/pix_indireto/devolucao/fechar_devolucao
The Indirect Participant can close a refund request if the Participant is the Contested Participant.
To close the request, the status must be OPEN .
:::danger IMPORTANT
The Central Bank of Brazil requires that, within a period of 1 day from the receipt of the Refund Request by the Indirect Participant, the Refund must be closed .
If there is a delay on the part of the Indirect Participant, QI Tech will close the Refund Request with the status of totally_accepted to ensure the institution is not penalized by the Central Bank of Brazil.
:::
## Request
ENDPOINT /pix/refund_request/ REFUND_REQUEST_KEY
METHOD PATCH
**Request Body**
```json
{
"request_control_key":"xpjae07e-1dc7-4df0-8472-233624706e08",
"refund_request_status": "closed",
"analysis_result": "totally_accepted",
"analysis_details": "Valor bloqueado. Para mais informações, contatar central antifraude em 11 3000-45012, informando ID 0000.",
"refund_transfer_key": "cdcf0d25-08a1-46e3-902a-6d7ca75e6c48"
}
```
### Path Params
| Field | Type | Description | Characters |
|----------------------|--------|----------------------------------|------------|
| `refund_request_key` *| string | UUID4 of the already created refund. | 36 |
### Body Params
| Field | Type | Description | Characters |
|------------------------|--------|----------------------------------|------------|
| `request_control_key` * | uuidv4 | UUID4 for querying about the made request. | 36 |
| `request_request_status` * | enum | Status | **[Enumerators refund_request_status](#enumeradores-refund_request_status)** |
| `analysis_result` * | enum | Result of the analysis | **[Enumerators analysis_result](#enumeradores-analysis_result)** |
| `analysis_details` | string | Comment on the analysis | Less or 2000 |
| `refund_transfer_key` | string | UUID4 of the refund transaction sent via the "reversal" route. Should be used when the "analysis_result" is acceptance. | 36 |
| `reject_reason` | enum | Reason for rejecting the refund. Should be used when the 'analysis_result' is 'rejected'. | **[Enumerators reject_reason](#enumeradores-reject_reason)** |
## Response
STATUS 200
**Response Body - Rejected**
```json
{
"refund_request_key": "2e42116f-4bdb-4f07-931f-c4dc7a78ed99",
"pix_transfer_key": "d5856a5f-378f-43ed-818b-df33b9fae703",
"end_to_end_id": "E60701190202406281828JCBxFsqssCf",
"requested_amount": 10,
"refund_request_status": "closed",
"refund_request_type": "operational_flaw",
"infraction_report_key": null,
"refund_request_details": "Foi identificada uma fraude na transação.",
"requesting_participant": "99999999",
"contested_participant": "73856642",
"analysis_result": "rejected",
"analysis_details": "Conta sem saldo.",
"reject_reason": "no_balance",
"refund_transfer_key": null,
"refunded_amount": 0.00,
"refund_request_direction": "incoming",
"created_at": "2024-07-01T15:46:18Z"
}
```
**Response Body - Agreed**
```json
{
"refund_request_key": "2e42116f-4bdb-4f07-931f-c4dc7a78ed99",
"pix_transfer_key": "d5856a5f-378f-43ed-818b-df33b9fae703",
"end_to_end_id": "E60701190202406281828JCBxFsqssCf",
"requested_amount": 10,
"refund_request_status": "closed",
"refund_request_type": "operational_flaw",
"infraction_report_key": null,
"refund_request_details": "Foi identificada uma fraude na transação.",
"requesting_participant": "99999999",
"contested_participant": "73856642",
"analysis_result": "totally_accepted",
"analysis_details": "Valor devolvido.",
"reject_reason": null,
"refund_transfer_key": "ab1189d8-5a87-4e5b-b49c-d05776bd8efe",
"refunded_amount": 10.00,
"refund_request_direction": "incoming",
"created_at": "2024-07-01T15:46:18Z"
}
```
### Body Params
| Field | Type | Description | Characters |
|-----------------------------|--------|---------------------------------------------------------------------------|------------|
| `pix_transfer_key`* | string | Unique identifier of the PIX transaction. | 36 |
| `refund_request_key`* | string | Unique identifier of the refund request. | 36 |
| `infraction_report_key`* | string | Unique identifier of the infraction related to the refund. Only when the type is FRAUD | 36 |
| `refund_request_type` | enum | Type of refund request. | **[Enumerators refund_request_type](#enumeradores-refund_request_type)** |
| `requested_amount`* | float | Refund amount | - |
| `refund_request_status`* | enum | Status. | **[Enumerators refund_request_status](#enumeradores-refund_request_status)** |
| `contested_participant`* | string | ISPB of the Credited Participant (Contested). | 8 |
| `requesting_participant`* | string | ISPB of the Debited Participant (Requesting, who is requesting the refund).| 8 |
| `refund_request_details`* | string | Details about the refund request. | - |
| `analysis_result`* | enum | Result of the refund closure analysis. | **[Enumerators analysis_result](#enumeradores-analysis_result)** |
| `analysis_details`* | string | Details of the refund closure analysis. | - |
| `reject_reason`* | string | Reason for rejecting the refund, if it is closed with REJECTED. | **[Enumerators reject_reason](#enumeradores-reject_reason)** |
| `refund_transfer_key`* | string | pix_transfer_key of the refund transaction, if it is closed with acceptance. | - |
| `refunded_amount`* | float | Amount refunded in the refund transaction. | - |
| `refund_request_direction`* | string | Direction of the refund request. | **[Enumerators refund_request_direction](#enumeradores-refund_request_direction)** |
| `created_at` * | string | Refund Request creation date | 24 |
### Enumerators refund_request_status
| Field | Description |
|-------------|-----------------------------------------------------------------------------|
| `open` | Refund Request was created and is open at BACEN. |
| `cancelled` | Refund Request is cancelled at BACEN |
| `closed` | Refund Request is closed at BACEN |
### Enumerators refund_request_type
| Field | Description |
|-------------------|-----------------------------------------------------------|
| `fraud` | Refund Request originating from fraud. |
| `operational_flaw`| Refund Request originating from an internal error. |
### Enumerators analysis_result
| Field | Description |
|--------------------|------------------------------------------------------------|
| `totally_accepted` | Refund Request was fully accepted. |
| `partially_accepted` | Refund Request was partially accepted. |
| `rejected` | Refund Request was rejected. |
### Enumerators reject_reason
| Field | Description |
|-----------------|--------------------------------------------------------------|
| `no_balance` | Account does not have sufficient balance for the refund. |
| `account_closure` | Account is closed, so the refund cannot be processed |
| `other` | Other reason |
### Enumerators refund_request_direction
| Field | Description |
|-------------|------------------------------------------------------------|
| `outgoing` | Participant is the originator of the refund request. |
| `incoming` | Participant is the target of the refund request. |
---
# List Refund Requests
URL: /en/documentation/pix_indireto/devolucao/listar_solicitacoes
If the Indirect Participant requests a listing of Refund Requests, they can do so through the route below.
:::danger IMPORTANT
The Central Bank of Brazil requires that, within a period of 1 day from the receipt of the Refund Request by the Indirect Participant, the Refund must be closed .
If there is a delay on the part of the Indirect Participant, QI Tech will close the Refund Request with the status of totally_accepted to ensure the institution is not penalized by the Central Bank of Brazil.
:::
## Request
ENDPOINT /pix/refund_requests
METHOD GET
### Query Params
| Field | Type | Description | Characters |
|-------------------------|---------|-----------------------------------|------------|
| `refund_request_status` | enum | Status of the Infraction Report. | **[Enumerators refund_request_status](#enumeradores-refund_request_status)** |
| `refund_request_type` | enum | Type of the Infraction Report. | **[Enumerators refund_request_type](#enumeradores-refund_request_type)** |
| `initial_date` | string | Start search date. | **[Date format](#formato-de-data)** |
| `final_date` | string | End search date. | **[Date format](#formato-de-data)** |
| `page_number` | integer | Current page being queried. | - |
| `page_size` | integer | Number of results per page. | - |
### Enumerators refund_request_status
| Field | Type | Description | Characters |
|-------------|--------|-----------------------------------------------------------------------------|------------|
| `open` | string | Refund Request was created and is open at BACEN. | 4 |
| `cancelled` | string | Refund Request is cancelled at BACEN. | 9 |
| `closed` | string | Refund Request is closed at BACEN. | 6 |
### Enumerators refund_request_type
| Field | Type | Description | Characters |
|-------------------|--------|-----------------------------------------------------------|------------|
| `fraud` | string | Refund Request originating from fraud. | 5 |
| `operational_flaw`| string | Refund Request originating from an internal error. | 16 |
### Date format
| Field | Type | Description | Characters |
|--------------|--------|--------------------------------------------------------------------------|------------|
| `initial_date` | string | Start search date, in the format "%Y-%m-%d". Example: "2023-10-09". | 10 |
| `final_date` | string | End search date, in the format "%Y-%m-%d". Example: "2023-10-11". | 10 |
## Response
STATUS 200
**Response Body**
```json
{
"data": [
{
"refund_request_key": "817c9331-fe1d-4178-aff2-8bed87ce3099",
"pix_transfer_key": "029efb4e-ad3b-4ba5-a73c-c724f0d9c02b",
"end_to_end_id": "E73856642202406282112pEBgwN7kkqD",
"requested_amount": 10,
"refund_request_status": "cancelled",
"refund_request_type": "operational_flaw",
"infraction_report_key": null,
"refund_request_details": "Foi identificada uma fraude na transação.",
"requesting_participant": "73856642",
"contested_participant": "99999999",
"analysis_result": null,
"analysis_details": null,
"reject_reason": null,
"refund_transfer_key": null,
"refunded_amount": 0.00,
"refund_request_direction": "outgoing",
"created_at": "2024-06-28T21:25:20Z",
"refund_events": [
{
"event_type": "open",
"event_details": "Solicitação de Devolução criada pelo participante indireto",
"created_at": "2024-06-28T21:25:20Z"
},
{
"event_type": "cancelled",
"event_details": "Solicitação de Devolução cancelada pelo participante indireto",
"created_at": "2024-06-28T21:27:19Z"
}
]
},
{
"refund_request_key": "5d174097-3d5c-41a2-a548-b24c41eecfb4",
"pix_transfer_key": "d5856a5f-378f-43ed-818b-df33b9fae703",
"end_to_end_id": "E60701190202406281828JCBxFsqssCf",
"requested_amount": 10,
"refund_request_status": "closed",
"refund_request_type": "operational_flaw",
"infraction_report_key": null,
"refund_request_details": "Foi identificada uma fraude na transação.",
"requesting_participant": "99999999",
"contested_participant": "73856642",
"analysis_result": "rejected",
"analysis_details": null,
"reject_reason": "no_balance",
"refund_transfer_key": null,
"refunded_amount": 0.00,
"refund_request_direction": "incoming",
"created_at": "2024-07-01T12:47:41Z",
"refund_events": [
{
"event_type": "open",
"event_details": "Solicitação de Devolução criada por outra instituição financeira",
"created_at": "2024-07-01T12:47:41Z"
}
]
}
]
}
```
### Body Params
| Field | Type | Description | Characters |
|-----------------------------|--------|---------------------------------------------------------------------------|------------|
| `pix_transfer_key`* | string | Unique identifier of the PIX transaction. | 36 |
| `refund_request_key`* | string | Unique identifier of the refund request. | 36 |
| `infraction_report_key`* | string | Unique identifier of the infraction related to the refund. Only when the type is FRAUD | 36 |
| `refund_request_type` | enum | Type of refund request. | **[Enumerators refund_request_type](#enumeradores-refund_request_type)** |
| `requested_amount`* | float | Refund amount | - |
| `refund_request_status`* | enum | Status. | **[Enumerators refund_request_status](#enumeradores-refund_request_status)** |
| `contested_participant`* | string | ISPB of the Credited Participant (Contested). | 8 |
| `requesting_participant`* | string | ISPB of the Debited Participant (Requesting, who is requesting the refund).| 8 |
| `refund_request_details`* | string | Details about the refund request. | - |
| `analysis_result`* | enum | Result of the refund closure analysis. | **[Enumerators analysis_result](#enumeradores-analysis_result)** |
| `analysis_details`* | string | Details of the refund closure analysis. | - |
| `reject_reason`* | string | Reason for rejecting the refund, if it is closed with REJECTED. | **[Enumerators reject_reason](#enumeradores-reject_reason)** |
| `refund_transfer_key`* | string | pix_transfer_key of the refund transaction, if it is closed with acceptance. | - |
| `refunded_amount`* | float | Amount refunded in the refund transaction. | - |
| `refund_events`* | object | Object for refund request events. | **[Objects refund_events](#objects-refund-events)** |
| `refund_request_direction`* | string | Direction of the refund request. | **[Enumerators refund_request_direction](#enumeradores-refund_request_direction)** |
| `created_at` * | string | Refund Request creation date | 24 |
### Enumerators refund_request_status
| Field | Description |
|-------------|------------------------------------------------------------------------------|
| `open` | Refund Request was created and is open at BACEN. |
| `cancelled` | Refund Request is cancelled at BACEN |
| `closed` | Refund Request is closed at BACEN |
### Enumerators refund_request_type
| Field | Description |
|-------------------|-----------------------------------------------------------|
| `fraud` | Refund Request originating from fraud. |
| `operational_flaw`| Refund Request originating from an internal error. |
### Enumerators analysis_result
| Field | Description |
|--------------------|----------------------------------------------------------|
| `totally_accepted` | Refund Request was fully accepted. |
| `partially_accepted` | Refund Request was partially accepted. |
| `rejected` | Refund Request was rejected. |
### Enumerators reject_reason
| Field | Description |
|-----------------|-------------------------------------------------------------|
| `no_balance` | Account does not have sufficient balance for the refund. |
| `account_closure` | Account is closed, so the refund cannot be processed |
| `other` | Other reason |
### Enumerators refund_request_direction
| Field | Description |
|-------------|-----------------------------------------------------------------|
| `outgoing` | Participant is the originator of the refund request. |
| `incoming` | Participant is the target of the refund request |
### Objects refund_events
| Field | Description |
|----------------|-----------------------------------------------------------------------------------|
| `event_type` | Type of the refund event change. **[Enumerators refund_request_status](#enumeradores-refund_request_status)** |
| `event_details`| Details about the event. |
| `created_at` | Event creation date. |
---
# Introduction to the Refund Flow
URL: /en/documentation/pix_indireto/devolucao/maquina_estados
## Introduction
The Central Bank of Brazil allows that if the Indirect Participant wishes to request back to the account a debited amount in a transaction made via PIX, they can open a Refund Request.
:::info
It is emphasized that only the debited Participant can open a Refund Request. Formally, the Participant who opens a Refund Request is called the requesting_participant .
:::
| Enumerator | Translation | Description|
|-------------|---------------|---|
| open | open | After processing the creation of the Refund Request, it remains open at BACEN.
| cancelled | cancelled | The cancellation of the Refund Request was processed by QI Tech and is cancelled at BACEN.
| closed | closed | The closure of the Refund Request was processed by QI Tech and is closed at BACEN.
## State Machine Control
Even though the flow is synchronous , it is necessary to know the possible statuses a Refund Request can have. Below, it is described what the Indirect Participant can expect after opening, cancelling, completing, and receiving a Refund Request.
### Participant Opens Refund Request
The Indirect Participant can request the opening of a refund in two ways:
Due to operational error (operational_flaw).
Due to an already closed and accepted infraction report (refund_request)
After opening, the refund status will be open
### Participant Cancels Refund Request
After the Participant has opened a Refund Request, it is possible to cancel it if requested.
The Indirect Participant will receive a response with the status of cancelled .
### Participant Receives Refund Request
Since other Participants can open a Refund Request, it is necessary that the other party involved in the flow can receive it in order to close it .
Unlike the Infraction Report, which has an intermediate status of acknowledged , the Indirect Participant will receive, via webhook , a request indicating that there is a Refund Request with the status open .
The difference is that, for this request, the Contested Participant is the Indirect Participant.
### Participant Closes Refund Request
After QI Tech, via webhook , informs the Indirect Participant that there is an available Refund Request, they can close the report.
When the Indirect Participant executes this flow, they will send the closure request to QI Tech and will receive a status of closed .
---
# Scenario Simulation
URL: /en/documentation/pix_indireto/devolucao/simulacao_de_cenarios
Step-by-step guide to simulate the completion of actions performed by external agents. These simulations include receiving and updating refund requests.
:::info Information
There is no payload response (response body) for these requests, only a response status of 201.
:::
## 1 - Simulating the Receipt of a Refund Request
Simulates the receipt of a refund request opened by another institution.
:::info IMPORTANT
It is essential to have a valid pix_transfer_key to send the request, regardless of the information from the other party of the transfer, as all information from the second participant will be replaced in the mock process.
:::
### Request
ENDPOINT /mock/pix/refund_request
METHOD POST
Request Body
:::info IMPORTANT
If the refund type is FRAUD, there must be a closed infraction report for the same pix_transfer_key.
:::
```json
{
"pix_transfer_key": "d5856a5f-378f-43ed-818b-df33b9fae703",
"refund_request_type": "fraud",
"refund_request_details": "Foi identificada uma fraude na transação.",
"refund_request_status": "open",
}
```
### Object Request Body
| Field | Type | Description | Max. Characters |
|----------------------|--------|---------------------------------------------------------------------------|-----------------|
| `pix_transfer_key` * | string | Unique identifier of the Pix transfer in the QI system (UUIDv4) | 36 |
| `refund_request_type` * | enum | Type of refund request. | **[Enumerators refund_request_type](#enumeradores-refund_request_type)** |
| `refund_request_status` * | string | Initial status of the refund request. "open" | 36 |
| `refund_request_details` | string | Details of the refund request | 2000 |
### Enumerators refund_request_type
| Field | Type | Description |
|-------------------|--------|-----------------------------------------------------------|
| `fraud` | string | Refund Request originating from fraud. | 5 |
| `operational_flaw`| string | Refund Request originating from an internal error. | 16 |
## 2 - Simulating the Update of a Refund Request
Simulates the status update of a refund request opened by the indirect participant.
The simulation options for updating a refund request are:
1 - Cancellation: Simulates the cancellation (cancel), made by a "target" participant, of a refund request previously opened by them.
2 - Closure: Simulates the closure (close), made by a "target" participant, of a refund request opened by the indirect participant. It is important that this report has already been acknowledged as open.
### Request
ENDPOINT /mock/pix/refund_request
METHOD PATCH
Request Body - Cancelled
:::info IMPORTANT
The Refund Request identified by the refund_request_key must have been previously created in the simulation of creating a refund request.
:::
```json
{
"refund_request_status": "cancelled",
"refund_request_key": "c3e5664f-04bb-4625-9ef3-c8555d210c71"
}
```
Request Body - Total Acceptance Closure
:::info IMPORTANT
The Refund Request identified by the refund_request_key must have been previously created by the indirect participant.
:::
:::info IMPORTANT
The refund transfer key must have been previously created by the refund receipt mock with a value EQUAL to the original transaction.
:::
```json
{
"refund_request_key": "42035bdd-0551-41c5-aaae-cb27d108160a",
"refund_request_status": "closed",
"analysis_result": "totally_accepted",
"analysis_details": "Teste",
"refund_transfer_key": "6f421127-892f-415f-8efc-4e20cf5d622d"
}
```
Request Body - Partial Acceptance Closure
:::info IMPORTANT
The Refund Request identified by the refund_request_key must have been previously created by the indirect participant. Additionally, the refunded amount must not be equal to or greater than the total amount of the original transaction.
:::
:::info IMPORTANT
The refund transfer key must have been previously created by the refund receipt mock with a value LESS than the original transaction.
:::
```json
{
"refund_request_key": "42035bdd-0551-41c5-aaae-cb27d108160a",
"refund_request_status": "closed",
"analysis_result": "partially_accepted",
"analysis_details": "Teste",
"refund_transfer_key": "6f421127-892f-415f-8efc-4e20cf5d622d"
}
```
Request Body - Rejection Closure
:::info IMPORTANT
The Refund Request identified by the refund_request_key must have been previously created by the indirect participant.
:::
```json
{
"refund_request_key": "47633091-7d44-4d10-9d00-1f937104e537",
"refund_request_status": "closed",
"analysis_result": "rejected",
"analysis_details": "Teste",
"reject_reason": "no_balance"
}
```
### Object Request Body
| Field | Type | Description | Max. Characters |
|-------------------------|--------|----------------------------------------------------------------------------------------------|-----------------|
| `refund_request_status` * | string | Initial status of the refund request. "cancelled", "closed" | 36 |
| `refund_request_key` * | string | Unique key of the refund request | 36 |
| `analysis_result` * | string | Result of the refund request analysis. "totally_accepted", "partially_accepted", "rejected" | 36 |
| `analysis_details` | string | Details of the refund request analysis | 2000 |
| `refund_transfer_key` | float | Identifier of the refund transfer, mandatory in case of acceptance | 20 |
| `reject_reason` | string | Reason for rejecting a refund (only if analysis_result is rejected). "no_balance", "account_closure", or "other" | 15 |
---
# Receive Refund Request
URL: /en/documentation/pix_indireto/devolucao/webhooks_devolucao
:::danger Attention!
QI Tech's webhooks should not be strictly mapped.
Additional fields may be included in the payloads of the webhooks returned by our APIs.
:::
Since another Participant may open a Refund Request targeting the Indirect Participant, QI Tech needs to notify the Indirect Participant about the Refund Request opened by the other Participant.
QI Tech will notify the Indirect Participant via webhook .
:::danger IMPORTANT
The Central Bank of Brazil requires that, within a period of 1 day from the receipt of the Refund Request by the Indirect Participant, the Refund must be closed .
If there is a delay on the part of the Indirect Participant, QI Tech will close the Refund Request with the status of totally_accepted to ensure the institution is not penalized by the Central Bank of Brazil.
:::
## Webhook for Receiving Refund Request (Operational Flaw)
**Request Body**
```json
{
"requesting_participant": "99999999",
"requested_amount": 10,
"refund_request_key": "2e42116f-4bdb-4f07-931f-c4dc7a78ed99",
"infraction_report_key": null,
"end_to_end_id": "E60701190202406281828JCBxFsqssCf",
"contested_participant": "73856642",
"refund_request_details": "Foi identificada uma fraude na transação.",
"pix_transfer_key": "d5856a5f-378f-43ed-818b-df33b9fae703",
"refund_request_type": "operational_flaw",
"refund_request_status": "open",
"refunded_amount": 0.00,
"analysis_result": null,
"analysis_details": null,
"refund_transfer_key": null,
"reject_reason": null,
"refund_request_direction": "incoming",
"created_at": "2024-07-01T15:46:18Z"
}
```
## Webhook for Receiving Refund Request (Fraud)
**Request Body**
```json
{
"requesting_participant": "99999999",
"requested_amount": 10,
"refund_request_key": "2e42116f-4bdb-4f07-931f-c4dc7a78ed99",
"infraction_report_key": "9b36f112-ee56-4b26-9ba5-fde7b68b2d3b",
"end_to_end_id": "E60701190202406281828JCBxFsqssCf",
"contested_participant": "73856642",
"refund_request_details": "Foi identificada uma fraude na transação.",
"pix_transfer_key": "d5856a5f-378f-43ed-818b-df33b9fae703",
"refund_request_type": "fraud",
"refund_request_status": "open",
"refunded_amount": 0.00,
"analysis_result": null,
"analysis_details": null,
"refund_transfer_key": null,
"reject_reason": null,
"refund_request_direction": "incoming",
"created_at": "2024-07-01T15:46:18Z"
}
```
---
# Consult an Alias Entity
URL: /en/documentation/pix_indireto/gerenciamento_de_alias/consultar_alias
Consult an Alias entity that is already registered to an existing account.
## Request
ENDPOINT /account/ ACCOUNT_KEY /alias/ ALIAS_KEY
METHOD GET
### Path Params
| Field | Type | Description | Characters |
|--------------|--------|----------------------|------------|
| `account_key`| uuidv4 | Unique account key. | 36 |
| `alias_key` | uuidv4 | Unique alias key. | 36 |
## Response
STATUS 200
**Response Body**
```json
{
"alias_key": "c446e513-131c-4741-bbc2-b7e6b6282899",
"ispb": "12345678",
"account_branch": "0001",
"account_number": "4968688",
"account_digit": "3",
"account_type": "checking_account",
"account_created_at": "2021-10-22T20:30:23.459Z",
"owner_person_type": "legal",
"owner_document_number": "89248771384257",
"owner_name": " Vinicius De Oliveira",
"owner_trading_name": "Pix Ltda",
"created_at": "2021-10-22T20:30:23.459Z"
}
```
### Response Body Params
| Field | Type | Description | Max. Characters |
|----------------------------|-----------|---------------------------------------------------------------|-----------------|
| `alias_key` | string | Unique alias key | 36 |
| `ispb` | string | ISPB of the financial institution linked to the Alias | 36 |
| `account_branch` | string | Branch, without the check digit | 4 |
| `account_number` | string | Account number, without the check digit | 20 |
| `account_digit` | string | Account check digit | 1 |
| `account_type` | enumerator| Account type | **[Enumerator account_type](#enumerator-account_type)** |
| `account_created_at` | string | Account creation date | 20 |
| `owner_document_number` | string | CPF or CNPJ number | 14 |
| `owner_name` | string | Account owner's name | 120 |
| `owner_trading_name` | string | Account owner's trade name (only for CNPJ) | 100 |
| `created_at` | string | Date the request was made | 20 |
### Enumerator account_type
| Enumerator | Description |
|------------------------|---------------------------|
| **checking_account** | Conta Corrente |
| **salary_account** | Conta Salário |
| **saving_account** | Conta Poupança |
| **payment_account** | Conta de Pagamentos |
STATUS 404
Response Body: Not Found
```json
{
"title": "Not Found",
"description": "Account not found for the given key \{account_key\}",
"translation": "A account_key \{account_key\} não foi encontrada",
"extra_fields": {},
"code": "ACC000006"
}
```
Response Body: Not found
```json
{
"title": "Not found",
"description": "Alias \{alias_key\} not found",
"translation": "Alias \{alias_key\} n\u00e3o encontrado",
"extra_fields": {},
"code": "ACC000181"
}
```
---
# Consult Alias by Request Control Key
URL: /en/documentation/pix_indireto/gerenciamento_de_alias/consultar_request_control_key
Return of the alias_key obtained in the creation of an Alias, using the request_control_key originally assigned to it in the body of the original request.
## Request
ENDPOINT /account/ ACCOUNT_KEY /alias
METHOD GET
### Path Params
| Field | Type | Description | Characters |
|---------------|--------|-----------------------|------------|
| `account_key` | uuidv4 | Unique account key. | 36 |
### Query Params
| Field | Type | Description | Characters |
|------------------------|--------|---------------------------------------------------------|------------|
| `request_control_key` *| uuidv4 | UUID4 for querying about the made request. | 36 |
## Response
STATUS 200
**Response Body**
```json
{
"alias_key": "c446e513-131c-4741-bbc2-b7e6b6282899",
"ispb": "12345678",
"account_branch": "0001",
"account_number": "4968688",
"account_digit": "3",
"account_type": "checking_account",
"account_created_at": "2021-10-22T20:30:23.459Z",
"owner_person_type": "legal",
"owner_document_number": "89248771384257",
"owner_name": " Vinicius De Oliveira",
"owner_trading_name": "Pix Ltda",
"created_at": "2021-10-22T20:30:23.459Z"
}
```
### Response Body Params
| Field | Type | Description | Max. Characters |
|----------------------------|-----------|---------------------------------------------------------------|-----------------|
| `alias_key` | string | Unique alias key | 36 |
| `ispb` | string | ISPB of the financial institution linked to the Alias | 36 |
| `account_branch` | string | Branch, without the check digit | 4 |
| `account_number` | string | Account number, without the check digit | 20 |
| `account_digit` | string | Account check digit | 1 |
| `account_type` | enumerator| Account type | **[Enumerator account_type](#enumerator-account_type)** |
| `account_created_at` | string | Account creation date | 20 |
| `owner_document_number` | string | CPF or CNPJ number | 14 |
| `owner_name` | string | Account owner's name | 120 |
| `owner_trading_name` | string | Account owner's trade name (only for CNPJ) | 100 |
| `created_at` | string | Date the request was made | 20 |
### Enumerator account_type
| Enumerator | Description |
|------------------------|-------------------|
| **checking_account** | Checking Account |
| **salary_account** | Salary Account |
| **saving_account** | Savings Account |
| **payment_account** | Payment Account |
STATUS 404
Response Body: Not Found
```json
{
"title": "Not Found",
"description": "Account not found for the given key \{account_key\}",
"translation": "A account_key \{account_key\} não foi encontrada",
"extra_fields": {},
"code": "ACC000006"
}
```
STATUS 404
Response Body: Request Control Key Not found
```json
{
"title": "Request Control Key Not found",
"description": "The informed request_control_key \{request_control_key\} has no original registered entry associated",
"translation": "A request_control_key informada \{request_control_key\} n\u00e3o possui entrada original associada",
"extra_fields": {},
"code": "ACC000186"
}
```
---
# Creating an Alias Entity
URL: /en/documentation/pix_indireto/gerenciamento_de_alias/criacao_de_alias
This is the flow responsible for creating Alias entities, linked to an existing account.
## Request
ENDPOINT /account/ ACCOUNT_KEY /alias
METHOD POST
**Request Body**
```json
{
"request_control_key":"5b4259a4-dc4a-489f-a050-3391e13d9850",
"account_branch": "0001",
"account_number": "4968698",
"account_digit": "3",
"account_type": "checking_account",
"account_created_at": "2022-09-24T19:46:43.001Z",
"owner_person_type": "legal",
"owner_document_number": "89248771384257",
"owner_name": "Vinicius De Oliveira",
"owner_trading_name": "Pix Ltda"
}
```
### Path Params
| Field | Type | Description | Characters |
|---------------|--------|-----------------------|------------|
| `account_key` | uuidv4 | Unique account key. | 36 |
### Request Body Params
| Field | Type | Description | Max. Characters |
|---------------------------|------------|----------------------------------------------------------------------------------|---------------------------------------------------------|
| `request_control_key` * | string | Unique request identification key used by the client in uuidv4 format | 36 |
| `account_branch` * | string | Branch, without the check digit | 4 |
| `account_number` * | string | Account number, without the check digit | 20 |
| `account_digit` * | string | Account check digit | 1 |
| `account_type`* | enumerator | Account type | **[account_type Enumerator](#account_type-enumerator)** |
| `account_created_at` * | string | Account creation date. Ex: "2022-09-24T19:46:43.001Z" | 20 |
| `owner_document_number` * | string | CPF or CNPJ number | 11(CPF) or 14(CNPJ) |
| `owner_person_type` * | string | Account owner type. Can be **legal** or **natural** | 7 |
| `owner_name` * | string | Account owner name | 120 |
| `owner_trading_name` | string | Account owner trading name (optional, and only for CNPJ) | 100 |
### account_type Enumerator
| Enumerator | Description |
|----------------------|---------------------|
| **checking_account** | Checking Account |
| **salary_account** | Salary Account |
| **saving_account** | Savings Account |
| **payment_account** | Payment Account |
## Response
STATUS 201 created
**Response Body**
```json
{
"alias_key": "e04f496b-47be-4762-a6e2-8f2b05b46780",
"created_at": "2022-09-24T19:46:43.001Z"
}
```
### Response Body Params
| Field | Type | Description | Max. Characters |
|--------------|---------------|----------------------------------|-----------------|
| `alias_key` | uuidv4 | Unique alias key | 36 |
| `created_at` | datetime Zulu | Request execution date | 20 |
STATUS 404
Response Body: Not Found
```json
{
"title": "Not Found",
"description": "Account not found for the given key \{account_key\}",
"translation": "A account_key \{account_key\} não foi encontrada",
"extra_fields": {},
"code": "ACC000006"
}
```
STATUS 400
Response Body: Repeted Request Control Key
```json
{
"title": "Repeated Request Control Key",
"description": "The request_control_key sent \{request_control_key\}, was already been used in other requisition",
"translation": "A request_control_key enviada \{request_control_key\}, já foi utilizada em outra requisição",
"extra_fields": {},
"code": "ACC000179"
}
```
Response Body: Invalid owner trading name
```json
{
"title": "Bad Request",
"description": "The owner_trading_name can only be sent by a legal person type",
"translation": "O owner_trading_name s\u00f3 pode ser utilizado por uma pessoa jur\u00eddica",
"extra_fields": {},
"code": "ACC000180"
}
```
---
# Deletion of an Alias Entity
URL: /en/documentation/pix_indireto/gerenciamento_de_alias/deletar_alias
Deletion of an Alias entity that is already registered to an existing account.
## Request
ENDPOINT /account/ ACCOUNT_KEY /alias/ ALIAS_KEY
METHOD DELETE
### Path Params
| Field | Type | Description | Characters |
|--------------|--------|----------------------|------------|
| `account_key`| uuidv4 | Unique account key. | 36 |
| `alias_key` | uuidv4 | Unique alias key. | 36 |
## Response
STATUS 200
**Response Body**
```json
{}
```
STATUS 404
Response Body: Not Found
```json
{
"data": "{\"title\": \"Not Found\", \"description\": \"Account not found for the given key \{account_key\}\", \"translation\": \"A account_key \{account_key\} não foi encontrada\", \"extra_fields\": {}, \"code\": \"ACC000006\"}",
"title": "Not Found",
"description": "Account not found for the given key \{account_key\}",
"translation": "A account_key \{account_key\} não foi encontrada",
"extra_fields": {},
"code": "ACC000006"
}
```
STATUS 404
Response Body: Not found
```json
{
"data": "{\"title\": \"Not found\", \"description\": \"Alias \{alias_key\} not found\", \"translation\": \"Alias \{alias_key\} n\u00e3o encontrado\", \"extra_fields\": {}, \"code\": \"ACC000181\"}",
"title": "Not found",
"description": "Alias \{alias_key\} not found",
"translation": "Alias \{alias_key\} n\u00e3o encontrado",
"extra_fields": {},
"code": "ACC000181"
}
```
STATUS 400
Response Body: Alias Key Don't Match with Account Key
```json
{
"data": "{\"title\": \"Alias Key Dont Match with Account Key\", \"description\": \"The alias_key \{alias_key\} Dont Match with the account_key \{account_key\}\", \"translation\": \"AA alias_key \{alias_key\} não combina com a account_key \{account_key\}\", \"extra_fields\": {}, \"code\": \"ACC000181\"}",
"title": "Alias Key Dont Match with Account Key",
"description": "The alias_key \{alias_key\} Dont Match with the account_key \{account_key\}",
"translation": "A alias_key \{alias_key\} não combina com a account_key \{account_key\}",
"extra_fields": {},
"code": "ACC000181"
}
```
---
# Introduction to Alias Entity
URL: /en/documentation/pix_indireto/gerenciamento_de_alias/introducao_alias
In order to maintain and align data regarding PIX key registration, as required by the Central Bank of Brazil, the Indirect Participant must register an Alias with QI Tech.
Every Alias is necessarily linked to an account that the Indirect Participant has with QI Tech.
:::info Information
Everything described in this introduction section is also detailed, regarding how the Indirect Participant should handle it via API, in the following sections.
:::
## What does the Alias entity represent?
The Alias entity is a 'mask' of the account data that the Indirect Participant's client has registered with the Indirect Participant itself. It should be noted that QI Tech will only perform formatting validations on the data sent by the Indirect Participant to us.
For example: CPF validation, CNPJ validation, maximum character length for a trade name, etc.
The data that QI Tech requests the Indirect Participant to send, regarding their client's account, is only what is necessary for PIX functionality purposes.
## Alias in practice
In practice, the Alias entity represents the Indirect Participant's client.
An example regarding the need to create an Alias would be:
Indirect Participant has an account with account_key a520b977-d6b2-4f27-bef5-29760ebfd6a7 registered with QI Tech,
Indirect Participant wants to link their own client to this account registered with QI Tech,
Indirect Participant sends the client's data (account number, branch, name, trade name, etc) to link to this account registered with QI Tech,
QITech links the Indirect Participant's client to the Indirect Participant's registered account.
Indirect Participant receives a unique identification key for the registered Alias.
This way, the Indirect Participant can request the creation of a PIX key and QI Tech will be able to effectively communicate with the Central Bank of Brazil with the necessary data for registration.
##### Representation of Alias usage with 1:N relationship:
```mermaid
graph LR;
Account_A-->Alias_A1;
Account_A-->Alias_A2;
Account_A-->Alias_A3;
Account_A-->Alias_A4;
```
##### Representation of Alias usage with 1:1 relationship:
```mermaid
graph LR;
Account_A-->Alias_A;
Account_B-->Alias_B;
Account_C-->Alias_C;
Account_D-->Alias_D;
```
---
# Alias Listing
URL: /en/documentation/pix_indireto/gerenciamento_de_alias/listagem_de_alias
Listing of the Aliases of an account
## Request
ENDPOINT /account/ ACCOUNT_KEY /alias
METHOD GET
### Path Params
| Field | Type | Description | Characters |
|--------------|--------|----------------------|------------|
| `account_key`| uuidv4 | Unique account key. | 36 |
### Query Params
| Field | Type | Description | Max Value |
|---------------|---------|---------------------------------------|-----------|
| `page_number` | integer | Current page being queried. | - |
| `page_size` | integer | Number of results per page. | 100 |
## Response
STATUS 200
**Response Body**
```json
{
"data": [
{
"alias_key": "a446e513-131c-4741-bbc2-b7e6b6282899",
"ispb": "12345678",
"account_type": "checking_account",
"account_branch": "0001",
"account_number": "4968688",
"account_digit": "3",
"account_created_at": "2021-10-22T20:30:23.459Z",
"owner_person_type": "legal",
"owner_document_number": "89248771384257",
"owner_name": " Vinicius De Oliveira",
"owner_trading_name": "Pix Ltda",
"created_at": "2021-10-22T20:30:23.459Z"
},
{
"alias_key": "c246a573-131c-4741-bbc2-b7e6b6282424",
"ispb": "12345678",
"account_type": "checking_account",
"account_branch": "0001",
"account_number": "2987685",
"account_digit": "1",
"account_created_at": "2021-10-22T20:30:23.459Z",
"owner_person_type": "legal",
"owner_document_number": "23448771384689",
"owner_name": " Roberto Moraes",
"owner_trading_name": "Pix Ltda",
"created_at": "2021-10-22T20:30:23.459Z"
}
],
"pagination": {
"current_page": 1,
"next_page": null,
"rows_per_page": 10
}
}
```
### Response Body Params
| Field | Type | Description | Max. Characters |
|----------------------------|-----------|---------------------------------------------------------------|-----------------|
| `alias_key` | string | Unique alias key | 36 |
| `ispb` | string | ISPB of the financial institution linked to the Alias | 36 |
| `account_branch` | string | Branch, without the check digit | 4 |
| `account_number` | string | Account number, without the check digit | 20 |
| `account_digit` | string | Account check digit | 1 |
| `account_type` | enumerator| Account type | **[Enumerator account_type](#enumerator-account_type)** |
| `account_created_at` | string | Account creation date | 20 |
| `owner_document_number` | string | CPF or CNPJ number | 14 |
| `owner_name` | string | Account owner's name | 120 |
| `owner_trading_name` | string | Account owner's trade name (only for CNPJ) | 100 |
| `created_at` | string | Date the request was made | 20 |
### Enumerator account_type
| Enumerator | Description |
|------------------------|---------------------------|
| **checking_account** | Checking Account |
| **salary_account** | Salary Account |
| **saving_account** | Savings Account |
| **payment_account** | Payment Account |
STATUS 404
Response Body: Not Found
```json
{
"title": "Not Found",
"description": "Account not found for the given key \{account_key\}",
"translation": "A account_key \{account_key\} não foi encontrada",
"extra_fields": {},
"code": "ACC000006"
}
```
STATUS 400
Response Body: Wrong Pagination Query Parameter Set
```json
{
"title": "Wrong Pagination Query Parameter Set",
"description": "If page_number was informed, the page_size should also be informed",
"translation": "Se o page_number foi informado, o page_size deve ser informado tambem",
"extra_fields": {},
"code": "ACC000183"
}
```
STATUS 400
Response Body: Wrong Pagination Query Parameter Format
```json
{
"title": "Wrong Pagination Query Parameter Format",
"description": "The page_number and page_formar should be formatad as an integer",
"translation": "O page_number e o page_size devem ter formato de integer",
"extra_fields": {},
"code": "ACC000184"
}
```
---
# Introduction
URL: /en/documentation/pix_indireto/introducao
At QI Tech, we are proud to expand our services through the PIX Indirect service. We recognize the challenges some institutions may face when trying to integrate with PIX, and we are committed to making this a smooth and accessible reality for everyone.
As a direct participant of PIX, operating with efficiency and security, we have implemented a high-tech solution that allows banks, payment institutions, and fintechs of all sizes to become indirect participants, ensuring everyone enjoys the benefits of PIX without the burden of operational and technical costs.
Our PIX Indirect service provides simplified integration and hassle-free operation, with reduced costs and regulatory compliance. Furthermore, you won't have to worry about the complex technical processes; we will handle everything, allowing you to focus on what matters most - your customers.
With QI Tech, you will be equipped to provide your customers with a fast, secure, and always-available payment experience, 24/7. Our goal is to facilitate your transition to PIX, enabling you to offer the best customer service.
The following sections describe the functionalities that an Indirect Participant can perform, via API, within the scope of PIX Indirect.
---
# Mocked Pix keys in the sandbox environment
URL: /en/documentation/pix_indireto/movimentacoes/chaves_pix_mockadas
## 104 - CAIXA ECONOMICA FEDERAL
| Chave Pix | Tipo | Nome do titular | Documento do titular | Número da conta | Agencia da conta | ISPB |
|---|---|---|---|---|---|---|
| +5568970000000 | phone_number | Vivo Test | 65322181032 | 21837-5 | 4458 | 360305 |
| d6e2d611-6c68-4f84-9be5-962ad2f2bcb6 | random_key | Vivo Test | 61295118092 | 100091086-1 | 465 | 360305 |
| 61295118092 | cpf | Vivo Test | 61295118092 | 1300005670-8 | 4289 | 360305 |
| pix03@pix03.com | email | Vivo Test | 96969879003 | 363214578-8 | 8615 | 360305 |
| +5568911106520 | phone_number | Vivo Test | 66702118805 | 100071086-1 | 465 | 360305 |
| 5e6ce02a-e0da-4d56-73b8-84f118b4f371 | random_key | Vivo Test | 52720072800 | 100061086-1 | 465 | 360305 |
| 52720072800 | cpf | Vivo Test | 52720072800 | 100071076-1 | 465 | 360305 |
| pix10@pix10.com | email | Vivo Test | 24182533410 | 100071066-1 | 465 | 360305 |
| pix33@pix33.com | email | Vivo Test | 56151446887 | 96764-6 | 919 | 360305 |
| 88253032978 | cpf | Vivo Test | 88253032978 | 96764-6 | 919 | 360305 |
## 341 - ITAÚ UNIBANCO S.A.
| Chave Pix | Tipo | Nome do titular | Documento do titular | Número da conta | Agencia da conta | ISPB |
|---|---|---|---|---|---|---|
| 22156083070 | cpf | Vivo Test | 22156083070 | 19413-2 | 8534 | 60701190 |
| 96969879003 | cpf | Vivo Test | 96969879003 | 22110-1 | 8615 | 60701190 |
| 5e6ce06a-e0da-4d56-93b8-84f118b4f371 | random_key | Vivo Test | 43135154025 | 57980-4 | 5067 | 60701190 |
| pix11@pix11.com | email | Vivo Test | 66702118805 | 86091-8 | 3101 | 60701190 |
| 24182533410 | cpf | Vivo Test | 24182533410 | 20467-1 | 5807 | 60701190 |
| pix07@pix07.com | email | Vivo Test | 11646288874 | 33087-6 | 8872 | 60701190 |
## 237 - BCO BRADESCO S.A.
| Chave Pix | Tipo | Nome do titular | Documento do titular | Número da conta | Agencia da conta | ISPB |
|---|---|---|----------------------|-----------------------|---|---|
| 65322181032 | cpf | Vivo Test | 65322181032 | 1017372-2 | 1 | 60746948 |
| b9380607-dac6-4e17-8ca7-eb761e3aa1dd | random_key | José Alves | 24080025327 | 0001000000000022279-9 | 1 | 08744817 |
| b9380607-dac6-4e17-8ca7-eb761e3aa1dd | random_key | José Alves | 24080025327 | 0003000000000000288-9 | 1 | 08744817 |
| b9380607-dac6-4e17-8ca7-eb761e3aa1dd | random_key | José Alves | 24080025327 | 0013000000000013609-9 | 1 | 08744817 |
| b9380607-dac6-4e17-8ca7-eb761e3aa1dd | random_key | José Alves | 24080025327 | 1288000000884535174-9 | 1 | 08744817 |
| b9380607-dac6-4e17-8ca7-eb761e3aa1dd | random_key | José Alves | 24080025327 | 3701000000593070593-9 | 1 | 08744817 |
| pix01@pix01.com | email | Vivo Test | 65322181032 | 1017372-2 | 1 | 60746948 |
| pix01@pix01.com | email | Vivo Test | 65322181032 | 1925255-8 | 3952 | 60746948 |
| pix12@pix12.com | email | Vivo Test | 11085087824 | 1071659-4 | 427 | 60746948 |
| 5e6ce08a-e0da-4d56-93b8-84f118b4f371 | random_key | Vivo Test | 66702118805 | 1751795-3 | 6162 | 60746948 |
| +5568911137576 | phone_number | Vivo Test | 82104056080 | 1587784-7 | 1340 | 60746948 |
## 33 - BCO SANTANDER (BRASIL) S.A.
| Chave Pix | Tipo | Nome do titular | Documento do titular | Número da conta | Agencia da conta | ISPB |
|---|---|---|---|---|---|---|
| 5e6ce05a-e0da-4d56-93b8-84f118b4f371 | random_key | Vivo Test | 42759960030 | 9206744-2 | 4187 | 90400888 |
| 34175131205 | cpf | Vivo Test | 34175131205 | 9206744-2 | 4187 | 90400888 |
| 5e6ce05a-e0da-4d56-53b8-74f118b4f371 | random_key | Vivo Test | 11646288874 | 9206744-2 | 4187 | 90400888 |
| 82104056080 | cpf | Vivo Test | 82104056080 | 2850903-2 | 214 | 90400888 |
## 77 - BANCO INTER
ISPB: 416968
| Chave Pix | Tipo | Nome do titular | Documento do titular | Número da conta | Agencia da conta | ISPB |
|---|---|---|---|---|---|---|
| 22156083070 | cpf | Vivo Test | 22156083070 | 4810813-8 | 1 | 416968 |
| pix13@pix13.com | email | Vivo Test | 43135154025 | 4830813-8 | 1 | 416968 |
| 66702118805 | cpf | Vivo Test | 66702118805 | 4820813-8 | 1 | 416968 |
| 5e6ce05a-e0da-4d56-93b7-84f118b4f371 | random_key | Vivo Test | 24182533410 | 4850813-8 | 1 | 416968 |
| +5568911168384 | phone_number | Vivo Test | 17413005255 | 4850813-8 | 1 | 416968 |
| pix06@pix06.com | email | Vivo Test | 81035632691 | 4750813-8 | 1 | 416968 |
| pix31@pix31.com | email | Vivo Test | 55125236780 | 1768538-4 | 2960 | 416968 |
## 260 - NU PAGAMENTOS - IP
| Chave Pix | Tipo | Nome do titular | Documento do titular | Número da conta | Agencia da conta | ISPB |
|---|---|---|---|---|---|---|
| pix04@pix04.com | email | Vivo Test | 69017362073 | 81648459-8 | 1 | 18236120 |
| pix09@pix09.com | email | Vivo Test | 34175131205 | 81538459-8 | 1 | 18236120 |
| 5e6ce01a-e0da-4d56-93b8-44f118b4f371 | random_key | Vivo Test | 17413005255 | 81548459-8 | 1 | 18236120 |
| +5568911186420 | phone_number | Vivo Test | 81035632691 | 81538459-8 | 1 | 18236120 |
| pix32@pix32.com | email | Vivo Test | 56151446887 | 293201-6 | 2811 | 18236120 |
## 336 - BCO C6 S.A.
| Chave Pix | Tipo | Nome do titular | Documento do titular | Número da conta | Agencia da conta | ISPB |
|---|---|---|---|---|---|---|
| dbbf965d-677c-49ff-b9da-5131da1505f3 | random_key | Vivo Test | 65322181032 | 1019902-6 | 1 | 31872495 |
| 5e6ce07a-e0da-4d56-93b8-84f118b4f371 | random_key | Vivo Test | 11085087824 | 1018902-6 | 1 | 31872495 |
| 11646288874 | cpf | Vivo Test | 11646288874 | 1017902-6 | 1 | 31872495 |
## 403 - CORA SCD S.A.
| Chave Pix | Tipo | Nome do titular | Documento do titular | Número da conta | Agencia da conta | ISPB |
|---|---|---|---|---|---|---|
| 39284100000000 | cnpj | Parcela Mais | 39284100000000 | 1708315-8 | 1 | 37880206 |
## 422 - BCO SAFRA S.A.
| Chave Pix | Tipo | Nome do titular | Documento do titular | Número da conta | Agencia da conta | ISPB |
|---|---|---|---|---|---|---|
| pix02@pix02.com | email | Vivo Test | 69017362073 | 364522-5 | 284 | 58160789 |
| pix08@pix08.com | email | Vivo Test | 34175131205 | 264522-5 | 284 | 58160789 |
| +5568911106070 | phone_number | Vivo Test | 11646288874 | 354522-5 | 284 | 58160789 |
| 53465252110 | cpf | Vivo Test | 53465252110 | 364422-5 | 284 | 58160789 |
| +5568911122488 | phone_number | Vivo Test | 10632271 | 1558321-5 | 907 | 58160789 |
## 655 - BCO VOTORANTIM S.A.
| Chave Pix | Tipo | Nome do titular | Documento do titular | Número da conta | Agencia da conta | ISPB |
|---|---|---|---|---|---|---|
| 5301321099 | cpf | Vivo Test | 5301321099 | 622660113-8 | 1111 | 59588111 |
## DOCK SOLUCOES EM MEIOS DE PAGAMENTO S A
| Chave Pix | Tipo | Nome do titular | Documento do titular | Número da conta | Agencia da conta | ISPB |
|---|---|---|---|---|---|---|
| +5568911165580 | phone_number | Vivo Test | 53465252110 | 622470112-8 | 1111 | 8744817 |
| 17413005255 | cpf | Vivo Test | 17413005255 | 622450112-8 | 1111 | 8744817 |
| 81035632691 | cpf | Vivo Test | 81035632691 | 622450113-8 | 1111 | 8744817 |
| 5e6ce05a-e0da-4d56-93b8-64f118b4f371 | random_key | Vivo Test | 81035632691 | 622650113-8 | 1111 | 8744817 |
## COMPANHIA GLOBAL DE SOLUCOES E SERVICOS DE PAGAMENTOS S.A.
| Chave Pix | Tipo | Nome do titular | Documento do titular | Número da conta | Agencia da conta | ISPB |
|---|---|---|---|---|---|---|
| 96755229091 | cpf | Teste sem Compe | 96755229091 | 1444301-8 | 1 | 32024691 |
---
# Pix Key Lookup
URL: /en/documentation/pix_indireto/movimentacoes/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 Pix Key Types
The “pix_key” can be a CPF, CNPJ, Email, Phone, or a Random Key (UUID), following these formats:
**CPF**: Integer with 11 digits.
**CNPJ**: Integer with 14 digits.
**Email**: Text containing at least one “@”.
**Phone**: Text containing the following values: “+55” + “Mobile DDD“ + “Complete Mobile Number with a minimum of 8 and a maximum of 9 digits”. E.g., “+5511987654321“.
**Random Key**: UUID4.
:::
### Request Query Params
| Field | Type | Description | Characters |
|--------------|--------|----------------------|------------|
| `alias_key` *| uuidv4 | Unique alias key. | 36 |
:::info Usage of Query Tokens
To ensure the correct person is charged for the PIX key query token, it is mandatory to send the `alias_key`.
:::
## Response
STATUS 200
Response Body: Key active
```json
{
"account_branch": "0001",
"account_created_at": "2023-09-06T22:03:34.000Z",
"account_digit": "8",
"account_number": "2897775",
"account_type": "checking",
"bank_code": null,
"end_to_end_id": "E73856642202309201429bZKfklNlbwu",
"financial_institution": "BANCO INDIRETO PRUPRU",
"ispb": "32402502",
"owner_masked_document_number": "**.458.****/0001-**",
"owner_name": "Empresa teste 01",
"owner_person_type": "legal",
"owner_trading_name": null,
"pix_key": "0f723f66-b333-4187-be16-97fc37c86052"
}
```
| Field | Type | Description | Max. Characters |
|------------------------------|--------|--------------------------------------------------------|-----------------|
| `pix_key` | string | PIX key of the query | 4 |
| `account_branch` | string | Branch, without the check digit | 4 |
| `account_digit` | string | Account check digit | 1 |
| `account_number` | string | Account number, without the check digit | 20 |
| `account_type` | string | Definition of account type | 20 |
| `owner_person_type` | string | Type of account owner. Can be "legal" or "natural" | 7 |
| `owner_masked_document_number` | string | CPF or CNPJ number | 14 |
| `end_to_end_id` | string | Unit key of the PIX transaction | 32 |
| `owner_name` | string | Account owner's name | 120 |
| `owner_trading_name` | string | Account owner's trade name (only for CNPJ) | 100 |
| `ispb` | string | ISPB of the Participant holding the key | 8 |
| `bank_code` | string | COMPE code of the financial institution | 3 |
| `financial_institution` | string | Name of the financial institution holding the key | 100 |
| `account_created_at` | string | Account creation date | 20 |
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` |
|-------------|----------------------|----------------------------------|-------------------------------------------------------------------------------|----------------------------------------------------------------------------------|
| 400 | PIX000086 | Invalid Query Params Combination | Account_key and Alias_key are mutually exclusive query parameters. Choose one | Account_key e Alias_key são parâmetros mutualmente exclusivos. Escolha apenas um |
| 403 | PIX000080 | Not enough permission | The selected agent is not an Pix Indirect Participant | O agente selecionado não é um Participante Indireto do Pix |
| 404 | PIX000082 | Alias not found | Alias \{alias_key\} not found | Alias \{alias_key\} não encontrado |
| 404 | PIX000017 | Pix Key is Unregistered | Pix key \{pix_key\} is not currently used | A chave pix \{pix_key\} não está sendo utilizada |
| 400 | PIX000081 | Rate Limit Exceeded | Rate Limit Exceeded | Limite de requisições excedido |
---
# Consult Pix transaction
URL: /en/documentation/pix_indireto/movimentacoes/consultar_pix
## Request
ENDPOINT /account/ ACCOUNT_KEY /alias/ ALIAS_KEY /pix_transfer/ PIX_TRANSFER_KEY / PIX_TRANSFER_DIRECTION
METHOD GET
### Request Path Params
| Field | Type | Description |
|--------------------------|--------|--------------------------------------------------------------------------------------------------|
| `pix_transfer_direction` * | string | Filter to indicate if a transaction is incoming or outgoing. Values: **incoming** and **outgoing** |
| `account_key` * | string | Unique identification key for the QI account |
| `alias_key` * | string | Unique key for the Alias |
| `pix_transfer_key` * | string | Unique identification key for the Pix transfer |
:::caution Attention
Viewing a transfer will only be allowed if the requester has permissions on the outgoing alias of the transaction. Otherwise, a not found error will be returned.
:::
## Response
STATUS 201
Response Body: Transfer sent (outgoing)
```json
{
"request_control_key": "6e290347-330d-4b3a-8ebb-2ac217ad6eb3",
"pix_message": "Bom dia",
"pix_transfer_type": "manual",
"account_key": "fc6862c4-2b20-4057-8063-b8809866e494",
"alias_key": "c4332971-7cff-42eb-a117-7e6f0cd74db2",
"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": [
{
"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": "Bom dia",
"pix_transfer_type": "manual",
"account_key": "fc6862c4-2b20-4057-8063-b8809866e494",
"alias_key": "c4332971-7cff-42eb-a117-7e6f0cd74db2",
"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": "Bom dia",
"pix_transfer_type": "reversal",
"account_key": "fc6862c4-2b20-4057-8063-b8809866e494",
"alias_key": "c4332971-7cff-42eb-a117-7e6f0cd74db2",
"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",
"alias_key": "c4332971-7cff-42eb-a117-7e6f0cd74db2",
"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",
"alias_key": "c4332971-7cff-42eb-a117-7e6f0cd74db2",
"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",
"alias_key": "c4332971-7cff-42eb-a117-7e6f0cd74db2",
"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": "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` |
|-------------|----------------------|---------------------------------------------|---------------------------------------------------|-----------------------------------------------------------------------------|
| 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 |
---
# Pix Refund
URL: /en/documentation/pix_indireto/movimentacoes/devolucao_pix
A Pix refund can be made up to 90 days from its receipt.
## Request
ENDPOINT /account/ ACCOUNT_KEY /alias/ ALIAS_KEY /pix_transfer/ PIX_TRANSFER_KEY /reversal
METHOD POST
### Request Path Params
| Field | Type | Description | Characters |
|-------------------|--------|-------------------------------------------------------------------|------------|
| `account_key` | string | Unique account key (UUIDv4) | 36 |
| `alias_key` | string | Unique alias key (UUIDv4) | 36 |
| `pix_transfer_key`| string | Unique identification key of the Pix transfer in the QI system (UUIDv4) | 36 |
Request Body
```json
{
"request_control_key": "303393bf-8f2e-4ff0-b326-ee7ad612e8ca",
"reversal_amount": 147.00,
"reversal_reason": "client_request",
"reversal_message": "Mensagem Pix da Devolução"
}
```
### Request Body
| Field | Type | Description | Characters |
|------------------------|--------|--------------------------------------------------------|------------|
| `request_control_key` *| string | Uniqueness key for the request (UUIDv4) | 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** | If requested by the account owner |
| **reconciliation** | For reconciliation due to operational error |
## Response
### Response Body
| Field | Type | Description | Characters |
|------------------------|--------|---------------------------------------------------------|------------|
| `reversal_status` | string | Enumerator for the reversal transaction status. Can be 'pending', 'sent', or 'rejected' | 36 |
| `transfer_amount` | number | Refund transfer amount | 11 |
| `pix_transfer_key` | string | Key of the executed Pix transaction for the refund (UUIDv4) | 36 |
| `end_to_end_id` | string | Idempotency key of a Pix transaction within the SPI (Instant Payment System) | 32 |
| `request_control_key` | string | Unique identification key for the client's request (UUIDv4) | 36 |
| `created_at` | string | Date and time of the refund | --- |
STATUS 201 created
Response Body: Reversão Enviada
```json
{
"reversal_status": "sent",
"transfer_amount": 147.00,
"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"
}
```
STATUS 202
:::info Information
If a `pix_transfer_status` is returned in the **pending** state, the Pix request should not be retried.
This transfer will be reprocessed. It is necessary to check the transfer status through the pix transfer query.
:::
Response Body: Reversal pending
```json
{
"reversal_status": "pending",
"transfer_amount": 147.00,
"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"
}
```
STATUS 4XX
Response Body: Reversal 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": "E32402502202407112211Id9JbxoaiTf",
"pix_transfer_status": "rejected",
"created_at": "2021-10-22T20:30:23.459Z"
}
}
}
```
STATUS 400
:::info Information
In addition to the errors listed below, the Pix refund may encounter other errors established in [Pix Transaction](./transacao/transacao_pix_manual_sync).
:::
| HTTP Code | 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 |
---
# Introduction to PIX Transactions
URL: /en/documentation/pix_indireto/movimentacoes/introducao_movimentacoes
The Indirect Participant (Alias) client can request various functionalities related to PIX transactions. Among them are:
Manual PIX transaction
PIX transaction by key
PIX QR Code transaction
PIX reversal
### Pix Transfer Types (pix_transfer_type)
| Enumerator | Description |
|---------------------|---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|
| **manual** | Pix using destination account data. 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) |
| **reversal** | PIX reversal |
Among these functionalities, there is the type of transaction 'synchronicity' that an Indirect Participant can choose to use, according to their needs.
:::info Information
Everything described in this introduction section is also detailed, including how the Indirect Participant should handle it via API, in the following sections.
:::
## End to end ID
Every pix transaction has a unique identifier in the central bank. End to End ID is the end-to-end identifier of a pix transfer. It is used for rate-limiting control in the Central Bank.
```mermaid
sequenceDiagram
Participante Indireto->>+Banco Central: Consulta de Chave Pix
Banco Central-->>-Participante Indireto: Chave Pix + End to End ID da consulta
Token consumida do bucket
Participante Indireto->>+Banco Central: Transferência com End to End ID
Banco Central-->>-Participante Indireto: Sucesso na transação com chave pix
Token devolvido ao bucket
```
Each individual or legal entity registration has a bucket with the Central Bank. PIX key query requests consume tokens from this bucket, which are recovered when making a pix transaction linked to a query. The link between a pix key query and a transaction is made through the End to End ID.
## Transaction Synchronicity
The Indirect Participant can choose to perform a PIX transaction synchronously or asynchronously. In both modes, the PIX transaction will be executed within the time established by the Central Bank of Brazil.
:::info Information
Our team will configure the synchronicity regime to be used as agreed with the client.
:::
:::info Information
The endpoints, methods, payloads and other request components are identical for the synchronous and asynchronous regime. The difference would only be that for the asynchronous regime, the response will always be a `pix_transfer` with **pending** status if it has been approved in the initial validations. Subsequently a webhook will be sent informing the final status of the transaction (**sent** or **rejected**).
:::
## Transaction Retry
Due to possible delays in the Central Bank of Brazil's messaging system regarding PIX transactions, QITech has a retry mechanism for PIX transactions, both for the synchronous and asynchronous model.
If this scenario occurs, the Indirect Participant will receive an HTTP 202 status, indicating that the transaction was sent to QITech and is pending confirmation from the Central Bank of Brazil. Once this is retried, the Indirect Participant will be informed via webhook about the transaction completion.
---
# Scenario Simulation
URL: /en/documentation/pix_indireto/movimentacoes/simulacao
Step-by-step guide to simulate the completion of actions performed by external agents. These simulations include incoming transactions and refunds.
:::info Information
There is no payload response (response body) for these requests.
:::
## 1 - Simulating an Incoming PIX
### Request
ENDPOINT /mock/pix_transfer/incoming_pix_transfer
METHOD POST
Request Body
```json
{
"target_account_key": "fc6862c4-2b20-4057-8063-b8809866e494",
"target_alias_key": "c4332971-7cff-42eb-a117-7e6f0cd74db2",
"amount": 100.01
}
```
### Object Request Body
| Field | Type | Description | Max. Characters |
|----------------------|--------|---------------------------------------|-----------------|
| **target_account_key*** | string | Unique key of the destination account | 36 |
| **target_alias_key** | string | Unique key of the destination alias | 36 |
| **amount*** | number | Transaction amount | 6 |
## 2 - Simulation a QR Code Pix payment
### Request
ENDPOINT /mock/pix_transfer/incoming_pix_qrcode
METHOD POST
Request Body
```json
{
"target_alias_key": "\",
"amount": "\",
"receiver_conciliation_id": "\"
}
```
### Object Request Body
| Field | Type | Description | Max. Characters | Example | Note |
|------------------------------|---------|------------------------------------------|-----------------|---------------------------------------|-------------------------|
| **target_alias_key*** | string | Unique key of the destination alias | 36 | "41112f46-0034-4007-85687-5e592173db2"| |
| **amount*** | decimal | Transaction amount | 6 | 1000.00 | Maximum value of 100,000|
| **receiver_conciliation_id***| string | Reconciliation ID of the receiver of the QR code | 36 | 1000 | |
## 3 - Simulating a PIX Refund
Simulates the refund of an outgoing Pix transfer. The total value of the refunds must not exceed the value of the original transfer. To identify the target transaction, send the `end_to_end_id` of the original transfer.
### Request
ENDPOINT /mock/pix_transfer/reversal
METHOD POST
Request Body
```json
{
"end_to_end_id": "E35713491202309182110sSCNh25ooX2",
"amount": 100.00
}
```
### Object Request Body
| Field | Type | Description | Max. Characters |
|----------------------|--------|-----------------------------------------------|-----------------|
| **end_to_end_id*** | string | Unit key of the transaction to be refunded | 32 |
| **amount*** | number | Amount to be refunded | 6 |
## 4 - Simulating a Transaction in Pending Confirmation State
Pix transactions can enter the **pending_confirmation** status when there is a delay in receiving the Pix transaction response from the Central Bank. To simulate this scenario, make a transaction with the pix key `"target_pix_key": "0476f803-0129-430a-a66c-d2f0d7cf4aaa"` or, for **manual** pix transfers, use `"owner_document_number": "35586870002"` as the document number of the destination account owner.
To update the transaction status, make the request below with `transaction_status` set to **sent** to approve the transaction, or **rejected** to reject it.
### Request
ENDPOINT /mock/pix_transfer/pending_confirmation
METHOD POST
Request Body
```json
{
"end_to_end_id": "E32402502202308181802vSHbiqNCk9i",
"transaction_status": "rejected",
"status_reason_information": {
"error_description": "description",
"error_translation": "translation",
"error_short_description": "short_description"
},
"error_code": "test_error"
}
```
### Body Parameters
| Field | Type | Description | Max. Characters |
|-------------------------------|--------|----------------------------------------------------------------|-----------------|
| `end_to_end_id` * | string | Unit key of the PIX transaction | 36 |
| `transaction_status` * | enum | [Enumerator Transaction Status](#enumerator-transaction-status)|
| `status_reason_information` | object | [Object Status Reason Information](#object-status-reason-information) |
| `error_code` | string | Error code |
### Enumerator Transaction Status
| Enumerator | Description |
|------------|-------------|
| **sent** | Completed |
| **rejected** | Rejected |
### Object Status Reason Information
| Field | Type | Description | Max. Characters |
|-------------------------|--------|-------------------------------------------|-----------------|
| `error_description` | string | Description of the error in English | 100 |
| `error_translation` | string | Description of the error in Portuguese | 100 |
| `error_short_description` | string | Short description of the error in English | 100 |
## 5 - Simulating a Rejected Transaction
Pix transactions can enter the **rejected** status when there is an expected return of refusal from the Central Bank or the recipient PSP. To simulate this scenario, make a transaction with the pix key `"target_pix_key": "b9380607-dac6-4e17-8ca7-eb761e3aa1dc"` or, for **manual** pix transfers, use `"owner_document_number": "66972913039"` or `"owner_document_number": "50305556000164"` as the document number of the destination account owner.
---
# Execute Asynchronous Transfer to Manual Pix
URL: /en/documentation/pix_indireto/movimentacoes/transacao_async/transacao_pix_manual
## Manual Request
ENDPOINT /account/ ACCOUNT_KEY /alias/ ALIAS_KEY /pix_transfer
METHOD POST
Request Body
```json
{
"request_control_key": "6e290347-330d-4b3a-8ebb-2ac217ad6eb3",
"pix_transfer_type": "manual",
"target_account": {
"account_branch": "0001",
"account_digit": "1",
"account_number": "2983779",
"account_type": "checking_account",
"ispb": "99999004",
"owner_document_number": "36188081866",
"owner_name": "USER PF LIMIT LEDGER",
"owner_person_type": "natural"
},
"pix_message": "Bom dia",
"transaction_amount": 500.00,
"schedule_date": "2021-08-04"
}
```
### Body Param
| Field | Type | Description | Characters |
|-------|------|-------------|------------|
| `request_control_key` *| uuidv4 | UUID4 for querying purposes about the made request. | 36 |
| `pix_transfer_type` * | string | Pix has different initiation types, "manual" where the user must send the destination and source account fields and "key" where the user must send the recipient's Pix key fields (destination account) and the source account data. | 6 |
| `target_account` *| Object | Destination account - Should only be sent in "manual" type transactions. | **[target_account Object](#target_account-object)** |
| `pix_message` | string | Optional message that will accompany the Pix | 140 |
| `transaction_amount` * | float | Transaction amount | 20 |
| `schedule_date` | date | Transaction scheduling date (if not sent, the transfer is executed at the moment of approval). | 10 |
### target_account Object
| Field | Type | Description | Characters |
|-------|------|-------------|------------|
| `account_branch` * | string | Branch. | 4 |
| `account_digit` * | string | Account digit | 1 |
| `account_number` * | string | Account number. | 8 |
| `owner_document_number` * | string | CPF or CNPJ (numbers only) of the account holder.| 14 |
| `owner_name` * | string | Account holder name. | 120 |
| `account_type` * | string | Account type, which can be `checking_account`, `deposit_account`, `guaranteed_account`, `investment_account`, `saving_account` | 20 |
| `owner_trading_name` | string | Trading name for legal entities. Used only for CNPJ| 10 |
| `ispb` *| string | Eight-digit code that identifies banks in the Central Bank's reserve transfer system. | 8 |
:::info HTTP Status 202 Accepted
In asynchronous pix, every transaction returns **http status 202 Accepted**, the Pix request **should not be retried**. In this scenario, the transaction will be executed opportunely and will be updated through the [Transaction Update Webhook](/documentation/pix_indireto/movimentacoes/webhook/webhook_transacao).
It is also possible to check the transaction status through the endpoint [/account/ACCOUNT_KEY/alias/ALIAS_KEY/pix_transfer/PIX_TRANSFER_KEY](/documentation/pix_indireto/movimentacoes/consultar_pix).
:::
## Response
STATUS 202 Accepted
Response Body: Manual transfer
```json
{
"request_control_key": "6e290347-330d-4b3a-8ebb-2ac217ad6eb3",
"pix_transfer_key": "8cb70dea-9fb0-4a68-9572-99a72849c8d6",
"pix_transfer_status": "pending_confirmation",
"created_at": "2021-10-22T20:30:23.459Z"
}
```
STATUS 400
Response Body
```json
{
"data": {
"title": "Bad Request",
"description": "Invalid request body.",
"translation": "Corpo da requisição inválido.",
"extra_fields": {},
"code": "LEG000069"
}
}
```
---
# Execute Asynchronous Transfer via Pix Key
URL: /en/documentation/pix_indireto/movimentacoes/transacao_async/transacao_pix_normal
## Normal Request
ENDPOINT /account/ ACCOUNT_KEY /alias/ ALIAS_KEY /pix_transfer
METHOD POST
Request Body
```json
{
"request_control_key": "6e290347-330d-4b3a-8ebb-2ac217ad6eb3",
"pix_transfer_type": "key",
"target_pix_key": "pix@qitech.com.br",
"pix_message": "Bom dia",
"transaction_amount": 500.00,
"end_to_end_id": "E3240250220211022203051750897529",
"schedule_date": "2021-08-04"
}
```
### Request Path Params
| Field | Type | Description | Characters |
|---------------------|--------|-----------------------|------------|
| `account_key` | uuidv4 | Unique account key. | 36 |
| `alias_key` | uuidv4 | Unique alias key. | 36 |
### Body Param
| Field | Type | Description | Max. Characters |
|---------|------|-----------|------------|
| `request_control_key` *| uuidv4 | UUID4 for query purposes about the request made. | 36 |
| `pix_transfer_type` * | string | Pix has different initiation types, "manual" where the user must send the destination and source account fields, and "key" where the user must send the receiver's Pix key fields (destination account) and source account data. | 6 |
| `transfer_time` * | string | Transaction synchronicity information, used to define when the transaction will be processed. If "synchronous", the transaction will be executed immediately, but respecting a maximum limit of transactions per minute. If "asynchronous", the transaction will be processed in a | 200 |
| `target_pix_key` * | string | Pix key that will receive the transaction. | 200 |
| `pix_message` * | string | Optional message that will accompany the Pix | 140 |
| `transaction_amount` * | float | Transaction amount | 20 |
| `end_to_end_id` | string | unique identification key for a transaction or query at the Central Bank. Example: E3240250220210615135810450327042 | 32 |
| `schedule_date` | date | Transaction scheduling date (if not sent, the transfer is executed at the moment of approval). | 10 |
:::info HTTP Status 202 Accepted
In asynchronous pix, every transaction returns **http status 202 Accepted**, the Pix request **should not be retried**. In this scenario, the transaction will be executed opportunely and will be updated through the [Transaction Update Webhook](/documentation/pix_indireto/movimentacoes/webhook/webhook_transacao).
It is also possible to check the transaction status through the endpoint [/account/ACCOUNT_KEY/alias/ALIAS_KEY/pix_transfer/PIX_TRANSFER_KEY](/documentation/pix_indireto/movimentacoes/consultar_pix).
:::
## Response
STATUS 202 Accepted
Response Body
```json
{
"request_control_key": "6e290347-330d-4b3a-8ebb-2ac217ad6eb3",
"pix_transfer_key": "8cb70dea-9fb0-4a68-9572-99a72849c8d6",
"pix_transfer_status": "pending_confirmation",
"created_at": "2021-10-22T20:30:23.459Z"
}
```
STATUS 400
Response Body: Invalid Request Body
```json
{
"data": {
"title": "Bad Request",
"description": "Invalid request body.",
"translation": "Corpo da requisição inválido.",
"extra_fields": {},
"code": "LEG000069"
}
}
```
---
# Perform Asynchronous Transfer to Pix QR Code
URL: /en/documentation/pix_indireto/movimentacoes/transacao_async/transacao_pix_qr_code
## QR Code Request
ENDPOINT /account/ ACCOUNT_KEY /alias/ ALIAS_KEY /pix_transfer
METHOD POST
Request Body
```json
{
"request_control_key": "6e290347-330d-4b3a-8ebb-2ac217ad6eb3",
"pix_transfer_type": "qr_code",
"target_pix_key": "pix@qitech.com.br",
"pix_message": "Bom dia",
"transaction_amount": 500.00,
"end_to_end_id": "E3240250220211022203051750897529",
"schedule_date": "2021-08-04",
"receiver_conciliation_id": "REC00000000000000000000009459463343"
}
```
### Body Param
| Field | Type | Description | Max. Characters |
|---------|------|-----------|------------|
| `request_control_key` *| uuidv4 | UUID4 for query purposes regarding the request made. | 36 |
| `pix_transfer_type` * | string | Pix has different initiation types, "manual" where the user must send the destination and source account fields and "key" where the user must send the receiver's Pix key fields (destination account) and the source account data. | 6 |
| `target_pix_key` * | string | Pix key that will receive the transaction. | 200 |
| `pix_message` | string | Optional message that will accompany the Pix | 140 |
| `transaction_amount` * | float | Transaction amount | 20 |
| `end_to_end_id` | string | unique identification key for a transaction or query in the Central Bank. Example: E3240250220210615135810450327042 | 32 |
| `schedule_date` | date | Transaction scheduling date (if not sent, the transfer is performed upon approval). | 10 |
| `receiver_conciliation_id` * | string | Receiver conciliation identification. Generated when decoding a QR Code | 10 |
:::info HTTP Status 202 Accepted
In asynchronous pix, every transaction returns **http status 202 Accepted**, the Pix request **should not be retried**. In this scenario, the transaction will be processed opportunely and will be updated through the [Transaction Update Webhook](/documentation/pix_indireto/movimentacoes/webhook/webhook_transacao).
It is also possible to check the transaction status through the endpoint [/account/ACCOUNT_KEY/alias/ALIAS_KEY/pix_transfer/PIX_TRANSFER_KEY](/documentation/pix_indireto/movimentacoes/consultar_pix).
:::
## Response
STATUS 202 Accepted
Response Body
```json
{
"request_control_key": "6e290347-330d-4b3a-8ebb-2ac217ad6eb3",
"pix_transfer_key": "8cb70dea-9fb0-4a68-9572-99a72849c8d6",
"pix_transfer_status": "pending_confirmation",
"created_at": "2021-10-22T20:30:23.459Z"
}
```
STATUS 400
Response Body: Invalid Request Body
```json
{
"data": {
"title": "Bad Request",
"description": "Invalid request body.",
"translation": "Corpo da requisição inválido.",
"extra_fields": {},
"code": "LEG000069"
}
}
```
STATUS 202
Response Body: Pending Transfer
```json
{
"request_control_key": "6e290347-330d-4b3a-8ebb-2ac217ad6eb3",
"pix_transfer_key": "8cb70dea-9fb0-4a68-9572-99a72849c8d6",
"pix_transfer_status": "pending_confirmation",
"created_at": "2021-10-22T20:30:23.459Z"
}
```
:::danger HTTP Status 202
If **http status 202** is returned, the Pix request **should not be retried**. You need to check the status of the Pix transfer request through a GET on the route [/baas/pix/pix_transfer](/documentation/pix/pesquisar_por_transferencia_pix_de_saida).
:::
---
# Transaction by Pix Key
URL: /en/documentation/pix_indireto/movimentacoes/transacao/transacao_pix_chave_sync
## Request Manual
ENDPOINT /account/ ACCOUNT_KEY /alias/ ALIAS_KEY /pix_transfer
METHOD POST
Request Body
```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"
}
```
### Body Params
| Field | Type | Description | Characters |
|------------------------|-----------|--------------------------------------------------------------------------------------------------|------------|
| `request_control_key` * | string | 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 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 |
:::info Warning
An `end_to_end_id` must be sent referring to the [key query](/documentation/pix_indireto/movimentacoes/consultar_chave_pix).
:::
:::danger Warning
The `end_to_end_id` from the query must be made in the name of the alias that will request the transaction!
:::
:::danger Warning
An `end_to_end_id` can only be used for a single transfer, regardless of whether it was successful or not.
:::
## Response
STATUS 201
Response Body: Transfer sent
```json
{
"request_control_key": "b6804f32-101e-4702-8fbc-c2dbc4c2caec",
"alias_key": "68908c98-59cb-4fbf-9321-5d223ec78376",
"pix_transfer_key": "8cb70dea-9fb0-4a68-9572-99a72849c8d6",
"pix_transfer_status": "sent",
"created_at": "2021-10-22T20:30:23.459Z"
}
```
STATUS 202
:::info Information
If a `pix_transfer_status` is returned in the **pending** state, the Pix request should not be retried.
This transfer will be reprocessed. It is necessary to check the transfer status through the pix transfer query.
:::
Response Body: Transfer pending
```json
{
"request_control_key": "b6804f32-101e-4702-8fbc-c2dbc4c2caec",
"alias_key": "68908c98-59cb-4fbf-9321-5d223ec78376",
"pix_transfer_key": "8cb70dea-9fb0-4a68-9572-99a72849c8d6",
"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": "descrição em portugues",
"code": "codigo",
"extra_fields": {
"pix_transfer_data": {
"request_control_key": "b6804f32-101e-4702-8fbc-c2dbc4c2caec",
"alias_key": "68908c98-59cb-4fbf-9321-5d223ec78376",
"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 Code | QI Code
`code` | Title
`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. | 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 |
---
# Manual Transaction
URL: /en/documentation/pix_indireto/movimentacoes/transacao/transacao_pix_manual_sync
## Request Manual
ENDPOINT /account/ ACCOUNT_KEY /alias/ ALIAS_KEY /pix_transfer
METHOD POST
Request Body
```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"
}
```
### Body Params
| Field | Type | Description | Characters |
|------------------------|-----------|---------------------------------------------------------------------------------------------------------|------------|
| `request_control_key` * | string | 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 manual transfer, it should be **manual** | "manual" |
| `target_account` * | Object | Destination account - Should only be sent for "manual" type transactions | **[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 |
:::warning Warning
An `end_to_end_id` can only be used for a single transfer, regardless of whether it was successful or not.
:::
### 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 | Account holder's name | 150 |
| `account_type` * | enumerator| Account type | **[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** | Checking Account |
| **salary_account** | Salary Account |
| **saving_account** | Savings Account |
| **payment_account** | Payment Account |
## Response
STATUS 201
Response Body: Transfer sent
```json
{
"request_control_key": "b6804f32-101e-4702-8fbc-c2dbc4c2caec",
"alias_key": "68908c98-59cb-4fbf-9321-5d223ec78376",
"pix_transfer_key": "8cb70dea-9fb0-4a68-9572-99a72849c8d6",
"pix_transfer_status": "sent",
"created_at": "2021-10-22T20:30:23.459Z"
}
```
STATUS 202
:::info Information
If a `pix_transfer_status` is returned in the **pending** state, the Pix request should not be retried.
This transfer will be reprocessed. It is necessary to check the transfer status through the pix transfer query.
:::
Response Body: Transfer pending
```json
{
"request_control_key": "b6804f32-101e-4702-8fbc-c2dbc4c2caec",
"alias_key": "68908c98-59cb-4fbf-9321-5d223ec78376",
"pix_transfer_key": "8cb70dea-9fb0-4a68-9572-99a72849c8d6",
"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": "descrição em portugues",
"code": "codigo",
"extra_fields": {
"pix_transfer_data": {
"request_control_key": "b6804f32-101e-4702-8fbc-c2dbc4c2caec",
"alias_key": "68908c98-59cb-4fbf-9321-5d223ec78376",
"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 Code | QI Code
`code` | Title
`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. | 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 |
---
# Transaction by QR Code
URL: /en/documentation/pix_indireto/movimentacoes/transacao/transacao_pix_qr_code_sync
## Manual Request
ENDPOINT /account/ ACCOUNT_KEY /alias/ ALIAS_KEY /pix_transfer
METHOD POST
Request Body
```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"
}
```
### Body Params
| Field | Type | Description | Characters |
|------------------------|-----------|---------------------------------------------------------------------------------------------------------|------------|
| `request_control_key` * | string | 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 QR code transfer, it should be **static_qr_code** or **dynamic_qr_code** | "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 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 |
:::info Warning
An `end_to_end_id` must be sent referring to the [QR code decoding](/documentation/pix/decodificar_qr_code).
:::
:::danger Warning
The `end_to_end_id` from the query must be made in the name of the alias that will request the transaction!
:::
:::danger Warning
An `end_to_end_id` can only be used for a single transfer, regardless of whether it was successful or not.
:::
## Response
STATUS 201
Response Body: Transfer sent
```json
{
"request_control_key": "b6804f32-101e-4702-8fbc-c2dbc4c2caec",
"alias_key": "68908c98-59cb-4fbf-9321-5d223ec78376",
"pix_transfer_key": "8cb70dea-9fb0-4a68-9572-99a72849c8d6",
"pix_transfer_status": "sent",
"created_at": "2021-10-22T20:30:23.459Z"
}
```
STATUS 202
:::info Information
If a `pix_transfer_status` is returned in the **pending** state, the Pix request should not be retried.
This transfer will be reprocessed. It is necessary to check the transfer status through the pix transfer query.
:::
Response Body: Transfer pending
```json
{
"request_control_key": "b6804f32-101e-4702-8fbc-c2dbc4c2caec",
"alias_key": "68908c98-59cb-4fbf-9321-5d223ec78376",
"pix_transfer_key": "8cb70dea-9fb0-4a68-9572-99a72849c8d6",
"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": "descrição em portugues",
"code": "codigo",
"extra_fields": {
"pix_transfer_data": {
"request_control_key": "b6804f32-101e-4702-8fbc-c2dbc4c2caec",
"alias_key": "68908c98-59cb-4fbf-9321-5d223ec78376",
"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 Code | QI Code
`code` | Title
`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. | 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 |
---
# Webhook for Pix Refunds
URL: /en/documentation/pix_indireto/movimentacoes/webhook/webhook_devolucao_outgoing_pix
Webhook to notify about Pix refunds received for an Alias.
## 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",
"alias_key": "fc6862c4-2b20-4057-8063-b8809866e494",
"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 the pix transaction performed | **[Enumerator pix_transfer_type](#enumerator-pix_transfer_type)** |
| `target_pix_key` | string | Pix key of the account to which the transaction was sent | 100 |
| `source_account` | Object | Source account - Should only be sent for "manual" type transactions | **[Object source_account](#object-source_account)** |
| `transfer_amount` | number | Transfer amount | 10 |
| `receiver_conciliation_id` | string | Reconciliation ID of the receiver | 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 | Status of the pix transaction | 10 |
| `account_key` | string | Unique identification key for the QI account | 36 |
| `alias_key` | string | Unique alias key | 36 |
| `pix_transfer_key` | string | Unique identification key for the Pix transfer | 36 |
| `original_outgoing_pix_transfer` | string | Unique identification key for the original outgoing Pix transfer | 36 |
### Enumerator pix_transfer_type
| Enumerator | Description |
|----------------------|---------------------------------------------|
| **manual** | Pix using 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 | 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 | **[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** | Checking Account |
| **salary_account** | Salary Account |
| **saving_account** | Savings Account |
| **payment_account** | Payment Account |
---
# Webhook for Incoming Pix
URL: /en/documentation/pix_indireto/movimentacoes/webhook/webhook_incoming_pix
Webhook to notify about Pix transactions received for an Alias.
## 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",
"alias_key": "fc6862c4-2b20-4057-8063-b8809866e494",
"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 the pix transaction performed | **[Enumerator pix_transfer_type](#enumerator-pix_transfer_type)** |
| `target_pix_key` | string | Pix key of the account to which the transaction was sent | 100 |
| `source_account` | Object | Source account - Should only be sent for "manual" type transactions | **[Object source_account](#object-source_account)** |
| `transfer_amount` | number | Transfer amount | 10 |
| `receiver_conciliation_id` | string | Reconciliation ID of the receiver | 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 | Status of the pix transaction | 10 |
| `account_key` | string | Unique identification key for the QI account | 36 |
| `alias_key` | string | Unique alias key | 36 |
| `pix_transfer_key` | string | Unique identification key for the Pix transfer | 36 |
### Enumerator pix_transfer_type
| Enumerator | Description |
|----------------------|---------------------------------------------|
| **manual** | Pix using 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 | 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 | **[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** | Checking Account |
| **salary_account** | Salary Account |
| **saving_account** | Savings Account |
| **payment_account** | Payment Account |
---
# Webhook for Pending Transactions
URL: /en/documentation/pix_indireto/movimentacoes/webhook/webhook_transacao
Webhook to notify about the completion of transactions that were originally responded to as pending (returned with http status 202).
## 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 querying about the made request | 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 of the transaction's creation | 20 |
---
# Cancel a Portability Request
URL: /en/documentation/pix_indireto/portabilidade/cancelar_pedido_de_portabilidade
:::info
Portability Request cancellations can be made under the following conditions:
Status must be `waiting resolution`.
If the cancellation reason is `default`, the deadline defined by the `max_resolution_date` field must have passed.
:::
The table below defines, depending on the reason, who can cancel a portability.
| Reason | Donor | Claimer |
|------------------|-------|---------|
| `client_request` | ✓ | ✓ |
| `account_closure`| ✓ | |
| `default` | | ✓ |
| `fraud` | ✓ | ✓ |
## Request
ENDPOINT /account/ ACCOUNT_KEY /alias/ ALIAS_KEY /claim/ CLAIM_REQUEST_KEY
METHOD PATCH
**Request Body**
```json
{
"request_control_key": "8a923886-afce-4116-ac1f-69bdffcf8da9",
"claim_request_status": "cancelled",
"cancellation_reason": "client_request",
}
```
| cancellation_reason | Description |
| ------------------- |---------------------------------------------------------------------------|
| `client_request` | The claimer user requested the cancellation of the portability request |
| `account_closure` | The account was closed during the portability process |
| `default` | The validation period for the claimer's key ownership expired |
| `fraud` | There was fraud in the opening of the portability request |
## Response
STATUS 200
**Response Body**
```json
{
"request_control_key": "95968498-5ad0-465a-9174-969d0bd1e84a",
"claim_request_status": "cancelled",
"created_at": "2024-05-25T12:13:25"
}
```
| Value | Description | type |
|-----------------------|---------------------------------------------------------|---------------|
| `claim_request_status`| Status of the portability request. | string |
| `created_at` | Date of creation of the portability request. | datetime string |
| `request_control_key` | Unique UUID4 identifier of the request. | uuid4 string |
### claim_request_status
| Value | Description |
|---------------------|-------------------------------------------------------------------------------------|
| `waiting_resolution`| The notification was received by the counterparty |
| `confirmed` | The donor confirmed the claim. It is waiting for the claimer to complete the process.|
| `cancelled` | The donor or claimer canceled the portability request |
| `completed` | Both the DICT and the claimer updated their records with the new linkage |
---
# Complete a Portability Request
URL: /en/documentation/pix_indireto/portabilidade/completar_pedido_de_portabilidade
:::info
Completes the claim operation. As a result, the link with the key is created.
:::
## Request
ENDPOINT /account/ ACCOUNT_KEY /alias/ ALIAS_KEY /claim/ CLAIM_REQUEST_KEY
METHOD PATCH
**Request Body**
```json
{
"request_control_key": "8a923886-afce-4116-ac1f-69bdffcf8da9",
"claim_request_status": "completed",
}
```
## Response
STATUS 200
**Response Body**
```json
{
"request_control_key": "95968498-5ad0-465a-9174-969d0bd1e84a",
"claim_request_status": "completed",
"created_at": "2024-05-25T12:13:25"
}
```
| Value | Description | type |
|-----------------------|---------------------------------------------------------|---------------|
| `claim_request_status`| Status of the portability request. | string |
| `created_at` | Date of creation of the portability request. | datetime string |
| `request_control_key` | Unique UUID4 identifier of the request. | uuid4 string |
### claim_request_status
| Value | Description |
|---------------------|-------------------------------------------------------------------------------------|
| `waiting_resolution`| The notification was received by the counterparty |
| `confirmed` | The donor confirmed the claim. It is waiting for the claimer to complete the process.|
| `cancelled` | The donor or claimer canceled the portability request |
| `completed` | Both the DICT and the claimer updated their records with the new linkage |
---
# Confirm a Portability Request
URL: /en/documentation/pix_indireto/portabilidade/confirmar_pedido_de_portabilidade
Confirms the claim operation. As a result, the key's link with the donor participant is removed.
Status must be `waiting_resolution`.
For possession claim, if the reason is `default`, the resolution deadline (`max_resolution_date`) must have passed. If the reason provided is `client_request`, the closure deadline (`max_conclusion_date`) will be brought forward to allow immediate closure by the claimer.
The tables below define, depending on the reason and type, who can confirm.
| Ownership | Donor | Claimer |
|----------------------|-------|--------------|
| `client_request` | ✓ | |
| `account_closure` | | |
| `default` | ✓ | |
| Portability | Donor | Claimer |
|----------------------|-------|--------------|
| `client_request` | ✓ | |
| `account_closure` | ✓ | |
| `default` | | |
## Request
ENDPOINT /account/ ACCOUNT_KEY /alias/ ALIAS_KEY /claim/ CLAIM_REQUEST_KEY
METHOD PATCH
**Request Body**
```json
{
"request_control_key": "8a923886-afce-4116-ac1f-69bdffcf8da9",
"claim_request_status": "confirmed",
"confirmation_reason": "client_request",
}
```
## Response
STATUS 200
**Response Body**
```json
{
"request_control_key": "95968498-5ad0-465a-9174-969d0bd1e84a",
"claim_request_status": "confirmed",
"created_at": "2024-05-25T12:13:25"
}
```
| Value | Description | type |
|-----------------------|--------------------------------------------|---------------|
| `claim_request_status`| Status of the portability request. | string |
| `created_at` | Date of creation of the portability request | datetime string |
| `request_control_key` | Unique UUID4 identifier of the request. | uuid4 string |
---
# Consult Portability Requests
URL: /en/documentation/pix_indireto/portabilidade/consultar_pedido_de_portabilidade
## Request
ENDPOINT /account/ ACCOUNT_KEY /alias/ ALIAS_KEY /claim_request/ CLAIM_REQUEST_KEY
METHOD GET
## Response
STATUS 200
**Response Body**
```json
{
{
"request_control_key": "be0884bc-44a4-4907-8627-ef976e477aef",
"claim_request_status": "pending",
"claim_request_direction": "incoming",
"claim_request_key": "fe3ab7c5-e907-4a66-b9c5-7ea156429f83",
"pix_key": "12345678000190",
"claim_request_type": "ownership",
"pix_key_type": "cnpj",
"cancellation_reason": null,
"cancelled_by": "donor",
"confirmation_reason": null,
"created_at": "2024-05-25T12:13:25",
"max_resolution_date": "2023-11-13T17:29:00",
"claim_request_events": [
{
"event_type": "waiting_resolution",
"event_details": "Relato de Infração recebido e em análise",
"created_at": "2023-03-03T12:04:06.179Z"
},
{
"event_type": "cancelled",
"event_details": "Relato de Infração cancelado",
"created_at": "2023-03-03T12:04:06.179Z"
},
],
}
}
```
| Value | Description | type |
|-------------------------|-----------------------------------------------------------------------------------------------------------|--------|
| `cancellation_reason` | Reason for cancellation. "client_request", "account_closure", "fraud", "default", "reconciliation" | string |
| `cancelled_by` | Agent who canceled the portability request. "donor", "claimer" | string |
| `claim_request_direction` | Indicates whether the portability request was received or sent. "incoming" or "outgoing" | string |
| `claim_request_key` | Unique identification key of the claim. | string |
| `claim_request_status` | Status of the portability request. | string |
| `claim_request_type` | Type of portability request. "ownership" or "portability" | string |
| `confirmation_reason` | Reason for confirmation. "client_request", "account_closure", "fraud", "default", "reconciliation" | string |
| `created_at` | Date of creation of the portability request. | datetime string |
| `max_conclusion_date` | Deadline to close the portability request. Only for "ownership" type portabilities. | string |
| `max_resolution_date` | Deadline for the resolution of the portability request. | string |
| `pix_key` | PIX key of the portability request. | string |
| `pix_key_type` | Type of PIX key of the portability request. | string |
| `request_control_key` | Unique UUID4 identifier of the request. | uuid4 string |
| `claim_request_events` | Group of events related to the portability request. | uuid4 string |
### claim_request_status
| Value | Description |
|-------------------------|-------------------------------------------------------------------------------------|
| `waiting_resolution` | The notification was received by the counterparty. |
| `confirmed` | The donor confirmed the claim. It is waiting for the claimer to complete the process.|
| `cancelled` | The donor or claimer canceled the portability request. |
| `completed` | Both the DICT and the claimer updated their records with the new linkage. |
---
# Portability Request creation
URL: /en/documentation/pix_indireto/portabilidade/criar_pedido_de_portabilidade
## Request
ENDPOINT /account/ ACCOUNT_KEY /alias/ ALIAS_KEY /claim_request
METHOD POST
**Request Body**
```json
{
"request_control_key": "4b61f25d-b8b5-49cb-a391-e4878091ac3f",
"pix_key": "12345678000190",
"claim_request_type": "ownership",
"pix_key_type": "cnpj"
}
```
| Field | Type | Description | Max. Characters |
|-------------------------|--------|-------------------------------------------------------------------------|-----------------|
| `request_control_key` * | string | UUID4 for querying about the made request. | 36 |
| `pix_key` * | string | PIX key related to the portability request | 36 |
| `claim_request_type` * | string | Type of portability. "ownership" for claim and "portability" for portability | 36 |
| `pix_key_type` * | string | Definition of key type. Can be "cpf", "cnpj", "email", "phone_number". | 10 |
## Response
STATUS 201 created
**Response Body**
```json
{
"request_control_key": "8a923886-afce-4116-ac1f-69bdffcf8da9",
"claim_request_status": "pending",
"claim_request_key": "fe3ab7c5-e907-4a66-b9c5-7ea156429f83",
"max_conclusion_date": "2024-05-26T12:13:25",
"created_at": "2024-05-25T12:13:25"
}
```
---
# Introduction to Portability Requests
URL: /en/documentation/pix_indireto/portabilidade/introducao_portabilidade
PIX key claims and portability are special mechanisms provided by the central bank for potential changes in PIX key ownership.
- Claims are used in cases where there is a change in ownership of a key (**phone** or **email**), and the new owner wishes to create a link for their account, but the previous owner (former holder of the **phone** or **email**) already has a record in the DICT with this key.
- Portabilities are used when the key owner wishes to change its linkage to another account, which is domiciled in a different participant from the current one.
For each type of ownership change resource, there are only a few types of keys enabled, which are:
| Compatible | Claim | Portability |
|------------|-------------|-------------|
| cpf | ✓ | |
| cnpj | ✓ | |
| phone_number | ✓ | ✓ |
| email | ✓ | ✓ |
| random_key | | |
In the scope of indirect PIX, the ownership change mechanisms will work with the same premises, with special routes provided in the QI Tech infrastructure so that accounts enabled to use indirect PIX can make requests and receive responses from the flows presented above.
### 1. Claimant Flow
:::info
The flowcharts below represent the behaviors pertinent to the **claim flow** of PIX key
:::
##### 1.1. QI Tech Indirect Participant requests opening a portability request
```mermaid
flowchart LR
PARTICIPANT(Indirect Participant\n QiTech);
WAITING_RESOLUTION{{Portability \n'waiting_resolution'}};
PARTICIPANT -. portability\n request.-> WAITING_RESOLUTION
```
##### 1.2. Donor Bank confirms receipt of portability request
```mermaid
flowchart RL
OTHER_BANK(Donor Bank);
QI_PARTICIPANT(Indirect Participant\n QiTech);
CONFIRMED{{Portability \n 'confirmed'}};
OTHER_BANK-. Confirm portability\n request.->CONFIRMED -- Webhook Update --> QI_PARTICIPANT;
```
##### 1.3. QI Tech Indirect Participant completes the portability request and the PIX key link is created
```mermaid
flowchart LR
BACEN(Banco Central \n do Brasil);
QI_PARTICIPANT(Indirect Participant\n QiTech);
COMPLETED{{Portability \n 'completed'}};
QI_PARTICIPANT-. Completes portability\n request.->COMPLETED -- Pix key link \n creation--> BACEN;
```
##### 1.4. QI Tech Indirect Participant completes the portability request and the PIX key link is created
:::warning Important
Portability Requests with **confirmed** status can only be canceled if they are of type **"fraud"**
:::
```mermaid
flowchart LR
BACEN(Banco Central \n do Brasil);
QI_PARTICIPANT(Indirect Participant\n QiTech);
PORTABILITY{{Portability \n 'waiting_resolution' ou 'confirmed'}};
QI_PARTICIPANT-. Cancel portability \n request.->PORTABILITY -- Pix key link creation --> BACEN;
```
### 2. Donor Flow
:::info
The flowcharts below represent the behaviors pertinent to the **donation flow** of PIX key
:::
#### 2.1. Claimant Bank opens a portability request
```mermaid
flowchart RL
OTHER_BANK(Claimant Bank);
QI_PARTICIPANT(Indirect Participant\n QiTech);
CONFIRMED{{Portability \n 'waiting_resolution'}};
OTHER_BANK-. Confirm portability \n request.->CONFIRMED -- Portability Request Receipt \n Webhook --> QI_PARTICIPANT;
```
#### 2.2. QI Tech Indirect Participant confirms receipt of portability request
```mermaid
flowchart LR
PARTICIPANT(Indirect Participant\n QiTech);
CONFIRMED{{Portability \n'confirmed'}};
PARTICIPANT -. Confirms receipt \n and removes link .-> CONFIRMED
```
#### 2.3. Claimant Bank completes a portability request
```mermaid
flowchart RL
OTHER_BANK(Claimant Bank);
QI_PARTICIPANT(Indirect Participant\n QiTech);
CONFIRMED{{Portability \n 'completed'}};
OTHER_BANK-. Completes portability\n request.->CONFIRMED -- Webhook Update --> QI_PARTICIPANT;
```
#### 2.4. Claimant Bank cancels a portability request
:::warning Important
Portability Requests with **confirmed** status can only be canceled if they are of type **"fraud"**
:::
```mermaid
flowchart RL
OTHER_BANK(Claimant Bank);
QI_PARTICIPANT(Indirect Participant\n QiTech);
PORTABILITY{{Portability \n 'waiting_resolution' ou 'confirmed'}};
OTHER_BANK-. Cancels portability\n request.->PORTABILITY -- Webhook Update --> QI_PARTICIPANT;
```
---
# Consult Portability Requests for an Alias
URL: /en/documentation/pix_indireto/portabilidade/listar_pedidos_de_portabilidade_de_um_alias
## Request
ENDPOINT /account/ ACCOUNT_KEY /alias/ ALIAS_KEY /claim_requests
METHOD GET
## Response
STATUS 200
**Response Body**
```json
{
"data": [
{
"cancellation_reason": null,
"cancelled_by": null,
"claim_request_flow_type": "donator",
"claim_request_key": "be0884bc-44a4-4907-8627-ef976e477aef",
"claim_request_status": "pending_confirmation",
"claim_request_type": "portability",
"confirmation_reason": null,
"created_at": "2023-11-06T17:30:11",
"donator_ispb": 32402502,
"limit_conclusion_date": null,
"limit_resolve_date": "2023-11-13T17:29:00",
"max_conclusion_date": null,
"max_resolution_date": "2023-11-13T17:29:00",
"pix_key": "45574823098",
"pix_key_claim_id": "205c72ab-c03e-43b7-a43d-2409e21fa5be",
"pix_key_type": "cpf",
"request_control_key": "be0884bc-44a4-4907-8627-ef976e477aef"
},
{
"cancellation_reason": null,
"cancelled_by": null,
"claim_request_flow_type": "donator",
"claim_request_key": "852d0192-68a7-4bad-bc22-0002f9c5cb1c",
"claim_request_status": "concluded",
"claim_request_type": "portability",
"confirmation_reason": null,
"created_at": "2023-11-05T17:30:11",
"donator_ispb": 32402502,
"limit_conclusion_date": null,
"limit_resolve_date": "2023-11-12T17:29:00",
"max_conclusion_date": null,
"max_resolution_date": "2023-11-12T17:29:00",
"pix_key": "93109309009",
"pix_key_claim_id": "089db155-59cf-4a19-881b-22ca932a4612",
"pix_key_type": "cpf",
"request_control_key": "9a4336be-a729-4245-9b90-72bbeb04f13c"
}
],
"pagination": {
"current_page": 1,
"rows_per_page": 10
}
}
```
---
# Portability Update Webhook
URL: /en/documentation/pix_indireto/portabilidade/webhook/webhook_atualizacao_do_pedido_de_portabilidade
**Request Body: Update a Portability Request**
```json
{
"webhook_type": "baas.pix_keys.claim_request",
"webhook_datetime": "2024-05-27T12:13:24",
"data": {
"claim_request_status": "pending",
"claim_request_direction": "incoming",
"claim_request_key": "fe3ab7c5-e907-4a66-b9c5-7ea156429f83",
"pix_key": "12345678000190",
"claim_request_type": "ownership",
"pix_key_type": "cnpj",
"cancellation_reason": null,
"cancelled_by": "donor",
"confirmation_reason": null,
"max_resolution_date": "2023-11-13T17:29:00",
"updated_at": "2024-05-25T12:13:25",
}
}
```
### Webhook Body Param
| Field | Type | Description | Characters |
|------------------------|----------|-------------------------------------------------------------|------------|
| `claim_request_status` * | string | PIX key representing the destination account of the transaction. | - |
| `claim_request_key` * | string | UUID4 key identifying the QR Code. | - |
| `updated_at` * | datetime | Date and time of QR Code payment. | - |
### claim_request_status
| Value | Description |
|-----------------------|-------------------------------------------------------------------------------------|
| `waiting_resolution` | The notification was received by the counterparty |
| `confirmed` | The donor confirmed the claim. It is waiting for the claimer to complete the process.|
| `cancelled` | The donor or claimer canceled the portability request |
| `completed` | Both the DICT and the claimer updated their records with the new linkage |
---
# Portability Request Received Webhook
URL: /en/documentation/pix_indireto/portabilidade/webhook/webhook_receber_registro_externo_de_portabilidade
**Request Body: Receiving a Portability Request**
```json
{
"webhook_type": "baas.pix_keys.claim_request",
"webhook_datetime": "2024-05-27T12:13:24",
"data": {
"claim_request_status": "pending",
"claim_request_direction": "incoming",
"claim_request_key": "fe3ab7c5-e907-4a66-b9c5-7ea156429f83",
"pix_key": "12345678000190",
"claim_request_type": "ownership",
"pix_key_type": "cnpj",
"cancellation_reason": null,
"cancelled_by": "donor",
"confirmation_reason": null,
"max_resolution_date": "2023-11-13T17:29:00",
"created_at": "2024-05-25T12:13:25",
}
}
```
### Webhook Body Param
| Field | Type | Description | Characters |
|------------------------|----------|-------------------------------------------------------------|------------|
| `claim_request_status` * | string | PIX key representing the destination account of the transaction. | - |
| `claim_request_key` * | string | UUID4 key identifying the QR Code. | - |
| `updated_at` * | datetime | Date and time of QR Code payment. | - |
### claim_request_status
| Value | Description | Characters |
|-----------------------|-------------------------|------------|
| `waiting_resolution` | Description | - |
| `confirmed` | Description | - |
| `cancelled` | Description | - |
| `completed` | Description | - |
---
# Consult QR Code
URL: /en/documentation/pix_indireto/qr_code/consultar_qr_code
It is possible to search for a specific QR Code of the Alias by the qr_code_key generated during its creation. This endpoint will return all its information, such as status, payment, and events.
## Request
ENDPOINT /account/ ACCOUNT_KEY /alias/ ALIAS_KEY /qrcode/ QR_CODE_KEY
METHOD GET
## Response
STATUS 200 Ok
Response Body: Geral
```json
{
"request_control_key": "037b46b1-0c67-4c0d-aac3-1e395dfdcb10",
"pix_key": "3d7d6a2b-f72f-44z7-bb20-79a94dff5645",
"receiver_conciliation_id": "01GVGV9NXBCY287Z6CJ4S0ENW9",
"qr_code_key": "d74bf12a-9243-4bfa-9b00-6b63755b6555",
"qr_code_status": "active",
"qr_code_type": "dynamic_instant",
"amount": 22.34,
"expiration_seconds": 864000,
"expiration_date": null,
"max_payment_days": null,
"payer_name": "João da Silva",
"payer_document_number": "00000000000000",
"payer_person_type": "legal",
"payer_request": "Payment for order XXXXXXXXXXXX",
"rebate_amount": 1,
"interest_amount": 2,
"fine_amount": 3,
"discounts": [],
"additional_data": [
{
"key_name": "Juros e Multa",
"value": "Juros 2 ao mes e multa de 1%"
}
],
"pix_transfer_key": null,
"paid_amount": null,
"base_64_payload": "",
"qr_code_events": [
{
"request_control_key": "037b46b1-0c67-4c0d-aac3-1e395dfdcb10",
"event_type": "registration",
"created_at": "2023-03-03T12:04:06.179Z"
},
{
"request_control_key": "cae915c8-1940-43ec-890b-ba1a3a66354c",
"event_type": "payment",
"created_at": "2023-03-03T12:04:06.179Z"
}
],
"created_at": "2023-03-03T12:04:06.179Z"
}
```
| Field | Type | Description | Characters |
|-----------------------------|--------|-------------------------------------------------------------------------|------------|
| `request_control_key` * | string | Unique UUID4 identifier of the request that originated the QR Code. | - |
| `pix_key` * | string | PIX key representing the destination account of the transaction. | - |
| `receiver_conciliation_id` *| string | QR Code identifier for reconciliation after payment. | - |
| `qr_code_key` * | string | UUID4 key identifying the QR Code. | - |
| `qr_code_status` * | string | QR Code status. | - |
| `qr_code_type` * | string | QR Code type. | "dynamic_term" or "dynamic_instant" |
| `amount` * | float | QR Code amount before calculating discounts or interest and fines. | - |
| `expiration_seconds` | string | Indicates the validity time of the QR Code in seconds, default is 1 day | - |
| `expiration_date` | date | Due date of the charge (in the format "YYYY-MM-DD"). | - |
| `max_payment_days` | int32 | Maximum days for paying the charge after due date. | - |
| `payer_name` * | string | Payer's name. | - |
| `payer_document_number` * | string | Payer's CPF/ CNPJ. | - |
| `payer_request` * | string | Message to the payer. | - |
| `rebate_amount` | float | Absolute rebate amount before payment. | - |
| `interest_amount` | float | Absolute value per day of delay after the due date. | - |
| `fine_amount` | float | Absolute fine amount after the due date. | - |
| `discounts` | array of objects | Discount settings. | - |
| `additional_data` | array of objects | Information to be presented to the payer. | - |
| `pix_transfer_key` | string | UUID4 key identifying the PIX transaction corresponding to the QR Code settlement. | - |
| `paid_amount` | float | Amount of the payment made, considering fines, discounts, and others. | - |
| `base_64_payload` | string | URL of the QR Code for payment in base64. | - |
| `qr_code_events` | array of objects | List of status changes the QR Code has undergone. | - |
| `created_at` | datetime | Date and time the QR Code was created in the system. | - |
### Object qr_code_status
| Field | Type | Description | Characters |
|-----------------|--------|-----------------------------------------------------|------------|
| `active` | string | QR Code is active and available for payment. | - |
| `finished` | string | QR Code has been paid. | - |
| `written_off` | string | QR Code has been canceled by the client. | - |
| `bank_written_off` | string | QR Code was automatically canceled due to expiration. | - |
### Object discount
| Field | Type | Description | Characters |
|---------------------|--------|--------------------------|------------|
| `discount_value` * | float | Discount amount. | - |
| `discount_number` | int32 | Order in which the discount should be applied. | - |
| `discount_limit_date` | string | Discount limit date. | - |
### Object additional_data
| Field | Type | Description | Characters |
|--------------------|--------|---------------------------|------------|
| `key_name` * | string | Name of the field | - |
| `value` | string | Value of the field | - |
### Object qr_code_events
| Field | Type | Description | Characters |
|-------------------------|----------|----------------------------------------------------------|------------|
| `request_control_key` * | string | Unique UUID4 identifier of the request that originated the event. | - |
| `event_type` * | string | Event type | "registration", "write_off", "payment" |
| `created_at` * | datetime | Date and time the event was created. | - |
STATUS 400
Response Body
```json
{
"title": "Bad Request",
"description": "Invalid payload for QR Code creation.",
"translation": "Payload inválido para a criação de QR Code.",
"code": "QRI000003"
}
```
STATUS 404
Response Body: QR Code key not found
```json
{
"title": "Not found",
"description": "No Pix QR Code found for qr_code_key {qr_code_key}.",
"translation": "Não foi encontrado nenhum QR Code com a qr_code_key {qr_code_key}.",
"code": "QRI000005"
}
```
---
# Create Dynamic PIX QR Code with Due Date
URL: /en/documentation/pix_indireto/qr_code/Criar QR Code/criar_qr_code_dinamico_com_vencimento
The dynamic QR Code with a due date is used for payments where the originator is known and it is desirable to facilitate payment, allowing the addition of deadlines, discounts, fines, and interest. This QR Code is typically used as a replacement for bank slips.
## Request
ENDPOINT /account/ ACCOUNT_KEY /alias/ ALIAS_KEY /qrcode
METHOD POST
Request Body: Dynamic QR Code with Due Date
```json
{
"request_control_key": "8a923886-afce-4116-ac1f-69bdffcf8da9",
"qr_code_type": "dynamic_term",
"amount": 10.25,
"receiver_conciliation_id": "01GVGV9NXBCY287Z6CJ4S0ENW9",
"payer_document_number": "00000000000000",
"payer_name": "Random",
"payer_request": "Payment for order XXXXXXXXXX",
"pix_key": "3d7d6a2b-f72f-44c7-bb20-79a94dff5954",
"expiration_date": "2023-03-25",
"max_payment_days": 128,
"fine_amount": 3,
"interest_amount": 2,
"rebate_amount": 1,
"discounts": [],
"additional_data": [
{
"key_name": "merchant_name",
"value": "Lojas Costa S.A."
}
],
}
```
### Body Params
| Field | Type | Description | Characters |
|-----------------------------|--------|--------------------------------------------------------------------------------------|------------|
| `request_control_key` * | string | Unique UUID4 identifier of the request. | - |
| `qr_code_type` * | string | Type of the dynamic QR Code. `"dynamic_term"` or `"dynamic_instant"` | - |
| `amount` * | float | QR Code amount before calculating discounts or interest and fines. | - |
| `receiver_conciliation_id` * | string | QR Code identifier for reconciliation after payment. | - |
| `payer_document_number` * | string | Payer's CPF/ CNPJ. | - |
| `payer_name` * | string | Payer's name. | - |
| `payer_request` * | string | Message to the payer. | - |
| `pix_key` * | string | PIX key representing the destination account of the transaction. | - |
| `expiration_date` * | date | Due date of the charge (in the format "YYYY-MM-DD"). | - |
| `max_payment_days` * | int32 | Maximum days for paying the charge. | - |
| `fine_amount` * | float | Absolute fine amount after the due date. | - |
| `interest_amount` * | float | Absolute value per day of delay after the due date. If paid one day after the due date, the total amount will be the original value + fine. | - |
| `rebate_amount` * | float | Absolute rebate amount before payment. | - |
| `discounts` | array of objects | Discount settings. | - |
| `additional_data` | array of objects | Extra information for the QR Code used for reconciliations. | - |
### Object additional_data
| Field | Type | Description | Characters |
|-----------------------------|--------|---------------------------|------------|
| `key_name` * | string | Name of the field | - |
| `value` * | string | Value of the field | - |
### Object discount
| Field | Type | Description | Characters |
|-----------------------------|--------|--------------------------|------------|
| `discount_value` * | float | Discount amount. | - |
| `discount_number` | int32 | Order in which the discount should be applied. | - |
| `discount_limit_date` * | string | Discount limit date. | - |
## Response
STATUS 201 Created
Response Body: Create dynamic QR Code with Due Date
```json
{
"request_control_key": "037b46b1-0c67-4c0d-aac3-1e395dfdcb10",
"qr_code_key": "d74bf12a-9243-4bfa-9b00-6b63755b6555",
"qr_code_status": "active",
"base_64_payload": "",
"created_at": "2023-03-03T12:04:06.179Z",
}
```
| Field | Type | Description | Characters |
|-------------------------|----------|------------------------------------------------------|------------|
| `request_control_key` * | string | Unique UUID4 identifier of the request. | - |
| `qr_code_key` * | string | QR Code identifier for future requests. | - |
| `qr_code_status` * | string | QR Code status in the system. | "active": default for creation. |
| `base_64_payload` * | string | URL of the QR Code for payment in base64. | - |
| `created_at` * | datetime | Date and time the QR Code was created in the system. | - |
### Object qr_code_status
| Field | Type | Description | Characters |
|-----------------|--------|-----------------------------------------------------|------------|
| `active` | string | QR Code is active and available for payment. | - |
| `finished` | string | QR Code has been paid. | - |
| `written_off` | string | QR Code has been canceled by the client. | - |
| `bank_written_off` | string | QR Code was automatically canceled due to expiration. | - |
STATUS 400
Response Body
```json
{
"title": "Bad Request",
"description": "Invalid payload for QR Code creation.",
"translation": "Payload inválido para a criação de QR Code.",
"code": "QRI000003"
}
```
---
# Create Dynamic PIX QR Code for Immediate Payment
URL: /en/documentation/pix_indireto/qr_code/Criar QR Code/criar_qr_code_dinamico_imediato
The dynamic QR Code for immediate payment is used for payments with a short payment term, usually processed in seconds, for routine payment collection operations.
## Request
Request Body: Dynamic PIX QR Code for Immediate Payment
```json
{
"request_control_key": "8a923886-afce-4116-ac1f-69bdffcf8da9",
"qr_code_type": "dynamic_instant",
"amount": 22.34,
"receiver_conciliation_id": "01GVGV9NXBCY287Z6CJ4S0ENW9",
"payer_document_number": "00000000000000",
"payer_name": "Random",
"payer_request": "Payment for order XXXXXXXXXX",
"pix_key": "3d7d6a2b-f72f-44z7-bb20-79a94dff5645",
"expiration_seconds": 864000,
"additional_data": [
{
"key_name": "identificacao_venda",
"value": "Venda número 123 na plataforma"
}
],
}
```
### Body Params
| Field | Type | Description | Characters |
|-----------------------------|--------|--------------------------------------------------------------------------------------|------------|
| `request_control_key` * | string | Unique UUID4 identifier of the request. | - |
| `qr_code_type` * | string | Type of the dynamic QR Code. `"dynamic_term"` or `"dynamic_instant"` | - |
| `amount` * | float | QR Code amount before calculating discounts or interest and fines. | - |
| `receiver_conciliation_id` *| string | QR Code identifier for reconciliation after payment. | - |
| `payer_document_number` * | string | Payer's CPF/ CNPJ. | - |
| `payer_name` * | string | Payer's name. | - |
| `payer_request` * | string | Message to the payer. | - |
| `pix_key` * | string | PIX key representing the destination account of the transaction. | - |
| `expiration_seconds` | string | Indicates the validity time of the QR Code in seconds, default is 1 day | - |
| `additional_data` | array of objects | Information to be presented to the payer. | - |
### Object additional_data
| Field | Type | Description | Characters |
|--------------------|--------|---------------------------|------------|
| `key_name` * | string | Name of the field | - |
| `value` | string | Value of the field | - |
## Response
STATUS 201 Created
Response Body: Create Dynamic PIX QR Code for Immediate Payment
```json
{
"request_control_key": "037b46b1-0c67-4c0d-aac3-1e395dfdcb10",
"qr_code_key": "d74bf12a-9243-4bfa-9b00-6b63755b6555",
"qr_code_status": "active",
"base_64_payload": "",
"created_at": "2023-03-03T12:04:06.179Z",
}
```
| Field | Type | Description | Characters |
|-------------------------|----------|------------------------------------------------------|------------|
| `request_control_key` * | string | Unique UUID4 identifier of the request. | - |
| `qr_code_key` * | string | QR Code identifier for future requests. | - |
| `qr_code_status` * | string | QR Code status in the system. | "active": default for creation. |
| `base_64_payload` * | string | URL of the QR Code for payment in base64. | - |
| `created_at` * | datetime | Date and time the QR Code was created in the system. | - |
### Object qr_code_status
| Field | Type | Description | Characters |
|-----------------|--------|-----------------------------------------------------|------------|
| `active` | string | QR Code is active and available for payment. | - |
| `finished` | string | QR Code has been paid. | - |
| `written_off` | string | QR Code has been canceled by the client. | - |
| `bank_written_off` | string | QR Code was automatically canceled due to expiration. | - |
STATUS 400
Response Body
```json
{
"title": "Bad Request",
"description": "Invalid payload for QR Code creation.",
"translation": "Payload inválido para a criação de QR Code.",
"code": "QRI000003"
}
```
---
# Create Static PIX QR Code
URL: /en/documentation/pix_indireto/qr_code/Criar QR Code/criar_qr_code_estatico
The static QR Code is used for payments where the identity of the payer is unknown, as well as when and how many payers there will be. Basically, it consists of a key, and optionally a value, encoded, and can be paid multiple times, as it only references the key.
## Request
ENDPOINT /account/ ACCOUNT_KEY /alias/ ALIAS_KEY /qrcode
METHOD POST
Request Body: Static QR Code
```json
{
"request_control_key": "8a923886-afce-4116-ac1f-69bdffcf8da9",
"qr_code_type": "static",
"pix_key": "joaosilva@gmail.com",
"amount": 10.25,
}
```
### Body Params
| Field | Type | Description | Characters |
|------------------------|--------|-----------------------------------------------|------------|
| `request_control_key` * | string | Unique UUID4 identifier of the request. | - |
| `qr_code_type` * | string | Type of the QR Code. | "static" |
| `pix_key` * | string | PIX key representing the destination account of the transaction. | - |
| `amount` | float | QR Code value. | If not provided, it will be entered by the payer. |
## Response
STATUS 201 Created
Response Body: Create Static QR Code
```json
{
"request_control_key": "037b46b1-0c67-4c0d-aac3-1e395dfdcb10",
"base_64_payload": ""
}
```
| Field | Type | Description | Characters |
|------------------------|--------|-----------------------------------------|------------|
| `request_control_key` * | string | Unique UUID4 identifier of the request. | - |
| `base_64_payload` * | string | URL of the QR Code for payment, in base64. | - |
STATUS 400
Response Body
```json
{
"title": "Bad Request",
"description": "Invalid payload for QR Code creation.",
"translation": "Payload inválido para a criação de QR Code.",
"code": "QRI000003"
}
```
---
# List QR Codes of an alias
URL: /en/documentation/pix_indireto/qr_code/decodificar_qr_code
PIX QR Codes, used in image or URL format, follow a standard and must be decoded using logic to extract the payment information. With the URL of the QR Code, it is possible to decode all the information that originated it. The decoding generates an `end_to_end_id`, which must be used in the QR Code payment along with the receiver_conciliation_id to identify the QR Code payment.
## Request
ENDPOINT /account/ ACCOUNT_KEY /alias/ ALIAS_KEY /qrcode/decode
METHOD POST
Request Body: Decode QR Code
```json
{
"qr_code_payload": "00020126580014br.gov.bcb.pix0136a23bf0e9-5175-4829-bf89-e8fe6ac09aa1520400005303986540530.005802BR5914TywinLannister6008saopaulo62070503***6304D4FD",
}
```
| Field | Type | Description | Characters |
|-------------------|--------|---------------------------------------|------------|
| `qr_code_payload` | string | URL of the QR Code for payment (PIX copy and paste). | - |
## Response
STATUS 200 Ok
Response Body: Static QR Code
```json
{
"end_to_end_id": "E32402502202303131806WTFZTGAOWiq",
"qr_code_data": {
"additional_data": null,
"amount": null,
"ispb_number": "90400888",
"receiver_conciliation_id": "01GVGV9NXBCY287Z6CJ4S0ENW9",
"target_account_branch": "2980",
"target_account_digit": "5",
"target_account_number": "0000000000022039741",
"target_account_type": "checking_account",
"target_bank_code": 33,
"target_bank_name": "BCO SANTANDER (BRASIL) S.A.",
"target_document_number": "00000000000000",
"target_name": "JOSE RONALDO",
"target_pix_key": "00000000000000"
},
"qr_code_key": "e54671f5-3eda-4180-8539-0ac6271fe185",
"qr_code_payload": "00020126360032br.gov.bcb.pix0111234590280001665204000051234565802BR5925JOSE RONALDO BERNARDINO 26008BRASILIA62070503***63044293",
"qr_code_type": "static"
}
```
STATUS 200 Ok
Response Body: Dynamic QR Code with due date
```json
{
"request_control_key": "037b46b1-0c67-4c0d-aac3-1e395dfdcb10",
"end_to_end_id": "E32402502202303101532yCipbxgUnUj",
"qr_code_data": {
"account_type": "payment_account",
"additional_data": [],
"amount": "55.59",
"category_code": "0000",
"max_payment_days": 16,
"discount_amount": null,
"expiration_date": "2023-03-27",
"fee_amount": null,
"fine_amount": null,
"ispb_number": "20018183",
"original_amount": "55.59",
"payer_document_number": "00000000000",
"payer_name": "Willian Rocha",
"payer_request": null,
"receiver_conciliation_id": "8b434df48c30482a81f7c936ae35cc87",
"receiver_url": "invoice.starkbank.com/v2/cobv/8b434df48c30482a81f7c936ae351234",
"reduction_amount": null,
"qr_code_status": "active",
"target_account_branch": "0001",
"target_account_digit": "8",
"target_account_number": "589575519784140",
"target_bank_code": null,
"target_bank_name": "Stark Bank S.A.",
"target_document_number": "00000000000000",
"target_name": "TESTE LTDA.",
"target_pix_key": "e623e7b0-d00a-400e-aee6-79632430e817",
"target_trading_name": null,
"presented_at": "2023-03-10T15:32:15.87Z",
"created_at": "2023-01-10T19:49:58.30Z",
},
"qr_code_key": "8c2c19bd-f260-4714-955c-956f3eaa30ca",
"qr_code_payload": "00020101021226840014br.gov.bcb.pix2562invoice.starkbank.com/v2/cobv/8b434df48c30482a81f7c936ae35cc123456000053039865802BR5925Oncred Sociedade de Credi6015TESTE 62070503***6304D008",
"qr_code_type": "dynamic_term"
}
```
STATUS 200 Ok
Response Body: QR Code with due date
```json
{
"request_control_key": "037b46b1-0c67-4c0d-aac3-1e395dfdcb10",
"end_to_end_id": "E32402502202303141907qlBAF1evdJ2",
"qr_code_data": {
"account_type": "checking_account",
"additional_data": [],
"amount": "9367.61",
"category_code": "0000",
"expiration_seconds": 201574,
"ispb_number": "00000000",
"payer_document_number": "10003550206",
"payer_name": "ISMAEL FATIMA AMARAL",
"payer_request": "Liquidacao de Parcelas",
"receiver_conciliation_id": "fgnb4NTt7pOUBGfrcporERwVVqr0f8PWRfK",
"receiver_url": "qrcodepix.bb.com.br/pix/v2/d373e385-dfe7-49f6-b9ec-14ba60a90000",
"qr_code_status": "active",
"target_account_branch": "1253",
"target_account_digit": "8",
"target_account_number": "107260",
"target_bank_code": 1,
"target_bank_name": "BCO DO BRASIL S.A.",
"target_document_number": "0000000000000",
"target_name": "TESTE LTDA.",
"target_pix_key": "teste.cobrancapix@gmail.com.br",
"presented_at": "2023-03-14T19:07:48.729Z",
"created_at": "2023-03-13T19:00:28.440Z",
},
"qr_code_key": "ffd7d60a-0f2d-4b29-9ae2-7f2b919fa65e",
"qr_code_payload": "00020101021226850014br.gov.bcb.pix2563qrcodepix.bb.com.br/pix/v2/d373e385-dfe7-49f6-b9ec-14ba60a9b8285204001234567895802BR5925TESTE DE JANEIRO62070503***63047B7D",
"qr_code_type": "dynamic_instant"
}
```
### Response Body
| Field | Type | Description | Characters |
|-----------------------------|--------|-------------------------------------------------------------------------|------------|
| `request_control_key` * | string | Unique UUID4 identifier of the request that originated the QR Code. | - |
| `end_to_end_id` * | string | Unique identifier of the Pix transaction, end-to-end. | - |
| `account_type` * | string | Type of origin account. | - |
| `amount` * | float | QR Code amount currently. | - |
| `category_code` * | string | QR Code identifier for reconciliation after payment. | - |
| `expiration_seconds` | string | Indicates the validity time of the QR Code in seconds, default is 1 day | - |
| `ispb_number` * | string | Bank identifier. | - |
| `payer_document_number` * | string | Payer's CPF/ CNPJ. | - |
| `payer_name` * | string | Payer's name. | - |
| `payer_request` * | string | Message to the payer. | - |
| `receiver_conciliation_id` * | string | QR Code identifier for reconciliation after payment. | - |
| `receiver_url` * | string | URL for querying the dynamic QR Code data. | - |
| `qr_code_status` * | string | QR Code status. | - |
| `target_account_branch` * | string | Destination account branch. | - |
| `target_account_digit` * | string | Destination account check digit. | - |
| `target_account_number` * | string | Destination account number. | - |
| `target_bank_code` * | string | Destination bank code. | - |
| `target_bank_name` * | string | Destination bank name. | - |
| `target_document_number` * | string | Collector's CPF/ CNPJ. | - |
| `target_name` * | string | Collector's name. | - |
| `target_trading_name` * | string | Collector's trade name - only for CNPJ. | - |
| `target_pix_key` * | string | Collector's PIX key. | - |
| `qr_code_key` * | string | UUID4 key identifying the QR Code. | - |
| `qr_code_payload` * | string | QR Code copy and paste URL. | - |
| `qr_code_type` * | string | Type of the QR Code. | "static", "dynamic_term", or "dynamic_instant" |
| `max_payment_days` | int32 | Maximum days for paying the charge after due date. | - |
| `expiration_date` | date | Due date of the charge (in the format "YYYY-MM-DD"). | - |
| `fine_amount` | float | Absolute fine amount after the due date. | - |
| `interest_amount` | float | Absolute value per day of delay after the due date. | - |
| `discount_amount` | float | Discount amount. | - |
| `original_amount` | float | Original QR Code amount. | - |
| `additional_data` | array of objects | Information to be presented to the payer. | - |
| `presented_at` * | datetime | Date and time the QR Code was decoded. | - |
| `created_at` * | datetime | Date and time the QR Code was created in the system. | - |
| `rebate_amount` | float | Absolute rebate amount before payment. | - |
### Object qr_code_status
| Field | Type | Description | Characters |
|-----------------|--------|-----------------------------------------------------|------------|
| `active` | string | QR Code is active and available for payment. | - |
| `finished` | string | QR Code has been paid. | - |
| `written_off` | string | QR Code has been canceled by the client. | - |
| `bank_written_off` | string | QR Code was automatically canceled due to expiration. | - |
### Object additional_data
| Field | Type | Description | Characters |
|--------------------|--------|---------------------------|------------|
| `key_name` * | string | Name of the field | - |
| `value` | string | Value of the field | - |
STATUS 400
Response Body: Impossible to decode QR Code
```json
{
"title": "Bad Request",
"description": "Could not decode QR Code.",
"translation": "Não foi possível decodificar o QR Code.",
"code": "QRI000001"
}
```
STATUS 404
Response Body: QR Code not found
```json
{
"title": "Not found",
"description": "Could not find the queried QR Code.",
"translation": "Não possível encontrar o QR Code buscado.",
"code": "QRI000002"
}
```
---
# Update/Deactivate a PIX QR Code
URL: /en/documentation/pix_indireto/qr_code/desativar_qr_code
Only dynamic-type PIX QR Codes can be updated. Upon updating, identified by the qr_code_key generated when creating the QR Code, it becomes invalid for subsequent payments. There are several reasons to request an update of a PIX QR Code, but in the internal system, the deactivation can be performed by a request from the alias (write_off).
## Request
ENDPOINT /account/ ACCOUNT_KEY /alias/ ALIAS_KEY /qrcode/ QR_CODE_KEY
METHOD PATCH
Request Body: Write off QR Code
```json
{
"request_control_key": "76d4506d-31a4-48db-bc71-61068b138ffd",
"qr_code_status": "written_off",
}
```
| Field | Type | Description | Characters |
|-------------------------|--------|-----------------------------------------|------------|
| `request_control_key` * | string | Unique UUID4 identifier of the request. | - |
| `qr_code_status` * | string | QR Code status | - |
### Object qr_code_status
| Field | Type | Description | Characters |
|-----------------|--------|-----------------------------------------------------|------------|
| `active` | string | QR Code is active and available for payment. | - |
| `finished` | string | QR Code has been paid. | - |
| `written_off` | string | QR Code has been canceled by the client. | - |
| `bank_written_off` | string | QR Code was automatically canceled due to expiration. | - |
## Response
STATUS 204 No content
Response Body
```json
{}
```
STATUS 404
Response Body
```json
{
"title": "Not found",
"description": "Could not find the queried QR Code.",
"translation": "Não possível encontrar o QR Code buscado.",
"code": "QRI000002"
}
```
---
# Introduction to PIX QR Code
URL: /en/documentation/pix_indireto/qr_code/introducao_qr_code
Any Indirect Participant (Alias) customer can perform operations for creating, querying, and canceling PIX QR Codes.
- Creation: Static or dynamic QR Codes can be generated. With dynamic QR Codes, it is possible to generate one for instant payment or with a long-term due date. The types will be further explained in the creation process.
- Querying: With a QR Code or the URL of the QR Code (PIX copy and paste), it is possible to query its information for subsequent payment. The query is called QR Code decoding and generates an `end_to_end_id` for subsequent payment.
- Canceling: Canceling a QR Code makes it invalid for payment. The main causes of cancellation are: expired term, QR Code cancellation by alias, or payment.
## Types of QR Codes
The type of QR Code is defined during creation by the `qr_code_type` field.
| Name | Enumerator | Description |
|--------------------------------------|---------------------|---|
| Static | `static` | Contains destination PIX key and may contain value. Can be paid at any time, as long as the key is active. No validity period. Reusable. |
| Dynamic for Instant Payment | `dynamic_instant` | Contains payment information, with defined payer, value, and reconciliation key. Payment term in seconds. Single use. |
| Dynamic with Due Date | `dynamic_term` | Contains payment information, with defined payer, value, and reconciliation key. Payment term in days, with fine and interest information. Single use. |
## Payment of a QR Code
After decoding a QR Code and querying the key, an `end_to_end_id` is generated, which is used in the payment order to finalize the transaction. Additionally, for Dynamic QR Codes, the `receiver_conciliation_id` field is used to identify the specific QR Code being paid, used by the receiver to continue the operation after payment.
When decoding a QR Code, you must send a PIX payment order with the `end_to_end_id` and `receiver_conciliation_id`, and the receiving bank will know how to proceed. Similarly, when receiving a PIX payment of the type `static_qr_code` or `dynamic_qr_code`, a webhook will be sent, also handled at the end of this QR Code section.
---
# List QR Codes of an alias
URL: /en/documentation/pix_indireto/qr_code/listar_alias_qr_codes
The search for QR Codes is used to manage the status of dynamic QR Codes, verify payments, cancellations, etc.
## Request
ENDPOINT /account/ ACCOUNT_KEY /alias/ ALIAS_KEY /qrcodes
METHOD GET
### Path params
| Field | Type | Description | Characters |
|----------------------|---------|-------------------------------------------|------------|
| `page` | integer | Page number being searched (default = 0) | - |
| `page_size` | integer | Number of items per page (default = 15) | - |
| `qr_code_status` | string | Status of the searched QR codes | - |
| `qr_code_type` | string | Type of the searched QR codes | - |
| `request_control_key`| string | Request control key that originated the QR code | - |
## Response
STATUS 200 Ok
Response Body: General
```json
{
"data":[
{
"request_control_key":"037b46b1-0c67-4c0d-aac3-1e395dfdcb10",
"pix_key":"3d7d6a2b-f72f-44z7-bb20-79a94dff5645",
"receiver_conciliation_id":"01GVGV9NXBCY287Z6CJ4S0ENW9",
"qr_code_key":"d74bf12a-9243-4bfa-9b00-6b63755b6555",
"qr_code_status":"active",
"qr_code_type":"dynamic_instant",
"amount":22.34,
"expiration_seconds":864000,
"expiration_date":null,
"max_payment_days":null,
"payer_name":"João da Silva",
"payer_document_number":"00000000000000",
"payer_request":"Payment for order XXXXXXXXXXXX",
"rebate_amount":1,
"interest_amount":2,
"fine_amount":3,
"discounts":[
],
"additional_data":[
{
"key_name":"Juros e Multa",
"value":"Juros 2 ao mes e multa de 1%"
},
],
"pix_transfer_key":null,
"paid_amount":null,
"base_64_payload":"",
"qr_code_events":[
{
"request_control_key":"037b46b1-0c67-4c0d-aac3-1e395dfdcb10",
"event_type":"registration",
"created_at":"2023-03-03T12:04:06.179Z"
},
{
"request_control_key":"cae915c8-1940-43ec-890b-ba1a3a66354c",
"event_type":"payment",
"created_at":"2023-03-03T12:04:06.179Z"
},
],
"created_at":"2023-03-03T12:04:06.179Z"
},
],
"pagination":{
"current_page":1,
"rows_per_page":30
},
},
```
| Field | Type | Description | Characters |
|-----------------------------|--------|-------------------------------------------------------------------------|------------|
| `request_control_key` * | string | Unique UUID4 identifier of the request that originated the QR Code. | - |
| `pix_key` * | string | PIX key representing the destination account of the transaction. | - |
| `receiver_conciliation_id` *| string | QR Code identifier for reconciliation after payment. | - |
| `qr_code_key` * | string | UUID4 key identifying the QR Code. | - |
| `qr_code_status` * | string | QR Code status. | - |
| `qr_code_type` * | string | QR Code type. | "dynamic_term" or "dynamic_instant" |
| `amount` * | float | QR Code amount before calculating discounts or interest and fines. | - |
| `expiration_seconds` | string | Indicates the validity time of the QR Code in seconds, default is 1 day | - |
| `expiration_date` | date | Due date of the charge (in the format "YYYY-MM-DD"). | - |
| `max_payment_days` | int32 | Maximum days for paying the charge after due date. | - |
| `payer_name` * | string | Payer's name. | - |
| `payer_document_number` * | string | Payer's CPF/ CNPJ. | - |
| `payer_request` * | string | Message to the payer. | - |
| `rebate_amount` | float | Absolute rebate amount before payment. | - |
| `interest_amount` | float | Absolute value per day of delay after the due date. | - |
| `fine_amount` | float | Absolute fine amount after the due date. | - |
| `discounts` | array of objects | Discount settings. | - |
| `additional_data` | array of objects | Information to be presented to the payer. | - |
| `pix_transfer_key` | string | UUID4 key identifying the PIX transaction corresponding to the QR Code settlement. | - |
| `paid_amount` | float | Amount of the payment made, considering fines, discounts, and others. | - |
| `base_64_payload` | string | URL of the QR Code for payment in base64. | - |
| `qr_code_events` | array of objects | List of status changes the QR Code has undergone. | - |
| `created_at` | datetime | Date and time the QR Code was created in the system. | - |
### Object qr_code_status
| Field | Type | Description | Characters |
|-----------------|--------|-----------------------------------------------------|------------|
| `active` | string | QR Code is active and available for payment. | - |
| `finished` | string | QR Code has been paid. | - |
| `written_off` | string | QR Code has been canceled by the client. | - |
| `bank_written_off` | string | QR Code was automatically canceled due to expiration. | - |
### Object discount
| Field | Type | Description | Characters |
|---------------------|--------|--------------------------|------------|
| `discount_value` * | float | Discount amount. | - |
| `discount_number` | int32 | Order in which the discount should be applied. | - |
| `discount_limit_date` * | string | Discount limit date. | - |
### Object additional_data
| Field | Type | Description | Characters |
|--------------------|--------|---------------------------|------------|
| `key_name` * | string | Name of the field | - |
| `value` | string | Value of the field | - |
### Object qr_code_events
| Field | Type | Description | Characters |
|-------------------------|----------|----------------------------------------------------------|------------|
| `request_control_key` * | string | Unique UUID4 identifier of the request that originated the event. | - |
| `event_type` * | string | Event type | "registration", "write_off", "payment" |
| `created_at` * | datetime | Date and time the event was created. | - |
STATUS 404
Response Body
```json
{
"title": "Not found",
"description": "Could not find the queried QR Code.",
"translation": "Não possível encontrar o QR Code buscado.",
"code": "QRI000002"
}
```
---
# Webhook for Incoming PIX Payment of QR Code
URL: /en/documentation/pix_indireto/qr_code/webhook_incoming_pix
Webhook to notify about PIX transactions received for an Alias linked to a QR Code payment.
## Webhook Request Body
**Request Body: Received QR Code payment**
```json
{
"webhook_type": "baas.pix_qr_code.payment",
"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",
"qr_code_key": "8cb70dea-9fb0-4a68-9572-99a72849c8d6",
"qr_code_type": "dynamic_instant",
"receiver_conciliation_id": "faf1ef5b-e0a9-4430-8aa4-367b4825854c",
"amount": 10.63,
"updated_at": "2021-10-22T20:30:23.459Z"
}
}
```
### Webhook Body Param
| Field | Type | Description | Characters |
|-----------------------------|----------|------------------------------------------------------------|------------|
| `request_control_key` * | string | Unique UUID4 identifier of the request that originated the QR Code. | - |
| `pix_transfer_key` * | string | PIX key representing the destination account of the transaction. | - |
| `qr_code_key` * | string | UUID4 key identifying the QR Code. | - |
| `qr_code_type` * | string | Type of the QR Code. | "static", "dynamic_term", or "dynamic_instant" |
| `receiver_conciliation_id` *| string | QR Code identifier for reconciliation after payment. | - |
| `amount` * | string | Payment amount. | - |
| `updated_at` * | datetime | Date and time the QR Code payment was made. | - |
---
# Cancel Infraction Report
URL: /en/documentation/pix_indireto/relato_de_infracao/cancelar_relato_infracao
If an Infraction Report request was generated erroneously and the Indirect Participant wishes to cancel it, this can be done using the endpoint mentioned below.
:::danger IMPORTANT
It is emphasized that only the Participant who CREATED the Infraction Report can cancel it, and the cancellation can be made even if the infraction status is closed.
:::
:::info IMPORTANT
Canceled infraction reports can be listed using the endpoint [List Infraction Reports](#list-infraction-reports).
:::
## Request
ENDPOINT /pix/infraction_report/ INFRACTION_REPORT_KEY
METHOD PATCH
**Request Body**
```json
{
"infraction_report_status": "cancelled",
"request_control_key": "750cbfa0-f628-4944-a76c-9053bf1ebc87",
}
```
### Path Params
| Field | Type | Description | Characters |
|-------------------------|--------|------------------------------------------------------------------|------------|
| `infraction_report_key` | string | UUID4 of the Infraction Report created that is to be canceled. | 36 |
### Body Params
| Field | Type | Description | Characters |
|--------------------------|--------|------------------------------------------------------------------|------------|
| `infraction_report_status` * | string | Status to which the Infraction Report should be updated | 36 |
| `request_control_key` * | string | Unique identification key for the request used by the client in uuid v4 format | 36 |
## Response
STATUS 200
**Response Body**
```json
{
"infraction_report_key":"d7820e2f-1c23-4610-83d6-d9aad1845075",
"pix_transfer_key":"cdcf0d25-08a1-46e3-902a-6d7ca75e6c48",
"end_to_end_id":"E99999011202406251332F8n7dMUwOLE",
"infraction_report_status":"cancelled",
"infraction_report_situation":"scam",
"infraction_report_type":"refund_request",
"infraction_report_details":"usuario caiu em golpe…",
"debited_participant":"99999010",
"credited_participant":"99999011",
"infraction_report_direction": "outgoing",
"created_at": "2023-03-03T12:04:06.179Z",
"updated_at": "2023-03-03T12:05:03.421Z"
}
```
### Body Params| Field | Type | Description | Characters |
|-------------------------------|--------|--------------------------------------------------------------------------|------------|
| `infraction_report_key` * | string | Unique identifier of the infraction report. | 36 |
| `pix_transfer_key` * | string | Unique identifier of the PIX transaction. | 36 |
| `end_to_end_id` * | string | Unique identifier of the PIX transaction at BACEN. | 36 |
| `infraction_report_status` * | enum | Status of the Infraction Report | **[Enumerators infraction_report_status](#enumerators-infraction_report_status)** |
| `infraction_report_situation` *| enum | Situation in which the infraction occurred. | **[Enumerators infraction_report_situation](#enumerators-infraction_report_situation)** |
| `infraction_report_type` * | enum | Type of Infraction Report. | **[Enumerators infraction_report_type](#enumerators-infraction_report_type)** |
| `infraction_report_details` | string | Details about the created Infraction Report. | Less or equal 2000 |
| `credited_participant` * | string | ISPB of the Credited Participant. | 8 |
| `debited_participant` * | string | ISPB of the Debited Participant. | 8 |
| `infraction_report_direction` * | enum | Enumerator on whether the report was opened by the Indirect Participant or another Participant | **[Enumerators infraction_report_direction](#enumerators-infraction_report_direction)** |
| `created_at` * | string | Infraction Report creation date. | 24 |
| `updated_at` | string | Infraction Report update date. | 24 |
### Enumerators infraction_report_status
| Field | Type | Description | Characters |
| -------------- | ------ | ------------------------------------------------------------------------------ |------------|
| `open` | string | Infraction report was created and is open at BACEN. | - |
| `acknowledged` | string | Infraction report was received by the contested participant. | - |
| `cancelled` | string | Infraction report is cancelled at BACEN. | - |
| `closed` | string | Infraction report is closed at BACEN. | - |
### Enumerators infraction_report_situation
| Field | Type | Description | Characters |
|----------------------|--------|----------------------------------------------------------------------- |------------|
| `scam` | string | Cause of scam or fraud. | - |
| `account_takeover` | string | Cause of unauthorized transaction from the origin account. | - |
| `coercion` | string | Cause of coercion crime. | - |
| `fraudulent_access` | string | Cause of fraudulent access to the origin account. | - |
| `other` | string | Any causes not applicable to those listed above. | - |
### Enumerators infraction_report_type
| Field | Type | Description | Characters |
|--------------------|--------|--------------------------------------------------------------------|------------|
| `refund_request` | string | Infraction report will be generated to request a refund. | - |
| `refund_cancelled` | string | Infraction report will be generated due to a cancelled refund. | - |
### Enumerators infraction_report_direction
| Field | Type | Description | Characters |
| ----------- | ------ | ------------------------------------------------------------ |------------|
| `incoming` | string | Infraction report with the indirect participant as the target.| - |
| `outgoing` | string | Infraction report with the indirect participant as the originator.| - |
---
# Consult Infraction Report
URL: /en/documentation/pix_indireto/relato_de_infracao/consultar_relato_infracao
The Indirect Participant can query data about an Infraction Report, including all changes that have occurred to it.
## Request
ENDPOINT /pix/infraction_report/ INFRACTION_REPORT_KEY
METHOD GET
### Path Params
| Field | Type | Description | Characters |
|-------------------------|--------|------------------------------------------|------------|
| `infraction_report_key` | string | UUID4 of the Infraction Report. | 36 |
## Response
STATUS 200
**Response Body**
```json
{
"infraction_report_key":"d7820e2f-1c23-4610-83d6-d9aad1845075",
"pix_transfer_key":"cdcf0d25-08a1-46e3-902a-6d7ca75e6c48",
"end_to_end_id":"E99999010202406251332F8n7dMUwOLE",
"infraction_report_status":"cancelled",
"infraction_report_situation":"scam",
"infraction_report_type":"refund_request",
"report_details":"usuario caiu em golpe…",
"debited_participant":"99999011",
"credited_participant":"99999010",
"infraction_report_direction": "incoming",
"infraction_report_events": [
{
"event_type": "acknowledged",
"event_details": "Relato de Infração recebido e em análise",
"created_at": "2023-03-03T12:04:06.179Z"
},
{
"event_type": "cancelled",
"event_details": "Relato de Infração cancelado",
"created_at": "2023-03-03T12:04:06.179Z"
}
],
"created_at": "2023-03-03T12:04:06.179Z",
"updated_at": "2023-03-03T12:04:06.179Z"
}
```
### Body Params
| Field | Type | Description | Characters |
|-------------------------------|--------|--------------------------------------------------------------------------|------------|
| `infraction_report_key` * | string | Unique identifier of the infraction report. | 36 |
| `pix_transfer_key` * | string | Unique identifier of the PIX transaction. | 36 |
| `end_to_end_id` * | string | Unique identifier of the PIX transaction at BACEN. | 36 |
| `infraction_report_status` * | enum | Status. | **[Enumerators infraction_report_status](#enumerators-infraction_report_status)** |
| `infraction_report_situation` *| enum | Situation in which the infraction occurred. | **[Enumerators infraction_report_situation](#enumerators-infraction_report_situation)** |
| `infraction_report_type` * | enum | Type of Infraction Report. | **[Enumerators infraction_report_type](#enumerators-infraction_report_type)** |
| `infraction_report_details` | string | Details about the created Infraction Report. | Less or equal 2000 |
| `credited_participant` * | string | ISPB of the Credited Participant. | 8 |
| `debited_participant` * | string | ISPB of the Debited Participant. | 8 |
| `infraction_report_direction` * | enum | Enumerator on whether the report was opened by the Indirect Participant or another Participant | **[Enumerators infraction_report_direction](#enumerators-infraction_report_direction)** |
| `infraction_report_events` * | object | Events related to the Infraction Report. | **[Objects infraction_report_events](#objects-infraction_report_events)** |
| `created_at` * | string | Infraction Report creation time. | 24 |
| `updated_at` | string | Infraction Report update time. | 24 |
### Enumerators infraction_report_status
| Field | Type | Description | Characters |
| -------------- | ------ | ------------------------------------------------------------------------------ |------------|
| `open` | string | Infraction report was created and is open at BACEN. | 4 |
| `acknowledged` | string | Infraction report was received by the contested participant. | 12 |
| `cancelled` | string | Infraction report is cancelled at BACEN. | 9 |
| `closed` | string | Infraction report is closed at BACEN. | 6 |
### Enumerators infraction_report_situation
| Field | Type | Description | Characters |
|----------------------|--------|-------------------------------------------|------------|
| `scam` | string | Cause of scam or fraud. | - |
| `account_takeover` | string | Cause of unauthorized transaction from the origin account. | - |
| `coercion` | string | Cause of coercion crime. | - |
| `fraudulent_access` | string | Cause of fraudulent access to the origin account. | - |
| `other` | string | Any causes not applicable to those listed above. | - |
### Enumerators infraction_report_type
| Field | Type | Description | Characters |
|--------------------|--------|--------------------------------------------------------------------|------------|
| `refund_request` | string | Infraction report will be generated to request a refund. | - |
| `refund_cancelled` | string | Infraction report will be generated due to a cancelled refund. | - |
### Enumerators infraction_report_direction
| Field | Type | Description | Characters |
| ----------- | ------ | ------------------------------------------------------------ |------------|
| `incoming` | string | Infraction report with the indirect participant as the target.| - |
| `outgoing` | string | Infraction report with the indirect participant as the originator.| - |
### Objects infraction_report_events
| Field | Type | Description | Characters |
|------------------- |--------|-----------------------------------------------|------------|
| `event_type` | enum | Status change related to the event. | **[Enumerators infraction_report_status](#enumerators-infraction_report_status)** |
| `event_details` | string | Description of the event. | - |
| `created_at` * | string | Event creation time. | 24 |
---
# Open Infraction Report
URL: /en/documentation/pix_indireto/relato_de_infracao/criar_relato_infracao
The Infraction Report is one of the services that composes the Special Refund Mechanism (MED) as defined by the Central Bank of Brazil.
When there is an indication of a fraudulent transaction, refund request, or refund cancellation request, it is possible to create an infraction report to inform BACEN and the other Participant that there is an irregularity in one of these operations mentioned.
Both the debited Participant and the credited Participant can create an Infraction Report.
:::caution **Attention**
To understand the Infraction Report flow, it is necessary to know which ENDPOINTS the Indirect Participant who created the report can use.
When the Indirect Participant opens an Infraction Report, they can (if necessary) cancel the report if it was generated improperly.
When the Indirect Participant receives an Infraction Report, they must close it by informing the result of the report analysis.
Both cited flows will be described in the following sections.
:::
:::danger IMPORTANT
The Central Bank of Brazil requires that, within a period of 7 days from receiving the Infraction Report by the Indirect Participant, the Report must be closed .
If there is a delay on the part of the Indirect Participant, QI Tech will close the Infraction Report with the status of agreed , to ensure the institution is not penalized by the Central Bank of Brazil.
:::
:::info IMPORTANT
Only the originator of the transfer can create an infraction report about it.
:::
## Request
ENDPOINT /pix/infraction_report
METHOD POST
**Request Body**
```json
{
"pix_transfer_key": "c09fef15-ab30-469c-a1d4-4e9dd479943a",
"request_control_key": "c09fef15-ab30-469c-a1d4-4e9dd479943a",
"infraction_report_type": "refund_request",
"infraction_report_details": "Foi identificado uma fraude na transação",
"infraction_report_situation": "scam"
}
```
### Body Params
| Field | Type | Description | Characters |
|----------------------------|--------|----------------------------------------------------|------------|
| `request_control_key` * | uuidv4 | UUID4 for querying about the made request. | 36 |
| `pix_transfer_key` * | uuidv4 | Unique identifier of the PIX transaction. | 36 |
| `infraction_report_type` * | enum | Type of infraction report to be created. | **[Enumerators infraction_report_type](#enumerators-infraction_report_type)** |
| `infraction_report_details`| string | Details about the infraction report to be created. | 10 |
| `infraction_report_situation` | string | Situation in which the infraction occurred. | **[Enumerators infraction_report_situation](#enumerators-infraction_report_situation)** |
### Enumerators infraction_report_type
| Field | Type | Description | Characters |
|--------------------|--------|----------------------------------------------------------------------------- |------------|
| `refund_cancelled` | string | Infraction report will be generated due to a cancelled refund | 16 |
| `refund_request` | string | Infraction report will be generated to request a refund | 14 |
### Enumerators infraction_report_situation
| Field | Type | Description | Characters |
|----------------------|--------|----------------------------------------------------------------------- |------------|
| `scam` | string | Cause of scam or fraud. | - |
| `account_takeover` | string | Cause of unauthorized transaction from the origin account. | - |
| `coercion` | string | Cause of coercion crime. | - |
| `fraudulent_access` | string | Cause of fraudulent access to the origin account. | - |
| `other` | string | Any causes not applicable to those listed above. | - |
## Response
STATUS 200
**Response Body**
```json
{
"infraction_report_key":"d7820e2f-1c23-4610-83d6-d9aad1845075",
"pix_transfer_key":"cdcf0d25-08a1-46e3-902a-6d7ca75e6c48",
"end_to_end_id":"E99999010202406251332F8n7dMUwOLE",
"infraction_report_status":"acknowledged",
"infraction_report_situation":"scam",
"infraction_report_type":"refund_request",
"report_details":"usuario caiu em golpe…",
"debited_participant":"99999011",
"credited_participant":"99999010",
"infraction_report_direction": "outgoing",
"created_at": "2023-03-03T12:04:06.179Z",
"updated_at": "2023-03-03T12:04:06.179Z"
}
```
### Body Params
| Field | Type | Description | Characters |
| -------------------------------| ------ | ------------------------------------------------------------------------ |------------|
| `infraction_report_key` * | string | Unique identifier of the infraction report. | 36 |
| `pix_transfer_key` * | string | Unique identifier of the PIX transaction. | 36 |
| `end_to_end_id` * | string | Unique identifier of the PIX transaction at BACEN. | 36 |
| `infraction_report_status` * | enum | Status. | **[Enumerators infraction_report_status](#enumeradores-infraction_report_status)** |
| `infraction_report_situation` *| enum | Situation in which the infraction occurred. | **[Enumerators infraction_report_situation](#enumeradores-infraction_report_situation)** |
| `infraction_report_type` * | enum | Type of Infraction Report. | **[Enumerators infraction_report_type](#enumeradores-infraction_report_type)** |
| `infraction_report_details` | string | Details about the created Infraction Report. | \<\= 2000 |
| `credited_participant` * | string | ISPB of the Credited Participant. | 8 |
| `debited_participant` * | string | ISPB of the Debited Participant. | 8 |
| `infraction_report_direction` *| enum | Enumerator on whether the report was opened by the Indirect Participant or another Participant | **[Enumerators infraction_report_direction](#enumeradores-infraction_report_direction)** |
| `created_at` * | string | Infraction Report creation time. | 24 |
| `updated_at` | string | Infraction Report update time. | 24 |
### Enumerators infraction_report_status
| Field | Type | Description | Characters |
| -------------- | ------ | ------------------------------------------------------------------------------ |------------|
| `open` | string | Infraction report was created and is open at BACEN. | - |
| `acknowledged` | string | Infraction report was received by the contested participant. | - |
| `cancelled` | string | Infraction report is cancelled at BACEN. | - |
| `closed` | string | Infraction report is closed at BACEN. | - |
### Enumerators infraction_report_direction
| Field | Type | Description | Characters |
| ----------- | ------ | ------------------------------------------------------------ |------------|
| `incoming` | string | Infraction report with the indirect participant as the target.| - |
| `outgoing` | string | Infraction report with the indirect participant as the originator.| - |
---
# Close Infraction Report
URL: /en/documentation/pix_indireto/relato_de_infracao/fechar_relato_infracao
QI Tech will be responsible for conducting a polling with the Central Bank of Brazil to check if there are any Infraction Reports created by other Participants for the Indirect Participant, and will send the receipt webhook with the status acknowledged .
To inform the Indirect Participant that there is an Infraction Report to be responded to, QI Tech will send a receipt webhook .
:::danger IMPORTANT
It is emphasized that only the Participant who RECEIVED the Infraction Report can close it.
:::
:::danger IMPORTANT
The Central Bank of Brazil defines that within a period of 7 days from receiving the Infraction Report by the Indirect Participant, the Report must be closed .
If there is a delay on the part of the Indirect Participant, QI Tech will close the Infraction Report with the status of agreed, 6 calendar days after sending the receipt of infraction webhook, to ensure the institution is not penalized by the Central Bank of Brazil.
:::
To close the infraction report, the status must be acknowledged .
## Request
ENDPOINT /pix/infraction_report/ INFRACTION_REPORT_KEY
METHOD PATCH
**Request Body - Agreed**
```json
{
"infraction_report_status": "closed",
"request_control_key": "feb59932-be7a-4584-9830-02ed8bc0aa77",
"analysis_result": "agreed",
"fraud_type": "application_fraud",
"analysis_details": "Valor bloqueado. Para mais informações ligue para (11) 98871-1385.",
}
```
**Request Body - Disagreed**
```json
{
"infraction_report_status": "closed",
"request_control_key": "feb59932-be7a-4584-9830-02ed8bc0aa77",
"analysis_result": "disagreed",
"analysis_details": "Valor bloqueado. Para mais informações ligue para (11) 98871-1385.",
}
```
### Path Params
| Field | Type | Description | Characters |
|-------------------------|--------|------------------------------------------------------------------|------------|
| `infraction_report_key` | string | UUID4 of the created Infraction Report to be closed. | 36 |
### Body Params
| Field | Type | Description | Characters |
|--------------------------|--------|------------------------------------------------------------------|------------|
| `analysis_result` * | enum | Result of the analysis. | **[Enumerators analysis_result](#enumeradores-analysis_result)** |
| `request_control_key` * | uuidv4 | UUID4 for querying about the made request. | 36 |
| `infraction_report_status` * | enum | Status to be set for the infraction report. | **[Enumerators infraction_report_status](#enumeradores-infraction_report_status)** |
| `fraud_type` | enum | Type of fraud detected. Not part of the infraction report entity but necessary for closure. | **[Enumerators fraud_type](#enumeradores-fraud_type)** |
| `analysis_details` | string | Description of the analysis result | 250 |
### Enumerators analysis_result
| Field | Type | Description | Characters |
|-------------|--------|--------------------------------------------------------------------------------------|------------|
| `agreed` | string | The Indirect Participant agrees with the Infraction Report created by the other Participant. | - |
| `disagreed` | string | The Indirect Participant disagrees with the Infraction Report created by the other Participant. | - |
### Enumerators infraction_report_status
| Field | Type | Description | Characters |
|-----------------|--------|-----------------------------------------------------------------------------|------------|
| `open` | string | Infraction report was created and is open at BACEN. | - |
| `acknowledged` | string | Infraction report was received by the participant | - |
| `cancelled` | string | Infraction report is cancelled at BACEN | - |
| `closed` | string | Infraction report is closed at BACEN | - |
### Enumerators fraud_type
| Field | Type | Description | Characters |
|--------------------|--------|-----------------------------------------------------------------------|------------|
| `application_fraud`| string | Fraud by identity theft, with documents of another person. | - |
| `mule_account` | string | Fraud through mule account, opened legitimately. | - |
| `scammer_account` | string | Fraud in which the destination account is in the name of the real fraudster. | - |
| `other` | string | Fraud of a different nature, not fitting the above enumerators. | - |
## Response
STATUS 200
**Response Body**
```json
{
"infraction_report_key":"d7820e2f-1c23-4610-83d6-d9aad1845075",
"pix_transfer_key":"cdcf0d25-08a1-46e3-902a-6d7ca75e6c48",
"end_to_end_id":"E99999011202406251332F8n7dMUwOLE",
"infraction_report_status":"cancelled",
"infraction_report_situation":"scam",
"infraction_report_type":"refund_request",
"infraction_report_details":"usuario caiu em golpe…",
"debited_participant":"99999010",
"credited_participant":"99999011",
"analysis_result": "agreed",
"analysis_details": "Valor bloqueado. Para mais informações ligue para (11) 98871-1385.",
"infraction_report_direction": "incoming",
"created_at": "2023-03-03T12:04:06.179Z",
"updated_at": "2023-03-03T12:05:03.421Z",
}
```
### Body Params
| Field | Type | Description | Characters |
|---------------------------|--------|-------------------------------------------------------------------|------------|
| `infraction_report_key` * | string | Unique identifier of the infraction report. | 36 |
| `pix_transfer_key` * | string | Unique identifier of the PIX transaction. | 36 |
| `end_to_end_id` * | string | Unique identifier of the PIX transaction at BACEN. | 36 |
| `infraction_report_status` * | enum | Status of the Infraction Report | **[Enumerators infraction_report_status](#enumeradores-infraction_report_status)** |
| `infraction_report_situation` * | enum | Situation in which the infraction occurred. | **[Enumerators infraction_report_situation](#enumeradores-infraction_report_situation)** |
| `infraction_report_type` * | enum | Type of Infraction Report | **[Enumerators infraction_report_type](#enumeradores-infraction_report_type)** |
| `infraction_report_details` | string | Details about the created Infraction Report | Less or equal 2000 |
| `credited_participant` * | string | ISPB of the Credited Participant | 8 |
| `debited_participant` * | string | ISPB of the Debited Participant | 8 |
| `analysis_result` * | string | Result of the analysis | **[Enumerators analysis_result](#enumeradores-analysis_result)** |
| `analysis_details` * | string | Description of the analysis result | 250 |
| `infraction_report_direction` * | enum | Enumerator on whether the report was opened by the Indirect Participant or another Participant | **[Enumerators infraction_report_direction](#enumeradores-infraction_report_direction)** |
| `created_at` * | string | Infraction Report creation date | 24 |
| `updated_at` | string | Infraction Report update date | 24 |
### Enumerators infraction_report_situation
| Field | Type | Description | Characters |
|---------------------|--------|-------------------------------------------------------|------------|
| `scam` | string | Cause of scam or fraud. | - |
| `account_takeover` | string | Cause of unauthorized transaction from the origin account. | - |
| `coercion` | string | Cause of coercion crime. | - |
| `fraudulent_access` | string | Cause of fraudulent access to the origin account. | - |
| `other` | string | Any causes not applicable to those listed above. | - |
### Enumerators infraction_report_type
| Field | Type | Description | Characters |
|--------------------|--------|---------------------------------------------------|------------|
| `refund_request` | string | Infraction report will be generated to request a refund | - |
| `refund_cancelled` | string | Infraction report will be generated due to a cancelled refund | - |
### Enumerators infraction_report_direction
| Field | Type | Description | Characters |
| ----------- | ------ | ------------------------------------------------------------------------|------------|
| `incoming` | string | Infraction report with the indirect participant as the target. | - |
| `outgoing` | string | Infraction report with the indirect participant as the originator.| - |
### Enumerators analysis_result
| Field | Type | Description | Characters |
| ----------- | ------ | ------------------------------------------------------------------------ |------------|
| `agreed` | string | The Indirect Participant agrees with the Infraction Report created by the other Participant. | - |
| `disagreed` | string | The Indirect Participant disagrees with the Infraction Report created by the other Participant. | - |
### Enumerators infraction_report_status
| Field | Type | Description | Characters |
|-----------------|--------|-----------------------------------------------------------------------------|------------|
| `open` | string | Infraction report was created and is open at BACEN. | - |
| `acknowledged` | string | Infraction report was received by the participant | - |
| `cancelled` | string | Infraction report is cancelled at BACEN | - |
| `closed` | string | Infraction report is closed at BACEN | - |
---
# List Infraction Reports
URL: /en/documentation/pix_indireto/relato_de_infracao/listar_relatos
If the Indirect Participant requests a listing of Infraction Reports, they can do so through the route below.
## Request
ENDPOINT /pix/infraction_reports
METHOD GET
### Query Params
| Field | Type | Description | Characters |
|-------------------------|---------|-----------------------------------|------------|
| `infraction_report_status` | enum | Status of the Infraction Report. | **[Enumerators infraction_report_status](#enumeradores-infraction_report_status)** |
| `infraction_report_type` | enum | Type of the Infraction Report. | **[Enumerators infraction_report_type](#enumeradores-infraction_report_type)** |
| `initial_date` | string | Start search date. | **[Date format](#date-format)** |
| `final_date` | string | End search date. | **[Date format](#date-format)** |
| `page_number` | integer | Current page being queried. | - |
| `page_size` | integer | Number of results per page. | - |
### Date format
| Field | Type | Description | Characters |
|--------------|--------|--------------------------------------------------------------------------|------------|
| `initial_date` | string | Start search date, in the format "%Y-%m-%d". Example: "2023-10-09". | 10 |
| `final_date` | string | End search date, in the format "%Y-%m-%d". Example: "2023-10-11". | 10 |
## Response
STATUS 200
**Response Body**
```json
{
"data": [
{
"infraction_report_key":"2b4b262d-fa31-4bb5-87f9-52ef1d243275",
"pix_transfer_key":"16125a82-1842-4f29-a895-c80e14c70e44",
"end_to_end_id":"E99999010202406251332F8n7dMUwOLE",
"infraction_report_status":"cancelled",
"infraction_report_situation":"scam",
"infraction_report_type":"refund_request",
"report_details":"usuario caiu em golpe…",
"debited_participant":"99999011",
"credited_participant":"99999010",
"infraction_report_direction": "incoming",
"infraction_report_events": [
{
"event_type": "acknowledged",
"event_details": "Relato de Infração recebido e em análise",
"created_at": "2023-03-03T12:04:06.179Z"
},
{
"event_type": "cancelled",
"event_details": "Relato de Infração cancelado",
"created_at": "2023-03-03T12:04:06.179Z"
}
],
"created_at": "2023-03-03T12:04:06.179Z",
"updated_at": "2023-03-03T12:04:06.179Z"
},
{
"infraction_report_key":"facb89f7-49bb-41fd-8a4d-98792880a6f2",
"pix_transfer_key":"a913cfb4-0c4a-4069-99f2-7ab34b6a4bf9",
"end_to_end_id":"E99999010202406251332F8n7dMUwOLA",
"infraction_report_status":"acknowledged",
"infraction_report_situation":"scam",
"infraction_report_type":"refund_request",
"report_details":"usuario caiu em golpe de novo…",
"debited_participant":"99999011",
"credited_participant":"99999010",
"infraction_report_direction": "incoming",
"infraction_report_events": [
{
"event_type": "acknowledged",
"event_details": "Relato de Infração recebido e em análise",
"created_at": "2023-03-03T12:04:06.179Z"
},
],
"created_at": "2023-03-03T12:04:06.179Z",
"updated_at": "2023-03-03T12:04:06.179Z"
},
],
"pagination": {
"current_page": 1,
"next_page": null,
"rows_per_page": 10
}
}
```
### Body Params
| Field | Type | Description | Characters |
|-------------------------------|--------|--------------------------------------------------------------------------|------------|
| `infraction_report_key` * | string | Unique identifier of the infraction report. | 36 |
| `pix_transfer_key` * | string | Unique identifier of the PIX transaction. | 36 |
| `end_to_end_id` * | string | Unique identifier of the PIX transaction at BACEN. | 36 |
| `infraction_report_status` * | enum | Status. | **[Enumerators infraction_report_status](#enumeradores-infraction_report_status)** |
| `infraction_report_situation` *| enum | Situation in which the infraction occurred. | **[Enumerators infraction_report_situation](#enumeradores-infraction_report_situation)** |
| `infraction_report_type` * | enum | Type of Infraction Report. | **[Enumerators infraction_report_type](#enumeradores-infraction_report_type)** |
| `infraction_report_details` | string | Details about the created Infraction Report. | Less or equal 2000 |
| `credited_participant` * | string | ISPB of the Credited Participant. | 8 |
| `debited_participant` * | string | ISPB of the Debited Participant. | 8 |
| `infraction_report_direction` * | enum | Enumerator on whether the report was opened by the Indirect Participant or another Participant | **[Enumerators infraction_report_direction](#enumeradores-infraction_report_direction)** |
| `infraction_report_events` * | object | Events related to the Infraction Report. | **[Objects infraction_report_events](#objetos-infraction_report_events)** |
| `created_at` * | string | Infraction Report creation time. | 24 |
| `updated_at` | string | Infraction Report update time. | 24 |
### Enumerators infraction_report_status
| Field | Type | Description | Characters |
| -------------- | ------ | ------------------------------------------------------------------------------- |------------|
| `open` | string | Infraction report was created and is open at BACEN. | 4 |
| `acknowledged` | string | Infraction report was received by the contested participant. | 12 |
| `cancelled` | string | Infraction report is cancelled at BACEN. | 9 |
| `closed` | string | Infraction report is closed at BACEN. | 6 |
### Enumerators infraction_report_situation
| Field | Type | Description | Characters |
| ------------------- | ------ | ------------------------------------------------------|------------|
| `scam` | string | Cause of scam or fraud. | - |
| `account_takeover` | string | Cause of unauthorized transaction from the origin account. | - |
| `coercion` | string | Cause of coercion crime. | - |
| `fraudulent_access` | string | Cause of fraudulent access to the origin account. | - |
| `other` | string | Any causes not applicable to those listed above. | - |
### Enumerators infraction_report_type
| Field | Type | Description | Characters |
| ------------------ | ------ | -------------------------------------------------- |------------|
| `refund_request` | string | Infraction report will be generated to request a refund | - |
| `refund_cancelled` | string | Infraction report will be generated due to a cancelled refund | - |
### Enumerators infraction_report_direction
| Field | Type | Description | Characters |
| ----------- | ------ | ------------------------------------------------------------------------|------------|
| `incoming` | string | Infraction report with the indirect participant as the target. | - |
| `outgoing` | string | Infraction report with the indirect participant as the originator.| - |
### Objects infraction_report_events
| Field | Type | Description | Characters |
| -------------|--------|-----------------------------------------------|------------|
| `event_type` | enum | Status change related to the event. | **[Enumerators infraction_report_status](#enumeradores-infraction_report_status)** |
| `event_details` | string | Description of the event. | - |
| `created_at` | string | Event creation time. | 24 |
---
# Introduction to the Infraction Report Flow
URL: /en/documentation/pix_indireto/relato_de_infracao/maquina_estados
## Introduction
The Central Bank of Brazil allows that if there is an infraction in a PIX transaction, whether a common transaction or a refund, the Indirect Participant can inform the other Participant involved in the flow that there is an irregularity.
:::info
It is emphasized that, for a PIX transaction, only the credited Participant can open an Infraction Report.
:::
:::danger IMPORTANT
The Central Bank of Brazil defines that within a period of 7 days from receiving the Infraction Report by the Indirect Participant, the Report must be closed .
If there is a delay on the part of the Indirect Participant, QI Tech will close the Infraction Report with the status of agreed, 6 calendar days after sending the receipt of infraction webhook, to ensure the institution is not penalized by the Central Bank of Brazil.
:::
## Infraction_Report_Status State Machine
| Enumerator | Translation | Description|
|---|---|---|
| open | open | After processing the creation of the Infraction Report, it remains open at BACEN.
| acknowledged | received | QI Tech received an Infraction Report targeting the Indirect Participant and will forward it (report) via webhook.
| cancelled | cancelled | The Participant who opened the report sent the cancellation, and it is cancelled at BACEN.
| closed | closed | The closure of the Infraction Report was processed by QI Tech and is closed at BACEN.
## Infraction_Report_Status State Machine Control
Even though the flow is synchronous, it is necessary for the Indirect Participant to know the statuses an Infraction Report can have. Below, we describe what the Participant can expect after opening, cancelling, completing, and receiving an Infraction Report.
### Participant Opens Infraction Report
The Indirect Participant can open an Infraction Report at the Central Bank. The only requirement for opening the Report is that a transaction was made through PIX.
The Indirect Participant cannot open a second Infraction Report for the same transaction, even if the first Report is already closed.
### Participant Cancels Infraction Report
After the Indirect Participant opens an Infraction Report, the Participant can request its cancellation , if necessary, regardless of its status.
### Participant Receives Infraction Report
In the incoming infraction flow, the receipt (status acknowledged) is done automatically by QI Tech, and the webhook will be sent to the Indirect Participant with the received infraction.
In the outgoing flow, the receipt of a report by the counterparty does not result in an internal status update, as this action does not result in an Infraction entity change.
The Indirect Participant will receive the Infraction Report with the status of acknowledged
### Participant Closes Infraction Report
After the Indirect Participant is informed that there is an Infraction Report with the status of acknowledged , they must close it.
The Indirect Participant must inform, upon closure, the result of the analysis, being able to reject the Infraction Report or accept it within 6 calendar days from the receipt webhook. After this period, if there is no response, it will be automatically accepted by QI Tech to maintain commitment with BACEN and SPI response times.
## Infraction_Report_Direction State Machine Control
| Enumerator | Translation | Description|
|---|---|---|
| incoming | incoming | The Indirect Participant received the Infraction Report from another Participant.
| outgoing | outgoing | The Indirect Participant sent the Infraction Report to another Participant.
## Indirect Participant Receives/Closes Infraction Report
In this case, the "infraction_report_direction" field will be "incoming".
## Indirect Participant Sends/Cancels Infraction Report
In this case, the "infraction_report_direction" field will be "outgoing".
It is emphasized that none of these fields will be sent by the Indirect Participant. They are only contained in the request response.
---
# Scenario Simulation
URL: /en/documentation/pix_indireto/relato_de_infracao/simulacao_de_cenarios
Step-by-step guide to simulate the completion of actions performed by external agents. These simulations include the receipt and updates of infraction reports.
:::info Information
There is no payload response (response body) for these requests, only a response status of 204. The content generated by the mock should be received via webhook.
:::
## 1 - Simulating the Receipt of an Infraction Report
Simulates the receipt of an infraction report opened by another institution.
:::info IMPORTANT
It is essential to have a valid pix_transfer_key to send the request, regardless of the information from the other party of the transfer, as all information from the second participant will be replaced in the mock process.
:::
### Request
ENDPOINT /mock/pix/infraction_report
METHOD POST
Request Body
```json
{
"infraction_report_status": "acknowledged",
"pix_transfer_key": "28290ff2-2ba7-4e85-9a5e-862c92259b33",
"infraction_report_type": "refund_request",
"infraction_report_situation": "scam",
"infraction_report_details": "Transação com suspeita de fraude.",
}
```
### Object Request Body
| Field | Type | Description | Max. Characters |
|---------------------------------|--------|------------------------------------------------------------------------|-----------------|
| **infraction_report_status*** | string | Status of receipt of the infraction report. "acknowledged". | **[Enumerators infraction_report_status](#enumeradores-infraction_report_status)** |
| **pix_transfer_key*** | string | UUID4, unique key identifying the related transaction. | 36 |
| **infraction_report_type*** | string | Type of Infraction Report | **[Enumerators infraction_report_type](#enumeradores-infraction_report_type)** |
| **infraction_report_situation***| string | Situation in which the infraction occurred | **[Enumerators infraction_report_situation](#enumeradores-infraction_report_situation)** |
| **infraction_report_details*** | string | Details of the infraction report | 2000 |
### Enumerators infraction_report_status
| Field | Type | Description | Characters |
| --------------|--------|---------------------------------------------------------------------------- |------------|
| `open` | string | Infraction report was created and is open at BACEN. | - |
| `acknowledged`| string | Infraction report was received by the participant | - |
| `cancelled` | string | Infraction report is cancelled at BACEN | - |
| `closed` | string | Infraction report is closed at BACEN | - |
### Enumerators infraction_report_type
| Field | Type | Description | Characters |
| ------------------ |--------|-------------------------------------------------------------------------|------------|
| `refund_request` | string | Infraction report will be generated to request a refund. | - |
| `refund_cancelled` | string | Infraction report will be generated due to a cancelled refund. | - |
### Enumerators infraction_report_situation
| Field | Type | Description | Characters |
| ------------------- |--------|-------------------------------------------------------|------------|
| `scam` | string | Cause of scam or fraud. | - |
| `account_takeover` | string | Cause of unauthorized transaction from the origin account. | - |
| `coercion` | string | Cause of coercion crime. | - |
| `fraudulent_access`| string | Cause of fraudulent access to the origin account. | - |
| `other` | string | Any causes not applicable to those listed above. | - |
## 2 - Simulating the Update of an Infraction Report
Simulates the status update of an infraction report opened by the indirect participant.
The simulation options for updating an infraction report are:
1 - Cancellation: Simulates the cancellation (cancel), made by the other participant, of an infraction report previously opened by themselves.
2 - Closure: Simulates the closure (close), made by the other participant, of an infraction report opened by the indirect participant.
### Request
ENDPOINT /mock/pix/infraction_report
METHOD PATCH
Request Body - Cancel
:::info IMPORTANT
The Infraction Report identified by the infraction_report_key must have been previously created in the simulation of receiving an infraction report.
:::
```json
{
"infraction_report_status": "cancelled",
"infraction_report_key": "28290ff2-2ba7-4e85-9a5e-862c92259b34"
}
```
Request Body - Closing
:::info IMPORTANT
The Infraction Report identified by the infraction_report_key must have been previously created by the indirect participant and acknowledged in the simulation of updating an infraction report.
:::
```json
{
"infraction_report_status": "closed",
"infraction_report_key": "28290ff2-2ba7-4e85-9a5e-862c92259b34",
"analysis_result": "agreed",
"analysis_details": "Valor bloqueado. Para mais informações ligue para (99) 99999-9999."
}
```
### Object Request Body
| Field | Type | Description | Max. Characters | Information |
|------------------------------|--------|----------------------------------------------------------------------|-----------------|---------------------------------------|
| **infraction_report_status***| string | New status of the infraction report. "cancelled", "closed" | **[Enumerators infraction_report_status](#enumeradores-infraction_report_status)** | ---- |
| **infraction_report_key*** | string | Unique key of the infraction report | 36 | ---- |
| **analysis_result*** | string | Result of the infraction report analysis. "agreed" or "disagreed" | **[Enumerators analysis_result](#enumeradores-analysis_result)** | Mandatory for status "closed" |
| **analysis_details*** | string | Details of the infraction report analysis. | 2000 | Mandatory for status "closed" |
### Enumerators analysis_result
| Field | Type | Description | Characters |
| ----------- | ------ |--------------------------------------------------------------------------------------|------------|
| `agreed` | string | The Indirect Participant agrees with the Infraction Report created by the other Participant. | - |
| `disagreed` | string | The Indirect Participant disagrees with the Infraction Report created by the other Participant. | - |
---
# Receive Infraction Report
URL: /en/documentation/pix_indireto/relato_de_infracao/webhooks_relato_infracao
Since another Participant may open an Infraction Report targeting the Indirect Participant, it is necessary for QI Tech to notify the Indirect Participant about the report opened by the other Participant.
QI Tech will periodically poll for new reports opened to the Indirect Participants it manages and will notify the corresponding participant via webhook , already with the status acknowledged.
:::danger IMPORTANT
The Central Bank of Brazil requires that, within a period of 7 days from the receipt of the Infraction Report by the Indirect Participant, the Report must be closed .
If there is a delay on the part of the Indirect Participant, QI Tech will close the Infraction Report with the status of agreed, 6 calendar days after sending the receipt of infraction webhook, to ensure the institution is not penalized by the Central Bank of Brazil.
:::
The status of the Infraction Report will always be acknowledged , meaning that QI Tech has received the Report and will forward it to the Indirect Participant.
:::info Information
Everything described in this introduction section is also detailed in the sections related to Infraction Notifications on how the Indirect Participant should handle it via API.
:::
## Webhook for Receiving Infraction Report
**Request Body**
```json
{
"infraction_report_key":"d7820e2f-1c23-4610-83d6-d9aad1845075",
"pix_transfer_key":"cdcf0d25-08a1-46e3-902a-6d7ca75e6c48",
"end_to_end_id":"E99999010202406251332F8n7dMUwOLE",
"infraction_report_status":"acknowledged",
"infraction_report_situation":"scam",
"infraction_report_type":"refund_request",
"report_details":"usuario caiu em golpe…",
"debited_participant":"99999011",
"credited_participant":"99999010",
"infraction_report_direction": "incoming",
"created_at": "2023-03-03T12:04:06.179Z",
"updated_at": "2023-03-03T12:04:06.179Z"
}
```
### Body Params
| Field | Type | Description | Characters |
|-------------------------------|--------|--------------------------------------------------------------------------|------------|
| `infraction_report_key` * | string | Unique identifier of the infraction report. | 36 |
| `pix_transfer_key` * | string | Unique identifier of the PIX transaction. | 36 |
| `end_to_end_id` * | string | Unique identifier of the PIX transaction at BACEN. | 36 |
| `infraction_report_status` * | enum | Status. | **[Enumerators infraction_report_status](#enumeradores-infraction_report_status)** |
| `infraction_report_situation` *| enum | Situation in which the infraction occurred. | **[Enumerators infraction_report_situation](#enumeradores-infraction_report_situation)** |
| `infraction_report_type` * | enum | Type of Infraction Report. | **[Enumerators infraction_report_type](#enumeradores-infraction_report_type)** |
| `infraction_report_details` | string | Details about the created Infraction Report. | Less or equal 2000 |
| `credited_participant` * | string | ISPB of the Credited Participant. | 8 |
| `debited_participant` * | string | ISPB of the Debited Participant. | 8 |
| `infraction_report_direction` * | enum | Enumerator on whether the report was opened by the Indirect Participant or another Participant | **[Enumerators infraction_report_direction](#enumeradores-infraction_report_direction)** |
| `created_at` * | string | Infraction Report creation time. | 24 |
| `updated_at` | string | Infraction Report update time. | 24 |
### Enumerators infraction_report_status
| Field | Type | Description | Characters |
| -------------- | ------ | ------------------------------------------------------------------------------- |------------|
| `open` | string | Infraction report was created and is open at BACEN. | - |
| `acknowledged` | string | Infraction report was received by the contested participant. | - |
| `cancelled` | string | Infraction report is cancelled at BACEN. | - |
| `closed` | string | Infraction report is closed at BACEN. | - |
### Enumerators infraction_report_type
| Field | Type | Description | Characters |
| ------------------ | ------ | --------------------------------------------------------------------------- |------------|
| `refund_cancelled` | string | Infraction report will be generated due to a cancelled refund | 16 |
| `refund_request` | string | Infraction report will be generated to request a refund | 14 |
### Enumerators infraction_report_situation
| Field | Type | Description | Characters |
| ------------------- | ------ | ------------------------------------------------------|------------|
| `scam` | string | Cause of scam or fraud. | - |
| `account_takeover` | string | Cause of unauthorized transaction from the origin account. | - |
| `coercion` | string | Cause of coercion crime. | - |
| `fraudulent_access` | string | Cause of fraudulent access to the origin account. | - |
| `other` | string | Any causes not applicable to those listed above. | - |
### Enumerators infraction_report_direction
| Field | Type | Description | Characters |
|-------------|--------|--------------------------------------------------------------|------------|
| `incoming` | string | Infraction report with the indirect participant as the target.| - |
| `outgoing` | string | Infraction report with the indirect participant as the originator.| - |
## Webhook recebimento de alteração de Relato de Infração
**Request Body**
```json
{
"infraction_report_key":"d7820e2f-1c23-4610-83d6-d9aad1845075",
"pix_transfer_key":"cdcf0d25-08a1-46e3-902a-6d7ca75e6c48",
"end_to_end_id":"E99999010202406251332F8n7dMUwOLE",
"infraction_report_status":"closed",
"infraction_report_situation":"scam",
"infraction_report_type":"refund_request",
"report_details":"usuario caiu em golpe…",
"debited_participant":"99999011",
"credited_participant":"99999010",
"analysis_result": "agreed",
"analysis_details": "Valor bloqueado. Para mais informações ligue para (11) 98871-1385.",
"infraction_report_direction": "outgoing",
"created_at": "2023-03-03T12:04:06.179Z",
"updated_at": "2023-03-03T12:04:06.179Z"
}
```
### Body Params
| Field | Type | Description | Characters |
|-------------------------------|--------|--------------------------------------------------------------------------|------------|
| `infraction_report_key` * | string | Unique identifier of the infraction report. | 36 |
| `pix_transfer_key` * | string | Unique identifier of the PIX transaction. | 36 |
| `end_to_end_id` * | string | Unique identifier of the PIX transaction at BACEN. | 36 |
| `infraction_report_status` * | enum | Status. | **[Enumerators infraction_report_status](#enumeradores-infraction_report_status)** |
| `infraction_report_situation` *| enum | Situation in which the infraction occurred. | **[Enumerators infraction_report_situation](#enumeradores-infraction_report_situation)** |
| `infraction_report_type` * | enum | Type of Infraction Report. | **[Enumerators infraction_report_type](#enumeradores-infraction_report_type)** |
| `infraction_report_details` | string | Details about the created Infraction Report. | Less or equal 2000 |
| `credited_participant` * | string | ISPB of the Credited Participant. | 8 |
| `debited_participant` * | string | ISPB of the Debited Participant. | 8 |
| `analysis_result` * | string | Result of the analysis. | **[Enumerators analysis_result](#enumeradores-analysis_result)** |
| `analysis_details` * | string | Description of the analysis result | 250 |
| `infraction_report_direction` * | enum | Enumerator on whether the report was opened by the Indirect Participant or another Participant | **[Enumerators infraction_report_direction](#enumeradores-infraction_report_direction)** |
| `created_at` * | string | Infraction Report creation time. | 24 |
| `updated_at` | string | Infraction Report update time. | 24 |
### Enumerators analysis_result
| Field | Type | Description | Characters |
| ----------- | ------ | ------------------------------------------------------------------------ |------------|
| `agreed` | string | The Indirect Participant agrees with the Infraction Report created by the other Participant. | - |
| `disagreed` | string | The Indirect Participant disagrees with the Infraction Report created by the other Participant. | - |