Integrando o Pix Automático - guia técnico para desenvolvedores

O Pix Automático é uma evolução significativa do sistema de pagamentos instantâneos do Brasil. Lá em 2020, o Pix já transformou o mercado, e agora o Banco Central amplia seu alcance com uma funcionalidade pensada para pagamentos recorrentes.

Neste artigo, você vai entender o funcionamento técnico do Pix Automático, como ele se diferencia de outras formas de pagamento, e como integrá-lo por meio de APIs com o Efí Bank.

Mas antes, o que é o Pix Automático?

O Pix Automático é uma funcionalidade criada pelo Banco Central que permite autorizar pagamentos recorrentes com apenas uma aprovação inicial do pagador. A cobrança é feita de forma automática, com periodicidade semanal, mensal, trimestral, semestral ou anual, conforme o contrato estabelecido entre recebedor e pagador.

Atualmente, 42% das transações via Pix no Brasil são do tipo P2B (pessoa para empresa), somando R$ 2,6 trilhões em volume transacionado. Em 2023, o Pix superou o cartão de crédito como principal meio de pagamento digital. A chegada do Pix Automático mira especialmente o mercado de cobranças recorrentes.

Conheça e integre já o Pix Automático do Efí Bank

+ Veja também: 9 vantagens de aceitar pagamentos via Pix Automático no seu negócio

Quais são os trilhos e jornadas de autorização do Pix Automático?

O Pix Automático pode ser integrado via 2 trilhos:

Arranjo Pix: baseado em push notification, QR Code e Pix Copia e Cola;
Open Finance: com iniciação de pagamento via CPF e banco.

E possui 5 jornadas que representam os diferentes fluxos de autorização, adaptados a diversas realidades de empresas e modelos de negócio:

Jornada 1 | Push Notification

Cliente informa banco/agência/conta.
Recebedor envia push via API ao banco.
Cliente aprova pelo push ou via menu do app.

“A jornada 1 é uma jornada em que você já tem ali os dados do cliente. É como se estivesse num balcão ali de uma loja ou de uma academia, por exemplo. A empresa pergunta: ‘Qual é o seu CPF? Qual é o seu nome?’ E aí ela meio que cadastra isso e envia, naquele momento, uma solicitação para você fazer a assinatura por dados bancários.”
Gabriel Fróes, Código Fonte TV

Jornada 2 | QR Code para pagamento futuro

Recebedor cria location e recorrência.
Gera QR Code Pix com vencimento futuro.
Cliente escaneia e aceita.

Jornada 3 | QR Code com pagamento imediato

Ideal para planos com taxa de adesão.
Primeiro pagamento via Pix + ativação da recorrência.

Jornada 4 | Oferta após pagamento

Cliente paga via Pix tradicional.
É convidado a autorizar recorrência subsequente.

Jornada 5 | Iniciação via Open Finance

Cliente informa CPF e banco.
É redirecionado para aprovação direta no app.

Fale com um especialista e veja como o Efí Bank pode ajudar seu negócio

Quais são os endpoints da API Pix Automático?

“O Pix Automático é um produto complexo. E essa complexidade está associada também a uma flexibilização. São 23 novos endpoints, separados em 6 grupos, e muito personalizáveis.
Matheus Rodrigues, Coordenador de Consultoria Técnica – Efí Bank

Confira abaixo quais são esses grupos:

Rec: gerencia contratos de recorrência;
SolicRec: gerencia solicitações de autorização de recorrências;
CobR: cria, consulta, atualiza e cancela cobranças recorrentes;
PayloadLocationRec: configura URLs dos payloads JSON;
WebhookRec: notifica eventos de contratos de recorrência;
WebhookCobR: notifica eventos sobre cobranças (pagamento, falhas etc.)

+ Conheça a documentação e integre a API Pix Automático

Como é o fluxo de integração do Pix Automático?

Antes de tudo, é necessário abrir uma conta PJ no Efí Bank para começar a usar. Depois, é só seguir o passo a passo básico para recebedores:

Autenticação via MTLS
Utiliza os mesmos certificados da API Pix/API Open Finance.
Criação de Location (POST /v2/recurrence/location)
Gera o idLocation usado para criar a recorrência.
Criação de Recorrência (POST /v2/recurrence)
Envia idLocation, periodicidade, valor, datas, identificador do contrato.
Geração do Pix Copia e Cola ou QR Code
A partir do retorno do endpoint de consulta da recorrência.
Solicitação de autorização (POST /v2/recurrence/request) (para Jornada 1)
Envia CPF, banco, agência e conta do cliente.
Criação de cobranças (POST /v2/recurrence/charge)
Necessário apenas para valores variáveis. Valores fixos são automatizados pelo Efí Bank.
Webhooks (recorrência e cobrança)
Configure para receber atualizações de status de aceite, recusa e pagamento.

Confira aqui o fluxograma para cada jornada de autorização >

Exemplo de chamada de API (Criação de Recorrência)


POST /v2/recurrence
{
  "idLocation": "13",
  "contractId": "academia_123",
  "start": "2025-08-01",
  "end": "2026-08-01",
  "periodicity": "MONTHLY",
  "value": 99.90
}

Para quais casos é possível fazer uso do Pix Automático?

