1. Contexto
Este guia descreve o fluxo de uso da nossa API para o pagador autorizar e gerenciar recorrências de Pix Automático. Atualmente, o foco está no lado do pagador, incluindo autorizações via proposta direta ou leitura de QR Codes, e gerenciamento de autorizações ativas.
2. Pré-requisitos
Antes de utilizar o Pix Automático como pagador, é necessário:
- Estar autenticado com token válido da nossa API;
- Possuir client_id e client_secret ativos;
- Ter webhook de notificação configurado (opcional, mas recomendado);
- Ter recebido uma proposta de recorrência ou lido um QR Code válido.
3. Jornada 1 – Proposta recebida via relacionamento direto
O recebedor envia a proposta de autorização de Pix Automático diretamente ao pagador.
- A proposta é recebida via webhook (se configurado);
- O pagador deve autorizar ou rejeitar a solicitação.
API para autorizar ou rejeitar:
POST /v1/accounts/{accountId}/recurrences-requests/{requestRecId}/authorization
Exemplo de payload:
{
"acceptance": true,
"useAccountLimit": true,
"rejectionCode": "<string>",
"maximumValue": "<double>",
"municipalityCode": "<string>"
}
Para autorizar ou rejeitar uma recorrência via jornada 1, envie uma requisição para a API: POST/v1/accounts/{accountId}/recurrences-requests/{requestRecId}/authorization O resultado da requisição e da recorrência será enviado para o webhook caso esteja configurado. A Recorrência poderá ter os status APROVED ou REJECTED e a Solicitação de Recorrência poderá ter os status ACCEPTED ou REJECTED. |
4. Jornada 2 – QR Code com dados da recorrência
O pagador escaneia um QR Code que contém os dados da proposta de recorrência.
- Decodificar o QR Code:
POST /v1/qrcode/decoding
- Apresentar os dados ao usuário.
- Ativar recorrência (tópico 7. Ativar/Autorizar Recorrência):
POST /v1/accounts/{accountId}/recurrence
O resultado da solicitação de recorrência será enviado para o webhook caso esteja configurado. A Solicitação de Recorrência poderá ter os status SENDING_APPROVAL e APPROVED. |
5. Jornada 3 – QR Code com recorrência + 1ª cobrança
- Decodificar QR Code:
POST /v1/qrcode/decoding
- Apresente os dados do pagamento e da recorrência ao usuário;
- Aguarde a única autorização para executar as duas ações;
- Após obter a autorização, execute o fluxo de envio de Pix Cobrança imediata:
POST /v1/accounts/{accountId}/withdraw
- Ativar recorrência (tópico 7. Ativar/Autorizar Recorrência):
POST /v1/accounts/{accountId}/recurrence
6. Jornada 4 – QR Code com cobrança futura + oferta de recorrência
- Decodificar QR Code:
POST /v1/qrcode/decoding
- Apresente apenas os dados do pagamento ao usuário;
- Aguarde autorização para executar o pagamento;
- Execute o fluxo de envio de Pix Cobrança com vencimento ou de um QR Code estático, conforme realizado
atualmente:
POST /v1/accounts/{accountId}/withdraw
- Apresente os dados da recorrência como oferta e aguarde autorização.
- Exibir oferta de recorrência e ativar (tópico 7. Ativar/Autorizar Recorrência).
7. Ativar/Autorizar Recorrência
- Após ler o QR Code ou receber a proposta, o pagador ativa a recorrência com a seguinte chamada:
POST /v1/accounts/{accountId}/recurrence
- O retorno indicará que a solicitação está em processamento. A autorização pode assumir os status:
- SENDING_APPROVAL
- APPROVED
Notificação via webhook será enviada automaticamente se configurada. |
8. Configurar Recorrência
No contexto do Pix Automático, o pagador tem a opção de incluir ou modificar algumas configurações relacionadas à recorrência autorizada e ativa. Isso inclui definir um valor máximo permitido para as cobranças e a autorização para utilizar o limite de crédito da conta durante a liquidação.
Por exemplo, se o pagador possui uma recorrência com valor fixo e deseja estabelecer um limite, o Pix Automático será realizado apenas se o valor da cobrança não exceder o valor máximo configurado. Caso contrário, o Pix Automático não será efetuado, e o pagador receberá uma notificação.
PATCH /v1/accounts/{accountId}/recurrences/{recId}/configure
Exemplo de payload:
{
"useAccountLimit": true,
"maximumValue": 100.00
}
| Caso tenha o webhook configurado será enviado a aprovação e a recorrência permanecerá com status APPROVED. |
9. Cancelar Recorrência
Quando o usuário pagador cancelar uma autorização, o usuário recebedor não estará mais autorizado a realizar
cobranças vinculadas àquela recorrência na modalidade de Pix Automático. Cobranças vinculadas à recorrência serão canceladas, exceto aquelas com vencimento na data do cancelamento, que já estarão em processamento.
POST /v1/accounts/{accountId}/recurrences/{recId}/cancel
| Caso tenha o webhook configurado será enviado o cancelamento e a recorrência permanecerá com status CANCELED. |
10. Consultar Recorrências
- Consultar uma recorrência específica:
GET /v1/accounts/{accountId}/recurrences/{recId}
- Listar recorrências:
GET /v1/accounts/{accountId}/recurrences
11. Histórico de Recorrências
Permite visualizar o histórico de autorizações, modificações, recusas e cancelamentos.
GET /v1/accounts/{accountId}/recurrences/{recId}/histories
12. Consultar Solicitações de Recorrência
- Solicitação específica:
GET /v1/accounts/{accountId}/recurrencesrequests/{requestRecId}
- Listar solicitações:
GET /v1/accounts/{accountId}/recurrencesrequests
13. Gestão de Cobranças Recorrentes
Cobranças recorrentes são geradas com base nas autorizações ativas. O pagador pode cancelar uma cobrança até 23h59 do dia anterior à data programada.
- Consultar cobranças recorrentes:
GET /v1/accounts/{accountId}/billings
- Cancelar uma cobrança:
POST /v1/accounts/{accountId}/billings/{txid}/cancel
| Caso tenha o webhook configurado será enviado a solicitação de cancelamento e a cobrança permanecerá com status CANCELED. |
14. Webhook de Notificação
Configure o webhook para receber notificações automáticas de eventos relacionados a Pix Automático.
- Criar ou atualizar:
PUT /v1/autopix/webhook
O cadastro de webhook por esta API será utilizado apenas para o fluxo de PIX automático. |
- Visualizar:
GET /v1/autopix/webhook
- Remover:
DELETE /v1/autopix/webhook
Eventos do Webhook
| Exemplo de conteúdo do webhook | Quando é enviado |
| { "message": "This is a webhook configuration test" } | Enviado no momento de configuração (PUT /v1/autopix/webhook). Usado para testar a comunicação. |
{ "requestRecId": "SC2311444720250711DKrdMiWQwPY", "recId": "RN3521041020250711TEsG8Fr7t7d", "aggregateId": "0197faf3-3378-7cde-d0a4-2c5f3cbc2be1", "createdAt": 1752261932016, "cancellation": { "id": null, "createdAt": null, "requester": null, "code": null, "description": null, "requesterTaxId": null, "statusAckId": null }, "status": "RECEIVED", "integrationStatus": "SENDING_RECEIVING_CONFIRMATION", "expirationDate": 1752322631926, "recipient": { "account": { "branch": "1", "number": "487031" }, "taxDocument": { "type": "CNPJ", "number": "{{CNPJ}}" }, "participantIspb": "23114447" }, "recPayload": "{\"recId\":\"RN3521041020250711TEsG8Fr7t7d\",\"contractLink\":{\"contract\":\"1752261889\",\"debtor\":null,\"object\":\"streaming\"},\"calendar\":{\"initialDate\":\"2025-07-13\",\"finalDate\":null,\"frequencyType\":\"MNTH\"},\"value\":{\"recValue\":29.50,\"receiverMinimumValue\":null},\"receiver\":{\"cnpj\":\"50547282000110\",\"name\":\"Receiver Store\",\"participantIspb\":\"35210410\"},\"updates\":[{\"status\":\"CREATED\",\"datetime\":\"2025-07-11T19:24:49.218\"}],\"creationDateTime\":\"2025-07-11T19:24:49.218\",\"retryPolicy\":\"NOT_ALLOWED\"}", "statusAckId": "IS23114447202507116zBqc82DTr3", "accountId": "{{accountId}}", "mediatorId": "{{mediatorId}}" } | Enviado para requisição de recorrência da jornada 1. integrationStatus: SENDING_RECEIVING_CONFIRMATION. |
{ "recId": "RN3521041020250711seT7q6d0BDF", "createdAt": 1752244242890, "updatedAt": 1752244242890, "aggregateId": "0197f9e5-49c9-f1d0-ab80-f98b6eb84d43", "creationDateTime": 1706745600000, "contractLink": { "debtor": { "name": "Directa Bet", "taxDocument": { "type": "CPF", "number": "{{CPF}}" } }, "contract": "RR1234595456", "object": "streaming" }, "calendar": { "initialDate": "2025-04-25", "finalDate": null, "frequencyType": "MIAN" }, "retryPolicy": "ALLOWED_3R_7D", "payer": { "taxDocument": { "type": "CNPJ", "number": "{{CNPJ}}" }, "participantIspb": "23114447", "account": { "number": "990", "branch": "1" }, "municipalityCode": "1200344", "name": "fdfsdf" }, "receiver": { "cnpj": "{{CNPJ}}", "name": "Receiver", "participantIspb": "35210410" }, "value": { "recValue": 20, "receiverMinimumValue": null }, "status": "APPROVED", "integrationStatus": "SENDING_APPROVAL", "activation": { "journey": "JOURNEY_2", "journeyDateTime": 1752244242889 }, "authorization": { "id": "IS3521041020250711UAo7DM7iDna", "createdAt": 1752244242890, "updatedAt": 1752244242890, "acceptance": true, "rejectionCode": null, "statusAckId": null, "elapsedTime": null, "flow": null }, "limits": { "useAccountLimit": false, "maximumValue": null }, "cancellation": { "id": null, "requesterTaxId": null, "requester": null, "code": null, "description": null, "statusAckId": null, "createdAt": null }, "accountId": "{{accountId}}", "mediatorId": "{{mediatorId}}" } | Enviado ao aprovar uma recorrência. O integrationStatus SENDING_APPROVAL é enviado após a aprovação da recorrência, durante a comunicação com o BACEN. |
{ "recId": "RN3521041020250711seT7q6d0BDF", "createdAt": 1752244242890, "updatedAt": 1752244249333, "aggregateId": "0197f9e5-49c9-f1d0-ab80-f98b6eb84d43", "creationDateTime": 1706745600000, "contractLink": { "debtor": { "name": "Directa Bet", "taxDocument": { "type": "CPF", "number": "{{CPF}}" } }, "contract": "RR1234595456", "object": "streaming" }, "calendar": { "initialDate": "2025-04-25", "finalDate": null, "frequencyType": "MIAN" }, "retryPolicy": "ALLOWED_3R_7D", "payer": { "taxDocument": { "type": "CNPJ", "number": "{{CNPJ}}" }, "participantIspb": "23114447", "account": { "number": "990", "branch": "1" }, "municipalityCode": "1200344", "name": "fdfsdf" }, "receiver": { "cnpj": "{{CNPJ}}", "name": "Receiver", "participantIspb": "35210410" }, "value": { "recValue": 20, "receiverMinimumValue": null }, "status": "APPROVED", "integrationStatus": "APPROVED", "activation": { "journey": "JOURNEY_2", "journeyDateTime": 1752244242889 }, "authorization": { "id": "IS3521041020250711UAo7DM7iDna", "createdAt": 1752244242890, "updatedAt": 1752244242890, "acceptance": true, "rejectionCode": null, "statusAckId": "IS3521041020250711FctUXVpDyDo", "elapsedTime": "26414", "flow": "EXTERNAL" }, "limits": { "useAccountLimit": false, "maximumValue": null }, "cancellation": { "id": null, "requesterTaxId": null, "requester": null, "code": null, "description": null, "statusAckId": null, "createdAt": null }, "accountId": "{{accountId}}", "mediatorId": "{{mediatorId}}" } | Enviado ao aprovar uma recorrência. Após o sucesso na comunicação, o integrationStatus recebe o valor APPROVED. |
|
Em anexo, disponibilizamos as collections para realização dos testes e integração.
Suporte
Para dúvidas ou acompanhamento de chamados, acesse: Portal de Suporte