Stripe Payment Element in Next.js: a working App Router example, then a 3D card around it

The Payment Element is Stripe's one form for cards, wallets and local payment methods. Here it is in a Next.js App Router app the way Stripe now suggests: the form renders before any PaymentIntent exists, a Server Action creates the PaymentIntent when the buyer presses Pay, and a webhook marks the order paid. The plain form is free and shown in full. Then the same Payment Element goes inside an animated 3D card that shows the card brand as the buyer types.

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

The Payment Element inside the 3D card, in the App Router

app/pay/checkout.tsx

"use client";
import { useRouter } from "next/navigation";
import { loadStripe, type Appearance } from "@stripe/stripe-js";
import { Elements, PaymentElement, useElements, useStripe } from "@stripe/react-stripe-js";
import CardCheckout from "@/components/CardCheckout";
import { createPaymentIntent } from "./actions";

// Outside the component, so Stripe.js loads once.
const stripePromise = loadStripe(process.env.NEXT_PUBLIC_STRIPE_PUBLISHABLE_KEY!);

// Free: Stripe's Appearance API, set to the card's dark colours.
const appearance: Appearance = {
  theme: "night",
  labels: "above",
  variables: {
    colorPrimary: "#C6FF3D",
    colorBackground: "#0d0e13",
    colorText: "#F4F4F6",
    colorDanger: "#FF5C6C",
    fontFamily: "Space Grotesk, system-ui, sans-serif",
    borderRadius: "14px",
  },
  rules: {
    ".Input": { border: "1px solid #2a2e3b", fontSize: "16px" },
    ".Input:focus": { borderColor: "#C6FF3D", boxShadow: "0 0 0 4px rgba(198, 255, 61, 0.14)" },
    ".Tab--selected": { borderColor: "#C6FF3D" },
  },
};

type Props = { amount: number; currency: string; productName: string };

function PaymentForm({ amount, currency, productName }: Props) {
  const stripe = useStripe();
  const elements = useElements();
  const router = useRouter();

  return (
    <CardCheckout
      amount={amount / 100}
      currency={currency.toUpperCase()}
      productName={productName}
      resetAfter={null}
      renderCardFields={(slot) => (
        <PaymentElement
          options={{
            layout: "tabs",
            // The card already asks for the name, so Stripe doesn't ask twice.
            fields: { billingDetails: { name: "never" } },
          }}
          onChange={(e) => slot.onChange({ complete: e.complete })}
          onReady={(element) => {
            // React Stripe.js 7.0.0 has no prop for this event, so attach it here.
            element.on("carddetailschange", (e) => slot.onChange({ brand: e.details?.brands?.[0] ?? null }));
          }}
        />
      )}
      onConfirm={async ({ name }) => {
        if (!stripe || !elements) throw new Error("Stripe hasn't loaded yet.");

        // 1. Validate the form and collect wallet data. Call it before any await on your server.
        const { error: submitError } = await elements.submit();
        if (submitError) throw submitError;

        // 2. Create the PaymentIntent now, on the server.
        const clientSecret = await createPaymentIntent();

        // 3. Confirm. 3D Secure runs here when the card asks for it.
        const { error, paymentIntent } = await stripe.confirmPayment({
          elements,
          clientSecret,
          redirect: "if_required", // cards stay on the page, redirect methods leave and come back
          confirmParams: {
            return_url: `${window.location.origin}/pay/complete`,
            payment_method_data: { billing_details: { name } },
          },
        });
        if (error) throw error; // the card shows Stripe's message and Pay comes back

        setTimeout(() => router.push(`/pay/complete?payment_intent=${paymentIntent.id}`), 1200);
      }}
    />
  );
}

export default function Checkout(props: Props) {
  return (
    // Deferred intent: Elements renders from mode, amount and currency, before any PaymentIntent exists.
    <Elements stripe={stripePromise} options={{ mode: "payment", amount: props.amount, currency: props.currency, appearance }}>
      <PaymentForm {...props} />
    </Elements>
  );
}

app/pay/page.tsx

import { PLAN } from "@/lib/plan";
import Checkout from "./checkout";

