Set Up the Configurable Payment Retry Feature

Knowledge Center > Collect > Setup and Administration > Set Up the Configurable Payment Retry Feature

Set Up 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.

  • The retry logic is triggered via a Payment Run, which will require accounts to be in Auto-Pay on the Account level.

Configure System Settings

  1. Launch feature instance.

  2. Click Settings in the top-right corner, and complete settings details.

  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. Account is the default and 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 configurationCPR_settings.png

  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 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.


  1. Configure Callout Notifications

  2. Configure Feature Settings

  3. Configure Workflow Parameters

Configure Callout Notifications

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 Feature Settings

After launching the Configurable Payment Retry feature, you must use the following steps to complete configuration of the feature:

  1. Configure Customer Groups
  2. Configure Customer Group Priority
  3. Configure Response Codes
  4. Edit Retry Rules

Configure Customer Groups

This function allows you to use characteristics for your customers to group them together. You can then define actions for each of these groups. This function also allows you to prioritize groups so if a customer falls into multiple groups, you can decide which group takes priority. All customers that do not fall into a custom group get processed in the default group.

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

  2. Select the Customer Group box.

  3. Click + New Customer Group to create a new customer group.

  4. Complete the new Customer Group details:

    • Enter Customer Group Name

    • Active Group - Enable to include customer group in retry process

      Customer groups cannot be deleted, only disabled.

    • Filters for Selection - Select the desired field from the list of Zuora objects

      Account, Bill to Contact, Invoice, Payment, Payment Method and Sold to Contact

      Custom fields are included in the dropdown menu.

      Multiple values for custom fields can be added, but only two at a time. Add two, click update, edit the customer group and you will be able to add two more.

      All fields are with the AND statement, Bill to Contact Country = United States AND Bill to Zip = 30305, and does not work with the OR statement currently.

    • Operator - Select the desired operator to correlate to the field

      = (equal to)

      != (not equal to)

      > (greater than)

      < (less than)

      >= (greater than or equal to)

      <= (less than or equal to)

    • Value - Select the value of the desired field to qualify customer in group

      Field Value must match the value displayed in the tenant. For example: Value = United States not Value = US

  5. Click Update.


  • Customer Group Name - Hawaii living
  • Active group - Enabled
  • Filters for selection - SoldToContact.State = Hawaii


Multiple customer groups can be added by following the above steps. Each customer group will be assigned a customer group number when they are configured. If you want all customers with the billing contact in Georgia and Florida to have the same retry logic, each will need to have their own customer group. It is not possible to add the field for BilltoContact State = Georgia and BilltoContact.State = Florida as this is not supported within the tenant (i.e. a bill to contact cannot live in both Georgia and Florida).

All instances come with a configured customer group of “All Remaining Customers” 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 altered.

Configure Customer Group Priority

Each customer group is assigned to a priority to determine the set of retry rules that will be applied when an account meets the criteria of more than one customer group. Change the priority of a group by clicking and dragging the customer group box to the desired priority location. The priority of each customer group is displayed in their listing.

The customer group with the highest priority is the first listed group and the group with the least priority will be at the bottom of the list. The lowest priority group should always be the default customer group of “All Remaining Customers”.


Configure Response Codes

  1. Navigate to the homepage and click Response Codes and Group.


    The Gateway Response Code Mapping window opens:


  2. Each response code is automatically mapped to a specific label of either Hard Decline, Soft Decline or System Error. Success labels for each gateway cannot be changed.

    Change the mapping of a specific code by selecting a new label.

  3. Click + New Label to add a new label for response code for mapping (optional).

    All configured labels will appear in the label header row and have a red trash can icon next to them. Click the icon to remove the added label.

    A label cannot be deleted until all codes under that label have been reassigned.


  4. Click Save.

Edit Retry Rules

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. Select the appropriate Attempt located in the far right box.

    Click Add new Attempt to add more attempts for a response code. A new attempt will be added.

    Click Remove Last Attempt to remove the last attempt in the list.

  3. Complete the response code label retry logic details for each attempt.

    Each response code should have the logic details completed for each attempt.

Retry Logic Details

Identify the Action:

  • Retry - Further attempts to recover outstanding balance will be made.

    1. Choose the retry time amount from the dropdown menu.

    2. Select the increment of time and value.


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

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

  • Change Gateway and Retry - Select another payment gateway to be tried against

    1. Select a new gateway from the dropdown menu. Only configured gateways in Zuora tenant will be populated.

    2. Choose the retry time amount from the dropdown menu.

    3. Select the increment of time and value.


      New gateway will be used for all future attempts in particular retry cycle. Any new payments or retry cycles will return to your environment’s default gateway.

  • Optional: Trigger Workflow and Retry - Create a workflow task with Zuora’s Collection Manager feature for attempt to be tried against.

    1. Enter Workflow Endpoint.

      Obtain your Workflow Endpoint by navigating to Workflow feature instance > Click Edit on the desired Workflow > Settings > URL.

    2. Enter Workflow API Token.

      Obtain your Workflow API Token by navigating to Workflow feature instance > Click Edit on the desired Workflow > Settings > API Token.


      The callout will deliver the accountId and paymentId by default.

    3. Choose the retry time amount from the dropdown menu.

    4. Select the increment of time and value.


  • Optional: Trigger Workflow and Stop - Create a workflow task with Zuora’s Collection Manager feature and no further attempts will be made.

    1. Enter Workflow Endpoint.

      Obtain your Workflow Endpoint by navigating to Workflow feature instance > Click Edit on the desired Workflow > Settings > URL.

    2. Enter Workflow API Token.

      Obtain your Workflow API Token by navigating to Workflow feature instance > Click Edit on the desired Workflow > Settings > API Token.


      The callout will deliver the accountId and paymentId by default.

Configure Workflow Parameters

When configuring the Configurable Payment Retry (CPR) feature of Collect, you can identify specific retry logic actions to be taken. One action possibility is to “Trigger Workflow” which will initiate a call to the Workflow feature and initiate a workflow. Link a different workflow to each action that utilizes the “Trigger Workflow”. When the Configurable Payment Retry feature invokes a workflow, information about each account and payment that has failed in the batch is transferred to the workflow for identification. More than one workflows can be used with CPR’s retry logic, and parameters will need to be configured for each workflow used.

See Integrate Workflow with Other Zuora Products for details about the configuration.

Last modified



(not set)