The legacy version of Checkout presented customers with a modal dialog that collected card information, and returned a token or a source to your website.

In contrast, the new version of Checkout is a smart payment page hosted by Stripe that creates payments or subscriptions. It supports Apple Pay and dynamic 3D Secure3D Secure provides an additional layer of authentication for credit card transactions that protects merchants from liability for fraudulent card payments. During a transaction that incorporates the 3D Secure authorization process, the customer is prompted to supply a separate password or code to validate their purchase., with more features to come.

There are two ways to integrate the new version of Checkout: client and server. The client integration is quick to get started with and is suitable for simpler product catalogs. The server integration provides maximum flexibility, with support for dynamic line items, ConnectConnect is Stripe’s solution for any business that needs to process payments and pay out to sellers and service providers., re-using existing CustomersStripe Customer objects allow you to perform recurring charges, and to track multiple charges, that are associated with the same customer., and advanced subscription features.

To migrate from the legacy version to the new version, follow the guide that most closely represents your business model. Each guide will recommend an integration path along with example code.

• Simple product catalog with fixed pricing
  For example, you are selling a few products with pre-determined prices.

• Simple subscriptions
  For example, you are a SaaS provider with a monthly subscription plan.

• Dynamic product catalog and pricing
  For example, you have a large product catalog or require support for dynamically generated line items (such as donations or taxes).

• Dynamic subscriptions
  For example, you are a SaaS provider billing users and need support for advanced features.

• Connect platforms and marketplaces
  For example, you are operating a marketplace connecting service providers with customers.

• Saving payment methods for future use (Unsupported)
  If you were using the legacy version of Checkout to save a payment method for later use without also charging the customer at the same time, use Stripe Elements instead. The new version of Checkout does not yet support collecting payment method information outside of a transaction, although support is planned.

As you follow the relevant migration guide, you can also reference the conversion table for a mapping of specific parameters and configuration options between the two versions of Checkout.

Simple product catalog with fixed pricing

If you are selling a few products with fixed pricing (such as a few t-shirts or e-books), consider using the new version of Checkout’s client integration. Follow the instructions in the quickstart to create a product in the Dashboard and generate a code snippet to add to your website.

You may have used the legacy version of Checkout to create a token or source on the client, and passed it to your server to create a charge. The new version of Checkout, however, automatically creates the payment for you, and no server integration is required.

Client-side code

<form action="/pay" method="POST">
  <script
    src="https://checkout.stripe.com/checkout.js"
    class="stripe-button"
    data-key="pk_test_TYooMQauvdEDq54NiTphI7jx"
    data-name="T-shirt"
    data-description="Comfortable cotton t-shirt"
    data-amount="500">
  </script>
</form>

<script src="https://js.stripe.com/v3"></script>
<button id="checkout-button">Pay</button>

var stripe = Stripe('pk_test_TYooMQauvdEDq54NiTphI7jx');

var checkoutButton = document.querySelector('#checkout-button');
checkoutButton.addEventListener('click', function () {
  stripe.redirectToCheckout({
    items: [{
      // Define the product and SKU in the Dashboard first, and use the SKU
      // ID in your client-side code.
      sku: 'sku_EZcJ1irJxirScy',
      quantity: 1
    }],
    successUrl: 'https://www.example.com/success',
    cancelUrl: 'https://www.example.com/cancel'
  });
});

Server-side code

post '/pay' do
  customer = Stripe::Customer.create(
    email: params[:stripeEmail],
    source: params[:stripeToken]
  )

  charge = Stripe::Charge.create(
    amount: 500,
    description: 'T-shirt',
    currency: 'usd',
    customer: customer.id
  )

  [200, { charge: charge.id }.to_json]
end

The conversion table below provides a mapping of configuration options between the two versions of Checkout. For a full list of configuration options for the new version, see the redirectToCheckout reference.

If you need to fulfill purchased goods after the payment, refer to Checkout Purchase Fulfllment.

Simple subscriptions

If you are providing a simple subscription service (such as monthly access to software), consider using the new version of Checkout’s client integration. Follow the instructions in the quickstart to create a plan in the Dashboard and generate a code snippet to add to your website.

You may have used the legacy version of Checkout to create a token or source on the client, and passed it to your server to create a customer and a subscription. The new version of Checkout, however, automatically creates both the customer and the subscription for you, and no server integration is required.

Client-side code

