Skip to main content

Configure the Configurable Payment Retry feature

Zuora

Configure the Configurable Payment Retry feature

Before the retry logic of Configurable Payment Retry can be triggered upon the initial failed payment from the payment run, you need to complete the required configurations in both Configurable Payment Retry and Zuora Payments settings. Configuration tasks vary for the different retry logic.

Prerequisites

  • You must have installed the Configurable Payment Retry feature. See Install Zuora Collect AI 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. This task is not required if you plan to use Smart Retry.
  4. Configure callout notifications in Zuora.
  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.
    zuora_disable_retry_rules.png
  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.

    1. Configure App settings:
      • 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.

    2. Set response code levels for payment gateways in the Response Code Settings section. 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. It is recommended that set the response code level to Code in the case of unique error codes and code messages, while set the level to Description in the case of similar error codes but unique code messages.

Configure response codes 

If you plan to use Smart Retry, skip the configuration in this section.

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

    collect-cpr-response-codes.png

  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 all gateway response codes and suggested code mappings. The My Code List is a CSV file containing the custom code list and mappings that you last imported.

      3. Edit the exported CSV file. Make sure the following rules are met.

        • Gateway names and code labels are case-sensitive.

        • You can only use the existing code labels. New code labels can be added only through the UI (Menu icon > Edit Code Labels > Create Code Label).

        • Duplicate response codes are not accepted. 

      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.

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.

    CPR_Configuration_2.png

    CPR_Configuration_3.png

  2. Click Add New Notification.

    CPR_Configuration_4.png

    The Edit Notification dialog box opens:

    cpr_edit_noti.png

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

    collect-cpr-groups.png

  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.
        (((((((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 Smart Retry

Smart Retry utilizes machine learning to assist you in establishing an effective retry strategy. When the time comes to retry a payment, Smart Retry analyzes over 15 characteristics of a transaction such as an account MRR, currency, payment amount, payment gateway, gateway response codes, the issuing bank region, when it last had a failed payment, and more. The analysis is then applied to Zuora’s training dataset. The machine learning model then automatically retries an account’s failed payment at the optimal times. 

To enable Smart Retry, complete the following steps:

  1. On the Customer Groups tab, click the Menu icon in the Actions column and then click Edit Group. The Update Customer Group window opens.

    collect-cpr-editgroup.png

  2. In the Smart Retry section, enable Smart Retry. The Smart Retry settings are displayed.

    collect-cpr-smart-retry.png

  3. Complete the configuration details.
    • Initial Workflow Callout - Optional. Select the workflow to be triggered at the time the account/invoice enters the retry process. In the drop-down list, workflow names are listed based on the Workflow API token entered in the Settings page. The Workflow API token points to a specific Workflow instance where the names of configured workflows are retrieved.
    • Number of Attempts - Specify how many attempts Configurable Payment Retry will execute on the failed payment. If you enter 5, you will see a total of 6 attempts because the first attempt is executed by the payment run and then 5 additional attempts by Configurable Payment Retry. The maximum number of attempts allowed is 20.
    • Number of Days - Specify the days for the retry window, from the time the payment enters retry until the last attempt can be made. The minimum number of days depends on the number of attempts. An inline message will prompt you if the number of days is not valid. The maximum number of days allowed is 90.
    • Final Workflow Callout - Optional. Select the workflow to be triggered upon the completion of a retry cycle. It is recommended to execute a workflow on the last retry attempt as it indicates the account/invoice has completed the cycle and payment was not collected and subsequent action should be taken, such as writing off invoice, canceling subscription, suspending service, etc.
  4. Click Update. Smart Retry is enabled for this customer group.

If Smart Retry is enabled for a customer group, an indication is shown for this group on the Customer Groups tab, and the Edit Retry Rules menu will not be available for this group. To enable editing retry rules manually, disable Smart Retry in the Update Customer Group window and click Update.

Edit retry rules manually

  1. On the Customer Groups tab, click the menu icon in the Actions column and then click Edit Retry Rules. The Edit Retry Rules page opens.

    collect-cpr-editgroup.png

  2. In the left Attempts section, 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 decide and enable the action option first, including whether to stop retrying and whether to trigger a workflow. Other options vary for the enabled action. 

    The following table describes the system behaviors for different scenarios:

      Workflow Selected Workflow Disabled
    Stop Retrying Enabled

    The selected workflow will be triggered but no further attempts will be made.

    No further action to recover the failed payment.

    Stop Retrying Disabled

    The selected workflow will be triggered and retry attempts will be made according to your configuration.

    You need to configure the retry to occur in an incremental time or at a specific time or day.

    To learn about the configuration in Workflow, see Integrate Workflow with Other Zuora Products.

    Further payment attempts will be made according to your configuration.

    You need to configure the retry to occur in an incremental time or at a specific time or day.

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

You can create a backup for your configuration data in Configurable Payment Retry, but neither Collect AI nor Zuora will store your backup data. You need to store the data with your own system.

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. 

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.