Hyperswitch Vault is a PCI-compliant store for customer payment methods. Behind that simple description is an unusual design choice: where card data lives, who runs the orchestrator, and who carries PCI scope are three independent decisions. Merchants make them separately. And they can revisit them later without re-collecting a single card.

Most platforms force a single box. Fully SaaS or fully self-hosted. You handle PCI or you don't. That isn't what merchants actually look like.

Some already carry PCI certification and want to keep accessing raw card data. Others want to exit PCI scope to cut audit costs. Some are locked into VGS or TokenEx contracts. Some have a payment engine they're proud of but want a better vault. The Vault is built so each of those shapes is a configuration, not a different product.

Below picture describes how the architecture is wired, the five merchant shapes it covers, and what the merchant actually has to decide.

The architecture in one frame

The orchestrator stores and retrieves payment methods through a single interface: the Payment Method Management layer. That layer sits in front of one or more vault backends, namely Hyperswitch's general-purpose vault, a third-party vault like VGS, or a merchant-owned vault. The backend is configurable.

Every stored payment method comes back as a payment_method_id. That token looks the same regardless of what's underneath.

That's the load-bearing detail. The payment_method_id is the interface between the orchestrator and whatever sits below it. Swap the vault backend, and existing tokens, customer references, and integration code keep working. Adding a self-hosted orchestrator, swapping VGS in for the default vault, moving from SaaS to self-hosted these become configuration changes in the Control Centre, not re-vaulting projects.

How card data gets in

Two integration paths put card data into the Vault. The choice maps directly to who carries PCI scope.

Vault SDK

Card data is collected and tokenized inside a PCI-compliant iframe embedded in the merchant's checkout. Raw PAN never touches the merchant's servers. Minimal PCI scope. This is the path most merchants take.

Server-to-server

The merchant's backend calls the Vault REST API directly with raw card data. This requires the merchant to be PCI DSS certified. Used for B2B flows, batch migrations from a previous vault, and merchants who already carry PCI scope for other reasons.

A merchant can mix both. SDK for consumer checkout, server-to-server for a back-office migration script. They share the same payment_method_id namespace.

How a saved card gets charged

Once a card is in the Vault, charging it follows one of three patterns. Each suits a different operational shape.

Vault-Then-Pay

Decouples collection from purchase. Useful when those events happen at different times: subscription signup before the first billing cycle, account setup before checkout, B2B onboarding before invoicing.

Pay-Then-Vault

The fully managed shape. Charge happens first; the card is stored after a successful authorization, network-tokenized, and lifecycle-managed in the background. The merchant carries no PCI scope at all.

Proxy Payments

For merchants who want out of PCI scope without disrupting PSP relationships. Instead of calling the PSP directly, the merchant calls Hyperswitch's Proxy with the PSP request body containing placeholder strings, the destination PSP URL, and the token. The Vault detokenizes inside the request lifecycle, substitutes the placeholders, forwards to the PSP, and returns the response. Card numbers never touch the merchant's servers. PSP integrations require minimal change.

Five ways to configure the Vault

Three questions walk you to a configuration. The first sorts merchants into two big buckets; the next two narrow each bucket down to a specific shape.

• Who runs the payments stack: Hyperswitch, or your own engine?
• Who carries PCI scope: in-house, or outsourced?
• (If Hyperswitch and outsourced PCI) Self-host the orchestrator, or use Hyperswitch's SaaS?

The Vault supports a deployment for every combination.

The five shapes the tree lands on map directly to the merchant asks below. The integration shape doesn't change between them, only the configuration does.

"We're regulated. Card data has to stay inside our perimeter."

A healthcare, government, or financial-services merchant with residency or compliance constraints will opt for Self-hosted Hyperswitch end-to-end. Both the orchestrator and Vault run inside the merchant's perimeter. Nothing leaves. They own infrastructure, scaling, and PCI compliance and get full autonomy over security policies and encryption schemes. In-house PCI.

"We have a VGS contract we can't break, and we want orchestration on top."

A mid-size merchant with an existing third-party vault investment, or a SaaS platform whose merchants demand minimal PCI scope will opt for Self-hosted orchestrator + SaaS HS Vault / 3rd-party Vault. Merchant runs the orchestrator on their infrastructure for routing control, but card data sits with Hyperswitch's SaaS Vault or a 3rd-party like VGS. Existing tokens stay portable through the payment_method_id layer. Outsourced PCI.

"We want to launch fast and not own any of this."

A growth-stage merchant without an existing vault relationship will opt for SaaS orchestrator + SaaS Vault. No servers, no PCI audits, no infrastructure. Hyperswitch handles everything. The default starting point for most merchants. Outsourced PCI.

"We already process payments through our own engine. We just need a compliant place to store cards."

A bank or payment facilitator with a working payment stack they don't want to replace will go for Standalone Vault, own payment engine. The merchant keeps their engine and uses Hyperswitch only for vault storage and tokenization. They detokenize on retrieval to charge through their own PSP integrations which means card data flows through their servers, so they keep in-house PCI.

"We want out of PCI scope without disrupting our PSP relationships."

A merchant with their own payment engine and existing PSP integrations they've spent years tuning will go for Standalone Vault + Proxy Payments. Vault tokens go in, the Proxy detokenizes mid-call and forwards real card data to the PSP, and the PSP's response comes back to the merchant. The merchant never holds raw card data and never touches their PSP integration code. Outsourced PCI.

The pattern: Most of the asks that used to mean re-architecture now collapse into onboarding-time configuration. A merchant moves between shapes by changing a setting, not by rebuilding a stack.

Where responsibilities split

Two boundaries worth being explicit about. Most architectural confusion comes from blurring them.

Vault vs orchestration

The Vault stores card data and emits reusable tokens. It doesn't pick a PSP, retry failed authorizations, or run 3DS. The orchestrator turns a token into a PSP authorization request: picks the connector, applies retry policy, handles 3DS step-up. The payment_method_id is the interface between the two layers. That's why either can be swapped independently.

The token vs the data

The payment_method_id is a portable handle. It connects the customer identifier, the underlying vault token, and any PSP-side tokens (network tokens, PSP-issued tokens) into one stable reference.

The actual card bytes live wherever the configured vault backend puts them Hyperswitch's vault, VGS, the merchant's self-hosted vault. Switching the backend doesn't change the payment_method_id. Switching PSPs doesn't either.

Picking a starting point

For merchants without an existing vault relationship, SaaS orchestrator + SaaS Vault is the right start. Outsourced PCI, lightest integration, network tokenization included.

For merchants with existing constraints (i.e. a VGS contract, an in-house vault, an internal PCI environment, a self-built payments engine) pick the shape that wraps around what's already there. The integration looks the same.

The decision is real on day one. Who runs payments and who carries PCI scope both have downstream operational and compliance consequences. What the architecture removes is the cost of changing your mind later. Every shape shares the payment_method_id token standard. Moving between them - adding a self-hosted orchestrator, swapping the default vault for VGS, or moving from in-house PCI to outsourced by switching to Proxy Payments is a configuration change in the Control Centre, not a migration project.

For end-to-end request shapes, field references, and the full dashboard walkthrough, see the Vault Configuration guides. Want to see the Hyperswitch Vault in action? Try it yourself in the Hyperswitch Vault playground.