Skip to content
Create account
 or
Sign in
The Stripe Docs logo
/
Create account
Sign in
OverviewUpgrade your integration
Online payments
OverviewFind your use caseUse Managed Payments
Payment methods
Payment interfaces
Payment scenarios
In-person payments
Beyond payments

Accept a payment with the Express Checkout Element

Use a single integration to accept payments through one-click payment buttons.

Express Checkout Element

The Express Checkout Element is an integration for accepting payments through one-click payment method buttons. Supported payment methods include Link, Apple Pay, Google Pay, PayPal, Klarna, and Amazon Pay.

Customers see different payment buttons depending on their device and browser. Compatible devices automatically support Google Pay and Link. You must complete additional steps to support Apple Pay and PayPal.

Try the demo

Toggle the prebuilt options in the demo to change the background color, layout, size, and shipping address collection. The demo displays Google Pay and Apple Pay only on their available platforms. Payment method buttons are only shown in their supported countries.

If you don’t see the demo, try viewing this page in a supported browser.

OptionDescription
Merchant countrySet this using the publishable key that you use to initialize Stripe.js. To change the country, you must unmount the Express Checkout Element, update the publishable key, then re-mount the Express Checkout Element.
Background colorSet colors using the Elements Appearance API. Button themes are inherited from the Appearance API but you can also define them directly when you create the Element.
Desktop and mobile sizeUse the dropdown to set the max pixel width of the parent element that the Express Checkout Element is mounted to. You can set it to 750px (Desktop) or 320px (Mobile).
Max columns and max rowsSet these values using the layout parameter when you Create the Express Checkout Element.
Overflow menuSet this using the layout parameter when you Create the Express Checkout Element.
Collect shipping addressTo collect shipping information, you must pass options when creating the Express Checkout Element. Learn more about collecting customer details and displaying line items.

Before you begin

  1. Add a payment method to your browser. For example, you can add a card to your Google Pay account or to your Wallet for Safari.
  2. Serve your application over HTTPS. This is required in development and in production. You can use a service such as ngrok.
  3. Register your domain in both a sandbox and live mode.
  4. Create a PayPal Sandbox account to test your integration.

Set up Stripe
Server-side

First, create a Stripe account or sign in.

Use our official libraries to access the Stripe API from your application:

Command Line
Ruby
Python
PHP
Java
Node.js
Go
.NET
No results
# Available as a gem
sudo gem install stripe
Gemfile
Ruby
Python
PHP
Java
Node.js
Go
.NET
No results
# If you use bundler, you can add this line to your Gemfile
gem 'stripe'

Enable payment methods

By default, Stripe uses your payment methods settings to determine which payment methods are enabled in the Express Checkout Element. You can also configure specific payment methods on your Checkout Session using the payment_method_types attribute.

Supported payment methods

Apple Pay and Google Pay are automatically enabled when using the card payment method type. When using Link, you must also pass the card payment method type.

Payment methodPayment method type
Amazon Payamazon_pay
Apple Paycard
Google Paycard
Klarnaklarna
Linklink, card
PayPalpaypal

Create a Checkout Session
Server-side

Create a Checkout Session on your server to control the payment flow. The Checkout Session defines your line items, shipping options, and other settings for the payment.

Command Line
cURL
Stripe CLI
Ruby
Python
PHP
Java
Node.js
Go
.NET
No results
curl https://api.stripe.com/v1/checkout/sessions \
  -u "
sk_test_BQokikJOvBiI2HlWgH4olfQ2
:" \
  -d "line_items[0][price]"={{PRICE_ID}} \
  -d "line_items[0][quantity]"=1 \
  -d mode=payment \
  -d ui_mode=custom \
  -d return_url={{RETURN_URL}}

Set ui_mode to custom to integrate with the Express Checkout Element. The returned Checkout Session includes a client secret, which the client uses to securely display the checkout interface.

You can configure additional options on the Checkout Session:

Set up Stripe Elements
Client-side

The Express Checkout Element is automatically available as a feature of Stripe.js. Include the Stripe.js script on your checkout page by adding it to the head of your HTML file. Always load Stripe.js directly from js.stripe.com to remain PCI compliant. Don’t include the script in a bundle or host a copy of it yourself.

checkout.html
<head>
  <title>Checkout</title>
  <script src="https://js.stripe.com/clover/stripe.js"></script>
</head>

Create an instance of Stripe with the following JavaScript on your checkout page:

checkout.js
// Set your publishable key: remember to change this to your live publishable key in production
// See your keys here: https://dashboard.stripe.com/apikeys
const stripe = Stripe(
'pk_test_TYooMQauvdEDq54NiTphI7jx'
);

Create a fetchClientSecret function to retrieve the client secret from your server:

checkout.js
const fetchClientSecret = () => {
  return fetch('/create-checkout-session', {method: 'POST'})
    .then((response) => response.json())
    .then((json) => json.client_secret);
};

Create the Checkout instance:

checkout.js
const checkout = stripe.initCheckout({
  clientSecret
});

Create and mount the Express Checkout Element
Client-side

The Express Checkout Element contains an iframe that securely sends the payment information to Stripe over an HTTPS connection. The checkout page address must also start with https://, rather than http://, for your integration to work.

