Migrate to the express checkout element

Migrate your existing integration with the payment request button element to the express checkout element.

The payment request button element lets you accept card payments through Apple Pay, Google Pay, and Link. When you migrate to the express checkout element, you can also accept payments through PayPal, Amazon Pay, and Klarna, and display multiple payment buttons at the same time.

Enable payment methods

Enable the payment methods you want to support in your payment methods settings. You must enable at least one payment method.

By default, Stripe enables cards and other common payment methods. You can enable 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.

Create a Checkout Session Server-side

With the payment request button element, you create a paymentRequest object in your client-side code and provide the total, currency, and customer-detail requests.

With the Checkout Sessions API, create a Checkout Session on your server instead. The Checkout Session contains the amount, line items, eligible payment methods, and checkout configuration.

Create the Checkout Session with ui_mode: 'elements', then send its client_secret to your client.

server.js

With the payment request button element, your client-side paymentRequest object defines the payment amount, currency, requested customer details, and shipping options. With Checkout Sessions, configure these values when you create or update the Checkout Session on your server.

Initialize Checkout Client-side

After you create the Checkout Session, use its client secret to initialize Checkout on your client.

Before

After

const stripe = Stripe('pk_test_TYooMQauvdEDq54NiTphI7jx');
const elements = stripe.elements();

const stripe = Stripe('pk_test_TYooMQauvdEDq54NiTphI7jx');

const clientSecret = fetch('/create-checkout-session', {
 method: 'POST',
})
 .then((response) => response.json())
 .then((data) => data.clientSecret);

const checkout = stripe.initCheckoutElementsSdk({
 clientSecret,
});

Add the express checkout element Client-side

You no longer need to create a paymentRequest object or call canMakePayment().

Instead, create the express checkout element from the Checkout instance. Stripe displays the payment methods that are available for the current customer and Checkout Session.

Before

After

<div id="payment-request-button">
</div>

<div id="express-checkout-element">
 <!-- Mount the express checkout element here -->
</div>

Before

After

const paymentRequest = stripe.paymentRequest({
 country: 'US',
 currency: 'usd',
 total: {
 label: 'Demo total',
 amount: 1099,
 },
 requestPayerName: true,
 requestPayerEmail: true,
});
const paymentRequestButton = elements.create('paymentRequestButton', {
 paymentRequest,
});
paymentRequest.canMakePayment().then((result) => {
 if (result) {
 paymentRequestButton.mount('#payment-request-button');
 } else {
 document.getElementById('payment-request-button').style.display = 'none';
 }
});

const expressCheckoutElement = checkout.createExpressCheckoutElement();

expressCheckoutElement.mount('#express-checkout-element');

Optional Save payment details during a payment

Optional Style the express checkout element

Optional Adapt your UI to available payment methods

Confirm the Checkout Session Client-side

The payment request button element emits a paymentmethod event. In that handler, you typically confirm the PaymentIntent with stripe.confirmCardPayment, call event.complete(), and manually handle additional authentication.

The express checkout element emits a confirm event instead. Pass that event to Checkout to confirm the Checkout Session. Checkout handles required customer authentication and redirects for payment methods that require them.

Before

After

paymentRequest.on('paymentmethod', (event) => {
 stripe.confirmCardPayment(
 clientSecret,
 {
 payment_method: event.paymentMethod.id,
 },
 {
 handleActions: false,
 }
 ).then((confirmResult) => {
 if (confirmResult.error) {
 event.complete('fail');
 return;
 }

 event.complete('success');

 if (confirmResult.paymentIntent.status === 'requires_action') {
 stripe.confirmCardPayment(clientSecret);
 }
 });
});

const loadActionsResult = await checkout.loadActions();

if (loadActionsResult.type === 'error') {
 // Show loadActionsResult.error.message to your customer.
 return;
}

const {actions} = loadActionsResult;

expressCheckoutElement.on('confirm', async (event) => {
 const result = await actions.confirm({
 expressCheckoutConfirmEvent: event,
 });

 if (result.type === 'error') {
 // Show result.error.message to your customer.
 }
});

Handle post-payment events Server-side

When you migrate to the Checkout Sessions API, update your webhook endpoint to handle Checkout Session events. Fulfill the order after receiving checkout.session.completed. If you accept delayed payment methods, also handle checkout.session.async_payment_succeeded and checkout.session.async_payment_failed. Don’t rely on a client-side callback to fulfill orders. See Fulfill orders.