Começando

Este guia irá orientá-lo pelos fundamentos da criação do seu primeiro pedido de pagamento Pix Automático usando o Gateway de Pagamento da Pluggy. Você aprenderá como configurar pedidos de valores fixos e variáveis, entender os métodos disponíveis e usar a URL de pagamento para proporcionar uma experiência perfeita aos seus usuários.

1. Criando um Pedido de Pagamento#

Para iniciar um pagamento Pix Automático, você precisará criar um pedido de pagamento (mandato) através da API da Pluggy. Este pedido define o pagador, a recorrência e os detalhes do pagamento.

Exemplo: Criando um Pedido de Pagamento#

POST /payments/requests/automatic-pix
Content-Type: application/json
 
{
  "description": "Pix Automatico",
  "recipientId": "df3ed44b-f085-4b9e-b81e-7d1d4ed1476f",
  "interval": "WEEKLY",
  "startDate": "2025-06-10",
  "minimumVariableAmount": 0.01,
  "maximumVariableAmount": 0.02,
  "firstPayment": {
    "date": "2025-06-08",
    "amount": 0.03,
    "description": "Primeiro mês"
  }
}

2. Valores Fixos e Variáveis#

A Pluggy suporta pedidos de pagamento tanto de valor fixo quanto de valor variável:

• Valor Fixo: O mesmo valor é cobrado em cada recorrência (por exemplo, uma assinatura).
• Valor Variável: O valor pode mudar para cada pagamento (por exemplo, contas de serviços públicos).

Carga Útil de Valor Fixo

{
  "description": "Seu aluguel",
  "recipientId": "df3ed44b-f085-4b9e-b81e-7d1d4ed1476f",
  "interval": "MONTHLY",
  "startDate": "2025-06-10",
  "fixedAmount": 0.01,
  "firstPayment": {
    "date": "2025-06-08",
    "amount": 100,
    "description": "Aluguel"
  }
}

Carga Útil de Valor Variável

{
  "description": "Pix Automatico",
  "recipientId": "df3ed44b-f085-4b9e-b81e-7d1d4ed1476f",
  "interval": "WEEKLY",
  "startDate": "2025-06-10",
  "minimumVariableAmount": 100,
  "maximumVariableAmount": 200,
  "firstPayment": {
    "date": "2025-06-08",
    "amount": 300,
    "description": "Primeiro mês"
  }
}

3. Redirecionando o usuário para Autorizar#

Uma vez que um pedido de pagamento é criado, a Pluggy gera uma URL de pagamento. Esta URL é onde seu usuário (pagador) revisará e autorizará o mandato Pix Automático.

• Como funciona: Redirecione ou envie a URL de pagamento para seu usuário. Eles serão guiados pelo processo de autorização, que está totalmente em conformidade com os requisitos do Banco Central do Brasil.

• Exemplo de resposta:

{
  "id": "req_abc123",
  "paymentUrl": "https://pay.pluggy.ai/pix-automatico/req_abc123",
  "status": "CREATED"
}

• Melhores práticas:
  • Exiba a URL de pagamento em seu aplicativo ou envie-a por e-mail/SMS.
  • Monitore o status do pedido de pagamento via webhooks ou consultando a API.

API Direta#

Para criar uma intenção de pagamento Pix Automático via API, você precisa enviar uma solicitação POST para /payments/intents com uma carga que inclua o paymentRequestId, o CPF/CNPJ do pagador e o nome.

// https://api.pluggy.ai/payments/intents
{
  "paymentRequestId": "req_abc123", // O ID do pedido de pagamento criado anteriormente
  "connectorId": 123, // Placeholder: o id do conector da instituição do pagador (veja GET /connectors); para o fluxo de sandbox veja a seção 10
  "parameters": {
    "cpf": "12345678900", // Números de CPF
    "name": "Maria Silva" // Nome completo do pagador
  }
}

4. O que Acontece Após a Autorização?#

