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

# Plugin options

> Complete reference for every option accepted by the Razorpay plugin in your Better Auth server config.

The Razorpay plugin accepts a single options object when you call `razorpay(...)` inside your `betterAuth` plugins array. This page lists every option, grouped by purpose, so you can configure credentials, customer behavior, subscriptions, organizations, webhooks, and schema overrides in one place.

## Credentials

**razorpayClient** `Razorpay instance`

An existing `Razorpay` instance created with `new Razorpay({ key_id, key_secret })`. Use this when you already manage a Razorpay client elsewhere in your application.

**keyId** `string`

Your Razorpay key id, for example `rzp_test_XXXX`. Required when `razorpayClient` is not provided.

**keySecret** `string`

Your Razorpay key secret. Required when `razorpayClient` is not provided, and also required for payment signature verification.

> [!WARNING]
>
> If you omit both `razorpayClient` and either `keyId` or `keySecret`, the plugin throws `Provide either razorpayClient or both keyId and keySecret.` at runtime.

## Behavior

**defaultCurrency** `string` (default: INR)

ISO 4217 currency code used as the default for orders, plans, and invoices when no currency is explicitly supplied.

**requireSession** `boolean` (default: true)

When `true`, the one-time payment and Route transfer endpoints require an active Better Auth session. Set to `false` to remove session middleware from those endpoints.

**razorpayWebhookSecret** `string`

The secret used to verify Razorpay webhook signatures. If this is missing when a webhook arrives, the plugin raises `WEBHOOK_SECRET_NOT_FOUND`. See the webhooks guide for setup instructions.

## Customers

**createCustomerOnSignUp** `boolean` (default: false)

When `true`, a Razorpay customer is created automatically when a user signs up. The customer id is stored on `user.razorpayCustomerId`, and the `onCustomerCreate` callback is invoked. This is required for subscription upgrades; without it the plugin raises `CUSTOMER_NOT_FOUND`.

**onCustomerCreate** `(\{ razorpayCustomer, user \}, ctx) =\> void | Promise\<void\>`

Called after a Razorpay customer is created during sign-up. Use it to sync extra fields into your own database or trigger welcome emails.

**getCustomerCreateParams** `(user, ctx) =\> Promise\<Partial\<customer create params\>\>`

Merge additional parameters into the Razorpay customer create call. Return an object with fields such as `contact`, `gstin`, or `notes`.

> [!TIP]
>
> When `createCustomerOnSignUp` is enabled, the plugin also syncs the Razorpay customer email automatically whenever the user's email is updated in Better Auth.

## Subscriptions

**subscription** `\{ enabled: false \} | \{ enabled: true, ...SubscriptionOptions \}`

