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.

  • You must have installed and set up the Workflow feature. See Set Up the Workflow Feature.

    The Configurable Payment Retry feature uses your Workflow Endpoint and API Token.

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

Settings Configuration

  1. Launch feature instance.

  2. Complete settings details.

    System Settings:

    • Default time zone - Select the same time zone as set for the tenant 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 configuration

  3. In the Response Code Options section, click Choose.

    • Acquire All New Codes - Add new codes to ensure the most up to date list of gateway response codes

    • Choose Code Level for Each Gateway - Select the level the response code is read from the gateway

      Default code level is Code, but select gateways (such as Adyen and Paypal) will require the Description level to be selected.

      CPR_Configuration_1.png

  4. Click Save.

    CPR_Configuration_1a.png

After completing the configuration, the following custom fields will be available in your tenant:

Object Custom Field Label Custom Field Type

Account

Retry Status

Text

Debit Memo

Only available if the Invoice Settlement feature is enabled in your tenant.

Retry Status

Text

Invoice

Retry Status

Text

Configuration

  1. Configure Callout Notifications

  2. Configure App 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.

    CPR_Configuration_2.png

    CPR_Configuration_3.png

  2. Click Add New Notification.

    CPR_Configuration_4.png

    The Edit Notification dialog box opens:

    CPR_Configuration_5.png

  3. Complete the Edit Notification details.

    Basic Information:

    • Name - Enter “Completed Status”
    • Description - Enter 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 App Settings

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

  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 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 tenant. For example: Value = United States not Value = US

  5. Click Update.

Example:

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

CPR_Configuration_7.png

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

CPR_Configuration_8.png

Configure Response Codes

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

    CPR_Configuration_9.png

    The Gateway Response Code Mapping window opens:

    CPR_Configuration_10.png

  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 select a new label.

  1. Click + New Label to add new label for response code for mapping (optional).
    Adding a new label will also configuration of the specific retry rules.

    CPR_Configuration_11.png

    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.

    CPR_Configuration_12.png

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

    CPR_Configuration_13.png

    The Retry Logic window opens:

    CPR_Configuration_14.png

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

    2. Select the increment of time and value.

      CPR_Configuration_Retry_Time.png

    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 for attempt to be tried against

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

    2. Choose the retry time amount from dropdown menu.

    3. Select the increment of time and value.

      CPR_Configuration_Retry_Time_2.png

      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.

  • Trigger Workflow and Retry - Create a workflow task with Zuora’s Collection Manager app 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 app instance > Click Edit on the desired Workflow > Settings > API Token.

      CPR_Configuration_15.png

      The callout will deliver the accountId and paymentId by default.

    3. Choose the retry time amount from dropdown menu.

    4. Select the increment of time and value.

      CPR_Configuration_Retry_Time_3.png

  • Trigger Workflow and Stop - Create a workflow task with Zuora’s Collection Manager app 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 app instance > Click Edit on the desired Workflow > Settings > API Token.

      CPR_Configuration_Retry_Time_4.png

      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 workflow can be used with CPR’s retry logic, and parameters will need to be configured for each workflow used.

See Collect Feature - Workflow for further details on how to configure your Workflow Parameters.

CPR_Configuration_16.png

Last modified

Tags

Classifications

(not set)