PluggyDocs

Começando

Integrando-se ao gateway de pagamento da Pluggy para Pix Automático - aprenda como criar sua primeira solicitação de pagamento, lidar com autorização, agendar pagamentos e gerenciar tentativas.

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

Pré-requisitos

  • Crie um PaymentRecipient — assim como outros métodos de pagamento, a conta destinatária é configurada como um PaymentRecipient.
  • Prepare um callbackUrl para retornar ao seu aplicativo após o pagamento ter sido bem-sucedido / com erro.
  • Configure webhooks para receber notificações de PaymentRequests, PaymentIntents ou PixAutomaticPayments.
  • Entenda como a Pluggy gerencia solicitações de pagamento, para compartilhar com os usuários finais Links de Autorização de Pagamento.

1. Criando uma Solicitação de Pagamento#

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

Exemplo: Criando uma Solicitação de Pagamento#

HTTP
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 solicitações de pagamento tanto de valores fixos quanto de valores variáveis:

  • 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).

Payload de Valor Fixo

Payload 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"
  }
}

Payload de Valor Variável

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"
  }
}

Considerações extras

Ao enviar pagamentos, você poderá enviar um valor entre minimumVariableAmount e maximumVariableAmount. Você não poderá enviar um valor fora desse intervalo sem criar outra autenticação.

Os pagamentos fixos não poderão enviar um valor diferente do que foi configurado.

Os valores do primeiro pagamento podem ser diferentes e maiores do que a autorização que foi solicitada. Isso não afeta os limites para aquele intervalo também.

3. Redirecionando o usuário para Autorizar#

Uma vez que uma solicitação de pagamento é criada, 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 da solicitação 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 um payload que inclua o paymentRequestId, o CPF/CNPJ do pagador e o nome.

// https://api.pluggy.ai/payments/intents
{
  "paymentRequestId": "req_abc123", // O ID da solicitação de pagamento criada anteriormente
  "connectorId": 123, // O ID do conector (banco/instituição)
  "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 a solicitação de pagamento via 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 via API da Pluggy e webhooks.
  • Você receberá atualizações em tempo real sobre o status da Intenção de Pagamento, Solicitação de Pagamento e PIX Automático.
    • Incluindo autorizações bem-sucedidas (PAYMENT_COMPLETED), rejeições (CONSENT_REJECTED) e expiração de consentimento (EXPIRED)
    • Inclui notificações do primeiro pagamento e pagamentos futuros que estão sendo agendados
    • Mudanças no status da solicitação de pagamento são notificadas via webhook payment_request/updated

Timeouts

Se o processo de autorização de pagamento não for concluído, ele será atualizado para CONSENT_REJECTED após 60 minutos e será notificado através de webhooks também.

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

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

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 a solicitação de pagamento é autorizada (o status da Solicitação de Pagamento é AUTHORIZED), você pode agendar novos pagamentos para seu cliente usando a API da Pluggy.

Recomendado: Use o Agendador de PIX Automático

Em vez de agendar manualmente cada pagamento via API, você pode habilitar o Agendador de PIX Automático ao criar sua solicitação de pagamento. Com schedulerConfiguration.enabled: true, o sistema agenda automaticamente os pagamentos em cada ciclo de recorrência dentro da janela permitida de D+2 a D+10 — sem chamadas de API ou jobs cron necessários do seu lado.

Esta é a abordagem recomendada, pois remove a complexidade de rastrear datas de pagamento e respeitar janelas de agendamento você mesmo.

Para detalhes completos, consulte a documentação do Agendador de PIX Automático.

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 da solicitação de pagamento autorizada.

Exemplo de solicitação

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

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
}

Considerações Importantes

  • A solicitação de pagamento deve estar no status AUTHORIZED.
  • A data agendada deve respeitar o intervalo e os limites definidos na autorização original (por exemplo, mensal, semanal).
  • Apenas um pagamento pode ser feito no intervalo. Se você configurou a PaymentRequest para ser mensal, você poderá gerar apenas um pagamento mensal (mesmo dia do mês).
  • Para mandatos de valor variável, o valor deve estar dentro da faixa mínima/máxima autorizada.
  • Todas as validações de pagamento retornarão um erro HTTP 400 explicando por que o pagamento não será agendado.
  • Você pode mudar a conta do destinatário enviando outro "recipientId" no corpo da solicitação. Esse destinatário deve ter o mesmo taxNumber que o destinatário original (caso contrário, falhará).
  • Os pagamentos devem ser agendados entre 2 e 10 dias antes da data de pagamento. Por exemplo, se você deseja cobrar seu cliente no dia 15 de cada mês, precisa agendar o pagamento entre os dias 5 e 8 desse mês.

Revisando pagamentos#

  • Você pode listar todos os pagamentos para uma solicitação usando:
GET /payments/requests/{id}/automatic-pix/schedules

Isso incluirá o primeiro pagamento também.

  • Uma vez que você agendar 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 trabalho 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 sua Solicitação 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 gerencia as 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).

HTTP
POST /payments/requests/{id}/automatic-pix/schedules/{scheduleId}/retry
Content-Type: application/json
 
{
  "date": "2024-07-01"
}
  1. 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.

Consulte 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 — Ocorreu um erro desconhecido no iniciador ou 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), ordenado 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:

CampoDescrição
idIdentificador único da tentativa
statusStatus daquela tentativa (SCHEDULED, COMPLETED, ERROR, CANCELED, IN_PROGRESS)
endToEndIdID de ponta a ponta da instituição (quando disponível)
dateData da tentativa (YYYY-MM-DD)
errorDetailDetalhes do erro se a tentativa falhar (por exemplo, code, title, detail)

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": "Ocorreu um erro desconhecido no iniciador ou titular da conta.",
        "detail": "Ocorreu um erro desconhecido."
      }
    }
  ]
}

O status e a 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

  1. Verifique o Status da Solicitação de Pagamento — A API retornará um 204 informando que a solicitação de cancelamento foi aceita e que o banco procederá com o processamento do cancelamento.

  2. Ouça os Webhooks: O status atualizado da solicitação 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"
}

Importante

  • Pagamentos agendados para o dia seguinte ou primeiros pagamentos não serão cancelados.
  • Uma vez que a solicitação de pagamento é cancelada, não é possível autorizá-la novamente. Nesse caso, você precisa criar uma nova solicitação de pagamento.

Cancelando um Pagamento#

Se um pagamento estiver agendado, mas ainda não tiver sido 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.

  1. Verifique o Status do Pagamento Pix Automático Agendado — A API retornará um 204 informando que a solicitação de cancelamento foi aceita e que o banco procederá com o processamento do cancelamento.

  2. 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.

Importante:

Pagamentos que já foram processados ou estão em um estado terminal (por exemplo, COMPLETED, ERROR) não podem ser cancelados.

Para cancelamentos feitos após a janela de tempo do dia anterior (22hs BRT), podem não ser cancelados.

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