Registry / payments / better-auth-razorpay

better-auth-razorpay

library2.0.7jsnpmunverified

The `better-auth-razorpay` package provides a robust and type-safe integration of Razorpay payment functionalities into applications utilizing `better-auth`. As of version 2.0.7, it offers comprehensive support for the full Razorpay subscription lifecycle, including creation, upgrades, cancellations, pauses, and resumptions, alongside features like trial abuse prevention and automatic customer synchronization with user details. It caters to various billing models, including organization and seat-based billing, and provides secure, HMAC-SHA256 verified webhook processing for all critical Razorpay events. The plugin also ships with pre-built React hooks leveraging TanStack Query for seamless client-side integration and boasts end-to-end TypeScript coverage, ensuring type safety across its API. While a specific release cadence isn't published, it aligns with `better-auth` ecosystem updates and feature-driven development, often introducing new capabilities or refinements.

payments auth-security web-framework

npm install better-auth-razorpay

github ↗package ↗

INSTALL

IMPORT

SIG · BETTER-AUTH-RAZORP

better-auth-razorpay

paymentsjavascriptv2.0.7

Install

—

Import

—

Disk

—

Pass rate

0/ 6

Env Coverage0 / 6

glibc

18–22

musl

18–22

Install & Compatibility

Where this runs

tested against v? · npm install

Install × environment matrix

Each cell = how many times install + import succeeded across repeated harness runs. Partial = flaky.
glibc = Debian/Ubuntu slim · musl = Alpine Linux

musl

node 18–226 runs

build_error

glibc

node 18–226 runs

build_error

Code

Verified usage

Verified import paths — ran on the pinned version, not inferred.

razorpay

✓ import { razorpay } from 'better-auth-razorpay';

✗ const { razorpay } = require('better-auth-razorpay');

This is the server-side plugin initializer. Prefer ESM imports for `better-auth` plugins.

razorpayClient

✓ import { razorpayClient } from 'better-auth-razorpay/client';

✗ import { razorpay } from 'better-auth-razorpay/client';

This is the client-side plugin initializer, imported from a subpath. Ensure correct named import.

RazorpayPluginOptions

✓ import type { RazorpayPluginOptions } from 'better-auth-razorpay';

✗ import { RazorpayPluginOptions } from 'better-auth-razorpay';

Always use `import type` for type-only imports to prevent accidental runtime imports and optimize bundle size.

Demonstrates how to initialize the `better-auth-razorpay` plugin on the server, configure the Razorpay client, set up webhooks, and define subscription plans with lifecycle callbacks.

import { betterAuth } from "better-auth"; import { razorpay } from "better-auth-razorpay"; import Razorpay from "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 ?? '', createCustomerOnSignUp: true, subscription: { enabled: true, plans: [ { planId: "plan_XXXXXXXXXX", // Replace with your Razorpay Plan ID name: "pro", totalCount: 12, }, { planId: "plan_YYYYYYYYYY", // Replace with your Razorpay Plan ID annualPlanId: "plan_ZZZZZZZZZZ", // Optional: Annual Plan ID name: "enterprise", totalCount: 1, quantity: 1, // seat-based example }, ], onSubscriptionActivated: async ({ subscription, plan, event }) => { console.log(`Subscription activated: ${subscription.id} for plan ${plan.name}`); // Implement your business logic here, e.g., update user roles }, // ... other lifecycle callbacks }, }), ], });

Debug

Known issues

breakingMajor version updates (e.g., from 1.x to 2.x) may introduce breaking changes to the plugin's configuration options or API surface. Always review release notes or migration guides when upgrading major versions to avoid unexpected issues.

fix

Consult the `better-auth-razorpay` GitHub repository for specific migration instructions or breaking changes documentation associated with your target version.

affects: >=2.0.0

gotchaThe `razorpayWebhookSecret` is critical for verifying the authenticity of Razorpay webhooks using HMAC-SHA256. Misconfiguration, exposure, or failure to set this secret can lead to security vulnerabilities or processing of fraudulent webhook events.

