Square Web Payments SDK in React: the wrapper first, then the Card in a 3D checkout

If you just want to take cards with Square in React, use react-square-web-payments-sdk: a PaymentForm and a CreditCard component, free, with Square's own card form and pay button. This page starts there, then shows the same Card with @square/web-sdk directly in the Next.js App Router, with a typed server action that charges the token. Last, it puts the Card inside an animated 3D card that shows the brand and flips for the CVV, driven by Square's own events.

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 { useEffect, useRef, useState } from "react";
import { useRouter } from "next/navigation";
import { payments, type Card, type CardClassSelectors, type CardInputEvent, type SqEvent } from "@square/web-sdk";
import CardCheckout, { type CardFieldsSlot } from "@/components/CardCheckout";
import { charge } from "./actions";

// Square styles the inside of its iframe with a fixed set of selectors and a few properties each:
// text on input, borders on .input-container, colours on the error message.
const style: CardClassSelectors = {
  input: { backgroundColor: "#0d0e13", color: "#F4F4F6", fontSize: "16px" },
  "input::placeholder": { color: "#4a4f61" },
  ".input-container": { borderColor: "#262A36", borderRadius: "14px" },
  ".input-container.is-focus": { borderColor: "#C6FF3D" },
  ".input-container.is-error": { borderColor: "#FF5C6C" },
  ".message-text.is-error": { color: "#FF5C6C" },
};

// Square's field names to the three the 3D card knows. The postal code keeps the front side up.
const focusOf: Record<string, "number" | "expiry" | "cvc" | null> = {
  cardNumber: "number",
  expirationDate: "expiry",
  cvv: "cvc",
  postalCode: null,
};

