PayPal checkout in Next.js: the PayPal button and a 3D card form with react-paypal-js

The usual PayPal setup in a Next.js app: a Server Action creates the order, PayPal's button opens the PayPal window, and a second Server Action captures the order once the buyer approves. Nothing is paid until you capture. This page does it with @paypal/react-paypal-js 10 and PayPal's v6 SDK, then puts PayPal's card fields inside an animated 3D card under the button, so buyers without a PayPal account pay on the same page.

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 PayPal button and the 3D card, in the App Router

app/pay/checkout.tsx

"use client";
import { useEffect, useRef, useState, type RefObject } from "react";
import { useRouter } from "next/navigation";
import {
  PayPalProvider,
  PayPalOneTimePaymentButton,
  PayPalCardFieldsProvider,
  PayPalCardNumberField,
  PayPalCardExpiryField,
  PayPalCardCvvField,
  usePayPalCardFieldsOneTimePaymentSession,
  type EventPayload,
} from "@paypal/react-paypal-js/sdk-v6";
import CardCheckout, { type CardFieldsSlot } from "@/components/CardCheckout";
import { createPayPalOrder, capturePayPalOrder } from "./actions";

const AMOUNT = 10; // what the card shows; the server action sets what PayPal charges

// The card fields are PayPal iframes: style the input inside them here.
const style = {
  input: { color: "#F4F4F6", fontFamily: "monospace", fontSize: "19px", background: "transparent", border: "none", boxShadow: "none", padding: "0" },
  "input::placeholder": { color: "#4a4f61" },
};
const fill = { height: "100%" };

const brandOf = (e: EventPayload) => {
  const type = e.data.cards.length === 1 ? e.data.cards[0].type : null;
  return type === "master-card" ? "mastercard" : type;
};
const allValid = (e: EventPayload) => e.data.number.isValid && e.data.expiry.isValid && e.data.cvv.isValid;

type Outcome = { orderId?: string; error?: string };

function PayPalButton({ onError }: { onError: (message: string) => void }) {
  const router = useRouter();
  return (
    <PayPalOneTimePaymentButton
      type="pay"
      // The server creates the order. The browser only ever sees its id.
      createOrder={async () => ({ orderId: await createPayPalOrder() })}
      onApprove={async ({ orderId }) => {
        const { completed } = await capturePayPalOrder(orderId);
        if (!completed) return onError("PayPal didn't complete that payment. Try again or pay by card.");
        router.push(`/thanks?order=${orderId}`);
      }}
      onCancel={() => onError("Payment cancelled. Your cart is still here.")}
      onError={(e) => onError(e.message || "PayPal couldn't start. Try again.")}
    />
  );
}

function CardForm({ slot }: { slot: RefObject<CardFieldsSlot | null> }) {
  const router = useRouter();
  const { submit, submitResponse, error } = usePayPalCardFieldsOneTimePaymentSession();

  // submit() doesn't throw: its result lands in submitResponse or error.
  const waiting = useRef<((o: Outcome) => void) | null>(null);
  useEffect(() => {
    const done = waiting.current;
    if (!done || (!error && !submitResponse)) return;
    waiting.current = null;
    if (error) return done({ error: error.message });
    const { state, data } = submitResponse!;
    if (state === "succeeded") return done({ orderId: data.orderId });
    done({ error: state === "canceled" ? "The card check was cancelled. Try again." : data.message || "That card didn't go through." });
  }, [submitResponse, error]);

  return (
    <CardCheckout
      amount={AMOUNT}
      currency="USD"
      productName="Pro plan"
      resetAfter={null}
      renderCardFields={(s) => {
        slot.current = s;
        return (
          <div className="grid gap-[15px]">
            <div>
              <label className={s.labelClassName}>Card number</label>
              <div className={s.fieldClassName}><PayPalCardNumberField style={style} containerStyles={fill} placeholder="Card number" /></div>
            </div>
            <div className="flex gap-[14px]">
              <div className="flex-1">
                <label className={s.labelClassName}>Expiry</label>
                <div className={s.fieldClassName}><PayPalCardExpiryField style={style} containerStyles={fill} placeholder="MM/YY" /></div>
              </div>
              <div className="flex-1">
                <label className={s.labelClassName}>CVV</label>
                <div className={s.fieldClassName}><PayPalCardCvvField style={style} containerStyles={fill} placeholder="123" /></div>
              </div>
            </div>
          </div>
        );
      }}
      onConfirm={async ({ name }) => {
        const outcome = new Promise<Outcome>((resolve) => (waiting.current = resolve));
        await submit(createPayPalOrder(), { name }); // 3D Secure runs here when the card needs it
        const { orderId, error } = await outcome;
        if (!orderId) throw new Error(error);
        const { completed } = await capturePayPalOrder(orderId);
        if (!completed) throw new Error("The payment didn't go through. Try another card.");
        setTimeout(() => router.push(`/thanks?order=${orderId}`), 1200); // let the success state play
      }}
    />
  );
}

