Migrating payment tokens and saved cards

The question that quietly sinks a migration

When a shop plans a move to a new store, someone eventually asks the innocent question: what happens to everyone's saved cards? The expectation, almost always, is that the saved cards are rows in a database somewhere and that moving them is a copy and paste like any other table. They are not, and it is not. A saved card is one of the few things in your shop that you genuinely do not hold, cannot read, and cannot simply carry across. Getting this wrong does not produce a tidy error. It produces a month of failed renewals, a wave of customers asked to enter a card at six in the morning, and a churn number you cannot undo.

I build custom stores on Solidus, the open source Rails ecommerce framework, and I run the migrations onto them. Saved cards and the payment tokens behind them are the single topic where I am most careful to tell a client the truth before anyone signs anything. This article is that truth, written out. It links the parent piece on what moves and what does not, and it sits next to the companion on subscriptions and recurring payments, where the same token problem bites hardest.

How a saved card is actually stored

Start with where the card lives. When a customer saves a card at your checkout, your shop does not keep the card number. The long number on the front of the card, the primary account number or PAN, is held by your payment gateway or processor inside its own secure vault. In return the gateway hands your shop a token: a short, meaningless reference that stands in for the card. Your database stores that token. The next time you charge the customer, you send the gateway the token and it looks up the real card on your behalf.

This is not a technicality. It is the whole reason a normal shop can take cards at all without the cost and audit burden of handling raw card numbers. Because you never store, process or transmit the PAN yourself, you stay in the lightest tier of the card industry's security standard, which for most shops means a short self assessment rather than a full audit. I explain that scope in PCI DSS explained. The vault is what keeps you in the light. The token is the receipt.

One thing is never kept, by anyone, not even encrypted and not even with the customer's written consent: the three or four digit security code on the card. The PCI Security Standards Council is explicit that the code cannot be retained once the payment it was collected for has been authorised, and that it is not needed for card on file or recurring charges.¹ You do not need it to charge a saved card, so this costs you nothing. But it is the first sign that the idea of exporting everything is never literally true.

A token from one gateway means nothing to another

Here is the constraint that governs everything else. The token your shop holds is specific to the gateway that issued it. It is a reference into that gateway's vault and nowhere else. Hand that token to a different gateway and it is noise. There is no shared format, no interchange, no lookup table that turns gateway A's token into gateway B's.

So the obvious idea, export the tokens and load them into the new store, does not work. And the next idea, export the real card numbers and save them into the new gateway yourself, is worse. A normal merchant is not permitted to pull its customers' card numbers into a spreadsheet and move them by hand. That is precisely the handling of raw card data that the whole token arrangement exists to keep you away from, and it would drag you into a scope and liability you do not want. The card numbers are also not yours to take. The gateway holds them on your behalf under its own compliance, and releases them only through a controlled process to another party that can be trusted to receive them.

That is why "migrating saved cards" is the wrong phrase. The honest phrase is "migrating the vault", and only the gateways can do that, and only some of them will.

Migrating the vault, gateway to gateway, how it really works

There is an established, compliant path, and it is worth understanding in detail because knowing exactly how it works is how you tell a reversible move from a trap.

The card schemes and the security standard both allow a secure transfer of vaulted card data from one PCI DSS Level 1 provider to another. Level 1 is the top tier of the standard, the one that applies to the largest processors and carries a full external audit. The transfer goes provider to provider, encrypted end to end, and the merchant never sees a card number at any point. In practice the receiving processor publishes the terms it will accept. Stripe, to take a documented example, will only receive card data from, or send it to, another PCI DSS Level 1 compliant processor, and asks for that processor's current attestation of compliance (or its listing on Visa's registry of service providers) plus a public encryption key of at least 4,096 bits, hosted over a secure connection on the processor's own domain.² The data itself is encrypted with that key and moved over a dedicated secure file transfer server. The merchant supplies no card numbers and handles none.³

What comes across is the stored card details and the billing addresses, nothing more. The security code does not move, for the reason above.¹ Payment history, past charges, subscriptions and invoices do not move through this transfer at all, and they are separate problems with separate tools.² When the import finishes, the receiving processor returns a mapping file: a list that pairs each old customer and card identifier with its new one, so your new store can update every saved card record to point at the new token before the first charge runs.³

Two numbers matter for planning. The import itself is usually quick once clean data arrives. The slow, uncertain part is the export from the losing side, which the receiving processor cannot control and which can take anywhere from a few days to several months depending on the other provider's process, forms and fees.³ That is why the export request is the first thing you send, not the last.

The source has to agree to release the vault

Every word above assumes one thing: that your current provider will release the vault. Most mainstream processors will. Your contract often obliges them to return your data on request, and a competent receiving team will join the conversation and help move it along.³ A provider with a published, repeatable export process is a provider you can leave, and that is worth more at signing time than a slightly lower fee, because a provider you cannot leave can raise the fee later.

