Skip to main content

Configurable Payment Retry best practices

Zuora

Configurable Payment Retry best practices

  1. Last updated
  2. Save as PDF

This section describes the best practices and common use cases related to the Configurable Payment Retry (CPR) application.

The best practices are categorised as follows:

Install CPR

Configurable Payment Retry requires OAuth credentials to properly authenticate to your Zuora tenant and deploy necessary custom fields. After app creation, you can add OAuth credentials to an existing instance; however, it will not create the required custom fields in arrears. Create the custom fields manually, as they are required to process any application. For more information on the required custom fields, see Custom Fields of Collections.

When deploying Configurable Payment Retry, ensure you install the Production build version. Use this build in all tenant environments, testing or production.

AdvancedPaymentRetry_Collect_NewConfiguration.png

Stopping an app instance of CPR does not prevent already scheduled retries from executing. To stop further retries:

  • For Invoices and Accounts with existing retry cycles, use the CPR APIs to help remove them. For more information, see Developer Center.
  • Deactivate the callout notification to prevent new cycles from beginning. For more information, see CPR configuration details.

Response Code Mapping

While creating the Configurable Payment Retry (CPR) app, Zuora provides a list of response codes from any gateway configured in your tenant. To add more response codes or gateways, Configure Response Codes.

You can create additional mapping headers for a more flexible retry logic.

For instance, you can have the following headers:

  • Hard Decline - Never retried
  • Medium Decline - Retired, but not as frequent as a soft decline (for example, retry twice)
  • Soft Decline - Retried, to exhaust all possible retry attempts.

For example, you may be uncertain whether a specific payment error should be retried. In that case, it is advisable to map it as a 'Soft Decline' and monitor for further insights to determine if it's recoverable. You can change mappings at any time.

If a new gateway is added to your payment operations after you have installed CPR, you must add the new gateway's codes to your existing mapping. In the app instance, navigate to Response Codes > Menu > Export CSV and select Master Code List. 

  1. Copy the codes of your new gateway.
  2. Add to 'My Code List' export.
  3. Upload into CPR instance.

BulkEditResponseCodes_CPR.png

Response Code Mapping Edits

Once a mapping is modified (for example, switching from 'Hard Decline' to 'Soft Decline'), CPR will utilize this change in future scheduled retry attempts. However, the next immediate retry attempt that was already scheduled before the configuration change will not be impacted. Any retry cycles that have already been completed will not be restarted due to the configuration change.

To immediately stop further retries, you must manually stop the retry cycle. For more information on using the CPR APIs to complete this action, see the Zuora Developer Center. 

When bulk editing response codes or migrating CPR app instance configurations between environments, always download and save the current mapping list (referred to as 'My Code List'). After making any edits to your list, save your updated 'My Code List' for easy reference.

When importing a new or modified list of response codes, it will replace all existing codes. If you want new codes, add them to your existing code list and then import them.

Implement CPR

This section describes the best practices for implementing CPR.

Outstanding invoices

Invoices that may have begun a retry process before the implementation of CPR can still be entered into CPR for further retry attempts. However, the retry cycle will reset to the beginning of the CPR-defined cycles. You cannot select a specific retry cycle for a particular payment attempt; all CPR retry cycles will commence from the start and proceed through any configured retry attempts.

To prevent an outstanding invoice from being considered for retry, set the invoice’s auto-pay field to "false." This will ensure the invoice is excluded from tenant payment runs and will not be passed to CPR for additional retry attempts.

Configurable Payment Retry and Zuora’s retry logic should not be run simultaneously.

Retry Configuration

Before creating multiple customer groups or implementing complex retry logic, it is important to understand the ideal retry scenario for your business and customers. Consider whether additional customer groups are needed, whether segmentation based on specific identifiers is required, or whether the primary focus should be on 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 with your payment gateway provider on best practices surrounding payment failures, including which attempts should or should not be retried. CPR can be configured to meet most requirements, but will not automatically restrict any flows.

