# 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:

```json
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:

| Tentativa | Data | O que acontece |
|-----------|------|----------------|
| Original  | 10 de julho | Pagamento falha devido a fundos insuficientes |
| Tentativa 1 | 11 de julho | A Pluggy tenta automaticamente (data original + 1 dia) |
| Tentativa 2 | 13 de julho | Se a tentativa 1 falhar, a Pluggy tenta novamente (data original + 3 dias) |
| Tentativa 3 | 15 de julho | Se a tentativa 2 falhar, a Pluggy tenta novamente (data original + 5 dias) |

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:

```json
{
  "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:

```json
{
  "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:

```json
{
  "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 os 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:

| Evento | Quando |
|--------|--------|
| `automatic_pix_payment/error` | O pagamento (ou uma tentativa) falhou |
| `automatic_pix_payment/created` | Uma tentativa foi agendada |
| `automatic_pix_payment/completed` | Uma tentativa foi bem-sucedida |

## Erros recuperáveis

Veja [Erros recuperáveis](/docs/getting-started-with-pix-automático#retriable-errors) 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](/docs/getting-started-with-pix-automático#8-monitoring-retries) para detalhes sobre como rastrear todas as tentativas de um determinado pagamento.