> ## Documentation Index
> Fetch the complete documentation index at: https://better-auth-razorpay.amankushwaha.dev/llms.txt
> Use this file to discover all available pages before exploring further.

# Installation

> Install the Better Auth Razorpay plugin, set up environment variables, and configure your server and database.

This page covers installing the package, satisfying peer dependencies, setting environment variables, and wiring the plugin into your server and database.

## Install the package

Use your preferred package manager:

```bash theme={null}
npm install @amank-root/better-auth-razorpay
```

```bash theme={null}
yarn add @amank-root/better-auth-razorpay
```

```bash theme={null}
pnpm add @amank-root/better-auth-razorpay
```

```bash theme={null}
bun add @amank-root/better-auth-razorpay
```

## Peer dependencies

The server plugin requires these peers. They should already be present in a Better Auth project.

| Package | Version |
| - | - |
| `better-auth` | `^1.7.0` |
| `@better-auth/core` | `^1.7.0` |
| `typescript` | `^5.6.3` |

If you use the React hooks, you also need:

| Package | Version |
| - | - |
| `@tanstack/react-query` | `^5.104.3` |
| `react` | `^19.3.0` |

## Package entry points

The plugin exposes three entry points:

| Entry point | Purpose |
| - | - |
| `@amank-root/better-auth-razorpay` | Server plugin, types, and signature utilities |
| `@amank-root/better-auth-razorpay/client` | Client plugin for `createAuthClient` |
| `@amank-root/better-auth-razorpay/react` | TanStack Query hooks for React |

## Environment variables

Add these to your environment. Use test mode keys while developing.

```bash .env theme={null}
RAZORPAY_KEY_ID=rzp_test_XXXXXXXXXXXX
RAZORPAY_KEY_SECRET=XXXXXXXXXXXXXXXX
RAZORPAY_WEBHOOK_SECRET=whsec_XXXXXXXXXXXX
```

* `RAZORPAY_KEY_ID`: Your Razorpay API key id. Prefix with `rzp_test_` for test mode and `rzp_live_` for live mode.
* `RAZORPAY_KEY_SECRET`: Your Razorpay API key secret. Required for payment verification and server-side operations.
* `RAZORPAY_WEBHOOK_SECRET`: A secret you choose and configure in the Razorpay Dashboard. Used to verify webhook signatures.

You can find your keys in the Razorpay Dashboard under Account & Settings > API Keys. Toggle between test and live mode in the dashboard header. Test mode transactions use test cards and do not move real money.

## Alternative: pass a Razorpay client instance

Instead of passing `keyId` and `keySecret`, you can provide your own `Razorpay` instance. This is useful if you already manage a Razorpay client elsewhere in your application.

```ts auth.ts theme={null}
import { betterAuth } from "better-auth";
import Razorpay from "razorpay";
import { razorpay } from "@amank-root/better-auth-razorpay";

const razorpayClient = new Razorpay({
  key_id: process.env.RAZORPAY_KEY_ID!,
  key_secret: process.env.RAZORPAY_KEY_SECRET!,
});

export const auth = betterAuth({
  plugins: [
    razorpay({
      razorpayClient,
      razorpayWebhookSecret: process.env.RAZORPAY_WEBHOOK_SECRET,
    }),
  ],
});
```

If you provide neither `razorpayClient` nor both `keyId` and `keySecret`, the plugin throws an error at initialization.

## Mount the handler

All plugin endpoints live under your Better Auth base path. Mount the handler for your framework.

### Next.js App Router

```ts app/api/auth/[...all]/route.ts theme={null}
import { auth } from "@/auth";
import { toNextJsHandler } from "better-auth/next-js";

export const { POST, GET } = toNextJsHandler(auth);
```

### Express

```ts server.ts theme={null}
import { toNodeHandler } from "better-auth/node";
app.all("/api/auth/*", toNodeHandler(auth));
```

Use the equivalent adapter for other frameworks (for example, `toSolidStartHandler`, `toSvelteKitHandler`, or `toHonoHandler` from Better Auth).

## Run schema migration

The plugin adds fields and tables to your database, such as `user.razorpayCustomerId` and a local `subscription` table when subscriptions are enabled. Run Better Auth's migration command after adding the plugin.

```bash theme={null}
npx @better-auth/cli migrate
```

If you prefer to inspect the generated SQL first, run:

```bash theme={null}
npx @better-auth/cli generate
```

Then apply the generated migration to your database before starting the application.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.