How to migrate from Primer to Hyperswitch without losing stored cards
If your Primer renewal is coming up, or your data residency rules or policy now require card tokens to sit in infrastructure you control, the question is whether to self-host orchestration and how to move stored cards without breaking live payments. The migration rebuilds routing and checkout in Hyperswitch and moves stored cards through Primer's documented token export, but some token types, including wallet and network tokens, cannot be exported and must be re-tokenized with the customer. Start by inventorying which token types your Primer account holds, because that inventory determines how many customers will need to re-enter payment details.
Platform engineering usually leads this work, supported by payments engineers who know the processor integrations, security staff who own the PCI DSS scope, and finance or operations people who reconcile settlements during cutover. Expect the heaviest effort in rebuilding Primer's no-code workflows as Hyperswitch routing rules, in testing fallbacks against each processor, and in running the Router, Scheduler, PostgreSQL, Redis and card vault in your own cloud or data center. Confirm with Primer, through the token migration guide, the export format, the receiving-side requirements and the scheduling rules before you commit to a cutover date.
The main risk sits in the vault model you choose. Hyperswitch's self-hosted, in-house PCI model makes the merchant fully responsible for PCI DSS certification and data handling, so the receiving vault, its network segmentation, key management and access logs must be assessed by your qualified assessor before any card data arrives. If you prefer to keep card storage with a third party, the external PCI vault model changes that scope. Decide the model first, then plan the export, the re-tokenization campaign for customers whose wallet or network tokens cannot move, and a parallel-run period to compare authorization rates against Primer.
Which Primer capabilities map cleanly to Hyperswitch
This table maps each main Primer capability to its closest Hyperswitch component and marks it as clean, needs rework or gap. Read the status column first, then the notes, since the rework items drive most of the migration effort. The main takeaway is that routing and vaulting have close equivalents, while no-code workflows, wallet and network tokens, and Control Center sign-in need explicit planning.
| Primer capability | Hyperswitch equivalent | Status | What to confirm or plan |
|---|---|---|---|
| Centralized card vault | Hyperswitch card vault (locker), a separate Rust service | Needs rework | Confirm the vault deployment model you choose; in the in-house PCI model you carry PCI DSS responsibility for certification and data handling. |
| No-code routing workflows | Routing configuration in the Hyperswitch core router and intelligent routing docs | Needs rework | Every Primer no-code workflow must be rebuilt as Hyperswitch routing configuration and retested against the same transaction samples. |
| Processor fallbacks | Retries and routing rules in the Rust core app server | Clean | Map each fallback order to a routing rule and confirm the connectors you use are among the 100+ supported processors. |
| Checkout components | Client SDKs for web, Android, iOS, React Native and Flutter | Needs rework | Checkout screens and payment method display must be rebuilt on the SDKs; test each device and wallet flow. |
| Wallet and network tokens | Not confirmed in supplied material for this migration path | Gap | Confirm wallet and network token coverage with Hyperswitch and in a pilot before committing, since Primer does not export these tokens. |
| Observability and reporting | Core router observability and modules for reconciliation and cost observability | Clean | Confirm dashboards and export formats meet your finance and audit reporting needs. |
| Merchant dashboard and admin access | Hyperswitch Control Center | Needs rework | Control Center SSO supports OpenID Connect only, with no SAML, no SCIM and no JIT provisioning. Users must be invited first and roles are managed in Hyperswitch, not mapped from your identity provider. |
What moves from Primer, and what has to be re-created
Some Primer data can be exported to a new vault, and some cannot. The cards below separate stored card tokens, wallet and network tokens, and the configuration you rebuild in Hyperswitch, including connectors, routing, webhooks, reconciliation and Control Center access.
Stored card tokens and SFTP export
Primer's documented token migration delivers stored payment credentials over SFTP. Before you request the export, ask Primer support for the exact field list, file format and delivery schedule, because the file is only useful if the receiving vault accepts every field in it. Confirm the receiving vault is ready before the file arrives, since it carries card credentials that must land in a PCI DSS compliant environment. Hyperswitch documents three vault models, and under the in-house model your team takes full responsibility for PCI DSS certification and data handling.
Wallet and network tokens
Wallet tokens, such as those tied to Apple Pay or Google Pay, and network tokens cannot be exported from Primer. Treat every customer whose payment method depends on one of these tokens as a customer you must re-acquire. Plan a customer re-entry path before cutover, and count affected customers from your own Primer data so the workload is known in advance. Where a processor offers an update or account-level credential flow, confirm its availability for your accounts with that processor. Ask Primer to state in writing which token types fall outside the export.
Processor connectors and credentials
Hyperswitch connects to more than 100 payment processors, including Stripe, Adyen, PayPal, Worldpay and Checkout.com, plus wallets such as Apple Pay and Google Pay. Each Primer processor connection must be recreated as a Hyperswitch connector, and its credentials are entered again in the new system. Map every active merchant account to a connector, and confirm each processor's supported payment methods and regions. Test the connectors in the hosted sandbox or a local Docker setup before live traffic moves.
Routing and checkout workflows
Primer's no-code workflows hold routing, fallback and retry decisions that must be expressed again in Hyperswitch's routing configuration. Export the logic of each Primer workflow in writing, including conditions, fallback order and retry limits, before you start the rebuild. Rebuild each workflow branch and test it separately with sample transactions for each processor and payment method. Checkout components also need to be swapped to Hyperswitch client SDKs, so review every checkout surface against the SDK platforms you support.
Webhooks and reconciliation
Each processor webhook currently points at Primer. Repoint it to your Hyperswitch endpoint during cutover, and keep the old endpoint active until in-flight payments settle. Reconcile both systems across the overlap period, matching payment identifiers, refunds and disputes against processor settlement files. Keep Primer transaction exports as the audit record for the migration window. Hyperswitch documents reconciliation as one of its modules, so confirm that its output format matches the fields your finance ledger expects before go-live.
Control Center access and SSO
The Hyperswitch Control Center replaces the Primer dashboard for configuration and daily operations. Its single sign-on supports OpenID Connect only, with no SAML, no just-in-time provisioning and no SCIM. Roles are managed inside Hyperswitch, so they must be assigned there after sign-in. Users must be invited before they can sign in, so build invitation and role assignment into your onboarding runbook. Confirm that your identity provider supports OpenID Connect before you plan the rollout.
The migration sequence from inventory to decommission
This sequence moves Primer's routing, checkout and stored credentials to a self-hosted Hyperswitch stack in controlled stages, so each phase has a known output and a rollback point. Traffic only shifts after the inventory, pilot and parallel run confirm that payments behave the same way. Decommission happens last, once export and retention obligations are satisfied.
Inventory processors, token types and workflows
Your payments or engineering lead lists every processor and acquirer connected through Primer, every Primer workflow that routes, retries or falls back between them, every checkout flow in use, and every token type held in the vault. Include wallet tokens and network tokens, because these are the categories you must confirm with Primer before planning any export. The output is a signed-off inventory that maps each workflow to its Hyperswitch equivalent or to a documented gap. The step is done when the payments owner and the security owner both accept it in writing.
Confirm export scope and receiving vault model
Decide which vault model you will run in Hyperswitch: the native in-house PCI vault, an external PCI vault provider, or the SaaS Hyperswitch Vault. This choice determines who holds PCI DSS responsibility and how stored cards are received. Ask Primer, through its documented token migration process, which card fields can leave and which wallet and network tokens cannot, then plan re-tokenization for the latter. The output is a written decision on the vault model and a list of credentials that will need customer re-entry or re-tokenization.
Pilot Hyperswitch in a self-hosted environment
Your platform engineers start Hyperswitch locally with the Docker-based setup, then deploy the Helm charts on Kubernetes in a non-production cluster, or use the guide for AWS, GCP or Azure if that is your target. Connect one or two processors from the inventory, rebuild one representative routing rule, and run test transactions through the sandbox and your own test merchant accounts. Confirm the PostgreSQL and Redis dependencies, backups and monitoring are in place. The output is a working pilot with recorded test results, and the step is done when a payment flows end to end and a refund and a failed payment both behave as expected.
Run a parallel period with Primer still live
Route a small, defined share of new traffic to Hyperswitch while Primer continues to process the rest. Compare authorization rates, decline codes, retry behavior, webhook delivery and reconciliation totals between the two paths every business day. Keep Primer as the fallback for any transaction that Hyperswitch cannot complete. The output is a reconciliation report showing where the two stacks differ and a decision log for each difference. Do not expand traffic until the finance team confirms that settlement files match for the sampled period.
Cut over checkout and routing with a rollback path
Move checkout components to the Hyperswitch client SDKs and switch routing rules in stages, starting with the lowest-risk payment methods. Keep the Primer configuration intact and document the exact steps to revert routing and checkout within your change window. Your operations team owns the switch, and the payments owner approves each stage. The output is a cutover record listing each routing change, the time of each change and the tested rollback procedure. The step is done when all new traffic flows through Hyperswitch for a period agreed in advance and no rollback has been triggered.
Import stored credentials and close the vault gap
Once the receiving vault is ready and the export has been scheduled with Primer, import the approved card records into the Hyperswitch vault and verify a sample of tokens with test charges before going live with them. Ask the receiving provider and Primer to confirm the file format, encryption method and expected delivery window in writing. Re-collect wallet and network-tokenized credentials that cannot move, and track each customer's status. The output is a credential reconciliation showing migrated, re-collected and unrecoverable records, with the counts signed off by the payments and compliance owners.
Decommission Primer after retention obligations are met
Before closing the Primer account, confirm that every record your regulators, card schemes and contracts require you to keep has been exported or archived in your own storage, and that transaction history is available for disputes and audits. Ask Primer to confirm in writing how it deletes card data it holds after your export is complete. Revoke API keys, remove webhook endpoints and update the vendor register. The output is a decommission checklist with evidence of deletion and archival, approved by the compliance lead. Your compliance team, not DeployOpen, decides whether these records satisfy your obligations.
What drives the cost and duration of this migration
This table lists the factors that change the effort of moving from Primer to Hyperswitch, and how each one moves cost or time. Read it as a checklist for scoping: each row names what to count in your Primer account and what to decide before a quote is requested. The main takeaway is that stored card volume, token types and the PCI DSS scope decision matter more to the plan than the number of screens in checkout.
| Driver | Why it changes cost or effort | How to keep it down |
|---|---|---|
| Processors and connectors to rebuild | Each processor connection needs its own configuration, credential handling, routing rules and test cases in Hyperswitch, which supports more than 100 processors according to its repository. | Inventory only live processors, retire unused connections before migration, and rebuild in priority order. |
| Primer workflows and routing rules | No-code workflows in Primer must be translated into Hyperswitch routing configuration, and each conditional branch needs a test case to confirm the same outcome. | Export and document every workflow, remove dormant ones, and map each to a named Hyperswitch routing rule before build starts. |
| Checkout variants and client SDKs | Each checkout variant may need a rebuilt front end using Hyperswitch client SDKs for web, Android, iOS, React Native or Flutter, and each needs regression testing. | Consolidate variants where possible and limit the first release to the checkout paths that carry most volume. |
| Stored cards and token types | Primer's token export covers card data that can leave its vault. Wallet and network tokens that cannot be exported must be re-tokenized through customer re-entry or processor flows, which adds customer-facing work. | Count cards by token type early, confirm with Primer which types cannot be exported, and plan re-tokenization by customer segment. |
| PCI DSS scope decision | An in-house Hyperswitch vault makes the merchant fully responsible for PCI DSS certification and data handling. An external PCI vault such as VGS or Tokenex, or the SaaS Hyperswitch Vault, changes which controls and evidence you own. | Decide the vault model before design. Ask the QSA or assessor which evidence each model requires, then size the scope to that choice. |
| SSO and access model | The Control Center supports OpenID Connect only, with no SAML, JIT or SCIM provisioning, and roles are managed inside Hyperswitch. Each identity integration and access review adds configuration and testing work. | Confirm your identity provider supports OpenID Connect, define roles in advance, and document the manual invitation process for auditors. |
| Parallel running volume | Running Primer and Hyperswitch side by side for reconciliation and fallback doubles some operational work for the length of the overlap, and volume determines how much testing that needs. | Agree a cutover window and reconciliation criteria in advance, and limit parallel traffic to the processors being moved first. |
| Recurring operations | Hosting Router, Scheduler, PostgreSQL, Redis and the card vault, plus upgrades, on-call, security testing and PCI evidence, continue after cutover and are owned by your team or a retainer. | Ask for a run cost estimate with each quote, covering upgrades, monitoring and testing, and define who holds on-call duties. |
What usually goes wrong and how to prevent it
Most failed Primer exits trace back to a few decisions made early: what the export really contains, when it is requested, and who owns card security afterward. The cards below each name one risk and the check that prevents it, so the cutover plan is built around them rather than discovered during it.
Assuming every stored credential exports
Wallet credentials and network tokens are the items most often assumed to move with the card data, and they are the ones Primer's token export does not cover. Build an inventory of stored payment methods by type before scoping the migration. Anything outside the export becomes a re-tokenization task, which needs the customer to re-authorize, so count those customers and plan the outreach and checkout prompts for them early.
Late export request delays cutover
Primer's export is delivered through a support request, and the receiving provider has to be ready to accept an encrypted batch over SFTP. If the request starts late, the cutover date moves with it. Send the request as soon as the receiving Hyperswitch vault and SFTP endpoint are provisioned, and confirm with Primer in writing the delivery window, file format and key exchange. Ask whether a second delta export is available for cards saved after the first batch.
Processor connector gaps
Hyperswitch lists more than 100 processors, but the connector you use in production may be missing, partially supported, or configured differently from Primer's workflow. Map every processor and payment method from your Primer workflows to a Hyperswitch connector, then test each one in a sandbox with real merchant credentials. Confirm which features (refunds, partial captures, 3DS flows, network tokens) each connector supports before routing traffic to it.
In-house PCI responsibility without staffing
Choosing the self-hosted, in-house PCI model makes your organization fully responsible for PCI DSS certification and card data handling. Teams often adopt the card vault and then discover nobody owns key management, segmentation, logging or the annual assessment. Before the export arrives, name owners for each area, confirm the scope with a qualified assessor, and decide whether an external PCI vault provider is the better fit for your staffing.
SSO expectations beyond OpenID Connect
The Hyperswitch Control Center supports single sign-on through OpenID Connect only, with no SAML, no JIT or SCIM provisioning, and roles managed inside Hyperswitch rather than mapped from your identity provider. Teams that expect SAML federation or automated joiner and leaver flows will face manual account work after go-live. Confirm your identity provider can issue OpenID Connect tokens, and document an invitation and offboarding procedure for Control Center users.
Skipping parallel-run reconciliation
Running Primer and Hyperswitch side by side for a period is the only way to see whether authorizations, captures, refunds and fallbacks match across both systems. Without it, mismatched settlement files surface weeks later in finance. Define the reconciliation keys, compare daily totals per processor, and agree with finance who signs off each day before any traffic moves fully to Hyperswitch.
How the migration changes by starting point
A merchant with one or two processors and no vaulted cards has the simplest path. There is no token export to plan, so the work centers on rebuilding routing rules and replacing the checkout front end. Because nothing has to move between vaults, the cutover can be staged by payment method or by traffic share, and the old setup can stay live while the new one is tested. The main risks are routing gaps and checkout behavior that differs from what customers expect.
- Routing rebuilt from scratch: Recreate each Primer workflow as Hyperswitch routing configuration and test the fallback order with sandbox transactions.
- Checkout swap: Replace the Primer checkout component with a Hyperswitch client SDK for the platforms you actually use, such as web or mobile.
- Processor onboarding: Connect each processor directly and confirm credentials and settlement settings before any live traffic moves.
- Staged traffic shift: Move a small share of payments first, then increase it once authorization rates and error logs look normal.
- Operations ownership: Assign who will run Hyperswitch upgrades, monitoring and incident response, since a small team often has no dedicated platform owner.
Before starting, confirm with your team which processors and payment methods must work on day one, and whether any Primer features you use have no direct Hyperswitch equivalent.
A platform with a large stored-card base and wallet tokens faces the hardest data work. Token export from Primer runs through a documented process over SFTP, and some token types, including wallet and network tokens, cannot be exported. Those customers must be re-tokenized, usually by asking them to re-enter payment details or through a network token service, which depends on the receiving provider and on customer consent. Sequence therefore starts with an inventory of what can and cannot leave Primer, followed by the export and a parallel period in which both vaults hold data.
- Token inventory first: Split stored credentials into exportable card tokens and wallet or network tokens that will need re-tokenization.
- Receiving vault set up early: Confirm that the Hyperswitch vault or an external PCI vault can accept the export format and receive encrypted files.
- Re-tokenization campaign: Plan how customers with non-exportable tokens will re-authorize, and how subscriptions and saved payment methods will behave in the gap.
- Parallel running: Keep both vaults active until every exported token has been tested with a live or test charge.
- Customer communication: Prepare notices for customers who must re-enter card details, since failed renewals are the most likely support load.
Ask Primer's support team which token types your account holds and what the export timeline looks like before you commit to a cutover date.
A regulated operator that must keep card data inside its own infrastructure changes the choice of vault model before any routing work begins. Hyperswitch documents three vault models: self-hosted with the native in-house vault, self-hosted orchestration with an external PCI vault provider, and self-hosted orchestration with the SaaS Hyperswitch Vault. Only the first keeps all card data within your own environment, and in that model the Hyperswitch documentation states that the merchant is fully responsible for PCI DSS certification and data handling. The sequence therefore starts with a scope decision and a compliance readiness review, not with checkout.
- Vault model decision: Choose between the in-house vault, an external PCI vault and the SaaS vault based on where your assessor will draw the cardholder data boundary.
- Compliance scope mapping: Document which systems store, process or transmit card data, including the encryption service and the card vault host.
- Identity controls: The Control Center supports OpenID Connect single sign-on only, with no SAML and no SCIM, and roles are managed in Hyperswitch, so plan user administration accordingly.
- Independent testing: Commission security testing of the deployed environment before live cardholder data is migrated.
- Evidence collection: Prepare the controls and records your independent assessor will request, understanding that DeployOpen prepares evidence but does not issue certifications.
Confirm with your qualified security assessor which vault model they will accept before any token export is scheduled.
Questions teams ask before moving off Primer
What does a move from Primer to Hyperswitch cost, and what drives it?
The cost is a set of separate components, and no single figure covers them. Expect one-time work for routing rebuild, checkout swap, testing and token handling, plus recurring costs for hosting, PostgreSQL and Redis operations, on-call staff and the PCI DSS work that comes with holding card data yourself. The main drivers are the number of processors and payment methods in use, how many Primer workflows must be rebuilt, whether stored cards can be exported, and how much re-tokenization the wallet and network tokens require. Ask any provider for a quote built from a written scope that lists each component and states who performs it. Compare that with your current Primer invoices and your internal staffing cost, not with the licence line alone.
How long does a Primer to Hyperswitch migration take?
The timeline depends most on the token export schedule, followed by how many routing workflows and checkout flows you rebuild. Primer's documented token migration path runs through a support request and a receiving provider that must be ready before delivery is scheduled, so the export is often the longest external dependency. Confirm the export lead time with Primer in writing before you set a cutover date. Parallel running of both platforms, processor onboarding and penetration testing of the new card environment usually add time. Build the plan around the export date and your processor approval windows, and treat any duration proposed without that inventory as an estimate to challenge.
What must our team supply before a migration starts?
Your team needs to supply a complete inventory before any design work can be scoped. The inventory should list every Primer workflow, its conditions and fallbacks, each processor and its credentials, each payment method, and every stored token type with its volume. You will also need named owners for PCI DSS evidence, key management, operations on-call and finance reconciliation. Processor credentials and merchant account changes must be requested from each acquirer, and those requests often run on their own schedule. Ask any implementation partner to list these inputs in the written scope so gaps show up before the work starts.
Can an internal team migrate from Primer alone?
An internal team can do it alone if it already runs payment infrastructure, holds PCI DSS ownership and has engineers who know the Hyperswitch architecture. The architecture involves Router and Scheduler services, PostgreSQL with replicas, Redis, a separate card vault and the Control Center, all of which need operational runbooks. Teams with limited payments or security staff often bring in an outside party for specific pieces, such as the vault deployment model, security testing or documentation for an assessor. Decide this by mapping each piece of the inventory to a named owner. Any gap you cannot fill internally is a scope item to buy, not a reason to skip the work.
Can wallet and network tokens move from Primer to Hyperswitch?
Not every token type can move, so you should confirm this before planning. Primer's token export covers stored payment credentials that you can export, but wallet and network tokens are generally tied to the issuer, wallet provider or original processor and may not be exportable. Expect the customers attached to those tokens to need a new authorization or a new token through the new platform. Ask Primer for a written list of which token types its export includes and which it excludes, and ask Hyperswitch how it handles network tokenization for your processors. Plan for customer communication, a fallback path for declined transactions and a count of affected customers so the re-tokenization effort is sized from real data.
Does Hyperswitch replace Primer's no-code workflows?
Hyperswitch covers routing and retry logic through configuration and its Control Center, but it does not match Primer's no-code workflow builder one for one. Its documented intelligent routing and orchestration modules cover many of the same decisions, so the practical question is which of your Primer workflows are configuration and which need code. Workflows that depend on custom logic will need to be rewritten and tested against each processor. Confirm the specific capabilities your workflows use against the Hyperswitch docs, and check the Control Center's authentication limits, since it supports single sign-on through OpenID Connect only, not SAML, and needs users invited manually.
Who is responsible for PCI DSS once we self-host?
Once you self-host with the in-house vault model, your organization carries PCI DSS responsibility for the card data environment. Hyperswitch's documentation states that the merchant is fully responsible for PCI DSS certification and data handling in that model. Other models place part of that scope with an external PCI vault provider such as VGS or Tokenex, or with the SaaS Hyperswitch Vault. Choose the model before the design phase, because it changes your assessment scope. DeployOpen prepares systems, controls and evidence for compliance assessments, but independent assessors issue the attestation.
What a fixed-scope Hyperswitch migration covers
DeployOpen agrees the scope of a Hyperswitch migration in writing before any work starts. The written scope sets the deliverables for each phase: an inventory of what Primer does for you today, a pilot, a parallel run, cutover and decommissioning. The inventory is where most of the detail is settled. It should list every Primer workflow, each routing rule and retry condition, every checkout component in use, every webhook and reporting feed, and every token type held in the account. For each item, the inventory records whether it has a Hyperswitch equivalent, must be rebuilt, or needs a decision from your team. Ask for this inventory as a named deliverable with an owner on both sides, because the wallet and network tokens that cannot be exported will show up here and drive the re-tokenization plan.
The pilot and parallel run cover the Hyperswitch side: self-hosting the Router, Scheduler, PostgreSQL, Redis and card vault on Kubernetes with Helm charts, hardening those components, and wiring the Control Center to your identity provider. Confirm early that OpenID Connect is the only supported single sign-on method for the Control Center, since SAML is not supported and roles are managed inside Hyperswitch. The scope should also name the security testing of the APIs, the checkout and the vault, plus the backup and restore tests for the database. DeployOpen prepares systems, controls and evidence for compliance readiness, but DeployOpen does not issue PCI DSS attestations or certifications. An independent assessor must examine your environment, and the scope should say which assessor you will use and when they will engage, so the evidence DeployOpen produces matches what that assessor needs.
How DeployOpen runs the migration
DeployOpen plans, implements, customizes, integrates, hardens and documents self-hosted open-source platforms inside your own cloud accounts, data centers or air-gapped networks. For this migration, we start with a written scope that separates the orchestration rebuild from any card data movement, so each part can be reviewed before work begins.
How we scope
- Engagements are fixed-scope, with scope, deliverables and timelines agreed in writing before work starts
- Inventory of Primer routing workflows, processor connections, checkout components and stored token types
- Confirmation of which saved cards, wallet tokens and network tokens can be exported and which must be re-collected
How we build
- Deploy Hyperswitch in your environment using Helm on Kubernetes, with PostgreSQL and Redis configured for your availability needs
- Rebuild routing rules, retries and processor connections in Hyperswitch, then test each flow in a non-production environment
- Choose and document the vault deployment model, including who holds PCI DSS responsibility for card data handling
How we hand over
- Written runbooks covering deployment, configuration, routing changes, key management and the Control Center
- Cutover plan with rollback steps, reconciliation checks and a record of every token migrated or re-collected
- Documentation of evidence and controls prepared for your own assessor, which DeployOpen does not certify or audit
How we support
- Ongoing support, upgrades and continuous testing are available as a retainer after handover
- Security testing of the checkout, APIs and vault integration can be scoped separately before go-live
- Ask your DeployOpen contact to confirm response expectations and upgrade handling in the written scope before signing