// No PaymentIntent on page load, so this page can be static.
export default function PayPage() {
  return (
    <main className="grid min-h-dvh place-items-center overflow-hidden bg-[#0b0a14] p-4">
      <Checkout amount={PLAN.amount} currency={PLAN.currency} productName={PLAN.name} />
    </main>
  );
}

lib/plan.ts and lib/stripe.ts (server only)

// lib/plan.ts
// One place for what you sell. The page shows it, the Server Action charges it.
export const PLAN = { id: "pro", name: "Pro plan", amount: 1000, currency: "usd" } as const; // amount in cents

// lib/stripe.ts
import "server-only";
import Stripe from "stripe";

// The secret key stays on the server. server-only fails the build if a client file imports this.
export const stripe = new Stripe(process.env.STRIPE_SECRET_KEY!);

app/pay/actions.ts (Server Action: create the PaymentIntent on Pay)

"use server";
import { stripe } from "@/lib/stripe";
import { PLAN } from "@/lib/plan";

// Runs when the buyer presses Pay, not when the page loads.
// The amount comes from the server. Never take it from the browser.
export async function createPaymentIntent(): Promise<string> {
  const intent = await stripe.paymentIntents.create({
    amount: PLAN.amount,
    currency: PLAN.currency,
    automatic_payment_methods: { enabled: true }, // the methods you turned on in the Dashboard
    metadata: { plan: PLAN.id },
  });
  if (!intent.client_secret) throw new Error("Couldn't start the payment.");
  return intent.client_secret;
}

app/pay/complete/page.tsx (where redirect methods come back)

import Link from "next/link";
import { stripe } from "@/lib/stripe";

const MESSAGES: Record<string, string> = {
  succeeded: "Payment received. Thanks!",
  processing: "Your payment is processing. We'll email you when it clears.",
  requires_payment_method: "That payment didn't go through. Try another method.",
};

// Stripe sends redirect methods back here with ?payment_intent=pi_...
// Read the status from Stripe, not from the URL. Fulfil in the webhook, not here.
export default async function Complete({ searchParams }: { searchParams: Promise<{ payment_intent?: string }> }) {
  const { payment_intent } = await searchParams;
  if (!payment_intent?.startsWith("pi_")) return <p>No payment found.</p>;

  const intent = await stripe.paymentIntents.retrieve(payment_intent);
  return (
    <main className="grid min-h-dvh place-items-center p-6 text-center">
      <p>{MESSAGES[intent.status] ?? "Something went wrong."}</p>
      {intent.status === "requires_payment_method" && <Link href="/pay">Back to checkout</Link>}
    </main>
  );
}

app/api/stripe/webhook/route.ts (verify the signature, then fulfil)

import type Stripe from "stripe";
import { stripe } from "@/lib/stripe";

// Stripe signs every webhook. Check the signature on the raw body before you trust the event.
export async function POST(req: Request) {
  const body = await req.text();
  const signature = req.headers.get("stripe-signature");
  if (!signature) return new Response("missing signature", { status: 400 });

  let event: Stripe.Event;
  try {
    event = stripe.webhooks.constructEvent(body, signature, process.env.STRIPE_WEBHOOK_SECRET!);
  } catch {
    return new Response("bad signature", { status: 400 });
  }

  if (event.type === "payment_intent.succeeded") {
    const intent = event.data.object;
    // Fulfil here: mark intent.metadata.plan paid. Stripe can send an event twice, so key on intent.id.
    console.log("paid", intent.id, intent.amount_received);
  }
  if (event.type === "payment_intent.payment_failed") {
    // Optional: email the buyer. intent.last_payment_error?.message says why.
  }
  return new Response("ok");
}

Good to know

