Skip to main content

Configure the Configurable Payment Retry feature


Configure the Configurable Payment Retry feature


  • You must have installed the Configurable Payment Retry feature. See Install Zuora Collect Features for more information.

    The Configurable Payment Retry feature uses OAuth to authenticate to your Zuora tenant.

  • The Configurable Payment Retry feature is compatible with the Event Framework and Notifications feature. However, the Configurable Payment Retry feature does not require the Event Framework and Notifications feature to be enabled in your Zuora tenant.

    If the Event Framework and Notifications feature is not enabled in your Zuora tenant, Zuora recommends that you submit a request at Zuora Global Support and ask for the feature to be enabled.

  • If you want Configurable Payment Retry to trigger a workflow as a retry action, you must install Workflow and design a workflow to implement additional retry logic. 
    Configurable Payment Retry uses the endpoint and API-Token of the workflow designed for payment retries.

  • Auto-Pay is set to True for accounts using Configurable Payment Retry.

Disable the payment run retry rules in Zuora

To avoid the payment retry rules in Zuora from conflicting with the retry rules in Configurable Payment Retry, Zuora recommends that you disable the payment run retry rules in Zuora.

  1. In Zuora UI, navigate to Settings > Payments > Configure Payment Retry Rules.
  2. Turn off the Enable Payment Run retry rules option.
  3. Click save.

Configure system settings

  1. Start Configurable Payment Retry.

  2. Click Settings in the top-right corner. The settings page opens.

  3. Complete the configurations in the System Settings section. Click Save to save the configurations.

    • Default time zone - Select the same time zone as for your Zuora environment to avoid payment errors.

    • Retry level - Select the desired level retry attempts will be counted against. Invoice is the preferred method.

    • Process multiple documents - Enable to make a single payment for multiple billing documents

    • Default number of attempts - Select the default number of attempts in each customer group. Additional retry attempts can be also be added to configured customer groups. This is the number of default attempts for each attempt, but can be altered in later steps

    • Default label type - Identify the code mapping label for any unrecognized response codes

    • API Token - Token is generated on feature instantiation and should be copied for Callout Notification configuration

  4. In the Response Code Options section, configure response codes and response code levels for payment gateways. 

    • Use the Response Code Wizard to edit or add response codes or code descriptions, or change code labels (also known as code categories) from one to another (excluding the Success label). Click Master CSV to export the master code list into a CSV file. The master code list can be seen as a template that contains all gateway response codes and suggested code mapping. You can make changes in the exported master CSV file and import it back into the feature. Once imported, the new code list will override the existing code configuration. You can click Code Maps in the top-right to verify whether the changes or new response code are picked up in the system.
      When editing a code list CSV file, you need to pay attention to these rules:

      • Gateway names and code labels (also known as code categories) are case-sensitive.

      • You can only use existing code labels (excluding Success).

      • Duplicate response codes cannot be accepted. 

      • New code labels can be added only in the Code Maps page.

    • Click Set Code Level to configure the response code level for each gateway. Select either Code or Description for each gateway. 

      The response code level determines whether code or code description will be used to identify payment errors. Some payment gateways use codes, such as 203 or 1005, to identify payment errors, and some payment gateways use descriptions, such as insufficient funds or fraudulent card. Contact your payment gateway to learn more about which code level is used.

  5. Click Code Maps in the top right, or click the Response Codes and Groups box on the homepage to view and modify the response code mapping relationship. 
    Each response code is mapped to one of the code labels (Success, Hard Decline, Soft DeclineSystem Error, and custom labels). The default mapping is a recommendation. A response code can be reassigned among non-Success code labels. 
    • Click +New Label to add a custom label. Custom labels can be deleted only after all response codes are reassigned to other labels.
    • Click Save to save your settings.
      RC Mapping.png

After completing the configuration, several custom fields will be available in your tenant. See Custom Fields of Collect for details.

Configure callout notifications in Zuora

Callout notifications are used to notify Configurable Payment Retry that a payment run has completed. This initiates the retry process for all payments that failed during the payment run.

If your tenant utilizes the Event Framework and Notifications feature, contact Zuora Global Support to enable Legacy Notifications.

  1. In Zuora environment, navigate to Settings > Payments > Setup Profiles, Notification and Email Templates.



  2. Click Add New Notification.


    The Edit Notification dialog box opens:


  3. Complete the Edit Notification details.

    Basic Information:

    • Name - Enter “Completed Status”
    • Description - Enter the desired description of notification (optional)
    • Active - Enable

    Event Parameters:

    • Payment Run Result Status - Select Completed

    Basic Information:

    • Enable Callout

    • Select Default email template for Payment Run Completion with Completed Status

    • Base URL - Enter

    • Parameter Name - Select PaymentRunID

    • Parameter Value - Select PaymentRun.PaymentRunID

    • HTTP Method - Select POST

    • Body Format - JSON (only required for tenant using the Event Framework and Notifications feature)

    • Callout Authentication - Enable Username/Password

    • Username - Enter the Zuora username associated with the Zuora tenant

    • Password - Enter the CPR app instance API Token

      To obtain your API Token, launch the app instance > Settings > API token.


  4. Click Save.

