Migrate from Spreedly to Hyperswitch

Migrate from Spreedly to Hyperswitch: what the move involves

Moving from Spreedly to self-hosted Hyperswitch is a PCI-scoped card data migration plus gateway re-pointing, and it is usually led by payments engineering with security and compliance signing off on scope. Payments engineering owns the Hyperswitch deployment, the merchant connector configuration and the traffic cutover. Security owns the decisions about where the card vault runs, how the encrypted export is received and stored, and which PCI DSS requirements apply to the new environment. Compliance owns the evidence trail, including who approved the export, where the decryption key is held and when the old copies were deleted. Finance and procurement typically join to compare the Spreedly subscription against the hosting and assessment costs that replace it.

The short answer on effort and risk is that the hardest part is rarely the code. The largest risks are receiving card data in a format and location your PCI DSS assessor has approved, and keeping a clean record of every copy. Spreedly documents that exports to a PCI compliant third party can be made as a single card export or an encrypted batch file export, that batch exports are generally processed within 2 weeks, and that each merchant receives one free export per receiving service. Plan the export request early and do not assume a second export will be free if the first one needs correction. Confirm the receiving endpoint, file format and decryption process with Spreedly before any card data leaves its vault, and confirm with your assessor which of the three Hyperswitch vault models you will run.

Which Spreedly capabilities map cleanly to Hyperswitch

This table maps each Spreedly capability to its closest Hyperswitch equivalent and marks it as clean, needs rework or gap. Read the status column first, then the notes, since credential portability and network tokenization depend on each processor and must be confirmed with that provider before you commit to a cutover plan.

Spreedly capability	Hyperswitch equivalent	Status and what to confirm
Hosted card vault	Hyperswitch card vault (locker), a separate Rust service built for PCI DSS requirements	Needs rework. You hold the vault, so PCI DSS scope moves to you unless you use an external vault provider.
Encrypted batch export of vaulted payment methods	Import into the Hyperswitch vault from the receiving party's export file	Needs rework. Confirm with Spreedly and the receiving PCI compliant party how the file is encrypted, formatted and delivered.
Gateway connections	Connectors to more than 100 payment processors	Needs rework. Each connector must be configured and tested for your account, currency and payment methods.
Processor-specific credential behavior	Per-connector credential handling and token reuse	Gap until confirmed. Some processors may not accept re-used credentials from another vault; confirm with each provider.
Network tokenization	Network token handling depends on the connector and vault model	Gap until confirmed. Confirm which card networks and processors support network tokens for your migrated cards.
Routing and retries	Intelligent routing and retry logic in the Rust core app server	Clean for common flows. Replicate your current rules and test fallback paths before retiring Spreedly routes.
Dashboard and transaction reporting	Control Center merchant dashboard	Needs rework. Rebuild reports and check that roles and SSO fit your identity setup, since SSO is OpenID Connect only.
Client libraries and SDKs	Client SDKs for web, Android, iOS, React Native and Flutter	Needs rework. Your front end must be updated to call Hyperswitch rather than Spreedly endpoints.

What moves out of Spreedly and what you rebuild

Vaulted cards and bank accounts can leave Spreedly through two documented routes: a single card export or an encrypted batch file export sent to a PCI compliant receiver. Spreedly's export documentation states that batch exports are generally processed within 2 weeks and that each merchant gets one free export per receiving service, so a second destination, a failed attempt or a re-run for a different environment may carry a fee. Ask Spreedly to confirm the current fee schedule in writing before you plan the cutover. The receiver must be able to hold raw card data under PCI DSS, which in a Hyperswitch deployment means either the native Hyperswitch card vault run in your own PCI scope or an external PCI vault that Hyperswitch orchestrates. The exported file is not usable card data on its own. Until a compliant receiver decrypts and stores it, the tokens are only references, so do not start redacting Spreedly tokens in your applications until the import is verified.

Almost everything around the vault must be rebuilt. Webhooks, reporting exports, reconciliation feeds and any dashboards that read Spreedly transaction data have to be re-pointed at Hyperswitch events and the Control Center, and each downstream consumer should be inventoried before the cutover. For access, the Control Center supports single sign-on through OpenID Connect only. SAML is not supported, there is no just-in-time or SCIM provisioning, and roles are managed inside Hyperswitch rather than mapped from your identity provider. Users must be invited first, so plan an access review that lists who needs operator, reporting or administrator rights and assign them manually. Confirm the current SSO and role behavior against the Control Center SSO guide for the release you deploy, since these controls change between versions.

