> ## 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.

# Quickstart

> Get your first Razorpay payment working end to end with Better Auth in a few steps.

This guide walks you through your first end-to-end Razorpay payment with Better Auth. You will install the plugin, add environment variables, configure the server and client, create an order, open Razorpay Checkout, verify the payment, and receive a webhook confirmation.

**1. Install the package**

Install the plugin with your preferred package manager. You also need `better-auth` and its peer dependencies.

```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
```

**2. Add environment variables**

Add your Razorpay keys 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
```

You can find these in the Razorpay Dashboard under Account & Settings > API Keys.

**3. Configure the server plugin**

Import `razorpay` from the server package and add it to your Better Auth config. The plugin registers all endpoints under your auth base path, such as `/api/auth/*`.

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

export const auth = betterAuth({
  plugins: [
    razorpay({
      keyId: process.env.RAZORPAY_KEY_ID!,
      keySecret: process.env.RAZORPAY_KEY_SECRET!,
      razorpayWebhookSecret: process.env.RAZORPAY_WEBHOOK_SECRET,
      createCustomerOnSignUp: true,
      subscription: {
        enabled: true,
        plans: [{ planId: "plan_XXXX", name: "pro" }],
      },
    }),
  ],
});
```

Mount the Better Auth handler in your framework. For example, in 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);
```

Or in Express:

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

**4. Run schema migration**

The plugin adds fields and tables to your database. Run Better Auth's migration command to apply them.

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

If you prefer to generate a migration file first, run:

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

**5. Configure the client plugin**

Create your auth client with the Razorpay client plugin. Set `subscription: true` when your server has subscriptions enabled.

```ts client.ts theme={null}
import { createAuthClient } from "better-auth/react";
import { razorpayClient } from "@amank-root/better-auth-razorpay/client";

export const authClient = createAuthClient({
  plugins: [razorpayClient({ subscription: true })],
});
```

**6. Create an order and open Checkout**

In your frontend, create a Razorpay order through the auth client, then open Razorpay Checkout with the returned order id.

```tsx checkout.tsx theme={null}
"use client";

import { authClient } from "@/client";

export function CheckoutButton() {
  async function handlePay() {
    const { data: order, error } = await authClient.razorpay.createOrder({
      amount: 50000, // INR 500 in paise
      currency: "INR",
      receipt: "rcpt_001",
    });

    if (error || !order) {
      console.error(error);
      return;
    }

    const rzp = new window.Razorpay({
      key: process.env.NEXT_PUBLIC_RAZORPAY_KEY_ID!,
      order_id: order.id,
      amount: order.amount,
      currency: order.currency,
      name: "My Store",
      description: "Premium plan",
      handler: async (response: {
        razorpay_order_id: string;
        razorpay_payment_id: string;
        razorpay_signature: string;
      }) => {
        const { data, error: verifyError } =
          await authClient.razorpay.verifyPayment({
            razorpayOrderId: response.razorpay_order_id,
            razorpayPaymentId: response.razorpay_payment_id,
            razorpaySignature: response.razorpay_signature,
          });

        if (verifyError) {
          console.error(verifyError);
          return;
        }

        console.log("Verification result:", data);
      },
    });

    rzp.open();
  }

  return <button onClick={handlePay}>Pay INR 500</button>;
}
```

> [!TIP]
>
> Load the Razorpay Checkout script in your app root or page head:
>
> ```html theme={null}
> <script src="https://checkout.razorpay.com/v1/checkout.js" async />
> ```

**7. Verify the payment on the server**

The `verifyPayment` client call already hits your server endpoint, which checks the signature and payment status. For extra safety, also listen to the `order.paid` webhook before fulfilling the order. See the next step.

**8. Set up a webhook**

Configure a webhook in the Razorpay Dashboard pointing to your plugin's webhook endpoint, for example `https://your-domain.com/api/auth/razorpay/webhook`. Provide the same secret you set in `RAZORPAY_WEBHOOK_SECRET` and select the events you need, such as `order.paid`.

On the server, handle the event with the plugin's built-in webhook support. Use the `onOrderPaid` callback to fulfill orders reliably.

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

export const auth = betterAuth({
  plugins: [
    razorpay({
      keyId: process.env.RAZORPAY_KEY_ID!,
      keySecret: process.env.RAZORPAY_KEY_SECRET!,
      razorpayWebhookSecret: process.env.RAZORPAY_WEBHOOK_SECRET,
      onOrderPaid: async ({ event, order }) => {
        console.log("Order paid:", order.id);
        // fulfill the order here
      },
    }),
  ],
});
```

> [!NOTE]
>
> The exact webhook path depends on your auth base path and the plugin's route registration. If requests return 404, confirm the path in your server setup (for example, by listing the plugin endpoints).

## Next steps

> [card] [One-time payments](https://better-auth-razorpay.amankushwaha.dev/guides/one-time-payments.md)
>
> Learn about manual capture, partial payments, and refunds.

> [card] [Subscriptions](https://better-auth-razorpay.amankushwaha.dev/guides/subscriptions.md)
>
> Set up recurring billing, trials, and seat-based plans.

> [card] [Webhooks](https://better-auth-razorpay.amankushwaha.dev/guides/webhooks.md)
>
> See all supported events and how to handle them.

> [card] [React hooks](https://better-auth-razorpay.amankushwaha.dev/react/overview.md)
>
> Use TanStack Query hooks for subscriptions and payments.


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