# QI Tech — Banking-as-a-Service › Pix
Documentação da QI Tech em texto corrido, para colar em um LLM.
Fonte: https://docs.qitech.com.br
69 página(s).
Índice:
- Aprovar Transação com Autenticação de Dois Fatores (/documentation/baas/pix/2fa_v2/aprovar_transacao_pix_2fa)
- Introdução a Autenticação de Dois Fatores (/documentation/baas/pix/2fa_v2/introducao_a_transacao_pix_2fa)
- Solicitar a devolução de um Pix recebido (/documentation/baas/pix/2fa_v2/solicitacao_de_devolucao_pix)
- Solicitar reenvio de token para uma transação (/documentation/baas/pix/2fa_v2/solicitacao_de_reenvio_de_token)
- Solicitar Transação com Autenticação de Dois Fatores (/documentation/baas/pix/2fa_v2/solicitacao_de_transacao_pix_2fa)
- Aprovar Agendamento de Transação Pix com Autenticação de Dois Fatores (/documentation/baas/pix/agendamento/aprovacao_de_agendamento_2fa)
- Aprovar Agendamento em Lote de Transação Pix com Autenticação de Dois Fatores (/documentation/baas/pix/agendamento/batch/aprovacao_de_agendamento_em_lote_2fa)
- Cancelar Agendamento de Transação Pix em Lote (/documentation/baas/pix/agendamento/batch/cancelamento_de_agendamento_em_lote)
- Listar Agendamentos de um Lote de Agendamento (/documentation/baas/pix/agendamento/batch/consulta_de_agendamentos_de_um_lote)
- Listar Lotes de Agendamento de uma conta (/documentation/baas/pix/agendamento/batch/consulta_de_agendamentos_em_lote_de_uma_conta)
- Solicitar Agendamento de Transação Pix em Lote (/documentation/baas/pix/agendamento/batch/solicitacao_de_agendamento_em_lote)
- Solicitar Agendamento de Transação Pix em Lote (/documentation/baas/pix/agendamento/batch/solicitacao_de_agendamento_em_lote_2fa)
- Solicitar reenvio de token para um agendamento em lote (/documentation/baas/pix/agendamento/batch/solicitacao_de_reenvio_de_token_para_agendamento_em_lote_2fa)
- Cancelar Agendamento de Transação Pix (/documentation/baas/pix/agendamento/cancelamento_de_agendamento)
- Consultar Agendamento de Transação Pix (/documentation/baas/pix/agendamento/consulta_de_agendamento)
- Consultar Agendamentos de Transação Pix de uma conta (/documentation/baas/pix/agendamento/consulta_de_agendamentos_de_uma_conta)
- Introdução (/documentation/baas/pix/agendamento/introducao)
- Introdução a Autenticação de Dois Fatores (/documentation/baas/pix/agendamento/introducao_a_agendamento_2fa)
- Solicitar Agendamento de Transação Pix (/documentation/baas/pix/agendamento/solicitacao_de_agendamento)
- Solicitar Agendamento de Transação Pix com Autenticação de Dois Fatores (/documentation/baas/pix/agendamento/solicitacao_de_agendamento_2fa)
- Solicitar reenvio de token para um agendamento (/documentation/baas/pix/agendamento/solicitacao_de_reenvio_de_token_para_agendamento_2fa)
- Webhook de conclusão de Agendamento Pix (/documentation/baas/pix/agendamento/webhook_de_conclusao_de_agendamento)
- Aprovar Transação em Lote com Autenticação de Dois Fatores (/documentation/baas/pix/batch/aprovar_transacao_em_lote_pix_2fa)
- Introdução a Transação em Lote Pix (/documentation/baas/pix/batch/introducao_a_transacao_em_lote_pix)
- Listar Transações de um lote de uma conta (/documentation/baas/pix/batch/listar_transacoes_de_um_lote_de_transacoes_pix)
- Listar Transações em Lote de uma conta (/documentation/baas/pix/batch/listar_transacoes_em_lote_pix_de_uma_conta)
- Solicitar reenvio de token para uma Transação Pix em Lote (/documentation/baas/pix/batch/solicitacao_de_reenvio_de_token_para_lote)
- Realizar Transação Pix em Lote (/documentation/baas/pix/batch/solicitacao_de_transacao_em_lote_pix)
- Realizar Transação Pix em Lote com Autenticação de Dois Fatores (/documentation/baas/pix/batch/solicitacao_de_transacao_em_lote_pix_2fa)
- Consulta de Dados de Chave Pix no Banco Central (/documentation/baas/pix/consultar_chave_pix)
- Consultar Transferências (/documentation/baas/pix/consultar_transferencias)
- Listar Transferências de uma Conta (/documentation/baas/pix/listar_transferencias)
- Realizar Transação Pix (/documentation/baas/pix/realizar_transferencia)
- Solicitar a devolução de um Pix recebido (/documentation/baas/pix/solicitar_devolucao)
- Webhooks (/documentation/baas/pix/webhooks)
- Baixar QR Code Pix dinâmico (/documentation/pix/baixar_qr_code_dinamico)
- Busca por solicitação de limite Pix (/documentation/pix/busca_por_solicitacao_de_limite_pix)
- Busca por uso de limite Pix (/documentation/pix/busca_por_uso_de_limite_pix)
- Chaves PIX mockadas em ambiente de sandbox (/documentation/pix/chaves_pix_mockadas)
- Comprovante de transação (/documentation/pix/comprovante_de_transferencia)
- Criar Chave Pix (/documentation/pix/criar_chave)
- Criar QR Code Pix dinâmico (/documentation/pix/criar_qr_code_dinamico)
- Criar QR Code Estático (/documentation/pix/criar_qr_code_estatico)
- Decodificar QR Code Pix (/documentation/pix/decodificar_qr_code)
- Excluir chave Pix (/documentation/pix/excluir_chave)
- Introdução (/documentation/pix/introducao)
- Listar chaves Pix de uma conta (/documentation/pix/listar_chaves_pix)
- MED 2.0 — Consultar Recuperações de Valores (/documentation/pix/med/consultar_recuperacao_de_valores)
- Mecanismo Especial de Devolução do PIX (MED) (/documentation/pix/med/introducao)
- Recebimento de Pedidos de Devolução (/documentation/pix/med/recebimento_pedidos_de_devolucao)
- MED 2.0 — Recebimento de Recuperação de Valores (/documentation/pix/med/recebimento_recuperacao_de_valores)
- Recebimento de Relatos de Infração (/documentation/pix/med/recebimento_relatos_de_infracao)
- MED 2.0 — Responder Recuperação de Valores (/documentation/pix/med/responder_recuperacao_de_valores)
- Responder Relatos de Infração (/documentation/pix/med/resposta_relatos_de_infracao)
- Pesquisar por QR Code Pix dinâmico próprio (/documentation/pix/pesquisar_por_qr_code_dinamico)
- Conclusão da portabilidade (/documentation/pix/portabilidade/conclusao_de_portabilidade)
- Consulta de portabilidade por conta (/documentation/pix/portabilidade/consulta_de_portabilidade_por_conta)
- Criando um pedido de portabilidade (/documentation/pix/portabilidade/criando_um_pedido_de_portabilidade)
- Deletando um pedido de portabilidade (/documentation/pix/portabilidade/deletando_um_pedido_de_portabilidade)
- Portabilidade (/documentation/pix/portabilidade/recebendo_pedido_de_portabilidade)
- Reenviando a validação de dois fatores (/documentation/pix/portabilidade/reenviando_a_2fa)
- Portabilidade (/documentation/pix/portabilidade/respondendo_pedido_de_portabilidade)
- Simular alteração de status de portabilidade (/documentation/pix/portabilidade/simular_alteracao_de_status_de_portabilidade)
- Simular webhook de conclusão do pedido de portabilidade (/documentation/pix/portabilidade/simular_webhook_de_conclusao)
- Simular webhook de recebimento de um pedido de portabilidade (/documentation/pix/portabilidade/simular_webhook_recebimento)
- Validação de dois fatores (/documentation/pix/portabilidade/validacao_de_dois_fatores)
- Simulação de cenários (/documentation/pix/simulacao)
- Solicitar alteração de limite Pix (/documentation/pix/solicitar_alteracao_de_limite_pix)
- Webhook por QR Code Pix dinâmico expirado (/documentation/pix/webhook_por_qr_code_expirado)
---
# Aprovar Transação com Autenticação de Dois Fatores
URL: /documentation/baas/pix/2fa_v2/aprovar_transacao_pix_2fa
## Request
ENDPOINT /account/ ACCOUNT_KEY /pix_transfer/ PIX_TRANSFER_KEY /validate_token
MÉTODO PUT
### Path Params
| Campo | Tipo | Descrição | Caracteres |
|--------------------|--------|------------------------------------------------|------------|
| `account_key` | uuidv4 | Chave única de identificação da conta. | 36 |
| `pix_transfer_key` | uuidv4 | Chave única de identificação da transação pix. | 36 |
## Autenticação via Email e SMS
Request Body
```json
{
"token": "329adf"
}
```
## Autenticação via Dispositivo
Para aprovar e finalizar a autenticação via dispositivo, a requisição deve ser enviada com um payload vazio. A validação ocorre internamente, sem necessidade de informações adicionais no corpo da requisição. É importante destacar que este endpoint só deve ser utilizado após a [solicitação de transação](./solicitacao_de_transacao_pix_2fa.md) ter sido iniciada.
Request Body
```json
{
}
```
## Body Params
| Campo | Tipo | Descrição | Caracteres |
|-----------|--------|-----------------------------------------------------------------------|------------|
| `token` | string | Código de autenticação enviado ao aprovador de movimentações da conta **obrigatório para TFA via SMS ou e-mail**| 6 |
## Response
STATUS 201
Response Body: Transferência Enviada
```json
{
"request_control_key": "b6804f32-101e-4702-8fbc-c2dbc4c2caec",
"pix_transfer_key": "8cb70dea-9fb0-4a68-9572-99a72849c8d6",
"end_to_end_id": "E32402502202405081755SxyT2DDcVwc",
"pix_transfer_status": "sent",
"created_at": "2021-10-22T20:30:23.459Z",
"transaction_key": "46804f32-101e-4702-8fbc-c2dbc4c2caec"
}
```
STATUS 202
Response Body: Transferência Pendente
```json
{
"request_control_key": "b6804f32-101e-4702-8fbc-c2dbc4c2caec",
"pix_transfer_key": "8cb70dea-9fb0-4a68-9572-99a72849c8d6",
"end_to_end_id": "E32402502202405081755SxyT2DDcVwc",
"pix_transfer_status": "pending",
"created_at": "2021-10-22T20:30:23.459Z"
}
```
STATUS 4xx
Response Body: Transferê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",
"pix_transfer_key": "8cb70dea-9fb0-4a68-9572-99a72849c8d6",
"end_to_end_id": "E32402502202405081755SxyT2DDcVwc",
"pix_transfer_status": "rejected",
"created_at": "2021-10-22T20:30:23.459Z"
}
}
}
```
STATUS 4xx
Response Body: Error
```json
{
"title": "titulo",
"description": "description in English",
"translation": "descrição em portugues",
"code": "codigo",
"extra_fields": {}
}
```
| Código HTTP
`status` | Código QI
`code` | Título
`title` | Descrição (eng)
`description` | Descrição (ptbr)
`translation` |
|--------------------------|----------------------|----------------------------------------------------|-------------------------------------------------------------------------------------------------------------------------|------------------------------------------------------------------------------------------------------------------------|
| 400 | QIT000001 | Bad Request | Schema Error | Erro de Schema |
| 404 | PXT000023 | Outgoing PIX Transfer Not Found | Pix transfer key \{pix_transfer_key\} was not found | Transferência PIX de saída com chave \{pix_transfer_key\} não foi encontrada |
| 400 | PXT000175 | Invalid Status | Pix transfer not in pending_2fa_approval status | Pix transfer não está pendente de aprovação por two factor authentication |
| 400 | PXT000182 | Bad Request | The given Pix transfer is tied to a batch. It cannot be individually approved. Please approve batch | A Pix transfer enviada está ligada a um lote. Ela não pode ser individualmente aprovada. Por favor aprove o lote |
| 400 | PXT000174 | Error Sending Token | An error occurred while sending token and its being investigated | Um erro ocorreu ao enviar token e está sendo investigado |
| 400 | PXT000173 | Incorrect Token | Token sent does not match expected | Token enviado não condiz com, o esperado |
| 400 | PXT000172 | Token Expired | Token has expired. Resend token or recreate transfer | Token expirado. Reenvie token ou recrie a transferência |
| 400 | PXT000171 | Number of token validation attempts exceeded | The maximum number of failed token validation attempts has been reached | Número máximo de tentativas de validação de token atingida |
| 406 | PXT000103 | request_control_key must be a valid uuid v4 string | request_control_key was not accepted for not being a valid uuid v4 string | request_control_key não foi aceito por não ser uma palavra uuid v4 válida |
| 400 | PXT000048 | Bad Request | Emoji not allowed in pix message. | Emoji não é permitido na mensagem pix. |
| 400 | PXT000104 | Invalid Transaction Amount | Transaction amount of \{transaction_amount\} is not valid. It must be a positive value with at maximum 2 decimal places | O valor de transação \{transaction_amount\} não é válido. Deve ser um valor positivo com no máximo duas casas decimais |
| 404 | PXT000004 | Account not found | Account not found for: \{account_datum\} | Conta não encontrada para: \{account_datum\} |
| 400 | PXT000003 | Account is Closed | Account \{account_key\} is closed. | Conta \{account_key\} está fechada. |
| 422 | PXT000092 | Invalid Account Type | Pix is not yet implemented for non-checking or non-escrow account types | Transações Pix não estão implementadas para conta que não sejam escrow ou livres |
| 403 | PIT000001 | User is not allowed to do this transaction | | Usuário não tem autorização para fazer essa transação |
| 400 | PXT000010 | Account is Blocked | Account \{account_key\} is blocked. | Conta \{account_key\} está bloqueada. |
| 400 | PXT000003 | Account is Closed | Account \{account_key\} is closed. | Conta \{account_key\} está fechada. |
| 400 | PIT000003 | Bad Request | Insufficient account balance for transfer and fee amount. | Saldo de conta insuficiente para a transferência e a taxa. |
| 400 | PXT000118 | Requester is not Pix Participant | The requester sent an alias key but is not a indirect pix participant | O requisitante enviou uma alias key no entanto não é um participante do pix indireto |
| 404 | PXT000120 | Alias sent not found | Alias key attached to this account not found | Alias key vinculada à conta não encontrada |
| 406 | PXT000105 | Invalid end_to_end_id | The end_to_end_id sent \{end_to_end_id\} is not valid. | O end_to_end_id enviado \{end_to_end_id\} não é válido. |
| 400 | PXT000108 | Bad Request | Billing account closed or blocked | Conta de cobrança encerrada ou bloqueada |
| 400 | PXT000079 | Bad Request | Insufficient billing account balance for fee. | Saldo de conta de cobrança insuficiente para a taxa. |
| 400 | PIT000004 | Bad Request | Transaction amount is over limit. | O total da transferência é superior ao limite. |
| 404 | PIX000056 | Not Found | Pix key inquiry not found | Consulta de chave pix não encontrada |
| 404 | PXT000041 | Not Found | Qr Code not found | Qr Code não encontrado |
| 400 | PXT000053 | Bad Request | QrCode already paid | Qr Code já Pago |
| 400 | PXT000118 | Requester is not Pix Participant | The requester sent an alias key but is not a indirect pix participant | O requisitante enviou uma alias key no entanto não é um participante do pix indireto |
| 404 | PXT000120 | Alias sent not found | Alias key attached to this account not found | Alias key vinculada à conta não encontrada |
| 400 | PXT000115 | Bad Request | Insufficient account balance for transfer and fee amount. | Saldo de conta insuficiente para a transferência e a taxa |
| 400 | PXT000128 | Bad Request | Pix key \{pix_key\} sent does match inquiry pix key. Verify if end_to_end_id sent is correct | Chave Pix \{pix_key\} enviada não condiz com consulta. Verifique se end_to_end_id enviado está correto |
| 400 | PXT000109 | Bad Request | request_control_key \{request_control_key\} already in use | request_control_key \{request_control_key\} já utilizada |
| 400 | PXT000061 | Bad Request | End to end id invalid. A pix transfer with the end to end id \{end_to_end\} has already been registered! | End to end id inválido. Uma transação pix com o identificador único \{end_to_end\} já foi registrada! |
| 400 | PXT000129 | SPI Error message | Message rejected by SPI-ICOM | Mensagem rejeitada pela SPI-ICOM |
| 408 | PXT000130 | SPI Timeout Control | SPI Timeout Control | Controle de timeout no SPI |
| 400 | PXT000131 | Receiver Internal Error | Cancelled transaction due to receiver's internal error | Transação interrompida devido a erro no PSP do Recebedor |
| 400 | PXT000132 | Invalid Target Account Number | Target account number is invalid | Número da conta de destino é inexistente ou inválido |
| 400 | PXT000133 | Blocked Target Account | Target account is blocked. | A conta de destino encontra-se bloqueada. |
| 400 | PXT000134 | Closed Target Account | Target account is closed. | A conta de destino encontra-se encerrada. |
| 400 | PXT000135 | Unsupported Transaction | Unsupported transaction for given target account. | A conta de destino não suporta este tipo de transação. |
| 400 | PXT000136 | Invalid Participant | SPI participant is not PSP settler agent of payer nor receiver. | Participante direto do SPI não é liquidante do PSP do Pagador / Recebedor. |
| 400 | PXT000137 | Zero Value Payment Order | Zero value payment order. | Ordem de pagamento com valor zero. |
| 400 | PXT000138 | Insufficient Funds | Insufficient funds in PI account from payer. | Saldo insuficiente na conta PI do pagador. |
| 400 | PXT000139 | Return Value Too Great | Return value greater than corresponding payment order. | Valor de devolução acima do valor de pagamento correspondente. |
| 400 | PXT000140 | Invalid Transactions Number | Invalid transactions number. | Quantidade de transações inválida. |
| 400 | PXT000141 | Unrelated Beneficiary Document Number | Beneficiary document number is not that of target account owner. | CPF/CNPJ do usuário recebedor não é compatível com o titular da conta de destino. |
| 400 | PXT000142 | Invalid Beneficiary Document Number | Invalid beneficiary document number | CPF/CNPJ da conta de destino está incorreto. |
| 400 | PXT000143 | Incorrect Message Element | Incorrect message element. | Elemento da mensagem incorreto. |
| 403 | PXT000144 | Rejected Payment Order | Beneficiary's PSP has rejected payment order. | Ordem de pagamento foi rejeitada pelo banco recebedor. |
| 403 | PXT000145 | Unauthorized Payer | Signing participant is unauthorized to make a payment order for paying account. | Participante que assinou a mensagem não é autorizado a realizar a operação na conta PI debitada. |
| 400 | PXT000146 | Invalid Datetime | Invalid datetime for message delivery. | Data e Hora do envio da mensagem inválida. |
| 400 | PXT000147 | Generic Error | Error while processing payment (generic error). | Erro no processamento do pagamento (erro genérico). |
| 400 | PXT000148 | Bad Format Operation Identifier | Badly formatted operation's identifier. | Identificador da operação mal formatado. |
| 400 | PXT000149 | Invalid Payer ISPB | Invalid or non-existent payer's PSP ISPB number. | Número ISPB do PSP do Pagador é inválido ou inexistente. |
| 400 | PXT000150 | Invalid Beneficiary ISPB | Invalid or non-existent beneficiary's PSP ISPB number. | Número ISPB do banco recebedor é inválido ou inexistente. |
| 400 | PXT000151 | Incorrect Type | Incorrect type for target account. | Tipo incorreto para a conta transacional especificada. |
| 400 | PXT000152 | Repeated End-to-End ID Error | The end_to_end_id was already used | O end_to_end_id já foi utilizado |
| 400 | PXT000153 | Invalid Target Account Type | The target account type cannot receive PIX transactions | O tipo de conta destino não pode receber transações PIX |
| 400 | PXT000154 | Invalid ISPB | Invalid or non-existent ISPB number. | Número ISPB é inválido ou inexistente. |
| 400 | PXT000155 | Amount too Great | Amount too great for credited account. | Valor de pagamento/devolução acima do permitido para a conta de destino creditada. |
| 400 | PXT000156 | QR Code Rejected | QR Code rejected by beneficiary's PSP. | QR Code rejeitado pelo PSP do usuário recebedor. |
| 503 | PXT000157 | Bacen Service Unavailable Error | Could not send the message to ICOM after 3 retries | Não pode enviar a mensagem para a ICOM depois de 3 tentativas |
| 400 | PXT000158 | Invalid Amount | Paid amount diverges from expected amount of \{expected_amount\} | O valor do pagamento diverge do valor esperado de \{expected_amount\} |
| 400 | PXT000159 | QR code inactive | QR code is not active at the time of payment | QR code não está ativo no instante do pagamento |
| 400 | PXT000189 | Token Required | A token is required for SMS or email validation. | Um token é necessário para validação via SMS ou email. |
---
# Introdução a Autenticação de Dois Fatores
URL: /documentation/baas/pix/2fa_v2/introducao_a_transacao_pix_2fa
Neste tipo de transação, é necessário a confirmação do pagamento via token enviado à pessoa com poderes de aprovação de
movimentação na conta credora.
A solicitação de transação Pix por parceiros integradores configurados para a utilização de autenticação de dois
fatores é realizada de forma similar ao descrito
em [realizar transação Pix](/documentation/baas/pix/realizar_transferencia). A diferença ocorre na adição do
objeto `tfa_info`, contento informações sobre o aprovador da transferência e a forma de contato, e o status de uma
solicitação bem sucedida que será sempre **pending_2fa_approval**.
O mesmo vale para transações em lote Pix descrito em [realizar transação pix em lote](/documentation/baas/pix/batch/solicitacao_de_transacao_em_lote_pix).
## Fluxo para uma transação Pix com autorização
A transação Pix bem sucedida seguirá o seguinte fluxo de processos:
Realização da [solicitação de transação Pix](/documentation/baas/pix/2fa_v2/solicitacao_de_transacao_pix_2fa) e recebimento de resposta de forma síncrona com status de **pending_2fa_approval** e valor da `pix_transfer_key`.
O aprovador indicado receberá um `token` de 6 dígitos compostos por algarismos.
O requisitante realiza a [confirmação de transação pix](/documentation/baas/pix/2fa_v2/aprovar_transacao_pix_2fa) com a `pix_transfer_key` e o `token`.
A transferência será concluída de forma síncrona ou assíncrona a depender da configuração do parceiro integrador.
## Observações
Cada transação possui um limite máximo de tentativas de validação do `token` de 5. Quando este limite é alcançado a transação será colocada em status de rejeitada (**rejected**) automaticamente.
Cada `token` possui duração máxima de 5 minutos.
Uma transação pode ter seu `token` renovado e reenviado para o aprovador da transferência. Este processo reinica o tempo de 5 minutos e não reinicia o contador de tentativas inválidas. O `token` anterior torna-se inválido.
Uma vez aprovada a transação, esta será concluída em regime síncrono ou assíncrono a depender da configuração do parceiro integrador.
O evento de notificação para o envio de `token` ao aprovador é **baas.token_validation.pix_transfer.single**. É possível [personalizar](/documentation/notificacoes/template) a mensagem enviada.
As formas de envio (`contact_type`) de token implementadas são por **sms** e **email**.
---
# Solicitar a devolução de um Pix recebido
URL: /documentation/baas/pix/2fa_v2/solicitacao_de_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 /pix_transfer/ PIX_TRANSFER_KEY /reversal
MÉTODO POST
### Path Params
| Campo | Tipo | Descrição | Caracteres |
|----------------------|--------|------------------------------------------------------------------|------------|
| `account_key` * | uuidv4 | Chave única de identificação da conta. | 36 |
| `pix_transfer_key` * | uuidv4 | Chave única de identificação da transferência Pix no sistema QI. | 36 |
Request Body
```json
{
"request_control_key": "303393bf-8f2e-4ff0-b326-ee7ad612e8ca",
"reversal_amount": 147,
"reversal_reason": "client_request",
"reversal_message": "Mensagem Pix da Devolução",
"tfa_info": {
"approver_document_number": "98765432100",
"contact_type": "email"
}
}
```
### Request Params
| Campo | Tipo | Descrição | Caracteres |
|-------------------------|--------|---------------------------------------------------------------------------------|---------------------------------------------------------------|
| `request_control_key` * | uuidv4 | Chave de unicidade da requisição. | 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 |
| `tfa_info`* | Object | Objeto contendo o documento da pessoa aprovadora da conta e a forma de contato. | **[Objeto tfa_info](#objeto-tfa_info)** |
### Enumerador reversal_reason
| Enumerador | Descrição |
|--------------------|-----------------------------------------------|
| **client_request** | Caso tenha sido requerido pelo dono da conta. |
| **reconciliation** | Para reconciliação devido a erro operacional. |
### Objeto tfa_info
| Campo | Tipo | Descrição | Caracteres |
|-----------------------------|--------|-------------------------------------------------------------------------------------|------------|
| `approver_document_number`* | string | Número de documento da pessoa aprovadora da conta. | 11 |
| `contact_type`* | string | Forma de contato com a pessoa aprovadora da conta, podendo ser **sms** ou **email** | |
## Response
STATUS 202
Response Body: Reversão Requisitada
```json
{
"reversal_status": "pending_2fa_approval",
"end_to_end_id": "E32402502202405081755SxyT2DDcVwc",
"pix_transfer_key": "cdcf0d25-08a1-46e3-902a-6d7ca75e6c48",
"request_control_key": "7c5a1425-73eb-420e-b4fb-0ce3386c7d0c",
"created_at": "2021-10-22T20:30:23.459Z"
}
```
### Response Body
| Campo | Tipo | Descrição | Caracteres |
|-----------------------|------------|-----------------------------------------------------------------|-----------------------------------------------------------|
| `reversal_status` | enumerator | Enumerador de status da transação de devolução. | [Enumerador reversal_status](#enumerador-reversal_status) |
| `transfer_amount` | number | Valor da transferência de devolução. | 11 |
| `pix_transfer_key` | uuidv4 | Chave da transação pix executada na devolução. | 36 |
| `request_control_key` | uuidv4 | Chave única de identificação da request utilizada pelo cliente. | 36 |
| `created_at` | string | Data e hora da devolução. | 10 |
### Enumerador reversal_status
| Enumerador | Descrição |
|--------------------------|----------------------------------------------------------|
| **sent** | Transferência Pix realizada com sucesso. |
| **pending** | Transferência Pix pendente. |
| **pending_2fa_approval** | Transferência Pix pendente de aprovação por dois fatores |
| **rejected** | Transferência Pix rejeitada. |
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": "E32402502202405081755SxyT2DDcVwc",
"pix_transfer_status": "rejected",
"created_at": "2021-10-22T20:30:23.459Z"
}
}
}
```
:::info Informação
Além dos erros anteriormente listados para [transferência Pix](/documentation/baas/pix/realizar_transferencia), a
devolução de um Pix também pode retornar os erros listados abaixo.
:::
| Código HTTP
`status` | Código QI
`code` | Título
`title` | Descrição (eng)
`description` | Descrição (ptbr)
`translation` |
|--------------------------|----------------------|--------------------------------------|------------------------------------------------------------------------|-------------------------------------------------------------------------------------------|
| 400 | QIT000001 | Bad Request | Schema Error | 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 |
---
# Solicitar reenvio de token para uma transação
URL: /documentation/baas/pix/2fa_v2/solicitacao_de_reenvio_de_token
Um novo token será gerado e enviado para o aprovador da transação pix. Caso o número limite de tentativas de validação
do token tenha sido excedida, não será permitido o reenvio.
## Request
ENDPOINT /account/ ACCOUNT_KEY /pix_transfer/ PIX_TRANSFER_KEY /resend_token
MÉTODO PATCH
### Path Params
| Campo | Tipo | Descrição | Caracteres |
|----------------------|--------|------------------------------------------------------------------|------------|
| `account_key` * | uuidv4 | Chave única de identificação da conta. | 36 |
| `pix_transfer_key` * | uuidv4 | Chave única de identificação da transferência Pix no sistema QI. | 36 |
### Body Params
| Campo | Tipo | Descrição | Caracteres |
|----------------|--------|-------------------------------------------------------------------------------------------|------------|
| `contact_type` | enumerator | Forma de envio do token de autenticação | **[Enumerador contact_type](#enumerador-contact_type)** |
:::info Informação
Caso não seja enviado um `contact_type`, o token será enviado da forma solicitada originalmente.
:::
| Enumerador | Descrição |
|------------|---------------------------------------------------|
| **sms** | Envio por Mensagem de Texto para telefone celular |
| **email** | Envio por correio eletrônico |
## Response
STATUS 202
Response Body: Transação Solicitada
```json
{
"request_control_key": "b6804f32-101e-4702-8fbc-c2dbc4c2caec",
"pix_transfer_key": "8cb70dea-9fb0-4a68-9572-99a72849c8d6",
"end_to_end_id": "E32402502202405081755SxyT2DDcVwc",
"pix_transfer_status": "pending_2fa_approval",
"created_at": "2021-10-22T20:30:23.459Z"
}
```
STATUS 4xx
Response Body: Transferê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",
"pix_transfer_key": "8cb70dea-9fb0-4a68-9572-99a72849c8d6",
"pix_transfer_status": "rejected",
"created_at": "2021-10-22T20:30:23.459Z"
}
}
}
```
| Código HTTP
`status` | Código QI
`code` | Título
`title` | Descrição (eng)
`description` | Descrição (ptbr)
`translation` |
|--------------------------|----------------------|----------------------------------------------|-------------------------------------------------------------------------|------------------------------------------------------------------------------|
| 400 | QIT000001 | Bad Request | Schema Error | Erro de Schema |
| 404 | PXT000004 | Account not found | Account not found for: \{account_datum\} | Conta não encontrada para: \{account_datum\} |
| 404 | PXT000023 | Outgoing PIX Transfer Not Found | Pix transfer key \{pix_transfer_key\} was not found | Transferência PIX de saída com chave \{pix_transfer_key\} não foi encontrada |
| 400 | PXT000171 | Number of token validation attempts exceeded | The maximum number of failed token validation attempts has been reached | Número máximo de tentativas de validação de token atingida |
| 400 | PXT000175 | Invalid Status | Pix transfer not in pending_2fa_approval status | Pix transfer não está pendente de aprovação por two factor authentication |
| 400 | PXT000176 | Error Sending Token | An error occurred while resending token and its being investigated | Um erro ocorreu ao reenviar token e está sendo investigado |
---
# Solicitar Transação com Autenticação de Dois Fatores
URL: /documentation/baas/pix/2fa_v2/solicitacao_de_transacao_pix_2fa
## Request
ENDPOINT /account/ ACCOUNT_KEY /pix_transfer
MÉTODO POST
### Path Params
| Campo | Tipo | Descrição | Caracteres |
|---------------|--------|----------------------------------------|------------|
| `account_key` | uuidv4 | Chave única de identificação da conta. | 36 |
**Chave**
## Autenticação via Email e SMS
Request Body: Transferência via Chave Pix com TFA por SMS ou Email
```json
{
"request_control_key": "b6804f32-101e-4702-8fbc-c2dbc4c2caec",
"pix_transfer_type": "key",
"target_pix_key": "target_pix_key@email.com",
"transaction_amount": 500.65,
"end_to_end_id": "E73856642202309201429bZKfklNlbwu",
"pix_message": "Ola Mundo",
"tfa_info": {
"approver_document_number": "98765432100",
"contact_type": "email"
}
}
```
## Autenticação via Dispositivo
Além das formas já existentes de autenticação via **sms** e **email**, é possível autenticar a transação utilizando um dispositivo [previamente cadastrado](/documentation/baas/dispositivo/create/solicitacao_cadastro_dispositivo). Nesse caso, o `session_id` deve ser obtido na **Device Scan** e enviado no `tfa_info`.
Request Body: Transferência via Chave Pix com TFA por Dispositivo
```json
{
"request_control_key": "b6804f32-101e-4702-8fbc-c2dbc4c2caec",
"pix_transfer_type": "key",
"target_pix_key": "target_pix_key@email.com",
"transaction_amount": 500.65,
"end_to_end_id": "E73856642202309201429bZKfklNlbwu",
"pix_message": "Ola Mundo",
"tfa_info": {
"approver_document_number": "98765432100",
"session_id": "b2f18d3a-67c2-4a7f-98e5-1d3f5c6b8a72",
"contact_type": "device"
}
}
```
### Body Params
| Campo | Tipo | Descrição | Caracteres |
|-------------------------|------------|--------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|-----------------------------------------|
| `request_control_key` * | uuidv4 | Chave única de identificação da request utilizada pelo cliente no formato uuid v4. | 36 |
| `pix_transfer_type` * | enumerator | 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 transferência. | 10 |
| `end_to_end_id` * | string | Chave de idempotência de uma transação Pix dentro do SPI (Sistema de Pagamento Instantâneo). Esta chave é retornada na consulta de chave Pix. Só deve ser enviado se o `pix_transfer_type` for **key**, **static_qr_code** ou **static_qr_code** | 32 |
| `pix_message` | string | Mensagem a ser enviada junto à transferência Pix. | 140 |
| `tfa_info`* | Object | Objeto contendo o documento da pessoa aprovadora da conta e a forma de contato. | **[Objeto tfa_info](#objeto-tfa_info)** |
**Manual**
## Autenticação via Email e SMS
Request Body: Transferência Manual com TFA por SMS ou Email
```json
{
"request_control_key": "b6804f32-101e-4702-8fbc-c2dbc4c2caec",
"pix_transfer_type": "manual",
"target_account": {
"account_branch": "0001",
"account_digit": "3",
"account_number": "12345678",
"owner_document_number": "32402502000135",
"owner_name": "Qi Tech",
"account_type": "checking_account",
"ispb": "32402502"
},
"transaction_amount": 500.65,
"pix_message": "Ola Mundo",
"tfa_info": {
"approver_document_number": "98765432100",
"contact_type": "email"
}
}
```
## Autenticação via Dispositivo
Além das formas já existentes de autenticação via **sms** e **email**, é possível autenticar a transação utilizando um dispositivo [previamente cadastrado](/documentation/baas/dispositivo/create/solicitacao_cadastro_dispositivo). Nesse caso, o `session_id` deve ser obtido na **Device Scan** e enviado no `tfa_info`.
Request Body: Transferência Manual com TFA por Dispositivo
```json
{
"request_control_key": "b6804f32-101e-4702-8fbc-c2dbc4c2caec",
"pix_transfer_type": "manual",
"target_account": {
"account_branch": "0001",
"account_digit": "3",
"account_number": "12345678",
"owner_document_number": "32402502000135",
"owner_name": "Qi Tech",
"account_type": "checking_account",
"ispb": "32402502"
},
"transaction_amount": 500.65,
"pix_message": "Ola Mundo",
"tfa_info": {
"approver_document_number": "98765432100",
"session_id": "b2f18d3a-67c2-4a7f-98e5-1d3f5c6b8a72",
"contact_type": "device"
}
}
```
### Body Params
| Campo | Tipo | Descrição | Caracteres |
|-------------------------|------------|---------------------------------------------------------------------------------------------------|-----------------------------------------------------|
| `request_control_key` * | uuidv4 | Chave única de identificação da request utilizada pelo cliente no formato uuid v4. | 36 |
| `pix_transfer_type` * | enumerator | Tipo de transferência Pix. | **manual** |
| `target_account` * | Object | Conta destino - Só deve ser enviada em transferências com `pix_transfer_type` do tipo **manual**. | **[Objeto target_account](#objeto-target_account)** | 10 |
| `transaction_amount` * | number | Valor da transferência. | 10 |
| `pix_message` | string | Mensagem a ser enviada junto à transferência Pix. | 140 |
| `tfa_info`* | Object | Objeto contendo o documento da pessoa aprovadora da conta e a forma de contato. | **[Objeto tfa_info](#objeto-tfa_info)** |
### Objeto target_account
| Campo | Tipo | Descrição | Caracteres |
|---------------------------|------------|-----------------------------------------------------|---------------------------------------------------------|
| `account_branch` * | string | Agência da conta. | 4 |
| `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`* | enumerator | Tipo da conta. | **[Enumerador account_type](#enumerador-account_type)** |
| `ispb` * | string | Base no CNPJ da instituição financeira (8 dígitos). | 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 |
**Qr Code**
## Autenticação via Email e SMS
Request Body: Transferência via QR Code com TFA por SMS ou Email
```json
{
"request_control_key": "b6804f32-101e-4702-8fbc-c2dbc4c2caec",
"pix_transfer_type": "static_qr_code",
"transaction_amount": 500.65,
"end_to_end_id": "E73856642202309201429bZKfklNlbwu",
"receiver_conciliation_id": "REC00000000000000000000009459463343",
"target_pix_key": "target_pix_key@email.com",
"pix_message": "Ola Mundo",
"tfa_info": {
"approver_document_number": "98765432100",
"contact_type": "email"
}
}
```
## Autenticação via Dispositivo
Além das formas já existentes de autenticação via **sms** e **email**, é possível autenticar a transação utilizando um dispositivo [previamente cadastrado](/documentation/baas/dispositivo/create/solicitacao_cadastro_dispositivo). Nesse caso, o `session_id` deve ser obtido na **Device Scan** e enviado no `tfa_info`.
Request Body: Transferência via QR Code com TFA por Dispositivo
```json
{
"request_control_key": "b6804f32-101e-4702-8fbc-c2dbc4c2caec",
"pix_transfer_type": "static_qr_code",
"transaction_amount": 500.65,
"end_to_end_id": "E73856642202309201429bZKfklNlbwu",
"receiver_conciliation_id": "REC00000000000000000000009459463343",
"target_pix_key": "target_pix_key@email.com",
"pix_message": "Ola Mundo",
"tfa_info": {
"approver_document_number": "98765432100",
"session_id": "b2f18d3a-67c2-4a7f-98e5-1d3f5c6b8a72",
"contact_type": "device"
}
}
```
### Body Params
| Campo | Tipo | Descrição | Caracteres |
|----------------------------|------------|---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|-------------------------------------------|
| `request_control_key`* | uuidv4 | Chave única de identificação da request utilizada pelo cliente no formato uuid v4. | 36 |
| `pix_transfer_type`* | enumerator | Tipo de transferência Pix. | **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 transferência. | 10 |
| `end_to_end_id`* | string | Chave de idempotência de uma transação Pix dentro do SPI (Sistema de Pagamento Instantâneo). Esta chave é retornada na consulta de chave Pix. Só deve ser enviado se o `pix_transfer_type` for **key**, **static_qr_code** ou **static_qr_code**. | 32 |
| `pix_message` | string | Mensagem a ser enviada junto à transferência Pix. | 140 |
| `tfa_info`* | Object | Objeto contendo o documento da pessoa aprovadora da conta e a forma de contato. | **[Objeto tfa_info](#objeto-tfa_info)** |
:::info Aviso
O `end_to_end_id` é retornado ao [decodificar o QR Code Pix](/documentation/pix/decodificar_qr_code), utilizando a URI
do Pix Copia e Cola.
:::
### Objeto tfa_info
| Campo | Tipo | Descrição | Caracteres |
|-----------------------------|--------|-------------------------------------------------------------------------------------|------------|
| `approver_document_number`* | string | Número de documento da pessoa aprovadora da conta. | 11 |
| `session_id`| string | Chave única de identificação da sessão do dispositivo no formato UUID v4 (obrigatório para TFA via dispositivo). | 36 |
| `contact_type`* | string | Forma de contato com a pessoa aprovadora da conta, podendo ser **sms**, **email** ou **device** | |
:::danger Aviso
O `end_to_end_id` da consulta deve ter sido feito em nome da conta 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 a transferência tenha sido bem
sucedida ou não.
:::
## Response
STATUS 202
Response Body: Transação Solicitada
```json
{
"request_control_key": "b6804f32-101e-4702-8fbc-c2dbc4c2caec",
"pix_transfer_key": "8cb70dea-9fb0-4a68-9572-99a72849c8d6",
"end_to_end_id": "E32402502202405081755SxyT2DDcVwc",
"pix_transfer_status": "pending_2fa_approval",
"created_at": "2021-10-22T20:30:23.459Z"
}
```
STATUS 4xx
Response Body: Transferê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",
"pix_transfer_key": "8cb70dea-9fb0-4a68-9572-99a72849c8d6",
"end_to_end_id": "E32402502202405081755SxyT2DDcVwc",
"pix_transfer_status": "rejected",
"created_at": "2021-10-22T20:30:23.459Z"
}
}
}
```
STATUS 4xx
Response Body: Error
```json
{
"title": "titulo",
"description": "description in English",
"translation": "descrição em portugues",
"code": "codigo",
"extra_fields": {}
}
```
| Código HTTP
`status` | Código QI
`code` | Título
`title` | Descrição (eng)
`description` | Descrição (ptbr)
`translation` |
|--------------------------|----------------------|----------------------------------------------------|-------------------------------------------------------------------------------------------------------------------------|------------------------------------------------------------------------------------------------------------------------|
| 400 | QIT000001 | Bad Request | Schema Error | Erro de Schema |
| 400 | PXT000168 | No approver permission | Given document number does not belong to an approver for this account | Número de documento enviado não pertence a um aprovador da conta |
| 400 | PXT000169 | tfa_info is required | Client must send object tfa_info | Cliente deve enviar objeto tfa_info |
| 400 | PXT000170 | Error occurred while sending token | An unexpected error occurred while sending token | Um erro inexperado ocorreu ao tentar enviar token |
| 406 | PXT000103 | request_control_key must be a valid uuid v4 string | request_control_key was not accepted for not being a valid uuid v4 string | request_control_key não foi aceito por não ser uma palavra uuid v4 válida |
| 400 | PXT000048 | Bad Request | Emoji not allowed in pix message. | Emoji não é permitido na mensagem pix. |
| 400 | PXT000104 | Invalid Transaction Amount | Transaction amount of \{transaction_amount\} is not valid. It must be a positive value with at maximum 2 decimal places | O valor de transação \{transaction_amount\} não é válido. Deve ser um valor positivo com no máximo duas casas decimais |
| 404 | PXT000004 | Account not found | Account not found for: \{account_datum\} | Conta não encontrada para: \{account_datum\} |
| 400 | PXT000003 | Account is Closed | Account \{account_key\} is closed. | Conta \{account_key\} está fechada. |
| 422 | PXT000092 | Invalid Account Type | Pix is not yet implemented for non-checking or non-escrow account types | Transações Pix não estão implementadas para conta que não sejam escrow ou livres |
| 403 | PIT000001 | User is not allowed to do this transaction | | Usuário não tem autorização para fazer essa transação |
| 400 | PXT000010 | Account is Blocked | Account \{account_key\} is blocked. | Conta \{account_key\} está bloqueada. |
| 400 | PXT000003 | Account is Closed | Account \{account_key\} is closed. | Conta \{account_key\} está fechada. |
| 400 | PIT000003 | Bad Request | Insufficient account balance for transfer and fee amount. | Saldo de conta insuficiente para a transferência e a taxa. |
| 400 | PXT000118 | Requester is not Pix Participant | The requester sent an alias key but is not a indirect pix participant | O requisitante enviou uma alias key no entanto não é um participante do pix indireto |
| 404 | PXT000120 | Alias sent not found | Alias key attached to this account not found | Alias key vinculada à conta não encontrada |
| 406 | PXT000105 | Invalid end_to_end_id | The end_to_end_id sent \{end_to_end_id\} is not valid. | O end_to_end_id enviado \{end_to_end_id\} não é válido. |
| 400 | PXT000108 | Bad Request | Billing account closed or blocked | Conta de cobrança encerrada ou bloqueada |
| 400 | PXT000079 | Bad Request | Insufficient billing account balance for fee. | Saldo de conta de cobrança insuficiente para a taxa. |
| 400 | PIT000004 | Bad Request | Transaction amount is over limit. | O total da transferência é superior ao limite. |
| 404 | PIX000056 | Not Found | Pix key inquiry not found | Consulta de chave pix não encontrada |
| 404 | PXT000041 | Not Found | Qr Code not found | Qr Code não encontrado |
| 400 | PXT000053 | Bad Request | QrCode already paid | Qr Code já Pago |
| 400 | PXT000118 | Requester is not Pix Participant | The requester sent an alias key but is not a indirect pix participant | O requisitante enviou uma alias key no entanto não é um participante do pix indireto |
| 404 | PXT000120 | Alias sent not found | Alias key attached to this account not found | Alias key vinculada à conta não encontrada |
| 400 | PXT000115 | Bad Request | Insufficient account balance for transfer and fee amount. | Saldo de conta insuficiente para a transferência e a taxa |
| 400 | PXT000128 | Bad Request | Pix key \{pix_key\} sent does match inquiry pix key. Verify if end_to_end_id sent is correct | Chave Pix \{pix_key\} enviada não condiz com consulta. Verifique se end_to_end_id enviado está correto |
| 400 | PXT000109 | Bad Request | request_control_key \{request_control_key\} already in use | request_control_key \{request_control_key\} já utilizada |
| 400 | PXT000061 | Bad Request | End to end id invalid. A pix transfer with the end to end id \{end_to_end\} has already been registered! | End to end id inválido. Uma transação pix com o identificador único \{end_to_end\} já foi registrada! |
| 400 | PXT000129 | SPI Error message | Message rejected by SPI-ICOM | Mensagem rejeitada pela SPI-ICOM |
| 408 | PXT000130 | SPI Timeout Control | SPI Timeout Control | Controle de timeout no SPI |
| 400 | PXT000131 | Receiver Internal Error | Cancelled transaction due to receiver's internal error | Transação interrompida devido a erro no PSP do Recebedor |
| 400 | PXT000132 | Invalid Target Account Number | Target account number is invalid | Número da conta de destino é inexistente ou inválido |
| 400 | PXT000133 | Blocked Target Account | Target account is blocked. | A conta de destino encontra-se bloqueada. |
| 400 | PXT000134 | Closed Target Account | Target account is closed. | A conta de destino encontra-se encerrada. |
| 400 | PXT000135 | Unsupported Transaction | Unsupported transaction for given target account. | A conta de destino não suporta este tipo de transação. |
| 400 | PXT000136 | Invalid Participant | SPI participant is not PSP settler agent of payer nor receiver. | Participante direto do SPI não é liquidante do PSP do Pagador / Recebedor. |
| 400 | PXT000137 | Zero Value Payment Order | Zero value payment order. | Ordem de pagamento com valor zero. |
| 400 | PXT000138 | Insufficient Funds | Insufficient funds in PI account from payer. | Saldo insuficiente na conta PI do pagador. |
| 400 | PXT000139 | Return Value Too Great | Return value greater than corresponding payment order. | Valor de devolução acima do valor de pagamento correspondente. |
| 400 | PXT000140 | Invalid Transactions Number | Invalid transactions number. | Quantidade de transações inválida. |
| 400 | PXT000141 | Unrelated Beneficiary Document Number | Beneficiary document number is not that of target account owner. | CPF/CNPJ do usuário recebedor não é compatível com o titular da conta de destino. |
| 400 | PXT000142 | Invalid Beneficiary Document Number | Invalid beneficiary document number | CPF/CNPJ da conta de destino está incorreto. |
| 400 | PXT000143 | Incorrect Message Element | Incorrect message element. | Elemento da mensagem incorreto. |
| 403 | PXT000144 | Rejected Payment Order | Beneficiary's PSP has rejected payment order. | Ordem de pagamento foi rejeitada pelo banco recebedor. |
| 403 | PXT000145 | Unauthorized Payer | Signing participant is unauthorized to make a payment order for paying account. | Participante que assinou a mensagem não é autorizado a realizar a operação na conta PI debitada. |
| 400 | PXT000146 | Invalid Datetime | Invalid datetime for message delivery. | Data e Hora do envio da mensagem inválida. |
| 400 | PXT000147 | Generic Error | Error while processing payment (generic error). | Erro no processamento do pagamento (erro genérico). |
| 400 | PXT000148 | Bad Format Operation Identifier | Badly formatted operation's identifier. | Identificador da operação mal formatado. |
| 400 | PXT000149 | Invalid Payer ISPB | Invalid or non-existent payer's PSP ISPB number. | Número ISPB do PSP do Pagador é inválido ou inexistente. |
| 400 | PXT000150 | Invalid Beneficiary ISPB | Invalid or non-existent beneficiary's PSP ISPB number. | Número ISPB do banco recebedor é inválido ou inexistente. |
| 400 | PXT000151 | Incorrect Type | Incorrect type for target account. | Tipo incorreto para a conta transacional especificada. |
| 400 | PXT000152 | Repeated End-to-End ID Error | The end_to_end_id was already used | O end_to_end_id já foi utilizado |
| 400 | PXT000153 | Invalid Target Account Type | The target account type cannot receive PIX transactions | O tipo de conta destino não pode receber transações PIX |
| 400 | PXT000154 | Invalid ISPB | Invalid or non-existent ISPB number. | Número ISPB é inválido ou inexistente. |
| 400 | PXT000155 | Amount too Great | Amount too great for credited account. | Valor de pagamento/devolução acima do permitido para a conta de destino creditada. |
| 400 | PXT000156 | QR Code Rejected | QR Code rejected by beneficiary's PSP. | QR Code rejeitado pelo PSP do usuário recebedor. |
| 503 | PXT000157 | Bacen Service Unavailable Error | Could not send the message to ICOM after 3 retries | Não pode enviar a mensagem para a ICOM depois de 3 tentativas |
| 400 | PXT000158 | Invalid Amount | Paid amount diverges from expected amount of \{expected_amount\} | O valor do pagamento diverge do valor esperado de \{expected_amount\} |
| 400 | PXT000159 | QR code inactive | QR code is not active at the time of payment | QR code não está ativo no instante do pagamento |
| 400 | PXT000188 | Session ID needed | A session_id must be provided token | Uma session_id deve ser fornecida |
---
# Aprovar Agendamento de Transação Pix com Autenticação de Dois Fatores
URL: /documentation/baas/pix/agendamento/aprovacao_de_agendamento_2fa
## Request
ENDPOINT /account/ ACCOUNT_KEY /pix_schedule/ SCHEDULE_KEY /validate_token
MÉTODO PUT
### Path Params
| Campo | Tipo | Descrição | Caracteres |
|----------------|--------|----------------------------------------------|------------|
| `account_key` | uuidv4 | Chave única de identificação da conta. | 36 |
| `schedule_key` | uuidv4 | Chave única de identificação do agendamento. | 36 |
## Autenticação via Email e SMS
Request Body
```json
{
"token": "329adf"
}
```
## Autenticação via Dispositivo
Para aprovar e finalizar a autenticação via dispositivo, a requisição deve ser enviada com um payload vazio. A validação ocorre internamente, sem necessidade de informações adicionais no corpo da requisição. É importante destacar que este endpoint só deve ser utilizado após a [solicitação de agendamento](./solicitacao_de_agendamento_2fa.md) ter sido iniciada.
Request Body
```json
{
}
```
### Body Params
| Campo | Tipo | Descrição | Caracteres |
|---------|--------|----------------------------------------------------------------------------------------------------------------------------------------|------------|
| `token` | string | Código de autenticação enviado ao aprovador de movimentações da conta **obrigatório para TFA via SMS ou e-mail** | 6 |
## Response
STATUS 201
Response Body: Agendamento Aprovado
```json
{
"request_control_key": "b6804f32-101e-4702-8fbc-c2dbc4c2caec",
"schedule_key": "f64b3fa7-d09d-4927-ad4f-b966df9fb153",
"schedule_status": "scheduled",
"schedule_date": "2024-12-31",
"created_at": "2023-03-13T19:00:28.440Z"
}
```
STATUS 4xx
Response Body: Error
```json
{
"title": "titulo",
"description": "description in English",
"translation": "descrição em portugues",
"code": "codigo",
"extra_fields": {}
}
```
| Código HTTP
`status` | Código QI
`code` | Título
`title` | Descrição (eng)
`description` | Descrição (ptbr)
`translation` |
|--------------------------|----------------------|----------------------------------------------|-------------------------------------------------------------------------|----------------------------------------------------------------------------|
| 400 | QIT000001 | Bad Request | schema error description | Schema Inválido |
| 404 | PSC000001 | Account not Found | Account was not found | Conta não encontrada |
| 403 | PSC000012 | User is not allowed to do this transaction | User is not allowed to do this transaction | Usuário não tem autorização para fazer essa transação |
| 404 | PSC000025 | PixSchedule not Found | PixSchedule was not found | PixSchedule não encontrada |
| 400 | PSC000048 | Error occurred while sending token | An unexpected error occurred while sending token | Um erro inesperado ocorreu ao tentar enviar token |
| 400 | PSC000049 | Number of token validation attempts exceeded | The maximum number of failed token validation attempts has been reached | Número máximo de tentativas de validação de token atingida |
| 400 | PSC000052 | Incorrect Token | Token sent does not match expected | Token enviado não condiz com o esperado |
| 400 | PSC000053 | Error Sending Token | An error occurred while resending token and its being investigated | Um erro ocorreu ao reenviar token e está sendo investigado |
| 400 | PSC000054 | Invalid Schedule Date | Schedule must be approved before the scheduled date | Agendamento deve ser aprovado em data anterior à programada para transação |
| 400 | PSC000055 | Bad Request | Schedule cannot be approved in current status | Agendamento pix não pode ser aprovado no status atual |
| 400 | PSC000058 | Token Required | A token is required for SMS or email validation. | Um token é necessário para validação via SMS ou email. |
---
# Aprovar Agendamento em Lote de Transação Pix com Autenticação de Dois Fatores
URL: /documentation/baas/pix/agendamento/batch/aprovacao_de_agendamento_em_lote_2fa
## Request
ENDPOINT /account/ ACCOUNT_KEY /pix_schedule_batch/ SCHEDULE_BATCH_KEY /validate_token
MÉTODO PUT
### Path Params
| Campo | Tipo | Descrição | Caracteres |
|----------------------|--------|------------------------------------------------------|------------|
| `account_key` | uuidv4 | Chave única de identificação da conta. | 36 |
| `schedule_batch_key` | uuidv4 | Chave única de identificação do agendamento em lote. | 36 |
## Autenticação via Email e SMS
Request Body
```json
{
"token": "329adf"
}
```
## Autenticação via Dispositivo
Para aprovar e finalizar a autenticação via dispositivo, a requisição deve ser enviada com um payload vazio. A validação ocorre internamente, sem necessidade de informações adicionais no corpo da requisição. É importante destacar que este endpoint só deve ser utilizado após a [solicitação de agendamento em lote](./solicitacao_de_agendamento_em_lote_2fa.md) ter sido iniciada.
Request Body
```json
{
}
```
### Body Params
| Campo | Tipo | Descrição | Caracteres |
|---------|--------|----------------------------------------------------------------------------------------------------------------------------------------|------------|
| `token` | string | Código de autenticação enviado ao aprovador de movimentações da conta **obrigatório para TFA via SMS ou e-mail** | 6 |
## Response
STATUS 201
Response Body: Agendamento Aprovado
```json
{
"request_control_key": "b6804f32-101e-4702-8fbc-c2dbc4c2caec",
"schedule_batch_key": "f64b3fa7-d09d-4927-ad4f-b966df9fb153",
"schedule_batch_status": "approved",
"created_at": "2023-03-13T19:00:28.440Z"
}
```
STATUS 4xx
Response Body: Error
```json
{
"title": "titulo",
"description": "description in English",
"translation": "descrição em portugues",
"code": "codigo",
"extra_fields": {}
}
```
| Código HTTP
`status` | Código QI
`code` | Título
`title` | Descrição (eng)
`description` | Descrição (ptbr)
`translation` |
|--------------------------|----------------------|----------------------------------------------|-------------------------------------------------------------------------|------------------------------------------------------------------------------------|
| 400 | QIT000001 | Bad Request | schema error description | Schema Inválido |
| 404 | PSC000001 | Account not Found | Account was not found | Conta não encontrada |
| 403 | PSC000012 | User is not allowed to do this transaction | User is not allowed to do this transaction | Usuário não tem autorização para fazer essa transação |
| 404 | PSC000042 | Schedule Batch not Found | ScheduleBatch was not found | ScheduleBatch não encontrada |
| 400 | PSC000048 | Error occurred while sending token | An unexpected error occurred while sending token | Um erro inesperado ocorreu ao tentar enviar token |
| 400 | PSC000049 | Number of token validation attempts exceeded | The maximum number of failed token validation attempts has been reached | Número máximo de tentativas de validação de token atingida |
| 400 | PSC000052 | Incorrect Token | Token sent does not match expected | Token enviado não condiz com o esperado |
| 400 | PSC000053 | Error Sending Token | An error occurred while resending token and its being investigated | Um erro ocorreu ao reenviar token e está sendo investigado |
| 400 | PSC000054 | Invalid Schedule Date | Schedule must be approved before the scheduled date | Agendamento deve ser aprovado em data anterior à programada para transação |
| 400 | PSC000055 | Bad Request | Schedule cannot be approved in current status | Agendamento pix não pode ser aprovado no status atual |
| 400 | PSC000056 | Bad Request | Schedule Batch cannot be approved in current status | Lote de agendamento pix não pode ser aprovado no status atual |
| 400 | PSC000057 | Invalid Schedule Date | Batch Schedule must be approved before the earliest scheduled date | Lote de agendamento deve ser aprovado em data anterior à programada para transação |
| 400 | PSC000058 | Token Required | A token is required for SMS or email validation. | Um token é necessário para validação via SMS ou email. |
---
# Cancelar Agendamento de Transação Pix em Lote
URL: /documentation/baas/pix/agendamento/batch/cancelamento_de_agendamento_em_lote
## Request
ENDPOINT /account/ ACCOUNT_KEY /pix_schedule_batch/ SCHEDULE_BATCH_KEY /cancel
MÉTODO PATCH
### Path Params
| Campo | Tipo | Descrição | Caracteres |
|----------------------|--------|-----------------------------------------------------|------------|
| `account_key` | uuidv4 | Chave única de identificação da conta. | 36 |
| `schedule_batch_key` | uuidv4 | Chave única de identificação do lote de agendamento | 36 |
### Response
STATUS 200
Response Body: Agendamento Cancelado
```json
{
"request_control_key": "b6804f32-101e-4702-8fbc-c2dbc4c2caec",
"schedule_batch_key": "f64b3fa7-d09d-4927-ad4f-b966df9fb153",
"schedule_batch_status": "cancelled",
"created_at": "2023-03-13T19:00:28.440Z"
}
```
STATUS 4xx
Response Body: Error
```json
{
"title": "titulo",
"description": "description in English",
"translation": "descrição em portugues",
"code": "codigo",
"extra_fields": {}
}
```
| Código HTTP
`status` | Código QI
`code` | Título
`title` | Descrição (eng)
`description` | Descrição (ptbr)
`translation` |
|--------------------------|----------------------|-----------------------------------------------------|--------------------------------------------------------------------------------------------------------------------------------------|---------------------------------------------------------------------------------------------------------------------------------------------|
| 400 | QIT000001 | Bad Request | schema error description | Schema Inválido |
| 404 | PSC000001 | Account not Found | Account was not found | Conta não encontrada |
| 403 | PSC000012 | User is not allowed to do this transaction | User is not allowed to do this transaction | Usuário não tem autorização para fazer essa transação |
| 404 | PSC000025 | PixSchedule not Found | PixSchedule was not found | PixSchedule não encontrada |
| 400 | PSC000027 | Bad Request | Action cannot be taken place as there is currently a pending transfer in progress | A ação não pôde ser completada como há uma transferência pendente |
| 404 | PSC000042 | Schedule Batch not Found | ScheduleBatch was not found | ScheduleBatch não encontrada |
| 400 | PSC000043 | Schedule Batch could not be canceled | ScheduleBatch could not be canceled due to current date being equal or after earliest schedule date. Cancel pix_schedules one by one | ScheduleBatch não pode ser cancelada devido a data atual ser superior ou igual à menor schedule_date. Cancele pix_schedules individualmente |
| 400 | PSC000044 | Bad Request | Schedule Batch cannot be cancelled in current status | Agendamento pix não pode ser cancelado no status atual |
---
# Listar Agendamentos de um Lote de Agendamento
URL: /documentation/baas/pix/agendamento/batch/consulta_de_agendamentos_de_um_lote
## Request
ENDPOINT /account/ ACCOUNT_KEY /pix_schedule_batch/ SCHEDULE_BATCH_KEY /pix_schedules
MÉTODO GET
### Path Params
| Campo | Tipo | Descrição | Caracteres |
|----------------------|--------|-------------------------------------------------------|------------|
| `account_key` | uuidv4 | Chave única de identificação da conta. | 36 |
| `schedule_batch_key` | uuidv4 | Chave única de identificação do lote de agendamentos. | 36 |
### Query Params
| Campo | Tipo | Descrição | Caracteres |
|-----------------------|---------|-------------------------------------------------------------------------|--------------------|
| `request_control_key` | uuidv4 | Chave única de identificação da request utilizada pelo cliente. | 36 |
| `schedule_status` | string | Status do agendamento. Pode ser enviado em forma de lista. | **[Enumerador schedule_status](#enumerador-schedule_status)** |
| `page` | integer | Número da página requisitada. 1 por padrão | |
| `page_size` | integer | Tamanho da página requisitada na consulta. 30 por padrão e valor máximo | Valor máximo de 30 |
### Enumerador schedule_status
| Enumerador | Descrição |
|----------------------------|------------------------------------------------------------------------------------------------|
| **scheduled** | Transação agendada |
| **sent** | Agendamento concluído e enviado com sucesso. Estado final |
| **rejected** | Agendamento rejeitado durante criação ou execução. Estado final |
| **cancelled** | Agendamento cancelado por solicitação de cliente. Estado final |
| **pending_2fa_approval** | Pendente de aprovação por autenticação de dois fatores |
| **pending_creation** | Agendamento em processo de criação (Estado transitório para agendamento em lote) |
| **waiting_batch_approval** | Agendamento criado e vinculado a um lote aguardando aprovação por autenticação de dois fatores |
### Response
STATUS 200
Response Body
```json
{
"data": [
{
"request_control_key": "b6804f32-101e-4702-8fbc-c2dbc4c2caec",
"schedule_key": "8cb70dea-9fb0-4a68-9572-99a72849c8d6",
"schedule_status": "scheduled",
"schedule_date": "2024-12-31",
"created_at": "2023-03-13T19:00:28.440Z"
},
{
"request_control_key": "bf6b0a4b-c7a5-446b-9dad-1ae10b25342a",
"schedule_key": "2479a5cd-079e-4d72-bf4e-16a695bda45e",
"schedule_status": "cancelled",
"schedule_date": "2024-12-31",
"created_at": "2023-03-13T19:00:28.440Z"
},
{
"request_control_key": "9d36c03e-2db7-4c90-87ed-6c9ddb3c03c7",
"schedule_key": "5d6b14b9-053f-408c-bcd7-61ecf9224f2c",
"schedule_status": "rejected",
"schedule_date": "2024-12-31",
"created_at": "2023-03-13T19:00:28.440Z"
}
],
"pagination": {
"current_page": 1,
"next_page": null,
"rows_per_page": 30
}
}
```
---
# Listar Lotes de Agendamento de uma conta
URL: /documentation/baas/pix/agendamento/batch/consulta_de_agendamentos_em_lote_de_uma_conta
## Request
ENDPOINT /account/ ACCOUNT_KEY /pix_schedule_batches
MÉTODO GET
### Path Params
| Campo | Tipo | Descrição | Caracteres |
|---------------|--------|----------------------------------------|------------|
| `account_key` | uuidv4 | Chave única de identificação da conta. | 36 |
### Query Params
| Campo | Tipo | Descrição | Caracteres |
|-------------------------|---------|-------------------------------------------------------------------------|--------------------|
| `request_control_key` | uuidv4 | Chave única de identificação da request utilizada pelo cliente. | 36 |
| `schedule_batch_status` | string | Status do lote de agendamento. Pode ser enviado em forma de lista. | 20 |
| `page` | integer | Número da página requisitada. 1 por padrão | |
| `page_size` | integer | Tamanho da página requisitada na consulta. 30 por padrão e valor máximo | Valor máximo de 30 |
### Response
STATUS 200
Response Body
```json
{
"data": [
{
"request_control_key": "b6804f32-101e-4702-8fbc-c2dbc4c2caec",
"schedule_batch_key": "8cb70dea-9fb0-4a68-9572-99a72849c8d6",
"schedule_batch_status": "approved",
"created_at": "2021-10-22T20:30:23.459Z"
},
{
"request_control_key": "bf6b0a4b-c7a5-446b-9dad-1ae10b25342a",
"schedule_batch_key": "2479a5cd-079e-4d72-bf4e-16a695bda45e",
"schedule_batch_status": "cancelled",
"created_at": "2021-10-22T20:30:23.459Z"
},
{
"request_control_key": "9d36c03e-2db7-4c90-87ed-6c9ddb3c03c7",
"schedule_batch_key": "5d6b14b9-053f-408c-bcd7-61ecf9224f2c",
"schedule_batch_status": "rejected",
"created_at": "2021-10-22T20:30:23.459Z"
}
],
"pagination": {
"current_page": 1,
"next_page": null,
"rows_per_page": 30
}
}
```
# Consultar Lote de Agendamento de uma conta
## Request
ENDPOINT /account/ ACCOUNT_KEY /pix_schedule_batch/ SCHEDULE_BATCH_KEY
MÉTODO GET
### Path Params
| Campo | Tipo | Descrição | Caracteres |
|----------------------|--------|-------------------------------------------------------|------------|
| `account_key` | uuidv4 | Chave única de identificação da conta. | 36 |
| `schedule_batch_key` | uuidv4 | Chave única de identificação do lote de agendamentos. | 36 |
### Response
STATUS 200
Response Body
```json
{
"request_control_key": "b6804f32-101e-4702-8fbc-c2dbc4c2caec",
"schedule_batch_key": "8cb70dea-9fb0-4a68-9572-99a72849c8d6",
"schedule_batch_status": "approved",
"created_at": "2021-10-22T20:30:23.459Z"
}
```
---
# Solicitar Agendamento de Transação Pix em Lote
URL: /documentation/baas/pix/agendamento/batch/solicitacao_de_agendamento_em_lote
A QI Tech oferece a possibilidade de realizar várias transações agendadas pix com uma única chamada. Nesse sistema os
agendamentos são realizados de forma assíncrona. Caso na chamada inicial seja retornado um **http status 4xx**, nenhum
dos agendamentos será realizado. Após a solicitação, o parceiro integrador receberá um webhook para cada **pix_schedule
**
rejeitado no ato da criação.
## Request
ENDPOINT /account/ ACCOUNT_KEY /pix_schedule_batch
MÉTODO POST
```json
{
"request_control_key": "6e4fc980-f8a1-4462-b6e2-d8a49f0ac055",
"pix_schedules": [
{
"request_control_key": "b6804f32-101e-4702-8fbc-c2dbc4c2caec",
"pix_transfer_type": "key",
"target_pix_key": "target_pix_key@email.com",
"transaction_amount": 500.65,
"end_to_end_id": "E73856642202309201429bZKfklNlbwu",
"pix_message": "Ola Mundo",
"schedule_date": "2024-12-01"
},
{
"request_control_key": "c6804f35-101e-4702-8fbc-c2dbc4c2caea",
"pix_transfer_type": "manual",
"target_account": {
"account_branch": "0001",
"account_digit": "3",
"account_number": "12345678",
"owner_document_number": "32402502000135",
"owner_name": "Qi Tech",
"account_type": "checking_account",
"ispb": "32402502"
},
"transaction_amount": 500.65,
"pix_message": "Ola Mundo",
"schedule_date": "2024-12-01"
},
{
"request_control_key": "a6804f42-101e-4702-8fbc-c2dbc4c2caed",
"pix_transfer_type": "static_qr_code",
"transaction_amount": 500.65,
"end_to_end_id": "E73856642202309201429bZKfklNlbwu",
"receiver_conciliation_id": "REC00000000000000000000009459463343",
"target_pix_key": "target_pix_key@email.com",
"pix_message": "Ola Mundo"
}
]
}
```
## Path Params
| Campo | Tipo | Descrição | Caracteres |
|---------------|--------|----------------------------------------|------------|
| `account_key` | uuidv4 | Chave única de identificação da conta. | 36 |
### Body Params
| Campo | Tipo | Descrição | Caracteres |
|-------------------------|--------|------------------------------------------------------------------------------------|----------------------------------------------------------|
| `request_control_key` * | uuidv4 | Chave única de identificação da request utilizada pelo cliente no formato uuid v4. | 36 |
| `pix_schedules` * | array | Lista de objetos pix_schedule vinculados ao lote. | lista de **[Objeto pix_schedule](#objeto-pix_schedule)** |
### Objeto pix_schedule
| Campo | Tipo | Descrição | Caracteres |
|----------------------------|------------|---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|-------------------------------------------------------------------|
| `request_control_key`* | uuidv4 | Chave única de identificação da request utilizada pelo cliente no formato uuid v4. | 36 |
| `pix_transfer_type`* | enumerator | Tipo de transferência Pix. | **[Enumerador pix_transfer_type](#enumerador-pix_transfer_type)** |
| `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 |
| `target_account` * | Object | Conta destino - Só deve ser enviada em transferências com `pix_transfer_type` do tipo **manual**. | **[Objeto target_account](#objeto-target_account)** | 10 |
| `transaction_amount`* | number | Valor da transferência. | 10 |
| `end_to_end_id` | string | Chave de idempotência de uma transação Pix dentro do SPI (Sistema de Pagamento Instantâneo). Esta chave é retornada na consulta de chave Pix. Só deve ser enviado se o `pix_transfer_type` for **key**, **static_qr_code** ou **static_qr_code**. | 32 |
| `pix_message` | string | Mensagem a ser enviada junto à transferência Pix. | 140 |
### 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`* | enumerator | Tipo da conta. | **[Enumerador account_type](#enumerador-account_type)** |
| `ispb` * | string | Base no CNPJ da instituição financeira (8 dígitos). | 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 |
### Enumerador 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) |
## Response
STATUS 201
Response Body: Agendamento em lote Aprovado
```json
{
"request_control_key": "b6804f32-101e-4702-8fbc-c2dbc4c2caec",
"schedule_batch_key": "8cb70dea-9fb0-4a68-9572-99a72849c8d6",
"schedule_batch_status": "approved",
"created_at": "2021-10-22T20:30:23.459Z"
}
```
### Enumerador schedule_batch_status
| Enumerador | Descrição |
|--------------------------|----------------------------------------------------------------------------|
| **created** | Agendamento em lote criado |
| **approved** | Agendamento em lote aprovado |
| **rejected** | Agendamento em lote rejeitado |
| **pending_2fa_approval** | Agendamento em lote pendente de aprovação por autenticação de dois fatores |
STATUS 4xx
Response Body: Error
```json
{
"title": "titulo",
"description": "description in English",
"translation": "descrição em portugues",
"code": "codigo",
"extra_fields": {}
}
```
| Código HTTP
`status` | Código QI
`code` | Título
`title` | Descrição (eng)
`description` | Descrição (ptbr)
`translation` |
|--------------------------|----------------------|-----------------------------------------------------|---------------------------------------------------------------------------------------------------------------------------|-----------------------------------------------------------------------------------------------------------------------------------|
| 400 | QIT000001 | Bad Request | schema error description | Schema Inválido |
| 404 | PSC000001 | Account not Found | Account was not found | Conta não encontrada |
| 406 | PSC000002 | Invalid Uuid | key was not accepted for not being a valid uuid v4 string | key não foi aceito por não ser uma palavra uuid v4 válida |
| 400 | PSC000003 | Bad Request | pix_message can not be longer than 140 characters | pix_message não pode ser maior que 140 caracteres |
| 400 | PSC000004 | Bad Request | Emoji not allowed in pix message | Emoji não é permitido na mensagem pix |
| 406 | PSC000005 | Invalid Transaction Amount | Transaction amount of transaction_amount is not valid. It must be a positive value with at maximum 2 decimal places | O valor de transação transaction_amount não é válido. Deve ser um valor positivo com no máximo duas casas decimais |
| 406 | PSC000006 | Invalid end_to_end_id | The end_to_end_id sent end_to_end_id is not valid | O end_to_end_id enviado end_to_end_id não é válido |
| 400 | PSC000007 | Invalid date format | Dates must be sent using format YYYY-MM-DD | Datas devem ser enviadas no formato YYYY-MM-DD |
| 400 | PSC000008 | Invalid Schedule Date | Schedule date must be after current date for UTC-3 | Data de agendamento deve ser após a data atual em UTC-3 |
| 400 | PSC000009 | Account is Closed | Account is closed | Conta está fechada |
| 400 | PSC000010 | Account is Blocked | Account is blocked | Conta está bloqueada |
| 422 | PSC000011 | Invalid Account Type | Pix is not yet implemented for non-checking or non-escrow account types | Transações Pix não estão implementadas para conta que não sejam escrow ou livres |
| 403 | PSC000012 | User is not allowed to do this transaction | User is not allowed to do this transaction | Usuário não tem autorização para fazer essa transação |
| 400 | PSC000013 | Bad Request | For Manual Pix Transfer Type a target account must be provided | Para transação pix do tipo manual, uma conta destino deve ser fornecida |
| 404 | PSC000014 | Inquiry Not Found | Pix key inquiry was not found | Pesquisa de chave pix não encontrada |
| 400 | PSC000015 | Bad Request | Pix key sent does match inquiry pix key. Verify if end_to_end_id sent is correct | Chave Pix enviada não condiz com consulta. Verifique se end_to_end_id enviado está correto |
| 404 | PSC000016 | Account not found | Nonexistent account in destination financial institution | Conta inexistente na instituição financeira de destino |
| 400 | PSC000017 | Target Account and Source Account must be different | Target Account must not be the same as Source Account | A conta de destino não pode ser a mesma da conta de origem |
| 409 | PSC000018 | Bad Request | request_control_key request_control_key already in use | request_control_key request_control_key já utilizada |
| 400 | PSC000019 | Invalid Target | Account does not have permission to transfer to the given target account | A conta não possui permissão para realizar transferências para a conta enviada |
| 404 | PSC000020 | Decode Inquiry Not Found | QR Code decode inquiry not found | Pesquisa e decodificação de QR code não encontrada |
| 400 | PSC000021 | Bad Request | Receiver Conciliation Id sent does match decode inquiry receiver_conciliation_id. Verify if end_to_end_id sent is correct | Identificador de transação enviado não condiz com consulta. Verifique se end_to_end_id enviado está correto |
| 400 | PSC000022 | Bad Request | Dynamic Instant QR codes cannot be scheduled for payment | Pagamentos de vencimento instantâneo não podem ter pagamento agendado |
| 400 | PSC000023 | Bad Request | Schedule Date sent is after max payment date for target qr code | Data de agendamento enviada é após a data máxima de pagamento para o qr code enviado |
| 400 | PSC000024 | Bad Request | Pix transfer type sent does match decode inquiry qr code type. Verify if end_to_end_id sent is correct | Tipo de transação pix enviado enviado não condiz com tipo de qr code da consulta. Verifique se end_to_end_id enviado está correto |
| 400 | PSC000040 | Empty pix-schedule list received | A list of pix schedules must be provided | Uma lista de agendamentos pix deve ser fornecida |
| 409 | PSC000041 | Bad Request | One or more request_control_key already in use | Uma ou mais request_control_key já está sendo utilizada |
| 403 | PSC000045 | Requester not allowed to access this endpoint | Requester has no permission to perform pix transfers on this endpoint | Requester não possui permissão de realizar transações pix através deste endpoint |
---
# Solicitar Agendamento de Transação Pix em Lote
URL: /documentation/baas/pix/agendamento/batch/solicitacao_de_agendamento_em_lote_2fa
A QI Tech oferece a possibilidade de realizar várias transações agendadas pix com uma única chamada. Nesse sistema os
agendamentos são realizados de forma assíncrona. Caso na chamada inicial seja retornado um **http status 4xx**, nenhum
dos agendamentos será realizado. Após a solicitação, o parceiro integrador receberá um webhook para cada **pix_schedule
** rejeitado no ato da criação.
Neste tipo de agendamento, é necessário a confirmação da programação de pagamento via token enviado à pessoa com poderes
de aprovação de movimentação na conta credora.
A solicitação de agendamento Pix em lote por parceiros integradores configurados para a utilização de autenticação de
dois
fatores é realizada de forma similar ao descrito
em [solicitar agendamento de_transação_pix_em_lote](/documentation/baas/pix/agendamento/solicitacao_de_agendamento_em_lote).
A diferença
ocorre na adição do objeto `tfa_info`, contento informações sobre o aprovador da transferência e a forma de contato, e o
status de uma solicitação bem sucedida que será sempre **pending_2fa_approval**.
O evento de notificação para o envio de `token` ao aprovador é **baas.token_validation.pix_transfer.schedule.batch**. É
possível [personalizar](/documentation/notificacoes/template) a mensagem enviada.
## Request
ENDPOINT /account/ ACCOUNT_KEY /pix_schedule_batch
MÉTODO POST
## Autenticação via Email e SMS
Request Body: Agendamento em Lote com TFA por SMS ou Email
```json
{
"request_control_key": "6e4fc980-f8a1-4462-b6e2-d8a49f0ac055",
"tfa_info": {
"approver_document_number": "98765432100",
"contact_type": "email"
},
"pix_schedules": [
{
"request_control_key": "b6804f32-101e-4702-8fbc-c2dbc4c2caec",
"pix_transfer_type": "key",
"target_pix_key": "target_pix_key@email.com",
"transaction_amount": 500.65,
"end_to_end_id": "E73856642202309201429bZKfklNlbwu",
"pix_message": "Ola Mundo",
"schedule_date": "2024-12-01"
},
{
"request_control_key": "c6804f35-101e-4702-8fbc-c2dbc4c2caea",
"pix_transfer_type": "manual",
"target_account": {
"account_branch": "0001",
"account_digit": "3",
"account_number": "12345678",
"owner_document_number": "32402502000135",
"owner_name": "Qi Tech",
"account_type": "checking_account",
"ispb": "32402502"
},
"transaction_amount": 500.65,
"pix_message": "Ola Mundo",
"schedule_date": "2024-12-01"
},
{
"request_control_key": "a6804f42-101e-4702-8fbc-c2dbc4c2caed",
"pix_transfer_type": "static_qr_code",
"transaction_amount": 500.65,
"end_to_end_id": "E73856642202309201429bZKfklNlbwu",
"receiver_conciliation_id": "REC00000000000000000000009459463343",
"target_pix_key": "target_pix_key@email.com",
"pix_message": "Ola Mundo"
}
]
}
```
## Autenticação via Dispositivo
Além das formas já existentes de autenticação via **sms** e **email**, é possível autenticar a transação utilizando um dispositivo [previamente cadastrado](/documentation/baas/dispositivo/create/solicitacao_cadastro_dispositivo). Nesse caso, o `session_id` deve ser obtido na **Device Scan** e enviado no `tfa_info`.
Request Body: Agendamento em Lote com TFA por Dispositivo
```json
{
"request_control_key": "6e4fc980-f8a1-4462-b6e2-d8a49f0ac055",
"tfa_info": {
"approver_document_number": "98765432100",
"session_id": "b2f18d3a-67c2-4a7f-98e5-1d3f5c6b8a72",
"contact_type": "device"
},
"pix_schedules": [
{
"request_control_key": "b6804f32-101e-4702-8fbc-c2dbc4c2caec",
"pix_transfer_type": "key",
"target_pix_key": "target_pix_key@email.com",
"transaction_amount": 500.65,
"end_to_end_id": "E73856642202309201429bZKfklNlbwu",
"pix_message": "Ola Mundo",
"schedule_date": "2024-12-01"
},
{
"request_control_key": "c6804f35-101e-4702-8fbc-c2dbc4c2caea",
"pix_transfer_type": "manual",
"target_account": {
"account_branch": "0001",
"account_digit": "3",
"account_number": "12345678",
"owner_document_number": "32402502000135",
"owner_name": "Qi Tech",
"account_type": "checking_account",
"ispb": "32402502"
},
"transaction_amount": 500.65,
"pix_message": "Ola Mundo",
"schedule_date": "2024-12-01"
},
{
"request_control_key": "a6804f42-101e-4702-8fbc-c2dbc4c2caed",
"pix_transfer_type": "static_qr_code",
"transaction_amount": 500.65,
"end_to_end_id": "E73856642202309201429bZKfklNlbwu",
"receiver_conciliation_id": "REC00000000000000000000009459463343",
"target_pix_key": "target_pix_key@email.com",
"pix_message": "Ola Mundo"
}
]
}
```
## Path Params
| Campo | Tipo | Descrição | Caracteres |
|---------------|--------|----------------------------------------|------------|
| `account_key` | uuidv4 | Chave única de identificação da conta. | 36 |
### Body Params
| Campo | Tipo | Descrição | Caracteres |
|-------------------------|--------|------------------------------------------------------------------------------------|----------------------------------------------------------|
| `request_control_key` * | uuidv4 | Chave única de identificação da request utilizada pelo cliente no formato uuid v4. | 36 |
| `pix_schedules` * | array | Lista de objetos pix_schedule vinculados ao lote. | lista de **[Objeto pix_schedule](#objeto-pix_schedule)** |
| `tfa_info`* | Object | Objeto contendo o documento da pessoa aprovadora da conta e a forma de contato. | **[Objeto tfa_info](#objeto-tfa_info)** |
### Objeto tfa_info
| Campo | Tipo | Descrição | Caracteres |
|-----------------------------|--------|----------------------------------------------------------------------------------------------------------------------------------|------------|
| `approver_document_number`* | string | Número de documento da pessoa aprovadora da conta. | 11 |
| `session_id` | string | Chave única de identificação da sessão do dispositivo no formato UUID v4 (obrigatório para TFA via dispositivo). | 36 |
| `contact_type`* | string | Forma de contato com a pessoa aprovadora da conta, podendo ser **sms**, **email** ou **device** | |
### Objeto pix_schedule
| Campo | Tipo | Descrição | Caracteres |
|----------------------------|------------|---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|-------------------------------------------------------------------|
| `request_control_key`* | uuidv4 | Chave única de identificação da request utilizada pelo cliente no formato uuid v4. | 36 |
| `pix_transfer_type`* | enumerator | Tipo de transferência Pix. | **[Enumerador pix_transfer_type](#enumerador-pix_transfer_type)** |
| `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 |
| `target_account` * | Object | Conta destino - Só deve ser enviada em transferências com `pix_transfer_type` do tipo **manual**. | **[Objeto target_account](#objeto-target_account)** | 10 |
| `transaction_amount`* | number | Valor da transferência. | 10 |
| `end_to_end_id` | string | Chave de idempotência de uma transação Pix dentro do SPI (Sistema de Pagamento Instantâneo). Esta chave é retornada na consulta de chave Pix. Só deve ser enviado se o `pix_transfer_type` for **key**, **static_qr_code** ou **static_qr_code**. | 32 |
| `pix_message` | string | Mensagem a ser enviada junto à transferência Pix. | 140 |
### 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`* | enumerator | Tipo da conta. | **[Enumerador account_type](#enumerador-account_type)** |
| `ispb` * | string | Base no CNPJ da instituição financeira (8 dígitos). | 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 |
### Enumerador 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) |
## Response
STATUS 202
Response Body: Agendamento em lote Aprovado
```json
{
"request_control_key": "b6804f32-101e-4702-8fbc-c2dbc4c2caec",
"schedule_batch_key": "8cb70dea-9fb0-4a68-9572-99a72849c8d6",
"schedule_batch_status": "pending_2fa_approval",
"created_at": "2021-10-22T20:30:23.459Z"
}
```
### Enumerador schedule_batch_status
| Enumerador | Descrição |
|--------------------------|----------------------------------------------------------------------------|
| **created** | Agendamento em lote criado |
| **approved** | Agendamento em lote aprovado |
| **rejected** | Agendamento em lote rejeitado |
| **pending_2fa_approval** | Agendamento em lote pendente de aprovação por autenticação de dois fatores |
STATUS 4xx
Response Body: Error
```json
{
"title": "titulo",
"description": "description in English",
"translation": "descrição em portugues",
"code": "codigo",
"extra_fields": {}
}
```
| Código HTTP
`status` | Código QI
`code` | Título
`title` | Descrição (eng)
`description` | Descrição (ptbr)
`translation` |
|--------------------------|----------------------|-----------------------------------------------------|---------------------------------------------------------------------------------------------------------------------------|-----------------------------------------------------------------------------------------------------------------------------------|
| 400 | QIT000001 | Bad Request | schema error description | Schema Inválido |
| 404 | PSC000001 | Account not Found | Account was not found | Conta não encontrada |
| 406 | PSC000002 | Invalid Uuid | key was not accepted for not being a valid uuid v4 string | key não foi aceito por não ser uma palavra uuid v4 válida |
| 400 | PSC000003 | Bad Request | pix_message can not be longer than 140 characters | pix_message não pode ser maior que 140 caracteres |
| 400 | PSC000004 | Bad Request | Emoji not allowed in pix message | Emoji não é permitido na mensagem pix |
| 406 | PSC000005 | Invalid Transaction Amount | Transaction amount of transaction_amount is not valid. It must be a positive value with at maximum 2 decimal places | O valor de transação transaction_amount não é válido. Deve ser um valor positivo com no máximo duas casas decimais |
| 406 | PSC000006 | Invalid end_to_end_id | The end_to_end_id sent end_to_end_id is not valid | O end_to_end_id enviado end_to_end_id não é válido |
| 400 | PSC000007 | Invalid date format | Dates must be sent using format YYYY-MM-DD | Datas devem ser enviadas no formato YYYY-MM-DD |
| 400 | PSC000008 | Invalid Schedule Date | Schedule date must be after current date for UTC-3 | Data de agendamento deve ser após a data atual em UTC-3 |
| 400 | PSC000009 | Account is Closed | Account is closed | Conta está fechada |
| 400 | PSC000010 | Account is Blocked | Account is blocked | Conta está bloqueada |
| 422 | PSC000011 | Invalid Account Type | Pix is not yet implemented for non-checking or non-escrow account types | Transações Pix não estão implementadas para conta que não sejam escrow ou livres |
| 403 | PSC000012 | User is not allowed to do this transaction | User is not allowed to do this transaction | Usuário não tem autorização para fazer essa transação |
| 400 | PSC000013 | Bad Request | For Manual Pix Transfer Type a target account must be provided | Para transação pix do tipo manual, uma conta destino deve ser fornecida |
| 404 | PSC000014 | Inquiry Not Found | Pix key inquiry was not found | Pesquisa de chave pix não encontrada |
| 400 | PSC000015 | Bad Request | Pix key sent does match inquiry pix key. Verify if end_to_end_id sent is correct | Chave Pix enviada não condiz com consulta. Verifique se end_to_end_id enviado está correto |
| 404 | PSC000016 | Account not found | Nonexistent account in destination financial institution | Conta inexistente na instituição financeira de destino |
| 400 | PSC000017 | Target Account and Source Account must be different | Target Account must not be the same as Source Account | A conta de destino não pode ser a mesma da conta de origem |
| 409 | PSC000018 | Bad Request | request_control_key request_control_key already in use | request_control_key request_control_key já utilizada |
| 400 | PSC000019 | Invalid Target | Account does not have permission to transfer to the given target account | A conta não possui permissão para realizar transferências para a conta enviada |
| 404 | PSC000020 | Decode Inquiry Not Found | QR Code decode inquiry not found | Pesquisa e decodificação de QR code não encontrada |
| 400 | PSC000021 | Bad Request | Receiver Conciliation Id sent does match decode inquiry receiver_conciliation_id. Verify if end_to_end_id sent is correct | Identificador de transação enviado não condiz com consulta. Verifique se end_to_end_id enviado está correto |
| 400 | PSC000022 | Bad Request | Dynamic Instant QR codes cannot be scheduled for payment | Pagamentos de vencimento instantâneo não podem ter pagamento agendado |
| 400 | PSC000023 | Bad Request | Schedule Date sent is after max payment date for target qr code | Data de agendamento enviada é após a data máxima de pagamento para o qr code enviado |
| 400 | PSC000024 | Bad Request | Pix transfer type sent does match decode inquiry qr code type. Verify if end_to_end_id sent is correct | Tipo de transação pix enviado enviado não condiz com tipo de qr code da consulta. Verifique se end_to_end_id enviado está correto |
| 400 | PSC000040 | Empty pix-schedule list received | A list of pix schedules must be provided | Uma lista de agendamentos pix deve ser fornecida |
| 409 | PSC000041 | Bad Request | One or more request_control_key already in use | Uma ou mais request_control_key já está sendo utilizada |
| 403 | PSC000045 | Requester not allowed to access this endpoint | Requester has no permission to perform pix transfers on this endpoint | Requester não possui permissão de realizar transações pix através deste endpoint |
---
# Solicitar reenvio de token para um agendamento em lote
URL: /documentation/baas/pix/agendamento/batch/solicitacao_de_reenvio_de_token_para_agendamento_em_lote_2fa
Um novo token será gerado e enviado para o aprovador do agendamento pix. Caso o número limite de tentativas de validação
do token tenha sido excedida, não será permitido o reenvio.
## Request
ENDPOINT /account/ ACCOUNT_KEY /pix_schedule_batch/ SCHEDULE_BATCH_KEY /resend_token
MÉTODO PATCH
### Path Params
| Campo | Tipo | Descrição | Caracteres |
|----------------------|--------|------------------------------------------------------|------------|
| `account_key` | uuidv4 | Chave única de identificação da conta. | 36 |
| `schedule_batch_key` | uuidv4 | Chave única de identificação do agendamento em lote. | 36 |
### Body Params
| Campo | Tipo | Descrição | Caracteres |
|----------------|------------|-----------------------------------------|---------------------------------------------------------|
| `contact_type` | enumerator | Forma de envio do token de autenticação | **[Enumerador contact_type](#enumerador-contact_type)** |
:::info Informação
Caso não seja enviado um `contact_type`, o token será enviado da forma solicitada originalmente.
:::
| Enumerador | Descrição |
|------------|---------------------------------------------------|
| **sms** | Envio por Mensagem de Texto para telefone celular |
| **email** | Envio por correio eletrônico |
## Response
STATUS 202
Response Body: Agendamento em lote Solicitado
```json
{
"request_control_key": "b6804f32-101e-4702-8fbc-c2dbc4c2caec",
"schedule_batch_key": "8cb70dea-9fb0-4a68-9572-99a72849c8d6",
"schedule_batch_status": "pending_2fa_approval",
"created_at": "2021-10-22T20:30:23.459Z"
}
```
STATUS 4xx
Response Body: Transferência Rejeitada
```json
{
"title": "titulo",
"description": "description in English",
"translation": "descrição em portugues",
"code": "codigo",
"extra_fields": {}
}
```
| Código HTTP
`status` | Código QI
`code` | Título
`title` | Descrição (eng)
`description` | Descrição (ptbr)
`translation` |
|--------------------------|----------------------|----------------------------------------------|-------------------------------------------------------------------------|------------------------------------------------------------------------------------|
| 400 | QIT000001 | Bad Request | schema error description | Schema Inválido |
| 404 | PSC000001 | Account not Found | Account was not found | Conta não encontrada |
| 403 | PSC000012 | User is not allowed to do this transaction | User is not allowed to do this transaction | Usuário não tem autorização para fazer essa transação |
| 404 | PSC000042 | Schedule Batch not Found | ScheduleBatch was not found | ScheduleBatch não encontrada |
| 400 | PSC000049 | Number of token validation attempts exceeded | The maximum number of failed token validation attempts has been reached | Número máximo de tentativas de validação de token atingida |
| 400 | PSC000052 | Incorrect Token | Token sent does not match expected | Token enviado não condiz com o esperado |
| 400 | PSC000053 | Error Sending Token | An error occurred while resending token and its being investigated | Um erro ocorreu ao reenviar token e está sendo investigado |
| 400 | PSC000054 | Invalid Schedule Date | Schedule must be approved before the scheduled date | Agendamento deve ser aprovado em data anterior à programada para transação |
| 400 | PSC000055 | Bad Request | Schedule cannot be approved in current status | Agendamento pix não pode ser aprovado no status atual |
| 400 | PSC000056 | Bad Request | Schedule Batch cannot be approved in current status | Lote de agendamento pix não pode ser aprovado no status atual |
| 400 | PSC000057 | Invalid Schedule Date | Batch Schedule must be approved before the earliest scheduled date | Lote de agendamento deve ser aprovado em data anterior à programada para transação |
---
# Cancelar Agendamento de Transação Pix
URL: /documentation/baas/pix/agendamento/cancelamento_de_agendamento
## Request
ENDPOINT /account/ ACCOUNT_KEY /pix_schedule/ SCHEDULE_KEY /cancel
MÉTODO PATCH
### Path Params
| Campo | Tipo | Descrição | Caracteres |
|----------------|--------|---------------------------------------------|------------|
| `account_key` | uuidv4 | Chave única de identificação da conta. | 36 |
| `schedule_key` | uuidv4 | Chave única de identificação do agendamento | 36 |
### Response
STATUS 200
Response Body: Agendamento Cancelado
```json
{
"request_control_key": "b6804f32-101e-4702-8fbc-c2dbc4c2caec",
"schedule_key": "f64b3fa7-d09d-4927-ad4f-b966df9fb153",
"schedule_status": "cancelled",
"schedule_date": "2024-12-31",
"created_at": "2023-03-13T19:00:28.440Z"
}
```
STATUS 4xx
Response Body: Error
```json
{
"title": "titulo",
"description": "description in English",
"translation": "descrição em portugues",
"code": "codigo",
"extra_fields": {}
}
```
| Código HTTP
`status` | Código QI
`code` | Título
`title` | Descrição (eng)
`description` | Descrição (ptbr)
`translation` |
|--------------------------|----------------------|--------------------------------------------|-----------------------------------------------------------------------------------|---------------------------------------------------------------------------------------------|
| 400 | QIT000001 | Bad Request | schema error description | Schema Inválido |
| 404 | PSC000001 | Account not Found | Account was not found | Conta não encontrada |
| 403 | PSC000012 | User is not allowed to do this transaction | User is not allowed to do this transaction | Usuário não tem autorização para fazer essa transação |
| 404 | PSC000025 | PixSchedule not Found | PixSchedule was not found | PixSchedule não encontrada |
| 400 | PSC000027 | Bad Request | Action cannot be taken place as there is currently a pending transfer in progress | A ação não pôde ser completada como há uma transferência pendente |
| 400 | PSC000028 | Bad Request | Pix Schedule cannot be cancelled in current status | Agendamento pix não pode ser cancelado no status atual |
| 400 | PSC000029 | Bad Request | The given Pix Schedule is tied to a batch. It cannot be individually cancelled | O agendamento pix enviado está ligado a um lote. Ela não pode ser individualmente cancelada |
---
# Consultar Agendamento de Transação Pix
URL: /documentation/baas/pix/agendamento/consulta_de_agendamento
## Request
ENDPOINT /account/ ACCOUNT_KEY /pix_schedule/ SCHEDULE_KEY
MÉTODO GET
### Path Params
| Campo | Tipo | Descrição | Caracteres |
|----------------|--------|---------------------------------------------|------------|
| `account_key` | uuidv4 | Chave única de identificação da conta. | 36 |
| `schedule_key` | uuidv4 | Chave única de identificação do agendamento | 36 |
### Response
STATUS 200
Response Body
```json
{
"created_at": "2024-07-10T16:17:28Z",
"pix_message": null,
"rejection_info": null,
"rejection_reason": null,
"request_control_key": "b8eb663e-10fe-4729-9db5-8f8c93de5001",
"schedule_date": "2024-07-10",
"schedule_key": "0c9091ab-079b-4a43-8b3d-d4ba36a23883",
"schedule_status": "sent",
"schedule_transfers": [
{
"created_at": "2024-07-10T16:19:33Z",
"end_to_end_id": "E3240250220240710161922sSHNf8BjI",
"pix_transfer_key": "427b70cd-73b0-45d1-bb4a-97f50f605022",
"pix_transfer_status": "sent"
}
],
"target_account": {
"account_branch": "0001",
"account_digit": "8",
"account_number": "1234567",
"account_type": "checking_account",
"ispb": "99999004",
"owner_document_number": "***91111***",
"owner_name": "Conta manual geral",
"owner_person_type": "natural",
"pix_key": null,
"receiver_conciliation_id": null
},
"transaction_amount": 2.0,
"updated_at": "2024-07-10T16:19:38Z"
}
```
---
# Consultar Agendamentos de Transação Pix de uma conta
URL: /documentation/baas/pix/agendamento/consulta_de_agendamentos_de_uma_conta
## Request
ENDPOINT /account/ ACCOUNT_KEY /pix_schedules
MÉTODO GET
### Path Params
| Campo | Tipo | Descrição | Caracteres |
|----------------|--------|---------------------------------------------|------------|
| `account_key` | uuidv4 | Chave única de identificação da conta. | 36 |
### Query Params
| Campo | Tipo | Descrição | Caracteres |
|-----------------------|---------|-------------------------------------------------------------------------|--------------------|
| `request_control_key` | uuidv4 | Chave única de identificação da request utilizada pelo cliente. | 36 |
| `schedule_status` | string | Status do agendamento. Pode ser enviado em forma de lista. | **[Enumerador schedule_status](#enumerador-schedule_status)** |
| `page` | integer | Número da página requisitada. 1 por padrão | |
| `page_size` | integer | Tamanho da página requisitada na consulta. 30 por padrão e valor máximo | Valor máximo de 30 |
### Enumerador schedule_status
| Enumerador | Descrição |
|----------------------------|------------------------------------------------------------------------------------------------|
| **scheduled** | Transação agendada |
| **sent** | Agendamento concluído e enviado com sucesso. Estado final |
| **rejected** | Agendamento rejeitado durante criação ou execução. Estado final |
| **cancelled** | Agendamento cancelado por solicitação de cliente. Estado final |
| **pending_2fa_approval** | Pendente de aprovação por autenticação de dois fatores |
| **pending_creation** | Agendamento em processo de criação (Estado transitório para agendamento em lote) |
| **waiting_batch_approval** | Agendamento criado e vinculado a um lote aguardando aprovação por autenticação de dois fatores |
### Response
STATUS 200
Response Body
```json
{
"data": [
{
"request_control_key": "b6804f32-101e-4702-8fbc-c2dbc4c2caec",
"schedule_key": "8cb70dea-9fb0-4a68-9572-99a72849c8d6",
"schedule_status": "scheduled",
"schedule_date": "2024-12-31",
"created_at": "2023-03-13T19:00:28.440Z"
},
{
"request_control_key": "bf6b0a4b-c7a5-446b-9dad-1ae10b25342a",
"schedule_key": "2479a5cd-079e-4d72-bf4e-16a695bda45e",
"schedule_status": "cancelled",
"schedule_date": "2024-12-31",
"created_at": "2023-03-13T19:00:28.440Z"
},
{
"request_control_key": "9d36c03e-2db7-4c90-87ed-6c9ddb3c03c7",
"schedule_key": "5d6b14b9-053f-408c-bcd7-61ecf9224f2c",
"schedule_status": "rejected",
"schedule_date": "2024-12-31",
"created_at": "2023-03-13T19:00:28.440Z"
}
],
"pagination": {
"current_page": 1,
"next_page": null,
"rows_per_page": 30
}
}
```
---
# Introdução
URL: /documentation/baas/pix/agendamento/introducao
Por meio dos endpoints apresentados nesta sessão, o parceiro integrador pode solicitar o agendamento de transações do
tipo pix. Com esta funcionalidade será possível criar, listar e cancelar agendamentos de uma determinada conta.
## Observações
- A data de agendamento leva em consideração o horário de Brasília (BRT ou UTC/GMT -03:00)
- As transações serão tentadas a partir de 8h BRT
- Transações que tenham falhado por falta de saldo serão retentadas em 1 hora com um limite de 3 tentativas
- Para transaçôes do tipo **key**, **static_qr_code** e **dynamic_qr_code**, antes de a transação ser completada, será
realizada uma nova verificação da chave Pix para garantir que a conta destino não foi alterada. Caso seja detectada
alguma discrepância, o agendamento será rejeitado (**rejected**)
- Um webhook será enviado ao parceiro integrador informando o sucesso ou rejeição de um agendamento
- Não é possível agendar um **dynamic_qr_code** instantâneo
- Transferencias por agendamento consomem limite de transação pix
## Pix Schedule Status
| Enumerador | Descrição |
|----------------------------|------------------------------------------------------------------------------------------------|
| **scheduled** | Transação agendada |
| **sent** | Agendamento concluído e enviado com sucesso. Estado final |
| **rejected** | Agendamento rejeitado durante criação ou execução. Estado final |
| **cancelled** | Agendamento cancelado por solicitação de cliente. Estado final |
| **pending_2fa_approval** | Pendente de aprovação por autenticação de dois fatores |
| **pending_creation** | Agendamento em processo de criação (Estado transitório para agendamento em lote) |
| **waiting_batch_approval** | Agendamento criado e vinculado a um lote aguardando aprovação por autenticação de dois fatores |
## Schedule Transfers
No dia do agendamento, após a realização da verificação de consistência da conta alvo, será tentada a transação pix.
Neste momento é gerada uma **pix_transfer** e esta será adicionada à lista de `schedule_transfers`. Serão tentadas um
máximo 3 transações pix.
### Schedule Transfer Object
| Campo | Tipo | Descrição | Caracteres |
|-----------------------|--------|---------------------------------------------------------------------------------------------|---------------------------------------------------------------------|
| `pix_transfer_key` | uuidv4 | Chave única de identificação da transferência Pix no sistema QI. | 36 |
| `end_to_end_id` * | string | Chave de idempotência de uma transação Pix dentro do SPI (Sistema de Pagamento Instantâneo) | 32 |
| `pix_transfer_status` | string | Status da transação. | [Enumeradores pix_transfer_status](#enumerador-pix-transfer-status) | |
| `created_at` | string | Data e hora de criação da transação. | 20 |
### Enumerador Pix Transfer Status
| Enumerador | Descrição |
|--------------|-----------------------------------------------------|
| **sent** | Transação enviada com sucesso. Estado final |
| **rejected** | Transação rejeitada durante execução. Estado final |
| **pending** | Transação pendente de conclusão. Estado Transitório |
---
# Introdução a Autenticação de Dois Fatores
URL: /documentation/baas/pix/agendamento/introducao_a_agendamento_2fa
Neste tipo de agendamento, é necessário a confirmação da programação de pagamento via token enviado à pessoa com poderes
de aprovação de movimentação na conta credora.
A solicitação de agendamento Pix por parceiros integradores configurados para a utilização de autenticação de dois
fatores é realizada de forma similar ao descrito
em [solicitar agendamento de_transação_pix](/documentation/baas/pix/agendamento/solicitacao_de_agendamento). A diferença
ocorre na adição do objeto `tfa_info`, contento informações sobre o aprovador da transferência e a forma de contato, e o
status de uma solicitação bem sucedida que será sempre **pending_2fa_approval**.
O mesmo vale para transações em lote Pix descrito
em [realizar transação pix em lote](/documentation/baas/pix/batch/solicitacao_de_transacao_em_lote_pix).
## Fluxo para um agendamento Pix com autorização
O agendamento Pix bem sucedido seguirá o seguinte fluxo de processos:
Realização da [solicitação de transação Pix](/documentation/baas/pix/agendamento/solicitacao_de_agendamento_2fa) e recebimento de resposta de forma síncrona com status de **pending_2fa_approval** e valor da `schedule_key`.
O aprovador indicado receberá um `token` de 6 dígitos compostos por algarismos.
O requisitante realiza a [confirmação de transação pix](/documentation/baas/pix/agendamento/aprovacao_de_agendamento_2fa) com a `schedule_key` e o `token`.
O agendamento será então atualizado para o status de **scheduled**.
## Observações
Cada agendamento possui um limite máximo de tentativas de validação do `token` de 5. Quando este limite é alcançado o agendamento será colocado em status de rejeitado (**rejected**) automaticamente.
Cada `token` possui duração máxima de 5 minutos.
Um agendamento pode ter seu `token` renovado e reenviado para o aprovador da transferência. Este processo reinica o tempo de 5 minutos e não reinicia o contador de tentativas inválidas. O `token` anterior torna-se inválido.
O evento de notificação para o envio de `token` ao aprovador é **baas.token_validation.pix_transfer.schedule.single**. É possível [personalizar](/documentation/notificacoes/template) a mensagem enviada.
As formas de envio (`contact_type`) de token implementadas são por **sms** e **email**.
---
# Solicitar Agendamento de Transação Pix
URL: /documentation/baas/pix/agendamento/solicitacao_de_agendamento
## Request
ENDPOINT /account/ ACCOUNT_KEY /pix_schedule
MÉTODO POST
### Path Params
| Campo | Tipo | Descrição | Caracteres |
|---------------|--------|----------------------------------------|------------|
| `account_key` | uuidv4 | Chave única de identificação da conta. | 36 |
**Chave**
Request Body: Agendamento por Chave Pix
```json
{
"request_control_key": "b6804f32-101e-4702-8fbc-c2dbc4c2caec",
"pix_transfer_type": "key",
"target_pix_key": "target_pix_key@email.com",
"transaction_amount": 500.65,
"end_to_end_id": "E73856642202309201429bZKfklNlbwu",
"pix_message": "Ola Mundo",
"schedule_date": "2024-12-01"
}
```
### Body Params
| Campo | Tipo | Descrição | Caracteres |
|-------------------------|------------|--------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|------------|
| `request_control_key` * | uuidv4 | Chave única de identificação da request utilizada pelo cliente no formato uuid v4. | 36 |
| `pix_transfer_type` * | enumerator | 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 transferência. | 10 |
| `end_to_end_id` * | string | Chave de idempotência de uma transação Pix dentro do SPI (Sistema de Pagamento Instantâneo). Esta chave é retornada na consulta de chave Pix. Só deve ser enviado se o `pix_transfer_type` for **key**, **static_qr_code** ou **static_qr_code** | 32 |
| `pix_message` | string | Mensagem a ser enviada junto à transferência Pix. | 140 |
| `schedule_date`* | string | Data a ser realizada a transação. | 10 |
**Manual**
Request Body: Transferência Manual
```json
{
"request_control_key": "b6804f32-101e-4702-8fbc-c2dbc4c2caec",
"pix_transfer_type": "manual",
"target_account": {
"account_branch": "0001",
"account_digit": "3",
"account_number": "12345678",
"owner_document_number": "32402502000135",
"owner_name": "Qi Tech",
"account_type": "checking_account",
"ispb": "32402502"
},
"transaction_amount": 500.65,
"pix_message": "Ola Mundo",
"schedule_date": "2024-12-01"
}
```
### Body Params
| Campo | Tipo | Descrição | Caracteres |
|-------------------------|------------|---------------------------------------------------------------------------------------------------|-----------------------------------------------------|
| `request_control_key` * | uuidv4 | Chave única de identificação da request utilizada pelo cliente no formato uuid v4. | 36 |
| `pix_transfer_type` * | enumerator | Tipo de transferência Pix. | **manual** |
| `target_account` * | Object | Conta destino - Só deve ser enviada em transferências com `pix_transfer_type` do tipo **manual**. | **[Objeto target_account](#objeto-target_account)** | 10 |
| `transaction_amount` * | number | Valor da transferência. | 10 |
| `pix_message` | string | Mensagem a ser enviada junto à transferência Pix. | 140 |
| `schedule_date`* | string | Data a ser realizada a transação. | 10 |
### Objeto target_account
| Campo | Tipo | Descrição | Caracteres |
|---------------------------|------------|-----------------------------------------------------|---------------------------------------------------------|
| `account_branch` * | string | Agência da conta. | 4 |
| `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`* | enumerator | Tipo da conta. | **[Enumerador account_type](#enumerador-account_type)** |
| `ispb` * | string | Base no CNPJ da instituição financeira (8 dígitos). | 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 |
**Qr Code**
Request Body: Transferência por Qr Code
```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",
"schedule_date": "2024-12-01"
}
```
### Body Params
| Campo | Tipo | Descrição | Caracteres |
|----------------------------|------------|---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|-------------------------------------------|
| `request_control_key`* | uuidv4 | Chave única de identificação da request utilizada pelo cliente no formato uuid v4. | 36 |
| `pix_transfer_type`* | enumerator | Tipo de transferência Pix. | **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 transferência. | 10 |
| `end_to_end_id`* | string | Chave de idempotência de uma transação Pix dentro do SPI (Sistema de Pagamento Instantâneo). Esta chave é retornada na consulta de chave Pix. Só deve ser enviado se o `pix_transfer_type` for **key**, **static_qr_code** ou **static_qr_code**. | 32 |
| `pix_message` | string | Mensagem a ser enviada junto à transferência Pix. | 140 |
:::info Aviso
O `end_to_end_id` é retornado ao [decodificar o QR Code Pix](/documentation/pix/decodificar_qr_code), utilizando a URI
do Pix Copia e Cola.
:::
:::danger Aviso
O `end_to_end_id` da consulta deve ter sido feito em nome da conta 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 a transferência tenha sido bem
sucedida ou não.
:::
## Response
STATUS 201
Response Body: Agendamento Criado
```json
{
"request_control_key": "b6804f32-101e-4702-8fbc-c2dbc4c2caec",
"schedule_key": "f64b3fa7-d09d-4927-ad4f-b966df9fb153",
"schedule_status": "scheduled",
"schedule_date": "2024-12-31",
"created_at": "2023-03-13T19:00:28.440Z"
}
```
STATUS 4xx
Response Body: Error
```json
{
"title": "titulo",
"description": "description in English",
"translation": "descrição em portugues",
"code": "codigo",
"extra_fields": {}
}
```
| Código HTTP
`status` | Código QI
`code` | Título
`title` | Descrição (eng)
`description` | Descrição (ptbr)
`translation` |
|--------------------------|----------------------|-----------------------------------------------------|--------------------------------------------------------------------------------------------------------------------------------------|---------------------------------------------------------------------------------------------------------------------------------------------|
| 400 | QIT000001 | Bad Request | schema error description | Schema Inválido |
| 404 | PSC000001 | Account not Found | Account was not found | Conta não encontrada |
| 406 | PSC000002 | Invalid Uuid | key was not accepted for not being a valid uuid v4 string | key não foi aceito por não ser uma palavra uuid v4 válida |
| 400 | PSC000003 | Bad Request | pix_message can not be longer than 140 characters | pix_message não pode ser maior que 140 caracteres |
| 400 | PSC000004 | Bad Request | Emoji not allowed in pix message | Emoji não é permitido na mensagem pix |
| 406 | PSC000005 | Invalid Transaction Amount | Transaction amount of transaction_amount is not valid. It must be a positive value with at maximum 2 decimal places | O valor de transação transaction_amount não é válido. Deve ser um valor positivo com no máximo duas casas decimais |
| 406 | PSC000006 | Invalid end_to_end_id | The end_to_end_id sent end_to_end_id is not valid | O end_to_end_id enviado end_to_end_id não é válido |
| 400 | PSC000007 | Invalid date format | Dates must be sent using format YYYY-MM-DD | Datas devem ser enviadas no formato YYYY-MM-DD |
| 400 | PSC000008 | Invalid Schedule Date | Schedule date must be after current date for UTC-3 | Data de agendamento deve ser após a data atual em UTC-3 |
| 400 | PSC000009 | Account is Closed | Account is closed | Conta está fechada |
| 400 | PSC000010 | Account is Blocked | Account is blocked | Conta está bloqueada |
| 422 | PSC000011 | Invalid Account Type | Pix is not yet implemented for non-checking or non-escrow account types | Transações Pix não estão implementadas para conta que não sejam escrow ou livres |
| 403 | PSC000012 | User is not allowed to do this transaction | User is not allowed to do this transaction | Usuário não tem autorização para fazer essa transação |
| 400 | PSC000013 | Bad Request | For Manual Pix Transfer Type a target account must be provided | Para transação pix do tipo manual, uma conta destino deve ser fornecida |
| 404 | PSC000014 | Inquiry Not Found | Pix key inquiry was not found | Pesquisa de chave pix não encontrada |
| 400 | PSC000015 | Bad Request | Pix key sent does match inquiry pix key. Verify if end_to_end_id sent is correct | Chave Pix enviada não condiz com consulta. Verifique se end_to_end_id enviado está correto |
| 404 | PSC000016 | Account not found | Nonexistent account in destination financial institution | Conta inexistente na instituição financeira de destino |
| 400 | PSC000017 | Target Account and Source Account must be different | Target Account must not be the same as Source Account | A conta de destino não pode ser a mesma da conta de origem |
| 409 | PSC000018 | Bad Request | request_control_key request_control_key already in use | request_control_key request_control_key já utilizada |
| 400 | PSC000019 | Invalid Target | Account does not have permission to transfer to the given target account | A conta não possui permissão para realizar transferências para a conta enviada |
| 404 | PSC000020 | Decode Inquiry Not Found | QR Code decode inquiry not found | Pesquisa e decodificação de QR code não encontrada |
| 400 | PSC000021 | Bad Request | Receiver Conciliation Id sent does match decode inquiry receiver_conciliation_id. Verify if end_to_end_id sent is correct | Identificador de transação enviado não condiz com consulta. Verifique se end_to_end_id enviado está correto |
| 400 | PSC000022 | Bad Request | Dynamic Instant QR codes cannot be scheduled for payment | Pagamentos de vencimento instantâneo não podem ter pagamento agendado |
| 400 | PSC000023 | Bad Request | Schedule Date sent is after max payment date for target qr code | Data de agendamento enviada é após a data máxima de pagamento para o qr code enviado |
| 400 | PSC000024 | Bad Request | Pix transfer type sent does match decode inquiry qr code type. Verify if end_to_end_id sent is correct | Tipo de transação pix enviado enviado não condiz com tipo de qr code da consulta. Verifique se end_to_end_id enviado está correto |
---
# Solicitar Agendamento de Transação Pix com Autenticação de Dois Fatores
URL: /documentation/baas/pix/agendamento/solicitacao_de_agendamento_2fa
## Request
ENDPOINT /account/ ACCOUNT_KEY /pix_schedule
MÉTODO POST
### Path Params
| Campo | Tipo | Descrição | Caracteres |
|---------------|--------|----------------------------------------|------------|
| `account_key` | uuidv4 | Chave única de identificação da conta. | 36 |
**Chave**
## Autenticação via Email e SMS
Request Body: Agendamento por Chave Pix com TFA por SMS ou Email
```json
{
"request_control_key": "b6804f32-101e-4702-8fbc-c2dbc4c2caec",
"pix_transfer_type": "key",
"target_pix_key": "target_pix_key@email.com",
"transaction_amount": 500.65,
"end_to_end_id": "E73856642202309201429bZKfklNlbwu",
"pix_message": "Ola Mundo",
"schedule_date": "2024-12-01",
"tfa_info": {
"approver_document_number": "98765432100",
"contact_type": "email"
}
}
```
## Autenticação via Dispositivo
Além das formas já existentes de autenticação via **sms** e **email**, é possível autenticar a transação utilizando um dispositivo [previamente cadastrado](/documentation/baas/dispositivo/create/solicitacao_cadastro_dispositivo). Nesse caso, o `session_id` deve ser obtido na **Device Scan** e enviado no `tfa_info`.
Request Body: Agendamento por Chave Pix com TFA por Dispositivo
```json
{
"request_control_key": "b6804f32-101e-4702-8fbc-c2dbc4c2caec",
"pix_transfer_type": "key",
"target_pix_key": "target_pix_key@email.com",
"transaction_amount": 500.65,
"end_to_end_id": "E73856642202309201429bZKfklNlbwu",
"pix_message": "Ola Mundo",
"schedule_date": "2024-12-01",
"tfa_info": {
"approver_document_number": "98765432100",
"session_id": "b2f18d3a-67c2-4a7f-98e5-1d3f5c6b8a72",
"contact_type": "device"
}
}
```
### Body Params
| Campo | Tipo | Descrição | Caracteres |
|-------------------------|------------|--------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|-----------------------------------------|
| `request_control_key` * | uuidv4 | Chave única de identificação da request utilizada pelo cliente no formato uuid v4. | 36 |
| `pix_transfer_type` * | enumerator | 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 transferência. | 10 |
| `end_to_end_id` * | string | Chave de idempotência de uma transação Pix dentro do SPI (Sistema de Pagamento Instantâneo). Esta chave é retornada na consulta de chave Pix. Só deve ser enviado se o `pix_transfer_type` for **key**, **static_qr_code** ou **static_qr_code** | 32 |
| `pix_message` | string | Mensagem a ser enviada junto à transferência Pix. | 140 |
| `schedule_date`* | string | Data a ser realizada a transação. | 10 |
| `tfa_info`* | Object | Objeto contendo o documento da pessoa aprovadora da conta e a forma de contato. | **[Objeto tfa_info](#objeto-tfa_info)** |
**Manual**
## Autenticação via Email e SMS
Request Body: Transferência Manual com TFA por SMS ou Email
```json
{
"request_control_key": "b6804f32-101e-4702-8fbc-c2dbc4c2caec",
"pix_transfer_type": "manual",
"target_account": {
"account_branch": "0001",
"account_digit": "3",
"account_number": "12345678",
"owner_document_number": "32402502000135",
"owner_name": "Qi Tech",
"account_type": "checking_account",
"ispb": "32402502"
},
"transaction_amount": 500.65,
"pix_message": "Ola Mundo",
"schedule_date": "2024-12-01",
"tfa_info": {
"approver_document_number": "98765432100",
"contact_type": "email"
}
}
```
## Autenticação via Dispositivo
Além das formas já existentes de autenticação via **sms** e **email**, é possível autenticar a transação utilizando um dispositivo [previamente cadastrado](/documentation/baas/dispositivo/create/solicitacao_cadastro_dispositivo). Nesse caso, o `session_id` deve ser obtido na **Device Scan** e enviado no `tfa_info`.
Request Body: Transferência Manual com TFA por Dispositivo
```json
{
"request_control_key": "b6804f32-101e-4702-8fbc-c2dbc4c2caec",
"pix_transfer_type": "manual",
"target_account": {
"account_branch": "0001",
"account_digit": "3",
"account_number": "12345678",
"owner_document_number": "32402502000135",
"owner_name": "Qi Tech",
"account_type": "checking_account",
"ispb": "32402502"
},
"transaction_amount": 500.65,
"pix_message": "Ola Mundo",
"schedule_date": "2024-12-01",
"tfa_info": {
"approver_document_number": "98765432100",
"session_id": "b2f18d3a-67c2-4a7f-98e5-1d3f5c6b8a72",
"contact_type": "device"
}
}
```
### Body Params
| Campo | Tipo | Descrição | Caracteres |
|-------------------------|------------|---------------------------------------------------------------------------------------------------|-----------------------------------------------------|
| `request_control_key` * | uuidv4 | Chave única de identificação da request utilizada pelo cliente no formato uuid v4. | 36 |
| `pix_transfer_type` * | enumerator | Tipo de transferência Pix. | **manual** |
| `target_account` * | Object | Conta destino - Só deve ser enviada em transferências com `pix_transfer_type` do tipo **manual**. | **[Objeto target_account](#objeto-target_account)** | 10 |
| `transaction_amount` * | number | Valor da transferência. | 10 |
| `pix_message` | string | Mensagem a ser enviada junto à transferência Pix. | 140 |
| `schedule_date`* | string | Data a ser realizada a transação. | 10 |
| `tfa_info`* | Object | Objeto contendo o documento da pessoa aprovadora da conta e a forma de contato. | **[Objeto tfa_info](#objeto-tfa_info)** |
### Objeto target_account
| Campo | Tipo | Descrição | Caracteres |
|---------------------------|------------|-----------------------------------------------------|---------------------------------------------------------|
| `account_branch` * | string | Agência da conta. | 4 |
| `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`* | enumerator | Tipo da conta. | **[Enumerador account_type](#enumerador-account_type)** |
| `ispb` * | string | Base no CNPJ da instituição financeira (8 dígitos). | 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 |
**Qr Code**
## Autenticação via Email e SMS
Request Body: Transferência por Qr Code com TFA por SMS ou Email
```json
{
"request_control_key": "b6804f32-101e-4702-8fbc-c2dbc4c2caec",
"pix_transfer_type": "static_qr_code",
"transaction_amount": 500.65,
"end_to_end_id": "E73856642202309201429bZKfklNlbwu",
"receiver_conciliation_id": "REC00000000000000000000009459463343",
"target_pix_key": "target_pix_key@email.com",
"pix_message": "Ola Mundo",
"tfa_info": {
"approver_document_number": "98765432100",
"contact_type": "email"
}
}
```
## Autenticação via Dispositivo
Além das formas já existentes de autenticação via **sms** e **email**, é possível autenticar a transação utilizando um dispositivo [previamente cadastrado](/documentation/baas/dispositivo/create/solicitacao_cadastro_dispositivo). Nesse caso, o `session_id` deve ser obtido na **Device Scan** e enviado no `tfa_info`.
Request Body: Transferência por Qr Code com TFA por Dispositivo
```json
{
"request_control_key": "b6804f32-101e-4702-8fbc-c2dbc4c2caec",
"pix_transfer_type": "static_qr_code",
"transaction_amount": 500.65,
"end_to_end_id": "E73856642202309201429bZKfklNlbwu",
"receiver_conciliation_id": "REC00000000000000000000009459463343",
"target_pix_key": "target_pix_key@email.com",
"pix_message": "Ola Mundo",
"tfa_info": {
"approver_document_number": "98765432100",
"session_id": "b2f18d3a-67c2-4a7f-98e5-1d3f5c6b8a72",
"contact_type": "device"
}
}
```
### Body Params
| Campo | Tipo | Descrição | Caracteres |
|----------------------------|------------|---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|-------------------------------------------|
| `request_control_key`* | uuidv4 | Chave única de identificação da request utilizada pelo cliente no formato uuid v4. | 36 |
| `pix_transfer_type`* | enumerator | Tipo de transferência Pix. | **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 transferência. | 10 |
| `end_to_end_id`* | string | Chave de idempotência de uma transação Pix dentro do SPI (Sistema de Pagamento Instantâneo). Esta chave é retornada na consulta de chave Pix. Só deve ser enviado se o `pix_transfer_type` for **key**, **static_qr_code** ou **static_qr_code**. | 32 |
| `pix_message` | string | Mensagem a ser enviada junto à transferência Pix. | 140 |
| `tfa_info`* | Object | Objeto contendo o documento da pessoa aprovadora da conta e a forma de contato. | **[Objeto tfa_info](#objeto-tfa_info)** |
:::info Aviso
O `end_to_end_id` é retornado ao [decodificar o QR Code Pix](/documentation/pix/decodificar_qr_code), utilizando a URI
do Pix Copia e Cola.
:::
### Objeto tfa_info
| Campo | Tipo | Descrição | Caracteres |
|-----------------------------|--------|----------------------------------------------------------------------------------------------------------------------------------|------------|
| `approver_document_number`* | string | Número de documento da pessoa aprovadora da conta. | 11 |
| `session_id` | string | Chave única de identificação da sessão do dispositivo no formato UUID v4 (obrigatório para TFA via dispositivo). | 36 |
| `contact_type`* | string | Forma de contato com a pessoa aprovadora da conta, podendo ser **sms**, **email** ou **device** | |
:::danger Aviso
O `end_to_end_id` da consulta deve ter sido feito em nome da conta 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 a transferência tenha sido bem
sucedida ou não.
:::
## Response
STATUS 201
Response Body: Agendamento Criado
```json
{
"request_control_key": "b6804f32-101e-4702-8fbc-c2dbc4c2caec",
"schedule_key": "f64b3fa7-d09d-4927-ad4f-b966df9fb153",
"schedule_status": "pending_2fa_approval",
"schedule_date": "2024-12-31",
"created_at": "2023-03-13T19:00:28.440Z"
}
```
STATUS 4xx
Response Body: Error
```json
{
"title": "titulo",
"description": "description in English",
"translation": "descrição em portugues",
"code": "codigo",
"extra_fields": {}
}
```
| Código HTTP
`status` | Código QI
`code` | Título
`title` | Descrição (eng)
`description` | Descrição (ptbr)
`translation` |
|--------------------------|----------------------|-----------------------------------------------------|---------------------------------------------------------------------------------------------------------------------------|-----------------------------------------------------------------------------------------------------------------------------------|
| 400 | QIT000001 | Bad Request | schema error description | Schema Inválido |
| 404 | PSC000001 | Account not Found | Account was not found | Conta não encontrada |
| 406 | PSC000002 | Invalid Uuid | key was not accepted for not being a valid uuid v4 string | key não foi aceito por não ser uma palavra uuid v4 válida |
| 400 | PSC000003 | Bad Request | pix_message can not be longer than 140 characters | pix_message não pode ser maior que 140 caracteres |
| 400 | PSC000004 | Bad Request | Emoji not allowed in pix message | Emoji não é permitido na mensagem pix |
| 406 | PSC000005 | Invalid Transaction Amount | Transaction amount of transaction_amount is not valid. It must be a positive value with at maximum 2 decimal places | O valor de transação transaction_amount não é válido. Deve ser um valor positivo com no máximo duas casas decimais |
| 406 | PSC000006 | Invalid end_to_end_id | The end_to_end_id sent end_to_end_id is not valid | O end_to_end_id enviado end_to_end_id não é válido |
| 400 | PSC000007 | Invalid date format | Dates must be sent using format YYYY-MM-DD | Datas devem ser enviadas no formato YYYY-MM-DD |
| 400 | PSC000008 | Invalid Schedule Date | Schedule date must be after current date for UTC-3 | Data de agendamento deve ser após a data atual em UTC-3 |
| 400 | PSC000009 | Account is Closed | Account is closed | Conta está fechada |
| 400 | PSC000010 | Account is Blocked | Account is blocked | Conta está bloqueada |
| 422 | PSC000011 | Invalid Account Type | Pix is not yet implemented for non-checking or non-escrow account types | Transações Pix não estão implementadas para conta que não sejam escrow ou livres |
| 403 | PSC000012 | User is not allowed to do this transaction | User is not allowed to do this transaction | Usuário não tem autorização para fazer essa transação |
| 400 | PSC000013 | Bad Request | For Manual Pix Transfer Type a target account must be provided | Para transação pix do tipo manual, uma conta destino deve ser fornecida |
| 404 | PSC000014 | Inquiry Not Found | Pix key inquiry was not found | Pesquisa de chave pix não encontrada |
| 400 | PSC000015 | Bad Request | Pix key sent does match inquiry pix key. Verify if end_to_end_id sent is correct | Chave Pix enviada não condiz com consulta. Verifique se end_to_end_id enviado está correto |
| 404 | PSC000016 | Account not found | Nonexistent account in destination financial institution | Conta inexistente na instituição financeira de destino |
| 400 | PSC000017 | Target Account and Source Account must be different | Target Account must not be the same as Source Account | A conta de destino não pode ser a mesma da conta de origem |
| 409 | PSC000018 | Bad Request | request_control_key request_control_key already in use | request_control_key request_control_key já utilizada |
| 400 | PSC000019 | Invalid Target | Account does not have permission to transfer to the given target account | A conta não possui permissão para realizar transferências para a conta enviada |
| 404 | PSC000020 | Decode Inquiry Not Found | QR Code decode inquiry not found | Pesquisa e decodificação de QR code não encontrada |
| 400 | PSC000021 | Bad Request | Receiver Conciliation Id sent does match decode inquiry receiver_conciliation_id. Verify if end_to_end_id sent is correct | Identificador de transação enviado não condiz com consulta. Verifique se end_to_end_id enviado está correto |
| 400 | PSC000022 | Bad Request | Dynamic Instant QR codes cannot be scheduled for payment | Pagamentos de vencimento instantâneo não podem ter pagamento agendado |
| 400 | PSC000023 | Bad Request | Schedule Date sent is after max payment date for target qr code | Data de agendamento enviada é após a data máxima de pagamento para o qr code enviado |
| 400 | PSC000024 | Bad Request | Pix transfer type sent does match decode inquiry qr code type. Verify if end_to_end_id sent is correct | Tipo de transação pix enviado enviado não condiz com tipo de qr code da consulta. Verifique se end_to_end_id enviado está correto |
| 400 | PSC000046 | tfa_info is required | Client must send object tfa_info | Cliente deve enviar objeto tfa_info |
| 403 | PSC000047 | No approver permission | Given document number does not belong to an approver for this account | Número de documento enviado não pertence a um aprovador da conta |
| 400 | PSC000048 | Error occurred while sending token | An unexpected error occurred while sending token | Um erro inesperado ocorreu ao tentar enviar token |
---
# Solicitar reenvio de token para um agendamento
URL: /documentation/baas/pix/agendamento/solicitacao_de_reenvio_de_token_para_agendamento_2fa
Um novo token será gerado e enviado para o aprovador do agendamento pix. Caso o número limite de tentativas de validação
do token tenha sido excedida, não será permitido o reenvio.
## Request
ENDPOINT /account/ ACCOUNT_KEY /pix_schedule/ SCHEDULE_KEY /resend_token
MÉTODO PATCH
### Path Params
| Campo | Tipo | Descrição | Caracteres |
|----------------|--------|----------------------------------------------|------------|
| `account_key` | uuidv4 | Chave única de identificação da conta. | 36 |
| `schedule_key` | uuidv4 | Chave única de identificação do agendamento. | 36 |
### Body Params
| Campo | Tipo | Descrição | Caracteres |
|----------------|------------|-----------------------------------------|---------------------------------------------------------|
| `contact_type` | enumerator | Forma de envio do token de autenticação | **[Enumerador contact_type](#enumerador-contact_type)** |
:::info Informação
Caso não seja enviado um `contact_type`, o token será enviado da forma solicitada originalmente.
:::
| Enumerador | Descrição |
|------------|---------------------------------------------------|
| **sms** | Envio por Mensagem de Texto para telefone celular |
| **email** | Envio por correio eletrônico |
## Response
STATUS 202
Response Body: Transação Solicitada
```json
{
"request_control_key": "b6804f32-101e-4702-8fbc-c2dbc4c2caec",
"schedule_key": "f64b3fa7-d09d-4927-ad4f-b966df9fb153",
"schedule_status": "pending_2fa_approval",
"schedule_date": "2024-12-31",
"created_at": "2023-03-13T19:00:28.440Z"
}
```
STATUS 4xx
Response Body: Transferência Rejeitada
```json
{
"title": "titulo",
"description": "description in English",
"translation": "descrição em portugues",
"code": "codigo",
"extra_fields": {}
}
```
| Código HTTP
`status` | Código QI
`code` | Título
`title` | Descrição (eng)
`description` | Descrição (ptbr)
`translation` |
|--------------------------|----------------------|----------------------------------------------|-------------------------------------------------------------------------|----------------------------------------------------------------------------|
| 400 | QIT000001 | Bad Request | schema error description | Schema Inválido |
| 404 | PSC000001 | Account not Found | Account was not found | Conta não encontrada |
| 403 | PSC000012 | User is not allowed to do this transaction | User is not allowed to do this transaction | Usuário não tem autorização para fazer essa transação |
| 404 | PSC000025 | PixSchedule not Found | PixSchedule was not found | PixSchedule não encontrada |
| 400 | PSC000049 | Number of token validation attempts exceeded | The maximum number of failed token validation attempts has been reached | Número máximo de tentativas de validação de token atingida |
| 400 | PSC000052 | Incorrect Token | Token sent does not match expected | Token enviado não condiz com o esperado |
| 400 | PSC000053 | Error Sending Token | An error occurred while resending token and its being investigated | Um erro ocorreu ao reenviar token e está sendo investigado |
| 400 | PSC000054 | Invalid Schedule Date | Schedule must be approved before the scheduled date | Agendamento deve ser aprovado em data anterior à programada para transação |
| 400 | PSC000055 | Bad Request | Schedule cannot be approved in current status | Agendamento pix não pode ser aprovado no status atual |
---
# Webhook de conclusão de Agendamento Pix
URL: /documentation/baas/pix/agendamento/webhook_de_conclusao_de_agendamento
Após a conclusão de um agendamento Pix, um webhook será enviado ao parceiro integrador com o resultado.
:::danger Atenção!
Os webhooks da QI Tech não devem ser mapeados de forma restrita. Campos adicionais podem ser incluídos aos payloads dos
webhooks retornados em nossas APIs.
:::
### Webhook Request Body
Request Body: Agendamento Concluído e Enviado
```json
{
"webhook_type": "baas.pix_schedule.completed",
"webhook_datetime": "2021-10-22T20:30:23.459Z",
"data": {
"created_at": "2024-07-10T16:17:28Z",
"pix_message": null,
"rejection_info": null,
"rejection_reason": null,
"request_control_key": "b8eb663e-10fe-4729-9db5-8f8c93de5001",
"schedule_date": "2024-07-10",
"schedule_key": "0c9091ab-079b-4a43-8b3d-d4ba36a23883",
"schedule_status": "sent",
"schedule_transfers": [
{
"created_at": "2024-07-10T16:19:33Z",
"end_to_end_id": "E3240250220240710161922sSHNf8BjI",
"pix_transfer_key": "427b70cd-73b0-45d1-bb4a-97f50f605022",
"pix_transfer_status": "sent"
}
],
"target_account": {
"account_branch": "0001",
"account_digit": "8",
"account_number": "1234567",
"account_type": "checking_account",
"ispb": "99999004",
"owner_document_number": "***91111***",
"owner_name": "Conta manual geral",
"owner_person_type": "natural",
"pix_key": null,
"receiver_conciliation_id": null
},
"transaction_amount": 2.0,
"updated_at": "2024-07-10T16:19:38Z"
}
}
```
Request Body: Agendamento Concluído e Rejeitado
```json
{
"created_at": "2024-07-11T16:03:54Z",
"pix_message": null,
"rejection_info": {
"error_code": "PSC000030",
"error_description": "The maximum amount of pix transfer attempts has been reached",
"error_translation": "A maxima quantidade de retentativas de transacao pix foi atingida",
"rejection_reason": "max_tries_exceeded"
},
"rejection_reason": null,
"request_control_key": "b8eb663e-10fe-4729-9db5-8f8c93de0008",
"schedule_date": "2024-07-11",
"schedule_key": "8b262d82-3fc6-40f0-bfe5-bf18556ededb",
"schedule_status": "rejected",
"schedule_transfers": [
{
"created_at": "2024-07-11T16:04:21Z",
"end_to_end_id": "E32402502202407111604ffoPVrGebI0",
"pix_transfer_key": "c2c4e064-e684-450b-add5-07fb1efe8991",
"pix_transfer_status": "rejected"
},
{
"created_at": "2024-07-11T16:08:33Z",
"end_to_end_id": "E32402502202407111608TQ3C4vRPRPk",
"pix_transfer_key": "c30254db-86b2-4d8a-be01-29fa0d93ae92",
"pix_transfer_status": "rejected"
},
{
"created_at": "2024-07-11T16:09:20Z",
"end_to_end_id": "E32402502202407111609zSUQQOvmMV6",
"pix_transfer_key": "1a329248-fc39-4b49-9b95-8f1c1bb10c8b",
"pix_transfer_status": "rejected"
}
],
"target_account": {
"account_branch": "0001",
"account_digit": "8",
"account_number": "1234567",
"account_type": "checking_account",
"ispb": "99999004",
"owner_document_number": "***91111***",
"owner_name": "Conta manual geral",
"owner_person_type": "natural",
"pix_key": null,
"receiver_conciliation_id": null
},
"transaction_amount": 2.0,
"updated_at": "2024-07-11T16:09:21Z"
}
```
### Webhook Body Param
| 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 |
| `transaction_amount` | number | Valor da transferencia | 10 |
| `target_account` | object | Conta destino do agendamento | **[Objeto target_account](#objeto-target_account)** |
| `schedule_transfers` | array | Lista de tentativas de transferências realizadas pelo agendamento | lista de **[Objeto schedule_transfer](#schedule-transfer-object)** |
| `schedule_status` | string | Status do agendamento | **[Enumerador schedule_status](#pix-schedule-status)** |
| `schedule_key` | string | Chave única de identificação do agendamento | 36 |
| `schedule_date` | string | Data a ser realizada a transação. | 10 |
| `request_control_key` | uuidv4 | Chave única de identificação da request utilizada pelo cliente no formato uuid v4. | 36 | |
| `rejection_info` | object | Objeto com informaçôes sobre o evento de rejeição | |
| `rejection_reason` | string | Motivo da rejeição | **[Enumeradores rejection_reason](#enumeradores-rejection_reason)** |
| `pix_message` | string | Mensagem a ser enviada junto à transferência Pix | 140 |
| `updated_at` | string | Data e hora da última atualização do agendamento. | 20 |
| `created_at` | string | Data e hora de criação do agendamento. | 20 |
## Pix Schedule Status
| Enumerador | Descrição |
|----------------------------|------------------------------------------------------------------------------------------------|
| **scheduled** | Transação agendada |
| **sent** | Agendamento concluído e enviado com sucesso. Estado final |
| **rejected** | Agendamento rejeitado durante criação ou execução. Estado final |
| **cancelled** | Agendamento cancelado por solicitação de cliente. Estado final |
| **pending_2fa_approval** | Pendente de aprovação por autenticação de dois fatores |
| **pending_creation** | Agendamento em processo de criação (Estado transitório para agendamento em lote) |
| **waiting_batch_approval** | Agendamento criado e vinculado a um lote aguardando aprovação por autenticação de dois fatores |
### Schedule Transfer Object
| Campo | Tipo | Descrição | Caracteres |
|-----------------------|--------|---------------------------------------------------------------------------------------------|---------------------------------------------------------------------|
| `pix_transfer_key` | uuidv4 | Chave única de identificação da transferência Pix no sistema QI. | 36 |
| `end_to_end_id` * | string | Chave de idempotência de uma transação Pix dentro do SPI (Sistema de Pagamento Instantâneo) | 32 |
| `pix_transfer_status` | string | Status da transação. | [Enumeradores pix_transfer_status](#enumerador-pix-transfer-status) | |
| `created_at` | string | Data e hora de criação da transação. | 20 |
### Enumerador Pix Transfer Status
| Enumerador | Descrição |
|--------------|-----------------------------------------------------|
| **sent** | Transação enviada com sucesso. Estado final |
| **rejected** | Transação rejeitada durante execução. Estado final |
| **pending** | Transação pendente de conclusão. Estado Transitório |
### 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 |
| `owner_person_type` | enumerator | Identificador de que o dono da conta enviada é uma pessoa física ou jurídica | **[Enumerador owner_person_type](#enumerador-owner_person_type)** | |
| `owner_name` | string | Nome do titular da conta | 150 |
| `account_type` | enumerator | 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 |
| `pix_key` | string | Chave pix alvo do agendamento | 100 |
### Enumerador owner_person_type
| Enum | Description |
|-------------|-----------------|
| **natural** | Pessoa física |
| **legal** | Pessoa jurídica |
### 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 |
### Enumeradores rejection_reason
| Enumerador | Descrição |
|-----------------------------------------------------|---------------------------------------------------------------------------|
| `target_creation_error` | Erro na criação do agendamento |
| `limit_date_for_approval_surpassed` | Data limite para aprovação ultrapassada |
| `limit_date_for_batch_approval_surpassed` | Data limite para aprovação de lote ultrapassada |
| `max_tries_exceeded` | Número máximo de tentativas excedido |
| `rejection_by_transfer` | Rejeição pela transferência |
| `target_change` | Mudança na conta destino |
| `invalid_pix_key` | Chave Pix inválida |
| `max_token_validation_attempts_exceeded` | Número máximo de tentativas de validação de token excedido |
| `error_sending_token` | Erro ao enviar token |
| `max_token_validation_attempts_exceeded_for_batch` | Número máximo de tentativas de validação de token para lote excedido |
---
# Aprovar Transação em Lote com Autenticação de Dois Fatores
URL: /documentation/baas/pix/batch/aprovar_transacao_em_lote_pix_2fa
## Request
ENDPOINT /account/ ACCOUNT_KEY /pix_transfer_batch/ PIX_TRANSFER_BATCH_KEY /validate_token
MÉTODO PUT
### Path Params
| Campo | Tipo | Descrição | Caracteres |
|--------------------------|--------|--------------------------------------------------------|------------|
| `account_key` | uuidv4 | Chave única de identificação da conta. | 36 |
| `pix_transfer_batch_key` | uuidv4 | Chave única de identificação da transação em lote pix. | 36 |
## Autenticação via Email e SMS
Request Body
```json
{
"token": "329adf"
}
```
## Autenticação via Dispositivo
Para aprovar e finalizar a autenticação via dispositivo, a requisição deve ser enviada com um payload vazio. A validação ocorre internamente, sem necessidade de informações adicionais no corpo da requisição. É importante destacar que este endpoint só deve ser utilizado após a [solicitação de transação em lote](./solicitacao_de_transacao_em_lote_pix_2fa.md) ter sido iniciada.
Request Body
```json
{
}
```
### Body Params
| Campo | Tipo | Descrição | Caracteres |
|---------|--------|----------------------------------------------------------------------------------------------------------------------------------------|------------|
| `token` | string | Código de autenticação enviado ao aprovador de movimentações da conta **obrigatório para TFA via SMS ou e-mail** | 6 |
## Response
STATUS 201
Response Body: Transferência Enviada
```json
{
"request_control_key": "b6804f32-101e-4702-8fbc-c2dbc4c2caec",
"pix_transfer_batch_key": "8cb70dea-9fb0-4a68-9572-99a72849c8d6",
"pix_transfer_batch_status": "approved"
}
```
STATUS 4xx
Response Body: Transferência Rejeitada
```json
{
"title": "titulo",
"description": "description in English",
"translation": "descrição em portugues",
"code": "codigo",
"extra_fields": {
"pix_transfer_batch_data": {
"request_control_key": "b6804f32-101e-4702-8fbc-c2dbc4c2caec",
"pix_transfer_batch_key": "8cb70dea-9fb0-4a68-9572-99a72849c8d6",
"pix_transfer_batch_status": "rejected"
}
}
}
```
STATUS 4xx
Response Body: Error
```json
{
"title": "titulo",
"description": "description in English",
"translation": "descrição em portugues",
"code": "codigo",
"extra_fields": {}
}
```
| Código HTTP
`status` | Código QI
`code` | Título
`title` | Descrição (eng)
`description` | Descrição (ptbr)
`translation` |
|--------------------------|----------------------|----------------------------------------------|----------------------------------------------------------------------------------------------------------|--------------------------------------------------------------------------------------|
| 404 | PXT000178 | Pix Transfer Batch not found | A pix_transfer_batch not found | Uma pix_transfer_batch não encontrada |
| 400 | PXT000180 | Invalid Status | Pix transfer Batch not in pending_2fa_approval status | Pix transfer em lote não está pendente de aprovação por autenticação de dois fatores |
| 400 | PXT000171 | Number of token validation attempts exceeded | The maximum number of failed token validation attempts has been reached | Número máximo de tentativas de validação de token atingida |
| 400 | PXT000172 | Token Expired | Token has expired. Resend token or recreate transferToken has expired. Resend token or recreate transfer | Token expirado. Reenvie token ou recrie a transferência |
| 400 | PXT000173 | Incorrect Token | Token sent does not match expected | Token enviado não condiz com, o esperado |
| 400 | PXT000189 | Token Required | A token is required for SMS or email validation. | Um token é necessário para validação via SMS ou email. |
---
# Introdução a Transação em Lote Pix
URL: /documentation/baas/pix/batch/introducao_a_transacao_em_lote_pix
A QI Tech oferece a possibilidade de realizar várias transações pix com uma única chamada. Nesse sistema as transações
são realizadas de forma assíncrona. Caso na chamada inicial seja retornado um **http status 4xx**, nenhuma das
transações será realizada. Após a solicitação, o parceiro integrador receberá um webhook para cada transação informando
o status final da tentativa, podendo ser **rejected** ou **sent**.
## Autenticação de Dois Fatores
Assim como em transações pix, parceiros integradores com configuração de autenticação de dois fatores devem enviar o
objeto `tfa_info` com as informações de contato e envio de token.
---
# Listar Transações de um lote de uma conta
URL: /documentation/baas/pix/batch/listar_transacoes_de_um_lote_de_transacoes_pix
## Request
ENDPOINT /account/ ACCOUNT_KEY /pix_transfer_batch/ PIX_TRANSFER_BATCH_KEY /pix_transfers
MÉTODO GET
### Path Params
| Campo | Tipo | Descrição | Caracteres |
|--------------------------|--------|----------------------------------------------------|------------|
| `account_key` | uuidv4 | Chave única de identificação da conta. | 36 |
| `pix_transfer_batch_key` | uuidv4 | Chave única de identificação da transação em lote. | 36 |
### Query Params
| Campo | Tipo | Descrição | Caracteres |
|-----------------------------|---------|-------------------------------------------------------------------------|-------------------------------------------------------------------|
| `request_control_key` | uuidv4 | Chave única de identificação da request utilizada pelo cliente. | 36 |
| `pix_transfer_batch_status` | string | Status da transação Pix. | [Enumerador pix_transfer_status](#enumerador-pix_transfer_status) |
| `page` | integer | Número da página requisitada. 1 por padrão | |
| `page_size` | integer | Tamanho da página requisitada na consulta. 30 por padrão e valor máximo | Valor máximo de 30 |
### Enumerador pix_transfer_status
| Enumerador | Descrição |
|--------------------------|----------------------------------------------------------|
| **sent** | Transferência Pix realizada com sucesso. |
| **pending** | Transferência Pix pendente. |
| **pending_2fa_approval** | Transferência Pix pendente de aprovação por dois fatores |
| **rejected** | Transferência Pix rejeitada. |
### Response
STATUS 200
Response Body
```json
{
"data": [
{
"request_control_key": "b6804f32-101e-4702-8fbc-c2dbc4c2caec",
"pix_transfer_key": "8cb70dea-9fb0-4a68-9572-99a72849c8d6",
"end_to_end_id": "E32402502202405081755SxyT2DDcVwc",
"pix_transfer_status": "sent",
"created_at": "2021-10-22T20:30:23.459Z"
},
{
"request_control_key": "697c07c3-5398-48d2-a418-853323f85f97",
"pix_transfer_key": "e95eabdb-4520-4c3d-a76f-99cb5b64724b",
"end_to_end_id": "E32402502202405081755SxyT14Dtvwa",
"pix_transfer_status": "sent",
"created_at": "2021-10-22T20:30:23.459Z"
},
{
"request_control_key": "ca35c526-b5a0-40d7-8c56-8566c77a34f4",
"pix_transfer_key": "58d2fa9e-42ec-4779-b2fc-14ec98cbdca8",
"end_to_end_id": "E32402502202405081755SsbT7DDcVwb",
"pix_transfer_status": "rejected",
"created_at": "2021-10-22T20:30:23.459Z"
}
],
"pagination": {
"current_page": 1,
"rows_per_page": 30
}
}
```
---
# Listar Transações em Lote de uma conta
URL: /documentation/baas/pix/batch/listar_transacoes_em_lote_pix_de_uma_conta
## Request
ENDPOINT /account/ ACCOUNT_KEY /pix_transfer_batches
MÉTODO GET
### Path Params
| Campo | Tipo | Descrição | Caracteres |
|---------------|--------|----------------------------------------|------------|
| `account_key` | uuidv4 | Chave única de identificação da conta. | 36 |
### Query Params
| Campo | Tipo | Descrição | Caracteres |
|-----------------------|---------|-------------------------------------------------------------------------|--------------------|
| `request_control_key` | uuidv4 | Chave única de identificação da request utilizada pelo cliente. | 36 |
| `date_from` | string | Data inicial. Formato "YYYY-MM-DD" | |
| `date_to` | string | Data final. Formato "YYYY-MM-DD" | |
| `page` | integer | Número da página requisitada. 1 por padrão | |
| `page_size` | integer | Tamanho da página requisitada na consulta. 30 por padrão e valor máximo | Valor máximo de 30 |
### Response
STATUS 200
Response Body
```json
{
"data": [
{
"request_control_key": "b6804f32-101e-4702-8fbc-c2dbc4c2caec",
"pix_transfer_batch_key": "8cb70dea-9fb0-4a68-9572-99a72849c8d6",
"pix_transfer_batch_status": "approved"
},
{
"request_control_key": "939d1503-aa5a-49a6-ae3b-ff84122a6dd3",
"pix_transfer_batch_key": "03cf9181-0eb9-480e-8bb4-66a5a9a6410e",
"pix_transfer_batch_status": "rejected"
},
{
"request_control_key": "43a14f3a-b2af-4a0e-8a74-70af2fca74a9",
"pix_transfer_batch_key": "94ab9fad-9c65-4117-b9c3-a47b1269508f",
"pix_transfer_batch_status": "approved"
}
],
"pagination": {
"current_page": 1,
"next_page": null,
"rows_per_page": 30
}
}
```
# Consultar Transação em Lote
## Request
ENDPOINT /account/ ACCOUNT_KEY /pix_transfer_batch/ PIX_TRANSFER_BATCH_KEY
MÉTODO GET
### Path Params
| Campo | Tipo | Descrição | Caracteres |
|--------------------------|--------|----------------------------------------------------|------------|
| `account_key` | uuidv4 | Chave única de identificação da conta. | 36 |
| `pix_transfer_batch_key` | uuidv4 | Chave única de identificação da transação em lote. | 36 |
### Response
STATUS 200
Response Body
```json
{
"request_control_key": "b6804f32-101e-4702-8fbc-c2dbc4c2caec",
"pix_transfer_batch_key": "8cb70dea-9fb0-4a68-9572-99a72849c8d6",
"pix_transfer_batch_status": "approved"
}
```
---
# Solicitar reenvio de token para uma Transação Pix em Lote
URL: /documentation/baas/pix/batch/solicitacao_de_reenvio_de_token_para_lote
Um novo token será gerado e enviado para o aprovador de movimentação da conta. Caso o número limite de tentativas de
validação do token tenha sido excedida, não será permitido o reenvio.
## Request
ENDPOINT /account/ ACCOUNT_KEY /pix_transfer_batch/ PIX_TRANSFER_BATCH_KEY /resend_token
MÉTODO PATCH
### Path Params
| Campo | Tipo | Descrição | Caracteres |
|----------------------------|--------|----------------------------------------------------|------------|
| `account_key` * | uuidv4 | Chave única de identificação da conta. | 36 |
| `pix_transfer_batch_key` * | uuidv4 | Chave única de identificação da transação em lote. | 36 |
Request Body
```json
{
"contact_type": "sms"
}
```
### Body Params
| Campo | Tipo | Descrição | Caracteres |
|----------------|--------|-------------------------------------------------------------------------------------------|------------|
| `contact_type` | enumerator | Forma de envio do token de autenticação | **[Enumerador contact_type](#enumerador-contact_type)** |
:::info Informação
Caso não seja enviado um `contact_type`, o token será enviado da forma solicitada originalmente.
:::
| Enumerador | Descrição |
|------------|---------------------------------------------------|
| **sms** | Envio por Mensagem de Texto para telefone celular |
| **email** | Envio por correio eletrônico |
## Response
STATUS 202
Response Body: Transação Solicitada
```json
{
"request_control_key": "b6804f32-101e-4702-8fbc-c2dbc4c2caec",
"pix_transfer_batch_key": "8cb70dea-9fb0-4a68-9572-99a72849c8d6",
"pix_transfer_status": "pending_2fa_approval"
}
```
STATUS 4xx
Response Body: Transferê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",
"pix_transfer_batch_key": "8cb70dea-9fb0-4a68-9572-99a72849c8d6",
"pix_transfer_status": "rejected"
}
}
}
```
| Código HTTP
`status` | Código QI
`code` | Título
`title` | Descrição (eng)
`description` | Descrição (ptbr)
`translation` |
|--------------------------|----------------------|----------------------------------------------|----------------------------------------------------------------------------------------------------------|--------------------------------------------------------------------------------------------|
| 400 | QIT000001 | Bad Request | Schema Error | Erro de Schema |
| 404 | PXT000004 | Account not found | Account not found for: \{account_datum\} | Conta não encontrada para: \{account_datum\} |
| 400 | PXT000176 | Error Sending Token | An error occurred while resending token and its being investigated | Um erro ocorreu ao reenviar token e está sendo investigado |
| 404 | PXT000178 | Pix Transfer Batch not found | A pix_transfer_batch not found | Uma pix_transfer_batch não encontrada |
| 400 | PXT000180 | Invalid Status | Pix transfer Batch not in pending_2fa_approval status | Pix transfer em lote não está pendente de aprovação por duṕla autenticação |
| 400 | PXT000171 | Number of token validation attempts exceeded | The maximum number of failed token validation attempts has been reached | Número máximo de tentativas de validação de token atingida |
| 400 | PXT000172 | Token Expired | Token has expired. Resend token or recreate transferToken has expired. Resend token or recreate transfer | Token expirado. Reenvie token ou recrie a transferência |
| 400 | PXT000173 | Incorrect Token | Token sent does not match expected | Token enviado não condiz com, o esperado |
---
# Realizar Transação Pix em Lote
URL: /documentation/baas/pix/batch/solicitacao_de_transacao_em_lote_pix
A QI Tech oferece a possibilidade de realizar várias transações pix com uma única chamada. Nesse sistema as transações
são realizadas de forma assíncrona. Caso na chamada inicial seja retornado um **http status 4xx**, nenhuma das
transações será realizada. Após a solicitação, o parceiro integrador receberá um webhook para cada transação informando
o status final da tentativa, podendo ser **rejected** ou **sent**.
## Request
ENDPOINT /account/ ACCOUNT_KEY /pix_transfer_batch
MÉTODO POST
```json
{
"request_control_key": "6e4fc980-f8a1-4462-b6e2-d8a49f0ac055",
"pix_transfers": [
{
"request_control_key": "b6804f32-101e-4702-8fbc-c2dbc4c2caec",
"pix_transfer_type": "key",
"target_pix_key": "target_pix_key@email.com",
"transaction_amount": 500.65,
"end_to_end_id": "E73856642202309201429bZKfklNlbwu",
"pix_message": "Ola Mundo"
},
{
"request_control_key": "5fb20e2e-78e3-4ca7-bb36-515640ec2e78",
"pix_transfer_type": "manual",
"target_account": {
"account_branch": "0001",
"account_digit": "3",
"account_number": "12345678",
"owner_document_number": "32402502000135",
"owner_name": "Qi Tech",
"account_type": "checking_account",
"ispb": "32402502"
},
"transaction_amount": 500.65,
"pix_message": "Ola Mundo"
},
{
"request_control_key": "10ad6e08-1a4c-403c-8122-178b0acf1dfa",
"pix_transfer_type": "static_qr_code",
"transaction_amount": 500.65,
"end_to_end_id": "E73856642202309201429bZKfklNlbrb",
"receiver_conciliation_id": "REC00000000000000000000009459463343",
"target_pix_key": "target_pix_key@email.com",
"pix_message": "Ola Mundo"
}
]
}
```
## Path Params
| Campo | Tipo | Descrição | Caracteres |
|---------------|--------|----------------------------------------|------------|
| `account_key` | uuidv4 | Chave única de identificação da conta. | 36 |
### Body Params
| Campo | Tipo | Descrição | Caracteres |
|-------------------------|--------|------------------------------------------------------------------------------------|----------------------------------------------------------|
| `request_control_key` * | uuidv4 | Chave única de identificação da request utilizada pelo cliente no formato uuid v4. | 36 |
| `pix_transfers` * | array | Lista de objetos pix_transfer vinculados ao lote. | lista de **[Objeto pix_transfer](#objeto-pix_transfer)** |
### Objeto pix_transfer
| Campo | Tipo | Descrição | Caracteres |
|----------------------------|------------|--------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|-------------------------------------------------------------------|
| `request_control_key` * | uuidv4 | Chave única de identificação da request utilizada pelo cliente no formato uuid v4. | 36 |
| `pix_transfer_type` * | enumerator | Tipo do pix a ser realizado. | **[Enumerador pix_transfer_type](#enumerador-pix_transfer_type)** |
| `target_pix_key` | string | Chave pix da conta a ser enviada a transação. | 100 |
| `target_account` | Object | Conta destino - Só deve ser enviada em transferências com `pix_transfer_type` do tipo **manual**. | **[Objeto target_account](#objeto-target_account)** |
| `receiver_conciliation_id` | string | Identicação de conciliação do recebedor. | 35 |
| `transaction_amount` * | number | Valor da transferência. | 10 |
| `end_to_end_id` | string | Chave de idempotência de uma transação Pix dentro do SPI (Sistema de Pagamento Instantâneo). Esta chave é retornada na consulta de chave Pix. Só deve ser enviado se o `pix_transfer_type` for **key**, **static_qr_code** ou **static_qr_code** | 32 |
| `pix_message` | string | Mensagem a ser enviada junto à transferência Pix. | 140 |
### Objeto target_account
| Campo | Tipo | Descrição | Caracteres |
|---------------------------|------------|-----------------------------------------------------|---------------------------------------------------------|
| `account_branch` * | string | Agência da conta. | 4 |
| `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`* | enumerator | Tipo da conta. | **[Enumerador account_type](#enumerador-account_type)** |
| `ispb` * | string | Base no CNPJ da instituição financeira (8 dígitos). | 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 |
### Enumerador 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) |
## Response
STATUS 201
Response Body: Transferência em lote Aprovada
```json
{
"request_control_key": "b6804f32-101e-4702-8fbc-c2dbc4c2caec",
"pix_transfer_batch_key": "8cb70dea-9fb0-4a68-9572-99a72849c8d6",
"pix_transfer_batch_status": "approved"
}
```
### Enumerador pix_transfer_batch_status
| Enumerador | Descrição |
|--------------------------|----------------------------------------------------------------------|
| **approved** | Transferência em lote aprovada e transações em processo de execução. |
| **rejected** | Transferência em lote rejeitada |
| **pending_2fa_approval** | Transferência em lote pendente de aprovação manual |
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_batch_data": {
"request_control_key": "b6804f32-101e-4702-8fbc-c2dbc4c2caec",
"pix_transfer_batch_key": "8cb70dea-9fb0-4a68-9572-99a72849c8d6",
"pix_transfer_batch_status": "rejected"
}
}
}
```
STATUS 4xx
Response Body: Error
```json
{
"title": "titulo",
"description": "description in English",
"translation": "descrição em portugues",
"code": "codigo",
"extra_fields": {}
}
```
:::info Informação
Os erros anteriormente listados para [transferência Pix](/documentation/baas/pix/realizar_transferencia) são
passiveis de serem retornados por este endpoint.
:::
---
# Realizar Transação Pix em Lote com Autenticação de Dois Fatores
URL: /documentation/baas/pix/batch/solicitacao_de_transacao_em_lote_pix_2fa
A QI Tech oferece a possibilidade de realizar várias transações pix com uma única chamada. Nesse sistema as transações
são realizadas de forma assíncrona. Caso na chamada inicial seja retornado um **http status 4xx**, nenhuma das
transações será realizada. Após a solicitação, o parceiro integrador receberá um webhook para cada transação informando
o status final da tentativa, podendo ser **rejected** ou **sent**.
Neste tipo de transação, é necessário a confirmação do pagamento via token enviado à pessoa com poderes de aprovação de
movimentação na conta credora.
A solicitação de transação Pix por parceiros integradores configurados para a utilização de autenticação de dois fatores
é realizada de forma similar ao descrito
em [realizar transação pix em lote](/documentation/baas/pix/batch/solicitacao_de_transacao_em_lote_pix). A diferença
ocorre na adição do objeto `tfa_info`, contento informações sobre o aprovador da transferência e a forma de contato, e o
status de uma solicitação bem sucedida que será sempre **pending_2fa_approval**.
O evento de notificação para o envio de `token` ao aprovador é **baas.token_validation.pix_transfer.batch**. É
possível [personalizar](/documentation/notificacoes/template) a mensagem enviada.
## Request
ENDPOINT /account/ ACCOUNT_KEY /pix_transfer_batch
MÉTODO POST
## Autenticação via Email e SMS
Request Body: Transferência em Lote com TFA por SMS ou Email
```json
{
"request_control_key": "6e4fc980-f8a1-4462-b6e2-d8a49f0ac055",
"tfa_info": {
"approver_document_number": "98765432100",
"contact_type": "email"
},
"pix_transfers": [
{
"request_control_key": "b6804f32-101e-4702-8fbc-c2dbc4c2caec",
"pix_transfer_type": "key",
"target_pix_key": "target_pix_key@email.com",
"transaction_amount": 500.65,
"end_to_end_id": "E73856642202309201429bZKfklNlbwu",
"pix_message": "Ola Mundo"
},
{
"request_control_key": "5fb20e2e-78e3-4ca7-bb36-515640ec2e78",
"pix_transfer_type": "manual",
"target_account": {
"account_branch": "0001",
"account_digit": "3",
"account_number": "12345678",
"owner_document_number": "32402502000135",
"owner_name": "Qi Tech",
"account_type": "checking_account",
"ispb": "32402502"
},
"transaction_amount": 500.65,
"pix_message": "Ola Mundo"
},
{
"request_control_key": "10ad6e08-1a4c-403c-8122-178b0acf1dfa",
"pix_transfer_type": "static_qr_code",
"transaction_amount": 500.65,
"end_to_end_id": "E73856642202309201429bZKfklNlbrb",
"receiver_conciliation_id": "REC00000000000000000000009459463343",
"target_pix_key": "target_pix_key@email.com",
"pix_message": "Ola Mundo"
}
]
}
```
## Autenticação via Dispositivo
Além das formas já existentes de autenticação via **sms** e **email**, é possível autenticar a transação utilizando um dispositivo [previamente cadastrado](/documentation/baas/dispositivo/create/solicitacao_cadastro_dispositivo). Nesse caso, o `session_id` deve ser obtido na **Device Scan** e enviado no `tfa_info`.
Request Body: Transferência em Lote com TFA por Dispositivo
```json
{
"request_control_key": "6e4fc980-f8a1-4462-b6e2-d8a49f0ac055",
"tfa_info": {
"approver_document_number": "98765432100",
"session_id": "b2f18d3a-67c2-4a7f-98e5-1d3f5c6b8a72",
"contact_type": "device"
},
"pix_transfers": [
{
"request_control_key": "b6804f32-101e-4702-8fbc-c2dbc4c2caec",
"pix_transfer_type": "key",
"target_pix_key": "target_pix_key@email.com",
"transaction_amount": 500.65,
"end_to_end_id": "E73856642202309201429bZKfklNlbwu",
"pix_message": "Ola Mundo"
},
{
"request_control_key": "5fb20e2e-78e3-4ca7-bb36-515640ec2e78",
"pix_transfer_type": "manual",
"target_account": {
"account_branch": "0001",
"account_digit": "3",
"account_number": "12345678",
"owner_document_number": "32402502000135",
"owner_name": "Qi Tech",
"account_type": "checking_account",
"ispb": "32402502"
},
"transaction_amount": 500.65,
"pix_message": "Ola Mundo"
},
{
"request_control_key": "10ad6e08-1a4c-403c-8122-178b0acf1dfa",
"pix_transfer_type": "static_qr_code",
"transaction_amount": 500.65,
"end_to_end_id": "E73856642202309201429bZKfklNlbrb",
"receiver_conciliation_id": "REC00000000000000000000009459463343",
"target_pix_key": "target_pix_key@email.com",
"pix_message": "Ola Mundo"
}
]
}
```
## Path Params
| Campo | Tipo | Descrição | Caracteres |
|---------------|--------|----------------------------------------|------------|
| `account_key` | uuidv4 | Chave única de identificação da conta. | 36 |
### Body Params
| Campo | Tipo | Descrição | Caracteres |
|-------------------------|--------|------------------------------------------------------------------------------------|----------------------------------------------------------|
| `request_control_key` * | uuidv4 | Chave única de identificação da request utilizada pelo cliente no formato uuid v4. | 36 |
| `pix_transfers` * | array | Lista de objetos pix_transfer vinculados ao lote. | lista de **[Objeto pix_transfer](#objeto-pix_transfer)** |
| `tfa_info`* | Object | Objeto contendo o documento da pessoa aprovadora da conta e a forma de contato. | **[Objeto tfa_info](#objeto-tfa_info)** |
### Objeto tfa_info
| Campo | Tipo | Descrição | Caracteres |
|-----------------------------|--------|----------------------------------------------------------------------------------------------------------------------------------|------------|
| `approver_document_number`* | string | Número de documento da pessoa aprovadora da conta. | 11 |
| `session_id` | string | Chave única de identificação da sessão do dispositivo no formato UUID v4 (obrigatório para TFA via dispositivo). | 36 |
| `contact_type`* | string | Forma de contato com a pessoa aprovadora da conta, podendo ser **sms**, **email** ou **device** | |
### Objeto pix_transfer
| Campo | Tipo | Descrição | Caracteres |
|----------------------------|------------|--------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|-------------------------------------------------------------------|
| `request_control_key` * | uuidv4 | Chave única de identificação da request utilizada pelo cliente no formato uuid v4. | 36 |
| `pix_transfer_type` * | enumerator | Tipo do pix a ser realizado. | **[Enumerador pix_transfer_type](#enumerador-pix_transfer_type)** |
| `target_pix_key` | string | Chave pix da conta a ser enviada a transação. | 100 |
| `target_account` | Object | Conta destino - Só deve ser enviada em transferências com `pix_transfer_type` do tipo **manual**. | **[Objeto target_account](#objeto-target_account)** | 10 |
| `receiver_conciliation_id` | string | Identicação de conciliação do recebedor. | 35 |
| `transaction_amount` * | number | Valor da transferência. | 10 |
| `end_to_end_id` | string | Chave de idempotência de uma transação Pix dentro do SPI (Sistema de Pagamento Instantâneo). Esta chave é retornada na consulta de chave Pix. Só deve ser enviado se o `pix_transfer_type` for **key**, **static_qr_code** ou **static_qr_code** | 32 |
| `pix_message` | string | Mensagem a ser enviada junto à transferência Pix. | 140 |
### Objeto target_account
| Campo | Tipo | Descrição | Caracteres |
|---------------------------|------------|-----------------------------------------------------|---------------------------------------------------------|
| `account_branch` * | string | Agência da conta. | 4 |
| `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`* | enumerator | Tipo da conta. | **[Enumerador account_type](#enumerador-account_type)** |
| `ispb` * | string | Base no CNPJ da instituição financeira (8 dígitos). | 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 |
### Enumerador 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) |
## Response
STATUS 201
Response Body: Transferência em Lote Solicitada
```json
{
"request_control_key": "b6804f32-101e-4702-8fbc-c2dbc4c2caec",
"pix_transfer_batch_key": "8cb70dea-9fb0-4a68-9572-99a72849c8d6",
"pix_transfer_batch_status": "pending_2fa_approval"
}
```
### Enumerador pix_transfer_batch_status
| Enumerador | Descrição |
|--------------------------|----------------------------------------------------------------------------|
| **approved** | Transferência em lote aprovada e transações em processo de execução. |
| **rejected** | Transferência em lote rejeitada |
| **pending_2fa_approval** | Agendamento em lote pendente de aprovação por autenticação de dois fatores |
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_batch_data": {
"request_control_key": "b6804f32-101e-4702-8fbc-c2dbc4c2caec",
"pix_transfer_batch_key": "8cb70dea-9fb0-4a68-9572-99a72849c8d6",
"pix_transfer_batch_status": "rejected"
}
}
}
```
STATUS 4xx
Response Body: Error
```json
{
"title": "titulo",
"description": "description in English",
"translation": "descrição em portugues",
"code": "codigo",
"extra_fields": {}
}
```
:::info Informação
Os erros anteriormente listados para [transferência Pix](/documentation/baas/pix/realizar_transferencia) são
passiveis de serem retornados por este endpoint além dos erros listados abaixo.
:::
| Código HTTP
`status` | Código QI
`code` | Título
`title` | Descrição (eng)
`description` | Descrição (ptbr)
`translation` |
|--------------------------|----------------------|------------------------------------|-----------------------------------------------------------------------|------------------------------------------------------------------|
| 400 | PXT000168 | No approver permission | Given document number does not belong to an approver for this account | Número de documento enviado não pertence a um aprovador da conta |
| 400 | PXT000169 | tfa_info is required | Client must send object tfa_info | Cliente deve enviar objeto tfa_info |
| 400 | PXT000170 | Error occurred while sending token | An unexpected error occurred while sending token | Um erro inexperado ocorreu ao tentar enviar token |
---
# Consulta de Dados de Chave Pix no Banco Central
URL: /documentation/baas/pix/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 |
|-------------------|--------|------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|------------|
| `account_key` * | uuidv4 | Chave única de identificação da conta. | 36 |
| `document_number` | string | CPF/CNPJ do titular da Chave Pix. Ao passar este parâmetro o campo `is_pix_key_owner` será retornado com um valor booleano identificando se o CPF/CNPJ informado é igual ao do titular da Chave Pix. | 14 ou 11 |
:::info Utilização de tokens de consulta
Para que o token de consulta de chave pix seja cobrado da pessoa titular da conta, é obrigatório que o `account_key`
seja enviado.
Caso não seja enviado o account_key, o token será cobrado do número de documento do parceiro integrador.
:::
## Response
STATUS 200
Response Body: Chave Ativa
```json
{
"bank_code": "237",
"end_to_end_id": "E3240250220230404185631R0kjZnC6G",
"financial_institution": "BCO BRADESCO S.A.",
"is_pix_key_owner": false,
"ispb": "60746948",
"owner_masked_document_number": "***.141.857-**",
"owner_name": "Teste teste",
"owner_person_type": "legal",
"owner_trading_name": "Teste LTDA.",
"pix_key": "teste@gmail.com"
}
```
| Campo | Tipo | Descrição | Max. Caracteres |
|--------------------------------|---------|-----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|-------------------------------------------------------------------|
| `bank_code` | string | Código do banco registrador da Chave Pix. Pode ser retornado como nulo, para instituições que não possuem código de banco | 3 |
| `end_to_end_id` | string | Indentificador único da consulta da chave Pix no Bacen. Deve ser enviado na transferência Pix para que o token consumido na consulta seja recuperado. | 32 |
| `financial_institution` | string | Nome da instituição financeira registradora da Chave Pix. | 200 |
| `is_pix_key_owner` | boolean | Será retornado um valor boleano, caso o parâmetro `document_number` seja passado na request. Este campo informa se o CPF/CNPJ informado no parâmetro `document_number` é o mesmo do titular da Chave Pix. Será retornado um valor nulo caso o parâmetro `document_number` não seja informado. | - |
| `ispb` | string | ISPB do Participate detentor da Chave Pix. | 8 |
| `owner_masked_document_number` | string | Número de CPF mascarado ou CNPJ do titular da Chave Pix. | 14 |
| `owner_name` | string | Nome do titular da Chave Pix. | 120 |
| `owner_person_type` | enum | Natureza jurídica do titular da Chave Pix. | [Enumeradores Owner Person Type](#enumeradores-owner_person_type) |
| `owner_trading_name` | string | Nome fantasia do titular da Chave Pix (somente para `owner_person_type=legal`). | 100 |
| `pix_key` | string | Chave Pix. | - |
### Enumeradores account_type
| Enumerador | Descrição |
|--------------------|--------------------|
| `payment` | Conta de pagamento |
| `checking` | Conta de corrente |
| `savings` | Conta poupança |
| `saving` | Conta poupança |
| `salary` | Conta salário |
| `saving_account` | Conta poupança |
| `payment_account` | Conta de pagamento |
| `checking_account` | Conta de corrente |
| `salary_account` | Conta salário |
| `escrow` | Conta Vinculada |
:::info
Diferentes enumeradores podem significar o mesmo tipo de conta devido a informação retornada por diferentes
instituições.
:::
### Enumeradroes owner_person_type
| Enumerador | Descrição |
|------------|-----------|
| `natural` | string |
| `legal` | string |
STATUS 4XX
Response Body
```json
{
"title": "titulo",
"description": "description in English",
"translation": "descrição em portugues",
"code": "codigo"
}
```
| Código HTTP | Código QI
`code` | Título
`title` | Descrição (eng)
`Description` | Descrição (ptbr)
`translation` |
|-------------|----------------------|------------------------------|---------------------------------------------------------------------|-------------------------------------------------------------------|
| 404 | PIX000017 | Pix Key Not Found | Pix key \{pix_key\} not found. | A chave pix \{pix_key\} não foi encontrada. |
| 403 | PIX000080 | Not enough permission | The selected agent doesn't have permission to access this resource. | O agente selecionado não tem permissão para acessar este recurso. |
| 429 | PIX000081 | Rate Limit Exceeded | Rate Limit Exceeded | Limite de requisições excedido |
| 404 | PIX000083 | Pix Key not found | Pix Key \{pix_key\} not found for Alias \{alias_key\} | Chave Pix \{pix_key\} não encontrada para o Alias \{alias_key\} |
| 400 | PIX000084 | Only one query param allowed | Only one query param allowed | Somente um parâmetro de consulta é permitido |
---
# Consultar Transferências
URL: /documentation/baas/pix/consultar_transferencias
## Consultar Transação Pix por pix_transfer_key
### Request
ENDPOINT /account/ ACCOUNT_KEY /pix_transfer/ PIX_TRANSFER_KEY / PIX_TRANSFER_DIRECTION
MÉTODO GET
### Path Params
| Campo | Tipo | Descrição | Caracteres |
|----------------------------|------------|-------------------------------------------------------|-----------------------------------------------------------------------------|
| `pix_transfer_direction` * | enumerator | Indicador do sentido da transação (entrada ou saída). | [Enumeradores pix_transfer_direction](#enumeradores-pix_transfer_direction) |
| `account_key` * | uuidv4 | Chave única de identificação da conta QI. | 36 |
| `pix_transfer_key` * | uuidv4 | Chave única de identificação da transferência Pix. | 36 |
### Enumeradores pix_transfer_direction
| Enumerador | Descrição |
|--------------|------------------------------|
| **incoming** | Transferência Pix de entrada |
| **outgoing** | Transferência Pix de saída |
### Response
STATUS 200
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",
"updated_at": "2021-10-22T20:30:23.459Z",
"created_at": "2021-10-22T20:30:23.459Z",
"target_account": {
"account_branch": "0001",
"account_digit": "3",
"account_number": "12345678",
"owner_document_number": "***02502000***",
"owner_person_type": "legal",
"owner_name": "Qi Tech",
"account_type": "checking_account",
"ispb": "32402502",
"financial_institution_name": "QI SCD",
"pix_key": null
},
"receiver_conciliation_id": null,
"pix_transfer_key": "8cb70dea-9fb0-4a68-9572-99a72849c8d6",
"end_to_end_id": "E3240250220211022203051750897529",
"pix_transfer_status": "sent",
"transfer_amount": 126.97,
"fee_amount": 0.0,
"rejection_reason": null,
"reversals": [
{
"end_to_end_id": "D35713491202309182058jlqdBkkHSWU",
"transfer_amount": 0.01,
"reversal_reason": "client_request",
"pix_transfer_status": "received",
"pix_transfer_key": "423866cd-0f3f-4cdd-904b-0d2e33273afd",
"request_control_key": "7c5a1425-73eb-420e-b4fb-0ce3386c7d0a",
"created_at": "2021-10-23T20:30.459Z"
}
]
}
```
Response Body: Transferê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",
"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",
"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": null,
"pix_transfer_key": "8cb70dea-9fb0-4a68-9572-99a72849c8d6",
"account_key": "fc6862c4-2b20-4057-8063-b8809866e494",
"end_to_end_id": "E18236120202308111235s14fddf2801",
"pix_transfer_status": "received",
"receiver_conciliation_id": "745c28c780bc4822bbade86dd875d10b",
"transfer_amount": 126.97,
"fee_amount": 0.0,
"source_account": {
"account_branch": "0001",
"account_digit": "3",
"account_number": "12345678",
"owner_document_number": "***02502000***",
"owner_person_type": "legal",
"owner_name": "Qi Tech",
"account_type": "checking_account",
"ispb": "32402502"
},
"pix_transfer_type": "dynamic_qr_code",
"error_code": null,
"error_description": null,
"error_translation": null,
"error_short_description": null,
"reversals": []
}
```
Response Body: Devolução Recebida (incoming)
```json
{
"request_control_key": null,
"pix_transfer_key": "8cb70dea-9fb0-4a68-9572-99a72849c8d6",
"account_key": "fc6862c4-2b20-4057-8063-b8809866e494",
"end_to_end_id": "E18236120202308111235s14fddf2801",
"pix_transfer_status": "received",
"receiver_conciliation_id": "745c28c780bc4822bbade86dd875d10b",
"transfer_amount": 126.97,
"fee_amount": 0.0,
"source_account": {
"account_branch": "0001",
"account_digit": "3",
"account_number": "12345678",
"owner_document_number": "***02502000***",
"owner_person_type": "legal",
"owner_name": "Qi Tech",
"account_type": "checking_account",
"ispb": "32402502"
},
"pix_transfer_type": "reversal",
"error_code": null,
"error_description": null,
"error_translation": null,
"error_short_description": null,
"reversals": [],
"original_outgoing_pix_transfer": "6e290347-330d-4b3a-8ebb-2ac217ad6eb3"
}
```
Response Body: Transferência Em Análise Manual (incoming)
```json
{
"request_control_key": null,
"pix_transfer_key": "8cb70dea-9fb0-4a68-9572-99a72849c8d6",
"account_key": "fc6862c4-2b20-4057-8063-b8809866e494",
"end_to_end_id": "E18236120202308111235s14fddf2801",
"pix_transfer_status": "in_manual_analysis",
"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",
"error_code": null,
"error_description": null,
"error_translation": null,
"error_short_description": null,
"reversals": []
}
```
Response Body: Transferência Rejeitada Pela Análise (incoming)
```json
{
"request_control_key": null,
"pix_transfer_key": "8cb70dea-9fb0-4a68-9572-99a72849c8d6",
"account_key": "fc6862c4-2b20-4057-8063-b8809866e494",
"end_to_end_id": "E18236120202308111235s14fddf2801",
"pix_transfer_status": "rejected_by_analysis",
"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",
"error_code": "PXT000194",
"error_description": "Incoming pix transfer rejected by manual analysis",
"error_translation": "Transferência de Pix de entrada rejeitada pela análise manual",
"error_short_description": null,
"reversals": []
}
```
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",
"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 |
---
# Listar Transferências de uma Conta
URL: /documentation/baas/pix/listar_transferencias
## Request
ENDPOINT /account/ ACCOUNT_KEY /pix_transfers
MÉTODO GET
### Path Params
| Campo | Tipo | Descrição | Caracteres |
|-----------------|--------|------------------------------------------|------------|
| `account_key` * | uuidv4 | Chave única de identificação da conta QI | 36 |
### Query Params
| Campo | Tipo | Descrição | Caracteres |
|--------------------------|------------|------------------------------------------------------------------------------------------------------------|-----------------------------------------------------------------------------|
| `pix_transfer_direction` | enumerator | Indicador do sentido da transação (entrada ou saída). Caso não seja enviado, **outgoing** será considerado | [Enumeradores pix_transfer_direction](#enumeradores-pix_transfer_direction) |
| `request_control_key` | uuidv4 | Chave única de identificação da request utilizada pelo cliente. | 36 |
| `end_to_end_id` | string | Chave de idempotência de uma transação Pix | 32 |
| `transaction_key` | uuidv4 | Chave de identificação da movimentação na conta | 36 |
| `order_by` | string | "asc" para ordem ascendente ou "desc" para descendente. "asc" por padrão |
| `date_from` | string | Data inicial. Formato "YYYY-MM-DD" | |
| `date_to` | string | Data final. Formato "YYYY-MM-DD" | |
| `page` | integer | Número da página requisitada. 1 por padrão | |
| `page_size` | integer | Tamanho da página requisitada na consulta. 30 por padrão e valor máximo | Valor máximo de 30 |
### Enumeradores pix_transfer_direction
| Enumerador | Descrição |
|--------------|------------------------------|
| **incoming** | Transferência Pix de entrada |
| **outgoing** | Transferência Pix de saída |
## Response
STATUS 201
Response Body
```json
{
"data": [
{
"request_control_key": "6e290347-330d-4b3a-8ebb-2ac217ad6eb3",
"pix_message": "Bom dia",
"pix_transfer_type": "manual",
"account_key": "fc6862c4-2b20-4057-8063-b8809866e494",
"updated_at": "2021-10-22T20:30:23.459Z",
"created_at": "2021-10-22T20:30:23.459Z",
"target_account": {
"account_branch": "0001",
"account_digit": "3",
"account_number": "12345678",
"owner_document_number": "***02502000***",
"owner_person_type": "legal",
"owner_name": "Qi Tech",
"account_type": "checking_account",
"ispb": "32402502",
"financial_institution_name": "QI SCD",
"pix_key": null
},
"receiver_conciliation_id": null,
"pix_transfer_key": "8cb70dea-9fb0-4a68-9572-99a72849c8d6",
"transaction_key": "848d3ff7-4e98-4911-8773-f1d1b48c3068",
"end_to_end_id": "E3240250220211022203051750897529",
"pix_transfer_status": "sent",
"transfer_amount": 126.97,
"fee_amount": 0.0,
"rejection_reason": null,
"reversals": [
{
"end_to_end_id": "D35713491202309182058jlqdBkkHSWU",
"transfer_amount": 0.01,
"reversal_reason": "client_request",
"pix_transfer_status": "received",
"pix_transfer_key": "423866cd-0f3f-4cdd-904b-0d2e33273afd",
"request_control_key": "7c5a1425-73eb-420e-b4fb-0ce3386c7d0a",
"created_at": "2021-10-23T20:30.459Z"
}
]
}
],
"pagination": {
"current_page": 1,
"rows_per_page": 30
}
}
```
Response Body: Error
```json
{
"title": "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 |
---
# Realizar Transação Pix
URL: /documentation/baas/pix/realizar_transferencia
## Request
ENDPOINT /account/ ACCOUNT_KEY /pix_transfer
MÉTODO POST
## Path Params
| Campo | Tipo | Descrição | Caracteres |
|---------------|--------|----------------------------------------|------------|
| `account_key` | uuidv4 | Chave única de identificação da conta. | 36 |
## Transferência por Chave Pix
Request Body: Transferência por Chave Pix
```json
{
"request_control_key": "b6804f32-101e-4702-8fbc-c2dbc4c2caec",
"pix_transfer_type": "key",
"target_pix_key": "target_pix_key@email.com",
"transaction_amount": 500.65,
"end_to_end_id": "E73856642202309201429bZKfklNlbwu",
"pix_message": "Ola Mundo"
}
```
### Body Params
| Campo | Tipo | Descrição | Caracteres |
|-------------------------|------------|--------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|------------|
| `request_control_key` * | uuidv4 | Chave única de identificação da request utilizada pelo cliente no formato uuid v4. | 36 |
| `pix_transfer_type` * | enumerator | 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 transferência. | 10 |
| `end_to_end_id` * | string | Chave de idempotência de uma transação Pix dentro do SPI (Sistema de Pagamento Instantâneo). Esta chave é retornada na consulta de chave Pix. Só deve ser enviado se o `pix_transfer_type` for **key**, **static_qr_code** ou **static_qr_code** | 32 |
| `pix_message` | string | Mensagem a ser enviada junto à transferência Pix. | 140 |
## Transferência Manual - Utilizando os Dados da Conta
Request Body: Transferência Manual
```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` * | uuidv4 | Chave única de identificação da request utilizada pelo cliente no formato uuid v4. | 36 |
| `pix_transfer_type` * | enumerator | Tipo de transferência Pix. | **manual** |
| `target_account` * | Object | Conta destino - Só deve ser enviada em transferências com `pix_transfer_type` do tipo **manual**. | **[Objeto target_account](#objeto-target_account)** | 10 |
| `transaction_amount` * | number | Valor da transferência. | 10 |
| `pix_message` | string | Mensagem a ser enviada junto à transferência Pix. | 140 |
### Objeto target_account
| Campo | Tipo | Descrição | Caracteres |
|---------------------------|------------|-----------------------------------------------------|---------------------------------------------------------|
| `account_branch` * | string | Agência da conta. | 4 |
| `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`* | enumerator | Tipo da conta. | **[Enumerador account_type](#enumerador-account_type)** |
| `ispb` * | string | Base no CNPJ da instituição financeira (8 dígitos). | 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 |
## Transferência por QR Code Pix
Os dados utilizados para realizção de uma transação de pagamento de um QR Code Pix devem ser obtidos através
da [decodificação do QR Code Pix](/documentation/pix/decodificar_qr_code), utilizando a URI do Pix Copia e Cola.
I - O campo “end_to_end_id” deve ser o mesmo valor retornado da decodificação do QR Code Dinâmico.
II - Informar no campo “transaction_amount“ o mesmo valor retornado no campo “qr_code_data.amount” da decodificação do
QR Code Dinâmico;
III - Alterar o campo “pix_transfer_type” para o enumerador correspondente (**static_qr_code** ou **dynamic_qr_code** ), para solicitação do pagamento.
IV - O campo “receiver_conciliation_id” deve ser o mesmo valor retornado da decodificação do QR Code Dinâmico.
Request Body: Transferência por Qr Code
```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` * | uuidv4 | Chave única de identificação da request utilizada pelo cliente no formato uuid v4. | 36 |
| `pix_transfer_type` * | enumerator | Tipo de transferência Pix. | **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 transferência. | 10 |
| `end_to_end_id` * | string | Chave de idempotência de uma transação Pix dentro do SPI (Sistema de Pagamento Instantâneo). Esta chave é retornada na [consulta de chave Pix](/documentation/pix/consultar_chave). Só deve ser enviado se o `pix_transfer_type` for **key**, **static_qr_code** ou **static_qr_code**. | 32 |
| `pix_message` | string | Mensagem a ser enviada junto à transferência Pix. | 140 |
:::danger Aviso
O `end_to_end_id` da consulta deve ter sido feito em nome da conta 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 a transferência tenha sido bem
sucedida ou não.
:::
## Response
STATUS 201
Response Body: Transferência Enviada
```json
{
"request_control_key": "b6804f32-101e-4702-8fbc-c2dbc4c2caec",
"pix_transfer_key": "8cb70dea-9fb0-4a68-9572-99a72849c8d6",
"transaction_key": "848d3ff7-4e98-4911-8773-f1d1b48c3068",
"pix_transfer_status": "sent",
"created_at": "2021-10-22T20:30:23.459Z"
}
```
STATUS 202
Response Body: Transferência Pendente
```json
{
"request_control_key": "b6804f32-101e-4702-8fbc-c2dbc4c2caec",
"pix_transfer_key": "8cb70dea-9fb0-4a68-9572-99a72849c8d6",
"transaction_key": "848d3ff7-4e98-4911-8773-f1d1b48c3068",
"pix_transfer_status": "pending",
"created_at": "2021-10-22T20:30:23.459Z",
"transaction_key": "8ea90347-330d-4b3a-8ebb-2ac217ad6eb3"
}
```
:::info Informação
Caso seja retornado **HTTP Status 202** com o campo `pix_transfer_status` com valor **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](#consultar-transação-pix).
:::
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",
"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
`status` | Código QI
`code` | Título
`title` | Descrição (eng)
`description` | Descrição (ptbr)
`translation` |
|--------------------------|----------------------|----------------------------------------------------|-------------------------------------------------------------------------------------------------------------------------|------------------------------------------------------------------------------------------------------------------------|
| 400 | QIT000001 | Bad Request | Schema Error | Erro de Schema |
| 403 | PIT000001 | User is not allowed to do this transaction | | Usuário não tem autorização para fazer essa transação |
| 400 | PIT000003 | Bad Request | Insufficient account balance for transfer and fee amount. | Saldo de conta insuficiente para a transferência e a taxa. |
| 400 | PIT000004 | Bad Request | Transaction amount is over limit. | O total da transferência é superior ao limite. |
| 400 | PXT000003 | Account is Closed | Account \{account_key\} is closed. | Conta \{account_key\} está fechada. |
| 404 | PXT000004 | Account not found | Account not found for: \{account_datum\} | Conta não encontrada para: \{account_datum\} |
| 400 | PXT000010 | Account is Blocked | Account \{account_key\} is blocked. | Conta \{account_key\} está bloqueada. |
| 404 | PXT000018 | Reversal Original Transfer not Found | Reversal original pix transfer not found | Transferência original da devolução não foi encontrada |
| 400 | PXT000033 | Target Account Must Not Be Source Account | Target Account Must Not Be Source Account | A conta de destino não pode ser a conta de origem |
| 404 | PXT000041 | Not Found | Qr Code not found | Qr Code não encontrado |
| 400 | PXT000048 | Bad Request | Emoji not allowed in pix message. | Emoji não é permitido na mensagem pix. |
| 400 | PXT000053 | Bad Request | QrCode already paid | Qr Code já Pago |
| 400 | PXT000060 | Bad Request | Nonexistent account in destination bank | Conta inexistente no banco de destino |
| 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 | PXT000079 | Bad Request | Insufficient billing account balance for fee. | Saldo de conta de cobrança insuficiente para a taxa. |
| 400 | PXT000083 | Bad Request | Pix rejected | Pix rejeitado |
| 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 | 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 |
| 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 | PXT000109 | Bad Request | request_control_key \{request_control_key\} already in use | request_control_key \{request_control_key\} já utilizada |
| 400 | PXT000115 | 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 |
| 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 | 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\} |
| 403 | PXT000167 | Requester not allowed to access this endpoint | Requester has no permission to perform pix transfers on this endpoint | Requester não possui permissão de realizar transações pix através deste endpoint |
---
# Solicitar a devolução de um Pix recebido
URL: /documentation/baas/pix/solicitar_devolucao
A devolução de um Pix pode ser efetuada em até 90 dias a partir de seu recebimento.
## Request
ENDPOINT /account/ ACCOUNT_KEY /pix_transfer/ PIX_TRANSFER_KEY /reversal
MÉTODO POST
### Path Params
| Campo | Tipo | Descrição | Caracteres |
|----------------------|--------|------------------------------------------------------------------|------------|
| `account_key` * | uuidv4 | Chave única de identificação da conta. | 36 |
| `pix_transfer_key` * | uuidv4 | Chave única de identificação da transferência Pix no sistema QI. | 36 |
Request Body
```json
{
"request_control_key": "303393bf-8f2e-4ff0-b326-ee7ad612e8ca",
"reversal_amount": 147,
"reversal_reason": "client_request",
"reversal_message": "Mensagem Pix da Devolução"
}
```
### Request Body
| Campo | Tipo | Descrição | Caracteres |
|-------------------------|--------|-----------------------------------|---------------------------------------------------------------|
| `request_control_key` * | uuidv4 | Chave de unicidade da requisição. | 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
STATUS 201
Response Body: Reversão Enviada
```json
{
"reversal_status": "sent",
"transaction_amount": 147,
"pix_transfer_key": "cdcf0d25-08a1-46e3-902a-6d7ca75e6c48",
"end_to_end_id": "E32402502202405081755SxyT2DDcVwc",
"request_control_key": "7c5a1425-73eb-420e-b4fb-0ce3386c7d0c",
"created_at": "2021-10-22T20:30:23.459Z"
}
```
STATUS 202
Response Body: Reversão Pendente
```json
{
"reversal_status": "pending",
"transaction_amount": 147,
"pix_transfer_key": "cdcf0d25-08a1-46e3-902a-6d7ca75e6c48",
"end_to_end_id": "E32402502202407112211Id9JbxoaiTf",
"request_control_key": "7c5a1425-73eb-420e-b4fb-0ce3386c7d0c",
"created_at": "2021-10-22T20:30:23.459Z"
}
```
:::info Informação
Caso seja retornado **HTTP Status 202** com o campo `pix_transfer_status` com valor **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](#consultar-transação-pix).
:::
### Response Body
| Campo | Tipo | Descrição | Caracteres |
|-----------------------|------------|---------------------------------------------------------------------------------------------|-----------------------------------------------------------|
| `reversal_status` | enumerator | Enumerador de status da transação de devolução. | [Enumerador reversal_status](#enumerador-reversal_status) |
| `transfer_amount` | number | Valor da transferência de devolução. | 11 |
| `pix_transfer_key` | uuidv4 | Chave da transação pix executada na devolução. | 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` | uuidv4 | Chave única de identificação da request utilizada pelo cliente. | 36 |
| `created_at` | string | Data e hora da devolução. | 10 |
### Enumerador reversal_status
| Enumerador | Descrição |
|--------------|------------------------------------------|
| **sent** | Transferência Pix realizada com sucesso. |
| **pending** | Transferência Pix pendente. |
| **rejected** | Transferência Pix rejeitada. |
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"
}
}
}
```
:::info Informação
Além dos erros anteriormente listados para [transferência Pix](/documentation/baas/pix/realizar_transferencia), a
devolução de um Pix também pode retornar os erros
listados abaixo.
:::
| Código HTTP
`status` | Código QI
`code` | Título
`title` | Descrição (eng)
`description` | Descrição (ptbr)
`translation` |
|--------------------------|----------------------|--------------------------------------|------------------------------------------------------------------------|-------------------------------------------------------------------------------------------|
| 400 | QIT000001 | Bad Request | Schema Error | Erro de Schema |
| 404 | PXT000018 | Reversal Original Transfer not Found | Reversal original pix transfer not found. | Transferência original da devolução não foi encontrada. |
| 400 | PXT000017 | Reversal Too Great | Reversal transfers sum amount surpasses that of original pix transfer. | A soma das transferências de devolução ultrapassam o valor da transferência pix original. |
| 400 | PXT000015 | Reversal date expired | Reversal original transaction is older than 90 days | A data de criação da transação original é mais antiga que 90 dias |
| 400 | PXT0000127 | Invalid Reversal Reason | Reversal reason \{reversal_reason\} is not valid | Razão de reversão \{reversal_reason\} não é válida |
---
# Webhooks
URL: /documentation/baas/pix/webhooks
Uma vez que as transferências ocorrem de forma assíncrona, é de suma importância o mapeamento e o tratamento corretos
dos webhooks enviados.
:::danger Atenção!
Os webhooks da QI Tech não devem ser mapeados de forma restrita.
Campos adicionais podem ser incluídos aos payloads dos webhooks retornados em nossas APIs.
:::
## Webhook para Transações Pendentes
Webhook destinado para atualizar o status das transferências que ficaram pendentes (status 202)
na [requisição](/documentation/baas/pix/realizar_transferencia) de envio do Pix.
### 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 |
| `error_code` | string | Código do erro ocorrido na transação | 20 |
| `error_description` | string | Descrição do erro em inglês | 200 |
| `error_translation` | string | Descrição do erro traduzida para português | 200 |
| `error_short_description` | string | Descrição curta do erro | 100 |
[//]: # (Break here for new page -----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------)
## Webhook para Pix de Entrada
Webhook que servirá para avisar sobre transações Pix que chegaram para uma conta.
### 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",
"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",
"error_code": null,
"error_description": null,
"error_translation": null,
"error_short_description": null,
"created_at": "2021-10-22T20:30:23.459Z",
"reversals": []
}
}
```
Request Body: Pix Em Análise Manual
```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": "in_manual_analysis",
"account_key": "7c5a1425-73eb-420e-b4fb-0ce3386c7d0c",
"receiver_conciliation_id": "745c28c780bc4822bbade86dd875d10b",
"transfer_amount": 126.97,
"fee_amount": 0.0,
"source_account": {
"account_branch": "0001",
"account_digit": "3",
"account_number": "12345678",
"owner_document_number": "***02502000***",
"owner_person_type": "legal",
"owner_name": "Qi Tech",
"account_type": "checking_account",
"ispb": "32402502"
},
"pix_transfer_type": "dynamic_qr_code",
"pix_message": "pix message",
"error_code": null,
"error_description": null,
"error_translation": null,
"error_short_description": null,
"created_at": "2021-10-22T20:30:23.459Z",
"reversals": []
}
}
```
Request Body: Pix Rejeitado Pela Análise
```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": "rejected_by_analysis",
"account_key": "7c5a1425-73eb-420e-b4fb-0ce3386c7d0c",
"receiver_conciliation_id": "745c28c780bc4822bbade86dd875d10b",
"transfer_amount": 126.97,
"fee_amount": 0.0,
"source_account": {
"account_branch": "0001",
"account_digit": "3",
"account_number": "12345678",
"owner_document_number": "***02502000***",
"owner_person_type": "legal",
"owner_name": "Qi Tech",
"account_type": "checking_account",
"ispb": "32402502"
},
"pix_transfer_type": "dynamic_qr_code",
"pix_message": "pix message",
"error_code": "PXT000194",
"error_description": "Incoming pix transfer rejected by manual analysis",
"error_translation": "Transferência de Pix de entrada rejeitada pela análise manual",
"error_short_description": null,
"created_at": "2021-10-22T20:30:23.459Z",
"reversals": []
}
}
```
:::info Bloqueio Cautelar
Ao receber um Pix, o mesmo pode ficar bloqueado cautelarmente. Nesse cenário, nenhum recurso é creditado na conta destino e um webhook com o status `in_manual_analysis` é enviado para o cliente. O Pix passará pelo processo de análise manual em até no máximo 72 horas. Após realizada a análise, a entrada será aceita ou recusada e o Pix de entrada irá para o status `received` (nesse momento o recurso será creditado na conta do cliente) ou `rejected_by_analysis`, respectivamente.
:::
### 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` | enumerator | 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 |
| `pix_transfer_key` | string | Chave única de identificação da transferência Pix | 36 |
| `error_code` | string | Código do erro ocorrido na transação | 20 |
| `error_description` | string | Descrição do erro em inglês | 200 |
| `error_translation` | string | Descrição do erro traduzida para português | 200 |
| `error_short_description` | string | Descrição curta do erro | 100 |
### 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`* | enumerator | 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 |
[//]: # (Break here for new page -----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------)
## Webhook para Devoluções de Pix
Webhook que servirá para avisar sobre devoluções Pix que chegaram para uma conta.
### 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": "D18236120202308111235s14fddf2801",
"pix_transfer_status": "received",
"account_key": "7c5a1425-73eb-420e-b4fb-0ce3386c7d0c",
"receiver_conciliation_id": "745c28c780bc4822bbade86dd875d10b",
"transfer_amount": 126.97,
"fee_amount": 0.0,
"source_account": {
"account_branch": "0001",
"account_digit": "3",
"account_number": "12345678",
"owner_document_number": "***02502000***",
"owner_person_type": "legal",
"owner_name": "Qi Tech",
"account_type": "checking_account",
"ispb": "32402502"
},
"pix_transfer_type": "reversal",
"pix_message": "pix message received",
"error_code": null,
"error_description": null,
"error_translation": null,
"error_short_description": null,
"created_at": "2021-10-22T20:30:23.459Z",
"reversals": [],
"original_outgoing_pix_transfer": "b56862c4-2b20-4057-8063-b8809866e494",
"original_end_to_end_id": "E18236120202308111235s14fddf2801"
}
}
```
### 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` | enumerator | 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 |
| `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 |
| `original_end_to_end_id` | string | End to end da transferência Pix de saída Original | 36 |
| `error_code` | string | Código do erro ocorrido na transação | 20 |
| `error_description` | string | Descrição do erro em inglês | 200 |
| `error_translation` | string | Descrição do erro traduzida para português | 200 |
| `error_short_description` | string | Descrição curta do erro | 100 |
### 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` | enumerator | 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 |
---
# Baixar QR Code Pix dinâmico
URL: /documentation/pix/baixar_qr_code_dinamico
## Request
ENDPOINT /baas/qrcode/dynamic
MÉTODO POST
Request Body
```json
{
"occurrence_type": "write_off",
"qr_code_key": "461d29e6-d2ed-48f7-bc7b-c3143a1e43d2",
"qr_code_type": "dynamic_term"
}
```
### Body Params
| Campo | Tipo | Descrição | Caracteres |
|---|---|---|---|
| `occurrence_type` * | string |Tipo de ocorrencia. payment: Ocorrência do tipo pagamento, registration: Ocorrência do tipo registro, write_off: Ocorrência do tipo cancelamento pelo gerador, bank_written_off: Ocorrência do tipo cancelamento pelo banco. | - |
| `qr_code_type` * | string | Tipo do QR Code dinâmico | - |
| `qr_code_key` * | string | Chave do QR Code devolvida no momento da geração. | uuid |
## Response
STATUS 200
Response Body
```json
{
"qr_code_type": "dynamic_instant",
"amount": null,
"expiration_seconds": null,
"max_payment_days": 180,
"receiver_conciliation_id": "461d29e6d2ed48f7bc7bc3143a1e43d2",
"payer_name": null,
"payer_document_number": null,
"payer_person_type": "natural",
"payer_request": null,
"pix_message": null,
"modality_alteration": false,
"expiration_date": null,
"rebate_amount": null,
"interest_amount": null,
"fine_amount": null,
"paid_amount": null,
"discounts": [],
"additional_data": [],
"origin": "system",
"origin_key": null,
"pix_key": "9de04466-0b02-4263-9c28-9cdc0fb638bb",
"qr_code_key": "461d29e6-d2ed-48f7-bc7b-c3143a1e43d2",
"occurrence_type": "write_off",
"end_to_end_id": null,
"source_account_branch": null,
"source_account_financial_institution": null,
"source_account_ispb": null,
"source_account_number": null,
"source_account_digit": null,
"disable": null,
"qr_code_occurrence_key": "32ec9e60-b630-45fa-a0c7-653fbb30a32a",
"base_64": null,
"image": null
}
```
STATUS 400
Response Body
```json
{
"data": "{\"title\": \"Bad Request\", \"description\": \"Invalid request body.\", \"translation\": \"Corpo da requisição inválido.\", \"extra_fields\": {}, \"code\": \"LEG000069\"}"
}
```
---
# Busca por solicitação de limite Pix
URL: /documentation/pix/busca_por_solicitacao_de_limite_pix
## Request
ENDPOINT /baas/pix/limits_request
MÉTODO GET
### Query String
| Campo | Tipo | Descrição |Caracteres|
|-------------|--------|--------------------------------|---------|
| `account_key` | string | chave de identificação da QIConta | 36
| `request_status` | string | status da solicitação de limite. Status válidos: **"pending_approval"**, **"approved"**, **"rejected"**, **"executed"**. Pode ser enviado em forma de lista, por exemplo: **"pending_approval,approved"**|
| `page` | integer | Número da página pesquisada | - |
| `page_size` | integer | Quantidade de itens por página | - |
## Response
STATUS 200
Response Body
```json
{
"pagination": {
"current_page": 0,
"next_page": 1,
"rows_per_page": 15,
"total_pages": 1,
"total_rows": 4
},
"data": [
{
"account_key": "dc94d45c-11a1-46f1-b19a-a1af9884a3c5",
"amount_limit": 2000,
"created_at": "2023-05-29T11:50:03",
"limit_type": "daily",
"request_key": "155afa76-4e80-4a11-917a-34d48e39325c",
"request_status": "pending_approval",
"routine_key": null
},
{
"account_key": "dc94d45c-11a1-46f1-b19a-a1af9884a3c5",
"amount_limit": 1000,
"created_at": "2023-05-29T11:50:03",
"limit_type": "nightly",
"request_key": "805a457d-307d-46c5-8dce-e98e309a3380",
"request_status": "pending_approval",
"routine_key": null
},
{
"account_key": "dc94d45c-11a1-46f1-b19a-a1af9884a3c5",
"amount_limit": 1500,
"created_at": "2023-05-29T11:50:03",
"limit_type": "self_daily",
"request_key": "7cd413ab-fc78-41e6-ab27-206f69e2e294",
"request_status": "pending_approval",
"routine_key": null
},
{
"account_key": "dc94d45c-11a1-46f1-b19a-a1af9884a3c5",
"amount_limit": 500,
"created_at": "2023-05-29T11:50:03",
"limit_type": "self_nightly",
"request_key": "febe9087-1eba-4169-a63e-29e546aaf874",
"request_status": "pending_approval",
"routine_key": null
}
]
}
```
STATUS 403
Response Body: Usuário não possui credenciais
```json
{
"title": "Unauthorized",
"description": "User is not allowed to do this transaction",
"translation": "Usuário não tem autorização para fazer essa transação",
"code": "PIT000001"
}
```
---
# Busca por uso de limite Pix
URL: /documentation/pix/busca_por_uso_de_limite_pix
## Request
ENDPOINT /baas/pix/limits/ ACCOUNT_KEY /usage
MÉTODO GET
### Path Params
| Campo | Tipo | Descrição |Caracteres|
|-------------|--------|--------------------------------|---------|
| `account_key` | string | chave de identificação da QIConta | 36 |
## Response
STATUS 200
Response Body
```json
{
"daily_amount_limit": "800012.67",
"daily_amount_percentage": null,
"daily_amount_used": "0",
"nightly_amount_limit": "100000.00",
"nightly_amount_percentage": null,
"nightly_amount_used": "0",
"self_daily_amount_limit": "500.03",
"self_daily_amount_percentage": null,
"self_daily_amount_used": "0",
"self_nightly_amount_limit": "100000.00",
"self_nightly_amount_percentage": null,
"self_nightly_amount_used": "0"
}
```
STATUS 403
Response Body: Usuário não possui credenciais
```json
{
"title": "Unauthorized",
"description": "User is not allowed to do this transaction",
"translation": "Usuário não tem autorização para fazer essa transação",
"code": "PIT000001"
}
```
---
# Chaves PIX mockadas em ambiente de sandbox
URL: /documentation/pix/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 | Mock Person Name | 65322181032 | 21837-5 | 4458 | 360305 |
| d6e2d611-6c68-4f84-9be5-962ad2f2bcb6 | random_key | Mock Person Name | 61295118092 | 100091086-1 | 465 | 360305 |
| 61295118092 | cpf | Mock Person Name | 61295118092 | 1300005670-8 | 4289 | 360305 |
| pix03@pix03.com | email | Mock Person Name | 96969879003 | 363214578-8 | 8615 | 360305 |
| +5568911106520 | phone_number | Mock Person Name | 66702118805 | 100071086-1 | 465 | 360305 |
| 5e6ce02a-e0da-4d56-73b8-84f118b4f371 | random_key | Mock Person Name | 52720072800 | 100061086-1 | 465 | 360305 |
| 52720072800 | cpf | Mock Person Name | 52720072800 | 100071076-1 | 465 | 360305 |
| pix10@pix10.com | email | Mock Person Name | 24182533410 | 100071066-1 | 465 | 360305 |
| pix33@pix33.com | email | Mock Person Name | 56151446887 | 96764-6 | 919 | 360305 |
| 88253032978 | cpf | Mock Person Name | 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 | Mock Person Name | 22156083070 | 19413-2 | 8534 | 60701190 |
| 96969879003 | cpf | Mock Person Name | 96969879003 | 22110-1 | 8615 | 60701190 |
| 5e6ce06a-e0da-4d56-93b8-84f118b4f371 | random_key | Mock Person Name | 43135154025 | 57980-4 | 5067 | 60701190 |
| pix11@pix11.com | email | Mock Person Name | 66702118805 | 86091-8 | 3101 | 60701190 |
| 24182533410 | cpf | Mock Person Name | 24182533410 | 20467-1 | 5807 | 60701190 |
| pix07@pix07.com | email | Mock Person Name | 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 | Mock Person Name | 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 | Mock Person Name | 65322181032 | 1017372-2 | 1 | 60746948 |
| pix01@pix01.com | email | Mock Person Name | 65322181032 | 1925255-8 | 3952 | 60746948 |
| pix12@pix12.com | email | Mock Person Name | 11085087824 | 1071659-4 | 427 | 60746948 |
| 5e6ce08a-e0da-4d56-93b8-84f118b4f371 | random_key | Mock Person Name | 66702118805 | 1751795-3 | 6162 | 60746948 |
| +5568911137576 | phone_number | Mock Person Name | 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 | Mock Person Name | 42759960030 | 9206744-2 | 4187 | 90400888 |
| 34175131205 | cpf | Mock Person Name | 34175131205 | 9206744-2 | 4187 | 90400888 |
| 5e6ce05a-e0da-4d56-53b8-74f118b4f371 | random_key | Mock Person Name | 11646288874 | 9206744-2 | 4187 | 90400888 |
| 82104056080 | cpf | Mock Person Name | 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 | Mock Person Name | 22156083070 | 4810813-8 | 1 | 416968 |
| pix13@pix13.com | email | Mock Person Name | 43135154025 | 4830813-8 | 1 | 416968 |
| 66702118805 | cpf | Mock Person Name | 66702118805 | 4820813-8 | 1 | 416968 |
| 5e6ce05a-e0da-4d56-93b7-84f118b4f371 | random_key | Mock Person Name | 24182533410 | 4850813-8 | 1 | 416968 |
| +5568911168384 | phone_number | Mock Person Name | 17413005255 | 4850813-8 | 1 | 416968 |
| pix06@pix06.com | email | Mock Person Name | 81035632691 | 4750813-8 | 1 | 416968 |
| pix31@pix31.com | email | Mock Person Name | 55125236780 | 1768538-4 | 2960 | 416968 |
| 8501216b-d676-4927-be65-060d3d4394fb | random_key | Mocked Enterprise S.A | 40008675000100 | 1049122-2 | 1 | 416968 |
| pix_key@mockenterprise.com.br | email | Mocked Enterprise S.A | 40008675000100 | 1049122-2 | 1 | 416968 |
| 40008675000100 | cnpj | Mocked Enterprise S.A | 40008675000100 | 1049122-2 | 1 | 416968 |
| +5568956720123 | phone_number | Mocked Enterprise S.A | 40008675000100 | 1049122-2 | 1 | 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 | Mock Person Name | 69017362073 | 81648459-8 | 1 | 18236120 |
| pix09@pix09.com | email | Mock Person Name | 34175131205 | 81538459-8 | 1 | 18236120 |
| 5e6ce01a-e0da-4d56-93b8-44f118b4f371 | random_key | Mock Person Name | 17413005255 | 81548459-8 | 1 | 18236120 |
| +5568911186420 | phone_number | Mock Person Name | 81035632691 | 81538459-8 | 1 | 18236120 |
| pix32@pix32.com | email | Mock Person Name | 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 | Mock Person Name | 65322181032 | 1019902-6 | 1 | 31872495 |
| 5e6ce07a-e0da-4d56-93b8-84f118b4f371 | random_key | Mock Person Name | 11085087824 | 1018902-6 | 1 | 31872495 |
| 11646288874 | cpf | Mock Person Name | 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 | Mock Person Name | 69017362073 | 364522-5 | 284 | 58160789 |
| pix08@pix08.com | email | Mock Person Name | 34175131205 | 264522-5 | 284 | 58160789 |
| +5568911106070 | phone_number | Mock Person Name | 11646288874 | 354522-5 | 284 | 58160789 |
| 53465252110 | cpf | Mock Person Name | 53465252110 | 364422-5 | 284 | 58160789 |
| +5568911122488 | phone_number | Mock Person Name | 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 | Mock Person Name | 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 | Mock Person Name | 53465252110 | 622470112-8 | 1111 | 8744817 |
| 17413005255 | cpf | Mock Person Name | 17413005255 | 622450112-8 | 1111 | 8744817 |
| 81035632691 | cpf | Mock Person Name | 81035632691 | 622450113-8 | 1111 | 8744817 |
| 5e6ce05a-e0da-4d56-93b8-64f118b4f371 | random_key | Mock Person Name | 81035632691 | 622650113-8 | 1111 | 8744817 |
## COMPANHIA GLOBAL DE SOLUCOES E SERVICOS DE PAGAMENTOS S.A.
| Chave Pix | Tipo | Nome do titular | Documento do titular | Número da conta | Agencia da conta | ISPB |
|-------------|------|-----------------|----------------------|-----------------|------------------|----------|
| 96755229091 | cpf | Teste sem Compe | 96755229091 | 1444301-8 | 1 | 32024691 |
## 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. |
---
# Comprovante de transação
URL: /documentation/pix/comprovante_de_transferencia
## Request
ENDPOINT /transaction_receipt/TRANSACTION_KEY
MÉTODO GET
:::info
A resposta desta requisição irá trazer os dados referentes á aquela transação consultada e caso o parâmetro PDF seja verdadeiro o campo "pdf_encoded_string" estará disponível com a string do PDF encodada em base-64.
:::
### Path params
| Campo | Tipo | Descrição | Caracteres |
|---|---|---|---|
| `TRANSACTION_KEY` * | string | Chave da transação consultada. | chave uuid |
### Query params
| Campo | Tipo | Descrição | Caracteres |
|---|---|---|---|
| `pdf` | boolean | Booleano que define se a resposta deverá gerar um PDF ou não. | true/false |
STATUS 200
Response Body: Recibo de transação com chave
```json
{
"is_schedule": true,
"origin_key": "f7507645-534c-4790-a19c-b89763d42fe5",
"schedule_date": "2021-11-06",
"scheduled_for_br_formatted": "Agendado Para 06/11/2021",
"source_account": {
"account_branch": "0001",
"account_digit": "9",
"account_number": "09661",
"financial_institution_compe_number": 329,
"financial_institution_name": "QI SOCIEDADE DE CRÉDITO DIRETO S.A.",
"owner_document_number": "45783565660"
},
"source_subtype": "pix_withdrawal",
"source_subtype_translation_ptbr": "Transferência de PIX",
"target_account": {
"account_branch": "3952",
"account_digit": "8",
"account_number": "1925255",
"account_type": "checking_account",
"account_type_str": "Conta Corrente",
"financial_institution_compe_number": 237,
"financial_institution_name": "BANCO BRADESCO S.A.",
"owner_document_number": "***.221.81*-**",
"owner_name": "Vivo Test",
"pix_key": "pix01@pix01.com",
"pix_transfer_type": "key"
},
"transaction_amount": 12.2,
"transaction_key": "53301505-342a-4bf4-b7de-845e5c79ed02"
}
```
## Response
STATUS 200
Response Body: Recibo de transação manual
```json
{
"chargeback_returned_amount": null,
"end_to_end_id": "E3210272497339911957760452404275",
"is_chargeback": false,
"pix_message": null,
"pix_transfer_key": "2c4d15c4-2a03-4979-813e-0ead374686d8",
"source_account_key": "e10a6f94-facc-4392-9eba-d0d0b278bc5d",
"receiver_conciliation_id": "REC00000000000000000000009459463343",
"pix_transfer_type": "transfer",
"target_account": {
"account_branch": "3952",
"account_digit": "8",
"account_number": "1925255",
"financial_institution_compe_number": 237,
"financial_institution_name": "BANCO BRADESCO S.A.",
"is_internal": false,
"ispb_number": "60746948",
"owner_document_number": "***22181***",
"owner_name": "Vivo Test",
"target_pix_key": "pix01@pix01.com"
},
"transfer_amount": 1891268.97
}
```
STATUS 400
Response Body
```json
{
"data": "{\"title\": \"Bad Request\", \"description\": \"Invalid request body.\", \"translation\": \"Corpo da requisição inválido.\", \"extra_fields\": {}, \"code\": \"LEG000069\"}"
}
```
---
# Criar Chave Pix
URL: /documentation/pix/criar_chave
## Criar Chave Pix CPF, CNPJ ou Aleatória
### Request
- MÉTODO POST
- ENDPOINT /baas/pix/keys
Request Body
```json
{
"account_key": "6d30a0b1-cb90-4ceb-b1ea-5bd600cdf3c8",
"pix_key_type": "random_key"
}
```
Request Body
```json
{
"account_key": "6d30a0b1-cb90-4ceb-b1ea-5bd600cdf3c8",
"pix_key_type": "cnpj",
"pix_key": "09080702000105"
}
```
Request Body
```json
{
"account_key": "6d30a0b1-cb90-4ceb-b1ea-5bd600cdf3c8",
"pix_key_type": "cpf",
"pix_key": "03882617038"
}
```
:::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: UUID.
:::
:::info Regra de CPF/CNPJ no Ambiente Sandbox
Para simular situações de aprovação e reprovação pode ser utilizado o primeiro digito do CPF/CNPJ do titular da chave pix a ser criada:
1, 2, 3, 4, 5 -> Reprovado automático
0, 6, 7, 8, 9 -> Aprovação automática
:::
### Response
- MÉTODO POST
- ENDPOINT /baas/pix/keys
Response Body
```json
{
"account_key": "6d30a0b1-cb90-4ceb-b1ea-5bd600cdf3c8",
"created_at": "2022-09-02T18:20:52",
"pix_key": {
"account_key": "6d30a0b1-cb90-4ceb-b1ea-5bd600cdf3c8",
"created_at": "2022-09-02T18:20:51",
"pix_key": "09080702000105",
"pix_key_status": "pending_confirmation",
"pix_key_type": "cnpj",
"updated_at": "2022-09-02T18:20:51"
},
"pix_key_request_key": "d60abf67-ad9c-42ee-9089-d26c8fc855b9",
"request_data": {
"account_created_at": "2022-09-02T22:44:36",
"account_digit": "2",
"account_number": "2359934",
"account_type": "checking",
"branch_number": "0001",
"key": "09080702000105",
"owner_document_number": "09080702000105",
"owner_name": "VOVO LUCIA CONVENIENCIA LTDA",
"owner_person_type": "legal",
"trading_name": "VOVO LUCIA"
},
"request_failure_reason": null,
"request_status": "pending",
"request_type": "inclusion",
"requester_key": "ef48fbe4-267b-45c1-9049-75345c075486",
"updated_at": "2022-09-02T18:20:52"
}
```
STATUS 400
Response Body: Chave pix já existe.
```json
{
"title": "Bad Request",
"description": "Pix key: \{pix_key\} already exists.",
"translation": "A chave pix: \{pix_key\} já existe.",
"code": "PIX000065"
}
```
STATUS 404
Response Body: Conta não encontrada
```json
{
"title": "Account not found",
"description": "Conta não encontrada para account_key: \{account_key\}",
"translation": "Conta não encontrada para account_key: \{account_key\}",
"code": "PIX000026"
}
```
STATUS 400
Response Body: Pessoa não encontrada
```json
{
"title": "Person not found",
"description": "Pessoa não encontrada para person_key: \{person_key\}",
"translation": "Pessoa não encontrada para person_key: \{person_key\}",
"code": "PIX000027"
}
```
STATUS 400
Response Body: Chave Pix não Finalizada
```json
{
"title": "Pix Key Creation Non Finished",
"description": "A chave pix \{pix_key\} já possui um pedido de criação não finalizado.",
"translation": "A chave pix \{pix_key\} já possui um pedido de criação não finalizado.",
"code": "PIX000074"
}
```
STATUS 400
Response Body: Número Máximo de Chaves Pix em Uso
```json
{
"title": "Maximum Number of Pix Keys in Use",
"description": "A conta \{account_key\} já atingiu o número máximo de chaves pix.",
"translation": "A conta \{account_key\} já atingiu o número máximo de chaves pix.",
"code": "PIX000014"
}
```
STATUS 400
Response Body: Conta não Aberta
```json
{
"title": "Account is not Opened",
"description": "A conta \{account_key\} não está aberta.",
"translation": "A conta \{account_key\} não está aberta.",
"code": "PIX000002"
}
```
STATUS 403
Response Body: Permissão Inválida
```json
{
"title": "Invalid Permission",
"description": "A pessoa \{person_key\} não possui credenciais de administrador para a conta \{account_key\}.",
"translation": "A pessoa \{person_key\} não possui credenciais de administrador para a conta \{account_key\}.",
"code": "PIX000054"
}
```
STATUS 422
Response Body: Tentativa de Chave Pix CPF Inválida
```json
{
"title": "Attempted CPF Pix Key is Not that of Account Owner",
"description": "A chave pix fornecida \{pix_key\} não corresponde ao CPF {document_number} do titular da conta.",
"translation": "A chave pix fornecida \{pix_key\} não corresponde ao CPF {document_number} do titular da conta.",
"code": "PIX000020"
}
```
:::caution Atenção
No caso da Response de criação de uma Chave Pix **Aleatória**, o campo “***pix_key***“ retornará um valor nulo. Para recuperar o valor da chave aleatória gerada, é necessária realizar uma consulta à lista de chaves cadastradas em uma conta, ou através do webhook de ativação.
:::
:::caution Atenção
A criação de chaves é assíncrona, sendo assim, a chave apenas estará disponível para uso após o recebimento do [webhook de inclusão de chave pix.](#webhook-de-inclusao-de-chave-pix)
:::
## Criar Chave Pix E-mail e Celular
**Para criação da chave:** POST no endpoint “**/baas/pix/keys**“. Neste momento, será enviado um Token para o E-mail ou Celular informado no campo “***pix_key***“.
### Request
- MÉTODO POST
- ENDPOINT /baas/pix/keys
Request Body
```json
{
"account_key": "6d30a0b1-cb90-4ceb-b1ea-5bd600cdf3c8",
"pix_key_type": "email",
"pix_key": "vovo.lucia@gmail.com.br"
}
```
Request Body
```json
{
"account_key": "6d30a0b1-cb90-4ceb-b1ea-5bd600cdf3c8",
"pix_key_type": "phone_number",
"pix_key": "+5511987654321"
}
```
### Response
- MÉTODO POST
- ENDPOINT /baas/pix/keys
Response Body
```json
{
"account_key": "6d30a0b1-cb90-4ceb-b1ea-5bd600cdf3c8",
"created_at": "2022-09-02T17:41:55",
"pix_key": {
"account_key": "6d30a0b1-cb90-4ceb-b1ea-5bd600cdf3c8",
"created_at": "2022-09-02T17:41:54",
"pix_key": "pedro.pinho@qitech.com.br",
"pix_key_status": "pending_confirmation",
"pix_key_type": "email",
"updated_at": "2022-09-02T17:41:54"
},
"pix_key_request_key": "f6209b7e-82da-44a8-9cfa-6ad0a689adb2",
"request_data": {
"account_created_at": "2022-09-02T22:44:36",
"account_digit": "2",
"account_number": "2359934",
"account_type": "checking",
"branch_number": "0001",
"key": "pedro.pinho@qitech.com.br",
"owner_document_number": "09080702000105",
"owner_name": "VOVO LUCIA CONVENIENCIA LTDA",
"owner_person_type": "legal",
"trading_name": "VOVO LUCIA"
},
"request_failure_reason": null,
"request_status": "pending_validation",
"request_type": "inclusion",
"requester_key": "ef48fbe4-267b-45c1-9049-75345c075486",
"updated_at": "2022-09-02T17:41:55"
}
```
STATUS 400
Response Body: Chave pix já existe.
```json
{
"title": "Bad Request",
"description": "Pix key: \{pix_key\} already exists.",
"translation": "A chave pix: \{pix_key\} já existe.",
"code": "PIX000065"
}
```
STATUS 404
Response Body: Conta não encontrada
```json
{
"title": "Account not found",
"description": "Conta não encontrada para account_key: \{account_key\}",
"translation": "Conta não encontrada para account_key: \{account_key\}",
"code": "PIX000026"
}
```
STATUS 400
Response Body: Pessoa não encontrada
```json
{
"title": "Person not found",
"description": "Pessoa não encontrada para person_key: \{person_key\}",
"translation": "Pessoa não encontrada para person_key: \{person_key\}",
"code": "PIX000027"
}
```
STATUS 400
Response Body: Chave Pix não Finalizada
```json
{
"title": "Pix Key Creation Non Finished",
"description": "A chave pix \{pix_key\} já possui um pedido de criação não finalizado.",
"translation": "A chave pix \{pix_key\} já possui um pedido de criação não finalizado.",
"code": "PIX000074"
}
```
STATUS 400
Response Body: Número Máximo de Chaves Pix em Uso
```json
{
"title": "Maximum Number of Pix Keys in Use",
"description": "A conta \{account_key\} já atingiu o número máximo de chaves pix.",
"translation": "A conta \{account_key\} já atingiu o número máximo de chaves pix.",
"code": "PIX000014"
}
```
STATUS 400
Response Body: Conta não Aberta
```json
{
"title": "Account is not Opened",
"description": "A conta \{account_key\} não está aberta.",
"translation": "A conta \{account_key\} não está aberta.",
"code": "PIX000002"
}
```
STATUS 403
Response Body: Permissão Inválida
```json
{
"title": "Invalid Permission",
"description": "A pessoa \{person_key\} não possui credenciais de administrador para a conta \{account_key\}.",
"translation": "A pessoa \{person_key\} não possui credenciais de administrador para a conta \{account_key\}.",
"code": "PIX000054"
}
```
STATUS 422
Response Body: Tentativa de Chave Pix CPF Inválida
```json
{
"title": "Attempted CPF Pix Key is Not that of Account Owner",
"description": "A chave pix fornecida \{pix_key\} não corresponde ao CPF {document_number} do titular da conta.",
"translation": "A chave pix fornecida \{pix_key\} não corresponde ao CPF {document_number} do titular da conta.",
"code": "PIX000020"
}
```
**IMPORTANTE:** O valor retornado no campo “pix_key_request_key“ deve ser utilizado na URL da requisição para aprovação da criação da Chave Pix.
## Aprovação de Chave Pix E-mail ou Celular
### Request
- MÉTODO PATCH
- ENDPOINT /baas/pix/keys/ PIX_KEY_REQUEST_KEY /twofa_validation
Request Body
```json
{
"verification_code": "756816"
}
```
### Response
Response Body
```json
{
"account_key": "6d30a0b1-cb90-4ceb-b1ea-5bd600cdf3c8",
"created_at": "2022-09-02T17:41:55",
"pix_key": {
"account_key": "6d30a0b1-cb90-4ceb-b1ea-5bd600cdf3c8",
"created_at": "2022-09-02T17:41:54",
"pix_key": "pedro.pinho@qitech.com.br",
"pix_key_status": "pending_confirmation",
"pix_key_type": "email",
"updated_at": "2022-09-02T17:41:54"
},
"pix_key_request_key": "f6209b7e-82da-44a8-9cfa-6ad0a689adb2",
"request_data": {
"account_created_at": "2022-09-02T22:44:36",
"account_digit": "2",
"account_number": "2359934",
"account_type": "checking",
"branch_number": "0001",
"key": "pedro.pinho@qitech.com.br",
"owner_document_number": "09080702000105",
"owner_name": "VOVO LUCIA CONVENIENCIA LTDA",
"owner_person_type": "legal",
"trading_name": "VOVO LUCIA"
},
"request_failure_reason": null,
"request_status": "pending",
"request_type": "inclusion",
"requester_key": "ef48fbe4-267b-45c1-9049-75345c075486",
"updated_at": "2022-09-02T17:41:55"
}
```
STATUS 404
Response Body: Solicitação de chave Pix não encontrada
```json
{
"title": "Pix Key Request not found",
"description": "Pix Key Request not found for key: {pix_key_request_key}.",
"translation": "Pix Key Request não encontrada para a chave: {pix_key_request_key}.",
"code": "PIX000008"
}
```
STATUS 403
Response Body: Erro do Validador de Permissão
```json
{
"title": "Permission Validator Error",
"description": "Selected agent do not own this item.",
"translation": "O agente selecionado não é dono do item.",
"code": "QIT000005"
}
```
STATUS 400
Response Body: Pedido de criação não possui validação
```json
{
"title": "Key request does not have validation",
"description": "Key request does not have two steps validation",
"translation": "Pedido de criação não possui validação de duas etapas",
"code": "PIX000075"
}
```
STATUS 400
Response Body: Pedido de criação não está pendente de validação
```json
{
"title": "Key Request Is Not Pending Validation",
"description": "Key request {pix_key_request_key}, is not pending validation.",
"translation": "Pedido de criação {pix_key_request_key}, não está pendente de validação.",
"code": "PIX000076"
}
```
STATUS 404
Response Body: Token Expirado
```json
{
"title": "Gone",
"description": {
"description": "Expired Code.",
"translation": "Código de verificação expirado."
},
"translation": {},
"extra_fields": {},
"code": "2FA000410"
}
```
STATUS 403
Response Body: Token Expirado
```json
{
"title": "Forbidden",
"description": {
"description": "Code already verified.",
"translation": "Este código já foi utilizado."
},
"translation": {},
"extra_fields": {},
"code": "2FA000403"
}
```
## Reenviar o token de aprovação
### Request
- MÉTODO PATCH
- ENDPOINT /baas/pix/keys/ PIX_KEY_REQUEST_KEY /resend_twofa
Request Body
```json
{}
```
### Response
Response Body
```json
{
"account_key": "6d30a0b1-cb90-4ceb-b1ea-5bd600cdf3c8",
"created_at": "2022-09-02T17:41:55",
"pix_key": {
"account_key": "6d30a0b1-cb90-4ceb-b1ea-5bd600cdf3c8",
"created_at": "2022-09-02T17:41:54",
"pix_key": "pedro.pinho@qitech.com.br",
"pix_key_status": "pending_confirmation",
"pix_key_type": "email",
"updated_at": "2022-09-02T17:41:54"
},
"pix_key_request_key": "f6209b7e-82da-44a8-9cfa-6ad0a689adb2",
"request_data": {
"account_created_at": "2022-09-02T22:44:36",
"account_digit": "2",
"account_number": "2359934",
"account_type": "checking",
"branch_number": "0001",
"key": "pedro.pinho@qitech.com.br",
"owner_document_number": "09080702000105",
"owner_name": "VOVO LUCIA CONVENIENCIA LTDA",
"owner_person_type": "legal",
"trading_name": "VOVO LUCIA"
},
"request_failure_reason": null,
"request_status": "pending_validation",
"request_type": "inclusion",
"requester_key": "ef48fbe4-267b-45c1-9049-75345c075486",
"updated_at": "2022-09-02T17:41:55"
}
```
STATUS 404
Response Body: Solicitação de chave Pix não encontrada
```json
{
"title": "Pix Key Request not found",
"description": "Pix Key Request not found for key: {pix_key_request_key}.",
"translation": "Pix Key Request não encontrada para a chave: {pix_key_request_key}.",
"code": "PIX000008"
}
```
STATUS 403
Response Body: Erro do Validador de Permissão
```json
{
"title": "Permission Validator Error",
"description": "Selected agent do not own this item.",
"translation": "O agente selecionado não é dono do item.",
"code": "QIT000005"
}
```
STATUS 400
Response Body: Pedido de criação não possui validação
```json
{
"title": "Key request does not have validation",
"description": "Key request does not have two steps validation",
"translation": "Pedido de criação não possui validação de duas etapas",
"code": "PIX000075"
}
```
STATUS 400
Response Body: Pedido de criação não está pendente de validação
```json
{
"title": "Key Request Is Not Pending Validation",
"description": "Key request {pix_key_request_key}, is not pending validation.",
"translation": "Pedido de criação {pix_key_request_key}, não está pendente de validação.",
"code": "PIX000076"
}
```
### Webhook de Inclusão de Chave Pix
WEBHOOK_TYPE key_inclusion
STATUS approved
Webhook Body
```json
{
"pix_key": "c232142c-ddbf-41d6-a54f-3b90c28b97dc",
"account_key": "94945886-7a6f-43e6-a307-e36c959e4903",
"webhook_type": "key_inclusion",
"pix_key_status": "active",
"pix_key_request_key": "e274eb13-40b3-4902-978e-8e5fa267af53",
"pix_key_request_type": "inclusion",
"pix_key_request_status": "approved"
}
```
WEBHOOK_TYPE key_inclusion
STATUS failed
Webhook Body
```json
{
"pix_key": "03882617038",
"account_key": "94945886-7a6f-43e6-a307-e36c959e4903",
"webhook_type": "key_inclusion",
"pix_key_status": "inactivated",
"pix_key_request_key": "e274eb13-40b3-4902-978e-8e5fa267af53",
"pix_key_request_type": "inclusion",
"pix_key_request_status": "failed",
"request_failure_reason": "DCT200016"
}
```
:::info Código de Motivo de Falha da Requisição
- DCT200012: Já existe vínculo para essa chave, mas ela é possuída por outra pessoa. Indica-se que seja feita uma reivindicação de posse.
- DCT200013: Já existe vínculo para essa chave com o mesmo dono, mas ela encontra-se associada a outro participante. Indica-se que seja feita uma reivindicação de portabilidade.
- DCT200014: Existe uma reivindicação com status diferente de concluída ou cancelada para a chave do vínculo. Enquanto estiver nessa situação, o vínculo não pode ser excluído.
- DCT200015: Falha na validação dos parâmetros informados no request.
- DCT200016: O titular da chave (CPF/CNPJ) possui situação cadastral irregular. A inclusão da chave PIX não é permitida até a regularização.
:::
---
# Criar QR Code Pix dinâmico
URL: /documentation/pix/criar_qr_code_dinamico
## Request
ENDPOINT /baas/qrcode/dynamic
MÉTODO POST
Request Body: Com vencimento
```json
{
"account_key": "f0d363be-fc49-4cfc-a1f8-c8d4d4195095",
"amount": 22.34,
"occurrence_type": "registration",
"payer_document_number": "00000000000000",
"payer_name": "Random",
"payer_person_type": "legal",
"payer_request": "Payment for order XXXXXXXXXX",
"pix_key": "3d7d6a2b-f72f-44z7-bb20-79a94dff5645",
"receiver_conciliation_id": "3d7d6a2bf72f44z7bb2079a94dff5645",
"qr_code_type": "dynamic_term",
"additional_data": [
{
"key_name": "Juros e Multa",
"value": "Juros 2 ao mes e multa de 1%"
}
],
"fine_amount": 3,
"interest_amount": 2,
"expiration_date": "2023-03-25",
"max_payment_days": 128,
"rebate_amount": 1,
"discounts": []
}
```
Request Body: Pagamento imediato
```json
{
"account_key": "f0d363be-fc49-4cfc-a1f8-c8d4d4195095",
"amount": 22.34,
"expiration_seconds": 864000,
"occurrence_type": "registration",
"payer_document_number": "00000000000000",
"payer_name": "Random",
"payer_person_type": "legal",
"payer_request": "Payment for order XXXXXXXXXX",
"pix_key": "3d7d6a2b-f72f-44z7-bb20-79a94dff5645",
"receiver_conciliation_id": "3d7d6a2bf72f44z7bb2079a94dff5645",
"qr_code_type": "dynamic_instant",
"additional_data": [
{
"key_name": "Juros e Multa",
"value": "Juros 2 ao mes e multa de 1%"
}
],
"fine_amount": 3,
"interest_amount": 2,
"max_payment_days": 128,
"rebate_amount": 1,
"discounts": []
}
```
### Body Params
| Campo | Tipo | Descrição | Caracteres |
|---|---|---|---|
| `amount` * | float | Valor do QR Code antes do cálculo de descontos ou juros e multas. | - |
| `occurrence_type` * | string |Tipo de ocorrencia. payment: Ocorrência do tipo pagamento, registration: Ocorrência do tipo registro, write_off: Ocorrência do tipo cancelamento pelo gerador, bank_written_off: Ocorrência do tipo cancelamento pelo banco. | - |
| `qr_code_type` * | string | Tipo do QR Code dinâmico | - |
| `pix_key` * | string | Chave Pix que representa a conta de destino da transação. | - |
| `receiver_conciliation_id` * | string | Identificador único para conciliação | 32 |
| `expiration_date` | date | Data de vencimento da cobrança (no formato "YYYY-MM-DD" | - |
| `expiration_seconds` | string | indica qual o tempo de validad e do QR Code em segundos, padrão 1 dia. | - |
| `payer_name` * | string | Nome do pagador. | - |
| `payer_document_number` * | string | CPF do pagador. | - |
| `payer_person_type` * | string | Tipo de pessoa (natural = física ou legal = jurídica). | - |
| `payer_request` * | string | Mensagem ao pagador. | - |
| `additional_data` * | array of objects | Informações que serão apresentadas para o pagador. | - |
| `max_payment_days` * | int32 | Dias máximo para pagamento da cobrança. | - |
| `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. | - |
### 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 200
Response Body: Com vencimento
```json
{
"qr_code_type": "dynamic_instant",
"amount": 22.34,
"expiration_seconds": null,
"max_payment_days": null,
"receiver_conciliation_id": "01GVGV9NXBCY287Z6CJ4S0ENW9",
"payer_name": "Random",
"payer_document_number": "00000000000000",
"payer_person_type": "legal",
"payer_request": "Payment for order XXXXXXXXXXXX",
"pix_message": null,
"modality_alteration": false,
"expiration_date": "2023-03-25",
"rebate_amount": 1,
"interest_amount": 2,
"fine_amount": 3,
"paid_amount": null,
"discounts": [],
"additional_data": [],
"origin": "system",
"origin_key": null,
"pix_key": "3d7d6a2b-f72f-44z7-bb20-79a94dff5645",
"qr_code_key": "6fd14834-03e3-4777-b907-d2c43d4c2a1e",
"occurrence_type": "registration",
"end_to_end_id": null,
"source_account_branch": null,
"source_account_financial_institution": null,
"source_account_ispb": null,
"source_account_number": null,
"source_account_digit": null,
"disable": null,
"qr_code_occurrence_key": "38c55754-2c26-4065-aa21-240c6b9a8ce7",
"base_64": "\",
"image": "\"
}
```
STATUS 200
Response Body: Pagamento imediato
```json
{
"qr_code_type": "dynamic_instant",
"amount": 22.34,
"expiration_seconds": 864000,
"max_payment_days": null,
"receiver_conciliation_id": "01GVGV9NXBCY287Z6CJ4S0ENW9",
"payer_name": "Random",
"payer_document_number": "00000000000000",
"payer_person_type": "legal",
"payer_request": "Payment for order XXXXXXXXXXXX",
"pix_message": null,
"modality_alteration": false,
"expiration_date": null,
"rebate_amount": 1,
"interest_amount": 2,
"fine_amount": 3,
"paid_amount": null,
"discounts": [],
"additional_data": [],
"origin": "system",
"origin_key": null,
"pix_key": "3d7d6a2b-f72f-44z7-bb20-79a94dff5645",
"qr_code_key": "6fd14834-03e3-4777-b907-d2c43d4c2a1e",
"occurrence_type": "registration",
"end_to_end_id": null,
"source_account_branch": null,
"source_account_financial_institution": null,
"source_account_ispb": null,
"source_account_number": null,
"source_account_digit": null,
"disable": null,
"qr_code_occurrence_key": "38c55754-2c26-4065-aa21-240c6b9a8ce7",
"base_64": "\",
"image": "\"
}
```
STATUS 400
Response Body
```json
{
"data": "{\"title\": \"Bad Request\", \"description\": \"Invalid request body.\", \"translation\": \"Corpo da requisição inválido.\", \"extra_fields\": {}, \"code\": \"LEG000069\"}"
}
```
---
# Criar QR Code Estático
URL: /documentation/pix/criar_qr_code_estatico
## Request
ENDPOINT /baas/qrcode/static
MÉTODO POST
Request Body
```json
{
"qr_code_format": "both",
"pix_key": "3d7d6a2b-f72f-44c7-bb20-79a94dff5954",
"receiver_name": "Tywin Lannister",
"amount": 10.25
}
```
### Body params
| Campo | Tipo | Descrição | Caracteres |
|---|---|---|---|
| `qrcode_format` | string | indica qual o tipo de retorno após a geração do QR Code (image, payload, both: padrão). | - |
| `pix_key` * | string |Chave Pix atrelada a conta de recebimento ao executar o pagamento com o QR Code. | 10 |
| `receiver_name` * | string | Nome do dono da conta. | - |
| `amount` | float | Valor do QR Code. Caso não seja enviado o pagador deverá inserir o total durante a transferência. | - |
## Response
STATUS 200
Response Body
```json
{
"image": "\",
"payload": "\"
}
```
STATUS 400
Response Body
```json
{
"data": "{\"title\": \"Bad Request\", \"description\": \"Invalid request body.\", \"translation\": \"Corpo da requisição inválido.\", \"extra_fields\": {}, \"code\": \"LEG000069\"}"
}
```
---
# Decodificar QR Code Pix
URL: /documentation/pix/decodificar_qr_code
Decodifica um QR Code Pix retornando os dados contidos no payload. Não realiza consulta DICT na conta destino e não persiste o QR Code consultado — adequado para fluxos de pré-visualização (preview) antes da decisão de pagamento.
## Request
ENDPOINT /pix/decode_qrcode_payload
MÉTODO POST
Request Body
```json
{
"qr_code_payload": "00020126580014br.gov.bcb.pix0136a23bf0e9-5175-4829-bf89-e8fe6ac09aa1520400005303986540530.005802BR5914TywinLannister6008saopaulo62070503***6304D4FD"
}
```
### Body Params
| Campo | Tipo | Descrição | Caracteres |
|---------------------|--------|-------------------------|------------|
| `qr_code_payload` * | string | Pix Copia e Cola | - |
## Response
STATUS 200
Response Body: QR Code estático
```json
{
"qr_code_type": "static",
"qr_code_payload": "00020126580014br.gov.bcb.pix0136a23bf0e9-5175-4829-bf89-e8fe6ac09aa1520400005303986540530.005802BR5914TywinLannister6008saopaulo62070503***6304D4FD",
"pix_key": "a23bf0e9-5175-4829-bf89-e8fe6ac09aa1",
"transfer_amount": "30.00",
"additional_data": null,
"qr_code_data": {
"target_pix_key": "a23bf0e9-5175-4829-bf89-e8fe6ac09aa1",
"amount": "30.00",
"receiver_conciliation_id": "***",
"additional_data": [],
"category_code": "0000",
"city": "saopaulo",
"postal_code": null,
"reusable_qrcode": "no"
}
}
```
STATUS 200
Response Body: QR Code dinâmico pagamento imediato
```json
{
"qr_code_type": "dynamic_instant",
"qr_code_payload": "00020101021226850014br.gov.bcb.pix2563qrcodepix.bb.com.br/pix/v2/d373e385-dfe7-49f6-b9ec-14ba60a9b8285204000053039865802BR5925TESTE62070503***63047B7D",
"pix_key": "teste.cobrancapix@gmail.com.br",
"receiver_conciliation_id": "fgnb4NTt7pOUBGfrcporERwVVqr0f8PWRfK",
"amount": "9367.61",
"status": "ATIVA",
"qr_code_data": {
"target_pix_key": "teste.cobrancapix@gmail.com.br",
"receiver_conciliation_id": "fgnb4NTt7pOUBGfrcporERwVVqr0f8PWRfK",
"amount": "9367.61",
"can_change": "no",
"expiration_seconds": 201574,
"created_at": "2023-03-13T19:00:28.440Z",
"presented_at": "2023-03-14T19:07:48.729Z",
"question_to_payer": "Liquidacao de Parcelas",
"status": "ATIVA",
"revision": 0,
"category_code": "0000",
"city": "RIO DE JANEIRO",
"postal_code": null,
"reusable_qrcode": "no",
"receiver_url": "qrcodepix.bb.com.br/pix/v2/d373e385-dfe7-49f6-b9ec-14ba60a90000",
"additional_data": [],
"payer_name": "ISMAEL FATIMA AMARAL",
"payer_document_number": "10003550206",
"payer_person_type": "natural",
"target_name": "TESTE LTDA.",
"target_trading_name": null,
"address": "Rua Tapajos, 941",
"state": "RJ"
}
}
```
STATUS 200
Response Body: QR Code dinâmico com vencimento
```json
{
"qr_code_type": "dynamic_term",
"qr_code_payload": "00020101021226840014br.gov.bcb.pix2562invoice.starkbank.com/v2/cobv/8b434df48c30482a81f7c936ae35cc123456000053039865802BR5925Oncred Sociedade de Credi6015TESTE 62070503***6304D008",
"pix_key": "e623e7b0-d00a-400e-aee6-79632430e817",
"receiver_conciliation_id": "8b434df48c30482a81f7c936ae35cc87",
"amount": "55.59",
"status": "ATIVA",
"qr_code_data": {
"target_pix_key": "e623e7b0-d00a-400e-aee6-79632430e817",
"receiver_conciliation_id": "8b434df48c30482a81f7c936ae35cc87",
"original_amount": "55.59",
"reduction_amount": null,
"discount_amount": null,
"fee_amount": null,
"fine_amount": null,
"amount": "55.59",
"due_date": "2023-03-27",
"days_after_due_accepted": 16,
"created_at": "2023-01-10T19:49:58.30Z",
"presented_at": "2023-03-10T15:32:15.87Z",
"question_to_payer": null,
"status": "ATIVA",
"revision": 0,
"category_code": "0000",
"reusable_qrcode": "no",
"receiver_url": "invoice.starkbank.com/v2/cobv/8b434df48c30482a81f7c936ae351234",
"additional_data": [],
"payer_name": "Willian Rocha",
"payer_document_number": "00000000000",
"payer_person_type": "natural",
"target_name": "TESTE LTDA.",
"target_trading_name": null,
"address": "Rua Tapajos, 941",
"state": "SP",
"city": "Sao Caetano do Sul",
"postal_code": "09551230"
}
}
```
### Campos da resposta
| Campo | Tipo | Descrição | Presente em |
|------------------------------------|-----------------|--------------------------------------------------------------------------------------------|-------------------|
| `qr_code_type` | string | Tipo do QR Code: `static`, `dynamic_instant` ou `dynamic_term` | Todos |
| `qr_code_payload` | string | Payload EMV original enviado na requisição | Todos |
| `qr_code_data.target_pix_key` | string | Chave Pix do recebedor | Todos |
| `qr_code_data.amount` | string/decimal | Valor da cobrança. Em `dynamic_term` representa o valor final (após multa/juros/desconto) | Todos |
| `qr_code_data.receiver_conciliation_id` | string | Identificador de conciliação do recebedor (txid) | Todos |
| `qr_code_data.additional_data` | array | Lista de informações adicionais `{name, value}` | Todos |
| `qr_code_data.category_code` | string | Código de categoria do estabelecimento (MCC) | Todos |
| `qr_code_data.city` | string | Cidade do recebedor | Todos |
| `qr_code_data.postal_code` | string | CEP do recebedor | Todos |
| `qr_code_data.reusable_qrcode` | string | `yes` se o QR Code pode ser pago múltiplas vezes, `no` caso contrário | Todos |
| `qr_code_data.receiver_url` | string | URL do PSP do recebedor (campo `loc` do BR Code) | `dynamic_*` |
| `qr_code_data.status` | string | Status da cobrança (ver enumeradores abaixo) | `dynamic_*` |
| `qr_code_data.revision` | integer | Versão atual da cobrança | `dynamic_*` |
| `qr_code_data.created_at` | string (ISO) | Data de criação da cobrança no PSP do recebedor | `dynamic_*` |
| `qr_code_data.presented_at` | string (ISO) | Data de apresentação da cobrança ao pagador | `dynamic_*` |
| `qr_code_data.question_to_payer` | string | Mensagem do recebedor para o pagador (`solicitacaoPagador`) | `dynamic_*` |
| `qr_code_data.payer_name` | string | Nome do pagador esperado, quando informado pelo recebedor | `dynamic_*` |
| `qr_code_data.payer_document_number` | string | CPF/CNPJ do pagador esperado | `dynamic_*` |
| `qr_code_data.payer_person_type` | string | `natural` ou `legal` | `dynamic_*` |
| `qr_code_data.target_name` | string | Nome do recebedor | `dynamic_*` |
| `qr_code_data.expiration_seconds` | integer | Tempo de validade da cobrança em segundos a partir de `created_at` | `dynamic_instant` |
| `qr_code_data.can_change` | string | `yes` se o pagador pode alterar o valor, `no` caso contrário | `dynamic_instant` |
| `qr_code_data.original_amount` | string/decimal | Valor original da cobrança antes de multa/juros/desconto | `dynamic_term` |
| `qr_code_data.due_date` | string (date) | Data de vencimento da cobrança | `dynamic_term` |
| `qr_code_data.days_after_due_accepted` | integer | Dias após o vencimento em que a cobrança ainda aceita pagamento | `dynamic_term` |
| `qr_code_data.fine_amount` | string/decimal | Multa aplicada após o vencimento | `dynamic_term` |
| `qr_code_data.fee_amount` | string/decimal | Juros aplicados após o vencimento | `dynamic_term` |
| `qr_code_data.discount_amount` | string/decimal | Desconto concedido antes do vencimento | `dynamic_term` |
| `qr_code_data.reduction_amount` | string/decimal | Abatimento aplicado à cobrança | `dynamic_term` |
| `qr_code_data.target_trading_name` | string | Nome fantasia do recebedor | `dynamic_*` |
| `qr_code_data.address` | string | Logradouro do recebedor | `dynamic_*` |
| `qr_code_data.state` | string | UF do recebedor | `dynamic_*` |
:::caution Campos deprecated na raiz da resposta
Os campos abaixo são retornados na raiz da resposta apenas por retrocompatibilidade e serão removidos em uma versão futura. Utilize os equivalentes dentro de `qr_code_data`.
| Campo | Equivalente | Presente em |
|----------------------------|------------------------------------------|--------------|
| `pix_key` | `qr_code_data.target_pix_key` | Todos |
| `transfer_amount` | `qr_code_data.amount` | `static` |
| `additional_data` | `qr_code_data.additional_data` | `static` |
| `amount` | `qr_code_data.amount` | `dynamic_*` |
| `receiver_conciliation_id` | `qr_code_data.receiver_conciliation_id` | `dynamic_*` |
| `status` | `qr_code_data.status` | `dynamic_*` |
:::
:::info QR Code estático
Por especificação do BR Code, QR Codes estáticos não contêm dados do pagador esperado, data de expiração, multa, juros, descontos nem abatimento. Esses campos só existem em QR Codes dinâmicos.
:::
:::info Status
Para o QR Code do tipo dinâmico, é retornado o status do QR Code conforme a tabela de enumeradores abaixo.
:::
#### Enumeradores Status QR Code dinâmico
| Enumerador | Descrição |
|-------------------------------------|------------------------------------------------------|
| **ATIVA** | Cobrança disponível, sem pagamento realizado |
| **CONCLUIDA** | Cobrança paga e finalizada |
| **REMOVIDA_PELO_USUARIO_RECEBEDOR** | Usuário recebedor solicitou a remoção da cobrança |
| **REMOVIDA_PELO_PSP** | Banco recebedor solicitou a remoção da cobrança |
## Erros
STATUS 400
QR Code com formato inválido
```json
{
"data": "{\"title\": \"Invalid Qr Code Format\", \"description\": \"The Qr Code format is invalid, please enter a valid Qr Code\", \"translation\": \"O formato do Qr Code é inválido, por favor insira um Qr Code válido\", \"extra_fields\": {}, \"code\": \"PXT000070\"}"
}
```
Tipo de QR Code não identificado no payload
```json
{
"data": "{\"title\": \"Invalid Qr Code Type\", \"description\": \"The Qr Code payload given did not provide a propper Qr Code type\", \"translation\": \"O payload de QR Code fornecido não contêm um tipo de Qr Code Válido\", \"extra_fields\": {}, \"code\": \"PXT000071\"}"
}
```
Erro ao processar QR Code dinâmico
```json
{
"data": "{\"title\": \"Error in Qr Code Payload Request\", \"description\": \"An error occurred while requesting the qr code payload to the registry institution\", \"translation\": \"Um erro ocorreu durante a requisição do payload do qr code para a instituição de registro\", \"extra_fields\": {}, \"code\": \"PXT000069\"}"
}
```
---
# Excluir chave Pix
URL: /documentation/pix/excluir_chave
## Request
ENDPOINT /baas/pix/keys/ PIX_KEY
MÉTODO DELETE
### Path params
| Campo | Tipo | Descrição | Caracteres |
|---|---|---|---|
| `pix_key` * | string | Chave PIX que será excluída. | chave uuid |
## Response
STATUS 200
Response Body
```json
{
"account_key": "9d3d0083-ac71-43f0-8a90-c00a157a4883",
"created_at": "2021-12-06T21:16:11",
"pix_key": {
"account_key": "9d3d0083-ac71-43f0-8a90-c00a157a4883",
"created_at": "2021-12-06T21:16:11",
"pix_key": "b1afcafb-bd88-4958-b8ab-48c3a00044a0",
"pix_key_status": "inactive",
"pix_key_type": "random_key",
"updated_at": "2021-12-06T21:16:22"
},
"pix_key_request_key": "ab816c64-bce9-42e9-be6f-9f690a1dccbc",
"request_data": {},
"request_failure_reason": null,
"request_status": "approved",
"request_type": "deletion",
"requester_key": "62d1f47a-397d-4a46-bcf6-29e4a07d1375",
"updated_at": "2021-12-06T21:16:22"
}
```
STATUS 400
Response Body
```json
{
"data": "{\"title\": \"Bad Request\", \"description\": \"Invalid request body.\", \"translation\": \"Corpo da requisição inválido.\", \"extra_fields\": {}, \"code\": \"LEG000069\"}"
}
```
---
# Introdução
URL: /documentation/pix/introducao
Pix é o pagamento instantâneo brasileiro. O meio de pagamento criado pelo Banco Central (BACEN) em que os recursos são transferidos entre contas em poucos segundos, a qualquer hora ou dia. É prático, rápido e seguro.
A QI Tech por ser uma instituição homologada junto ao Banco Central é integrante do Sistema de Pagamento Brasileiro (SPB), podendo oferecer mais essa facilidade aos seus clientes.
## Vantagens e potencial
Além de aumentar a velocidade em que pagamentos ou transferências são feitos e recebidos, o Pix tem o potencial de:
- Alavancar a competitividade e a eficiência do mercado;
- Baixar o custo, aumentar a segurança e aprimorar a experiência dos clientes;
- Incentivar a eletronização do mercado de pagamentos de varejo;
- Promover a inclusão financeira; e
- Preencher uma série de lacunas existentes na cesta de instrumentos de pagamentos disponíveis atualmente à população.
## Erros
### Exemplo de resposta de erro:
**Response Body**
```json
{
"title": "SPI Timeout Control",
"description": "SPI Timeout Control.",
"translation": "Controle de timeout no SPI.",
"extra_fields": {
"description": "SPI Timeout Control.",
"translation": "Controle de timeout no SPI.",
"external_title": "SPI Timeout Control",
"external_code": "PXP000007"
},
"code": "PXP000007"
}
```
### Tabela de erros:
| Code | Message | Status HTTP | Description | Translated description |
|---|---|---|---|---|
| QIT000403 | Forbidden | 403 | Participant has not rights to this operation. | Participante não tem poderes para essa operação. |
| QIT000400 | BadRequest | 400 | The server cannot or will not process the request due to an apparent client error (e.g., malformed request syntax, size too large, invalid request message framing, or deceptive request routing). | O servidor não pode ou não processará a request devido a um erro do cliente (por exemplo, sintaxe de request malformada, tamanho muito grande, enquadramento de mensagem de request inválida ou roteamento de request enganoso). |
| PXP000046 | Gone | 410 | Expired QR code. |QR Code expirado. |
| PXP000046 | Gone | 410 | Expired QR code. | QR Code expirado. |
| QIT000404 | NotFound | 404 | The requested resource could not be found but may be available in the future. Subsequent requests by the client are permissible. | O resource solicitado não pôde ser encontrado, mas pode estar disponível no futuro. Requests subsequentes do cliente são permitidos. |
| QIT000500 | InternalServerError | 500 | An internal error has occurred and its being investigated. | Um erro interno aconteceu e está sendo investigado. |
| PXP000040 | ClaimKeyNotFound | 408 | Claim Key Not Found. | Chave a ser reivindicada não encontrada. |
| QIT000403 | Forbidden | AB03 | Participant has not rights to this operation. | Translated description |
| PXP000007 | AB03 | 408 | SPI Timeout Control. | Controle de timeout no SPI. |
| PXP000037 | AB09 | 502 | Cancelled transaction due to receiver's internal error. | Transação interrompida devido a erro no PSP do Recebedor. |
| PXP000037 | AB11 | 408 | Target PSP Timeout. | Timeout do participante emissor da ordem de pagamento. |
| PXP000009 | AC03 | 400 | Target account number is invalid. | Número da conta de destino é inexistente ou inválido. |
| PXP000010 | AC06 | 400 | Target account is blocked. | A conta de destino encontra-se bloqueada. |
| PXP000011 | AC07 | 400 | Target account is closed. | A conta de destino encontra-se encerrada. |
| PXP000032 | AC14 | 400 | Incorrect type for target account. | Tipo incorreto para a conta transacional especificada. |
| PXP000012 | AG03 | 400 | Unsupported transaction for given target account. | A conta de destino não suporta este tipo de transação. |
| PXP000013 | AGNT | 400 | SPI participant is not PSP settler agent of payer nor receiver. | Participante direto do SPI não é liquidante do PSP do Pagador / Recebedor. |
| PXP000014 | AM01 | 400 | Zero value payment order. | Ordem de pagamento com valor zero. |
| PXP000015 | AM04 | 400 | Insufficient funds in PI account from payer. | Saldo insuficiente na conta PI do pagador. |
| PXP000016 | AM09 | 400 | Return value greater than corresponding payment order. | Valor de devolução acima do valor de pagamento correspondente. |
| PXP000017 | AM18 | 400 | Invalid transactions number. | Quantidade de transações inválida. |
| PXP000018 | BE01 | 400 | 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. |
| PXP000019 | CH11 | 400 | Invalid beneficiary document number. | CPF/CNPJ da conta de destino está incorreto. |
| PXP000020 | CH16 | 400 | Incorrect message element. | Elemento da mensagem incorreto. |
| PXP000021 | DS04 | 400 | Beneficiary's PSP has rejected payment order. | Ordem de pagamento foi rejeitada pelo banco recebedor. |
| PXP000022 | DS0G | 403 | 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. |
| PXP000023 | DT02 | 400 | Invalid datetime for message delivery. | Data e Hora do envio da mensagem inválida. |
| PXP000024 | ED05 | 400 | Error while processing payment (generic error). | Erro no processamento do pagamento (erro genérico). |
| PXP000025 | FF08 | 400 | Badly formatted operation's identifier. | Identificador da operação mal formatado. |
| PXP000026 | RC09 | 400 | Invalid or non-existent payer's PSP ISPB number. | Número ISPB do PSP do Pagador é inválido ou inexistente. |
| PXP000027 | RC10 | 400 | Invalid or non-existent beneficiary's PSP ISPB number. | Número ISPB do banco recebedor é inválido ou inexistente. |
| PXP000043 | DS27 | 400 | Invalid or non-existent ISPB number. | Número ISPB é inválido ou inexistente. |
| PXP000044 | AM02 | 400 | Amount too great for credited account. | Valor de pagamento/devolução acima do permitido para a conta de destino creditada. |
| PXP000028 | JDPISPI001 | 500 | Insufficient funds on JDPI managed PI account. | Saldo insuficiente na conta PI gerenciada pelo JDPI. |
| PXP000029 | JDPISPI002 | 500 | SPI has returned admi.002 message. N/A. | SPI retornou mensagem admi.002. Erro retornado na mensagem: N/A. |
| PXP000030 | JDPISPI003 | 500 | Insufficient funds on PSP sub-account. | Saldo insuficiente na subconta do PSP. |
| PXP000031 | JDPISPI004 | 500 | General failure during debt on JDPI managed PI account. | Falha geral ao realizar o débito em conta PI gerenciada pelo JDPI. |
| PXP000001 | JDPICHV001 | 404 | Pix key not found. | Chave Pix não encontrada. |
| PXP000002 | JDPICHV002 | 404 | Account has no pix keys linked. | Conta não possui nenhuma chave pix. |
| PXP000003 | JDPICHV003 | 404 | CPF/CNPJ has no pix keys linked. | CPF/CNPJ informada não possui nenhuma chave pix vinculada. |
| PXP000004 | JDPICHV004 | 400 | Pix key already linked on DICT. | Chave pix já está vinculada. |
| PXP000005 | JDPICHV005 | 400 | Pix key is linked to another person. Claim recommended. | Chave pix existe mas está possuída por outra pessoa. Reivindicação de posse recomendada. |
| PXP000006 | JDPICHV006 | 400 | Pix key is linked on another account of the same owner. Key alteration recommended. | Chave pix está vinculada a outra conta com o mesmo dono. Alteração de chave recomendada. |
| PXP000033 | JDPICHV007 | 400 | Missing new account or client name on pix key alteration request. | Nova conta ou nome do cliente faltando no pedido de alteração de chave pix. |
| PXP000034 | JDPICHV008 | 400 | Wrong field for trading name on natural person pix key alteration. | Campo para nome fantasia incorreto para alteração de chave pix pessoa física.recomendada. |
| PXP000035 | JDPICHV009 | 400 | Missing account type, account number, account created at, name or trading name on key alteration request. | Dados incompletos para alteração de chave pix. Faltando tipo de conta, número da conta, data de abertura, nome ou nome fantasia. |
| PXP000042 | JDPIRVN011 | 400 | Claim current status does not allow conclusion. | A situação da sua Reivindicação não permite a sua conclusão. |
| PXP000041 | JDPIRVN014 | 400 | Claim Key Not Found. | Chave a ser reivindicada não encontrada. |
| PXP000046 | EntryKeyInCustodyOfDifferentParticipant | 400 | There is already a link for this key with the same owner, but it is associated with another participant. It is indicated that a portability claim be made. | Já existe vínculo para essa chave com o mesmo dono, mas ela encontra-se associada a outro participante. Indica-se que seja feita uma reivindicação de portabilidade. |
| PXP000047 | RateLimited | 429 | Connection was refused by BACEN. Max requests per minute has been exceeded. | A requisição foi recusada pelo BACEN. A quantidade máxima de requisições por minuto foi excedida. |
---
# Listar chaves Pix de uma conta
URL: /documentation/pix/listar_chaves_pix
## Request
ENDPOINT /baas/pix/keys
MÉTODO GET
## Query Params
| Campo | Tipo | Descrição | Caracteres |
|------------------|--------|-------------------------------------------------------------------------------------------------------------------------|------------|
| `account_key`* | string | Chave uuid da conta. | Chave uuid |
| `pix_key_status` | enum | **[Enumerador Pix Key Status](#Pix-Key-Status)** Enumerador indicando o status das chaves pix que devem ser retornadas. | - |
### Enumerador _Pix Key Status_
| Enumerador | Descrição |
|----------------------------------------|-----------------------------------------------------------------|
| **pending_confirmation** | Pendente de confirmação |
| **active** | Ativa |
| **inactivated** | Inativa |
| **pending_claim_request_confirmation** | Pendente de confirmação do pedido de portabilidade de chave Pix |
## Response
STATUS 200
Response Body
```json
[
{
"account_key": "6d30a0b1-cb90-4ceb-b1ea-5bd600cdf3c8",
"pix_key": "63927180432",
"pix_key_status": "active",
"pix_key_type": "cpf",
"updated_at": "2022-09-02T20:00:36",
"created_at": "2022-09-02T20:00:36"
},
{
"account_key": "40cea00e-9d99-46f9-b55f-dbafa84553a9",
"pix_key": "+5562985013819",
"pix_key_status": "pending_confirmation",
"pix_key_type": "phone_number",
"updated_at": "2022-09-02T20:00:36",
"created_at": "2022-09-02T20:00:36"
},
{
"account_key": "0ebc3bfb-be25-4093-adf2-f0cdee6f5e69",
"pix_key": "address@email.com",
"pix_key_status": "pending_confirmation",
"pix_key_type": "email",
"updated_at": "2022-09-02T20:00:36",
"created_at": "2022-09-02T20:00:36"
}
]
```
STATUS 400
Response Body
```json
{
"data": "{\"title\": \"Bad Request\", \"description\": \"Invalid request body.\", \"translation\": \"Corpo da requisição inválido.\", \"extra_fields\": {}, \"code\": \"LEG000069\"}"
}
```
---
# MED 2.0 — Consultar Recuperações de Valores
URL: /documentation/pix/med/consultar_recuperacao_de_valores
Além dos webhooks de acompanhamento, você pode consultar as recuperações de valores abertas contra a sua conta: a listagem devolve todas as recuperações recebidas, e a consulta individual devolve o detalhe de uma recuperação a partir do seu `funds_recovery_id` — o mesmo identificador recebido no webhook.
## Listar recuperações de valores
ENDPOINT /internal/pix/funds_recovery/incoming
MÉTODO GET
### Query params
| Campo | Tipo | Descrição |
| ----------------------- | ------- | -------------------------------------------------------------------------------------------------------- |
| `funds_recovery_status` | string | Filtra pelo status da recuperação: `awaiting_analysis`, `pending_approval`, `completed` ou `cancelled`. |
| `initial_date` | string | Filtra recuperações criadas a partir desta data. Formato `YYYY-MM-DD`. |
| `final_date` | string | Filtra recuperações criadas até esta data. Formato `YYYY-MM-DD`. |
| `page_number` | integer | Página da listagem. Padrão: `1`. |
| `page_size` | integer | Itens por página. Padrão: `10`, máximo: `30`. |
### Response
STATUS 200
Response Body
```json
{
"data": [
{
"funds_recovery_key": "9eb5f452-81fd-4f67-9f2a-49e14e53ef64",
"funds_recovery_id": "b8d19bd4-51dc-4784-a2ad-52807c6dfc80",
"infraction_report_id": "3541127e-cbc9-44f6-bb0e-3e346ddaefb4",
"pix_transfer_key": "957ef961-1824-47e6-90fd-f8b4775a1e1c",
"target_account_key": "6711e3cf-fdf4-41b4-88e8-0a31cb83b9f4",
"target_person_key": "4f6ea994-e53a-4ef8-b2b0-89d14c4667bc",
"end_to_end_id": "E12345678202607161648s188f18bJty",
"funds_recovery_status": "awaiting_analysis",
"situation_type": "scam",
"report_details": "Transação acusada como fraudulenta pelo originador.",
"infraction_amount": 150.50,
"credited_participant": "32402502",
"debited_participant": "12345678",
"analysis_result": null,
"analysis_details": null,
"blocked_balance_status": "completelly_blocked",
"tracking_graph": null,
"funds_recovery_status_events": [
{
"old_status": null,
"new_status": "awaiting_analysis",
"created_at": "2026-07-16T16:48:43Z"
}
],
"updated_at": "2026-07-16T16:48:43Z",
"created_at": "2026-07-16T16:48:43Z"
}
],
"pagination": {
"current_page": 1,
"next_page": null,
"rows_per_page": 10
}
}
```
| Campo | Tipo | Descrição |
| -------- | ----- | ------------------------------------------------------------------------------------------------------------------------------------ |
| `data` * | array | Lista de recuperações de valores abertas contra a sua conta, da mais recente para a mais antiga. **[Objeto funds_recovery](./recebimento_recuperacao_de_valores.md#objeto-funds_recovery)** |
| `pagination` * | object | Dados de paginação: `current_page`, `next_page` (nulo na última página) e `rows_per_page`. |
## Consultar uma recuperação de valores
ENDPOINT /internal/pix/funds_recovery/incoming/ FUNDS_RECOVERY_ID
MÉTODO GET
### Path params
| Campo | Tipo | Descrição | Caracteres |
| --------------------- | ------ | ------------------------------------------------------------------------------ | ---------- |
| `FUNDS_RECOVERY_ID` * | string | Identificador da recuperação de valores no Bacen (`funds_recovery_id`). | 32 |
### Response
STATUS 200
A resposta é o **[objeto funds_recovery](./recebimento_recuperacao_de_valores.md#objeto-funds_recovery)**, incluindo o histórico de eventos de status (`funds_recovery_status_events`) e, quando a recuperação já foi respondida, o campo `client_awnser`.
---
# Mecanismo Especial de Devolução do PIX (MED)
URL: /documentation/pix/med/introducao
O Banco central desenvolveu um sistema de integração entre bancos com o objetivo de diminuir as ocorrências e a gravidade das fraudes cometidas envolvendo transações monetárias no escopo do PIX. O sistema consiste em duas entidades: o relato de infração e o pedido de devolução, sendo que para clientes internos da QI Tech, por questões de segurança, o gerenciamento das mesmas é realizado internamente, evitando possíveis fraudes.
O fluxo normalmente seguido é, ao identificar uma transação fraudulenta, o participante originador deve abrir um relato de infração, o qual o participante de destino deve apurar e, num período de 7 dias, responder acatando ou não o mesmo. Caso seja acatado, o participante originador novamente pode abrir um pedido de devolução relativo à infração, o qual deve ser acatado pelo participante recebedor.
---
# Recebimento de Pedidos de Devolução
URL: /documentation/pix/med/recebimento_pedidos_de_devolucao
Ao contrário de relatos de infração, os pedidos de devolução, desde que de acordo com algumas diretrizes, devem, sempre que possível, serem fechados com aceite, a não ser que a conta esteja fechada ou sem saldo. Dito isso, o cliente apenas receberá os webhooks de atualização de status do pedido de devolução, não sendo algo contestável, visto que as razões para se abrir um pedido de devolução pelo MED são ou devido a um relato de infração já aceito, ou outro participante abrindo vido a uma falha operacional.
## Webhook de um incoming refund request
Um incoming refund request é uma devolução aberta por outro banco, onde o dono da conta é o alvo da transação contestada.
## Webhook request body
Webhook: incoming refund request
```json
{
"event_datetime": "2024-07-16T16:48:43Z",
"key": "0dedf537-a75e-4945-be1d-5d278c623022",
"data": {
"refund_request_key": "9eb5f452-81fd-4f67-9f2a-49e14e53ef64",
"infraction_report_key": "3541127e-cbc9-44f6-bb0e-3e346ddaefb4",
"target_account_key": "6711e3cf-fdf4-41b4-88e8-0a31cb83b9f4",
"refund_request_type": "fraud",
"blocked_balance_status": "completelly_blocked",
"pix_transfer_key": "957ef961-1824-47e6-90fd-f8b4775a1e1c",
"end_to_end_id": "E12345678202404302308s188f18bJty",
"requesting_participant": "18236120",
"contested_participant": "32402502",
"refund_request_details": null,
"refund_payment_event": null,
"requested_amount": 40,
"refunded_amount": 0,
"refund_request_status": "open",
"analysis_result": null,
"analysis_details": null,
"reject_reason": null,
"updated_at": "2024-07-16T19:48:43Z",
"created_at": "2024-07-16T19:48:43Z"
},
"status": "open",
"webhook_type": "incoming.internal_refund_request"
}
```
| Campo | Tipo | Descrição | Caracteres |
| ------------------ | ------ | ------------------------------------------------ | ----------------------------------------------------------------------------- |
| `event_datetime` * | string | Data e hora de criação da transação. | 20 |
| `key` * | string | Chave única de identificação do envio do evento. | 32 |
| `data` * | string | Objeto incoming refund request data. | **[Objeto incoming_refund_request](#objeto-incoming_refund_request)** |
| `status` * | string | Status da devolução. | **[Enumeradores refund_request_status](#enumeradores-refund_request_status)** |
### Enumeradores refund_request_status
| Enumerador | Descrição |
| ----------- | --------------------------------------- |
| `open` | Pedido recebido, e pendente de análise. |
| `closed` | Análise concluída e pedido fechado. |
| `cancelled` | Pedido cancelado pelo originados. |
### Objeto incoming_refund_request
| Campo | Tipo | Descrição | Caracteres |
| -------------------------- | ------ | -------------------------------------------------------- | ----------------------------------------------------------------------------------------------- |
| `refund_request_key` * | string | UUID4 identificador da devolução no Bacen. | 32 |
| `infraction_report_key` | string | UUID4 identificador da infração relacionada no Bacen. | 32 |
| `target_account_key` * | string | Account key da conta de destino da transação original. | 32 |
| `refund_request_type` * | string | Tipo do pedido de devolução. | **[Enumeradores refund_request_type](#enumeradores-refund_request_type)** |
| `pix_transfer_key` * | string | Pix transfer key da transação original. | 32 |
| `end_to_end_id` * | string | end_to_end_id da transação original. | 32 |
| `requesting_participant` * | string | Participante que originou a transação. | 8 |
| `contested_participant` * | string | Participante que recebeu a transação. | 8 |
| `refund_request_details` | string | Detalhes da devolução, enviados pelo outro participante. | 2000 |
| `refund_payment_event` | string | Evento de realização da devolução. | **[Objeto refund_payment_event](#objeto-refund_payment_event)** |
| `requested_amount` * | float | Valor requisitado na devolução. | 2000 |
| `refunded_amount` * | float | Valor total devolvido. | 2000 |
| `refund_request_status` * | string | Status da devolução. | **[Enumeradores refund_request_status](#enumeradores-refund_request_status)** |
| `analysis_result` | string | Resultado da análise. Decidido pela QI Tech. | **[Enumeradores refund_request_analysis_result](#enumeradores-refund_request_analysis_result)** |
| `analysis_details` | string | Justificativa do resultado da análise. | 200 |
| `reject_reason` | string | Motivo de rejeição do pedido. | **[Enumeradores refund_request_reject_reason](#enumeradores-refund_request_reject_reason)** |
| `blocked_balance_status` * | string | Status do bloqueio de saldo da conta de destino. | **[Enumeradores blocked_balance_status](#enumeradores-blocked_balance_status)** |
| `created_at` * | string | Data e hora de alteração da transação. | 20 |
| `updated_at` * | string | Data e hora de criação da transação. | 20 |
### Objeto refund_payment_event
| Campo | Tipo | Descrição | Caracteres |
| ---------------------- | ------ | ------------------------------------------- | ---------- |
| `refund_end_to_end_id` | string | end_to_end_id da transação de devolução. | 32 |
| `refund_transfer_key` | string | Pix transfer key da transação de devolução. | 32 |
| `refund_amount` | string | Valor da transação de devolução. | |
| `created_at` | string | Data e hora de criação da transação. | 20 |
### Enumeradores refund_request_analysis_result
| Enumerador | Descrição |
| -------------------- | -------------------------------------------------------------------------------------------------------------- |
| `totally_accepted` | Devolução realizada de todos os valores requisitados. |
| `partially_accepted` | Devolução parcial por falta de saldo. Monitorando conta para realizar posteriores devoluções. |
| `rejected` | Devolução rejeitada e nenhum recurso foi devolvido. Se motivo for por falta de saldo, a conta será monitorada. |
### Enumeradores refund_request_type
| Enumerador | Descrição |
| ------------------ | ------------------------------------------------------------------------------------------------ |
| `fraud` | Aberta posterior ao aceite de um relato de infração. |
| `operational_flaw` | Aberta sem um relato de infração, utilizada para corrigir falhas operacionais dos participantes. |
| `refund_cancelled` | Correção de uma devolução realizada erroneamente. |
### Enumeradores blocked_balance_status
| Enumerador | Descrição |
| --------------------- | --------------------------------------------------------------------------------- |
| `no_balance` | Conta do cliente sem saldo. Monitorando saldo pendente. |
| `completelly_blocked` | Recursos equivalentes à transação completamente bloqueados. |
| `partially_blocked` | Recursos equivalentes à transação parcialmente bloqueados. Monitorando saldo. |
| `settled` | Infração aceita, e pagamento do pedido de devolução realizado. |
| `partially_settled` | Infração aceita, e pagamento do pedido de devolução parcialmente realizado. |
| `released` | Recursos liberados, seja por cancelamento da infração ou fechamento em desacordo. |
### Enumeradores refund_request_reject_reason
| Enumerador | Descrição |
| ----------------- | ------------------------------------------------------------------- |
| `no_balance` | Conta do cliente sem saldo. Monitorando saldo pendente. |
| `account_closure` | Relacionamento com cliente encerrado. Impossível realizar devolução |
| `other` | Outro motivo, não aplicável nos listados acima. |
:::info
O monitoramento de saldo de uma conta com devolução parcial tem um limite de 90 dias após a transação original ocorrer.
:::
## Webhook de um outgoing refund request
### Um outgoing refund request é pedido de devolução aberto pela QI, tendo como alvo outro participante.
## Webhook request body
Webhook: outgoing refund request
```json
{
"event_datetime": "2024-07-22T10:31:09Z",
"key": "15d91f4b-a55c-41a6-9c46-2704253a1cf7",
"data": {
"refund_request_key": "5f98671e-9ec0-4ed7-95a9-061861243efc",
"pix_transfer_key": "d04e0858-ea91-4dab-8089-a27d6cc68235",
"source_account_key": "134ad635-ce80-4c8c-bca0-9dd3e8251317",
"end_to_end_id": "E32402502202404302308s188f18bJty",
"requested_amount": 78.5,
"refund_request_status": "open",
"infraction_report_key": "3b727ade-a736-473e-91a6-07b841253f55",
"refund_request_type": "fraud",
"refund_request_details": "Infraction aceita, favor realizar devolução de recursos.",
"requesting_participant": "32402502",
"contested_participant": "12345678",
"analysis_result": null,
"analysis_details": null,
"reject_reason": null,
"refund_payment_event": null,
"updated_at": "2024-07-16T19:48:43Z",
"created_at": "2024-07-16T19:48:43Z",
},
"status": "open",
"webhook_type": "outgoing.internal_refund_request"
}
```
| Campo | Tipo | Descrição | Caracteres |
| ------------------ | ------ | ------------------------------------------------ | ----------------------------------------------------------------------------- |
| `event_datetime` * | string | Data e hora de criação da transação. | 20 |
| `key` * | enum | Chave única de identificação do envio do evento. | 32 |
| `data` * | string | Objeto outgoing infraction report data. | **[Objeto outgoing_refund_request](#objeto-outgoing_refund_request)** |
| `status` * | string | Status da devolução. | **[Enumeradores refund_request_status](#enumeradores-refund_request_status)** |
### Objeto outgoing_refund_request
| Campo | Tipo | Descrição | Caracteres |
| -------------------------- | ------ | -------------------------------------------------------- | ----------------------------------------------------------------------------------------------- |
| `refund_request_key` * | string | UUID4 identificador da devolução no Bacen. | 32 |
| `infraction_report_key` | string | UUID4 identificador da infração relacionada no Bacen. | 32 |
| `source_account_key` * | string | Account key da conta de origem da transação. | 32 |
| `refund_request_type` * | string | Tipo do pedido de devolução. | **[Enumeradores refund_request_type](#enumeradores-refund_request_type)** |
| `pix_transfer_key` * | string | Pix transfer key da transação original. | 32 |
| `end_to_end_id` * | string | end_to_end_id da transação original. | 32 |
| `requesting_participant` * | string | Participante que originou a transação. | 8 |
| `contested_participant` * | string | Participante que recebeu a transação. | 8 |
| `refund_request_details` | string | Detalhes da devolução, enviados pelo outro participante. | 2000 |
| `refund_payment_event` | string | Evento de realização da devolução. | **[Objeto refund_payment_event](#objeto-refund_payment_event)** |
| `requested_amount` * | float | Valor requisitado na devolução. | 2000 |
| `refund_request_status` * | string | Status da devolução. | **[Enumeradores refund_request_status](#enumeradores-refund_request_status)** |
| `analysis_result` | string | Resultado da análise. Decidido pela QI Tech. | **[Enumeradores refund_request_analysis_result](#enumeradores-refund_request_analysis_result)** |
| `analysis_details` | string | Justificativa do resultado da análise. | 200 |
| `reject_reason` | string | Motivo de rejeição do pedido. | **[Enumeradores refund_request_reject_reason](#enumeradores-refund_request_reject_reason)** |
| `created_at` * | string | Data e hora de alteração da transação. | 20 |
| `updated_at` * | string | Data e hora de criação da transação. | 20 |
---
# MED 2.0 — Recebimento de Recuperação de Valores
URL: /documentation/pix/med/recebimento_recuperacao_de_valores
O MED 2.0 introduz a **recuperação de valores** (funds recovery), que unifica em um único fluxo o relato de infração e o pedido de devolução de uma transação PIX contestada. Ao receber uma recuperação de valores contra uma conta, a QI Tech automaticamente bloqueia de forma cautelar o recurso equivalente à transação contestada e envia uma notificação via webhook, dando a você a oportunidade de justificar a legitimidade da transação antes do fechamento.
O ciclo de vida de uma recuperação de valores recebida é:
1. **`awaiting_analysis`** — recuperação recebida e saldo bloqueado; aguardando a sua resposta, que deve ser enviada no prazo máximo de **5 dias**.
2. **`pending_approval`** — resposta enviada (justificativa + arquivo de evidências); em análise pela QI Tech.
3. **`completed`** — fechada pela QI Tech, acatando (`agreed`) ou recusando (`disagreed`) a recuperação.
4. **`cancelled`** — cancelada pelo participante originador.
Toda a comunicação de acompanhamento é realizada via webhooks.
## Webhook de uma incoming funds recovery
Uma incoming funds recovery é uma recuperação de valores aberta por outro participante, onde a sua conta é o alvo da transação contestada.
:::info Observação
Os webhooks de recuperação de valores são enviados com `webhook_type` **`incoming.internal_infraction_report`**. Para diferenciá-los dos relatos de infração, verifique a presença do campo `funds_recovery_key` no objeto `data`.
:::
Webhook: incoming funds recovery
```json
{
"event_datetime": "2026-07-16T16:48:43Z",
"key": "0dedf537-a75e-4945-be1d-5d278c623022",
"data": {
"funds_recovery_key": "9eb5f452-81fd-4f67-9f2a-49e14e53ef64",
"funds_recovery_id": "b8d19bd4-51dc-4784-a2ad-52807c6dfc80",
"infraction_report_id": "3541127e-cbc9-44f6-bb0e-3e346ddaefb4",
"pix_transfer_key": "957ef961-1824-47e6-90fd-f8b4775a1e1c",
"target_account_key": "6711e3cf-fdf4-41b4-88e8-0a31cb83b9f4",
"target_person_key": "4f6ea994-e53a-4ef8-b2b0-89d14c4667bc",
"end_to_end_id": "E12345678202607161648s188f18bJty",
"funds_recovery_status": "awaiting_analysis",
"situation_type": "scam",
"report_details": "Transação acusada como fraudulenta pelo originador.",
"infraction_amount": 150.50,
"contact_email": "contato@participante.com.br",
"contact_phone_number": "+5511999999999",
"credited_participant": "32402502",
"debited_participant": "12345678",
"client_details": null,
"analysis_result": null,
"analysis_details": null,
"blocked_balance_status": "completelly_blocked",
"tracking_graph": null,
"updated_at": "2026-07-16T16:48:43Z",
"created_at": "2026-07-16T16:48:43Z"
},
"status": "awaiting_analysis",
"webhook_type": "incoming.internal_infraction_report"
}
```
### Objeto funds_recovery
| Campo | Tipo | Descrição | Caracteres |
| ------------------------- | ------ | ------------------------------------------------------------------------- | -------------------------------------------------------------------------------------------- |
| `funds_recovery_key` * | string | UUID4 identificador da recuperação de valores na QI Tech. | 32 |
| `funds_recovery_id` * | string | Identificador da recuperação de valores no Bacen. Usado nas consultas e na resposta. | 32 |
| `infraction_report_id` * | string | Identificador da infração que originou a recuperação no Bacen. | 32 |
| `pix_transfer_key` * | string | Pix transfer key da transação original. | 32 |
| `target_account_key` * | string | Account key da conta de destino da transação original. | 32 |
| `target_person_key` * | string | Person key do alvo da recuperação. | 32 |
| `end_to_end_id` * | string | end_to_end_id da transação original. | 32 |
| `funds_recovery_status` * | string | Status da recuperação de valores. | **[Enumeradores funds_recovery_status](#enumeradores-funds_recovery_status)** |
| `situation_type` * | string | Situação apontada pelo originador. | **[Enumeradores situation_type](#enumeradores-situation_type)** |
| `report_details` | string | Detalhes enviados pelo participante originador. | 2000 |
| `infraction_amount` | number | Valor contestado. Quando ausente, considera-se o valor total da transação. | - |
| `contact_email` | string | E-mail de contato do participante originador. | 255 |
| `contact_phone_number` | string | Telefone de contato do participante originador. | 20 |
| `credited_participant` * | string | Participante que recebeu a transação. | 8 |
| `debited_participant` * | string | Participante que originou a transação. | 8 |
| `client_awnser` | string | Justificativa enviada na resposta. Presente após responder. | 2000 |
| `analysis_result` | string | Resultado da análise. Decidido pela QI Tech. | **[Enumeradores analysis_result](#enumeradores-analysis_result)** |
| `analysis_details` | string | Justificativa do resultado da análise. | 2000 |
| `blocked_balance_status` * | string | Status do bloqueio de saldo da conta de destino. | **[Enumeradores blocked_balance_status](#enumeradores-blocked_balance_status)** |
| `tracking_graph` | object | Grafo de rastreamento das movimentações dos recursos contestados, quando disponível. | - |
| `created_at` * | string | Data e hora de criação. | 20 |
| `updated_at` * | string | Data e hora de alteração. | 20 |
### Enumeradores funds_recovery_status
| Enumerador | Descrição |
| ------------------- | --------------------------------------------------------------------------- |
| `awaiting_analysis` | Recuperação recebida e saldo bloqueado, aguardando a sua resposta. |
| `pending_approval` | Justificativa enviada, aguardando análise interna da QI Tech. |
| `completed` | Fechada pela QI Tech após a análise. |
| `cancelled` | Cancelada pelo participante originador. |
### Enumeradores situation_type
| Enumerador | Descrição |
| ------------------- | ------------------------------------------------------- |
| `scam` | Causa de golpe ou estelionato. |
| `account_takeover` | Causa de transação não autorizada pela conta de origem. |
| `coercion` | Causa de crime de coerção. |
| `fraudulent_access` | Causa de acesso fraudulento à conta de origem. |
| `other` | Quaisquer causas não aplicáveis às listadas acima. |
### Enumeradores analysis_result
| Enumerador | Descrição |
| ----------- | ---------------------------------------------------------------- |
| `agreed` | A QI Tech acata a recuperação de valores e os recursos bloqueados são devolvidos. |
| `disagreed` | A QI Tech recusa a recuperação de valores e os recursos bloqueados são liberados. |
### Enumeradores blocked_balance_status
| Enumerador | Descrição |
| --------------------- | ------------------------------------------------------------------------------- |
| `completelly_blocked` | Recursos equivalentes ao valor contestado completamente bloqueados. |
| `partially_blocked` | Recursos equivalentes ao valor contestado parcialmente bloqueados. Monitorando saldo. |
| `no_balance` | Conta sem saldo. Monitorando saldo pendente. |
| `account_closed` | Conta encerrada. Nenhum recurso bloqueado. |
---
# Recebimento de Relatos de Infração
URL: /documentation/pix/med/recebimento_relatos_de_infracao
Ao receber um relato de infração, a QI Tech automaticamente bloqueará o recurso da conta equivalente à transação contestada, e enviará notificações de acompanhamento sobre todo o ciclo da infração, inclusive dando chance do cliente justificar a transação, entretanto, vale ressaltar que a decisão final sobre acatar ou não uma infração partirá da QI Tech. Toda a comunicação relativa às infrações são realizadas via webhooks.
## Webhook de uma incoming infraction report
Uma incoming infraction report é uma infração aberta por outro banco, onde o dono da conta é o alvo da transação contestada.
## Webhook request body
Webhook: incoming infraction report
```json
{
"event_datetime": "2024-07-22T10:31:09Z",
"key": "15d91f4b-a55c-41a6-9c46-2704253a1cf7",
"data": {
"target_person_key": "4f6ea994-e53a-4ef8-b2b0-89d14c4667bc",
"end_to_end_id": "E12345678202407171627342xlR8KpoD",
"pix_transfer_key": "6cf241f8-328a-4813-90ab-2aef74d853ac",
"target_account_key": "9d5b1a98-03ac-4202-91e8-29dbff3d1108",
"infraction_report_status": "pending_client_awnser",
"infraction_report_situation": "fraudulent_access",
"analysis_result": null,
"analysis_details": null,
"infraction_report_type": "refund_request",
"debited_participant": "12345678",
"credited_participant": "32402502",
"blocked_balance_status": "completelly_blocked",
"infraction_report_key": "90b4e1bc-89bc-4df8-98a2-f912447b178f",
"infraction_report_details": "Transação acusada como fraudulenta pelo originador.",
"client_details": null,
"created_at": "2024-07-22T13:31:09Z",
"updated_at": "2024-07-22T13:31:09Z",
},
"status": "pending_client_awnser",
"webhook_type": "incoming.internal_infraction_report"
}
```
| Campo | Tipo | Descrição | Caracteres |
| ------------------ | ------ | ------------------------------------------------ | ----------------------------------------------------------------------------------------------------- |
| `event_datetime` * | string | Data e hora de criação da transação. | 20 |
| `key` * | enum | Chave única de identificação do envio do evento. | 32 |
| `data` * | string | Objeto incoming infraction report data. | **[Objeto incoming_infraction_report](#objeto-incoming_infraction_report)** |
| `status` * | string | Status da infração. | **[Enumeradores incoming_infraction_report_status](#enumeradores-incoming_infraction_report_status)** |
### Objeto incoming_infraction_report
| Campo | Tipo | Descrição | Caracteres |
| ------------------------------- | ------ | ------------------------------------------------------------ | ----------------------------------------------------------------------------------------------------- |
| `target_person_key` * | string | Person key do alvo da infração. | 32 |
| `end_to_end_id` * | string | end_to_end_id da transação original. | 32 |
| `pix_transfer_key` * | string | Pix transfer key da transação original. | 32 |
| `target_account_key` * | string | Account key da conta de destino da transação original. | 32 |
| `infraction_report_status` * | string | Status da infração. | **[Enumeradores incoming_infraction_report_status](#enumeradores-incoming_infraction_report_status)** |
| `infraction_report_situation` * | string | Situação da infração. | **[Enumeradores infraction_report_situation](#enumeradores-infraction_report_situation)** |
| `analysis_result` | string | Resultado da análise. Decidido pela QI Tech. | **[Enumeradores infraction_report_analysis_result](#enumeradores-infraction_report_analysis_result)** |
| `analysis_details` | string | Justificativa do resultado da análise. | 200 |
| `infraction_report_type` * | string | Tipo do relato de infração. | **[Enumeradores infraction_report_type](#enumeradores-infraction_report_type)** |
| `debited_participant` * | string | Participante que originou a transação. | 8 |
| `credited_participant` * | string | Participante que recebeu a transação. | 8 |
| `blocked_balance_status` * | string | Status do bloqueio de saldo da conta de destino. | **[Enumeradores blocked_balance_status](#enumeradores-blocked_balance_status)** |
| `infraction_report_key` * | string | UUID4 identificador da transação no Bacen. | 32 |
| `infraction_report_details` | string | Detalhes da infração, enviados pelo outro participante. | 2000 |
| `client_details` | string | Detalhes fornecidos pelo cliente sobre a transação original. | 2000 |
| `created_at` * | string | Data e hora de alteração da transação. | 20 |
| `updated_at` * | string | Data e hora de criação da transação. | 20 |
### Enumeradores incoming_infraction_report_status
| Enumerador | Descrição |
| ----------------------- | -------------------------------------------------------------- |
| `pending_client_awnser` | Infração recebida, aguardando justificativa do cliente. |
| `pending_approval` | Justificativa enviada, aguardando aprovação interna. |
| `automatically_closed` | Fechado automaticamente devido a falta de resposta do cliente. |
| `manually_closed` | Fechado pela QI Tech após análise da resposta do cliente. |
| `cancelled` | Cancelada pelo originador. |
### Enumeradores infraction_report_situation
| Enumerador | Descrição |
| ------------------- | ------------------------------------------------------- |
| `scam` | Causa de golpe ou estelionato. |
| `account_takeover` | Causa de transação não autorizada pela conta de origem. |
| `coercion` | Causa de crime de coerção. |
| `fraudulent_access` | Causa de acesso fraudulento à conta de origem. |
| `other` | Quaisquer causas não aplicáveis às listadas acima. |
### Enumeradores infraction_report_analysis_result
| Enumerador | Descrição |
| ----------- | ----------------------------------------------------------------------------------------- |
| `agreed` | O Participante Indireto concorda com o Relato de Infração criado pelo outro Participante. |
| `disagreed` | O Participante Indireto discorda com o Relato de Infração criado pelo outro Participante. |
### Enumeradores infraction_report_type
| Enumerador | Descrição |
| ------------------ | ---------------------------------------------------------------------- |
| `refund_cancelled` | Relato de infração será gerado pelo motivo de uma devolução cancelada. |
| `refund_request` | Relato de infração será gerado a fim de se solicitar uma devolução. |
### Enumeradores blocked_balance_status
| Enumerador | Descrição |
| --------------------- | --------------------------------------------------------------------------------- |
| `no_balance` | Conta do cliente sem saldo. Monitorando saldo pendente. |
| `completelly_blocked` | Recursos equivalentes à transação completamente bloqueados. |
| `partially_blocked` | Recursos equivalentes à transação parcialmente bloqueados. Monitorando saldo. |
| `settled` | Infração aceita, e pagamento do pedido de devolução realizado. |
| `partially_settled` | Infração aceita, e pagamento do pedido de devolução parcialmente realizado. |
| `released` | Recursos liberados, seja por cancelamento da infração ou fechamento em desacordo. |
:::info
Uma infração será fechada automaticamente aceitando caso o cliente não responda à infração em 5 dias.
:::
## Webhook de uma outgoing infraction report
### Uma outgoing infraction report é uma infração aberta pela QI, tendo como alvo outro participante.
## Webhook request body
Webhook: outgoing infraction report
```json
{
"event_datetime": "2024-07-22T10:31:09Z",
"key": "15d91f4b-a55c-41a6-9c46-2704253a1cf7",
"data": {
"infraction_report_key": "4f6ea994-e53a-4ef8-b2b0-89d14c4667bc",
"pix_transfer_key": "6cf241f8-328a-4813-90ab-2aef74d853ac",
"source_account_key": "9d5b1a98-03ac-4202-91e8-29dbff3d1108",
"end_to_end_id": "E32402502202407171627342xlR8KpoD",
"infraction_report_status": "open",
"infraction_report_situation": "account_takeover",
"infraction_report_type": "refund_request",
"infraction_report_details": "Transação fraudulenta.",
"debited_participant": "32402502",
"credited_participant": "12345678",
"analysis_result": null,
"analysis_details": null,
"updated_at": "2024-07-22T13:31:09Z",
"created_at": "2024-07-22T13:31:09Z",
},
"status": "open",
"webhook_type": "outgoing.internal_infraction_report"
}
```
| Campo | Tipo | Descrição | Caracteres |
| ------------------ | ------ | ------------------------------------------------ | -------------------------------------------------------------------------------------------- |
| `event_datetime` * | string | Data e hora de criação da transação. | 20 |
| `key` * | enum | Chave única de identificação do envio do evento. | 32 |
| `data` * | string | Objeto outgoing infraction report data. | **[Objeto outgoing_infraction_report](#objeto-outgoing_infraction_report)** |
| `status` * | string | Status da infração. | **[Enumeradores infraction_report_status](#enumeradores-outgoing_infraction_report_status)** |
### Objeto outgoing_infraction_report
| Campo | Tipo | Descrição | Caracteres |
| ------------------------------- | ------ | ------------------------------------------------------- | ----------------------------------------------------------------------------------------------------- |
| `infraction_report_key` * | string | UUID4 identificador da transação no Bacen. | 32 |
| `end_to_end_id` * | string | end_to_end_id da transação original. | 32 |
| `pix_transfer_key` * | string | Pix transfer key da transação original. | 32 |
| `source_account_key` * | string | Account key da conta de origem da transação original. | 32 |
| `infraction_report_status` * | string | Status da infração. | **[Enumeradores outgoing_infraction_report_status](#enumeradores-outgoing_infraction_report_status)** |
| `infraction_report_situation` * | string | Situação da infração. | **[Enumeradores infraction_report_situation](#enumeradores-infraction_report_situation)** |
| `infraction_report_type` * | string | Tipo do relato de infração. | **[Enumeradores infraction_report_type](#enumeradores-infraction_report_type)** |
| `infraction_report_details` | string | Detalhes da infração, enviados pela QI Tech. | 2000 |
| `debited_participant` * | string | Participante que originou a transação. | 8 |
| `credited_participant` * | string | Participante que recebeu a transação. | 8 |
| `analysis_result` | string | Resultado da análise. Decidido pelo outro participante. | **[Enumeradores infraction_report_analysis_result](#enumeradores-infraction_report_analysis_result)** |
| `analysis_details` | string | Justificativa do resultado da análise. | 200 |
| `created_at` * | string | Data e hora de alteração da transação. | 20 |
| `updated_at` * | string | Data e hora de criação da transação. | 20 |
### Enumeradores outgoing_infraction_report_status
| Enumerador | Descrição |
| ----------- | ------------------------------------------------ |
| `open` | Infração aberta e enviada ao outro participante. |
| `closed` | Infração respondida pelo outro participante. |
| `cancelled` | Infração cancelada pela QI Tech. |
---
# MED 2.0 — Responder Recuperação de Valores
URL: /documentation/pix/med/responder_recuperacao_de_valores
Enquanto a recuperação de valores está com status `awaiting_analysis`, você pode respondê-la justificando a legitimidade da transação. A resposta é composta por uma **explicação em texto** e um **arquivo .zip de evidências** (nota fiscal, comprovantes, etc.), enviados como **`multipart/form-data`**.
Após a resposta, a recuperação passa para o status **`pending_approval`**, seguindo para a etapa de análise.
:::caution Aviso
O prazo máximo para responder a um MED é de **5 dias**.
:::
## Identificador da recuperação de valores
O identificador utilizado na rota é o campo **`funds_recovery_id`**, recebido no **[webhook de incoming funds recovery](./recebimento_recuperacao_de_valores.md#webhook-de-uma-incoming-funds-recovery)** no momento da abertura da recuperação.
O mesmo identificador também pode ser obtido pela **[listagem de recuperações de valores](./consultar_recuperacao_de_valores.md#listar-recuperações-de-valores)**.
## Request
ENDPOINT /internal/pix/funds_recovery/incoming/ FUNDS_RECOVERY_ID
MÉTODO PATCH
### Path params
| Campo | Tipo | Descrição | Caracteres |
| --------------------- | ------ | ------------------------------------------------------------------------ | ---------- |
| `FUNDS_RECOVERY_ID` * | string | Identificador da recuperação de valores no Bacen (`funds_recovery_id`). | 32 |
### Form data
| Campo | Tipo | Descrição | Caracteres |
| ----------------- | ------ | --------------------------------------------------------------------------------------- | ---------- |
| `client_awnser` * | string | Sua interpretação acerca da transação apontada como fraudulenta. | 2000 |
| `file` * | file | Arquivo **.zip** com as evidências que sustentam a justificativa. Tamanho máximo: **50MB**. | - |
### Response
STATUS 200
Response Body
```json
{
"funds_recovery_key": "9eb5f452-81fd-4f67-9f2a-49e14e53ef64",
"funds_recovery_id": "b8d19bd4-51dc-4784-a2ad-52807c6dfc80",
"infraction_report_id": "3541127e-cbc9-44f6-bb0e-3e346ddaefb4",
"pix_transfer_key": "957ef961-1824-47e6-90fd-f8b4775a1e1c",
"target_account_key": "6711e3cf-fdf4-41b4-88e8-0a31cb83b9f4",
"target_person_key": "4f6ea994-e53a-4ef8-b2b0-89d14c4667bc",
"end_to_end_id": "E12345678202607161648s188f18bJty",
"funds_recovery_status": "pending_approval",
"situation_type": "scam",
"report_details": "Transação acusada como fraudulenta pelo originador.",
"infraction_amount": 150.50,
"credited_participant": "32402502",
"debited_participant": "12345678",
"client_awnser": "Transação legítima, conforme demonstrado na nota fiscal XXXXXXXXXX que confirma a venda do produto.",
"analysis_result": null,
"analysis_details": null,
"blocked_balance_status": "completelly_blocked",
"tracking_graph": null,
"funds_recovery_status_events": [
{
"old_status": null,
"new_status": "awaiting_analysis",
"created_at": "2026-07-16T16:48:43Z"
},
{
"old_status": "awaiting_analysis",
"new_status": "pending_approval",
"created_at": "2026-07-17T10:12:05Z"
}
],
"updated_at": "2026-07-17T10:12:05Z",
"created_at": "2026-07-16T16:48:43Z"
}
```
A resposta é o **[objeto funds_recovery](./recebimento_recuperacao_de_valores.md#objeto-funds_recovery)** atualizado, com `funds_recovery_status` = `pending_approval` e a justificativa em `client_awnser`.
### Erros
| Código | Status | Descrição |
| ----------- | ------ | ----------------------------------------------------------------------------------- |
| `MED000042` | 400 | A recuperação de valores não está com status `awaiting_analysis`. |
| `MED000043` | 400 | O arquivo enviado não é um arquivo **.zip**. |
| `MED000044` | 400 | O arquivo enviado excede o tamanho máximo de **50MB**. |
| `MED000039` | 404 | Recuperação de valores não encontrada para o `FUNDS_RECOVERY_ID` informado. |
---
# Responder Relatos de Infração
URL: /documentation/pix/med/resposta_relatos_de_infracao
O Banco central estipula um limite de 7 dias para a análise de relatos de infração, com o objetivo de manter a qualidade do serviço e do mecanismo de devolução. A QI Tech reserva até 5 dias para que o cliente responda à infração recebida justificando a legitmidade ou não da transação, e 2 dias para a análise interna e apuração dos fatos. Vale ressaltar que a palavra final para o aceite ou não de um relato cabe exclusivamente à QI Tech.
:::caution Aviso
Após o decorrer dos 5 dias, a infração será automaticamente fechada aceitando, caso o cliente não responda.
:::
## Request
ENDPOINT /internal/pix/infraction_report/incoming/ INFRACTION_REPORT_KEY
MÉTODO PATCH
Request Body
```json
{
"client_awnser": "Transação legítma, conforme demonstrado na nota fiscal XXXXXXXXXX que confirma a venda do produto.",
}
```
### Body params
| Campo | Tipo | Descrição | Caracteres |
| ----------------- | ------ | ----------------------------------------------------------------------- | ---------- |
| `client_awnser` * | string | Interpretação do cliente acerca da transação apontada como fraudulenta. | 2000 |
### Response
STATUS 200
Response Body
```json
{
"target_person_key": "4f6ea994-e53a-4ef8-b2b0-89d14c4667bc",
"end_to_end_id": "E12345678202407171627342xlR8KpoD",
"pix_transfer_key": "6cf241f8-328a-4813-90ab-2aef74d853ac",
"target_account_key": "9d5b1a98-03ac-4202-91e8-29dbff3d1108",
"infraction_report_status": "pending_approval",
"infraction_report_situation": "fraudulent_access",
"analysis_result": null,
"analysis_details": null,
"infraction_report_type": "refund_request",
"debited_participant": "12345678",
"credited_participant": "32402502",
"blocked_balance_status": "completelly_blocked",
"infraction_report_key": "90b4e1bc-89bc-4df8-98a2-f912447b178f",
"infraction_report_details": "Transação acusada como fraudulenta pelo originador.",
"client_details": "Transação legítma, conforme demonstrado na nota fiscal XXXXXXXXXX que confirma a venda do produto.",
"created_at": "2024-07-22T13:31:09Z",
"updated_at": "2024-07-22T13:31:09Z",
}
```
| Campo | Tipo | Descrição | Caracteres |
| ------------------------------ | ------ | ------------------------------------------------------------ | ----------------------------------------------------------------------------------------------------- |
| `target_person_key`* | string | Person key do alvo da infração. | 32 |
| `end_to_end_id`* | string | end_to_end_id da transação original. | 32 |
| `pix_transfer_key`* | string | Pix transfer key da transação original. | 32 |
| `target_account_key`* | string | Account key da conta de destino da transação original. | 32 |
| `infraction_report_status`* | string | Status da infração. | **[Enumeradores incoming_infraction_report_status](#enumeradores-incoming_infraction_report_status)** |
| `infraction_report_situation`* | string | Situação da infração. | **[Enumeradores infraction_report_situation](#enumeradores-infraction_report_situation)** |
| `analysis_result` | string | Resultado da análise. Decidido pela QI Tech. | **[Enumeradores infraction_report_analysis_result](#enumeradores-infraction_report_analysis_result)** |
| `analysis_details` | string | Justificativa do resultado da análise. | 200 |
| `infraction_report_type`* | string | Tipo do relato de infração. | **[Enumeradores infraction_report_type](#enumeradores-infraction_report_type)** |
| `debited_participant`* | string | Participante que originou a transação. | 8 |
| `credited_participant`* | string | Participante que recebeu a transação. | 8 |
| `blocked_balance_status`* | string | Status do bloqueio de saldo da conta de destino. | **[Enumeradores blocked_balance_status](#enumeradores-blocked_balance_status)** |
| `infraction_report_key`* | string | UUID4 identificador da transação no Bacen. | 32 |
| `infraction_report_details` | string | Detalhes da infração, enviados pelo outro participante. | 2000 |
| `client_details`* | string | Detalhes fornecidos pelo cliente sobre a transação original. | 2000 |
| `created_at`* | string | Data e hora de alteração da transação. | 20 |
| `updated_at`* | string | Data e hora de criação da transação. | 20 |
### Enumeradores incoming_infraction_report_status
| Enumerador | Descrição |
| ----------------------- | -------------------------------------------------------------- |
| `pending_client_awnser` | Infração recebida, aguardando justificativa do cliente. |
| `pending_approval` | Justificativa enviada, aguardando aprovação interna. |
| `automatically_closed` | Fechado automaticamente devido a falta de resposta do cliente. |
| `manually_closed` | Fechado pela QI Tech após análise da resposta do cliente. |
| `cancelled` | Cancelada pelo originador. |
### Enumeradores infraction_report_situation
| Enumerador | Descrição |
| ------------------- | ------------------------------------------------------- |
| `scam` | Causa de golpe ou estelionato. |
| `account_takeover` | Causa de transação não autorizada pela conta de origem. |
| `coercion` | Causa de crime de coerção. |
| `fraudulent_access` | Causa de acesso fraudulento à conta de origem. |
| `other` | Quaisquer causas não aplicáveis às listadas acima. |
### Enumeradores infraction_report_analysis_result
| Enumerador | Descrição |
| ----------- | ----------------------------------------------------------------------------------------- |
| `agreed` | O Participante Indireto concorda com o Relato de Infração criado pelo outro Participante. |
| `disagreed` | O Participante Indireto discorda com o Relato de Infração criado pelo outro Participante. |
### Enumeradores infraction_report_type
| Enumerador | Descrição |
| ------------------ | ---------------------------------------------------------------------- |
| `refund_cancelled` | Relato de infração será gerado pelo motivo de uma devolução cancelada. |
| `refund_request` | Relato de infração será gerado a fim de se solicitar uma devolução. |
### Enumeradores blocked_balance_status
| Enumerador | Descrição |
| --------------------- | --------------------------------------------------------------------------------- |
| `no_balance` | Conta do cliente sem saldo. Monitorando saldo pendente. |
| `completelly_blocked` | Recursos equivalentes à transação completamente bloqueados. |
| `partially_blocked` | Recursos equivalentes à transação parcialmente bloqueados. Monitorando saldo. |
| `settled` | Infração aceita, e pagamento do pedido de devolução realizado. |
| `partially_settled` | Infração aceita, e pagamento do pedido de devolução parcialmente realizado. |
| `released` | Recursos liberados, seja por cancelamento da infração ou fechamento em desacordo. |
---
# Pesquisar por QR Code Pix dinâmico próprio
URL: /documentation/pix/pesquisar_por_qr_code_dinamico
## Request
ENDPOINT /baas/qrcode/dynamic
MÉTODO GET
### Path params
| Campo | Tipo | Descrição | Caracteres |
|----------------------------|---------|------------------------------------------------------------------|------------|
| `account_key` | string | chave de identificação da QIConta vinculada à chave pix (UUIDv4) | 36 |
| `pix_key` | string | Chave PIX vinculado ao QRCode | - |
| `receiver_conciliation_id` | string | Identicação de conciliação do recebedor | max_length = 35 |
| `page` | integer | Número da página pesquisada (default = 0) | - |
| `page_size` | integer | Quantidade de itens por página (default = 15) | - |
| `first_result` | boolean | Retornar apenas o primeiro resultado (default = desc) | - |
| `order_by` | string | Determina a ordem de retorno dos resultados (default = desc) | asc, desc |
:::info
É obrigatório enviar `account_key` ou `pix_key`, sendo apenas um deles obrigatório.
:::
:::caution Atenção
Para consultar apenas um QR Code específico, devem ser utilizados os parâmetros `receiver_conciliation_id` e `pix_key`.
:::
## Response
STATUS 200
Response Body
```json
{
"pagination": {
"current_page": 0,
"next_page": 1,
"rows_per_page": 15,
"total_pages": 1,
"total_rows": 4
},
"data": [
{
"additional_data": [],
"amount": 1.0,
"discounts": [],
"qr_code_type": "dynamic_term",
"end_to_end_id": null,
"base_64": "MDAwMjAxMjY4OTAwMTRici5nb3YuYmNiLnBpeDI1NjdxcmNvZGUtaC5kZXYucWl0ZWNoLmFwcC9iYWNlbi9jb2J2LzQ1NWQ4ZmY1NGE0ZDQ2Mzg4YmVhN2I4MmFhMDZiNzdmNTIwNDAwMDA1MzAzOTg2NTgwMkJSNTkxOVBydVBydXVDb211bmljYWNvZXM2MDA4i2FvUGF1bG82MTA4MDU0MjUwMjA2MjA3MDUwMyoqKjYzMDQyNkNF",
"expiration_date": "2023-03-30",
"expiration_seconds": null,
"max_payment_days": 180,
"rebate_amount": 0.0,
"interest_amount": 0.0,
"fine_amount": 0.0,
"paid_amount": null,
"payer_request": null,
"pix_message": null,
"modality_alteration": false,
"payer_name": "Random",
"payer_document_number": "00000000000000",
"payer_person_type": "natural",
"pix_key": {
"account_key": "ce0db38f-a2ba-446f-bb1a-51d0bf3f40fc",
"is_activated": true,
"pix_key": "63602991000100",
"created_at": "2023-02-14T23:26:52"
},
"qr_code_key": "455d8ff5-4a4d-4638-8bea-7b82aa06b77f",
"qr_code_status": {
"enumerator": "active"
},
"receiver_conciliation_id": "01234567891293134978",
"created_at": "2023-03-29T15:26:50"
}
]
}
```
STATUS 400
Response Body: Parâmetros Obrigatórios Faltantes
```json
{
"title": "Bad Request",
"description": "Must use pix key or account key to search for QR Codes",
"translation": "Chave Pix ou Chave da Conta devem ser utilizados para realizar buscas por QR Codes",
"code": "PQR000009"
}
```
STATUS 400
Response Body: Usuário não possui credenciais
```json
{
"title": "Unauthorized",
"description": "User is not allowed to do this transaction",
"translation": "Usuário não tem autorização para fazer essa transação",
"code": "PQR000004"
}
```
STATUS 400
Response Body: Usuário não é dono da conta
```json
{
"title": "Unauthorized",
"description": "Person is not account owner.",
"translation": "A pessoa não é dona da conta.",
"code": "PQR000005"
}
```
STATUS 404
Response Body: Chave Pix Não encontrada
```json
{
"title": "Not Found",
"description": "No active Pix key found with key \{pix_key\}",
"translation": "Não foi encontrada pix key ativa com a chave \{pix_key\}",
"code": "PQR000007"
}
```
### Enumeradores QR Code Status
| Enumerador | Descrição |
|--------------------|----------------------------------------------------------|
| `active` | QR Code ativo |
| `finished` | QR Code pago |
| `written_off` | QR Code desativado por solicitação do recebedor/parceiro |
| `bank_written_off` | QR Code desativado pela QI |
---
# Conclusão da portabilidade
URL: /documentation/pix/portabilidade/conclusao_de_portabilidade
:::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.
:::
Após a confirmação ou recusa da portabilidade, a QI dará continuidade ao processo de portabilidade da chave. O usuário deve receber autualizações da portabilidade no banco de destino em alguns minutos.
Assim que o pedido de portabilidade for concluído ou cancelado, a QI informará o solicitante sobre a conclusão da portabilidade através do seguinte webhook:
WEBHOOK_TYPE claim_request
Webhook Body
```json
{
"account_key": "169010e3-6c1e-4521-9253-11cbbf36c59j",
"pix_key": "12345678000190",
"pix_key_type": "cnpj",
"claim_request_type": "portability",
"role": "claimant",
"claim_request_key": "7f8b67d2-d8e4-4759-85eb-e4d0ac24708c",
"claim_request_status": "concluded",
"claimant_person_type": "natural",
"claimant_document_number": "12345678000190",
"claimant_account_branch": "0001",
"claimant_account_number": "5050396",
"claimant_account_digit": "1",
"webhook_type": "claim_request"
}
```
#### Enumeradores claim_request_status
| Enumerador | Tradução |
|----------------------|-------------------------|
| **concluded** | concluído |
| **cancelled** | cancelado |
| **failed** | falha |
| **pending_confirmation** | pendente de confirmação |
---
# Consulta de portabilidade por conta
URL: /documentation/pix/portabilidade/consulta_de_portabilidade_por_conta
## Request
ENDPOINT /baas/pix/key_claim_request/account/ ACCOUNT_KEY
MÉTODO GET
Request Body
### Path Params
| Campo | Tipo | Descrição | Caracteres |
|---------------|--------|------------------------------------|------------|
| `account_key` | string | chave de identificação da QIConta. | 36 |
### 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. | - |
| `claim_status` | string | Status da portabilidade. Caso não seja enviado, todas as portabiliades não concluidas serão listadas | **[Enumeradores](#enumeradores-pix_key_type)** |
#### Enumeradores pix_key_type
| Enumerador | Tradução |
|--------------------------------|-------------------------------|
| **pending** | pendente |
| **opened** | aberto |
| **pending_confirmation** | confirmação pendente |
| **confirmed** | confirmado |
| **cancelled** | cancelado |
| **concluded** | concluído |
| **failed** | falha |
| **pending_donator_validation** | validação de doador pendente |
| **pending_claimer_validation** | validaçao de pedinte pendente |
## Response
STATUS 200
Response Body
```json
{
"data": [
{
"account_key": "be0884bc-44a4-4907-8627-ef976e477aef",
"cancellation_reason": null,
"cancelled_by": null,
"claim_flow_type": "donator",
"claim_request_key": "be0884bc-44a4-4907-8627-ef976e477aef",
"claim_status": "pending_confirmation",
"claim_type": "portability",
"claimant_account_branch": "9999",
"claimant_account_number": "0",
"claimant_document_number": "37059093800",
"claimant_person_type": "natural",
"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",
"requester_key": "be0884bc-44a4-4907-8627-ef976e477aef"
}
],
"pagination": {
"current_page": 1,
"next_page": null,
"rows_per_page": 10
}
}
```
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 | PIX000071 | Unknown Claim Request Status | Unknown claim_status \{claim_status\}. | claim_status \{claim_status\} não reconhecido. |
| 403 | PIX000054 | Invalid Permission | Person \{person_key\} does not have administration roles for account \{account_key\}. | Pessoa \{person_key\} não tem credencial de administrador para a conta \{account_key\}. |
---
# Criando um pedido de portabilidade
URL: /documentation/pix/portabilidade/criando_um_pedido_de_portabilidade
:::caution **Atenção**
É necessário realizar validação de dois fatores caso o tipo da chave que a portabilidade está sendo solicitada seja
número de telefone ou e-mail, o token será enviado para o número ou e-mail solicitado. Caso a validação de dois fatores seja necessária o "claim_request_status" será "pending_claimer_validation".
A orientação para o envio do token está no item 2.5.3.5.2 Validação de dois fatores
:::
:::danger **Atenção!!**
A criação do pedido de portabilidade deve ser feita utilizando uma das chaves Pix mockadas para o ambiente de sandbox.
[Chaves Pix Mockadas](/documentation/pix/chaves_pix_mockadas)
:::
### Request
ENDPOINT /baas/pix/key_claim_request
MÉTODO POST
Request Body
```json
{
"account_key": "169010e3-6c1e-4521-9253-11cbbf36c59j",
"pix_key": "12345678000190",
"pix_key_type": "cnpj"
}
```
#### Body Params
| Campo | Tipo | Descrição | Caracteres |
|----------------|--------|-----------------------------------------|------------------------------------------------|
| `account_key` | string | chave de identificação da QIConta. | 36 |
| `pix_key` | enum | chave a ser solicitada a portabilidade. | - |
| `pix_key_type` | enum | tipo da chave pix da portabilidade. | **[Enumeradores](#enumeradores-pix_key_type)** |
#### Enumeradores pix_key_type
| Enumerador | Tradução |
|------------------|--------------------|
| **random_key** | aleatória |
| **email** | e-mail |
| **phone_number** | número de telefone |
| **cpf** | cpf |
| **cnpj** | cnpj |
:::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: UUID.
:::
### Response
STATUS 200
Response Body
```json
{
"max_conclusion_date": "2023-05-26T12:13:25",
"claim_request_status": "pending",
"claimant": {
"document_number": "12345678000190",
"claimant_key": "6aaadfbc-76ba-45d2-bb21-138bcb2baa62",
"account_opened_at": "2023-01-17T12:28:37",
"account_branch": "0001",
"account_type": "escrow",
"account_number": "7336349",
"person_type": "legal",
"account_digit": "0"
},
"max_resolution_date": "2023-05-19T12:13:25",
"claimant_bank_name": "QI SCD S.A.",
"pix_key": {
"pix_key_type": "cnpj",
"pix_key_status": "pending_confirmation",
"created_at": "2023-05-12T12:13:24",
"updated_at": "2023-05-12T12:13:24",
"account_key": "169010e3-6c1e-4521-9253-11cbbf36c59j",
"pix_key": "12345678000190"
},
"donator_ispb": null,
"external_key": null,
"claim_request_key": "7f8b67d2-d8e4-4759-85eb-e4d0ac24708c",
"claim_request_type": "portability",
"client_role": "claimant",
"confirmation_reason": null,
"requester_key": "e151044c-44d0-48b3-9df1-0b9475077fe5",
"claimant_bank_code": "329",
"cancelled_by": null,
"request_failure_reason": null,
"donator": null,
"account_key": "169010e3-6c1e-4521-9253-11cbbf36c59j"
}
```
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 | PIX000022 | Pix key already registered | Pix key already registered for the account. | Chave pix já cadastrada para a conta. |
| 400 | PIX000014 | Maximum Number of Pix Keys in Use | Maximum number of pix keys for account \{account_key\} has reached | A conta \{account_key\} já tem o número máximo de chaves pix. |
| 400 | PIX000003 | Account is not Opened | Account \{account_key\} is not opened | Conta \{account_key\} não está aberta |
| 400 | PIX000053 | Invalid Portability Request | Portability within same Financial Institution should follow key alteration flow instead | Não é possível realizar portabilidade dentro da própria instituição financeira. Proceder com o fluxo de alteração |
| 403 | PIX000054 | Invalid Permission | Person 5dbd5598-6b42-4d80-8e5e-1c616cf8b9ab does not have administration roles for account 169010e3-6c1e-4521-9253-11cbbf36c59j. | Pessoa 5dbd5598-6b42-4d80-8e5e-1c616cf8b9ab não tem credencial de administrador para a conta 169010e3-6c1e-4521-9253-11cbbf36c59j. |
| 404 | PIX000017 | Pix Key is Unregistered | Pix key 12345678000190 is not currently used. | A chave pix 12345678000190 não está sendo utilizada. |
| 422 | PIX000077 | Error when querying pix key | Error when querying pix key 12345678000190 | Erro ao consultar chave pix 12345678000190 |
| 400 | PIX000028 | Key Type not allowed for portability or claim | Only cpf, cnpj, email and phone_number key_types can be portabilized or claim. Received key_type: random_key | Somente os key_types cpf, cnpj, email e phone_number podem ser portabilizados ou reivindicados. key_type recebido: random_key |
| 400 | PIX000061 | Invalid Document | Invalid document sent 12345678000190. | Documento enviado é inválido 12345678000190. |
| 404 | PIX000026 | Account not found | Account not found for account_key: 6aaadfbc-76ba-45d2-bb21-138bcb2baa62 | Conta não encontrada para account_key: 6aaadfbc-76ba-45d2-bb21-138bcb2baa62 |
| 404 | PIX000027 | Person not found | Person not found for person_key: \{person_key\} | Pessoa não encontrada para person_key: \{person_key\} |
| 422 | PIX000069 | Pix Key inquiry timeout | Pix key inquiry timeout. Please try again. | Consulta de chave pix excedeu o tempo limite. Por favor tente novamente. |
| 400 | PIX000072 | Pix Key Claim Non Finished | Pix key 12345678000190, already has a claim request non finished. | Chave pix 12345678000190, já possui um pedido de portabilidade não finalizado. |
---
# Deletando um pedido de portabilidade
URL: /documentation/pix/portabilidade/deletando_um_pedido_de_portabilidade
Caso o pedido de portabilidade esteja no status "pending_claimer_validation" é possível deletar a portabilidade.
### Request
ENDPOINT /baas/pix/key_claim_request/ CLAIM_REQUEST_KEY
MÉTODO DELETE
Request Body
```json
{}
```
### Response
STATUS 200
Response Body
```json
{
"max_conclusion_date": "2023-05-26T12:13:25",
"claim_request_status": "cancelled",
"claimant": {
"document_number": "12345678000190",
"claimant_key": "6aaadfbc-76ba-45d2-bb21-138bcb2baa62",
"account_opened_at": "2023-01-17T12:28:37",
"account_branch": "0001",
"account_type": "escrow",
"account_number": "7336349",
"person_type": "legal",
"account_digit": "0"
},
"max_resolution_date": "2023-05-19T12:13:25",
"claimant_bank_name": "QI SCD S.A.",
"pix_key": {
"pix_key_type": "email",
"pix_key_status": "inactivated",
"created_at": "2023-05-12T12:13:24",
"updated_at": "2023-05-12T12:13:24",
"account_key": "169010e3-6c1e-4521-9253-11cbbf36c59j",
"pix_key": "example@gmail.com"
},
"donator_ispb": null,
"external_key": null,
"claim_request_key": "7f8b67d2-d8e4-4759-85eb-e4d0ac24708c",
"claim_request_type": "portability",
"client_role": "claimant",
"confirmation_reason": null,
"requester_key": "e151044c-44d0-48b3-9df1-0b9475077fe5",
"claimant_bank_code": "329",
"cancelled_by": null,
"request_failure_reason": null,
"donator": null,
"account_key": "169010e3-6c1e-4521-9253-11cbbf36c59j"
}
```
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` |
|-------------|----------------------|-----------------------------------------------------------|-------------------------------------------------------------------------------------------------|--------------------------------------------------------------------------------------------------------------|
| 404 | PIX000031 | Claim Request not found | Claim Request not found for key: 7f8b67d2-d8e4-4759-85eb-e4d0ac24708c. | Claim Request não encontrada para a chave: 7f8b67d2-d8e4-4759-85eb-e4d0ac24708c. |
| 403 | QIT000005 | Permission Validator Error. | Selected agent do not own this item. | O agente selecionado não é dono do item. |
| 400 | PIX000047 | Claim request does not have validation. | Claim request does not have two steps validation. | Pedido de reinvindicação não possui validação de duas etapas. |
| 400 | PIX000047 | Claim Request Is Not Pending Validation From The Claimer. | Claim request 7f8b67d2-d8e4-4759-85eb-e4d0ac24708c, is not pending validation from the claimer. | Pedido de portabilidade 7f8b67d2-d8e4-4759-85eb-e4d0ac24708c, não está pendente de validação do solicitante. |
---
# Portabilidade
URL: /documentation/pix/portabilidade/recebendo_pedido_de_portabilidade
:::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.
:::
## Recebendo pedido de portabilidade
Após a criação do pedido de portabilidade em outro banco, a QI informará o solicitante sobre o pedido de portabilidade
em aberto através do seguinte webhook:
WEBHOOK_TYPE claim_request
Webhook Body
```json
{
"account_key": "169010e3-6c1e-4521-9253-11cbbf36c59j",
"pix_key": "12345678000190",
"pix_key_type": "cnpj",
"claim_request_type": "portability",
"role": "donator",
"claim_request_key": "7f8b67d2-d8e4-4759-85eb-e4d0ac24708c",
"claim_request_status": "pending_confirmation",
"claimant_person_type": "natural",
"claimant_document_number": "12345678000190",
"claimant_account_branch": "0001",
"claimant_account_number": "5050396",
"claimant_account_digit": "1",
"webhook_type": "claim_request"
}
```
#### Enumeradores claim_request_status
| Enumerador | Tradução |
|----------------------|-------------------------|
| concluded | concluído |
| cancelled | cancelado |
| failed | falha |
| pending_confirmation | pendente de confirmação |
---
# Reenviando a validação de dois fatores
URL: /documentation/pix/portabilidade/reenviando_a_2fa
Caso o pedido de portabilidade esteja no status "pending_claimer_validation" é possível reenviar o código da validação
de dois fatores.
### Request
ENDPOINT /baas/pix/key_claim_request/ CLAIM_REQUEST_KEY /resend_twofa
MÉTODO PATCH
Request Body
```json
{}
```
### Response
STATUS 205
Response Body
```json
{
"max_conclusion_date": "2023-05-26T12:13:25",
"claim_request_status": "pending_claimer_validation",
"claimant": {
"document_number": "12345678000190",
"claimant_key": "6aaadfbc-76ba-45d2-bb21-138bcb2baa62",
"account_opened_at": "2023-01-17T12:28:37",
"account_branch": "0001",
"account_type": "escrow",
"account_number": "7336349",
"person_type": "legal",
"account_digit": "0"
},
"max_resolution_date": "2023-05-19T12:13:25",
"claimant_bank_name": "QI SCD S.A.",
"pix_key": {
"pix_key_type": "email",
"pix_key_status": "pending_confirmation",
"created_at": "2023-05-12T12:13:24",
"updated_at": "2023-05-12T12:13:24",
"account_key": "169010e3-6c1e-4521-9253-11cbbf36c59j",
"pix_key": "example@gmail.com"
},
"donator_ispb": null,
"external_key": null,
"claim_request_key": "7f8b67d2-d8e4-4759-85eb-e4d0ac24708c",
"claim_request_type": "portability",
"client_role": "claimant",
"confirmation_reason": null,
"requester_key": "e151044c-44d0-48b3-9df1-0b9475077fe5",
"claimant_bank_code": "329",
"cancelled_by": null,
"request_failure_reason": null,
"donator": null,
"account_key": "169010e3-6c1e-4521-9253-11cbbf36c59j"
}
```
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` |
|-------------|----------------------|-----------------------------------------------------------|-------------------------------------------------------------------------------------------------|--------------------------------------------------------------------------------------------------------------|
| 404 | PIX000031 | Claim Request not found | Claim Request not found for key: 7f8b67d2-d8e4-4759-85eb-e4d0ac24708c. | Claim Request não encontrada para a chave: 7f8b67d2-d8e4-4759-85eb-e4d0ac24708c. |
| 403 | QIT000005 | Permission Validator Error. | Selected agent do not own this item. | O agente selecionado não é dono do item. |
| 400 | PIX000047 | Claim request does not have validation. | Claim request does not have two steps validation. | Pedido de reinvindicação não possui validação de duas etapas. |
| 400 | PIX000047 | Claim Request Is Not Pending Validation From The Claimer. | Claim request 7f8b67d2-d8e4-4759-85eb-e4d0ac24708c, is not pending validation from the claimer. | Pedido de portabilidade 7f8b67d2-d8e4-4759-85eb-e4d0ac24708c, não está pendente de validação do solicitante. |
---
# Portabilidade
URL: /documentation/pix/portabilidade/respondendo_pedido_de_portabilidade
### Request
ENDPOINT /baas/pix/key_claim_request/ CLAIM_REQUEST_KEY/
CLAIM_ACTION
MÉTODO PATCH
#### Path params
| Campo | Tipo | Descrição |
|-------------|--------|--------------------------------|
| `claim_request_key` | string | a chave do pedido de portabilidade. |
| `claim_action` | enum | **[Enumeradores](#enumeradores-claim_action)** |
#### Enumeradores claim_action
| Enumerador | Tradução | Descrição |
|---|---|---|
| confirmed | confirmado | use essa action para confirmar o pedido de portabilidade
| cancelled | cancelado | use essa action para cancelar o pedido de portabilidade
| pending_donator_validation | pending_donator_validation | use essa auction para receber a autenticaçã de dois fatores
:::caution **Atenção**
Antes de cancelar uma claim que o "claim_request_type" seja "ownership" é necessário realizar a action "pending_donator_validation" para receber a autenticação de dois fatores e realizar o envio no payload. A única "cancelation_reason" aceita para cancelamento de claims desse tipo são "ownership" e "fraud".
:::
:::caution **Atenção**
Após a action de cancelamento ser executada o processo de claim request chegou ao final e não existem hooks para serem recebidos.
:::
Request Body
```json title='Confirmação'
{
"confirmation_reason": "client_request"
}
```
```json title='Cancelamento'
{
"cancellation_reason": "client_request"
}
```
```json title='Cancelamento de ownership'
{
"cancellation_reason": "fraud",
"verification_code": "432371"
}
```
```json title='Pendente de validação do doador'
{}
```
#### Body Params
| Campo | Tipo | Descrição | Caracteres |
|---|---|---|---|
| `confirmation_reason` | enum | **[Enumeradores](#enumeradores-confirmation_reason)**. | 14 |
| `cancellation_reason` | enum | **[Enumeradores](#enumeradores-cancellation_reason)**. | 14 |
| `verification_code` | string | token recebido no número de telefone ou e-mail. | 6 |
#### Enumeradores confirmation_reason
| Enumerador | Tradução |
|---|---|
| client_request | pedido do clitente |
#### Enumeradores cancellation_reason
| Enumerador | Tradução |
|---|---|
| **client_request** | pedido do clitente |
| **fraud** | fraude |
:::caution **Atenção**
Ao cancelar um pedido de portabilidade do tipo "ownership" o "cancelation_reason" sempre deve ser "fraud".
:::
### Response
STATUS 200
Response Body
```json
{
"max_conclusion_date": "2023-05-26T12:13:25",
"claim_request_status": "confirmed",
"claimant": {
"document_number": "12345678000190",
"claimant_key": "6aaadfbc-76ba-45d2-bb21-138bcb2baa62",
"account_opened_at": "2023-01-17T12:28:37",
"account_branch": "0001",
"account_type": "checking",
"account_number": "7336349",
"person_type": "legal",
"account_digit": "0"
},
"max_resolution_date": "2023-05-19T12:13:25",
"claimant_bank_name": "QI SCD S.A.",
"pix_key": {
"pix_key_type": "cnpj",
"pix_key_status": "active",
"created_at": "2023-05-12T12:13:24",
"updated_at": "2023-05-12T12:13:24",
"account_key": "169010e3-6c1e-4521-9253-11cbbf36c59j",
"pix_key": "12345678000190"
},
"donator_ispb": null,
"external_key": null,
"claim_request_key": "7f8b67d2-d8e4-4759-85eb-e4d0ac24708c",
"claim_request_type": "portability",
"client_role": "claimant",
"confirmation_reason": null,
"requester_key": "e151044c-44d0-48b3-9df1-0b9475077fe5",
"claimant_bank_code": "329",
"cancelled_by": null,
"request_failure_reason": null,
"donator": null,
"account_key": "169010e3-6c1e-4521-9253-11cbbf36c59j"
}
```
| Código HTTP | Código QI
`code` | Título
`title` | Descrição (eng)
`Description` | Descrição (ptbr)
`translation` |
|-------------|----------------------|-----------------------------------------------|----------------------------------------------------------------------------------------------------------------------------------|------------------------------------------------------------------------------------------------------------------------------------|
| 400 | PIX000043 | Claim request action not allowed on current status | confirmed Claim request action only allowed for pending_confirmation requests | Ação confirmed para claim request permitida somente para pedidos com status pending_confirmation. |
| 400 | PIX000036 | Claim request action not allowed for claimant | Claim request action not allowed for claimant. Only donator can perform this action | Ação sobre claim request não permitida para reivindicador. Somente o doador pode executar esta ação |
| 400 | PIX000044 | Claim request confirm action without reason | confirmation_reason is required on action confirmed | confirmation_reason é obrigatório na ação confirmed |
| 400 | PIX000045 | Razão da confirmação não permitida | cancellation_reason: invalid not allowed for client_role: donator and claim_request_type: portability | cancellation_reason: invalid não permitida para client_role: donator and claim_request_type: portability |
| 400 | PIX000039 | Claim request action not allowed on current status | Cancelled Claim request action only allowed for non concluded requests | Ação cancelled para claim request permitida somente para pedidos com status diferente de concluded |
| 400 | PIX000040 | Claim request cancel action without reason | cancellation_reason is required on action cancelled | cancellation_reason é obrigatório na ação cancelled |
| 400 | PIX000042 | Razão do cancelamento não permitida | cancellation_reason: client_request not allowed for client_role: donator and claim_request_type: ownership | cancellation_reason: client_request não permitida para client_role: donator and claim_request_type: ownership |
| 400 | PIX000051 | Verification code required | 2FA verification code required. | Código de verificação 2FA necessário. |
| 400 | PIX000100 | External Claim Already Cancelled | The external claim request has already been cancelled | O pedido de portabilidade externo já foi cancelado |
| 404 | PIX000034 | Claim Request not found | IClaim Request not found. claim_request_key: 7f8b67d2-d8e4-4759-85eb-e4d0ac24708c external_key: b8e25f24-4051-4b13-90a7-76be7b6e96d2. | Claim Request não encontrada. claim_request_key: 7f8b67d2-d8e4-4759-85eb-e4d0ac24708c external_key: b8e25f24-4051-4b13-90a7-76be7b6e96d2. |
| 401 | 2FA000401 | Unauthorized | Invalid verification combination. | CCódigo de verificação inválido. |
| 403 | 2FA000403 | Forbidden | Code already verified. | Este código já foi utilizado. |
| 410 | 2FA000410 | Gone | Expired Code. | Código de verificação expirado. |
---
# Simular alteração de status de portabilidade
URL: /documentation/pix/portabilidade/simular_alteracao_de_status_de_portabilidade
### Request
ENDPOINT /mock/pix_keys/key_claim_simulation/ CLAIM_REQUEST_KEY
/receive_response/ CLAIM_ACTION
MÉTODO PATCH
#### Path params
| Campo | Tipo | Descrição |
|---------------------|--------|----------------------------------------------------------|
| `claim_request_key` | uuidv4 | Chave única de identificação do pedido de portabilidade. |
| `claim_action` | string | **[Enumeradores](#enumeradores-claim_action)** |
#### Enumeradores claim_action
| Enumerador | Tradução | Descrição |
|---------------|------------|-------------------------------------------------------------------------------------------------------------------------------------------|
| **failed** | falhou | O pedido de portabilidade falhou |
| **confirmed** | confirmado | O pedido de portabilidade está confirmado, necessita de aprovação do banco doador para ser concluido ou de rejeição para ser cancelado |
| **cancelled** | cancelado | O pedido de portabilidade está cancelado, logo, para se realizar uma claim sobre está chave deve-se abrir um novo pedido de portabilidade |
| **concluded** | concluído | O pedido de portabilidade está concluído |
Request Body
```json
{}
```
### Response
STATUS 204
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` |
|-------------|----------------------|----------------------------------------------|-------------------------------------------------------------------------------------------|-----------------------------------------------------------------------------------------------------|
| 404 | PIX000034 | Claim Request not found | Claim Request not found. claim_request_key: claim_request_key external_key: external_key. | Claim Request não encontrada. claim_request_key: claim_request_key external_key: external_key. |
| 400 | PIX000035 | Claim request action not allowed for donator | Claim request action not allowed for donator. Only claimant can perform this action | Ação sobre claim request não permitida para doador. Somente o reinvidicador pode executar esta ação |
---
# Simular webhook de conclusão do pedido de portabilidade
URL: /documentation/pix/portabilidade/simular_webhook_de_conclusao
### Request
ENDPOINT /mock/pix_keys/key_claim_simulation/ CLAIM_REQUEST_KEY
/complete
MÉTODO PATCH
#### Path params
| Campo | Tipo | Descrição |
|---------------------|--------|-------------------------------------|
| `claim_request_key` | string | a chave do pedido de portabilidade. |
Request Body
```json
{}
```
### Response
STATUS 204
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` |
|-------------|----------------------|-----------------------------------------------------|-------------------------------------------------------------------------------------------------------------------------------------------|------------------------------------------------------|
| 404 | PIX000034 | Pedido de portabilidade não encontrado | Claim Request não encontrada. claim_request_key: 7f8b67d2-d8e4-4759-85eb-e4d0ac24708c external_key: b8e25f24-4051-4b13-90a7-76be7b6e96d2. | Pedido de portabilidade não encontrado. |
| 400 | PIX000046 | Ação de portabilidade não permitida no status atual | Ação concluded para pedido de reivindicação permitida somente para status confirmed | Ação de portabilidade não permitida no status atual. |
| 400 | PIX000036 | Ação não permitida para requerente | Ação sobre claim request não permitida para reivindicador. Somente o doador pode executar esta ação | Ação não permitida para requerente. |
---
# Simular webhook de recebimento de um pedido de portabilidade
URL: /documentation/pix/portabilidade/simular_webhook_recebimento
### Request
ENDPOINT
/mock/pix_keys/key_claim_simulation/receive
MÉTODO
POST
Request Body
```json
{
"pix_key": "12345678000190",
"pix_key_type": "cnpj"
}
```
#### Body Params
| Campo | Tipo | Descrição | Caracteres |
|----------------|------|--------------------------------------------------------------|------------------------------------------------|
| `pix_key` | enum | chave para simular o recebimento de pedido de portabilidade. | - |
| `pix_key_type` | enum | tipo da chave pix da portabilidade. | **[Enumeradores](#enumeradores-pix_key_type)** |
#### Enumeradores pix_key_type
| Enumerador | Tradução |
|--------------|--------------------|
| **random_key** | aleatória |
| **email** | e-mail |
| **phone_number** | número de telefone |
| **cpf** | cpf |
| **cnpj** | cnpj |
:::info Tipos de Chave Pix
A chave pix enviada no payload deve estar ativa no ambiente de sandbox e em uma conta que você tenha criado.
:::
### Response
STATUS 201
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` |
|-------------|----------------------|----------------------------|-------------------------------------------------------------------------|--------------------------------------------------------------------------------|
| 400 | PIX000072 | Pix Key Claim Non Finished | Pix key 12345678000190, already has a claim request non finished. | Chave pix 12345678000190, já possui um pedido de portabilidade não finalizado. |
| 400 | PIX000026 | Account not found | Account not found for account_key: 6aaadfbc-76ba-45d2-bb21-138bcb2baa62 | Conta não encontrada para account_key: 6aaadfbc-76ba-45d2-bb21-138bcb2baa62 |
---
# Validação de dois fatores
URL: /documentation/pix/portabilidade/validacao_de_dois_fatores
:::info Token em Sandbox
Para facilitar os testes no ambiente de sandbox, o token terá sempre o valor `329329`.
Este comportamento é exclusivo para o ambiente de sandbox.
:::
### Request
ENDPOINT /baas/pix/key_claim_request/ CLAIM_REQUEST_KEY /twofa_validation
MÉTODO PATCH
#### Path params
| Campo | Tipo | Descrição |
|---------------------|--------|-------------------------------------|
| `claim_request_key` | string | a chave do pedido de portabilidade. |
Request Body
```json
{
"verification_code": "432371"
}
```
#### Body Params
| Campo | Tipo | Descrição | Caracteres |
|---------------------|--------|-------------------------------------------------|------------|
| `verification_code` | string | token recebido no número de telefone ou e-mail. | 6 |
### Response
STATUS 200
Response Body
```json
{
"max_conclusion_date": "2023-05-26T12:13:25",
"claim_request_status": "pending",
"claimant": {
"document_number": "12345678000190",
"claimant_key": "6aaadfbc-76ba-45d2-bb21-138bcb2baa62",
"account_opened_at": "2023-01-17T12:28:37",
"account_branch": "0001",
"account_type": "escrow",
"account_number": "7336349",
"person_type": "legal",
"account_digit": "0"
},
"max_resolution_date": "2023-05-19T12:13:25",
"claimant_bank_name": "QI SCD S.A.",
"pix_key": {
"pix_key_type": "cnpj",
"pix_key_status": "pending_confirmation",
"created_at": "2023-05-12T12:13:24",
"updated_at": "2023-05-12T12:13:24",
"account_key": "169010e3-6c1e-4521-9253-11cbbf36c59j",
"pix_key": "12345678000190"
},
"donator_ispb": null,
"external_key": null,
"claim_request_key": "7f8b67d2-d8e4-4759-85eb-e4d0ac24708c",
"claim_request_type": "portability",
"client_role": "claimant",
"confirmation_reason": null,
"requester_key": "e151044c-44d0-48b3-9df1-0b9475077fe5",
"claimant_bank_code": "329",
"cancelled_by": null,
"request_failure_reason": null,
"donator": null,
"account_key": "169010e3-6c1e-4521-9253-11cbbf36c59j"
}
```
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 | PIX000047 | Claim request action not allowed on current status | Validate Claim request action only allowed for pending_validation requests. | Ação validate para claim request permitida somente para pedidos pending_validation. |
| 401 | 2FA000401 | Unauthorized | Invalid verification combination. | Código de verificação inválido. |
| 403 | 2FA000403 | Forbidden | Code already verified. | Este código já foi utilizado. |
| 403 | QIT000005 | Permission Validator Error. | Selected agent do not own this item. | O agente selecionado não é dono do item. |
| 410 | 2FA000410 | Gone | Expired Code. | Código de verificação expirado. |
| 404 | PIX000031 | Claim Request not found | Claim Request not found for key: 7f8b67d2-d8e4-4759-85eb-e4d0ac24708c. | Claim Request não encontrada para a chave: 7f8b67d2-d8e4-4759-85eb-e4d0ac24708c. |
---
# Simulação de cenários
URL: /documentation/pix/simulacao
Passo a passo para simular a efetivação de ações feitas por agentes externos. Essas simulações incluem: entrada, estorno
e portabilidade IN de chave PIX.
## 1 - Simulação de entrada de PIX
### Request
ENDPOINT /mock/pix_transfer/incoming_pix_transfer
MÉTODO POST
Request Body
```json
{
"target_account_key": "\",
"amount": "\"
}
```
### Body Parameters
| Campo | Tipo | Descrição | Máx. Caract. | Exemplo | Observação |
|----------------------|--------|------------------------------------|--------------|----------------------------------------|-------------------------|
| `target_account_key` | string | Chave unitária da conta de destino | 36 | "41112f46-0034-4007-85687-5e592173db2" | |
| `amount` | number | Valor da transação | 6 | 1000 | Valor máximo de 100.000 |
## Response
STATUS 201
Response Body
```json
{
"end_to_end_id": "E60701190202601291553Zrxq8RRUwS1"
}
```
## 2 - Simulação de resultado da análise de entrada PIX
Para simular o cenário onde a entrada PIX entra em análise manual, é necessário simular uma entrada com valor superior a R$ 2.000.000,00 (dois milhões de reais). Nesse caso, o PIX ficará em status de análise manual e o cliente receberá os devidos webhooks.
:::caution Atenção
A regra de dois milhões é exclusiva para ambiente de sandbox e **não reflete os casos de produção**.
:::
Após receber o webhook de análise manual, é necessário utilizar esta rota de simulação para aprovar ou recusar a entrada do recurso. O cliente também receberá os devidos webhooks com o resultado da análise.
### Request
ENDPOINT /mock/pix_transfer/incoming_pix_analysis_result
MÉTODO POST
Request Body
```json
{
"end_to_end_id": "E60701190202601291537yo1ZxpvVzJn",
"analysis_status": "manually_reproved"
}
```
### Body Parameters
| Campo | Tipo | Descrição | Máx. Caract. | Exemplo | Observação |
|-------------------|--------|-------------------------------------------------------------|--------------|------------------------------------|-----------|
| `end_to_end_id` | string | Chave unitária da transação PIX | 32 | "E60701190202601291537yo1ZxpvVzJn" | |
| `analysis_status` | enum | [Enumerador Analysis Status](#enumerador-analysis-status) | | "manually_reproved" | |
### Enumerador Analysis Status
| Enumerador | Descrição |
|-----------------------|-----------------------|
| **manually_approved** | Aprovado manualmente |
| **manually_reproved** | Reprovado manualmente |
## 3 - Simulação de pagamento de PIX QR Code
### Request
ENDPOINT /mock/pix_transfer/incoming_pix_qrcode
MÉTODO POST
Request Body
```json
{
"qr_code_key": "41112f46-0034-4007-85687-5e592173db2"
}
```
### Body Parameters
| Campo | Tipo | Descrição | Máx. Caract. | Exemplo | Observação |
|---------------|--------|--------------------------------------------|--------------|----------------------------------------|------------|
| `qr_code_key` | string | Chave unitária de identificação do qr code | 36 | "41112f46-0034-4007-85687-5e592173db2" | |
## 4 - Simulação de estorno de PIX
### Request
ENDPOINT /mock/pix_transfer/chargeback
MÉTODO POST
Request Body
```json
{
"end_to_end_id": "\",
"amount": "\"
}
```
### Body Parameters
| Campo | Tipo | Descrição | Máx. Caract. | Exemplo | Observação |
|-----------------|--------|---------------------------------|--------------|------------------------------------|-------------------------|
| `amount` | number | Valor da transação | 6 | 1000 | Valor máximo de 100.000 | |
| `end_to_end_id` | string | Chave unitária da transação PIX | 32 | "E3240250220210723142712312751267" | |
## 5 - Simulação de webhook de portabilidade IN de chave PIX
### Request
ENDPOINT /mock/pix_keys/key_claim_request/webhook
MÉTODO POST
Request Body
```json
{
"claim_request_key": "\",
"claim_request_status": "\"
}
```
### Body Parameters
| Campo | Tipo | Descrição | Máx. Caract. | Exemplo | Observação |
|------------------------|--------|---------------------------------------------------------------------|--------------|----------------------------------------|------------|
| `claim_request_key` | string | Chave unitária do requester | 36 | "ced00dc6-000a-0bd4-a111-85710a46ec05" | |
| `claim_request_status` | enum | [Enumerador Claim Request Status](#enumerador-claim-request-status) | | "concluded" | |
### Enumerador _Claim Request Status_
| Enumerador | Descrição |
|--------------------------|-------------------------|
| **concluded** | Concluído |
| **cancelled** | Cancelado |
| **failed** | Falha |
| **pending_confirmation** | Pendente de confirmação |
## 6 - 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 |
## 7 - 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.
## 8 - Recuperar Token enviado para Autenticação de Dois Fatores
Para transações pix individuais e em lote de parceiros integradores com configuração de autenticação de dois fatores,
um `token` é enviado ao aprovador de movimentação da conta. Por meio deste endpoint é possível recuperar o endpoint
enviado para fins de teste de integração.
ENDPOINT /mock/2fa/transaction_request/ TRANSACTION_REQUEST_KEY
MÉTODO GET
## Path Params
| Campo | Tipo | Descrição | Caracteres |
|---------------------------|-------|---------------------------------------------------------------------------------------------------------------------------------------------------------------------|------------|
| `transaction_request_key` | uuid4 | Chave única de identificação transação. Para o caso de transação pix seria a `pix_transfer_key` e para o caso de transação pix em lote é a `pix_transfer_batch_key` | 36 |
Response Body
```json
{
"token": "1a2b3c"
}
```
---
# Solicitar alteração de limite Pix
URL: /documentation/pix/solicitar_alteracao_de_limite_pix
## Request
ENDPOINT /baas/pix/limits/ ACCOUNT_KEY
MÉTODO POST
Request Body
```json
{
"daily_amount_limit": 2000.00,
"nightly_amount_limit": 1000.00,
"self_daily_amount_limit": 1500.00,
"self_nightly_amount_limit": 500.00
}
```
### Body Params
| Campo | Tipo | Descrição |
|-----------------------------|-------|------------------------------------------------------------------------------------|
| `daily_amount_limit` | float | Limite durante o período diurno para transferências Pix de diferente titularidade |
| `nightly_amount_limit` | float | Limite durante o período noturno para transferências Pix de diferente titularidade |
| `self_daily_amount_limit` | float | Limite durante o período diurno para transferências Pix de mesma titularidade |
| `self_nightly_amount_limit` | float | Limite durante o período noturno para transferências Pix de mesma titularidade |
:::info Horário diurno
Para o período **diurno** são contabilizadas transferências realizadas entre **06:00** e **20:00**.
:::
:::danger Atenção
As Solicitações de aumento de limite Pix possuem um SLA de **48 horas** para aprovação.
Solicitações de redução do limite Pix são aprovação e executadas imediatamente.
Caso o SLA de **48 horas** seja atingido sem aprovação, a solicitação é automaticamente rejeitada com o motivo `Tempo de avaliação expirado.` e um webhook de rejeição é enviado ao requisitante (ver [Webhook Request Rejected Body](#webhook-request-rejected-body)).
:::
## Response
STATUS 200
Response Body
```json
[
{
"account_digit": "5",
"account_key": "467ce632-cc2c-412a-bc56-aa949bd8393d",
"account_name": "Default",
"account_number": "26709",
"amount_limit": 2000.0,
"event_type": "pix_limit_request",
"limit_type": "daily",
"owner_document_number": "63602991000100",
"request_status": "pending_approval",
"requester_document_number": "77669728833"
},
{
"account_digit": "5",
"account_key": "467ce632-cc2c-412a-bc56-aa949bd8393d",
"account_name": "Default",
"account_number": "26709",
"amount_limit": 1000.0,
"event_type": "pix_limit_request",
"limit_type": "nightly",
"owner_document_number": "63602991000100",
"request_status": "pending_approval",
"requester_document_number": "77669728833"
},
{
"account_digit": "5",
"account_key": "467ce632-cc2c-412a-bc56-aa949bd8393d",
"account_name": "Default",
"account_number": "26709",
"amount_limit": 1500.0,
"event_type": "pix_limit_request",
"limit_type": "self_daily",
"owner_document_number": "63602991000100",
"request_status": "pending_approval",
"requester_document_number": "53417895200"
},
{
"account_digit": "5",
"account_key": "467ce632-cc2c-412a-bc56-aa949bd8393d",
"account_name": "Default",
"account_number": "26709",
"amount_limit": 500.0,
"event_type": "pix_limit_request",
"limit_type": "self_nightly",
"owner_document_number": "63602991000100",
"request_status": "pending_approval",
"requester_document_number": "53417895200"
}
]
```
STATUS 400
Response Body: Número enviado inválido
```json
{
"title": "Bad Request",
"description": "Invalid decimal amount, sent 1500.001",
"translation": "Valor decimal inválido, enviado 1500.001",
"code": "PXT000043",
"additional_data": {}
}
```
STATUS 403
Response Body: Usuário não possui credenciais
```json
{
"title": "Unauthorized",
"description": "User is not allowed to do this transaction",
"translation": "Usuário não tem autorização para fazer essa transação",
"code": "PIT000001"
}
```
### Webhook Response
:::info Evento gerador de webhook
Webhooks são enviados ao requisitante da conta ao ser realizada a execução da solicitação de limite
:::
Webhook Request Accepted Body
```json
{
"webhook_type": "baas.pix.limits.account_limit_config.updated",
"webhook_datetime": "2023-08-05T19:54:01.514Z",
"data": {
"pix_transfer_limit_config": [
{
"period": "daily",
"account_key": "467ce632-cc2c-412a-bc56-aa949bd8393d",
"amount_limit": 800012.67,
"self_amount_limit": 500.03
},
{
"period": "nightly",
"account_key": "467ce632-cc2c-412a-bc56-aa949bd8393d",
"amount_limit": 100000.0,
"self_amount_limit": 100000.0
}
]
}
}
```
Webhook Request Rejected Body
```json
{
"webhook_type":"baas.pix.limits.account_limit_config.updated",
"webhook_datetime": "2023-08-05T19:54:01.514Z",
"data":{
"message": "QI Tech informa que a solicitacao de limite PIX diário para terceiros da sua conta foi rejeitada. Motivo: limite reanalisado.",
"account_key": "467ce632-cc2c-412a-bc56-aa949bd8393d",
"request_status": "rejected",
"limit_type": "daily"
}
}
```
### Enumeradores limit_type
| Enumerador | Descrição |
|-----------------------|------------------------------------------------------------------------------------|
| `daily` | Limite durante o período diurno para transferências Pix de diferente titularidade |
| `nightly` | Limite durante o período noturno para transferências Pix de diferente titularidade |
| `self_daily` | Limite durante o período diurno para transferências Pix de mesma titularidade |
| `self_nightly` | Limite durante o período noturno para transferências Pix de mesma titularidade |
---
# Webhook por QR Code Pix dinâmico expirado
URL: /documentation/pix/webhook_por_qr_code_expirado
:::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).
:::
## Webhook
:::info Evento gerador de webhook
Webhooks são enviados ao detentor da chave pix vinculada ao QR Code Dinâmico. Este evento ocorre uma única vez após o vencimento do QR Code.
:::
Resquest Body
```json
{
"event_type":"baas.pix_qr_code.occurrence.bank_write_off",
"origin_key":"faf1ef5b-e0a9-4430-8aa4-367b4825854c",
"data":{
"pix_key":"c05b7c73-fb43-45c2-871d-8c890dbe5d85",
"qr_code_key":"458b4a77-9cb2-4232-bae5-078150c4e93d",
"qr_code_type":"dynamic_instant",
"qr_code_status":"bank_written_off",
"qr_code_occurrence_key":"faf1ef5b-e0a9-4430-8aa4-367b4825854c",
"receiver_conciliation_id":"458b4a779cb24232bae5078150c4e93d"
}
}
```