Skip to main content

Create and manage Payment Gateway Routing rules

Zuora

Create and manage Payment Gateway Routing rules

  1. Last updated
  2. Save as PDF

Use the instructions in this article to create gateway routing rules and manage them for your needs. Before creating a rule, ensure the Payment Gateway Routing feature is enabled.

Introduction

With the Payment Gateway Routing feature enabled, you are able to define your own custom rule for processing payments through preferred gateways. The rules determine when to route transactions to preferred payment gateways and to handle fallback scenarios in case those transactions fail.

A rule is presented as a route map, which consists of one trigger, one or more conditions, and actions:

  • The trigger determines when to trigger the defined rule. 
  • The condition defines how to categorize payments and generates rule branches, based on attributes of payments or payment methods. 
  • The action assigns a gateway instance to payments that match the condition of a branch.

The following image shows a rule example:

routing-rule-example.png

The following table describes the components supported in Payment Gateway Routing rules.

Component Type Description

Trigger

Payment Trigger

When initializing an electronic payment through an API operation, a manual operation from the UI, or a payment run, the Payment Gateway Routing rule is triggered.

Condition

Payment Condition




 

Use any of the following attributes of payments to categorize transactions and generate branches of the rule:

  • Source: Whether the payment is initialized through one of the following sources. If no Source condition is configured, payments from all the following sources will be captured by Payment Gateway Routing.
    • Payment Run
    • UI
    • Payments API
    • Subscriptions API 
    • Orders API
  • Amount: The amount of the payment. The format must be an integer.
  • Currency: The currency of the payment.

Payment Method Condition


 

Use any of the following attributes of payment methods to categorize transactions and generate branches of the rule:

  • Type: Payment method type.
  • BIN: The Bank Identification Number of a payment method.
  • Country: The issuing country of the credit card.

Split Traffic Condition

Define the percentage of payment volumes processed on two different branches. The sum of these numbers must be 100. 

Response Condition

Perform an in-transaction retry with another payment gateway based on the Gateway Response Code without needing to wait for another retry cycle.

The Response Condition can only be used behind an Assign Gateway Action. Up to two in-transaction retries are allowed in a branch. This means behind the first Assign Gateway Action, you can use the Response Condition - Assign Gateway Action pair at most twice.

Payment gateways used in in-transaction retries must support the Sharing NTI feature.

Action

Assign Gateway

Assign a payment gateway instance to a branch of the rule. This payment gateway will be used to process payments that match the conditions of this branch.

The Assign Gateway Action is either the end of a branch or followed by a Response Condition to do an in-transaction retry.

Prerequisites

  • The Payment Gateway Routing feature is enabled on your tenant. For how to enable this feature, see Enable Payment Gateway Routing.
  • You are on the Payment Gateway Routing tab. To navigate to the Payment Gateway Routing tab:
    1. Click your username in the upper right and navigate to Settings > Payments > Setup Payment Gateway. 
    2. Click the Payment Gateway Routing tab.

Create a rule

You can create a rule through one of the following methods:

Create a rule from scratch

The following demonstration shows that you can easily build up a rule from scratch in the Zuora UI. For detailed instructions, see the section behind this demonstration.

routing-rule-demo-4.gif

Complete the following steps to define a rule:

  1. In the Routing Rules section on the Payment Gateway Routing tab, click Create Rule > Create from Blank.
  2. Add a Trigger component. From the Component Library on the left, drag and drop the Payment Trigger component to the trigger node in the editing area.
  3. Add Condition components. You can drag and drop to move your rule map.
    1. Click the plus icon on the connector line.
    2. Select a condition type for your needs. The condition builder dialog opens. For more information about each condition type, see the preceding Introduction section.
    3. In the Basic Info section, enter a name for the condition in the Description Name field. This name will be displayed in the condition node.
    4. In the Route Condition section, define route conditions. Each route condition represents a branch of the rule.
      1. Define the first route condition.

        Enter a label for the branch, select an attribute from the field on the left, select an operator from the field in the middle, and specify an attribute value in the field on the right. 

        The Split Traffic Condition has only two branches. For each branch, enter a label for the branch in the left field and enter an integer in the right field.

        If you want to combine multiple attributes to handle complex gateway decision-making, you can add multiple condition items. Click Add Rule, and then define the item. The items are joined with an AND comparator. For example, you can define an item for Amount Greater Than 100, and an item for Currency Equal To US Dollar. The transactions that meet this condition (amount > 100 AND currency = USD) will be routed to this branch.

      2. Define more route conditions by clicking Add Conditional Branch. Repeat step i to define the items of each condition.
      3. Click Save.
  4. Add an Action component:
    1. Click the plus icon on the connector line behind the last condition of a branch.
    2. Click Assign Gateway under Actions.
    3. Enter a name for the action and select a payment gateway instance available on your tenant from the Payment Gateway list.
    4. Click Save.
  5. If you want to do an in-transaction retry based on the Gateway Response Code without needing to wait for another retry cycle, add a Response Condition component, and then add an Assign Gateway Action.
  6. After you finish editing all branches, give your rule a name:
    1. Click the pen icon in the upper left of the page.
    2. Enter a name in the field next to the Rename button.
    3. Click Rename.
  7. Click Save in the upper right of the page to save your rule.