• Uma vez que o usuário autoriza o pedido de pagamento através da paymentUrl, a Pluggy gerará uma Intenção de Pagamento para o connectorId específico (a instituição financeira ou banco selecionado pelo usuário).
• A Intenção de Pagamento representa o pagamento agendado real e pode ser rastreada através da API da Pluggy e webhooks.
• Você receberá atualizações em tempo real sobre o status da Intenção de Pagamento, Pedido de Pagamento e PIX Automático.
  • Incluindo autorizações bem-sucedidas (PAYMENT_COMPLETED), rejeições (CONSENT_REJECTED) e expiração de consentimento (EXPIRED)
  • Timeouts de autorização são relatados como PAYMENT_TIMEOUT
  • Inclui notificações de primeiro pagamento e pagamentos futuros que estão sendo agendados
  • Mudanças no status do pedido de pagamento são notificadas via webhook payment_request/updated

5. Primeiro Pagamento#

Automaticamente, após a autorização ter sido concedida, se o primeiro pagamento estiver agendado para o mesmo dia (pagamentos imediatos), você receberá notificações de que o pagamento foi agendado e está sendo processado, e você receberá uma segunda notificação de que o pagamento foi concluído.

automatic_pix_payment/created

{
  "paymentRequestId": "624cb41e-2b76-42ac-8021-ce6b6b4ace6b",
  "automaticPixPaymentId": "8429f45a-f541-4fc3-8439-cbc8d9dc9952",
  "endToEndId": "E37943755202506111319U0da92d1b7e",
  "eventId": "71e0b4db-4e8c-401d-8ad8-5ab3ecd1f3d0",
  "event": "automatic_pix_payment/created"
}

automatic_pix_payment/completed

{
  "paymentRequestId": "624cb41e-2b76-42ac-8021-ce6b6b4ace6b",
  "automaticPixPaymentId": "8429f45a-f541-4fc3-8439-cbc8d9dc9952",
  "endToEndId": "E37943755202506111319U0da92d1b7e",
  "eventId": "71e0b4db-4e8c-401d-8ad8-5ab3ecd1f3d0",
  "event": "automatic_pix_payment/completed"
}

6. Cobrança do seu cliente#

Uma vez que o pedido de pagamento é autorizado (o status do Pedido de Pagamento é AUTHORIZED), você pode agendar novos pagamentos para seu cliente usando a API da Pluggy.

Agendamento Manual#

Se você preferir controlar quando cada pagamento é agendado, pode fazê-lo manualmente via API.

Agendando um Novo Pagamento#

Para agendar um novo pagamento Pix Automático, faça uma solicitação POST para: POST /payments/requests/{id}/automatic-pix/schedule

Onde {id} é o ID do pedido de pagamento autorizado.

Exemplo de solicitação

// POST /payments/requests/req_abc123/automatic-pix/schedule
// Content-Type: application/json
{
  "amount": 150.00,
  "date": "2025-07-10",
  "description": "Conta de serviços públicos de julho"
}

Exemplo de resposta

{
  "id": "66d503f1-0cfa-4d64-9f87-0782d959eba7",
  "status": "SCHEDULED",
  "amount": 150.00,
  "description": "Conta de serviços públicos de julho",
  "date": "2025-07-10",
  "endToEndId": null,
  "errorDetail": null
}

Revisando pagamentos#

• Você pode listar todos os pagamentos para um pedido usando:

GET /payments/requests/{id}/automatic-pix/schedules

Isso incluirá o primeiro pagamento também.

• Uma vez que você agenda um PIX Automático, nós o retornaremos na lista e enviaremos webhooks (automatic_pix_payment/created) quando ele for criado.
• Na data em que o pagamento foi agendado, ele tentará o pagamento e mudará para COMPLETED. Você poderá listá-lo e receber notificações de webhook também.

7. Como Repetir um Pagamento#

Às vezes, um pagamento automático agendado pode falhar devido a fundos insuficientes, problemas de rede ou outros problemas temporários. Para garantir que seu fluxo de pagamento seja robusto, você precisa de um mecanismo de repetição para pagamentos falhados.

Primeiramente, a instituição fará o seguinte:

• Primeira tentativa: Entre 00:00 e 08:00 no dia agendado.
• Segunda tentativa: Se a primeira tentativa falhar (por exemplo, devido a fundos insuficientes), uma segunda tentativa é feita entre 18:00 e 21:00 no mesmo dia.

Se ambas as tentativas falharem, você tem duas opções:

Recomendado: Repetições Automáticas#

