1. Contexto


Este guia descreve o fluxo de uso da nossa API para o fluxo do recebedor explicando como acontece as etapas de criação das recorrências, solicitação de recorrências e a cobrança nas APIs Flagship conforme cada Jornada.


2. Pré-requisitos


Antes de utilizar o Pix Automático como recebedor, é necessário:

  • Estar autenticado com token válido da nossa API;
  • Possuir client_id e client_secret ativos;
  • Ter webhook de notificação configurado.


Cadastro do Recebedor 


Para cadastrar um novo recebedor é preciso chamar a API: 


POST /api/v1/accounts/:accountId/receivers 


O Serviço realizara o cadastro das contas do documento informado na requisição. 


⚠️ Observações Importantes

Não é permitido editar ou remover um recebedor, sendo necessário a abertura de um chamado.


3. Jornada 1


Jornada de autorização iniciada com a criação de uma solicitação de confirmação de recorrência, enviada ao PSP Pagador por meio de mensagem via SPI. Para utilizar esta jornada, siga os passos abaixo: 


- Execute o fluxo criar recorrência (5.1 Criar recorrência);

- Execute o fluxo de criar solicitação de confirmação de recorrência (8.1 Criar solicitação de confirmação de recorrência).


Será enviado para o webhook a notificação de uma nova recorrência e a atualização de seu status.


4. Jornada 2


Jornada de autorização com QR Code contendo apenas os dados da recorrência. Para utilizar esta jornada, siga os passos abaixo:


- Execute o fluxo criar location do payload de recorrência (7.1 Criar location do payload de recorrência);

- Execute o fluxo criar recorrência (5.1 Criar recorrência), informando o ID da Location;

- Execute o fluxo consultar uma recorrência (5.3 Consultar recorrência) ou fluxo alternativo para gerar imagem do QR Code e Pix copia e cola composto (6. Fluxo alternativo para gerar imagem do QR Code e Pix Copia e Cola Composto).


5. Gestão de recorrências


Recorrência é o conjunto de parâmetros que contém as características de uma recorrência de cobranças. As informações da recorrência compreendem os dados do usuário recebedor, do devedor, do pagador e do objeto das cobranças recorrentes, bem como sua periodicidade, data de início e o valor do débito (para recorrências de valor fixo). A recorrência é criada pelo usuário recebedor e só permite o envio das instruções de pagamento ao PSP pagador após a confirmação do usuário pagador.


5.1 Criar recorrência


Para criar uma recorrência, envie uma requisição para o endpoint: 


POST /v1/accounts/{{accountID}}/rec 


Estes serviços retornarão no response o resultado da requisição.


5.2 Revisar recorrência


Para revisar uma recorrência, envie uma requisição para o endpoint:


