Routing Rules

Overview

Routing Rules allows merchants to set up business logic to control routing through a user interface. You can use Routing Rules to easily define what payment gateway should receive your transactions based on transaction details such as Issuing Country and Card Brand. Routing Rules can also use Transaction Retry to automatically retry a transaction on another gateway in the case of an outage or soft decline.

Note: This feature is currently in beta. If you have interest in Routing Rules please contact your account manager or reach out to success@spreedly.com. We are adding more supported rules and adjusting the user experience based on beta customer feedback and demand. 

How Routing Rules Works

Routing Rules leverages a gateway-agnostic endpoint that is controlled by a rule engine. Customers can define their own rules using the Routing Rules user interface found in their Spreedly Dashboard. When a transaction is sent to the Routing Rules API Endpoint, https://core.spreedly.com/v1/transactions, the rule engine will determine how the transaction will be processed (e.g., which gateway? will it be retried on another gateway? etc.). 

Each ruleset is specific to a Spreedly Environment. Customers that have multiple environments should set up one ruleset per environment. 

A ruleset can have many rules, and rules are evaluated from top to bottom with the highest priority rule at the top of the page and the lowest priority at the bottom. Each ruleset must have a default gateway. If no rules are evaluated as true, the transaction will be routed to the default gateway. 

Transaction Rules

Transaction Rules allow you to create logic based on transaction characteristics such as Issuing Country, Transaction Currency, Card Type, and Card Brand to a payment gateway. Use the drop down to select the gateway token in the rule, this will be the target gateway that receives the transaction. You can also select a retry gateway if you would like retry the same transaction in the case of a soft decline or outage.

Each Transaction Rule has a rule name and gateway. Each rule has one or more rule conditions (e.g. Country). Each rule condition has one or more attribute values (i.e. United States, Spain). You can order your rules by priority, with highest priority rules at the top of the page. The highest-priority rule that matches a transaction will be used. Consider the example where Rule 1 states that Visa cards go to Stripe and Rule 2 states that Visa Cards with a USD currency go to Braintree.  A transaction that has both Visa and USD will go to Stripe as per Rule 1. Rule 2 is never evaluated in this example, as Rule 1 is a higher priority rule and is true. As such, it’s important to carefully define rule priority. 

A rule is only true when every rule condition is true. Once a rule is true, the transaction will be sent to the gateway defined in the rule - lower priority rules will not be checked. If even one rule condition is false, for example if a country condition is true and a currency condition is false, the rule will fail. When a rule fails, Transaction Rules will move to the rule below. If there are no transaction rules left to evaluate, Routing Rules will send the transaction to the default gateway.

Default Gateway

Default Gateway is the gateway token that will be used in the case that all Transaction Rules are false.

All rulesets must have a default gateway. Rulesets cannot be saved unless a default gateway is chosen.

We recommend you use your most reliable and versatile gateway as your default gateway. The default gateway must be able to process all leftover transactions. If your default gateway can’t process certain transactions, it’s recommended to create a Transaction Rule to capture transactions that a default gateway cannot process. 

API Request Format

Once you have saved your Routing Rule configuration, you can send authorize and purchase calls to the Routing Rules API Endpoint. 

Routing Rules uses the gateway-agnostic transactions endpoint https://core.spreedly.com/v1/transactions. Both XML and JSON format are supported. 

The request body requirements are similar to how you send gateway-specific API calls today, except all Gateway Specific Fields should be populated for all gateway types that could potentially receive a transaction from Routing Rules.

The following calls are supported, please see the API Reference for more details:

• purchase with Routing Rules
  • Tokenized Payment Method
  • Pass-in Credit Card
• authorize with Routing Rules
  • Tokenized Payment Method
  • Pass-in Credit Card

How to Send Gateway Specific Fields

Gateway specific fields are contained within a top-level gateway_specific_fields attribute, and can be sent for transactions against certain gateways.