Recomendamos usar Repetições Automáticas. Quando você cria seu Pedido de Pagamento, você configura quais dias após uma falha a Pluggy deve tentar automaticamente novamente (por exemplo, 1, 3 e 5 dias depois). A Pluggy então cuida das repetições para você — sem chamadas de API extras, sem jobs cron e sem risco de perder a janela de repetição. Você só precisa ouvir os mesmos webhooks que já usa.

Alternativa: Repetições Manuais#

Se você preferir controlar as repetições você mesmo, pode chamar a API de repetição quando receber um webhook de erro:

1. Identifique o Pagamento Falhado — Monitore o status dos seus pagamentos agendados usando a API da Pluggy. Você receberá notificações de webhook para cada status de pagamento que mudar.

   Para repetir um pagamento, ele deve ter sido agendado com sucesso e depois falhado na data de liquidação. Para verificar se um pagamento foi agendado corretamente, ele precisa ter um end_to_end_id definido. Além disso, o pagamento precisa estar no status ERROR.

2. Inicie uma Repetição — Para repetir um pagamento, use o endpoint da API para criar um novo pagamento, referenciando os detalhes do pagamento original. Você pode precisar fornecer o ID do pagamento original e atualizar quaisquer campos necessários (como a data agendada).

POST /payments/requests/{id}/automatic-pix/schedules/{scheduleId}/retry
Content-Type: application/json
 
{
  "date": "2024-07-01"
}

3. Rastreie a Tentativa de Repetição — Cada repetição gerará um novo registro de pagamento. Use a resposta para rastrear o status do novo pagamento.

Veja FAQ do PIX Automático - Repetições para mais detalhes.

Exemplo de Fluxo de Trabalho#

• O pagamento agendado para 1º de julho falhou devido a fundos insuficientes.
• As instituições podem tentar novamente durante aquele dia após as 18hs.
• Se a segunda tentativa falhar, você agenda uma repetição para o dia seguinte.
• Após 3 repetições manuais falhadas, o pagamento pode ser considerado como não bem-sucedido.

Erros Repetíveis#

Nem todos os erros são elegíveis para repetições. Apenas os seguintes códigos de erro da instituição financeira acionam repetições automáticas:

• UNKNOWN_ERROR — Um erro desconhecido ocorreu na instituição Open Finance ou no titular da conta (por exemplo, fundos insuficientes)
• PAGAMENTO_RECUSADO_DETENTORA — Pagamento rejeitado pela instituição do titular da conta
• PAGAMENTO_RECUSADO_SPI — Pagamento rejeitado pelo SPI
• FALHA_INFRAESTRUTURA_SPI — Falha na infraestrutura do SPI
• FALHA_INFRAESTRUTURA_ICP — Falha na infraestrutura do ICP
• FALHA_INFRAESTRUTURA_PSP_RECEBEDOR — Falha na infraestrutura do PSP receptor
• FALHA_INFRAESTRUTURA_DETENTORA — Falha na infraestrutura da instituição do titular da conta
• NAO_INFORMADO — Não informado (por exemplo, detecção de fraude)
• LIMITE_VALOR_TRANSACAO_CONSENTIMENTO_EXCEDIDO — Limite de valor da transação de consentimento excedido

8. Monitorando repetições#

Você pode rastrear todas as tentativas (originais e repetições) para um determinado agendamento usando o endpoint Obter agendamento por ID. Isso retorna o agendamento de pagamento mais um array attempts com o histórico completo de tentativas — uma entrada por tentativa (agendamento inicial mais cada repetição), ordenada da mais recente para a mais antiga.

Endpoint:

GET /payments/requests/{requestId}/automatic-pix/schedules/{paymentId}

A resposta inclui o status atual do agendamento, date, errorDetail e um array attempts. Cada tentativa tem:

Use isso para:

• Suporte: Mostrar aos usuários o histórico completo do que aconteceu (por exemplo, "Falhou em 10 de julho (fundos insuficientes), repetido em 11 de julho, concluído em 12 de julho").
• Dashboards: Contar repetições, taxa de sucesso após repetições ou códigos de erro mais comuns.
• Auditoria: Manter um registro claro de cada tentativa para um determinado pagamento.

Exemplo de resposta (agendamento com uma tentativa falhada e uma repetição bem-sucedida):

