Cashfree in React and Next.js: the hosted checkout first, then card components in a 3D card

If you just want to take payments with Cashfree in a Next.js app, use its hosted checkout: a Server Action creates the order with cashfree-pg, the browser opens Cashfree's page with the payment_session_id, and your server checks the order status before you mark anything paid. It brings UPI, netbanking and wallets with it. This page shows that route, then the other one: Cashfree's card number, expiry and CVV components inside an animated 3D card that shows the brand and flips for the CVV.

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

Cashfree card components inside the card, in the App Router

app/pay/checkout.tsx

"use client";
import { useEffect, useId, useRef } from "react";
import { useRouter } from "next/navigation";
import { load, type Cashfree, type CashfreeComponent } from "@cashfreepayments/cashfree-js";
import CardCheckout, { type CardFieldsSlot } from "@/components/CardCheckout";
import { verifyOrder } from "./actions";

type Order = { orderId: string; paymentSessionId: string };
type Confirm = (name: string) => Promise<void>;
type Field = "number" | "expiry" | "cvc";

// load() makes a new Cashfree object on every call, so keep one per page.
let sdk: Promise<Cashfree | null> | undefined;
const loadCashfree = () =>
  (sdk ??= load({ mode: process.env.NEXT_PUBLIC_CASHFREE_ENV === "production" ? "production" : "sandbox" }));

// The fields are iframes and don't read your CSS, so their text is styled here.
const style = { base: { color: "#f4f5f7", fontSize: "18px", backgroundColor: "transparent" } };

function CashfreeFields({ slot, order, onReady }: {
  slot: CardFieldsSlot;
  order: Order;
  onReady: (confirm: Confirm | null) => void;
}) {
  const id = useId();
  const box = (name: string) => `#${CSS.escape(id + name)}`;
  const failed = useRef<HTMLParagraphElement>(null);

  useEffect(() => {
    let gone = false;
    let parts: CashfreeComponent[] = [];
    const done: Record<Field, boolean> = { number: false, expiry: false, cvc: false };
    const changed = (field: Field, complete: boolean) => {
      done[field] = complete;
      slot.onChange({ complete: done.number && done.expiry && done.cvc });
    };

    (async () => {
      const cashfree = await loadCashfree();
      if (!cashfree || gone) return;
      const number = cashfree.create("cardNumber", { values: { placeholder: "1234 5678 9012 3456" }, style });
      const expiry = cashfree.create("cardExpiry", { style });
      const cvv = cashfree.create("cardCvv", { style });
      // The card has its own Cardholder name input. Cashfree still wants its cardHolder
      // component for a card payment, so one is mounted out of sight and gets the name on Pay.
      const holder = cashfree.create("cardHolder", { style });
      parts = [number, expiry, cvv, holder];

      number.on("change", (d) => {
        changed("number", d.complete);
        slot.onChange({ brand: d.value.brand ?? null }); // visa, mastercard, amex, rupay
        if (d.value.cvvLength) cvv.update({ cvvLength: d.value.cvvLength });
      });
      expiry.on("change", (d) => changed("expiry", d.complete));
      cvv.on("change", (d) => changed("cvc", d.complete));
      number.on("focus", () => slot.onChange({ focus: "number" }));
      expiry.on("focus", () => slot.onChange({ focus: "expiry" }));
      cvv.on("focus", () => slot.onChange({ focus: "cvc" })); // flips the card
      cvv.on("blur", () => slot.onChange({ focus: null }));
      number.on("loaderror", (d) => {
        if (failed.current) failed.current.textContent = d.error?.message ?? "The card fields didn't load.";
      });

      number.mount(box("number"));
      expiry.mount(box("expiry"));
      cvv.mount(box("cvv"));
      holder.mount(box("holder"));

      // pay() goes on the card number component; Cashfree reads the other three by itself.
      onReady(async (name) => {
        holder.update({ cardHolder: name });
        const result = await cashfree.pay({
          paymentMethod: number,
          paymentSessionId: order.paymentSessionId,
          redirect: "if_required", // stay on the page when the card needs no redirect
        });
        if (result.error) throw new Error(result.error.message);
        if (result.redirect) return new Promise<void>(() => {}); // Cashfree is taking the buyer to 3D Secure
        const { paid } = await verifyOrder(order.orderId);
        if (!paid) throw new Error("That payment didn't go through.");
      });
    })();

    return () => {
      gone = true;
      onReady(null);
      parts.forEach((p) => p.destroy());
    };
  }, [slot, order, onReady]);

  return (
    <div className="space-y-3">
      <div>
        <label className={slot.labelClassName}>Card number</label>
        <div id={id + "number"} className={slot.fieldClassName} />
      </div>
      <div className="flex gap-3">
        <div className="flex-1">
          <label className={slot.labelClassName}>Expiry</label>
          <div id={id + "expiry"} className={slot.fieldClassName} />
        </div>
        <div className="flex-1">
          <label className={slot.labelClassName}>CVV</label>
          <div id={id + "cvv"} className={slot.fieldClassName} />
        </div>
      </div>
      <div id={id + "holder"} inert className="sr-only" />
      <p ref={failed} role="alert" className="text-sm text-red-400" />
    </div>
  );
}