Zuora does not offer the ability to revert settings within the application. If you are making significant changes to the configuration, it is highly recommended to export your settings and save them externally. These exported settings can then be imported to revert changes if necessary.

It is recommended to configure retry at the Invoice level rather than the Account level in the CPR settings. Retry at the invoice level allows for manipulation of only the invoice auto-pay flag, ensuring that the account will remain eligible for future tenant payment runs. Retrying at the account level affects both the account and invoice auto-pay flags.

  • Invoice level retry(preferred)
    • Once an invoice enters the retry process, its auto-pay flag is set to false and will not be altered by the CPR system again.
  • Account level retry
    • Once an invoice enters the retry process, both the invoice and account auto-pay flags are set to false.
    • The account auto-pay flag will only be reset to true if payment is successfully collected via a CPR-initiated payment retry attempt.

CPR In-Process

Verifying the CPR process execution

Once CPR (Credit Payment Retry) is configured properly, several steps will occur after the tenant payment run is executed to confirm its functionality.

When CPR is properly configured, there are a series of steps which will occur after the tenant payment run has been executed and can be used to identify the system is properly working.

  • Verify Callout Notification - The payment run completion callout must be configured to pass failed payments from the tenant payment run to CPR. To check if the callout has been triggered:
    • Navigate to Settings > Payments > Setup Profiles, Notification and Email Templates > Notification History.
    • Ensure the callout notification has been successfully triggered.
      Common errors:
      • Incorrect Parameter Name (PaymentRunID) or Value (PaymentRun.PaymentRunID)
      • Incorrect Authentication (use the API token of the instance in your desired environment)
  • Review retry status for updates - Once CPR is invoked, it will retrieve the failed payments and schedule the next retry based on configured logic. CPR will also update the retry status on both the account and invoice, and disable the invoice autopay flag.
    • If the retry status of an invoice shows a Failure state, CPR was called but encountered an issue, either due to configuration settings that prevent future retries or a payment processing error.
    • To view the error and gain insights, navigate to CPR > Failures and locate the relevant payment.
  • Test CPR Configuration Flows - During testing, you can attach a workflow to each payment attempt, which will trigger an email or other notification when a retry is executed.
  • Review the Retry Cycle Schedule - To determine when the next CPR retry attempt is scheduled:
    • Use the CPR System Health Dashboard.
    • Alternatively, query the collections_retrycycles schema in Data Query or use the CPR API to retrieve cycle information.

Stopping Scheduled Retries

Stopping an app instance of CPR will not prevent retries that are already scheduled from executing. To prevent further retries:

  • For Invoices and Accounts with Existing Retry Cycles: Use the CPR APIs to remove the cycles. For more information, see Developer Center.
  • To Prevent New Cycles from Starting: Deactivate the callout notification. For more information, see CPR configuration.

Modifying Retry Status

Changing the retry status of a document or account will not prevent retries from being executed. To stop further retries:

  • For Existing Retry Cycles: Use the CPR APIs to remove the cycles. For more information, see Developer Center.
  • To Stop New Cycles: Deactivate the callout notification. For more information, see CPR configuration.

Modify an existing retry cycle 

Once a CPR cycle has started, it cannot be paused or resumed. The retry cycle will continue attempting retries until either all attempts are exhausted or the invoice balance is cleared. To manually stop a retry cycle, use the remove invoice from retry cycle API. Once stopped, the cycle cannot be restarted; if restarted, it will begin from the first retry attempt.

You can modify parameters for a customer group at any time. Any updated parameters will apply to future evaluations, as each invoice is assigned to a customer group upon entry into CPR. However, changes will not affect invoices already in an active retry cycle. Invoices in progress will retain their current settings until the cycle concludes. Once an invoice is assigned to a customer group, its group assignment will not change mid-cycle.

