Razorpay Mock Studio ⚡

🛑 DISCLAIMER: UNOFFICIAL COMMUNITY TOOL This package is not affiliated with, endorsed by, or maintained by Razorpay Software Private Limited. It is an independent, unofficial mock server built by the community for local testing purposes. All trademarks belong to their respective owners.

A high-fidelity, local mock engine and dashboard for testing Razorpay integrations without exposing real credentials or interacting with the live banking network.

🚀 Getting Started

If you install the mock studio via npm in your project, starting the mock server is extremely simple!

Installation

Run the following command in your project directory:

npm install -g @premprakashgupta/razorpay-mock-server
npm install @premprakashgupta/razorpay-mock-client --save

Starting the Server

Once installed, you can start the mock server anywhere inside your project by running:

npx @premprakashgupta/razorpay-mock-server

Volatile CI/CD Mode: If you are running the mock server in a CI pipeline (e.g. GitHub Actions) and want to avoid writing to a local db.json file, use the --memory-only flag:

npx @premprakashgupta/razorpay-mock-server --memory-only

Alternatively, you can just add a simple script to your package.json to make it easier to launch alongside your dev server:

{
  "scripts": {
    "dev": "your-dev-command",
    "mock-studio": "razorpay-mock-studio"
  }
}

The Mock Studio dashboard will instantly be available at: http://localhost:3001/studio

⚡ Instant Project Scaffolding

Don't want to manually integrate into an existing app? Both packages contain built-in boilerplate generators!

1. Generating a Backend Playground

If you want a ready-to-run Mock Backend folder, run:

npx @premprakashgupta/razorpay-mock-server init

This instantly scaffolds a razorpay-mock-backend/ folder complete with configuration wrappers.

2. Generating a Frontend React Boilerplate

If you want to test the checkout UI without setting up a React app manually:

npx @premprakashgupta/razorpay-mock-client init

This drops a razorpay-mock-frontend/ folder containing standard Checkout.js and Checkout.tsx boilerplate implementations!

🛠️ Integration Guide

1. Update API Keys

Go to the API Keys tab in the Mock Studio and copy your key_id and key_secret. Use these safely in your local .env file instead of your real Razorpay credentials.

2. Connect Your Backend (Node.js SDK)

When creating orders on your server, simply inject the x-razorpay-mock-host header to route requests to the Mock Studio instead of the live Razorpay API:

const Razorpay = require('razorpay');

const rzp = new Razorpay({
  key_id: process.env.RAZORPAY_KEY_ID,    // From Mock Studio
  key_secret: process.env.RAZORPAY_SECRET, // From Mock Studio
  headers: {
    'x-razorpay-mock-host': 'http://localhost:3001'
  }
});

// Orders will now hit your local Mock DB natively
const order = await rzp.orders.create({ amount: 500, currency: 'INR' });

// You can also create Plans and Subscriptions!
const plan = await rzp.plans.create({ period: 'monthly', interval: 1, item: { name: 'Pro', amount: 50000, currency: 'INR' } });
const sub = await rzp.subscriptions.create({ plan_id: plan.id, total_count: 12 });

// You can process Refunds against captured Order IDs
const refund = await rzp.payments.refund("pay_MOCK1234", { amount: 500 });

3. Connect Your Frontend Client

Replace the official Razorpay script/hook with the mock client in your frontend app (React, Vue, plain JS, etc.):

import { useRazorpay } from "@premprakashgupta/razorpay-mock-client";

// The rest of your code remains identical!
const Razorpay = useRazorpay();

// Works for both one-time orders and subscriptions natively:
const rzp = new Razorpay({
   key: options.key,
   order_id: options.order_id, // OR subscription_id: options.subscription_id
   handler: function (response) {
      console.log(response.razorpay_payment_id);
   }
   // ...
});
rzp.open();

🔁 Webhooks & HMAC Verification

Mock Studio implements the exact same HMAC SHA-256 signature algorithm used by Razorpay for production webhook deliveries.

1. Open the Mock Studio Webhooks tab.
2. Click Add Webhook and provide your local endpoint (e.g., http://localhost:3000/api/webhook) and a secret.
3. Every time a mock payment is successful, Mock Studio will fire a payment.captured event to your endpoint.
4. Your application can verify the x-razorpay-signature HTTP header exactly as it would in production!

💡 Express.js Pro Tip: If your backend uses Express, ensure your webhook route is placed above the express.json() middleware, or that you use express.raw({type: 'application/json'}) for this specific route.

🗄️ Database & Storage

Razorpay Mock Studio uses the native Node.js SQLite engine for production-grade stability and zero external dependencies.

• Persistence: By default, it creates a hidden .razorpay-mock folder in your project directory to store the SQLite database. This hidden folder ensures that tools like Next.js, Vite, and Webpack do not trigger infinite re-build loops when the database is updated.
• Requirements: This tool requires Node.js 22.5.0 or higher (recommended Node 24+) to utilize the built-in SQLite features.

💡 Troubleshooting & Performance

If you are running a very large project (e.g., Next.js 15 with Turbopack) and encounter a "Fatal process out of memory" error in your frontend, this is a known issue with the memory overhead of modern build tools on newer Node versions.

Recommended Fix: Increase your Node.js heap limit by setting the following environment variable before starting your dev server:

# Windows (PowerShell)
$env:NODE_OPTIONS="--max-old-space-size=4096"

# Mac/Linux
export NODE_OPTIONS="--max-old-space-size=4096"