Outstanding invoices

Invoices that began a retry process before you implemented CPR can still enter CPR for further retry attempts. However, the retry cycle resets to the beginning of the CPR-defined cycles. You cannot select a specific retry cycle for a particular payment attempt; all CPR retry cycles start from the beginning and proceed through any configured retry attempts.

To exclude an outstanding invoice from retry, set the invoice's auto-pay field to false. This setting excludes the invoice from tenant payment runs and prevents CPR from making additional retry attempts.

Retry configuration

Before you create multiple customer groups or implement complex retry logic, identify the ideal retry scenario for your business and customers. Consider whether you need additional customer groups, whether you require segmentation based on specific identifiers, or whether the primary focus is the retry logic itself.

You can replicate the current retry logic in CPR with minimal changes. You can also create customer groups and modify the retry attempt logic as needed.

Confirm best practices for payment failures with your payment gateway provider, including which attempts to retry. CPR supports most requirements, but does not automatically restrict any flows.

Zuora does not support reverting settings within the application. If you make significant changes to the configuration, export your settings and save them externally. You can then import the exported settings to revert changes if necessary.

Zuora recommends that you configure retry at the Invoice level rather than the Account level in the CPR settings. Invoice-level retry changes only the invoice auto-pay flag, which keeps the account eligible for future tenant payment runs. Account-level retry changes both the account and invoice auto-pay flags.

• Invoice-level retry (preferred)

  • When an invoice enters the retry process, CPR sets its auto-pay flag to false and does not change it again.

• Account-level retry

  • When an invoice enters the retry process, CPR sets both the invoice and account auto-pay flags to false.

  • CPR resets the account auto-pay flag to true only when a CPR-initiated payment retry successfully collects payment.

Verify CPR process execution

After you configure CPR correctly, you can verify that it works by checking the following items after the tenant payment run completes.

• Verify callout notification - The payment run completion callout must pass failed payments from the tenant payment run to CPR. To check whether the callout is triggered:

  • Navigate to Settings > Payments > Setup Profiles, Notification and Email Templates > Notification History.

  • Confirm that the callout notification is triggered successfully. Common errors include:

    • Incorrect parameter name (PaymentRunID) or value (PaymentRun.PaymentRunID).

    • Incorrect authentication. Use the API token of the instance in your target environment.

• Review retry status for updates - After CPR is invoked, it retrieves the failed payments and schedules the next retry based on the configured logic. CPR also updates the retry status on both the account and the invoice, and disables the invoice auto-pay flag.

  • If the retry status of an invoice shows a Failure state, CPR was called but encountered an issue, either because of configuration settings that prevent future retries or because of a payment processing error.

  • To view the error, navigate to CPR > Failures and locate the relevant payment.

• Test CPR configuration flows - During testing, you can attach a workflow to each payment attempt. The workflow sends an email or other notification when a retry runs.

• Review the retry cycle schedule - To determine when CPR schedules the next retry attempt:

  • Use the CPR System Health Dashboard.

  • Alternatively, query the collections_retrycycles schema in Data Query, or use the CPR API to retrieve cycle information.

Stop scheduled retries

Stopping a CPR app instance does not prevent already-scheduled retries from running. To prevent further retries:

• For invoices and accounts with existing retry cycles, use the CPR APIs to remove the cycles. For more information, see the Developer Center.

• To prevent new cycles from starting, deactivate the callout notification. For more information, see CPR configuration. To stop new cycles, deactivate the callout notification. .

Modify retry status

Changing the retry status of a document or account does not prevent retries from running. To stop further retries:

• For existing retry cycles, use the CPR APIs to remove the cycles. For more information, see the Developer Center.

• To stop new cycles, deactivate the callout notification. For more information, see CPR configuration.

Modify an existing retry cycle

After a CPR cycle starts, you cannot pause or resume it. The retry cycle continues to attempt retries until either all attempts are exhausted or the invoice balance is cleared. To stop a retry cycle manually, use the Remove invoice from retry cycle API. After a cycle stops, you cannot restart it; if you restart it, the cycle begins from the first retry attempt.

You can modify parameters for a customer group at any time. Updated parameters apply to future evaluations, because CPR assigns each invoice to a customer group when the invoice enters CPR. However, changes do not affect invoices that are already in an active retry cycle. Invoices in progress keep their current settings until the cycle ends. After CPR assigns an invoice to a customer group, the group assignment does not change mid-cycle.

You can adjust retry logic at any time. Updated logic applies to all future payment attempts in active retry cycles. However, changes do not affect the next immediate retry attempt in an active cycle, because that attempt is already scheduled based on the time of the prior payment failure.

The following use cases illustrate this behavior.

Use case 1

• Original schedule:

  • Attempt 1 (payment run) runs on 2/1/24 at 8:00 AM.

  • Attempt 2 (first retry) runs on 2/2/24 at 8:00 AM.

  • Attempt 3 is scheduled for 2/3/24 at 8:00 AM, and so on.

• After you modify the retry time:

  • On 2/2/24, after the second attempt, you update the retry time to 9:00 AM for all future attempts.

  • CPR schedules the third, fourth, and fifth attempts as follows:

    • Attempt 3: 2/3/24 at 8:00 AM (scheduled before the change, not affected).

    • Attempt 4: 2/4/24 at 9:00 AM.

    • Attempt 5: 2/5/24 at 9:00 AM.

In this scenario, attempts that are already scheduled run at their original times, and all subsequent attempts follow the new schedule.

Use case 2

• Original schedule:

  • Attempt 1 (payment run) runs on 2/1/24 at 8:00 AM.

  • Attempt 2 (first retry) runs on 2/2/24 at 8:00 AM.

  • Attempt 3 is scheduled for 2/3/24 at 8:00 AM, and so on.

• After you modify the retry cycle parameters:

  • After the second attempt, you update the retry logic to increase the total number of attempts to 7 and change the retry interval to 48 hours.

  • Attempt 3 is already scheduled for 2/3/24 at 8:00 AM and remains unchanged.

  • The new retry schedule is as follows:

    • Attempt 3: 2/3/24 at 8:00 AM.

    • Attempt 4: 2/5/24 at 8:00 AM.

    • Attempt 5: 2/7/24 at 8:00 AM.

    • Attempt 6: 2/9/24 at 8:00 AM.

    • Attempt 7: 2/11/24 at 8:00 AM.

In this case, the modified retry logic applies only to the remaining future attempts. The third attempt is not affected by the change.

Apply credit memos during CPR

The payment run cannot apply credit memos automatically after the retry cycle for an invoice begins, because the CPR process disables the auto-pay flag. To apply a credit memo during a retry cycle, either apply it manually or use a workflow to apply the credit memo to the invoice.

Notifications

Use Zuora's notification framework to personalize communications with customers about failed payments. When you create a custom event, you can specify the customer group, the attempt number, or both to trigger the notification.

The following figure shows an example custom event configuration.

Ensure that notifications include instructions for customers to update payment information or make a payment.

Workflow

You can configure CPR to trigger a specific workflow after a payment failure. Zuora recommends that you enable email notifications for workflow failures across all workflow instances in the tenant, or for a specific workflow. For more information, see Enable alert notifications for workflow failures.

When you switch settings between tenants, you must reselect the target workflow that you want the retry logic to trigger.