Retry Policies

What are Retry Policies?

Retry policies define how the system automatically handles failed payments. When a payment fails (e.g., insufficient funds, account closed, authorization revoked), the system can automatically retry the payment according to the configured retry policy, without requiring merchant intervention.

This feature improves payment success rates by automatically recovering from temporary failures and ensures compliance with regulatory requirements for specific payment methods.

How Retry Policies Work

When a payment fails, the system automatically:

Checks the retry policy to determine if retries are allowed
Validates retry limits haven't been exceeded
Calculates the next retry date based on the policy rules
Schedules the retry for the calculated date
Executes the retry on the scheduled date
Repeats the process if the retry fails (until limits are reached) or marks the payment as permanently failed

Retry Policy Types

PIX_SPECIFIC

Automatically configured retry policy for PIX Automatic that complies with Brazilian Central Bank (Bacen) regulations.

Configuration:

type: "PIX_SPECIFIC"
maxRetries: 3 (fixed, cannot be changed)
retryIntervalDays: 7 (fixed, cannot be changed)

Rules:

Maximum 3 retries within 7 consecutive days from the first failure
Maximum 3 distinct days with retry attempts
Time Windows:
- Initial Payment Window: 0:00-8:00 AM BRT (original payment attempt)
- Retry #1:
  - If initial payment failed between 0:00-8:00 AM BRT: Same day intraday retry at 6:00 PM-9:00 PM BRT (18:00-21:00)
  - Otherwise: Next day at 0:00-8:00 AM BRT
- Retry #2: Next day at 0:00-8:00 AM BRT
- Retry #3: Next day at 0:00-8:00 AM BRT

When to Use:

Only available for PIX channel
Automatically applied when channel: "PIX" and retryPolicy.type: "PIX_SPECIFIC"
Ensures compliance with Bacen regulations

Example Timeline:

Day 1 (January 10, 2025 - 05:00 BRT):
  - Initial payment attempt fails (insufficient funds)
  - Retry #1 scheduled for same day 18:00 BRT (intraday retry)

Day 1 (January 10, 2025 - 18:00 BRT):
  - Retry #1 executed → Fails
  - Retry #2 scheduled for next day 05:00 BRT

Day 2 (January 11, 2025 - 05:00 BRT):
  - Retry #2 executed → Fails
  - Retry #3 scheduled for next day 05:00 BRT

Day 3 (January 12, 2025 - 05:00 BRT):
  - Retry #3 executed → Fails
  - No more retries allowed (maximum 3 retries in 7 days)
  - Payment marked as permanently FAILED

Additional Validations:

Payment amount must remain unchanged during retry period
Subscription must remain active
Retry cannot exceed the next billing cycle date
Must comply with time window restrictions

FIXED_RETRY

Configurable retry policy for any payment method. This is a generic policy that allows you to customize retry behavior.

Configuration:

type: "FIXED_RETRY"
maxRetries: Configurable (e.g., 3, 5, 10)
retryIntervalDays: Configurable (e.g., 1, 2, 7)

Rules:

Maximum retries: As specified in maxRetries
Retry interval: As specified in retryIntervalDays
Retries occur at regular intervals until limit is reached

When to Use:

For payment methods other than PIX
When you need custom retry behavior
When regulatory requirements don't specify retry rules

Example Configuration:

{
  "retryPolicy": {
    "type": "FIXED_RETRY",
    "maxRetries": 5,
    "retryIntervalDays": 2
  }
}

Example Timeline:

Day 1 (January 10, 2025):
  - Payment fails
  - Retry #1 scheduled for Day 3 (2 days later)

Day 3 (January 12, 2025):
  - Retry #1 executed → Fails
  - Retry #2 scheduled for Day 5 (2 days later)

Day 5 (January 14, 2025):
  - Retry #2 executed → Fails
  - Retry #3 scheduled for Day 7 (2 days later)

... continues until maxRetries (5) is reached

NOT_ALLOWED

No automatic retries will be performed. Failed payments are immediately marked as permanently failed.