When using Routing Rules, you should send all gateway specific fields for all gateways that could potentially receive a transaction in your Routing Rule configuration. Here is an example of how to send gateway specific fields for multiple gateways:

Response Structure

The Routing Rules API response is much like a traditional purchase or authorize response, with a few additions:

• smart_routed - This attribute will be true when your request is sent to the Routing Rules endpoint.
• routes - contains a reference to the rule that was used to route the transaction and whether a retry was set.

You can notice these fields in the sample response below:

  "smart_routed": true,
  "routing": {
    "routes": [
      {
        "rule": "routing_rule, LATAM countries to Stripe",
        "retry": null,
        "result": "succeeded",
        "gateway_type": "stripe",
        "gateway_token": "Sx6yb6aCqzdX2vmjzGwGxjWAIh2"
      }
    ]
  },

Retry Gateways

We recommend that all merchants with one or more getaways use Transaction Retry in their routing rules to boost authorization rates and protect themselves from gateway outages. 

When creating a rule, you will be able to select which mode of retry you would like to use. There are two types, Standard and Outage Only. Standard mode will proceed to the first retry gateway in the case of a soft decline code (for example, “do not honor”) or a gateway outage. If a second retry gateway is set, the transaction will proceed to the second retry gateway in the case that the first retry gateway declines the transaction.

Outage Only mode will only proceed to the first retry gateway in the case of a gateway outage. Outage Only mode only supports one retry gateway.

If a retry mode is set, the transaction details will automatically be sent to the retry gateways defined in your configuration - maximizing the transactions chance of success. Refer to our Transaction Retry Guide for more information.

How to Use Routing Rules

Beta Prerequisite: You must contact your account manager or success@spreedly.com to enroll as a beta customer for Routing Rules.

Prerequisite: Your account must have the role level of Administrator to edit and save Routing Rules. 

Navigate to Rules

1. Log into your Spreedly Dashboard using your credentials. 
2. Navigate to Routing Rules in the left navigation menu.

Specify Environment and Default Gateway

3. Select the Spreedly environment you would like to create a ruleset on by using the drop down box.
4. Use the drop down to select your desired Default Gateway.
   • You must have at least one gateway in your environment to use Routing Rules. Refer to Add a Gateway Guide for more information.

Create a Rule

5. Add a Transaction Rule by pressing ‘+ RULE’ in the top right corner. Enter a rule name and select a gateway using the drop down box. 
6. Select one or more rule conditions in a rule by pressing one of the rule condition values below (i.e. Country or Currency). Use the drop down to define an attribute value (i.e. for Country select united states)
   1. You can add multiple attribute values by using the drop down to select another value. This is treated logically as an or condition. For example, for the rule condition of Country, you may add United States + Canada using the drop down. If the issuing country is from the United States or Canada, the rule condition will pass. 
   2. Multiple rule conditions in a rule are treated logically as an and condition. For example, if a rule has two rule conditions 1) Currency is the United States Dollar (USD) and 2) Issuing Card is from the United States - if either one of these rule conditions is false, the rule will fail.
7. Recommended: Select a retry mode (Standard or Outage Only). Select a retry gateway from the dropdown. Standard mode will retry the transaction in the case of a gateway outage or a soft decline.

8. Select “Create” to save a rule. The rule will be added as a Transaction Rule. 
   1. Note: You can drag and drop rules to the top if you would like to change the order that rules are considered. Routing Rules will always start with the rule at the top of the stack and move down. 

Save your Rules

9. Confirm that the default gateway is correct by looking at the gateway type and gateway token. 
   1. If you would like to change your default gateway, select “Change” at the top of the screen and choose another gateway from the drop down, similar to step 4. 
10. Save your ruleset configuration by selecting “Save” in the bottom left.
    1. If there are any errors, Transaction Rules will flag errors after you press save. Fix all errors before saving again. 
    2. Success! You should see the following message once the ruleset is saved.

