# Automatic retries (Beta)

When a Automatic Pix Payment fails (e.g., due to insufficient funds), it needs to be retried within a specific time window. With **Automatic Retries**, Pluggy handles this for you — no extra API calls, no polling, no cron jobs on your side.

## How it works

When you create a Payment Request, you can include an `automaticRetriesConfiguration` object with a `retryDays` array. Each value represents the number of days **after the original payment date** when Pluggy should automatically retry the payment if it fails.

When a payment enters `ERROR` status with a retriable error, Pluggy will automatically schedule the next retry on the first available future date from your `retryDays` configuration. You will receive the usual `automatic_pix_payment/created` webhook when the retry is scheduled, and `automatic_pix_payment/completed` or `automatic_pix_payment/error` when it settles.

> **Note:** Automatic retries only apply to payments that were successfully scheduled and then failed on the settlement date. Payments that fail before being scheduled are not eligible for automatic retries.

## Setting up Automatic Retries

Add the `automaticRetriesConfiguration` field when creating your Payment Request:

```json
POST /payments/requests/automatic-pix

{
  "description": "Monthly subscription",
  "recipientId": "df3ed44b-f085-4b9e-b81e-7d1d4ed1476f",
  "interval": "MONTHLY",
  "startDate": "2025-07-01",
  "fixedAmount": 49.90,
  "isRetryAccepted": true,
  "automaticRetriesConfiguration": {
    "retryDays": [1, 3, 5]
  }
}
```

In this example, if a payment scheduled for July 10th fails:

| Attempt | Date | What happens |
|---------|------|-------------|
| Original | July 10 | Payment fails due insufficient funds |
| Retry 1 | July 11 | Pluggy automatically retries (original date + 1 day) |
| Retry 2 | July 13 | If retry 1 fails, Pluggy retries again (original date + 3 days) |
| Retry 3 | July 15 | If retry 2 fails, Pluggy retries again (original date + 5 days) |

You will receive webhook notifications for each attempt, so you can keep your users informed.

## Configuration rules

### `retryDays`

An array of integers (from 1 to 7) representing the days after the original payment date when retries should be attempted.

- Each value must be between **1** and **7**.
- A maximum of **3 retries** will be attempted per payment.
- For `WEEKLY` interval, retry days must be **5 or less** (to stay within the recurrence cycle).

### `isRetryAccepted`

Must be set to `true` when using `automaticRetriesConfiguration`. This field is part of the Open Finance consent and signals that the payer has authorized retries.

## Examples

### Fixed monthly subscription with aggressive retries

Retry every day for 3 consecutive days after a failure:

```json
{
  "description": "Gym membership",
  "recipientId": "df3ed44b-f085-4b9e-b81e-7d1d4ed1476f",
  "interval": "MONTHLY",
  "startDate": "2025-07-01",
  "fixedAmount": 99.90,
  "isRetryAccepted": true,
  "automaticRetriesConfiguration": {
    "retryDays": [1, 2, 3]
  }
}
```

### Variable amount with spaced-out retries

Give the user more time between retries:

```json
{
  "description": "Utility bill",
  "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]
  }
}
```

### Weekly interval

For weekly intervals, retries must be within 5 days:

```json
{
  "description": "Weekly delivery fee",
  "recipientId": "df3ed44b-f085-4b9e-b81e-7d1d4ed1476f",
  "interval": "WEEKLY",
  "startDate": "2025-07-07",
  "fixedAmount": 25.00,
  "isRetryAccepted": true,
  "automaticRetriesConfiguration": {
    "retryDays": [1, 3, 5]
  }
}
```

## Why use Automatic Retries instead of implementing retries yourself

### Timing and compliance

The Open Finance regulation defines specific rules about when and how Pix Automatico payments can be retried. Retry windows depend on the recurrence interval, cycle boundaries, and the type of error. Pluggy's automatic retries are built to comply with these rules out of the box, so you don't need to track cycle dates or validate retry windows yourself.

### Handling delayed error notifications

Financial institutions sometimes delay reporting a payment's final status. If a payment fails on Monday but the institution only notifies the error on Wednesday, a retry scheduled for Tuesday would have already been missed. Pluggy handles this gracefully — when the error notification arrives, it automatically picks the **next available future retry date** from your configuration, skipping any dates that are already in the past.

### Reduced complexity

Without automatic retries, you would need to:

- Listen for `automatic_pix_payment/error` webhooks
- Determine if the error is retriable
- Calculate the correct retry date within the allowed window
- Call `POST /payments/requests/{id}/automatic-pix/schedules/{scheduleId}/retry` with the right date
- Handle edge cases like delayed notifications, cycle boundaries, and max retry limits

With automatic retries, all of this is handled by Pluggy. You only need to configure `retryDays` once when creating the Payment Request.

### Reliability

Automatic retries are triggered server-side immediately when the error is received. There's no dependency on your infrastructure being available, no risk of missed webhooks, and no need to implement idempotency logic for retry calls.

## Webhook notifications

You will continue to receive the same webhook events as with manual retries:

| Event | When |
|-------|------|
| `automatic_pix_payment/error` | The payment (or a retry) has failed |
| `automatic_pix_payment/created` | A retry has been scheduled |
| `automatic_pix_payment/completed` | A retry was successful |

## Retriable errors

See [Retriable errors](/docs/getting-started-with-pix-automático#retriable-errors) for the full list of error codes that trigger automatic retries.

Errors outside this list indicate a non-transient problem and will **not** trigger automatic retries.

## Monitoring retries

See [Monitoring retries](/docs/getting-started-with-pix-automático#8-monitoring-retries) for details on how to track all attempts for a given payment.