<form action="/subscribe" method="POST">
  <script
    src="https://checkout.stripe.com/checkout.js"
    class="stripe-button"
    data-key="pk_test_TYooMQauvdEDq54NiTphI7jx"
    data-name="Gold Tier"
    data-description="Monthly subscription"
    data-amount="2000"
    data-label="Subscribe">
  </script>
</form>

<script src="https://js.stripe.com/v3"></script>
<button id="checkout-button">Subscribe</button>

var stripe = Stripe('pk_test_TYooMQauvdEDq54NiTphI7jx');

var checkoutButton = document.querySelector('#checkout-button');
checkoutButton.addEventListener('click', function () {
  stripe.redirectToCheckout({
    items: [{
      // Define the product and plan in the Dashboard first, and use the plan
      // ID in your client-side code.
      plan: 'plan_EZcJ1irJxirScy',
      quantity: 1
    }],
    successUrl: 'https://www.example.com/success',
    cancelUrl: 'https://www.example.com/cancel'
  });
});

Server-side code

post '/subscribe' do
  customer = Stripe::Customer.create(
    email: 'customer@example.com',
    source: params[:stripeToken]
  )

  subscription = Stripe::Subscription.create(
    customer: customer.id,
    items: [{plan: 'gold_tier_monthly'}]
  )

  [200, { subscription: subscription.id }.to_json]
end

The conversion table below provides a mapping of configuration options between the two versions of Checkout. For a full list of configuration options for the new version, see the redirectToCheckout reference.

If you need to fulfill purchased services after the payment, refer to Checkout Purchase Fulfllment.

Dynamic product catalog and pricing

If you are selling products where the amount or line items are determined dynamically (say, with a large product catalog or for donations), consider using the new version of Checkout’s server integration. Follow the instructions in the quickstart to integrate the Checkout Sessions API in your application.

You may have used the legacy version of Checkout to create a token or source on the client, and passed it to your server to create a charge. The new version of Checkout’s server integration, however, reverses this flow. You first create a Session on your server, pass its ID to your client, redirect your customer to Checkout, who then gets redirected back to your application upon success.

Before

With the legacy version of Checkout, you would display the dynamic amount and description and collect card information from your customer.

<form action="/purchase" method="POST">
  <script
    src="https://checkout.stripe.com/checkout.js"
    class="stripe-button"
    data-key="pk_test_TYooMQauvdEDq54NiTphI7jx"
    data-name="Your cart"
    data-description="{{DESCRIPTION}}"
    data-amount="{{AMOUNT}}">
  </script>
</form>

Next, you would send the resulting token or source to your server and charge it.

post '/purchase' do
  customer = Stripe::Customer.create(
    email: 'customer@example.com',
    source: params[:stripeToken]
  )

  charge = Stripe::Charge.create(
    amount: @cart.amount,
    description: @cart.description,
    currency: 'usd',
    customer: customer.id
  )

  [200, { charge: charge.id }.to_json]
end

After

With the new version of Checkout, first create a Checkout Session on your server.

post '/session' do
  session = Stripe::Checkout::Session.create(
    success_url: 'https://www.example.com/success',
    cancel_url: 'https://www.example.com/cancel',
    payment_method_types: ['card'],
    line_items: @cart.items.map do |item|
      {
        amount: item.amount,
        quantity: item.quantity,
        name: item.name,
        currency: item.currency
      }
    end
  )

  [200, { session: session.id }.to_json]
end

Next, pass the Session ID to your client and redirect your customer to Checkout to complete payment.

var stripe = Stripe('pk_test_TYooMQauvdEDq54NiTphI7jx');

stripe.redirectToCheckout({
  sessionId: '{{CHECKOUT_SESSION_ID}}'
});

The customer will be redirected to the success_url once they complete payment.

If you need to fulfill purchased goods after the payment, refer to Checkout Purchase Fulfllment.

Dynamic subscriptions

If you are providing subscription services that are dynamically determined or require support for other advanced features, consider using the new version of Checkout’s server integration. Follow the instructions in the quickstart to integrate the Checkout Sessions API in your application.

You may have used the legacy version of Checkout to create a token or source on the client, and passed it to your server to create a customer and subscription. The new version of Checkout’s server integration, however, reverses this flow. You first create a Session on your server, pass its ID to your client, redirect your customer to Checkout, who then gets redirected back to your application upon success.

Before

With the legacy version of Checkout, you would display the subscription information and collect card information from your customer.

