If you serve multiple merchants and payments are part of your core offering, this one's for you. Before we talk about Superposition, we need to talk about configuration, and why it quietly sits between your merchants and almost every outcome they care about.

Imagine a SaaS company that builds practice management software for healthcare providers, with payments embedded in the product. They have a few hundred sub-merchants on the platform, spread across the US, Europe, and parts of Asia. Some are single-practitioner telehealth clinics. Others are multi-site groups with dozens of locations.

It's a Monday. Three requests come in.

One is from a telehealth practice in the Netherlands. Their checkout isn't converting the way it used to. Turns out Dutch patients mostly want to pay with iDEAL, and the payment page on this platform shows cards first. The practice has been watching completion rates drop and they want the page reordered so iDEAL is on top.

The second is from a US orthopedic group running a dozen clinics. Their auth success rate on high-ticket surgery deposits, $3k to $15k transactions, often on HSA cards with insurance pre-auths in the mix has been going down. The PSP sometimes takes longer than the platform's default sync window to confirm, and those transactions get marked as failed when they weren't. The fix they need: a longer sync window, scoped to their traffic.

The third is from a German digital health platform preparing for a PSD2 compliance review. The regulator wants tighter guarantees around 3DS finality, and they have two weeks to show it. The fix: shorter polling intervals on external 3DS, so abandoned authentications are detected faster.

So we've got three sub-merchants, three real business problems (completion rate, auth success, a compliance deadline), and three configuration changes that would fix them. In principle that's a day's work. In practice, each of those three changes lives in a completely different part of the stack, and each part of the stack has its own rules about how and when you're allowed to change things.

That's the problem. Let's take a closer look at the problem.

The hidden tax of configuration

Think about where configurations actually live in a typical payments platform. They end up in one of three places.

Some configs live in TOML/YAML files which are environment variables which are read once when the service starts up. These are fine for settings that genuinely never change. But when something does need to change, you're looking at a release cycle - edit the file, deploy, wait. Rolling back is another release. Staggering a change to 10% of traffic to watch metrics first? Not possible because the value is global to the deployment.

Some configs live in a database table. This is better, on the face of it as engineers can change values without a deployment. But the generic config tables don't natively understand scope. When you want a different value for one merchant, someone writes a code path that reads the merchant ID and picks the right value. The value lives in the database; the scoping lives in code. Every new scope is a code change.

And some configs live in domain tables which are strongly-typed columns on a merchant or profile record. This is the most merchant-aware of the three, which is why it's often used for merchant-facing settings. But every new field added needs a schema migration, and every override pattern ("this merchant, except on Thursdays") is more code.

Now let's go back to the three Monday asks. Depending on how your stack is built, each of changes to be done could land in any of these three layers and each layer has its own cost. Notice the common thread: values can live in a file, a database, or a schema column, but the decision about which merchant gets which value almost always lives in application code. That's the real tax.

And it's not just an operational tax. Every commercial outcome your merchants care about better auth success, better checkout completion or cleaner compliance posture eventually routes through a configuration change somewhere in this stack. On a platform carrying hundreds of configurations across backend, SDK, and control center, multiplied by hundreds of sub-merchants, that system isn't just hard to manage. It's the thing sitting between your merchants and the outcomes you promised them.

Evolution of our configurations

We know about this problem well, because we experienced it ourselves running Hyperswitch.

Hyperswitch didn't arrive at its current configuration model by theorizing. We got there by trying the obvious things first, and watching each of them come up short in its own way.

We started with deployment configs in TOML files. Fine for settings that genuinely never change. Painful for anything else, every tweak was a release, every rollback was another release, and anything staggered was off the table.

So we moved more configs into a runtime database table. Faster to change, no deploys. But the table didn't understand scope, so every new "apply this to just these merchants" rule was a code change. And there was no type safety, nothing stopped a value from being saved in a shape the code didn't expect.

So we moved the most important configs into domain tables strongly-typed columns, merchant-aware by design. Safer. But now every new config was a schema migration, and every nuanced override was still code.