The rule is created in inactive status. To activate it, see Activate a rule for more information. 

The newly created rule will be the last one in the rule priority list. To change the order of the priority, see Prioritize rules.

Create a rule with a template

The following pre-defined routing rule templates are available to help you quickly build a rule:

Template Description
Route to Backup Gateways Route the payment transaction to a backup payment gateway in case the primary payment gateway fails to process the payment.
Route by Currency Route payments by currency to specific gateways leading to advantages such as higher success rates.
Route by Splitting Traffic Route a percentage of traffic payment to a specific gateway to achieve benefits such as meeting contractual volume obligations.
Route on Multiple Conditions Route payments based on a combination of multiple facets to achieve the balance between success rates, processing fees, and contractual obligations with the providers.

Complete the following steps to create a rule by using a template:

  1. On the Payment Gateway Routing tab, click Create Rule > Create from Template in the Routing Rules section.
  2. In the Rule Templates dialog, select a template and then click Use Template. The pre-defined rule is presented on the canvas.
  3. To customize the pre-defined rule, perform the following operations according to your needs:
    • To edit a component, click the more icon icon-more.png on the component and click Edit. Ensure that you edit the Assign Gateway Action components to assign specific gateway instances to each branch.
    • To delete a component, click the more icon on the component and click Delete.
    • To add a component in the middle of a path:
      1. Delete the existing component at the position where you want to add the new component. The existing component and all the components after it will be deleted.
      2. Click the plus icon on the connector line and add the new component.
      3. Add other components to build the rule path. 
    • To do an in-transaction retry based on the Gateway Response Code without needing to wait for another retry cycle, add a Response Condition component behind the existing Assign Gateway Action component, and then add another Assign Gateway Action after the Response Condition component.
  4. After finishing your editing, give your rule a name:
    1. Click the pen icon in the upper left of the page.
    2. Enter a name in the field next to the Rename button.
    3. Click Rename.
  5. Click Save in the upper right of the page to save your rule.

The rule is created in inactive status. To activate it, see Activate a rule for more information. 

The newly created rule will be the last one in the rule priority list. To change the order of the priority, see Prioritize rules.

Activate a rule

Before a routing rule takes effect, you must activate it:

  1. In the Routing Rules section on the Payment Gateway Routing tab, find the rule. If you have a long list of rules in the table, click the column header to sort rules and quickly find the rule.
  2. Click the more icon in the Actions column, and then click Activate.

You can have up to 10 active rules. If the number of active rules reaches the limit, you must deactivate the rules to activate new rules. If you want to increase the limit of active rules, contact Zuora Global Support.

To deactivate a rule, click the more icon in the Actions column and then click Deactivate.

Prioritize rules

If you have multiple rules in Active status, the rules are executed according to the priority level of the rules. You can prioritize rules to handle complex routing scenarios and avoid conflicts for your needs. Complete the following steps to prioritize rules.

  1. In the Routing Rules section on the Payment Gateway Routing tab, click Edit Priority Order.
  2. In the Reorder Priority Levels dialog, drag and drop the rule to reorder the list.
  3. Click Save.

Update an existing rule

Complete the following steps to update an existing rule in active or inactive status:

  1. In the Routing Rules section on the Payment Gateway Routing tab, find the rule that you want to edit. You can click the column headers to sort the rules and quickly find the rule.
  2. Click the pen icon in the Actions column to open the rule in editing mode.
  3. Perform the following operations according to your needs:
    • To edit a component, click the more icon on the component and click Edit.
    • To delete a component, click the more icon on the component and click Delete.
    • To add a component in the middle of a path:
      1. Delete the existing component at the position where you want to add the new component. The existing component and all the components after it will be deleted.
      2. Click the plus icon on the connector line and add the new component.
      3. Add other components to build the rule path. 
  4. If you want to rename the rule, complete the following steps:
    1. Click the pen icon in the upper left of the page.
    2. Enter a name in the field next to the Rename button.
    3. Click Rename.
  5. Click Save in the upper right of the page to save your rule.

Delete a rule

By deleting a rule, the configuration of this rule will be permanently deleted. If you want to keep the rule configuration for later use, deactivate the rule instead of deleting it. 

Complete the following steps to delete a rule:

  1. In the Routing Rules section on the Payment Gateway Routing tab, find the rule you want to delete. You can click the column headers to sort the rules and quickly find the rule.
  2. Click the more icon in the Actions column, and then click Delete.
  3. Click Yes in the confirmation dialog.