Migrate to the Payment Element with the Checkout Sessions API

View your payment methods settings and enable the payment methods you want to support. You need at least one payment method enabled to create a Checkout Session.

By default, Stripe enables cards and other common payment methods that can help you reach more customers, but we recommend turning on additional payment methods that are relevant for your business and customers. See Payment method support for product and payment method support, and our pricing page for fees.

Set the SDK to use at least the 2025-03-31.basil API version.

// Set your secret key. Remember to switch to your live secret key in production.
// See your keys here: https://dashboard.stripe.com/apikeys
import Stripe from 'stripe';
const stripe = new Stripe(
'sk_test_BQokikJOvBiI2HlWgH4olfQ2', {
  apiVersion: '2025-03-31.basil;' as any,
});

Because the Payment Element allows you to accept multiple payment methods, we recommend using dynamic payment methods, which are automatically enabled if you don’t pass payment_method_types into the Checkout Session. When enabled, Stripe evaluates the currency, payment method restrictions, and other parameters to determine the list of payment methods available for your customers. We prioritise payment methods that increase conversion and are most relevant to the currency and location of the customer.

Update your PaymentIntent creation call to create a Checkout Session instead. In the Checkout Sessions instance, you’ll pass:

• line_items: Represents what’s in the order
• ui_mode: custom: Indicates that you’re using embedded components
• mode: payment: Indicates that you’ll accept one-off payments for the Checkout Session
• return_url: Represents the URL to redirect your customer back to after they authenticate or cancel their payment on the payment method’s app or site.

In addition, return the Checkout Session’s client_secret to the client-side to use later.

Each Checkout Session generates a PaymentIntent upon confirmation. If you want to retain any extra parameters from your current integration while creating a PaymentIntent, refer to the options available in payment_intent_data.

intent = Stripe::PaymentIntent.create({
  amount: 1099,
  currency: 'usd',
  payment_method_types: ['card'],
})

session = Stripe::Checkout::Session.create({
  line_items: [
    {
      price_data: {
        currency: 'usd',
        product_data: {name: 'T-shirt'},
        unit_amount: 1099,
      },
      quantity: 1,
    },
  ],
  mode: 'payment',
  ui_mode: 'custom',
  return_url: '{{RETURN_URL}}',
})

{
  clientSecret: session.client_secret,
}.to_json

Migrating to embedded components requires the additional step of collecting your customer’s email.

<input type="text" id="email" />
<div id="email-errors"></div>

stripe.initCheckout({fetchClientSecret}).then((checkout) => {
  const emailInput = document.getElementById('email');
  const emailErrors = document.getElementById('email-errors');

  emailInput.addEventListener('input', () => {
    // Clear any validation errors
    emailErrors.textContent = '';
  });

  emailInput.addEventListener('blur', () => {
    const newEmail = emailInput.value;
    checkout.updateEmail(newEmail).then((result) => {
      if (result.error) {
        emailErrors.textContent = result.error.message;
      }
    });
  });
});

You can now replace the Card Element and individual payment method Elements with the Payment Element. The Payment Element automatically adjusts to collect input fields based on the payment method and country (for example, full billing address collection for SEPA Direct Debit) so you don’t have to maintain customised input fields any more.

The following example replaces CardElement with PaymentElement:

<form id="payment-form">
  <div id="card-element">
  </div>
  <div id="payment-element">
    <!-- Mount the Payment Element here -->
  </div>
  <button id="submit">Submit</button>
</form>

const cardElement = elements.create("card");
cardElement.mount("#card-element");
const paymentElement = checkout.createPaymentElement();
paymentElement.mount("#payment-element");

Instead of using individual confirm methods like stripe.confirmCardPayment or stripe.confirmP24Payment, use checkout.confirm to collect payment information and submit it to Stripe.

To confirm the Checkout Session, update your submit handler to use checkout.confirm instead of individual confirm methods.

When called, checkout.confirm attempts to complete any required actions, such as displaying a 3DS window or redirecting them to a bank authorisation page. When confirmation is complete, customers redirect to the return_url you configured, which normally corresponds to a page on your website that provides the status of the payment.

If you want to keep the same checkout flow for card payments and only redirect for redirect-based payment methods, you can set redirect to if_required.

The following code example replaces stripe.confirmCardPayment with checkout.confirm:

// Create the PaymentIntent and obtain clientSecret
const res = await fetch("/create-intent", {
  method: "POST",
  headers: {"Content-Type": "application/json"},
});

const {client_secret: clientSecret} = await res.json();

const handleSubmit = async (event) => {
  event.preventDefault();

  if (!stripe) {
    // Stripe.js hasn't yet loaded.
    // Make sure to disable form submission until Stripe.js has loaded.
    return;
  }

  setLoading(true);

  const {error} = await stripe.confirmCardPayment(clientSecret, {
    payment_method: {
      card: elements.getElement(CardElement)
    }
  });

  if (error) {
    handleError(error);
  }
};

const handleSubmit = async (event) => {
  event.preventDefault();

  if (!stripe) {
    // Stripe.js hasn't yet loaded.
    // Make sure to disable form submission until Stripe.js has loaded.
    return;
  }

  setLoading(true);

  const {error} = await checkout.confirm();

  if (error) {
    handleError(error);
  }
};

Stripe sends a checkout.session.completed event when the payment completes. Use the Dashboard webhook tool or follow the webhook guide to receive these events and run actions, such as sending an order confirmation email to your customer, logging the sale in a database, or starting a shipping workflow.

Listen for these events rather than waiting on a callback from the client. On the client, the customer could close the browser window or quit the app before the callback executes, and malicious clients could manipulate the response. Setting up your integration to listen for asynchronous events is what enables you to accept different types of payment methods with a single integration.

In addition to handling the checkout.session.completed event, we recommend handling these other events when collecting payments with the Payment Element:

1. Navigate to your checkout page.
2. Fill out the payment details with a payment method from the following table. For card payments:
   • Enter any future date for card expiry.
   • Enter any 3-digit number for CVC.
   • Enter any billing postal code.
3. Submit the payment to Stripe.
4. Go to the Dashboard and look for the payment on the Transactions page. If your payment succeeded, you’ll see it in that list.
5. Click your payment to see more details, like billing information and the list of purchased items. You can use this information to fulfil the order.

See Testing for additional information to test your integration.