export default function Checkout({ clientToken }: { clientToken: string }) {
  const slot = useRef<CardFieldsSlot | null>(null);
  const [message, setMessage] = useState("");

  return (
    <PayPalProvider
      clientToken={clientToken}
      environment={process.env.NEXT_PUBLIC_PAYPAL_ENV === "production" ? "production" : "sandbox"}
      components={["paypal-payments", "card-fields"]}
      pageType="checkout"
    >
      <div className="mx-auto grid w-full max-w-[440px] gap-4">
        <PayPalButton onError={setMessage} />
        <p role="status" className="min-h-5 text-center text-sm text-red-400">{message}</p>
        <p className="text-center text-xs uppercase tracking-widest text-white/40">or pay by card</p>
        <PayPalCardFieldsProvider
          cardtypechange={(e) => slot.current?.onChange({ brand: brandOf(e) })}
          validitychange={(e) => slot.current?.onChange({ complete: allValid(e) })}
          focus={(e) => slot.current?.onChange({ focus: e.sender === "cvv" ? "cvc" : null })}
          blur={() => slot.current?.onChange({ focus: null })}
        >
          <CardForm slot={slot} />
        </PayPalCardFieldsProvider>
      </div>
    </PayPalProvider>
  );
}

app/pay/page.tsx

import { browserSafeClientToken } from "@/lib/paypal";
import Checkout from "./checkout";

// A fresh client token for every visit, so render this page on request.
export const dynamic = "force-dynamic";

export default async function PayPage() {
  const clientToken = await browserSafeClientToken();
  return (
    <main className="grid min-h-dvh place-items-center overflow-hidden bg-[#0b0a14] p-4">
      <Checkout clientToken={clientToken} />
    </main>
  );
}

app/pay/actions.ts (Server Actions: create and capture the order)

"use server";
import { paypalPost } from "@/lib/paypal";

type Order = { id?: string };
type Capture = {
  status?: string;
  purchase_units?: { payments?: { captures?: { id: string; status: string }[] } }[];
};

// The amount is set here, on the server. Never take it from the browser.
export async function createPayPalOrder(): Promise<string> {
  const { ok, data } = await paypalPost<Order>("/v2/checkout/orders", {
    intent: "CAPTURE",
    purchase_units: [{ amount: { currency_code: "USD", value: "10.00" } }],
  });
  if (!ok || !data.id) throw new Error("Couldn't start the payment.");
  return data.id;
}

// Approval only means the buyer said yes. The money moves when you capture.
export async function capturePayPalOrder(orderId: string) {
  if (!/^[A-Z0-9]+$/.test(orderId)) return { completed: false };
  const { ok, data } = await paypalPost<Capture>(`/v2/checkout/orders/${orderId}/capture`);
  const capture = data.purchase_units?.[0]?.payments?.captures?.[0];
  // A capture can come back PENDING (an eCheck, a review). Ship on COMPLETED only.
  return { completed: ok && data.status === "COMPLETED" && capture?.status === "COMPLETED", captureId: capture?.id };
}

lib/paypal.ts (server only: tokens and the REST calls)

import "server-only";

const BASE = process.env.PAYPAL_API_BASE ?? "https://api-m.sandbox.paypal.com"; // https://api-m.paypal.com when live

