# QI Tech — Banking-as-a-Service › Pix Automático
Documentação da QI Tech em texto corrido, para colar em um LLM.
Fonte: https://docs.qitech.com.br
29 página(s).
Índice:
- Consultar Dados de um Lote de Pagamentos por conta (/documentation/baas/pix_automatico/conciliacao/consultar_lote_por_conta)
- Consultar Lotes de Pagamentos por Requester (/documentation/baas/pix_automatico/conciliacao/consultar_lote_requester)
- Listagem de Pagamentos de uma Conta (/documentation/baas/pix_automatico/conciliacao/listar_payment_orders)
- Webhook de Criação de Lote de Conciliação de Ordens de Pagamento (/documentation/baas/pix_automatico/conciliacao/webhooks)
- FAQ - Pix Automático (/documentation/baas/pix_automatico/faq)
- Introdução ao Pix Automático (/documentation/baas/pix_automatico/introducao)
- Aceitar recorrência de pagamento (/documentation/baas/pix_automatico/movimentacoes/aceitar_recorrencia)
- Cancelar a recorrência (/documentation/baas/pix_automatico/movimentacoes/cancelar_recorrencia)
- Consultar Recorrência (/documentation/baas/pix_automatico/movimentacoes/consultar_recorrencia)
- Listagem de Recorrências (/documentation/baas/pix_automatico/movimentacoes/listar_recorrencias)
- Simulação de cenários (/documentation/baas/pix_automatico/movimentacoes/simulacao)
- Webhooks (/documentation/baas/pix_automatico/movimentacoes/webhooks)
- Atualizar Valor da Ordem de Pagamento (/documentation/baas/pix_automatico/pagamentos/atualizar_payment_order)
- Cancelar uma Ordem de Pagamento (/documentation/baas/pix_automatico/pagamentos/cancelar_payment_order)
- Consultar Payment Order (/documentation/baas/pix_automatico/pagamentos/consultar_payment_order)
- Listar Payment Orders por Conta (/documentation/baas/pix_automatico/pagamentos/listar_account_payment_orders)
- Decodificar QR Code para Pix Automático (/documentation/baas/pix_automatico/qr_code/decodificar_qr_code)
- Cancelar recorrência de pagamento (/documentation/baas/pix_automatico/recebedor/cancelar_recorrencia)
- Consultar dados de uma recorrência por outgoing_recurrence_key (/documentation/baas/pix_automatico/recebedor/consultar_recorrencia)
- Consulta de Dados de Recorrência Automática Pix pelo QRCode (/documentation/baas/pix_automatico/recebedor/consultar_recorrencia_receiver)
- Conciliação e Liquidação de Pagamentos (/documentation/baas/pix_automatico/recebedor/introducao)
- Criar uma Recorrência (Jornada 4) (/documentation/baas/pix_automatico/recebedor/journey_four)
- Criar uma Recorrência (Jornada 1) (/documentation/baas/pix_automatico/recebedor/journey_one)
- Criar uma Recorrência (Jornada 3) (/documentation/baas/pix_automatico/recebedor/journey_three)
- Criar uma Recorrência (Jornada 2) (/documentation/baas/pix_automatico/recebedor/journey_two)
- Listagem de Recorrências de um Requester (/documentation/baas/pix_automatico/recebedor/listar_recorrencias_de_um_requester)
- Listagem de Recorrências de uma Conta (/documentation/baas/pix_automatico/recebedor/listar_recorrencias_de_uma_conta)
- Simulação de cenários (/documentation/baas/pix_automatico/recebedor/simulacao)
- Webhooks Pix Automático (/documentation/baas/pix_automatico/recebedor/webhooks)
---
# Consultar Dados de um Lote de Pagamentos por conta
URL: /documentation/baas/pix_automatico/conciliacao/consultar_lote_por_conta
## Request
ENDPOINT /account/ ACCOUNT_KEY /payment_order_conciliation_batch/ PAYMENT_ORDER_CONCILIATION_BATCH_KEY
MÉTODO GET
### Path Params
| Campo | Tipo | Descrição | Caracteres |
|--------------------------|--------|---------------------------------------------------|------------|
| **`ACCOUNT_KEY`** * | uuidv4 | Chave única de identificação da conta. | 36 |
| **`PAYMENT_ORDER_CONCILIATION_BATCH_KEY`***| uuidv4 | Chave única de identificação do lote. | 36 |
## Response
STATUS 200
Response Body
```json
{
"payment_order_conciliation_batch_status": "open",
"payment_order_conciliation_batch_type": "fixed_amount",
"total_amount": 1000.00,
"conciliated_amount": 500.00,
"total_payment_orders": 10,
"conciliated_payment_orders": 5,
"reference_date": "2025-06-13",
"created_at": "2025-06-10T20:30:23.459Z"
}
```
### Response Body Params
| Campo | Tipo | Descrição | Caracteres |
|------------------------------------------|------------|----------------------------------------------------------------|------------|
| `payment_order_conciliation_batch_status`| enumerator | Status do lote de conciliação de ordens de pagamento. | [Enumeradores payment_order_conciliation_batch_status](#enumeradores-payment_order_conciliation_batch_status) |
| `payment_order_conciliation_batch_type` | enumerator | Tipo do lote de conciliação de ordens de pagamento. | [Enumeradores payment_order_conciliation_batch_type](#enumeradores-payment_order_conciliation_batch_type) |
| `total_amount` | number | Valor total do lote de conciliação em reais (R$). | - |
| `conciliated_amount` | number | Valor já conciliado do lote em reais (R$). | - |
| `total_payment_orders` | integer | Número total de ordens de pagamento no lote. | - |
| `conciliated_payment_orders` | integer | Número de ordens de pagamento já conciliadas no lote. | - |
| `reference_date` | string | Data de referência do lote (formato ISO 8601, e.g., "2025-06-13"). | 10 |
| `created_at` | string | Data e hora de criação do lote (formato ISO 8601). | - |
### Enumeradores payment_order_conciliation_batch_status
| Enumerador | Descrição |
|--------------|---------------------------------------------|
| `open` | Lote de conciliação aberto |
| `closed` | Lote de conciliação fechado |
| `processing` | Lote de conciliação em processamento |
| `completed` | Lote de conciliação concluído |
| `cancelled` | Lote de conciliação cancelado |
### Enumeradores payment_order_conciliation_batch_type
| Enumerador | Descrição |
|-------------------|---------------------------------------------|
| `fixed_amount` | Lote de conciliação de valor fixo |
| `variable_amount` | Lote de conciliação de valor variável |
STATUS 4XX
Response Error
```json
{
"title": "titulo",
"description": "description in English",
"translation": "descrição em português",
"code": "codigo"
}
```
| Código HTTP | Código QI
`code` | Título
`title` | Descrição (eng)
`description` | Descrição (ptbr)
`translation` |
|-------------|----------------------|-----------------------------------|----------------------------------------------------------------------------|--------------------------------------------------------------------|
| 400 | QIT000002 | Bad Request | Invalid request schema. | Erro no esquema da requisição. |
| 404 | APX000003 | Conciliation Batch Not Found | Conciliation batch \{conciliation_batch_key\} not found. | Lote de conciliação \{conciliation_batch_key\} não encontrado. |
---
# Consultar Lotes de Pagamentos por Requester
URL: /documentation/baas/pix_automatico/conciliacao/consultar_lote_requester
## Request
ENDPOINT /payment_order_conciliation_batches
MÉTODO GET
### Query Params
| Campo | Tipo | Descrição | Obrigatório |
|------------------------------------------|------------|----------------------------------------------------------------|-------------|
| `payment_order_conciliation_batch_status`| enumerator | Filtro por status do lote de conciliação. | Não |
| `payment_order_conciliation_batch_type` | enumerator | Filtro por tipo do lote de conciliação. | Não |
| `page` | integer | Número da página para paginação (padrão: 1). | Não |
| `page_size` | integer | Tamanho da página para paginação (padrão: 25). | Não |
| `from_date` | string | Data inicial para filtro (formato ISO 8601, e.g., "2025-06-01"). | Não |
| `to_date` | string | Data final para filtro (formato ISO 8601, e.g., "2025-06-30"). | Não |
## Response
STATUS 200
Response Body
```json
{
"payment_order_conciliation_batches": [
{
"payment_order_conciliation_batch_key": "98fc62fd-b0a0-4604-9bea-475e91a9dc82",
"payment_order_conciliation_batch_status": "closed",
"payment_order_conciliation_batch_type": "fixed_amount",
"account_key": "9b9ae7b0-7292-4b0d-9131-0167525ab067",
"total_amount": 1200,
"conciliated_amount": 1200,
"total_payment_orders": 12,
"conciliated_payment_orders": 12,
"reference_date": "2025-06-13",
"created_at": "2025-06-10T20:30:23.459Z"
},
{
"payment_order_conciliation_batch_key": "98fc62fd-b0a0-4604-9bea-475e91a9dc82",
"payment_order_conciliation_batch_status": "closed",
"payment_order_conciliation_batch_type": "variable_amount",
"account_key": "9b9ae7b0-7292-4b0d-9131-0167525ab067",
"total_amount": 700,
"conciliated_amount": 600,
"total_payment_orders": 7,
"conciliated_payment_orders": 6,
"reference_date": "2025-06-13",
"created_at": "2025-06-10T20:30:23.459Z"
},
{
"payment_order_conciliation_batch_key": "98fc62fd-b0a0-4604-9bea-475e91a9dc82",
"payment_order_conciliation_batch_status": "open",
"payment_order_conciliation_batch_type": "variable_amount",
"account_key": "9b9ae7b0-7292-4b0d-9131-0167525ab067",
"total_amount": 900,
"conciliated_amount": 700,
"total_payment_orders": 9,
"conciliated_payment_orders": 7,
"reference_date": "2025-06-17",
"created_at": "2025-06-10T20:30:23.459Z"
},
{
"payment_order_conciliation_batch_key": "98fc62fd-b0a0-4604-9bea-475e91a9dc82",
"payment_order_conciliation_batch_status": "closed",
"payment_order_conciliation_batch_type": "fixed_amount",
"account_key": "c24a0ac4-792c-494e-b887-6185e07a33a3",
"total_amount": 800,
"conciliated_amount": 800,
"total_payment_orders": 8,
"conciliated_payment_orders": 8,
"reference_date": "2025-06-13",
"created_at": "2025-06-10T20:30:23.459Z"
},
{
"payment_order_conciliation_batch_key": "98fc62fd-b0a0-4604-9bea-475e91a9dc82",
"payment_order_conciliation_batch_status": "open",
"payment_order_conciliation_batch_type": "variable_amount",
"account_key": "c24a0ac4-792c-494e-b887-6185e07a33a3",
"total_amount": 1000,
"conciliated_amount": 500,
"total_payment_orders": 10,
"conciliated_payment_orders": 5,
"reference_date": "2025-06-17",
"created_at": "2025-06-10T20:30:23.459Z"
}
],
"pagination": {
"page": 1,
"page_size": 25,
"number_of_pages": 1
}
}
```
### Response Body Params
| Campo | Tipo | Descrição | Caracteres |
|--------------------------------------|-------|--------------------------------------------------------------|------------|
| `payment_order_conciliation_batches` | array | Lista de lotes de conciliação de ordens de pagamento. | [Array payment_order_conciliation_batches](#array-payment_order_conciliation_batches) |
| `pagination` | object| Informações de paginação da consulta. | [Objeto pagination](#objeto-pagination) |
### Array payment_order_conciliation_batches
| Campo | Tipo | Descrição | Caracteres |
|------------------------------------------|------------|----------------------------------------------------------------|------------|
| `payment_order_conciliation_batch_key` | uuidv4 | Identificador único do lote de conciliação. | 36 |
| `payment_order_conciliation_batch_status`| enumerator | Status do lote de conciliação de ordens de pagamento. | [Enumeradores payment_order_conciliation_batch_status](#enumeradores-payment_order_conciliation_batch_status) |
| `payment_order_conciliation_batch_type` | enumerator | Tipo do lote de conciliação de ordens de pagamento. | [Enumeradores payment_order_conciliation_batch_type](#enumeradores-payment_order_conciliation_batch_type) |
| `account_key` | uuidv4 | Chave única de identificação da conta. | 36 |
| `total_amount` | number | Valor total do lote de conciliação em reais (R$). | - |
| `conciliated_amount` | number | Valor já conciliado do lote em reais (R$). | - |
| `total_payment_orders` | integer | Número total de ordens de pagamento no lote. | - |
| `conciliated_payment_orders` | integer | Número de ordens de pagamento já conciliadas no lote. | - |
| `reference_date` | string | Data de referência do lote (formato ISO 8601, e.g., "2025-06-13"). | 10 |
| `created_at` | string | Data e hora de criação do lote (formato ISO 8601). | - |
### Objeto pagination
| Campo | Tipo | Descrição | Caracteres |
|--------------------|---------|------------------------------------------------|------------|
| `page` | integer | Página atual da consulta. | - |
| `page_size` | integer | Tamanho da página (número de itens por página). | - |
| `number_of_pages` | integer | Número total de páginas disponíveis. | - |
### Enumeradores payment_order_conciliation_batch_status
| Enumerador | Descrição |
|--------------|---------------------------------------------|
| `open` | Lote de conciliação aberto |
| `closed` | Lote de conciliação fechado |
| `processing` | Lote de conciliação em processamento |
| `completed` | Lote de conciliação concluído |
| `cancelled` | Lote de conciliação cancelado |
### Enumeradores payment_order_conciliation_batch_type
| Enumerador | Descrição |
|-------------------|---------------------------------------------|
| `fixed_amount` | Lote de conciliação de valor fixo |
| `variable_amount` | Lote de conciliação de valor variável |
STATUS 4XX
Response Error
```json
{
"title": "titulo",
"description": "description in English",
"translation": "descrição em português",
"code": "codigo"
}
```
| Código HTTP | Código QI
`code` | Título
`title` | Descrição (eng)
`description` | Descrição (ptbr)
`translation` |
|-------------|----------------------|-----------------------------------|----------------------------------------------------------------------------|--------------------------------------------------------------------|
| 400 | QIT000002 | Bad Request | Invalid request schema. | Erro no esquema da requisição. |
| 404 | APX000003 | Conciliation Batch Not Found | Conciliation batch not found. | Lote de conciliação não encontrado. |
---
# Listagem de Pagamentos de uma Conta
URL: /documentation/baas/pix_automatico/conciliacao/listar_payment_orders
## Request
ENDPOINT /account/ ACCOUNT_KEY /payment_order_conciliation_batch/ PAYMENT_ORDER_CONCILIATION_BATCH_KEY /payment_orders
MÉTODO GET
### Query Params
| Campo | Tipo | Descrição | Caracteres |
|------------------------|------------|--------------------------------------------------------------------------------|------------|
| `payment_order_status` | enumerador | Filtra pagamentos pelo status (e.g., `processed`, `pending`, `failed`). | 30 |
| `page` | integer | Número da página a ser retornada (paginação). | - |
| `page_size` | integer | Número de itens por página (paginação). | - |
## Response
STATUS 200
Response Body
```json
{
"payment_orders": [
{
"payment_order_key": "a1b2c3d4-e5f6-7890-ghij-1234567890kl",
"payment_order_status": "processed",
"amount": 150.75,
"currency": "BRL",
"transaction_date": "2023-10-05",
"recipient_data": {
"name": "Maria Silva",
"document_number": "12345678900",
"bank_account": {
"account_number": "987654",
"account_digit": "2",
"account_branch": "1234",
"ispb": "12345678"
}
},
"pix_key": "maria@example.com",
"pix_message": "Pagamento ref. Fatura 123",
"conciliation_id": "uuid-conciliation"
}
],
"pagination": {
"page": 1,
"page_size": 25,
"number_of_pages": 3
}
}
```
## Response Body Params
| Campo | Tipo | Descrição | Caracteres |
|-----------------|--------|---------------------------------------------------------|------------|
| `payment_orders`| array | Lista de objetos de pedidos de pagamento. | [Array payment_orders](#array-payment_orders) |
| `pagination` | object | Objeto de paginação contendo informações dos resultados. | [Objeto pagination](#objeto-pagination) |
---
### Array payment_orders
| Campo | Tipo | Descrição | Caracteres |
|-----------------------|------------|-------------------------------------------------------------------------|------------|
| `payment_order_key` | uuidv4 | Identificador único do pedido de pagamento. | 36 |
| `payment_order_status`| string | Status do pedido de pagamento (`processed`, `pending`, `failed`, etc.). | 30 |
| `amount` | number | Valor do pedido de pagamento em reais (R$). | - |
| `currency` | string | Moeda do pagamento. | 3 |
| `transaction_date` | string | Data da transação (formato ISO 8601, e.g., `2023-10-05`). | 10 |
| `recipient_data` | object | Dados do destinatário do pagamento. | [Objeto recipient_data](#objeto-recipient_data) |
| `pix_key` | string | Chave Pix do destinatário. | 77 |
| `pix_message` | string | Mensagem enviada junto à transação Pix. | 140 |
| `conciliation_id` | string | Identificador de conciliação do pagamento. | 36 |
---
### Objeto recipient_data
| Campo | Tipo | Descrição | Caracteres |
|-------------------|--------|-------------------------|------------|
| `name` | string | Nome do destinatário. | 50 |
| `document_number` | string | CPF ou CNPJ do destinatário. | 14 |
| `bank_account` | object | Dados da conta bancária do destinatário. | [Objeto bank_account](#objeto-bank_account) |
---
### Objeto bank_account
| Campo | Tipo | Descrição | Caracteres |
|-----------------|--------|------------------------------|------------|
| `account_number`| string | Número da conta. | - |
| `account_digit` | string | Dígito da conta. | - |
| `account_branch`| string | Agência. | - |
| `ispb` | string | ISPB da instituição financeira.| - |
### Objeto pagination
| Campo | Tipo | Descrição | Caracteres |
|------------------|---------|-------------------------------------|------------|
| `page` | integer | Número da página retornada. | - |
| `page_size` | integer | Quantidade de itens por página. | - |
| `number_of_pages`| integer | Total de páginas disponíveis. |
- |
### Enumeradores payment_order_status
| Enumerador | Descrição |
|-----------------------|----------------------------------------------------|
| `pending_conciliation`| Aguardando conciliação. |
| `pending` | Pendente e ainda não processada. |
| `accepted` | Aceita e aguardando pagamento. |
| `paid` | Paga com sucesso. |
| `rejected` | Rejeitada e não será processada. |
| `cancelled` | Cancelada antes do pagamento. |
STATUS 4XX
Response Error
```json
{
"title": "titulo",
"description": "description in English",
"translation": "descrição em português",
"code": "codigo"
}
```
| Código HTTP | Código QI
`code` | Título
`title` | Descrição (eng)
`description` | Descrição (ptbr)
`translation` |
|-------------|----------------------|-----------------------------------|----------------------------------------------------------------------------|--------------------------------------------------------------------|
| 400 | QIT000002 | Bad Request | Invalid request schema. | Erro no esquema da requisição. |
| 404 | APX000002 | Payment Order Not Found | Payment order \{payment_order_key\} not found. | Pedido de pagamento \{payment_order_key\} não encontrado. |
---
# Webhook de Criação de Lote de Conciliação de Ordens de Pagamento
URL: /documentation/baas/pix_automatico/conciliacao/webhooks
As notificações via webhook são essenciais para processamento de eventos sobre conciliação de pagamentos no Pix Automático. Este webhook informa sobre a criação de lotes de conciliação de ordens de pagamento.
## Webhook de Criação de Lote de Conciliação
Este webhook é emitido quando um novo lote de conciliação de ordens de pagamento é criado.
:::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: Jornada 1
```json
{
"webhook_type": "baas.automatic_pix.payment_order_conciliation_batch.creation",
"webhook_datetime": "2021-10-22T20:30:23.459Z",
"data": {
"payment_order_conciliation_batches": [
{
"payment_order_conciliation_batch_key": "98fc62fd-b0a0-4604-9bea-475e91a9dc82",
"payment_order_conciliation_batch_status": "open",
"payment_order_conciliation_batch_type": "fixed_amount",
"account_key": "uuid",
"total_amount": 0,
"conciliated_amount": 0,
"total_payment_orders": 0,
"conciliated_payment_orders": 0,
"reference_date": "2025-06-13",
"created_at": "2025-06-10T20:30:23.459Z"
},
{
"payment_order_conciliation_batch_key": "99fc62fd-b0a0-4604-9bea-475e91a9dc82",
"payment_order_conciliation_batch_status": "open",
"payment_order_conciliation_batch_type": "variable_amount",
"account_key": "uuid",
"total_amount": 0,
"conciliated_amount": 0,
"total_payment_orders": 0,
"conciliated_payment_orders": 0,
"reference_date": "2025-06-13",
"created_at": "2025-06-10T20:30:23.459Z"
}
]
}
}
```
### Webhook Body Params
| Campo | Tipo | Descrição | Caracteres |
|-------------------|---------|-----------------------------------------------------------------------------------------------|------------|
| `webhook_type` * | string | Tipo do evento do webhook (`baas.automatic_pix.payment_order_conciliation_batch.creation`). | 100 |
| `webhook_datetime` * | string | Data e hora que o webhook foi gerado (formato ISO 8601). | - |
| `data` * | Object | Objeto contendo detalhes dos lotes de conciliação. | [Objeto data](#objeto-data) |
---
### Objeto data
| Campo | Tipo | Descrição | Caracteres |
|---------------------------------------|-------|-----------------------------------------------------------------------------------|------------|
| `payment_order_conciliation_batches` * | array | Lista de lotes de conciliação criados. | [Array payment_order_conciliation_batches](#array-payment_order_conciliation_batches) |
### Array payment_order_conciliation_batches
| Campo | Tipo | Descrição | Caracteres |
|----------------------------------------|---------|--------------------------------------------------------------------------|------------|
| `payment_order_conciliation_batch_key` | string | Chave única do lote de conciliação. | 36 |
| `payment_order_conciliation_batch_status` | string | Status do lote de conciliação (`open`). | - |
| `payment_order_conciliation_batch_type` | string | Tipo do lote de conciliação (`fixed_amount`, `variable_amount`). | - |
| `account_key` | uuidv4 | Chave de identificação da conta associada ao lote. | 36 |
| `total_amount` | number | Valor total do lote de conciliação. | - |
| `conciliated_amount` | number | Valor total conciliado no lote. | - |
| `total_payment_orders` | number | Número total de ordens de pagamento no lote. | - |
| `conciliated_payment_orders` | number | Número de ordens de pagamento conciliadas no lote. | - |
| `reference_date` | string | Data de referência do lote (formato YYYY-MM-DD). | 10 |
| `created_at` | string | Data de criação do lote (formato ISO 8601). | - |
---
# FAQ - Pix Automático
URL: /documentation/baas/pix_automatico/faq
{`
.faq-container {
margin: 30px 0;
}
.faq-section {
margin-bottom: 40px;
}
.faq-section-title {
font-size: 20px;
font-weight: 700;
color: #0f172a;
margin-bottom: 24px;
padding-bottom: 12px;
border-bottom: 2px solid #e5e7eb;
}
.faq-grid {
display: grid;
grid-template-columns: 1fr;
gap: 20px;
}
.faq-card {
background: linear-gradient(135deg, #ffffff 0%, #f8fafc 100%);
border: 2px solid #1e40af;
border-radius: 12px;
padding: 24px;
transition: all 0.3s ease;
position: relative;
overflow: hidden;
width: 100%;
}
.faq-card::before {
content: '';
position: absolute;
top: 0;
left: 0;
width: 4px;
height: 100%;
background: linear-gradient(to bottom, rgb(40, 85, 232), #0f172a);
transition: width 0.3s ease;
}
.faq-card:hover {
transform: translateY(-4px);
box-shadow: 0 10px 25px rgba(0, 0, 0, 0.1);
border-color: #1e3a8a;
}
.faq-card:hover::before {
width: 6px;
}
.faq-question {
font-size: 18px;
font-weight: 700;
color: #0f172a;
margin-bottom: 16px;
display: flex;
align-items: flex-start;
gap: 12px;
line-height: 1.4;
}
.faq-question::before {
content: '';
font-size: 20px;
flex-shrink: 0;
margin-top: 2px;
}
.faq-answer {
font-size: 14px;
line-height: 1.7;
color: #475569;
margin: 0;
}
.faq-answer ul {
margin: 12px 0;
padding-left: 20px;
}
.faq-answer li {
margin-bottom: 8px;
line-height: 1.6;
}
.faq-answer strong {
color: #0f172a;
font-weight: 700;
}
@media (max-width: 768px) {
.faq-grid {
grid-template-columns: 1fr;
}
}
`}
Perguntas sobre Recorrências
Uma recorrência precisa ter vigência ou quantidade de pagamentos pré-definidos?
A vigência da recorrência é um parâmetro definido na relação entre o recebedor e o pagador. A autorização pode ser concedida por período indefinido , ou alternativamente ter pré-definidos o número de cobranças ou a data final de vigência .
A data escolhida para o débito poderá ser qualquer uma dentro do ciclo?
Sim, desde que respeitada a antecedência mínima de 2 dias entre a data do agendamento e a data prevista para a liquidação, que deverá ser anterior à data de início do próximo ciclo .
Perguntas sobre Jornadas de Autorização
Qual a diferença principal entre as jornadas com QR Code?
A diferença principal está na experiência do usuário e no momento da autorização da recorrência. A Jornada 2 autoriza apenas a recorrência futura, sem processar pagamento na hora. A Jornada 3 permite o primeiro pagamento imediato junto com a autorização da recorrência - o pagamento efetuado é o que ativa a recorrência. A Jornada 4 funciona de forma diferente: o usuário lê um QR Code como se fosse um PIX normal, e após realizar o pagamento ou agendamento, o sistema oferece a opção de pix automático para ele. A Jornada 4 é a única que suporta recorrências de valor variável e oferece mais flexibilidade na experiência do usuário.
Se, por meio da jornada 3, ocorrer sucesso na liquidação e insucesso na autorização, será necessário o cancelamento do pagamento, já que o fluxo prevê o sucesso de ambos?
Fica a critério do usuário recebedor . Ele poderá devolver o Pix liquidado e viabilizar uma nova jornada 3 ou poderá oferecer outra jornada de autorização do Pix Automático com a finalidade exclusiva de viabilizar a autorização para pagamentos subsequentes.
Perguntas Frequentes sobre Lotes de Conciliação
O que são lotes de conciliação?
Os lotes de conciliação são agrupamentos de pagamentos que são criados automaticamente pelo sistema para facilitar a conciliação e controle dos pagamentos do Pix Automático. Eles servem como uma forma de organizar e rastrear os pagamentos por data de liquidação e tipo de recorrência.
Como os pagamentos são agrupados em lotes?
Os pagamentos são agrupados automaticamente em lotes baseados em critérios como:
Data de liquidação prevista para o pagamento
Tipo de recorrência: fixed_amount ou variable_amount
Conta específica
Requester específico
Quando um lote é criado?
Os lotes são criados automaticamente pelo sistema quando há ordens de pagamento que precisam ser processadas para determinada data de pagamento. O sistema agrupa essas ordens que possuem liquidação no mesmo dia em lotes , para facilitar o processamento, visualização e conciliação.
Quando um lote é fechado?
Um lote é fechado sempre três dias antes da data de referência de pagamento daquele lote, pois as ordens de pagamento precisam ser enviadas com até no máximo dois dias de antecedência referente à data de pagamento daquele ciclo. Ou seja, quando chega a data do seu fechamento.
O sistema calcula automaticamente essa data baseado na data de liquidação do pagamento menos 3 dias, garantindo que as instruções de pagamento sejam enviadas dentro do prazo regulamentar estabelecido pelo Banco Central.
Posso consultar pagamentos de lotes fechados?
Sim, você pode consultar pagamentos de lotes fechados através dos endpoints de consulta de lotes e listagem de pagamentos de um lote específico.
Perguntas sobre Ordens de Pagamento e Tentativas
Qual a diferença entre ordem de pagamento e tentativa de pagamento?
Ordem de Pagamento: É a instrução criada pelo sistema para realizar um pagamento específico em uma data determinada.
Tentativa de Pagamento: É cada execução individual dessa ordem de pagamento, podendo haver múltiplas tentativas se a primeira falhar.
Quantas tentativas de pagamento são realizadas?
O sistema realiza até 4 tentativas de pagamento por ordem de pagamento. Se todas as tentativas falharem, a ordem de pagamento é marcada como rejeitada.
O que acontece quando todas as tentativas falham?
Quando todas as 4 tentativas de pagamento falham, a ordem de pagamento tem seu status alterado para "rejected" e não serão realizadas mais tentativas para o pagamento desse ciclo.
Como funcionam as retentativas?
As retentativas são executadas automaticamente pelo sistema de acordo com os dias de retentativas configurados pelo recebedor na hora da criação da recorrência. Cada tentativa que falha gera um webhook de notificação para que você possa acompanhar o status desse pagamento.
Perguntas sobre Cancelamentos
Posso cancelar uma ordem de pagamento específica?
Sim, você pode cancelar uma ordem de pagamento específica através do endpoint de cancelamento de ordem de pagamento, desde que ela ainda não tenha sido liquidada.
Qual a diferença entre cancelar uma recorrência e cancelar uma ordem de pagamento?
Cancelar Recorrência: Cancela toda a recorrência e todas as ordens de pagamento futuras associadas a ela.
Cancelar Ordem de Pagamento: Cancela apenas a ordem de pagamento específica daquele ciclo, sem afetar a recorrência ou outras ordens.
Perguntas sobre Simulação
Para que servem os cenários de simulação?
Os cenários de simulação servem para testar o fluxo completo do Pix Automático no ambiente sandbox, simulando as respostas e interações do PSP Pagador (Provedor de Serviços de Pagamento).
Como usar adequadamente os cenários de simulação?
Os cenários devem ser executados em sequência para simular o fluxo completo:
Criar uma recorrência
Processar ordens de pagamento
Atualizar datas de execução (sandbox)
Processar tentativas de pagamento
Simular PIX de entrada
Simular tentativas rejeitadas (se necessário)
Perguntas sobre Webhooks
Quais webhooks são enviados pelo Pix Automático?
O sistema envia webhooks para diversos eventos, incluindo:
Mudanças de status de recorrências
Mudanças de status de ordens de pagamento
Mudanças de status de tentativas de pagamento
Criação e fechamento de lotes de conciliação
Perguntas sobre Benefícios e Comparações
Quais são os principais benefícios para os recebedores aderirem ao Pix Automático relativamente aos demais meios de pagamento existentes?
O Pix Automático oferece uma nova opção aos usuários recebedores para o recebimento e gestão das cobranças periódicas recorrentes, utilizando a infraestrutura do Pix. Dentre as vantagens, destacam-se: aumento da base de clientes , menor custo operacional por não precisar firmar convênios com mais de uma instituição, diversificação da forma de pagamento , oferecendo o Pix como alternativa aos clientes que usam cartão ou boleto, além da redução da inadimplência e mais agilidade no gerenciamento de seus recebimentos.
Qual a principal diferença entre o débito automático em conta (tradicional) e o Pix Automático?
Com foco na experiência tanto dos usuários recebedores, quanto dos pagadores, o Pix Automático apresenta novas funcionalidades para gerenciamento de autorizações e agendamentos recorrentes . Além disso, qualquer participante do Pix pode oferecer o produto a seus clientes, ampliando o acesso de cidadãos e empresas que hoje não são atendidos pelo serviço de débito automático, ofertado de forma mais restrita apenas entre instituições bancárias.
---
# Introdução ao Pix Automático
URL: /documentation/baas/pix_automatico/introducao
O **Pix Automático** é uma solução inovadora que automatiza pagamentos recorrentes de forma simplificada, eficiente e segura. Ideal para negócios que trabalham com assinaturas, mensalidades ou cobranças recorrentes de contas, o Pix Automático evolui dos métodos tradicionais ao eliminar a necessidade de interação manual, reduzir inadimplências e facilitar a gestão financeira, atendendo tanto empresas quanto consumidores.
{`
.hero-section {
background: linear-gradient(135deg, #eff6ff 0%, #ffffff 100%);
border: 1px solid #e5e7eb;
border-radius: 16px;
padding: 24px;
margin: 24px 0 32px 0;
}
.hero-grid {
display: grid;
grid-template-columns: repeat(auto-fit, minmax(200px, 1fr));
gap: 16px;
margin-top: 20px;
}
.hero-item {
background: #ffffff;
border: 1px solid #e5e7eb;
border-radius: 10px;
padding: 16px;
}
.hero-item strong {
display: block;
color: #1e40af;
font-size: 14px;
margin-bottom: 6px;
}
.hero-item p {
margin: 0;
font-size: 13px;
color: #475569;
line-height: 1.5;
}
.flow-section {
margin: 32px 0;
}
.flow-grid {
display: grid;
grid-template-columns: repeat(auto-fit, minmax(220px, 1fr));
gap: 16px;
margin-top: 20px;
}
.flow-step-card {
border-radius: 12px;
padding: 18px;
color: #ffffff;
min-height: 100px;
display: flex;
flex-direction: column;
gap: 8px;
}
.flow-step-card h4 {
margin: 0;
font-size: 15px;
font-weight: 700;
}
.flow-step-card p {
margin: 0;
font-size: 13px;
opacity: 0.95;
line-height: 1.5;
}
`}
Como funciona na prática?
Para quem?
Ideal para empresas que oferecem assinaturas, serviços recorrentes, mensalidades escolares, planos de saúde e similares.
O que preciso fazer?
O recebedor cria uma recorrência e o pagador autoriza uma única vez. Depois, os pagamentos acontecem automaticamente em cada ciclo.
Vantagens principais
Reduz atrasos, elimina necessidade de lembrar datas de pagamento e simplifica a gestão financeira para ambas as partes.
### Fluxo em 4 etapas simples
1. Criar Recorrência
O recebedor define as características da cobrança recorrente (valor, periodicidade, data de início).
2. Autorizar
O pagador autoriza uma única vez no aplicativo do banco, escolhendo uma das 4 jornadas disponíveis.
3. Agendar
A cada ciclo, o recebedor envia a instrução de pagamento e o banco do pagador agenda automaticamente.
4. Liquidar
Na data agendada, o débito e crédito são processados automaticamente na conta de cada parte.
---
## Funcionalidades da API do Pix Automático
A QI Tech, por meio de sua **API Automatic Pix**, capacita a integração de pagamentos automáticos usando o Pix, com base em autorizações prévias do pagador ao recebedor. O sistema abrange as seguintes responsabilidades:
{`
.features-grid {
display: grid;
grid-template-columns: repeat(auto-fit, minmax(280px, 1fr));
gap: 20px;
margin: 30px 0;
}
.feature-card {
background: linear-gradient(135deg, #ffffff 0%, #f8fafc 100%);
border: 2px solid #e5e7eb;
border-radius: 12px;
padding: 24px;
transition: all 0.3s ease;
position: relative;
overflow: hidden;
}
.feature-card::before {
content: '';
position: absolute;
top: 0;
left: 0;
width: 4px;
height: 100%;
background: linear-gradient(to bottom, #3b82f6, #1e40af);
transition: width 0.3s ease;
}
.feature-card:hover {
transform: translateY(-4px);
box-shadow: 0 10px 25px rgba(0, 0, 0, 0.1);
border-color: #3b82f6;
}
.feature-card:hover::before {
width: 6px;
}
.feature-title {
font-size: 16px;
font-weight: 700;
color: #1e40af;
margin-bottom: 12px;
display: flex;
align-items: center;
gap: 10px;
}
.feature-icon {
font-size: 20px;
}
.feature-description {
font-size: 14px;
line-height: 1.6;
color: #475569;
margin: 0;
}
.recurrence-types {
display: grid;
grid-template-columns: repeat(auto-fit, minmax(300px, 1fr));
gap: 24px;
margin: 30px 0;
}
.recurrence-card {
background: #ffffff;
border-radius: 16px;
padding: 28px;
border: 2px solid;
position: relative;
transition: all 0.3s ease;
box-shadow: 0 4px 12px rgba(0, 0, 0, 0.08);
}
.recurrence-card:hover {
transform: translateY(-5px);
box-shadow: 0 12px 30px rgba(0, 0, 0, 0.12);
}
.recurrence-card.fixed {
border-color:rgb(11, 63, 250);
background: linear-gradient(135deg, #ffffff 0%,rgb(235, 240, 255) 100%);
}
.recurrence-card.variable {
border-color:rgb(11, 63, 250);
background: linear-gradient(135deg, #ffffff 0%,rgb(235, 240, 255) 100%);
}
.recurrence-header {
display: flex;
align-items: center;
gap: 12px;
margin-bottom: 16px;
}
.recurrence-badge {
padding: 6px 14px;
border-radius: 20px;
font-size: 12px;
font-weight: 700;
text-transform: uppercase;
letter-spacing: 0.5px;
}
.recurrence-card.fixed .recurrence-badge {
background:rgb(16, 64, 185);
color: #ffffff;
}
.recurrence-card.variable .recurrence-badge {
background:rgb(16, 64, 185);
color: #ffffff;
}
.recurrence-title {
font-size: 20px;
font-weight: 700;
color: #0f172a;
margin: 0;
}
.recurrence-description {
font-size: 15px;
line-height: 1.7;
color: #475569;
margin-bottom: 16px;
}
.recurrence-detail {
background: rgba(255, 255, 255, 0.7);
border-left: 3px solid;
padding: 12px 16px;
border-radius: 8px;
font-size: 13px;
line-height: 1.6;
color: #64748b;
}
.recurrence-card.fixed .recurrence-detail {
border-left-color:rgb(203, 15, 68);
}
.recurrence-card.variable .recurrence-detail {
border-left-color:rgb(203, 15, 68);
}
.periodicity-container {
background: linear-gradient(135deg, #eff6ff 0%, #ffffff 100%);
border: 2px solid #e5e7eb;
border-radius: 16px;
padding: 28px;
margin: 30px 0;
}
.periodicity-grid {
display: grid;
grid-template-columns: repeat(auto-fit, minmax(150px, 1fr));
gap: 16px;
margin-top: 20px;
}
.periodicity-item {
background: #ffffff;
padding: 16px;
border-radius: 10px;
text-align: center;
border: 2px solid #e5e7eb;
transition: all 0.3s ease;
}
.periodicity-item:hover {
border-color: #3b82f6;
transform: translateY(-3px);
box-shadow: 0 6px 20px rgba(59, 130, 246, 0.15);
}
.periodicity-label {
font-size: 14px;
font-weight: 600;
color: #1e40af;
margin: 0;
}
.journeys-container {
margin: 30px 0;
}
.journey-card {
background: #ffffff;
border: 2px solid #e5e7eb;
border-radius: 12px;
padding: 24px;
margin-bottom: 16px;
transition: all 0.3s ease;
border-left: 5px solid;
}
.journey-card:hover {
transform: translateX(5px);
box-shadow: 0 8px 20px rgba(0, 0, 0, 0.1);
}
.journey-card.journey-1 {
border-left-color: #3b82f6;
}
.journey-card.journey-2 {
border-left-color: #10b981;
}
.journey-card.journey-3 {
border-left-color: #f59e0b;
}
.journey-card.journey-4 {
border-left-color: #ec4899;
}
.journey-header {
display: flex;
align-items: center;
gap: 12px;
margin-bottom: 12px;
}
.journey-number {
background: linear-gradient(135deg, #1e40af, #3b82f6);
color: #ffffff;
width: 36px;
height: 36px;
border-radius: 50%;
display: flex;
align-items: center;
justify-content: center;
font-weight: 700;
font-size: 16px;
flex-shrink: 0;
}
.journey-card.journey-1 .journey-number {
background: linear-gradient(135deg, #1e40af, #3b82f6);
}
.journey-card.journey-2 .journey-number {
background: linear-gradient(135deg, #059669, #10b981);
}
.journey-card.journey-3 .journey-number {
background: linear-gradient(135deg, #d97706, #f59e0b);
}
.journey-card.journey-4 .journey-number {
background: linear-gradient(135deg, #db2777, #ec4899);
}
.journey-title {
font-size: 18px;
font-weight: 700;
color: #0f172a;
margin: 0;
}
.journey-description {
font-size: 14px;
line-height: 1.7;
color: #475569;
margin: 0;
padding-left: 48px;
}
.cancellation-info {
background: linear-gradient(135deg, #f8fafc 0%, #ffffff 100%);
border: 2px solid #e5e7eb;
border-radius: 16px;
padding: 28px;
margin: 30px 0;
}
.cancellation-list {
list-style: none;
padding: 0;
margin: 20px 0 0 0;
}
.cancellation-item {
background: #ffffff;
padding: 16px 20px;
border-radius: 10px;
margin-bottom: 12px;
border-left: 4px solid #3b82f6;
display: flex;
gap: 12px;
}
.cancellation-item:last-child {
margin-bottom: 0;
}
.cancellation-label {
font-weight: 700;
color: #1e40af;
min-width: 180px;
}
.cancellation-text {
color: #475569;
flex: 1;
margin: 0;
}
.advantages-grid {
display: grid;
grid-template-columns: repeat(auto-fit, minmax(280px, 1fr));
gap: 20px;
margin: 30px 0;
}
.advantage-card {
background: linear-gradient(135deg, #ffffff 0%, #f0fdf4 100%);
border: 2px solid #d1fae5;
border-radius: 12px;
padding: 20px;
transition: all 0.3s ease;
}
.advantage-card:hover {
transform: translateY(-4px);
border-color: #10b981;
box-shadow: 0 10px 25px rgba(16, 185, 129, 0.15);
}
.advantage-text {
font-size: 14px;
line-height: 1.7;
color: #475569;
margin: 0;
display: flex;
align-items: flex-start;
gap: 10px;
}
.advantage-icon {
color: #10b981;
font-size: 18px;
flex-shrink: 0;
margin-top: 2px;
}
@media (max-width: 768px) {
.features-grid,
.recurrence-types,
.advantages-grid {
grid-template-columns: 1fr;
}
.periodicity-grid {
grid-template-columns: repeat(2, 1fr);
}
.journey-description {
padding-left: 0;
margin-top: 12px;
}
}
`}
Criação e Gestão
Facilita a criação, gestão e cancelamento de recorrências de forma simplificada e eficiente.
Orquestração de Autorizações
Garante que os pagamentos recorrentes do Pix Automático sejam autorizados corretamente pelo pagador.
Agendamento e Liquidação
Automatiza completamente os ciclos de pagamento, desde o agendamento até a liquidação.
Logs e Auditorias
Mantém registro completo de todas as operações para conformidade com as regras do Bacen.
---
## Tipos de Recorrência
Valor Fixo
Recorrência de Valor Fixo
Na modalidade de valor fixo, o pagador autoriza a recorrência de pagamentos periódicos de valores fixos, previamente estabelecidos na criação da recorrência.
Ideal para: Assinaturas mensais, mensalidades escolares, planos de serviços com valores fixos.
Valor Variável
Recorrência de Valor Variável
Na modalidade de valor variável, o pagador e o recebedor concordam com uma faixa de valores permitidos para cada cobrança recorrente. O recebedor define o valor mínimo e o pagador define o valor máximo.
Importante: O recebedor deve conciliar a ordem de pagamento com o valor a ser cobrado no período de 10 a 3 dias antes da data da cobrança.
Ideal para: Modelos baseados em consumo, contas de serviços variáveis, pagamentos ajustáveis ao longo do tempo.
---
## Periodicidade das Recorrências
Atualmente, é possível realizar a criação de recorrências com as seguintes periodicidades:
Periodicidades Disponíveis
Semanal
Mensal
Trimestral
Semestral
Anual
---
## Jornadas de Autorização do Pix Automático
O Pix Automático suporta várias jornadas de autorização para atender a diferentes cenários de negócio:
1
Jornada 1: Push Notification
Notificação via app para confirmação da recorrência, sem necessidade de QR Code. O pagador recebe uma notificação e autoriza diretamente no aplicativo.
2
Jornada 2: QR Code - Recorrência
Autorização com QR Code contendo apenas dados da recorrência. O pagador escaneia o QR Code e autoriza apenas a recorrência futura.
3
Jornada 3: QR Code + Primeiro Pagamento
QR Code permitindo o primeiro pagamento imediato e a configuração de recorrência simultaneamente. Ideal para casos onde deseja-se receber o primeiro pagamento e criar a recorrência na mesma transação.
4
Jornada 4: QR Code Completo
QR Code incluindo dados para pagamento/agendamento imediato e oferta de pix automático para aquela cobrança, após pagamento ou agendamento. Permite pagamento (ou agendamento) e oferta do pix automático em uma única operação.
:::info Documentação das Jornadas
Para detalhes completos sobre como implementar cada jornada, consulte:
- [Jornada 1 - Push Notification](./recebedor/journey_one.md)
- [Jornada 2 - QR Code (apenas recorrência)](./recebedor/journey_two.md)
- [Jornada 3 - QR Code (com primeiro pagamento)](./recebedor/journey_three.md)
- [Jornada 4 - QR Code (com primeiro pagamento e valores variáveis)](./recebedor/journey_four.md)
:::
---
## Cancelamento de Recorrência
Regras de Cancelamento
Solicitação de Cancelamento
Pode ser feita tanto pelo usuário pagador quanto pelo recebedor de forma unilateral, sem necessidade de aprovação mútua.
Impacto do Cancelamento
A autorização e a recorrência são canceladas simultaneamente, bloqueando novas instruções de pagamento automaticamente.
Processo de Cancelamento
O usuário pagador atualiza e comunica o status de cancelamento ao usuário recebedor, que deve ser informado imediatamente.
Efeitos Imediatos
Cancela automaticamente todos os agendamentos associados, exceto aqueles previstos para liquidação no próprio dia do cancelamento.
Iniciativa do Recebedor
O recebedor pode cancelar a recorrência por decisão própria ou sob solicitação do pagador através da API.
---
## Vantagens e Potencial
O Pix Automático oferece diversas vantagens, como a centralização de autorizações e pagamentos, incentivo à digitalização financeira, e eficiência em soluções de débito automático, suprindo lacunas dos métodos tradicionais de pagamento.
✓
Redução do risco de atrasos e da necessidade de lembrar datas de vencimento, com eliminação de etapas manuais
✓
Centralização do controle de autorizações e pagamentos em uma única plataforma
✓
Incentivo à digitalização dos processos financeiros e modernização do relacionamento com clientes
✓
Simplificação das operações para estabelecimentos e clientes finais
✓
Eficiência em soluções de débito automático com tecnologia Pix
✓
Preenchimento de lacunas existentes nos instrumentos tradicionais de pagamento
---
## Simulação de Cenários
Durante o desenvolvimento e testes da integração com o Pix Automático, é essencial validar todos os fluxos antes de utilizar o ambiente de produção. A **Simulação de Cenários** fornece um ambiente sandbox completo que permite testar todo o ciclo de vida de uma recorrência, desde a criação até a liquidação dos pagamentos.
### O que é a Simulação de Cenários?
A Simulação de Cenários é uma ferramenta que permite **testar o fluxo completo do Pix Automático** no ambiente sandbox, simulando as respostas da SPI (Sistema de Pagamentos Instantâneos) sem realizar transações reais. Ela abrange:
- **Criação e aprovação de recorrências** utilizando as 4 jornadas disponíveis
- **Processamento de ordens de pagamento** e criação de lotes de conciliação
- **Simulação de tentativas de pagamento** com diferentes resultados (sucesso ou rejeição)
- **Teste de fluxos de cancelamento** e gestão de recorrências
### Quando usar?
A simulação é recomendada para:
- **Validação de integração**: Testar se sua aplicação está corretamente integrada com a API
- **Desenvolvimento**: Desenvolver e debugar sua implementação sem custos
- **Testes de fluxos**: Validar diferentes cenários (pagamentos bem-sucedidos, rejeições, cancelamentos)
- **Treinamento**: Familiarizar sua equipe com os fluxos do Pix Automático antes de ir para produção
### Como usar?
O processo de simulação segue uma sequência de passos que replica o fluxo real:
1. **Criar uma recorrência** usando uma das jornadas de autorização
2. **Aprovar a recorrência** via mock, simulando a confirmação do pagador
3. **Processar ordens de pagamento** que criam automaticamente os lotes de conciliação
4. **Consultar e conciliar** as ordens (obrigatório para valores variáveis)
5. **Atualizar data de execução** para acelerar os testes no sandbox
6. **Processar tentativas** de pagamento
7. **Simular o resultado**: Pix de entrada (sucesso) ou rejeição
:::tip Documentação Completa
Para um guia passo a passo detalhado sobre como usar a simulação de cenários, incluindo todos os endpoints disponíveis e exemplos de requisições, consulte:
**[📋 Guia de Simulação de Cenários](./recebedor/simulacao.md)**
:::
### Benefícios da Simulação
✓
Testes sem custos ou riscos, em ambiente controlado e isolado
✓
Validação completa de todos os fluxos antes da produção
✓
Aceleração de datas e processos para testes mais rápidos
✓
Simulação de diferentes cenários (sucessos, falhas, cancelamentos)
---
# Aceitar recorrência de pagamento
URL: /documentation/baas/pix_automatico/movimentacoes/aceitar_recorrencia
## Request
ENDPOINT /account/ ACCOUNT_KEY /incoming_recurrence/ INCOMING_RECURRENCE_KEY /approve
MÉTODO PATCH
### Request Path Params
| Campo | Tipo | Descrição | Caracteres |
|-------------|--------|--------------------------------|------------|
| `account_key` * | uuid4 | Chave única de identificação da conta. | 36 |
| `incoming_recurrence_key` * | uuid4 | Chave única de identificação da autorização | 36 |
### Request Body
Request Body: Aprovar recorrência de valor fixo
```json
{
"incoming_recurrence_status": "active"
}
```
Request Body: Aprovar recorrência de valor variável com limite máximo
```json
{
"incoming_recurrence_status": "active",
"maximum_transaction_amount": 500.00
}
```
### Body Params
| Campo | Tipo | Descrição | Caracteres |
|-------------------------|------------|--------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|------------|
| `incoming_recurrence_status` * | string | Identificador de status da recorrência Pix. Deve ser "active" para ativar a recorrência | 20 |
| `maximum_transaction_amount` | number | Valor máximo que o usuário aceita pagar por transação (opcional, apenas para recorrências de valor variável) | 10 |
:::info Valor Máximo para Recorrências Variáveis
O campo `maximum_transaction_amount` é **opcional** e deve ser usado apenas para **recorrências de valor variável**. Ele permite que o pagador defina o valor máximo que aceita pagar por transação dentro da recorrência autorizada.
:::
## Response
STATUS 200
Response Body: Recorrência ativada
```json
{
"incoming_recurrence_key": "cfa32109-a6dd-4304-94db-03a7b6d92a47",
"incoming_recurrence_status": "active",
"created_at": "2025-05-22T20:30:23.459Z",
"updated_at": "2025-05-22T20:39:23.459Z"
}
```
STATUS 4XX
Response Body
```json
{
"title": "titulo",
"description": "description in English",
"translation": "descrição em portugues",
"code": "codigo"
}
```
| Código HTTP | Código QI
`code` | Título
`title` | Descrição (eng)
`Description` | Descrição (ptbr)
`translation` |
|-------------|----------------------|------------------------------|---------------------------------------------------------------------|-------------------------------------------------------------------|
| 400 | QIT000001 | Bad Request | Schema Error | Erro de Schema |
403 | APX000025 | User is not allowed to do this transaction | User is not allowed to do this transaction | Usuário não tem autorização para fazer essa transação |
| 403 | APX000017 | Requester not allowed to access this endpoint | Requester has no permission to perform pix transfers on this endpoint | Requester não possui permissão de realizar transações pix através deste endpoint |
| 404 | APX000020 | Account not Found | Account was not found | Conta \{account_key\} não foi encontrada. |
| 404 | APX000001 | Recurrence not Found | Recurrence was not found | Recorrência \{incoming_recurrence_key\} não foi encontrada |
---
# Cancelar a recorrência
URL: /documentation/baas/pix_automatico/movimentacoes/cancelar_recorrencia
## Request
ENDPOINT /account/ ACCOUNT_KEY /incoming_recurrence/ INCOMING_RECURRENCE_KEY /cancel
MÉTODO PATCH
### Request Path Params
| Campo | Tipo | Descrição | Caracteres |
|-------------|--------|--------------------------------|------------|
| `account_key` * | uuid4 | Chave única de identificação da conta. | 36 |
| `incoming_recurrence_key` * | uuid4 | Chave única de identificação da autorização | 36 |
### Request Body
Request Body: Cancelar uma recorrência
```json
{
"incoming_recurrence_status": "cancelled",
}
```
### Body Params
| Campo | Tipo | Descrição | Caracteres |
|-------------------------|------------|--------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|------------|
| `incoming_recurrence_status` * | string | Identificador de status da recorrência Pix. | cancelled |
## Response
STATUS 200
Response Body: Recorrência cancelada
```json
{
"incoming_recurrence_key": "cfa32109-a6dd-4304-94db-03a7b6d92a47",
"incoming_recurrence_status": "cancelled",
"created_at": "2025-05-22T20:30:23.459Z",
"updated_at": "2025-05-22T20:39:23.459Z"
}
```
STATUS 4XX
Response Body
```json
{
"title": "titulo",
"description": "description in English",
"translation": "descrição em portugues",
"code": "codigo"
}
```
| Código HTTP | Código QI
`code` | Título
`title` | Descrição (eng)
`Description` | Descrição (ptbr)
`translation` |
|-------------|----------------------|------------------------------|---------------------------------------------------------------------|-------------------------------------------------------------------|
| 400 | QIT000001 | Bad Request | Schema Error | Erro de Schema |
403 | APX000025 | User is not allowed to do this transaction | User is not allowed to do this transaction | Usuário não tem autorização para fazer essa transação |
| 403 | APX000017 | Requester not allowed to access this endpoint | Requester has no permission to perform pix transfers on this endpoint | Requester não possui permissão de realizar transações pix através deste endpoint |
| 404 | APX000020 | Account not Found | Account was not found | Conta \{account_key\} não foi encontrada. |
| 404 | APX000001 | Recurrence not Found | Recurrence was not found | Recorrência \{incoming_recurrence_key\} não foi encontrada |
---
# Consultar Recorrência
URL: /documentation/baas/pix_automatico/movimentacoes/consultar_recorrencia
## Consultar recorrência Pix por incoming_recurrency_key
### Request
ENDPOINT /account/ ACCOUNT_KEY /incoming_recurrence/ INCOMING_RECURRENCE_KEY
MÉTODO GET
### Path Params
| Campo | Tipo | Descrição | Caracteres |
|----------------------------|------------|-------------------------------------------------------|-----------------------------------------------------------------------------|
| `account_key` * | uuid4 | Chave única de identificação da conta QI. | 36 |
| `incoming_recurrency_key` * | uuid4 | Chave única de identificação da recorrência de Pix automático. | 36 |
### Response
STATUS 200
Response Body: Consulta da recorrência
```json
{
"incoming_recurrence_key": "c2f3eefa-1b8e-4d5f-9b9d-123456789abc",
"incoming_recurrence_status": "pending_confirmation",
"request_control_key": "e04197f6-433e-48d2-8a8e-9258a70aba0b",
"transaction_amount": "150.00",
"periodicity": "monthly",
"journey_type": "journey_one",
"pix_transfer_type": "key",
"end_to_end_id": "E1234567890123456789012",
"start_date": "2025-06-01",
"end_date": "2026-06-01",
"next_execution_date": "2025-07-01",
"receiver_conciliation_id": "rec-conc-789",
"target_pix_key": "receiver@bank.com.br",
"payer_document_number": "12345678900",
"pix_message": "Pagamento mensal de serviço",
"created_at": "2025-05-22T10:00:00Z",
"updated_at": "2025-05-22T12:00:00Z",
}
```
| Campo | Tipo | Descrição | Max. Caracteres |
|--------------------------------|---------|-----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|-------------------------------------------------------------------|
| `incoming_recurrence_key` | uuid4 | Chave única de identificação da autorização | 36 |
| `incoming_recurrence_status` | string |Identificador de status da recorrência | [Enumerador incoming_recurrence_status](#enumerador-incoming_recurrence_status) |
| `request_control_key` | uuid4 | Chave única de identificação da request utilizada pelo cliente | 36 |
| `transaction_amount` | number | Valor da transferência para ocorrência de valor fixo. | 10 |
| `minimum_transaction_amount` | number | Valor mínimo da transferência para ocorrência de valor variável. | 10 |
| `maximum_transaction_amount` | number | Valor máximo da transferência para ocorrência de valor valor variável. | 10 |
| `periodicity` | enumerator | Tipo da periodicidade associada ao pagamento | [Enumeradores periodicity](#enumeradores-periodicity) |
| `journey_type` | enumerator | Tipo da jornada de solicitação | [Enumeradores journey_type](#enumeradores-journey_type) |
| `pix_transfer_type` | enumerator | Tipo do pix a ser realizado | [Enumeradores pix_transfer_type](#enumeradores-pix_transfer_type) |
| `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. | 32 |
| `start_date` | string | Data de ínicio da recorrência | - |
| `end_date` | string | Data de término da recorrência, para os casos de tempo indeterminado, enviar como null
| `next_execution_date` | string | Data de execução da próxima transação da recorrência | - |
| `receiver_conciliation_id` | string | Identicação de conciliação do recebedor. | 35 |
| `target_pix_key` | string | Chave pix da conta da transação. | 100 |
| `payer_document_number` | string | Número de documento do pagador da transação transação. | 14 |
| `pix_message` | string | Mensagem a ser enviada junto à transferência Pix. | 140 |
| `created_at` | string | Horário da criação da solicitação de recorrência | -
| `updated_at` | string | Horário de atualização da solicitação de recorrência | -
### Enumerador incoming_recurrence_status
| Enumerador | Descrição |
|----------------------|---------------------|
| `pending_confirmation` | Recorrência pendente de confirmação |
| `active` | Recorrência ativa |
| `cancelled` | Recorrência cancelada |
| `suspended` | Recorrência suspensa |
| `expired` | Recorrência expirada |
### Enumeradores periodicity
| Enumerador | Descrição |
|------------------|--------------------|
| `weekly` | Recorrência semanal |
| `monthly` | Recorrência mensal |
| `quarterly` | Recorrência trimestral |
| `semiannual` | Recorrência semestral |
| `annual` | Recorrência anual |
### Enumeradores journey_type
| Enumerador | Descrição |
|------------------|--------------------|
| `journey_one` | Solicitação de autorização mediante uma notificação no aplicativo |
| `jouney_two` | Solicitação de autorização mediante a leitura de um QR Code |
| `journey_three` | Autorização de recorrência por meio de um pix imediato mediante leitura de um QR Code |
| `journey_four` | Pagamento ou agendamento de um pix com uma solicitação de autorização da recorrência em sequência |
### Enumeradores 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 |
STATUS 4xx
Response Body: Error
```json
{
"title": "titulo",
"description": "description in English",
"translation": "descrição em portugues",
"code": "codigo",
"extra_fields": {}
}
```
| Código HTTP | Código QI
`code` | Título
`title` | Descrição (eng)
`Description` | Descrição (ptbr)
`translation` |
|-------------|----------------------|---------------------------------------------|-----------------------------------------------------|-------------------------------------------------------------------------------|
403 | APX000025 | User is not allowed to do this transaction | User is not allowed to do this transaction | Usuário não tem autorização para fazer essa transação |
| 403 | APX000017 | Requester not allowed to access this endpoint | Requester has no permission to perform pix transfers on this endpoint | Requester não possui permissão de realizar transações pix através deste endpoint |
| 404 | APX000020 | Account not Found | Account was not found | Conta \{account_key\} não foi encontrada. |
| 404 | APX000001 | Recurrence not Found | Recurrence was not found | Recorrência \{incoming_recurrence_key\} não foi encontrada |
---
# Listagem de Recorrências
URL: /documentation/baas/pix_automatico/movimentacoes/listar_recorrencias
## Listagem de recorrências Pix para uma conta
### Request
ENDPOINT /account/ ACCOUNT_KEY /incoming_recurrences
MÉTODO GET
### Path Params
| Campo | Tipo | Descrição | Caracteres |
|----------------------------|------------|-------------------------------------------------------|-----------------------------------------------------------------------------|
| `account_key` * | uuid4 | Chave única de identificação da conta QI. | 36 |
### Query Params
| Campo | Tipo | Descrição | Caracteres |
|--------------------------|------------|------------------------------------------------------------------------------------------------------------|-----------------------------------------------------------------------------|
| `request_control_key` | uuid4 | Chave única de identificação da request utilizada pelo cliente. | 36 |
| `status` | string | Identificador de status da recorrência Pix | [Enumerador status](#enumerador-status) |
| `date_from` | string | Data inicial para o filtro de listagem. | Formato "YYYY-MM-DD" |
| `date_to` | string | Data final para o filtro de listagem. | Formato "YYYY-MM-DD" |
| `page` | integer | Número da página requisitada. | Padrão 1 |
| `page_size` | integer | Tamanho da página requisitada na consulta. | Valor padrão e máximo de 30
### Enumerador status
| Enumerador | Descrição |
|----------------------|---------------------|
| `pending_confirmation` | Recorrência pendente de confirmação |
| `active` | Recorrência ativa |
| `cancelled` | Recorrência cancelada |
| `suspended` | Recorrência suspensa |
| `expired` | Recorrência expirada |
### Response
STATUS 200
Response Body: Listagem das recorrências
```json
{
"data": [
{
"incoming_recurrence_key": "c2f3eefa-1b8e-4d5f-9b9d-123456789abc",
"incoming_recurrence_status": "pending_confirmation",
"request_control_key": "e04197f6-433e-48d2-8a8e-9258a70aba0b",
"transaction_amount": "150.00",
"periodicity": "monthly",
"journey_type": "journey_one",
"pix_transfer_type": "key",
"end_to_end_id": "E1234567890123456789012",
"start_date": "2025-06-01",
"end_date": "2026-06-01",
"next_execution_date": "2025-07-01",
"receiver_conciliation_id": "rec-conc-789",
"target_pix_key": "receiver@bank.com.br",
"payer_document_number": "12345678900",
"pix_message": "Pagamento mensal de serviço",
"created_at": "2025-05-22T10:00:00Z",
"updated_at": "2025-05-22T12:00:00Z"
}
],
"pagination": {
"current_page": 1,
"rows_per_page": 30
}
}
```
STATUS 4xx
Response Body: Error
```json
{
"title": "titulo",
"description": "description in English",
"translation": "descrição em portugues",
"code": "codigo",
"extra_fields": {}
}
```
| Código HTTP | Código QI
`code` | Título
`title` | Descrição (eng)
`Description` | Descrição (ptbr)
`translation` |
|-------------|----------------------|---------------------------------------------|-----------------------------------------------------|-------------------------------------------------------------------------------|
403 | APX000025 | User is not allowed to do this transaction | User is not allowed to do this transaction | Usuário não tem autorização para fazer essa transação |
| 403 | APX000017 | Requester not allowed to access this endpoint | Requester has no permission to perform pix transfers on this endpoint | Requester não possui permissão de realizar transações pix através deste endpoint |
| 404 | APX000020 | Account not Found | Account was not found | Conta \{account_key\} não foi encontrada. |
---
# Simulação de cenários
URL: /documentation/baas/pix_automatico/movimentacoes/simulacao
Passo a passo para simular a criação de recorrências e pagamentos automáticos no âmbito do PIX Automático. Essas simulações incluem a criação de recorrências e a criação de pagamentos programados.
## 1 - Simulação de criação de recorrência
### Request
ENDPOINT /mock/incoming_recurrence
MÉTODO POST
Request Body: Recorrência de valor fixo
```json
{
"request_control_key": "01585acf-b0c3-4389-baf3-a58abbe92d58",
"recurrence_type": "fixed_amount",
"transaction_amount": 100.50,
"periodicity": "monthly",
"journey_type": "journey_one",
"start_date": "2025-07-01",
"is_retry_allowed": true,
"payer_account_information": {
"owner_name": "John Doe",
"document_number": "06975239000136",
"ispb": "32402502",
"account_digit": "7",
"account_branch": "3",
"account_number": "9552432"
}
```
Request Body: Recorrência de valor variável
```json
{
"request_control_key": "01585acf-b0c3-4389-baf3-a58abbe92d58",
"recurrence_type": "variable_amount",
"minimum_transaction_amount": 50.00,
"periodicity": "monthly",
"journey_type": "journey_one",
"start_date": "2025-07-01",
"is_retry_allowed": true,
"payer_account_information": {
"owner_name": "John Doe",
"document_number": "06975239000136",
"ispb": "32402502",
"account_digit": "7",
"account_branch": "3",
"account_number": "9552432"}
```
### Objeto Request Body
| Campo | Tipo | Descrição | Máx. Caract. |
|--------------------------------|----------------|--------------------------------------------------------------|--------------|
| **request_control_key*** | string | Chave única de identificação da request no formato uuid4 | 36 |
| **recurrence_type*** | string | Tipo de recorrência (fixed_amount ou variable_amount) | 20 |
| **transaction_amount** | number, null | Valor da transação para recorrência de valor fixo (fixed_amount) | 10 |
| **minimum_transaction_amount** | number, null | Valor mínimo da transação para recorrência de valor variável (variable_amount) | 10 |
| **periodicity*** | string | Periodicidade da recorrência | 20 |
| **journey_type*** | string | Tipo da jornada de autorização | 50 |
| **start_date*** | string | Data de início da recorrência (formato YYYY-MM-DD) | 10 |
| **end_date** | string, null | Data de término da recorrência (formato YYYY-MM-DD) | 10 |
| **is_retry_allowed*** | boolean | Permissão para retentativa de transação | - |
| **payer_account_information*** | object | Dados da conta do pagador | - |
| **pix_message** | string, null | Mensagem PIX associada à transação | 140 |
:::caution Observação
Pelo menos um dos campos `transaction_amount` ou `minimum_transaction_amount` deve ser fornecido com um valor não nulo. Ambos os campos não podem ser nulos simultaneamente.
:::
### Objeto payer_account_information
| Campo | Tipo | Descrição | Máx. Caract. |
|----------------------------|--------|-----------------------------------------------------|--------------|
| **owner_name*** | string | Nome do titular da conta | 150 |
| **document_number*** | string | CPF ou CNPJ do titular da conta (apenas números) | 14 |
| **ispb*** | string | Código ISPB da instituição financeira | 8 |
| **account_digit*** | string | Dígito da conta | 1 |
| **account_branch*** | string | Agência da conta | 6 |
| **account_number*** | string | Número da conta | 20 |
:::info Tipos de Recorrência
- **Recorrência de valor fixo (fixed_amount)**: Utilize o campo `transaction_amount` e não envie `minimum_transaction_amount`
- **Recorrência de valor variável (variable_amount)**: Utilize o campo `minimum_transaction_amount` e não envie `transaction_amount`
:::
## Response
STATUS 200
Response Body
```json
{
"incoming_recurrence_key": "e13c5986-f4d1-4d07-a56b-eda90862630a",
"incoming_recurrence_spi_id": "RR32402502202507170197A5B7CB9",
"incoming_recurrence_status": "pending_confirmation",
"created_at": "2025-07-17T14:44:38Z",
"account_key": "ba685cfd-3aee-4992-b6bf-58f8038faa6b"
}
```
### Response Body
| Campo | Tipo | Descrição | Caracteres |
|-------------------------------|------------|--------------------------------------------------------------|------------|
| `incoming_recurrence_key` | uuid | Chave única de identificação da recorrência de entrada | 36 |
| `incoming_recurrence_spi_id` | string | Identificador SPI da recorrência de entrada | 29 |
| `incoming_recurrence_status` | enumerator | Status atual da recorrência de entrada | [Enumeradores incoming_recurrence_status](#enumeradores-incoming_recurrence_status) |
| `created_at` | string | Data e hora de criação da recorrência (formato ISO 8601) | - |
| `account_key` | uuid | Chave única de identificação da conta | 36 |
### Enumeradores incoming_recurrence_status
| Enumerador | Descrição |
|-------------------------|-------------------------------------|
| `pending_confirmation` | Recorrência pendente de confirmação |
| `active` | Recorrência ativa |
| `cancelled` | Recorrência cancelada |
| `suspended` | Recorrência suspensa |
| `expired` | Recorrência expirada |
## 2 - Simulação de criação de pagamento
### Request
ENDPOINT /mock/incoming_recurrence/ INCOMING_RECURRENCE_SPI_ID /outgoing_payment
MÉTODO POST
Request Body
```json
{
"transaction_amount": 100.50,
"target_account_data": {
"owner_name": "John Doe",
"owner_document_number": "06975239000136",
"ispb": "32402502",
"account_digit": "7",
"account_branch": "3",
"account_type": "checking_account",
"account_number": "9552432"
},
"receiver_conciliation_id": "3d7d6a2bf72f44z7bb2079a2b94dff56452",
"outgoing_payment_spi_id": "7d2d1b6cd72f44z7bb2079a2b94dff52673",
"end_to_end_id": "E60701190202110191604DY5LHIZ9O66",
"next_execution_datetime": "2023-06-01"
}
```
### Objeto Request Body
| Campo | Tipo | Descrição | Máx. Caract. |
|-------------------------------|--------|--------------------------------------------------------------|--------------|
| **transaction_amount*** | number | Valor da transação | 10 |
| **target_account_data** | object | Dados da conta de destino | - |
| **receiver_conciliation_id*** | string | Identificação de conciliação do recebedor | 35 |
| **outgoing_payment_spi_id*** | string | Identificador SPI do pagamento | 20 |
| **end_to_end_id*** | string | Chave de idempotência da transação PIX no SPI | 32 |
| **next_execution_datetime** | string | Data e hora da próxima execução (formato YYYY-MM-DD) | 10 |
### Objeto target_account_data
| Campo | Tipo | Descrição | Máx. Caract. |
|----------------------------|--------|-----------------------------------------------------|--------------|
| **owner_name*** | string | Nome do titular da conta | 150 |
| **owner_document_number*** | string | CPF ou CNPJ do titular da conta (apenas números) | 14 |
| **ispb_number*** | string | Código ISPB da instituição financeira | 8 |
| **account_digit*** | string | Dígito da conta | 1 |
| **account_branch*** | string | Agência da conta | 6 |
| **account_type*** | string | Tipo da conta | 20 |
| **account_number*** | string | Número da conta | 20 |
### Enumerador account_type
| Enumerador | Descrição |
|----------------------|---------------------|
| **checking_account** | Conta Corrente |
| **salary_account** | Conta Salário |
| **saving_account** | Conta Poupança |
| **payment_account** | Conta de Pagamentos |
### Enumeradores periodicity
| Enumerador | Descrição |
|---------------|----------------------|
| **weekly** | Recorrência semanal |
| **monthly** | Recorrência mensal |
| **quarterly** | Recorrência trimestral |
| **semiannual**| Recorrência semestral |
| **annual** | Recorrência anual |
### Enumeradores journey_type
| Enumerador | Descrição |
|--------------------------------|------------------------------------------------------------------------------|
| **journey_one** | Solicitação de autorização mediante uma notificação no aplicativo |
| **journey_two** | Solicitação de autorização mediante a leitura de um QR Code |
| **journey_three** | Autorização de recorrência por meio de um pix imediato mediante leitura de um QR Code |
| **journey_four** | Pagamento ou agendamento de um pix com uma solicitação de autorização da recorrência em sequência |
---
# Webhooks
URL: /documentation/baas/pix_automatico/movimentacoes/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 criação da recorrência de Pix Automático
Webhook destinado com as informações de criação de recorrência do cliente
### Webhook Request Body
Request Body: Criação de recorrência
```json
{
"webhook_type": "baas.automatic_pix.incoming_recurrence",
"webhook_datetime": "2025-10-22T20:30:23.459Z",
"data": {
"account_key": "13385acf-b0c3-4389-baf3-a58abbe92d58",
"incoming_recurrence_key": "12385acf-b0c3-4389-baf3-a58abbe92d58",
"incoming_recurrence_status": "pending_confirmation",
"transaction_amount": "150.00",
"periodicity": "monthly",
"journey_type": "journey_one",
"pix_transfer_type": "key",
"end_to_end_id": "E1234567890123456789012",
"start_date": "2025-06-01",
"end_date": "2026-06-01",
"receiver_conciliation_id": "rec-conc-789",
"target_pix_key": "receiver@bank.com.br",
"payer_document_number": "12345678900",
"pix_message": "Pagamento mensal de serviço",
"created_at": "2025-05-22T10:00:00Z",
"updated_at": "2025-05-22T12:00:00Z"
}
}
```
### Webhook Body Param
| 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 |
| `account_key` | uuid4 | Chave única de identificação da conta. | 36 |
| `incoming_recurrence_key` | uuid4 | Chave única de identificação da autorização | 36 |
| `incoming_recurrence_status` | string | Identificador de status da recorrência Pix. | [Enumeradores incoming_recurrence_status](#enumeradores-incoming_recurrence_status) |
| `transaction_amount` | number | Valor da transferência para ocorrência de valor fixo. | 10 |
| `minimum_transaction_amount` | number | Valor mínimo da transferência para ocorrência de valor variável. | 10 |
| `maximum_transaction_amount` | number | Valor máximo da transferência para ocorrência de valor variável. | 10 |
| `periodicity` | enum | Tipo da periodicidade associada ao pagamento | [Enumeradores periodicity](#enumeradores-periodicity) |
| `journey_type` | enum | Tipo da jornada de solicitação | [Enumeradores journey_type](#enumeradores-journey_type) |
| `pix_transfer_type` | enum | Tipo do Pix a ser realizado | [Enumeradores pix_transfer_type](#enumeradores-pix_transfer_type) |
| `end_to_end_id` | string | Chave de idempotência de uma transação Pix dentro do SPI. | 32 |
| `start_date` | string | Data de início da recorrência | - |
| `end_date` | string | Data de término da recorrência, para os casos de tempo indeterminado, enviar como null | - |
| `receiver_conciliation_id` | string | Identificação de conciliação do recebedor. | 35 |
| `target_pix_key` | string | Chave Pix da conta da transação. | 100 |
| `payer_document_number` | string | Número de documento do pagador da transação | 14 |
| `pix_message` | string | Mensagem a ser enviada junto à transferência Pix. | 140 |
| `created_at` | string | Horário da criação da solicitação de recorrência | - |
| `updated_at` | string | Horário de atualização da solicitação de recorrência | - |
### Enumerador incoming_recurrence_status
| Enumerador | Descrição |
|----------------------|---------------------|
| `pending_confirmation` | Recorrência pendente de confirmação |
| `active` | Recorrência ativa |
| `cancelled` | Recorrência cancelada |
| `suspended` | Recorrência suspensa |
| `expired` | Recorrência expirada |
### Enumeradores periodicity
| Enumerador | Descrição |
|------------------|--------------------|
| `weekly` | Recorrência semanal |
| `monthly` | Recorrência mensal |
| `quarterly` | Recorrência trimestral |
| `semiannual` | Recorrência semestral |
| `annual` | Recorrência anual |
### Enumeradores journey_type
| Enumerador | Descrição |
|------------------|--------------------|
| `journey_one` | Solicitação de autorização mediante uma notificação no aplicativo |
| `journey_two` | Solicitação de autorização mediante a leitura de um QR Code |
| `journey_three` | Autorização de recorrência por meio de um pix imediato mediante leitura de um QR Code |
| `journey_four` | Pagamento ou agendamento de um pix com uma solicitação de autorização da recorrência em sequência |
### Enumeradores 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 |
[//]: # (Break here for new page -----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------)
---
# Atualizar Valor da Ordem de Pagamento
URL: /documentation/baas/pix_automatico/pagamentos/atualizar_payment_order
## Request
ENDPOINT /account/ ACCOUNT_KEY /outgoing_recurrence/ OUTGOING_RECURRENCE_KEY /payment_order/ PAYMENT_ORDER_KEY
MÉTODO PATCH
### Path Params
| Campo | Tipo | Descrição | Caracteres |
|--------------------------|--------|----------------------------------------------------|------------|
| `ACCOUNT_KEY` | uuidv4 | Chave única de identificação da conta. | 36 |
| `OUTGOING_RECURRENCE_KEY`| uuidv4 | Chave única da recorrência a ser atualizada. | 36 |
| `PAYMENT_ORDER_KEY` | uuidv4 | Chave única da ordem de pagamento a ser atualizada.| 36 |
### Request Body
Atualizar Payment Order
```json
{
"transaction_amount": 100
}
```
### Request Body Params
| Campo | Tipo | Descrição | Caracteres |
|----------------------|--------|------------------------------------|------------|
| `transaction_amount` | floating | Valor da transação a ser atualizado.| - |
## Response
STATUS 200
Response Body
```json
{}
```
STATUS 4XX
Response Error
```json
{
"title": "titulo",
"description": "description in English",
"translation": "descrição em português",
"code": "codigo"
}
```
| Código HTTP | Código QI
`code` | Título
`title` | Descrição (eng)
`description` | Descrição (ptbr)
`translation` |
|-------------|----------------------|-----------------------------------|----------------------------------------------------------------------------|--------------------------------------------------------------------|
| 400 | QIT000002 | Bad Request | Invalid request schema. | Erro no esquema da requisição. |
| 404 | APX000404 | Payment Order Not Found | Payment Order \{payment_order_key\} not found. | Lote de conciliação \{payment_order_key\} não encontrado. |
---
# Cancelar uma Ordem de Pagamento
URL: /documentation/baas/pix_automatico/pagamentos/cancelar_payment_order
Este endpoint permite cancelar uma ordem de pagamento específica associada a uma recorrência automática Pix.
:::warning
Só é possível cancelar uma payment order que está em status de pending_conciliation ou pending, até as 22h do dia anterior ao reference_date.
:::
## Request
ENDPOINT /automatic_pix/account/ ACCOUNT_KEY /outgoing_recurrence/ OUTGOING_RECURRENCE_KEY /payment_order/ PAYMENT_ORDER_KEY /cancel
MÉTODO PATCH
### Path Params
| Campo | Tipo | Descrição | Caracteres |
|--------------------------|--------|----------------------------------------------------|------------|
| `ACCOUNT_KEY` | uuidv4 | Chave única de identificação da conta. | 36 |
| `OUTGOING_RECURRENCE_KEY`| uuidv4 | Chave única da recorrência. | 36 |
| `PAYMENT_ORDER_KEY` | uuidv4 | Chave única da ordem de pagamento a ser cancelada. | 36 |
### Request Body
Cancelar Payment Order
```json
{}
```
## Response
STATUS 200
Response Body
```json
{
"payment_order_key": "10fc62fd-b0a0-4604-9bea-475e91a9dc82",
"payment_order_conciliation_batch_key": "11fc62fd-b0a0-4604-9bea-475e91a9dc82",
"payment_order_status": "cancelled"
}
```
### Response Body Params
| Campo | Tipo | Descrição | Caracteres |
|----------------------------------------|--------|----------------------------------------------------|------------|
| `payment_order_key` | string | Chave única da ordem de pagamento. | 36 |
| `payment_order_conciliation_batch_key` | string | Chave do lote de conciliação da ordem de pagamento.| 36 |
| `payment_order_status` | string | Status atual da ordem de pagamento. | - |
### Enumeradores payment_order_status
| Enumerador | Descrição |
|-----------------------|----------------------------------------------------|
| `pending_conciliation`| Aguardando conciliação. |
| `pending` | Pendente e ainda não processada. |
| `accepted` | Aceita e aguardando pagamento. |
| `paid` | Paga com sucesso. |
| `rejected` | Rejeitada e não será processada. |
| `cancelled` | Cancelada antes do pagamento. |
STATUS 4XX
Response Error
```json
{
"title": "titulo",
"description": "description in English",
"translation": "descrição em português",
"code": "codigo"
}
```
| Código HTTP | Código QI
`code` | Título
`title` | Descrição (eng)
`description` | Descrição (ptbr)
`translation` |
|-------------|----------------------|-----------------------------------|----------------------------------------------------------------------------|--------------------------------------------------------------------|
| 400 | QIT000002 | Bad Request | Invalid request schema. | Erro no esquema da requisição. |
| 404 | APX000404 | Payment Order Not Found | Payment Order \{payment_order_key\} not found. | Lote de conciliação \{payment_order_key\} não encontrado. |
---
# Consultar Payment Order
URL: /documentation/baas/pix_automatico/pagamentos/consultar_payment_order
## Request
Este endpoint permite consultar os detalhes de uma payment order específica associada a uma recorrência automática Pix.
ENDPOINT /account/ ACCOUNT_KEY /outgoing_recurrence/ OUTGOING_RECURRENCE_KEY /payment_order/ PAYMENT_ORDER_KEY
MÉTODO GET
### Path Params
| Campo | Tipo | Descrição | Caracteres |
|--------------------------|--------|---------------------------------------------------|------------|
| `account_key` | uuidv4 | Chave única de identificação da conta. | 36 |
| `outgoing_recurrence_key`| uuidv4 | Chave única da recorrência a ser consultada. | 36 |
| `payment_order_key` | uuidv4 | Chave única da ordem de pagamento a ser consultada.| 36 |
## Response Body
STATUS 200
Response Body
```json
{
"outgoing_recurrence_spi_id": "RR2222222220240429njua7shf40k",
"payment_order_status": "paid",
"reference_date": "2025-06-30",
"payment_order_conciliation_batch_key": "21fc62fd-b0a0-4604-9bea-475e91a9dc82",
"receiver_conciliation_id": "cac0b5f7-4ee2-40f1-b2ad-16902506503d",
"transaction_amount": 125.53,
"transaction_key": "21fc62fd-b0a0-4604-9bea-475e91a9dc56",
"incoming_pix_transfer_key": "21fc62fd-b0a0-4604-9bea-475e91a9dc56",
"debtor_account_data": {
"account_number": "897465",
"account_digit": "1",
"account_branch": "0123",
"ispb": "323243"
},
"created_at": "2021-10-22T20:30:23.459Z",
"paid_at": "2023-10-22T20:30:23.459Z",
"payment_order_attempts": [
{
"payment_order_attempt_key": "uuid",
"end_to_end_id": "id",
"payment_order_attempt_status": "sent",
"payment_order_attempt_error": {
"code": "code",
"description": "description do error",
"translation": "translation"
},
"created_at": "2021-10-22T20:30:23.459Z"
}
]
}
```
### Response Body Params
| Campo | Tipo | Descrição | Caracteres |
|------------------------------------|----------|---------------------------------------------------------------------------|------------|
| `outgoing_recurrence_spi_id` | string | ID da SPI da recorrência automática. | 36 |
| `payment_order_status` | string | Status atual da ordem de pagamento. |[Enumeradores payment_order_status](#payment_order_status) |
| `reference_date` | string | Data de referência da cobrança. | 10 |
| `payment_order_conciliation_batch_key`| uuidv4 | Chave do lote de conciliação da ordem de pagamento. | 36 |
| `receiver_conciliation_id` | uuidv4 | ID de conciliação do recebedor. | 36 |
| `transaction_amount` | number | Valor da transação. | - |
| `transaction_key` | uuidv4 | Chave única da transação. | 36 |
| `incoming_pix_transfer_key` | uuidv4 | Chave de transferência Pix recebida. | 36 |
| `debtor_account_data` | object | Dados da conta devedor. | [Objeto debtor_account_data](#objeto-debtor_account_data) |
| `created_at` | string | Data/hora de criação da ordem. | - |
| `paid_at` | string | Data/hora do pagamento efetuado. | - |
| `payment_order_attempts` | array | Tentativas de pagamento da ordem. | [Array payment_order_attempts](#array-payment_order_attempts) |
### Objeto debtor_account_data
| Campo | Tipo | Descrição | Caracteres |
|------------------|--------|----------------------------|------------|
| `account_number` | string | Número da conta | - |
| `account_digit` | string | Dígito da conta | - |
| `account_branch` | string | Agência | - |
| `ispb` | string | ISPB da instituição financeira | - |
### Array payment_order_attempts
| Campo | Tipo | Descrição | Caracteres |
|------------------------------|----------|----------------------------------------------------------------|------------|
| `payment_order_attempt_key` | string | Chave única da tentativa de pagamento. | 36 |
| `end_to_end_id` | string | Identificador end-to-end da tentativa. | 36 |
| `payment_order_attempt_status`| string | Status da tentativa de pagamento. | - |
| `payment_order_attempt_error`| object | Erro associado à tentativa de pagamento. | [Objeto payment_order_attempt_error](#objeto-payment_order_attempt_error) |
| `created_at` | string | Data/hora de criação da tentativa. | - |
### Objeto payment_order_attempt_error
| Campo | Tipo | Descrição | Caracteres |
|-------------|--------|-------------------------|------------|
| `code` | string | Código do erro. | - |
| `description`| string | Descrição do erro. | - |
| `translation`| string | Tradução da descrição. | - |
### Enumeradores payment_order_status
| Enumerador | Descrição |
|-----------------------|----------------------------------------------------|
| `pending_conciliation`| Aguardando conciliação. |
| `pending` | Pendente e ainda não processada. |
| `accepted` | Aceita e aguardando pagamento. |
| `paid` | Paga com sucesso. |
| `rejected` | Rejeitada e não será processada. |
| `cancelled` | Cancelada antes do pagamento. |
STATUS 4XX
Response Error
```json
{
"title": "titulo",
"description": "description in English",
"translation": "descrição em português",
"code": "codigo"
}
```
| Código HTTP | Código QI
`code` | Título
`title` | Descrição (eng)
`description` | Descrição (ptbr)
`translation` |
|-------------|----------------------|-----------------------------------|----------------------------------------------------------------------------|--------------------------------------------------------------------|
| 400 | QIT000002 | Bad Request | Invalid request schema. | Erro no esquema da requisição. |
| 404 | APX000002 | Payment Order Not Found | Payment order \{payment_order_key\} not found. | Ordem de pagamento \{payment_order_key\} não encontrada. |
---
# Listar Payment Orders por Conta
URL: /documentation/baas/pix_automatico/pagamentos/listar_account_payment_orders
Este endpoint permite listar as ordens de pagamento associadas a uma conta específica.
ENDPOINT /account/ ACCOUNT_KEY /payment_orders
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 |
|----------------------|--------|--------------------------------------------------|------------|
| `payment_order_status`| string | Filtra as ordens por status (e.g., `paid`). | - |
| `start_date` | string | Data de início para filtrar ordens (formato YYYY-MM-DD). | 10 |
| `end_date` | string | Data de fim para filtrar ordens (formato YYYY-MM-DD). | 10 |
## Response Body
STATUS 200
Response Body
```json
{
"payment_orders": [
{
"payment_order_key": "a1b2c3d4-e5f6-4789-a123-456789abcdef",
"payment_order_spi_id": "1a2b3c4d5e6f7890abcdef1234567890",
"outgoing_recurrence_key": "b2c3d4e5-f6a7-4890-b234-567890abcdef",
"outgoing_recurrence_spi_id": "RR3240250220251025A1B2C3D4E5F",
"payment_order_conciliation_batch_key": "c3d4e5f6-a7b8-4901-c345-678901abcdef",
"payment_order_status": "pending_conciliation",
"reference_date": "2025-11-15",
"receiver_conciliation_id": "2b3c4d5e6f7890abcdef1234567890ab",
"transaction_amount": null,
"account_key": "d4e5f6a7-b8c9-4012-d456-789012abcdef",
"transaction_key": null,
"incoming_pix_transfer_key": null,
"debtor_account_data": {
"ispb": "31872495",
"account_digit": "7",
"account_branch": "0001",
"account_number": "123456"
},
"created_at": "2025-10-15T03:00:12Z",
"paid_at": null,
"payment_order_attempts": []
},
{
"payment_order_key": "e5f6a7b8-c9d0-4123-e567-890123abcdef",
"payment_order_spi_id": "3c4d5e6f7890abcdef1234567890abcd",
"outgoing_recurrence_key": "f6a7b8c9-d0e1-4234-f678-901234abcdef",
"outgoing_recurrence_spi_id": "RR3240250220251025B2C3D4E5F6A",
"payment_order_conciliation_batch_key": "c3d4e5f6-a7b8-4901-c345-678901abcdef",
"payment_order_status": "pending",
"reference_date": "2025-11-15",
"receiver_conciliation_id": "4d5e6f7890abcdef1234567890abcdef",
"transaction_amount": 220.00,
"account_key": "d4e5f6a7-b8c9-4012-d456-789012abcdef",
"transaction_key": null,
"incoming_pix_transfer_key": null,
"debtor_account_data": {
"ispb": "31872495",
"account_digit": "7",
"account_branch": "0001",
"account_number": "123456"
},
"created_at": "2025-10-15T03:00:10Z",
"paid_at": null,
"payment_order_attempts": []
}
],
"pagination": {
"page": 1,
"page_size": 25,
"number_of_pages": 9
}
}
```
### Response Body Params
| Campo | Tipo | Descrição | Caracteres |
|----------------------------------------|----------|---------------------------------------------------------------------|------------|
| `payment_order_key` | uuidv4 | Chave única da ordem de pagamento. | 36 |
| `payment_order_spi_id` | string | ID da SPI da ordem de pagamento. | 32 |
| `outgoing_recurrence_key` | uuidv4 | Chave única da recorrência de saída. | 36 |
| `outgoing_recurrence_spi_id` | string | ID da SPI da recorrência automática. | 27 |
| `payment_order_conciliation_batch_key` | uuidv4 | Chave do lote de conciliação da ordem de pagamento. | 36 |
| `payment_order_status` | string | Status atual da ordem de pagamento. | - |
| `reference_date` | string | Data de referência da cobrança. | 10 |
| `receiver_conciliation_id` | string | ID de conciliação do recebedor. | 32 |
| `transaction_amount` | number | Valor da transação (pode ser null). | - |
| `account_key` | uuidv4 | Chave única da conta. | 36 |
| `transaction_key` | uuidv4 | Chave única da transação (pode ser null). | 36 |
| `incoming_pix_transfer_key` | uuidv4 | Chave de transferência Pix recebida (pode ser null). | 36 |
| `debtor_account_data` | object | Dados da conta do devedor. | [Objeto debtor_account_data](#objeto-debtor_account_data) |
| `created_at` | string | Data/hora de criação da ordem (formato ISO 8601). | - |
| `paid_at` | string | Data/hora do pagamento efetuado (formato ISO 8601, pode ser null). | - |
| `payment_order_attempts` | array | Tentativas de pagamento da ordem. | [Array payment_order_attempts](#array-payment_order_attempts) |
### Objeto debtor_account_data
| Campo | Tipo | Descrição | Caracteres |
|------------------|--------|----------------------------|------------|
| `account_number` | string | Número da conta | - |
| `account_digit` | string | Dígito da conta | - |
| `account_branch` | string | Agência | - |
| `ispb` | string | ISPB da instituição financeira | - |
### Array payment_order_attempts
| Campo | Tipo | Descrição | Caracteres |
|------------------------------|----------|----------------------------------------------------------------|------------|
| `payment_order_attempt_key` | string | Chave única da tentativa de pagamento. | 36 |
| `end_to_end_id` | string | Identificador end-to-end da tentativa. | 32 |
| `due_date` | string | Data de vencimento da tentativa (formato YYYY-MM-DD, pode ser null). | 10 |
| `payment_order_attempt_status`| string | Status da tentativa de pagamento. | - |
| `payment_order_attempt_error`| object | Erro associado à tentativa de pagamento (pode ser null). | [Objeto payment_order_attempt_error](#objeto-payment_order_attempt_error) |
| `sent_at` | string | Data/hora de envio da tentativa (formato ISO 8601, pode ser null). | - |
| `created_at` | string | Data/hora de criação da tentativa (formato ISO 8601). | - |
### Objeto payment_order_attempt_error
| Campo | Tipo | Descrição | Caracteres |
|-------------|--------|-------------------------|------------|
| `code` | string | Código do erro. | - |
| `description`| string | Descrição do erro. | - |
| `translation`| string | Tradução da descrição. | - |
### Enumeradores payment_order_status
| Enumerador | Descrição |
|-------------------------|----------------------------------------------------|
| `pending_conciliation` | A ordem de pagamento está pendente de conciliação |
| `pending` | A ordem de pagamento está pendente |
| `accepted` | A ordem de pagamento foi aceita |
| `paid` | A ordem de pagamento foi paga |
| `rejected` | A ordem de pagamento foi rejeitada |
| `cancelled` | A ordem de pagamento foi cancelada |
STATUS 4XX
Response Error
```json
{
"title": "titulo",
"description": "description in English",
"translation": "descrição em português",
"code": "codigo"
}
```
| Código HTTP | Código QI
`code` | Título
`title` | Descrição (eng)
`description` | Descrição (ptbr)
`translation` |
|-------------|----------------------|-----------------------------------|----------------------------------------------------------------------------|--------------------------------------------------------------------|
| 400 | QIT000002 | Bad Request | Invalid request schema. | Erro no esquema da requisição. |
| 404 | APX000002 | Payment Order Not Found | Payment order \{payment_order_key\} not found. | Ordem de pagamento \{payment_order_key\} não encontrada. |
---
# Decodificar QR Code para Pix Automático
URL: /documentation/baas/pix_automatico/qr_code/decodificar_qr_code
## Request
ENDPOINT /account/ ACCOUNT_KEY /qrcode/decode
MÉTODO POST
### Request Path Params
| Campo | Tipo | Descrição | Caracteres |
|-------------|--------|--------------------------------|------------|
| `account_key` * | uuid4 | Chave única de identificação da conta. | 36 |
### Request Body
Request Body: Decodificar QR Code
```json
{
"qr_code_payload": "00020101021226840014br.gov.bcb.pix2562invoice.starkbank.com/v2/cobv/8b434df48c30482a81f7c936ae35cc87080400005303986540555.595802BR5925Stark Bank S.A.6015Sao Caetano do Sul62070503***80740014br.gov.bcb.pix2552pix.example.com/rec/2353c790eefb11eaadc10242ac120002630411FC"
}
```
### Body Params
| Campo | Tipo | Descrição | Caracteres |
|-------------------------|------------|--------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|------------|
| `qr_code_payload` * | string | URL do PIX Copia e Cola | - |
## Response
STATUS 200
Response Body: QR decodificado
```json
{
"end_to_end_id": "E32402502202303101532yCipbxgUnUj",
"qr_code_payload": "00020101021226840014br.gov.bcb.pix2562invoice.starkbank.com/v2/cobv/8b434df48c30482a81f7c936ae35cc87080400005303986540555.595802BR5925Stark Bank S.A.6015Sao Caetano do Sul62070503***80740014br.gov.bcb.pix2552pix.example.com/rec/2353c790eefb11eaadc10242ac120002630411FC",
"qr_code_key": "8c2c19bd-f260-4714-955c-956f3eaa30ca",
"qr_code_type": "dynamic_composed",
"qr_code_data": {
"incoming_recurrence": {
"incoming_recurrence_key": "67abc123-4567-89ab-cdef-1234567890ab",
"journey_type": "j2_recurrence_only_qrcode",
"incoming_recurrence_type": "variable_amount",
"incoming_recurrence_status": "pending_confirmation",
"start_date": "2024-08-01",
"end_date": null,
"periodicity": "weekly",
"target_pix_key": "teste.recorrencia@email.com.br",
"minimum_transaction_amount": "100.00",
"maximum_transaction_amount": "500.00",
"transaction_amount": null,
"is_retry_allowed": true,
"created_at": "2024-07-23T14:30:45.123Z",
"payer_document_number": "12345678901",
"payer_name": "João da Silva",
"payer_account_key": "a5d7e60f-1c9b-4b8a-9de7-6f3b919cc45d",
"request_control_key": "c7d7e60f-1c9b-4b8a-9de7-6f3b919cc45f",
"receiver_conciliation_id": "RRAUTOTESTE001",
"pix_message": "Autorização de débito mensal"
},
"payment_data": {
"request_control_key": "c7d7e60f-1c9b-4b8a-9de7-6f3b919cc45f",
"transaction_amount": "150.75",
"target_pix_key": "teste.recorrencia@email.com.br",
"target_account": null,
"receiver_conciliation_id": "fgnb4NTt7pOUBGfrcporERwVVqr0f8PWRfK",
"pix_message": "Assinatura mensal do serviço"
}
}
}
```
| Campo | Tipo | Descrição | Max. Caracteres |
|--------------------------------|---------|-----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|-------------------------------------------------------------------|
| `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. | 32 |
| `qr_code_payload` | string | URL do PIX Copia Cola | |
| `qr_code_key` | uuid4 | Chave única de identificação do qr code | 36 |
`qr_code_data` | Object | Dados dos qr code | [Objeto qr_code_data](#objeto-qr_code_data) | 10 |
### Objeto qr_code_data
| Campo | Tipo | Descrição | Caracteres |
|---------------------------|------------|-----------------------------------------------------|---------------------------------------------------------|
| `incoming_recurrence` | objeto | Objeto de identificação da recorrência | [Objeto incoming_recurrence](#objeto-incoming_recurrence) |
| `payment_data` | objeto | Objeto com informações de pagamento para journey_types: *j3_payment_and_recurrence_qrcode*, *j4_recurrence_offer_post_payment* | [Objeto payment_data](#objeto-payment_data)
### Objeto incoming_recurrence
| Campo | Tipo | Descrição | Caracteres |
|---------------------------|------------|-----------------------------------------------------|---------------------------------------------------------|
| `incoming_recurrence_key` | uuid4 | Chave única de identificação da autorização | 36 |
| `incoming_recurrence_status` | string |Identificador de status da recorrência | [Enumerador incoming_recurrence_status](#enumerador-incoming_recurrence_status) |
| `request_control_key` | uuid4 | Chave única de identificação da request utilizada pelo cliente | 36 |
| `transaction_amount` | number | Valor da transferência para ocorrência de valor fixo. | 10 |
| `minimum_transaction_amount` | number | Valor mínimo da transferência para ocorrência de valor variável. | 10 |
| `maximum_transaction_amount` | number | Valor máximo da transferência para ocorrência de valor valor variável. | 10 |
| `periodicity` | enumerator | Tipo da periodicidade associada ao pagamento | [Enumeradores periodicity](#enumeradores-periodicity) |
| `journey_type` | enumerator | Tipo da jornada de solicitação | [Enumeradores journey_type](#enumeradores-journey_type) |
| `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. | 32 |
| `start_date` | string | Data de ínicio da recorrência | - |
| `end_date` | string | Data de término da recorrência, para os casos de tempo indeterminado, enviar como null
| `next_execution_date` | string | Data de execução da próxima transação da recorrência | - |
| `receiver_conciliation_id` | string | Identicação de conciliação do recebedor. | 35 |
| `target_pix_key` | string | Chave pix da conta da transação. | 100 |
| `is_retry_allowed` | boolean | Permissão para retentativa de transação Pix. | - |
| `payer_document_number` | string | Número de documento do pagador da transação transação. | 14 |
| `payer_name` | string | Nome do pagador da transação transação. | - |
| `payer_account_key` | string | Identificador da conta do pagador da transação transação. | - |
| `pix_message` | string | Mensagem a ser enviada junto à transferência Pix. | 140 |
| `created_at` | string | Horário da criação da solicitação de recorrência | -
### Objeto payment_data
| Campo | Tipo | Descrição | Caracteres |
|---------------------------|------------|-----------------------------------------------------|---------------------------------------------------------|
| `request_control_key` | uuid4 | Chave única de identificação da request utilizada pelo cliente | 36 |
| `transaction_amount` | number | Valor da transferência para ocorrência de valor fixo. | 10 |
| `target_pix_key` | string | Chave pix da conta da transação. | 100 |
| `target_account` | Object | Conta destino em transferências manuais. | [Objeto target_account](#objeto-target_account) | 10 |
| `receiver_conciliation_id` | string | Identicação de conciliação do recebedor. | 35 |
| `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 |
:::info
Diferentes enumeradores podem significar o mesmo tipo de conta devido a informação retornada por diferentes
instituições.
:::
### 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 incoming_recurrence_status
| Enumerador | Descrição |
|----------------------|---------------------|
| **pending_confirmation** | Recorrência pendente de confirmação |
| **active** | Recorrência ativa |
| **cancelled** | Recorrência cancelada |
| **suspended** | Recorrência suspensa |
| **expired** | Recorrência expirada |
### Enumeradores periodicity
| Enumerador | Descrição |
|------------------|--------------------|
| `weekly` | Recorrência semanal |
| `monthly` | Recorrência mensal |
| `quarterly` | Recorrência trimestral |
| `semiannual` | Recorrência semestral |
| `annual` | Recorrência anual |
### Enumeradores journey_type
| Enumerador | Descrição |
|------------------|--------------------|
| `j1_in_app_only_recurrence` | Solicitação de autorização mediante uma notificação no aplicativo |
| `j2_recurrence_only_qrcode` | Solicitação de autorização mediante a leitura de um QR Code |
| `j3_payment_and_recurrence_qrcode` | Autorização de recorrência por meio de um pix imediato mediante leitura de um QR Code |
| `j4_recurrence_offer_post_payment` | Pagamento ou agendamento de um pix com uma solicitação de autorização da recorrência em sequência |
### Enumeradores 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 |
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` |
|-------------|----------------------|------------------------------|---------------------------------------------------------------------|-------------------------------------------------------------------|
| 400 | QIT000001 | Bad Request | Schema Error | Erro de Schema |
403 | APX000025 | User is not allowed to do this transaction | User is not allowed to do this transaction | Usuário não tem autorização para fazer essa transação |
| 403 | APX000017 | Requester not allowed to access this endpoint | Requester has no permission to perform pix transfers on this endpoint | Requester não possui permissão de realizar transações pix através deste endpoint |
| 404 | APX000020 | Account not Found | Account was not found | Conta \{account_key\} não foi encontrada. |
---
# Cancelar recorrência de pagamento
URL: /documentation/baas/pix_automatico/recebedor/cancelar_recorrencia
## Request
ENDPOINT /account/ ACCOUNT_KEY /outgoing_recurrence/ OUTGOING_RECURRENCE_KEY /cancel
MÉTODO PATCH
### Request Path Params
| Campo | Tipo | Descrição | Caracteres |
|-------------|--------|--------------------------------|------------|
| `account_key` * | uuid4 | Chave única de identificação da conta. | 36 |
| `outgoing_recurrence_key` * | uuid4 | Chave única de identificação da autorização | 36 |
### Request Body
Request Body: Cancelar uma recorrência
```json
{
"outgoing_recurrence_status": "cancelled",
}
```
### Body Params
| Campo | Tipo | Descrição | Caracteres |
|-------------------------|------------|--------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|------------|
| `outgoing_recurrence_status` * | string | Identificador de status da recorrência Pix. | cancelled |
## Response
STATUS 200
Response Body: Recorrência cancelada
```json
{
"outgoing_recurrence_key": "cfa32109-a6dd-4304-94db-03a7b6d92a47",
"outgoing_recurrence_status": "cancelled",
"created_at": "2025-05-22T20:30:23.459Z",
"updated_at": "2025-05-22T20:39:23.459Z"
}
```
STATUS 4XX
Response Body
```json
{
"title": "titulo",
"description": "description in English",
"translation": "descrição em portugues",
"code": "codigo"
}
```
| Código HTTP | Código QI
`code` | Título
`title` | Descrição (eng)
`Description` | Descrição (ptbr)
`translation` |
|-------------|----------------------|------------------------------|---------------------------------------------------------------------|-------------------------------------------------------------------|
| 400 | QIT000001 | Bad Request | Schema Error | Erro de Schema |
403 | APX000025 | User is not allowed to do this transaction | User is not allowed to do this transaction | Usuário não tem autorização para fazer essa transação |
| 403 | APX000017 | Requester not allowed to access this endpoint | Requester has no permission to perform pix transfers on this endpoint | Requester não possui permissão de realizar transações pix através deste endpoint |
| 404 | APX000020 | Account not Found | Account was not found | Conta \{account_key\} não foi encontrada. |
| 404 | APX000001 | Recurrence not Found | Recurrence was not found | Recorrência \{outgoing_recurrence_key\} não foi encontrada |
---
# Consultar dados de uma recorrência por outgoing_recurrence_key
URL: /documentation/baas/pix_automatico/recebedor/consultar_recorrencia
## Request
ENDPOINT /account/ ACCOUNT_KEY /outgoing_recurrence/ OUTGOING_RECURRENCE_KEY
MÉTODO GET
### Path Params
| Campo | Tipo | Descrição | Caracteres |
|--------------------------|--------|---------------------------------------------------|------------|
| `account_key` * | uuidv4 | Chave única de identificação da conta. | 36 |
| `outgoing_recurrence_key`*| uuidv4 | Chave única da recorrência a ser consultada. | 36 |
## Response
STATUS 200
Response Body
```json
{
"request_control_key":"98fc62fd-b0a0-4604-9bea-475e91a9dc82",
"outgoing_recurrence_key":"8cb70dea-9fb0-4a68-9572-99a72849c8d6",
"outgoing_recurrence_status":"approved",
"periodicity":"monthly",
"journey_type":"journey_four",
"start_date":"2025-06-10",
"end_date":"2027-06-10",
"outgoing_recurrence_data":{
"minimum_recurrence_amount":123.45,
"recurrence_amount":null,
"retry_configuration":{
"retry_allowed":true,
"retry_rule":{
"first_retry":{
"day":"1",
"time":"14:00"
},
"second_retry":{
"day":"3",
"time":"12:00"
},
"third_retry":{
"day":"4",
"time":"15:32"
}
}
},
"debtor_data":{
"name":"Sebastião",
"email":"sebastiao@test.com",
"document_number":"05431134850",
"address":{
"city":"São Paulo",
"postal_code":"123456-789",
"uf":"SP",
"street":"Av Paulista 123"
},
"account_data":{
"account_number":"123456",
"account_digit":"7",
"account_branch":"0001",
"ispb":"31872495"
}
},
"qr_code_data":{
"qr_code_key":"0f45cc3d-9bd1-4d68-a865-4cf477b5da45",
"qr_code_url":"urlqrcode.url",
"qr_code_image":"image_base64"
},
"initial_payment_data":{
"amount":22.34,
"pix_key":"3d7d6a2b-f72f-44z7-bb20-79a94dff5645",
"qr_code_type":"dynamic_term",
"additional_data":[
{
"key_name":"Juros e Multa",
"value":"Juros 2 ao mes e multa de 1%"
}
],
"fine_amount":3,
"interest_amount":2,
"expiration_date":"2023-03-25",
"max_payment_days":128,
"rebate_amount":1,
"discounts":[],
"receiver_conciliation_id":"3d7d6a2bf72f44z7bb2079a94dff5645",
"transaction_data":{
"transaction_key":"4d7d6a2b-f72f-44z7-bb20-79a94dff5645",
"pix_transfer_key":"5d7d6a2b-f72f-44z7-bb20-79a94dff5645",
"end_to_end_id":"E32402502202303141907qlBAF1evdJ2"
}
},
"pix_message":"Conta de Luz Residencial nº123",
"settlement_date_type":"calendar_days"
},
"payment_orders":[
{
"payment_order_key":"10fc62fd-b0a0-4604-9bea-475e91a9dc82",
"payment_order_status":"paid",
"reference_date":"2025-06-30",
"receiver_conciliation_id":"cac0b5f74ee240f1b2ad16902506503d",
"transaction_amount":125.53,
"transaction_key":"21fc62fd-b0a0-4604-9bea-475e91a9dc56",
"incoming_pix_transfer_key":"21fc62fd-b0a0-4604-9bea-475e91a9dc56",
"created_at":"2021-10-22T20:30:23.459Z",
"paid_at":"2023-10-22T20:30:23.459Z"
}
],
"outgoing_recurrence_events":[
{
"outgoing_recurrence_event_key":"20fc62fd-b0a0-4604-9bea-475e91a9dc82",
"outgoing_recurrence_status":"created",
"created_at":"2021-10-22T20:30:23.459Z"
}
]
}
```
### Response Body Params
| Campo | Tipo | Descrição | Caracteres |
|------------------------------|------------|---------------------------------------------------------------------------------------------|------------|
| `request_control_key` | uuidv4 | Chave única para controle da requisição. | 36 |
| `outgoing_recurrence_key` | uuidv4 | Identificador da recorrência automática. | 36 |
| `outgoing_recurrence_status` | string | Status atual da recorrência (`approved`, `pending`, `rejected`, etc.). | 30 |
| `periodicity` | enumerator | Periodicidade da recorrência. | [Enumeradores periodicity](#enumeradores-periodicity) |
| `journey_type` | enumerator | Jornada da recorrência automática. | [Enumeradores journey_type](#enumeradores-journey_type) |
| `start_date` | string | Data de início da recorrência (formato ISO 8601, e.g., `2025-06-10`). | 10 |
| `end_date` | string | Data de término da recorrência (formato ISO 8601) ou null, se indeterminado. | 10 ou null |
| `outgoing_recurrence_data` | object | Objeto agrupando parâmetros da assinatura e dados complementares. | [Objeto outgoing_recurrence_data](#objeto-outgoing_recurrence_data) |
| `payment_orders` | array | Objeto agrupando parâmetros da assinatura e dados complementares. | [Objeto payment_orders](#objeto-payment_orders) |
| `outgoing_recurrence_events` | array | Objeto agrupando parâmetros dos eventos da recorrência | [Objeto outgoing_recurrence_events](#objeto-outgoing_recurrence_events) |
### Objeto outgoing_recurrence_data
| Campo | Tipo | Descrição | Caracteres |
|-----------------------------|----------|--------------------------------------------------------------------|------------|
| `minimum_recurrence_amount` | number | Valor mínimo esperado nas recorrências de valor variável | - |
| `recurrence_amount` | number | Valor da recorrência (para valor fixo; null se variável) | - |
| `retry_configuration` | object | Configuração de tentativas para recorrências não concluídas | [Objeto retry_configuration](#objeto-retry_configuration) |
| `debtor_data` | object | Dados do devedor (assinante) | [Objeto debtor_data](#objeto-debtor_data) |
| `qr_code_data` | object | Dados de QR Code gerado para o pagamento (se houver) | [Objeto qr_code_data](#objeto-qr_code_data) |
| `initial_payment_data` | object | Dados da cobrança inicial | [Objeto initial_payment_data](#objeto-initial_payment_data) |
| `pix_message` | string | Mensagem enviada junto à transação Pix | 140 |
| `settlement_date_type` | enumerator| Tipo do ajuste da data de liquidação | [Enumeradores settlement_date_type](#enumeradores-settlement_date_type) |
---
### Objeto retry_configuration
| Campo | Tipo | Descrição | Caracteres |
|-----------------|---------|---------------------------------------------|------------|
| `retry_allowed` | boolean | Indica se retentativas estão habilitadas | - |
| `retry_rule` | object | Regras detalhadas das retentativas | [Objeto retry_rule](#objeto-retry_rule) |
---
### Objeto retry_rule
| Campo | Tipo | Descrição | Caracteres |
|---------------|--------|-----------------------------------|------------|
| `first_retry` | object | Configuração para 1ª retentativa | [Objeto retry_detail](#objeto-retry_detail) |
| `second_retry`| object | Configuração para 2ª retentativa | [Objeto retry_detail](#objeto-retry_detail) |
| `third_retry` | object | Configuração para 3ª retentativa | [Objeto retry_detail](#objeto-retry_detail) |
---
### Objeto retry_detail
| Campo | Tipo | Descrição | Caracteres |
|-------|--------|-------------------------|------------|
| `day` | string | Dia da retentativa. | - |
| `time`| string | Horário da retentativa. | - |
---
### Objeto debtor_data
| Campo | Tipo | Descrição | Caracteres |
|-------------------|--------|------------------------|------------|
| `name` | string | Nome do assinante. | 50 |
| `email` | string | E-mail do assinante. | 100 |
| `document_number` | string | CPF ou CNPJ. | 14 |
| `address` | object | Endereço do assinante. | [Objeto address](#objeto-address) |
| `account_data` | object | Dados bancários. | [Objeto account_data](#objeto-account_data) |
---
### Objeto address
| Campo | Tipo | Descrição | Caracteres |
|---------------|--------|-------------------|------------|
| `city` | string | Cidade. | - |
| `postal_code` | string | CEP. | - |
| `uf` | string | Estado (sigla). | - |
| `street` | string | Logradouro. | - |
---
### Objeto account_data
| Campo | Tipo | Descrição | Caracteres |
|-----------------|--------|------------------------------|------------|
| `account_number`| string | Número da conta | - |
| `account_digit` | string | Dígito da conta | - |
| `account_branch`| string | Agência | - |
| `ispb` | string | ISPB da instituição financeira| - |
---
### Objeto qr_code_data
| Campo | Tipo | Descrição | Caracteres |
|------------------|--------|---------------------------------------------|------------|
| `qr_code_key` | string | Identificador do QR Code gerado | - |
| `qr_code_url` | string | URL para visualização do QR Code | - |
| `qr_code_image` | string | Imagem do QR Code (em Base64) | - |
---
### Objeto initial_payment_data
| Campo | Tipo | Descrição | Caracteres |
|---------------------------|----------|--------------------------------------------------------------------------|------------|
| `amount` | number | Valor principal da cobrança inicial em reais (R$) | - |
| `pix_key` | string | Chave Pix de destino para o pagamento inicial | 77 |
| `qr_code_type` | enum | Tipo de QR Code para cobrança inicial. | [Enumeradores qr_code_type](#enumeradores-qr_code_type) |
| `additional_data` | array | Lista de informações adicionais relacionadas à cobrança | [Array de objects additional_data](#array-additional_data) |
| `fine_amount` | number | Valor da multa, caso ocorra atraso no pagamento | - |
| `interest_amount` | number | Valor dos juros, caso ocorra atraso no pagamento | - |
| `expiration_date` | string | Data de expiração da cobrança inicial (formato ISO 8601) | 10 |
| `max_payment_days` | integer | Número máximo de dias de aceite após expiração | - |
| `rebate_amount` | number | Valor do desconto para pagamento antecipado | - |
| `discounts` | array | Lista de descontos adicionais | - |
| `receiver_conciliation_id`| string | Identificador de conciliação do pagamento pelo recebedor | 35 |
| `transaction_data` | object | Detalhes da transação relacionada à cobrança inicial | [Objeto transaction_data](#objeto-transaction_data) |
---
### Array additional_data
| Campo | Tipo | Descrição | Caracteres |
|--------------|---------|-----------------------------------------------------------------|------------|
| `key_name` | string | Nome da informação adicional (ex: "Juros e Multa") | 140 |
| `value` | string | Valor ou descrição da informação adicional | 140 |
---
### Objeto transaction_data
| Campo | Tipo | Descrição | Caracteres |
|---------------------|--------|----------------------------------------|------------|
| `transaction_key` | string | Chave única da transação | 36 |
| `pix_transfer_key` | string | Identificador da transferência Pix | 36 |
| `end_to_end_id` | string | Identificador end-to-end do Pix | 32 |
---
### Objeto payment_orders
| Campo | Tipo | Descrição | Caracteres |
|-----------------------------|---------|---------------------------------------------------------|------------|
| `payment_order_key` | string | Chave única identificadora da ordem de pagamento | 32 |
| `payment_order_status` | string | Status da ordem de pagamento | - |
| `reference_date` | string | Data de referência da cobrança | - |
| `receiver_conciliation_id` | uuidv4 | ID de conciliação do recebedor | 35 |
| `transaction_amount` | number | Valor monetário da transação | - |
| `transaction_key` | uuidv4 | Chave única da transação | 36 |
| `incoming_pix_transfer_key` | uuidv4 | Chave de transferência Pix recebida | 36 |
| `created_at` | string | Data/hora de criação da ordem (formato ISO 8601) | - |
| `paid_at` | string | Data/hora do pagamento efetuado (formato ISO 8601) | - |
### Objeto outgoing_recurrence_events
| Campo | Tipo | Descrição | Caracteres |
|-----------------------------|---------|---------------------------------------------------------|------------|
| `outgoing_recurrence_event_key` | string | Chave única identificadora do evento de recorrência | 36 |
| `outgoing_recurrence_status` | string | Status da recorrência | - |
| `created_at` | string | Data/hora de criação da ordem (formato ISO 8601) | - |
### Enumeradores periodicity
| Enumerador | Descrição |
|--------------|----------------------|
| `weekly` | Recorrência semanal |
| `monthly` | Recorrência mensal |
| `quarterly` | Recorrência trimestral|
| `semiannual` | Recorrência semestral |
| `annual` | Recorrência anual |
---
### Enumeradores journey_type
| Enumerador | Descrição |
|-----------------|-----------------------------------------------|
| `journey_one` | Notificação direta no aplicativo bancário |
| `journey_two` | Experiência QR Code para cobrança recorrente |
| `journey_three` | Pagamento instantâneo + recorrência QR Code |
| `journey_four` | Opt-in recorrente a partir de operação Pix |
---
### Enumeradores settlement_date_type
| Enumerador | Descrição |
|-----------------|----------------------|
| `workdays` | Dias úteis |
| `calendar_days` | Dias corridos |
---
### Enumeradores qr_code_type
| Enumerador | Descrição |
|-------------------|------------------------------------------------------------|
| `dynamic_instant` | QR Code dinâmico para pagamento instantâneo |
| `dynamic_term` | QR Code dinâmico para pagamento com vencimento futuro |
STATUS 4XX
Response Error
```json
{
"title": "titulo",
"description": "description in English",
"translation": "descrição em português",
"code": "codigo"
}
```
| Código HTTP | Código QI
`code` | Título
`title` | Descrição (eng)
`description` | Descrição (ptbr)
`translation` |
|-------------|----------------------|-----------------------------------|----------------------------------------------------------------------------|--------------------------------------------------------------------|
| 400 | QIT000002 | Bad Request | Invalid request schema. | Erro no esquema da requisição. |
| 404 | APX000002 | Recurrence Not Found | Recurrence \{recurrence_key\} not found. | Recorrência \{recurrence_key\} não encontrada. |
---
# Consulta de Dados de Recorrência Automática Pix pelo QRCode
URL: /documentation/baas/pix_automatico/recebedor/consultar_recorrencia_receiver
## Request
ENDPOINT /account/ ACCOUNT_KEY /outgoing_recurrence/qr_code_initial_payment/ RECEIVER_CONCILIATION_ID
MÉTODO GET
### Path Params
| Campo | Tipo | Descrição | Caracteres |
|--------------------------|--------|---------------------------------------------------|------------|
| `account_key` * | uuidv4 | Chave única de identificação da conta. | 36 |
| `receiver_conciliation_id`*| string | Id de conciliação do qr_code associado à recorrência | 32 |
## Response
STATUS 200
Response Body
```json
{
"request_control_key": "98fc62fd-b0a0-4604-9bea-475e91a9dc82",
"outgoing_recurrence_key": "8cb70dea-9fb0-4a68-9572-99a72849c8d6",
"outgoing_recurrence_status": "approved",
"periodicity": "monthly",
"journey_type": "journey_four",
"start_date": "2025-06-10",
"end_date": "2027-06-10",
"outgoing_recurrence_data": {
"minimum_recurrence_amount": 123.45,
"recurrence_amount": null,
"retry_configuration": {
"retry_allowed": true,
"retry_rule": {
"first_retry": {
"day": "1"
},
"second_retry": {
"day": "3"
},
"third_retry": {
"day": "4"
}
}
},
"debtor_data": {
"name": "Sebastião",
"email": "sebastiao@test.com",
"document_number": "05431134850",
"address": {
"city": "São Paulo",
"postal_code": "123456-789",
"uf": "SP",
"street": "Av Paulista 123"
},
"account_data": {
"account_number": "123456",
"account_digit": "7",
"account_branch": "0001",
"ispb": "31872495"
}
},
"qr_code_data": {
"qr_code_key": "0f45cc3d-9bd1-4d68-a865-4cf477b5da45",
"qr_code_url": "urlqrcode.url",
"qr_code_image": "image_base64"
},
"initial_payment_data": {
"amount": 22.34,
"pix_key": "3d7d6a2b-f72f-44z7-bb20-79a94dff5645",
"qr_code_type": "dynamic_term",
"additional_data": [
{
"key_name": "Juros e Multa",
"value": "Juros 2 ao mes e multa de 1%"
}
],
"fine_amount": 3,
"interest_amount": 2,
"expiration_date": "2023-03-25",
"max_payment_days": 128,
"rebate_amount": 1,
"discounts": [],
"receiver_conciliation_id":"3d7d6a2bf72f44z7bb2079a94dff5645",
"transaction_data":{
"transaction_key":"4d7d6a2b-f72f-44z7-bb20-79a94dff5645",
"pix_transfer_key":"5d7d6a2b-f72f-44z7-bb20-79a94dff5645",
"end_to_end_id":"E32402502202303141907qlBAF1evdJ2"
}
},
"pix_message": "Conta de Luz Residencial nº123",
"settlement_date_type": "calendar_days"
}
}
```
### Response Body Params
| Campo | Tipo | Descrição | Caracteres |
|------------------------------|------------|---------------------------------------------------------------------------------------------|------------|
| `request_control_key` | uuidv4 | Chave única para controle da requisição. | 36 |
| `outgoing_recurrence_key` | uuidv4 | Identificador da recorrência automática. | 36 |
| `outgoing_recurrence_status` | string | Status atual da recorrência (`approved`, `pending`, `rejected`, etc.). | 30 |
| `periodicity` | enumerator | Periodicidade da recorrência. | [Enumeradores periodicity](#enumeradores-periodicity) |
| `journey_type` | enumerator | Jornada da recorrência automática. | [Enumeradores journey_type](#enumeradores-journey_type) |
| `start_date` | string | Data de início da recorrência (formato ISO 8601, e.g., `2025-06-10`). | 10 |
| `end_date` | string | Data de término da recorrência (formato ISO 8601) ou null, se indeterminado. | 10 ou null |
| `outgoing_recurrence_data` | object | Objeto agrupando parâmetros da assinatura e dados complementares. | [Objeto outgoing_recurrence_data](#objeto-outgoing_recurrence_data) |
---
### Objeto outgoing_recurrence_data
| Campo | Tipo | Descrição | Caracteres |
|-----------------------------|----------|--------------------------------------------------------------------|------------|
| `minimum_recurrence_amount` | number | Valor mínimo esperado nas recorrências de valor variável | - |
| `recurrence_amount` | number | Valor da recorrência (para valor fixo; null se variável) | - |
| `retry_configuration` | object | Configuração de tentativas para recorrências não concluídas | [Objeto retry_configuration](#objeto-retry_configuration) |
| `debtor_data` | object | Dados do devedor (assinante) | [Objeto debtor_data](#objeto-debtor_data) |
| `qr_code_data` | object | Dados de QR Code gerado para o pagamento (se houver) | [Objeto qr_code_data](#objeto-qr_code_data) |
| `initial_payment_data` | object | Dados da cobrança inicial | [Objeto initial_payment_data](#objeto-initial_payment_data) |
| `pix_message` | string | Mensagem enviada junto à transação Pix | 140 |
| `settlement_date_type` | enumerator| Tipo do ajuste da data de liquidação | [Enumeradores settlement_date_type](#enumeradores-settlement_date_type) |
---
### Objeto retry_configuration
| Campo | Tipo | Descrição | Caracteres |
|-----------------|---------|---------------------------------------------|------------|
| `retry_allowed` | boolean | Indica se retentativas estão habilitadas | - |
| `retry_rule` | object | Regras detalhadas das retentativas | [Objeto retry_rule](#objeto-retry_rule) |
---
### Objeto retry_rule
| Campo | Tipo | Descrição | Caracteres |
|---------------|--------|-----------------------------------|------------|
| `first_retry` | object | Configuração para 1ª retentativa | [Objeto retry_detail](#objeto-retry_detail) |
| `second_retry`| object | Configuração para 2ª retentativa | [Objeto retry_detail](#objeto-retry_detail) |
| `third_retry` | object | Configuração para 3ª retentativa | [Objeto retry_detail](#objeto-retry_detail) |
---
### Objeto retry_detail
| Campo | Tipo | Descrição | Caracteres |
|-------|--------|-------------------------|------------|
| `day` | string | Dia da retentativa. | - |
| `time`| string | Horário da retentativa. | - |
---
### Objeto debtor_data
| Campo | Tipo | Descrição | Caracteres |
|-------------------|--------|------------------------|------------|
| `name` | string | Nome do assinante. | 50 |
| `email` | string | E-mail do assinante. | 100 |
| `document_number` | string | CPF ou CNPJ. | 14 |
| `address` | object | Endereço do assinante. | [Objeto address](#objeto-address) |
| `account_data` | object | Dados bancários. | [Objeto account_data](#objeto-account_data) |
---
### Objeto address
| Campo | Tipo | Descrição | Caracteres |
|---------------|--------|-------------------|------------|
| `city` | string | Cidade. | - |
| `postal_code` | string | CEP. | - |
| `uf` | string | Estado (sigla). | - |
| `street` | string | Logradouro. | - |
---
### Objeto account_data
| Campo | Tipo | Descrição | Caracteres |
|-----------------|--------|------------------------------|------------|
| `account_number`| string | Número da conta | - |
| `account_digit` | string | Dígito da conta | - |
| `account_branch`| string | Agência | - |
| `ispb` | string | ISPB da instituição financeira| - |
---
### Objeto qr_code_data
| Campo | Tipo | Descrição | Caracteres |
|------------------|--------|---------------------------------------------|------------|
| `qr_code_key` | string | Identificador do QR Code gerado | - |
| `qr_code_url` | string | URL para visualização do QR Code | - |
| `qr_code_image` | string | Imagem do QR Code (em Base64) | - |
---
### Objeto initial_payment_data
| Campo | Tipo | Descrição | Caracteres |
|---------------------------|----------|--------------------------------------------------------------------------|------------|
| `amount` | number | Valor principal da cobrança inicial em reais (R$) | - |
| `pix_key` | string | Chave Pix de destino para o pagamento inicial | 77 |
| `qr_code_type` | enum | Tipo de QR Code para cobrança inicial. | [Enumeradores qr_code_type](#enumeradores-qr_code_type) |
| `additional_data` | array | Lista de informações adicionais relacionadas à cobrança | [Array de objects additional_data](#array-additional_data) |
| `fine_amount` | number | Valor da multa, caso ocorra atraso no pagamento | - |
| `interest_amount` | number | Valor dos juros, caso ocorra atraso no pagamento | - |
| `expiration_date` | string | Data de expiração da cobrança inicial (formato ISO 8601) | 10 |
| `max_payment_days` | integer | Número máximo de dias de aceite após expiração | - |
| `rebate_amount` | number | Valor do desconto para pagamento antecipado | - |
| `discounts` | array | Lista de descontos adicionais | - |
| `receiver_conciliation_id`| string | Identificador de conciliação do pagamento pelo recebedor | 35 |
| `transaction_data` | object | Detalhes da transação relacionada à cobrança inicial | [Objeto transaction_data](#objeto-transaction_data) |
---
### Array additional_data
| Campo | Tipo | Descrição | Caracteres |
|--------------|---------|-----------------------------------------------------------------|------------|
| `key_name` | string | Nome da informação adicional (ex: "Juros e Multa") | 140 |
| `value` | string | Valor ou descrição da informação adicional | 140 |
---
### Objeto transaction_data
| Campo | Tipo | Descrição | Caracteres |
|---------------------|--------|----------------------------------------|------------|
| `transaction_key` | string | Chave única da transação | 36 |
| `pix_transfer_key` | string | Identificador da transferência Pix | 36 |
| `end_to_end_id` | string | Identificador end-to-end do Pix | 32 |
---
### Enumeradores periodicity
| Enumerador | Descrição |
|--------------|----------------------|
| `weekly` | Recorrência semanal |
| `monthly` | Recorrência mensal |
| `quarterly` | Recorrência trimestral|
| `semiannual` | Recorrência semestral |
| `annual` | Recorrência anual |
---
### Enumeradores journey_type
| Enumerador | Descrição |
|-----------------|-----------------------------------------------|
| `journey_one` | Notificação direta no aplicativo bancário |
| `journey_two` | Experiência QR Code para cobrança recorrente |
| `journey_three` | Pagamento instantâneo + recorrência QR Code |
| `journey_four` | Opt-in recorrente a partir de operação Pix |
---
### Enumeradores settlement_date_type
| Enumerador | Descrição |
|-----------------|----------------------|
| `workdays` | Dias úteis |
| `calendar_days` | Dias corridos |
---
### Enumeradores qr_code_type
| Enumerador | Descrição |
|-------------------|------------------------------------------------------------|
| `dynamic_instant` | QR Code dinâmico para pagamento instantâneo |
| `dynamic_term` | QR Code dinâmico para pagamento com vencimento futuro |
STATUS 4XX
Response Error
```json
{
"title": "titulo",
"description": "description in English",
"translation": "descrição em português",
"code": "codigo"
}
```
| Código HTTP | Código QI
`code` | Título
`title` | Descrição (eng)
`description` | Descrição (ptbr)
`translation` |
|-------------|----------------------|-----------------------------------|----------------------------------------------------------------------------|--------------------------------------------------------------------|
| 400 | QIT000002 | Bad Request | Invalid request schema. | Erro no esquema da requisição. |
| 404 | APX000002 | Recurrence Not Found | Recurrence \{recurrence_key\} not found. | Recorrência \{recurrence_key\} não encontrada. |
---
# Conciliação e Liquidação de Pagamentos
URL: /documentation/baas/pix_automatico/recebedor/introducao
## Visão Geral do Negócio
O sistema de pagamentos via Pix Automático oferece uma solução eficiente para automatizar débitos recorrentes, proporcionando maior comodidade tanto para o pagador quanto para o recebedor. Ao garantir a automação e a notificação dos envolvidos, minimiza-se o risco de inadimplência e otimiza-se o fluxo de caixa das empresas.
## Processamento de Pagamentos via Pix Automático
Na data agendada para o pagamento de um débito via Pix Automático, o banco do pagador deve emitir a ordem de pagamento entre meia-noite e 8h. Após a confirmação do pagamento, o usuário pagador receberá uma notificação. Caso o débito seja cancelado pelo pagador ou recebedor antes dessa etapa, a transação não será processada.
## Recorrências de Valor Variável
Para recorrências com valor variável, o usuário recebedor definirá o valor mínimo, enquanto o pagador determinará o valor máximo permitido. O valor específico a ser cobrado deve ser enviado pelo recebedor entre 10 a 2 dias antes da data de pagamento.
:::warning
Se não for enviado, a cobrança não será realizada. Essa etapa não se aplica a recorrências de valor fixo.
:::
### Contexto de Negócio
As recorrências de valor variável são particularmente úteis em setores onde os valores cobráveis podem oscilar, como no fornecimento de utilidades ou em assinaturas baseadas em uso, permitindo flexibilidade nos pagamentos.
## Lotes de Conciliação de Pagamentos
Um conjunto de recorrências com pagamentos a receber será chamado de grupo de liquidação (`conciliation_batch`).
- A criação dos lotes de conciliação ocorre 10 dias antes da data de pagamento.
- Os lotes são fechados 2 dias antes da data de pagamento.
- Após a criação de um lote, um webhook será enviado com a `conciliation_batch_key`. As recorrências associadas podem ser obtidas através do endpoint específico.
### Impacto no Negócio
Os lotes de conciliação facilitam a gestão de recebíveis em escala, proporcionando transparência e controle sobre os fluxos financeiros programados, essencial para o planejamento estratégico e financeiro de qualquer organização.
## Retentativas de Recebimento
O usuário recebedor pode definir retentativas de recebimento durante a criação da recorrência, respeitando as seguintes condições:
- As retentativas podem ocorrer até 7 dias após a data de vencimento original.
- No máximo três tentativas podem ser efetuadas, conforme definido na criação.
- O valor deve ser o mesmo do pagamento original.
### Considerações de Negócio
As retentativas de recebimento são uma funcionalidade crucial para a maximização de recebíveis, garantindo oportunidades adicionais para liquidar pagamentos que, por qualquer motivo, falharam na data original. Isso reduz perdas por inadimplência e melhora a experiência do cliente ao proporcionar flexibilidade adicional.
---
# Criar uma Recorrência (Jornada 4)
URL: /documentation/baas/pix_automatico/recebedor/journey_four
> Jornada 4 — QR Code + Pagament ou agendamento + Oferta do pix automático
{`
.hero-section { background: linear-gradient(135deg, #eff6ff 0%, #ffffff 100%); border: 1px solid #e5e7eb; border-radius: 16px; padding: 24px; margin: 24px 0 32px 0; }
.hero-grid { display: grid; grid-template-columns: repeat(auto-fit, minmax(220px, 1fr)); gap: 16px; margin-top: 20px; }
.hero-item { background: #ffffff; border: 1px solid #e5e7eb; border-radius: 10px; padding: 16px; }
.hero-item > strong { display: block; color: #1e40af; font-size: 14px; margin-bottom: 6px; font-weight: 700; }
.hero-item p { margin: 0; font-size: 13px; color: #475569; line-height: 1.5; }
.endpoint-card { background: linear-gradient(135deg, #ffffff 0%, #f8fafc 100%); border: 2px solid #e5e7eb; border-radius: 12px; padding: 24px; position: relative; overflow: hidden; }
.endpoint-card::before { content: ''; position: absolute; top: 0; left: 0; width: 4px; height: 100%; background: linear-gradient(to bottom, #3b82f6, #1e40af); }
.endpoint-list { display: grid; gap: 12px; font-size: 13px; color: #334155; }
.endpoint__item { display: grid; grid-template-columns: 120px 1fr; align-items: center; gap: 12px; background: #ffffff; border: 1px solid #e5e7eb; border-radius: 8px; padding: 10px 14px; }
.badge { font-size: 11px; font-weight: 800; padding: 4px 10px; border-radius: 6px; color: #fff; text-transform: uppercase; letter-spacing: .4px; background: #1e40af; }
.details-container { background: linear-gradient(135deg, #ffffff 0%, #f8fafc 100%); border: 1px solid #e5e7eb; border-radius: 10px; padding: 8px 12px; margin: 20px 0; }
.details-container summary { font-weight: 700; color: #1e40af; cursor: pointer; font-size: 14px; padding: 10px 0 10px 28px; display: flex; align-items: center; position: relative; }
.details-container summary::-webkit-details-marker { display: none; }
.details-container summary::before { content: ''; position: absolute; left: 10px; width: 0; height: 0; border-left: 7px solid #1e40af; border-top: 6px solid transparent; border-bottom: 6px solid transparent; transition: transform .2s ease; }
.details-container[open] summary::before { transform: rotate(90deg); }
.code-block { margin-top: 12px; border-radius: 8px; overflow: hidden; }
.table-container { overflow: auto; border: 0; border-radius: 0; margin: 20px 0; background: transparent; }
.table-container table { width: 100%; border-collapse: collapse; font-size: 13px; }
.table-container th, .table-container td { border-top: 1px solid #e5e7eb; padding: 12px 16px; text-align: left; }
.table-container thead th { background: linear-gradient(135deg, #f8fafc 0%, #ffffff 100%); font-weight: 700; color: #0f172a; font-size: 13px; }
`}
Visão geral
O que é O cliente realiza o pagamento ou agendamento de um QR Code e, depois, recebe a oferta para ativar a recorrência Pix Automático.
Quando usar Indicado para faturas, boletos ou contas com proposta de adesão à recorrência, mas só após o pagamento ou agendamento inicial.
Como funciona Pagador lê o QR Code → paga ou agenda o pagamento → ao concluir, recebe convite para ativar o Pix Automático para aquela cobrança (opcional).
Benefícios Flexível: a decisão sobre a recorrência ocorre após o pagamento/agendamento, permitindo adesão voluntária e espontânea pelo pagador.
Pontos de atenção A oferta de recorrência é feita somente após o pagamento/agendamento — pode ser recusada pelo cliente. Se não disponível para aquele caso, prossiga apenas com o pagamento, sem oferecer recorrência.
## Request
{`
.endpoint-card { background: linear-gradient(135deg, #ffffff 0%, #f8fafc 100%); border: 2px solid #e5e7eb; border-radius: 12px; padding: 24px; position: relative; overflow: hidden; }
.endpoint-card::before { content: ''; position: absolute; top: 0; left: 0; width: 4px; height: 100%; background: linear-gradient(to bottom, #3b82f6, #1e40af); }
.endpoint-list { display: grid; gap: 12px; font-size: 13px; color: #334155; }
.endpoint__item { display: grid; grid-template-columns: 120px 1fr; align-items: center; gap: 12px; background: #ffffff; border: 1px solid #e5e7eb; border-radius: 8px; padding: 10px 14px; }
.badge { font-size: 11px; font-weight: 800; padding: 4px 10px; border-radius: 6px; color: #fff; text-transform: uppercase; letter-spacing: .4px; background: #1e40af; }
.details-container { background: linear-gradient(135deg, #ffffff 0%, #f8fafc 100%); border: 1px solid #e5e7eb; border-radius: 10px; padding: 8px 12px; margin: 20px 0; }
.details-container summary { font-weight: 700; color: #1e40af; cursor: pointer; font-size: 14px; padding: 10px 0 10px 28px; display: flex; align-items: center; position: relative; }
.details-container summary::-webkit-details-marker { display: none; }
.details-container summary::before { content: ''; position: absolute; left: 10px; width: 0; height: 0; border-left: 7px solid #1e40af; border-top: 6px solid transparent; border-bottom: 6px solid transparent; transition: transform .2s ease; }
.details-container[open] summary::before { transform: rotate(90deg); }
.code-block { margin-top: 12px; border-radius: 8px; overflow: hidden; }
`}
ENDPOINT /account/ account_key /outgoing_recurrence/journey_four
MÉTODO POST
### Request Path Params
| Campo | Tipo | Descrição | Caracteres |
|---------------|-------|------------------------------------------------|------------|
| `account_key`*| uuid4 | Chave única de identificação da conta. | 36 |
### Request Body
**Request Body: Criar Recorrência (Jornada 4)**
```json
{
"request_control_key": "98fc62fd-b0a0-4604-9bea-475e91a9dc82",
"periodicity": "monthly",
"minimum_recurrence_amount": 125,
"start_date": "2025-06-10",
"end_date": "2027-06-10",
"pix_message": "Conta de Luz Residencial nº123",
"recurrence_type": "variable_amount",
"debtor_data": {
"name": "Sebastião",
"email": "sebastiao@test.com",
"document_number": "05431134850",
"contract_id": "12345",
"address": {
"street": "Av. Brigadeiro Faria Lima",
"state": "SP",
"city": "São Paulo",
"neighborhood": "Jardim Paulistano",
"number": "2391",
"postal_code": "01452905",
"complement": "Complemento"
}
},
"initial_payment_data": {
"amount": 22.34,
"pix_key": "3d7d6a2b-f72f-44z7-bb20-79a94dff5645",
"qr_code_type": "dynamic_term",
"additional_data": [
{
"key_name": "Juros e Multa",
"value": "Juros 2 ao mes e multa de 1%"
}
],
"fine_amount": 3,
"interest_amount": 2,
"expiration_date": "2023-03-25",
"max_payment_days": 128,
"rebate_amount": 1,
"discounts": [],
"receiver_conciliation_id": "3d7d6a2bf72f44z7bb2079a94dff5645"
},
"retry_configuration": {
"retry_allowed": true,
"retry_rule": {
"first_retry": {
"day": "1"
},
"second_retry": {
"day": "3"
},
"third_retry": {
"day": "4"
}
}
},
"settlement_date_type": "workdays"
}
```
### Body Params
| Campo | Tipo | Descrição | Caracteres |
|-----------------------------------|-------------|-------------------------------------------------------------------------------------------------------------------|------------|
| `request_control_key` * | uuid | Chave única de identificação da requisição utilizada pelo cliente no formato uuid4. | 36 |
| `periodicity` * | enumerator | Tipo da periodicidade associada à recorrência da assinatura. | [Enumeradores periodicity](#enumeradores-periodicity) |
| `minimum_recurrence_amount` | float | Valor mínimo da transação para recorrências de valor variável | - |
| `start_date` * | string | Data de início da recorrência (formato ISO 8601, e.g., "2025-07-01"). | - |
| `end_date` | string | Data de término da recorrência; para tempo indeterminado, enviar como null. | - |
| `pix_message` * | string | Mensagem a ser enviada junto à transação Pix. | 140 |
| `debtor_data` * | Object | Dados do devedor (assinante). | [Objeto debtor_data](#objeto-debtor_data) |
| `retry_configuration` * | Object | Configuração de retentativas para transações não concluídas. | [Objeto retry_configuration](#objeto-retry_configuration) |
| `settlement_date_type` * | enumerator | Tipo de ajuste da data de liquidação | [Enumeradores settlement_date_type](#enumeradores-settlement_date_type) |
| `recurrence_type` * | enumerator | Tipo de recorrência | [Enumeradores recurrence_type](#enumeradores-recurrence_type) |
| `initial_payment_data` * | Object | Objeto com informações da cobrança inicial a ser realizada na criação da assinatura. | [Objeto initial_payment_data](#objeto-initial_payment_data) |
:::caution Atenção
O campo `minimum_recurrence_amount` é opcional e deve ser informado apenas para recorrência de valor variável. Caso a recorrência seja de valor fixo, deve-se enviar o campo `recurrence_amount`, com o valor da recorrência. Assim como o enumerador `recurrence_type`, que deverá corresponder ao tipo da recorrência (Valor fixo ou variável).
:::
### Enumeradores periodicity
| Enumerador | Descrição |
|--------------|-----------------------|
| `weekly` | Recorrência semanal |
| `monthly` | Recorrência mensal |
| `quarterly` | Recorrência trimestral|
| `semiannual` | Recorrência semestral |
| `annual` | Recorrência anual |
### Enumeradores settlement_date_type
| Enumerador | Descrição |
|--------------|-----------------------|
| `workdays` | Dias úteis |
| `calendar_days` | Dias corridos |
### Enumeradores recurrence_type
| Enumerador | Descrição |
|--------------|-----------------------|
| `fixed_amount` | Recorrência de Valor Fixo |
| `variable_amount` | Recorrência de Valor Variável |
### Objeto debtor_data
| Campo | Tipo | Descrição | Caracteres |
|---------------------|--------|-----------------------|------------|
| `name` * | string | Nome do assinante. | 50 |
| `email` * | string | E-mail do assinante. | 100 |
| `document_number` * | string | CPF ou CNPJ do assinante. | 14 |
| `contract_id` | string | Identificador do contrato do assinante. | 100 |
| `address` * | Object | Endereço do assinante.| [Objeto address](#objeto-address) |
### Objeto address
| Campo | Tipo | Descrição | Caracteres |
|---------------|--------|-------------------|------------|
| `street` | string | Rua. | - |
| `state` | string | Estado. | - |
| `city` | string | Cidade. | - |
| `neighborhood`| string | Bairro. | - |
| `number` | string | Número. | - |
| `postal_code` | string | CEP. | - |
| `complement` | string | Complemento. | - |
### Objeto retry_configuration
| Campo | Tipo | Descrição | Caracteres |
|---------------|---------|-------------------------|------------|
| `retry_allowed`| boolean | Indica se retentativas são permitidas. | - |
| `retry_rule` | Object | Regras de retentativa. | [Objeto retry_rule](#objeto-retry_rule) |
### Objeto retry_rule
| Campo | Tipo | Descrição | Caracteres |
|---------------|--------|-------------------------|------------|
| `first_retry` | Object | Configuração da primeira retentativa. | [Objeto retry_detail](#objeto-retry_detail) |
| `second_retry`| Object | Configuração da segunda retentativa. | [Objeto retry_detail](#objeto-retry_detail) |
| `third_retry` | Object | Configuração da terceira retentativa. | [Objeto retry_detail](#objeto-retry_detail) |
### Objeto retry_detail
| Campo | Tipo | Descrição | Caracteres |
|-------|--------|-------------------------|------------|
| `day` | string | Dia da retentativa. | - |
### Objeto initial_payment_data
| Campo | Tipo | Descrição | Caracteres |
|----------------------------|------------|------------------------------------------------------------------------------------------|------------|
| `amount` * | number | Valor principal da cobrança inicial em reais (R$). | - |
| `pix_key` * | string | Chave Pix de destino para o pagamento. | 77 |
| `qr_code_type`* | enumerator | Tipo de QR Code para a cobrança inicial. | [Enumeradores qr_code_type](#enumeradores-qr_code_type) |
| `additional_data`* | array | Lista de objetos com informações adicionais relacionadas à cobrança (ex: juros, multa). | [Objetos additional_data](#obj-additional_data) |
| `fine_amount` | number | Valor da multa, caso ocorra atraso no pagamento. | - |
| `interest_amount` | number | Valor dos juros, caso ocorra atraso no pagamento. | - |
| `expiration_date` * | string | Data de expiração da cobrança inicial (formato ISO 8601, e.g., "2023-03-25"). | - |
| `max_payment_days` | integer | Número máximo de dias, a partir da data de expiração, em que o pagamento pode ser aceito.| - |
| `rebate_amount` | number | Valor do desconto para pagamento antecipado. | - |
| `discounts` | array | Lista de descontos adicionais aplicáveis (se houver). | - |
| `receiver_conciliation_id` | string | Identificador único para conciliação do pagamento pelo recebedor. | 32 |
### Enumeradores qr_code_type
| Valor | Descrição |
|--------------------|---------------------------------------------------------------------------|
| `dynamic_instant` | Gera um QR Code dinâmico para pagamento instantâneo, com vencimento imediato. |
| `dynamic_term` | Gera um QR Code dinâmico com prazo definido para pagamento (vencimento futuro). |
### Objeto additional_data
| Campo | Tipo | Descrição | Caracteres |
|--------------|---------|-----------------------------------------------------------------|------------|
| `key_name` | string | Nome do campo adicional de informação (exemplo: "Juros e Multa").| - |
| `value` | string | Valor ou descrição da informação adicional. | - |
## Response
STATUS 200
:::caution Atenção
Quando o usuário pagor recebe a notificação, ele pode optar por agendar o Pix ou realizar a transferência naquele momento. Caso o pagador realize instantaneamente o pagamento, será enviado o webhook do tipo `baas.automatic_pix.outgoing_recurrence.status_change` com as informações preenchidas, em caso de agendamento os valores serão `null`.
:::
**Response Body**
```json
{
"request_control_key": "98fc62fd-b0a0-4604-9bea-475e91a9dc82",
"outgoing_recurrence_key": "8cb70dea-9fb0-4a68-9572-99a72849c8d6",
"outgoing_recurrence_status": "pending_confirmation",
"qr_code_data": {
"qr_code_url": "url",
"qr_code_key": "6f270b64-1b7a-4269-91f8-3f9cf30ba0bb",
"qr_code_image": "imageb64"
},
"initial_payment_data": {
"receiver_conciliation_id": "6f270b64-1b7a-4269-91f8-3f9cf30ba0bb"
},
"created_at": "2021-10-22T20:30:23.459Z"
}
```
### Response Body
| Campo | Tipo | Descrição | Caracteres |
|-----------------------|------------|---------------------------------------------------------------------------|------------|
| `request_control_key` | uuid | Chave de controle da requisição enviada pelo cliente. | 36 |
| `recurrence_key` | uuid | Chave única de identificação da recorrência de assinatura. | 36 |
| `recurrence_status` | enumerator | Status atual da recorrência. | [Enumeradores recurrence_status](#enumeradores-recurrence_status) |
| `qr_code_data` | enumerator | Dados do QRCode | [Objeto qr_code_data](#enumeradores-qr_code_data) |
| `initial_payment_data`| enumerator | Informações do pagamento iniciado | [Objeto qr_code_data](#enumeradores-qr_code_data) |
| `created_at` | string | Data e hora de criação da recorrência (formato ISO 8601). | - |
### Objeto qr_code_data
| Campo | Tipo | Descrição | Caracteres |
|-------|--------|-------------------------|------------|
| `qr_code_url` | string | URL do copia e cola do qr_code | - |
| `qr_code_key`| uuuid | Chave Única de identificação do qr_code. | 36 |
| `qr_code_image`| string | Base64 da imagem do qr_code | - |
### Objeto initial_payment_data
| Campo | Tipo | Descrição | Caracteres |
|-------|--------|-------------------------|------------|
| `receiver_conciliation_id` | string | Identificador único para conciliação do pagamento pelo recebedor. | 32 |
### Enumeradores recurrence_status
| Enumerador | Descrição |
|----------------------|-----------------------------------|
| `pending_confirmation` | Recorrência pendente de confirmação |
| `active` | Recorrência ativa |
| `cancelled` | Recorrência cancelada |
| `suspended` | Recorrência suspensa |
| `expired` | Recorrência expirada |
STATUS 4XX
**Response Error**
```json
{
"title": "titulo",
"description": "description in English",
"translation": "descrição em português",
"code": "codigo"
}
```
| Código HTTP | Código QI
`code` | Título
`title` | Descrição (eng)
`description` | Descrição (ptbr)
`translation` |
|-------------|----------------------|-----------------------------------|----------------------------------------------------------------------------|--------------------------------------------------------------------|
| 400 | QIT000002 | Bad Request | Invalid request schema. | Erro no esquema da requisição. |
| 403 | APX000030 | Unauthorized Transaction | User is not authorized to create this recurrence. | Usuário não autorizado a criar esta recorrência. |
| 403 | APX000018 | Endpoint Access Denied | Requester lacks permission to access this endpoint. | Requester não possui permissão para acessar este endpoint. |
| 404 | APX000021 | Subscription Not Found | Subscription \{subscription_key\} not found. | Assinatura \{subscription_key\} não encontrada. |
| 404 | APX000002 | Recurrence Not Found | Recurrence \{recurrence_key\} not found. | Recorrência \{recurrence_key\} não encontrada. |
| 406 | APX000027 | Invalid Transaction Amount | Transaction amount \{minimum_transaction_amount\} is invalid. | Valor da transação \{minimum_transaction_amount\} é inválido. |
| 409 | APX000014 | Request Control Key Conflict | The request_control_key \{request_control_key\} is already in use. | A request_control_key \{request_control_key\} já está em uso. |
---
# Criar uma Recorrência (Jornada 1)
URL: /documentation/baas/pix_automatico/recebedor/journey_one
> Jornada 1 — Sem QR Code (notificação no app)
{`
.hero-section { background: linear-gradient(135deg, #eff6ff 0%, #ffffff 100%); border: 1px solid #e5e7eb; border-radius: 16px; padding: 24px; margin: 24px 0 32px 0; }
.hero-grid { display: grid; grid-template-columns: repeat(auto-fit, minmax(220px, 1fr)); gap: 16px; margin-top: 20px; }
.hero-item { background: #ffffff; border: 1px solid #e5e7eb; border-radius: 10px; padding: 16px; }
.hero-item > strong { display: block; color: #1e40af; font-size: 14px; margin-bottom: 6px; font-weight: 700; }
.hero-item p { margin: 0; font-size: 13px; color: #475569; line-height: 1.5; }
.endpoint-card { background: linear-gradient(135deg, #ffffff 0%, #f8fafc 100%); border: 2px solid #e5e7eb; border-radius: 12px; padding: 24px; position: relative; overflow: hidden; }
.endpoint-card::before { content: ''; position: absolute; top: 0; left: 0; width: 4px; height: 100%; background: linear-gradient(to bottom, #3b82f6, #1e40af); }
.endpoint-list { display: grid; gap: 12px; font-size: 13px; color: #334155; }
.endpoint__item { display: grid; grid-template-columns: 120px 1fr; align-items: center; gap: 12px; background: #ffffff; border: 1px solid #e5e7eb; border-radius: 8px; padding: 10px 14px; }
.badge { font-size: 11px; font-weight: 800; padding: 4px 10px; border-radius: 6px; color: #fff; text-transform: uppercase; letter-spacing: .4px; background: #1e40af; }
.details-container { background: linear-gradient(135deg, #ffffff 0%, #f8fafc 100%); border: 1px solid #e5e7eb; border-radius: 10px; padding: 8px 12px; margin: 20px 0; }
.details-container summary { font-weight: 700; color: #1e40af; cursor: pointer; font-size: 14px; padding: 10px 0 10px 28px; display: flex; align-items: center; position: relative; }
.details-container summary::-webkit-details-marker { display: none; }
.details-container summary::before { content: ''; position: absolute; left: 10px; width: 0; height: 0; border-left: 7px solid #1e40af; border-top: 6px solid transparent; border-bottom: 6px solid transparent; transition: transform .2s ease; }
.details-container[open] summary::before { transform: rotate(90deg); }
.code-block { margin-top: 12px; border-radius: 8px; overflow: hidden; }
.table-container { overflow: auto; border: 0; border-radius: 0; margin: 20px 0; background: transparent; }
.table-container table { width: 100%; border-collapse: collapse; font-size: 13px; }
.table-container th, .table-container td { border-top: 1px solid #e5e7eb; padding: 12px 16px; text-align: left; }
.table-container thead th { background: linear-gradient(135deg, #f8fafc 0%, #ffffff 100%); font-weight: 700; color: #0f172a; font-size: 13px; }
`}
Visão geral
O que é Autorização solicitada ao pagador diretamente no app do banco, sem leitura de QR Code.
Quando usar Contato ativo (telefone, chat, presencial) ou relacionamento já existente com o cliente.
Como funciona Recebedor cria a recorrência com dados da conta do pagador → o pagador recebe uma notificação no app → aprova a recorrência → futuras cobranças podem ser agendadas.
Benefícios Experiência simples e direta; não exige exibição de QR Code.
## Request
ENDPOINT /account/ account_key /outgoing_recurrence/journey_one
MÉTODO POST
### Request Path Params
| Campo | Tipo | Descrição | Caracteres |
|---------------|-------|------------------------------------------------|------------|
| `account_key`*| uuid4 | Chave única de identificação da conta. | 36 |
### Request Body
**Request Body: Criar Recorrência (Jornada 1)**
```json
{
"request_control_key": "98fc62fd-b0a0-4604-9bea-475e91a9dc82",
"periodicity": "monthly",
"minimum_recurrence_amount": 125,
"start_date": "2025-06-10",
"end_date": "2027-06-10",
"pix_message": "Conta de Luz Residencial nº123",
"recurrence_type": "variable_amount",
"debtor_data": {
"name": "Sebastião",
"email": "sebastiao@test.com",
"document_number": "05431134850",
"contract_id": "Contrato de pagamento recorrente",
"address": {
"street": "Av. Brigadeiro Faria Lima",
"state": "SP",
"city": "São Paulo",
"neighborhood": "Jardim Paulistano",
"number": "2391",
"postal_code": "01452905",
"complement": "Complemento"
},
"account_data": {
"account_number": "123456",
"account_digit": "7",
"account_branch": "0001",
"ispb": "31872495"
}
},
"retry_configuration": {
"retry_allowed": true,
"retry_rule": {
"first_retry": {
"day": "1",
},
"second_retry": {
"day": "3",
},
"third_retry": {
"day": "4",
}
}
},
"settlement_date_type": "workdays"
}
```
### Body Params
| Campo | Tipo | Descrição | Caracteres |
|--------------------------------|------------|------------------------------------------------------------------------------------------------------------|------------|
| `request_control_key` * | uuid | Chave única de identificação da requisição utilizada pelo cliente no formato uuid4. | 36 |
| `periodicity` * | enumerator | Tipo da periodicidade associada à recorrência da assinatura. | [Enumeradores periodicity](#enumeradores-periodicity) |
| `minimum_recurrence_amount` | number | Valor mínimo da transação para recorrências de valor variável (em centavos). | - |
| `start_date` * | string | Data de início da recorrência (formato ISO 8601, e.g., "2025-07-01"). | - |
| `end_date` | string | Data de término da recorrência; para tempo indeterminado, enviar como null. | - |
| `pix_message` * | string | Mensagem a ser enviada junto à transação Pix. | 140 |
| `debtor_data` * | Object | Dados do devedor (assinante). | [Objeto debtor_data](#objeto-debtor_data) |
| `retry_configuration` * | Object | Configuração de retentativas para transações não concluídas. | [Objeto retry_configuration](#objeto-retry_configuration) |
| `settlement_date_type` * | enumerator | Tipo de ajuste da data de liquidação | [Enumeradores settlement_date_type](#enumeradores-settlement_date_type) |
| `recurrence_type` * | enumerator | Tipo de recorrência | [Enumeradores recurrence_type](#enumeradores-recurrence_type) |
:::caution Atenção
O campo `minimum_recurrence_amount` é opcional e deve ser informado apenas para recorrência de valor variável. Caso a recorrência seja de valor fixo, deve-se enviar o campo `recurrence_amount`, com o valor da recorrência. Assim como o enumerador `recurrence_type`, que deverá corresponder ao tipo da recorrência (Valor fixo ou variável).
:::
### Enumeradores periodicity
| Enumerador | Descrição |
|--------------|-----------------------|
| `weekly` | Recorrência semanal |
| `monthly` | Recorrência mensal |
| `quarterly` | Recorrência trimestral|
| `semiannual` | Recorrência semestral |
| `annual` | Recorrência anual |
### Enumeradores settlement_date_type
| Enumerador | Descrição |
|--------------|-----------------------|
| `workdays` | Dias úteis |
| `calendar_days` | Dias corridos |
### Enumeradores recurrence_type
| Enumerador | Descrição |
|--------------|-----------------------|
| `fixed_amount` | Recorrência de Valor Fixo |
| `variable_amount` | Recorrência de Valor Variável |
### Objeto debtor_data
| Campo | Tipo | Descrição | Caracteres |
|---------------------|--------|-----------------------|------------|
| `name` * | string | Nome do assinante. | 50 |
| `email` * | string | E-mail do assinante. | 100 |
| `document_number` * | string | CPF ou CNPJ do assinante. | 14 |
| `contract_id` | string | Identificador do contrato do assinante. | 100 |
| `address` * | Object | Endereço do assinante.| [Objeto address](#objeto-address) |
| `account_data` * | Object | Dados bancários do assinante. | [Objeto account_data](#objeto-account_data) |
### Objeto address
| Campo | Tipo | Descrição | Caracteres |
|---------------|--------|-------------------|------------|
| `street` | string | Rua. | - |
| `state` | string | Estado. | - |
| `city` | string | Cidade. | - |
| `neighborhood`| string | Bairro. | - |
| `number` | string | Número. | - |
| `postal_code` | string | CEP. | - |
| `complement` | string | Complemento. | - |
### Objeto account_data
| Campo | Tipo | Descrição | Caracteres |
|-----------------|--------|------------------------------|------------|
| `account_number`| string | Número da conta. | - |
| `account_digit` | string | Dígito da conta. | - |
| `account_branch`| string | Agência da conta. | - |
| `ispb` | string | ISPB da instituição financeira. | - |
### Objeto retry_configuration
| Campo | Tipo | Descrição | Caracteres |
|---------------|---------|-------------------------|------------|
| `retry_allowed`| boolean | Indica se retentativas são permitidas. | - |
| `retry_rule` | Object | Regras de retentativa. | [Objeto retry_rule](#objeto-retry_rule) |
### Objeto retry_rule
| Campo | Tipo | Descrição | Caracteres |
|---------------|--------|-------------------------|------------|
| `first_retry` | Object | Configuração da primeira retentativa. | [Objeto retry_detail](#objeto-retry_detail) |
| `second_retry`| Object | Configuração da segunda retentativa. | [Objeto retry_detail](#objeto-retry_detail) |
| `third_retry` | Object | Configuração da terceira retentativa. | [Objeto retry_detail](#objeto-retry_detail) |
### Objeto retry_detail
| Campo | Tipo | Descrição | Caracteres |
|-------|--------|-------------------------|------------|
| `day` | string | Dia da retentativa. | - |
## Response
STATUS 200
**Response Body**
```json
{
"request_control_key": "a7b9e3c1-f2d4-4a8b-9c7e-123456789abc",
"recurrence_key": "b2c3d4e5-f6g7-4h8i-9j0k-l1m2n3o4p5q6",
"recurrence_status": "pending_confirmation",
"created_at": "2025-06-16T23:52:00.000Z"
}
```
### Response Body
| Campo | Tipo | Descrição | Caracteres |
|-----------------------|------------|---------------------------------------------------------------------------|------------|
| `request_control_key` | uuid | Chave de controle da requisição enviada pelo cliente. | 36 |
| `recurrence_key` | uuid | Chave única de identificação da recorrência de assinatura. | 36 |
| `recurrence_status` | enumerator | Status atual da recorrência. | [Enumeradores recurrence_status](#enumeradores-recurrence_status) |
| `created_at` | string | Data e hora de criação da recorrência (formato ISO 8601). | - |
### Enumeradores recurrence_status
| Enumerador | Descrição |
|----------------------|-----------------------------------|
| `pending_confirmation` | Recorrência pendente de confirmação |
| `active` | Recorrência ativa |
| `cancelled` | Recorrência cancelada |
| `suspended` | Recorrência suspensa |
| `expired` | Recorrência expirada |
STATUS 4XX
Response Error
```json
{
"title": "titulo",
"description": "description in English",
"translation": "descrição em português",
"code": "codigo"
}
```
| Código HTTP | Código QI
`code` | Título
`title` | Descrição (eng)
`description` | Descrição (ptbr)
`translation` |
|-------------|----------------------|-----------------------------------|----------------------------------------------------------------------------|--------------------------------------------------------------------|
| 400 | QIT000002 | Bad Request | Invalid request schema. | Erro no esquema da requisição. |
| 403 | APX000030 | Unauthorized Transaction | User is not authorized to create this recurrence. | Usuário não autorizado a criar esta recorrência. |
| 403 | APX000018 | Endpoint Access Denied | Requester lacks permission to access this endpoint. | Requester não possui permissão para acessar este endpoint. |
| 404 | APX000021 | Subscription Not Found | Subscription \{subscription_key\} not found. | Assinatura \{subscription_key\} não encontrada. |
| 404 | APX000002 | Recurrence Not Found | Recurrence \{recurrence_key\} not found. | Recorrência \{recurrence_key\} não encontrada. |
| 406 | APX000027 | Invalid Transaction Amount | Transaction amount \{minimum_transaction_amount\} is invalid. | Valor da transação \{minimum_transaction_amount\} é inválido. |
| 409 | APX000014 | Request Control Key Conflict | The request_control_key \{request_control_key\} is already in use. | A request_control_key \{request_control_key\} já está em uso. |
---
# Criar uma Recorrência (Jornada 3)
URL: /documentation/baas/pix_automatico/recebedor/journey_three
> Jornada 3 — QR Code + Primeiro Pagamento (ativação imediata da recorrência)
{`
.hero-section {
background: linear-gradient(135deg, #eff6ff 0%, #ffffff 100%);
border: 1px solid #e5e7eb;
border-radius: 16px;
padding: 24px;
margin: 24px 0 32px 0;
}
.hero-grid {
display: grid;
grid-template-columns: repeat(auto-fit, minmax(220px, 1fr));
gap: 16px;
margin-top: 20px;
}
.hero-item {
background: #ffffff;
border: 1px solid #e5e7eb;
border-radius: 10px;
padding: 16px;
transition: all 0.3s ease;
}
.hero-item:hover {
transform: translateY(-2px);
box-shadow: 0 4px 12px rgba(0, 0, 0, 0.08);
border-color: #3b82f6;
}
/* FIX: título em bloco, destaques inline dentro do parágrafo */
.j3-card > strong,
.hero-item > strong {
display: block;
color: #1e40af;
font-size: 14px;
margin-bottom: 6px;
font-weight: 700;
}
.j3-card p strong,
.hero-item p strong {
display: inline;
color: #1e40af;
font-weight: 700;
}
.hero-item p {
margin: 0;
font-size: 13px;
color: #475569;
line-height: 1.5;
}
.flow-section {
margin: 32px 0;
}
.flow-grid {
display: grid;
grid-template-columns: repeat(auto-fit, minmax(240px, 1fr));
gap: 16px;
margin-top: 20px;
}
.flow-step-card {
border-radius: 12px;
padding: 18px;
color: #ffffff;
min-height: 100px;
display: flex;
flex-direction: column;
gap: 8px;
}
.flow-step-card h4 {
margin: 0;
font-size: 15px;
font-weight: 700;
}
.flow-step-card p {
margin: 0;
font-size: 13px;
opacity: 0.95;
line-height: 1.5;
}
.endpoint-section {
margin: 32px 0;
}
.endpoint-card {
background: linear-gradient(135deg, #ffffff 0%, #f8fafc 100%);
border: 2px solid #e5e7eb;
border-radius: 12px;
padding: 24px;
transition: all 0.3s ease;
position: relative;
overflow: hidden;
}
.endpoint-card::before {
content: '';
position: absolute;
top: 0;
left: 0;
width: 4px;
height: 100%;
background: linear-gradient(to bottom, #3b82f6, #1e40af);
transition: width 0.3s ease;
}
.endpoint-card:hover {
transform: translateY(-4px);
box-shadow: 0 10px 25px rgba(0, 0, 0, 0.1);
border-color: #3b82f6;
}
.endpoint-card:hover::before {
width: 6px;
}
.endpoint-list {
display: grid;
gap: 12px;
font-size: 13px;
color: #334155;
}
.endpoint-item {
display: grid;
grid-template-columns: 120px 1fr;
align-items: center;
gap: 12px;
background: #ffffff;
border: 1px solid #e5e7eb;
border-radius: 8px;
padding: 10px 14px;
}
.badge {
font-size: 11px;
font-weight: 800;
padding: 4px 10px;
border-radius: 6px;
color: #fff;
text-transform: uppercase;
letter-spacing: 0.4px;
background: #1e40af;
}
.info-note {
background: linear-gradient(135deg, #eff6ff 0%, #ffffff 100%);
border-left: 4px solid #3b82f6;
padding: 14px 18px;
border-radius: 8px;
font-size: 13px;
color: #1e40af;
margin: 20px 0;
line-height: 1.6;
}
.warn-note {
background: linear-gradient(135deg, #fef3c7 0%, #ffffff 100%);
border-left: 4px solid #f59e0b;
padding: 14px 18px;
border-radius: 8px;
font-size: 13px;
color: #0f172a;
margin: 20px 0;
line-height: 1.6;
}
.table-container {
overflow: auto;
border: 0;
border-radius: 0;
margin: 20px 0;
background: transparent;
}
.table-container table {
width: 100%;
border-collapse: collapse;
font-size: 13px;
}
.table-container th,
.table-container td {
border-top: 1px solid #e5e7eb;
padding: 12px 16px;
text-align: left;
}
.table-container thead th {
background: linear-gradient(135deg, #f8fafc 0%, #ffffff 100%);
font-weight: 700;
color: #0f172a;
font-size: 13px;
}
.table-container tbody tr:hover {
background: #f8fafc;
}
.details-container {
background: linear-gradient(135deg, #ffffff 0%, #f8fafc 100%);
border: 1px solid #e5e7eb;
border-radius: 10px;
padding: 8px 12px;
margin: 20px 0;
}
.details-container summary {
font-weight: 700;
color: #1e40af;
cursor: pointer;
font-size: 14px;
padding: 10px 0 10px 28px;
display: flex;
align-items: center;
position: relative;
}
.details-container summary::-webkit-details-marker { display: none; }
.details-container summary::before {
content: '';
position: absolute;
left: 10px;
width: 0; height: 0;
border-left: 7px solid #1e40af;
border-top: 6px solid transparent;
border-bottom: 6px solid transparent;
transition: transform .2s ease;
}
.details-container[open] summary::before { transform: rotate(90deg); }
.code-block {
margin-top: 12px;
border-radius: 8px;
overflow: hidden;
}
.tips-section {
margin: 32px 0;
}
.tip-card {
background: linear-gradient(135deg, #ffffff 0%, #f0fdf4 100%);
border: 2px solid #d1fae5;
border-radius: 12px;
padding: 18px 20px;
margin-bottom: 16px;
transition: all 0.3s ease;
}
.tip-card:hover {
transform: translateY(-2px);
border-color: #10b981;
box-shadow: 0 6px 20px rgba(16, 185, 129, 0.15);
}
.tip-text {
font-size: 14px;
line-height: 1.7;
color: #475569;
margin: 0;
display: flex;
align-items: flex-start;
gap: 10px;
}
.tip-icon {
color: #10b981;
font-size: 18px;
flex-shrink: 0;
margin-top: 2px;
font-weight: 700;
}
.section-title {
font-size: 20px;
font-weight: 700;
color: #0f172a;
margin: 32px 0 20px 0;
padding-bottom: 12px;
border-bottom: 2px solid #e5e7eb;
}
@media (max-width: 768px) {
.hero-grid,
.flow-grid {
grid-template-columns: 1fr;
}
.endpoint-item {
grid-template-columns: 100px 1fr;
font-size: 12px;
}
.endpoint-item code {
font-size: 11px;
}
}
`}
Visão geral
O que é
Um único QR Code que permite pagar agora e ativar a recorrência no mesmo fluxo.
Quando usar
Casos com cobrança inicial obrigatória (ex.: adesão, matrícula, primeira mensalidade).
Como funciona
O pagador lê o QR → realiza o primeiro pagamento → autoriza a recorrência imediatamente.
Benefícios
Receita imediata + recorrência configurada, reduzindo fricção e inadimplência.
### Fluxo da Jornada 3
1. Ler o QR Code
O usuário escaneia o QR dinâmico gerado para a cobrança inicial.
2. Pagar Agora
O pagamento imediato é processado, registrando a cobrança inicial.
3. Autorizar Recorrência
Na mesma experiência, o usuário confirma a autorização da recorrência.
4. Recorrência Ativa
Próximos ciclos são automatizados; você só precisa conciliar valores quando necessário.
---
## Request
ENDPOINT
/account/ account_key /outgoing_recurrence/journey_three
MÉTODO
POST
### Path Params
Campo Tipo Descrição Caracteres
account_key * uuid4 Chave única de identificação da conta. 36
### Request Body
**Request Body: Criar Recorrência (Jornada 3)**
```json
{
"request_control_key": "98fc62fd-b0a0-4604-9bea-475e91a9dc82",
"periodicity": "monthly",
"minimum_recurrence_amount": 125,
"start_date": "2025-06-10",
"end_date": "2027-06-10",
"pix_message": "Conta de Luz Residencial nº123",
"recurrence_type": "variable_amount",
"debtor_data": {
"name": "Sebastião",
"email": "sebastiao@test.com",
"document_number": "05431134850",
"contract_id": "12345",
"address": {
"street": "Av. Brigadeiro Faria Lima",
"state": "SP",
"city": "São Paulo",
"neighborhood": "Jardim Paulistano",
"number": "2391",
"postal_code": "01452905",
"complement": "Complemento"
}
},
"initial_payment_data": {
"amount": 22.34,
"pix_key": "3d7d6a2b-f72f-44z7-bb20-79a94dff5645",
"qr_code_type": "dynamic_term",
"additional_data": [
{
"key_name": "Juros e Multa",
"value": "Juros 2 ao mes e multa de 1%"
}
],
"fine_amount": 3,
"interest_amount": 2,
"expiration_date": "2023-03-25",
"max_payment_days": 128,
"rebate_amount": 1,
"discounts": [],
"receiver_conciliation_id": "3d7d6a2bf72f44z7bb2079a94dff5645"
},
"retry_configuration": {
"retry_allowed": true,
"retry_rule": {
"first_retry": {
"day": "1"
},
"second_retry": {
"day": "3"
},
"third_retry": {
"day": "4"
}
}
},
"settlement_date_type": "workdays"
}
```
### Body Params
Campo Tipo Descrição Caracteres
request_control_key * uuid Chave única da requisição (uuid4). 36
periodicity * enumerator Periodicidade da recorrência. Enumeradores periodicity
minimum_recurrence_amount float Valor mínimo por transação (recorrências variáveis). -
start_date * string Data de início (ISO 8601). -
end_date string Data de término ou null para indeterminado. -
pix_message * string Mensagem exibida na transação Pix. 140
debtor_data * Object Dados do assinante. Objeto debtor_data
retry_configuration * Object Regras de retentativa. Objeto retry_configuration
settlement_date_type * enumerator Ajuste da data de liquidação. Enumeradores settlement_date_type
recurrence_type * enumerator Tipo da recorrência. Enumeradores recurrence_type
initial_payment_data * Object Dados da cobrança inicial. Objeto initial_payment_data
Atenção: para recorrência de valor variável, informe minimum_recurrence_amount . Para valor fixo, envie recurrence_amount e ajuste o enumerador recurrence_type de acordo.
#### Enumeradores periodicity
Enumerador Descrição
weekly Recorrência semanal
monthly Recorrência mensal
quarterly Recorrência trimestral
semiannual Recorrência semestral
annual Recorrência anual
#### Enumeradores settlement_date_type
Enumerador Descrição
workdays Dias úteis
calendar_days Dias corridos
#### Enumeradores recurrence_type
Enumerador Descrição
fixed_amount Recorrência de Valor Fixo
variable_amount Recorrência de Valor Variável
#### Objeto debtor_data
Campo Tipo Descrição Caracteres
name * string Nome do assinante. 50
email * string E-mail do assinante. 100
document_number * string CPF/CNPJ do assinante. 14
contract_id string Identificador do contrato. 100
address * Object Endereço do assinante. Objeto address
#### Objeto address
Campo Tipo Descrição
street string Rua
state string Estado
city string Cidade
neighborhood string Bairro
number string Número
postal_code string CEP
complement string Complemento
#### Objeto retry_configuration
Campo Tipo Descrição
retry_allowed boolean Habilita retentativas
retry_rule Object Regras de retentativa
#### Objeto retry_rule
Campo Tipo Descrição
first_retry Object Primeira retentativa
second_retry Object Segunda retentativa
third_retry Object Terceira retentativa
#### Objeto retry_detail
Campo Tipo Descrição
day string Dia da retentativa
#### Objeto initial_payment_data
Campo Tipo Descrição Caracteres
amount * number Valor da cobrança inicial (R$). -
pix_key * string Chave Pix de destino. 77
qr_code_type * enumerator Tipo de QR Code da cobrança inicial. Enumeradores qr_code_type
additional_data * array Lista de dados adicionais (ex.: juros/multa). Objetos additional_data
fine_amount number Multa por atraso. -
interest_amount number Juros por atraso. -
expiration_date * string Data de expiração (ISO 8601). -
max_payment_days integer Dias máximos após expiração para aceitar o pagamento. -
rebate_amount number Desconto por antecipação. -
discounts array Descontos adicionais. -
receiver_conciliation_id string Identificador para conciliação pelo recebedor. 32
#### Enumeradores qr_code_type
Valor Descrição
dynamic_instant QR dinâmico para pagamento imediato
dynamic_term QR dinâmico com prazo (vencimento futuro)
#### Objetos additional_data
Campo Tipo Descrição
key_name string Rótulo da informação (ex.: Juros e Multa)
value string Valor/descrição
---
## Response
STATUS
200
**Response Body (exemplo)**
```json
{
"request_control_key": "98fc62fd-b0a0-4604-9bea-475e91a9dc82",
"outgoing_recurrence_key": "8cb70dea-9fb0-4a68-9572-99a72849c8d6",
"outgoing_recurrence_status": "pending_confirmation",
"qr_code_data": {
"qr_code_url": "url",
"qr_code_key": "98fc62fd-b0a0-4604-9bea-475e91a9dc85",
"qr_code_image": "imageb64"
},
"initial_payment_data": {
"receiver_conciliation_id": "6f270b64-1b7a-4269-91f8-3f9cf30ba0bb"
},
"created_at": "2021-10-22T20:30:23.459Z"
}
```
### Campos do Response
Campo Tipo Descrição Caracteres
request_control_key uuid Chave de controle enviada pelo cliente 36
recurrence_key uuid Identificação da recorrência de assinatura 36
recurrence_status enumerator Status da recorrência Enumeradores recurrence_status
qr_code_data Object Dados do QR gerado para o primeiro pagamento Objeto qr_code_data
initial_payment_data Object Informações do pagamento inicial Objeto initial_payment_data
created_at string Data/hora de criação (ISO 8601) -
#### Objeto qr_code_data
Campo Tipo Descrição Caracteres
qr_code_url string URL do copia e cola -
qr_code_key uuid Identificador do QR 36
qr_code_image string Imagem (Base64) -
#### Objeto initial_payment_data
Campo Tipo Descrição Caracteres
receiver_conciliation_id string ID de conciliação do pagamento 32
#### Enumeradores recurrence_status
Enumerador Descrição
pending_confirmation Pendente de confirmação
active Ativa
cancelled Cancelada
suspended Suspensa
expired Expirada
---
## Dicas e Boas Práticas
✓
Conciliação em recorrência variável: para variable_amount , concilie o valor de 10 a 3 dias antes da data de cobrança.
✓
Mensagens Pix: utilize pix_message com até 140 caracteres para explicar claramente a cobrança inicial.
⚠
Segurança: valide documentos/contas e trate erros de rede e de integrações externas com retentativas idempotentes.
---
# Criar uma Recorrência (Jornada 2)
URL: /documentation/baas/pix_automatico/recebedor/journey_two
> Jornada 2 — QR Code com dados apenas da recorrência
{`
.hero-section { background: linear-gradient(135deg, #eff6ff 0%, #ffffff 100%); border: 1px solid #e5e7eb; border-radius: 16px; padding: 24px; margin: 24px 0 32px 0; }
.hero-grid { display: grid; grid-template-columns: repeat(auto-fit, minmax(220px, 1fr)); gap: 16px; margin-top: 20px; }
.hero-item { background: #ffffff; border: 1px solid #e5e7eb; border-radius: 10px; padding: 16px; }
.hero-item > strong { display: block; color: #1e40af; font-size: 14px; margin-bottom: 6px; font-weight: 700; }
.hero-item p { margin: 0; font-size: 13px; color: #475569; line-height: 1.5; }
.endpoint-card { background: linear-gradient(135deg, #ffffff 0%, #f8fafc 100%); border: 2px solid #e5e7eb; border-radius: 12px; padding: 24px; position: relative; overflow: hidden; }
.endpoint-card::before { content: ''; position: absolute; top: 0; left: 0; width: 4px; height: 100%; background: linear-gradient(to bottom, #3b82f6, #1e40af); }
.endpoint-list { display: grid; gap: 12px; font-size: 13px; color: #334155; }
.endpoint__item { display: grid; grid-template-columns: 120px 1fr; align-items: center; gap: 12px; background: #ffffff; border: 1px solid #e5e7eb; border-radius: 8px; padding: 10px 14px; }
.badge { font-size: 11px; font-weight: 800; padding: 4px 10px; border-radius: 6px; color: #fff; text-transform: uppercase; letter-spacing: .4px; background: #1e40af; }
.details-container { background: linear-gradient(135deg, #ffffff 0%, #f8fafc 100%); border: 1px solid #e5e7eb; border-radius: 10px; padding: 8px 12px; margin: 20px 0; }
.details-container summary { font-weight: 700; color: #1e40af; cursor: pointer; font-size: 14px; padding: 10px 0 10px 28px; display: flex; align-items: center; position: relative; }
.details-container summary::-webkit-details-marker { display: none; }
.details-container summary::before { content: ''; position: absolute; left: 10px; width: 0; height: 0; border-left: 7px solid #1e40af; border-top: 6px solid transparent; border-bottom: 6px solid transparent; transition: transform .2s ease; }
.details-container[open] summary::before { transform: rotate(90deg); }
.code-block { margin-top: 12px; border-radius: 8px; overflow: hidden; }
.table-container { overflow: auto; border: 0; border-radius: 0; margin: 20px 0; background: transparent; }
.table-container table { width: 100%; border-collapse: collapse; font-size: 13px; }
.table-container th, .table-container td { border-top: 1px solid #e5e7eb; padding: 12px 16px; text-align: left; }
.table-container thead th { background: linear-gradient(135deg, #f8fafc 0%, #ffffff 100%); font-weight: 700; color: #0f172a; font-size: 13px; }
`}
Visão geral
O que é QR Code que apresenta apenas os dados da recorrência para o pagador autorizar, sem cobrança imediata.
Quando usar Onboarding sem cobrança inicial; uso em pontos de venda, balcões, telas ou materiais impressos.
Como funciona Pagador lê o QR → visualiza os dados da recorrência no app → autoriza → futuras cobranças poderão ser agendadas.
Benefícios Habilitação ágil via QR; permite captação em massa de clientes com baixo atrito e o QR pode ser reutilizado para novas recorrências.
## Request
{`
.endpoint-card { background: linear-gradient(135deg, #ffffff 0%, #f8fafc 100%); border: 2px solid #e5e7eb; border-radius: 12px; padding: 24px; position: relative; overflow: hidden; }
.endpoint-card::before { content: ''; position: absolute; top: 0; left: 0; width: 4px; height: 100%; background: linear-gradient(to bottom, #3b82f6, #1e40af); }
.endpoint-list { display: grid; gap: 12px; font-size: 13px; color: #334155; }
.endpoint__item { display: grid; grid-template-columns: 120px 1fr; align-items: center; gap: 12px; background: #ffffff; border: 1px solid #e5e7eb; border-radius: 8px; padding: 10px 14px; }
.badge { font-size: 11px; font-weight: 800; padding: 4px 10px; border-radius: 6px; color: #fff; text-transform: uppercase; letter-spacing: .4px; background: #1e40af; }
.details-container { background: linear-gradient(135deg, #ffffff 0%, #f8fafc 100%); border: 1px solid #e5e7eb; border-radius: 10px; padding: 8px 12px; margin: 20px 0; }
.details-container summary { font-weight: 700; color: #1e40af; cursor: pointer; font-size: 14px; padding: 10px 0 10px 28px; display: flex; align-items: center; position: relative; }
.details-container summary::-webkit-details-marker { display: none; }
.details-container summary::before { content: ''; position: absolute; left: 10px; width: 0; height: 0; border-left: 7px solid #1e40af; border-top: 6px solid transparent; border-bottom: 6px solid transparent; transition: transform .2s ease; }
.details-container[open] summary::before { transform: rotate(90deg); }
.code-block { margin-top: 12px; border-radius: 8px; overflow: hidden; }
`}
ENDPOINT /account/ account_key /outgoing_recurrence/journey_two
MÉTODO POST
### Request Path Params
| Campo | Tipo | Descrição | Caracteres |
|---------------|-------|------------------------------------------------|------------|
| `account_key`*| uuid4 | Chave única de identificação da conta. | 36 |
### Request Body
**Request Body: Criar Recorrência (Jornada 2)**
```json
{
"request_control_key": "98fc62fd-b0a0-4604-9bea-475e91a9dc82",
"periodicity": "monthly",
"minimum_recurrence_amount": 125,
"start_date": "2025-06-10",
"end_date": "2027-06-10",
"pix_message": "Conta de Luz Residencial nº123",
"recurrence_type": "variable_amount",
"debtor_data": {
"name": "Sebastião",
"email": "sebastiao@test.com",
"document_number": "05431134850",
"contract_id": "124587624",
"address": {
"street": "Av. Brigadeiro Faria Lima",
"state": "SP",
"city": "São Paulo",
"neighborhood": "Jardim Paulistano",
"number": "2391",
"postal_code": "01452905",
"complement": "Complemento"
}
},
"retry_configuration": {
"retry_allowed": true,
"retry_rule": {
"first_retry": {
"day": "1"
},
"second_retry": {
"day": "3"
},
"third_retry": {
"day": "4"
}
}
},
"settlement_date_type": "workdays"
}
```
### Body Params
| Campo | Tipo | Descrição | Caracteres |
|--------------------------------|------------|------------------------------------------------------------------------------------------------------------|------------|
| `request_control_key` * | uuid | Chave única de identificação da requisição utilizada pelo cliente no formato uuid4. | 36 |
| `periodicity` * | enumerator | Tipo da periodicidade associada à recorrência da assinatura. | [Enumeradores periodicity](#enumeradores-periodicity) |
| `minimum_recurrence_amount` | number | Valor mínimo da transação para recorrências de valor variável (em centavos). | - |
| `start_date` * | string | Data de início da recorrência (formato ISO 8601, e.g., "2025-07-01"). | - |
| `end_date` | string | Data de término da recorrência; para tempo indeterminado, enviar como null. | - |
| `pix_message` * | string | Mensagem a ser enviada junto à transação Pix. | 140 |
| `debtor_data` * | Object | Dados do devedor (assinante). | [Objeto debtor_data](#objeto-debtor_data) |
| `retry_configuration` * | Object | Configuração de retentativas para transações não concluídas. | [Objeto retry_configuration](#objeto-retry_configuration) |
| `settlement_date_type` * | enumerator | Tipo de ajuste da data de liquidação | [Enumeradores settlement_date_type](#enumeradores-settlement_date_type) |
| `recurrence_type` * | enumerator | Tipo de recorrência | [Enumeradores recurrence_type](#enumeradores-recurrence_type) |
:::caution Atenção
O campo `minimum_recurrence_amount` é opcional e deve ser informado apenas para recorrência de valor variável. Caso a recorrência seja de valor fixo, deve-se enviar o campo `recurrence_amount`, com o valor da recorrência. Assim como o enumerador `recurrence_type`, que deverá corresponder ao tipo da recorrência (Valor fixo ou variável).
:::
### Enumeradores periodicity
| Enumerador | Descrição |
|--------------|-----------------------|
| `weekly` | Recorrência semanal |
| `monthly` | Recorrência mensal |
| `quarterly` | Recorrência trimestral|
| `semiannual` | Recorrência semestral |
| `annual` | Recorrência anual |
### Enumeradores settlement_date_type
| Enumerador | Descrição |
|--------------|-----------------------|
| `workdays` | Dias úteis |
| `calendar_days` | Dias corridos |
### Enumeradores recurrence_type
| Enumerador | Descrição |
|--------------|-----------------------|
| `fixed_amount` | Recorrência de Valor Fixo |
| `variable_amount` | Recorrência de Valor Variável |
### Objeto debtor_data
| Campo | Tipo | Descrição | Caracteres |
|---------------------|--------|-----------------------|------------|
| `name` * | string | Nome do assinante. | 50 |
| `email` * | string | E-mail do assinante. | 100 |
| `document_number` * | string | CPF ou CNPJ do assinante. | 14 |
| `contract_id` | string | Identificador do contrato do assinante. | 100 |
| `address` * | Object | Endereço do assinante.| [Objeto address](#objeto-address) |
### Objeto address
| Campo | Tipo | Descrição | Caracteres |
|---------------|--------|-------------------|------------|
| `street` | string | Rua. | - |
| `state` | string | Estado. | - |
| `city` | string | Cidade. | - |
| `neighborhood`| string | Bairro. | - |
| `number` | string | Número. | - |
| `postal_code` | string | CEP. | - |
| `complement` | string | Complemento. | - |
### Objeto retry_configuration
| Campo | Tipo | Descrição | Caracteres |
|---------------|---------|-------------------------|------------|
| `retry_allowed`| boolean | Indica se retentativas são permitidas. | - |
| `retry_rule` | Object | Regras de retentativa. | [Objeto retry_rule](#objeto-retry_rule) |
### Objeto retry_rule
| Campo | Tipo | Descrição | Caracteres |
|---------------|--------|-------------------------|------------|
| `first_retry` | Object | Configuração da primeira retentativa. | [Objeto retry_detail](#objeto-retry_detail) |
| `second_retry`| Object | Configuração da segunda retentativa. | [Objeto retry_detail](#objeto-retry_detail) |
| `third_retry` | Object | Configuração da terceira retentativa. | [Objeto retry_detail](#objeto-retry_detail) |
### Objeto retry_detail
| Campo | Tipo | Descrição | Caracteres |
|-------|--------|-------------------------|------------|
| `day` | string | Dia da retentativa. | - |
## Response
STATUS 200
**Response Body**
```json
{
"request_control_key": "98fc62fd-b0a0-4604-9bea-475e91a9dc82",
"outgoing_recurrence_key": "8cb70dea-9fb0-4a68-9572-99a72849c8d6",
"outgoing_recurrence_status": "pending_confirmation",
"qr_code_data": {
"qr_code_url": "url",
"qr_code_key": "98fc62fd-b0a0-4604-9bea-475e91a9dc85",
"qr_code_image": "imageb64"
},
"created_at": "2021-10-22T20:30:23.459Z"
}
```
### Response Body
| Campo | Tipo | Descrição | Caracteres |
|-----------------------|------------|---------------------------------------------------------------------------|------------|
| `request_control_key` | uuid | Chave de controle da requisição enviada pelo cliente. | 36 |
| `recurrence_key` | uuid | Chave única de identificação da recorrência de assinatura. | 36 |
| `recurrence_status` | enumerator | Status atual da recorrência. | [Enumeradores recurrence_status](#enumeradores-recurrence_status) |
| `qr_code_data` | enumerator | Status atual da recorrência. | [Objeto qr_code_data](#enumeradores-qr_code_data) |
| `created_at` | string | Data e hora de criação da recorrência (formato ISO 8601). | - |
### Objeto qr_code_data
| Campo | Tipo | Descrição | Caracteres |
|-------|--------|-------------------------|------------|
| `qr_code_url` | string | URL do copia e cola do qr_code | - |
| `qr_code_key`| uuuid | Chave Única de identificação do qr_code. | 36 |
| `qr_code_image`| string | Base64 da imagem do qr_code | - |
### Enumeradores recurrence_status
| Enumerador | Descrição |
|----------------------|-----------------------------------|
| `pending_confirmation` | Recorrência pendente de confirmação |
| `active` | Recorrência ativa |
| `cancelled` | Recorrência cancelada |
| `suspended` | Recorrência suspensa |
| `expired` | Recorrência expirada |
STATUS 4XX
**Response Error**
```json
{
"title": "titulo",
"description": "description in English",
"translation": "descrição em português",
"code": "codigo"
}
```
| Código HTTP | Código QI
`code` | Título
`title` | Descrição (eng)
`description` | Descrição (ptbr)
`translation` |
|-------------|----------------------|-----------------------------------|----------------------------------------------------------------------------|--------------------------------------------------------------------|
| 400 | QIT000002 | Bad Request | Invalid request schema. | Erro no esquema da requisição. |
| 403 | APX000030 | Unauthorized Transaction | User is not authorized to create this recurrence. | Usuário não autorizado a criar esta recorrência. |
| 403 | APX000018 | Endpoint Access Denied | Requester lacks permission to access this endpoint. | Requester não possui permissão para acessar este endpoint. |
| 404 | APX000021 | Subscription Not Found | Subscription \{subscription_key\} not found. | Assinatura \{subscription_key\} não encontrada. |
| 404 | APX000002 | Recurrence Not Found | Recurrence \{recurrence_key\} not found. | Recorrência \{recurrence_key\} não encontrada. |
| 406 | APX000027 | Invalid Transaction Amount | Transaction amount \{minimum_transaction_amount\} is invalid. | Valor da transação \{minimum_transaction_amount\} é inválido. |
| 409 | APX000014 | Request Control Key Conflict | The request_control_key \{request_control_key\} is already in use. | A request_control_key \{request_control_key\} já está em uso. |
---
# Listagem de Recorrências de um Requester
URL: /documentation/baas/pix_automatico/recebedor/listar_recorrencias_de_um_requester
## Request
ENDPOINT /outgoing_recurrences
MÉTODO GET
### Query Params
| Campo | Tipo | Descrição | Caracteres |
|-----------------------------|-------------|------------------------------------------------------------------------|------------|
| `outgoing_recurrence_status`| enumerador | Filtra recorrências pelo status (`approved`, `pending`, `rejected`, `pending_confirmation`) | 30 |
| `page` | integer | Número da página a ser retornada (paginação). | - |
| `page_size` | integer | Número de itens por página (paginação). | - |
---
## Response
STATUS 200
Response Body
```json
{
"outgoing_recurrences": [
{
"request_control_key": "98fc62fd-b0a0-4604-9bea-475e91a9dc82",
"outgoing_recurrence_key": "8cb70dea-9fb0-4a68-9572-99a72849c8d6",
"outgoing_recurrence_status": "approved",
"periodicity": "monthly",
"journey_type": "journey_four",
"start_date": "2025-06-10",
"end_date": "2027-06-10",
"account_key": "uuuid",
"outgoing_recurrence_data": {
"minimum_recurrence_amount": 123.45,
"recurrence_amount": null,
"retry_configuration": {
"retry_allowed": true,
"retry_rule": {
"first_retry": {
"day": "1",
"time": "14:00"
},
"second_retry": {
"day": "3",
"time": "12:00"
},
"third_retry": {
"day": "4",
"time": "15:32"
}
}
},
"debtor_data": {
"name": "Sebastião",
"email": "sebastiao@test.com",
"document_number": "05431134850",
"address": {
"city": "São Paulo",
"postal_code": "123456-789",
"uf": "SP",
"street": "Av Paulista 123"
},
"account_data": {
"account_number": "123456",
"account_digit": "7",
"account_branch": "0001",
"ispb": "31872495"
}
},
"qr_code_data": {
"qr_code_key": "0f45cc3d-9bd1-4d68-a865-4cf477b5da45",
"qr_code_url": "urlqrcode.url",
"qr_code_image": "image_base64"
},
"initial_payment_data": {
"amount": 22.34,
"pix_key": "3d7d6a2b-f72f-44z7-bb20-79a94dff5645",
"qr_code_type": "dynamic_term",
"additional_data": [
{
"key_name": "Juros e Multa",
"value": "Juros 2 ao mes e multa de 1%"
}
],
"fine_amount": 3,
"interest_amount": 2,
"expiration_date": "2023-03-25",
"max_payment_days": 128,
"rebate_amount": 1,
"discounts": [],
"receiver_conciliation_id":"3d7d6a2bf72f44z7bb2079a94dff5645",
"transaction_data":{
"transaction_key":"4d7d6a2b-f72f-44z7-bb20-79a94dff5645",
"pix_transfer_key":"5d7d6a2b-f72f-44z7-bb20-79a94dff5645",
"end_to_end_id":"E32402502202303141907qlBAF1evdJ2"
}
},
"pix_message": "Conta de Luz Residencial nº123",
"settlement_date_type": "calendar_days"
}
}
],
"pagination": {
"page": 1,
"page_size": 25,
"number_of_pages": 4
}
}
```
### Response Body Params
| Campo | Tipo | Descrição | Caracteres |
|------------------------|--------|-----------------------------------------------------------------------------------------|------------|
| `outgoing_recurrences` | array | Lista de objetos de recorrências automáticas. | [Array outgoing_recurrences](#array-outgoing_recurrences) |
| `pagination` | object | Objeto de paginação contendo informações sobre as páginas dos resultados. | [Objeto pagination](#objeto-pagination) |
---
### Array outgoing_recurrences
| Campo | Tipo | Descrição | Caracteres |
|------------------------------|------------|-----------------------------------------------------------------------------------------|------------|
| `request_control_key` | uuidv4 | Chave única para controle da requisição. | 36 |
| `outgoing_recurrence_key` | uuidv4 | Identificador da recorrência automática. | 36 |
| `account_key` | uuidv4 | Chave única de identificação da conta | 36 |
| `outgoing_recurrence_status` | string | Status atual da recorrência (`approved`, `pending`, `rejected`, etc.). | 30 |
| `periodicity` | enumerator | Periodicidade da recorrência. | [Enumeradores periodicity](#enumeradores-periodicity) |
| `journey_type` | enumerator | Jornada da recorrência automática. | [Enumeradores journey_type](#enumeradores-journey_type) |
| `start_date` | string | Data de início da recorrência (formato ISO 8601, e.g., `2025-06-10`). | 10 |
| `end_date` | string | Data de término da recorrência (formato ISO 8601) ou null, se indeterminado. | 10 ou null |
| `outgoing_recurrence_data` | object | Objeto agrupando parâmetros da assinatura e dados complementares. | [Objeto outgoing_recurrence_data](#objeto-outgoing_recurrence_data) |
---
### Objeto outgoing_recurrence_data
| Campo | Tipo | Descrição | Caracteres |
|-----------------------------|----------|----------------------------------------------------------------|------------|
| `minimum_recurrence_amount` | number | Valor mínimo esperado nas recorrências de valor variável | - |
| `recurrence_amount` | number | Valor da recorrência (para valor fixo; null se variável) | - |
| `retry_configuration` | object | Configuração de tentativas para recorrências não concluídas | [Objeto retry_configuration](#objeto-retry_configuration) |
| `debtor_data` | object | Dados do devedor (assinante) | [Objeto debtor_data](#objeto-debtor_data) |
| `qr_code_data` | object | Dados de QR Code gerado para o pagamento (se houver) | [Objeto qr_code_data](#objeto-qr_code_data) |
| `initial_payment_data` | object | Dados da cobrança inicial | [Objeto initial_payment_data](#objeto-initial_payment_data) |
| `pix_message` | string | Mensagem enviada junto à transação Pix | 140 |
| `settlement_date_type` | enumerator| Tipo do ajuste da data de liquidação | [Enumeradores settlement_date_type](#enumeradores-settlement_date_type) |
---
### Objeto retry_configuration
| Campo | Tipo | Descrição | Caracteres |
|-----------------|---------|---------------------------------------------|------------|
| `retry_allowed` | boolean | Indica se retentativas estão habilitadas | - |
| `retry_rule` | object | Regras detalhadas das retentativas | [Objeto retry_rule](#objeto-retry_rule) |
---
### Objeto retry_rule
| Campo | Tipo | Descrição | Caracteres |
|---------------|--------|-----------------------------------|------------|
| `first_retry` | object | Configuração para 1ª retentativa | [Objeto retry_detail](#objeto-retry_detail) |
| `second_retry`| object | Configuração para 2ª retentativa | [Objeto retry_detail](#objeto-retry_detail) |
| `third_retry` | object | Configuração para 3ª retentativa | [Objeto retry_detail](#objeto-retry_detail) |
---
### Objeto retry_detail
| Campo | Tipo | Descrição | Caracteres |
|-------|--------|-------------------------|------------|
| `day` | string | Dia da retentativa. | - |
| `time`| string | Horário da retentativa. | - |
---
### Objeto debtor_data
| Campo | Tipo | Descrição | Caracteres |
|-------------------|--------|------------------------|------------|
| `name` | string | Nome do assinante. | 50 |
| `email` | string | E-mail do assinante. | 100 |
| `document_number` | string | CPF ou CNPJ. | 14 |
| `address` | object | Endereço do assinante. | [Objeto address](#objeto-address) |
| `account_data` | object | Dados bancários. | [Objeto account_data](#objeto-account_data) |
---
### Objeto address
| Campo | Tipo | Descrição | Caracteres |
|---------------|--------|-------------------|------------|
| `city` | string | Cidade. | - |
| `postal_code` | string | CEP. | - |
| `uf` | string | Estado (sigla). | - |
| `street` | string | Logradouro. | - |
---
### Objeto account_data
| Campo | Tipo | Descrição | Caracteres |
|-----------------|--------|------------------------------|------------|
| `account_number`| string | Número da conta | - |
| `account_digit` | string | Dígito da conta | - |
| `account_branch`| string | Agência | - |
| `ispb` | string | ISPB da instituição financeira| - |
---
### Objeto qr_code_data
| Campo | Tipo | Descrição | Caracteres |
|------------------|--------|---------------------------------------------|------------|
| `qr_code_key` | string | Identificador do QR Code gerado | - |
| `qr_code_url` | string | URL para visualização do QR Code | - |
| `qr_code_image` | string | Imagem do QR Code (em Base64) | - |
---
### Objeto initial_payment_data
| Campo | Tipo | Descrição | Caracteres |
|---------------------------|----------|--------------------------------------------------------------------------|------------|
| `amount` | number | Valor principal da cobrança inicial em reais (R$) | - |
| `pix_key` | string | Chave Pix de destino para o pagamento inicial | 77 |
| `qr_code_type` | enum | Tipo de QR Code para cobrança inicial. | [Enumeradores qr_code_type](#enumeradores-qr_code_type) |
| `additional_data` | array | Lista de informações adicionais relacionadas à cobrança | [Array de objects additional_data](#array-additional_data) |
| `fine_amount` | number | Valor da multa, caso ocorra atraso no pagamento | - |
| `interest_amount` | number | Valor dos juros, caso ocorra atraso no pagamento | - |
| `expiration_date` | string | Data de expiração da cobrança inicial (formato ISO 8601) | 10 |
| `max_payment_days` | integer | Número máximo de dias de aceite após expiração | - |
| `rebate_amount` | number | Valor do desconto para pagamento antecipado | - |
| `discounts` | array | Lista de descontos adicionais | - |
| `receiver_conciliation_id`| string | Identificador de conciliação do pagamento pelo recebedor | 35 |
| `transaction_data` | object | Detalhes da transação relacionada à cobrança inicial | [Objeto transaction_data](#objeto-transaction_data) |
---
### Array additional_data
| Campo | Tipo | Descrição | Caracteres |
|--------------|---------|-----------------------------------------------------------|------------|
| `key_name` | string | Nome da informação adicional (ex: "Juros e Multa") | 140 |
| `value` | string | Valor ou descrição da informação adicional | 140 |
---
### Objeto transaction_data
| Campo | Tipo | Descrição | Caracteres |
|---------------------|--------|----------------------------------------|------------|
| `transaction_key` | string | Chave única da transação | 36 |
| `pix_transfer_key` | string | Identificador da transferência Pix | 36 |
| `end_to_end_id` | string | Identificador end-to-end do Pix | 32 |
---
### Objeto pagination
| Campo | Tipo | Descrição | Caracteres |
|------------------|---------|-------------------------------------|------------|
| `page` | integer | Número da página retornada. | - |
| `page_size` | integer | Quantidade de itens por página. | - |
| `number_of_pages`| integer | Total de páginas disponíveis. | - |
---
### Enumeradores periodicity
| Enumerador | Descrição |
|--------------|-----------------------|
| `weekly` | Recorrência semanal |
| `monthly` | Recorrência mensal |
| `quarterly` | Recorrência trimestral|
| `semiannual` | Recorrência semestral |
| `annual` | Recorrência anual |
---
### Enumeradores journey_type
| Enumerador | Descrição |
|-----------------|----------------------------------------------|
| `journey_one` | Notificação direta no aplicativo bancário |
| `journey_two` | Experiência QR Code para cobrança recorrente |
| `journey_three` | Pagamento instantâneo + recorrência QR Code |
| `journey_four` | Opt-in recorrente a partir de operação Pix |
---
### Enumeradores settlement_date_type
| Enumerador | Descrição |
|-----------------|------------------|
| `workdays` | Dias úteis |
| `calendar_days` | Dias corridos |
---
### Enumeradores qr_code_type
| Enumerador | Descrição |
|-------------------|---------------------------------------------------|
| `dynamic_instant` | QR Code dinâmico para pagamento instantâneo |
| `dynamic_term` | QR Code dinâmico para pagamento com vencimento futuro |
STATUS 4XX
Response Error
```json
{
"title": "titulo",
"description": "description in English",
"translation": "descrição em português",
"code": "codigo"
}
```
| Código HTTP | Código QI
`code` | Título
`title` | Descrição (eng)
`description` | Descrição (ptbr)
`translation` |
|-------------|----------------------|-----------------------------------|----------------------------------------------------------------------------|--------------------------------------------------------------------|
| 400 | QIT000002 | Bad Request | Invalid request schema. | Erro no esquema da requisição. |
| 404 | APX000002 | Recurrence Not Found | Recurrence \{recurrence_key\} not found. | Recorrência \{recurrence_key\} não encontrada. |
---
# Listagem de Recorrências de uma Conta
URL: /documentation/baas/pix_automatico/recebedor/listar_recorrencias_de_uma_conta
## Request
ENDPOINT /account/ ACCOUNT_KEY /outgoing_recurrences
MÉTODO GET
### Query Params
| Campo | Tipo | Descrição | Caracteres |
|-----------------------------|-------------|------------------------------------------------------------------------|------------|
| `outgoing_recurrence_status`| enumerador | Filtra recorrências pelo status (`approved`, `pending`, `rejected`, `pending_confirmation`) | 30 |
| `page` | integer | Número da página a ser retornada (paginação). | - |
| `page_size` | integer | Número de itens por página (paginação). | - |
---
## Response
STATUS 200
Response Body
```json
{
"outgoing_recurrences": [
{
"request_control_key": "98fc62fd-b0a0-4604-9bea-475e91a9dc82",
"outgoing_recurrence_key": "8cb70dea-9fb0-4a68-9572-99a72849c8d6",
"outgoing_recurrence_status": "approved",
"periodicity": "monthly",
"journey_type": "journey_four",
"start_date": "2025-06-10",
"end_date": "2027-06-10",
"outgoing_recurrence_data": {
"minimum_recurrence_amount": 123.45,
"recurrence_amount": null,
"retry_configuration": {
"retry_allowed": true,
"retry_rule": {
"first_retry": {
"day": "1",
"time": "14:00"
},
"second_retry": {
"day": "3",
"time": "12:00"
},
"third_retry": {
"day": "4",
"time": "15:32"
}
}
},
"debtor_data": {
"name": "Sebastião",
"email": "sebastiao@test.com",
"document_number": "05431134850",
"address": {
"city": "São Paulo",
"postal_code": "123456-789",
"uf": "SP",
"street": "Av Paulista 123"
},
"account_data": {
"account_number": "123456",
"account_digit": "7",
"account_branch": "0001",
"ispb": "31872495"
}
},
"qr_code_data": {
"qr_code_key": "0f45cc3d-9bd1-4d68-a865-4cf477b5da45",
"qr_code_url": "urlqrcode.url",
"qr_code_image": "image_base64"
},
"initial_payment_data": {
"amount": 22.34,
"pix_key": "3d7d6a2b-f72f-44z7-bb20-79a94dff5645",
"qr_code_type": "dynamic_term",
"additional_data": [
{
"key_name": "Juros e Multa",
"value": "Juros 2 ao mes e multa de 1%"
}
],
"fine_amount": 3,
"interest_amount": 2,
"expiration_date": "2023-03-25",
"max_payment_days": 128,
"rebate_amount": 1,
"discounts": [],
"receiver_conciliation_id":"3d7d6a2bf72f44z7bb2079a94dff5645",
"transaction_data":{
"transaction_key":"4d7d6a2b-f72f-44z7-bb20-79a94dff5645",
"pix_transfer_key":"5d7d6a2b-f72f-44z7-bb20-79a94dff5645",
"end_to_end_id":"E32402502202303141907qlBAF1evdJ2"
}
},
"pix_message": "Conta de Luz Residencial nº123",
"settlement_date_type": "calendar_days"
}
}
],
"pagination": {
"page": 1,
"page_size": 25,
"number_of_pages": 4
}
}
```
### Response Body Params
| Campo | Tipo | Descrição | Caracteres |
|------------------------|--------|-----------------------------------------------------------------------------------------|------------|
| `outgoing_recurrences` | array | Lista de objetos de recorrências automáticas. | [Array outgoing_recurrences](#array-outgoing_recurrences) |
| `pagination` | object | Objeto de paginação contendo informações sobre as páginas dos resultados. | [Objeto pagination](#objeto-pagination) |
---
### Array outgoing_recurrences
| Campo | Tipo | Descrição | Caracteres |
|------------------------------|------------|-----------------------------------------------------------------------------------------|------------|
| `request_control_key` | uuidv4 | Chave única para controle da requisição. | 36 |
| `outgoing_recurrence_key` | uuidv4 | Identificador da recorrência automática. | 36 |
| `outgoing_recurrence_status` | string | Status atual da recorrência (`approved`, `pending`, `rejected`, etc.). | 30 |
| `periodicity` | enumerator | Periodicidade da recorrência. | [Enumeradores periodicity](#enumeradores-periodicity) |
| `journey_type` | enumerator | Jornada da recorrência automática. | [Enumeradores journey_type](#enumeradores-journey_type) |
| `start_date` | string | Data de início da recorrência (formato ISO 8601, e.g., `2025-06-10`). | 10 |
| `end_date` | string | Data de término da recorrência (formato ISO 8601) ou null, se indeterminado. | 10 ou null |
| `outgoing_recurrence_data` | object | Objeto agrupando parâmetros da assinatura e dados complementares. | [Objeto outgoing_recurrence_data](#objeto-outgoing_recurrence_data) |
---
### Objeto outgoing_recurrence_data
| Campo | Tipo | Descrição | Caracteres |
|-----------------------------|----------|----------------------------------------------------------------|------------|
| `minimum_recurrence_amount` | number | Valor mínimo esperado nas recorrências de valor variável | - |
| `recurrence_amount` | number | Valor da recorrência (para valor fixo; null se variável) | - |
| `retry_configuration` | object | Configuração de tentativas para recorrências não concluídas | [Objeto retry_configuration](#objeto-retry_configuration) |
| `debtor_data` | object | Dados do devedor (assinante) | [Objeto debtor_data](#objeto-debtor_data) |
| `qr_code_data` | object | Dados de QR Code gerado para o pagamento (se houver) | [Objeto qr_code_data](#objeto-qr_code_data) |
| `initial_payment_data` | object | Dados da cobrança inicial | [Objeto initial_payment_data](#objeto-initial_payment_data) |
| `pix_message` | string | Mensagem enviada junto à transação Pix | 140 |
| `settlement_date_type` | enumerator| Tipo do ajuste da data de liquidação | [Enumeradores settlement_date_type](#enumeradores-settlement_date_type) |
---
### Objeto retry_configuration
| Campo | Tipo | Descrição | Caracteres |
|-----------------|---------|---------------------------------------------|------------|
| `retry_allowed` | boolean | Indica se retentativas estão habilitadas | - |
| `retry_rule` | object | Regras detalhadas das retentativas | [Objeto retry_rule](#objeto-retry_rule) |
---
### Objeto retry_rule
| Campo | Tipo | Descrição | Caracteres |
|---------------|--------|-----------------------------------|------------|
| `first_retry` | object | Configuração para 1ª retentativa | [Objeto retry_detail](#objeto-retry_detail) |
| `second_retry`| object | Configuração para 2ª retentativa | [Objeto retry_detail](#objeto-retry_detail) |
| `third_retry` | object | Configuração para 3ª retentativa | [Objeto retry_detail](#objeto-retry_detail) |
---
### Objeto retry_detail
| Campo | Tipo | Descrição | Caracteres |
|-------|--------|-------------------------|------------|
| `day` | string | Dia da retentativa. | - |
| `time`| string | Horário da retentativa. | - |
---
### Objeto debtor_data
| Campo | Tipo | Descrição | Caracteres |
|-------------------|--------|------------------------|------------|
| `name` | string | Nome do assinante. | 50 |
| `email` | string | E-mail do assinante. | 100 |
| `document_number` | string | CPF ou CNPJ. | 14 |
| `address` | object | Endereço do assinante. | [Objeto address](#objeto-address) |
| `account_data` | object | Dados bancários. | [Objeto account_data](#objeto-account_data) |
---
### Objeto address
| Campo | Tipo | Descrição | Caracteres |
|---------------|--------|-------------------|------------|
| `city` | string | Cidade. | - |
| `postal_code` | string | CEP. | - |
| `uf` | string | Estado (sigla). | - |
| `street` | string | Logradouro. | - |
---
### Objeto account_data
| Campo | Tipo | Descrição | Caracteres |
|-----------------|--------|------------------------------|------------|
| `account_number`| string | Número da conta | - |
| `account_digit` | string | Dígito da conta | - |
| `account_branch`| string | Agência | - |
| `ispb` | string | ISPB da instituição financeira| - |
---
### Objeto qr_code_data
| Campo | Tipo | Descrição | Caracteres |
|------------------|--------|---------------------------------------------|------------|
| `qr_code_key` | string | Identificador do QR Code gerado | - |
| `qr_code_url` | string | URL para visualização do QR Code | - |
| `qr_code_image` | string | Imagem do QR Code (em Base64) | - |
---
### Objeto initial_payment_data
| Campo | Tipo | Descrição | Caracteres |
|---------------------------|----------|--------------------------------------------------------------------------|------------|
| `amount` | number | Valor principal da cobrança inicial em reais (R$) | - |
| `pix_key` | string | Chave Pix de destino para o pagamento inicial | 77 |
| `qr_code_type` | enum | Tipo de QR Code para cobrança inicial. | [Enumeradores qr_code_type](#enumeradores-qr_code_type) |
| `additional_data` | array | Lista de informações adicionais relacionadas à cobrança | [Array de objects additional_data](#array-additional_data) |
| `fine_amount` | number | Valor da multa, caso ocorra atraso no pagamento | - |
| `interest_amount` | number | Valor dos juros, caso ocorra atraso no pagamento | - |
| `expiration_date` | string | Data de expiração da cobrança inicial (formato ISO 8601) | 10 |
| `max_payment_days` | integer | Número máximo de dias de aceite após expiração | - |
| `rebate_amount` | number | Valor do desconto para pagamento antecipado | - |
| `discounts` | array | Lista de descontos adicionais | - |
| `receiver_conciliation_id`| string | Identificador de conciliação do pagamento pelo recebedor | 35 |
| `transaction_data` | object | Detalhes da transação relacionada à cobrança inicial | [Objeto transaction_data](#objeto-transaction_data) |
---
### Array additional_data
| Campo | Tipo | Descrição | Caracteres |
|--------------|---------|-----------------------------------------------------------|------------|
| `key_name` | string | Nome da informação adicional (ex: "Juros e Multa") | 140 |
| `value` | string | Valor ou descrição da informação adicional | 140 |
---
### Objeto transaction_data
| Campo | Tipo | Descrição | Caracteres |
|---------------------|--------|----------------------------------------|------------|
| `transaction_key` | string | Chave única da transação | 36 |
| `pix_transfer_key` | string | Identificador da transferência Pix | 36 |
| `end_to_end_id` | string | Identificador end-to-end do Pix | 32 |
---
### Objeto pagination
| Campo | Tipo | Descrição | Caracteres |
|------------------|---------|-------------------------------------|------------|
| `page` | integer | Número da página retornada. | - |
| `page_size` | integer | Quantidade de itens por página. | - |
| `number_of_pages`| integer | Total de páginas disponíveis. | - |
---
### Enumeradores periodicity
| Enumerador | Descrição |
|--------------|-----------------------|
| `weekly` | Recorrência semanal |
| `monthly` | Recorrência mensal |
| `quarterly` | Recorrência trimestral|
| `semiannual` | Recorrência semestral |
| `annual` | Recorrência anual |
---
### Enumeradores journey_type
| Enumerador | Descrição |
|-----------------|----------------------------------------------|
| `journey_one` | Notificação direta no aplicativo bancário |
| `journey_two` | Experiência QR Code para cobrança recorrente |
| `journey_three` | Pagamento instantâneo + recorrência QR Code |
| `journey_four` | Opt-in recorrente a partir de operação Pix |
---
### Enumeradores settlement_date_type
| Enumerador | Descrição |
|-----------------|------------------|
| `workdays` | Dias úteis |
| `calendar_days` | Dias corridos |
---
### Enumeradores qr_code_type
| Enumerador | Descrição |
|-------------------|---------------------------------------------------|
| `dynamic_instant` | QR Code dinâmico para pagamento instantâneo |
| `dynamic_term` | QR Code dinâmico para pagamento com vencimento futuro |
STATUS 4XX
Response Error
```json
{
"title": "titulo",
"description": "description in English",
"translation": "descrição em português",
"code": "codigo"
}
```
| Código HTTP | Código QI
`code` | Título
`title` | Descrição (eng)
`description` | Descrição (ptbr)
`translation` |
|-------------|----------------------|-----------------------------------|----------------------------------------------------------------------------|--------------------------------------------------------------------|
| 400 | QIT000002 | Bad Request | Invalid request schema. | Erro no esquema da requisição. |
| 404 | APX000002 | Recurrence Not Found | Recurrence \{recurrence_key\} not found. | Recorrência \{recurrence_key\} não encontrada. |
---
# Simulação de cenários
URL: /documentation/baas/pix_automatico/recebedor/simulacao
Guia completo para simular o fluxo recebedor da automatic-pix-api no ambiente sandbox. Este guia inclui tanto os endpoints de mock quanto os endpoints reais necessários para o fluxo completo de testes.
:::caution Pré-requisitos Importantes
Antes de executar qualquer simulação de mock, você **deve** criar uma recorrência utilizando uma das jornadas de autorização disponíveis. Os mocks simulam apenas as respostas da SPI, mas a recorrência precisa existir no sistema.
**Consulte as jornadas de criação:**
- [Jornada 1 - Push Notification](./journey_one.md)
- [Jornada 2 - QR Code (apenas recorrência)](./journey_two.md)
- [Jornada 3 - QR Code (com primeiro pagamento)](./journey_three.md)
- [Jornada 4 - QR Code (com primeiro pagamento e valores variáveis)](./journey_four.md)
:::
{`
.pix-flow-container {
width: 100%;
max-width: 800px;
margin: 40px auto;
background-color: #f8fafc;
border-radius: 16px;
box-shadow: 0 10px 30px rgba(0, 0, 0, 0.1);
padding: 30px;
position: relative;
border: 1px solid #e5e7eb;
}
.pix-flow-header {
text-align: center;
margin-bottom: 30px;
border-bottom: 2px solid #e5e7eb;
padding-bottom: 20px;
position: relative;
}
.pix-flow-header h3 {
font-size: 24px;
font-weight: 700;
color: #1e40af;
text-transform: uppercase;
letter-spacing: 1px;
margin-bottom: 8px;
}
.pix-flow-header p {
font-size: 14px;
color: #64748b;
}
.status-indicator {
position: absolute;
top: 10px;
right: 10px;
display: flex;
align-items: center;
gap: 6px;
font-size: 12px;
color: #64748b;
}
.status-light {
width: 10px;
height: 10px;
border-radius: 50%;
background-color: #10b981;
animation: pulse-status 2s infinite;
}
@keyframes pulse-status {
0%, 100% { opacity: 1; box-shadow: 0 0 0 0 rgba(16, 185, 129, 0.7); }
50% { opacity: 0.8; box-shadow: 0 0 0 8px rgba(16, 185, 129, 0); }
}
.pix-flowchart {
display: flex;
flex-direction: column;
gap: 20px;
max-height: 800px;
overflow-y: auto;
padding-right: 10px;
}
.pix-flowchart::-webkit-scrollbar {
width: 8px;
}
.pix-flowchart::-webkit-scrollbar-track {
background: #f1f5f9;
border-radius: 10px;
}
.pix-flowchart::-webkit-scrollbar-thumb {
background-color: #cbd5e1;
border-radius: 10px;
}
.pix-flowchart::-webkit-scrollbar-thumb:hover {
background-color: #94a3b8;
}
.pix-step {
background-color: #ffffff;
border-radius: 12px;
padding: 18px;
position: relative;
border-left: 5px solid;
transition: all 0.3s ease;
cursor: pointer;
opacity: 0;
transform: translateX(-20px);
animation: fadeInStep 0.5s forwards;
display: flex;
flex-direction: column;
box-shadow: 0 2px 8px rgba(0, 0, 0, 0.08);
text-decoration: none;
color: inherit;
}
.pix-step:hover {
transform: translateY(-5px);
box-shadow: 0 10px 25px rgba(0, 0, 0, 0.15);
border-left-width: 6px;
}
.pix-step:visited {
color: inherit;
}
.pix-step.step-create { border-left-color: #3b82f6; }
.pix-step.step-approve { border-left-color: #1e293b; }
.pix-step.step-process { border-left-color: #1e40af; }
.pix-step.step-conciliate { border-left-color: #0f172a; }
.pix-step.step-update { border-left-color: #ec4899; }
.pix-step.step-attempts { border-left-color: #3b82f6; }
.pix-step-header {
display: flex;
justify-content: space-between;
align-items: center;
margin-bottom: 12px;
}
.pix-step-number {
width: 32px;
height: 32px;
border-radius: 50%;
background-color: #f1f5f9;
display: flex;
justify-content: center;
align-items: center;
font-size: 14px;
font-weight: 700;
flex-shrink: 0;
transition: all 0.3s ease;
}
.pix-step:hover .pix-step-number {
transform: scale(1.15);
box-shadow: 0 6px 15px rgba(0, 0, 0, 0.2);
}
.pix-step.step-create .pix-step-number { background-color: #3b82f6; color: #ffffff; }
.pix-step.step-approve .pix-step-number { background-color: #1e293b; color: #ffffff; }
.pix-step.step-process .pix-step-number { background-color: #1e40af; color: #ffffff; }
.pix-step.step-conciliate .pix-step-number { background-color: #0f172a; color: #ffffff; }
.pix-step.step-update .pix-step-number { background-color: #ec4899; color: #ffffff; }
.pix-step.step-attempts .pix-step-number { background-color: #3b82f6; color: #ffffff; }
.pix-step-title {
font-size: 16px;
font-weight: 700;
color: #0f172a;
flex-grow: 1;
margin-left: 12px;
}
.pix-step-type {
font-size: 11px;
background-color: #f1f5f9;
padding: 4px 10px;
border-radius: 6px;
font-weight: 600;
text-transform: uppercase;
letter-spacing: 0.5px;
}
.pix-step-type.mock { background-color: #dbeafe; color: #1e40af; }
.pix-step-type.real { background-color: #dcfce7; color: #16a34a; }
.pix-step-type.optional { background-color: #fef3c7; color: #d97706; }
.pix-step-content {
display: flex;
flex-direction: column;
gap: 12px;
max-height: 0;
overflow: hidden;
transition: max-height 0.4s ease;
margin-top: 8px;
}
.pix-step.active .pix-step-content {
max-height: 500px;
}
.pix-step-description {
font-size: 14px;
line-height: 1.6;
color: #475569;
}
.pix-step-info {
background-color: #eff6ff;
border-left: 3px solid #3b82f6;
padding: 10px 14px;
font-size: 13px;
color: #1e40af;
border-radius: 6px;
}
.pix-step-warning {
background-color: #fef3c7;
border-left: 3px solid #f59e0b;
padding: 10px 14px;
font-size: 13px;
color: #92400e;
border-radius: 6px;
}
.pix-connector {
height: 24px;
width: 3px;
background: linear-gradient(to bottom, #cbd5e1, #94a3b8);
margin: -12px auto;
position: relative;
z-index: 1;
border-radius: 2px;
}
.pix-connector::before {
content: '';
position: absolute;
bottom: 0;
left: 50%;
transform: translateX(-50%);
width: 0;
height: 0;
border-left: 6px solid transparent;
border-right: 6px solid transparent;
border-top: 8px solid #94a3b8;
}
.pix-branch-container {
margin-top: 30px;
padding-top: 0px;
}
.pix-branch-title {
text-align: center;
font-size: 18px;
font-weight: 700;
color: #0f172a;
margin-bottom: 24px;
}
.pix-branch-container {
position: relative;
}
.pix-branch-connectors {
position: absolute;
top: -25px;
left: 0;
right: 0;
height: 40px;
display: flex;
justify-content: space-between;
align-items: flex-start;
pointer-events: none;
z-index: 0;
}
.pix-branch-arrow {
width: 3px;
height: 105px;
position: relative;
opacity: 0.9;
}
.pix-branch-arrow::after {
content: '';
position: absolute;
bottom: 0;
left: 50%;
transform: translateX(-50%);
width: 0;
height: 0;
border-left: 6px solid transparent;
border-right: 6px solid transparent;
border-top: 10px solid;
}
.pix-branch-options {
display: grid;
grid-template-columns: 1fr 1fr;
gap: 20px;
}
.pix-branch-option {
background-color: #ffffff;
border-radius: 12px;
padding: 20px;
text-align: center;
transition: all 0.3s ease;
box-shadow: 0 2px 8px rgba(0, 0, 0, 0.08);
cursor: pointer;
text-decoration: none;
color: inherit;
}
.pix-branch-option:hover {
transform: translateY(-3px);
box-shadow: 0 8px 20px rgba(0, 0, 0, 0.12);
}
.branch-title-payment {
font-weight: 800;
font-size: 16px;
margin-bottom: 14px;
color: #1e40af;
}
.branch-title-rejection {
font-weight: 800;
font-size: 16px;
margin-bottom: 14px;
color: #ec4899;
}
.pix-branch-button {
padding: 14px 20px 5px 20px;
border-radius: 10px;
font-weight: 700;
font-size: 14px;
color: #ffffff;
border: none;
cursor: pointer;
width: 100%;
margin-top: 8px;
transition: all 0.3s ease;
text-decoration: none;
display: inline-block;
align-items: center;
justify-content: center;
}
.pix-branch-button:hover {
transform: scale(1.02);
}
.branch-button-payment {
background: linear-gradient(135deg, #1e3a8a 0%, #3b82f6 50%, #60a5fa 100%);
box-shadow: 0 4px 12px rgba(30, 64, 175, 0.3);
}
.branch-button-rejection {
background: linear-gradient(135deg, #9f1239 0%, #ec4899 50%, #f472b6 100%);
box-shadow: 0 4px 12px rgba(236, 72, 153, 0.3);
}
@keyframes fadeInStep {
to {
opacity: 1;
transform: translateX(0);
}
}
@media (max-width: 768px) {
.pix-flow-container {
padding: 20px;
}
.pix-flow-header h3 {
font-size: 20px;
}
.pix-step {
padding: 14px;
}
.pix-step-title {
font-size: 14px;
}
.pix-step-number {
width: 28px;
height: 28px;
font-size: 12px;
}
.pix-branch-options {
grid-template-columns: 1fr;
}
.status-indicator {
top: 5px;
right: 5px;
font-size: 10px;
}
}
`}
Fluxo Completo de Simulação
Teste de ponta a ponta do Pix Automático - Sandbox Environment
SANDBOX
1
Criar Recorrência
REAL
Passo obrigatório antes de qualquer simulação. Escolha uma das quatro jornadas disponíveis (Jornada 1: Push Notification, Jornadas 2-4: QR Code com diferentes configurações). Após criar, guarde o outgoing_recurrence_spi_id retornado.
Jornadas disponíveis: Jornada 1 (Push), Jornada 2 (QR Code - recorrência), Jornada 3 (QR Code + primeiro pagamento), Jornada 4 (QR Code + pagamento + valores variáveis)
2
Aprovar Recorrência
MOCK
Simula as atualizações de status de recorrência que a SPI enviará para a automatic-pix-api. Utilize o endpoint /mock/outgoing_recurrence/OUTGOING_RECURRENCE_SPI_ID para atualizar o status para pending_confirmation e depois para approved .
Atenção: Nas jornadas 2, 3 e 4, é necessário enviar também os dados da conta ( account_data ) na aprovação. Nas jornadas 3 e 4, inclua também informações do primeiro pagamento.
3
Processar Ordens de Pagamento
MOCK
Simula o processamento das ordens de pagamento através do endpoint /mock/process_payment_orders . Este passo cria automaticamente os lotes de conciliação e envia o webhook de criação de lote para sua URL configurada.
O que acontece: Ordens são criadas automaticamente, lotes de conciliação são criados ou atualizados com base na reference_date e tipo de recorrência, e o webhook de criação é disparado.
4
Consultar e Conciliar Ordens
REAL
Passo real (não é mock): Consultar o lote de conciliação criado e obter o receiver_conciliation_id e payment_order_key . Para recorrências do tipo variable_amount , você deve atualizar a ordem de pagamento com o valor específico.
Importante: Este passo é obrigatório para recorrências variable_amount . Sem a atualização do valor, a ordem não será processada. Para fixed_amount , este passo não é necessário.
5
Atualizar Data de Execução
MOCK
Atualiza o next_retry_execution_datetime de uma ordem de pagamento para a data atual, permitindo que o processamento das tentativas ocorra imediatamente. Utilize o endpoint /mock/payment_order/PAYMENT_ORDER_KEY/update_next_retry_execution_datetime .
Disponível apenas no sandbox. Este passo é necessário para avançar o fluxo e permitir o processamento imediato das tentativas de pagamento.
6
Processar Tentativas de Pagamento
MOCK
Simula o processamento das tentativas de pagamento através do endpoint /mock/process_payment_order_attempts . Cria as tentativas necessárias para o fluxo de PIX automático, preparando o sistema para receber a simulação de PIX de entrada ou rejeição.
Disponível apenas no sandbox. Após este passo, você pode simular o recebimento do PIX (Passo 7) ou a rejeição (Passo 8).
Simulações de Resultado
Pagamento
7. Simular Pix de Entrada
Simula o recebimento bem-sucedido do pagamento via PIX
Rejeições
7. Simular Rejeição
Simula a rejeição de uma tentativa de pagamento
{`
if (typeof document !== 'undefined') {
document.addEventListener('DOMContentLoaded', function() {
const steps = document.querySelectorAll('.pix-step');
steps.forEach((step, index) => {
step.style.animationDelay = \`\${index * 0.15}s\`;
step.addEventListener('click', function(e) {
e.preventDefault();
const targetId = this.getAttribute('href');
// Toggle active state
const wasActive = this.classList.contains('active');
// Close all steps
steps.forEach(s => s.classList.remove('active'));
// If wasn't active, open it
if (!wasActive) {
this.classList.add('active');
// Scroll to section
if (targetId) {
const targetElement = document.querySelector(targetId);
if (targetElement) {
setTimeout(() => {
targetElement.scrollIntoView({ behavior: 'smooth', block: 'start' });
}, 300);
}
}
} else {
// If was active and clicked again, navigate to section
if (targetId) {
const targetElement = document.querySelector(targetId);
if (targetElement) {
targetElement.scrollIntoView({ behavior: 'smooth', block: 'start' });
}
}
}
});
});
// Auto-open first step after animation
setTimeout(() => {
if (steps.length > 0) {
steps[0].classList.add('active');
}
}, steps.length * 150 + 200);
});
}
`}
---
## Pré-requisito: Criar Recorrência
:::danger Obrigatório
**Este passo é obrigatório** antes de qualquer simulação de mock. Escolha uma das jornadas de criação de recorrência conforme sua necessidade.
:::
### Escolha sua Jornada
| Jornada | Descrição | Link |
|---------|-----------|------|
| **Jornada 1** | Push Notification - Autorização via notificação | [Criar Recorrência: Jornada 1](./journey_one.md) |
| **Jornada 2** | QR Code - Apenas autorização da recorrência | [Criar Recorrência: Jornada 2](./journey_two.md) |
| **Jornada 3** | QR Code - Recorrência + primeiro pagamento | [Criar Recorrência: Jornada 3](./journey_three.md) |
| **Jornada 4** | QR Code - Recorrência + primeiro pagamento + valores variáveis | [Criar Recorrência: Jornada 4](./journey_four.md) |
:::info Informação Importante
Após criar a recorrência, guarde o `outgoing_recurrence_spi_id` retornado. Ele será necessário para as simulações de mock.
:::
---
## Passo 1: Simulação de Atualização de Recorrência (Simulação)
:::caution Pré-requisito
**Antes deste passo**, você deve ter:
1. Criado uma recorrência usando uma das [jornadas de criação](#passo-0-criar-recorrência-pré-requisito)
2. Obtido o `outgoing_recurrence_spi_id` da recorrência criada
:::
Este endpoint simula as atualizações de status de recorrência que a SPI enviará para a automatic-pix-api durante diferentes jornadas do fluxo recebedor.
### Request
ENDPOINT /mock/outgoing_recurrence/ OUTGOING_RECURRENCE_SPI_ID
MÉTODO PATCH
Request Body: Jornada 1 - Recebimento da solicitação pelo PSP Pagador
```json
{
"outgoing_recurrence_status": "pending_confirmation"
}
```
Request Body: Jornada 1 - Recebimento da confirmação da solicitação pelo PSP Pagador
```json
{
"outgoing_recurrence_status": "approved"
}
```
Request Body: Jornadas 2, 3 e 4 - Recebimento da solicitação pelo PSP Pagador
```json
{
"outgoing_recurrence_status": "pending_confirmation"
}
```
Request Body: Jornada 2 - Recebimento da confirmação da solicitação pelo PSP Pagador
```json
{
"outgoing_recurrence_status": "approved",
"account_data": {
"account_number": "123456",
"account_digit": "7",
"account_branch": "0001",
"ispb": "31872495"
}
}
```
Request Body: Jornadas 3 e 4 - Recebimento da confirmação da solicitação pelo PSP Pagador
```json
{
"outgoing_recurrence_status": "approved",
"account_data": {
"account_number": "123456",
"account_digit": "7",
"account_branch": "0001",
"ispb": "31872495"
},
"receiver_conciliation_id": "064b6563329047c59db6902725b8d31e",
"target_account_key": "23a4a1c8-9d82-4ebe-a90d-44fe8d839ec0",
"transaction_amount": 250
}
```
### Path Parameters
| Campo | Tipo | Descrição | Máx. Caract. |
|--------------------------------|--------|------------------------------------------------|--------------|
| **outgoing_recurrence_spi_id*** | string | Identificador SPI da recorrência de saída | 50 |
### Objeto Request Body
| Campo | Tipo | Descrição | Máx. Caract. |
|-------------------------------|--------|-------------------------------------------------|--------------|
| **outgoing_recurrence_status*** | string | Status da recorrência de saída | 50 |
| **account_data** | object | Dados da conta (apenas jornadas 2, 3 e 4) | - |
### Objeto account_data
| Campo | Tipo | Descrição | Máx. Caract. |
|---------------------|--------|------------------------------------------|--------------|
| **account_number*** | string | Número da conta | 20 |
| **account_digit*** | string | Dígito da conta | 1 |
| **account_branch*** | string | Agência da conta | 6 |
| **ispb*** | string | Código ISPB da instituição financeira | 8 |
### Enumerador outgoing_recurrence_status
| Enumerador | Descrição |
|-------------------------|-------------------------------------|
| **pending_confirmation** | Pendente de confirmação |
| **approved** | Aprovado |
:::info Fluxos de Jornada
- **Jornada 1**: Apenas atualização de status, sem dados da conta
- **Jornada 2**: Primeiro apenas status, depois status + dados da conta (apenas aprovação da recorrência)
- **Jornadas 3 e 4**: Primeiro apenas status, depois status + dados da conta + dados do primeiro pagamento
:::
:::tip Próximo Passo
Após aprovar a recorrência, prossiga para o [Passo 3: Processar Ordens de Pagamento](#passo-3-processar-ordens-de-pagamento-mock)
:::
---
## Passo 2: Simulação de Cancelamento de Recorrência (Simulação - Opcional)
:::caution Pré-requisito
**Antes deste passo**, você deve ter:
1. Criado uma recorrência
2. Aprovado a recorrência ([Passo 1](#passo-1-simulação-de-atualização-de-recorrência-mock))
:::
Este endpoint simula o cancelamento de uma recorrência de saída acionado pela SPI.
### Request
ENDPOINT /mock/outgoing_recurrence/ OUTGOING_RECURRENCE_SPI_ID /cancel
MÉTODO PATCH
:::info Sem Payload
Este endpoint não possui request body (payload). Apenas o path parameter é necessário.
:::
### Path Parameters
| Campo | Tipo | Descrição | Máx. Caract. |
|--------------------------------|--------|------------------------------------------------|--------------|
| **outgoing_recurrence_spi_id*** | string | Identificador SPI da recorrência de saída | 50 |
---
## Passo 3: Processar Ordens de Pagamento (Simulação)
:::caution Pré-requisitos
**Antes deste passo**, você deve ter:
1. Criado uma recorrência
2. Aprovado a recorrência ([Passo 1](#passo-1-simulação-de-atualização-de-recorrência-mock))
:::
Este endpoint simula o processamento das ordens de pagamento que, consequentemente, irá criar os lotes de conciliação e enviar o Webhook de criação desses lotes.
### Request
ENDPOINT /mock/process_payment_orders
MÉTODO PATCH
:::info Sem Payload
Este endpoint não possui request body (payload). A simulação é executada automaticamente.
:::
:::info O que acontece neste passo?
1. **Ordens de pagamento são criadas** automaticamente pelo sistema
2. **Lote de conciliação é criado ou atualizado** (`payment_order_conciliation_batch`)
- Se já existir um lote aberto para a `reference_date` e para o tipo de recorrência ('fixed_amount' ou 'variable_amount'), a ordem é incluída nele
- Caso contrário, um novo lote é criado
3. **Webhook de criação de lote é enviado** para sua URL configurada
:::
:::tip Próximo Passo
Após processar as ordens, você precisa **consultar e conciliar** as ordens de pagamento antes de continuar. Veja o [Passo 4](#passo-4-consultar-e-conciliar-ordens-de-pagamento).
:::
---
## Passo 4: Consultar e Conciliar Ordens de Pagamento
:::danger Passo Obrigatório (NÃO é Mock)
**Este é um passo real**, não é uma simulação! Você precisa consultar o lote de conciliação criado no passo anterior e obter o `receiver_conciliation_id` e a `payment_order_key` que serão usados posteriormente.
:::
:::caution Pré-requisitos
**Antes deste passo**, você deve ter:
1. Processado as ordens de pagamento ([Passo 3](#passo-3-processar-ordens-de-pagamento-mock))
2. Recebido o webhook de criação do lote de conciliação
:::
### 4.1 - Consultar Lote de Pagamentos
Para consultar os lotes criados, utilize o endpoint de consulta de lotes:
**Consulte a documentação completa:**
- [Consultar lote de pagamentos por conta](../conciliacao/consultar_lote_por_conta.md)
- [Consultar lote de pagamentos por requester](../conciliacao/consultar_lote_requester.md)
:::info Informações Importantes
Na resposta do GET, você encontrará:
- `payment_order_conciliation_batch_key`: Chave do lote
- `payment_orders`: Lista de ordens de pagamento dentro do lote
- `receiver_conciliation_id`: **Guarde este valor!** Será usado no Passo 7 para simular o PIX de entrada
- `payment_order_spi_id`: Identificador SPI da ordem de pagamento
- `payment_order_key`: Chave única da ordem de pagamento
:::
### 4.2 - Atualizar Ordem de Pagamento (Obrigatório para Valor Variável)
:::warning Importante
**Este passo é obrigatório** para recorrências do tipo `variable_amount`. Para recorrências de valor fixo (`fixed_amount`), este passo não é necessário.
:::
Para recorrências de valor variável, você **deve** atualizar a ordem de pagamento informando o valor específico que será cobrado neste ciclo:
**Consulte a documentação completa:**
- [Atualizar ordem de pagamento](../pagamentos/atualizar_payment_order.md)
ENDPOINT
/account/ ACCOUNT_KEY /outgoing_recurrence/ OUTGOING_RECURRENCE_KEY /payment_order/ PAYMENT_ORDER_KEY
MÉTODO
PATCH
Request Body - Exemplo para Valor Variável
```json
{
"transaction_amount": 150.75,
}
```
### Quando é Obrigatório?
| Tipo de Recorrência | Atualização Obrigatória? | Motivo |
|---------------------|---------------------------|---------|
| **`fixed_amount`** | Não | Valor já definido na criação da recorrência |
| **`variable_amount`** | **Sim** | Valor deve ser informado a cada execução |
:::info Informação
- **Recorrências fixas**: O valor já está definido na criação, não precisa ser atualizado
- **Recorrências variáveis**: O valor deve ser informado antes de cada processamento de pagamento
- **Sem atualização**: Recorrências variáveis sem atualização não serão processadas
:::
:::tip Próximo Passo
Após consultar o lote e atualizar a ordem de pagamento (se necessário), prossiga para o [Passo 5](#passo-5-atualizar-data-de-execução-mock---sandbox).
:::
---
## Passo 5: Atualizar Data de Execução (Simulação)
:::caution Pré-requisitos
**Antes deste passo**, você deve ter:
1. Processado as ordens de pagamento ([Passo 3](#passo-3-processar-ordens-de-pagamento-mock))
2. Consultado o lote de conciliação ([Passo 4](#passo-4-consultar-e-conciliar-ordens-de-pagamento))
3. Obtido o `payment_order_key` da ordem de pagamento
:::
Este endpoint permite atualizar o `next_retry_execution_datetime` de uma Ordem de Pagamento específica para a data atual, possibilitando que o processamento das Order Attempts ocorra imediatamente.
:::info Sandbox Apenas
Este endpoint está disponível **apenas no ambiente sandbox**.
:::
### Request
ENDPOINT /mock/payment_order/ payment_order_key /update_next_retry_execution_datetime
MÉTODO PATCH
### Path Params
| Campo | Tipo | Descrição | Máx. Caract. |
|----------------------|--------|------------------------------------------------|--------------|
| **payment_order_key*** | uuid4 | Chave única de identificação da ordem de pagamento | 36 |
Request Body
```json
{
"next_retry_execution_datetime": "2025-08-22"
}
```
### Request Body Params
| Campo | Tipo | Descrição | Máx. Caract. |
|----------------------------------|--------|------------------------------------------------|--------------|
| **next_retry_execution_datetime*** | string | Nova data de execução da order (formato YYYY-MM-DD) | 10 |
:::info Finalidade
Este endpoint atualiza a data de próxima execução da tentativa para a data atual, permitindo que o sistema processe imediatamente as tentativas de pagamento, que são necessárias para simular o recebimento de PIX de entrada.
:::
:::tip Próximo Passo
Após atualizar a data de execução, prossiga para o [Passo 6](#passo-6-processar-tentativas-de-pagamento-mock---sandbox).
:::
---
## Passo 6: Processar Tentativas de Pagamento (Simulação)
:::caution Pré-requisitos
**Antes deste passo**, você deve ter:
1. Atualizado a data de execução ([Passo 5](#passo-5-atualizar-data-de-execução-mock---sandbox))
:::
Este endpoint simula o processamento das tentativas de pagamento, criando as tentativas necessárias para o fluxo de PIX automático.
:::info Sandbox Apenas
Este endpoint está disponível **apenas no ambiente sandbox**.
:::
### Request
ENDPOINT /mock/process_payment_order_attempts
MÉTODO PATCH
:::info Sem Payload
Este endpoint não possui request body (payload). A simulação é executada automaticamente.
:::
:::info Finalidade
Este endpoint processa as tentativas de pagamento baseadas nas ordens de pagamento com datas de execução atualizadas, criando as tentativas necessárias para simular o recebimento de PIX de entrada.
:::
:::tip Próximo Passo - Escolha seu Caminho
**Fluxo de Sucesso**: Prossiga para o [Passo 7: Simular PIX de Entrada](#passo-7-simular-pix-de-entrada-mock)
**Fluxo de Rejeição**: Prossiga para o [Passo 8: Simular Tentativa Rejeitada](#passo-8-simular-tentativa-de-pagamento-rejeitada-mock)
:::
---
## Passo 7: Simular Pix de Entrada
:::caution Pré-requisitos
**Antes deste passo**, você deve ter:
1. Atualizado a data de execução ([Passo 5](#passo-5-atualizar-data-de-execução-mock---sandbox))
2. Processado as tentativas de pagamento ([Passo 6](#passo-6-processar-tentativas-de-pagamento-mock---sandbox))
3. Obtido o `receiver_conciliation_id` do lote ([Passo 4](#passo-4-consultar-e-conciliar-ordens-de-pagamento))
4. Obtido o `outgoing_recurrence_spi_id` e `payment_order_spi_id`
:::
Este endpoint simula o recebimento de um Pix que será associado a uma Ordem de Pagamento de uma recorrência.
### Request
ENDPOINT /mock/automatic_pix/incoming_pix
MÉTODO POST
Request Body
```json
{
"target_account_key": "23a4a2c8-9d82-4ebe-a90d-44fe8d839ec0",
"amount": 1000.00,
"receiver_conciliation_id": "7535f0467d9a4af69c4d99408c2fec9d"
}
```
### Objeto Request Body
| Campo | Tipo | Descrição | Máx. Caract. |
|-------------------------------|--------|--------------------------------------------------------------|--------------|
| **target_account_key*** | string | Chave única da conta de destino | 36 |
| **amount*** | number | Valor da transação PIX | - |
| **receiver_conciliation_id*** | string | Identificação de conciliação do recebedor (obtido no Passo 4) | 35 |
:::info Informação
Este endpoint simula o fluxo completo de Incoming Pix, incluindo:
1. Processamento da transferência Pix
2. Associação à ordem de pagamento da automatic-pix usando o `receiver_conciliation_id`
:::
:::success Fluxo Concluído!
Parabéns! Você completou o fluxo de pagamento bem-sucedido. O sistema processou:
- Criação da recorrência
- Aprovação da recorrência
- Criação de ordens de pagamento e lotes
- Processamento de tentativas
- Recebimento do PIX
:::
---
## Passo 8: Simular Tentativa de Pagamento Rejeitada (Simulação)
:::caution Pré-requisitos
**Antes deste passo**, você deve ter:
1. Processado as ordens de pagamento ([Passo 3](#passo-3-processar-ordens-de-pagamento-mock))
2. Atualizado a data de execução ([Passo 5](#passo-5-atualizar-data-de-execução-mock---sandbox))
3. Processado as tentativas de pagamento ([Passo 6](#passo-6-processar-tentativas-de-pagamento-mock---sandbox))
4. Obtido o `outgoing_recurrence_spi_id` e `payment_order_spi_id`
:::
Este endpoint simula a rejeição de uma tentativa de pagamento PIX dentro de uma recorrência de saída, replicando o comportamento quando a SPI rejeita uma transação. O sistema criará automaticamente as tentativas de pagamento e simulará o PIX rejeitado, resultando no envio do webhook de mudança de status da tentativa.
### Request
ENDPOINT /mock/automatic_pix/outgoing_recurrence/ OUTGOING_RECURRENCE_SPI_ID /payment_order/ PAYMENT_ORDER_SPI_ID
MÉTODO PATCH
Request Body: Tentativa rejeitada
```json
{
"payment_order_status": "rejected",
"rejection_information": {
"bacen_reason_code": "AC06"
}
}
```
### Path Parameters
| Campo | Tipo | Descrição | Máx. Caract. |
|--------------------------------|--------|------------------------------------------------|--------------|
| **outgoing_recurrence_spi_id*** | string | Identificador SPI da recorrência de saída | 50 |
| **payment_order_spi_id*** | string | Identificador SPI da ordem de pagamento | 50 |
### Objeto Request Body
| Campo | Tipo | Descrição | Máx. Caract. |
|-------------------------------|--------|-------------------------------------------------|--------------|
| **payment_order_status*** | string | Status da ordem de pagamento (sempre "rejected") | 50 |
| **rejection_information*** | object | Informações sobre a rejeição | - |
### Objeto rejection_information
| Campo | Tipo | Descrição | Máx. Caract. |
|-----------------------|--------|------------------------------------------|--------------|
| **bacen_reason_code*** | string | Código de erro do Bacen para rejeição | 4 |
### Códigos de Erro Bacen Comuns
| Código | Descrição (Inglês) | Descrição (Português) |
|--------|-------------------|----------------------|
| **AB10** | ErrorInstructedAgent | Erro interno no PSP pagador |
| **AC05** | ClosedDebtorAccountNumber | Conta do pagador encerrada |
| **AC06** | BlockedAccount | Conta do pagador bloqueada |
| **AG12** | NotAllowedBookTransfer | Transferência não permitida entre contas da mesma instituição |
| **AM02** | NotAllowedAmount | Valor excede limite máximo do pagador |
| **AM09** | WrongAmount | Valor não corresponde ao estabelecido na recorrência |
| **DENC** | DebtorIdentifierNotCorrespond | CPF/CNPJ do pagador não confere com a recorrência |
| **DS27** | UserNotYetActivated | Participante não cadastrado no SPI |
| **DTED** | InvalidExpiryDate | Data de vencimento inválida para a periodicidade |
| **DTNT** | - | Tentativas pós vencimento fora do prazo permitido |
| **FBRD** | FailureToComplyBusinessRuleDeadline | Solicitação fora do prazo para regras de negócio |
| **IRNT** | - | Recorrência não permite novas tentativas pós vencimento |
| **MIDI** | MandateIdIncorrect | ID da recorrência inexistente ou incorreto |
| **MSUC** | UnconfirmedMandateStatus | Status da recorrência não confirmado pelo pagador |
| **NIEC** | - | Ordem de pagamento anterior ainda pendente |
| **NIPA** | - | Pagamento já foi efetivado |
| **NITX** | - | Instrução não corresponde à cobrança recorrente anterior |
| **QUNT** | - | Limite de tentativas pós vencimento excedido |
| **RC09** | InvalidDebtorClearingSystemMemberIdentifier | ISPB do pagador inválido ou inexistente |
| **UDEI** | UltimateDebtorIdentifierIncorrect | CPF/CNPJ do devedor incorreto |
:::info Funcionamento do Sistema
1. **Simulação de rejeição**: O sistema simula o PIX rejeitado com o código de erro especificado
2. **Webhook enviado**: Para cada tentativa rejeitada, é enviado o webhook `baas.automatic_pix.payment_order_attempt.status_change`
3. **Múltiplas tentativas**: O sistema permite até 4 tentativas de pagamento. Na 4ª tentativa rejeitada, a ordem de pagamento tem seu status alterado para "rejected"
:::
:::info Webhook Resultante
Cada tentativa rejeitada irá gerar um webhook com o seguinte formato:
```json
{
"event_type": "baas.automatic_pix.payment_order_attempt.status_change",
"origin_key": "8cb70dea-9fb0-4a68-9572-99a72849c8d6",
"data": {
"request_control_key": "8cb70dea-9fb0-4a68-9572-99a72849c8d6",
"payment_order_key": "8cb70dea-9fb0-4a68-9572-99a72849c8d6",
"payment_order_attempt_key": "21fc62fd-b0a0-4604-9bea-475e91a9dc82",
"payment_order_status": "pending",
"payment_order_attempt_status": "rejected",
"transaction_amount": 125.53,
"reason": "Conta de destino inexistente",
"outgoing_recurrence_key": "98fc62fd-b0a0-4604-9bea-475e91a9dc82"
}
}
```
:::
### Fluxo de Múltiplas Tentativas
1. **1ª Tentativa**: Payment order permanece com status "pending", attempt status "rejected"
2. **2ª Tentativa**: Payment order permanece com status "pending", nova attempt criada
3. **3ª Tentativa**: Payment order permanece com status "pending", nova attempt criada
4. **4ª Tentativa**: Payment order muda para status "rejected" (limite máximo atingido)
---
## Resumo dos Fluxos
### Fluxo Completo de Sucesso
| Passo | Descrição | Fluxo | Documentação |
|-------|-----------|------|--------------|
| 0 | Criar Recorrência | **Real** | [Jornadas de criação](#passo-0-criar-recorrência-pré-requisito) |
| 1 | Aprovar Recorrência | Simulação | [Ver detalhes](#passo-1-simulação-de-atualização-de-recorrência-mock) |
| 3 | Processar Ordens de Pagamento | Simulação | [Ver detalhes](#passo-3-processar-ordens-de-pagamento-mock) |
| 4 | Consultar e Conciliar Ordens | **Real** | [Consultar lotes](../conciliacao/consultar_lote_por_conta.md) |
| 5 | Atualizar Data de Execução | Simulação | [Ver detalhes](#passo-5-atualizar-data-de-execução-mock---sandbox) |
| 6 | Processar Tentativas | Simulação | [Ver detalhes](#passo-6-processar-tentativas-de-pagamento-mock---sandbox) |
| 7 | Simular PIX de Entrada | Simulação | [Ver detalhes](#passo-7-simular-pix-de-entrada-mock) |
### Fluxo Completo de Rejeição
| Passo | Descrição | Fluxo | Documentação |
|-------|-----------|------|--------------|
| 0 | Criar Recorrência | **Real** | [Jornadas de criação](#passo-0-criar-recorrência-pré-requisito) |
| 1 | Aprovar Recorrência | Simulação | [Ver detalhes](#passo-1-simulação-de-atualização-de-recorrência-mock) |
| 3 | Processar Ordens de Pagamento | Simulação | [Ver detalhes](#passo-3-processar-ordens-de-pagamento-mock) |
| 4 | Consultar e Conciliar Ordens | **Real** | [Consultar lotes](../conciliacao/consultar_lote_por_conta.md) |
| 5 | Atualizar Data de Execução | Simulação | [Ver detalhes](#passo-5-atualizar-data-de-execução-mock---sandbox) |
| 6 | Processar Tentativas | Simulação | [Ver detalhes](#passo-6-processar-tentativas-de-pagamento-mock---sandbox) |
| 8 | Simular Rejeição | Simulação | [Ver detalhes](#passo-8-simular-tentativa-de-pagamento-rejeitada-mock) |
---
## Links Úteis
### Gerenciamento de Recorrências
- [Consultar uma recorrência](./consultar_recorrencia.md)
- [Consultar uma recorrência pelo QR Code](./consultar_recorrencia_receiver.md)
- [Listar recorrências de uma conta](./listar_recorrencias_de_uma_conta.md)
- [Cancelar recorrência](./cancelar_recorrencia.md)
### Gerenciamento de Pagamentos
- [Listar ordens de pagamento](../pagamentos/listar_account_payment_orders.md)
- [Consultar ordem de pagamento](../pagamentos/consultar_payment_order.md)
- [Atualizar ordem de pagamento](../pagamentos/atualizar_payment_order.md)
- [Cancelar ordem de pagamento](../pagamentos/cancelar_payment_order.md)
### Lotes de Conciliação
- [Consultar lote por conta](../conciliacao/consultar_lote_por_conta.md)
- [Consultar lote por requester](../conciliacao/consultar_lote_requester.md)
- [Listar pagamentos de um lote](../conciliacao/listar_payment_orders.md)
- [Webhooks de conciliação](../conciliacao/webhooks.md)
### Webhooks
- [Webhooks do Usuário Recebedor](./webhooks.md)
- [Webhooks de Lotes de Conciliação](../conciliacao/webhooks.md)
---
# Webhooks Pix Automático
URL: /documentation/baas/pix_automatico/recebedor/webhooks
As notificações via webhook são fundamentais para o correto processamento de eventos assíncronos relacionados ao Pix Automático, incluindo especialmente as autorizações e execuções de pagamentos recorrentes em diferentes jornadas.
:::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 de Status de Recorrência
Este webhook é destinado ao reporte de alterações de status de autorizações e ciclos de recorrência do Pix Automático, diferenciando os tipos de jornadas envolvidas.
### Webhook Request Body
### Jornada 1 – journey_one
Request Body: Jornada 1
```json
{
"event_type": "baas.automatic_pix.outgoing_recurrence.status_change",
"origin_key": "8cb70dea-9fb0-4a68-9572-99a72849c8d6",
"data": {
"request_control_key": "98fc62fd-b0a0-4604-9bea-475e91a9dc82",
"outgoing_recurrence_key": "8cb70dea-9fb0-4a68-9572-99a72849c8d6",
"outgoing_recurrence_status": "approved",
"journey_type": "journey_one",
"outgoing_recurrence_data": {
"minimum_recurrence_amount": 123.45,
"recurrence_amount": null
},
"payment_conciliation_batch_key": "uuid"
}
}
```
### Jornada 2 – journey_two
Request Body: Jornada 2
```json
{
"event_type": "baas.automatic_pix.outgoing_recurrence.status_change",
"origin_key": "8cb70dea-9fb0-4a68-9572-99a72849c8d6",
"data": {
"request_control_key": "98fc62fd-b0a0-4604-9bea-475e91a9dc82",
"outgoing_recurrence_key": "8cb70dea-9fb0-4a68-9572-99a72849c8d6",
"outgoing_recurrence_status": "approved",
"journey_type": "journey_two",
"outgoing_recurrence_data": {
"minimum_recurrence_amount": 123.45,
"recurrence_amount": null
},
"payment_conciliation_batch_key": "uuid" or null
}
}
```
### Jornada 3 – journey_three
Request Body: Jornada 3
```json
{
"event_type": "baas.automatic_pix.outgoing_recurrence.status_change",
"origin_key": "8cb70dea-9fb0-4a68-9572-99a72849c8d6",
"data": {
"request_control_key": "98fc62fd-b0a0-4604-9bea-475e91a9dc82",
"outgoing_recurrence_key": "8cb70dea-9fb0-4a68-9572-99a72849c8d6",
"outgoing_recurrence_status": "approved",
"journey_type": "journey_three",
"outgoing_recurrence_data": {
"minimum_recurrence_amount": 123.45,
"recurrence_amount": null,
"qr_code_initial_payment_data": {
"receiver_conciliation_id": "id",
"transaction_data": {
"transaction_key": "uuid",
"pix_transfer_key": "uuid",
"end_to_end_id": "end_to_end"
}
},
"payment_conciliation_batch_key": "uuid" or null
}
}
}
```
### Jornada 4 – journey_four
Request Body: Jornada 4
```json
{
"event_type": "baas.automatic_pix.outgoing_recurrence.status_change",
"origin_key": "8cb70dea-9fb0-4a68-9572-99a72849c8d6",
"data": {
"request_control_key": "98fc62fd-b0a0-4604-9bea-475e91a9dc82",
"outgoing_recurrence_key": "8cb70dea-9fb0-4a68-9572-99a72849c8d6",
"outgoing_recurrence_status": "approved",
"journey_type": "journey_four",
"outgoing_recurrence_data": {
"minimum_recurrence_amount": 123.45,
"recurrence_amount": null
},
"qr_code_initial_payment_data": {
"receiver_conciliation_id": "id",
"transaction_data": {
"transaction_key": "uuid" or null,
"pix_transfer_key": "uuid" or null,
"end_to_end_id": "end_to_end" or null
}
},
"payment_conciliation_batch_key": "uuid" or null
}
}
```
:::caution Atenção
Quando o usuário pagor recebe a notificação, ele pode optar por agendar o Pix ou realizar a transferência naquele momento. Caso o pagador realize instantaneamente o pagamento, será enviado o webhook do tipo `baas.automatic_pix.outgoing_recurrence.status_change` com as informações preenchidas, em caso de agendamento os valores serão `null`.
:::
### Webhook Body Params
| Campo | Tipo | Descrição | Caracteres |
|-------------------------------------- |------------|-------------------------------------------------------------------------------------------------------------------------|------------|
| `event_type` * | string | Tipo do evento reportado (exemplo: `baas.automatic_pix.outgoing_recurrence.status_change`). | 100 |
| `origin_key` * | string | Identificador único de origem do evento (UUID). | 36 |
| `data` * | Object | Objeto principal contendo os detalhes da recorrência automática. | [Objeto data](#objeto-data) |
---
### Objeto data
| Campo | Tipo | Descrição | Caracteres |
|-------------------------------------- |------------|-----------------------------------------------------------------------------------------------------|------------|
| `request_control_key` * | string | Chave de controle única da requisição (UUID4). | 36 |
| `outgoing_recurrence_key` * | string | Identificador único da recorrência automática (UUID). | 36 |
| `outgoing_recurrence_status` * | string | Status da recorrência em questão (ex: `approved`, `pending`, `rejected`, etc.) | 30 |
| `journey_type` * | enumerator | Jornada correspondente à autorização do Pix Automático (`journey_one`, `journey_two`, etc.). | [Enumeradores journey_type](#enumeradores-journey_type) |
| `outgoing_recurrence_data` * | Object | Objeto contendo informações específicas da recorrência e da jornada. | [Objeto outgoing_recurrence_data](#objeto-outgoing_recurrence_data) |
| `payment_conciliation_batch_key` | string | Identificador de agrupamento para conciliação de pagamentos. Pode ser null. | 36 ou null |
| `qr_code_initial_payment_data` | Object | (Jornada 3 e 4) Detalhamento de dados do pagamento via QR Code inicial, se houver. | [Objeto qr_code_initial_payment_data](#objeto-qr_code_initial_payment_data) |
---
### Objeto outgoing_recurrence_data
| Campo | Tipo | Descrição | Caracteres |
|----------------------------------|---------|----------------------------------------------------------------------------------------------- |------------|
| `minimum_recurrence_amount` | number | Valor mínimo da recorrência autorizada. | - |
| `recurrence_amount` | number | Valor total da recorrência (pode ser null se não aplicável). | - |
| `qr_code_initial_payment_data` | Object | (Jornada 3) Dados detalhados do pagamento inicial caso QR Code seja utilizado. | [Objeto qr_code_initial_payment_data](#objeto-qr_code_initial_payment_data) |
| `payment_conciliation_batch_key` | string | Identificador de lote/conciliação do pagamento. | 36 |
---
### Objeto qr_code_initial_payment_data
| Campo | Tipo | Descrição | Caracteres |
|---------------------------|---------|---------------------------------------------------------|------------|
| `receiver_conciliation_id`| string | Identificador único da conciliação do recebedor. | - |
| `transaction_data` | Object | Detalhes da transação associada ao QR code inicial. | [Objeto transaction_data](#objeto-transaction_data) |
---
### Objeto transaction_data
| Campo | Tipo | Descrição | Caracteres |
|---------------------|--------|---------------------------------------------|------------|
| `transaction_key` | string | Chave única da transação. | 36 |
| `pix_transfer_key` | string | Identificador da transferência Pix associada.| 36 |
| `end_to_end_id` | string | Identificador end-to-end do Pix. | 32 |
---
### Enumeradores journey_type
| Enumerador | Descrição |
|-----------------|----------------------------------------------|
| `journey_one` | Notificação direta no aplicativo bancário |
| `journey_two` | Experiência QR Code para cobrança recorrente |
| `journey_three` | Pagamento instantâneo + recorrência QR Code |
| `journey_four` | Opt-in recorrente a partir de operação Pix |
## Webhook de Status de Ordem de Pagamento
Este webhook é destinado ao reporte de alterações de status de ordens de pagamento do Pix Automático, informando sobre cancelamentos, pagamentos realizados e rejeições.
### Webhook Request Body
### Status: Cancelado (cancelled)
Request Body: Payment Order Cancelada
```json
{
"event_type": "baas.automatic_pix.payment_order.status_change",
"origin_key": "8cb70dea-9fb0-4a68-9572-99a72849c8d6",
"data": {
"payment_order_key": "8cb70dea-9fb0-4a68-9572-99a72849c8d6",
"payment_order_spi_id": "RR2222222220240429njua7shf40k",
"outgoing_recurrence_key": "98fc62fd-b0a0-4604-9bea-475e91a9dc82",
"payment_order_status": "cancelled",
"receiver_conciliation_id": "cac0b5f7-4ee2-40f1-b2ad-16902506503d",
"transaction_amount": 125.53,
"payment_order_conciliation_batch_key": "21fc62fd-b0a0-4604-9bea-475e91a9dc82",
"transaction_key": "21fc62fd-b0a0-4604-9bea-475e91a9dc56",
"incoming_pix_transfer_key": "21fc62fd-b0a0-4604-9bea-475e91a9dc56"
}
}
```
### Status: Pago (paid)
Request Body: Payment Order Paga
```json
{
"event_type": "baas.automatic_pix.payment_order.status_change",
"origin_key": "8cb70dea-9fb0-4a68-9572-99a72849c8d6",
"data": {
"payment_order_key": "8cb70dea-9fb0-4a68-9572-99a72849c8d6",
"payment_order_spi_id": "RR2222222220240429njua7shf40k",
"outgoing_recurrence_key": "98fc62fd-b0a0-4604-9bea-475e91a9dc82",
"payment_order_status": "paid",
"receiver_conciliation_id": "cac0b5f7-4ee2-40f1-b2ad-16902506503d",
"transaction_amount": 125.53,
"payment_order_conciliation_batch_key": "21fc62fd-b0a0-4604-9bea-475e91a9dc82",
"transaction_key": "21fc62fd-b0a0-4604-9bea-475e91a9dc56",
"incoming_pix_transfer_key": "21fc62fd-b0a0-4604-9bea-475e91a9dc56",
"paid_at": "2021-10-22T20:30:23.459Z"
}
}
```
### Status: Rejeitado (rejected)
Request Body: Payment Order Rejeitada
```json
{
"event_type": "baas.automatic_pix.payment_order.status_change",
"origin_key": "8cb70dea-9fb0-4a68-9572-99a72849c8d6",
"data": {
"payment_order_key": "8cb70dea-9fb0-4a68-9572-99a72849c8d6",
"payment_order_spi_id": "RR2222222220240429njua7shf40k",
"outgoing_recurrence_key": "98fc62fd-b0a0-4604-9bea-475e91a9dc82",
"payment_order_status": "rejected",
"receiver_conciliation_id": "cac0b5f7-4ee2-40f1-b2ad-16902506503d",
"transaction_amount": 125.53,
"payment_order_conciliation_batch_key": "21fc62fd-b0a0-4604-9bea-475e91a9dc82"
}
}
```
:::info Informação
As ordens de pagamento rejeitadas são enviadas após o esgotamento do número máximo de tentativas (caso a recorrência permita retentativas). Neste caso, os campos `transaction_key` e `incoming_pix_transfer_key` não são incluídos no payload.
:::
### Webhook Body Params - Payment Order
| Campo | Tipo | Descrição | Caracteres |
|-------------------------------------- |------------|-------------------------------------------------------------------------------------------------------------------------|------------|
| `event_type` * | string | Tipo do evento reportado (`baas.automatic_pix.payment_order.status_change`). | 100 |
| `origin_key` * | string | Identificador único de origem do evento (UUID da payment order). | 36 |
| `data` * | Object | Objeto principal contendo os detalhes da ordem de pagamento. | [Objeto data](#objeto-data-payment-order) |
---
### Objeto data (Payment Order)
| Campo | Tipo | Descrição | Caracteres |
|-------------------------------------- |------------|-----------------------------------------------------------------------------------------------------|------------|
| `payment_order_key` * | string | Chave única da ordem de pagamento (UUID). | 36 |
| `payment_order_spi_id` * | string | Identificador SPI da ordem de pagamento. | 29 |
| `outgoing_recurrence_key` * | string | Identificador único da recorrência automática associada (UUID). | 36 |
| `payment_order_status` * | string | Status da ordem de pagamento (`cancelled`, `paid`, `rejected`). | 30 |
| `receiver_conciliation_id` * | string | Identificador de conciliação do recebedor (UUID). | 36 |
| `transaction_amount` * | number | Valor da transação da ordem de pagamento. | - |
| `payment_order_conciliation_batch_key` * | string | Identificador do lote de conciliação associado (UUID). | 36 |
| `transaction_key` | string | Chave única da transação (presente apenas em status `cancelled` e `paid`). | 36 |
| `incoming_pix_transfer_key` | string | Identificador da transferência PIX de entrada (presente apenas em status `cancelled` e `paid`). | 36 |
| `paid_at` | string | Data e hora do pagamento (presente apenas em status `paid`, formato ISO 8601). | - |
---
### Enumeradores payment_order_status
| Enumerador | Descrição |
|-----------------|--------------------------------------------------------------|
| `cancelled` | Ordem de pagamento cancelada pelo pagador ou recebedor |
| `paid` | Ordem de pagamento executada com sucesso |
| `rejected` | Ordem de pagamento rejeitada após esgotamento de tentativas |
## Webhook de Status de Tentativa de Ordem de Pagamento
Este webhook é destinado ao reporte de alterações de status das tentativas de execução de ordens de pagamento do Pix Automático, informando especialmente sobre tentativas rejeitadas e os motivos de rejeição.
### Webhook Request Body
### Status: Rejeitado (rejected)
Request Body: Tentativa de Payment Order Rejeitada
```json
{
"event_type": "baas.automatic_pix.payment_order_attempt.status_change",
"origin_key": "8cb70dea-9fb0-4a68-9572-99a72849c8d6",
"data": {
"request_control_key": "8cb70dea-9fb0-4a68-9572-99a72849c8d6",
"payment_order_key": "8cb70dea-9fb0-4a68-9572-99a72849c8d6",
"payment_order_attempt_key": "21fc62fd-b0a0-4604-9bea-475e91a9dc82",
"payment_order_status": "pending",
"payment_order_attempt_status": "rejected",
"transaction_amount": 125.53,
"reason": "Conta de destino inexistente",
"outgoing_recurrence_key": "98fc62fd-b0a0-4604-9bea-475e91a9dc82"
}
}
```
:::info Informação
Este webhook é enviado sempre que uma tentativa de execução de uma ordem de pagamento é rejeitada pelo SPI. A ordem de pagamento pode ter novas tentativas dependendo da configuração da recorrência e do motivo da rejeição. O campo `reason` contém a descrição do motivo da rejeição baseado no código de erro do Bacen.
:::
### Webhook Body Params - Payment Order Attempt
| Campo | Tipo | Descrição | Caracteres |
|-------------------------------------- |------------|-------------------------------------------------------------------------------------------------------------------------|------------|
| `event_type` * | string | Tipo do evento reportado (`baas.automatic_pix.payment_order_attempt.status_change`). | 100 |
| `origin_key` * | string | Identificador único de origem do evento (UUID da payment order). | 36 |
| `data` * | Object | Objeto principal contendo os detalhes da tentativa de ordem de pagamento. | [Objeto data](#objeto-data-payment-order-attempt) |
---
### Objeto data (Payment Order Attempt)
| Campo | Tipo | Descrição | Caracteres |
|-------------------------------------- |------------|-----------------------------------------------------------------------------------------------------|------------|
| `request_control_key` * | string | Chave de controle única da requisição (UUID da payment order). | 36 |
| `payment_order_key` * | string | Chave única da ordem de pagamento associada (UUID). | 36 |
| `payment_order_attempt_key` * | string | Chave única da tentativa de pagamento (UUID). | 36 |
| `payment_order_status` * | string | Status atual da ordem de pagamento (`pending`, `accepted`, `cancelled`, etc.). | 30 |
| `payment_order_attempt_status` * | string | Status da tentativa de pagamento (`rejected`). | 30 |
| `transaction_amount` * | number | Valor da transação da tentativa de pagamento. | - |
| `reason` * | string | Motivo da rejeição da tentativa (descrição do erro baseado no código Bacen). | 200 |
| `outgoing_recurrence_key` * | string | Identificador único da recorrência automática associada (UUID). | 36 |
---
### Enumeradores payment_order_attempt_status
| Enumerador | Descrição |
|-----------------|-------------------------------------------------------------------|
| `rejected` | Tentativa de pagamento rejeitada pelo SPI por erro específico |
## Webhook para tentativa de ordem de pagamento não liquidada
Webhook destinado a notificar quando uma tentativa de ordem de pagamento foi aceita mas não foi liquidada no prazo esperado.
### Webhook Request Body
Request Body: Tentativa de ordem de pagamento não liquidada
```json
{
"webhook_type": "baas.automatic_pix.payment_order_attempt.not_liquidated",
"webhook_datetime": "2025-10-22T21:15:00.000Z",
"data": {
"payment_order_key": "8cb70dea-9fb0-4a68-9572-99a72849c8d6",
"payment_order_spi_id": "RR2222222220240429njua7shf40k",
"outgoing_recurrence_key": "98fc62fd-b0a0-4604-9bea-475e91a9dc82",
"payment_order_status": "pending",
"receiver_conciliation_id": "cac0b5f7-4ee2-40f1-b2ad-16902506503d",
"transaction_amount": "125.53",
"payment_order_conciliation_batch_key": "21fc62fd-b0a0-4604-9bea-475e91a9dc82",
"payment_order_attempt_key": "21fc62fd-b0a0-4604-9bea-475e91a9dc83",
"payment_order_attempt_status": "not_liquidated",
"due_date": "2025-10-22",
"end_to_end_id": "E1234567890123456789012"
}
}
```
### Webhook Body Param
| Campo | Tipo | Descrição | Max. Caracteres |
|--------------------------------------|-----------|----------------------------------------------------------------------------------------------------------|-----------------|
| `webhook_type` | string | Um enumerador que define o tipo de evento sendo reportado | 100 |
| `webhook_datetime` | string | Data e hora do envio do webhook | 20 |
| `payment_order_key` | uuid4 | Chave única de identificação da ordem de pagamento. | 36 |
| `payment_order_spi_id` | string | Identificador da ordem de pagamento no SPI. | 50 |
| `outgoing_recurrence_key` | uuid4 | Chave única de identificação da recorrência de saída associada. | 36 |
| `payment_order_status` | string | Status atual da ordem de pagamento. | [Enumeradores payment_order_status](#enumeradores-payment_order_status) |
| `receiver_conciliation_id` | string | Identificação de conciliação do recebedor. | 36 |
| `transaction_amount` | number | Valor da transação da ordem de pagamento. | - |
| `payment_order_conciliation_batch_key` | uuid4 | Chave única de identificação do lote de conciliação associado. | 36 |
| `payment_order_attempt_key` | uuid4 | Chave única de identificação da tentativa de ordem de pagamento. | 36 |
| `payment_order_attempt_status` | string | Status da tentativa de ordem de pagamento. | [Enumeradores payment_order_attempt_status](#enumeradores-payment_order_attempt_status) |
| `due_date` | string | Data de vencimento da tentativa de ordem de pagamento (formato YYYY-MM-DD). | 10 |
| `end_to_end_id` | string | Chave de idempotência de uma transação Pix dentro do SPI. | 32 |
### Enumeradores payment_order_status
| Enumerador | Descrição |
|-----------------------|----------------------------------------------------|
| `pending_conciliation`| Aguardando conciliação. |
| `pending` | Pendente e aguardando pagamento. |
| `paid` | Paga com sucesso. |
| `rejected` | Rejeitada e não será processada. |
| `cancelled` | Cancelada antes do pagamento. |
### Enumeradores payment_order_attempt_status
| Enumerador | Descrição |
|-----------------|-------------------------------------------------------------------|
| `sent` | Tentativa de pagamento enviada |
| `accepted` | Tentativa de pagamento aceita |
| `rejected` | Tentativa de pagamento rejeitada pelo SPI por erro específico |
| `not_liquidated`| Tentativa de pagamento aceita mas não liquidada no prazo esperado |