Switching Your Integration to Stripe

    Learn how to convert your website or app to Stripe from another payment processor.

    With the right preparation, moving your business from an existing payment processor to Stripe can be done smoothly:

    1. Plan your data migration
    2. Implement tokenization of payment methods
    3. Write the API calls
    4. Test your integration
    5. Go live!

    As you go through this guide and your actual conversion, we’re always here to help. We’ll coordinate the migration of your data with your current processor and answer any questions you have along the way.

    How Stripe works

    Stripe is designed to minimize your security requirements without your customers having to leave your site. 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 sent directly to Stripe’s servers.
    2. Stripe returns a representative token to the customer’s browser.
    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 or a subscription).

    Thanks to this approach, the customer remains in your checkout flow but the sensitive payment information never touches your server, thereby reducing what steps you must take to remain PCI compliant. (This change alone may 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 may have any of these differences:

    • The customer never leaves your site
    • The 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)

    Separately, you may find Stripe’s pricing and our support for 135+ currencies to compare favorably to other options as well.

    Note that you do need to be a developer to perform a Stripe integration, or hire one to do that work. If you can’t meet this requirement, consider using a third-party integration instead.

    Step 1: Plan your data migration

    Switching to Stripe doesn’t mean you’ll lose or have to recreate your customer data! In collaboration with your current processor, we securely migrate your data over, including the payment details. This allows you to continue charging customers without interruption or asking them to provide their payment information again.

    How data migration works

    The data migration itself has three steps:

    1. You request an export of your data from your current processor to Stripe.
    2. We work with your current processor to have your data securely sent straight to Stripe.
    3. We import your data into your Stripe account.

    What to watch for

    When it comes to creating your Stripe integration, you should be prepared to handle two situations. First, the 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_pdfypbz5mHqCwd in your Stripe account.

    Once we migrate your data over, we provide you with a JSON file that maps all your customers: customer ID 1893 is now cus_pdfypbz5mHqCwd. You’ll need to parse this mapping file to update your database accordingly.

    The second situation you should be prepared to handle is the rare event that a customer wants to change their payment method after the data has been exported from your previous processor but before you’ve finished mapping that data on your side. During this narrow window, payment method changes made at your previous processor will be lost (as they are after the data migration), but customer payment method changes cannot be made to the data in Stripe (as you haven’t completed the mapping yet). In this situation, if a customer logs into your site to change their payment method, your site won’t be able to properly handle that (due to a lack of knowing that customer’s new Stripe customer ID).

    To handle this possibility, have your site’s “update your payment method” process be prepared 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. Recreate the subscription, if applicable (see below).

    If your integration is capable of handling this slight possibility, your customer won’t see errors, lose functionality at your site, or experience billing issues. Your customer will never know you switched to Stripe!

    Working with subscriptions

    If you’re using subscriptions (aka recurring billing) at your current processor, you can still easily switch to Stripe, with just two extra steps. First, you need to create your subscription plans in your Stripe account, using the same pricing and billing interval as at your current processor.

    Second, when remapping your customer records, you need to recreate the subscription for each customer in Stripe. To ensure proper billing, start each subscription with a trial period that ends when they should next be billed. For example, if it’s the first of the month and a customer had already paid for a subscription through the 15th, create the new Stripe subscription with a trial period that ends on the 15th.

    Optimal migration flow

    Factoring in how the migration process works and what your integration ought to be prepared to handle, here is the optimal migration flow:

    1. Code your Stripe integration.
    2. Use the Stripe integration for all new customers.
    3. Define an “update your payment method” process with a self-migration capability.
    4. Request an export of your data from your current processor.
    5. After receiving the JSON mapping file from Stripe, realign your stored data with your new Stripe objects. (And recreate any subscriptions in Stripe, if using recurring billing.)
    6. Disconnect your previous integration.

    You can always reach out to us if you have questions along the way.

    Step 2: Implement tokenization of payment methods

    A Stripe integration begins with the secure, client-side tokenization of the customer’s payment details. Stripe provides three approaches for doing so:

    Of the two non-mobile tools, Checkout provides the quickest integration whereas Elements provides the most customization. Click the Pay with Card button to see the user experience for a basic Checkout integration:

    That button and the required client-side functionality is created using this code:

    <form action="/your-server-side-code" method="POST">
      <script
        src="https://checkout.stripe.com/checkout.js" class="stripe-button"
        data-key="pk_test_6pRNASCoBOKtIshFeQd4XMUh"
        data-name="Your Site"
        data-locale="auto"
        data-zip-code="true">
      </script>
    </form>

    When changing your integration to Stripe, this code may simply replace an existing tokenization approach. If your current processor setup has the payment details going directly to your server, then this is a new step in your integration.

    Remember that whichever tokenization approach you choose, your customer never leaves your site and their payment details never touch your server. Instead your server receives a token ID, for use in an API call.

    Step 3: Write the API calls

    Once you’ve tokenized the customer’s payment method, charging the customer is a simple API call.

    curl https://api.stripe.com/v1/charges \
       -u sk_test_BQokikJOvBiI2HlWgH4olfQ2: \
       -d amount=1000 \
       -d currency=usd \
       -d description="Example charge" \
       -d source=tok_a7fifnrmpGGHDOXFDII07Fex
    
    # Set your secret key: remember to change this to your live secret key in production
    # See your keys here: https://dashboard.stripe.com/account/apikeys
    Stripe.api_key = "sk_test_BQokikJOvBiI2HlWgH4olfQ2"
    
    # Token is created using Checkout or Elements!
    # Get the payment token ID submitted by the form:
    token = params[:stripeToken]
    
    # Charge the user's card:
    charge = Stripe::Charge.create(
      :amount => 1000,
      :currency => "usd",
      :description => "Example charge",
      :source => token,
    )
    
    # Set your secret key: remember to change this to your live secret key in production
    # See your keys here: https://dashboard.stripe.com/account/apikeys
    stripe.api_key = "sk_test_BQokikJOvBiI2HlWgH4olfQ2"
    
    # Token is created using Checkout or Elements!
    # Get the payment token ID submitted by the form:
    token = request.form['stripeToken'] # Using Flask
    
    # Charge the user's card:
    charge = stripe.Charge.create(
      amount=1000,
      currency="usd",
      description="Example charge",
      source=token,
    )
    
    // Set your secret key: remember to change this to your live secret key in production
    // See your keys here: https://dashboard.stripe.com/account/apikeys
    \Stripe\Stripe::setApiKey("sk_test_BQokikJOvBiI2HlWgH4olfQ2");
    
    // Token is created using Checkout or Elements!
    // Get the payment token ID submitted by the form:
    $token = $_POST['stripeToken'];
    
    // Charge the user's card:
    $charge = \Stripe\Charge::create(array(
      "amount" => 1000,
      "currency" => "usd",
      "description" => "Example charge",
      "source" => $token,
    ));
    
    // Set your secret key: remember to change this to your live secret key in production
    // See your keys here: https://dashboard.stripe.com/account/apikeys
    Stripe.apiKey = "sk_test_BQokikJOvBiI2HlWgH4olfQ2";
    
    // Token is created using Checkout or Elements!
    // Get the payment token ID submitted by the form:
    String token = request.getParameter("stripeToken");
    
    // Charge the user's card:
    Map<String, Object> params = new HashMap<String, Object>();
    params.put("amount", 1000);
    params.put("currency", "usd");
    params.put("description", "Example charge");
    params.put("source", token);
    
    Charge charge = Charge.create(params);
    
    // Set your secret key: remember to change this to your live secret key in production
    // See your keys here: https://dashboard.stripe.com/account/apikeys
    var stripe = require("stripe")("sk_test_BQokikJOvBiI2HlWgH4olfQ2");
    
    // Token is created using Checkout or Elements!
    // Get the payment token ID submitted by the form:
    var token = request.body.stripeToken; // Using Express
    
    // Charge the user's card:
    stripe.charges.create({
      amount: 1000,
      currency: "usd",
      description: "Example charge",
      source: token,
    }, function(err, charge) {
      // asynchronously called
    });
    
    // Set your secret key: remember to change this to your live secret key in production
    // See your keys here: https://dashboard.stripe.com/account/apikeys
    stripe.Key = "sk_test_BQokikJOvBiI2HlWgH4olfQ2"
    
    // Token is created using Checkout or Elements!
    // Get the payment token ID submitted by the form:
    token := r.FormValue("stripeToken")
    
    // Charge the user's card:
    params := &stripe.ChargeParams{
      Amount: 1000,
      Currency: "usd",
      Description: "Example charge",
    }
    params.SetSource(token)
    
    charge, err := charge.New(params)
    
    // Set your secret key: remember to change this to your live secret key in production
    // See your keys here: https://dashboard.stripe.com/account/apikeys
    StripeConfiguration.SetApiKey("sk_test_BQokikJOvBiI2HlWgH4olfQ2");
    
    // Token is created using Checkout or Elements!
    // Get the payment token submitted by the form:
    var token = model.Token; // Using ASP.NET MVC
    
    // Charge the user's card:
    var charges = new StripeChargeService();
    var charge = charges.Create(new StripeChargeCreateOptions {
      Amount = 1000,
      Currency = "usd",
      Description = "Example charge",
      SourceTokenOrExistingSourceId = token
    });
    

    You probably already have some server-side code doing this, unless your current processor handles the charging on their side (i.e., the customer leaves your site). Note that Stripe expects all amounts to be expressed as an integer in the lowest currency unit.

    When making this switch, be certain to update your error handling as well.

    Using a bit more code, you can alternatively store the token on a Customer object in Stripe, for use on subsequent charges or subscriptions:

    # Create a Customer:
    curl https://api.stripe.com/v1/customers \
       -u sk_test_BQokikJOvBiI2HlWgH4olfQ2: \
       -d email="jenny.rosen@example.com" \
       -d source=tok_5xUjSGPc91LgqpZ0Z7wG7glU
    # Create a Subscription:
    curl https://api.stripe.com/v1/subscriptions \
       -u sk_test_BQokikJOvBiI2HlWgH4olfQ2: \
       -d customer=cus_4fdAW5ftNQow1a \
       -d items[0][plan]=pro-monthly
    
    # Set your secret key: remember to change this to your live secret key in production
    # See your keys here: https://dashboard.stripe.com/account/apikeys
    Stripe.api_key = "sk_test_BQokikJOvBiI2HlWgH4olfQ2"
    
    # Token is created using Checkout or Elements!
    # Get the payment token submitted by the form:
    token = params[:stripeToken]
    
    # Create a Customer:
    customer = Stripe::Customer.create(
      :email => "jenny.rosen@example.com",
      :source => token,
    )
    
    # Create a Subscription:
    Stripe::Subscription.create(
      :customer => customer.id,
      :items => [{:plan => "pro-monthly"}],
    )
    
    # Set your secret key: remember to change this to your live secret key in production
    # See your keys here: https://dashboard.stripe.com/account/apikeys
    stripe.api_key = "sk_test_BQokikJOvBiI2HlWgH4olfQ2"
    
    # Token is created using Checkout or Elements!
    # Get the payment token submitted by the form:
    token = request.POST['stripeToken']
    
    # Create a Customer:
    customer = stripe.Customer.create(
      email="jenny.rosen@example.com",
      source=token,
    )
    
    # Create a Subscription:
    stripe.Subscription.create(
      customer=customer.id,
      items=[{"plan": "pro-monthly"}],
    )
    
    // Set your secret key: remember to change this to your live secret key in production
    // See your keys here: https://dashboard.stripe.com/account/apikeys
    \Stripe\Stripe::setApiKey("sk_test_BQokikJOvBiI2HlWgH4olfQ2");
    
    // Token is created using Checkout or Elements!
    // Get the payment token submitted by the form:
    $token = $_POST['stripeToken'];
    
    // Create a Customer:
    $customer = \Stripe\Customer::create(array(
      "email" => "jenny.rosen@example.com",
      "source" => $token,
    ));
    
    // Create a Subscription:
    \Stripe\Subscription::create(array(
      "customer" => $customer->id,
      "items" => array(
        array("plan" => "pro-monthly")
      ),
    ));
    
    // Set your secret key: remember to change this to your live secret key in production
    // See your keys here: https://dashboard.stripe.com/account/apikeys
    Stripe.apiKey = "sk_test_BQokikJOvBiI2HlWgH4olfQ2";
    
    // Token is created using Checkout or Elements!
    // Get the payment token submitted by the form:
    String token = request.getParameter("stripeToken");
    
    // Create a Customer:
    Map<String, Object> customerParams = new HashMap<String, Object>();
    customerParams.put("email", "jenny.rosen@example.com");
    customerParams.put("source", token);
    Customer customer = Customer.create(customerParams);
    
    // Create a Subscription:
    Map<String, Object> item = new HashMap<String, Object>();
    item.put("plan", "pro-monthly");
    Map<String, Object> items = new HashMap<String, Object>();
    items.put("0", item);
    Map<String, Object> subsParams = new HashMap<String, Object>();
    subsParams.put("customer", customer.getId());
    subsParams.put("items", items);
    
    Subscription subscription = Subscription.create(subsParams);
    
    // Set your secret key: remember to change this to your live secret key in production
    // See your keys here: https://dashboard.stripe.com/account/apikeys
    var stripe = require("stripe")("sk_test_BQokikJOvBiI2HlWgH4olfQ2");
    
    (async function() {
      // Token is created using Checkout or Elements!
      // Get the payment token submitted by the form:
      const token = request.body.stripeToken; // Using Express
    
      // Create a Customer:
      const customer = await stripe.customers.create({
        email: "jenny.rosen@example.com",
        source: token,
      });
    
      // Create a Subscription:
      const sub = await stripe.subscriptions.create({
        customer: customer.id,
        items: [{plan: "pro-monthly"}],
      });
    
    })();
    
    // Set your secret key: remember to change this to your live secret key in production
    // See your keys here: https://dashboard.stripe.com/account/apikeys
    stripe.Key = "sk_test_BQokikJOvBiI2HlWgH4olfQ2"
    
    // Token is created using Checkout or Elements!
    // Get the payment token submitted by the form:
    token := r.FormValue("stripeToken")
    
    // Create a Customer:
    customerParams := &stripe.CustomerParams{
      Email: "jenny.rosen@example.com",
    }
    customerParams.SetSource(token)
    customer, err := customer.New(customerParams)
    
    // Create a Subscription:
    subsParams := &stripe.SubParams{
      Customer: customer.id,
      Items: []*stripe.SubItemsParams{
        {Plan: "pro-monthly"},
      },
    }
    subscription, err := sub.New(subsParams)
    
    // Set your secret key: remember to change this to your live secret key in production
    // See your keys here: https://dashboard.stripe.com/account/apikeys
    StripeConfiguration.SetApiKey("sk_test_BQokikJOvBiI2HlWgH4olfQ2");
    
    // Token is created using Checkout or Elements!
    // Get the payment token submitted by the form:
    var token = model.Token; // Using ASP.NET MVC
    
    // Create a Customer:
    var customers = new StripeCustomerService();
    StripeCustomer customer = customers.Create(new StripeCustomerCreateOptions {
      Email = "jenny.rosen@example.com",
      SourceToken = token,
    });
    
    // Create a Subscription:
    var subs = new StripeSubscriptionService();
    StripeSubscription sub = subs.Create(new StripeSubscriptionCreateOptions {
      Customer = customer.Id,
      Plan = "pro-monthly",
    });
    

    The code does assume you've already created a pro-monthly plan in your Stripe account.

    Step 4: Test your integration

    After completing your Stripe integration, you’ll want to test it thoroughly before going live. We provide test credit card numbers to replicate common results.

    At the very least, test for these scenarios:

    • Charge succeeded
    • Charge declined (a card_error)
    • Bad request (i.e., an invalid_request_error)
    • Stripe server error (an api_error, these are extremely rare)
    • Additional subscriptions scenarios, if applicable

    If you have unexpected issues along the way, look at the logs in your Dashboard to see what requests we received and what response we returned.

    Step 5: Go live!

    Once you’ve thoroughly tested your integration, switch to your live Stripe keys—both secret and publishable. Then disable the code for your now-previous processor. Make sure you disable all instances of the previous code (i.e., you might have multiple checkout paths)!