But not every card vault sits behind a provider that will let it go. Some payment products are welded to the platform the shop runs on. The platform holds the vault, treats it as part of its own service, and offers no route to export the underlying card data to an outside processor. When that is the arrangement, the gateway to gateway transfer above is simply not on the table, and the tokens cannot come across at all.

An anonymised cautionary example

I will keep this deliberately vague, because the point is the shape of the trap and not the names. A real subscription business wanted to move to a less expensive gateway. It had built its recurring billing on its platform's own payments product, which only permitted subscriptions through that product and through one named gateway behind it. The vaulted cards were held by that gateway, not by the merchant, and there was no export to anywhere else. The business could move its catalogue, its customers and its content, but the saved cards and the live subscriptions behind them were locked to the product it was trying to leave. It went ahead with a partial move anyway, and ended with the worst of both worlds: a new storefront that could not bill its existing subscribers, and an old system it was still paying for only because that was where the paying customers' cards still lived. The hard lesson is that this was knowable before the move began. I tell the longer version of how gateway tie ins catch people out in the hidden dangers of switching payment gateways.

What can move and what cannot, in one view

Before the fallbacks, here is the honest summary of where each piece stands.

What you have	Does it move?	The honest plan
The saved card number (PAN)	Only provider to provider, encrypted, Level 1 to Level 1, if the source agrees	Request the export first, then confirm the destination will receive it
Your gateway tokens	No, they are meaningless to any other gateway	Replaced by the destination's own tokens via the vault transfer
The card security code	Never, for anyone	Not needed to charge a saved card
Proof of earlier authentication	Yes, as a network transaction identifier, if the source includes it	Ask for it in the export so customers are not challenged again
Payment history and subscriptions	Not through the card transfer	Separate tools, cancel old schedules as new ones go live
A vault locked to a platform payments product	Often not at all	Decide before you commit, then plan to collect cards again

Network tokens are not a migration, but they help

When a clean vault transfer is available, take it. When it is awkward, or when you want to make the cards you do move as durable as possible, two network level services are worth understanding. They are often confused with migration. Neither is migration, and saying so plainly is part of doing this honestly.

The first is the network token. Instead of your gateway storing the raw card number and minting its own private token, the card networks can issue a token at the network level that stands in for the card across its life. Mastercard describes its token service as replacing the PAN, converting the sensitive number into a digital token so that merchants work with "digital tokens instead of account PANs", and it offers a bulk service to tokenise cards already held on file.⁴ Visa runs an equivalent service. A network token tends to survive events that would otherwise break a stored card, such as a reissue, and processors report better approval rates on it. Stripe, for instance, lists network tokens among the features that can improve authorisation on migrated cards.³ The limit to understand is that a network token is still provisioned and held through a provider's integration. It is a better credential to carry, not a magic wire that teleports your vault from one provider to another. It makes a real migration smoother. It does not replace one.

Account updater keeps cards current, it does not move them

The second service gets confused with migration even more often, so be careful with it. Visa's Account Updater and Mastercard's Automatic Billing Updater are services that keep the cards you already hold current. When a customer's card is reissued, expires or is replaced, the networks can feed the new number and expiry back to merchants that participate, so a recurring charge does not fail just because the plastic in someone's wallet changed. Visa describes its service as letting issuers, acquirers and qualified merchants "exchange updated account information" including new account numbers, expiry dates and account closures, so that "issuers can retain a cardholder's merchant payment relationship after account information changes".⁵ Mastercard describes its service as providing "updated payment account credentials including PAN and expiry date updates" to cut the card on file declines caused by expired or reissued cards.⁶

Read those descriptions carefully and you will see what they are not. They update the card details you are already allowed to hold. They do not hand your vault to a different provider, and they do not create a stored card where you had none. An account updater is maintenance for a vault you keep. It is a genuinely useful thing to switch on after a move, so your freshly migrated cards stay chargeable. It is not a way to perform the move.

Collecting cards again, done well

Sometimes the vault cannot move. The source will not release it, or a slice of it is tied up in wallet credentials that do not export. When that happens the only honest route left is to ask customers for their card again. Done carelessly this is the most expensive thing you can do in a migration. Done well it is survivable, and the difference is entirely in the planning.

The expected loss from asking a group of customers to re enter a card is easy to size, and it is an expected value, a probability multiplied by an amount, which I set out in the Foundations reference:

L = N \times (1 - q) \times v \times T

Here $L$ is the revenue you expect to lose, $N$ is the number of customers whose card you have to collect again, $q$ is the share who successfully do it so that $(1 - q)$ is the share you lose, $v$ is the average value per customer per month, and $T$ is the number of months a retained customer would otherwise have kept paying. The whole art is lifting $q$ , the share who complete the step, as close to one as you can.

What lifts it: a single, calm, one time flow that asks the customer to confirm their details, not a dead subscription that silently stops. Use a hosted field or the payment sheet your new processor provides, so the card is captured straight into the new vault and your store still never touches the number. Time the request to a moment the customer is already engaged, such as their next login or next order, rather than a cold email. Tell them plainly why, keep it to one screen, and never bundle it with a price rise or a redesign, so the only decision in front of them is "yes, this is still my card". And stage it: move a batch, watch the completion rate, and only then move the next, so a problem costs you one group and not the whole base.