async function token(form: string) {
  const basic = Buffer.from(`${process.env.PAYPAL_CLIENT_ID}:${process.env.PAYPAL_CLIENT_SECRET}`).toString("base64");
  const res = await fetch(`${BASE}/v1/oauth2/token`, {
    method: "POST",
    headers: { Authorization: `Basic ${basic}`, "Content-Type": "application/x-www-form-urlencoded" },
    body: form,
    cache: "no-store",
  });
  if (!res.ok) throw new Error(`PayPal token request failed (${res.status})`);
  return ((await res.json()) as { access_token: string }).access_token;
}

/** Browser-safe token for <PayPalProvider clientToken>. */
export const browserSafeClientToken = () =>
  token("grant_type=client_credentials&response_type=client_token&intent=sdk_init");

/** POST to a PayPal REST API with a full-scope token (server only). */
export async function paypalPost<T>(path: string, body?: unknown): Promise<{ ok: boolean; data: T }> {
  const access = await token("grant_type=client_credentials&response_type=token");
  const res = await fetch(`${BASE}${path}`, {
    method: "POST",
    headers: { Authorization: `Bearer ${access}`, "Content-Type": "application/json" },
    body: body === undefined ? undefined : JSON.stringify(body),
    cache: "no-store",
  });
  return { ok: res.ok, data: (await res.json()) as T };
}

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

import { paypalPost } from "@/lib/paypal";

// PayPal signs every webhook. Ask PayPal to check the signature before you trust the event.
export async function POST(req: Request) {
  const raw = await req.text();
  const h = req.headers;
  const { ok, data } = await paypalPost<{ verification_status?: string }>("/v1/notifications/verify-webhook-signature", {
    auth_algo: h.get("paypal-auth-algo"),
    cert_url: h.get("paypal-cert-url"),
    transmission_id: h.get("paypal-transmission-id"),
    transmission_sig: h.get("paypal-transmission-sig"),
    transmission_time: h.get("paypal-transmission-time"),
    webhook_id: process.env.PAYPAL_WEBHOOK_ID, // from the app's Webhooks list in the developer dashboard
    webhook_event: JSON.parse(raw),
  });
  if (!ok || data.verification_status !== "SUCCESS") return new Response("bad signature", { status: 400 });

  const event = JSON.parse(raw) as { event_type: string; resource: { id: string; status?: string } };
  if (event.event_type === "PAYMENT.CAPTURE.COMPLETED") {
    // Mark the order paid here. PayPal can send an event more than once: key on resource.id.
  }
  return new Response("ok");
}

Good to know

Two steps, two server calls. createOrder runs when the buyer clicks the PayPal button: your server creates the order and returns its id. onApprove runs when the buyer says yes in the PayPal window: that is only a promise to pay. The money moves when your server calls capture, and the capture's status is what you trust.
Check the capture, not just the HTTP status. A capture can come back PENDING (an eCheck, a payment under review), so the action ships on status COMPLETED for both the order and purchase_units[0].payments.captures[0]. Keep the capture id: refunds use it.
The amount lives on the server. createPayPalOrder sets value "10.00" itself and takes nothing from the browser. AMOUNT in checkout.tsx is only what the card prints. PayPal's value is a string with two decimals in the currency's major unit, so an amount of 10 is "10.00", not 1000 in cents.
One provider, two components. PayPalProvider loads the SDK once with components ["paypal-payments", "card-fields"]: the button and the card fields share it and share your two Server Actions. The card fields send the same order through submit(), which runs 3D Secure when the card asks for it, and the same capture finishes it.
environment is required in v6. A live client id still loads the sandbox SDK if you pass environment="sandbox". The snippet reads NEXT_PUBLIC_PAYPAL_ENV; the server side switches with PAYPAL_API_BASE (api-m.sandbox.paypal.com or api-m.paypal.com).
The client token is minted per page view on the server with response_type=client_token and intent=sdk_init, so the page is force-dynamic. PAYPAL_CLIENT_SECRET never leaves lib/paypal.ts, and server-only makes the build fail if a client file imports it.
The PayPal button is PayPal's own web component, so it keeps PayPal's look: type picks the label (pay, checkout, buynow, donate, subscribe). Don't restyle it into your own button. The card under it is where your design goes.
What the 3D card shows: the number, expiry and CVV stay in PayPal's iframes. The card hears the brand from cardtypechange, which fields are valid from validitychange, and focus on the CVV, which flips it. It draws Visa and Mastercard marks; other brands still pay without a logo.

