Migrating Stored Cards Between Payment Processors

Card data cannot be exported by you, and it does not need to be. Every major processor supports a network-sanctioned migration in which the outgoing provider transmits the encrypted vault directly to the incoming one, which returns a mapping from old token to new. Your responsibility is identifiers, reconciliation, and the customers whose credentials do not survive the move. This guide sits under Payment Provider Migration & Portability and covers that process end to end.

The part teams underestimate is the timeline. The technical import takes an afternoon; the paperwork, scheduling, and network approvals take weeks. Starting the commercial process at the same time as the engineering work is the single most effective way to shorten a migration.

The part teams underestimate second is the shortfall. Some proportion of tokens will not carry — expired cards, unsupported issuers, single-use tokens — and those customers need a re-authentication path that must exist before the mapping lands, not after.

Trade-offs

Approach to moving credentials Customer impact Coverage Lead time Risk
Network-supported vault migration None 95%+ typically Weeks Low
Ask customers to re-enter details High friction Whatever converts Days Loses passive customers
Dual-charge fallback during overlap None Full, temporarily Days Two live integrations
Network tokens where available None Issuer-dependent Weeks Updater history varies
Vault migration path The outgoing provider sends the encrypted vault directly to the incoming provider, which returns only a mapping of old token to new token to the merchant. Outgoing provider holds the vault Incoming provider issues new tokens Your database identifiers only encrypted transfer token mapping card numbers never enter your systems, so scope does not change weeks of lead time — start the paperwork first
The merchant handles only identifiers, which is exactly why the migration does not expand PCI scope.

The re-entry option is worth quantifying rather than dismissing, because it is sometimes the only path — for example when moving a rail the vault migration does not cover. Expect a meaningful share of passive subscribers not to act, and expect them to skew toward low-engagement accounts that would otherwise have renewed silently.

Step-by-Step Implementation

1. Start the process before you need it

Both providers require signed agreements, and the receiving provider will schedule the import into its own pipeline. Ask for the timeline in the first conversation, and plan the engineering phases around it rather than the other way around.

Ask two specific questions early: what proportion of tokens they typically carry across for your issuer mix, and whether network tokens are included or reissued. The answers determine the size of your re-authentication campaign, which determines how much notice your support and marketing teams need.

2. Import the mapping additively

ALTER TABLE payment_methods
  ADD COLUMN provider        TEXT NOT NULL DEFAULT 'incumbent',
  ADD COLUMN provider_ref    TEXT,
  ADD COLUMN legacy_provider TEXT,
  ADD COLUMN legacy_ref      TEXT,
  ADD COLUMN migrated_at     TIMESTAMPTZ;

-- Import: keep the old reference, add the new one. Never overwrite.
UPDATE payment_methods pm
   SET legacy_provider = pm.provider,
       legacy_ref      = pm.provider_ref,
       provider        = 'incoming',
       provider_ref    = m.new_token,
       migrated_at     = now()
  FROM vault_mapping m
 WHERE m.old_token = pm.provider_ref
   AND pm.provider = 'incumbent';

Preserving legacy_ref is what makes rollback and refund routing possible. A refund against a charge taken at the old provider must go back through the old provider, and without the legacy reference that path is gone.

3. Reconcile the mapping

Mapping reconciliation Every active payment method resolves into matched tokens, unmatched methods needing re-authentication, or unexpected mapping rows with no local method. Active payment methods Matched new token stored Unmatched re-authentication needed Unexpected mapping row, no method
Three buckets, and the third matters most — a mapping row with no local method usually means a payment method you stopped tracking but never detached.
-- Active methods with no new token: the re-authentication population.
SELECT pm.payment_method_id, pm.customer_id, s.subscription_id, s.current_period_end
  FROM payment_methods pm
  JOIN subscriptions s ON s.default_payment_method_id = pm.payment_method_id
 WHERE s.status IN ('active', 'trialing', 'past_due')
   AND pm.provider_ref IS NULL;

4. Validate a sample before trusting the whole set

Run zero-amount or minimal authorisations against a stratified sample — by issuer, by country, by card brand — and confirm the new tokens work. A mapping that imported cleanly can still contain tokens the new acquirer cannot charge, and finding that out on a renewal batch is considerably worse than finding it on fifty deliberate tests.

5. Run the re-authentication campaign

Sequence it by renewal date, contacting customers whose next charge is soonest first. The message should be short, explain that a payment update is needed, and link straight to a hosted update page — not to a login flow that requires the customer to find the billing section themselves. Send well before the renewal so that a non-responder still has time to be caught by a second attempt.

Coverage, Network Tokens, and What Silently Changes

The headline coverage number hides several details worth understanding before the cutover.