PATCH /v1/accounts/{{accountID}}/rec/{idRec


Essa ação permite tanto o cancelamento quanto a atualização de informações da recorrência.


5.3 Consultar recorrência


- Consultar dados de uma recorrência: GET /v1/accounts/{accountId}/rec/{idRec} 

- Listar recorrências de uma conta: GET /v1/accounts/{accountId}/rec 


6. Fluxo alternativo para gerar imagem do QR Code e Pix Copia e Cola Composto 


Ao utilizar a API, o usuário recebedor deve criar a imagem do QR Code, pois a API Pix não prevê o retorno dessa informação, oferecendo apenas a informação do “Pix copia e cola” que é retornado no endpoint de busca da recorrência ( GET GET /v1/accounts/{accountId}/rec/{idRec} ). 


7. Configuração e remoção de locations para uso de payloads de recorrências 


Conjunto de serviços destinados a gerenciar a configuração e a remoção de locations para o uso dos payloads de recorrências.


7.1 Criar location do payload de recorrência:


Para criar location do payload de recorrência, envie uma requisição para o endpoint: 


POST /accounts/{{accountId}}/locrec


7.2 Consultar locations cadastradas 


Para consultar uma lista de locations cadastradas, envie uma requisição para o endpoint:


GET /accounts/{{accountId}}/locrec


Os dados das locations cadastradas serão retornados no corpo da resposta. 


7.3 Recuperar location no payload 


Para recuperar a location no payload individualmente, envie uma requisição para o endpoint: 


GET /accounts/{{accountId}}/locrec/{id}


Os dados da locations serão retornados no corpo da resposta 


7.4 Desvincular uma recorrência de uma location 


Para desvincular uma recorrência de uma location, envie uma requisição para o endpoint:


DELETE /accounts/{{accountId}}/locrec/{id}/idRec


8. Gestão de solicitação de confirmação de recorrências 


A solicitação de confirmação de recorrência, referente à Jornada 01, consiste no envio de uma mensagem ao PSP pagador para que ele notifique o usuário pagador sobre a recorrência de cobranças. Com a confirmação do usuário, os pagamentos futuros podem ser realizados via Pix Automático. 

A gestão de solicitações de confirmação de recorrências abrange os serviços disponibilizados para criar, consultar e revisar solicitações de recorrências.  

 

8.1 Criar solicitação de confirmação de recorrência:


Para criar uma solicitação de confirmação de recorrência, envie uma requisição para o endpoint:


POST /v1/accounts/{accountId}/solicRec 


O sistema enviará a solicitação via solução de mensageria Pix, retornando na própria chamada de API que a solicitação está sendo processada. 


8.2 Revisar solicitação de confirmação de recorrência 


Para revisar solicitação de confirmação de recorrência, envie uma requisição para o endpoint: 


PATCH /accounts/{accountId}/solicRec/{idSolicRec} 


8.3 Consultar solicitação de confirmação de recorrência 


Para consultar solicitação de confirmação de recorrência, envie uma requisição para o endpoint: 


GET /accounts/{accountId}/solicRec/{idSolicRec} 


9. Gestão de cobranças recorrentes


Cobranças recorrentes são cobranças periódicos realizados pelo usuário recebedor a um pagador (que pode ou não ser o usuário devedor), geralmente em troca de um serviço. 

As instruções de pagamento são informações que o recebedor envia, através de seu PSP, para o PSP do pagador agendar uma transação de Pix Automático. Para enviar uma instrução de pagamento, o pagador deve ter previamente autorizado o recebedor. Em essência, a instrução de pagamento é o objeto da cobrança em si. 

A gestão de cobranças recorrentes permite criar, revisar, consultar e solicitar retentativas para as cobranças recorrentes. 


9.1 Criar cobrança recorrente 


Para criar uma cobrança recorrente, envie uma requisição para o endpoint: 


POST /accounts/{accountId}/cobr/ 


9.2 Revisar cobrança recorrente 


Para revisar uma cobrança, envie uma requisição para o endpoint: 


PATCH /accounts/{accountId}/cobr/{txid} 


9.3 Consultar uma cobrança recorrente 


Para consultar uma cobrança recorrente, envie uma requisição para o endpoint:


GET /accounts/{accountId}/cobr/{txid} 


Os dados da cobrança recorrente serão retornados no corpo da resposta.


9.4 Consultar lista de cobranças recorrentes 


Para consultar uma lista de cobranças, envie uma requisição para o endpoint:


GET /accounts/{accountId}/cobr 


Os dados das cobranças recorrentes serão retornados no corpo da resposta. 


9.5 Solicitar retentativa de cobrança


Para solicitar a retentativa de cobrança, envie uma requisição para o endpoint:


POST /accounts/{accountId}/cobr/{txid}/retentativa/{data} 


10. Controle do webhook 


- Cadastrar ou atualizar a configuração de webhook, utilize o serviço da API:


PUT /v1/autopix/receiver/webhook 


- Visualizar a configuração de webhook, utilize: 


GET/v1/autopix/receiver/webhook 


- Desativar configuração: 


DELETE /v1/autopix/receiver/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/receiver/webhook). Usado para testar a comunicação.
{
"idRec": "RRXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX",
"status": "CRIADA",
"atualizacao": [{ "status": "CRIADA", "data": "2025-09-23T17:21:29.405Z" }],
"ativacao": { "tipoJornada": "AGUARDANDO_DEFINICAO", "dadosJornada": {} }
}
Enviado quando uma recorrência é criada / atualizada
{
"idRec": "RRXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX",
"status": "CANCELADA",
"atualizacao": [
{ "status": "CANCELADA", "data": "2025-09-23T17:23:33.585Z" },
{ "status": "CRIADA", "data": "2025-09-23T17:21:29.405Z" }
],
"ativacao": { "tipoJornada": "AGUARDANDO_DEFINICAO", "dadosJornada": {} },
"encerramento": {
"cancelamento": {
"solicitante": "USUARIO_RECEBEDOR",
"codigo": "SLCR",
"descricao": "Cancelamento solicitado pelo usuário recebedor"
}
}
}
Enviado quando uma recorrência é criada / atualizada
{
"idRec": "RRXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX",
"status": "APROVADA",
"atualizacao": [
{ "status": "CRIADA", "data": "2025-09-23T17:24:39.737Z" },
{ "status": "APROVADA", "data": "2025-09-23T17:25:12.697Z" }
],
"ativacao": { "tipoJornada": "JORNADA_1", "dadosJornada": {} }
}
Enviado quando uma recorrência é aprovada
{
"idRec": "RRXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX",
"txid": "321412342342342342342342342342",
"status": "CRIADA",
"atualizacao": [{ "status": "CRIADA", "data": "2025-09-23T17:27:52.892Z" }],
"tentativas": [
{
"dataLiquidacao": "2025-09-26",
"tipo": "AGND",
"status": "SOLICITADA",
"endToEndId": "E23114447202509261500CweWj9lilGJ",
"atualizacao": [
{ "status": "SOLICITADA", "data": "2025-09-23T17:27:52.892Z" }
]
}
]
}
Enviado quando uma cobrança é criada
{
"idRec": "RRXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX",
"txid": "321412342342342342342342342342",
"status": "ATIVA",
"atualizacao": [
{ "status": "CRIADA", "data": "2025-09-23T17:27:52.892Z" },
{ "status": "ATIVA", "data": "2025-09-23T17:28:02.969Z" }
],
"tentativas": [
{
"dataLiquidacao": "2025-09-26",
"tipo": "AGND",
"status": "AGENDADA",
"endToEndId": "E23114447202509261500CweWj9lilGJ",
"atualizacao": [
{ "status": "SOLICITADA", "data": "2025-09-23T17:27:52.892Z" },
{ "status": "AGENDADA", "data": "2025-09-23T17:28:02.969Z" }
]
}
]
}
Enviado quando uma cobrança fica ativa
{
"idRec": "RRXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX",
"txid": "321412342342342342342342342342",
"status": "CANCELADA",
"atualizacao": [
{ "status": "CRIADA", "data": "2025-09-23T17:27:52.892Z" },
{ "status": "ATIVA", "data": "2025-09-23T17:28:02.969Z" },
{ "status": "CANCELADA", "data": "2025-09-23T17:30:16.666Z" }
],
"tentativas": [
{
"dataLiquidacao": "2025-09-26",
"tipo": "AGND",
"status": "CANCELADA",
"endToEndId": "E23114447202509261500CweWj9lilGJ",
"atualizacao": [
{ "status": "SOLICITADA", "data": "2025-09-23T17:27:52.892Z" },
{ "status": "AGENDADA", "data": "2025-09-23T17:28:02.969Z" },
{ "status": "CANCELADA", "data": "2025-09-23T17:30:16.666Z" }
]
}
],
"encerramento": {
"cancelamento": {
"solicitante": "USUARIO_RECEBEDOR",
"codigo": "SLCR",
"descricao": "Receiver requested cancellation"
}
}
}
Enviado quando uma cobrança é cancelada pelo recebedor


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