Enhanced configuration management & reliability in Hyperswitch
A unified, context-aware configuration layer for the whole payment stack - change runtime behaviour without redeploys, scope it along any payment dimension and stagger rollouts
TL;DR - Starting with this release, Hyperswitch is adopting Superposition as a configuration engine as a mandatory service in its stack. The runtime configurations that previously lived in Hyperswitch's config table are now hosted on Superposition and resolved against a rich set of dimensions - covering the Organization → Merchant → Profile (OMP) hierarchy among many others.
This is the first step in a broader move where feature flags, TOML runtime configs will follow. The goal is a single, type-safe, context-aware configuration layer for the entire payment stack - one that lets you change behaviour without redeploys, scope behaviour along any combination of dimensions that matter to a payment, stagger rollouts, and run experiments against real traffic.
- First, a one-line on the engine. Superposition is an open-source, context-aware configuration platform built by Juspay. Applications send it a configuration key and a runtime context and it evaluates the context against a hierarchy of overrides and returns the resolved value - type-checked, audited, and optionally part of a live experiment. Resolution is sub-millisecond and happens in-process via an embedded client.
- With that in mind, the concrete changes in this release:
- A unified configuration engine. The config table is replaced by a context-aware engine where every key has a JSON Schema and every value is overridable along any combination of the 16 dimensions.
- In-process resolution. The Superposition Rust client ships embedded in Hyperswitch with in-memory caching and async polling. Lookups are sub-millisecond - no network hop on the hot path.
- Superposition is required. Hyperswitch will not start without a reachable Superposition deployment. Docker Compose, Helm, and self-host blueprints are updated.
- The client integration is built-in. Hyperswitch ships with the Superposition Rust client embedded, with in-memory caching and async polling for refreshes. Lookups are sub-millisecond and happen in-process.
- This is a coupled change rather than an opt-in integration. Two parallel config paths will be an operational overhead of both systems and the benefits of neither, and every upcoming surface (feature flags, TOML runtime) assumes the new engine is present.
- This release is an upgrade to how configuration works in Hyperswitch - built around four properties the payment stack increasingly needs.
- Granular customizability along the dimensions/parameters that matter. Any configuration can vary along any combination of payment dimensions - organization, merchant, profile, connector, currency, country, payment method, mandate type, and more - without writing a single new branch in application code. The same key can resolve to one value for a Dutch telehealth practice paying through Adyen and a different value for a US orthopedic group paying through Worldpay, and both expressions coexist on a single code path
- Configuration changes without deployment dependency. Settings that previously required a release cycle to change - or a schema migration - now propagate in seconds. A merchant-success engineer can adjust a retry posture, a PM can swap payment method ordering for one country, a compliance team can tighten 3DS polling for a regulatory perimeter, and none of it touches the release train. Configuration moves at business speed; code moves at engineering speed.
- Experimentation as a first-class primitive. Every configuration can be tested against live traffic - control variant, one or more candidate variants, traffic split in configurable percentages, ramped or rolled back from a UI without any deployment. Conversion-sensitive surfaces (retries, 3DS thresholds, ordering) stop being one-shot decisions and become continuously tunable.
- Type safety and audit by default. Every key has a JSON Schema enforced at write time, and every change is recorded with who, when, what, and against which context. The class of incidents where a malformed value silently breaks a payment flow is closed off, and the patchwork of git history, DB change logs, and Slack threads collapses into one audit surface.
-
The payments journey keeps getting deeper. What used to be a single auth call is now a graph - dynamic 3DS, mandate setup, wallet-specific field collection, network tokens, smart retries, processor-specific webhook handling, payout retry chains. Each new capability ships with its own configuration surface. Hyperswitch is at 300+ configurations today across backend, SDKs, and Control Center, and that number grows every release. Deeper journeys raise the cost of getting any one config wrong - a bad value in production is now a wrong payment, a missed mandate, a stuck payout. This demands reliability: type safety, audit, scoped rollouts, instant rollback.
-
ISF and platform deployments keep multiplying the variance. A single Hyperswitch instance now serves hundreds of sub-merchants - each with their own PSPs, geographies, payment methods, regulatory posture, and commercial constraints. On these deployments the variance isn't a corner case, it's the product.
Hyperswitch has been managing configurations across three mechanisms
| Mechanism | Time to change | Staggerable | Type-safe | Hierarchical |
|---|---|---|---|---|
| Deployment configs (env / TOML) | Release cycle | Deploy-level only | Partial | No |
| Runtime configs (config table) | Seconds | No | No | No |
| Domain configs (schema columns) | Code + migration | No | Yes | Implicit |
Deployment configs are reliable but slow. Runtime configs are fast but loose. Domain configs are type-safe but expensive to evolve. And all three share the same root cause: the logic deciding which value applies to which merchant, country, or connector lives in application code. Every new override pattern is a code change. That coupling is the tax the platform has been paying - on every merchant ask, every compliance deadline, every new payment method rollout.
Hyperswitch already gives ISF platforms an OMP hierarchy for isolating PSPs, payment methods, user access, and analytics. The configuration layer should respect that hierarchy - and the broader payment dimensions alongside it. Until now, it didn't. With this release, it does, and reliability and agility stop being a trade-off.
At request time, Hyperswitch builds a context object from the payment and asks the embedded Superposition client to resolve a key. Every matching override is evaluated, the most specific one wins - like CSS specificity - and the default applies if nothing matches.
The layers of resolution, from least specific to most specific which wins:
- Experiment override - a small test cohort
- Combined override - a specific mix of dimensions (For instance: one merchant + one processor + one currency)
- Hierarchy override - an organization, a merchant, or a profile
- Single-dimension override - a single country, processor, currency, etc.
- Default - everything else
Each layer is optional. A configuration might have only a default and one merchant override; another might use all five. The same key can be expressed at different layers for different merchants - that's the whole point.
For instance, take a single key: poll_config_external_three_ds - how often Hyperswitch checks back with the external 3DS authentication service to see whether the customer has completed the challenge, and how long it keeps trying before giving up.
Poll too aggressively and you generate wasted load on the authentication provider; poll too lazily and abandoned authentications sit in limbo, hurting conversion and dragging out failed payments. There is no single right value - it depends on who the merchant is, which 3DS provider is on the other side, and what the regulatory bar looks like in their market.
| Layer | Context | Value | Why |
|---|---|---|---|
| Default | - | every 5s, give up at 5m | Reasonable balance for most external 3DS flows |
| Connector | connector = threedsecureio | every 3s, give up at 5m | This provider returns faster, so a tighter poll surfaces results sooner |
| Country | country IN (DE, FR, NL, IT, …) | every 2s, give up at 3m | PSD2-driven - abandoned authentications need to be detected quickly |
| Merchant × payment method type | merchant_id = m_telehealth_eu AND payment_method_type = credit | every 1.5s, give up at 2m | High-intent, high-drop-off checkout - every second of limbo costs conversion |
| Experiment | same context, variant tighter_poll_v2 @ 10% traffic | every 1s, give up at 90s | Testing whether sub-2-minute timeouts recover more abandoned authentications |
Now two payments arrive on the same deployment, the same code path, the same key: Two cases emerge:
- A telehealth subscription on a German credit card routed through threedecure.io. Four overrides match - connector, country, and merchant × method. The most specific wins: every 1.5s, give up at 2m. Unless the payment lands in the 10% experiment bucket, in which case it resolves to the variant and its outcome feeds the experiment's metrics.
- A US subscription on a debit card from a different sub-merchant, routed through a different 3DS provider. None of the European or merchant overrides apply; only the default. Every 5s, give up at 5m. The European merchant's special-casing is invisible to everyone it doesn't apply to. One key, five co-existing answers, zero deploys, zero schema migrations, zero for a merchant_id branch. And when the experiment concludes that tighter polling recovers meaningfully more authentications, promoting the variant to a permanent override is a click - scoped exactly to where the data says it helps
The 3DS polling window isn't special - almost every consequential configuration in payments has this shape. A recurring-mandate retry policy is really a mandate_type × connector decision. A wallet checkout field rule is really a payment_method × connector decision. A payment-sync window is really a merchant × payment_method_type decision. The new configuration management lets each configuration express what the decision actually depends on, instead of forcing every variation through the merchant ID - and lets all of those expressions coexist on one code path.
The mechanical wins - runtime changes, type safety, audit - are real, but the more interesting story is what becomes possible for the ones building, selling, and operating the payment stack.
- Phased payment method launches. Bring a new payment method live for a single country or merchant cohort first, monitor conversion, then expand. The same scoped override is also the rollback button.
- Continuous experimentation on the metrics that matter. Test variants of retry policies, 3DS thresholds, or payment method ordering against live traffic, with traffic-splitting and instant rollback built in. Conversion-sensitive surfaces stop being one-shot decisions.
- One feature flag model across the stack. The engine that scopes a configuration also gates a feature. The gap between "the feature is shipped" and "the feature is on for the right cohort" disappears.
- Same-day response to merchant requests. A sub-merchant asks that today an engineering ticket - a longer sync window, a different retry posture, a payment method ordering change - resolves as a scoped override in minutes.
- Templated sub-merchant onboarding. New sub-merchants in a known segment (EU healthcare, US high-ticket B2B, APAC subscription) onboard against an existing override pattern. Onboarding becomes a checklist, not a sprint.
- Compliance windows hit without collateral. A regulator-driven change rolls out to exactly the affected perimeter and no further - no platform-wide release, no impact on unaffected merchants.
- Controlled PSP migrations. Move a merchant cohort to a new processor as a staged rollout - 5% -> 25% -> 100% - with authorization-rate monitoring at each step.
- For ISF platforms, the cumulative effect is the difference between being a platform and being a queue of bespoke engineering work. Variance becomes a configuration question instead of a roadmap question.
- Decouples change cadence. Configuration moves at business speed; code moves at engineering speed. Most merchant escalations stop landing on the engineering backlog at all.
- Type-safe writes. JSON Schema validation at save time closes the class of production incidents caused by a malformed configuration value.
- One code path, many tenants. Override patterns that used to live in if merchant_id == … branches now live in resolution contexts. The base code stays the same; one binary serves every variant.
- Staggered rollout and instant rollback as primitives. No more building deployment-gating machinery in-house for every risky change.
- Audit by default. Every change is recorded with who, when, what, and against which context. Replaces the patchwork of git history, DB change logs, and Slack threads.
- Changes scoped to the regulatory perimeter. A PSD2-driven change applies to the EU; a US healthcare flow tweak applies to that perimeter alone. No global flags for local requirements.
- Reversible by design. Every change is a one-click rollback in the Admin UI, not a hotfix release. For changes touching authorization rates, payout reliability, or chargeback exposure, this is the safety net that lets the platform move faster and safer.
- Stronger control over regulation-sensitive flows. Mandates, 3DS behaviour, and retry chains - historically the most exposed surfaces - are tuned explicitly along the dimensions that matter, instead of being implicit in code that's hard to audit.
The config table is the first tenant. Migrating next, each behind its own release note:
- Feature flags - today scattered across env vars and DB tables, gaining hierarchical scoping and staggered rollout.
- TOML runtime configs - settings that don't strictly need a redeploy but live in TOML for historical reasons. Pure deployment-lifecycle settings (bind addresses, DB strings, secrets) stay in TOML.
- Required dynamic fields for Web and Mobile SDKs - field composition of the payment page, per merchant and per payment method. This closes the loop for ISFs whose sub-merchants need scoped checkout customization.
- Embedded Superposition inside the Hyperswitch Control Center - so merchants (and sub-merchants and business profiles) can manage their own configurations, define their own overrides, and run their own experiments directly from the control center, without filing a ticket against Hyperswitch. This is the change that turns configuration from a Juspay-operated surface into a merchant-operated one.
- Deploying Superposition: Ensure the specific version of Superposition mentioned in the Hyperswitch stable release notes is deployed to your environment. Deployment helm charts will be provided in hyperswitch-helm along with the stable release.
- Execute migration tools: With every stable release, we provide a migration utility (SQL query and Python script) to transition configurations from hyperswitch_db into Superposition. To use it, first run the following SQL query and export configurations as a configs.csv:
SELECT * FROM configs WHERE key LIKE '%poll_config_external_three_ds%';
Then, process this file using the provided Python script to automatically create overrides for any non-default configs:
python migrate_config.py --input configs.csv --env prod
The script processes one Superposition environment at a time, selected using the --env flag (local, integ, sandbox, or prod). You must define connection details—including the host URL, organisation ID, workspace ID, and auth token—in the script's ENVS dictionary before execution. This utility performs two primary functions: it can seed the necessary dimensions into a new workspace using --seed-dimensions, and it executes the migration by registering default configuration values and creating dimensional context overrides based on your database dump.
- Point Hyperswitch at Superposition: Configure the new environment variables (SUPERPOSITION_HOST, workspace identifiers, and polling intervals). Hyperswitch is designed to fail fast on startup if the connection is unreachable. Use the following configuration block:
[superposition] endpoint = "http://localhost:8081" org_id = "localorg" workspace_id = "dev" polling_interval = 300 backup_file_path = "./config/superposition_seed.toml"
- endpoint: The base URL of the running Superposition service.
- org_id: The identifier for your organization within Superposition.
- workspace_id: The identifier for your specific development or production workspace.
- polling_interval: The interval, in seconds, at which the client checks for configuration updates.
- backup_file_path: The path to a local configuration file used as a fallback if the Superposition service is unreachable, ensuring the application can still function during service disruptions.
- Update Superposition and run DB migrations: For every new release, update Superposition to the corresponding version and execute necessary database migrations before upgrading the superposition application.
- Run migration scripts for new configs: Execute the provided Python migration scripts to move new configuration values from the database into Superposition overrides as required by the release.
- Upgrade Hyperswitch: Once the configuration layer and migrations are finalized, proceed with upgrading the Hyperswitch application to the latest stable version as usual.