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

# One-time payments

> Create orders, collect payments with Razorpay Checkout, verify signatures, and fulfill purchases securely using webhooks.

This guide shows you how to accept one-time payments using the better-auth-razorpay plugin. You will create a Razorpay order from your server, render Razorpay Checkout on the client, verify the payment signature, and fulfill the purchase using the `order.paid` webhook.

**1. Create a Razorpay order**

On the server, call `authClient.razorpay.createOrder` or `auth.api.createRazorpayOrder` to create a Razorpay order. The amount must be an integer in the smallest currency unit (paise for INR). The minimum amount for INR is 100 (₹1).

```ts server.ts theme={null}
import { auth } from "./auth";

// Inside an API route or server action
const { data, error } = await auth.api.createRazorpayOrder({
  body: {
    amount: 50000,        // ₹500
    currency: "INR",
    receipt: "order_rcpt_001",
    notes: { productId: "prod_123", userId: "user_456" },
  },
  headers: req.headers,   // pass headers for session
});
```

The response is a Razorpay order object containing `id`, `amount`, `currency`, `receipt`, `status`, and other fields.

**2. Collect payment with Razorpay Checkout**

On the client, load Razorpay Checkout and pass the `order_id` returned from the server. After the user completes payment, the `handler` callback receives `razorpay_order_id`, `razorpay_payment_id`, and `razorpay_signature`.

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

import { useState } from "react";
import { authClient } from "./auth-client";

export function CheckoutButton() {
  const [loading, setLoading] = useState(false);

  async function handleCheckout() {
    setLoading(true);
    const { data: order, error } = await authClient.razorpay.createOrder({
      amount: 50000,
      currency: "INR",
      receipt: "order_rcpt_001",
      notes: { productId: "prod_123" },
    });
    if (error || !order) {
      alert(error?.message ?? "Failed to create order");
      setLoading(false);
      return;
    }

    const rzp = new (window as any).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: any) => {
        const verify = await authClient.razorpay.verifyPayment({
          razorpayOrderId: response.razorpay_order_id,
          razorpayPaymentId: response.razorpay_payment_id,
          razorpaySignature: response.razorpay_signature,
          expectedAmount: 50000,
        });
        if (verify.data?.valid) {
          alert("Payment verified!");
        } else {
          alert("Payment verification failed: " + verify.data?.reason);
        }
        setLoading(false);
      },
      modal: {
        ondismiss: () => setLoading(false),
      },
    });
    rzp.open();
  }

  return (
    <button onClick={handleCheckout} disabled={loading}>
      {loading ? "Loading..." : "Pay ₹500"}
    </button>
  );
}
```

**3. Verify the payment on the server**

The `verifyPayment` endpoint checks the payment signature, confirms the payment is captured, and optionally validates the amount. Call it from the client as shown above, or directly on the server.

```ts server-verify.ts theme={null}
import { auth } from "./auth";

const result = await auth.api.verifyRazorpayPayment({
  body: {
    razorpayOrderId: "order_XXXX",
    razorpayPaymentId: "pay_XXXX",
    razorpaySignature: "sig_XXXX",
    expectedAmount: 50000,
  },
  headers: req.headers,
});
```

The response contains:

**valid** `boolean`

True only when the signature is valid, the payment is captured, the order matches, and the expected amount matches (if provided).

**paymentStatus** `string`

The Razorpay payment status, for example "captured".

**reason** `string`

One of: `invalid_signature`, `order_mismatch`, `amount_mismatch`, or `payment_not_captured`. Only present when `valid` is false.

**4. Fulfill on the order.paid webhook**

Client-side verification helps the UI respond quickly, but you should treat the `order.paid` webhook as the source of truth for fulfillment. Configure the plugin's `onOrderPaid` callback to deliver purchases, update inventory, or send confirmation emails.

```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
      },
    }),
  ],
});
```

## Partial payments

You can allow customers to pay an order in multiple installments by enabling `partialPayment` and setting `firstPaymentMinAmount`.

```ts theme={null}
const { data } = await authClient.razorpay.createOrder({
  amount: 100000,
  currency: "INR",
  partialPayment: true,
  firstPaymentMinAmount: 25000,
});
```

> [!WARNING]
>
> `firstPaymentMinAmount` requires `partialPayment: true`. Without it, the server returns `INVALID_PARTIAL_PAYMENT`.

## Guest checkout (requireSession: false)

If you want to accept payments from users who are not signed in, set `requireSession: false` in the plugin options. This removes the session middleware from one-time payment and transfer endpoints.

```ts auth.ts theme={null}
razorpay({
  keyId: process.env.RAZORPAY_KEY_ID!,
  keySecret: process.env.RAZORPAY_KEY_SECRET!,
  requireSession: false,
})
```

> [!WARNING]
>
> Disabling session requirements means anyone can call `createOrder` and other payment endpoints. Protect your business logic by validating the request payload, rate-limiting, and verifying payments on the server before fulfillment.

## Listing orders and payments

Use the list and fetch endpoints to manage orders and payments from your dashboard or admin panel.

```ts theme={null}
// List orders
const orders = await authClient.razorpay.order.list({
  query: { count: 10, skip: 0 },
});

// Fetch payments for a specific order
const payments = await authClient.razorpay.order.payments({
  query: { orderId: "order_XXXX" },
});

// Fetch a single payment
const payment = await authClient.razorpay.payment.get({
  query: { id: "pay_XXXX" },
});
```

## Error handling

Common errors you may encounter:

| Error code | Meaning |
| - | - |
| `INVALID_ORDER_AMOUNT` | The amount is not a positive integer, or below the minimum for the currency. |
| `INVALID_PARTIAL_PAYMENT` | `firstPaymentMinAmount` was provided without `partialPayment: true`. |
| `INVALID_PAYMENT_SIGNATURE` | The signature does not match the expected HMAC. |
| `PAYMENT_FETCH_FAILED` | The server could not retrieve the payment from Razorpay. |
| `PAYMENT_NOT_CAPTURED` | The payment exists but has not been captured yet. |
| `PAYMENT_ORDER_MISMATCH` | The payment does not belong to the expected order. |
| `PAYMENT_AMOUNT_MISMATCH` | The payment amount does not match the expected amount. |


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