Network tokens generally transfer with their updater relationships intact, which means the automatic refresh of expired or reissued cards continues working. Provider-specific tokens are reissued by the incoming provider, and any card-updater history held by the outgoing provider does not come with them. The practical effect is a modest rise in expired-card declines in the first months after cutover, which looks like a migration failure and is actually a temporary loss of updater coverage that rebuilds over time.

Stored authentication history is similarly provider-scoped. For European customers, the exemption and mandate data attached to a credential lives with the provider that collected it, so the first charge at the new provider is more likely to require a challenge. Plan for an elevated authentication rate on the first post-migration cycle and warn support before it happens — see routing 3DS2 SCA challenge flows for how to keep that from costing conversion.

Some credential types do not migrate at all. Wallet tokens tied to a specific provider integration, mandates for bank rails, and any instrument stored through a third party generally need re-collection. Enumerate these by type before the export so the “shortfall” number you plan around includes them rather than being discovered as a surprise.

Finally, expect the coverage figure to be a range rather than a promise. Providers quote typical rates, and your own mix of issuers, card ages, and geographies moves the result. Plan the campaign for the pessimistic end; a smaller shortfall than expected is a pleasant afternoon, and a larger one is an incident.

Re-authentication campaign sequencing Customers whose renewals fall soonest are contacted first, with a second attempt and a support-assisted path before the renewal date arrives. Renewal in 21 days first email in 10 days reminder + in-app in 3 days final notice renewal day dunning takes over sequenced by renewal date, not by when the mapping landed every message links straight to a hosted update page
Ordering by renewal date means effort lands where it changes an outcome, rather than being spread evenly across a base that mostly does not need it yet.

Sizing and Running the Campaign

The re-authentication campaign is a marketing exercise with a billing deadline, and treating it as either one alone produces poor results.

Size it before the mapping arrives. Take the provider’s expected coverage range, apply the pessimistic end to your active subscription count, and you have the population. Multiply by your typical email-to-action conversion for billing messages — usually far higher than marketing messages, but well short of universal — and you have the expected residual that will need a second channel. Knowing that number in advance is what lets support staff the queue rather than discovering it.

Segment the message by value. A high-value annual customer deserves a personal note from an account manager rather than a templated email, and the cost of that attention is trivial next to the revenue at stake. The broad base of small monthly subscriptions is the opposite: automate entirely and accept the conversion rate.

Give the customer a path that does not require them to remember a password. A hosted update page reached by a signed, expiring link removes the largest friction point in the flow, since a meaningful share of subscribers cannot log in without a reset. Keep the link short-lived and single-purpose, and rate-limit it.

Measure the campaign against renewals, not against opens. The only outcome that matters is whether the next charge succeeded, so the dashboard should show, for each cohort, how many still lack a working credential as their renewal date approaches. That view also tells you when to stop: once the remaining population is small and consistently unresponsive, the residual belongs in ordinary dunning rather than in a campaign.

Verification & Testing

Before the import, snapshot the count of active payment methods by provider, status, and card brand. After the import, assert that matched plus unmatched equals the original total, and that no method lost its legacy reference. Simple totals catch import bugs that per-row spot checks miss.

Test the refund routing explicitly: create a fixture charge on the legacy provider, migrate the method, and assert a refund still routes to the legacy provider rather than the new one. This is the single most common post-migration defect and it is trivially preventable with one test.

Test the rollback. Pin a migrated subscription back to the legacy provider and run a renewal, asserting the legacy token is used and the charge succeeds. A rollback path that has never been exercised is not a rollback path.

Gotchas & Production Pitfalls

  • Overwriting the old token. Removes the refund path and the rollback path in one update. Always import additively.
  • Assuming full coverage. Planning for 100% leaves no campaign, no timeline, and no support briefing for the customers who need one.
  • Migrating and cutting over on the same day. Import the mapping, validate it, and only then begin routing charges. Two risky steps at once make failure hard to attribute.
  • Ignoring inactive methods. A cancelled subscription that reactivates later expects its stored card to work; decide deliberately whether inactive methods are in scope for the migration.
  • Forgetting the descriptor. The statement descriptor may change with the acquirer, and an unfamiliar descriptor drives disputes. Match it as closely as the new provider allows and warn support.

Frequently Asked Questions

Does the migration expand our PCI scope? No. Card data moves provider to provider; you receive only tokens. Your scope is unchanged, which is precisely why this path exists rather than an export to you.

How long does the whole process take? Weeks rather than days, dominated by agreements and the receiving provider’s scheduling. The import and reconciliation are short; plan the calendar around the paperwork.

Can we migrate only some customers? Usually the vault transfers wholesale, but you control routing afterwards, so a full import with a per-cohort cutover is the normal pattern — and the safer one.

What if the incumbent is uncooperative? Network rules generally support a merchant’s right to move their vault, and the receiving provider will usually drive the process. Expect delay rather than refusal, and factor it into the timeline.