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:

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:

1. 1Credenciais de acesso à API da Pluggy (clientId + clientSecret)
2. 2Um PaymentRecipient criado para receber os pagamentos
3. 3Uma callbackUrl configurada para receber webhooks de status
4. 4Sandbox 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 mandato
• automaticpixpayment/created — uma cobrança foi criada no ciclo
• automaticpixpayment/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 setup
• interval: WEEKLY, MONTHLY, QUARTERLY, SEMESTER ou YEARLY
• startDate: data de início das cobranças (formato ISO 8601)
• fixedAmount ou 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 automaticpixpayment/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

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 AUTOMATICPIXPAYMENTRECIPIENTNOT_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 automaticpixpayment/created notifica cada tentativa, e o automaticpixpayment/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.