Stripe Express Checkout Element in React and Next.js: the wallet row first, then the card

For Apple Pay, Google Pay and Link buttons in React, use Stripe's ExpressCheckoutElement. It's free in @stripe/react-stripe-js, and the first section below has the whole file. This page also builds the common layout around it: wallet buttons on top, "or pay with card" under them, and Stripe's card fields inside an animated 3D card that shows the brand and flips for the CVC.

One payment$3

By buying you agree to the Terms.

One payment, no subscription
Download right after paying
Use it in client projects
Won't run on the listed stack? We fix it or refund you

Ready forCursorv0Lovableshadcn CLI

Full product pageReact · Tailwind · TypeScript

Use it in Next.js

app/pay/checkout.tsx

"use client";
import { useRef, useState } from "react";
import { useRouter } from "next/navigation";
import { loadStripe, type Appearance, type StripeExpressCheckoutElementConfirmEvent } from "@stripe/stripe-js";
import {
  Elements,
  ExpressCheckoutElement,
  CardNumberElement,
  CardExpiryElement,
  CardCvcElement,
  useStripe,
  useElements,
} from "@stripe/react-stripe-js";
import CardCheckout, { type CardFieldsSlot } from "@/components/CardCheckout";
import { createPaymentIntent } from "./actions";
import { plan } from "./plan";

const stripePromise = loadStripe(process.env.NEXT_PUBLIC_STRIPE_PUBLISHABLE_KEY!);

// The wallet buttons follow the Appearance API: on a dark theme Stripe picks light buttons.
const appearance: Appearance = { theme: "night", variables: { borderRadius: "12px" } };
// The split card fields don't read appearance. They take the older style option.
const cardStyle = { base: { color: "#F4F4F6", fontFamily: "JetBrains Mono, monospace", fontSize: "18px", "::placeholder": { color: "#6E6A8A" } } };

function PayForm() {
  const stripe = useStripe();
  const elements = useElements();
  const router = useRouter();
  const [wallets, setWallets] = useState(false); // stays false when this browser has no wallet to show
  const [walletError, setWalletError] = useState<string | null>(null);
  const done = useRef({ number: false, expiry: false, cvc: false }).current;
  const paid = (id: string) => setTimeout(() => router.push(`/thanks?pi=${id}`), 1200);

  // Apple Pay, Google Pay or Link: the buyer approved in the wallet's own sheet.
  const onWalletConfirm = async (event: StripeExpressCheckoutElementConfirmEvent) => {
    if (!stripe || !elements) return event.paymentFailed();
    const { error: submitError } = await elements.submit();
    if (submitError) return event.paymentFailed({ message: submitError.message });
    const { clientSecret } = await createPaymentIntent();
    const { error, paymentIntent } = await stripe.confirmPayment({
      elements,
      clientSecret,
      redirect: "if_required", // wallets finish on this page
      confirmParams: { return_url: `${window.location.origin}/thanks` },
    });
    if (error) return setWalletError(error.message ?? "The payment didn't go through.");
    paid(paymentIntent.id);
  };

  const cardFields = (slot: CardFieldsSlot) => {
    const track = (k: keyof typeof done) => (e: { complete: boolean; brand?: string }) => {
      done[k] = e.complete;
      slot.onChange({ complete: done.number && done.expiry && done.cvc, ...(e.brand ? { brand: e.brand } : {}) });
    };
    return (
      <>
        {/* Hidden until Stripe says a wallet can show, so nobody sees an empty row and a lonely divider. */}
        <div hidden={!wallets}>
          <ExpressCheckoutElement
            options={{
              buttonType: { applePay: "buy", googlePay: "buy" },
              buttonHeight: 44,
              layout: { maxColumns: 3, maxRows: 1, overflow: "auto" },
            }}
            onReady={({ availablePaymentMethods }) => setWallets(!!availablePaymentMethods)}
            onAvailablePaymentMethodsChange={({ paymentMethods }) => setWallets(!!paymentMethods)}
            onLoadError={() => setWallets(false)} // a bad key or a blocked script: the card still works
            // resolve() has to run within 1 second of the click, so keep this synchronous.
            onClick={(event) => event.resolve({ lineItems: [{ name: plan.name, amount: plan.amount }] })}
            onConfirm={onWalletConfirm}
            onCancel={() => setWalletError(null)}
          />
          {walletError && <p role="alert" className="m-0 mt-[8px] text-[14px] text-[#FF5C6C]">{walletError}</p>}
          <div className="my-[14px] flex items-center gap-[12px] text-[13px] text-[#8A8FA3]">
            <span className="h-px flex-1 bg-[#262A36]" />
            or pay with card
            <span className="h-px flex-1 bg-[#262A36]" />
          </div>
        </div>
        <div className="grid gap-[15px]">
          <div>
            <label className={slot.labelClassName}>Card number</label>
            <div className={slot.fieldClassName}><CardNumberElement options={{ style: cardStyle }} onChange={track("number")} /></div>
          </div>
          <div className="flex gap-[14px]">
            <div className="flex-1">
              <label className={slot.labelClassName}>Expiry</label>
              <div className={slot.fieldClassName}><CardExpiryElement options={{ style: cardStyle }} onChange={track("expiry")} /></div>
            </div>
            <div className="flex-1">
              <label className={slot.labelClassName}>CVC</label>
              <div className={slot.fieldClassName}>
                <CardCvcElement
                  options={{ style: cardStyle }}
                  onChange={track("cvc")}
                  onFocus={() => slot.onChange({ focus: "cvc" })} // flips the card
                  onBlur={() => slot.onChange({ focus: null })}
                />
              </div>
            </div>
          </div>
        </div>
      </>
    );
  };

  return (
    <CardCheckout
      amount={plan.amount / 100}
      currency="USD"
      productName={plan.name}
      resetAfter={null}
      renderCardFields={cardFields}
      // The card path: Pay was pressed and Stripe says all three fields are complete.
      onConfirm={async ({ name }) => {
        if (!stripe || !elements) throw new Error("Stripe hasn't loaded yet.");
        const card = elements.getElement(CardNumberElement);
        if (!card) throw new Error("Card field missing.");
        const { clientSecret } = await createPaymentIntent();
        const { error, paymentIntent } = await stripe.confirmCardPayment(clientSecret, {
          payment_method: { card, billing_details: { name } },
        });
        if (error) throw error; // the card shows Stripe's message and Pay comes back
        paid(paymentIntent.id);
      }}
    />
  );
}

