Skip to main content
The plugin exposes full invoice and payment-link management through Better Auth endpoints. You can create draft invoices, add line items, issue them to customers, and react to payment events via webhooks. This page covers the full lifecycle from server configuration to React hooks.

Server setup

Enable the plugin in your Better Auth server configuration. No additional plugin options are required for invoices, but you need a valid Razorpay key pair and the webhook secret if you plan to handle invoice events.
auth.ts
Mount the Better Auth handler so the plugin endpoints are reachable under your auth base path, for example /api/auth/*. Invoices can be created as a draft (type: "invoice") or as a payment link (type: "link"). A draft invoice must be issued before the customer can pay. A payment link is immediately shareable.
client.ts
string
"invoice" for a draft invoice, or "link" for a payment link.
string
A short description of the invoice.
integer
Unix timestamp for the invoice date.
object
Customer details including name, email, contact, and addresses.
array
required
At least one line item. Each item can use an existing id (item ID) or inline name, amount, currency, description, and quantity.
string
default:"INR"
Three-letter currency code.
integer
Unix timestamp after which the invoice expires.
boolean
Send SMS notifications to the customer.
boolean
Send email notifications to the customer.
boolean
Allow partial payments.
object
Up to 15 key-value pairs, each value up to 256 characters.

Edit a draft invoice

Only draft invoices can be edited. After an invoice is issued, most fields become immutable in Razorpay.
client.ts

Issue an invoice

A draft invoice must be issued before the customer can pay it.
client.ts

Notify a customer

Send a reminder by email or SMS for an issued invoice.
client.ts

Cancel or delete an invoice

Cancel an issued invoice to prevent further payment. Delete a draft invoice to remove it entirely.
client.ts

List and fetch invoices

Query invoices with filters and pagination.
client.ts
string
Filter by "invoice" or "link".
string
Filter by the associated payment ID.
string
Filter by receipt ID.
string
Filter by customer ID.
string
Filter by subscription ID.
integer
Number of results to fetch, up to 100.
integer
Number of results to skip.

Webhook events

Configure the Razorpay webhook in your dashboard to point to the plugin’s webhook endpoint, for example https://your-domain.com/api/auth/razorpay/webhook, and select the invoice events. The plugin verifies the x-razorpay-signature header and invokes the matching callback.
Confirm the exact webhook path in your server setup. If requests return 404, check the registered plugin endpoints under your auth base path.
The following callbacks are available for invoice events:
  • onInvoicePaid — fired when invoice.paid is received.
  • onInvoicePartiallyPaid — fired when invoice.partially_paid is received.
  • onInvoiceExpired — fired when invoice.expired is received.
All invoice webhooks also trigger the global onEvent callback before the specific handler runs.

React hooks

If you use TanStack Query in your React app, import the hooks from the React entry point.

Create an invoice

invoice-form.tsx

List invoices

invoice-list.tsx

Issue and notify

invoice-actions.tsx

Error codes

The following error codes may be returned during invoice operations:
  • INVOICE_CREATE_FAILED: the invoice could not be created in Razorpay.
  • INVOICE_NOT_FOUND: the requested invoice does not exist.
  • INVOICE_FETCH_FAILED: failed to fetch an invoice.
  • INVOICE_LIST_FAILED: failed to list invoices.
  • INVOICE_EDIT_FAILED: the draft invoice could not be edited.
  • INVOICE_ISSUE_FAILED: the invoice could not be issued.
  • INVOICE_DELETE_FAILED: the invoice could not be deleted.
  • INVOICE_CANCEL_FAILED: the invoice could not be cancelled.
  • INVOICE_NOTIFY_FAILED: the notification could not be sent.

Next steps

  • Customers — manage customer records linked to invoices.
  • Items and add-ons — create catalog items to reuse in invoice line items.
  • Webhooks — learn how to configure and verify webhook delivery.