Code format for routing rules

At the top-right of the Smart Routing rules page (Dashboard › Smart Routing) is the Edit routing rules as code button. When you click this, the rule editor is replaced by a text editor that contains code like the following:

block{gateways: ;condition: velocity{path:card_fingerprint; interval:1h} > 1;  tags: velocity(card_fingerprint within 1h) > 1; }
trigger_3ds{gateways: ;condition: merchant_initiated == false;  tags: Default 3DS; run_for_card_verifications: true}
route{gateways: gway_conf_5kayat82v11r36unnm0downk0odoibdm;condition: amount < 30 AND rand() > 0.5;  tags: 50% dummy gateway,value < 30; }

Whitespace is ignored, so you could reformat the code to look like this:

block{
    gateways: ;
    condition: velocity{path:card_fingerprint; interval:1h} > 1;
    tags: velocity(card_fingerprint within 1h) > 1;
}

trigger_3ds{
    gateways: ;
    condition: merchant_initiated == false;
    tags: Default 3DS;
    run_for_card_verifications: true
}

route{
    gateways: gway_conf_5kayat82v11r36unnm0downk0odoibdm;
    condition: amount < 30 AND rand() > 0.5;
    tags: 50% dummy gateway,value < 30;
}

dynamic_3ds{
    gateways: gway_conf_5kayat82v11r36unnm0downk0odoibdm;
    condition: card_country == "GB";
    dynamic_3ds_params: {
        sca_exemption_reason: "valid_reason";
        challenge_indicator: "no_preference"
    }
}

The text format is similar to CSS. Each rule introduced by its category name (block, route, trigger_3ds, or dynamic_3ds) with the rule definition inside curly braces. The rule properties are key-value pairs with a colon after the key name and a semicolon as a separator between properties. Note that the value part of a property can be left blank, if appropriate. See the sections below for details of the available properties.

condition

The data field names for the condition property are derived from the corresponding names shown in the where menu of the rule editor. Most names are converted to all lowercase and have spaces and dashes replaced by underscores. So, the Card co-scheme field is referred to as card_co_scheme in the code editor. However, there are a few fields that are slightly different:

  • Card IIN/BIN becomes card_iin
  • Card last 4 digits becomes card_last4
  • Card issuing bank becomes card_bank
  • Is 3DS flow becomes check_3ds
  • Is merchant initiated becomes merchant_initiated
  • Random number (0-1) is specified as a function called rand() (see the code sample above)
  • The velocity function behaves as if it were a sub-rule, with its own property list inside curly braces. The path property specifies the field and the interval property specifies the time interval (eg, 5m for 5 minutes or 1h for 1 hour, as shown in the code sample above).

You can also use special matching features with the card_iin and card_bank fields from the code format:

  • If you use a card number that is shorter than the standard format then it will match all card numbers that begin with the digits you provide (eg, card_iin = 42 will match all cards whose numbers begin with 42...)
  • If you supply a portion of a bank’s name between asterisks (eg, *hsbc*) then this will act as a wildcard that matches any bank name containing the portion (eg, card_bank === *hsbc* will match names like “united kingdom hsbc ltd company”).

tags

This is just a list of the tag names separated by commas.

run_for_card_verifications

This is the code equivalent of the Enable this trigger on card verifications switch and is only used for trigger_3ds rules. It has a Boolean value, true or false.

gateways

This property is a list of PSPs used by route, trigger_3ds, and dynamic_3ds rules. The PSPs are specified by their gateway IDs separated by commas. Go to Dashboard › Payment providers to see your enabled PSPs and access their gateway IDs.

dynamic_3ds_params

These properties are specified as if they were a sub-rule, as with the velocity function. The two properties of dynamic_3ds_params are sca_exemption_reason and challenge_indicator. The values are the same as those on the values menu in the rule editor except that the dash characters are replaced by underscores (so no-preference becomes no_preference).