Configure the Configurable Payment Retry feature

Prerequisites

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

• The feature must be created by using the OAuth credential. See Verify and update OAuth credentials for more information.

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

Procedure

Configuring Configurable Payment Retry involves the following tasks:

1. Disable the payment run retry rules in Zuora.
2. Configure system settings.
3. If you plan to edit retry rules manually based on gateway response codes, configure response codes.
4. Configure callout notifications for Configurable Payment Retry.
5. Configure customer groups.
6. Edit retry rules for a customer group, through either editing retry rules manually or enabling AI-driven Smart Retry.
7. Optional: Export or import your settings.

Disable the payment run retry rules in Zuora

Ensure that out-of-box payment retry is not running in Zuora environment. Failure to disable the out-of-box payment retry while running Configurable Payment Retry will result in disruption to the retry service.

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

Complete the following steps to configure the system settings for your retry logic:

1. Start Configurable Payment Retry.

2. Click the Settings tab. The API Token at the top is the API token of Configurable Payment Retry used for configuring the payment run callout notification in a later step.

3. On the Settings tab, complete the following configurations for your needs and then click Save All Settings to save the updates.

   • Instance 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 a single Payment for all Invoices/Debit Memos that are due on an account - Click to enable or disable the setting.

   • Process payments even if the default payment method is closed - Click to enable or disable the setting.

   • Auto-apply unapplied credit memos during payment runs - Click to enable or disable the setting.

   • Auto-apply unapplied payments during payment runs - Click to enable or disable the setting.

   • Default label - Select the default code mapping label to classify any unknown gateway response codes. Skip this setting if you plan to use Smart Retry.

   • Workflow API token - The Workflow API token was generated during feature installation and indicates which Workflow is being used for the Workflow callouts in the retry logic.

Configure response codes 

The response code mapping for each gateway is presented on the Response Codes tab. Each response code is mapped to one of the code labels, including the built-in labels (Hard Decline, Soft Decline, System Error) and the custom labels.

If you plan to edit the retry rules manually based on gateway response codes, complete the following steps to configure the response code mapping:

1. Click the Response Codes tab. The default response code mapping is shown on the Response Codes tab if you did not edit the mapping previously. The default mapping is a recommendation. A response code can be reassigned to other available code labels.

   

2. On the Response Codes tab, configure the response codes and mappings for your needs:

   • To reassign response codes to other available code labels, click the Edit icon in the upper right and click the radio button under the desirable code label. You can use the Gateways filter and the Search bar to quickly locate the response codes. After you complete your editing, click Save All Mappings.

   • To add a custom code label, complete the following steps:

     1. Click the Menu icon in the upper right and then click Edit Code Labels.

     2. In the Edit Code Labels window that opens, click Create Code Label.

     3. Input the name and description for the custom label and click Create. You can delete a custom label if no response code is mapped to this label.

   • To edit the response codes in batch by importing your own mapping file, complete the following steps:

     1. Click the Menu icon in the upper right and then click Bulk Edit Response Codes.

     2. In the Bulk Edit Response Codes window that opens, export the code list as the base for your editing by clicking Export CSV and then selecting Master Code List or My Code List. The Master Code List is a template in CSV format that contains gateway response codes and suggested code mappings. The Master Code List may not contain all response codes applicable to the gateway.  Check with your gateway to ensure all codes are correctly listed and mapped. The My Code List is a CSV file containing the current code list and mappings.

     3. Edit the exported CSV file to include new response codes in your mapping. Make sure the following rules are met.

        • Gateway names and code labels are case-sensitive.

          You must use the payment gateway type names. Use the List all payment gateways REST API to identify the gateway type names. In the response, the type field of each returned gateway indicates the type name of that gateway.

        • Only existing code labels can be mapped to codes. New code labels can be added only through the UI (Menu icon > Edit Code Labels > Create Code Label).

        • Duplicate response codes are not accepted. 

          The addition of new codes will not be added to the master list.

     4. When you complete your editing, in the Bulk Edit Response Codes window, import the custom CSV file by choosing it from your computer and clicking Import CSV. Once imported, the new code list will override the existing code configuration.

        Importing a new CSV will override all existing response code configurations.

Configure callout notifications for Configurable Payment Retry