The migration sequence from inventory to decommission

This sequence moves card and payment method data out of Spreedly and into a Hyperswitch vault you control, while keeping live payments running until each gateway has been verified. Each step ends with a check that tells you whether the next step can start.

Inventory gateways, payment methods and dependencies
Start by listing every gateway, receiver and stored payment method connected to your Spreedly account, and every internal system that calls Spreedly's API. Record which gateways carry live volume, which are fallbacks, and which payment methods (cards, bank accounts, network tokens) are vaulted. Confirm with your compliance lead which PCI DSS scope statement you will rely on for the new environment. The output is a signed inventory that maps each gateway credential and each consuming service to a planned Hyperswitch connector, so nothing is left unassigned when traffic moves.
Pilot in the Hyperswitch sandbox or Docker
Before you touch production, have your engineers run Hyperswitch in its hosted sandbox or locally with the Docker setup. Configure one test merchant, connect a sandbox credential for each gateway on your list, and run authorization, capture, refund and void flows through the same client SDK your application uses. Confirm that the webhook handling, error mapping and retry behavior match what your order management system expects. The pilot is complete when every flow passes for every gateway in the inventory and the team has written down the differences from Spreedly's responses.
Deploy Hyperswitch on Kubernetes with Helm
Deploy the production environment in your own cloud account or data center using the Helm charts for Kubernetes, with the Router, Scheduler, PostgreSQL with a replica, Redis and the card vault configured as described in the architecture documentation. Put the key management and encryption components under your existing key custody process, and restrict network paths so only your payment services can reach the vault. Your platform team should also confirm backup and restore for the database and the vault. The step is complete when a health check passes on every service and a restore test has been run against a copy of the database, with results recorded.
Request and ingest the encrypted batch export
Ask Spreedly for an encrypted batch export of your vaulted payment methods, sent to a receiver that meets your PCI DSS obligations for the data it holds. Spreedly documents this path as one free export per merchant per receiving service, with processing generally completed within two weeks. Ingest the file into the Hyperswitch card vault in a restricted environment, verify record counts against the inventory from step one, and test a sample of tokens by making a sandbox charge against each gateway. Keep the decryption keys and the import logs under access control. The step is complete when counts reconcile and the sample charges succeed, and any failed records are listed with a reason.
Run a parallel period with phased traffic
Route a small share of live traffic for one gateway through Hyperswitch while the rest continues through Spreedly, then widen the share in steps you defined in advance. Compare authorization rates, decline codes, latency and reconciliation totals between the two paths for the same gateway and time window. Use the intelligent routing configuration only after the basic path is stable, so you can tell routing effects apart from migration defects. The step is complete for each gateway when the new path meets the success thresholds your finance and operations teams agreed in the inventory, and the reconciliation reports match to the cent.
Cut over all traffic to Hyperswitch
Move the remaining payment calls, webhook endpoints and merchant configuration to Hyperswitch in a planned change window, with a documented rollback that re-points calls to Spreedly. Confirm that any stored payment methods used for recurring or card-on-file charges are now tokenized in the Hyperswitch vault. Monitor authorization, webhook delivery and settlement files closely for the first full settlement cycle. The cutover is complete when no production calls reach Spreedly for the agreed period and settlement totals reconcile across all gateways.
Decommission Spreedly and redact tokens
After the settlement cycle closes and the rollback window ends, disable Spreedly's API keys and gateway receivers, then request the deletion or redaction of stored payment methods in your Spreedly account as your contract and data retention policy require. Confirm in writing with Spreedly what has been removed and what is retained, and keep the export logs, reconciliation evidence and change records for your compliance file. Record the final state in your inventory. The step is complete when Spreedly no longer receives traffic or holds usable credentials, and the evidence package is filed with your compliance lead.

How the Hyperswitch vault and gateways fit together during the move

