Migrate Your Data

Your Finance organization or product managers typically own this phase. Its timeline is case-specific. Also, note (below) that you’ll need to reserve some lead time.

Migration overview

If you have existing payment details stored with another provider, Stripe can help import these details. Your first step is to contact your existing processor to inquire about exporting your data to Stripe. Next, log in to your Stripe account and contact Stripe to advise our Migrations team to be ready to import your data.

From there, at a high level, the flow proceeds like this: Your existing processor will export the stored card details to a CSV (comma-separated values) or other plaintext file, which they will encrypt with Stripe’s PGP key. They will then store the file on their server, and will email Stripe’s Migrations team an encrypted message to access the data securely.

Be sure to tell your Stripe Sales contact what your MCC code was with your existing processor, so that Stripe can apply the same MCC code to your account. Also, note that Stripe can import only the card details from your customers, not their payment histories or subscriptions logic.

For further details about exporting your existing data, see Stripe’s general migration documentation.

Migration timing

We recommend that you target completing your migration two to three weeks before you go live for existing customers. For example, if you want to go live for existing customers on January 15, we recommend ensuring that your migration is complete no later than January 1.

This lead time allows Stripe to make sure that your cards run successfully against Stripe’s card updater functionality. Our card updaters run weekly to automatically update Visa, Amex, Mastercard, and Discover cards if a customer gets a new card from their bank, or if the card’s number or expiration date changes.

The customer.source.updated webhook fires whenever a card is updated. Webhooks sent due to automatically updated cards won’t have a request field set.

When migrating, you can also pass the trial_end parameter, with a value of the next billing date, so that the customer doesn’t get charged immediately.

Migration details

You can subscribe your migrated existing customers to Stripe using Stripe’s API. At a high level: After your customers have been migrated in bulk by Stripe’s migrations team, you’ll iterate through your list of existing customers, and their subscription details, to create subscriptions on Stripe.

Stripe will provide a file that maps the customers we migrated from your existing processor to corresponding Customer objects on Stripe. You can use Stripe’s Subscriptions API to create the subscription for each customer.

As a simple example, you might have a list that includes internal user IDs, processor card IDs, a subscription plan, and a recurring date:

customer_id plan card_id recur_date
0001 gold eT4TfQ9TzSvkve 11-1-19
0002 silver m9frQB9RvvpnMX 11-12-19
0003 gold QnTqtVe2ZfhnEZ 11-13-19

When you migrate to Stripe, we’ll return a JSON file mapping the customer IDs you provide to Stripe’s Customer and Card objects. For the example above, the first object might look like this:

  "0001": {
	"cards": {
		"eT4TfQ9TzSvkve": {
			"id": "card_8732JC82qoaOp821",
			"fingerprint": "T3wipXA4euWRkniF",
			"last4": "4242",
			"exp_month": 1,
			"exp_year": 2020,
			"brand": "Visa"
	"id": "cus_9NJftYCDc9Vnd9"

You can use this file, in combination with your existing list, to subscribe the customer cus_9NJftYCDc9Vnd9 to the “gold” plan, with a starting date of 11-1-2019. (Within Stripe, this will be a combination of the “gold” product plus a specific pricing plan.)

You can also pass the trial_end parameter, with a value of the next billing date, so that the customer doesn’t get charged immediately. Alternatively, you could pass the billing_cycle_anchor date, with a value of the next billing date, and with proration set to false. This will also prevent the customer from being charged immediately.

For further details about mapping customers, payment sources, and subscriptions into your Stripe integration, see Stripe’s documentation about completing migration.

Next steps

Was this page helpful? Yes No


Thank you for helping improve Stripe's documentation. If you need help or have any questions, please consider contacting support.

On this page