Callout notifications are used to notify Configurable Payment Retry that a payment run has been completed, regardless of whether the payment run was triggered by Advanced Payment Manager or Zuora Payment Run. This initiates the retry process for all payments that failed during the payment run.

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 https://advanced-payment-retry---collect.apps.zuora.com/api/v1/payment_run

   • 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, navigate to Configurable Payment Retry instance, click the Settings tab, and the API Token is shown at the top. If it is not shown, click the Show API Token button.

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. Click the Customer Groups tab. All customer groups that have been defined are displayed. 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.

   

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

   1. Click Add Group.
   2. Enter a name to identify the customer group.
   3. If you want the group to be included in the retry process, enable Active Status. Once enabled, the customers who meet the definition will begin filtering into the group.
   4. Define a customer group with either filters or custom ZOQL query:
      • To use the filters, click the Plus icon and then configure the fields, operators, and values. You can add multiple filters but only AND relation 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.

      • To use the custom ZOQL query, enable the Custom ZOQL Query option and then enter filter statements for the WHERE clause of a ZOQL query. Here is an example. Note the Custom ZOQL Query does not support querying subscription data. The query only supports PaymentApplication, or InvoicePayment objects add and their related objects.

        (((((((Account.AccountNumber like '%1') or Account.AccountNumber like '%2') or Account.AccountNumber like '%3') or Account.AccountNumber like '%4') or Account.AccountNumber like '%5') and Account.Batch = 'Batch1')

   5. If you plan to use the AI-driven Smart Retry logic instead of editing retry rules manually based on gateway response codes, enable Smart Retry. See Enable Smart Retry for details about the configuration. Once enabled, Smart Retry will override existing retry logic with AI machine learning. 

   6. Click Create. 

3. To change the priority of a customer group, click Edit Priority, drag the customer group and drop to a desirable location, and click Save.

   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”. If a customer is in multiple customer groups, the retry rules for the group with the highest priority will be applied.

If you need to edit an existing customer group, complete the following steps:

1. On the Customer Groups tab, click the menu icon in the Actions column.
2. Click Edit Group. 
3. Edit the customer group in the Update Customer Group window and then click Update.

Edit retry rules for a customer group

Retry logic is configured for each customer group to indicate the required action for the retry attempt. For a customer group, you can select to configure the retry logic with either of the following methods:

• Enable the AI-driven Smart Retry to automatically retry failed payments at optimal times.
• Manually configure the retry rules for each retry attempt based on gateway response codes.

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 create a backup and restore the following data through exporting and importing your configurations:

• Response code mappings
• System settings configured on the Settings tab
• Customer groups

To export/import your configurations, complete the following steps:

1. Click the Settings tab.
2. On the Settings tab, scroll down to the Data Configurations section.
   • To export the configurations, click Export and then the configuration data will be displayed in JSON format in the window. Copy the JSON code and paste it into 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.
   • To import the configurations, click Import. In the window that opens, copy and paste the JSON code of the configurations that you want to import into the text field and click Save.

     When you import configurations, all existing configurations, including customer groups, code labels, code mappings, and system settings, will be overwritten. Any workflows associated with retry logic must be updated to point to the appropriate workflows in the production environment.

Set up a test to compare Smart Retry and your existing retry logic

To compare Smart Retry and your existing retry logic configured based on gateway response codes, you can set up an A/B test by replicating your current retry logic to the Smart Retry customer group.

1. Create a new customer group for Smart Retry.

   1. Name the group. It is recommended to name the new group to be easily identified as using Smart Retry, such as “Group Smart Retry”.

   2. Create filters for the “Group Smart Retry” customer group. It is recommended to use ZOQL filter to help segment out the number of the customers. To use ZOQL filter, enable the Custom ZOQL Query option.

      The ideal situation is to have 50% of the customers entering your smart retry customer group and the other 50% continuing to use previously configured logic.

      Here are two examples. Filters can be added such as region, gateway, or other customer filters. It is recommended to use a random filter to obtain true A/B testing.

      (((((Account.AccountNumber like '%6') or Account.AccountNumber like '%7') or Account.AccountNumber like '%8') or Account.AccountNumber like '%9') or Account.AccountNumber like '%0')

      (((((Payment.GatewayResponseCode = '15006') or Payment.GatewayResponseCode = '15007') or Payment.GatewayResponseCode = '15008') or Payment.GatewayResponseCode = '15009') and Payment.Gateway = 'PayPalEC') and (Account.AccountNumber like '%6')

2. Apply the existing retry logic to the “All Remaining Customers” group.

3. Enable Smart Retry on “Group Smart Retry” and configure the retry logic to mimic your existing retry logic. 

   For example, if your current retry logic retries payments every 48 hours for 4 attempts, you can set up the time constraints of Smart Retry as the following:

   • Number of attempts: 4

   • Number of days: 8

   • Optional: Add workflows upon entry into retry and/or upon exit. The best practice is to include a workflow upon exit to ensure any account/invoice that was not collected to address the outstanding balance, such as writing off invoice, suspending/canceling subscription, sending customer communications, etc.

4. Ensure that the “Group Smart Retry” group is of a higher priority than the “All Remaining Customers” group.

It is recommended to run the A/B test long enough (at minimum for 4 to 6 weeks) for several retry cycles to complete.