export default function Checkout() {
  // Deferred mode: no PaymentIntent yet, so Elements gets the amount and currency up front.
  return (
    <Elements stripe={stripePromise} options={{ mode: "payment", amount: plan.amount, currency: plan.currency, appearance }}>
      <PayForm />
    </Elements>
  );
}

app/pay/actions.ts

"use server";
import Stripe from "stripe";
import { plan } from "./plan";

const stripe = new Stripe(process.env.STRIPE_SECRET_KEY!);

// Both ways to pay end here: the wallet row and the card form.
// The amount is set on the server, so a buyer can't change it in the browser.
export async function createPaymentIntent(): Promise<{ clientSecret: string }> {
  const intent = await stripe.paymentIntents.create({
    amount: plan.amount, // must match the amount on <Elements>
    currency: plan.currency,
    automatic_payment_methods: { enabled: true }, // cards, Apple Pay, Google Pay and Link
    metadata: { plan: "pro" },
  });
  return { clientSecret: intent.client_secret! };
}

app/pay/plan.ts

// What the buyer pays, in the smallest currency unit. The server action reads it; the browser only displays it.
export const plan = { name: "Pro plan", amount: 2900, currency: "usd" } as const;

app/pay/page.tsx

import Checkout from "./checkout";

// No PaymentIntent is created on page load. The server action makes one when the buyer pays.
export default function PayPage() {
  return (
    <main className="grid min-h-dvh place-items-center overflow-hidden bg-[#0b0a14] p-4">
      <Checkout />
    </main>
  );
}

Good to know

