---
title: Rules Guide
slug: rules-guide
docTags: 
createdAt: 2026-10-09T09:09:14.069Z
---

## Setting up a rule

Setting up a rule takes four calls:

1. Create a rule
2. Add a version with the routing logic
3. Make that version current
4. Create a transaction routing rule and attach it to a configuration

:::Heading{depth="3" indent="1"}
Create the rule
:::

```curl
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`.

:::Heading{depth="3" indent="1"}
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
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`

:::Heading{depth="3" indent="1"}
Make the version current
:::

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

```curl
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.

:::Heading{depth="3" indent="1"}
Create the transaction routing rule and attach it
:::

```curl
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
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
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.