# QI Tech — Banking-as-a-Service › Pix Indireto
Documentação da QI Tech em texto corrido, para colar em um LLM.
Fonte: https://docs.qitech.com.br
60 página(s).
Índice:
- Criação de uma chave pix para um Alias (/documentation/pix_indireto/chaves_pix/criacao_de_chaves)
- Deleção de chave Pix de um Alias (/documentation/pix_indireto/chaves_pix/deletar_chaves)
- Introdução a gestao de chaves PIX para um Alias (/documentation/pix_indireto/chaves_pix/introducao_chaves_pix)
- Listagem de chaves Pix de um Alias (/documentation/pix_indireto/chaves_pix/listar_chaves)
- Cancelar Solicitação de Devolução (/documentation/pix_indireto/devolucao/cancelar_devolucao)
- Consultar Solicitação de Devolução (/documentation/pix_indireto/devolucao/consultar_devolucao)
- Abrir Solicitação de Devolução (/documentation/pix_indireto/devolucao/criar_devolucao)
- Fechar Solicitação de Devolução (/documentation/pix_indireto/devolucao/fechar_devolucao)
- Listar Solicitações de Devolução (/documentation/pix_indireto/devolucao/listar_solicitacoes)
- Introdução ao fluxo de Devolução (/documentation/pix_indireto/devolucao/maquina_estados)
- Simulação de Cenários (/documentation/pix_indireto/devolucao/simulacao_de_cenarios)
- Receber Solicitação de Devolução (/documentation/pix_indireto/devolucao/webhooks_devolucao)
- Consulta de uma entidade Alias (/documentation/pix_indireto/gerenciamento_de_alias/consultar_alias)
- Consulta de Alias por Request Control Key (/documentation/pix_indireto/gerenciamento_de_alias/consultar_request_control_key)
- Criação de uma entidade Alias (/documentation/pix_indireto/gerenciamento_de_alias/criacao_de_alias)
- Deleção de uma entidade Alias (/documentation/pix_indireto/gerenciamento_de_alias/deletar_alias)
- Introdução à entidade de Alias (/documentation/pix_indireto/gerenciamento_de_alias/introducao_alias)
- Listagem de Alias (/documentation/pix_indireto/gerenciamento_de_alias/listagem_de_alias)
- Introdução (/documentation/pix_indireto/introducao)
- Chaves PIX mockadas em ambiente de sandbox (/documentation/pix_indireto/movimentacoes/chaves_pix_mockadas)
- Consulta de Dados de Chave Pix no Banco Central (/documentation/pix_indireto/movimentacoes/consultar_chave_pix)
- Consultar Transação Pix (/documentation/pix_indireto/movimentacoes/consultar_pix)
- Efetuar devolução de um Pix (/documentation/pix_indireto/movimentacoes/devolucao_pix)
- Introdução à movimentações no âmbito do PIX (/documentation/pix_indireto/movimentacoes/introducao_movimentacoes)
- Simulação de cenários (/documentation/pix_indireto/movimentacoes/simulacao)
- Efetuar Transferencia Assíncrona para Pix Manual (/documentation/pix_indireto/movimentacoes/transacao_async/transacao_pix_manual)
- Efetuar Transferencia Assíncrona via Chave Pix (/documentation/pix_indireto/movimentacoes/transacao_async/transacao_pix_normal)
- Efetuar Transferencia Assíncrona para Pix Qr Code (/documentation/pix_indireto/movimentacoes/transacao_async/transacao_pix_qr_code)
- Transação Pix por Chave Pix (/documentation/pix_indireto/movimentacoes/transacao/transacao_pix_chave_sync)
- Transação Pix Manual (/documentation/pix_indireto/movimentacoes/transacao/transacao_pix_manual_sync)
- Transação Pix por QR Code (/documentation/pix_indireto/movimentacoes/transacao/transacao_pix_qr_code_sync)
- Webhook para Devoluções de Pix (/documentation/pix_indireto/movimentacoes/webhook/webhook_devolucao_outgoing_pix)
- Webhook para Pix de Entrada (/documentation/pix_indireto/movimentacoes/webhook/webhook_incoming_pix)
- Webhook para Transações Pendentes (/documentation/pix_indireto/movimentacoes/webhook/webhook_transacao)
- Cancelar um Pedido de Portabilidade (/documentation/pix_indireto/portabilidade/cancelar_pedido_de_portabilidade)
- Completa um Pedido de Portabilidade (/documentation/pix_indireto/portabilidade/completar_pedido_de_portabilidade)
- Confirmar um Pedido de Portabilidade (/documentation/pix_indireto/portabilidade/confirmar_pedido_de_portabilidade)
- Consultar Pedidos de Portabilidade (/documentation/pix_indireto/portabilidade/consultar_pedido_de_portabilidade)
- Criação de um Pedido de Portabilidade (/documentation/pix_indireto/portabilidade/criar_pedido_de_portabilidade)
- Introdução a Pedidos de Portabilidade (/documentation/pix_indireto/portabilidade/introducao_portabilidade)
- Consultar Pedidos de Portabilidade de um Alias (/documentation/pix_indireto/portabilidade/listar_pedidos_de_portabilidade_de_um_alias)
- Webhook Atualização de Portabilidade (/documentation/pix_indireto/portabilidade/webhook/webhook_atualizacao_do_pedido_de_portabilidade)
- Webhook Registro Externo de Portabilidade (/documentation/pix_indireto/portabilidade/webhook/webhook_receber_registro_externo_de_portabilidade)
- Consultar um QR Code Pix (/documentation/pix_indireto/qr_code/consultar_qr_code)
- Criar QR Code Pix dinâmico com vencimento (/documentation/pix_indireto/qr_code/Criar QR Code/criar_qr_code_dinamico_com_vencimento)
- Criar QR Code Pix dinâmico pagamento imediato (/documentation/pix_indireto/qr_code/Criar QR Code/criar_qr_code_dinamico_imediato)
- Criar QR Code Pix Estático (/documentation/pix_indireto/qr_code/Criar QR Code/criar_qr_code_estatico)
- Listar QR Codes de um alias (/documentation/pix_indireto/qr_code/decodificar_qr_code)
- Alterar um QR Code Pix (/documentation/pix_indireto/qr_code/desativar_qr_code)
- Introdução QR Code pix (/documentation/pix_indireto/qr_code/introducao_qr_code)
- Listar QR Codes de um alias (/documentation/pix_indireto/qr_code/listar_alias_qr_codes)
- Webhook para Pix de Entrada de pagamento de QR Code (/documentation/pix_indireto/qr_code/webhook_incoming_pix)
- Cancelar Relato de Infração (/documentation/pix_indireto/relato_de_infracao/cancelar_relato_infracao)
- Consultar Relato de Infração (/documentation/pix_indireto/relato_de_infracao/consultar_relato_infracao)
- Abrir Relato de Infração (/documentation/pix_indireto/relato_de_infracao/criar_relato_infracao)
- Fechar Relato de Infração (/documentation/pix_indireto/relato_de_infracao/fechar_relato_infracao)
- Listar Relatos de Infração (/documentation/pix_indireto/relato_de_infracao/listar_relatos)
- Introdução ao fluxo de Relato de Infração (/documentation/pix_indireto/relato_de_infracao/maquina_estados)
- Simulação de Cenários (/documentation/pix_indireto/relato_de_infracao/simulacao_de_cenarios)
- Receber Relato de Infração (/documentation/pix_indireto/relato_de_infracao/webhooks_relato_infracao)
---
# Criação de uma chave pix para um Alias
URL: /documentation/pix_indireto/chaves_pix/criacao_de_chaves
## Request
ENDPOINT /account/ ACCOUNT_KEY /alias/ ALIAS_KEY /pix_key
MÉTODO POST
**Request Body - Chave do tipo 'random_key'**
```json
{
"request_control_key": "3d3d0083-ac71-46f0-8a90-c00a157a4893",
"pix_key_type": "random_key"
}
```
**Request Body - Chave do tipo CPF**
```json
{
"request_control_key": "3d3d0083-ac71-46f0-8a90-c00a157a4893",
"pix_key_type": "cpf",
"pix_key": "67824450007"
}
```
### Request Path Params
| Campo | Tipo | Descrição | Caracteres |
|---------------|--------|-----------------------|------------|
| `account_key` | uuidv4 | Chave única da conta. | 36 |
| `alias_key` | uuidv4 | Chave única do alias. | 36 |
### Request Body Params
| Campo | Tipo | Descrição | Max. Caracteres |
|-------------------------|--------|---------------------------------------------------------------------------------|-----------------|
| `request_control_key` * | string | UUID4 para fins de consulta sobre a requisição feita. | 36 |
| `pix_key_type` * | string | Definição do tipo de chave que será criada. Valores possíveis: 'cpf', 'cnpj', 'email', 'phone_number', 'random_key' | 10 |
| `pix_key` | string | Valor da chave Pix a ser criado. Não deve ser enviado para casos de chave do tipo 'random_key'. | 10 |
:::info Tipos de Chave Pix
A `pix_key` enviada na requisição pode ser um CPF, CNPJ, E-mail ou celular, seguindo as seguintes formatações:
**CPF**: Número inteiro com 11 dígitos.
**CNPJ**: Número inteiro com 14 dígitos.
**E-mail**: Texto contendo ao menos um “@”.
**Celular**: Texto contendo os seguintes valores: “+55” + “DDD do celular“ + “Número Inteiro do Celular com no mínimo 8
e no máximo 9 dígitos”. 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
| Campo | Tipo | Descrição | Max. Caracteres |
|-------------------------|--------|---------------------------------------------------------------------------------|-----------------|
| `pix_key` | string | Valor da chave Pix criada. | 200 |
| `pix_key_status` | string | Status de ativação da chave Pix. Pode ser "active","inactive" ou "pending" | 8 |
| `created_at` | datetime Zulu | Data de criação da requisição. | 20 |
:::info Tipos de Chave Pix
A `pix_key` enviada na resposta da requisição pode ser um CPF, CNPJ, E-mail, celular ou chave aleatória, seguindo as seguintes formatações:
**CPF**: Número inteiro com 11 dígitos.
**CNPJ**: Número inteiro com 14 dígitos.
**E-mail**: Texto contendo ao menos um “@”.
**Celular**: Texto contendo os seguintes valores: “+55” + “DDD do celular“ + “Número Inteiro do Celular com no mínimo 8
e no máximo 9 dígitos”. Ex: “+5511987654321“.
**Chave aleatória**: UUIDV4.
:::
STATUS 4XX
Response Body: Error
```json
{
"title": "titulo",
"description": "description in English",
"translation": "descrição em portugues",
"code": "codigo",
"extra_fields": {}
}
```
| Código HTTP | Código QI
`code` | Título
`title` | Descrição (eng)
`Description` | Descrição (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 |
---
# Deleção de chave Pix de um Alias
URL: /documentation/pix_indireto/chaves_pix/deletar_chaves
## Request
ENDPOINT /account/ ACCOUNT_KEY /alias/ ALIAS_KEY /pix_key/ PIX_KEY
MÉTODO DELETE
Request Body
```json
{}
```
### Path Params
| Campo | Tipo | Descrição | Caracteres |
|---------------|--------|------------------------------|------------|
| `account_key` | uuidv4 | Chave única da conta. | 36 |
| `alias_key` | uuidv4 | Chave única do alias. | 36 |
| `pix_key` | string | Chave PIX que será deletada. | 200 |
## Response
STATUS 200
Response Body
```json
{}
```
STATUS 4XX
Response Body: Error
```json
{
"title": "titulo",
"description": "description in English",
"translation": "descrição em portugues",
"code": "codigo",
"extra_fields": {}
}
```
| Código HTTP | Código QI
`code` | Título
`title` | Descrição (eng)
`Description` | Descrição (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\} |
---
# Introdução a gestao de chaves PIX para um Alias
URL: /documentation/pix_indireto/chaves_pix/introducao_chaves_pix
Após o Participante Indireto ter realizado o cadastro de um Alias para sua conta aberta na QI Tech, este pode realizar o cadastro de uma chave PIX para este Alias o qual, na prática, representa o cliente do Participante Indireto.
Como o Participante Indireto já realizou o cadastro do Alias, basta indicar à QI Tech, que se deseja abrir uma chave PIX para determinado Alias, o qual possui uma chave única que é fornecida quando o Participante Indireto registra um Alias.
:::info Informação
Tudo o descrito nesta seção de introdução também está, de forma detalhada como o Participante Indireto deve tratar via API, na seções seguintes.
:::
---
# Listagem de chaves Pix de um Alias
URL: /documentation/pix_indireto/chaves_pix/listar_chaves
## Request
ENDPOINT /account/ ACCOUNT_KEY /alias/ ALIAS_KEY /pix_key
MÉTODO GET
### Path Params
| Campo | Tipo | Descrição | Caracteres |
|---------------|--------|-----------------------|------------|
| `account_key` | string | Chave única da conta. | 36 |
| `alias_key` | string | Chave única do alias. | 36 |
:::info Tipos de Chave Pix
A “pix_key” é do tipo Chave Aleatória (UUID4), seguindo a seguinte formatação:
Chave Aleatória: UUID4.
:::
### Query Params
| Campo | Tipo | Descrição | Caracteres |
|---------------|---------|-----------------------------------------|------------|
| `page_number` | integer | Página atual que está sendo consultada. | - |
| `page_size` | integer | Quantidade de resultados por página. | - |
## Response
STATUS 200
Response Body: Chave Ativa
```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
| Campo | Tipo | Descrição | Max. Caracteres |
|------------------|---------------|----------------------------------------------------------------------------|-----------------|
| `pix_key` | string | Chave Pix. | 77 |
| `pix_key_type` | string | Tipo da chave Pix. Pode ser "random_key" | 10 |
| `pix_key_status` | string | Status de ativação da chave Pix. Pode ser "active","inactive" ou "pending" | 8 |
| `created_at` | datetime Zulu | Data de criação da requisição. | 20 |
STATUS 4XX
Response Body: Error
```json
{
"title": "titulo",
"description": "description in English",
"translation": "descrição em portugues",
"code": "codigo",
"extra_fields": {}
}
```
| Código HTTP | Código QI
`code` | Título
`title` | Descrição (eng)
`Description` | Descrição (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 |
---
# Cancelar Solicitação de Devolução
URL: /documentation/pix_indireto/devolucao/cancelar_devolucao
O Participante Indireto pode cancelar uma solicitação de devolução, caso seja necessário.
Apenas o Participante (Direto ou Indireto) o qual criou a solicitação de devolução pode cancelá-la.
Para o cancelamento, o status deve ser de OPEN
:::danger IMPORTANTE
O Banco Central do Brasil define que, dentro de um período de 1 dia do recebimento da Solicitação de Devolução pelo Participante Indireto, a Devolução precisa ser fechada .
Caso haja atraso por parte do Participante Indireto, a QI Tech irá fechar a Solicitação de Devolução, com o status de totally_accepted , a fim de que a instituição não seja penalizada pelo Banco Central do Brasil.
:::
## Request
ENDPOINT /pix/refund_request/ REFUND_REQUEST_KEY
MÉTODO PATCH
**Request Body**
```json
{
"refund_request_status": "cancelled",
"request_control_key": "e09aba97-0051-4c18-b645-1cb3c2581c34"
}
```
### Path Params
| Campo | Tipo | Descrição | Caracteres |
| ---------------------- | ------ | ----------------------------- | ---------- |
| `refund_request_key` * | string | UUID4 da devolução já criada. | 36 |
### Body Params
| Campo | Tipo | Descrição | Caracteres |
| ------------------------- | ------ | ----------------------------------------------------- | ---------- |
| `refund_request_status` * | string | Status de atualização da devolução. | 36 |
| `request_control_key` * | uuidv4 | UUID4 para fins de consulta sobre a requisição feita. | 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
| Campo | Tipo | Descrição | Caracteres |
| --------------------------- | ------ | ----------------------------------------------------------------------------------------- | ----------------------------------------------------------------------------------- |
| `pix_transfer_key`* | string | Identificador único da transação PIX. | 36 |
| `refund_request_key`* | string | Identificador único da devolução. | 36 |
| `infraction_report_key`* | string | Identificador único da infração relacionada à devolução. Somente quando o tipo for FRAUDE | 36 |
| `refund_request_type` | enum | Tipo de solicitação de devolução. | **[Enumeradores refund_request_type](#enumeradores-refund_request_type)** |
| `requested_amount`* | float | Valor da devolução | - |
| `refund_request_status`* | enum | Status . | **[Enumeradores refund_request_status](#enumeradores-refund_request_status)** |
| `contested_participant`* | string | ISPB do Participante Creditado (Contestado). | 8 |
| `requesting_participant`* | string | ISPB do Participante Debitado (Requisitante, o qual está pedindo a devolução). | 8 |
| `refund_request_details`* | string | Detalhes da devolução. | - |
| `analysis_result`* | enum | Resultado da análise de fechamento da devolução. | **[Enumeradores analysis_result](#enumeradores-analysis_result)** |
| `analysis_details`* | string | Detalhes da análise de fechamento da devolução. | - |
| `reject_reason`* | string | Motivo da rejeição da devolução, caso seja fechada com REJECTED. | **[Enumeradores reject_reason](#enumeradores-reject_reason)** |
| `refund_transfer_key`* | string | pix_transfer_key da transação de devolução, caso seja fechada com aceite. | - |
| `refunded_amount`* | float | Valor devolvido na transação de devolução. | - |
| `refund_request_direction`* | string | Direção da solicitação de devolução. | **[Enumeradores refund_request_direction](#enumeradores-refund_request_direction)** |
| `created_at` * | string | Data de criação da Solicitação de Devolução | 24 |
### Enumeradores refund_request_status
| Campo | Descrição |
| ----------- | ---------------------------------------------------------------------------- |
| `open` | Solicitação de Devolução foi criada e está aberta no BACEN. |
| `cancelled` | Solicitação de Devolução está cancelada no BACEN |
| `closed` | Solicitação de Devolução está fechada no BACEN |
### Enumeradores refund_request_type
| Campo | Descrição |
| ------------------ | ------------------------------------------------------ |
| `fraud` | Solicitação de Devolução originada de uma fraude. |
| `operational_flaw` | Solicitação de Devolução originada de um erro interno. |
### Enumeradores analysis_result
| Campo | Descrição |
| -------------------- | ------------------------------------------------- |
| `totally_accepted` | Solicitação de Devolução foi totalmente aceita. |
| `partially_accepted` | Solicitação de Devolução foi parcialmente aceita; |
| `rejected` | Solicitação de Devolução foi rejeitada. |
### Enumeradores reject_reason
| Campo | Descrição |
| ----------------- | -------------------------------------------------------------------------- |
| `no_balance` | Conta não possui saldo para realizar a devolução. |
| `account_closure` | Conta se encontra fechada e, portanto, não é possível realizar a devolução |
| `other` | Outro motivo |
### Enumeradores refund_request_direction
| Campo | Descrição |
| ---------- | ------------------------------------------------- |
| `outgoing` | Participante é originador do pedido de devolução. |
| `incoming` | Participante é o alvo do pedido de devolução |
---
# Consultar Solicitação de Devolução
URL: /documentation/pix_indireto/devolucao/consultar_devolucao
Caso o Participante Indireto queira consultar as informações de uma Solicitação de Devolução, a rota abaixo o permite.
:::danger IMPORTANTE
O Banco Central do Brasil define que, dentro de um período de 1 dia do recebimento da Solicitação de Devolução pelo Participante Indireto, a Devolução precisa ser fechada .
Caso haja atraso por parte do Participante Indireto, a QI Tech irá fechar a Solicitação de Devolução, com o status de totally_accepted , a fim de que a instituição não seja penalizada pelo Banco Central do Brasil.
:::
## Request
ENDPOINT /pix/refund_request/ REFUND_REQUEST_KEY
MÉTODO GET
### Path Params
| Campo | Tipo | Descrição | Caracteres |
| -------------------- | ------ | ------------------- | ---------- |
| `refund_request_key` | string | UUID4 da devolução. | 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
| Campo | Tipo | Descrição | Caracteres |
| --------------------------- | ------ | ----------------------------------------------------------------------------------------- | ----------------------------------------------------------------------------------- |
| `pix_transfer_key`* | string | Identificador único da transação PIX. | 36 |
| `refund_request_key`* | string | Identificador único da devolução. | 36 |
| `infraction_report_key`* | string | Identificador único da infração relacionada à devolução. Somente quando o tipo for FRAUDE | 36 |
| `refund_request_type` | enum | Tipo de solicitação de devolução. | **[Enumeradores refund_request_type](#enumeradores-refund_request_type)** |
| `requested_amount`* | float | Valor da devolução | - |
| `refund_request_status`* | enum | Status . | **[Enumeradores refund_request_status](#enumeradores-refund_request_status)** |
| `contested_participant`* | string | ISPB do Participante Creditado (Contestado). | 8 |
| `requesting_participant`* | string | ISPB do Participante Debitado (Requisitante, o qual está pedindo a devolução). | 8 |
| `refund_request_details`* | string | Detalhes da devolução. | - |
| `analysis_result`* | enum | Resultado da análise de fechamento da devolução. | **[Enumeradores analysis_result](#enumeradores-analysis_result)** |
| `analysis_details`* | string | Detalhes da análise de fechamento da devolução. | - |
| `reject_reason`* | string | Motivo da rejeição da devolução, caso seja fechada com REJECTED. | **[Enumeradores reject_reason](#enumeradores-reject_reason)** |
| `refund_transfer_key`* | string | pix_transfer_key da transação de devolução, caso seja fechada com aceite. | - |
| `refunded_amount`* | float | Valor devolvido na transação de devolução. | - |
| `refund_events`* | object | Objeto eventos de pedido de devolução. | **[Objeto refund_events](#objetos-refund_events)** |
| `refund_request_direction`* | string | Direção da solicitação de devolução. | **[Enumeradores refund_request_direction](#enumeradores-refund_request_direction)** |
| `created_at` * | string | Data de criação da Solicitação de Devolução | 24 |
### Enumeradores refund_request_status
| Campo | Descrição |
| ----------- | ---------------------------------------------------------------------------- |
| `open` | Solicitação de Devolução foi criada e está aberta no BACEN. |
| `cancelled` | Solicitação de Devolução está cancelada no BACEN |
| `closed` | Solicitação de Devolução está fechada no BACEN |
### Enumeradores refund_request_type
| Campo | Descrição |
| ------------------ | ------------------------------------------------------ |
| `fraud` | Solicitação de Devolução originada de uma fraude. |
| `operational_flaw` | Solicitação de Devolução originada de um erro interno. |
### Enumeradores analysis_result
| Campo | Descrição |
| -------------------- | ------------------------------------------------- |
| `totally_accepted` | Solicitação de Devolução foi totalmente aceita. |
| `partially_accepted` | Solicitação de Devolução foi parcialmente aceita; |
| `rejected` | Solicitação de Devolução foi rejeitada. |
### Enumeradores reject_reason
| Campo | Descrição |
| ----------------- | -------------------------------------------------------------------------- |
| `no_balance` | Conta não possui saldo para realizar a devolução. |
| `account_closure` | Conta se encontra fechada e, portanto, não é possível realizar a devolução |
| `other` | Outro motivo |
### Enumeradores refund_request_direction
| Campo | Descrição |
| ---------- | ------------------------------------------------- |
| `outgoing` | Participante é originador do pedido de devolução. |
| `incoming` | Participante é o alvo do pedido de devolução |
### Objetos refund_events
| Campo | Descrição |
| --------------- | --------------------------------------------------------------------------------------------------------------------- |
| `event_type` | Tipo do evento de mudança da devolução. **[Enumeradores refund_request_status](#enumeradores-refund_request_status)** |
| `event_details` | Detalhes acerca do evento. |
| `created_at` | Data de criação do evento. |
---
# Abrir Solicitação de Devolução
URL: /documentation/pix_indireto/devolucao/criar_devolucao
A Solicitação de Devolução é mais uma funcionalidade presente no MED, definido pelo BACEN.
O principal objetivo é facilitar a devolução de uma transação PIX feita. Tem-se que a Solicitação de Devolução pode ser gerada tanto por uma falha operacional quanto por uma infração . Neste último caso, há um Relato de Infração, para uma transação PIX, já fechado e aceito .
:::caution **Atenção**
A fim de se compreender o fluxo de Solicitação de Devolução, é necessário saber quais ENDPOINTS o Participante Indireto que criou a devolução pode utilizar.
Quando o Participante Indireto cria uma Solicitação de Devolução, este pode (se necessário) cancelar a solicitação caso tenha sido gerado de maneira indevida.
Quando o Participante Indireto recebe uma Solicitação de Devolução, esta deve respondê-lo informando o resultado da análise da solicitação.
Ambos os fluxos citados serão descritos nas seções seguintes.
Ressalta-se também que se o Participante Indireto abrir a Solicitação, então ele contesta outro Participante. No fluxo contrário, o Participante Indireto é o contestado .
:::
:::danger IMPORTANTE
O Banco Central do Brasil define que, dentro de um período de 1 dia do recebimento da Solicitação de Devolução pelo Participante Indireto, a Devolução precisa ser fechada .
Caso haja atraso por parte do Participante Indireto, a QI Tech irá fechar a Solicitação de Devolução, com o status de totally_accepted , a fim de que a instituição não seja penalizada pelo Banco Central do Brasil.
:::
## Request
ENDPOINT /pix/refund_request
MÉTODO 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
| Campo | Tipo | Descrição | Caracteres |
| ------------------------ | ------ | ------------------------------------------------------------------------------------------ | ------------------------------------------------------------------------- |
| `pix_transfer_key` * | string | Identificador único da transação PIX. | 36 |
| `request_control_key` * | uuidv4 | UUID4 para fins de consulta sobre a requisição feita. | 36 |
| `amount` | float | Valor da devolução. Caso não seja fornecido, será utilizado o valor da transação original. | 19 |
| `refund_request_details` | string | Detalhes acerca da solicitação de devolução a ser criada | \<\= 2000 |
| `refund_request_type` * | enum | Pode ser (fraud/operational_flaw) | **[Enumeradores refund_request_type](#enumeradores-refund_request_type)** |
## 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 Informação
Caso o campo "refund_request_type" seja de "fraud", a QI Tech informará, na resposta, a infraction_report_key que já foi fechada e aceita.
:::
### Body Params
| Campo | Tipo | Descrição | Caracteres |
| --------------------------- | ------ | ----------------------------------------------------------------------------------------- | ----------------------------------------------------------------------------------- |
| `pix_transfer_key`* | string | Identificador único da transação PIX. | 36 |
| `refund_request_key`* | string | Identificador único da devolução. | 36 |
| `infraction_report_key`* | string | Identificador único da infração relacionada à devolução. Somente quando o tipo for FRAUDE | 36 |
| `refund_request_type` | enum | Tipo de solicitação de devolução. | **[Enumeradores refund_request_type](#enumeradores-refund_request_type)** |
| `requested_amount`* | float | Valor da devolução | - |
| `refund_request_status`* | enum | Status . | **[Enumeradores refund_request_status](#enumeradores-refund_request_status)** |
| `contested_participant`* | string | ISPB do Participante Creditado (Contestado). | 8 |
| `requesting_participant`* | string | ISPB do Participante Debitado (Requisitante, o qual está pedindo a devolução). | 8 |
| `refund_request_details`* | string | Detalhes da devolução. | - |
| `analysis_result`* | enum | Resultado da análise de fechamento da devolução. | **[Enumeradores analysis_result](#enumeradores-analysis_result)** |
| `analysis_details`* | string | Detalhes da análise de fechamento da devolução. | - |
| `reject_reason`* | string | Motivo da rejeição da devolução, caso seja fechada com REJECTED. | **[Enumeradores reject_reason](#enumeradores-reject_reason)** |
| `refund_transfer_key`* | string | pix_transfer_key da transação de devolução, caso seja fechada com aceite. | - |
| `refunded_amount`* | float | Valor devolvido na transação de devolução. | - |
| `refund_request_direction`* | string | Direção da solicitação de devolução. | **[Enumeradores refund_request_direction](#enumeradores-refund_request_direction)** |
| `created_at` * | string | Data de criação da Solicitação de Devolução | 24 |
### Enumeradores refund_request_status
| Campo | Descrição |
| ----------- | ---------------------------------------------------------------------------- |
| `open` | Solicitação de Devolução foi criada e está aberta no BACEN. |
| `cancelled` | Solicitação de Devolução está cancelada no BACEN |
| `closed` | Solicitação de Devolução está fechada no BACEN |
### Enumeradores refund_request_type
| Campo | Descrição |
| ------------------ | ------------------------------------------------------ |
| `fraud` | Solicitação de Devolução originada de uma fraude. |
| `operational_flaw` | Solicitação de Devolução originada de um erro interno. |
### Enumeradores analysis_result
| Campo | Descrição |
| -------------------- | ------------------------------------------------- |
| `totally_accepted` | Solicitação de Devolução foi totalmente aceita. |
| `partially_accepted` | Solicitação de Devolução foi parcialmente aceita; |
| `rejected` | Solicitação de Devolução foi rejeitada. |
### Enumeradores reject_reason
| Campo | Descrição |
| ----------------- | -------------------------------------------------------------------------- |
| `no_balance` | Conta não possui saldo para realizar a devolução. |
| `account_closure` | Conta se encontra fechada e, portanto, não é possível realizar a devolução |
| `other` | Outro motivo |
### Enumeradores refund_request_direction
| Campo | Descrição |
| ---------- | ------------------------------------------------- |
| `outgoing` | Participante é originador do pedido de devolução. |
| `incoming` | Participante é o alvo do pedido de devolução |
---
# Fechar Solicitação de Devolução
URL: /documentation/pix_indireto/devolucao/fechar_devolucao
O Participante Indireto pode fechar uma solicitação de devolução, se este (Participante) estiver como Participante Contestado.
Para o fechamento, o status deve ser de OPEN .
:::danger IMPORTANTE
O Banco Central do Brasil define que, dentro de um período de 1 dia do recebimento da Solicitação de Devolução pelo Participante Indireto, a Devolução precisa ser fechada .
Caso haja atraso por parte do Participante Indireto, a QI Tech irá fechar a Solicitação de Devolução, com o status de totally_accepted , a fim de que a instituição não seja penalizada pelo Banco Central do Brasil.
:::
## Request
ENDPOINT /pix/refund_request/ REFUND_REQUEST_KEY
MÉTODO 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
| Campo | Tipo | Descrição | Caracteres |
|---|---| ---| ---|
| `refund_request_key` *| string | UUID4 da devolução já criada.| 36 |
### Body Params
| Campo | Tipo | Descrição | Caracteres |
|---|---| ---| ---|
| `request_control_key` * | uuidv4 | UUID4 para fins de consulta sobre a requisição feita. | 36 |
| `request_request_status` * | enum | status | **[Enumeradores refund_request_status](#enumeradores-refund_request_status)** |
| `analysis_result` * | enum | Resultado da análise | **[Enumeradores analysis_result](#enumeradores-analysis_result)** |
| `analysis_details` | string | Comentário sobre a análise | \<\= 2000 |
| `refund_transfer_key` | string | UUID4 da transação de devolução enviada pela rota de "reversal". Deve ser utilizado quando o "analysis_result" é de aceite.| 36 |
| `reject_reason` | enum | Razão da rejeição da devolução. Deve ser utilizado quando o campo 'analysis_result' é 'rejected'. | **[Enumeradores reject_reason](#enumeradores-reject_reason)** |
## Response
STATUS 200
**Response Body - Recusa**
```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 - Aceite**
```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
| Campo | Tipo | Descrição | Caracteres |
| --------------------------- | ------ | ----------------------------------------------------------------------------------------- | ----------------------------------------------------------------------------------- |
| `pix_transfer_key`* | string | Identificador único da transação PIX. | 36 |
| `refund_request_key`* | string | Identificador único da devolução. | 36 |
| `infraction_report_key`* | string | Identificador único da infração relacionada à devolução. Somente quando o tipo for FRAUDE | 36 |
| `refund_request_type` | enum | Tipo de solicitação de devolução. | **[Enumeradores refund_request_type](#enumeradores-refund_request_type)** |
| `requested_amount`* | float | Valor da devolução | - |
| `refund_request_status`* | enum | Status . | **[Enumeradores refund_request_status](#enumeradores-refund_request_status)** |
| `contested_participant`* | string | ISPB do Participante Creditado (Contestado). | 8 |
| `requesting_participant`* | string | ISPB do Participante Debitado (Requisitante, o qual está pedindo a devolução). | 8 |
| `refund_request_details`* | string | Detalhes da devolução. | - |
| `analysis_result`* | enum | Resultado da análise de fechamento da devolução. | **[Enumeradores analysis_result](#enumeradores-analysis_result)** |
| `analysis_details`* | string | Detalhes da análise de fechamento da devolução. | - |
| `reject_reason`* | string | Motivo da rejeição da devolução, caso seja fechada com REJECTED. | **[Enumeradores reject_reason](#enumeradores-reject_reason)** |
| `refund_transfer_key`* | string | pix_transfer_key da transação de devolução, caso seja fechada com aceite. | - |
| `refunded_amount`* | float | Valor devolvido na transação de devolução. | - |
| `refund_request_direction`* | string | Direção da solicitação de devolução. | **[Enumeradores refund_request_direction](#enumeradores-refund_request_direction)** |
| `created_at` * | string | Data de criação da Solicitação de Devolução | 24 |
### Enumeradores refund_request_status
| Campo | Descrição |
| ----------- | ---------------------------------------------------------------------------- |
| `open` | Solicitação de Devolução foi criada e está aberta no BACEN. |
| `cancelled` | Solicitação de Devolução está cancelada no BACEN |
| `closed` | Solicitação de Devolução está fechada no BACEN |
### Enumeradores refund_request_type
| Campo | Descrição |
| ------------------ | ------------------------------------------------------ |
| `fraud` | Solicitação de Devolução originada de uma fraude. |
| `operational_flaw` | Solicitação de Devolução originada de um erro interno. |
### Enumeradores analysis_result
| Campo | Descrição |
| -------------------- | ------------------------------------------------- |
| `totally_accepted` | Solicitação de Devolução foi totalmente aceita. |
| `partially_accepted` | Solicitação de Devolução foi parcialmente aceita; |
| `rejected` | Solicitação de Devolução foi rejeitada. |
### Enumeradores reject_reason
| Campo | Descrição |
| ----------------- | -------------------------------------------------------------------------- |
| `no_balance` | Conta não possui saldo para realizar a devolução. |
| `account_closure` | Conta se encontra fechada e, portanto, não é possível realizar a devolução |
| `other` | Outro motivo |
### Enumeradores refund_request_direction
| Campo | Descrição |
| ---------- | ------------------------------------------------- |
| `outgoing` | Participante é originador do pedido de devolução. |
| `incoming` | Participante é o alvo do pedido de devolução |
---
# Listar Solicitações de Devolução
URL: /documentation/pix_indireto/devolucao/listar_solicitacoes
Caso o Participante Indireto solicite a listagem de Solicitações de Devolução, pode fazê-lo por meio da rota abaixo.
:::danger IMPORTANTE
O Banco Central do Brasil define que, dentro de um período de 1 dia do recebimento da Solicitação de Devolução pelo Participante Indireto, a Devolução precisa ser fechada .
Caso haja atraso por parte do Participante Indireto, a QI Tech irá fechar a Solicitação de Devolução, com o status de totally_accepted , a fim de que a instituição não seja penalizada pelo Banco Central do Brasil.
:::
## Request
ENDPOINT /pix/refund_requests
MÉTODO GET
### Query Params
| Campo | Tipo | Descrição | Caracteres |
| ----------------------- | ------- | --------------------------------------- | ----------------------------------------------------------------------------- |
| `refund_request_status` | enum | Status do Relato de Infração. | **[Enumeradores refund_request_status](#enumeradores-refund_request_status)** |
| `refund_request_type` | enum | Tipo do Relato de Infração. | **[Enumeradores refund_request_type](#enumeradores-refund_request_type)** |
| `initial_date` | string | Data inicial de busca. | **[Formato de data](#formato-de-data)** |
| `final_date` | string | Data final de busca. | **[Formato de data](#formato-de-data)** |
| `page_number` | integer | Página atual que está sendo consultada. | - |
| `page_size` | integer | Quantidade de resultados por página. | - |
### Enumeradores refund_request_status
| Campo | Tipo | Descrição | Caracteres |
| ----------- | ------ | ---------------------------------------------------------------------------- | ---------- |
| `open` | string | Solicitação de Devolução foi criada e está aberto no BACEN. | 4 |
| `cancelled` | string | Solicitação de Devolução está cancelada no BACEN. | 9 |
| `closed` | string | Solicitação de Devolução está fechada no BACEN. | 6 |
### Enumeradores refund_request_type
| Campo | Tipo | Descrição | Caracteres |
| ------------------ | ------ | ------------------------------------------------------ | ---------- |
| `fraud` | string | Solicitação de Devolução originada de uma fraude. | 5 |
| `operational_flaw` | string | Solicitação de Devolução originada de um erro interno. | 16 |
### Formato de data
| Campo | Tipo | Descrição | Caracteres |
| -------------- | ------ | --------------------------------------------------------------------------- | ---------- |
| `initial_date` | string | Data de inicio para a procura, em formato "%Y-%m-%d. Exemplo: "2023-10-09". | 10 |
| `final_date` | string | Data final para a procura, em formato "%Y-%m-%d. Exemplo: "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
| Campo | Tipo | Descrição | Caracteres |
| --------------------------- | ------ | ----------------------------------------------------------------------------------------- | ---------------------------------------------------------------------------------- |
| `pix_transfer_key`* | string | Identificador único da transação PIX. | 36 |
| `refund_request_key`* | string | Identificador único da devolução. | 36 |
| `infraction_report_key`* | string | Identificador único da infração relacionada à devolução. Somente quando o tipo for FRAUDE | 36 |
| `refund_request_type` | enum | Tipo de solicitação de devolução. | **[Enumeradores refund_request_type](#enumeradores-refund_request_type)** |
| `requested_amount`* | float | Valor da devolução | - |
| `refund_request_status`* | enum | Status . | **[Enumeradores refund_request_status](#enumeradores-refund_request_status)** |
| `contested_participant`* | string | ISPB do Participante Creditado (Contestado). | 8 |
| `requesting_participant`* | string | ISPB do Participante Debitado (Requisitante, o qual está pedindo a devolução). | 8 |
| `refund_request_details`* | string | Detalhes da devolução. | - |
| `analysis_result`* | enum | Resultado da análise de fechamento da devolução. | **[Enumeradores analysis_result](#enumeradores-analysis_result)** |
| `analysis_details`* | string | Detalhes da análise de fechamento da devolução. | - |
| `reject_reason`* | string | Motivo da rejeição da devolução, caso seja fechada com REJECTED. | **[Enumeradores reject_reason](#enumeradores-reject_reason)** |
| `refund_transfer_key`* | string | pix_transfer_key da transação de devolução, caso seja fechada com aceite. | - |
| `refunded_amount`* | float | Valor devolvido na transação de devolução. | - |
| `refund_events`* | object | Objeto eventos de pedido de devolução. | **[Objeto refund_events](#objetos-refund_events)** |
| `refund_request_direction`* | string | Direção da solicitação de devolução. | **[Enumeradores refund_request_direction](#enumeradores-refund_request_direction)** |
| `created_at` * | string | Data de criação da Solicitação de Devolução | 24 |
### Enumeradores refund_request_status
| Campo | Descrição |
| ----------- | ---------------------------------------------------------------------------- |
| `open` | Solicitação de Devolução foi criada e está aberta no BACEN. |
| `cancelled` | Solicitação de Devolução está cancelada no BACEN |
| `closed` | Solicitação de Devolução está fechada no BACEN |
### Enumeradores refund_request_type
| Campo | Descrição |
| ------------------ | ------------------------------------------------------ |
| `fraud` | Solicitação de Devolução originada de uma fraude. |
| `operational_flaw` | Solicitação de Devolução originada de um erro interno. |
### Enumeradores analysis_result
| Campo | Descrição |
| -------------------- | ------------------------------------------------- |
| `totally_accepted` | Solicitação de Devolução foi totalmente aceita. |
| `partially_accepted` | Solicitação de Devolução foi parcialmente aceita; |
| `rejected` | Solicitação de Devolução foi rejeitada. |
### Enumeradores reject_reason
| Campo | Descrição |
| ----------------- | -------------------------------------------------------------------------- |
| `no_balance` | Conta não possui saldo para realizar a devolução. |
| `account_closure` | Conta se encontra fechada e, portanto, não é possível realizar a devolução |
| `other` | Outro motivo |
### Enumeradores refund_request_direction
| Campo | Descrição |
| ---------- | ------------------------------------------------- |
| `outgoing` | Participante é originador do pedido de devolução. |
| `incoming` | Participante é o alvo do pedido de devolução |
### Objetos refund_events
| Campo | Descrição |
| --------------- | --------------------------------------------------------------------------------------------------------------------- |
| `event_type` | Tipo do evento de mudança da devolução. **[Enumeradores refund_request_status](#enumeradores-refund_request_status)** |
| `event_details` | Detalhes acerca do evento. |
| `created_at` | Data de criação do evento. |
---
# Introdução ao fluxo de Devolução
URL: /documentation/pix_indireto/devolucao/maquina_estados
## Introdução
O Banco Central do Brasil permite que, caso o Participante Indireto queira solicitar de volta para a conta um valor debitado em uma transação feita via PIX, este pode abrir uma Solicitação de Devolução.
:::info
Ressalta-se que apenas o Participante debitado pode abrir uma Solicitação de Devolução. Formalmente, o Participante o qual abre uma Solicitação de Devolução é chamado de requesting_participant .
:::
| Enumerador | Tradução | Descrição|
|---|---|---|
| open | aberto | Após o processamento da criação da Solicitação de Devolução, o mesmo fica aberto no BACEN.
| cancelled | cancelado | O cancelamento da Solicitação de Devolução foi processado pela QI Tech e está cancelado no BACEN.
| closed | fechado | O fechamento da Solicitação de Devolução foi processado pela QI Tech e está fechado no BACEN.
## Controle da Máquina de Estados
Mesmo o fluxo sendo síncrono , é necesário que se conheça os possíveis status os quais uma Solicitação de Devolução pode ter. Abaixo, está descrito o que o Participante Indireto pode esperar após abrir, cancelar, completar e receber uma Solicitação de Devolução.
### Participante Abre Solicitação de Devolução
O Participante Indireto pode solicitar a abertura de devolução de duas maneiras:
Por erro operacional (operational_flaw).
Por um relato de infração já fechado e aceito (refund_request)
Após a abertura, o status da devolução será de open
### Participante Cancela Solicitação de Devolução
Após o Participante ter aberto uma Solicitação de Devolução, é possível realizar o cancelamento desta, caso seja solicitado.
O Participante Indireto receberá uma resposta com o status de cancelled .
### Participante Recebe Solicitação de Devolução
Visto que outros Participantes podem abrir uma Solicitação de Devolução, é necessário que a outra ponta envolvida no fluxo possa saber recebê-lo, a fim de fechá-lo .
Diferentemente do Relato de Infração, o qual há um status intermediário de acknowledged , o Participante Indireto receberá, via webhook , uma requisição informando que há uma Solicitação de Devolução com o status open .
A diferença é de que, para esta requisição, o Participante Contestado é o Participante Indireto.
### Participante Fecha Solicitação de Devolução
Após a QI Tech, via webhook , informar o Participante Indireto de que há uma Solicitação de Devolução disponível, este pode fechar o relato.
Quando o Participante Indireto realizar este fluxo, enviará a requisição de fechamento para a QI Tech e receberá um status de closed
---
# Simulação de Cenários
URL: /documentation/pix_indireto/devolucao/simulacao_de_cenarios
Passo a passo para simular a efetivação de ações feitas por agentes externos. Essas simulações incluem recebimentos e atualizações de solicitações de devolução.
:::info Informação
Não há payload de retorno (response body) nessas requisições, somente response status de 201.
:::
## 1 - Simulação de recebimento de solicitação de devolução
Simula o recebimento de uma solicitação de devolução aberta por outra instituição.
:::info IMPORTANTE
É essencial possuir uma pix_transfer_key válida para mandar a request, não importando necessariamente as informações da outra parte da transferencia, visto que todas as informações do segundo participante serão substituidas no processo de mock.
:::
### Request
ENDPOINT /mock/pix/refund_request
MÉTODO POST
Request Body
:::info IMPORTANTE
Caso o tipo de devolução seja de FRAUD, é necessário haver um relato de infração fechado para a mesma 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",
}
```
### Objeto Request Body
| Campo | Tipo | Descrição | Máx. Caract. |
| -------------------------- | ------ | ------------------------------------------------------------------ | ------------------------------------------------------------------------- |
| `pix_transfer_key` * | string | Chave de identificação da transferência Pix no sistema QI (UUIDv4) | 36 |
| `refund_request_type` * | enum | Tipo de solicitação de devolução. | **[Enumeradores refund_request_type](#enumeradores-refund_request_type)** |
| `refund_request_status` * | string | Status inicial da solicitação de devolução. "open" | 36 |
| `refund_request_details` | string | Detalhes do relato da solicitação de devolução | 2000 |
### Enumeradores refund_request_type
| Campo | Tipo | Descrição | Caracteres |
| ------------------ | ------ | ------------------------------------------------------ | ---------- |
| `fraud` | string | Solicitação de Devolução originada de uma fraude. | 5 |
| `operational_flaw` | string | Solicitação de Devolução originada de um erro interno. | 16 |
## 2 - Simulação de atualização de uma solicitação de devolução
Simula a atualização de status de uma solicitação de devolução aberta pelo participante indireto.
As opções de simulação para atualização de uma solicitação de devolução são:
1 - Cancelamento: Simula o cancelamento (cancel), feito por um participante "alvo", sobre uma solicitação de devolução aberta por ele mesmo previamente.
2 - Fechamento: Simula o fechamento (close), feito por um participante "alvo", sobre uma solicitação de devolução aberta pelo participante indireto. É importante que esse relato ja tenha sido reconhecido aberto.
### Request
ENDPOINT /mock/pix/refund_request
MÉTODO PATCH
Request Body - Cancelamento
:::info IMPORTANTE
A Solicitação de devolução identificada pela refund_request_key ja deve ter sido previamente criada na simulação de criação de solicitação de devolução.
:::
```json
{
"refund_request_status": "cancelled",
"refund_request_key": "c3e5664f-04bb-4625-9ef3-c8555d210c71"
}
```
Request Body - Fechamento com Aceite Total
:::info IMPORTANTE
A Solicitação de devolução identificada pela refund_request_key ja deve ter sido previamente criado pelo participante indireto.
:::
:::info IMPORTANTE
A refund transfer key deve ter sido préviamente criada pelo mock de recebimento de devolução com valor IGUAL à transação original.
:::
```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 - Fechamento com Aceite Parcial
:::info IMPORTANTE
A Solicitação de devolução identificada pela refund_request_key ja deve ter sido previamente criado pelo participante indireto. Além disso, o valor devolvido não deve ser igual ou superior ao valor total da transação original.
:::
:::info IMPORTANTE
A refund transfer key deve ter sido préviamente criada pelo mock de recebimento de devolução com valor MENOR à transação original.
:::
```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 - Fechamento com Recusa
:::info IMPORTANTE
A Solicitação de devolução identificada pela refund_request_key ja deve ter sido previamente criado pelo participante indireto.
:::
```json
{
"refund_request_key": "47633091-7d44-4d10-9d00-1f937104e537",
"refund_request_status": "closed",
"analysis_result": "rejected",
"analysis_details": "Teste",
"reject_reason": "no_balance"
}
```
### Objeto Request Body
| Campo | Tipo | Descrição | Máx. Caract. |
| -------------------------- | ------ | --------------------------------------------------------------------------------------------------------------------------- | ------------ |
| `refund_request_status` * | string | Status inicial da solicitação de devolução. "cancelled", "closed" | 36 |
| `refund_request_key` * | string | Chave única da solicitação de devolução | 36 |
| `analysis_result` * | string | Resultado da análise da solicitação de devolução. "totally_accepted" ou "partially_accepted", "rejected". | 36 |
| `analysis_details` | string | Detalhes da análise da solicitação de devolução | 2000 |
| `refund_transfer_key` | float | Identificador da transferência de devolução, obrigatório no caso de aceite | 20 |
| `reject_reason` | string | Motivo da recusa de uma devolução (somente em analysis_result igual a rejected). "no_balance", "account_closure" ou "other" | 15 |
---
# Receber Solicitação de Devolução
URL: /documentation/pix_indireto/devolucao/webhooks_devolucao
:::danger Atenção!
Os webhooks da QI Tech não devem ser mapeadas de forma restrita.
Campos adicionais podem ser incluídos aos payloads dos webhooks retornados em nossas APIs.
:::
:::info Reenvio de Webhooks
Você pode consultar e reenviar webhooks seguindo as instruções detalhadas na documentação: [Reenvio de Webhooks](/documentation/notificacoes/reenvio_de_notificacoes).
:::
Visto que um outro Participante pode abrir uma Solicitação de Devoluçao, tendo como alvo o Participante Indireto, é necessário que a QI Tech notifique o Participante Indireto acerca da Solicitação de Devolução aberta por outro Participante.
A QI Tech notificará o Participante Indireto via webhook .
:::danger IMPORTANTE
O Banco Central do Brasil define que, dentro de um período de 1 dia do recebimento da Solicitação de Devolução pelo Participante Indireto, a Devolução precisa ser fechada .
Caso haja atraso por parte do Participante Indireto, a QI Tech irá fechar a Solicitação de Devolução, com o status de totally_accepted , a fim de que a instituição não seja penalizada pelo Banco Central do Brasil.
:::
## Webhook recebimento de Devolução (Falha Operacional)
**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 recebimento de Devolução (Fraude)
**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"
}
```
---
# Consulta de uma entidade Alias
URL: /documentation/pix_indireto/gerenciamento_de_alias/consultar_alias
Consulta de uma entidade Alias, ja cadastrada para uma conta existente.
## Request
ENDPOINT /account/ ACCOUNT_KEY /alias/ ALIAS_KEY
MÉTODO GET
### Path Params
| Campo | Tipo | Descrição | Caracteres |
|---------------|--------|-----------------------|------------|
| `account_key` | uuidv4 | Chave única da conta. | 36 |
| `alias_key` | uuidv4 | Chave única do alias. | 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
| Campo | Tipo | Descrição | Max. Caracteres |
|-------------------------|------------|----------------------------------------------------|---------------------------------------------------------|
| `alias_key` | string | Chave única do alias | 36 |
| `ispb` | string | Ispb da instituição financeira vinculada ao Alias | 36 |
| `account_branch` | string | Agência, sem o dígito verificador | 4 |
| `account_number` | string | Número de conta, sem o dígito verificador | 20 |
| `account_digit` | string | Dígito verificador da conta | 1 |
| `account_type` | enumerador | Tipo da conta | **[Enumerador account_type](#enumerador-account_type)** |
| `account_created_at` | string | Data de criação da conta | 20 |
| `owner_document_number` | string | Numero de CPF ou CNPJ | 14 |
| `owner_name` | string | Nome do dono da conta | 120 |
| `owner_trading_name` | string | Nome fantasia do dono da conta (somente para CNPJ) | 100 |
| `created_at` | string | Data de criação da requisição | 20 |
### Enumerador account_type
| Enumerador | Descrição |
|----------------------|---------------------|
| **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"
}
```
---
# Consulta de Alias por Request Control Key
URL: /documentation/pix_indireto/gerenciamento_de_alias/consultar_request_control_key
Retorno da alias_key obtida na criação de um Alias, utilizando a request_control_key originalmente atribuida para ela no
corpo da requisição original.
## Request
ENDPOINT /account/ ACCOUNT_KEY /alias
MÉTODO GET
### Path Params
| Campo | Tipo | Descrição | Caracteres |
|---------------|--------|-----------------------|------------|
| `account_key` | uuidv4 | Chave única da conta. | 36 |
### Query Params
| Campo | Tipo | Descrição | Caracteres |
|-------------------------|--------|-------------------------------------------------------|------------|
| `request_control_key` * | uuidv4 | UUID4 para fins de consulta sobre a requisição feita. | 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
| Campo | Tipo | Descrição | Max. Caracteres |
|-------------------------|------------|----------------------------------------------------|---------------------------------------------------------|
| `alias_key` | string | Chave única do alias | 36 |
| `ispb` | string | Ispb da instituição financeira vinculada ao Alias | 36 |
| `account_branch` | string | Agência, sem o dígito verificador | 4 |
| `account_number` | string | Número de conta, sem o dígito verificador | 20 |
| `account_digit` | string | Dígito verificador da conta | 1 |
| `account_type` | enumerador | Tipo da conta | **[Enumerador account_type](#enumerador-account_type)** |
| `account_created_at` | string | Data de criação da conta | 20 |
| `owner_document_number` | string | Numero de CPF ou CNPJ | 14 |
| `owner_name` | string | Nome do dono da conta | 120 |
| `owner_trading_name` | string | Nome fantasia do dono da conta (somente para CNPJ) | 100 |
| `created_at` | string | Data de criação da requisição | 20 |
### Enumerador account_type
| Enumerador | Descrição |
|----------------------|---------------------|
| **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"
}
```
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"
}
```
---
# Criação de uma entidade Alias
URL: /documentation/pix_indireto/gerenciamento_de_alias/criacao_de_alias
É o Fluxo responsável por criar entidades Alias, atreladas a uma conta jś existente.
## Request
ENDPOINT /account/ ACCOUNT_KEY /alias
MÉTODO 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
| Campo | Tipo | Descrição | Caracteres |
|---------------|--------|-----------------------|------------|
| `account_key` | uuidv4 | Chave única da conta. | 36 |
### Request Body Params
| Campo | Tipo | Descrição | Max. Caracteres |
|---------------------------|------------|----------------------------------------------------------------------------------|---------------------------------------------------------|
| `request_control_key` * | string | Chave única de identificação da request utilizada pelo cliente no formato uuidv4 | 36 |
| `account_branch` * | string | Agência, sem o dígito verificador | 4 |
| `account_number` * | string | Número de conta, sem o dígito verificador | 20 |
| `account_digit` * | string | Dígito verificador da conta | 1 |
| `account_type`* | enumerador | Tipo da conta | **[Enumerador account_type](#enumerador-account_type)** |
| `account_created_at` * | string | Data de criação da conta. Ex: "2022-09-24T19:46:43.001Z" | 20 |
| `owner_document_number` * | string | Numero de CPF ou CNPJ | 11(CPF) ou 14(CNPJ) |
| `owner_person_type` * | string | Tipo de dono da conta. Pode ser **legal** ou **natural** | 7 |
| `owner_name` * | string | Nome do dono da conta | 120 |
| `owner_trading_name` | string | Nome fantasia do dono da conta (opcional, e somente para CNPJ) | 100 |
### Enumerador account_type
| Enumerador | Descrição |
|----------------------|---------------------|
| **checking_account** | Conta Corrente |
| **salary_account** | Conta Salário |
| **saving_account** | Conta Poupança |
| **payment_account** | Conta de Pagamentos |
## 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
| Campo | Tipo | Descrição | Max. Caracteres |
|--------------|---------------|----------------------------------|-----------------|
| `alias_key` | uuidv4 | Chave única do alias | 36 |
| `created_at` | datetime Zulu | Data de realização da requisição | 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"
}
```
---
# Deleção de uma entidade Alias
URL: /documentation/pix_indireto/gerenciamento_de_alias/deletar_alias
Deleção de uma entidade Alias, já cadastrada para uma conta account existente.
## Request
ENDPOINT /account/ ACCOUNT_KEY /alias/ ALIAS_KEY
MÉTODO DELETE
### Path Params
| Campo | Tipo | Descrição | Caracteres |
|-------|------|-----------|------------|
| `account_key` | uuidv4 | Chave única da conta. | 36 |
| `alias_key` | uuidv4 | Chave única do alias. | 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 Dont 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"
}
```
---
# Introdução à entidade de Alias
URL: /documentation/pix_indireto/gerenciamento_de_alias/introducao_alias
A fim de manter e alinhar os dados em relação ao cadastro de chave PIX, conforme o Banco Central do Brasil requisita, o Participante Indireto deve registrar um Alias na QI Tech,
Todo Alias está, necessariamente, vinculado a uma conta a qual o Participante Indireto possui na QI Tech.
:::info Informação
Tudo o descrito nesta seção de introdução também está, de forma detalhada como o Participante Indireto deve tratar via API, na seções seguintes.
:::
## O que a entidade Alias representa?
A entidade Alias é uma 'máscara' dos dados da conta o qual o cliente do Participante Indireto possui cadastrado no próprio Participante Indireto. Ressalta-se que a QI Tech fará apenas as verificações de formatação em relação aos dados enviados pelo Participante Indireto a nós.
Por exemplo: validação de CPF, CNPJ, tamanho máximo de caracteres de um nome fantasia, etc.
Os dados os quais a QI Tech pede ao Participante Indireto enviar, em relação à conta de seu cliente, são apenas os necessários para o âmbito das funcionalidades do PIX.
## Alias na prática
Na prática, a entidade de Alias representa o cliente do Participante Indireto.
Um exemplo acerca da necessidade de criação de um Alias seria:
Participante Indireto possui uma conta, de account_key a520b977-d6b2-4f27-bef5-29760ebfd6a7 cadastrada na QI Tech,
Participante Indireto deseja vincular um cliente próprio a esta conta cadastrada na QI Tech,
Participante Indireto envia os dados do cliente (número da conta, agência, nome, nome fantasia, etc) para vincular a esta conta cadastrada na QI Tech,
QITech vincula o cliente do Participante Indireto à conta do Participante Indireto cadastrada.
Participante Indireto recebe uma chave única de identificaçã do Alias cadastrado.
Deste modo, o Participante Indireto pode solicitar a criação de uma chave PIX e a QI Tech conseguirá, efetivamente, comunicar-se com o Banco Central do Brasil com os dados necessários para o cadastro.
##### Representação de uso de Alias com relação de 1:N:
##### Representação de uso de Alias com relação de 1:1:
---
# Listagem de Alias
URL: /documentation/pix_indireto/gerenciamento_de_alias/listagem_de_alias
Listagem dos Alias de uma conta
## Request
ENDPOINT /account/ ACCOUNT_KEY /alias
MÉTODO GET
### Path Params
| Campo | Tipo | Descrição | Caracteres |
|---------------|--------|-----------------------|------------|
| `account_key` | uuidv4 | Chave única da conta. | 36 |
### Query Params
| Campo | Tipo | Descrição | Max Value |
|---------------|---------|-----------------------------------------|-----------|
| `page_number` | integer | Página atual que está sendo consultada. | - |
| `page_size` | integer | Quantidade de resultados por página. | 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
| Campo | Tipo | Descrição | Max. Caracteres |
|-------------------------|------------|----------------------------------------------------|---------------------------------------------------------|
| `alias_key` | string | Chave única do alias | 36 |
| `ispb` | string | Ispb da instituição financeira vinculada ao Alias | 36 |
| `account_branch` | string | Agência, sem o dígito verificador | 4 |
| `account_number` | string | Número de conta, sem o dígito verificador | 20 |
| `account_digit` | string | Dígito verificador da conta | 1 |
| `account_type` | enumerador | Tipo da conta | **[Enumerador account_type](#enumerador-account_type)** |
| `account_created_at` | string | Data de criação da conta | 20 |
| `owner_document_number` | string | Numero de CPF ou CNPJ | 14 |
| `owner_name` | string | Nome do dono da conta | 120 |
| `owner_trading_name` | string | Nome fantasia do dono da conta (somente para CNPJ) | 100 |
| `created_at` | string | Data de criação da requisição | 20 |
### Enumerador account_type
| Enumerador | Descrição |
|----------------------|---------------------|
| **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"
}
```
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"
}
```
---
# Introdução
URL: /documentation/pix_indireto/introducao
Na QI Tech, estamos orgulhosos de expandir nossos serviços através do serviço de PIX Indireto. Reconhecemos os desafios que algumas instituições podem enfrentar ao tentar se integrar ao PIX e, por isso, estamos comprometidos em tornar isso uma realidade fácil e acessível para todos.
Como participante direto do PIX, que opera com eficiência e segurança, implementamos uma solução de alta tecnologia que permite a bancos, instituições de pagamento e fintechs de todos os tamanhos se tornarem participantes indiretos, garantindo a todos os benefícios do PIX sem o peso dos custos operários e técnicos.
Nosso serviço de PIX Indireto proporciona uma integração simplificada e uma operação sem complicações, com custos reduzidos e compliance regulatório. Além disso, você não precisará se preocupar com os complexos processos técnicos; cuidaremos de tudo, permitindo que você se concentre no que é mais importante - seus clientes.
Com a QI Tech, você estará equipado para proporcionar aos seus clientes uma experiência de pagamento rápida, segura e disponível 24 horas por dia, 7 dias por semana. Nosso objetivo é facilitar sua transição para o PIX, permitindo que você ofereça o melhor serviço ao cliente.
Nas seções seguintes a esta introdução estão descritas as funcionalidades que um Participante Indireto pode executar, via API, no âmbito do PIX Indireto.
---
# Chaves PIX mockadas em ambiente de sandbox
URL: /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 |
## Empresas com CNPJ Alfanumérico
| Chave Pix | Tipo | Nome do titular | Documento do titular | Número da conta | Agencia da conta | ISPB | Participante |
|---|---|---|---|---|---|---|---|
| HSRMASY3000160 | cnpj | Empresa Alfa Mock 1 | HSRMASY3000160 | 1050001-2 | 1 | 416968 | BANCO INTER |
| 0ZSD0MBG000135 | cnpj | Empresa Alfa Mock 2 | 0ZSD0MBG000135 | 81550001-2 | 1 | 18236120 | NU PAGAMENTOS - IP |
| DDA9RHST000100 | cnpj | Empresa Alfa Mock 3 | DDA9RHST000100 | 1750001-9 | 1 | 37880206 | CORA SCD S.A. |
## 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 |
---
# Consulta de Dados de Chave Pix no Banco Central
URL: /documentation/pix_indireto/movimentacoes/consultar_chave_pix
## Request
ENDPOINT /pix_key/ PIX_KEY
MÉTODO GET
### Request Path Params
| Campo | Tipo | Descrição | Caracteres |
|-------------|--------|--------------------------------|------------|
| `pix_key` * | string | Chave PIX que será consultada. | 77 |
:::info Tipos de Chave Pix
A “pix_key” pode ser um CPF, CNPJ, E-mail, Celular ou uma Chave Aleatória (UUID), seguindo as seguintes formatações:
**CPF**: Número inteiro com 11 dígitos.
**CNPJ**: Número inteiro com 14 dígitos.
**E-mail**: Texto contendo ao menos um “@”.
**Celular**: Texto contendo os seguintes valores: “+55” + “DDD do celular“ + “Número Inteiro do Celular com no mínimo 8
e no máximo 9 dígitos”. Ex: “+5511987654321“.
**Chave Aleatória**: UUID4.
:::
### Request Query Params
| Campo | Tipo | Descrição | Caracteres |
|---------------|--------|-----------------------|------------|
| `alias_key` * | uuidv4 | Chave única do alias. | 36 |
:::info Utilização de tokens de consulta
Para que o token de consulta de chave pix seja cobrado da pessoa correta, é obrigatório que o `alias_key` seja enviado.
:::
## Response
STATUS 200
Response Body: Chave Ativa
```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"
}
```
| Campo | Tipo | Descrição | Max. Caracteres |
|--------------------------------|--------|----------------------------------------------------|-----------------|
| `pix_key` | string | Chave pix da consulta | 4 |
| `account_branch` | string | Agência, sem o dígito verificador | 4 |
| `account_digit` | string | Dígito verificador da conta | 1 |
| `account_number` | string | Número de conta, sem o dígito verificador | 20 |
| `account_type` | string | Definição do tipo de conta | 20 |
| `owner_person_type` | string | Tipo de dono da contaPode ser "legal" ou "natural" | 7 |
| `owner_masked_document_number` | string | Numero de CPF ou CNPJ | 14 |
| `end_to_end_id` | string | Chave unitária da transação PIX | 32 |
| `owner_name` | string | Nome do dono da conta | 120 |
| `owner_trading_name` | string | Nome fantasia do dono da conta (somente para CNPJ) | 100 |
| `ispb` | string | ISPB do Participate detentor da chave | 8 |
| `bank_code` | string | Código COMPE da instituição financeira | 3 |
| `financial_institution` | string | Nome da instituição financeira detentora da chave | 100 |
| `account_created_at` | string | Data de criação da conta | 20 |
STATUS 4XX
Response Body: Error
```json
{
"title": "titulo",
"description": "description in English",
"translation": "descrição em portugues",
"code": "codigo",
"extra_fields": {}
}
```
| Código HTTP | Código QI
`code` | Título
`title` | Descrição (eng)
`Description` | Descrição (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 |
---
# Consultar Transação Pix
URL: /documentation/pix_indireto/movimentacoes/consultar_pix
## Request
ENDPOINT /account/ ACCOUNT_KEY /alias/ ALIAS_KEY /pix_transfer/ PIX_TRANSFER_KEY / PIX_TRANSFER_DIRECTION
MÉTODO GET
### Request Path Params
| Campo | Tipo | Descrição |
|----------------------------|--------|--------------------------------------------------------------------------------------------------|
| `pix_transfer_direction` * | string | Filtro para indicar se uma transação é de entrada ou saída. Valores: **incoming** e **outgoing** |
| `account_key` * | string | Chave única de identificação da conta QI |
| `alias_key` * | string | Chave única do Alias |
| `pix_transfer_key` * | string | Chave única de identificação da transferência Pix |
:::caution Atenção
Será apenas permitida a visualização de uma transferência caso o requisitante tenha permissões no alias de saída da
transação. Caso o contrário um erro de não encontrado será retornado.
:::
## Response
STATUS 201
Response Body: Transferência Enviada (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ência Rejeitada (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: Devolução Enviada (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ência Recebida (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: Devolução Recebida (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ência Rejeitada (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": {}
}
```
| Código HTTP | Código QI
`code` | Título
`title` | Descrição (eng)
`Description` | Descrição (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 |
---
# Efetuar devolução de um Pix
URL: /documentation/pix_indireto/movimentacoes/devolucao_pix
A devolução de um Pix pode ser efetuada em até 90 dias a partir de seu recebimento.
## Request
ENDPOINT /account/ ACCOUNT_KEY /alias/ ALIAS_KEY /pix_transfer/ PIX_TRANSFER_KEY /reversal
MÉTODO POST
### Request Path Params
| Campo | Tipo | Descrição | Caracteres |
|--------------------|--------|--------------------------------------------------------------------|------------|
| `account_key` | string | Chave única da conta (UUIDv4) | 36 |
| `alias_key` | string | Chave única do alias (UUIDv4) | 36 |
| `pix_transfer_key` | string | chave de identificação da transferência Pix no sistema QI (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
| Campo | Tipo | Descrição | Caracteres |
|------------------------|--------|-------------------------------------------|---------------------------------------------------------------|
| `request_control_key`* | string | Chave de unicidade da requisição (UUIDv4) | 36 |
| `reversal_amount`* | number | Valor da devolução | 11 |
| `reversal_reason`* | string | Motivo da devolução | **[Enumerador reversal_reason](#enumerador-reversal_reason)** |
| `reversal_message` | string | Mensagem da devolução | 140 |
### Enumerador reversal_reason
| Enumerador | Descrição |
|--------------------|----------------------------------------------|
| **client_request** | Caso tenha sido requerido pelo dono da conta |
| **reconciliation** | Para reconciliação devido a erro operacional |
## Response
### Response Body
| Campo | Tipo | Descrição | Caracteres |
|-----------------------|--------|---------------------------------------------------------------------------------------------|------------|
| `reversal_status` | string | Enumerador de status da transação de devolução. Pode ser 'pending', 'sent' e 'rejected' | 36 |
| `transfer_amount` | number | Valor da transferência de devolução | 11 |
| `pix_transfer_key` | string | Chave da transação pix executada na devolução (UUIDv4) | 36 |
| `end_to_end_id` | string | Chave de idempotência de uma transação Pix dentro do SPI (Sistema de Pagamento Instantâneo) | 32 |
| `request_control_key` | string | Chave única de identificação da request utilizada pelo cliente (UUIDv4) | 36 |
| `created_at` | string | Data e hora da devolução | --- |
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 Informação
Caso seja retornado uma `pix_transfer_status` no estado de **pending**, a solicitação de Pix não deve ser retentada.
Esta transferência será reprocessada. É necessário verificar o status da transferência por meio da consulta de
transferência pix.
:::
Response Body: Reversão Pendente
```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: Reversão Rejeitada
```json
{
"title": "titulo",
"description": "description in English",
"translation": "descrição em portugues",
"code": "codigo",
"extra_fields": {
"pix_transfer_data": {
"request_control_key": "b6804f32-101e-4702-8fbc-c2dbc4c2caec",
"pix_transfer_key": "8cb70dea-9fb0-4a68-9572-99a72849c8d6",
"end_to_end_id": "E32402502202407112211Id9JbxoaiTf",
"pix_transfer_status": "rejected",
"created_at": "2021-10-22T20:30:23.459Z"
}
}
}
```
STATUS 400
:::info Informação
Além dos erros discriminados abaixo, a devolução pix pode receber como erro os demais estabelecidos
em [Transação Pix](./transacao/transacao_pix_manual_sync)
:::
| Código HTTP | Código QI
`code` | Título
`title` | Descrição (eng)
`Description` | Descrição (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 |
---
# Introdução à movimentações no âmbito do PIX
URL: /documentation/pix_indireto/movimentacoes/introducao_movimentacoes
O cliente do Participante Indireto (Alias) pode solicitar diversas funcionalidades em relação à transações no âmbito do
PIX. Dentre elas, estão:
Transação PIX manual
Transação PIX por chave
Transação PIX QRCode
Devolução de um PIX
### Tipos de transferência Pix (pix_transfer_type)
| Enumerador | Descrição |
|---------------------|---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|
| **manual** | Pix utilizando os dados da conta destino. Obrigatório enviar `target_account` |
| **key** | Pix utilizando uma chave pix. Obrigatório enviar `target_pix_key`. Recomendado enviar `end_to_end_id` da [consulta de chave](/documentation/pix_indireto/movimentacoes/consultar_chave_pix) pix caso tenha sido realizada |
| **static_qr_code** | Pix utilizando um QR code estático. Obrigatório enviar o `end_to_end_id` retornado na [decodificação do QR code](/documentation/pix/decodificar_qr_code) |
| **dynamic_qr_code** | Pix utilizando um QR code dinâmico. Obrigatório enviar o `end_to_end_id` retornado na [decodificação do QR code](/documentation/pix/decodificar_qr_code) |
| **reversal** | Devolução de um Pix |
Dentre estas funcionalidades, há o tipo de 'sincronicidade' de transação que um Participante Indireto pode optar por
fazer, de acordo com suas necessidades.
:::info Informação
Tudo o descrito nesta seção de introdução também está, de forma detalhada como o Participante Indireto deve tratar via
API, na seções seguintes.
:::
## End to end ID
Toda transação pix possui um identificador único no banco central. End to End ID é o identificador fim-a-fim de uma
transferência pix. É utilizado para controle de rate-limiting no Banco Central.
Cada cadastro de pessoa física ou jurídica possui um bucket para com o Banco Central. As requisições de consulta de
chave pix, consomem tokens desse bucket, que são recuperadas ao efetuar uma transação pix vinculada a uma consulta. O
vinculo entre uma consulta de chave pix e uma transação se dá por meio do End to End ID.
## Sincronicidade de uma movimentação
O Participante Indireto pode optar por realizar uma transação PIX de forma síncrona ou assíncrona. Em ambos os modos,
tem-se que a movimentação PIX será executada dentro do tempo estabelecido pelo Banco Central do Brasil.
:::info Informação
Nossa equipe configurará a o regime de sincronicidade a ser utilizado conforme acordado com o cliente.
:::
:::info Informação
Os endpoints, métodos, payloads e demais componentes da requisição são idênticos para o regime síncrono e assíncrono. A
diferença seria apenas que para o regime assíncrono, a resposta será sempre uma `pix_transfer` com status **pending**
caso tenha sido aprovada nas validações iniciais. Em seguida um webhook será enviado informando o status final da
transação (**sent** ou **rejected** ).
:::
## Retentativa de movimentações
Devido aos possíveis atrasos no sistema de mensageria no Banco Central do Brasil, em relação às movimentações PIX, a
QITech possui um mecanismo de retentativa das movimentações PIX, tanto para o modelo síncrono quanto assíncrono.
Caso este cenário aconteça, o Participante Indireto receberá um status HTTP 202, indicando que a transação foi enviada à
QITech e está pendente de confirmação por parte do Banco Central do Brasil. Assim que esta for retentada, o Participante
Indireto será informado, via webhook acerca da efetivação da transação.
---
# Simulação de cenários
URL: /documentation/pix_indireto/movimentacoes/simulacao
Passo a passo para simular a efetivação de ações feitas por agentes externos. Essas simulações inclúi transações de
entrada e devolução .
:::info Informação
Não há payload de retorno (response body) nessas requisições.
:::
## 1 - Simulação de entrada de PIX
### Request
ENDPOINT /mock/pix_transfer/incoming_pix_transfer
MÉTODO POST
Request Body
```json
{
"target_account_key": "fc6862c4-2b20-4057-8063-b8809866e494",
"target_alias_key": "c4332971-7cff-42eb-a117-7e6f0cd74db2",
"amount": 100.01
}
```
### Objeto Request Body
| Campo | Tipo | Descrição | Máx. Caract. |
|-------------------------|--------|---------------------------------|--------------|
| **target_account_key*** | string | Chave única da conta de destino | 36 |
| **target_alias_key** | string | Chave única do alias de destino | 36 |
| **amount*** | number | Valor da transação | 6 | |
## 2 - Simulação de pagamento de PIX QR Code
### Request
ENDPOINT /mock/pix_transfer/incoming_pix_qrcode
MÉTODO POST
Request Body
```json
{
"target_alias_key": "\",
"amount": "\",
"receiver_conciliation_id": "\"
}
```
### Objeto Request Body
| Campo | Tipo | Descrição | Máx. Caract. | Exemplo | Observação |
|-------------------------------|---------|-------------------------------------------|--------------|----------------------------------------|-------------------------|
| **target_alias_key*** | string | Chave única do alias de destino | 36 | "41112f46-0034-4007-85687-5e592173db2" | |
| **amount*** | decimal | Valor da transação | 6 | 1000.00 | Valor máximo de 100.000 | |
| **receiver_conciliation_id*** | string | id de conciliação do recebedor do qr code | 36 | 1000 | | |
## 3 - Simulação de devolução de PIX
Simula a devolução de uma transferência de saída Pix. Para isso o valor total das devoluções não deve exceder o valor da
transferência original. Para identificar a transação alvo, envie o `end_to_end_id` da transferência original.
### Request
ENDPOINT /mock/pix_transfer/reversal
MÉTODO POST
Request Body
```json
{
"end_to_end_id": "E35713491202309182110sSCNh25ooX2",
"amount": 100.00
}
```
### Objeto Request Body
| Campo | Tipo | Descrição | Máx. Caract. |
|--------------------|--------|---------------------------------------------|--------------|
| **end_to_end_id*** | string | Chave unitária da transação a ser devolvida | 32 |
| **amount*** | number | Valor a ser devolvido | 6 | |
## 4 - Simulação de transação em estado pendente de confirmação
Transações pix podem entrar em status **pending_confirmation** quando ocorre alguma demora no retorno da resposta da
transação Pix pelo Banco Central. Para simular este cenário, realize uma transação com a chave
pix `"target_pix_key": "0476f803-0129-430a-a66c-d2f0d7cf4aaa"` ou, para transferências pix do tipo **manual**,
utilize `"owner_document_number": "35586870002"` como número de documento do proprietário da conta de destino.
Para que o status da transação seja atualizado, realize a requisição abaixo com `transaction_status` de **sent** para
aprovar a transação, ou **rejected** para reprová-la.
### Request
ENDPOINT /mock/pix_transfer/pending_confirmation
MÉTODO 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
| Campo | Tipo | Descrição | Máx. Caract. |
|-----------------------------|--------|-----------------------------------------------------------------------|--------------|
| `end_to_end_id`* | string | Chave unitária da transação PIX | 36 |
| `transaction_status`* | enum | [Enumerador Transaction Status](#enumerador-transaction-status) |
| `status_reason_information` | objeto | [Objeto Status Reason Information](#objeto-status-reason-information) |
| `error_code` | string | Código de erro |
### Enumerador Transaction Status
| Enumerador | Descrição |
|--------------|-----------|
| **sent** | Concluído |
| **rejected** | Rejeitado |
### Objeto Status Reason Information
| Campo | Tipo | Descrição | Máx. Caract. |
|---------------------------|--------|-----------------------------------|--------------|
| `error_description` | string | Descrição do erro em inglês | 100 |
| `error_translation` | string | Descrição do erro em português | 100 |
| `error_short_description` | string | Descrição curta do erro em inglês | 100 |
## 5 - Simulação de transação rejeitada
Transações pix podem entrar em status **rejected** quando ocorre algum retorno esperado de recusa da
transação Pix pelo Banco Central ou PSP recebedor. Para simular este cenário, realize uma transação com a chave
pix `"target_pix_key": "b9380607-dac6-4e17-8ca7-eb761e3aa1dc"` ou, para transferências pix do tipo **manual**,
utilize `"owner_document_number": "66972913039"` ou `"owner_document_number": "50305556000164"` como número de documento do proprietário da conta de destino.
---
# Efetuar Transferencia Assíncrona para Pix Manual
URL: /documentation/pix_indireto/movimentacoes/transacao_async/transacao_pix_manual
## Request Manual
ENDPOINT /account/ ACCOUNT_KEY /alias/ ALIAS_KEY /pix_transfer
MÉTODO 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
| Campo | Tipo | Descrição | Caracteres |
|-------|------|-----------|------------|
| `request_control_key` *| uuidv4 | UUID4 para fins de consulta sobre a requisição feita. | 36 |
| `pix_transfer_type` * | string | O Pix possui diferentes tipos de iniciação, o "manual" onde o usuário deve enviar os campos da conta de destino e conta de origem e o "key" onde o usuário deve enviar os campos da chave Pix do recebedor (conta de destino) e os dados da conta de origem. | 6 |
| `target_account` *| Object | Conta destino - Só deve ser enviada em transações do tipo "manual". | **[Objeto target_account](#objeto-target_account)** |
| `pix_message` | string | Mensagem opcional que acompanhará o Pix | 140 |
| `transaction_amount` * | float | Valor da transação realizada | 20 |
| `schedule_date` | date | Data de agendamento da transação (caso não seja enviado a transferência é realizada no momento da aprovação). | 10 |
### Objeto target_account
| Campo | Tipo | Descrição | Caracteres |
|-------|------|-----------|------------|
| `account_branch` * | string | Agência. | 4 |
| `account_digit` * | string | Dígito da conta | 1 |
| `account_number` * | string | Número da conta. | 8 |
| `owner_document_number` * | string | CPF ou CNPJ (apenas números) do titular da conta.| 14 |
| `owner_name` * | string | Nome do titular da conta. | 120 |
| `account_type` * | string | Tipo de conta, podendo ser `checking_account`, `deposit_account`, `guaranteed_account`, `investment_account`, `saving_account` | 20 |
| `owner_trading_name` | string | Nome fantasia para pessoa jurídica. Usado somente para CNPJ| 10 |
| `ispb` *| string | Código de oito dígitos que identifica os bancos no sistema de transferência de reserva do Banco Central. | 8 |
:::info HTTP Status 202 Accepted
No pix assíncrono, toda transação retorna **http status 202 Accepted**, a solicitação de Pix **não deve ser retentada**. Neste cenário, a transação será efetuada oportunamente e será atualizada por meio do [Webhook de Atualização de Transação](/documentation/pix_indireto/movimentacoes/webhook/webhook_transacao).
É possível ainda consultar o status da transação por meio do endpoint [/account/ACCOUNT_KEY/alias/ALIAS_KEY/pix_transfer/PIX_TRANSFER_KEY](/documentation/pix_indireto/movimentacoes/consultar_pix).
:::
## Response
STATUS 202 Accepted
Response Body: Transferência manual
```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"
}
}
```
---
# Efetuar Transferencia Assíncrona via Chave Pix
URL: /documentation/pix_indireto/movimentacoes/transacao_async/transacao_pix_normal
## Request Normal
ENDPOINT /account/ ACCOUNT_KEY /alias/ ALIAS_KEY /pix_transfer
MÉTODO 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
| Campo | Tipo | Descrição | Caracteres |
|---------------------|--------|-----------------------|------------|
| `account_key` | uuidv4 | Chave única da conta. | 36 |
| `alias_key` | uuidv4 | Chave única do alias. | 36 |
### Body Param
| Campo | Tipo | Descrição | Max. Caracteres |
|---------|------|-----------|------------|
| `request_control_key` *| uuidv4 | UUID4 para fins de consulta sobre a requisição feita. | 36 |
| `pix_transfer_type` * | string | O Pix possui diferentes tipos de iniciação, o "manual" onde o usuário deve enviar os campos da conta de destino e conta de origem e o "key" onde o usuário deve enviar os campos da chave Pix do recebedor (conta de destino) e os dados da conta de origem. | 6 |
| `transfer_time` * | string | Informação de sincronicidade da trasação, utilizada para definir quando a transação será processada. Caso seja "synchronous", a transação sera efetuada imediatamente, porém respeitando-se um limite maximo de transações por minuto. Ja se for "asynchronous", a transação será processada em um | 200 |
| `target_pix_key` * | string | Chave Pix que irá receber a transação. | 200 |
| `pix_message` * | string | Mensagem opcional que acompanhará o Pix | 140 |
| `transaction_amount` * | float | Valor da transação realizada | 20 |
| `end_to_end_id` | string | chave de identificação única de uma transação ou consulta no Banco Central. Exemplo: E3240250220210615135810450327042 | 32 |
| `schedule_date` | date | Data de agendamento da transação (caso não seja enviado a transferência é realizada no momento da aprovação). | 10 |
:::info HTTP Status 202 Accepted
No pix assíncrono, toda transação retorna **http status 202 Accepted**, a solicitação de Pix **não deve ser retentada**. Neste cenário, a transação será efetuada oportunamente e será atualizada por meio do [Webhook de Atualização de Transação](/documentation/pix_indireto/movimentacoes/webhook/webhook_transacao).
É possível ainda consultar o status da transação por meio do 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"
}
}
```
---
# Efetuar Transferencia Assíncrona para Pix Qr Code
URL: /documentation/pix_indireto/movimentacoes/transacao_async/transacao_pix_qr_code
## Request Qr Code
ENDPOINT /account/ ACCOUNT_KEY /alias/ ALIAS_KEY /pix_transfer
MÉTODO 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
| Campo | Tipo | Descrição | Max. Caracteres |
|---------|------|-----------|------------|
| `request_control_key` *| uuidv4 | UUID4 para fins de consulta sobre a requisição feita. | 36 |
| `pix_transfer_type` * | string | O Pix possui diferentes tipos de iniciação, o "manual" onde o usuário deve enviar os campos da conta de destino e conta de origem e o "key" onde o usuário deve enviar os campos da chave Pix do recebedor (conta de destino) e os dados da conta de origem. | 6 |
| `target_pix_key` * | string | Chave Pix que irá receber a transação. | 200 |
| `pix_message` | string | Mensagem opcional que acompanhará o Pix | 140 |
| `transaction_amount` * | float | Valor da transação realizada | 20 |
| `end_to_end_id` | string | chave de identificação única de uma transação ou consulta no Banco Central. Exemplo: E3240250220210615135810450327042 | 32 |
| `schedule_date` | date | Data de agendamento da transação (caso não seja enviado a transferência é realizada no momento da aprovação). | 10 |
| `receiver_conciliation_id` * | string | Identicação de conciliação do recebedor. Gerada ao decodar um Qr Code | 10 |
:::info HTTP Status 202 Accepted
No pix assíncrono, toda transação retorna **http status 202 Accepted**, a solicitação de Pix **não deve ser retentada**. Neste cenário, a transação será efetuada oportunamente e será atualizada por meio do [Webhook de Atualização de Transação](/documentation/pix_indireto/movimentacoes/webhook/webhook_transacao).
É possível ainda consultar o status da transação por meio do 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
Caso seja retornado **http status 202**, a solicitação de Pix **não deve ser retentada**. É preciso checar o status da solicitação de transferência Pix através de um GET na rota [/baas/pix/pix_transfer](/documentation/pix/pesquisar_por_transferencia_pix_de_saida).
:::
---
# Transação Pix por Chave Pix
URL: /documentation/pix_indireto/movimentacoes/transacao/transacao_pix_chave_sync
## Request Manual
ENDPOINT /account/ ACCOUNT_KEY /alias/ ALIAS_KEY /pix_transfer
MÉTODO 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
| Campo | Tipo | Descrição | Caracteres |
|-------------------------|------------|-------------------------------------------------------------------------------------------------------|------------|
| `request_control_key` * | string | Chave única de identificação da request utilizada pelo cliente no formato uuid v4 | 36 |
| `pix_transfer_type` * | enumerador | Tipo do pix a ser realizado. Para o caso de transferência por chave deve ser **key** | "key" |
| `target_pix_key` * | string | Chave pix da conta a ser enviada a transação | 100 |
| `transaction_amount` * | number | Valor da transferencia | 10 |
| `end_to_end_id` * | string | Chave de idempotência de uma transação Pix - só deve ser enviado se o tipo de transferência for "key" | 32 |
| `pix_message` | string | Mensagem a ser enviada junto à transferência Pix | 140 |
:::info Aviso
Um `end_to_end_id` deve ser enviado referente
á [consulta de chave](/documentation/pix_indireto/movimentacoes/consultar_chave_pix).
:::
:::danger Aviso
O `end_to_end_id` da consulta deve ter sido feito em nome do alias que solicitará a movimentação!
:::
:::danger Aviso
Um `end_to_end_id` só pode ser utilizado para uma única transferência, não importando se tenha sido bem sucedida ou não.
:::
## Response
STATUS 201
Response Body: Transferência Enviada
```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 Informação
Caso seja retornado uma `pix_transfer_status` no estado de **pending**, a solicitação de Pix não deve ser retentada.
Esta transferência será reprocessada. É necessário verificar o status da transferência por meio da consulta de
transferência pix.
:::
Response Body: Transferência Pendente
```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ência Rejeitada
```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": {}
}
```
| Código HTTP | Código QI
`code` | Título
`title` | Descrição (eng)
`Description` | Descrição (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 |
---
# Transação Pix Manual
URL: /documentation/pix_indireto/movimentacoes/transacao/transacao_pix_manual_sync
## Request Manual
ENDPOINT /account/ ACCOUNT_KEY /alias/ ALIAS_KEY /pix_transfer
MÉTODO 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
| Campo | Tipo | Descrição | Caracteres |
|-------------------------|------------|--------------------------------------------------------------------------------------|-----------------------------------------------------|
| `request_control_key` * | string | Chave única de identificação da request utilizada pelo cliente no formato uuid v4 | 36 |
| `pix_transfer_type` * | enumerador | Tipo do pix a ser realizado. Para o caso de transferência manual deve ser **manual** | "manual" |
| `target_account` * | Object | Conta destino - Só deve ser enviada em transações do tipo "manual" | **[Objeto target_account](#objeto-target_account)** | 10 |
| `transaction_amount` * | number | Valor da transferencia | 10 |
| `pix_message` | string | Mensagem a ser enviada junto à transferência Pix | 140 |
:::warning Aviso
Um `end_to_end_id` só pode ser utilizado para uma única transferência, não importando se tenha sido bem sucedida ou não.
:::
### Objeto target_account
| Campo | Tipo | Descrição | Caracteres |
|---------------------------|------------|---------------------------------------------------------------------------------------------------------|---------------------------------------------------------|
| `account_branch` * | string | Agência da conta | 6 |
| `account_digit` * | string | Dígito da conta | 1 |
| `account_number` * | string | Número da conta | 20 |
| `owner_document_number` * | string | CPF ou CNPJ (apenas números) do titular da conta | 14 |
| `owner_name` * | string | Nome do titular da conta | 150 |
| `account_type`* | enumerador | Tipo da conta | **[Enumerador account_type](#enumerador-account_type)** |
| `ispb` * | string | Código de oito dígitos que identifica os bancos no sistema de transferência de reserva do Banco Central | 8 |
### Enumerador account_type
| Enumerador | Descrição |
|----------------------|---------------------|
| **checking_account** | Conta Corrente |
| **salary_account** | Conta Salário |
| **saving_account** | Conta Poupança |
| **payment_account** | Conta de Pagamentos |
## Response
STATUS 201
Response Body: Transferência Enviada
```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 Informação
Caso seja retornado uma `pix_transfer_status` no estado de **pending**, a solicitação de Pix não deve ser retentada.
Esta transferência será reprocessada. É necessário verificar o status da transferência por meio da consulta de
transferência pix.
:::
Response Body: Transferência Pendente
```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ência Rejeitada
```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": {}
}
```
| Código HTTP | Código QI
`code` | Título
`title` | Descrição (eng)
`Description` | Descrição (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 |
---
# Transação Pix por QR Code
URL: /documentation/pix_indireto/movimentacoes/transacao/transacao_pix_qr_code_sync
## Request Manual
ENDPOINT /account/ ACCOUNT_KEY /alias/ ALIAS_KEY /pix_transfer
MÉTODO 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
| Campo | Tipo | Descrição | Caracteres |
|----------------------------|------------|--------------------------------------------------------------------------------------------------------------------------|---------------------------------------|
| `request_control_key` * | string | Chave única de identificação da request utilizada pelo cliente no formato uuid v4 | 36 |
| `pix_transfer_type` * | enumerador | Tipo do pix a ser realizado. Para o caso de transferência por QR code deve ser **static_qr_code** ou **dynamic_qr_code** | "static_qr_code" ou "dynamic_qr_code" |
| `target_pix_key` * | string | Chave pix da conta a ser enviada a transação | 100 |
| `receiver_conciliation_id` | string | Identicação de conciliação do recebedor | 35 |
| `transaction_amount` * | number | Valor da transferencia | 10 |
| `end_to_end_id` * | string | Chave de idempotência de uma transação Pix - só deve ser enviado se o tipo de transferência for "key" | 32 |
| `pix_message` | string | Mensagem a ser enviada junto à transferência Pix | 140 |
:::info Aviso
Um `end_to_end_id` deve ser enviado referente
á [decodificação do QR code](/documentation/pix/decodificar_qr_code).
:::
:::danger Aviso
O `end_to_end_id` da consulta deve ter sido feito em nome do alias que solicitará a movimentação!
:::
:::danger Aviso
Um `end_to_end_id` só pode ser utilizado para uma única transferência, não importando se tenha sido bem sucedida ou não.
:::
## Response
STATUS 201
Response Body: Transferência Enviada
```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 Informação
Caso seja retornado uma `pix_transfer_status` no estado de **pending**, a solicitação de Pix não deve ser retentada.
Esta transferência será reprocessada. É necessário verificar o status da transferência por meio da consulta de
transferência pix.
:::
Response Body: Transferência Pendente
```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ência Rejeitada
```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": {}
}
```
| Código HTTP | Código QI
`code` | Título
`title` | Descrição (eng)
`Description` | Descrição (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 para Devoluções de Pix
URL: /documentation/pix_indireto/movimentacoes/webhook/webhook_devolucao_outgoing_pix
Webhook que servirá para avisar sobre devoluções Pix que chegaram para um Alias.
## Webhook Request Body
**Request Body: Pix Recebido**
```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
| Campo | Tipo | Descrição | Max. Caracteres |
|----------------------------------|------------|-------------------------------------------------------------------------------------------------------|-------------------------------------------------------------------|
| `webhook_type` | string | Um enumerador que define o tipo de evento sendo reportado | 23 |
| `webhook_datetime` | string | Data e hora do envio do webhook | 20 |
| `pix_transfer_type` | enumerador | Tipo do pix realizado | **[Enumerador pix_transfer_type](#enumerador-pix_transfer_type)** |
| `target_pix_key` | string | Chave pix da conta a ser enviada a transação | 100 |
| `source_account` | Object | Conta destino - Só deve ser enviada em transações do tipo "manual" | **[Objeto source_account](#objeto-source_account)** |
| `transfer_amount` | number | Valor da transferencia | 10 |
| `receiver_conciliation_id` | string | Identicação de conciliação do recebedor | 35 |
| `end_to_end_id` | string | Chave de idempotência de uma transação Pix - só deve ser enviado se o tipo de transferência for "key" | 32 |
| `pix_message` | string | Mensagem a ser enviada junto à transferência Pix | 140 |
| `fee_amount` | number | Valor da transferencia | 10 |
| `pix_transfer_status` | string | Status da transação pix | 10 |
| `account_key` | string | Chave única de identificação da conta QI | 36 |
| `alias_key` | string | Chave única do Alias | 36 |
| `pix_transfer_key` | string | Chave única de identificação da transferência Pix | 36 |
| `original_outgoing_pix_transfer` | string | Chave única de identificação da transferência Pix de saída Original | 36 |
### Enumerador pix_transfer_type
| Enumerador | Descrição |
|---------------------|------------------------------------------|
| **manual** | Pix utilizando os dados da conta destino |
| **key** | Pix utilizando uma chave pix |
| **static_qr_code** | Pix utilizando um QR code estático |
| **dynamic_qr_code** | Pix utilizando um QR code dinâmico |
| **reversal** | Devolução Pix |
### Objeto source_account
| Campo | Tipo | Descrição | Caracteres |
|-------------------------|------------|---------------------------------------------------------------------------------------------------------|---------------------------------------------------------|
| `account_branch` | string | Agência da conta | 6 |
| `account_digit` | string | Dígito da conta | 1 |
| `account_number` | string | Número da conta | 20 |
| `owner_document_number` | string | CPF ou CNPJ (apenas números) do titular da conta | 14 |
| `owner_name` | string | Nome do titular da conta | 150 |
| `account_type` | enumerador | Tipo da conta | **[Enumerador account_type](#enumerador-account_type)** |
| `ispb` | string | Código de oito dígitos que identifica os bancos no sistema de transferência de reserva do Banco Central | 8 |
### Enumerador account_type
| Enumerador | Descrição |
|----------------------|---------------------|
| **checking_account** | Conta Corrente |
| **salary_account** | Conta Salário |
| **saving_account** | Conta Poupança |
| **payment_account** | Conta de Pagamentos |
---
# Webhook para Pix de Entrada
URL: /documentation/pix_indireto/movimentacoes/webhook/webhook_incoming_pix
Webhook que servirá para avisar sobre transações Pix que chegaram para um Alias.
## Webhook Request Body
**Request Body: Pix Recebido**
```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
| Campo | Tipo | Descrição | Max. Caracteres |
|----------------------------|------------|-------------------------------------------------------------------------------------------------------|-------------------------------------------------------------------|
| `webhook_type` | string | Um enumerador que define o tipo de evento sendo reportado | 23 |
| `webhook_datetime` | string | Data e hora do envio do webhook | 20 |
| `pix_transfer_type` | enumerador | Tipo do pix realizado | **[Enumerador pix_transfer_type](#enumerador-pix_transfer_type)** |
| `target_pix_key` | string | Chave pix da conta a ser enviada a transação | 100 |
| `source_account` | Object | Conta destino - Só deve ser enviada em transações do tipo "manual" | **[Objeto source_account](#objeto-source_account)** |
| `transfer_amount` | number | Valor da transferencia | 10 |
| `receiver_conciliation_id` | string | Identicação de conciliação do recebedor | 35 |
| `end_to_end_id` | string | Chave de idempotência de uma transação Pix - só deve ser enviado se o tipo de transferência for "key" | 32 |
| `pix_message` | string | Mensagem a ser enviada junto à transferência Pix | 140 |
| `fee_amount` | number | Valor da transferencia | 10 |
| `pix_transfer_status` | string | Status da transação pix | 10 |
| `account_key` | string | Chave única de identificação da conta QI | 36 |
| `alias_key` | string | Chave única do Alias | 36 |
| `pix_transfer_key` | string | Chave única de identificação da transferência Pix | 36 |
### Enumerador pix_transfer_type
| Enumerador | Descrição |
|---------------------|------------------------------------------|
| **manual** | Pix utilizando os dados da conta destino |
| **key** | Pix utilizando uma chave pix |
| **static_qr_code** | Pix utilizando um QR code estático |
| **dynamic_qr_code** | Pix utilizando um QR code dinâmico |
| **reversal** | Devolução Pix |
### Objeto source_account
| Campo | Tipo | Descrição | Caracteres |
|---------------------------|------------|---------------------------------------------------------------------------------------------------------|---------------------------------------------------------|
| `account_branch` * | string | Agência da conta | 6 |
| `account_digit` * | string | Dígito da conta | 1 |
| `account_number` * | string | Número da conta | 20 |
| `owner_document_number` * | string | CPF ou CNPJ (apenas números) do titular da conta | 14 |
| `owner_name` | string | Nome do titular da conta | 150 |
| `account_type`* | enumerador | Tipo da conta | **[Enumerador account_type](#enumerador-account_type)** |
| `ispb` * | string | Código de oito dígitos que identifica os bancos no sistema de transferência de reserva do Banco Central | 8 |
### Enumerador account_type
| Enumerador | Descrição |
|----------------------|---------------------|
| **checking_account** | Conta Corrente |
| **salary_account** | Conta Salário |
| **saving_account** | Conta Poupança |
| **payment_account** | Conta de Pagamentos |
---
# Webhook para Transações Pendentes
URL: /documentation/pix_indireto/movimentacoes/webhook/webhook_transacao
Webhook que servirá para avisar sobre conclusão de transações que foram originalmente respondidas como pendentes (retornaram com http status 202).
## Webhook Request Body
**Request Body: Transação Enviada**
```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: Transação Rejeitada**
```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
| Campo | Tipo | Descrição | Max. Caracteres |
|---------|---------|-----------------------------------------------------------|------------|
| `webhook_type` | string | Um enumerador que define o tipo de evento sendo reportado | 23 |
| `webhook_datetime` | string | Data e hora do envio do webhook | 20 |
| `request_control_key` | string | UUID4 para fins de consulta sobre a requisição feita. | 36 |
| `pix_transfer_key` | string | Chave de identificação da transferência Pix no sistema QI | 36 |
| `pix_transfer_status` | string | Status da transação. | 200 |
| `created_at` | string | Data e hora de criação da transação. | 20 |
---
# Cancelar um Pedido de Portabilidade
URL: /documentation/pix_indireto/portabilidade/cancelar_pedido_de_portabilidade
:::info
Cancelamentos de Pedido de Portabilidade podem ser realizados com as seguintes condições:
Status deve ser `waiting resolution`.
Se razão de cancelamento for `default`, prazo definido pelo campo `max_resolution_date` deve ter passado.
:::
A tabela abaixo define, a depender da razão, quem pode cancelar uma portabilidade.
| Razão | Doador | Reivindicador |
| ----------------- | ------ | ------------- |
| `client_request` | ✓ | ✓ |
| `account_closure` | ✓ | |
| `default` | | ✓ |
| `fraud` | ✓ | ✓ |
## Request
ENDPOINT /account/ ACCOUNT_KEY /alias/ ALIAS_KEY /claim/ CLAIM_REQUEST_KEY
MÉTODO PATCH
**Request Body**
```json
{
"request_control_key": "8a923886-afce-4116-ac1f-69bdffcf8da9",
"claim_request_status": "cancelled",
"cancellation_reason": "client_request",
}
```
| cancellation_reason | Descrição |
| ------------------- |---------------------------------------------------------------------------|
| `client_request` | O usuário reivindicador solicitou cancelamento do pedido de portabilidade |
| `account_closure` | A conta foi encerrada durante o processo de portabilidade |
| `default` | O prazo de validação de posse da chave do usuário reivindicador expirou |
| `fraud` | Houve fraude na abertura do pedido de portabilidade |
## 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 do pedido de portabilidade. | string |
| `created_at` | Data de criação do pedido de portabilidade | datetime string |
| `request_control_key` | Identificador UUID4 único da request. | uuid4 string |
| claim_request_status | Descrição |
| -------------------- | ---------------------------------------------------------------------------------------- |
| `waiting_resolution` | A notificação foi recebida pela contraparte |
| `confirmed` | O doador confirmou a reivindicação. Está aguardando o reivindicador encerrar o processo. |
| `cancelled` | O doador ou reivindicador cancelou o pedido de portabilidade |
| `completed` | Tanto o DICT quanto o reivindicador atualizaram suas bases com o novo vínculo |
---
# Completa um Pedido de Portabilidade
URL: /documentation/pix_indireto/portabilidade/completar_pedido_de_portabilidade
:::info
Completa a operação de reivindicação. Como consequência, o vínculo com a chave é criado.
## Request
ENDPOINT /account/ ACCOUNT_KEY /alias/ ALIAS_KEY /claim/ CLAIM_REQUEST_KEY
MÉTODO 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 do pedido de portabilidade. | string |
| `created_at` | Data de criação do pedido de portabilidade | datetime string |
| `request_control_key` | Identificador UUID4 único da request. | uuid4 string |
| claim_request_status | Descrição |
| -------------------- | ---------------------------------------------------------------------------------------- |
| `waiting_resolution` | A notificação foi recebida pela contraparte |
| `confirmed` | O doador confirmou a reivindicação. Está aguardando o reivindicador encerrar o processo. |
| `cancelled` | O doador ou reivindicador cancelou o pedido de portabilidade |
| `completed` | Tanto o DICT quanto o reivindicador atualizaram suas bases com o novo vínculo |
---
# Confirmar um Pedido de Portabilidade
URL: /documentation/pix_indireto/portabilidade/confirmar_pedido_de_portabilidade
Confirma a operação de reivindicação. Como consequência, vínculo da chave com participante doador é removido.
Status deve estar em `waiting_resolution`.
Para reivindicação de posse, caso razão seja `default`, o prazo de resolução (`max_resolution_date`) deve ter passado. Se a razão informada for `client_request`, o prazo de encerramento (`max_conclusion_date`) será adiantado para permitir o encerramento imediato pelo reivindicador.
As tabelas abaixo definem, a depender da razão e do tipo, quem pode confirmar.
| Ownership | Doador | Reivindicador |
|---------------------|--------|---------------|
| `client_request` | ✓ | |
| `account_closure` | | |
| `default` | ✓ | |
| Portability | Doador | Reivindicador |
|---------------------|--------|---------------|
| `client_request` | ✓ | |
| `account_closure` | ✓ | |
| `default` | | |
## Request
ENDPOINT /account/ ACCOUNT_KEY /alias/ ALIAS_KEY /claim/ CLAIM_REQUEST_KEY
MÉTODO 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 do pedido de portabilidade. | string |
| `created_at` | Data de criação do pedido de portabilidade | datetime string |
| `request_control_key` | Identificador UUID4 único da request. | uuid4 string |
---
# Consultar Pedidos de Portabilidade
URL: /documentation/pix_indireto/portabilidade/consultar_pedido_de_portabilidade
Descrição
## Request
ENDPOINT /account/ ACCOUNT_KEY /alias/ ALIAS_KEY /claim_request/ CLAIM_REQUEST_KEY
MÉTODO 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` | Razão do cancelamento. "client_request", "account_closure", "fraud", "default", "reconciliation" | string |
| `cancelled_by` | Agente que cancelou o pedido de portabilidade. "donor", "claimer" | string |
| `claim_request_direction` | Indica se o pedido de portabilidade foi recebido ou enviado. "incoming" ou "outgoing" | string |
| `claim_request_key` | Chave única de identificação da claim | string |
| `claim_request_status` | Status do pedido de portabilidade. | string |
| `claim_request_type` | Tipo de pedido de portabilidade. "ownership" ou "portability" | string |
| `confirmation_reason` | Razão da confirmação. "client_request", "account_closure", "fraud", "default", "reconciliation" | string |
| `created_at` | Data de criação do pedido de portabilidade | datetime string |
| `max_conclusion_date` | Data limite para encerrar o pedido de portabilidade. apenas para portabilidades do tipo "ownership" | string |
| `max_resolution_date` | Data limite para a resolução do pedido de portabilidade | string |
| `pix_key` | Chave pix do pedido de portabilidade | string |
| `pix_key_type` | Tipo de chave pix do pedido de portabilidade | string |
| `request_control_key` | Identificador UUID4 único da request. | uuid4 string |
| `claim_request_events` | Grupo de eventos relacionados ao pedido de portabilidade | uuid4 string |
| claim_request_status | Descrição |
| -------------------- | ---------------------------------------------------------------------------------------- |
| `waiting_resolution` | A notificação foi recebida pela contraparte |
| `confirmed` | O doador confirmou a reivindicação. Está aguardando o reivindicador encerrar o processo. |
| `cancelled` | O doador ou reivindicador cancelou o pedido de portabilidade |
| `completed` | Tanto o DICT quanto o reivindicador atualizaram suas bases com o novo vínculo |
---
# Criação de um Pedido de Portabilidade
URL: /documentation/pix_indireto/portabilidade/criar_pedido_de_portabilidade
## Request
ENDPOINT /account/ ACCOUNT_KEY /alias/ ALIAS_KEY /claim_request
MÉTODO POST
**Request Body**
```json
{
"request_control_key": "4b61f25d-b8b5-49cb-a391-e4878091ac3f",
"pix_key": "12345678000190",
"claim_request_type": "ownership",
"pix_key_type": "cnpj"
}
```
| Campo | Tipo | Descrição | Max. Caracteres |
| ----------------------- | ------ | ---------------------------------------------------------------------------------------- | --------------- |
| `request_control_key` * | string | UUID4 para fins de consulta sobre a requisição feita. | 36 |
| `pix_key` * | string | Chave pix referente ao pedido de portabilidade | 36 |
| `claim_request_type` * | string | Tipo de portabilidade. "ownership" para reivindicação e "portability" para portabilidade | 36 |
| `pix_key_type` * | string | Definição do tipo de chave. Podendo ser "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"
}
```
---
# Introdução a Pedidos de Portabilidade
URL: /documentation/pix_indireto/portabilidade/introducao_portabilidade
As reivindicações e portabilidades de chave são mecanismos especiais disponibilizados pelo banco central, para eventuais trocas de posse de chaves pix.
- Reivindicações são utilizadas nos casos que haja troca de posse de uma chave (**telefone** ou **email**) e o novo dono deseja criar um vínculo para sua conta, mas o dono anterior (antigo detentor do **telefone** ou **email**) já possui vínculo registrado no DICT com essa chave.
- Portabilidades são utilizadas em situações que o dono da chave deseja mudar a vinculação dela para outra conta sua, que está domiciliada em um participante diferente do atual.
Para cada tipo de recurso de mudança de posse, existem somente alguns tipos de chave habilitados, que são:
| Compatível | Reivindicação | Portabilidade |
|--------------|---------------|---------------|
| cpf | ✓ | |
| cnpj | ✓ | |
| phone_number | ✓ | ✓ |
| email | ✓ | ✓ |
| random_key | | |
No âmbito do Pix indireto, os mecanismos de mudança de posse funcionarão com os mesmos preceitos, sendo disponibilizadas rotas especiais na infraestrutura QI Tech para que as contas habilitadas a usar o Pix indireto sejam capazes de realizar requisições e receber respostas dos fluxos apresentados acima.
### 1. Fluxo de Reivindicador
:::info
Os fluxogramas abaixo representam os comportamentos pertinentes ao **fluxo de reivindicação** de chave pix
:::
##### 1.1. Participante Indireto QI Tech solicita abertura de pedido de portabilidade
##### 1.2. Banco Doador confirma o recebimento de pedido de portabilidade
##### 1.3. Participante Indireto QI Tech completa o pedido de portabilidade e vínculo de chave pix é criado
##### 1.4. Participante Indireto QI Tech completa o pedido de portabilidade e vínculo de chave pix é criado
:::warning Importante
Pedidos de Portabilidade com status **confirmed** só podem ser cancelados se forem do tipo **"fraud"**
:::
### 2. Fluxo de Doador
:::info
Os fluxogramas abaixo representam os comportamentos pertinentes ao **fluxo de doação** de chave pix
:::
#### 2.1. Banco Reivindicador abre um pedido de portabilidade
#### 2.2. Participante Indireto QI Tech confirma recebimento de pedido de portabilidade
#### 2.3. Banco Reivindicador completa um pedido de portabilidade
#### 2.4. Banco Reivindicador cancela um pedido de portabilidade
:::warning Importante
Pedidos de Portabilidade com status **confirmed** só podem ser cancelados se forem do tipo **"fraud"**
:::
---
# Consultar Pedidos de Portabilidade de um Alias
URL: /documentation/pix_indireto/portabilidade/listar_pedidos_de_portabilidade_de_um_alias
Descrição
## Request
ENDPOINT /account/ ACCOUNT_KEY /alias/ ALIAS_KEY /claim_requests
MÉTODO 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
}
}
```
---
# Webhook Atualização de Portabilidade
URL: /documentation/pix_indireto/portabilidade/webhook/webhook_atualizacao_do_pedido_de_portabilidade
**Request Body: Atualização de Pedido de Portabilidade**
```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
| Campo | Tipo | Descrição | Caracteres |
| ------------------------ | -------- | --------------------------------------------------------- | ---------- |
| `claim_request_status` * | string | Chave Pix que representa a conta de destino da transação. | - |
| `claim_request_key` * | string | Chave UUID4 identificadora do QR Code. | - |
| `updated_at` * | datetime | Data hora de pagamento QR Code. | - |
| claim_request_status | Descrição |
| -------------------- | ---------------------------------------------------------------------------------------- |
| `waiting_resolution` | A notificação foi recebida pela contraparte |
| `confirmed` | O doador confirmou a reivindicação. Está aguardando o reivindicador encerrar o processo. |
| `cancelled` | O doador ou reivindicador cancelou o pedido de portabilidade |
| `completed` | Tanto o DICT quanto o reivindicador atualizaram suas bases com o novo vínculo |
---
# Webhook Registro Externo de Portabilidade
URL: /documentation/pix_indireto/portabilidade/webhook/webhook_receber_registro_externo_de_portabilidade
**Request Body: Recebimento de Pedido de Portabilidade**
```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
| Campo | Tipo | Descrição | Caracteres |
| ------------------------ | -------- | --------------------------------------------------------- | ---------- |
| `claim_request_status` * | string | Chave Pix que representa a conta de destino da transação. | - |
| `claim_request_key` * | string | Chave UUID4 identificadora do QR Code. | - |
| `updated_at` * | datetime | Data hora de pagamento QR Code. | - |
| claim_request_status | Descrição | Valores |
| -------------------- | --------- | ---------- |
| waiting_resolution | Descrição | Caracteres |
| confirmed | Descrição | Caracteres |
| cancelled | Descrição | Caracteres |
| completed | Descrição | Caracteres |
---
# Consultar um QR Code Pix
URL: /documentation/pix_indireto/qr_code/consultar_qr_code
É possível buscar um QR Code específico do Alias pela qr_code_key gerada na criação do mesmo. Esse endpoint retornará todas as informações do mesmo, como status, pagamento, eventos.
## Request
ENDPOINT /account/ ACCOUNT_KEY /alias/ ALIAS_KEY /qrcode/ QR_CODE_KEY
MÉTODO 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"
}
```
| Campo | Tipo | Descrição | Caracteres |
|---|---|---|---|
| `request_control_key` * | string | Identificador UUID4 único da request que originou o QR Code. | - |
| `pix_key` * | string | Chave Pix que representa a conta de destino da transação. | - |
| `receiver_conciliation_id` * | string | Identificador do QR Code para conciliação após o pagamento. | - |
| `qr_code_key` * | string | Chave UUID4 identificadora do QR Code. | - |
| `qr_code_status` * | string | Status do QR Code. | - |
| `qr_code_type` * | string | Tipo do QR Code. | "dynamic_term" ou "dynamic_instant" |
| `amount` * | float | Valor do QR Code antes do cálculo de descontos ou juros e multas. | - |
| `expiration_seconds` | string | indica qual o tempo de validade do QR Code em segundos, padrão 1 dia. | - |
| `expiration_date` | date | Data de vencimento da cobrança (no formato "YYYY-MM-DD"). | - |
| `max_payment_days` | int32 | Dias máximos para pagamento da cobrança após vencimento. | - |
| `payer_name` * | string | Nome do pagador. | - |
| `payer_document_number` * | string | CPF/ CNPJ do pagador. | - |
| `payer_request` * | string | Mensagem ao pagador. | - |
| `rebate_amount` | float | Valor absoluto de abatimento antes do pagamento. | - |
| `interest_amount` | float | Valor absoluto por dia de atraso após o vencimento, caso seja pago um dia após o vencimento o valor total será o valor ordinario + multa. | - |
| `fine_amount` | float | Multa em valor absoluto após o vencimento. | - |
| `discounts` | array of objects | Configurações de desconto. | - |
| `additional_data` | array of objects | Informações que serão apresentadas para o pagador. | - |
| `pix_transfer_key` | string | Chave UUID4 identificadora da transação pix correspondente à liquidação do QR Code. | - |
| `paid_amount` | float | Valor do pagamento realizado, considerando multas, descontos e outros. | - |
| `base_64_payload` | string | URL do QR Code para pagamento, em base64. | - |
| `qr_code_events` | array of objects | Lista de mudanças de status pelas quais o QR Code passou. | - |
| `created_at` | datetime | Data e hora que o QR Code foi criado no sistema. | - |
### Objeto qr_code_status
| Campo | Tipo | Descrição | Caracteres |
|---|---|---|---|
| `active` | string | QR Code se encontra ativo e disponível para pagamento. | - |
| `finished` | string | QR Code pago. | - |
| `written_off` | string | QR Code foi baixado pelo cliente. | - |
| `bank_written_off` | string | QR Code foi baixado automaticamente devido prazo expirado. | - |
### Objeto discount
| Campo | Tipo | Descrição | Caracteres |
|---|---|---|---|
| `discount_value` * | float | Valor do desconto. | - |
| `discount_number` | int32 | Ordem que o desconto deve ser aplicado. | - |
| `discount_limit_date` | string | Data limite do desconto. | - |
### Objeto additional_data
| Campo | Tipo | Descrição | Caracteres |
|---|---|---|---|
| `key_name` * | string | Nome do campo | - |
| `value` | string | Valor do campo | - |
### Objeto qr_code_events
| Campo | Tipo | Descrição | Caracteres |
|---|---|---|---|
| `request_control_key` * | string | Identificador UUID4 único da request que originou o event. | - |
| `event_type` * | string | Tipo de evento | "registration", "write_off", "payment" |
| `created_at` * | datetime | Data e hora que o evento foi criado. | - |
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 não encontrada
```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"
}
```
---
# Criar QR Code Pix dinâmico com vencimento
URL: /documentation/pix_indireto/qr_code/Criar QR Code/criar_qr_code_dinamico_com_vencimento
O QR Code dinâmico com vencimento é utilizado para pagamentos onde o originador é conhecido e é desejado facilitar o pagamento, possibilitando adicionar prazos, descontos, multas, e juros. Este QR Code é utilizado normalmente em substituição ao boleto bancário.
## Request
ENDPOINT /account/ ACCOUNT_KEY /alias/ ALIAS_KEY /qrcode
MÉTODO POST
Request Body: Qr Code dinâmico com vencimento
```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
| Campo | Tipo | Descrição | Caracteres |
|---|---|---|---|
| `request_control_key` * | string | Identificador UUID4 único da request. | - |
| `qr_code_type` * | string | Tipo do QR Code dinâmico. | "dynamic_term" ou "dynamic_instant" |
| `amount` * | float | Valor do QR Code antes do cálculo de descontos ou juros e multas. | - |
| `receiver_conciliation_id` * | string | Identificador do QR Code para conciliação após o pagamento. | - |
| `payer_document_number` * | string | CPF/ CNPJ do pagador. | - |
| `payer_name` * | string | Nome do pagador. | - |
| `payer_request` * | string | Mensagem ao pagador. | - |
| `pix_key` * | string | Chave Pix que representa a conta de destino da transação. | - |
| `expiration_date` * | date | Data de vencimento da cobrança (no formato "YYYY-MM-DD"). | - |
| `max_payment_days` * | int32 | Dias máximo para pagamento da cobrança. | - |
| `fine_amount` * | float | Multa em valor absoluto após o vencimento. | - |
| `interest_amount` * | float | Valor absoluto por dia de atraso após o vencimento, caso seja pago um dia após o vencimento o valor total será o valor ordinario + multa. | - |
| `rebate_amount` * | float | Valor absoluto de abatimento antes do pagamento. | - |
| `discounts` | array of objects | Configurações de desconto. | - |
| `additional_data` | array of objects | Informações extras do QR Code utilizado para conciliações. | - |
### Objeto additional_data
| Campo | Tipo | Descrição | Caracteres |
|---|---|---|---|
| `key_name` * | string | Nome do campo | - |
| `value` * | string | Valor do campo | - |
### Objeto discount
| Campo | Tipo | Descrição | Caracteres |
|---|---|---|---|
| `discount_value` * | float | Valor do desconto. | - |
| `discount_number` | int32 | Ordem que o desconto deve ser aplicado. | - |
| `discount_limit_date` * | string | Data limite do desconto. | - |
## Response
STATUS 201 Created
Response Body: Criação Qr Code dinâmico com vencimento
```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",
}
```
| Campo | Tipo | Descrição | Caracteres |
|---|---|---|---|
| `request_control_key` * | string | Identificador UUID4 único da request. | - |
| `qr_code_key` * | string | Identificador do QR Code para futuras requisições. | - |
| `qr_code_status` * | string | Status do QR Code no sistema. | "active": default para criação. |
| `base_64_payload` * | string | URL do QR Code para pagamento, em base64. | - |
| `created_at` * | datetime | Data e hora que o QR Code foi criado no sistema. | - |
### Objeto qr_code_status
| Campo | Tipo | Descrição | Caracteres |
|---|---|---|---|
| `active` | string | QR Code se encontra ativo e disponível para pagamento. | - |
| `finished` | string | QR Code pago. | - |
| `written_off` | string | QR Code foi baixado pelo cliente. | - |
| `bank_written_off` | string | QR Code foi baixado automaticamente devido prazo expirado. | - |
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"
}
```
---
# Criar QR Code Pix dinâmico pagamento imediato
URL: /documentation/pix_indireto/qr_code/Criar QR Code/criar_qr_code_dinamico_imediato
O QR Code dinâmico imediato é utilizado para pagamentos que possuem um prazo de pagamento curto, normalmente providenciado em segundos, para operações rotineiras de cobrança para pagamento imediato.
## Request
Request Body: Qr Code dinâmico pagamento imediato
```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
| Campo | Tipo | Descrição | Caracteres |
|---|---|---|---|
| `request_control_key` * | string | Identificador UUID4 único da request. | - |
| `qr_code_type` * | string | Tipo do QR Code dinâmico. | "dynamic_term" ou "dynamic_instant" |
| `amount` * | float | Valor do QR Code antes do cálculo de descontos ou juros e multas. | - |
| `receiver_conciliation_id` * | string | Identificador do QR Code para conciliação após o pagamento. | - |
| `payer_document_number` * | string | CPF/ CNPJ do pagador. | - |
| `payer_name` * | string | Nome do pagador. | - |
| `payer_request` * | string | Mensagem ao pagador. | - |
| `pix_key` * | string | Chave Pix que representa a conta de destino da transação. | - |
| `expiration_seconds` | string | indica qual o tempo de validad e do QR Code em segundos, padrão 1 dia | - |
| `additional_data` | array of objects | Informações que serão apresentadas para o pagador. | - |
### Objeto additional_data
| Campo | Tipo | Descrição | Caracteres |
|---|---|---|---|
| `key_name` * | string | Nome do campo | - |
| `value` | string | Valor do campo | - |
## Response
STATUS 201 Created
Response Body: Criação Qr Code dinâmico pagamento imediato
```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",
}
```
| Campo | Tipo | Descrição | Caracteres |
|---|---|---|---|
| `request_control_key` * | string | Identificador UUID4 único da request. | - |
| `qr_code_key` * | string | Identificador do QR Code para futuras requisições. | - |
| `qr_code_status` * | string | Status do QR Code no sistema. | "active": default para criação. |
| `base_64_payload` * | string | URL do QR Code para pagamento, em base64. | - |
| `created_at` * | datetime | Data e hora que o QR Code foi criado no sistema. | - |
### Objeto qr_code_status
| Campo | Tipo | Descrição | Caracteres |
|---|---|---|---|
| `active` | string | QR Code se encontra ativo e disponível para pagamento. | - |
| `finished` | string | QR Code pago. | - |
| `written_off` | string | QR Code foi baixado pelo cliente. | - |
| `bank_written_off` | string | QR Code foi baixado automaticamente devido prazo expirado. | - |
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"
}
```
---
# Criar QR Code Pix Estático
URL: /documentation/pix_indireto/qr_code/Criar QR Code/criar_qr_code_estatico
O QR Code estático é utilizado para pagamentos onde não se sabe a identidade do pagador, muito menos quando irá pagar e quantos pagadores terão. Basicamente, consiste em uma chave, e opcionalmente um valor, codificados, e pode ser pago multiplas vezes, por referenciar apenas a chave.
## Request
ENDPOINT /account/ ACCOUNT_KEY /alias/ ALIAS_KEY /qrcode
MÉTODO POST
Request Body: Qr Code estático
```json
{
"request_control_key": "8a923886-afce-4116-ac1f-69bdffcf8da9",
"qr_code_type": "static",
"pix_key": "joaosilva@gmail.com",
"amount": 10.25,
}
```
### Body Params
| Campo | Tipo | Descrição | Caracteres |
|---|---|---|---|
| `request_control_key` * | string | Identificador UUID4 único da request. | - |
| `qr_code_type` * | string | Tipo do QR Code dinâmico. | "static" |
| `pix_key` * | string | Chave Pix que representa a conta de destino da transação. | - |
| `amount` | float | Valor do QR Code. | Se não passado, inserido a cargo do pagador. |
## Response
STATUS 201 Created
Response Body: Criação Qr Code estático
```json
{
"request_control_key": "037b46b1-0c67-4c0d-aac3-1e395dfdcb10",
"base_64_payload": ""
}
```
| Campo | Tipo | Descrição | Caracteres |
|---|---|---|---|
| `request_control_key` * | string | Identificador UUID4 único da request. | - |
| `base_64_payload` * | string | URL do QR Code para pagamento, em 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"
}
```
---
# Listar QR Codes de um alias
URL: /documentation/pix_indireto/qr_code/decodificar_qr_code
Os QR Codes Pix, utilizados no formato imagem ou URL, seguem um padrão, e devem ser decodificados seguindo uma lógica para extrair as informações do pagamento a ser realizado. Tendo a URL do QR Code, é possível decodificar todas as informações que originaram o mesmo. A decodificação gera um `end_to_end_id`, que deverá ser utilizado no pagamento do QR Code, juntamente com o receiver_conciliation_id, para identificar o pagamento do QR Code.
## Request
ENDPOINT /account/ ACCOUNT_KEY /alias/ ALIAS_KEY /qrcode/decode
MÉTODO POST
Request Body: Decode QR Code
```json
{
"qr_code_payload": "00020126580014br.gov.bcb.pix0136a23bf0e9-5175-4829-bf89-e8fe6ac09aa1520400005303986540530.005802BR5914TywinLannister6008saopaulo62070503***6304D4FD",
}
```
| Campo | Tipo | Descrição | Caracteres |
|---|---|---|---|
| `qr_code_payload` | string | URL do QR Code para pagamento (pix copia e cola). | - |
## Response
STATUS 200 Ok
Response Body: QR Code estático
```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: QR Code dinâmico com vencimento
```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 dinâmico com vencimento
```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
| Campo | Tipo | Descrição | Caracteres |
|---|---|---|---|
| `request_control_key` * | string | Identificador UUID4 único da request que originou o QR Code. | - |
| `end_to_end_id` * | string | Identificador único da transação Pix, de ponta a ponta. | - |
| `account_type` * | string | Tipo da conta de origem. | - |
| `amount` * | float | Valor do QR Code atualmente. | - |
| `category_code` * | string | Identificador do QR Code para conciliação após o pagamento. | - |// aaaaaaaaaaa
| `expiration_seconds` | string | Indica qual o tempo de validade do QR Code em segundos, padrão 1 dia. | - |
| `ispb_number` * | string | Identificador do banco. | - |aaaaaaaaaaaa
| `payer_document_number` * | string | CPF/ CNPJ do pagador. | - |
| `payer_name` * | string | Nome do pagador. | - |
| `payer_request` * | string | Mensagem ao pagador. | - |
| `receiver_conciliation_id` * | string | Identificador do QR Code para conciliação após o pagamento. | - |
| `receiver_url` * | string | URL para consulta dos dados do QR Code dinâmico. | - |
| `qr_code_status` * | string | Status do QR Code. | - |
| `target_account_branch` * | string | Agência da conta de destino. | - |
| `target_account_digit` * | string | Digito verificador da conta de destino. | - |
| `target_account_number` * | string | Número da conta de destino. | - |
| `target_bank_code` * | string | Código do banco de destino. | - |
| `target_bank_name` * | string | Nome do banco de destino. | - |
| `target_document_number` * | string | CPF/ CNPJ do cobrador. | - |
| `target_name` * | string | Nome do cobrador. | - |
| `target_trading_name` * | string | Nome fantasia do cobrador - apenas para CNPJ. | - |
| `target_pix_key` * | string | Chave pix do cobrador. | - |
| `qr_code_key` * | string | Chave UUID4 identificadora do QR Code. | - |
| `qr_code_payload` * | string | URL copia e cola do QR Code. | - |
| `qr_code_type` * | string | Tipo do QR Code. | "static", "dynamic_term" ou "dynamic_instant" |
| `max_payment_days` | int32 | Dias máximos para pagamento da cobrança após vencimento. | - |
| `expiration_date` | date | Data de vencimento da cobrança (no formato "YYYY-MM-DD"). | - |
| `fine_amount` | float | Multa em valor absoluto após o vencimento. | - |
| `interest_amount` | float | Valor absoluto por dia de atraso após o vencimento, caso seja pago um dia após o vencimento o valor total será o valor ordinario + multa. | - |
| `discount_amount` | float | Valor do desconto. | - |
| `original_amount` | float | Valor original do QR Code. | - |
| `additional_data` | array of objects | Informações que serão apresentadas para o pagador. | - |
| `presented_at` * | datetime | Data e hora que o QR Code foi decodificado. | - |
| `created_at` * | datetime | Data e hora que o QR Code foi criado no sistema. | - |
| `rebate_amount` | float | Valor absoluto de abatimento antes do pagamento. | - |
### Objeto qr_code_status
| Campo | Tipo | Descrição | Caracteres |
|---|---|---|---|
| `active` | string | QR Code se encontra ativo e disponível para pagamento. | - |
| `finished` | string | QR Code pago. | - |
| `written_off` | string | QR Code foi baixado pelo cliente. | - |
| `bank_written_off` | string | QR Code foi baixado automaticamente devido prazo expirado. | - |
### Objeto additional_data
| Campo | Tipo | Descrição | Caracteres |
|---|---|---|---|
| `key_name` * | string | Nome do campo | - |
| `value` | string | Valor do campo | - |
STATUS 400
Response Body: Impossível decodificar 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 não encontrado
```json
{
"title": "Not found",
"description": "Could not find the queried QR Code.",
"translation": "Não possível encontrar o QR Code buscado.",
"code": "QRI000002"
}
```
---
# Alterar um QR Code Pix
URL: /documentation/pix_indireto/qr_code/desativar_qr_code
Só é possível realizar a alteração de QR Code pix do tipo dinâmico. Ao realizar a mesma, identificada pela qr_code_key gerada na criação do QR Code, ele se torna inválido para posteriores pagamentos. Existem vários motivos para requisitar a alteração de um QR Code Pix, porém no sistema interno a inativação de um QR Code pode ser realizada por baixa requisitada pelo alias (write_off).
## Request
ENDPOINT /account/ ACCOUNT_KEY /alias/ ALIAS_KEY /qrcode/ QR_CODE_KEY
MÉTODO PATCH
Request Body: Baixa de QR Code
```json
{
"request_control_key": "76d4506d-31a4-48db-bc71-61068b138ffd",
"qr_code_status": "written_off",
}
```
| Campo | Tipo | Descrição | Caracteres |
|---|---|---|---|
| `request_control_key` * | string | Identificador UUID4 único da request. | - |
| `qr_code_status` * | string | Status do QR Code | - |
### Objeto qr_code_status
| Campo | Tipo | Descrição | Caracteres |
|---|---|---|---|
| `active` | string | QR Code se encontra ativo e disponível para pagamento. | - |
| `finished` | string | QR Code pago. | - |
| `written_off` | string | QR Code foi baixado pelo cliente. | - |
| `bank_written_off` | string | QR Code foi baixado automaticamente devido prazo expirado. | - |
## 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"
}
```
---
# Introdução QR Code pix
URL: /documentation/pix_indireto/qr_code/introducao_qr_code
Qualquer cliente do Participante Indireto (Alias) pode realizar operações de criação, consulta e baixa de QR Codes pix.
- Criação: Pode-se gerar QR Codes do tipo estático ou dinâmico. No último, é possível gerar um dinâmico para pagamento instantâneo ou com vencimento de longo prazo. Os tipos serão explicados melhor no processo de criação.
- Consulta: Tendo um QR Code ou a URL do QR Code (pix copia e cola), é possível consultar suas informações para posterior pagamento realizado. A consulta é chamada de decodificação de QR Code, e gera um `end_to_end_id` para posterior pagamento.
- Baixa: A baixa de um QR Code o torna inválido para pagamento. As principais causas para baixa são: prazo expirado, cancelamento do QR Code pelo alias, ou pagamento.
## Tipos de QR Code
O tipo do QR Code é definido na criação, pelo campo qr_code_type
| Nome | Enumerador | Descrição |
|---|---|---|
| Estático | `static` | Contém chave pix de destino e pode conter valor. Pode ser pago a qualquer momento, desde que a chave steja ativa. Não possui prazo de validade. Reutilizável.|
| Dinâmico para Pagamento Instantaneo | `dynamic_instant` | Cotém informações de pagamento, com pagador definido, valor e chave de conciliação. Prazo de pagamento em segundos. Uso único.|
| Dinâmico com Vencimento | `dynamic_term` | Cotém informações de pagamento, com pagador definido, valor e chave de conciliação. Prazo de pagamento em dias, informações de multa e juros. Uso único. |
## Pagamento de um QR Code
Após a decodificação de um QR Code e consulta da chave, é gerado um `end_to_end_id`, o qual é utilizado na ordem de pagamento para finalizar a transação. Além disso, no caso do QR Code Dinâmico, o campo `receiver_conciliation_id` é utilizado para identificar o QR Code específico sendo pago, utilizado pelo recebedor para dar continuidade na operação após pagamento.
Ao decodificar um QR Code, deve enviar uma ordem de pagamento pix com o `end_to_end_id` e `receiver_conciliation_id`, e o banco recebedor saberá dar prosseguimento. Seguindo a mesma linha, ao receber um pagamento pix do tipo `static_qr_code` ou `dynamic_qr_code`, será enviado um webhook, tratado também no final dessa seção de QR Code.
---
# Listar QR Codes de um alias
URL: /documentation/pix_indireto/qr_code/listar_alias_qr_codes
A busca de QR Codes é utilizado para gerenciar o status de QR Codes dinâmicos, averiguar pagamentos, baixas, etc.
## Request
ENDPOINT /account/ ACCOUNT_KEY /alias/ ALIAS_KEY /qrcodes
MÉTODO GET
### Path params
| Campo | Tipo | Descrição | Caracteres |
|----------------------------|---------|------------------------------------------------------------------|------------|
| `page` | integer | Número da página pesquisada (default = 0) | - |
| `page_size` | integer | Quantidade de itens por página (default = 15) | - |
| `qr_code_status` | string | Status dos qr codes buscados | - |
| `qr_code_type` | string | Tipo dos qr codes buscados | - |
| `request_control_key` | string | Request control key que originou o qr code | - |
## Response
STATUS 200 Ok
Response Body: Geral
```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
},
},
```
| Campo | Tipo | Descrição | Caracteres |
|---|---|---|---|
| `request_control_key` * | string | Identificador UUID4 único da request que originou o QR Code. | - |
| `pix_key` * | string | Chave Pix que representa a conta de destino da transação. | - |
| `receiver_conciliation_id` * | string | Identificador do QR Code para conciliação após o pagamento. | - |
| `qr_code_key` * | string | Chave UUID4 identificadora do QR Code. | - |
| `qr_code_status` * | string | Status do QR Code. | - |
| `qr_code_type` * | string | Tipo do QR Code. | "dynamic_term" ou "dynamic_instant" |
| `amount` * | float | Valor do QR Code antes do cálculo de descontos ou juros e multas. | - |
| `expiration_seconds` | string | indica qual o tempo de validade do QR Code em segundos, padrão 1 dia. | - |
| `expiration_date` | date | Data de vencimento da cobrança (no formato "YYYY-MM-DD"). | - |
| `max_payment_days` | int32 | Dias máximos para pagamento da cobrança após vencimento. | - |
| `payer_name` * | string | Nome do pagador. | - |
| `payer_document_number` * | string | CPF/ CNPJ do pagador. | - |
| `payer_request` * | string | Mensagem ao pagador. | - |
| `rebate_amount` | float | Valor absoluto de abatimento antes do pagamento. | - |
| `interest_amount` | float | Valor absoluto por dia de atraso após o vencimento, caso seja pago um dia após o vencimento o valor total será o valor ordinario + multa. | - |
| `fine_amount` | float | Multa em valor absoluto após o vencimento. | - |
| `discounts` | array of objects | Configurações de desconto. | - |
| `additional_data` | array of objects | Informações que serão apresentadas para o pagador. | - |
| `pix_transfer_key` | string | Chave UUID4 identificadora da transação pix correspondente à liquidação do QR Code. | - |
| `paid_amount` | float | Valor do pagamento realizado, considerando multas, descontos e outros. | - |
| `base_64_payload` | string | URL do QR Code para pagamento, em base64. | - |
| `qr_code_events` | array of objects | Lista de mudanças de status pelas quais o QR Code passou. | - |
| `created_at` | datetime | Data e hora que o QR Code foi criado no sistema. | - |
### Objeto qr_code_status
| Campo | Tipo | Descrição | Caracteres |
|---|---|---|---|
| `active` | string | QR Code se encontra ativo e disponível para pagamento. | - |
| `finished` | string | QR Code pago. | - |
| `written_off` | string | QR Code foi baixado pelo cliente. | - |
| `bank_written_off` | string | QR Code foi baixado automaticamente devido prazo expirado. | - |
### Objeto discount
| Campo | Tipo | Descrição | Caracteres |
|---|---|---|---|
| `discount_value` * | float | Valor do desconto. | - |
| `discount_number` | int32 | Ordem que o desconto deve ser aplicado. | - |
| `discount_limit_date` | string | Data limite do desconto. | - |
### Objeto additional_data
| Campo | Tipo | Descrição | Caracteres |
|---|---|---|---|
| `key_name` * | string | Nome do campo | - |
| `value` | string | Valor do campo | - |
### Objeto qr_code_events
| Campo | Tipo | Descrição | Caracteres |
|---|---|---|---|
| `request_control_key` * | string | Identificador UUID4 único da request que originou o event. | - |
| `event_type` * | string | Tipo de evento | "registration", "write_off", "payment" |
| `created_at` * | datetime | Data e hora que o evento foi criado. | - |
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 para Pix de Entrada de pagamento de QR Code
URL: /documentation/pix_indireto/qr_code/webhook_incoming_pix
Webhook que servirá para avisar sobre transações Pix que chegaram para um Alias de pagamento de um QR Code vinculado.
## Webhook Request Body
**Request Body: Pagamento QR Code Recebido**
```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
| Campo | Tipo | Descrição | Caracteres |
|---|---|---|---|
| `request_control_key` * | string | Identificador UUID4 único da request que originou o QR Code. | - |
| `pix_transfer_key` * | string | Chave Pix que representa a conta de destino da transação. | - |
| `qr_code_key` * | string | Chave UUID4 identificadora do QR Code. | - |
| `qr_code_type` * | string | Tipo do QR Code. | "static", "dynamic_term" ou "dynamic_instant" |
| `receiver_conciliation_id` * | string | Identificador do QR Code para conciliação após o pagamento. | - |
| `amount` * | string | Valor do pagamento. | - |
| `updated_at` * | datetime | Data hora de pagamento QR Code. | - |
---
# Cancelar Relato de Infração
URL: /documentation/pix_indireto/relato_de_infracao/cancelar_relato_infracao
Se um pedido de Relato de Infração foi gerado erroneamente e o Participante Indireto deseja cancelá-lo, é possível fazê-lo utilizando o endpoint citado abaixo.
:::danger IMPORTANTE
Ressalta-se que apenas o Participante o qual CRIOU o Relato de Infração pode cancelá-lo, e o cancelamento pode ser realizado mesmo que o status da infração seja de closed.
:::
:::info IMPORTANTE
Relatos de infração cancelados podem ser listados utilizando o endpoint [Listar Relatos de Infração](#listar-relatos-de-infração)
:::
## Request
ENDPOINT /pix/infraction_report/ INFRACTION_REPORT_KEY
MÉTODO PATCH
**Request Body**
```json
{
"infraction_report_status": "cancelled",
"request_control_key": "750cbfa0-f628-4944-a76c-9053bf1ebc87",
}
```
### Path Params
| Campo | Tipo | Descrição | Caracteres |
| ----------------------- | ------ | ------------------------------------------------------------- | ---------- |
| `infraction_report_key` | string | UUID4 do Relato de Infração criado o qual se deseja cancelar. | 36 |
### Body Params
| Campo | Tipo | Descrição | Caracteres |
| ---------------------------- | ------ | ---------------------------------------------------------------------------------- | ---------- |
| `infraction_report_status` * | string | Status o qual se deseja atualizar o Relato de Infração. | 36 |
| `request_control_key` * | string | Chave única de identificação da request utilizada pelo cliente no formato uuid v4. | 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
| Campo | Tipo | Descrição | Caracteres |
| ------------------------------- | ------ | --------------------------------------------------------------------------------------------- | ----------------------------------------------------------------------------------------- |
| `infraction_report_key` * | string | Identificador único do relato de infração. | 36 |
| `pix_transfer_key` * | string | Identificador único da transação PIX. | 36 |
| `end_to_end_id` * | string | Identificador único da transação PIX no BACEN. | 36 |
| `infraction_report_status` * | enum | Status acerca do Relato de Infração | **[Enumeradores infraction_report_status](#enumeradores-infraction_report_status)** |
| `infraction_report_situation` * | enum | Situação em que ocorreu a infração. | **[Enumeradores infraction_report_situation](#enumeradores-infraction_report_situation)** |
| `infraction_report_type` * | enum | Tipo de Relato de Infração. | **[Enumeradores infraction_report_type](#enumeradores-infraction_report_type)** |
| `infraction_report_details` | string | Detalhes acerca do Relato de Infração criado. | \<\= 2000 |
| `credited_participant` * | string | ISPB do Participante Creditado. | 8 |
| `debited_participant` * | string | ISPB do Participante Debitado. | 8 |
| `infraction_report_direction` * | enum | Enumerador acerca se o relato foi aberto pelo Participante Indireto ou por outro Participante | **[Enumeradores infraction_report_direction](#enumeradores-infraction_report_direction)** |
| `created_at` * | string | Data de criação do Relato de Infração | 24 |
| `updated_at` * | string | Data de atualização do Relato de Infração | 24 |
### Enumeradores infraction_report_status
| Campo | Tipo | Descrição | Caracteres |
| -------------- | ------ | ----------------------------------------------------------------------------- | ---------- |
| `open` | string | Relato de infração foi criado e está aberto no BACEN. | - |
| `acknowledged` | string | Relato de infração foi recebido pelo participante contestado | - |
| `cancelled` | string | Relato de infração está cancelado no BACEN | - |
| `closed` | string | Relato de infração está fechado no BACEN | - |
### Enumeradores infraction_report_situation
| Campo | Tipo | Descrição | Caracteres |
| ------------------- | ------ | ------------------------------------------------------- | ---------- |
| `scam` | string | Causa de golpe ou estelionato. | - |
| `account_takeover` | string | Causa de transação não autorizada pela conta de origem. | - |
| `coercion` | string | Causa de crime de coerção. | - |
| `fraudulent_access` | string | Causa de acesso fraudulento à conta de origem. | - |
| `other` | string | Quaisquer causas não aplicáveis às listadas acima. | - |
### Enumeradores infraction_report_type
| Campo | Tipo | Descrição | Caracteres |
| ------------------ | ------ | ---------------------------------------------------------------------- | ---------- |
| `refund_request` | string | Relato de infração será gerado a fim de se solicitar uma devolução. | - |
| `refund_cancelled` | string | Relato de infração será gerado pelo motivo de uma devolução cancelada. | - |
### Enumeradores infraction_report_direction
| Campo | Tipo | Descrição | Caracteres |
| ---------- | ------ | ------------------------------------------------------------- | ---------- |
| `incoming` | string | Relato de infração com participante indireto como alvo. | - |
| `outgoing` | string | Relato de infração com participante indireto como originador. | - |
---
# Consultar Relato de Infração
URL: /documentation/pix_indireto/relato_de_infracao/consultar_relato_infracao
O Participante Indireto pode consultar os dados acerca de um Relato de Infração, inclusive todas as alterações que ocorreram com o mesmo.
## Request
ENDPOINT /pix/infraction_report/ INFRACTION_REPORT_KEY
MÉTODO GET
### Path Params
| Campo | Tipo | Descrição | Caracteres |
| ----------------------- | ------ | ---------------------------- | ---------- |
| `infraction_report_key` | string | UUID4 do Relato de Infração. | 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
| Campo | Tipo | Descrição | Caracteres |
| ------------------------------- | ------ | --------------------------------------------------------------------------------------------- | ----------------------------------------------------------------------------------------- |
| `infraction_report_key` * | string | Identificador único do relato de infração. | 36 |
| `pix_transfer_key` * | string | Identificador único da transação PIX. | 36 |
| `end_to_end_id` * | string | Identificador único da transação PIX no BACEN. | 36 |
| `infraction_report_status` * | enum | Status . | **[Enumeradores infraction_report_status](#enumeradores-infraction_report_status)** |
| `infraction_report_situation` * | enum | Situação em que ocorreu a infração. | **[Enumeradores infraction_report_situation](#enumeradores-infraction_report_situation)** |
| `infraction_report_type` * | enum | Tipo de Relato de Infração. | **[Enumeradores infraction_report_type](#enumeradores-infraction_report_type)** |
| `infraction_report_details` | string | Detalhes acerca do Relato de Infração criado. | \<\= 2000 |
| `credited_participant` * | string | ISPB do Participante Creditado. | 8 |
| `debited_participant` * | string | ISPB do Participante Debitado. | 8 |
| `infraction_report_direction` * | enum | Enumerador acerca se o relato foi aberto pelo Participante Indireto ou por outro Participante | **[Enumeradores infraction_report_direction](#enumeradores-infraction_report_direction)** |
| `infraction_report_events`* | object | Eventos relacionados ao Relato de Infração. | **[Objetos infraction_report_events](#objetos-infraction_report_events)** |
| `created_at` * | string | Horário de criação do Relato de Infração | 24 |
| `updated_at` | string | Horário de atualização do Relato de Infração | 24 |
### Enumeradores infraction_report_status
| Campo | Tipo | Descrição | Caracteres |
| -------------- | ------ | ----------------------------------------------------------------------------- | ---------- |
| `open` | string | Relato de infração foi criado e está aberto no BACEN. | 4 |
| `acknowledged` | string | Relato de infração foi recebido pelo participante contestado | 12 |
| `cancelled` | string | Relato de infração está cancelado no BACEN | 9 |
| `closed` | string | Relato de infração está fechado no BACEN | 6 |
### Enumeradores infraction_report_situation
| Campo | Tipo | Descrição | Caracteres |
| ------------------- | ------ | ------------------------------------------------------- | ---------- |
| `scam` | string | Causa de golpe ou estelionato. | - |
| `account_takeover` | string | Causa de transação não autorizada pela conta de origem. | - |
| `coercion` | string | Causa de crime de coerção. | - |
| `fraudulent_access` | string | Causa de acesso fraudulento à conta de origem. | - |
| `other` | string | Quaisquer causas não aplicáveis às listadas acima. | - |
### Enumeradores infraction_report_type
| Campo | Tipo | Descrição | Caracteres |
| ------------------ | ------ | ---------------------------------------------------------------------- | ---------- |
| `refund_request` | string | Relato de infração será gerado a fim de se solicitar uma devolução. | - |
| `refund_cancelled` | string | Relato de infração será gerado pelo motivo de uma devolução cancelada. | - |
### Enumeradores infraction_report_direction
| Campo | Tipo | Descrição | Caracteres |
| ---------- | ------ | ------------------------------------------------------------- | ---------- |
| `incoming` | string | Relato de infração com participante indireto como alvo. | - |
| `outgoing` | string | Relato de infração com participante indireto como originador. | - |
### Objetos infraction_report_events
| Campo | Tipo | Descrição | Caracteres |
| --------------- | ------ | ---------------------------------------- | ----------------------------------------------------------------------------------- |
| `event_type` | enum | Mudança de status relacionada ao evento. | **[Enumeradores infraction_report_status](#enumeradores-infraction_report_status)** |
| `event_details` | string | Descrição do evento. | - |
| `created_at` * | string | Horário de criação do evento | 24 |
---
# Abrir Relato de Infração
URL: /documentation/pix_indireto/relato_de_infracao/criar_relato_infracao
O Relato de Infração é um dos serviços o qual compoẽ o Mecanismo Especial de Devolução (MED) como definido pelo Banco Central do Brasil.
Quando há um indício de uma transação, pedido de devolução ou cancelamento de pedido de devolução fraudulentos, é possível criar um relato de infração a fim de se informar o BACEN e o outro Participante que há uma irregularidade em uma destas operações citadas.
Tanto o Participante debitado quanto creditado podem criar um Relato de Infração.
:::caution **Atenção**
A fim de se compreender o fluxo de Relato de Infração, é necessário saber quais ENDPOINTS o Participante Indireto que criou o relato pode utilizar.
Quando o Participante Indireto abre um Relato de Infração, este pode (se necessário) cancelar o relato caso tenha sido gerado de maneira indevida.
Quando o Participante Indireto recebe um Relato de Infração, este deve fechá-lo informando o resultado da análise do relato.
Ambos os fluxos citados serão descritos nas seções seguintes.
:::
:::danger IMPORTANTE
O Banco Central do Brasil define que, dentro de um período de 7 dias do recebimento do Relato de Infração pelo Participante Indireto, o Relato precisa ser fechado .
Caso haja atraso por parte do Participante Indireto, a QI Tech irá fechar o Relato de Infração, com o status de agreed , a fim de que a instituição não seja penalizada pelo Banco Central do Brasil.
:::
:::info IMPORTANTE
Apenas o participante originador da transferência pode criar um relato de infração sobre a mesma
:::
## Request
ENDPOINT /pix/infraction_report
MÉTODO 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
| Campo | Tipo | Descrição | Caracteres |
| ----------------------------- | ------ | ----------------------------------------------------- | ----------------------------------------------------------------------------------------- |
| `request_control_key` * | uuidv4 | UUID4 para fins de consulta sobre a requisição feita. | 36 |
| `pix_transfer_key` * | uuidv4 | Identificador único da transação PIX. | 36 |
| `infraction_report_type` * | enum | Tipo de relato de infração a ser criado. | **[Enumeradores infraction_report_type](#enumeradores-infraction_report_type)** |
| `infraction_report_details` | string | Detalhes acerca do relato de infração a ser criado. | 10 |
| `infraction_report_situation` | string | Situação em que ocorreu a infração. | **[Enumeradores infraction_report_situation](#enumeradores-infraction_report_situation)** |
### Enumeradores infraction_report_type
| Campo | Tipo | Descrição | Caracteres |
| ------------------ | ------ | --------------------------------------------------------------------- | ---------- |
| `refund_cancelled` | string | Relato de infração será gerado pelo motivo de uma devolução cancelada | 16 |
| `refund_request` | string | Relato de infração será gerado a fim de se solicitar uma devolução | 14 |
### Enumeradores infraction_report_situation
| Campo | Tipo | Descrição | Caracteres |
| ------------------- | ------ | ------------------------------------------------------- | ---------- |
| `scam` | string | Causa de golpe ou estelionato. | - |
| `account_takeover` | string | Causa de transação não autorizada pela conta de origem. | - |
| `coercion` | string | Causa de crime de coerção. | - |
| `fraudulent_access` | string | Causa de acesso fraudulento à conta de origem. | - |
| `other` | string | Quaisquer causas não aplicáveis às listadas acima. | - |
## 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
| Campo | Tipo | Descrição | Caracteres |
| ------------------------------- | ------ | --------------------------------------------------------------------------------------------- | ----------------------------------------------------------------------------------------- |
| `infraction_report_key` * | string | Identificador único do relato de infração. | 36 |
| `pix_transfer_key` * | string | Identificador único da transação PIX. | 36 |
| `end_to_end_id` * | string | Identificador único da transação PIX no BACEN. | 36 |
| `infraction_report_status` * | enum | Status . | **[Enumeradores infraction_report_status](#enumeradores-infraction_report_status)** |
| `infraction_report_situation` * | enum | Situação em que ocorreu a infração. | **[Enumeradores infraction_report_situation](#enumeradores-infraction_report_situation)** |
| `infraction_report_type` * | enum | Tipo de Relato de Infração. | **[Enumeradores infraction_report_type](#enumeradores-infraction_report_type)** |
| `infraction_report_details` | string | Detalhes acerca do Relato de Infração criado. | \<\= 2000 |
| `credited_participant` * | string | ISPB do Participante Creditado. | 8 |
| `debited_participant` * | string | ISPB do Participante Debitado. | 8 |
| `infraction_report_direction` * | enum | Enumerador acerca se o relato foi aberto pelo Participante Indireto ou por outro Participante | **[Enumeradores infraction_report_direction](#enumeradores-infraction_report_direction)** |
| `created_at` * | string | Horário de criação do Relato de Infração | 24 |
| `updated_at` | string | Horário de atualização do Relato de Infração | 24 |
### Enumeradores infraction_report_status
| Campo | Tipo | Descrição | Caracteres |
| -------------- | ------ | ----------------------------------------------------------------------------- | ---------- |
| `open` | string | Relato de infração foi criado e está aberto no BACEN. | - |
| `acknowledged` | string | Relato de infração foi recebido pelo participante contestado | - |
| `cancelled` | string | Relato de infração está cancelado no BACEN | - |
| `closed` | string | Relato de infração está fechado no BACEN | - |
### Enumeradores infraction_report_direction
| Campo | Tipo | Descrição | Caracteres |
| ---------- | ------ | ------------------------------------------------------------- | ---------- |
| `incoming` | string | Relato de infração com participante indireto como alvo. | - |
| `outgoing` | string | Relato de infração com participante indireto como originador. | - |
---
# Fechar Relato de Infração
URL: /documentation/pix_indireto/relato_de_infracao/fechar_relato_infracao
A QI Tech será responsável por realizar um pooling no Banco Central do Brasil a fim de se verificar se há Relato(s) de Infração criados por outros Participantes para o Participante Indireto, e enviará o webhook de recebimento já com o status acknowledged para o mesmo.
A fim de informar o Participante Indireto de que há um Relato de Infração a ser respondido pelo mesmo, a QI Tech irá fazer um webhook de recebimento no mesmo.
:::danger IMPORTANTE
Ressalta-se que apenas o Participante o qual RECEBEU o Relato de Infração pode fechá-lo.
:::
:::danger IMPORTANTE
O Banco Central do Brasil define que, dentro de um período de 7 dias do recebimento do Relato de Infração pelo Participante Indireto, o Relato precisa ser fechado .
Caso haja atraso por parte do Participante Indireto, a QI Tech irá fechar o Relato de Infração, com o status de agreed, 6 dias corridos após o envio do webhook de recebimento da infração, a fim de que a instituição não seja penalizada pelo Banco Central do Brasil.
:::
Para o fechamento do relato de infração, o status deve ser acknowledged .
## Request
ENDPOINT /pix/infraction_report/ INFRACTION_REPORT_KEY
MÉTODO PATCH
**Request Body - Aceite**
```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 - Recusa**
```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
| Campo | Tipo | Descrição | Caracteres |
| ----------------------- | ------ | ----------------------------------------------------------- | ---------- |
| `infraction_report_key` | string | UUID4 do Relato de Infração criado o qual se deseja fechar. | 36 |
### Body Params
| Campo | Tipo | Descrição | Caracteres |
| ---------------------------- | ------ | ------------------------------------------------------------------------------------------------------------ | ----------------------------------------------------------------------------------- |
| `analysis_result` * | enum | Resultado da análise. | **[Enumeradores analysis_result](#enumeradores-analysis_result)** |
| `request_control_key` * | uuidv4 | UUID4 para fins de consulta sobre a requisição feita. | 36 |
| `infraction_report_status` * | enum | Status o qual se deseja 'setar' o relato de infração. | **[Enumeradores infraction_report_status](#enumeradores-infraction_report_status)** |
| `fraud_type` | enum | Tipo de fraude constatada. Não pertencente à entidade infraction report, porém necessário para o fechamento. | **[Enumeradores fraud_type](#enumeradores-fraud_type)** |
| `analysis_details` | string | Descrição acerca do resultado da análise | 250 |
### Enumeradores analysis_result
| Campo | Tipo | Descrição | Caracteres |
| ----------- | ------ | ---------------------------------------------------------------------------------------------------------- | ---------- |
| `agreed` | string | O Participante Indireto concorda com o Relato de Infração criado pelo outro Participante. | - |
| `disagreed` | string | O Participante Indireto discorda com o Relato de Infração criado pelo outro Participante. | - |
### Enumeradores infraction_report_status
| Campo | Tipo | Descrição | Caracteres |
| -------------- | ------ | ---------------------------------------------------------------------- | ---------- |
| `open` | string | Relato de infração foi criado e está aberto no BACEN. | - |
| `acknowledged` | string | Relato de infração foi recebido pelo participante | - |
| `cancelled` | string | Relato de infração está cancelado no BACEN | - |
| `closed` | string | Relato de infração está fechado no BACEN | - |
### Enumeradores fraud_type
| Campo | Tipo | Descrição | Caracteres |
| ------------------- | ------ | -------------------------------------------------------------------- | ---------- |
| `application_fraud` | string | Fraude por falsidade ideológica, com documentos de outra pessoa. | - |
| `mule_account` | string | Fraude por conta laranja, aberta de forma legítma. | - |
| `scammer_account` | string | Fraude na qual a conta destino esta no nome do verdadeiro fraudador. | - |
| `other` | string | Fraude de outra naturaza, não enquadrada nos enumeradores acima. | - |
## 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
| Campo | Tipo | Descrição | Caracteres |
| ------------------------------- | ------ | --------------------------------------------------------------------------------------------- | ----------------------------------------------------------------------------------------- |
| `infraction_report_key` * | string | Identificador único do relato de infração. | 36 |
| `pix_transfer_key` * | string | Identificador único da transação PIX. | 36 |
| `end_to_end_id` * | string | Identificador único da transação PIX no BACEN. | 36 |
| `infraction_report_status` * | enum | Status acerca do Relato de Infração | **[Enumeradores infraction_report_status](#enumeradores-infraction_report_status)** |
| `infraction_report_situation` * | enum | Situação em que ocorreu a infração. | **[Enumeradores infraction_report_situation](#enumeradores-infraction_report_situation)** |
| `infraction_report_type` * | enum | Tipo de Relato de Infração. | **[Enumeradores infraction_report_type](#enumeradores-infraction_report_type)** |
| `infraction_report_details` | string | Detalhes acerca do Relato de Infração criado. | \<\= 2000 |
| `credited_participant` * | string | ISPB do Participante Creditado. | 8 |
| `debited_participant` * | string | ISPB do Participante Debitado. | 8 |
| `analysis_result` * | string | Resultado da análise. | **[Enumeradores analysis_result](#enumeradores-analysis_result)** |
| `analysis_details` * | string | Descrição acerca do resultado da análise. | 250 |
| `infraction_report_direction` * | enum | Enumerador acerca se o relato foi aberto pelo Participante Indireto ou por outro Participante | **[Enumeradores infraction_report_direction](#enumeradores-infraction_report_direction)** |
| `created_at` * | string | Data de criação do Relato de Infração | 24 |
| `updated_at` * | string | Data de atualização do Relato de Infração | 24 |
### Enumeradores infraction_report_situation
| Campo | Tipo | Descrição | Caracteres |
| ------------------- | ------ | ------------------------------------------------------- | ---------- |
| `scam` | string | Causa de golpe ou estelionato. | - |
| `account_takeover` | string | Causa de transação não autorizada pela conta de origem. | - |
| `coercion` | string | Causa de crime de coerção. | - |
| `fraudulent_access` | string | Causa de acesso fraudulento à conta de origem. | - |
| `other` | string | Quaisquer causas não aplicáveis às listadas acima. | - |
### Enumeradores infraction_report_type
| Campo | Tipo | Descrição | Caracteres |
| ------------------ | ------ | ---------------------------------------------------------------------- | ---------- |
| `refund_request` | string | Relato de infração será gerado a fim de se solicitar uma devolução. | - |
| `refund_cancelled` | string | Relato de infração será gerado pelo motivo de uma devolução cancelada. | - |
### Enumeradores infraction_report_direction
| Campo | Tipo | Descrição | Caracteres |
| ---------- | ------ | ------------------------------------------------------------- | ---------- |
| `incoming` | string | Relato de infração com participante indireto como alvo. | - |
| `outgoing` | string | Relato de infração com participante indireto como originador. | - |
---
# Listar Relatos de Infração
URL: /documentation/pix_indireto/relato_de_infracao/listar_relatos
Caso o Participante Indireto solicite a listagem de Relatos de Infração, pode fazê-lo por meio da rota abaixo.
## Request
ENDPOINT /pix/infraction_reports
MÉTODO GET
### Query Params
| Campo | Tipo | Descrição | Caracteres |
|---|---| ---| ---|
| `infraction_report_status` | enum | Status do Relato de Infração. | **[Enumeradores infraction_report_status](#enumeradores-infraction_report_status)** |
| `infraction_report_type` | enum | Tipo do Relato de Infração. | **[Enumeradores infraction_report_type](#enumeradores-infraction_report_type)** |
| `initial_date` | string | Data inicial de busca. | **[Formato de data](#formato-de-data)** |
| `final_date` | string | Data final de busca. | **[Formato de data](#formato-de-data)** |
| `page_number` | integer | Página atual que está sendo consultada. | - |
| `page_size` | integer | Quantidade de resultados por página. | - |
### Formato de data
| Campo | Tipo | Descrição | Caracteres |
|---|---| ---| ---|
| `initial_date` | string | Data de inicio para a procura, em formato "%Y-%m-%d. Exemplo: "2023-10-09".| 10 |
| `final_date` | string | Data final para a procura, em formato "%Y-%m-%d. Exemplo: "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
| Campo | Tipo | Descrição | Caracteres |
| ------------------------------- | ------ | --------------------------------------------------------------------------------------------- | ----------------------------------------------------------------------------------------- |
| `infraction_report_key` * | string | Identificador único do relato de infração. | 36 |
| `pix_transfer_key` * | string | Identificador único da transação PIX. | 36 |
| `end_to_end_id` * | string | Identificador único da transação PIX no BACEN. | 36 |
| `infraction_report_status` * | enum | Status . | **[Enumeradores infraction_report_status](#enumeradores-infraction_report_status)** |
| `infraction_report_situation` * | enum | Situação em que ocorreu a infração. | **[Enumeradores infraction_report_situation](#enumeradores-infraction_report_situation)** |
| `infraction_report_type` * | enum | Tipo de Relato de Infração. | **[Enumeradores infraction_report_type](#enumeradores-infraction_report_type)** |
| `infraction_report_details` | string | Detalhes acerca do Relato de Infração criado. | \<\= 2000 |
| `credited_participant` * | string | ISPB do Participante Creditado. | 8 |
| `debited_participant` * | string | ISPB do Participante Debitado. | 8 |
| `infraction_report_direction` * | enum | Enumerador acerca se o relato foi aberto pelo Participante Indireto ou por outro Participante | **[Enumeradores infraction_report_direction](#enumeradores-infraction_report_direction)** |
| `infraction_report_events`* | object | Eventos relacionados ao Relato de Infração. | **[Objetos infraction_report_events](#objetos-infraction_report_events)** |
| `created_at` * | string | Horário de criação do Relato de Infração | 24 |
| `updated_at` | string | Horário de atualização do Relato de Infração | 24 |
### Enumeradores infraction_report_status
| Campo | Tipo | Descrição | Caracteres |
| -------------- | ------ | ----------------------------------------------------------------------------- | ---------- |
| `open` | string | Relato de infração foi criado e está aberto no BACEN. | 4 |
| `acknowledged` | string | Relato de infração foi recebido pelo participante contestado | 12 |
| `cancelled` | string | Relato de infração está cancelado no BACEN | 9 |
| `closed` | string | Relato de infração está fechado no BACEN | 6 |
### Enumeradores infraction_report_situation
| Campo | Tipo | Descrição | Caracteres |
| ------------------- | ------ | ------------------------------------------------------- | ---------- |
| `scam` | string | Causa de golpe ou estelionato. | - |
| `account_takeover` | string | Causa de transação não autorizada pela conta de origem. | - |
| `coercion` | string | Causa de crime de coerção. | - |
| `fraudulent_access` | string | Causa de acesso fraudulento à conta de origem. | - |
| `other` | string | Quaisquer causas não aplicáveis às listadas acima. | - |
### Enumeradores infraction_report_type
| Campo | Tipo | Descrição | Caracteres |
| ------------------ | ------ | ---------------------------------------------------------------------- | ---------- |
| `refund_request` | string | Relato de infração será gerado a fim de se solicitar uma devolução. | - |
| `refund_cancelled` | string | Relato de infração será gerado pelo motivo de uma devolução cancelada. | - |
### Enumeradores infraction_report_direction
| Campo | Tipo | Descrição | Caracteres |
| ---------- | ------ | ------------------------------------------------------------- | ---------- |
| `incoming` | string | Relato de infração com participante indireto como alvo. | - |
| `outgoing` | string | Relato de infração com participante indireto como originador. | - |
### Objetos infraction_report_events
| Campo | Tipo | Descrição | Caracteres |
| --------------- | ------ | ---------------------------------------- | ----------------------------------------------------------------------------------- |
| `event_type` | enum | Mudança de status relacionada ao evento. | **[Enumeradores infraction_report_status](#enumeradores-infraction_report_status)** |
| `event_details` | string | Descrição do evento. | - |
| `created_at` * | string | Horário de criação do evento | 24 |
---
# Introdução ao fluxo de Relato de Infração
URL: /documentation/pix_indireto/relato_de_infracao/maquina_estados
## Introdução
O Banco Central do Brasil permite que, caso haja uma infração em uma transação PIX, podendo esta ser uma transação comum ou uma devolução, que o Participante Indireto possa informar o outro Participante envolvido no fluxo de que há uma irregularidade.
:::info
Ressalta-se que, para uma transação PIX, somente o Participante creditado pode abrir um Relato de Infração.
:::
:::danger IMPORTANTE
O Banco Central do Brasil define que, dentro de um período de 7 dias do recebimento do Relato de Infração pelo Participante Indireto, o Relato precisa ser fechado .
Caso haja atraso por parte do Participante Indireto, a QI Tech irá fechar o Relato de Infração, com o status de agreed, 6 dias corridos após o envio do webhook de recebimento da infração, a fim de que a instituição não seja penalizada pelo Banco Central do Brasil.
:::
## Máquina de Estados Infraction_Report_Status
| Enumerador | Tradução | Descrição|
|---|---|---|
| open | aberto | Após o processamento da criação do Relato de Infração, o mesmo fica aberto no BACEN.
| acknowledged | recebido | A QI Tech recebeu um Relato de Infração o qual possui o Participante Indireto como alvo, e irá encaminhá-lo (relato) via webhook.
| cancelled | cancelado | O Participante que abriu o relato enviou o cancelamento e o mesmo está cancelado no BACEN.
| closed | fechado | O fechamento do Relato de Infração foi processado pela QI Tech e está fechado no BACEN.
## Controle da Máquina de Estados Infraction_Report_Status
Mesmo o fluxo sendo síncrono, é necessário que o Participante Indireto conheça os status os quais um Relato de Infração pode ter. Abaixo, está descrito o que o Participante pode esperar após abrir, cancelar, completar e receber um Relato de Infração.
### Participante Abre Relato de Infração
O Participante Indireto pode abrir um Relato de Infração no Banco Central. O único requisito, para a abertura do Relato, é de que uma transação tenha sido feita via PIX.
O Participante Indireto não pode abrir um segundo Relato de Infração para uma mesma transação, mesmo que o primeiro Relato já esteja fechado.
### Participante Cancela Relato de Infração
Após o Participante Indireto ter aberto um Relato de Infração, o Participante pode solicitar o cancelamento deste, se necessário, independente do status do mesmo.
### Participante Recebe Relato de Infração
No fluxo de incoming infraction, o recebimento (status acknowledged) é feito de maneira automática pela QI Tech, e será feito o envio do webhook ao Participante Indireto com a infração recebida.
No fluxo de outgoing, o recebimento de um relato pela contraparte não resulta em atualização de status interna, visto que essa ação não resulta numa alteração da entidade Infração.
O Participante Indireto receberá o Relato de Infração com o status de acknowledged
### Participante Fecha Relato de Infração
Após o Participante Indireto ter sido informado de que há um Relato de Infração com o status de acknowledged , este deve fechá-lo.
O Participante Indireto deverá informar, no fechamento, o resultado da análise feita, podendo rejeitar o Relato de Infração, ou aceitá-lo no prazo de 6 dias corridos à partir do webhook de recebimento do mesmo, apoś esse período, caso não haja resposta, o mesmo será aceito automaticamente pela QI Tech a fim de manter o compromisso com o BACEN e o SPI de tempos de resposta.
## Controle da Máquina de Estados Infraction_Report_Direction
| Enumerador | Tradução | Descrição|
|---|---|---|
| incoming | vindo | O Participante Indireto recebeu o Relato de Infração de um outro Participante.
| outgoing | enviado | O Participante Indireto enviou o Relato de Infração a um outro Participante.
## Participande Indireto Recebe/Fecha Relato de Infração
Neste caso, o campo "infraction_report_direction" será de "incoming".
## Participande Indireto Envia/Cancela Relato de Infração
Neste caso, o campo "infraction_report_direction" será de "outgoing".
Ressalta-se que nenhum destes campos será enviado pelo Participante Indireto. Contém apenas na resposta da requisição.
---
# Simulação de Cenários
URL: /documentation/pix_indireto/relato_de_infracao/simulacao_de_cenarios
Passo a passo para simular a efetivação de ações feitas por agentes externos. Essas simulações incluem recebimentos e atualizações de relatos de infração .
:::info Informação
Não há payload de retorno (response body) nessas requisições, somente response status de 204. O conteúdo gerado pelo mock deve ser recebido via webhook.
:::
## 1 - Simulação de recebimento de relato de infração
Simula o recebimento de um relato de infração aberto por outra instituição.
:::info IMPORTANTE
É essencial possuir uma pix_transfer_key válida para mandar a request, não importando necessariamente as informações da outra parte da transferencia, visto que todas as informações do segundo participante serão substituidas no processo de mock.
:::
### Request
ENDPOINT /mock/pix/infraction_report
MÉTODO 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.",
}
```
### Objeto Request Body
| Campo | Tipo | Descrição | Máx. Caract. |
| --------------------------------- | ------ | ------------------------------------------------------------ | ----------------------------------------------------------------------------------------- |
| **infraction_report_status\*** | string | Status de recebimento do relato de infração. "acknowledged". | **[Enumeradores infraction_report_status](#enumeradores-infraction_report_status)** |
| **pix_transfer_key\*** | string | UUID4, chave única que identifica a transação relacionada. | 36 |
| **infraction_report_type\*** | string | Tipo de Relato de Infração | **[Enumeradores infraction_report_type](#enumeradores-infraction_report_type)** |
| **infraction_report_situation\*** | string | Situação em que ocorreu a infração | **[Enumeradores infraction_report_situation](#enumeradores-infraction_report_situation)** |
| **infraction_report_details\*** | string | Detalhes do relato de infração | 2000 |
### Enumeradores infraction_report_status
| Campo | Tipo | Descrição | Caracteres |
| -------------- | ------ | ---------------------------------------------------------------------- | ---------- |
| `open` | string | Relato de infração foi criado e está aberto no BACEN. | - |
| `acknowledged` | string | Relato de infração foi recebido pelo participante | - |
| `cancelled` | string | Relato de infração está cancelado no BACEN | - |
| `closed` | string | Relato de infração está fechado no BACEN | - |
### Enumeradores infraction_report_type
| Campo | Tipo | Descrição | Caracteres |
| ------------------ | ------ | ---------------------------------------------------------------------- | ---------- |
| `refund_request` | string | Relato de infração será gerado a fim de se solicitar uma devolução. | - |
| `refund_cancelled` | string | Relato de infração será gerado pelo motivo de uma devolução cancelada. | - |
### Enumeradores infraction_report_situation
| Campo | Tipo | Descrição | Caracteres |
| ------------------- | ------ | ------------------------------------------------------- | ---------- |
| `scam` | string | Causa de golpe ou estelionato. | - |
| `account_takeover` | string | Causa de transação não autorizada pela conta de origem. | - |
| `coercion` | string | Causa de crime de coerção. | - |
| `fraudulent_access` | string | Causa de acesso fraudulento à conta de origem. | - |
| `other` | string | Quaisquer causas não aplicáveis às listadas acima. | - |
## 2 - Simulação de atualização de um relato de infração
Simula a atualização de status de um relato de infração aberto pelo participante indireto.
As opções de simulação para atualização de um relato de infração são:
1 - Cancelamento: Simula o cancelamento (cancel), feito pelo outro participante, sobre um relato de infração aberto por ele mesmo previamente.
2 - Fechamento: Simula o fechamento (close), feito pelo outro participante, sobre um relato de infração aberto pelo participante indireto.
### Request
ENDPOINT /mock/pix/infraction_report
MÉTODO PATCH
Request Body - Cancelamento
:::info IMPORTANTE
O Relato de infração identificado pela infraction_report_key ja deve ter sido previamente criado na simulação de recebimento de relato de infração.
:::
```json
{
"infraction_report_status": "cancelled",
"infraction_report_key": "28290ff2-2ba7-4e85-9a5e-862c92259b34"
}
```
Request Body - Fechamento
:::info IMPORTANTE
O Relato de infração identificado pela infraction_report_key ja deve ter sido previamente criado pelo participante indireto, e reconhecido na simulação de atualização de um relato de infração.
:::
```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."
}
```
### Objeto Request Body
| Campo | Tipo | Descrição | Máx. Caract. | Informações |
| ------------------------------ | ------ | -------------------------------------------------------------------- | ----------------------------------------------------------------------------------- | -------------------------------- |
| **infraction_report_status\*** | string | Novo status do relato de infração. "cancelled", "closed" | **[Enumeradores infraction_report_status](#enumeradores-infraction_report_status)** | ---- |
| **infraction_report_key\*** | string | Chave única do relato de infração | 36 | ---- |
| **analysis_result\*** | string | Resultado da análise do relato de infração. "agreed" ou "disagreed". | **[Enumeradores analysis_result](#enumeradores-analysis_result)** | Obrigatório para status "closed" |
| **analysis_details\*** | string | Detalhes da análise do relato de infração. | 2000 | Obrigatório para status "closed" |
### Enumeradores analysis_result
| Campo | Tipo | Descrição | Caracteres |
| ----------- | ------ | ---------------------------------------------------------------------------------------------------------- | ---------- |
| `agreed` | string | O Participante Indireto concorda com o Relato de Infração criado pelo outro Participante. | - |
| `disagreed` | string | O Participante Indireto discorda com o Relato de Infração criado pelo outro Participante. | - |
---
# Receber Relato de Infração
URL: /documentation/pix_indireto/relato_de_infracao/webhooks_relato_infracao
Visto que um outro Participante pode abrir um Relato de Infração, tendo como alvo o Participante Indireto, é necessário que a QI Tech notifique o Participante Indireto acerca do Relato aberto por outro Participante.
A QI Tech realizará o pooling periódico de novos relatos abertos aos Participantes Indiretos administrados, e notificará o correspondente via webhook , já com o status acknowledged.
:::danger IMPORTANTE
O Banco Central do Brasil define que, dentro de um período de 7 dias do recebimento do Relato de Infração pelo Participante Indireto, o Relato precisa ser fechado .
Caso haja atraso por parte do Participante Indireto, a QI Tech irá fechar o Relato de Infração, com o status de agreed, 6 dias corridos após o envio do webhook de recebimento da infração, a fim de que a instituição não seja penalizada pelo Banco Central do Brasil.
:::
O status do Relato de Infração sempre será de acknowledged , significando que a QI Tech recebeu o Relato e irá enviá-lo ao Participante Indireto.
:::info Informação
Tudo o descrito nesta seção de introdução também está, de forma detalhada como o Participante Indireto deve tratar via API, na seções relacionadas a Notificações de Infração.
:::
## Webhook recebimento 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":"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
| Campo | Tipo | Descrição | Caracteres |
| ------------------------------- | ------ | --------------------------------------------------------------------------------------------- | ----------------------------------------------------------------------------------------- |
| `infraction_report_key` * | string | Identificador único do relato de infração. | 36 |
| `pix_transfer_key` * | string | Identificador único da transação PIX. | 36 |
| `end_to_end_id` * | string | Identificador único da transação PIX no BACEN. | 36 |
| `infraction_report_status` * | enum | Status . | **[Enumeradores infraction_report_status](#enumeradores-infraction_report_status)** |
| `infraction_report_situation` * | enum | Situação em que ocorreu a infração. | **[Enumeradores infraction_report_situation](#enumeradores-infraction_report_situation)** |
| `infraction_report_type` * | enum | Tipo de Relato de Infração. | **[Enumeradores infraction_report_type](#enumeradores-infraction_report_type)** |
| `infraction_report_details` | string | Detalhes acerca do Relato de Infração criado. | \<\= 2000 |
| `credited_participant` * | string | ISPB do Participante Creditado. | 8 |
| `debited_participant` * | string | ISPB do Participante Debitado. | 8 |
| `infraction_report_direction` * | enum | Enumerador acerca se o relato foi aberto pelo Participante Indireto ou por outro Participante | **[Enumeradores infraction_report_direction](#enumeradores-infraction_report_direction)** |
| `created_at` * | string | Horário de criação do Relato de Infração | 24 |
| `updated_at` | string | Horário de atualização do Relato de Infração | 24 |
### Enumeradores infraction_report_status
| Campo | Tipo | Descrição | Caracteres |
| -------------- | ------ | ----------------------------------------------------------------------------- | ---------- |
| `open` | string | Relato de infração foi criado e está aberto no BACEN. | - |
| `acknowledged` | string | Relato de infração foi recebido pelo participante contestado | - |
| `cancelled` | string | Relato de infração está cancelado no BACEN | - |
| `closed` | string | Relato de infração está fechado no BACEN | - |
### Enumeradores infraction_report_type
| Campo | Tipo | Descrição | Caracteres |
| ------------------ | ------ | --------------------------------------------------------------------- | ---------- |
| `refund_cancelled` | string | Relato de infração será gerado pelo motivo de uma devolução cancelada | 16 |
| `refund_request` | string | Relato de infração será gerado a fim de se solicitar uma devolução | 14 |
### Enumeradores infraction_report_situation
| Campo | Tipo | Descrição | Caracteres |
| ------------------- | ------ | ------------------------------------------------------- | ---------- |
| `scam` | string | Causa de golpe ou estelionato. | - |
| `account_takeover` | string | Causa de transação não autorizada pela conta de origem. | - |
| `coercion` | string | Causa de crime de coerção. | - |
| `fraudulent_access` | string | Causa de acesso fraudulento à conta de origem. | - |
| `other` | string | Quaisquer causas não aplicáveis às listadas acima. | - |
### Enumeradores infraction_report_direction
| Campo | Tipo | Descrição | Caracteres |
| ---------- | ------ | ------------------------------------------------------------- | ---------- |
| `incoming` | string | Relato de infração com participante indireto como alvo. | - |
| `outgoing` | string | Relato de infração com participante indireto como originador. | - |
## 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
| Campo | Tipo | Descrição | Caracteres |
| ------------------------------- | ------ | --------------------------------------------------------------------------------------------- | ----------------------------------------------------------------------------------------- |
| `infraction_report_key` * | string | Identificador único do relato de infração. | 36 |
| `pix_transfer_key` * | string | Identificador único da transação PIX. | 36 |
| `end_to_end_id` * | string | Identificador único da transação PIX no BACEN. | 36 |
| `infraction_report_status` * | enum | Status . | **[Enumeradores infraction_report_status](#enumeradores-infraction_report_status)** |
| `infraction_report_situation` * | enum | Situação em que ocorreu a infração. | **[Enumeradores infraction_report_situation](#enumeradores-infraction_report_situation)** |
| `infraction_report_type` * | enum | Tipo de Relato de Infração. | **[Enumeradores infraction_report_type](#enumeradores-infraction_report_type)** |
| `infraction_report_details` | string | Detalhes acerca do Relato de Infração criado. | \<\= 2000 |
| `credited_participant` * | string | ISPB do Participante Creditado. | 8 |
| `debited_participant` * | string | ISPB do Participante Debitado. | 8 |
| `analysis_result` * | string | Resultado da análise. | **[Enumeradores analysis_result](#enumeradores-analysis_result)** |
| `analysis_details` * | string | Descrição acerca do resultado da análise. | 250 |
| `infraction_report_direction` * | enum | Enumerador acerca se o relato foi aberto pelo Participante Indireto ou por outro Participante | **[Enumeradores infraction_report_direction](#enumeradores-infraction_report_direction)** |
| `created_at` * | string | Horário de criação do Relato de Infração | 24 |
| `updated_at` | string | Horário de atualização do Relato de Infração | 24 |
### Enumeradores analysis_result
| Campo | Tipo | Descrição | Caracteres |
| ----------- | ------ | ---------------------------------------------------------------------------------------------------------- | ---------- |
| `agreed` | string | O Participante Indireto concorda com o Relato de Infração criado pelo outro Participante. | - |
| `disagreed` | string | O Participante Indireto discorda com o Relato de Infração criado pelo outro Participante. | - |