Defining custom routing rules

By default, Smart Routing tries to route each transaction to the optimal Payment Service Provider (PSP) based on performance and availability. However, you can override this behavior if you want to choose your own routing for certain types of payments.

Smart Router lets you define custom routing rules. These rules select particular PSPs for any transactions that meet a set of filter conditions that you specify. For example, you might choose a subset of your PSPs for all transactions that originate in Europe, or for payments over a certain amount. You can also set rules to activate 3DS authentication for transactions, applying parameters to fit your SCA strategy or block unwanted transactions completely.

Using the rule builder

Go to Dashboard › Smart Routing to view the current set of routing rules in the rule builder.
The page has 4 tabs, one for each type of rule that you can define:

• Blocking: Refuse to process the transaction
• Trigger 3DS: Enable 3DS for the transaction
• Dynamic 3DS: Add extra conditions for 3DS authentication to a PSP
• Routing: Select which PSP will handle the transaction

With enabled Edit permissions for Payment settings, you can switch to the Edit mode by clicking Edit rules. To define a new rule, click Add new rule from there.

Each new rule applies to all transactions by default. It is generally more useful to apply rules selectively by adding one or more filter conditions. For example, if you believe that payments over €99 should always be authenticated, then you might create a rule to trigger 3DS on any transactions that match this condition.

You can also add tags to a rule to help you identify it. At its simplest, a tag acts as a name for the rule. Select any step of the rule to open the rule menu and type the name at the top. Press Enter to create a new tag. You can add more than one tag to each rule, and you can also use the same tag text for different rules. This lets you create groups of related rules. For example, you might use the name of a PSP as a tag for all rules that route transactions to that PSP.

You can duplicate a rule by clicking on the three dots menu on the left, then Duplicate rule. From the same menu, you can use Delete rule.

When you have finished editing your rules, click the Save button to review and confirm your changes.

You can also Exit edit mode without saving changes.

Adding filter conditions

The filters are described by "where" clauses similar to those used in SQL (e.g., trigger 3DS for transactions where the amount paid is more than €99). The conditions in these clauses compare a value from a transaction
with a value that you supply.

All the transaction data parameters are available in the Conditions menu on the left in Edit mode. Add the conditions you want to filter by with the + sign, or simply drag and drop them to the required rule.
When two or more conditions are active, they will be combined using boolean AND (ie, all of the conditions must be satisfied to apply the rule).

The data type of the field determines the kinds of comparisons you can use, as shown in the
table below:

Note that the velocity function returns the number of occurrences of a data value in transactions within a given time period. For example, you might use this to block transactions from a card number that gets used more than 50 times within an hour, which might indicate that the card has been stolen. Also, note that the text comparison operators === and !== are case-insensitive versions of the equal and not-equal operators. The velocity counting starts from 0.

Note that the random number (0 - 1) function can be thought of as generating a new number between 0 and 1 for each transaction. Then the computation is a simple math comparison where if the result is true then we execute the rule. Be mindful of the rule sequence when deciding the random number to apply.

• Random number < 0.3 will mean that 29.9999% of the transactions reaching this rule will match it
• Random number >= 0.3 then it will be true in 70% of cases

Note that when applying a metadata Lookup key to a routing rule, only transactions containing the corresponding metadata field will match with the routing rule. If the metadata field is absent in a transaction, it will not match with the routing rule.

Rule priority

You can rearrange the rules in any of the categories by dragging them using the three dots area on the right. During processing, the rules are activated in the order they appear in the list. This is important for the routing rules because more than one rule might apply to a particular transaction and so the ordering defines a priority system for choosing the right PSP.

Rule categories

The sections below explain the rule categories in more detail.

Block

These rules simply abort any transaction that matches your conditions. Transactions will be blocked at the ProcessOut level, meaning they won't reach a PSP, which can improve your performance. Note that a blocking rule with no filter will block all transactions, so make sure you set a filter for each blocking rule before saving.

Trigger 3DS

The rules in this category enable 3DS for any transactions that match the filters. Each rule has a switch to enable or disable it for card verifications.

Dynamic 3DS

These rules allow more fine-grained control of 3DS challenges. They are applied to a particular PSP after that PSP has been chosen by one of the routing rules. Use the On menu in the rule editor to choose the PSP that the rule applies to.

The filter conditions for dynamic 3DS rules work in the usual way. For transactions that match your filter conditions, you can add a claim for exemption from 3DS, specify a challenge indicator or both. (Note that you can also set these values using the ProcessOut API. See the description of the Invoice object for more information.)

Route

Routing rules send the selected transactions to a particular PSP. As well as the main PSP, you can supply a fallback for Smart Router to use when the main one isn't available. You can also select Smart Routing instead of a PSP. This option lets you specify a set of PSPs (either all enabled providers, or a defined subset) for the usual smart routing algorithm to choose from.