export default function CashfreeCardCheckout({ order, amount }: { order: Order; amount: number }) {
  const router = useRouter();
  const confirm = useRef<Confirm | null>(null);
  const setConfirm = useRef((c: Confirm | null) => (confirm.current = c)).current;

  return (
    <CardCheckout
      amount={amount}
      currency="INR"
      locale="en-IN"
      resetAfter={null}
      renderCardFields={(slot) => <CashfreeFields slot={slot} order={order} onReady={setConfirm} />}
      onConfirm={async ({ name }) => {
        if (!confirm.current) throw new Error("The card fields haven't loaded yet.");
        await confirm.current(name);
        router.push("/thanks");
      }}
    />
  );
}

app/pay/page.tsx

import { createOrder } from "@/lib/cashfree";
import CashfreeCardCheckout from "./checkout";

export const dynamic = "force-dynamic";

export default async function PayPage() {
  // The amount is set here on the server. A fresh order (and payment session) for every visit.
  // Cashfree needs a customer id and phone on every order: use your signed-in buyer's.
  const order = await createOrder(10, { id: "guest_demo", phone: "9999999999" });
  return <CashfreeCardCheckout order={order} amount={10} />;
}

app/pay/actions.ts (Server Action: ask Cashfree whether the order is paid)

"use server";
import { isPaid } from "@/lib/cashfree";

// The browser only says "the payment finished". Ask Cashfree before you show success.
export async function verifyOrder(orderId: string) {
  return { paid: await isPaid(orderId) };
}

lib/cashfree.ts (server: the cashfree-pg client, create and read orders)

import { Cashfree, CFEnvironment } from "cashfree-pg";

// Server only: never import this from a "use client" file. The client secret stays on the server.
// cashfree-pg 6.x sends x-api-version 2026-01-01 unless you set cashfree.XApiVersion.
export const cashfree = new Cashfree(
  process.env.CASHFREE_ENV === "production" ? CFEnvironment.PRODUCTION : CFEnvironment.SANDBOX,
  process.env.CASHFREE_CLIENT_ID!,
  process.env.CASHFREE_CLIENT_SECRET!,
  undefined, // partner key
  undefined, // client signature
  undefined, // partner merchant id
  false, // error analytics: true by default, which calls Sentry.init in your server with Cashfree's project
);

// One order per payment attempt. Its payment_session_id is single use.
export async function createOrder(amount: number, customer: { id: string; phone: string }) {
  const { data } = await cashfree.PGCreateOrder({
    order_id: `order_${crypto.randomUUID().replaceAll("-", "")}`.slice(0, 45),
    order_amount: amount, // in rupees, not paise: 10 is 10.00 INR
    order_currency: "INR",
    customer_details: { customer_id: customer.id, customer_phone: customer.phone },
    order_meta: { return_url: `${process.env.NEXT_PUBLIC_SITE_URL}/pay/return?order_id={order_id}` },
  });
  return { orderId: data.order_id!, paymentSessionId: data.payment_session_id! };
}

// The source of truth: Cashfree's own order status, read from your server.
export async function isPaid(orderId: string) {
  const { data } = await cashfree.PGFetchOrder(orderId);
  return data.order_status === "PAID";
}

lib/cashfree-js.d.ts (types for the browser SDK, which ships none)