function SquareCard({ slot, appId, locationId, onReady }: {
  slot: CardFieldsSlot;
  appId: string;
  locationId: string;
  onReady: (card: Card | null) => void;
}) {
  const box = useRef<HTMLDivElement>(null);
  const [failed, setFailed] = useState(false);

  useEffect(() => {
    let gone = false;
    let card: Card | undefined;
    const valid: Record<string, boolean> = { cardNumber: false, expirationDate: false, cvv: false };

    // Square has no per keystroke change event. Its events fire on focus, blur, error and brand
    // changes, and each one carries the field's currentState.
    const track = (e: SqEvent<CardInputEvent>) => {
      const { field, currentState } = e.detail;
      if (field in valid) valid[field] = currentState.isCompletelyValid;
      slot.onChange({ complete: valid.cardNumber && valid.expirationDate && valid.cvv });
    };

    (async () => {
      try {
        const sq = await payments(appId, locationId);
        // Strict Mode runs this effect twice in dev. The first run stops here, before it builds a card.
        if (!sq || gone) return;
        const created = await sq.card({ style });
        if (gone) return void created.destroy();
        card = created;
        // cardBrand is "VISA", "MASTERCARD", "AMERICAN_EXPRESS" and so on.
        card.addEventListener("cardBrandChanged", (e) => slot.onChange({ brand: e.detail.cardBrand.toLowerCase() }));
        card.addEventListener("focusClassAdded", (e) => slot.onChange({ focus: focusOf[e.detail.field] ?? null }));
        card.addEventListener("focusClassRemoved", (e) => {
          track(e);
          slot.onChange({ focus: null });
        });
        card.addEventListener("errorClassAdded", track);
        card.addEventListener("errorClassRemoved", track);
        await card.attach(box.current!);
        if (!gone) onReady(card);
      } catch {
        if (!gone) setFailed(true);
      }
    })();

    return () => {
      gone = true;
      onReady(null);
      void card?.destroy();
    };
  }, [appId, locationId, slot, onReady]);

  // One iframe holds number, expiry, CVV and postal code. Square draws its own borders inside it.
  return (
    <div>
      <label className={slot.labelClassName}>Card</label>
      <div ref={box} className="min-h-[54px]" />
      {failed && <p role="alert" className="text-sm text-[#FF5C6C]">The card form didn't load. Refresh to try again.</p>}
    </div>
  );
}

// The checkout is a fixed 1000 x 660 scene. Scale it down to the width you give it, as the README says.
function useFit() {
  const box = useRef<HTMLDivElement>(null);
  const [scale, setScale] = useState(1);
  useEffect(() => {
    const ro = new ResizeObserver(([entry]) => setScale(Math.min(1, entry.contentRect.width / 1000)));
    ro.observe(box.current!);
    return () => ro.disconnect();
  }, []);
  return { box, scale };
}

export default function SquareCheckout({ appId, locationId, amount }: { appId: string; locationId: string; amount: number }) {
  const router = useRouter();
  const { box, scale } = useFit();
  const card = useRef<Card | null>(null);
  const setCard = useRef((c: Card | null) => (card.current = c)).current;

  return (
    <div ref={box} className="w-full max-w-[1000px] overflow-hidden" style={{ height: 660 * scale }}>
    <CardCheckout
      className="origin-top-left"
      style={{ transform: `scale(${scale})` }}
      amount={amount}
      currency="USD"
      resetAfter={null}
      renderCardFields={(slot) => <SquareCard slot={slot} appId={appId} locationId={locationId} onReady={setCard} />}
      onConfirm={async ({ name }) => {
        if (!card.current) throw new Error("The card form hasn't loaded yet.");
        // Passing verification details lets Square run its buyer checks (SCA) inside tokenize().
        const result = await card.current.tokenize({
          amount: amount.toFixed(2),
          currencyCode: "USD",
          intent: "CHARGE",
          billingContact: { givenName: name },
          customerInitiated: true,
          sellerKeyedIn: false,
        });
        if (result.status !== "OK") {
          const first = "errors" in result ? result.errors[0]?.message : undefined;
          throw new Error(first ?? "Check the card details and try again.");
        }
        const paid = await charge(result.token, crypto.randomUUID());
        if (!paid.ok) throw new Error(paid.error);
        setTimeout(() => router.push(`/thanks?payment=${paid.id}`), 1200); // let the success state play
      }}
    />
    </div>
  );
}

app/pay/page.tsx

import SquareCheckout from "./checkout";

// Read the ids per request, so one build works in sandbox and production.
export const dynamic = "force-dynamic";

export default function PayPage() {
  // Both ids are public: they identify your app and location, they can't charge anything.
  return (
    <SquareCheckout
      appId={process.env.SQUARE_APPLICATION_ID!}
      locationId={process.env.SQUARE_LOCATION_ID!}
      amount={10}
    />
  );
}

app/pay/actions.ts

"use server";
import { SquareError } from "square";
import { square } from "@/lib/square";

type Charge = { ok: true; id: string } | { ok: false; error: string };

export async function charge(token: string, idempotencyKey: string): Promise<Charge> {
  try {
    const { payment } = await square().payments.create({
      sourceId: token,
      idempotencyKey, // the same key on a retry means Square charges once
      // Set on the server, never by the browser. Money amounts are bigint, in the smallest unit.
      amountMoney: { amount: BigInt(1000), currency: "USD" },
      locationId: process.env.SQUARE_LOCATION_ID,
    });
    if (payment?.id && payment.status !== "FAILED") return { ok: true, id: payment.id };
    return { ok: false, error: "That card didn't go through." };
  } catch (err) {
    // A declined card comes back as a SquareError. errors[0].code says why, e.g. CVV_FAILURE.
    if (err instanceof SquareError) return { ok: false, error: err.errors[0]?.detail ?? "That card didn't go through." };
    throw err;
  }
}

lib/square.ts

import { SquareClient, SquareEnvironment } from "square";

// Server only. The access token never reaches the browser.
// Built on first use, so next build doesn't need your keys.
let client: SquareClient | undefined;

export function square() {
  return (client ??= new SquareClient({
    token: process.env.SQUARE_ACCESS_TOKEN,
    environment: process.env.SQUARE_ENV === "production" ? SquareEnvironment.Production : SquareEnvironment.Sandbox,
  }));
}

Good to know

What the card can show: the card number, expiry, CVV and postal code sit in Square's iframe, so your page and your server never see them. tokenize() hands you a one-time token and your server charges it. The 3D card hears the brand from cardBrandChanged, which field has focus from focusClassAdded, and whether each field is valid from the state every event carries. It shows a Visa or Mastercard mark, flips for the CVV and lights up Pay. It doesn't show the number the buyer types.
What we ran on October 26, 2026: we type-checked every file on this page against @square/web-sdk 2.3.0 (types from @square/web-payments-sdk-types 1.87.1), react-square-web-payments-sdk 3.3.0, square 46.0.0, next 15.5.28, react 19.1.1, @types/react 19.3.0, framer-motion 14.6.0 and TypeScript 5.9.3 with target ES2017, as create-next-app sets it, and the shipped CardCheckout source. Five deliberate mistakes failed the check, as they should: a wrong event name, a wrong event field, a border style key on the wrong selector, a number instead of a bigint amount, and a misspelled token. next build passed. In Chromium at 390 and 1440 px, with Square's real sandbox script and a made-up application id, the script loaded, card() refused the id, the slot showed its message, and the page had no errors from our code and no sideways scroll. With @square/web-sdk swapped for a local stand-in that fires the same events with the same detail shape, the card showed the Mastercard mark, flipped on CVV focus and back on the postal code, lit up Pay, passed the verification details to tokenize() and sent the token to the server action, which received the amount as a bigint. Under React Strict Mode in dev the card was created once.
What we didn't run: we have no Square account on this test, so no sandbox application id was used, no real Square card form rendered inside the 3D card, and no tokenize(), payments.create or buyer verification went through. Pay with Square's sandbox test cards before you ship.
Square needs a secure context. Called from a page with no secure origin, payments() threw "Web Payments SDK can only be embedded on sites that use HTTPS and have a secure context" in our test. http://localhost counts as secure, so next dev works; a preview on a plain http address won't.
Strict Mode: in development React runs the effect twice. The snippets check gone right after payments() resolves, so the first run stops before it creates a card, and the cleanup calls destroy() on the real one. Without that check you get two card forms in one div.
Money and retries: Square's server SDK takes amounts as a bigint in the smallest unit of the currency, cents for USD. Use BigInt() rather than a 1000n literal if your tsconfig targets ES2017, which is the create-next-app default. The idempotency key is made in the browser once per press of Pay, like Square's quickstart does. Send the same key again on a retry and Square charges once. Fulfil orders from the payment on your server or Square's webhooks, not from the redirect to /thanks.
Size: the checkout is a fixed 1000 x 660 scene, and its README says to scale it with a CSS transform. The snippet scales it to the width of its parent, so a 390 px phone shows it at about 0.39 and Square's form inside is small. For a phone-first checkout, use the plain Card form below and show the 3D card from tablet width up.
Set SQUARE_APPLICATION_ID, SQUARE_LOCATION_ID and SQUARE_ACCESS_TOKEN, and SQUARE_ENV=production when you go live. The application id and location id are public; the access token stays on the server. A sandbox application id starts with sandbox-sq0idb-, and @square/web-sdk 2.3.0 loads the sandbox script for it by itself. The card draws a Visa or a Mastercard mark; other brands still pay with no logo. Every rule in the piece's card-checkout.css starts with .qcc- (re-read October 26, 2026), so it doesn't touch the rest of your styles.

react-square-web-payments-sdk: the quickest route

react-square-web-payments-sdk 3.3.0 (published January 2026) wraps Square's Web Payments SDK in React components. Its peer range is React 16 through 19, and it depends on @square/web-sdk and @stitches/react. PaymentForm loads Square and takes applicationId, locationId and cardTokenizeResponseReceived. Inside it, CreditCard renders Square's card form and its own pay button. The package also exports GooglePay, ApplePay, CashAppPay, Afterpay, Ach and GiftCard.
This fits most stores better than anything below: square-form.tsx is the whole client side, and it sends the token to the same server action as the rest of this page. Style the button with buttonProps.css, and the fields with the style prop CreditCard passes on to Square.
One fact from its source, read today: in 3.3.0 the createVerificationDetails prop runs payments.verifyBuyer() after tokenize. Square's card payment guide now marks verifyBuyer() as deprecated and passes verification details to tokenize() instead, though Square still runs the buyer checks for verifyBuyer() until it is retired. If you use that prop, send the verified buyer's token to payments.create as verificationToken. The routes below call tokenize() with the details directly.

app/pay/simple/square-form.tsx (the free route)

"use client";
import { useState } from "react";
import { PaymentForm, CreditCard } from "react-square-web-payments-sdk";
import { charge } from "../actions";

// The free route: Square's card form and pay button from react-square-web-payments-sdk.
export default function SquareForm({ appId, locationId }: { appId: string; locationId: string }) {
  const [message, setMessage] = useState("");

  return (
    <PaymentForm
      applicationId={appId}
      locationId={locationId}
      cardTokenizeResponseReceived={async (result) => {
        if (result.status !== "OK") return setMessage("Check the card details and try again.");
        const paid = await charge(result.token, crypto.randomUUID());
        setMessage(paid.ok ? "Paid, thank you." : paid.error);
      }}
    >
      <CreditCard buttonProps={{ css: { backgroundColor: "#111827" } }}>Pay now</CreditCard>
      {message && <p role="status" className="mt-3 text-sm">{message}</p>}
    </PaymentForm>
  );
}

The Square Card with @square/web-sdk directly

To drive your own UI from the card's events, skip the wrapper. @square/web-sdk 2.3.0 has one function, payments(applicationId, locationId). It adds Square's script once, picks the sandbox script for a sandbox- application id, and returns null on the server. payments.card() gives you a Card; attach() mounts it into a div, addEventListener() listens to it, tokenize() returns the token, and destroy() removes it.
tokenize() resolves with a status. OK carries the token. Invalid means validation failed during tokenization and Error means it didn't succeed; both carry an errors list with a message and, where it applies, the field. Abort and Cancel mean it was aborted or cancelled by the buyer. The plain form below handles each one and puts the brand on the button, which is the smallest version of what the 3D card does.

app/pay/plain/card-form.tsx

"use client";
import { useEffect, useRef, useState } from "react";
import { payments, type Card } from "@square/web-sdk";
import { charge } from "../actions";

// @square/web-sdk with no wrapper: you own the card's lifecycle, its events and the button.
export default function CardForm({ appId, locationId }: { appId: string; locationId: string }) {
  const box = useRef<HTMLDivElement>(null);
  const card = useRef<Card | null>(null);
  const [ready, setReady] = useState(false);
  const [brand, setBrand] = useState("");
  const [busy, setBusy] = useState(false);
  const [message, setMessage] = useState("");

  useEffect(() => {
    let gone = false;
    (async () => {
      // payments() picks the sandbox script for an app id that starts with sandbox-sq0idb-.
      const sq = await payments(appId, locationId);
      if (!sq || gone) return;
      const created = await sq.card({
        style: { ".input-container.is-focus": { borderColor: "#2563eb" }, input: { fontSize: "16px" } },
      });
      if (gone) return void created.destroy();
      created.addEventListener("cardBrandChanged", (e) => setBrand(e.detail.cardBrand));
      await created.attach(box.current!);
      card.current = created;
      setReady(true);
    })().catch(() => !gone && setMessage("The card form didn't load. Refresh to try again."));

    return () => {
      gone = true;
      void card.current?.destroy();
      card.current = null;
    };
  }, [appId, locationId]);

  async function pay() {
    if (!card.current) return;
    setBusy(true);
    setMessage("");
    const result = await card.current.tokenize();
    if (result.status === "OK") {
      const paid = await charge(result.token, crypto.randomUUID());
      setMessage(paid.ok ? "Paid, thank you." : paid.error);
    } else {
      // "Invalid" means validation failed; errors[0].field names the field when it applies.
      setMessage("errors" in result ? result.errors[0]?.message ?? "Check the card." : "Payment cancelled.");
    }
    setBusy(false);
  }

  return (
    <div className="grid gap-3">
      <div ref={box} />
      <button
        type="button"
        onClick={pay}
        disabled={!ready || busy}
        className="h-12 rounded-lg bg-blue-600 font-medium text-white disabled:opacity-50"
      >
        {busy ? "Paying..." : brand && brand !== "OTHER_BRAND" ? `Pay with ${brand.replace("_", " ").toLowerCase()}` : "Pay"}
      </button>
      {message && <p role="status" className="text-sm">{message}</p>}
    </div>
  );
}

How Square's events drive the 3D card

Credit Card Checkout V1 has a renderCardFields slot. Inside it you render a div for Square and call slot.onChange with what Square tells you; the card does the rest. Square's Card has eight events (types read today): cardBrandChanged, focusClassAdded, focusClassRemoved, errorClassAdded, errorClassRemoved, postalCodeChanged, escape and submit. Each one names the field (cardNumber, expirationDate, cvv or postalCode), the card brand and the field's current state.
cardBrandChanged: VISA or MASTERCARD becomes the brand mark. focusClassAdded: cvv flips the card, cardNumber and expirationDate keep the front up, postalCode counts as no card field. focusClassRemoved and the error events: each carries isCompletelyValid for its field, and Pay lights up once the number, expiry and CVV have all reported valid and the name is filled. There is no change event per keystroke, so that happens when the buyer leaves the CVV field.
When Pay is pressed, onConfirm gets the cardholder name from the card, passes it to tokenize() as the billing contact with the amount and intent, and sends the token to the server action. Square checks the postal code at that point; if it is missing, tokenize() comes back Invalid and the card shows the message and goes back to idle.

One iframe for four fields, and phones

Square doesn't give you separate number, expiry and CVV fields. Its Card is one iframe that holds all four inputs and draws its own borders inside, so the slot gives it one full-width row with a label instead of the card's three boxes. Square sizes that form from the buyer's browser width; its types document recalculateSize() for when the form was hidden while it loaded.
Inside the scaled 3D scene on a 390 px phone, Square's form shrinks with everything else. Our page had no sideways scroll at 390 with the stand-in fields, but we couldn't see the real form's phone layout inside the slot without a sandbox account. On phones, render the plain Card form above at full width and keep the 3D card for wider screens.

Styling the Square Card

The fields are in Square's iframe, so your CSS and Tailwind classes don't reach them. You pass a style object to payments.card() (or as the style prop of CreditCard). @square/web-payments-sdk-types 1.87.1 lists the selectors it accepts: input, input.is-focus, input::placeholder, input.is-focus::placeholder, input.is-error, input.is-error::placeholder, .input-container, .input-container.is-focus, .input-container.is-error, .message-text, .message-icon, .message-text.is-error and .message-icon.is-error.
Each takes a few properties. input: backgroundColor, color, fontFamily, fontSize and fontWeight. .input-container: borderColor, borderRadius and borderWidth, and its focus and error states take borderColor and borderWidth. The placeholder and message selectors take color. With the types installed, a property on the wrong selector fails the type check, which is how one of our deliberate mistakes was caught.
Two options sit beside style: includeInputLabels shows labels inside the form, and postalCode fills the postal code in for the buyer.

Square sandbox test cards

From Square's Sandbox Payments page, read today: Visa 4111 1111 1111 1111 with CVV 111, Mastercard 5105 1051 0510 5100 with CVV 111, Discover 6011 0000 0000 0004, American Express 3400 000000 00009 with CVV 1111. Any future month and year work as the expiry.
Payments in USD, CAD or GBP need a valid postal code, so type one in the sandbox too, for example 94103. The same page lists values that fail on purpose, such as 4000 0000 0000 0002 for a declined card, and the cards that trigger a buyer verification challenge when you pass verification details to tokenize(). Use them to see your error messages before you go live.

Install

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

Props

renderCardFields: the Square Card inside the design
onConfirm: tokenize() and charge on your server; throw to show the error
amount / currency: what the card shows (your server sets what Square charges)
className / style: the scale transform for the fixed 1000 x 660 scene
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, CVV and postal code stay in Square's iframe. The card only hears the brand, which field has focus, and whether each field is valid.

react-square-web-payments-sdk or @square/web-sdk?

The wrapper for most stores: one PaymentForm and one CreditCard with Square's pay button. @square/web-sdk directly when your own UI follows the card's events, as the 3D card on this page does.

Why does payments() fail on my preview?

Square only runs in a secure context. Use https, or http://localhost while you develop. A sandbox application id must start with sandbox-sq0idb-, or @square/web-sdk throws InvalidApplicationIdError before it loads anything.

Does the Square Web Payments SDK work with React 19 and Next.js?

Yes, in a client component. react-square-web-payments-sdk 3.3.0 lists React 19 in its peer range, and @square/web-sdk has no React dependency at all. Our snippets type-check and build with react 19.1.1 and next 15.5.28. We didn't run them against a Square 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.