Payment Routing

Payment routing determines which terminal processes each transaction. Configure rules to optimize acceptance rates, manage costs, and distribute traffic across your provider connections.

How Routing Works

When a payment is created, the routing engine evaluates the transaction in two phases:

1. Phase 1 — Filter: Infrastructure filters narrow the pool to eligible terminals, then routing rules further refine the candidate set.
2. Phase 2 — Score: If multiple candidates remain, the scoring engine picks the best terminal based on priority.

The full pipeline runs in this order:

Payment created --> Limit check --> Risk check --> 3DS decision --> Routing --> Attempt

If the selected terminal declines the transaction, cascading can retry with the next eligible terminal.

Infrastructure Filters

Before any rules are evaluated, the system automatically excludes terminals that cannot handle the transaction. These filters are not configurable — they enforce hard constraints:

Routing Rules

Rules let you control which terminals handle specific types of transactions. Each rule has three components:

• Conditions — criteria that a transaction must match
• Action — include (add terminals to candidates) or exclude (remove terminals)
• Candidates — the terminal(s) affected by this rule

Rules are evaluated in priority order (lower number = higher priority). Conditions within a single rule are AND-combined — all must match for the rule to apply.

Available Conditions

The routing engine supports 21 condition fields, grouped by category:

Transaction attributes

Card attributes (from BIN lookup)

Payer attributes

Payer velocity (require aggregation)

Temporal

Custom

Include vs Exclude Rules

• Exclude rules are evaluated first. All matching exclude rules are applied (not just the first match). Excluded terminals are removed from the pool.
• Include rules are evaluated next in priority order. The first include rule whose conditions match AND whose candidates are still in the pool determines the final candidate set.
• If no include rules exist, all remaining terminals (after infrastructure filters and exclude rules) are used as candidates.

Creating a Routing Rule

Portal: Navigate to Routing and select Create Rule.

1. Name: Give the rule a descriptive name (e.g., "Route EUR Visa to Terminal A").
2. Direction: Select payin or payout.
3. Action: Choose include or exclude.
4. Conditions: Add one or more conditions. All conditions must match for the rule to apply.
5. Candidates: Select target terminal(s).
6. Priority: Set the evaluation order (lower number = evaluated first).
7. Status: Rules start as draft. Activate when ready.

Rule Lifecycle

Rules support versioning — activating a new version of a rule automatically archives the previous version.

Cascading

When a terminal declines a transaction with a soft decline, cascading automatically retries with the next eligible terminal. The failed terminal is excluded from the candidate set, and the routing engine runs again to pick the next terminal.

When cascading applies

Cascading applies only to instant payments — synchronous card transactions that have not yet entered a user interaction flow. Once the payer is involved in a 3DS challenge, app confirmation, or external redirect, cascading is prohibited. Delayed payment methods (bank transfer, SEPA, ACH) are never eligible for automatic cascading.

Configuration hierarchy

Cascade behavior is configured per merchant through the IntegrationProfile.cascadePolicy, not per channel. The system resolves the active policy using a three-level hierarchy:

The first non-null policy in this chain is used at runtime.

CascadePolicy fields

Channel kill-switch

Each channel has a cascadingEnabled boolean. This is a per-channel toggle — when set to false, no cascading occurs for transactions on that channel regardless of the merchant's cascade policy. It does not replace the policy configuration; it only acts as an override to disable cascading on specific channels.

How cascading works

1. The routing engine selects the primary terminal and sends the payment.
2. The terminal responds with a decline. The system classifies the decline (soft/hard).
3. The cascade engine checks the active policy: do launchConditions match? Do any blockConditions apply? Is maxAttempts exceeded? Is the total timeout budget remaining?
4. If cascading is allowed, the failed terminal is excluded and the routing engine selects the next terminal from the remaining candidate set.
5. The payment is re-submitted to the new terminal without any change to the payer's session.
6. The process repeats until the payment succeeds, attempts are exhausted, or a block condition is hit.

Fallback Behavior

If you have not configured any include rules for a given direction, the system falls back to using all infrastructure-filtered terminals. In this case, the terminal with the highest channel priority (lowest number) is selected.

This means you can start processing payments immediately after creating terminals and channels — routing rules are optional and additive.

Best Practices

• Assign clear priorities to avoid ambiguity — no two include rules should have the same priority.
• Use exclude rules sparingly for compliance (e.g., "never route country X to terminal Y").
• Monitor acceptance rates per terminal in the dashboard to identify optimization opportunities.