Migrating saved payment methods

When you move to yRecurring from another billing system, your customers' saved cards do not have to be lost. If you keep the same payment gateway account, the cards are still right there, vaulted with your gateway. What your old billing system held was only a set of references to them. This import brings those references over, so renewals keep charging without a single customer re-entering a card.

What actually moves

A saved card lives in your payment gateway's vault, not in any billing system. Your gateway knows the card; billing systems only hold the token that points at it (a Stripe pm_ id, a Paystack authorization code, a GoCardless mandate id) plus display details like the brand and last four digits.

So the import file contains tokens and display details, never card numbers. yRecurring will not accept card numbers in this import. Any column that looks like it holds one fails the row on purpose, whichever column it is: a last-four cell with more than four digits, or a real card number pasted into the token, gateway customer ID, brand or External ID column. If a row fails this way, fix the column mapping; there is no way to force it through.

Before you start

1. Connect the gateway first. The tokens belong to your gateway account, so that account must be connected under Settings, then Payment gateways. A row naming a gateway that is not connected fails with a message saying exactly that. See connecting a payment gateway.
2. Import customers first. Each method row links to a customer by the External ID you gave it in the customer import.
3. Match your keys to your tokens. Tokens from your live gateway account work with your live keys, and sandbox tokens with test keys. Connect the same account the tokens came from, and check you are in the matching mode: the import only accepts a gateway connected in the mode you are currently using.

Two ways to bring the methods in

Pull from your gateway is the direct route. On the import page for saved payment methods, pick a connected gateway that supports it and choose Fetch from gateway. Stripe, GoCardless, Authorize.Net and Paystack can all be read directly. PayPal, Adyen and Flutterwave cannot, because their APIs only return saved instruments one customer at a time with no way to list every customer; for those, use a file. If you bill under more than one business entity, the list names the entity too: each entity has its own gateway account holding its own saved cards, and a card saved in one account cannot be charged for invoices from another, so you fetch one account at a time.

The fetch runs in the background: a progress page shows how many cards have been read so far, keeps updating itself, and takes you to the normal review screen the moment the fetch finishes. Big accounts can take a while; you can close the page and come back, and the fetch carries on from where it was rather than starting over. If the gateway cannot be read, the page says what went wrong and offers to try again. If a fetch stops responding, the page tells you that too instead of spinning; nothing has been imported, so starting again is safe.

What comes over depends on the gateway: cards and bank mandates from Stripe, bank mandates from GoCardless, saved customer profiles from Authorize.Net, and reusable card authorizations from Paystack. A Paystack card the customer did not agree to keep on file is left behind, because it cannot be charged again anyway. Each instrument is matched to a customer by the email on the gateway's customer record. A card whose email matches no customer, or matches more than one, shows as an error row you can see and fix; nothing is guessed. Whichever card your gateway has marked as a customer's default comes across marked the same way, so renewals keep charging the card they charged before. Bank mandates saved at the gateway (ACH, SEPA, Bacs) come across too, not just cards.

Tick "Only customers without a saved card" to fill gaps without touching customers who already have one. A customer whose only card has expired counts as a gap, which is usually what you want.

One fetch brings over up to 5,000 saved cards, and looks at up to 50,000 while filtering. If it stops at either limit, the review screen says so and tells you which limit it was; commit that batch and fetch again to continue.

Upload a file works with any gateway, including the three that cannot be read directly, and with any old system that can export its token references. Rows can link to customers by External ID or by email, whichever your export has.

The file

One row per saved method:

Column	Required	What goes in it
Customer External ID	one of these two	The customer this method belongs to.
Customer email	one of these two	Alternative match: the email must belong to exactly one customer.
Gateway	yes	Which connected gateway holds the token: stripe, adyen, braintree, paypal, gocardless, authorizenet, paystack or flutterwave.
Gateway token	yes	The saved instrument's reference: pm_…, an authorization code, a mandate id.
Gateway customer ID	recommended	The gateway's id for the customer (cus_…). Most gateways need it to charge without the customer present.
Type	no	card, ach, sepa_debit, bacs_debit or paypal. Defaults to card.
Brand, Last 4	no	Display only, shown in lists ("Visa ···· 4242").
Expiry month, Expiry year	no	Drives expiring-card notices. Leave blank for mandates and wallets.
External ID	no	Your old system's id for this method, kept for traceability.
Is default	no	Mark the card this customer should be charged on. Worth filling in: a customer who arrives with several cards and none marked has no chosen default, and automatic collection falls back to whichever card was saved last.

A template file with example rows is available on the import screen.

What happens on import

Each row is vaulted as a saved method on its customer, exactly as if the gateway had saved it: renewals and automatic collection can charge it, it shows on the customer's page, and the customer can manage it from their update-card link.

Two safety behaviors are built in:

• No charge storm. Importing a method never triggers a charge. Invoices already in dunning are not retried just because a card arrived by import; collection follows its normal schedule.
• Re-runs are safe. A method is identified by its gateway and token. Re-importing the same file refreshes the display details instead of creating duplicates, and the run's summary counts those rows as updated rather than created.

Undo

Like every import, a committed run can be rolled back for seven days. Rolling back deletes the method records the run created; the instruments themselves stay untouched in your gateway's vault. A method that became a customer's default or backup payment method after the import is left in place and reported, and the report says which of the two it is, so an undo can never silently break a customer's renewals. Clear that designation on the customer and roll back again to finish.

What this import is not

This import moves references within the same gateway account. It does not move card data between gateways; that transfer happens between the gateways themselves under their card-security rules, and gateways differ in whether they support it. If you are switching gateway providers as well as billing systems, do the gateway-to-gateway transfer with your providers first, then import the new tokens here.