SaaS com trial: cria cobrança futura com data de vencimento após 10, 15 ou 30 dias, por exemplo;
Academia: jornada 3 com pagamento imediato + ativação de recorrência;
Provedor de internet: jornada 3 com 1º pagamento e ativação de recorrência imediata, e possibilidade de migrar cobranças tradicionais para o modelo automático com a jornada 4;
Mensalidade escolar: jornada 4, com possibilidade de migrar cobranças futuras para o modelo automático.

“Essa jornada 4 cai perfeitamente para mensalidade escolar. Nós temos aqui dois filhos e recebemos justamente as duas cobranças ali de cada um para fazer o pagamento. Uma vez que a gente paga com Pix, aparece a opção de automatizar as próximas mensalidades. Eu achei maravilhoso.”
Vanessa Weber, Código Fonte TV

+ Veja também: Controle de mensalidades: como funciona e como automatizar suas cobranças

Boas práticas para devs

Sempre use o ambiente de homologação antes de ir para produção.
Criptografe certificados e variáveis sensíveis.
Utilize identificadores exclusivos por contrato para controle.
Teste todas as jornadas, pois cada uma possui requisitos distintos.

Use o ambiente sandbox do Efí Bank para simular cobranças, autorizações e cancelamentos de Pix Automático. A rota base de testes é: https://pix-h.api.efipay.com.br/.

O Pix Automático representa uma nova geração de cobranças recorrentes. Com a API do Efí Bank, suporte técnico durante toda a integração e apoio da comunidade de desenvolvedores no Discord, é possível implementar soluções robustas, seguras e ágeis com um fluxo claro e escalável.

Pronto para começar? Fale agora com nosso time

Esse conteúdo foi retirado do webinar feito com os especialistas técnicos do Efí Bank e participação especial do ‪@codigofontetv. Confira o material na íntegra:

FAQ – Dúvidas frequentes sobre o Pix Automático

1. É possível atualizar o valor da assinatura sem nova recorrência?

Depende do tipo:

Valor fixo: não pode ser alterado. É necessário nova cobrança e nova autorização.
Valor variável: pode ser ajustado dentro da faixa mínima (definida pelo recebedor) e máxima (pelo pagador).

Isso acontece por questões de segurança e conformidade regulatória com o Bacen, já que a recorrência de valor fixo é tratada como um contrato que precisa ser respeitado.

“Na sessão de Pix Automático, vocês vão encontrar três grandes blocos: o gerenciamento da recorrência, o gerenciamento das solicitações de recorrência e o gerenciamento das cobranças associadas. Se for cobrança com valor fixo, a gente já automatiza para vocês — a recorrência entra no sistema e o Efí Bank gera tudo. Mas se for valor variável, vocês precisam enviar os valores a cada ciclo.”
— Matheus Rodrigues, Coordenador de Consultoria Técnica no Efí Bank

2. É possível isentar o cliente de uma parcela?

Não é possível inserir valor zero. Mas a cobrança daquele ciclo pode ser cancelada.

Exemplo prático: uma academia que oferece a opção de “pausar o plano” para alunos que vão viajar e não utilizarão os serviços naquele mês. Nesse caso, em vez de tentar emitir uma parcela com valor zerado, a academia pode simplesmente cancelar a cobrança daquele mês dentro do prazo permitido, mantendo a experiência positiva para o cliente e respeitando as regras do Pix Automático.

3. Como funciona a cobrança com valor variável?

O recebedor define o valor mínimo. Isso é obrigatório.
O pagador pode definir o valor máximo autorizado por parcela.

Exemplo prático:

O recebedor cria uma recorrência com valor mínimo de R$ 50,00.
O pagador, ao autorizar, define que aceita pagar até R$ 100,00 por cobrança – caso haja uma variação do valor do ciclo.

Assim, a cobrança pode variar entre R$ 50,00 e R$ 100,00, mas nunca poderá ultrapassar o valor máximo definido pelo pagador. Se a cobrança do mês ultrapassar o limite definido, o pagamento não será agendado e o pagador será notificado.

4. O valor máximo da recorrência pode ser preenchido automaticamente?

Não. A definição e input desse valor é exclusiva do usuário pagador, junto ao seu PSP pagador (banco, fintech etc.).

Essa é uma exigência do Bacen para garantir que:

O pagador tenha total controle e consciência sobre os limites de débito;
Não haja ingerência do recebedor sobre os parâmetros de consentimento.

Além disso, essa informação (valor máximo) não é compartilhada com o recebedor nem com seu PSP. Ela permanece registrada apenas nas bases internas do PSP pagador.

5. É possível converter uma cobrança CobV para Pix Automático (CobR)?

Não. O modelo CobV (imediata com vencimento) é diferente do CobR (recorrente com autorização única).

CobV é utilizado para cobranças pontuais e avulsas, como o pagamento de uma fatura única ou de um boleto específico;
CobR, por sua vez, é voltado para cobranças recorrentes, com agendamentos automáticos e autorização única prévia do pagador, viabilizando o funcionamento do Pix Automático.

Para usar o Pix Automático, é necessário cancelar a CobV e emitir uma nova CobR.

6. Quem já usa API Pix precisa criar nova aplicação ou certificado?

Não. Pode reutilizar a aplicação e o certificado. Apenas habilite os endpoints do Pix Automático.

7. Quais SDKs estão disponíveis no API Pix Automático do Efí Bank?

Disponíveis: Java, Python, C# e Node.js
Em atualização futura e gradual: Delphi e outras.

APIs e integrações

Integrando o Pix Automático – guia técnico para devs