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

Prerequisites

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

Procedure

The configurations for the Configurable Payment Retry involves the following tasks. 

  1. Configure system settings.
  2. Configure callout notifications in Zuora.
  3. Configure customer groups.
  4. Edit retry rules for a customer group.

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.
      response_code_wizard.png
      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.
        response_code_master.png

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

    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, launch the app instance > Settings > API token.

      CPR_Configuration_6.png

  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.

  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.

  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”.CPR_Configuration_8.png

  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.

    CPR_Configuration_13.png

    The Retry Logic window opens:

    CPR_Configuration_14.png

  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.

  • Change Gateway and Retry - Select another payment gateway to be tried against. You need to select a new gateway and configure the retry time. 
    The new gateway will be used for all future attempts in a particular retry cycle. Any new payment or new retry cycle will return to your environment’s default gateway

  • 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 by going to the Settings tab of the workflow.

    CPR_Configuration_15.png

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

Last modified

Tags

Classifications

(not set)