// @cashfreepayments/cashfree-js 1.0.7 ships no TypeScript types, so these are ours,
// written from Cashfree's JS SDK docs (read October 26, 2026). Only what this page uses.
declare module "@cashfreepayments/cashfree-js" {
  export type ComponentData = {
    value: { brand?: string; cvvLength?: number | string; [key: string]: unknown };
    error?: { message: string; type?: string };
    invalid?: boolean;
    empty: boolean;
    complete: boolean;
    ready: boolean;
    focus: boolean;
    componentName: string;
  };

  export type ComponentEvent =
    | "ready" | "focus" | "blur" | "invalid" | "change" | "empty" | "complete" | "loaderror" | "paymentrequested";

  export type ComponentOptions = {
    values?: Record<string, unknown>;
    style?: Record<string, unknown>; // CSS in camelCase, applied inside the iframe
    classes?: Partial<Record<"base" | "complete" | "empty" | "focus" | "invalid" | "disabled", string>>; // on your container
    fonts?: { cssSrc: string }[];
    disabled?: boolean;
    loader?: boolean;
  };

  export interface CashfreeComponent {
    mount(selector: string): void;
    update(values: Record<string, unknown>): void;
    unmount(): void;
    destroy(): void;
    data(): ComponentData;
    isComplete(): boolean;
    on(event: ComponentEvent, callback: (data: ComponentData) => void): void;
  }

  export type CashfreeResult = {
    error?: { message: string; type?: string; code?: string };
    redirect?: boolean;
    paymentDetails?: { paymentMessage: string };
  };

  export interface Cashfree {
    checkout(options: {
      paymentSessionId: string;
      redirectTarget?: "_self" | "_blank" | "_top" | "_modal" | HTMLElement;
      returnUrl?: string;
      appearance?: { width?: string; height?: string };
    }): Promise<CashfreeResult>;
    create(
      name: "cardNumber" | "cardHolder" | "cardExpiry" | "cardCvv" | "savePaymentInstrument",
      options?: ComponentOptions,
    ): CashfreeComponent;
    pay(options: {
      paymentMethod: CashfreeComponent;
      paymentSessionId: string;
      returnUrl?: string;
      redirect?: "if_required";
      redirectTarget?: "_self" | "_blank" | "_parent" | "_top";
      savePaymentInstrument?: CashfreeComponent;
    }): Promise<CashfreeResult>;
  }

  // Resolves to null on the server. Each call makes a new Cashfree object, so call it once per page.
  export function load(options: { mode: "sandbox" | "production" }): Promise<Cashfree | null>;
}

Good to know

