# Começando Este guia irá orientá-lo pelos conceitos básicos de como criar seu primeiro pedido de pagamento Pix Automático usando o Gateway de Pagamento da Pluggy. Você aprenderá a configurar pedidos 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 **pedidos de pagamento**, para compartilhar com os usuários finais *Links de Autorização de Pagamento*. ## 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 ```http title="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 pedidos 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** ```json title="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** ```json title="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 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:** ```json { "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 um payload que inclua o paymentRequestId, o CPF/CNPJ do pagador e o nome. ```json // https://api.pluggy.ai/payments/intents { "paymentRequestId": "req_abc123", // O ID do pedido de pagamento criado 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 o pedido 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, 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` > **Timeout de autorização** > > Se o processo de autorização do PIX Automático não for concluído dentro de 60 minutos, a Intenção de Pagamento é marcada como `PAYMENT_TIMEOUT` e a Pluggy envia um webhook `payment_intent/error`. Este timeout é separado da expiração do `consentUrl`: a URL de autorização do banco expira após 5 minutos. A `paymentUrl` não é um link de cinco minutos; sua disponibilidade depende do status e configuração do Pedido de Pagamento. ## 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** ```json title="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** ```json title="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. > **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 seu pedido 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 por conta própria. > > Para detalhes completos, veja a [documentação do Agendador de PIX Automático](/docs/payments/pix-scheduler). ### 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** ```json title="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** ```json title="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** > > - O pedido 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 o 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ê quiser cobrar seu cliente no dia 15 de cada mês, precisará agendar o pagamento entre os dias 5 e 8 desse mês. ### 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ê agende 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](/docs/automatic-pix-automatic-retries)**. 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 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 por conta própria, 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 title="HTTP" 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](/docs/automatic-pix-faq#/retries) 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 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), ordenadas da mais recente para a mais antiga. **Endpoint:** ```http 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: | Campo | Descrição | |-------|-------------| | `id` | Identificador único da tentativa | | `status` | Status daquela tentativa (`SCHEDULED`, `COMPLETED`, `ERROR`, `CANCELED`, `IN_PROGRESS`) | | `endToEndId` | ID de ponta a ponta da instituição (quando disponível) | | `date` | Data da tentativa (AAAA-MM-DD) | | `errorDetail` | Detalhes do erro se a tentativa falhou (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):** ```json { "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 na instituição Open Finance 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. ```http 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á com o processamento do 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:** ```json { "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 o pedido de pagamento é cancelado, não é possível autorizá-lo novamente. Nesse caso, você precisa criar um novo pedido 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. ```http 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á com o processamento do 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. > **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, veja a [Referência da API Pluggy: Agendar pagamento automático PIX](/reference/payment-request-create-automatic-pix-schedule).