Configure customer groups

You can group your customers based on certain criteria so that they can use the same set of retry rules. Customer groups have priorities. If a customer falls into multiple customer groups, the retry rules for the group of the highest priority will be applied. All customers that do not fall into a custom group get processed in the default group ("All Remaining Customers").

  1. Navigate to the homepage (select Configurable Payment Retry located in the top left).

  2. Click the Customer Group box. All customer groups that have been defined will display.
    The predefined “All Remaining Customers” is intended as a catch-all to ensure all accounts are included in the retry process. This customer group cannot be removed or disabled, but the retry rules can be edited. No filters are allowed for this group.

  3. To create a new customer group, complete the following steps:

    1. Click + New Customer Group.

    2. Enter a name to identify the customer group.

    3. If you want the group to be included in the retry process, select Active Group

    4. Use the fields, operators, and values to define filters for the group. Currently, only AND operator is supported.
      For example, if you want to define a customer group for customers living in Hawaii, you can create a customer group with the name "Hawaii living" and use "SoldToContact.State = Hawaii" as the filter.
      Field value must match the value displayed in the tenant. For example: Value = United States, not Value = US.
      If you want customers with the billing contact in Georgia and Florida to have the same retry logic, you need to create two groups and assign them the same retry logic. Combining the two filters "BilltoContact.State = Georgia" AND "BilltoContact.State = Florida" will generate no results, because a bill-to-contact can only live in one state.

    5. Click Create. CPR_Configuration_7.png

  4. To change the priority of a customer group, drag the customer group and drop to a desirable location.
    If a customer is in multiple customer groups, the retry rules for the group with the highest priority will be applied. The customer group with the highest priority is on the top of the list and the group with the least priority is at the bottom.
    The lowest priority group should always be the default customer group of “All Remaining Customers”.

  5. To edit the retry rules for a customer group. click Edit Retry Rules in the customer group. To learn more how to edit retry rules, see the following task. 

Edit retry rules for a customer group

Retry rules are configured for each customer group to indicate the required action for each retry attempt. A customer group attempt can be easily added or removed and customized to fit your needs.

  1. After a customer group has been created, click Edit Retry Rules.


    The Retry Logic window opens:


  2. In the far right box, select the attempt that you want to edit.

  3. Complete the details for the available responses in the attempt. For each response, you need to select the action first. Other options differ based on the action that you select. 

  • Retry - Further payment attempts will be made. You need to configure the retry to occur in an incremental time or at a specific time or day of week (or month).

    Zuora payment runs process payments every 15 minutes (on the quarter hour) in the order that they were received. Retry cycles with a time increment of less than 30 minutes are not guaranteed to process at the exact time due to payment run timing.

  • Stop Retrying - No further action to recover outstanding balance will be made.

  • Trigger Workflow and Retry - Trigger a workflow and retry payments. You need to enter the endpoint and API-Token of the desirable workflow, and configure the retry time. 
    The best practice is to link a different workflow to each trigger workflow action.
    The callout to the workflow will deliver two parameters, accountId and paymentId, to the workflow for further processing. To learn about the configuration in Workflow, see Integrate Workflow with Other Zuora Products.
    The endpoint and API-Token can be obtained in the Settings tab of the workflow.


  • Trigger Workflow and Stop - Trigger a workflow and no further attempts will be made. You need to enter the endpoint and API-Token of the workflow.
    The callout to the workflow will deliver two parameters, accountId and paymentId, to the workflow.

Export and import your configurations

Zuora recommends that you back up your configurations regularly so that you can restore a previous copy of configurations in case of serious errors.

You can back up and restore only the response code mappings or all configurations.

Export and import response code mappings

You can use the Response Code Wizard on the settings page to export and import response code mappings. 

To export the existing response code mappings into a CSV file, click My Codes CSV.

To import code mappings from a previously saved file, click Choose File, select the file, and click Import Codes.


Export all configurations

  1. On the home page of Configurable Payment Retry, click the Settings button in the top-right corner.
  2. On the settings page, click Export in the Import / Export Configurations section.
    All configurations (in JSON format) will be displayed in the window that opens.
  3. Copy the JSON code and paste it to a document that is in the cloud. You can include the current date in its title to help you distinguish different copies of the configurations.

Import a copy of all configurations

When you import configurations, all existing configurations, including customer groups, code labels, and code mappings, will be overwritten. 

  1. On the home page of Configurable Payment Retry, click the Settings button in the top-right corner.
  2. On the settings page, click Import in the Import / Export Configurations section.
    The window for importing configurations displays.
  3. Copy the JSON code of the configurations that you want to import. Paste it to the text field and click Import.
    You can see Import is changed to Update Setting while the configurations are being updated. Once the update completes, the window closes.