Controls whether subscription endpoints and the local `subscription` table are registered. Set `enabled: true` to unlock plan management, upgrades, cancellations, and lifecycle webhooks. See [subscription plans](https://better-auth-razorpay.amankushwaha.dev/configuration/subscription-plans.md) for the full `SubscriptionOptions` reference.

When `subscription.enabled` is `true`, the plugin registers endpoints for upgrading, cancelling, pausing, resuming, updating, restoring, and listing subscriptions. Razorpay subscription APIs such as `fetchSubscription`, `createSubscriptionLink`, and `fetchPendingUpdate` are always registered regardless of this flag.

## Organizations

**organization** `\{ enabled: true, getCustomerCreateParams?, onCustomerCreate? \}`

Enables organization-level subscriptions. Requires the Better Auth `organization()` plugin. When enabled, each organization can have its own Razorpay customer id, and seat-based plans automatically sync member counts to subscription quantity. See [organizations](https://better-auth-razorpay.amankushwaha.dev/configuration/organizations.md) for the full setup.

**organization.getCustomerCreateParams** `(organization, ctx) =\> Promise\<Partial\<customer create params\>\>`

Same shape as the user-level `getCustomerCreateParams`, but receives the organization record instead of the user.

**organization.onCustomerCreate** `(\{ razorpayCustomer, organization \}, ctx) =\> void | Promise\<void\>`

Called after the Razorpay customer for an organization is created.

## Webhook callbacks

**onEvent** `(event) =\> void | Promise\<void\>`

Called for every Razorpay webhook event before any specific handler runs. Use it for logging or custom routing.

**onPaymentAuthorized** `(\{ event, payment \}) =\> void | Promise\<void\>`

Fired when a payment is authorized.

**onPaymentCaptured** `(\{ event, payment \}) =\> void | Promise\<void\>`

Fired when a payment is captured.

**onPaymentFailed** `(\{ event, payment \}) =\> void | Promise\<void\>`

Fired when a payment fails.

**onOrderPaid** `(\{ event, order \}) =\> void | Promise\<void\>`

Fired when an order is fully paid. This is the safest place to fulfill goods or services because the signature and amount have already been verified by Razorpay.

**onRefundCreated** `(\{ event, refund \}) =\> void | Promise\<void\>`

Fired when a refund is created.

**onRefundProcessed** `(\{ event, refund \}) =\> void | Promise\<void\>`

Fired when a refund is processed.

**onRefundFailed** `(\{ event, refund \}) =\> void | Promise\<void\>`

Fired when a refund fails.

**onInvoicePaid** `(\{ event, invoice \}) =\> void | Promise\<void\>`

Fired when an invoice is fully paid.

**onInvoicePartiallyPaid** `(\{ event, invoice \}) =\> void | Promise\<void\>`

Fired when an invoice receives a partial payment.

**onInvoiceExpired** `(\{ event, invoice \}) =\> void | Promise\<void\>`

Fired when an invoice expires.

> [!NOTE]
>
> Subscription lifecycle callbacks such as `onSubscriptionActivated` and `onSubscriptionCharged` are defined inside `subscription` options, not at the top level. See [subscription plans](https://better-auth-razorpay.amankushwaha.dev/configuration/subscription-plans.md) for details.

For a complete list of webhook event names and when they fire, read the [webhook events reference](https://better-auth-razorpay.amankushwaha.dev/reference/webhook-events.md).

## Schema

**schema** `Better Auth plugin schema customization`

Override or extend the plugin's database schema. Use this to rename columns, add indexes, or change field types within Better Auth's schema customization system.

## Full example

The following configuration uses most options in a single `betterAuth` setup. Adjust values for your own keys, plans, and business logic.

```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,
      defaultCurrency: "INR",
      requireSession: true,
      createCustomerOnSignUp: true,
      onCustomerCreate: async ({ razorpayCustomer, user }) => {
        console.log("Razorpay customer created", razorpayCustomer.id, "for", user.id);
      },
      getCustomerCreateParams: async (user) => {
        return { contact: user.phone ?? undefined };
      },
      subscription: {
        enabled: true,
        plans: [
          { planId: "plan_XXXX", name: "starter", totalCount: 12 },
          { planId: "plan_YYYY", name: "pro", annualPlanId: "plan_ZZZZ", totalCount: 12, quantity: 1 },
        ],
        requireEmailVerification: false,
        onSubscriptionActivated: async ({ subscription, plan }) => {
          console.log("Activated", subscription.id, "on plan", plan.name);
        },
      },
      organization: {
        enabled: true,
        onCustomerCreate: async ({ razorpayCustomer, organization }) => {
          console.log("Org customer created", razorpayCustomer.id, "for", organization.id);
        },
      },
      onOrderPaid: async ({ order }) => {
        console.log("Order paid", order.id);
      },
      onPaymentCaptured: async ({ payment }) => {
        console.log("Payment captured", payment.id);
      },
    }),
  ],
});
```

> [!NOTE]
>
> After changing schema-related options, run `npx @better-auth/cli migrate` or `generate` to apply database migrations.


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