Split Volume between Two Gateways

To split transaction volume between two gateways within the same rule, follow these steps:

1. When creating a new rule, select the "Split Transaction Volume" option.

2. You will be prompted to add a second gateway and choose a Gateway Split percentage to determine the distribution of transactions between the two gateways. 

The volume split feature uses a random number generator to allocate transactions to each gateway based on the specified percentage. Volume is distributed based on number of transactions, not the amount. For smaller transaction volumes, you may notice minor variations between the actual and desired split due to the probabilistic nature of the volume split mechanism. As the transaction volume increases, these variations will decrease, providing a more accurate distribution.

Create a Rule using Transaction Metadata

You can create a rule based on custom transaction metadata sent on purchase and authorize calls. This custom metadata can be any additional information that can't be created using another rule condition, for example a custom risk score or product id. 

To create a rule using the transaction metadata rule condition, follow the following steps:

1. Send us metadata on the transaction using the optional transaction_metadata parameter when sending a purchase or authorize request. transaction_metadata will accept one or many pieces of metadata in key value pair format. For example, if you would like to send us a risk level and product ID you can structure a purchase request in the following:

POST /V1/transactions/purchase.<format>

{
  "transaction": {
    "payment_method_token": "N0GAK5ueWQjrHBEGvXedUDsgX24",
    "amount": 500,
    "currency_code": "USD",
    "transaction_metadata": {"risk_level":"high", "product_ID":"1890"}  
   }
}

2. When creating a new rule, select Metadata as a Rule Condition

3. Enter in the Metadata key value pairs that you would like to create a rule based on. You may enter in multiple key value pairs, and multiple values per key. For example, if you want transactions that have a product_id of 1890 and have a risk_level of medium or high to go to one gateway - you can create a metadata rule around these two criteria.

Routing Rules Reporting

You can access a report of all tokens that have been sent to Routing Rules in your Spreedly Dashboard under the Smart Routing tab. 

The Routing Rules table will record transaction tokens that have gone through Routing Rules. The rule name and target gateway used for the transaction will be displayed in the 'Rule', 'Gateway Type', and 'Gateway Token' columns. If a transaction goes to the default gateway, the 'Rule' will display default_gateway. The 'State' column displays whether or not a transaction is successful. 'Transaction Type' will be either Purchase or Authorize. If applicable, Transaction Retry details are stored in the 'Retry' and 'Payment Attempts' columns. You may also refer to the Transaction Retry table above the Routing Rules table for all tokens that include one or more retry gateways.

You can filter on specific Rule, State, Gateway Types, and Payment Attempts using the filter drop downs.  

You may download this report as a CSV or PDF or schedule a recurring email delivery by clicking on the kebab menu (⋮) in the top right hand corner.

FAQs

Q: Does Routing Rules support Payment Method Distribution (PMD)?

No, at this time Routing Rules does not support transactions sent via Payment Method Distribution. Additionally, Routing Rules only supports card payment methods today.

Q: Can I use 3DS2 on Routing Rules

Yes, but all target gateways that could receive a transaction must be a 3DS2 Global Supported Gateway in the chosen environment.

Additionally, requesting a transaction to go through 3DS2 must be all or nothing for that ruleset. Because of this limitation, we recommend that you separate your 3DS2 gateway to a separate environment. The ability to conditionally trigger 3DS2 on one rule and not another is not supported yet. 

Q: Can rules only be set at the Environment level? 

Yes, rule configurations are always tied to an environment. If a user wants rules for multiple environments they will need to create and save a rule configuration for each environment.

Q: Can I make it so that only some accounts can make changes to my Routing Rules?

Yes, only the Administrator role will have permissions to make changes to Routing Rules. Analyst roles will be able to view Routing Rules, but not make changes. The billing manager and environment manager will not be able to view or make changes. Refer to our RBAC guide for more information.