Skip to main content
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

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.
string
Your Razorpay key id, for example rzp_test_XXXX. Required when razorpayClient is not provided.
string
Your Razorpay key secret. Required when razorpayClient is not provided, and also required for payment signature verification.
If you omit both razorpayClient and either keyId or keySecret, the plugin throws Provide either razorpayClient or both keyId and keySecret. at runtime.

Behavior

string
default:"INR"
ISO 4217 currency code used as the default for orders, plans, and invoices when no currency is explicitly supplied.
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.
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

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.
({ 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.
(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.
When createCustomerOnSignUp is enabled, the plugin also syncs the Razorpay customer email automatically whenever the user’s email is updated in Better Auth.

Subscriptions

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

{ 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 for the full setup.
(organization, ctx) => Promise<Partial<customer create params>>
Same shape as the user-level getCustomerCreateParams, but receives the organization record instead of the user.
({ razorpayCustomer, organization }, ctx) => void | Promise<void>
Called after the Razorpay customer for an organization is created.

Webhook callbacks

(event) => void | Promise<void>
Called for every Razorpay webhook event before any specific handler runs. Use it for logging or custom routing.
({ event, payment }) => void | Promise<void>
Fired when a payment is authorized.
({ event, payment }) => void | Promise<void>
Fired when a payment is captured.
({ event, payment }) => void | Promise<void>
Fired when a payment fails.
({ 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.
({ event, refund }) => void | Promise<void>
Fired when a refund is created.
({ event, refund }) => void | Promise<void>
Fired when a refund is processed.
({ event, refund }) => void | Promise<void>
Fired when a refund fails.
({ event, invoice }) => void | Promise<void>
Fired when an invoice is fully paid.
({ event, invoice }) => void | Promise<void>
Fired when an invoice receives a partial payment.
({ event, invoice }) => void | Promise<void>
Fired when an invoice expires.
Subscription lifecycle callbacks such as onSubscriptionActivated and onSubscriptionCharged are defined inside subscription options, not at the top level. See subscription plans for details.
For a complete list of webhook event names and when they fire, read the webhook events reference.

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.
auth.ts
After changing schema-related options, run npx @better-auth/cli migrate or generate to apply database migrations.