Defining custom routing rules

By default, Smart Router 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 to 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 is dvided into 4 sections, one for each type of rule that you can define:

  • Block: Refuse to process the transaction
  • Trigger 3DS: Issue a 3DS challenge for the transaction
  • Dynamic 3DS: Add extra conditions for 3DS authentication to a PSP
  • Route: Select which PSP will handle the transaction

Use the Add another rule button at the bottom of each category to define new rules. You can also click the name of an existing rule to view or edit it and then click the Collapse button to hide the rule editor when you are done.

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 just acts a name for the rule. Click the Tags text box and type the name and 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.

When you have finished editing your rules, scroll to the bottom of the page and click the Save button to activate your changes.

Adding filter conditions

The filters are described by “where” clauses similar to those used in SQL (eg, trigger 3DS for transactions where the amount paid is more than €99). The conditions in these clauses compare a data value from a transaction with a value that you supply. Select the transaction data field that you want to use for your filter from the where menu, which also contains a description for each field. The data type of the field determines the kinds of comparisons you can use, as shown in the table below:

Data type Comparisons Example
Numeric Mathematical operators (<, >, ==, etc) Amount > 99
Text Equal (==, ===) or not equal (!=, !==) Card country == FR
Boolean (true/false) Equal Is merchant initiated false
Lookup Textual key-value pair metadata houseColor green
Velocity function Mathematical operators (<, >, ==, etc) velocity of card fingerprint every hour > 1

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.

Click the + button at the right-hand side of a condition to add an extra condition to the filter. 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 filter).

Rule priority

You can rearrange the rules in any of the categories using the Drag to order bar at the right-hand side. 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.


These rules simply abort any transaction that matches your conditions. 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 request a 3DS challenge 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.)


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.