Configuration:

type: "NOT_ALLOWED"
No additional configuration required

Behavior:

Payment is marked as FAILED immediately
No automatic retries are performed
Merchant must handle retries manually if needed

When to Use:

When you want to handle retries manually
When retries are not allowed by the payment method
For testing or specific business requirements
When you prefer immediate failure notification

Retry Tracking

You can track retry attempts through:

Payment status updates via webhooks
Payment details in API responses (includes retry count)
Webhook notifications for each retry attempt

PIX-Specific Retry Rules

Initial Payment Attempt

The original payment is processed during the initial payment window (0:00-8:00 AM BRT). If it fails, the retry process begins.

Retry #1

If initial payment failed between 0:00-8:00 AM BRT:

Retry #1 occurs the same day during the intraday window (6:00 PM-9:00 PM BRT / 18:00-21:00)

If initial payment failed outside 0:00-8:00 AM BRT:

Retry #1 occurs the next day during the initial window (0:00-8:00 AM BRT)

Retry #2 and #3

Both Retry #2 and Retry #3 occur on subsequent days during the initial window (0:00-8:00 AM BRT).

7-Day Window

All retries must occur within 7 consecutive calendar days from the first failure date. After 7 days, no further retries are allowed, even if the maximum retry count hasn't been reached.

3 Distinct Days Limit

The system can only attempt retries on a maximum of 3 distinct days within the 7-day window. This means:

Day 1: Initial failure + intraday retry (if applicable)
Day 2: Retry attempt
Day 3: Retry attempt
No more retry days allowed

Retry Validation

Before each retry attempt, the system validates:

Subscription Status

Subscription must be ACTIVE
Subscription cannot be cancelled or expired

Payment Amount

Amount must remain unchanged from the original payment
Cannot modify amount during retry period

Timing Windows

Retry must occur within allowed time windows (for PIX)
Retry cannot exceed the next billing cycle date

Retry Limits

Maximum retries not exceeded
7-day window not exceeded (for PIX)
3 distinct days limit not exceeded (for PIX)

Retry Execution

When a retry is executed:

System validates all retry requirements (limits, timing, subscription status)
System attempts the payment retry
System updates payment status and retry count
Merchant receives webhook notification with the result

Retry Results

Success:

Payment status changes to PAID
Merchant receives webhook notification
Next payment is scheduled (if automatic scheduling is enabled)

Failure:

If retry limits not exceeded: Another retry is scheduled
If retry limits exceeded: Payment marked as permanently FAILED
Merchant receives webhook notification

Webhook Notifications

Merchants receive webhook notifications for:

Each retry attempt (status: IN_PROGRESS)
Retry success (status: PAID)
Retry failure (status: FAILED)
Permanent failure after all retries exhausted

Example Retry Failure Webhook:

{
  "eventType": "subscription.payment",
  "entityId": "payment-guid",
  "status": "FAILED",
  "eventDate": "2025-01-12T05:00:00Z",
  "errorCode": "INSUFFICIENT_FUNDS",
  "errorMessage": "Insufficient funds",
  "additionalData": [
    {
      "key": "retryCount",
      "value": "3"
    },
    {
      "key": "retryNumber",
      "value": "3"
    }
  ]
}

Best Practices

Choose the Right Policy

PIX Automatic: Always use PIX_SPECIFIC for compliance
Other Methods: Use FIXED_RETRY with appropriate limits
Manual Control: Use NOT_ALLOWED if you prefer manual retry handling

Configure Appropriate Limits

Balance between recovery and customer experience
Consider payment method characteristics
Account for regulatory requirements

Monitor Retry Activity

Track retry success rates
Monitor retry patterns
Identify common failure reasons

Handle Permanent Failures

Notify customers when payments permanently fail
Provide options for updating payment methods
Consider subscription cancellation after multiple failures

Next Steps

Automatic Scheduling: Learn how payments are automatically scheduled
Webhooks and Notifications: Set up retry event notifications
PIX Automatic Compliance: Understand PIX-specific retry requirements