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:

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:

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:

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

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

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

1. Listen for automatic_pix_payment/error webhooks
2. Determine if the error is retriable
3. Calculate the correct retry date within the allowed window
4. Call POST /payments/requests/{id}/automatic-pix/schedules/{scheduleId}/retry with the right date
5. 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:

Retriable errors

See https://docs.pluggy.ai/docs/getting-started-with-pix-autom%C3%A1tico#retriable-errors

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

Monitoring retries

See https://docs.pluggy.ai/docs/getting-started-with-pix-autom%C3%A1tico#8-monitoring-retries