What a Hyperswitch migration involves
Moving onto self-hosted Hyperswitch means replacing the layer that sends your payments to processors. The starting point is usually either a single PSP integration, where your code calls one provider's API directly, or a hosted orchestrator that routes payments on your behalf. The work has four parts: setting up each processor as a connector on your own Hyperswitch deployment, cutting routing over from the old path to the new one, deciding how stored card tokens move, and running both paths side by side until the new one is proven.
Teams usually move for one or more of these reasons: the cost or control of a hosted layer, the need to own routing and processor choice, the wish to add processors the current setup does not cover, or requirements on where data lives and who operates the platform. The trigger shapes the scope. A cost-driven move may keep the same processors, while a routing-driven move adds connectors and rules. Write down the trigger first, because it determines which connectors, routing behavior and token decision matter most.
Stored card tokens are the decision most likely to stall a migration. Tokens issued by the old provider are tied to that provider, so confirm in writing whether a card export is possible, whether the new vault can receive it, and how cards would be re-collected if it cannot. The vault model and the PCI DSS scope that follow from this choice are covered on sibling pages, so settle the token path before you commit to a vault design.
Plan a period where old and new paths run side by side, starting with a small share of traffic on Hyperswitch and reconciling results against the old provider's reports before that share grows. Most migrations of this kind are run by an internal payments team, with a partner supporting connector configuration, testing and cutover reviews. A partner-led cutover fits teams without spare payments capacity. Ask for the length of the parallel period in the quote, since it depends on your volume and the number of processors involved.
What the work includes
A Hyperswitch migration scope is made of six workstreams, and each one ends in a deliverable you keep. DeployOpen prepares systems and evidence for PCI DSS assessments but does not issue PCI DSS attestations or audit reports.
Payment flow and processor inventory
A written map of every payment flow in scope, including authorization, capture, refund, void, recurring billing and payouts, with each processor, acquirer and wallet that receives them. Gaps in this map are the most common cause of flows that break at cutover. Deliverable: an inventory workbook listing flows, processors, data fields and named owners.
Connector configuration per processor
Each processor in use is set up as a Hyperswitch connector, with credentials held in your secrets store, webhook endpoints registered and payment method types enabled to match today's integration. Confirm each processor's supported features in the Hyperswitch connector documentation before assuming parity with your current setup. Deliverable: connector configuration records and a test matrix for each connector.
Routing cutover with traffic splitting and rollback
Defines how traffic moves from the current path to Hyperswitch in agreed percentage steps, with routing rules set for each step and triggers that return traffic to the old path. Parallel running keeps both paths live for a period you agree in advance. Test routing strategies, including default fallback, before any live split. Deliverable: a cutover plan with the traffic schedule, rollback triggers and a rehearsed rollback procedure.
Stored token migration design and execution
Stored card tokens either move to the new vault or customers re-enter their cards. The right option depends on whether your current provider allows token export, the vault model you choose and what each processor accepts. Moving card data changes PCI DSS scope, so the design comes first. Deliverable: the migration design, an execution log and a verification report.
Reconciliation between old and new paths
Settlement files, processor reports and ledger entries from both paths are matched day by day during parallel running. Differences in amount, status, currency or fees are logged and assigned an owner before the next traffic step begins. Deliverable: reconciliation reports or scripts, a difference log and written sign-off criteria for each cutover step.
Cutover runbook and handover documentation
A step-by-step runbook covers pre-checks, change windows, go and no-go decisions, monitoring, and rollback commands, with a named role for each step. Handover documentation transfers configuration, operating procedures and open risks to your operations team. Deliverable: an approved runbook and a handover pack with configuration records and operating procedures.
What drives cost and duration
Each driver shows why it moves effort on a Hyperswitch migration and one practical way to keep it manageable, and the quote follows the written scope.
| Driver | Why it changes effort | How to keep it down |
|---|---|---|
| Processors and payment methods | Each processor needs its own connector configuration, credential handling and test cases, and each wallet or local method adds more. | Start with the processors that carry most volume and move low-volume methods to a later phase. |
| Stored card tokens | Migrating saved cards needs an export from the current provider and a vault model that accepts the exported data, which can become the critical path. | Ask the current provider early whether it will export tokens and confirm the format before design starts. |
| Starting point | A direct PSP SDK, hosted checkout or hosted orchestrator each changes how much client code and contract work must move. | Map every payment entry point first so the team knows which apps and redirects change at cutover. |
| Routing complexity | Each routing rule, fallback order and retry policy must be rebuilt and tested before live traffic moves. | Begin with one rule-based route and default fallback, then add strategies once the baseline passes testing. |
| Parallel run | Old and new paths must run side by side long enough to compare authorization outcomes, which widens testing and reconciliation load. | Agree the traffic split, exit criteria and rollback trigger in writing before the parallel run starts. |
| PCI DSS scope | Hosting the card vault in-house brings more systems and controls into assessment scope than a tokenized design does. | Choose the vault model early and isolate the card data environment from other workloads. |
| Environments and clusters | Sandbox, staging and production, each with its own Kubernetes cluster and database, multiply deployment, secrets and monitoring work. | Define all environments from one Helm-based configuration with separate secrets and cluster boundaries. |
| Reconciliation and reporting | Settlement files, ledger exports and finance reports must match across the old and new paths, often needing custom mapping. | Define reconciliation outputs and their owners in the written scope before connector work begins. |
| Client apps and SDKs | Each web, mobile or backend app that calls payments needs SDK integration, testing and release coordination. | Inventory every client and integration, then group apps that can share one SDK version and release window. |
Migration phases and outputs
The sequence moves a payment flow from its current integration onto self-hosted Hyperswitch in controlled stages, with a named output at each phase so that go or no-go decisions rest on evidence.
Inventory payment flows and dependencies
DeployOpen maps every payment flow, processor integration, stored card token set, webhook consumer and reporting feed that touches the current path, with your payments and security owners. The closing output is a payment flow inventory that lists each flow, its volume class, its processors and the systems that depend on it.
Design target connectors, vault model and baseline routing
The team selects the connector set, chooses one of the three documented vault models and drafts an initial routing baseline with default fallback order. The outputs are a connector matrix, a vault model decision record that states PCI DSS responsibility, and a routing specification for the first live rules.
Build and validate connectors in non-production
Connectors are configured and tested in non-production environments against processor sandboxes, covering authorization, capture, refund, void and webhook handling. Completion is a validation report per connector that records passed and failed test cases and open defects.
Rehearse stored card token migration
Stored card tokens are exported from the current provider and imported into the target vault in a rehearsal, with counts and format checks at each stage. The output is a tested token import report that states matched, rejected and unresolved records, and confirms the provider's export terms before any production run.
Run old and new paths in parallel
A controlled share of live traffic is routed through Hyperswitch while the existing path handles the remainder, and the split is increased only when the agreed thresholds hold. The output is a reconciliation report comparing settled amounts, declines and fees across both paths for each traffic step.
Cut over and hold hypercare
Full traffic moves to Hyperswitch under a cutover runbook with named roles, rollback triggers and communication steps, followed by a hypercare period with heightened monitoring. The closing output is a signed cutover record and a hypercare exit report listing open issues and their owners.
Decommission the old path
Once the agreed hypercare exit criteria are met, the old integration is disabled, credentials are revoked, and retained data is archived under your retention policy. The output is a decommissioning record that confirms each removed endpoint, key and data store.
Which parts teams keep and which they outsource
This table compares which migration workstreams a client team usually owns in-house and which a partner typically carries, with the skills each one needs, so you can see where internal payments knowledge must stay.
| Workstream | Usually owned by | Skills needed and what stays with the client |
|---|---|---|
| Kubernetes deployment of Hyperswitch components | Partner builds, client platform team operates | Kubernetes, Helm, PostgreSQL and Redis operations. The client must own the cluster, secrets and on-call rota after handover. |
| Connector configuration | Client payments team, partner assists | Payments operations and processor account knowledge. Only the client holds merchant credentials and processor relationships, so this stays with the client. |
| Routing design | Client payments operations, partner documents options | Payments operations and risk judgment on approval rates, cost and fallback order. Routing decisions remain a client accountability. |
| Stored token migration | Client leads with old provider and vault provider, partner plans the process | PCI DSS scoping, data engineering and coordination with the outgoing provider. Card data movement needs a PCI-aware process owned by the client and approved by its assessor. |
| Reconciliation between old and new paths | Client finance operations, partner builds comparison tooling | Finance reconciliation and data engineering. Finance must sign off on matching rules and variances because they affect settlement records. |
| Cutover operations | Client payments operations leads, partner runs the runbook | Payments operations, QA for payment flows and Kubernetes change control. Go and no-go decisions and traffic shifts are the client's call. |
| Independent security testing | Third party tester selected by the client | Application, API and infrastructure testing skills. The tester should be independent of the build team, and results are evidence for the client's own assessment. |
What goes wrong and how to prevent it
These failures recur in payment migrations onto Hyperswitch. Each card names one risk and the step that prevents it before it reaches live payments.
Token export and format gaps
The current provider may refuse or delay export of stored card tokens, or export them in a format the Hyperswitch vault cannot read. Get export rights, file format and any PCI DSS evidence the provider requires in writing before the build starts. Plan a fallback, such as re-collecting cards from customers, for tokens that cannot move.
Connector behavior differences
Processors handle authentication, retries and webhooks differently, so a connector that passes sandbox tests can misbehave with live traffic. Test declines, timeouts, duplicate webhooks and retry paths for each processor before routing any payments to it. Start merchant account onboarding early, because processor approval can take longer than the build.
Parallel running without reconciliation
Running old and new payment paths side by side only proves something if both produce matching records. Agree the reconciliation keys, the tolerance for timing differences and the owner of each exception before parallel running starts. End the run only when every unmatched item is explained and signed off, and keep the reports as evidence.
Routing cutover without tested rollback
Routing changes can send live payments to a new processor almost immediately. Test rule-based and default fallback routing in a non-production environment, then shift traffic in stages with a written rollback that a named operator can execute. Keep the old payment path accepting transactions until the rollback window closes.
Release outside the compatibility matrix
Hyperswitch ships roughly monthly minor releases, each with a compatibility matrix for Control Center and web client versions. Choose a target release that the matrix supports with the dashboard and SDKs you plan to use. Some releases add required dependencies, such as Superposition in v1.124.0, so check prerequisites before the cutover date.
PCI DSS scope widening
Self-hosting can pull new systems into scope, including the card vault, encryption service, logs, backups and any cluster nodes that handle card data. Map every system that stores, processes or transmits card data during design, and isolate the vault and encryption service from the rest. In the in-house vault model, the merchant carries full PCI DSS responsibility, so plan the assessment early.
How the work changes by starting point
When the current setup is one processor integration, the work centers on replicating a single connector and showing that it behaves the same on the new path. Routing is simple, so the main unknown is whether stored credentials or tokens can leave the current provider.
- Scope: Configure the existing processor as a Hyperswitch connector and map its payment, refund and webhook flows to what your checkout already sends.
- Sequence: Confirm token export before design work starts, then run the new connector alongside the current integration on limited test traffic.
- Routing: Expect a default route to one processor, so the routing cutover is a switch-over step, not a rule design exercise.
- Parallel run: Check for duplicate webhooks or double charges while both paths are live.
- Involved: Your payments engineers, the processor's integration contact, and the team that owns the current webhook endpoints.
Moving off a hosted orchestrator involves more commercial and data questions than a single integration does. Each processor it connects has to be mapped, and the routing logic configured inside that product must be re-expressed as Hyperswitch rules before cutover.
- Contract and data: Review termination, notice and data export terms early, since they set when you can stop paying and what transaction history you receive.
- Processor mapping: List every processor connected through the orchestrator and confirm each one has a matching Hyperswitch connector and credentials.
- Routing rules: Document existing routing and fallback logic, then rebuild it using Hyperswitch routing strategies and test each rule against sample transactions.
- Overlap period: Plan how long both platforms run, since the old orchestrator may still hold tokens, reporting history and retry schedules that need a clean handover.
- Involved: Procurement and legal for contract terms, finance for reconciliation, and the orchestrator vendor's support contact for data export.
Stored payment credentials held by an outside provider often set the pace of the whole project. The export format, transfer controls and timing are decided by that provider and by your card data obligations, so these answers should come before the vault or cutover is designed.
- Export format: Confirm with the provider the format, encryption and fields included in any token or card export, and whether that format can be imported into Hyperswitch.
- Card data transfer: Confirm the transfer channel and controls, and whether the provider will send raw card data or only tokens, since that choice changes PCI DSS scope.
- Timing: Agree a transfer window and ask how long the provider retains data after export, then set the cutover date only after the transfer is confirmed.
- Vault decision: Choose the target vault model once the export path is known, because each option changes who carries PCI DSS responsibility.
- Involved: Your PCI DSS lead, the outside provider's technical and compliance teams, and the team that owns the vault deployment.
In environments with restricted outbound access, the migration depends mostly on network paths. Every processor endpoint and webhook path has to be reachable from the target network, and inbound callbacks have to arrive at a location your firewall allows.
- Endpoint inventory: List each processor API host Hyperswitch will call, including sandbox and production hosts, and confirm reachability from the target network.
- Webhook paths: Confirm that processors can reach your inbound webhook endpoints and that the network team has approved the rules for those callbacks.
- Sequence: Complete network approvals and connectivity tests before connector configuration begins, so credential setup does not wait on firewall changes.
- Egress controls: Confirm any proxy, allowlist or certificate requirements your environment applies to outbound payment traffic.
- Involved: Network and security teams, your change advisory board, and the processors' technical contacts for any addresses that must be allowlisted.
What you need to provide
Migration work moves quickly only when the client has already gathered the inputs that Hyperswitch cannot infer from code. The list below is what we need before the plan is baselined, and it should be owned by named people on your side rather than handed to a generic project inbox.
Inventory and accounts. Provide a current inventory of processors, payment methods, currencies and flows (authorization, capture, refund, void, recurring and payouts), along with access to the existing processor and provider accounts. API credentials should move through your approved secrets channel, not email or chat. Payments operations usually owns the inventory, and security owns the credential handling. Confirm with each processor which target connectors have a live contract or onboarding confirmation, since connector setup cannot be completed on paper alone.
Stored tokens and volumes. Confirm the stored token export options your current provider offers and obtain its written process for export and for the handover of vaulted card data. Your choice of vault model in Hyperswitch determines whether tokens can be re-keyed, re-vaulted or must be migrated by a PCI-compliant path. Traffic volumes by hour, day and seasonal peak, with the peak windows you want the cutover to avoid, come from payments operations and finance planning. Reconciliation files and named finance owners complete the picture, because routing changes will shift which processor settles each transaction.
Decisions and environments. Name one owner each for payments operations, security and the cutover decision, with authority to pause a routing change. Finally, provide staging environments that mirror the production processors and a written test plan covering payment flows, failure and retry cases, refunds and reconciliation. Without a test plan agreed in advance, parallel running has no defined pass criteria.
Questions buyers ask before hiring help
What drives the cost of a Hyperswitch migration and how do I compare quotes?
Cost follows scope: the number of processors to connect, the vault model, the number of Kubernetes environments, token export work, the PCI DSS assessment effort and the internal time your payments and security teams spend. One-time costs cover design, connector build, cutover and testing. Recurring costs cover infrastructure, monitoring, monthly upgrade work and any support retainer. To compare quotes, ask each provider for a written scope listing connectors, routing cutover, token migration, environments, parallel running, documentation and handover, with the assumptions and exclusions stated for each line.
How long does a Hyperswitch migration take?
Duration depends mainly on two workstreams: processor onboarding and token export. Each processor connection needs its own credentials, sandbox testing and sign-off from that processor, and part of that timing sits outside your control. Token export depends on data volume, the format your current provider allows and the vault model you choose. Ask for a timeline in the written scope with dependencies on processor and vault steps marked, the number of processors assumed and whether the plan includes a parallel run. Without those inputs, no duration is reliable.
What must our team provide before a migration starts?
Expect to provide current processor contracts and API documentation, sandbox and production credentials for each processor, a transaction and stored token inventory, cloud or data center access with clear ownership of networks and key management, identity provider details for Control Center access, existing PCI DSS scope documentation and named decision-makers who approve routing and cutover. Missing credentials or an incomplete inventory can delay the schedule, so ask each provider to list required inputs with owners and due dates in the scope.
Can our own team migrate to Hyperswitch without an implementation partner?
Yes, a capable team can, since Hyperswitch is open source under the Apache 2.0 license. The work is still substantial: Kubernetes deployment, PostgreSQL and Redis operation, connector configuration for each processor, routing design, vault and PCI DSS decisions, and a monthly release cadence with compatibility checks for the Control Center and SDKs. Assess honestly whether your team has run payment systems in production, can staff the build and parallel running, and can own upgrades after go-live. Some organizations use a partner for the build and keep operations in-house, and others reverse that split.
Can stored card tokens move to a self-hosted Hyperswitch vault?
Possibly, but the answer depends on conditions you must confirm. Three things decide it: whether your current provider allows export of card data or tokens in a usable form, which vault model you choose (the native Hyperswitch Vault, an external PCI vault such as VGS or Tokenex, or the SaaS Hyperswitch Vault), and whether the processors you move to accept the exported tokens or require new ones from customers. Get written confirmation from the current provider, the target vault provider and each processor before planning a token migration, and treat any customers who must re-enter card details as a separate workstream.
Does moving to self-hosted Hyperswitch change our PCI DSS scope?
It can, and the vault model is the main factor. Hyperswitch documents three self-hosted models. In the self-hosted, in-house PCI model, the Hyperswitch documentation states that the merchant is fully responsible for PCI DSS certification and data handling, so the card vault, its hosts, networks and key management are likely to fall within your assessment. An external PCI vault or the SaaS vault changes which systems are in scope and who carries responsibility for them. Confirm the boundary with your qualified security assessor before the design is fixed. DeployOpen prepares systems, controls and evidence for assessments, but independent assessors issue the reports and attestations.
How do parallel running and rollback work during the routing cutover?
Parallel running sends a defined share of payment traffic through Hyperswitch while the existing path handles the rest, using routing rules configured in Hyperswitch. Rollback means shifting that share back to the existing path, which only works if the old path still accepts the same tokens, webhooks and reconciliation feeds. Hyperswitch documents several routing strategies, including rule-based, volume-based, auth-rate and default fallback routing, and each change should be tested in a sandbox before it reaches live traffic. Ask providers to define the traffic steps, the rollback trigger and the owner of each decision in the written scope.
How DeployOpen runs a Hyperswitch migration
DeployOpen plans and builds the move from your current PSP integration or hosted orchestrator onto Hyperswitch in infrastructure you control, with connector setup, routing cutover and token migration scoped in writing before work starts. Engagements are fixed-scope, and ongoing support is available as a retainer.
How we scope
- Inventory the current PSP connectors, payment methods, webhooks and stored card tokens before agreeing a plan.
- Confirm which vault model you will use, since it determines PCI DSS responsibility and migration options.
- Agree in writing which connectors, routing strategies and parallel-running periods the migration covers.
- Confirm the Kubernetes environments, PostgreSQL and Redis setup, and the Superposition dependency for the target release.
How we build
- Deploy Hyperswitch from the Helm charts into your environments, with the card vault isolated from other services.
- Configure each connector and test it in a sandbox before any live payment traffic reaches it.
- Build routing rules and default fallback order, then test routing changes against controlled traffic before cutover.
- Run old and new payment paths in parallel with reconciliation checks so differences are found before the switch.
How we hand over
- Document the deployed architecture, connector configuration, routing rules and the cutover runbook for your team.
- Provide the token migration record, showing which stored cards moved, how they were verified and what remains on the old path.
- Walk your payments and security staff through monitoring, key handling and the rollback steps used during cutover.
- Record the compliance evidence your own assessor will need, while noting that DeployOpen does not issue audit reports.
How we support
- Offer ongoing support, upgrades and continuous testing as a retainer after go-live.
- Check each monthly Hyperswitch release against the Control Center and SDK compatibility matrix before upgrading.
- Plan database migrations and required dependency changes as part of each upgrade window.
- Confirm with your team which support tier, response expectations and maintenance windows apply before signing.