What the buyer sees: when Stripe says a wallet can show in this browser, the Apple Pay, Google Pay or Link buttons sit at the top of the form with "or pay with card" under them. When none can show, that row and the divider stay hidden and the card form looks the same as without wallets.
What the card can show: the number, expiry and CVC live in Stripe's iframes, so your page and your server never see the digits. The 3D card hears when each field is complete, which brand Stripe detected, and when the CVC field has focus. It lights up Pay, shows a Visa or Mastercard mark and flips for the CVC.
One server action for both ways to pay. The wallet path calls elements.submit(), then createPaymentIntent(), then stripe.confirmPayment with the same elements. The card path calls createPaymentIntent() and stripe.confirmCardPayment with the card number element. The amount lives in plan.ts on the server side, and the amount on <Elements> has to match it.
Stripe's docs say that with Apple Pay or Google Pay the billing details from the wallet win over any billing_details you pass in confirmParams. Read the wallet's values from the confirm event's billingDetails if you need them.
What we ran on October 26, 2026: these files type-checked and built (tsc --noEmit and next build, both exit 0) against @stripe/stripe-js 10.1.0, @stripe/react-stripe-js 7.0.0, stripe 23.0.1, next 15.5.28, react 19.1.1, framer-motion 11.18.2 and TypeScript 5.9.3, with the shipped CardCheckout source. Five deliberate mistakes failed the check, as they should: onConfirmed instead of onConfirm, buttonType applePay "pay" (not an Apple Pay type), resolve({ total }) in onClick, paymentFailed({ reason: "declined" }) and an import of PaymentRequestButtonElement.
In headless Chromium at 390 and 1440 px wide, with a placeholder publishable key, Stripe.js loaded and mounted the three card field iframes inside the card's field boxes. The Express Checkout Element failed to load with that key, onLoadError fired, and the wallet row stayed hidden, with 0 page errors and no sideways scroll. With three 44 px stand in buttons in the row, the form still ends 21 px above the bottom of the card's 660 px stage.
What we didn't run: we have no Stripe account on this test, so no wallet sheet opened, no PaymentIntent was created and nothing was paid. Headless Chromium has no Apple Pay or Google Pay, so we haven't seen Stripe's real buttons in the row. Test with your test keys over HTTPS on a registered domain before you ship.
The redirect to /thanks is not proof of payment. Fulfil orders from Stripe's payment_intent.succeeded webhook.
Set STRIPE_SECRET_KEY and NEXT_PUBLIC_STRIPE_PUBLISHABLE_KEY. The card is drawn on a fixed 1000 x 660 stage, so scale it on phones with the className or style props.

Stripe Express Checkout Element in React on its own

This is the free route, and for many stores it's the whole job. ExpressCheckoutElement ships in @stripe/react-stripe-js 7.0.0. One component shows Apple Pay, Google Pay, Link, PayPal, Klarna and Amazon Pay buttons, depending on the device, the browser and what you turned on in your Stripe Dashboard.
Elements runs in deferred mode here: you pass mode, amount and currency instead of a client secret, and the PaymentIntent is created only when the buyer approves in the wallet sheet. Stripe's guide recommends this order: "We recommend that you collect payment details before creating an Intent when using the Express Checkout Element."
onReady tells you which buttons could show. availablePaymentMethods is undefined when none can, so the file keeps the row hidden until then. Stripe's docs also offer the availablepaymentmethodschange event for the same check.
onClick opens the wallet sheet. You must call event.resolve within 1 second, so pass line items you already have instead of fetching them. onConfirm runs after the buyer approves: elements.submit(), then the server action, then stripe.confirmPayment. onCancel fires when the buyer closes the sheet.
On success Stripe sends the buyer to return_url. The error branch only runs on an immediate error, which matches the comment in Stripe's own React sample.

app/pay/express-checkout.tsx (free, no card)

"use client";
import { useState } from "react";
import { loadStripe } from "@stripe/stripe-js";
import { Elements, ExpressCheckoutElement, useStripe, useElements } from "@stripe/react-stripe-js";
import { createPaymentIntent } from "./actions";
import { plan } from "./plan";

const stripePromise = loadStripe(process.env.NEXT_PUBLIC_STRIPE_PUBLISHABLE_KEY!);

