Request a PAN data import

Stripe simplifies your security requirements so that your customers don’t have to leave your site to complete a payment. This is done through a combination of client-side and server-side steps:

1. From your website running in the customer’s browser, Stripe securely collects your customer’s payment details.
2. Stripe responds with a representative token.
3. The browser submits the token, along with any other form data, to your server.
4. Your server-side code uses that token in an API request (for example, when 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.

Stripe’s payment process flow

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.

Prepare your integration

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

• Collect and tokenize customer card information with one of our recommended payments integrations.
• Use Customer objects to save the card information.
• Create charges for these new customers.

Using 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.

Remap customer records

You need to remap Customer records 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, which 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.

As an alternative to creating a new customer in your Stripe account for each unique customer ID in the files we receive from your prior processor, we can import the payment method data from prior records into existing Stripe customer objects instead. To choose this option:

1. In the intake request form Do you want to import data into Stripe Customer objects that already exist in your Stripe account?, choose Yes.

2. Prepare a CSV mapping file containing two columns:

   • old_customer_id—The unique identifier used by your previous processor
   • stripe_customer_id—That customer’s corresponding Stripe customer ID in cus_xxxx format

   Don’t include sensitive data in the file.

3. When we receive the intake form, email you a request for the CSV mapping file. Reply to the email with the prepared file.

Handle updates to payment information

Customers might need to update their payment information after you ask your previous processor to transfer your data but before it’s 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 can’t 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. (Optional) Recreate the subscription.

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

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, 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 can’t, however, import any subscriptions—these need to be recreated 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’ll 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 payment method for charges and subscription payments.

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

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.

After you update your integration with this mapping file, you can begin charging all your customers on Stripe. In the following example:

• 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.

You can request that the data be imported as PaymentMethods when you submit the migration request to us, if you prefer. In this format, the only change to the mapping file is that IDs are in the form pm_2222222222.

{
  "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"
  }
}