Before you move any cards, map where each piece of the Hyperswitch stack sits. The core app server has two services: the Router, which handles payment API calls, routing, retries and vaulting, and the Scheduler, which runs background work in producer and consumer roles. Both rely on PostgreSQL, deployed with a master and replica, and on Redis for caching and the scheduler queue. Card data does not live in that core database. It is held by the separate card vault (locker) service, which the architecture documentation describes as built for PCI DSS requirements, and which is maintained in its own repository. Your migration plan should name each of these services, its database and its network path, because the vault's network boundary determines which systems fall into card data scope.

The vault decision comes before gateway re-pointing. Hyperswitch documents three models: self-hosted orchestration with the native Hyperswitch Vault (in-house PCI), self-hosted orchestration with an external PCI vault provider such as VGS or Tokenex, and self-hosted orchestration with the SaaS Hyperswitch Vault. In the in-house model, the merchant is fully responsible for PCI DSS certification and data handling, so the assessment covers the Router, the vault, their hosts and the networks between them. An external PCI vault changes that scope, since card capture and storage move to the provider, but it adds a contract, an integration and a dependency on that provider's assessment evidence. Confirm with your QSA and each vendor which evidence they will supply before you choose, and ask whether a given gateway can accept tokens issued by your chosen vault.

Once the vault model is fixed, connect each processor as a Hyperswitch connector and test it in a non-production environment before any live traffic moves. Spreedly's encrypted batch export delivers vaulted payment methods to your receiving service, so confirm that the Hyperswitch vault or the external vault can ingest that format and that each target gateway accepts the imported credentials. Keep Spreedly active for its existing gateways until the Hyperswitch routes have passed reconciliation, since rolling back is far harder once cards and routing rules have both changed. Document which processor handles which share of traffic at each phase, and record who approves each step.

What usually goes wrong in a Spreedly to Hyperswitch move

Most problems in this move come from timing, receiving infrastructure and scope rather than from the software itself. The six risks below follow the order of a typical migration: requesting the export, receiving card data, re-importing tokens, setting up access, re-issuing credentials and deciding who is in PCI DSS scope.

Export requests delayed by processing

Spreedly documents that encrypted batch exports are generally processed within 2 weeks, so a late request can hold up cutover for the whole project. Send the export request early, before gateway and environment work begins, and confirm with Spreedly what information it needs to start. Also check whether your receiving service qualifies for the one free export per merchant allowed per receiving service, because a failed or repeated request may cost you that free export.

Receiver not meeting PCI requirements

Spreedly exports vaulted cards only to a third party that can receive them under PCI DSS. Before requesting the export, confirm in writing that the Hyperswitch vault environment, its hosts, key management and access controls are in scope for your assessment and documented. A receiver built without this groundwork can delay the export or leave card data in an unassessed system, so ask your QSA to review the design before data moves.

Tokens that do not re-import cleanly

Exported batch files have to match the format and field mapping that the Hyperswitch vault expects, including card expiry, network tokens and any bank account records. Run a test import with a small, representative set of records and reconcile counts, expiry dates and token references against the source. Agree in advance how records that fail validation will be logged, retried or excluded from cutover.

SSO and role gaps in Control Center

The Hyperswitch Control Center supports single sign-on through OpenID Connect only, with no SAML, no just-in-time or SCIM provisioning, and roles managed inside Hyperswitch rather than mapped from your identity provider. Map each Spreedly user and role to a Hyperswitch role before go-live, plan manual invitations and removals as part of joiner and leaver steps, and document who owns that list after the move.

Gateway credentials not re-issued

Vaulted cards are only useful if the gateways you route to accept the requests, and each processor credential must be configured in Hyperswitch under your own account. Do not assume that credentials in Spreedly can be copied or reused. Inventory every connector, request new API keys from each processor, test each one in a sandbox, and keep traffic on the Spreedly path until each connector has passed its tests.

PCI scope underestimated in-house

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. Teams often budget for the orchestration software and forget the hosting, logging, backup, staff access and assessment work that follows. Decide early between in-house and an external PCI vault provider, and ask your assessor to confirm the resulting scope before you commit to a plan.

What drives the cost and duration of the migration

This table lists the factors that move the cost and calendar time of moving from Spreedly to self-hosted Hyperswitch, with the reason each one matters and how to keep it under control. Read it before requesting a quote, because the same scope written two ways can produce very different effort.