<form action="/subscribe" method="POST">
  <script
    src="https://checkout.stripe.com/checkout.js"
    class="stripe-button"
    data-key="pk_test_TYooMQauvdEDq54NiTphI7jx"
    data-name="Gold Tier"
    data-description="Monthly subscription with 30 days trial"
    data-amount="2000"
    data-label="Subscribe">
  </script>
</form>

Next, you would send the resulting token or source to your server to create a customer and a subscription.

post '/subscribe' do
  customer = Stripe::Customer.create(
    email: 'customer@example.com',
    source: params[:stripeToken]
  )

  subscription = Stripe::Subscription.create(
    customer: customer.id,
    items: [{plan: 'gold_tier_monthly'}],
    trial_period_days: 30
  )

  [200, { subscription: subscription.id }.to_json]
end

After

With the new version of Checkout, first create a Checkout Session on your server.

post '/session' do
  session = Stripe::Checkout::Session.create(
    success_url: 'https://www.example.com/success',
    cancel_url: 'https://www.example.com/cancel',
    payment_method_types: ['card'],
    subscription_data: {
      items: [{plan: 'gold_tier_monthly'}],
      trial_period_days: 30
    }
  )

  [200, { session: session.id }.to_json]
end

Next, pass the Session ID to your client and redirect your customer to Checkout to complete payment.

var stripe = Stripe('pk_test_TYooMQauvdEDq54NiTphI7jx');

stripe.redirectToCheckout({
  sessionId: '{{CHECKOUT_SESSION_ID}}'
});

The customer will be redirected to the success_url once the customer and subscription have been created.

If you need to fulfill purchased services after the payment, refer to Checkout Purchase Fulfillment.

Connect platforms and marketplaces

If you are operating a Connect platform or marketplace and create payments involving connected accounts, consider using the new version of Checkout’s server integration. Follow the instructions in the Connect guide to migrate your integration.

The following example demonstrates using the Checkout Sessions API to process a direct charge. Follow the Connect guide for details on how to create destination charges.

Before

With the legacy version of Checkout, you would collect card information from your customer on the client.

<form action="/purchase" method="POST">
  <script
    src="https://checkout.stripe.com/checkout.js"
    class="stripe-button"
    data-key="pk_test_TYooMQauvdEDq54NiTphI7jx"
    data-name="Food Marketplace"
    data-description="10 cucumbers from Roger's Farm"
    data-amount="2000">
  </script>
</form>

Next, you would send the resulting token or source to your server and charge it on behalf of the connected account.

post '/purchase' do
  charge = Stripe::Charge.create({
    amount: 2000,
    description: "10 cucumbers from Roger's Farm",
    currency: 'usd',
    source: params[:stripeToken],
    application_fee_amount: 200
  }, {
    stripe_account: '{{CONNECTED_STRIPE_ACCOUNT_ID}}'
  })

  [200, { charge: charge.id }.to_json]
end

After

With the new version of Checkout, first create a Checkout Session on your server on behalf of the connected account.

post '/session' do
  session = Stripe::Checkout::Session.create({
    success_url: 'https://www.example.com/success',
    cancel_url: 'https://www.example.com/cancel',
    payment_method_types: ['card'],
    line_items: [{
      amount: 200,
      quantity: 10,
      name: "10 cucumbers from Roger's farm",
      currency: 'usd'
    }],
    payment_intent_data: {
      application_fee_amount: 200
    },
  }, {
    stripe_account: '{CONNECTED_STRIPE_ACCOUNT_ID}'
  })

  [200, { session: session.id }.to_json]
end

Next, pass the Session ID to your client and redirect your customer to Checkout to complete payment. Make sure to provide the connected account’s ID when initializing Stripe.js.

var stripe = Stripe('pk_test_TYooMQauvdEDq54NiTphI7jx', {
  stripeAccount: '{{CONNECTED_STRIPE_ACCOUNT_ID}}'
});

stripe.redirectToCheckout({
  sessionId: '{{CHECKOUT_SESSION_ID}}'
});

The customer will be redirected to the success_url once they complete payment.

If you need to fulfill purchased goods or services after the payment, refer to Checkout Purchase Fulfllment.

Parameter conversion

The new version of Checkout supports most of the functionality of the legacy version of Checkout. However, the two versions do not share the same API. The table below maps parameters and configuration options between the legacy version and the new version.

The legacy Checkout reference documents parameters accepted by the previous version. For a full list of configuration options accepted by the new version of Checkout, see the Stripe.js reference and the API reference for Checkout Sessions.