Retry logic can be adjusted at any time and will apply to all future payment attempts in active retry cycles. However, changes will not affect the next immediate retry attempt in an active cycle, as these attempts are scheduled based on the time of the prior payment failure.

For example,

Use case1

  • Original Schedule:
    • Attempt 1 (payment run) is executed on 2/1/24 at 8:00 AM.
    • Attempt 2 (first retry) occurs on 2/2/24 at 8:00 AM.
    • Attempt 3 is scheduled for 2/3/24 at 8:00 AM, and so on.
  • After Modifying Retry Time:
    • On 2/2/24, after the second attempt, the retry time is updated to 9:00 AM for all future attempts.
    • The third, fourth, and fifth attempts are now scheduled as follows:
      • Attempt 3: 2/3/24 at 8:00 AM (scheduled before the change, will not be impacted)
      • Attempt 4: 2/4/24 at 9:00 AM
      • Attempt 5: 2/5/24 at 9:00 AM

In this scenario, attempts already scheduled will proceed with their original times, while all subsequent attempts follow the new schedule.

Use case2

  • Original Schedule:
    • Attempt 1 (payment run) is executed on 2/1/24 at 8:00 AM.
    • Attempt 2 (first retry) occurs on 2/2/24 at 8:00 AM.
    • Attempt 3 is scheduled for 2/3/24 at 8:00 AM, and so on.
  • After Modifying Retry Cycle Parameters:
    • After the second attempt, the retry logic is updated 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 will remain unchanged.
    • The new retry schedule will be:
      • 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, with the third attempt being unaffected by the change.

Apply CM during CPR

Credit memos cannot be applied automatically through the payment run once the retry cycle for an invoice begins, as the CPR process disables the auto-pay flag. To apply a credit memo during a retry cycle, you must either apply it manually or use a workflow (WF) to apply the credit memo to the invoice.

Notifications & Workflow

Notifications

Use Zuora’s Notification Framework to personalize communications with customers regarding failed payments. By creating a custom event, you can specify the customer group and/or attempt number to trigger the notification.

For example,

EditCustomEvent_CPR.png

When sending notifications, ensure they include instructions on how customers can update payment information or make a payment.

Workflow

CPR can be configured to trigger a specific workflow after a payment failure. It is recommended to 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 navigating settings between tenants, you must re-select the target workflow to be triggered within your retry logic.

Monitor CPR

This section describes the best practices for monitoring the operations of CPR and impacted invoices.

CPR Payment Execution

For more information on verifying CPR execution, see Implement CPR section. Additionally, the Failure tab within your CPR instance provides insights into any processing failures encountered, preventing CPR from continuing execution.

Check CPR performance

To monitor the performance of your CPR strategies, use the CPR Dashboard. Navigate to Administration > System Health > Configurable Payment Retry Dashboard to view the performance of your CPR strategies. For more information, see the Configurable Payment Retry dashboard.

Gateway Errors and Payment Attempts

Use the gateway error responses to determine whether payment failures should be mapped differently or if tailored logic is required for frequently received responses.

For example,

  • If there is a high number of failures related to expired payment methods, consider investigating the use of payment method updater service.
  • If there is a high number of failures due to insufficient funds, consider altering the retry logic schedule to retry on more favorable days for your subscriber base or modify the communication sent to better align with retry attempts.

Reviewing Payment Attempt analysis

Examine the Payment Attempt analysis to evaluate the success of configured retry attempts.

For example,

If you are retrying payments 10 times and never see a recovery on the last or second-to-last attempt, consider eliminating these retries.

Reviewing Customer Group performance

Reviewing the performance of a customer group provides insights into how the retry logic impacts payment recovery. If changes are required, you can modify the existing group or create a new one to facilitate easier data evaluation.

For example,

Consider a customer group that has a high number of documents with a retry status of Complete-External. It indicates that something is happening to the document between retry attempts, resulting in zero balance and requiring no retry. This can occur due to one-off payments or document write-offs.