Hyperswitch payment routing rules

Fallback order decides where a payment goes when your routing rules give no answer, and Hyperswitch documents two situations that trigger it. The first is that no rule matches the payment at all, for example because its currency, amount, or payment method falls outside every configured rule. The second is that the processor a rule selected is ineligible for that particular payment, such as an unsupported currency or payment method, or a connector that is not enabled for the business profile handling the payment. In both cases the payment moves to the default fallback routing you configured, so the fallback list deserves the same review as the rules themselves.

The main risk is silent drift. A fallback processor may cost more per transaction or approve fewer payments than the processor your rules were designed around, and nothing in the checkout flow will tell anyone that this happened. Volume that was meant to go to a least cost or high approval processor can end up on a more expensive one for weeks before finance or the payments team notices. Review the fallback list with the same scrutiny as the primary routing logic, and ask who owns changes to it. Confirm whether your chosen version exposes which connector was tried, in what order, and why each one was skipped or declined, so the path is visible without reconstructing it from logs.

Retries across processors add a second risk. When a payment is declined by one processor and then sent to another, the attempts may be counted differently by each processor, by your fee reports, and by your own decline metrics. A decline that was recovered on a fallback processor can look like a clean approval in one report and a failure in another. Before go-live, confirm with the Hyperswitch documentation for your exact release how retries and fallback interact: whether a retry can cross processors, how many attempts are allowed, and which response is returned to the merchant. Write those answers down, because they determine how you read approval rates later.

Record which processor handled each payment, including attempted processors and the reason for each switch, in a field your reconciliation process reads. Without this, refunds, chargebacks and settlement breaks cannot be matched to the correct processor agreement, and approval analysis will blend fallback traffic into the primary rules. Ask your engineering team to confirm that the stored attempt history survives retention rules and is available to finance and audit teams, not only to the platform team. Treat this record as part of the routing design, not as an afterthought added once reconciliation fails.

Treat every routing change as a release that must pass through three stages before it can touch live payment traffic: a local environment, a shared staging environment wired to connector sandbox credentials, and a limited production rollout with monitoring and a tested rollback. Each stage answers a different question. The local stage checks that the rule logic does what the configuration says. The staging stage checks that the rule works against real connector integrations and real configuration state. The limited production rollout checks that the outcome holds under actual traffic. Skipping a stage usually means discovering the problem later, in front of customers. For the local stage, run a self-hosted Hyperswitch instance using the Docker-based local setup that the project documents, or a Kubernetes deployment if your production topology depends on Kubernetes behavior. Load the routing configuration you intend to change, then drive test payments through the router with synthetic merchant and payment attributes. Your engineers should be able to reproduce every rule decision from a clean environment. If a result depends on a database row or cache entry that exists only on one engineer's machine, the test is not yet reliable. The hosted sandbox that Hyperswitch documents is useful for early tests, such as confirming that a connector responds and that the request shape is correct. It is not a substitute for production evidence. Sandbox processors do not reproduce live approval rates, decline patterns or issuer behavior, so an auth-rate or multi-objective strategy that looks correct in sandbox tells you little about how it will rank processors on real traffic. Use sandbox results to validate mechanics, and treat approval-rate claims as unverified until the limited production rollout produces data. Write test cases for three groups. First, one or more cases for each rule, covering the conditions that should match and the conditions that should not. Second, one case for each fallback path, including the default fallback order that applies when no rule matches. Third, cases for ineligible-processor scenarios, where a processor that would otherwise rank first is excluded because it does not support the currency, payment method, country or amount in the request. For every case, record the expected processor selection before running the test, then record the actual selection. A mismatch is a finding, not a note to explain away. Before the staging stage, confirm with Hyperswitch documentation and your own testing how a rule change is applied in the version you run: immediately after saving, or on a configured interval. This determines your test sequence and rollback timing. If changes take effect on an interval, a rollback is not instant, and your monitoring window must account for that delay. Record the answer in the change record so that the on-call team does not have to rediscover it during an incident.

Once routing rules carry live payment traffic, the work shifts from design to operations. The core obligation is to watch approval rate, cost and fallback frequency for each processor, and to be able to explain any change in where transactions go. Track these three measures per processor and per routing strategy, not just in aggregate, because a blended approval rate can hide a processor that has started declining a specific card type or region. Set thresholds in advance for each measure and agree who receives the alert and who decides whether to change the rule. Ask your team to confirm which metrics Hyperswitch exposes out of the box in your deployment and which must be built from the logs and database records of your own environment.

Alerts should fire on unexpected shifts in routing decisions, not only on falling approval rates. A sudden move of volume from one processor to another, a rise in fallback routing, or a rule that starts matching transactions it did not match during testing are all signals that a rule or an input has changed. Compare the share of traffic each processor receives against the share expected from the rule definition, and investigate when the gap grows. Fallback routing deserves its own alert because it is the path taken when no rule applies or a processor is ineligible, and frequent fallback usually means a gap in the rule set or a processor that is failing its eligibility checks.

Every rule change needs a versioned record that states what changed, why it changed, who approved it and when it went live. Keep this record in version control alongside the routing configuration, and require a named approver who is not the author. Without it, an investigation into a drop in approval rate will rely on memory. The record also gives your auditors and your PCI DSS assessor evidence that payment routing changes are controlled, which matters when routing touches cardholder data flows.

Review routing after every Hyperswitch upgrade, even when the upgrade looks minor. Hyperswitch publishes release notes and a compatibility matrix for the Control Center and web client with each release, and a release can add a required dependency. The v1.124.0 release notes, for example, made Superposition a required configuration dependency that must be running before the upgrade. Before each upgrade, read the release notes, confirm the compatibility matrix against your deployed dashboard and SDK versions, and rerun your routing test cases against the new build. Treat the routing configuration as something that must be re-verified after each upgrade, not assumed to carry over unchanged.

Schedule periodic reviews of the cost inputs used by multi-objective routing, which re-ranks processors by authorization rate and processor cost. Processor fee schedules change, and a stale cost table will send traffic to a processor that is no longer the cheapest option. Assign an owner for the cost data, set a review cadence agreed with finance and the payments team, and record each change in the same versioned log. Use the reconciliation and cost observability modules in the Hyperswitch docs as places to compare actual settled outcomes and fees with what routing assumed. Confirm with your Hyperswitch contact exactly what each module reports in your version before relying on it for decisions.