The older PayPalButtons API (v5 SDK) still works

Most tutorials for "react paypal button" use PayPalScriptProvider and PayPalButtons. Those are still exported from the package root in react-paypal-js 10 and load PayPal's v5 JS SDK with your client id. The shape is almost the same, with two small differences the types catch: createOrder returns the order id as a string, and onApprove gets data.orderID with a capital D.
The Server Actions above work unchanged with it, as the snippet shows. New code should start on the v6 import, @paypal/react-paypal-js/sdk-v6, which is what PayPal's current docs use and what card fields need here. Don't mix both SDKs on one page.
Coming from react-paypal-button-v2? Its last release, 2.6.3, is from February 2021 and lists React up to 17 as peers. Replace it with PayPalOneTimePaymentButton (or PayPalButtons if you stay on v5) and move order creation to the server, which the old package left to the browser.

app/pay/classic-buttons.tsx (v5 PayPalButtons, same Server Actions)

"use client";
// The older API, still exported from the package root: PayPal's v5 JS SDK and <PayPalButtons>.
import { PayPalScriptProvider, PayPalButtons } from "@paypal/react-paypal-js";
import { createPayPalOrder, capturePayPalOrder } from "./actions";

export default function ClassicButtons() {
  return (
    <PayPalScriptProvider options={{ clientId: process.env.NEXT_PUBLIC_PAYPAL_CLIENT_ID!, currency: "USD", intent: "capture" }}>
      <PayPalButtons
        style={{ layout: "vertical", shape: "rect", label: "pay" }}
        createOrder={() => createPayPalOrder()}
        onApprove={async ({ orderID }) => {
          const { completed } = await capturePayPalOrder(orderID);
          if (!completed) throw new Error("Payment not completed");
        }}
      />
    </PayPalScriptProvider>
  );
}

Webhooks: when the buyer closes the tab after paying

The capture in onApprove covers almost every payment, but the buyer can close the tab between approving and your capture response, and some captures finish later. Subscribe your app to PAYMENT.CAPTURE.COMPLETED (and PAYMENT.CAPTURE.DENIED) in the developer dashboard and fulfil from the webhook too, keyed on the capture id so a repeat event does nothing.
PayPal signs each webhook. The route reads the raw body, then asks PayPal's verify-webhook-signature endpoint with the five paypal-* headers and your webhook id, and only trusts the event when verification_status is SUCCESS. Read the body as text once and parse it yourself; don't let anything rewrite it first.

How this differs from the PayPal Card Fields guide

The Card Fields guide is about the card form alone, with the order and capture in route handlers. This page is the whole PayPal checkout: the PayPal button first, card fields as the second way to pay, and both calling the same Server Actions, plus the v5 API, the capture status check and the webhook.

PayPal Card Fields in React

Install

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

Props

renderCardFields: PayPal's card fields inside the design
onConfirm: submit the card fields, capture on your server; throw to show the error
amount / currency: what the card shows (PayPal charges the order amount)
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

Does the 3D card see the card number?

No. The number, expiry and CVV stay in PayPal's iframes. The card only hears the brand, which fields are valid and when the CVV has focus.

Do I need Server Actions, or can I use route handlers?

Either works. The page uses Server Actions because createOrder and onApprove only need a function that returns a promise. Route handlers are better when something other than your own pages calls them, like the webhook.

sdk-v6 or the package root?

New code: @paypal/react-paypal-js/sdk-v6 with PayPalProvider and PayPalOneTimePaymentButton. The root export (PayPalScriptProvider, PayPalButtons) loads the older v5 SDK and is fine for an app that already uses it.

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

react-paypal-js 10.6.1 lists React 16.8 to 19 as peers. Every snippet here type-checks and builds with React 19.1 and Next.js 15.5. We didn't run a payment against a PayPal sandbox 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.