npm package: @premprakashgupta/razorpay-mock-client
Description: Pixel-perfect Razorpay Checkout Mock for Frontend
Latest version: 1.0.2

# 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:
```bash
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:
```bash
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:
```bash
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:
```json
{
  "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:
```bash
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:
```bash
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:

```javascript
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.):

```javascript
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:

```bash
# Windows (PowerShell)
$env:NODE_OPTIONS="--max-old-space-size=4096"

# Mac/Linux
export NODE_OPTIONS="--max-old-space-size=4096"
```

---