What the card can show: the number, expiry and CVV sit in Cashfree's iframes, so your page and your server never see the digits. The 3D card hears when each field is complete, which field has focus, and the brand. It lights up Pay, flips for the CVV and shows a Visa or Mastercard mark. Cashfree also reports amex and rupay; those cards still pay, the card just shows no logo.
Amounts: order_amount is in rupees, not paise, so 10 means 10.00 INR. That is the opposite of Razorpay, where the order amount is in paise. Cashfree's Node sample on the web checkout page passes the amount as a string; the cashfree-pg 6.0.6 types want a number, and a string fails the type-check.
Every Create Order sample in Cashfree's docs sends customer_details with customer_id and customer_phone, and inside customer_details the 6.0.6 types make both required. Use your signed-in buyer's id and phone. A payment_session_id is single use, and Cashfree's FAQ says it expires after 30 minutes, so create the order when the buyer reaches the pay page, not earlier.
Cardholder name: Credit Card Checkout V1 has its own Cardholder name input, and Cashfree's docs say a card payment needs the cardNumber, cardExpiry, cardCvv and cardHolder components. So the snippet mounts Cashfree's cardHolder component out of sight (inert, so nobody can tab into it) and copies the typed name into it with update() when Pay is pressed. We haven't seen this against a Cashfree sandbox; if Cashfree answers that the name is missing, show its cardHolder field in the slot instead.
What we ran and what we didn't: on October 26, 2026 we type-checked these files against cashfree-pg 6.0.6, our own types for @cashfreepayments/cashfree-js 1.0.7, next 15.5.28, @types/react 19.3.0, framer-motion 11.18.2 and TypeScript 5.9.3, with the shipped CardCheckout source, and ran next build. Four deliberate mistakes failed the check, as they should. In a local build the real cashfree.js loaded in sandbox mode and mounted the number, expiry, CVV and hidden cardholder iframes in the card's boxes; typing Cashfree's test Visa number lit the Visa mark, the card flipped for the CVV, and Pay turned on. We didn't have a Cashfree account, so no order, pay() call, 3D Secure step or webhook went through. Pay with Cashfree's sandbox test cards before you ship.
Cashfree draws its own small brand icon inside the number field as well. If you only want the card's mark, cardNumber takes values.hideBrandIcon: true.
@cashfreepayments/cashfree-js is a small loader: it adds https://sdk.cashfree.com/js/v3/cashfree.js to the page and hands you the Cashfree object. It starts loading the script as soon as the module is imported in the browser, resolves to null on the server, and makes a new Cashfree object on every load() call, which is why the snippet keeps one per page. Cashfree's FAQ asks you to load the SDK from its CDN and not to bundle or self-host it, which is what the loader does.
Before the first payment works, add your domain under Domain Whitelisting in Cashfree's Merchant Dashboard; Cashfree's web checkout docs ask for it before you open checkout, and their FAQ calls it mandatory. If you run a Content Security Policy, the package README lists what to allow: connect-src https://api.cashfree.com, frame-src https://sdk.cashfree.com, https://api.cashfree.com, https://sandbox.cashfree.com, https://payments.cashfree.com and https://payments-test.cashfree.com, and script-src https://sdk.cashfree.com.
cashfree-pg 6.0.6 reports its own errors to Cashfree unless you say no: the constructor's seventh argument, XEnableErrorAnalytics, defaults to true and then calls Sentry.init in your server process with Cashfree's project (read in the package source). The snippet passes false. The package also brings axios and @sentry/node as dependencies.
Set CASHFREE_CLIENT_ID, CASHFREE_CLIENT_SECRET, CASHFREE_ENV, NEXT_PUBLIC_CASHFREE_ENV and NEXT_PUBLIC_SITE_URL. The client secret stays on the server. Cashfree also publishes @cashfreepayments/pg-react, a React wrapper for the same card components (1.0.3, last published May 2025); we used cashfree-js directly because the card needs the raw focus and change events.
Tailwind v4: Cashfree draws the three fields, so only the cardholder name is styled by the zip's CSS. That field can lose its font on Tailwind v4; the fix is on the checkout page guide (see the Tailwind v4 section there). Text inside the iframes takes its colour and size from the style object in the snippet. Cashfree's classes option puts your class names on the container div, outside the iframe, so Tailwind classes work there. Our CSS leak check of this piece found every rule starts with .qcc-, so it doesn't touch your shadcn styles.

When Cashfree's hosted checkout is the better pick

Cashfree gives you two ways to take a payment on the web. The hosted checkout is Cashfree's own page with every method you have turned on: cards, UPI, netbanking, wallets, EMI and pay later. Card and UPI components are pieces of that page you place in your own layout.
The hosted checkout fits better for most stores in India, mostly because of UPI. It's one cashfree.checkout() call with the payment_session_id from your order. redirectTarget picks how it opens: _self, _blank or _top send the buyer to Cashfree's page, _modal opens it in a popup over yours, and a DOM element shows it inline. For the popup and inline versions the call returns a promise with error, redirect or paymentDetails. hosted-checkout.tsx below is the whole popup route.
The card components are for when the card form has to look like your product. This page is that route, with a card that reacts while the buyer types. They take cards only, so keep the hosted checkout next to them as a "Pay with UPI or netbanking" button.
Building for React Native? The web SDK doesn't apply there. Cashfree has a separate React Native SDK.

app/pay/hosted-checkout.tsx (the free route)

"use client";
import { useState } from "react";
import { load } from "@cashfreepayments/cashfree-js";
import { verifyOrder } from "./actions";

// The free route: Cashfree's hosted checkout in a popup over your page. Cards, UPI,
// netbanking and wallets are all on Cashfree's page; you style none of it.
let sdk: ReturnType<typeof load> | undefined; // one Cashfree object per page

export default function HostedCheckout({ order }: { order: { orderId: string; paymentSessionId: string } }) {
  const [message, setMessage] = useState<string | null>(null);

  async function pay() {
    const cashfree = await (sdk ??= load({ mode: "sandbox" })); // "production" for live payments
    if (!cashfree) return;
    const result = await cashfree.checkout({ paymentSessionId: order.paymentSessionId, redirectTarget: "_modal" });
    if (result.error) return setMessage(result.error.message); // closed, or the payment failed
    if (result.redirect) return; // in-app browsers: Cashfree sends the buyer to your return_url instead
    const { paid } = await verifyOrder(order.orderId);
    setMessage(paid ? "Paid. Thanks!" : "We couldn't confirm that payment yet.");
  }

  return (
    <div className="grid gap-3">
      <button onClick={pay} className="rounded-xl bg-violet-500 px-5 py-3 font-medium text-white">
        Pay with Cashfree
      </button>
      {message && <p role="status" className="text-sm text-neutral-500">{message}</p>}
    </div>
  );
}