Three mechanisms. Each one solved a dimension the others missed, and broke something the others had right. And all three shared the same underlying problem: configuration logic was welded to application code. You could change values fast, or change them safely, or scope them precisely but not all three at once.

That's when Juspay, the team behind Hyperswitch stopped adding mechanisms and started over. The answer wasn't a fourth place to put configs. It was a way to get configuration logic out of the code entirely. Superposition was built as an answer to this problem.

What is Superposition and how it works

At its core, Superposition is a configuration platform that lets you define default values, write rules about when those values should change, and resolve the right answer in real time based on the context of the request.

If you've ever written CSS, you already understand the model. You set defaults, then write rules, "if the element is in the sidebar, make the text smaller," "if the user is on mobile, stack these columns." The most specific rule wins.

Superposition does exactly that, for configuration. You set defaults, then write rules: "if the merchant is in the EU, use this retry policy," "if the transaction is over $5k on this PSP, use these 3DS settings," "if the profile is this Dutch telehealth practice, surface iDEAL above cards." When a transaction comes in, Superposition evaluates the context, picks the most specific match, and returns the resolved values all in memory on the application itself, with no extra network hop.

Below are four concepts you need to know to understand Superposition better.

Defaults: Every configuration has a baseline value, the one that applies unless a more specific rule overrides it. Every value is type-checked the moment it's saved, so a setting that should be a number can't quietly be stored as text. That alone removes a whole category of "why is production behaving strangely" incidents.

Dimensions: These are the things that can cause a value to change a merchant, a region, a payment method, a connector, a business profile. In Hyperswitch, dimensions mirror the natural hierarchy of the platform: organisation → merchant → profile → connector. They're the axes of variation, and you can add your own.

Contexts and Overrides: A context is a condition: EU merchants on Stripe, or transactions over $5k on a specific PSP, or this Dutch telehealth practice. An override is the set of values that apply when the condition is true. You stack as many as you need. When a transaction comes in, Superposition evaluates every matching override and the most specific one wins just like CSS.

Experiments: Every configuration change can be rolled out as a test. Apply a new value to 10% of traffic, watch the metrics, ramp to 50%, then 100%. Something off? Roll back instantly. All of it happens live, with no deploy, no release, no window to coordinate with engineering.

What Superposition unlocks

Onboarding at the speed of configuration. A new sub-merchant stops being a project and starts being a pattern. You define the right overrides at the right level of the hierarchy organisation, merchant, profile, connector and every transaction that merchant ever processes resolves against those values automatically. Patterns clone across cohorts. A new EU healthcare merchant? Apply the EU healthcare override set. A new high-ticket B2B client? Apply the high-ticket pattern. The question - how fast can we onboard this merchant? becomes a configuration question, not a sprint-planning question.

Customization at the scale of reality. The variation that makes your platform commercially valuable: different retry windows, different payment method ordering, different 3DS behaviour, different feature toggles lives in data, not in code. One code path serves hundreds of sub-merchant realities. The platform grows without the configuration surface becoming unmanageable, because the complexity is expressed, not accumulated. Your stack finally matches the shape of your business.

Changes that are safe and fast at once. Type checks at write time mean malformed values never reach production. Experiments mean every change can be staged 10% of traffic first, then 50%, then 100%, with instant rollback if anything looks off. The auth-success fix for a high-ticket merchant? The completion-rate fix for a European cohort? The compliance-driven change with a regulator's deadline attached? All of them ship as scoped, staggered rollouts instead of platform-wide releases. The historical tradeoff moves fast or doesn't break things and stops being a tradeoff. You get both.

Configuration as infrastructure

Hyperswitch has always been built on one idea: payments should behave like infrastructure, modular, composable, and under your control rather than a vendor's. Configuration is where that idea meets the ground. A stack that serves a few hundred sub-merchants at scale needs its configuration layer to behave like infrastructure too: context-aware, type-safe, staggerable, resolved in real time.

Superposition is built with these principles in mind. It's open-source, it's battle-tested across the Juspay stack, and it's now a first-class part of how Hyperswitch is built.

Explore more - GitHub, Documentation, Demo.