The Express Checkout Element needs a place to live on your payment page. Create an empty DOM node (container) with a unique ID in your payment form.

checkout.html
<div id="express-checkout-element">
  <!-- Express Checkout Element will be inserted here -->
</div>
<div id="error-message">
  <!-- Display an error message to your customers here -->
</div>

When the form has loaded, create an instance of the Express Checkout Element and mount it to the container DOM node:

checkout.js
// Create and mount the Express Checkout Element
const expressCheckoutElement = checkout.createExpressCheckoutElement();
expressCheckoutElement.mount('#express-checkout-element');

Collect customer details and display line items
Client-side

The Checkout Session you created on the server automatically determines the line items, total amount, and available payment methods. The Express Checkout Element uses this information to display the appropriate interface.

Handle payment confirmation

Listen to the confirm event when your customer finalizes their payment:

checkout.js
expressCheckoutElement.on('confirm', (event) => {
  checkout.confirm({expressCheckoutConfirmEvent: event});
});

Handle dynamic updates

If you need to update the Checkout Session based on customer selections (such as shipping address or shipping rate changes), you can listen to events and update the session:

checkout.js
expressCheckoutElement.on('shippingaddresschange', async (event) => {
  const response = await fetch('/update-session-shipping', {
    method: 'POST',
    headers: {'Content-Type': 'application/json'},
    body: JSON.stringify({
      sessionId: checkout.session.id,
      shippingAddress: event.address
    })
  });
  const result = await response.json();

  if (result.error) {
    event.reject();
  } else {
    event.resolve();
  }
});

expressCheckoutElement.on('shippingratechange', async (event) => {
  const response = await fetch('/update-session-shipping-rate', {
    method: 'POST',
    headers: {'Content-Type': 'application/json'},
    body: JSON.stringify({
      sessionId: checkout.session.id,
      shippingRateId: event.shippingRate.id
    })
  });
  const result = await response.json();

  if (result.error) {
    event.reject();
  } else {
    event.resolve();
  }
});

OptionalListen to the ready event
Client-side

After mounting, the Express Checkout Element won’t show buttons for a brief period. To animate the Element when buttons appear, listen to the ready event. Inspect the availablePaymentMethods value to determine which buttons, if any, display in the Express Checkout Element.

checkout.js
// Optional: If you're doing custom animations, hide the Element
const expressCheckoutDiv = document.getElementById('express-checkout-element');
expressCheckoutDiv.style.visibility = 'hidden';

expressCheckoutElement.on('ready', ({availablePaymentMethods}) => {
  if (!availablePaymentMethods) {
    // No buttons will show
  } else {
    // Optional: Animate in the Element
    expressCheckoutDiv.style.visibility = 'initial';
  }
});

OptionalStyle the button
Client-side

You can style each payment method button differently and control the overall appearance of the Express Checkout Element.

checkout.js
const expressCheckoutElement = checkout.createExpressCheckoutElement({
  // Specify a type per payment method
  buttonType: {
    googlePay: 'checkout',
    applePay: 'check-out',
    paypal: 'buynow',
  },
  // Specify a theme per payment method
  buttonTheme: {
    applePay: 'white-outline'
  },
  // Height in pixels. Defaults to 44. The width is always '100%'.
  buttonHeight: 55
});

Test the integration

Before you go live, test each payment method integration. To determine a payment method’s browser compatibility, see supported browsers. If you use the Express Checkout Element within an iframe, the iframe must have the allow attribute set to payment *.

Caution

Don’t store real user data in sandbox Link accounts. Treat them as if they’re publicly available, because these test accounts are associated with your publishable key.

Currently, Link only works with credit cards, debit cards, and qualified US bank account purchases. Link requires domain registration.

You can create sandbox accounts for Link using any valid email address. The following table shows the fixed one-time passcode values that Stripe accepts for authenticating sandbox accounts:

ValueOutcome
Any other 6 digits not listed belowSuccess
000001Error, code invalid
000002Error, code expired
000003Error, max attempts exceeded

OptionalUse the Express Checkout Element with Stripe Connect

Connect platforms can use the Express Checkout Element with Checkout Sessions by including the connected account in the session.

  1. When creating the Checkout Session on your server, include the connected account:

    Command Line
    curl https://api.stripe.com/v1/checkout/sessions \
  -u sk_test_...: \
  -d "line_items[0][price]"="price_..." \
  -d "line_items[0][quantity]"=1 \
  -d "mode"="payment" \
  -d "ui_mode"="custom" \
  -d "return_url"="https://example.com/return" \
  -H "Stripe-Account: 
    {{CONNECTED_ACCOUNT_ID}}
    "

  2. Register all of the domains where you plan to show the Express Checkout Element.

Disclose Stripe to your customers

Stripe collects information on customer interactions with Elements to provide services to you, prevent fraud, and improve its services. This includes using cookies and IP addresses to identify which Elements a customer saw during a single checkout session. You’re responsible for disclosing and obtaining all rights and consents necessary for Stripe to use data in these ways. For more information, visit our privacy center.

See also

Was this page helpful?
YesNo