Check the payment on your server: order status and the webhook

The browser can tell you a payment finished, not that it was paid. Cashfree's docs say to check the order from your server before you deliver anything: PGFetchOrder(order_id) and order_status "PAID". The snippet's verifyOrder Server Action does that, and the card only shows success after it says paid.
The buyer can also close the tab before your code runs, so fulfil from the webhook. Cashfree signs each webhook with your client secret: the x-webhook-signature header is an HMAC SHA256 of the x-webhook-timestamp header plus the raw body, base64 encoded. PGVerifyWebhookSignature checks it and throws when it doesn't match. Read the body as text first; Cashfree's docs warn that parsing it can turn 170.00 into 170 and break the signature.

app/api/cashfree/webhook/route.ts

import { cashfree } from "@/lib/cashfree";

// Dashboard > Developers > Webhooks: point the payment webhooks at /api/cashfree/webhook.
export async function POST(req: Request) {
  // Verify against the raw text. Parsing first can turn 170.00 into 170 and break the signature.
  const raw = await req.text();
  const signature = req.headers.get("x-webhook-signature") ?? "";
  const timestamp = req.headers.get("x-webhook-timestamp") ?? "";

  let event;
  try {
    event = cashfree.PGVerifyWebhookSignature(signature, raw, timestamp); // throws on a mismatch
  } catch {
    return new Response("bad signature", { status: 401 });
  }

  if (event.type === "PAYMENT_SUCCESS_WEBHOOK") {
    const orderId: string = event.object.data.order.order_id;
    // Mark the order paid here. Cashfree retries, so make this safe to run twice.
    console.log("paid", orderId);
  }
  return new Response("ok");
}

Cashfree card component events and methods we used

We read these from Cashfree's component docs. cashfree.create(name, options) makes a component, mount(selector) puts it in a div, and on(event, callback) listens. The events are ready, focus, blur, invalid, change, empty, complete, loaderror and paymentrequested, and each callback gets the same object as data(): value, error, complete, empty, focus and so on.
The card's Pay button wants all three fields complete, so the snippet keeps a complete flag per field and reports complete only when all three are true. focus on the CVV flips the card and blur flips it back. The card number's value carries brand and cvvLength, and Cashfree's own sample passes cvvLength on to the CVV field with update(), as the snippet does.
mount() takes a selector string. React's useId() can make ids that aren't valid in a CSS selector (older React versions use colons), so the snippet runs them through CSS.escape(). destroy() in the effect cleanup removes the iframes, so Strict Mode's second run starts clean.

How this differs from the Razorpay and Airwallex guides

Razorpay's Standard Checkout has no card fields you can place, so its guide wraps the modal in an animated checkout and checks razorpay_signature on the server. Cashfree has both: a hosted checkout like Razorpay's modal, and card components like Airwallex's split card fields.
With Airwallex the browser confirms a PaymentIntent and the brand needs a getBinInfo call. With Cashfree the browser pays an order's payment_session_id, the brand arrives with every change event, and the server reads the order status instead of a signature.

Install

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

Props

renderCardFields: Cashfree's card components inside the design
onConfirm: pay the order and check it on your server; throw to show the error
amount / currency: what the card shows (Cashfree 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 Cashfree's iframes. The card only hears when each field is complete, which field has focus, and the brand.

Hosted checkout or card components?

The hosted checkout for most stores in India: one call, and UPI, netbanking and wallets come with it. The card components when the card form has to match your design, as on this page, with the hosted checkout kept for UPI.

Does @cashfreepayments/cashfree-js have TypeScript types?

Not in 1.0.7. The page writes its own, from Cashfree's docs, for the calls it uses: load, checkout, create, pay and the component methods.

Does it work with React 19?

The package has no React peer dependency; it loads Cashfree's script and mounts iframes into the divs you give it. Our snippet type-checks and builds with React 19 and Next.js 15. We didn't run it against a Cashfree 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.