When we introduced a single, standard payment payload in Hyperswitch, the goal was simple: give platforms one backend contract that works everywhere. One API that can handle any payment action across providers, regions, authentication methods, and fraud requirements without rewriting logic each time.
In a world where providers behave differently, this becomes the cleanest way to eliminate fragmented code paths, brittle SDK dependencies, and multi-quarter reintegration cycles. For ISFs that embed payments into their platform, this approach becomes the difference between scaling efficiently and accumulating years of technical debt.
This is the architectural pattern that modern platforms increasingly rely on, whether or not they ultimately choose Hyperswitch.
The Problem: Fragmentation by Default
Most payment stacks begin simply: one PSP, one flow, one integration. As a business scales, that simplicity quickly breaks down. In Blog 2, we showed how even a basic $100 payment takes different shapes across PSPs, forcing engineering teams to rebuild integrations for every new processor they add. Expansion into new markets brings new PSPs, compliance raises the bar on authentication, fraud patterns evolve, and product teams push for smarter routing and retries. Basically, each new need creates another integration path and creates pressure to an already fragile integration surface.
For platforms that serve large merchant bases, this fragmentation becomes a barrier to scale. You lose the ability to improve payments centrally without disrupting the experience merchants rely on. Hyperswitch is designed to prevent that outcome entirely.
One Envelope and One Integration Surface
The core idea is straightforward: your backend sends a single canonical JSON request (an envelope), and Hyperswitch handles the rest. In the context of blog 2, Hyperswitch would automatically translate that request into the PSP-specific formats required by each configured processor. Your team no longer has to build or maintain bespoke integrations for every PSP. You integrate once, and Hyperswitch absorbs the complexity.
The envelope (or payload) carries the facts and signals your platform already knows. This includes the amount, currency, customer reference, and payment method. It also carries 3DS context or any decision you have made upstream, the fraud context or any risk result, tokenization intent, vault preferences, routing guidance, and retry preferences. Merchant and profile identifiers are included as well so Hyperswitch can evaluate your configuration rules.
From the outside, nothing about your experience needs to change. There is no SDK to embed. There is no UI or checkout rewrite. Merchants do not need to adopt a new dashboard. Your backend does not need separate integrations for each PSP, risk provider, vault, or 3DS layer.
Your merchants continue to interact with the experience they already trust. You retain ownership of the entire customer surface. Hyperswitch takes responsibility for the orchestration beneath it. With the canonical envelope defined, the next step is understanding how it actually moves through the system. The diagram below maps the full journey end-to-end:
How the Envelope Works Behind the Scenes
The canonical envelope is powerful because it turns the moving parts of payments into signals rather than separate integration tracks. This allows platforms to evolve without introducing new code paths. Concretely, the canonical envelope is just a JSON body your backend sends to POST /payments. Here’s what that looks like in practice:
Below is a breakdown of how each capability sits within the envelope:
Routing and Retries as Strategy Rather Than Code
The envelope carries the context of the payment. This includes BIN information, the region, the merchant profile, and any risk signal. Configuration determines the actual behavior. You choose which acquirer should be prioritized, how domestic and cross-border decisioning should work, how authentication should be upgraded for risk, and how recovery should behave after errors.
Your system does not implement retries in each PSP. You simply tag a recovery approach and Hyperswitch applies it.
Fraud as a First-Class Signal
Most systems treat fraud as an entirely separate workflow. The envelope model removes that complexity. You can attach the outcome of your own fraud engine or you can attach the context required for Hyperswitch to make the call. That decision becomes part of routing, 3DS posture, and retry strategy.
Your integration surface remains the same regardless of the fraud system you use today or choose tomorrow.
3DS Without a Coupled SDK or Checkout Change
You provide 3DS intent and the required browser and device context. Hyperswitch translates that into the PSP-specific 3DS APIs and normalizes the results.
Your customer experience remains exactly the same. You can expand SCA coverage across new markets without reworking your checkout logic.
Tokenization Without Structural Lock-In or Dependency
Traditional tokenization binds your backend, vault provider, and PSP selections tightly together. Changing any element becomes a lengthy and fragile migration.
With the envelope, you only express intent. This may include storing a card, reusing an existing token, preferring network tokens, or storing the token in a particular vault. Hyperswitch handles the mechanics of PSP vaults, the Hyperswitch vault, network tokens, and any hybrid arrangement you choose. It also manages token transitions across providers when your strategy evolves.
Your payload shape never changes and your merchants never experience disruption.
What Stays Exactly the Same
This is often the part that resonates most strongly with product and platform teams.- Your checkout stays exactly as it is today.- Your dashboards maintain their existing structure.- Your merchants do not need to reconfigure or relearn anything.- Your brand and UX remain intact and untouched.
Hyperswitch enhances the engine beneath your platform without interfering with the part customers actually see.
Why This Matters for ISFs, SaaS Platforms, and Fintech Builders
A canonical payment envelope offers four material advantages that directly address the needs of modern platforms.
First, you gain a single integration surface.You never reintegrate when adding a new PSP, adjusting 3DS posture, improving fraud models, or optimizing routing.
Second, you gain true optionality.You can adjust provider relationships, authentication approaches, vaulting preferences, fraud sources, and retry logic entirely through configuration rather than code rewrites.
Third, payments become a product surface.You can introduce new tiers of capability, experiment with routing logic, introduce new methods, and evolve fraud posture without redesigning your integrations.
Fourth, you retain complete ownership of the user experience.Your platform determines how the experience looks and behaves. Hyperswitch operates behind the scenes.
These capabilities directly align with what ISFs need in order to scale across geographies, comply with shifting regulations, deliver differentiated merchant experiences, and monetize payments effectively.
Where the Architecture Goes From Here
On your side, the envelope remains stable and predictable. Your integration does not change over time.
On our side, the system continually evolves behind that contract. This includes new connectors, improved error normalization, more sophisticated routing, deeper tokenization strategies, enhanced 3DS behavior, richer analytics, and expanded fraud intelligence.
This is the value of a well-designed abstraction. You integrate once and the platform continually improves behind that boundary.
If you are considering building orchestration in-house or are looking for a way to escape a growing network of provider-specific code paths, the canonical envelope is the architectural model we encourage you to evaluate seriously.
