Como implementar Pix Automático no seu ERP: guia técnico com a API da Pluggy
Implementar Pix Automático no seu ERP via API leva menos tempo do que parece — e resolve de uma vez o problema de cobranças recorrentes que ainda dependem de boleto ou débito automático. Neste guia técnico, vamos do conceito à primeira cobrança em produção: arquitetura, endpoints, payloads e tratamento de erro.
Sem overhead conceitual, só o que você precisa para implementar.
Neste guia você vai implementar:
- Setup da API de Pix Automático da Pluggy
- Criação de mandato de cobrança recorrente (valor fixo e variável)
- Fluxo de consentimento e tratamento de webhooks
- Agendamento automático e retentativas em caso de falha
- Testes em sandbox antes de ir para produção
O que é o Pix Automático e por que faz diferença para ERPs
O Pix Automático (também conhecido como pix recorrente) é o débito recorrente via Pix. O usuário autoriza uma vez, e os pagamentos subsequentes acontecem automaticamente, sem nenhuma ação adicional dele.
Para ERPs que gerenciam cobranças de PMEs, isso muda o processo de forma concreta:
| Método | Liquidação | Inadimplência | Chargeback | MDR | | ------------------ | ---------- | ------------- | ---------- | -------- | | Boleto | D+1 a D+3 | Alta | Não | Baixo | | Cartão recorrente | D+30 | Média | Sim | Alto | | Débito automático | D+1 | Média | Não | Médio | | Pix Automático | D+0 | Baixa | Não | R$ 0 |
Além disso, o usuário não sai da sua plataforma para autorizar — todo o fluxo de consentimento pode ser disparado de dentro do ERP.
A Pluggy é uma Iniciadora de Transação de Pagamento (ITP) autorizada pelo Banco Central. Toda a implementação de Pix Automático descrita aqui usa a API da Pluggy como camada de infraestrutura entre o seu ERP e o SPI (Sistema de Pagamentos Instantâneos) do Bacen.
Arquitetura da integração de Pix Automático via API
Antes de escrever a primeira linha de código, entenda o fluxo de dados.
ERP → Pluggy API → Banco Central (SPI) → Banco do cliente final
O seu ERP faz chamadas para a API da Pluggy. A Pluggy cuida de tudo que fica entre você e o banco do seu cliente: autenticação no SPI, gestão do mandato de cobrança, retentativas e webhooks de status.
Duas opções de integração
➡️ Payment Gateway (hosted): a Pluggy redireciona o usuário para uma página de autorização gerenciada por ela. Você recebe o resultado via webhook. Menos código no seu lado, fluxo mais rápido de implementar.
➡️ API direta: você constrói o fluxo de consentimento dentro da sua interface. Mais controle sobre a experiência do usuário, mais trabalho de implementação.
Para ERPs que querem manter o usuário dentro da plataforma do início ao fim, a API direta costuma ser a opção escolhida. O guia abaixo cobre as duas, mas com foco nos endpoints que você vai usar no dia a dia da integração de Pix Automático.
Setup inicial: credenciais, recipient e webhooks
Pré-requisitos
Você vai precisar de:
- Credenciais de acesso à API da Pluggy (clientId + clientSecret)
- Um PaymentRecipient criado para receber os pagamentos
- Uma callbackUrl configurada para receber webhooks de status
- Sandbox ativo para testes antes de ir para produção
Criando o PaymentRecipient
O recipient é o destino dos pagamentos recorrentes. Crie uma vez, reutilize em todos os mandatos.
POST https://api.pluggy.ai/payments/recipients Authorization: Bearer {your_api_key} Content-Type: application/json { "name": "Empresa XYZ Ltda", "taxNumber": "12.345.678/0001-99", "paymentInstitutionId": "60746948-xxxx-xxxx-xxxx-xxxxxxxxxxxx", "account": { "branch": "0001", "number": "123456", "type": "CHECKING" } }
A resposta traz o recipientId. Guarde esse valor: ele é obrigatório em todo mandato de cobrança.
Configurando os webhooks
Defina a callbackUrl que vai receber as notificações de status de cada cobrança. A URL precisa ser HTTPS e responder com 2xx.
POST https://api.pluggy.ai/webhooks Authorization: Bearer {your_api_key} Content-Type: application/json { "event": "payment_request/updated", "url": "https://seuapp.com.br/webhooks/pluggy", "clientId": "{seu_client_id}" }
Repita o processo para os três eventos principais:
payment_request/updated— status geral do mandatoautomatic_pix_payment/created— uma cobrança foi criada no cicloautomatic_pix_payment/completed— cobrança liquidada com sucesso
Como criar um mandato de cobrança Pix Automático
Aqui está o coração da implementação. O mandato define quem paga, quanto, com qual frequência e por quanto tempo.
Endpoint da API de Pix Automático
POST /payments/requests/automatic-pix
Exemplo 1: valor fixo (assinatura mensal de R$ 99)
Caso de uso típico: SaaS, academia, coworking, qualquer serviço com mensalidade fixa.
{ "description": "Assinatura mensal ERP XYZ", "recipientId": "recipient_abc123", "interval": "MONTHLY", "startDate": "2025-02-01", "fixedAmount": 9900, "callbackUrls": { "success": "https://seuapp.com.br/pagamentos/sucesso", "error": "https://seuapp.com.br/pagamentos/erro", "pending": "https://seuapp.com.br/pagamentos/pendente" }, "firstPayment": { "date": "2025-02-01", "amount": 9900, "description": "Primeira mensalidade ERP XYZ" } }
Campos obrigatórios:
recipientId: ID do recipient criado no setupinterval:WEEKLY,MONTHLY,QUARTERLY,SEMESTERouYEARLYstartDate: data de início das cobranças (formato ISO 8601)fixedAmountou os campos de valor variável (veja abaixo)
Exemplo 2: valor variável (conta de consumo entre R$ 50 e R$ 300)
Caso de uso: contas de utilities, serviços por consumo, SaaS com planos variáveis.
{ "description": "Cobrança mensal por consumo", "recipientId": "recipient_abc123", "interval": "MONTHLY", "startDate": "2025-02-01", "minimumVariableAmount": 5000, "maximumVariableAmount": 30000, "callbackUrls": { "success": "https://seuapp.com.br/pagamentos/sucesso", "error": "https://seuapp.com.br/pagamentos/erro", "pending": "https://seuapp.com.br/pagamentos/pendente" }, "firstPayment": { "date": "2025-02-01", "amount": 12000, "description": "Cobrança de fevereiro por consumo" } }
Os valores são em centavos (R$ 50 = 5000, R$ 300 = 30000). Atenção a esse detalhe para evitar cobranças incorretas.
Fluxo de autorização e webhooks de Pix Automático
O fluxo de consentimento
Após criar o mandato, a API retorna um campo paymentUrl. Redirecione o usuário para essa URL.
O usuário vai autenticar no app do banco dele e autorizar o débito automático. O processo leva menos de dois minutos. A partir dali, as cobranças acontecem automaticamente na data configurada.
POST /payments/requests/automatic-pix ↓ Recebe paymentUrl na resposta ↓ Redireciona usuário → paymentUrl ↓ Usuário autoriza no banco ↓ Webhook: payment_request/updated com status ACCEPTED ou CONSENT_REJECTED
Tratamento de CONSENT_REJECTED
Se o usuário não completar a autorização em 60 minutos, o mandato expira com status CONSENT_REJECTED. Implemente esse fluxo:
// Exemplo de handler de webhook app.post('/webhooks/pluggy', (req, res) => { const { event, data } = req.body; if (event === 'payment_request/updated') { switch (data.status) { case 'ACCEPTED': // Mandato ativo. Habilitar feature no ERP. activateSubscription(data.paymentRequestId); break; case 'CONSENT_REJECTED': // Usuário não autorizou ou timeout de 60 min. // Notificar usuário e oferecer nova tentativa. handleConsentRejection(data.paymentRequestId); break; case 'COMPLETED': // Mandato encerrado (atingiu endDate ou foi cancelado). deactivateSubscription(data.paymentRequestId); break; } } if (event === 'automatic_pix_payment/completed') { // Cobrança liquidada. Dar baixa na fatura. markInvoicePaid(data.paymentId, data.amount); } res.status(200).send('OK'); });
Payload de webhook: exemplo completo
{ "id": "evt_abc123", "event": "automatic_pix_payment/completed", "createdAt": "2025-02-01T10:35:00Z", "data": { "paymentId": "pay_xyz789", "paymentRequestId": "req_abc456", "amount": 9900, "status": "COMPLETED", "completedAt": "2025-02-01T10:35:00Z" } }
Agendamento e retentativas automáticas no Pix Automático
Agendando cobranças manualmente
Para controle granular sobre cada ciclo de cobrança, use o endpoint de schedule:
POST /payments/requests/{id}/automatic-pix/schedule Authorization: Bearer {your_api_key} Content-Type: application/json { "date": "2025-02-01", "amount": 9900, "description": "Mensalidade fevereiro/2025" }
Regras importantes:
- A data de agendamento deve estar entre D+2 e D+10 a partir do vencimento configurado
- Apenas 1 pagamento por intervalo é permitido (não é possível agendar duas cobranças no mesmo ciclo mensal)
Para listar todas as cobranças agendadas de um mandato:
GET /payments/requests/{id}/automatic-pix/schedules
A resposta traz histórico completo: cobranças pagas, pendentes e falhas.
Automatic PIX Scheduler (beta)
Para ERPs com alto volume de cobranças, o Scheduler automatiza o agendamento ciclo a ciclo. Ative na criação do mandato:
{ "description": "Assinatura mensal ERP XYZ", "recipientId": "recipient_abc123", "interval": "MONTHLY", "fixedAmount": 9900, "schedulerConfiguration": { "enabled": true } }
Com o Scheduler ativo, a Pluggy cria automaticamente o próximo agendamento assim que o ciclo anterior é liquidado. Você não precisa chamar o endpoint de schedule manualmente para cada cliente.
Retentativas automáticas (beta)
Cobranças que falham por saldo insuficiente podem ser retentadas automaticamente. Configure o dia da semana em que a retentativa deve ocorrer:
{ "schedulerConfiguration": { "enabled": true }, "automaticRetriesConfiguration": { "retryDays": [3] } }
retryDays recebe um array de inteiros de 1 a 7 (representando dias da semana), com mínimo de 1 e máximo de 3 elementos. No exemplo acima, 3 corresponde a quarta-feira.
Toda retentativa gera um novo webhook automatic_pix_payment/created. Trate esse evento da mesma forma que a cobrança original: se completed, dar baixa; se falhar novamente, notificar o cliente.
Testando Pix Automático no sandbox da Pluggy
Testando sem risco
O ambiente sandbox da Pluggy replica o comportamento de produção sem movimentar dinheiro real. Você consegue:
- Criar mandatos e simular autorizações
- Disparar webhooks de teste com status diferentes
- Simular CONSENT_REJECTED e fluxos de retentativa
Para acessar o sandbox, use as credenciais de sandbox disponíveis no dashboard em dashboard.pluggy.ai.
Documentação técnica de referência
| Recurso | URL | | ---------------------------- | ---------------------------------------------------------------------------------------------------------------------------------- | | Pix Automático (visão geral) | https://docs.pluggy.ai/docs/pix-automatico | | Getting Started | https://docs.pluggy.ai/docs/getting-started-with-pix-automatico | | Automatic PIX Scheduler | https://docs.pluggy.ai/docs/automatic-pix-scheduler | | Retentativas automáticas | https://docs.pluggy.ai/docs/automatic-pix-automatic-retries | | FAQ técnico | https://docs.pluggy.ai/docs/automatic-pix-faq |
Pronto para testar?
Acesse dashboard.pluggy.ai, crie sua conta de sandbox e dispare o primeiro mandato de teste em menos de 30 minutos. Se tiver dúvida durante a implementação, entre na nossa comunidade de devs no Discord.
Perguntas frequentes sobre Pix Automático em ERPs
Pix Automático funciona para cobranças B2B (empresa para empresa)?
Para Pix Automático, o recipient deve obrigatoriamente ter CNPJ. Um recipient criado com CPF será rejeitado ao criar o mandato, com erro AUTOMATIC_PIX_PAYMENT_RECIPIENT_NOT_CNPJ. O endpoint POST /payments/recipients aceita CPF no campo taxNumber sem retornar erro, mas o problema aparece apenas ao tentar criar o mandato — atenção a esse comportamento durante os testes no sandbox.
Existe limite de valor por cobrança?
Os limites seguem as regras do Banco Central para o SPI. Consulte a documentação em docs.pluggy.ai/docs/automatic-pix-faq para os valores atualizados, pois os limites do Bacen são revisados periodicamente.
O que acontece se o banco do cliente estiver fora do ar na data de cobrança?
A cobrança entra em status PENDING e pode ser retentada via scheduler. O webhook automatic_pix_payment/created notifica cada tentativa, e o automatic_pix_payment/completed confirma quando a liquidação ocorre.
Quanto tempo leva para integrar o Pix Automático com a API da Pluggy?
Com as credenciais de sandbox em mãos e o endpoint de webhook configurado, os primeiros testes rodando levam menos de um dia de desenvolvimento. A integração completa, com todos os handlers de status e fluxo de consentimento na UI, costuma ser concluída em uma sprint.
A Pluggy é regulada para operar iniciação de pagamento?
Sim. A Pluggy é uma ITP (Iniciadora de Transação de Pagamento) autorizada pelo Banco Central do Brasil. Toda a operação de Pix Automático via API da Pluggy está dentro do arcabouço regulatório do Open Finance brasileiro.
Postado por
Victor Braga