The order of the three steps matters. elements.submit() checks the form and collects wallet details, then your Server Action creates the PaymentIntent, then confirmPayment sends the payment. Stripe's deferred intent docs put submit() first, before your own server call, so keep it the first await in the click.
No PaymentIntent on page load. Elements starts from mode, amount and currency, so every visit doesn't leave an unused PaymentIntent in your Dashboard, and /pay can be a static page. The intent is created only when someone actually presses Pay.
The amount lives on the server. createPaymentIntent reads PLAN and takes nothing from the browser. The amount passed to Elements is for display: Stripe's types say it is shown in Apple Pay, Google Pay and buy now pay later screens and changes which methods appear. Both read the same PLAN here, so they can't drift apart. Amounts are in the smallest unit: 1000 is 10.00 USD.
automatic_payment_methods: { enabled: true } means the Payment Element offers the methods you turned on under Settings, Payment methods in the Dashboard, filtered by currency, amount and the buyer's device. If you create the intent with payment_method_types: ["card"], you only get cards.
redirect: "if_required" keeps card payments on your page, so the card can play its success state. Methods that need a bank page (iDEAL, for example) still leave and come back to return_url with ?payment_intent=pi_... in the URL. The return page reads the status from Stripe instead of trusting the URL.
Fulfil in the webhook, not on the return page. The buyer can close the tab after paying, and some methods stay processing for days. payment_intent.succeeded is the event to ship on, and the handler keys on the intent id because Stripe can send the same event more than once.
What the 3D card shows: the number, expiry and CVC stay in Stripe's iframe. The card hears complete from onChange and the brand from carddetailschange, which React Stripe.js 7.0.0 has no prop for, so the file attaches it in onReady. The card can't flip for the CVC: the Payment Element's focus event only says the Element has focus, not which field.
fields.billingDetails.name: "never" stops the Payment Element from asking for a name the card already asks for. When you hide a field like that, Stripe expects it in confirmParams, which is why onConfirm passes billing_details.name.

The free route: the Payment Element in a plain form

If you don't need a designed card, this is the whole job, and it costs nothing beyond Stripe's fees. The same Server Action, the same return page and the same webhook work with it. It uses the accordion layout and lets confirmPayment always redirect to return_url, so success is handled in one place, the return page.
Two things people trip on. First, confirmPayment only resolves on an error when it redirects: on success the browser is already leaving, so the code after it is the error path. Second, the button stays disabled until useStripe() returns the Stripe object, because loadStripe is async.

app/pay/plain-form.tsx (no paid piece)

"use client";
// The free route: the Payment Element in a plain form, no paid piece. Same Server Action.
import { useState, type FormEvent } from "react";
import { loadStripe } from "@stripe/stripe-js";
import { Elements, PaymentElement, useElements, useStripe } from "@stripe/react-stripe-js";
import { createPaymentIntent } from "./actions";

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

function Form() {
  const stripe = useStripe();
  const elements = useElements();
  const [message, setMessage] = useState("");
  const [busy, setBusy] = useState(false);

  async function onSubmit(e: FormEvent) {
    e.preventDefault();
    if (!stripe || !elements) return;
    setBusy(true);
    const { error: submitError } = await elements.submit();
    if (submitError) {
      setMessage(submitError.message ?? "Check the form.");
      return setBusy(false);
    }

    const clientSecret = await createPaymentIntent();
    const { error } = await stripe.confirmPayment({
      elements,
      clientSecret,
      confirmParams: { return_url: `${window.location.origin}/pay/complete` }, // always redirects
    });
    // Only reached on an error: on success the browser is already on its way to return_url.
    setMessage(error.message ?? "The payment didn't go through.");
    setBusy(false);
  }

  return (
    <form onSubmit={onSubmit} className="grid gap-4">
      <PaymentElement options={{ layout: "accordion" }} />
      <button disabled={!stripe || busy} className="rounded-lg bg-black px-4 py-3 text-white disabled:opacity-50">
        {busy ? "Paying..." : "Pay"}
      </button>
      <p role="status" className="text-sm text-red-600">{message}</p>
    </form>
  );
}

export default function PlainCheckout({ amount, currency }: { amount: number; currency: string }) {
  return (
    <Elements stripe={stripePromise} options={{ mode: "payment", amount, currency }}>
      <Form />
    </Elements>
  );
}

Payment Element options worth knowing, and how to hide Link

These are the options on the PaymentElement itself, as typed in @stripe/stripe-js 10.1.0. layout takes "tabs", "accordion" or "auto", or an object for the accordion with defaultCollapsed, radios, spacedAccordionItems and visibleAccordionItemsCount. paymentMethodOrder sets which method comes first. fields hides billing fields you already collect; anything set to "never" has to be passed in confirmParams instead. terms hides the mandate text per method, defaultValues prefills billing details, and business overrides the business name Stripe shows.
Hiding Link: wallets takes applePay, googlePay and link, each "auto" or "never", so link: "never" turns it off in this one form. To turn Link off for the whole account, switch it off under Settings, Payment methods in the Dashboard. We type-checked these options but didn't render them against a Stripe account, so we haven't seen each one on screen.
Apple Pay and Google Pay show up only on a device and browser that support them, over HTTPS, and Apple Pay also needs your domain added under payment method domains in the Dashboard. A wallet missing on localhost is normal.

