Razorpay in Next.js: Standard Checkout first, then the modal inside your own checkout

If you want Razorpay in a Next.js app, use Standard Checkout: a Server Action creates the order with the razorpay Node SDK, the browser loads checkout.js and opens Razorpay's own modal with the order id, and your server checks razorpay_signature before you mark anything paid. The modal is Razorpay's page, so you can't restyle what's inside it. This page shows the whole flow, the theme options you do get, and how to wrap the modal in your own animated checkout.

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

Razorpay Standard Checkout in the App Router

app/checkout/pay-button.tsx

"use client";
import { useState } from "react";
import { openRazorpay } from "@/lib/razorpay-checkout";
import { createOrder, verifyPayment } from "./actions";

export function PayButton() {
  const [busy, setBusy] = useState(false);
  const [message, setMessage] = useState<string | null>(null);

  async function pay() {
    setBusy(true);
    setMessage(null);
    try {
      const order = await createOrder();
      const result = await openRazorpay({
        key: process.env.NEXT_PUBLIC_RAZORPAY_KEY_ID!,
        amount: order.amount, // the order's own amount, in paise
        currency: order.currency,
        order_id: order.orderId,
        name: "Northline Audio",
        description: "Studio headphones",
        theme: { color: "#8b6cff" },
      });
      if (result.status === "closed") {
        setMessage(result.error ?? "Payment cancelled. Nothing was charged.");
        return;
      }
      const { ok } = await verifyPayment(result.response);
      setMessage(ok ? "Paid. Thanks!" : "We couldn't verify that payment. Please contact us before paying again.");
    } catch (err) {
      setMessage(err instanceof Error ? err.message : "Something went wrong. Try again.");
    } finally {
      setBusy(false);
    }
  }

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

app/checkout/actions.ts (Server Actions: create the order, verify the signature)

"use server";
import { validatePaymentVerification } from "razorpay/dist/utils/razorpay-utils";
import { razorpay } from "@/lib/razorpay";
import type { RazorpaySuccess } from "@/lib/razorpay-checkout";

// The amount comes from your server, never from the browser. A Server Action is a public endpoint.
const ITEM = { name: "Studio headphones", amount: 249900 }; // in paise (1 rupee = 100 paise)

export async function createOrder() {
  const order = await razorpay.orders.create({
    amount: ITEM.amount,
    currency: "INR",
    receipt: `rcpt_${Date.now()}`, // your own reference, max 40 characters
    notes: { item: ITEM.name },
  });
  return { orderId: order.id, amount: Number(order.amount), currency: order.currency };
}

// Razorpay signs order_id|payment_id with your key secret. Check it before you mark anything paid.
export async function verifyPayment(response: RazorpaySuccess) {
  const ok = validatePaymentVerification(
    { order_id: response.razorpay_order_id, payment_id: response.razorpay_payment_id },
    response.razorpay_signature,
    process.env.RAZORPAY_KEY_SECRET!,
  );
  // ok means the reply really came from Razorpay for this order. Save the payment id with your order here.
  return { ok };
}

lib/razorpay-checkout.ts (loads checkout.js once, typed options, a Promise around the modal)

// checkout.js is a script tag that sets window.Razorpay. It ships no TypeScript types,
// so these are ours, written from Razorpay's Checkout options docs (read October 26, 2026).
export type RazorpaySuccess = {
  razorpay_payment_id: string;
  razorpay_order_id: string;
  razorpay_signature: string;
};

export type RazorpayFailure = {
  error: {
    code: string;
    description: string;
    source: string;
    step: string;
    reason: string;
    metadata: { order_id: string; payment_id: string };
  };
};

export type RazorpayOptions = {
  key: string; // your Key ID (rzp_test_... or rzp_live_...), never the secret
  amount: number; // in the currency subunit: paise for INR
  currency: string;
  order_id: string; // from orders.create on your server
  name: string; // your business name, shown at the top of the modal
  description?: string;
  image?: string; // logo URL or base64
  prefill?: { name?: string; email?: string; contact?: string };
  notes?: Record<string, string>;
  theme?: { color?: string; backdrop_color?: string };
  modal?: {
    ondismiss?: () => void;
    escape?: boolean;
    backdropclose?: boolean;
    confirm_close?: boolean;
    animation?: boolean;
  };
  retry?: { enabled?: boolean };
  config?: { display?: { language?: "en" | "ben" | "hi" | "mar" | "guj" | "tam" | "tel" } };
  handler: (response: RazorpaySuccess) => void;
};

export type RazorpayInstance = {
  open(): void;
  on(event: "payment.failed", callback: (response: RazorpayFailure) => void): void;
};

declare global {
  interface Window {
    Razorpay?: new (options: RazorpayOptions) => RazorpayInstance;
  }
}

let loading: Promise<void> | null = null;

// Loads checkout.js once, on first use, instead of on every page.
export function loadRazorpay(): Promise<void> {
  if (typeof window === "undefined") return Promise.reject(new Error("Razorpay Checkout runs in the browser."));
  if (window.Razorpay) return Promise.resolve();
  loading ??= new Promise<void>((resolve, reject) => {
    const script = document.createElement("script");
    script.src = "https://checkout.razorpay.com/v1/checkout.js";
    script.async = true;
    script.onload = () => resolve();
    script.onerror = () => {
      loading = null; // let the next click try again
      reject(new Error("Razorpay Checkout couldn't load. Check the connection or an ad blocker."));
    };
    document.body.appendChild(script);
  });
  return loading;
}

export type CheckoutResult =
  | { status: "paid"; response: RazorpaySuccess }
  | { status: "closed"; error?: string };

// Opens the modal and settles once: "paid" from handler, "closed" from ondismiss.
export async function openRazorpay(options: Omit<RazorpayOptions, "handler">): Promise<CheckoutResult> {
  await loadRazorpay();
  return new Promise<CheckoutResult>((resolve) => {
    let lastError: string | undefined;
    const rzp = new window.Razorpay!({
      ...options,
      handler: (response) => resolve({ status: "paid", response }),
      modal: { ...options.modal, ondismiss: () => resolve({ status: "closed", error: lastError }) },
    });
    // Retry is on by default: a failed attempt keeps the modal open so the buyer can try again.
    // Keep the reason and report it if they close the modal instead.
    rzp.on("payment.failed", (response) => {
      lastError = response.error.description;
    });
    rzp.open();
  });
}

lib/razorpay.ts

import Razorpay from "razorpay";

// Server only: never import this from a "use client" file. The key secret stays on the server.
export const razorpay = new Razorpay({
  key_id: process.env.RAZORPAY_KEY_ID!,
  key_secret: process.env.RAZORPAY_KEY_SECRET!,
});

app/checkout/page.tsx

import { PayButton } from "./pay-button";

export default function CheckoutPage() {
  return (
    <main className="mx-auto max-w-md px-6 py-16">
      <h1 className="text-2xl font-semibold">Studio headphones</h1>
      <p className="mt-2 mb-6 text-neutral-500">You pay in Razorpay's window: UPI, cards, netbanking or wallets.</p>
      <PayButton />
    </main>
  );
}

Good to know

Amounts are in the currency subunit: paise for INR, so the order amount is the rupee value times 100. Razorpay's docs give the rules for three decimal and zero decimal currencies. Read amount and currency back from the order you created and pass those to Checkout, rather than computing them again in the browser.
Create an order for every payment. Razorpay's troubleshooting page says payments made without an order_id can't be captured and are refunded automatically.
The handler only runs in the browser. A buyer can close the tab before it fires, so treat the webhook below as the record of the payment and the handler as the fast path for your UI.
checkout.js ships no TypeScript types. The RazorpayOptions type in lib/razorpay-checkout.ts is ours, written from Razorpay's Checkout options table, and covers the options used on this page. The razorpay Node SDK does ship its own .d.ts files, so orders.create and the signature helpers are typed by Razorpay.
Only NEXT_PUBLIC_ variables reach the browser in Next.js. The Key ID (rzp_test_ or rzp_live_) goes there; the key secret stays in RAZORPAY_KEY_SECRET on the server. In our build the test Key ID was in the client bundle and the secret wasn't.
What we ran on October 26, 2026: every file on this page type-checks against razorpay 2.9.8 (its own .d.ts), react-razorpay 3.0.1, next 15.5.28, react 19.1.1, @types/react 19.3.0, framer-motion 11.18.2 and TypeScript 5.9.3 strict, together with Receipt Morph Checkout's shipped source. Five deliberate mistakes failed the check, as they should: orders.create without currency, our modal options without order_id, a plain string as react-razorpay's currency, validatePaymentVerification without order_id, and a react-razorpay event other than payment.failed. next build passed. In headless Chromium at 390 and 1440 px, our loader fetched the real checkout.js from checkout.razorpay.com and window.Razorpay became a function, with no page errors and no sideways scroll.
What we didn't run: we have no Razorpay account on this test, so no real order was created and Razorpay's real modal never opened. To test the piece we swapped window.Razorpay for a stand-in that calls handler, payment.failed and ondismiss with the shapes in Razorpay's docs. Signed with a dummy secret, the success reply passed the server's signature check and the card turned into the receipt; a wrong signature, a failed payment and a closed modal each put the card back with a message. Pay with Razorpay's test mode keys before you ship.

react-razorpay: the useRazorpay hook

react-razorpay 3.0.1 (ISC, published September 27, 2024, by Piyush Garg, not by Razorpay) gives you a useRazorpay hook. It loads checkout.js for you and returns { Razorpay, isLoading, error }, plus a RazorpayOrderOptions type. npm counted 5,695 downloads for the week of October 16 to 22, 2026.
Its types are narrower than Razorpay's docs in places: currency is a union of currency codes, so a plain string from your server needs narrowing; on() only accepts payment.failed; and notes is typed as a string, where Razorpay's docs describe an object of key value pairs. The loader in lib/razorpay-checkout.ts above does the same job in about 20 lines with no dependency. Either works.

app/hook/hook-pay-button.tsx (react-razorpay 3.0.1)

"use client";
import { useRazorpay, type RazorpayOrderOptions } from "react-razorpay";
import { createOrder, verifyPayment } from "../checkout/actions";

export function HookPayButton() {
  // The hook loads checkout.js and hands back the Razorpay class.
  const { Razorpay, isLoading, error } = useRazorpay();

  async function pay() {
    const order = await createOrder();
    const options: RazorpayOrderOptions = {
      key: process.env.NEXT_PUBLIC_RAZORPAY_KEY_ID!,
      amount: order.amount,
      currency: "INR", // typed as a currency code union, so a plain string from the server needs narrowing
      name: "Northline Audio",
      order_id: order.orderId,
      handler: (response) => {
        void verifyPayment(response);
      },
      modal: { ondismiss: () => console.log("closed") },
    };
    const rzp = new Razorpay(options);
    rzp.on("payment.failed", (response) => console.warn(response.error.description));
    rzp.open();
  }

  return (
    <button onClick={pay} disabled={isLoading || !!error} className="rounded-xl bg-violet-500 px-5 py-3 text-white">
      Pay with Razorpay
    </button>
  );
}

Razorpay checkout page and theme: what you can change

Standard Checkout is Razorpay's own modal over your page. Your CSS and Tailwind classes don't reach inside it. These are the options Razorpay's Checkout docs list for its look, read on October 26, 2026.
theme.color: your brand colour as a HEX code. Razorpay's docs say it changes the text, the payment method icons and the main button. theme.backdrop_color changes the dimmed backdrop behind the modal.
name, description and image: your business name, a line about the purchase, and a logo URL (or a base64 string) shown at the top of the modal.
prefill: name, email and contact, so the buyer types less. readonly and hidden lock or hide those fields.
config.display: the language (en, ben, hi, mar, guj, tam or tel), and blocks, sequence, hide and preferences to group, order or hide payment methods. Razorpay's display configuration page shows the shape.
modal: ondismiss runs when the buyer closes the modal; escape, backdropclose, handleback, confirm_close and animation change how it closes and opens. retry.enabled (on by default) keeps the modal open after a failed attempt; Razorpay's docs say max_count only works in the Android and iOS SDKs, not on the web.
What you can't do: change the layout, fonts or the payment method screens themselves, or put your own components inside the modal. For your own UI around the payment, wrap the modal, as in the next section.

Razorpay inside Receipt Morph Checkout

Receipt Morph Checkout is our paid piece: a checkout card that splits, unrolls into a paper receipt and gets stamped PAID. It has a renderCardFields slot and an onConfirm callback, built for hosted card fields. With Razorpay there are no fields of yours, so the slot holds a short note and tells the piece it is complete. The piece's Name on card field stays, and onConfirm passes it on, so it becomes Razorpay's prefill name. The piece shows it in capitals, and that's how it arrives in the modal.
Pay calls onConfirm, which opens Razorpay's modal while the card's progress arc spins. When the handler fires and your server confirms razorpay_signature, onConfirm returns ok and the card turns into the receipt. If the buyer closes the modal, or a failed attempt ends with them closing it, onConfirm returns ok: false with a message and the card drops back to the form. The piece also catches an error thrown inside onConfirm, such as checkout.js failing to load, and shows its message.
Three edits for rupees, read from the shipped source on October 26, 2026: the piece formats amounts in US dollars in two places, the usd formatter in CheckoutReceiptMorph.tsx and the one in engine.ts. Change both to new Intl.NumberFormat("en-IN", { style: "currency", currency: "INR" }). The receipt's footer line is sample text from the demo (a card mark and a date); replace it with something true, such as "Paid via Razorpay" and the order id, as we did in our test. onComplete's last4 stays empty, because Razorpay's handler doesn't return card details.
Receipt Morph Checkout isn't a shadcn component; you copy its files from the zip. The page and component below are the files we ran.

app/pay/page.tsx (creates the Razorpay order on the server)

import { razorpay } from "@/lib/razorpay";
import type { NorthwindData } from "@/data/northwind";
import { RazorpayReceiptCheckout } from "./receipt-checkout";

export const dynamic = "force-dynamic"; // a fresh Razorpay order per visit, never one baked in at build

// Your cart, priced on the server. The piece shows major units (rupees); Razorpay wants paise.
const cart: NorthwindData["store"] = {
  name: "Northline Audio",
  orderId: "",
  items: [{ name: "Studio headphones", variant: "Graphite", qty: 1, price: 2499 }],
  shipping: 0,
  tax: 0,
  total: 2499,
};

export default async function PayPage() {
  const rzpOrder = await razorpay.orders.create({
    amount: Math.round(cart.total * 100), // paise
    currency: "INR",
    receipt: `rcpt_${Date.now()}`,
  });
  const order = { ...cart, orderId: rzpOrder.id.slice(-8) };
  return (
    <main className="min-h-dvh bg-[#0b0b0f]">
      <RazorpayReceiptCheckout
        order={order}
        razorpayOrder={{ orderId: rzpOrder.id, amount: Number(rzpOrder.amount), currency: rzpOrder.currency }}
      />
    </main>
  );
}

app/pay/receipt-checkout.tsx (Receipt Morph Checkout)

"use client";
import { useEffect } from "react";
import { useRouter } from "next/navigation";
import { CheckoutReceiptMorph, type CardFieldsSlot } from "@/components/CheckoutReceiptMorph";
import type { NorthwindData } from "@/data/northwind";
import { openRazorpay } from "@/lib/razorpay-checkout";
import { verifyPayment } from "../checkout/actions";

type Order = NorthwindData["store"];
type RazorpayOrder = { orderId: string; amount: number; currency: string };

// Razorpay takes the card, UPI or bank details in its own window, so the slot holds a note, not fields.
function PayInRazorpay({ slot }: { slot: CardFieldsSlot }) {
  useEffect(() => {
    slot.onChange({ complete: true }); // nothing to fill in here, so Pay is ready
  }, [slot]);
  return (
    <p className="rounded-xl border border-white/10 px-4 py-3 text-sm text-white/70">
      You'll pay in Razorpay's secure window: UPI, cards, netbanking or wallets.
    </p>
  );
}

export function RazorpayReceiptCheckout({ order, razorpayOrder }: { order: Order; razorpayOrder: RazorpayOrder }) {
  const router = useRouter();
  return (
    <CheckoutReceiptMorph
      order={order}
      autoplayDemo={false}
      renderCardFields={(slot) => <PayInRazorpay slot={slot} />}
      onConfirm={async ({ name }) => {
        // The card's arc keeps spinning while Razorpay's modal is open.
        const result = await openRazorpay({
          key: process.env.NEXT_PUBLIC_RAZORPAY_KEY_ID!,
          amount: razorpayOrder.amount,
          currency: razorpayOrder.currency,
          order_id: razorpayOrder.orderId,
          name: order.name,
          description: `Order ${order.orderId}`,
          prefill: name ? { name } : undefined, // the piece's name field becomes Razorpay's prefill
          theme: { color: "#8B6CFF", backdrop_color: "#0b0b0f" },
        });
        if (result.status === "closed") {
          return { ok: false, message: result.error ?? "Payment window closed. Your order is still here." };
        }
        const { ok } = await verifyPayment(result.response);
        return ok ? { ok: true } : { ok: false, message: "We couldn't verify that payment. Contact us before paying again." };
      }}
      onComplete={() => setTimeout(() => router.push(`/thanks?order=${razorpayOrder.orderId}`), 2500)}
    />
  );
}

Verify razorpay_signature on the server

Razorpay's docs say to build an HMAC SHA256 hex digest of order_id + "|" + razorpay_payment_id with your key secret and compare it to razorpay_signature. In razorpay 2.9.8 the helper is validatePaymentVerification, imported from razorpay/dist/utils/razorpay-utils, which is the path Razorpay's own docs use. Its .d.ts ships with the package.
Use the order_id you created on your server, from your database or session, not only the one the browser sends back. The SDK helper compares the two strings with ===. If you want a constant-time compare, this is the same check with Node's crypto.

lib/verify-signature.ts (the same check with node:crypto)

import { createHmac, timingSafeEqual } from "node:crypto";

// The same check as the SDK's validatePaymentVerification, with a constant-time compare.
export function isValidPaymentSignature(orderId: string, paymentId: string, signature: string) {
  const expected = createHmac("sha256", process.env.RAZORPAY_KEY_SECRET!)
    .update(`${orderId}|${paymentId}`)
    .digest("hex");
  const a = Buffer.from(expected);
  const b = Buffer.from(signature);
  return a.length === b.length && timingSafeEqual(a, b);
}

Webhooks: payment.captured

The handler tells your UI; a webhook tells your server even when the buyer's tab is gone. Subscribe to payment.captured (or order.paid) in the Dashboard. Razorpay sends the signature in the X-Razorpay-Signature header, computed over the raw request body with your webhook secret, which is a different value from your key secret.
Razorpay's docs say the same event can arrive more than once and that the x-razorpay-event-id header is unique per event, so skip ids you have already handled. Authorized payments have to be captured before they settle; Razorpay's best practices point to the payment capture setting in the Dashboard to do that automatically.

app/api/razorpay/webhook/route.ts

import { validateWebhookSignature } from "razorpay/dist/utils/razorpay-utils";

type RazorpayEvent = {
  event: string; // "payment.captured", "order.paid", "payment.failed", ...
  payload: {
    payment?: { entity: { id: string; order_id: string; amount: number; currency: string; status: string } };
  };
};

export async function POST(req: Request) {
  // The signature is over the raw body, so read text, not json().
  const body = await req.text();
  const signature = req.headers.get("x-razorpay-signature") ?? "";
  if (!validateWebhookSignature(body, signature, process.env.RAZORPAY_WEBHOOK_SECRET!)) {
    return new Response("Invalid signature", { status: 400 });
  }

  // Razorpay can send the same event more than once. Skip ids you've already handled.
  const eventId = req.headers.get("x-razorpay-event-id");
  const event = JSON.parse(body) as RazorpayEvent;

  if (event.event === "payment.captured" && event.payload.payment) {
    const payment = event.payload.payment.entity;
    await markOrderPaid(payment.order_id, payment.id, eventId);
  }
  return Response.json({ received: true });
}

// Your database write. Make it safe to run twice for the same order.
async function markOrderPaid(orderId: string, paymentId: string, eventId: string | null) {
  console.log("paid", { orderId, paymentId, eventId });
}

checkout.js didn't load: an ad blocker, a network error, or a Content Security Policy that doesn't allow checkout.razorpay.com. The loader on this page rejects with a message, and the piece shows it.
The key is missing in the browser: process.env.NEXT_PUBLIC_RAZORPAY_KEY_ID is undefined if the variable lacks the NEXT_PUBLIC_ prefix or was added after the build. Next.js inlines it at build time, so rebuild after you set it.
The order doesn't match: pass the order_id, amount and currency you got back from orders.create, and create the order with the same key pair whose Key ID the browser uses.
An in-app browser: Razorpay's troubleshooting page says the Checkout pop-up doesn't appear in some browsers, such as the Facebook and Instagram in-app browsers, and suggests callback_url with redirect for those. It also says Internet Explorer isn't supported.
Open is called on the server: window.Razorpay only exists in the browser, so open the modal from a click in a "use client" component, as above.

Install

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

Props

order: the order the receipt shows (items, shipping, tax, total), priced on your server
renderCardFields: slot for a note: Razorpay collects card, UPI and bank details in its own modal
onConfirm: open Razorpay, verify the signature on your server, return ok or a message
onComplete: gets the receipt: orderId, total, last4 (empty with Razorpay), paidAt
autoplayDemo: false in a real app
accent / secondary: brand colours

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.

Questions

Does Razorpay work with the Next.js App Router?

Yes. Create the order in a Server Action or a route handler with the razorpay Node SDK, load checkout.js in a "use client" component, and open the modal from a click. Verify razorpay_signature on the server before you mark the order paid.

Do I need react-razorpay?

No. It's a small community hook that loads checkout.js for you. A script loader and your own types do the same, as on this page. Both type-check against Razorpay's documented options.

How do I verify the Razorpay payment signature?

HMAC SHA256 of order_id + "|" + razorpay_payment_id with your key secret, compared to razorpay_signature. The razorpay SDK's validatePaymentVerification does this for you.

Can I style the Razorpay checkout page with Tailwind?

No. It's Razorpay's modal. You get theme.color, theme.backdrop_color, hide_topbar, your name, description and logo, and config.display for languages and payment method blocks.

How do I test Razorpay without real money?

Use your test mode Key ID and secret. Razorpay's docs say test mode shows a mock bank page with Success and Failure buttons, and no real money moves.

Does Receipt Morph Checkout work with Razorpay?

Yes, around Razorpay's modal. Its Pay button opens the modal through onConfirm, and the receipt animation runs after your server verifies the signature. Razorpay's own screens inside the modal stay Razorpay's. Change the piece's two dollar formatters and its sample footer line for rupees.

Does Receipt Morph Checkout work in Next.js?

Yes, as a client component. Keep "use client" at the top of the file that renders it, as in the snippet above. App Router and Pages Router both work.

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.

Razorpay in Next.js: Standard Checkout first, then the modal inside your own checkout

Razorpay Standard Checkout in the App Router

Good to know

react-razorpay: the useRazorpay hook

Razorpay checkout page and theme: what you can change

Razorpay inside Receipt Morph Checkout

Verify razorpay_signature on the server

Webhooks: payment.captured

Why the Razorpay modal doesn't open

Install

Props

How qodesign compares

Questions

Razorpay Standard Checkout in the App Router

Good to know

react-razorpay: the useRazorpay hook

Razorpay checkout page and theme: what you can change

Razorpay inside Receipt Morph Checkout

Verify razorpay_signature on the server

Webhooks: payment.captured

Why the Razorpay modal doesn't open

Install

Props

How qodesign compares

Questions