# Retry Policies

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

1. **Checks the retry policy** to determine if retries are allowed
2. **Validates retry limits** haven't been exceeded
3. **Calculates the next retry date** based on the policy rules
4. **Schedules the retry** for the calculated date
5. **Executes the retry** on the scheduled date
6. **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**:

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

1. **System validates** all retry requirements (limits, timing, subscription status)
2. **System attempts** the payment retry
3. **System updates** payment status and retry count
4. **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**:

```json
{
  "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](automatic-scheduling.md)**: Learn how payments are automatically scheduled
* **[Webhooks and Notifications](webhooks-and-notifications.md)**: Set up retry event notifications
* **[PIX Automatic Compliance](../payment-methods/pix-automatic/compliance-requirements.md)**: Understand PIX-specific retry requirements