app/pay/options.ts (StripePaymentElementOptions)

import type { StripePaymentElementOptions } from "@stripe/stripe-js";

// Options from @stripe/stripe-js 10.1.0. Pass them as <PaymentElement options={paymentOptions} />.
export const paymentOptions: StripePaymentElementOptions = {
  layout: { type: "accordion", defaultCollapsed: false, radios: "if_multiple", spacedAccordionItems: true },
  paymentMethodOrder: ["card", "apple_pay", "google_pay"], // first in the list, first on screen
  wallets: { applePay: "auto", googlePay: "auto", link: "never" }, // hide the Link button here
  fields: { billingDetails: { name: "never", email: "auto" } }, // "never" means you pass it in confirmParams
  terms: { card: "never" }, // hide the mandate text for cards
  defaultValues: { billingDetails: { email: "[email protected]" } }, // prefill from your user record
  business: { name: "Acme" }, // the name Stripe shows in mandates
};

Payment Element vs Stripe Checkout (and the Express Checkout Element)

Stripe Checkout, hosted or embedded, is a whole page Stripe runs: line items, tax, discount codes and receipts come with it, and you style it within its settings. The Payment Element is only the payment part, inside your own page: you build the order summary, the totals and the button, and you control the layout around it. The Express Checkout Element is just the wallet buttons (Apple Pay, Google Pay, Link, PayPal and others) and pairs with either.
Pick Checkout when you want the least code and Stripe's page is fine. Pick the Payment Element when the checkout has to look like the rest of your app, or when it sits inside a page with other things on it. Embedded Checkout in Next.js has its own guide, linked below.

Stripe Embedded Checkout in Next.js

Webhooks: test them locally with the Stripe CLI

Run stripe listen --forward-to localhost:3000/api/stripe/webhook. The CLI prints a signing secret that starts with whsec_: put it in STRIPE_WEBHOOK_SECRET for local runs, and use the secret from the Dashboard's webhook endpoint in production. stripe trigger payment_intent.succeeded sends a test event.
The route reads the body with req.text() and hands that exact string to constructEvent. If anything parses the body as JSON first, the signature check fails. In the App Router a route handler gets the raw body, so no extra config is needed.

How this differs from the Stripe Elements card form guide

The card form guide uses Stripe's split card fields (number, expiry and CVC as three Elements), so the 3D card can flip for the CVC, and creates the PaymentIntent when the page loads. This page is the Payment Element with the PaymentIntent created on Pay: you keep wallets and local methods, and give up the CVC flip. Its customization section covers what the Appearance API can and can't change.

Stripe Payment Element customization

Install

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

Props

renderCardFields: the Payment Element inside the design
onConfirm: submit, create the PaymentIntent, confirm; throw to show Stripe's message
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 have to create the PaymentIntent when the page loads?

No. With mode, amount and currency on Elements (the deferred intent flow) the Payment Element renders first, and a Server Action creates the PaymentIntent when the buyer presses Pay. The older flow, a clientSecret passed to Elements on page load, still works.

Why does the Payment Element only show cards?

It shows the methods turned on in your Dashboard that fit the currency, the amount and the buyer's device. Create the PaymentIntent with automatic_payment_methods enabled, not payment_method_types: ["card"], and turn methods on under Settings, Payment methods.

Can the 3D card flip for the CVC with the Payment Element?

No. The Payment Element doesn't say which of its fields has focus, so the card shows the brand but doesn't flip. If the flip matters more than wallets, use Stripe's split card fields, as in the Stripe Elements card form guide.

Does it work with React 19 and Next.js 15?

@stripe/react-stripe-js 7.0.0 lists React 16.8 to 19 as peers and needs @stripe/stripe-js 10. Every snippet here type-checks and builds with React 19.1, Next.js 15.5 and stripe 23.0.1. We didn't run a payment against a Stripe account.

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.