function WalletButtons() {
  const stripe = useStripe();
  const elements = useElements();
  const [visible, setVisible] = useState(false);
  const [message, setMessage] = useState<string | null>(null);

  return (
    <div hidden={!visible}>
      <ExpressCheckoutElement
        options={{
          buttonType: { applePay: "buy", googlePay: "buy" },
          buttonTheme: { applePay: "black", googlePay: "black" },
          buttonHeight: 48,
        }}
        // undefined means no button can show here: keep the row hidden and offer another way to pay.
        onReady={({ availablePaymentMethods }) => setVisible(!!availablePaymentMethods)}
        onLoadError={({ error }) => setMessage(error.message ?? "Wallet buttons couldn't load.")}
        onClick={(event) => event.resolve({ lineItems: [{ name: plan.name, amount: plan.amount }] })}
        onConfirm={async (event) => {
          if (!stripe || !elements) return event.paymentFailed();
          const { error: submitError } = await elements.submit();
          if (submitError) return event.paymentFailed({ message: submitError.message });
          const { clientSecret } = await createPaymentIntent();
          const { error } = await stripe.confirmPayment({
            elements,
            clientSecret,
            confirmParams: { return_url: `${window.location.origin}/thanks` },
          });
          // Only reached on an immediate error. On success Stripe sends the buyer to return_url.
          if (error) setMessage(error.message ?? "The payment didn't go through.");
        }}
        onCancel={() => setMessage(null)}
      />
      {message && <p role="alert">{message}</p>}
    </div>
  );
}

export default function ExpressCheckout() {
  return (
    <Elements stripe={stripePromise} options={{ mode: "payment", amount: plan.amount, currency: plan.currency }}>
      <WalletButtons />
    </Elements>
  );
}

Express Checkout Element options and events in @stripe/stripe-js 10.1.0

These are the option and event names in @stripe/stripe-js 10.1.0 and @stripe/react-stripe-js 7.0.0, read from their type definitions on October 26, 2026.
buttonType: per wallet. Apple Pay takes add-money, book, buy, check-out, contribute, donate, order, plain, reload, rent, subscribe, support, tip or top-up. Google Pay takes book, buy, checkout, donate, order, pay, plain or subscribe. PayPal takes paypal, buynow, checkout or pay. Stripe's docs say the defaults are buy for Google Pay and plain for Apple Pay.
buttonTheme: Apple Pay black, white or white-outline; Google Pay black or white; PayPal gold, blue, silver, white or black. Leave it out and Stripe picks from your Appearance settings, so a dark theme gets light buttons.
buttonHeight: Stripe's reference says 44 px by default and accepts 40 to 55 px. The width is always 100% of the container. Corner radius comes from the Appearance API's borderRadius variable.
layout: maxColumns, maxRows and overflow ("auto" or "never"). Stripe's docs say that when the row runs out of room, less relevant buttons can move into an overflow menu, and the layout option controls when that menu appears.
paymentMethods: per wallet, "auto" or "never", and Apple Pay and Google Pay also take "always". paymentMethodOrder takes a list of payment method types and overrides Stripe's own ordering. The older wallets option is marked deprecated in 10.1.0.
Collecting details: emailRequired, phoneNumberRequired, billingAddressRequired, shippingAddressRequired, allowedShippingCountries, shippingRates and lineItems. With shipping on, handle onShippingAddressChange and onShippingRateChange and call resolve or reject in each.
Events on the React component: onReady, onClick, onConfirm (required), onCancel, onEscape, onLoadError, onShippingAddressChange, onShippingRateChange and onAvailablePaymentMethodsChange. The confirm event carries billingDetails, shippingAddress, shippingRate, expressPaymentType and paymentFailed, whose reason is one of fail, invalid_shipping_address, invalid_billing_address, invalid_payment_data or address_unserviceable.

Why the Express Checkout Element buttons don't show