When strong customer authentication resurfaces

There is one more surprise waiting for European customers, and it is better named now than discovered during the first renewal. Under the European rules on strong customer authentication, most online card payments where the customer is involved need the customer to confirm their identity with two independent factors, the kind of check you see as a banking app prompt or a one time code. The legal basis is the regulatory technical standards made under the second Payment Services Directive.⁷ The European Banking Authority has confirmed that card payments are treated as initiated by the payer and fall under these rules, and that setting up or amending a payment arrangement through a remote channel is itself subject to the check.⁸ In the United Kingdom the same regime applies through the regulator's published approach.⁹

The practical implication is this. A card that was authenticated once, under an agreement set up on the old provider, carries proof of that authentication in the form of a network transaction identifier. When a proper vault transfer includes that identifier, the new provider can present it and the customer is usually not challenged again. Braintree, for example, includes network transaction identifier fields in its export so that history travels with the card.¹⁰ When you instead collect the card again, you are setting up a fresh arrangement, and that first step through a remote channel can trigger a new authentication.⁸ That is normal and fine, as long as you expect it, build the authentication step into your collect again flow, and do not run it at an hour when the customer is asleep. The failure mode is a silent renewal that the bank decides to challenge when nobody is at the screen.

The decision you must make before you commit

Everything above collapses into three questions, and the entire point of this article is that you answer them before you commit to a move, not halfway through one:

First, will my current provider release the vault, through a documented gateway to gateway transfer, and how long and how much will it ask? Second, will the destination provider receive that transfer, and does it require a Level 1 attestation and a key I can supply? Third, if some or all of the cards cannot move, what does collecting them again cost me in churn, using the formula above, and can I afford it? A move where all three answers are known is a project. A move where they are discovered in flight is the trap from the cautionary example.

A worked example

Let me make it concrete with an invented business. Rowan Supplements is a Leeds company selling a monthly supplements subscription at rowansupplements.example. Priya runs it. It has 25,000 saved cards on a mainstream processor, and it is moving to a custom Solidus store with a new Level 1 processor behind the checkout. Every number here is invented so I can show the steps.

Priya's first move, months before any launch date, is the boring one that decides everything: she asks her current processor, in writing, for a card data export to a named Level 1 destination, and she asks her new processor to confirm it will receive it and to supply its attestation and encryption key.² The current processor confirms it will release the vault and quotes a fee and a timeline of several weeks.³ Good: this is a reversible move, not a trap.

She then runs the two tracks in parallel. New customers and new orders go live on the new store and the new processor straight away, building fresh vaulted cards there. Meanwhile the export of the existing 25,000 is requested, encrypted provider to provider, and imported into the new vault, with network transaction identifiers included so her subscribers are not asked to authenticate again on their first renewal.¹⁰ When the mapping file comes back, her store updates all 25,000 saved card records to the new tokens before any renewal runs on them.³ She switches on an account updater afterwards, so a reissued card does not quietly fail three months later.⁶

Not everything comes clean. The export flags 1,800 cards that were captured through a wallet credential that cannot be transferred between processors.² For exactly those 1,800, and only those, Priya runs a staged collect again flow: a one time confirm your card step at next login, hosted by the new processor, communicated plainly, moved in batches of a few hundred with the completion rate watched between them. Using the formula, at $N = 1{,}800$ , a completion share $q = 0.9$ , $v = 24$ a month and $T = 10$ months, the expected loss is $1{,}800 \times 0.1 \times 24 \times 10 = 43{,}200$ pounds, and the whole purpose of the staged, well timed flow is to push $q$ higher and that number down. She sizes it before she starts, so it is a budgeted line and not a nasty surprise. The 23,200 cards that moved cleanly cost nothing and nobody noticed.

What I ask before anyone signs

Most of the outcome here is decided in the contract and the documentation, long before a line of migration code is written. So I ask every provider, incoming and outgoing, the same short list, and I want the answers in writing:

How do I export saved cards to another PCI DSS Level 1 provider, how long does it take, and what does it cost? Do you include network transaction identifiers, so customers are not asked to authenticate again? Will you receive a vault transfer from another Level 1 provider on the way in? Which cards, if any, cannot be transferred because they are held as wallet credentials? And after I stop processing, how long do I keep access for refunds and disputes on old payments?

A provider that answers these plainly is a provider you own your relationship with. That belongs in the same checklist as the data protection questions in vetting vendors before they undermine your compliance, and it sits underneath the larger truth that your customer and payment relationships should be yours to carry, which is the theme of who actually owns your business data. If your shop takes payment in the ways DACH and UK customers expect, the destination side of this is covered in DACH payments in Solidus.

Saved cards can very often move, cleanly and compliantly, through a proper gateway to gateway migration. But only with the source's cooperation, and the honest, unglamorous work is establishing that cooperation exists before you commit, not after. That is the whole job, and doing it in the right order is the difference between a quiet move and a painful one.