fix

Ensure `razorpayWebhookSecret` matches the secret configured in your Razorpay dashboard exactly. Store this secret securely in environment variables and never hardcode it.

affects: >=1.0.0

gotchaAPI keys (`RAZORPAY_KEY_ID`, `RAZORPAY_KEY_SECRET`) and the webhook secret should always be managed as environment variables. Hardcoding these credentials or committing them to version control poses a significant security risk.

fix

Use a robust environment variable management system (e.g., `.env` files, cloud secrets managers) to inject these sensitive values at runtime. Never embed them directly in your codebase.

affects: >=1.0.0

gotchaFailure to select all necessary webhook events in the Razorpay dashboard (as outlined in the documentation, e.g., `subscription.activated`, `subscription.cancelled`, `subscription.updated`) will result in incomplete or incorrect subscription lifecycle management within your application.

fix

Carefully review the required webhook events in the `better-auth-razorpay` documentation and ensure all specified events are enabled and correctly configured in your Razorpay dashboard for the registered webhook URL.

affects: >=1.0.0

gotchaThe `better-auth-razorpay` plugin has distinct server-side (`razorpay`) and client-side (`razorpayClient`) initializers, typically imported from different paths (`better-auth-razorpay` vs. `better-auth-razorpay/client`). Mismatched or incorrect imports are a common source of setup errors.

fix

Always use `import { razorpay } from 'better-auth-razorpay';` for server-side `betterAuth` configuration and `import { razorpayClient } from 'better-auth-razorpay/client';` for client-side `createAuthClient` configuration.

affects: >=1.0.0

Errors

Common errors & fixes

Error: Webhook signature verification failed.

The `razorpayWebhookSecret` configured in the plugin does not match the secret set in the Razorpay dashboard, or the raw request body was not properly passed to the handler.

fix

Ensure `process.env.RAZORPAY_WEBHOOK_SECRET` exactly matches the secret in your Razorpay dashboard. If using a web framework like Express, ensure you are using `express.raw()` or similar middleware for the webhook endpoint to capture the raw request body before parsing.

Razorpay Error: Bad Request - The subscription plan specified is invalid.

The `planId` configured in your `subscription.plans` array does not exist, is inactive, or is incorrectly mapped in your Razorpay account.

fix

Double-check all `planId` values in your `better-auth-razorpay` server-side configuration against active plans in your Razorpay dashboard. Ensure the `name` property for each plan is unique and correctly corresponds to the Razorpay `planId`.

TypeError: Cannot read properties of undefined (reading 'plugins') or Plugin 'razorpay' not found.

The `better-auth-razorpay` plugin was not correctly initialized and passed to the `betterAuth` instance's `plugins` array on the server, or the client-side plugin was not passed to `createAuthClient`.

fix

Verify that `razorpay({...})` is included in the `plugins` array for `betterAuth` on the server, and `razorpayClient({...})` is included in the `plugins` array for `createAuthClient` on the client. Ensure all required configuration options are provided to the plugin.

TS2307: Cannot find module 'better-auth-razorpay/client' or its corresponding type declarations.

Incorrect import path for the client-side plugin or a TypeScript module resolution issue.

fix

Ensure you are using the correct import statement: `import { razorpayClient } from 'better-auth-razorpay/client';`. If the issue persists, check your `tsconfig.json` for appropriate `moduleResolution` settings and ensure the package is correctly installed.

Upgrade

Version history

2.0.7latest on npm

Audit

Dependencies

better-authrequiredCore authentication library this plugin extends.

razorpayrequiredOfficial Razorpay SDK used for server-side interactions.

@tanstack/react-queryoptionalRequired for client-side React hooks for data fetching and caching.

reactoptionalRequired for client-side React hooks functionality.

Agent activity

49 hits · last 30 days

node

Perplexity

OpenAI (training)

Resources

githubhttps://github.com/iamjasonkendrick/better-auth-razorpay ↗

packagehttps://www.npmjs.com/package/better-auth-razorpay ↗