Driver	Why it changes cost or time	How to keep it down
Number of gateways and payment methods	Each connected processor needs its own credentials, routing rules, webhook handling and reconciliation checks, and card and bank account types add test cases.	Inventory live gateways and methods first, retire unused ones, and phase the highest-volume connectors before the long tail.
Network tokens in use	If Spreedly holds network tokens, they need a documented path into the new vault and a check that each processor accepts them, which adds design and test work.	Confirm with your processors which credentials are network tokens and whether they can be re-issued, and scope them as a separate workstream.
Export receiver choice	Spreedly's encrypted batch export goes to a PCI compliant receiver you name, and the receiver choice decides whether you build an in-house vault or integrate an external one.	Decide the receiver before the export request, since a Hyperswitch vault or an external PCI vault changes the receiver setup and the assessment scope.
Export timing and volume	Spreedly documents that batch exports are generally processed within 2 weeks, and the number of vaulted payment methods drives import validation and reconciliation effort.	Request the export early, ask Spreedly to confirm current processing times, and sample-check a subset of imported tokens before full cutover.
PCI DSS assessment scope	In the self-hosted, in-house PCI model, Hyperswitch documents that the merchant is fully responsible for PCI DSS certification and data handling, so assessment and remediation effort is the largest variable.	Pair self-hosted orchestration with an external PCI vault to narrow scope, and ask your qualified assessor to confirm the boundary early. DeployOpen prepares evidence but does not issue assessments.
Penetration testing scope	Testing must cover the card data environment, the vault, the orchestration APIs and the admin console, and each added environment or integration extends the test plan.	Define the in-scope systems in writing before testing starts and retest only changed components where the assessor agrees.
SSO requirements	Hyperswitch Control Center supports OpenID Connect only, with no SAML, no JIT or SCIM provisioning, and roles managed in Hyperswitch, so an identity provider that requires SAML or automated provisioning needs extra integration or manual user administration.	Confirm your identity provider supports OpenID Connect and decide early how users and roles will be managed, then document the access review process.
Parallel-run length	Running Spreedly and Hyperswitch side by side keeps two sets of fees, two reconciliation paths and two sets of operational runbooks until traffic is fully moved.	Set exit criteria for each gateway in advance, such as matching reconciliation and successful test transactions, so phased traffic moves on evidence rather than on a fixed calendar.

How the migration differs by starting point

A merchant with one connected gateway and a modest set of vaulted cards usually has the smallest migration. Most of the work is re-pointing one processor integration and moving a limited token set, so the phasing can be short and the number of moving parts is low. The main risk is treating the move as a simple switch when the vault itself becomes a new system you must secure.

Export scope: Confirm the number of vaulted payment methods and which receiving service Spreedly will export to, since the export is documented as one free export per merchant per receiving service.
Vault decision early: Choose between the in-house Hyperswitch Vault and an external PCI vault before the export request, because the receiving endpoint depends on it.
Single cutover window: Route a small share of traffic through Hyperswitch first, then move the rest once authorization and settlement reports reconcile.
Gateway credentials: Re-issue or re-register the single gateway's credentials in Hyperswitch and test refunds and voids before live traffic.
Retire Spreedly last: Keep the Spreedly account active until imported tokens are verified in production.

Before starting, confirm with your gateway whether existing tokens can be used directly in Hyperswitch or whether cards must be re-collected from customers.

Questions buyers ask before moving from Spreedly

How long does the Spreedly export take?

Spreedly's export documentation says exports are generally processed within 2 weeks, and each merchant gets one free export per receiving service. Ask Spreedly to confirm the current timing and fees for your account before you plan cutover, because the export is a batch job that you do not control once requested. Plan the receiving endpoint, its PCI DSS posture and the encryption key exchange before you submit the request, so the export is not waiting on your side. The Spreedly export documentation describes the supported export types.

Can our own team migrate from Spreedly to Hyperswitch without outside help?

Some teams can, especially those with strong Kubernetes, PostgreSQL and payments integration experience. The work includes standing up the Router, Scheduler, PostgreSQL, Redis and card vault, configuring each gateway connector, building the export receiver, testing token imports and running parallel traffic. Hyperswitch documents Helm-based deployments on Kubernetes and guides for AWS, GCP and Azure, which shortens the platform part. Whether your team has the capacity for a payment cutover alongside daily operations is the real question to answer internally.

