Tentativas automáticas (Beta)

Quando um Pagamento Pix Automático falha (por exemplo, devido a fundos insuficientes), ele precisa ser refeito dentro de uma janela de tempo específica. Com Tentativas Automáticas, a Pluggy cuida disso para você — sem chamadas de API extras, sem polling, sem jobs cron do seu lado.

Como funciona#

Quando você cria uma Solicitação de Pagamento, pode incluir um objeto automaticRetriesConfiguration com um array retryDays. Cada valor representa o número de dias após a data original do pagamento quando a Pluggy deve tentar automaticamente refazer o pagamento se ele falhar.

Quando um pagamento entra no status ERROR com um erro recuperável, a Pluggy agendará automaticamente a próxima tentativa na primeira data futura disponível da sua configuração retryDays. Você receberá o webhook usual automatic_pix_payment/created quando a tentativa for agendada, e automatic_pix_payment/completed ou automatic_pix_payment/error quando for concluído.

Nota: As tentativas automáticas se aplicam apenas a pagamentos que foram agendados com sucesso e depois falharam na data de liquidação. Pagamentos que falham antes de serem agendados não são elegíveis para tentativas automáticas.

Configurando Tentativas Automáticas#

Adicione o campo automaticRetriesConfiguration ao criar sua Solicitação de Pagamento:

POST /payments/requests/automatic-pix
 
{
  "description": "Assinatura mensal",
  "recipientId": "df3ed44b-f085-4b9e-b81e-7d1d4ed1476f",
  "interval": "MONTHLY",
  "startDate": "2025-07-01",
  "fixedAmount": 49.90,
  "isRetryAccepted": true,
  "automaticRetriesConfiguration": {
    "retryDays": [1, 3, 5]
  }
}

Neste exemplo, se um pagamento agendado para 10 de julho falhar:

Você receberá notificações de webhook para cada tentativa, para que possa manter seus usuários informados.

Regras de configuração#

retryDays#

Um array de inteiros (de 1 a 7) representando os dias após a data original do pagamento quando as tentativas devem ser feitas.

• Cada valor deve estar entre 1 e 7.
• Um máximo de 3 tentativas será feito por pagamento.
• Para intervalo WEEKLY, os dias de tentativa devem ser 5 ou menos (para permanecer dentro do ciclo de recorrência).

isRetryAccepted#

Deve ser definido como true ao usar automaticRetriesConfiguration. Este campo faz parte do consentimento do Open Finance e sinaliza que o pagador autorizou as tentativas.

Exemplos#

Assinatura mensal fixa com tentativas agressivas#

Tente todos os dias por 3 dias consecutivos após uma falha:

{
  "description": "Associação à academia",
  "recipientId": "df3ed44b-f085-4b9e-b81e-7d1d4ed1476f",
  "interval": "MONTHLY",
  "startDate": "2025-07-01",
  "fixedAmount": 99.90,
  "isRetryAccepted": true,
  "automaticRetriesConfiguration": {
    "retryDays": [1, 2, 3]
  }
}

Valor variável com tentativas espaçadas#

Dê ao usuário mais tempo entre as tentativas:

{
  "description": "Conta de serviços públicos",
  "recipientId": "df3ed44b-f085-4b9e-b81e-7d1d4ed1476f",
  "interval": "MONTHLY",
  "startDate": "2025-07-01",
  "minimumVariableAmount": 50.00,
  "maximumVariableAmount": 500.00,
  "isRetryAccepted": true,
  "automaticRetriesConfiguration": {
    "retryDays": [1, 4, 7]
  }
}

Intervalo semanal#

Para intervalos semanais, as tentativas devem estar dentro de 5 dias:

{
  "description": "Taxa de entrega semanal",
  "recipientId": "df3ed44b-f085-4b9e-b81e-7d1d4ed1476f",
  "interval": "WEEKLY",
  "startDate": "2025-07-07",
  "fixedAmount": 25.00,
  "isRetryAccepted": true,
  "automaticRetriesConfiguration": {
    "retryDays": [1, 3, 5]
  }
}

Por que usar Tentativas Automáticas em vez de implementar tentativas você mesmo#

Tempo e conformidade#

A regulamentação do Open Finance define regras específicas sobre quando e como os pagamentos Automáticos Pix podem ser refeito. As janelas de tentativas dependem do intervalo de recorrência, limites de ciclo e tipo de erro. As tentativas automáticas da Pluggy são construídas para cumprir essas regras desde o início, para que você não precise acompanhar datas de ciclo ou validar janelas de tentativas você mesmo.

Tratamento de notificações de erro atrasadas#

As instituições financeiras às vezes atrasam a comunicação do status final de um pagamento. Se um pagamento falhar na segunda-feira, mas a instituição só notificar o erro na quarta-feira, uma tentativa agendada para terça-feira já teria sido perdida. A Pluggy lida com isso de forma elegante — quando a notificação de erro chega, ela automaticamente escolhe a próxima data de tentativa futura disponível da sua configuração, pulando quaisquer datas que já estão no passado.

Complexidade reduzida#

Sem tentativas automáticas, você precisaria:

• Ouvir por webhooks automatic_pix_payment/error
• Determinar se o erro é recuperável
• Calcular a data correta da tentativa dentro da janela permitida
• Chamar POST /payments/requests/{id}/automatic-pix/schedules/{scheduleId}/retry com a data correta
• Lidar com casos extremos como notificações atrasadas, limites de ciclo e limites máximos de tentativas

Com tentativas automáticas, tudo isso é tratado pela Pluggy. Você só precisa configurar retryDays uma vez ao criar a Solicitação de Pagamento.

Confiabilidade#

As tentativas automáticas são acionadas no lado do servidor imediatamente quando o erro é recebido. Não há dependência da sua infraestrutura estar disponível, nenhum risco de webhooks perdidos e nenhuma necessidade de implementar lógica de idempotência para chamadas de tentativas.

Notificações de webhook#

Você continuará a receber os mesmos eventos de webhook que com tentativas manuais:

Erros recuperáveis#

Veja Erros recuperáveis para a lista completa de códigos de erro que acionam tentativas automáticas.

Erros fora desta lista indicam um problema não transitório e não acionarão tentativas automáticas.

Monitorando tentativas#

Veja Monitorando tentativas para detalhes sobre como rastrear todas as tentativas de um determinado pagamento.