{
  "id": "66d503f1-0cfa-4d64-9f87-0782d959eba7",
  "status": "COMPLETED",
  "amount": 150.00,
  "description": "Conta de serviços públicos de julho",
  "date": "2025-07-10",
  "endToEndId": "E37943755202507101324U4bbaa85088",
  "errorDetail": null,
  "attempts": [
    {
      "id": "a1b2c3d4-...",
      "status": "COMPLETED",
      "endToEndId": "E37943755202507101324U4bbaa85088",
      "date": "2025-07-11",
      "errorDetail": null
    },
    {
      "id": "e5f6g7h8-...",
      "status": "ERROR",
      "endToEndId": null,
      "date": "2025-07-10",
      "errorDetail": {
        "code": "UNKNOWN_ERROR",
        "title": "Um erro desconhecido ocorreu na instituição Open Finance ou titular da conta.",
        "detail": "Um erro desconhecido ocorreu."
      }
    }
  ]
}

O status e date de nível superior do agendamento refletem o estado atual (por exemplo, COMPLETED e a data da repetição). O array attempts fornece a linha do tempo completa.

9. Cancelando Autorizações ou Pagamentos#

Cancelando uma Autorização#

As autorizações permitem que pagamentos agendados sejam processados automaticamente. Se um usuário desejar interromper pagamentos futuros, ele pode cancelar a autorização a qualquer momento.

Como Cancelar uma Autorização#

1. Envie uma Solicitação de Cancelamento — Use o endpoint da API para cancelar a autorização. Isso impedirá que futuros pagamentos sejam processados sob esta autorização.

POST /payments/requests/{id}/automatic-pix/cancel
Content-Type: application/json

2. Verifique o Status do Pedido de Pagamento — A API retornará um 204 indicando que a solicitação de cancelamento foi aceita e que o banco procederá para processar o cancelamento.

3. Ouça os Webhooks: O status atualizado do pedido de pagamento será enviado como uma notificação via webhook payment_request/updated. Confirme que o status agora é CANCELED ou equivalente.

Exemplo de Payload de Webhook:

{
  "eventId": "71e0b4db-4e8c-401d-8ad8-5ab3ecd1f3d0",
  "event": "payment_request/updated",
  "paymentRequestId": "624cb41e-2b76-42ac-8021-ce6b6b4ace6b",
  "clientId": "client-123",
  "status": "CANCELED"
}

Cancelando um Pagamento#

Se um pagamento está agendado, mas ainda não foi processado, você pode cancelá-lo para evitar a transferência de fundos.

Como Cancelar um Pagamento#

1. Envie uma Solicitação de Cancelamento — Use o endpoint da API para cancelar o pagamento.

POST /payments/requests/{paymentId}/automatic-pix/schedules/{scheduleId}/cancel
Content-Type: application/json

Substitua {paymentId} pelo ID real do pagamento que você deseja cancelar.

2. Verifique o Status do Pagamento Pix Automático Agendado — A API retornará um 204 indicando que a solicitação de cancelamento foi aceita e que o banco procederá para processar o cancelamento.

3. Ouça os Webhooks: O status atualizado do agendamento de pagamento será enviado como uma notificação. Confirme que o status agora é CANCELED ou equivalente.

Para mais detalhes, veja a Referência da API Pluggy: Agendar pagamento automático PIXAPI.

10. Testando no sandbox#

Todo o fluxo do Pix Automático — consentimento, primeiro pagamento, cobranças agendadas e cancelamento — pode ser exercido contra o banco sandbox, sem conta real e sem dinheiro real.

{
  "paymentRequestId": "{YOUR-SANDBOX-PAYMENT-REQUEST-ID}",
  "connectorId": 600,
  "parameters": {
    "cpf": "76109277673",
    "name": "Maria Silva"
  }
}

Quando o sandbox executa pagamentos agendados#

O banco sandbox liquida todos os pagamentos devidos em uma determinada data em uma única execução diária às 09:00 UTC (06:00 em Brasília) naquela data — não há como fazer um pagamento agendado ser concluído mais cedo. Um pagamento agendado para D+2, portanto, é concluído dois dias depois, no início da manhã, e seu webhook automatic_pix_payment/completed chega então. A date que você envia é uma data do calendário (YYYY-MM-DD); a janela de D+2 a D+10 é contada a partir de hoje no horário de Brasília.