Migrating Data to Stripe

    Securely import sensitive payment data from your current payment processor into your Stripe account.

    Stripe makes it easy for you to bring along your existing customer data and import it into your Stripe account. We work with your current payment provider to securely migrate your data over, including payment information. This allows you to continue charging customers without interruption or asking them to provide their payment details again.

    Migrating data to Stripe is a three-step process:

    1. Build your Stripe integration
    2. Ask your current processor to transfer your data to Stripe
    3. Update your integration to complete the migration

    After the migration process is complete, all payments can be processed on Stripe.

    Step 1: Build your Stripe integration

    Stripe is designed to simplify your security requirements so that your customers remain on your site to complete a payment. This is accomplished through a combination of client-side and server-side steps:

    1. From your website running in the customer’s browser, the customer’s payment details are securely collected by Stripe
    2. Stripe responds with a representative token
    3. The token, along with any other form data, is submitted by the browser to your server
    4. Your server-side code uses that token in an API request (e.g., creating a charge)

    This approach streamlines your website’s checkout flow, while sensitive payment information never touches your server. This makes it easy for you to operate in a PCI-compliant way, which can provide a significant time and financial benefit over your current setup.

    The payment process flow on Stripe

    Compared to other payment processors, a Stripe integration can differ in the following ways:

    • Your customer never leaves your website
    • Token creation isn’t tied to a specific product or amount
    • There’s no need to create a client-side key on-demand (you use a set, publishable API key instead)

    Preparing your integration

    We recommend that you implement the following as you create tokens and charge all new customers:

    With this approach, you can accept payments on Stripe without impacting your current customers.

    Important considerations

    Before you ask your payment processor to transfer data to Stripe, you should be prepared to:

    • Remap customer records.
    • Handle updates to payment information during the migration.
    Remapping customer records

    Customer records will need to be remapped on your end after the migration. For example, a customer with an email address of jenny.rosen@example.com has an ID of 42 in your database. This corresponds to a customer ID of 1893 in your previous processor’s system.

    After the migration, this same customer has an ID of cus_12345 in your Stripe account. Stripe provides an import mapping file so you can update your database with the new references.

    Handling updates to payment information during the migration process

    Customers might need to update their payment information after you ask your previous processor to transfer your data but before it is received and imported by Stripe. During this window, payment method changes submitted to your previous processor will be lost as they aren’t included in the transferred data. Furthermore, these changes also cannot be made on Stripe as the data hasn’t been imported yet and the customer’s new Stripe customer ID isn’t yet known.

    To best handle this, you should make changes to your site’s process for handling updates to saved payment information. This includes preparations to perform a self-migration for any customer without a stored Stripe customer ID:

    1. Create a new Customer object in Stripe for your customer
    2. Attach the payment method to the Customer object
    3. Re-create the subscription, if necessary

    Updating your integration to handle these possibilities can prevent your customers from seeing errors or experiencing billing issues.

    Step 2: Ask your current processor to transfer your data to Stripe

    When you’ve built your integration and are ready to process payments on Stripe, it’s time to request your payment data from your previous processor. Having the account owner contact the processor aids in this process, as most will only initiate a data transfer upon the account owner’s request.

    After requesting the data transfer from your previous processor, get in touch and let us know. Stripe can import your customer payment details (such as credit cards and bank account information for ACH and SEPA payments) and billing address information. Stripe cannot, however, import any subscriptions—these need to be re-created separately.

    It can take between a few days and several weeks for your previous processor to transfer the final data to Stripe, so make sure to allow for this transition time in your migration plan. If the data we receive can’t be used, we will outline any issues and work with your previous processor to correct the data.

    After your previous processor transfers your data, Stripe begins importing it into your account. Stripe creates a Customer for each unique customer in the transferred data file, and creates and attaches the customer’s cards as Card or Source objects. If the transferred data indicates the customer’s default card, we set that as the customer’s default source for charges and subscription payments.

    This import process usually occurs within 10 business days of receiving complete and correct data from your previous processor.

    Step 3: Update your integration to complete the migration

    Once the import process is complete, Stripe sends you a JSON file that maps your current processor’s IDs to the imported Stripe object IDs—you’ll need to parse this mapping file and update your database accordingly. If you build your Stripe integration before attempting to import it, your system would have handled any card updates that happened during the transition.

      {
      "1893": {
        "cards": {
          "2600": {
            "id": "card_2222222222",
            "fingerprint": "x9yW1WE4nLvl6zjg",
            "last4": "4242",
            "exp_month": 1,
            "exp_year": 2020,
            "brand": "Visa"
          },
          "3520": {
            "id": "card_3333333333",
            "fingerprint": "nZnMWbJBurX3VHIN",
            "last4": "0341",
            "exp_month": 6,
            "exp_year": 2021,
            "brand": "Mastercard"
          }
        }
        "id": "cus_abc123def456"
      }
    }
    
    {
      "<OLD_CUSTOMER_ID>": {
        "cards": {
          "<OLD_CARD_ID>": {
            "id": "card_<NEW_ID>",
            "fingerprint": "<CARD NUMBER FINGERPRINT>",
            "last4": "4242",
            "exp_month": 1,
            "exp_year": 2020,
            "brand": "Visa"
          },
          ...
        },
        "id": "cus_<NEW_ID>"
      },
      ...
    }

    In the example above (download link):

    • Customer ID 1893 is imported as a new Customer with ID cus_abc123def456
    • The customer’s card with ID 2600 is imported as a new Card with ID card_2222222222
    • The customer’s card with ID 3520 is imported as a new Card with ID card_3333333333

    Once you update your integration with this mapping file, you can begin charging all your customers on Stripe.

    Working with subscriptions

    If you’re using subscriptions or a similar type of recurring billing at your current processor, switching to Stripe requires two additional steps:

    1. Create your subscription plans in your Stripe account, using the same pricing and billing interval as at your current processor
    2. Re-create the subscription for each customer in Stripe when remapping your customer records

    When remapping your customer records, you need to re-create the subscription for each customer in Stripe. Each subscription’s billing cycle anchor should be set to bill the customer on the correct day of the billing cycle to ensure proper billing. For example, if it’s the 1st and a customer had already paid for a monthly subscription through to the 15th, create the new Stripe subscription and set billing_cycle_anchor to a timestamp that falls on the 15th. This ensures your customer continues to be billed on the 15th of each month, as expected.

    Further reading

    Questions?

    We're always happy to help with code or other questions you might have! Search our documentation, contact support, or connect with our sales team. You can also chat live with other developers in #stripe on freenode.

    Was this page helpful? Yes No

    Send

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