Rules Guide

7 min

Setting up a rule

Setting up a rule takes four calls:

Create a rule

Add a version with the routing logic

Make that version current

Create a transaction routing rule and attach it to a configuration

Create the rule

curl -X POST https://mgmt-api.torogateway.dev/v1/rules \
  -H "Content-Type: application/json" \
  -H "API-Key: <KEY>" \
  -d '{
    "name": "Card brand routing",
    "description": "Amex to Amex Direct, Visa and Mastercard to Shift4",
    "type": "transaction_routing"
  }'

Note the id in the response, for example rule_abc123.

Add a version

The rule definition works outa weight for each acquirer. This example send Amex cards to Amex Direct, and Visa, Mastercard and Maestro to Shift4:

curl -X POST https://mgmt-api.torogateway.dev/v1/rules/rul_abc123/rule-versions \
  -H "Content-Type: application/json" \
  -H "API-Key: <KEY>" \
  -d '{
    "rule_id": "rul_abc123",
    "description": "Add Amex Direct",
    "definition": {
      "ruleName": "CardBrandRouting",
      "expression": "CardBrandIsAmex or CardBrandIsVisaOrMastercard",
      "localParams": [
        { "name": "CardBrandIsAmex", "expression": "binLookupResult.cardBrand == \"American Express\"" },
        { "name": "CardBrandIsVisaOrMastercard", "expression": "binLookupResult.cardBrand == \"Visa\" or binLookupResult.cardBrand == \"Mastercard\" or binLookupResult.cardBrand == \"Maestro\"" },
        { "name": "AmexDirectWeight", "expression": "CardBrandIsAmex ? 1 : 0" },
        { "name": "Shift4Weight", "expression": "CardBrandIsVisaOrMastercard ? 1 : 0" }
      ],
      "actions": {
        "onSuccess": {
          "name": "ReturnObjectFromParamKeys",
          "context": {
            "american_express": "AmexDirectWeight",
            "shift4": "Shift4Weight"
          }
        }
      }
    }
  }'

How the definition works:

localParams are named expressions. Later parameters can use earlier ones.

actions.onSuccess.context maps each acquirere to the parameter that holds its weight.

An acquirer with weight 0 is never chosen for that card.

Note the version id in the response, for example rlv_def456

Make the version current

Createa a version doesn't activate it. Set it as the rule's current version:

curl -X PATCH https://mgmt-api.torogateway.dev/v1/rules/rul_abc123 \
  -H "Content-Type: application/json" \
  -H "API-Key: <KEY>" \
  -d '{
    "current_version_id": "rlv_def456"
  }'

To change the routing later, add a new version and make it current. To roll back, set current_version_id back to the previous version.

Create the transaction routing rule and attach it

curl -X POST https://mgmt-api.torogateway.dev/v1/transaction-routing-rules \
  -H "Content-Type: application/json" \
  -H "API-Key: <KEY>" \
  -d '{
    "rule_id": "rul_abc123",
    "transaction_routing_strategy": "sorted"
  }'

Strategy	Behaviour
sorted	Uses the acquirer with the highest weight above zero. Use this one for routing by card brand.
weighted_random	Picks an acquirer at random, in proportion to the weights. Use this to split traffic.

Note the id in the response, for example trr_ghi789.

For the test, create a configuration that only sets the routing rule, and attach it to your test terminal:

curl -X POST https://mgmt-api.torogateway.dev/v1/configurations \
  -H "Content-Type: application/json" \
  -H "API-Key: <KEY>" \
  -d '{
    "transaction_routing_rule_id": "trr_ghi789"
  }'

curl -X PATCH https://mgmt-api.torogateway.dev/v1/pois/<TEST_POI_ID> \
  -H "Content-Type: application/json" \
  -H "API-Key: <KEY>" \
  -d '{
    "configuration_id": "cfg_test123"
  }'

If the terminal already has its own configuration, don't replace it. Instead, add transaction_routing_rule_id to that configuration with PATCH /v1/configurations/{id}.

The terminal still inherits your merchant details from its merchant group or merchant. Every other terminal keeps its current routing.