Skip to main content

Configuring Cascade Routing Rules

A cascade defines which gateway profiles Odus uses to process a payment and how traffic is distributed across them. This guide shows how to create and configure a cascade, assign it as the default for card payments, and verify it is active.

Prerequisites​

Create a cascade in the Dashboard​

  1. In the Dashboard, go to Cascades.
  2. Click Add.
  3. Enter a Title for the cascade. Optionally enter a Description.
  4. Select an Algorithm:
    • Round Robin — distribute payments evenly across all gateways.
    • Weighted Round Robin — distribute payments by percentage weight.
    • Priority Queue — always try the highest-priority gateway first, falling back on failure or exhaustion.
  5. Under Gateway rules, click New rule to add a gateway. Repeat for each gateway you want in the cascade.
  6. Configure each gateway rule. See Gateway rule options for the available fields.
  7. Click Add.

Gateway rule options​

Each rule links a gateway profile to the cascade and controls how that gateway is used. Every rule requires a Gateway (the profile to use) and a Position (order in which Odus tries the gateway, 1–10).

For Weighted Round Robin, each rule also takes a Weight — a whole number from 0 to 100 that controls the share of payments routed to that gateway.

For Priority Queue, each rule can optionally include a Transaction Limit with a Limit Period (Day, Week, or Month) and a Transaction Cap with a Cap Period. When a gateway reaches either threshold, Odus skips it for the rest of that period.

See the POST /cascades reference for the full parameter list.

important

A Priority Queue cascade must include exactly one gateway with no transaction limit and no transaction cap. This gateway acts as the permanent fallback when all other gateways are exhausted.

You can drag gateway rules to reorder them. A single cascade can have up to 10 gateway rules.

Create a cascade via the API​

Send a POST /cascades request with the cascade's name, algorithm, and at least one gateway.

The example below creates a priority-queue cascade with two gateways. The primary gateway has a daily transaction limit and a daily volume cap. The second gateway has no limits and acts as the fallback.

{
  "name": "Primary with fallback",
  "description": "Routes to the primary gateway up to its daily limits, then falls back.",
  "algorithm": "priorityQueue",
  "gateways": [
    {
      "profile": "gwp_2QUGPTQo8As1cNIvgKlSFDxjJDd",
      "position": 1,
      "transactionLimit": 500,
      "transactionLimitPeriod": "day",
      "transactionCap": 1000000,
      "transactionCapPeriod": "day"
    },
    {
      "profile": "gwp_3RTHQUROb9Bt2dJwhLmTGEykKEe",
      "position": 2
    }
  ]
}

A successful request returns 201 with the created cascade object, including the id you will need for future updates.

Update an existing cascade​

To change a cascade's name, description, algorithm, gateways, or active state, send a POST /cascades/:id request with only the fields you want to change. All fields are optional.

{
  "name": "Primary with fallback — updated",
  "active": true
}

You can also edit a cascade in the Dashboard by going to Cascades, clicking the cascade, modifying the form, and clicking Update.

Assign the cascade as the default for card payments​

After creating a cascade, you need to assign it in Merchant Configuration before it processes any payments.

  1. In the Dashboard, go to Settings > Merchant Configuration.
  2. Tick Set Card payment settings.
  3. Set Processing mode to cascade.
  4. In Default cascade, select the cascade you created.
  5. Click Update.

All card payments that do not have a more specific routing assignment will now be processed through this cascade.

See Merchant Configuration for the full list of card payment settings.

Verify the cascade is active​

The active field on the cascade response indicates whether the cascade will be used for routing. A cascade is active by default when created.

{
  "id": "cas_2ROexMdiEIv7Wv3iuIu9RQ6TbGL",
  "name": "Primary with fallback",
  "active": true,
  "algorithm": "priorityQueue",
  "gateways": [...]
}

If a cascade is not routing payments as expected, check the active field. To reactivate a cascade, send a POST /cascades/:id request with "active": true.