Razorpay Integration in React + Node.js
Payments look simple from the outside. Show a button, collect money, unlock the feature.
I wired up Razorpay into a subscription-based React + Node.js app recently and spent more time than I’d like to admit on things that aren’t obvious from the docs alone - signature verification, webhook edge cases, the difference between Orders and Subscriptions. Writing this down mostly so I have a reference, but hopefully it saves someone else the same debugging sessions.
Before You Write Any Code - Understand the Split
The most important thing to get right isn’t the code, it’s knowing which side does what.
Here’s the short version in plain English:
- Frontend asks backend to create an order → backend returns
order_id - Frontend opens Checkout → user pays → frontend sends payment response to backend
- Backend verifies signature → updates DB → grants access
- Razorpay also fires webhooks directly to the backend - no frontend involved
The frontend’s only job is to open Checkout and hand off the payment response. Everything that actually matters - creating orders, verifying signatures, updating your database, handling webhooks - happens on the backend.
If you mix these up, you either have a security hole or a broken integration. Keep this split in mind as you read the rest.
Environment Variables
Start here. Two .env files, one for each side.
Backend .env
RAZORPAY_API_KEY=rzp_test_xxxxxx
RAZORPAY_SECRET=xxxxxxxxxxxx
RAZORPAY_WEBHOOK_SECRET=your_webhook_secret
RAZORPAY_PLAN_ID_199=plan_xxxxxxFrontend .env
VITE_RAZORPAY_API_KEY=rzp_test_xxxxxxThe frontend only gets the public key ID. RAZORPAY_SECRET and RAZORPAY_WEBHOOK_SECRET never leave the server - not in API responses, not in logs, not anywhere.
BACKEND
Step 1 - Install the Razorpay SDK
npm install razorpayStep 2 - Initialize the SDK
Do this once, in a file your routes can import from.
import Razorpay from "razorpay";const razorpay = new Razorpay({
key_id: process.env.RAZORPAY_API_KEY,
key_secret: process.env.RAZORPAY_SECRET,
});Step 3 - Create Your Payment Routes
These routes handle order creation, verification, and subscription creation. Protect all of them with your auth middleware - a user shouldn’t be able to hit these without a valid session.
// payment.routes.js
router.post("/order", createOrderController); // one-time payment
router.post("/plan", createPlanController); // recurring subscription
router.post("/verify", verifyPaymentController); // verify after checkout
// in your main app file
app.use("/payment", AuthMiddleware, paymentRoutes);Step 4 - Create a One-Time Order
For one-time payments, your frontend needs an order_id from Razorpay before it can open Checkout. This endpoint creates it.
const createOrderController = async (req, res) => {
const { subscription } = req.body; // e.g. "QUESTION"
const amount = 49; // get this from your own constants, not from req.body
// Store a PENDING record in your DB before touching Razorpay
await storePaymentRecord({ user_id: req.user, plan: subscription, status: "PENDING" });
// Create the order on Razorpay
const order = await razorpay.orders.create({
amount: amount * 100, // ₹49 → 4900 paise. Don't forget this.
currency: "INR",
receipt: `receipt_${Date.now()}`,
payment_capture: 1,
});
// Update the DB record with the order_id Razorpay just gave us
await updatePaymentRecord({ order_id: order.id });return res.status(201).json({ order_id: order.id, amount: order.amount });
};Two things to note here. First, the amount goes in paise - ₹49 becomes 4900. Forget this, and your ₹499 plan charges ₹4.99. Second, create the DB record before calling Razorpay, with a PENDING status. This gives you a local paper trail even if something goes wrong mid-flow.
Step 5 - Create a Subscription (for Recurring Plans)
For recurring billing, use Razorpay Subscriptions instead of Orders. You’ll need to create a Plan in your Razorpay dashboard first and copy the plan ID into your .env.
const createPlanController = async (req, res) => {
// Check your DB — don't create a new subscription if one is already active
const isAlreadySubscribed = await checkActiveSubscription(req.user);
if (isAlreadySubscribed) {
return res.status(400).json({ message: "Already subscribed" });
}
const subscription = await razorpay.subscriptions.create({
plan_id: process.env.RAZORPAY_PLAN_ID_199,
total_count: 100,
quantity: 1,
customer_notify: 1,
notes: { user_id: req.user },
});
return res.status(201).json({ subscription_id: subscription.id });
};The response gives you a subscription_id. The frontend uses this instead of order_id when opening Checkout.
Step 6 - Verify the Payment Signature
This is the most important backend step. After a user pays, Razorpay sends three values to your frontend. Your frontend forwards them here, and your backend verifies they’re genuine.
const verifyPaymentController = async (req, res) => {
const { order_id, payment_id, signature } = req.body;
// Generate your own signature and compare
const generated_signature = crypto
.createHmac("sha256", process.env.RAZORPAY_SECRET)
.update(order_id + "|" + payment_id)
.digest("hex");if (generated_signature !== signature) {
// Signatures don't match - payment response was tampered with
// Mark payment as FAILED in your DB
await markPaymentFailed({ order_id });
return res.status(400).json({ message: "Payment verification failed" });
}
// Signatures match - mark as confirmed and activate access in your DB
await markPaymentConfirmed({ order_id, payment_id });
await activateUserAccess({ user_id: req.user });return res.status(200).json({ success: true });
};Do not skip this. Someone can open your browser dev tools, intercept the checkout response, and send fake values to this endpoint. The signature check is what catches that. Razorpay marks it as mandatory for exactly this reason.
FRONTEND
Step 1 - Install the React Wrapper
npm install react-razorpayThis package handles loading the Razorpay Checkout script and gives you a Razorpay constructor to work with.
Step 2 - Build the Payment Hook
All your payment logic lives here. The component just calls pay(planName) and this hook handles the rest.
// usePayment.js
import { useRazorpay } from "react-razorpay";
import axios from "axios";export const usePayment = ({ user, session }) => {
const { Razorpay } = useRazorpay();
const [isProcessing, setIsProcessing] = useState(false);
const pay = async (subscription) => {
setIsProcessing(true);
// Step 1: Ask backend to create the order or subscription
const isRecurring = subscription === "PRO";
const endpoint = isRecurring ? "/payment/plan" : "/payment/order";
const { data: orderData } = await axios.post(
`${import.meta.env.VITE_BACKEND_URL}${endpoint}`,
{ subscription },
{ headers: { Authorization: `Bearer ${session.access_token}` } }
);
// Step 2: Configure Checkout
const options = {
key: import.meta.env.VITE_RAZORPAY_API_KEY,
currency: "INR",
name: "Your App Name",
prefill: {
name: user.user_metadata?.full_name || "",
email: user.email,
},
handler: async (response) => {
// Step 3: After payment, send response to backend for verification
// Note: for subscriptions, Razorpay handles verification via webhooks
if (!isRecurring) {
await axios.post(
`${import.meta.env.VITE_BACKEND_URL}/payment/verify`,
{
order_id: response.razorpay_order_id,
payment_id: response.razorpay_payment_id,
signature: response.razorpay_signature,
},
{ headers: { Authorization: `Bearer ${session.access_token}` } }
);
}
setIsProcessing(false);
},
modal: {
ondismiss: () => setIsProcessing(false),
},
};
// Step 4: Attach the right ID — this is different for orders vs subscriptions
if (isRecurring) {
options.subscription_id = orderData.subscription_id; // recurring
} else {
options.order_id = orderData.order_id; // one-time
options.amount = orderData.amount;
}
// Step 5: Open Checkout
const rzp = new Razorpay(options);
rzp.open();
setIsProcessing(false);
};
return { pay, isProcessing };
};Step 3 - Use It in Your Component
// PricingModal.jsx
const PricingModal = ({ user, session }) => {
const { pay, isProcessing } = usePayment({ user, session }); return (
<div>
<button onClick={() => pay("PRO")} disabled={isProcessing}>
{isProcessing ? "Processing..." : "Subscribe — ₹199/mo"}
</button>
<button onClick={() => pay("QUESTION")} disabled={isProcessing}>
{isProcessing ? "Processing..." : "Buy Question Pack — ₹49"}
</button>
</div>
);
};The component itself knows nothing about Razorpay. It just calls pay() with a plan name.
BACKEND (continued)
Step 7 - Set Up Webhooks
This is where a lot of integrations are incomplete. Even for one-time payments, webhooks matter. If a user pays and then closes the browser before your frontend can call /payment/verify, that verification never happens. The webhook is what catches it and updates their access anyway.
Get Raj Gupta’s stories in your inbox
Join Medium for free to get updates from this writer.
For subscriptions it’s even more critical - renewals, cancellations, and failed charges all come through webhooks, not the frontend.
Register your webhook URL in the Razorpay Dashboard under Settings → Webhooks. Your endpoint needs to be publicly accessible.
// In your main app file — order matters here
app.use("/webhook", express.raw({ type: "*/*" }), webhookRouter);
app.use(express.json()); // This must come AFTER the webhook routeWhy raw body? Razorpay’s signature validation runs on the exact bytes of the request. If Express parses the JSON first, the body changes and your validation will always fail.
// webhook.controller.js
const paymentWebhookController = async (req, res) => {
// Verify the webhook is actually from Razorpay
const signature = req.headers["x-razorpay-signature"];
const rawBody = req.body.toString("utf8");
const isValid = Razorpay.validateWebhookSignature(
rawBody,
signature,
process.env.RAZORPAY_WEBHOOK_SECRET
);
if (!isValid) return res.status(400).send("Invalid signature");
// Check for duplicate events — Razorpay can send the same event more than once
const eventId = req.headers["x-razorpay-event-id"];
const alreadyProcessed = await hasWebhookBeenProcessed(eventId); // check your DB
if (alreadyProcessed) return res.status(200).send("Already processed");
// Store the event ID so we don't process it twice
await storeWebhookEventId(eventId);
const { event, payload } = JSON.parse(rawBody);
switch (event) {
case "payment.authorized":
// One-time payment confirmed
await grantAccess(payload.payment.entity);
break;
case "subscription.charged":
// Recurring payment went through
await activateSubscription(payload.subscription.entity);
break;
case "subscription.cancelled":
// User cancelled — revoke access at period end
await handleCancellation(payload.subscription.entity);
break;
}
return res.status(200).send("OK");
};⚠️ About this webhook setup
This works fine for a college project or an early-stage startup. The limitation is that your Express handler processes each webhook synchronously - if your database is slow or you get a traffic spike, timeouts happen and Razorpay retries, which can cause duplicate processing headaches.
Production systems at scale decouple this: the webhook endpoint just drops the event into a queue (BullMQ, SQS, RabbitMQ) and immediately returns 200 OK. A separate worker processes it. If you're just starting out, the direct approach above is fine. Just know this is the first thing you'd change once traffic picks up.
Database: Two Tables, Not One
Keep payment attempts and active access in separate tables.
userPaymentDetails -every attempt, successful or not
user_id | plan | order_id | payment_id | status
PENDING / CONFIRM / FAILEDuserSubscriptionDetails -what the user actually has right now
user_id | subscription_type | status | end_date
ACTIVE / EXPIRED / CANCELLEDA confirmed payment is not the same thing as active access. Keeping them separate makes it much easier to debug edge cases and handle things like refunds or expired subscriptions later.
Mistakes Worth Avoiding
Granting access from the frontend handler -the handler runs in the browser. It can be faked. Only grant access after backend verification.
Creating the order on the frontend - the frontend doesn’t know the real price. Always create orders server-side.
Using subscription_id where order_id is expected - one-time payments use order_id, recurring use subscription_id. They go in different fields in the checkout config.
Not handling subscription webhooks - Miss webhooks and your subscription users will have issues when renewal comes around.
Parsing webhook body before verification - already covered above, but it’s a common enough mistake to repeat: raw body first, JSON parsing after.
Before Going Live
- Orders and subscriptions created server-side only
RAZORPAY_SECRETnever sent to frontend- Signature verified on backend before granting access
- Webhook route receives raw body before JSON middleware
- Webhook signatures validated with
RAZORPAY_WEBHOOK_SECRET - Duplicate webhook events handled via
x-razorpay-event-id - Amount and plan defined on backend, not taken from request body
