How Cascade Routing Works
A cascade is a named configuration that defines which gateway profiles Odus uses to process a payment and in what order. When one gateway fails or is no longer available, Odus automatically routes the payment to the next gateway in the cascade — without any action required from you.
Why Use a Cascade
Without cascade routing, a payment sent to a single gateway has no automatic fallback. If that gateway is unavailable or declines the payment, the charge fails.
A cascade addresses this in three ways:
- Automatic failover — when a gateway fails or rejects a payment, Odus moves to the next gateway immediately, increasing the chance of a successful charge.
- Load distribution — traffic can be spread across multiple gateways, preventing any single integration from becoming a bottleneck.
- Protection against downtime — when a gateway is temporarily unavailable, Odus continues processing payments through the remaining gateways in the cascade.
Routing Algorithms
Each cascade uses one of three routing algorithms. The algorithm determines how Odus selects a gateway for each payment.
Round-robin
Odus distributes payments evenly across all gateways in the cascade, cycling through them in order. Each gateway receives approximately the same number of payments over time.
This algorithm is useful when all your gateways have similar capabilities and you want to share load equally.
Weighted round-robin
Odus distributes payments by percentage weight. You assign a weight to each gateway — for example, 70 to Gateway A and 30 to Gateway B — and Odus processes roughly 70% of payments through Gateway A and 30% through Gateway B.
Weights are whole numbers from 0 to 100. The weights across all gateways in a cascade do not need to sum to 100, but the distribution will be proportional to the values you set.
This algorithm is useful when your gateways have different costs, performance characteristics, or transaction limits.
Priority queue
Odus always tries the highest-priority gateway first. Priority is determined by position: the gateway with the lowest position value is tried first. If that gateway fails or is exhausted, Odus falls back to the gateway with the next-lowest position.
A cascade has three gateways:
| Position | Gateway |
|---|---|
| 1 | Primary |
| 2 | Backup A |
| 3 | Backup B |
Every payment goes to Primary first. If Primary fails, Odus tries Backup A. If Backup A also fails, Odus tries Backup B.
This algorithm is useful when you have a preferred gateway and want fallbacks to activate only on failure.
Transaction Limits and Caps
Each gateway entry in a cascade can have an optional limit and an optional cap. When a gateway exceeds either threshold, Odus considers it exhausted and skips it for the remainder of that period.
| Setting | Description |
|---|---|
transactionLimit | Maximum number of transactions allowed in the period |
transactionLimitPeriod | The period when the limit applies: day, week, or month |
transactionCap | Maximum total amount (in minor currency units) charged in the period |
transactionCapPeriod | The period when the cap applies: day, week, or month |
Limits and caps reset automatically at the start of each new period. The fields isTransactionLimitExhausted and isTransactionCapExhausted on a cascade gateway reflect the current state.
When all gateways in a cascade are exhausted, the payment cannot be routed and will fail. Make sure at least one gateway is available during each period.