Most "the buttons don't show" reports come down to a short list. All of these are from Stripe's docs, read on October 26, 2026.
Plain HTTP. Stripe's guide says to serve the page over HTTPS "in development and in production" and suggests a tunnel such as ngrok for local work. On http://localhost Stripe.js itself warns in the console: "You are testing over HTTP, so Google Pay will not appear." We saw that line in our own test run.
The domain isn't registered. Apple Pay requires every domain that shows it to be registered on Stripe's Payment method domains page, subdomains included. A domain registered in live mode is registered in sandboxes too. Stripe handles Apple's merchant validation for you, so you don't need an Apple Merchant ID.
No wallet in the browser. Stripe's guide asks you to add a card to Google Pay or Apple Wallet first. Stripe's docs also say: "you can't force a Google Pay button to appear if your customer's device doesn't support Google Pay."
The browser. Per Stripe's support table, Apple Pay on Chrome, Edge, Firefox or Opera on desktop shows only when paymentMethods.applePay is "always", Chrome on Android has no Apple Pay, and Link isn't supported on desktop Firefox. Inside an iframe, the iframe's origin has to match the page's (Safari 17 and later accept allow="payment").
The payment method isn't on. Stripe uses your Dashboard's payment method settings. Apple Pay and Google Pay ride on the card type, and Link also needs card. If you narrow it with allowedPaymentMethodTypes on Elements, keep card in the list.
Country and currency: Stripe's docs say buttons only show in their supported countries, and "always" still won't show a wallet for an unsupported currency.
The script failed. A wrong publishable key ends in a load error. Without an onLoadError handler Stripe.js logs "Unhandled expressCheckout Element loaderror" (we saw this with a placeholder key). The files on this page handle it and keep the row hidden.

Express Checkout Element vs Payment Request Button

Stripe's Payment Request Button page is titled "[Deprecated] Payment Request Button" and points to the Express Checkout Element. It says the button "isn't supported in Stripe.js endive or later" and keeps working in earlier versions while they are supported.
The same page lists its limits: card payment methods only, Link only with card funding sources, and one payment option at a time. The Express Checkout Element can show several buttons at once and adds PayPal, Klarna and Amazon Pay.
In React that means PaymentRequestButtonElement and stripe.paymentRequest() become ExpressCheckoutElement inside an <Elements> provider. The @stripe/react-stripe-js 7.0.0 types no longer export PaymentRequestButtonElement: on October 26, 2026 an import of it failed our type check with "has no exported member". Stripe's migration guide covers the change.

Install

Copy from the zipPut react/src/components into src/, then npm i framer-motion stripe @stripe/stripe-js @stripe/react-stripe-js.
Or ask your AIPaste PROMPT.md into Cursor, Lovable or v0.

Props

renderCardFields: the wallet row, the divider and Stripe's split card fields
onConfirm: the card path: confirmCardPayment with the same server action; throw to show the error
amount / currency: what the card shows (Stripe charges the PaymentIntent)
resetAfter: null keeps the success state

How qodesign compares

qodesign vs 21st.dev21st.dev is best for: browsing a huge marketplace and copying many components a month.
qodesign vs Skiper UISkiper UI is best for: unusual interaction details for landing pages: image reveals, cursor trails, tooltips, drag-and-scroll galleries.

All comparisons, with prices read on each library's own site.

From the blog: Stripe Elements With a Custom Card Design in React and Next.js

Questions

Do I need the 3D card to use the Express Checkout Element?

No. ExpressCheckoutElement is free in @stripe/react-stripe-js, and the first section has a complete file without the card. The card is for the layout where wallet buttons sit above a card form you want to animate.

Why doesn't Apple Pay show in Chrome on my Mac?

Stripe's support table says Apple Pay on non Safari desktop browsers shows only when paymentMethods.applePay is set to "always". The page also has to be on HTTPS and on a domain you registered with Stripe.

Can I style the Express Checkout Element buttons?

Partly. Stripe's docs say you can't fully customize them because each wallet sets its own logo and colours. You can set buttonHeight (40 to 55 px), buttonTheme per wallet, buttonType for the label, and the corner radius through the Appearance API.

Express Checkout Element or Payment Request Button?

The Express Checkout Element. Stripe marks the Payment Request Button as deprecated and says it isn't supported in Stripe.js endive or later, and @stripe/react-stripe-js 7.0.0 no longer exports PaymentRequestButtonElement.

Is it safe for real payments?

Yes, with the slot as shown. Card numbers go straight into Stripe's iframes and never reach your code or your server. Wallet payments happen in the wallet's own sheet.

Can Cursor or v0 add it for me?

Yes. Each download has a PROMPT.md. Paste it into Cursor, Lovable, v0 or Claude Code and it fits the piece into your app.

Can I use it in client work?

Yes, in personal and client projects. You can't resell the code itself as a kit.