What does the migration require from our own team?

You need named owners in several areas, and each one should be agreed before work starts:

Payments engineering for connector configuration, routing rules and webhook handling
Platform or SRE staff for cluster, database, Redis and backup operations
Security and compliance staff for the PCI DSS scope decision and the receiving endpoint
Finance or operations staff for reconciliation against each gateway's settlement reports

DeployOpen plans, implements, integrates, hardens and documents the platform in your own infrastructure under a written scope, so the division of labor should be stated in that scope.

Can Hyperswitch replace every gateway we use with Spreedly?

Not necessarily. The Hyperswitch README says it connects to more than 100 payment processors, including Stripe, Adyen, PayPal, Worldpay and Checkout.com, but coverage of your specific gateways, regions, payment methods and account features must be confirmed connector by connector. Some gateways may need a different connector version, a custom integration or a gateway-side change. Build a written list of every gateway and payment method you use, then check each one against the current Hyperswitch connector list in its repository before committing to a timeline.

How does moving to self-hosted Hyperswitch change our PCI DSS scope?

It depends on the vault model you choose. Hyperswitch documents a self-hosted model with its native vault, where the merchant is fully responsible for PCI DSS certification and data handling. Self-hosted orchestration with an external PCI vault provider, or with the SaaS Hyperswitch Vault, keeps less card data in your environment. Your QSA or assessor should confirm the scope with the chosen model before you receive any card data. DeployOpen prepares systems, controls and evidence for assessments, but independent auditors issue the actual assessment.

What happens to our existing stored cards and bank accounts?

Stored payment methods can be moved only through a supported path. Spreedly documents single card export and encrypted batch file export to a PCI compliant third party, and the receiving side must be able to decrypt and import the data into the Hyperswitch vault. Each token that does not transfer will require the customer to re-enter payment details, and that impact should be measured before cutover. Confirm with Spreedly and with your gateways which credentials are portable, and retain a fallback path for any payment methods that cannot be exported.

What does a quote for this migration depend on?

A quote follows from the written scope, so it depends on the work you define. The main drivers are the number of gateways and connectors, the vault model, the size and format of the card export, the hosting environment, the PCI DSS evidence you need, the amount of parallel running and the integrations with your ledger and reconciliation tools. Ask for line items that separate platform setup, connector work, data migration, security testing and ongoing support, so you can see which costs are one-time and which recur. DeployOpen does not publish a price list.

How DeployOpen scopes and runs a Spreedly to Hyperswitch migration

DeployOpen plans and implements self-hosted Hyperswitch inside your own cloud accounts, data centers or private networks, with the vault model and PCI DSS scope agreed before any card data moves. Engagements are fixed-scope, with scope, deliverables and timelines agreed in writing before work starts.

How we scope

Confirm which Spreedly gateways, payment methods and receiving endpoints are in use today and which must stay live during cutover
Agree the Hyperswitch vault model in writing, including whether card data stays in-house or sits with an external PCI vault provider
Define the written scope for export handling, gateway re-pointing, traffic phasing, testing and documentation before work starts

How we build

Deploy the Hyperswitch router, scheduler, PostgreSQL, Redis and card vault on Kubernetes with Helm charts in your environment
Prepare a PCI compliant receiver for Spreedly's encrypted batch export and test the import path with non-production data first
Configure gateway connections and routing rules, then test retries, failover and reconciliation before any production traffic moves

How we hand over

Document the architecture, network boundaries, key management, access roles and the PCI DSS evidence your assessor will request
Deliver runbooks for phased traffic cutover, rollback steps and redaction of Spreedly tokens once migrated cards are verified
Hand over configuration, test results and the migration record so your team can operate the platform without DeployOpen

How we support

Support upgrades to new Hyperswitch releases through a retainer, with testing in a staging environment before production changes
Run security testing of the APIs, infrastructure and vault boundary as part of readiness, and report findings for your remediation
Prepare compliance evidence for your assessor; DeployOpen does not issue audit reports, attestations or certifications

Migrate from Spreedly to Hyperswitch