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

# Signature utilities

> Server-side utilities for creating and verifying Razorpay payment and webhook signatures using HMAC-SHA256.

The plugin exports several utilities from the server entry for working with Razorpay signatures. These use `node:crypto` for HMAC-SHA256 and timing-safe comparison.

## Importing utilities

```ts theme={null}
import {
  createRazorpayPaymentSignature,
  verifyRazorpayPaymentSignature,
  verifyRazorpayPaymentStatus,
  createRazorpayWebhookSignature,
  verifyRazorpayWebhookSignature,
} from "@amank-root/better-auth-razorpay";
```

## createRazorpayPaymentSignature

Create the expected payment signature from an order ID and payment ID.

```ts theme={null}
function createRazorpayPaymentSignature(
  orderId: string,
  paymentId: string,
  keySecret: string
): string;
```

Returns a hex-encoded HMAC-SHA256 of `${orderId}|${paymentId}`.

```ts theme={null}
const signature = createRazorpayPaymentSignature(
  "order_9A33WU1c6",
  "pay_29QQoUBi66",
  process.env.RAZORPAY_KEY_SECRET!
);
console.log(signature); // e.g. "9b1b..."
```

## verifyRazorpayPaymentSignature

Verify a payment signature against the expected value.

```ts theme={null}
function verifyRazorpayPaymentSignature(
  orderId: string,
  paymentId: string,
  signature: string,
  keySecret: string
): boolean;
```

Returns `true` if the signature is valid, `false` otherwise.

```ts theme={null}
const isValid = verifyRazorpayPaymentSignature(
  "order_9A33WU1c6",
  "pay_29QQoUBi66",
  response.razorpay_signature,
  process.env.RAZORPAY_KEY_SECRET!
);
```

## verifyRazorpayPaymentStatus

Check whether a payment object satisfies business-level requirements without verifying the cryptographic signature.

```ts theme={null}
function verifyRazorpayPaymentStatus(
  payment: {
    status: string;
    amount: number;
    currency: string;
    order_id?: string;
  },
  expectedOrderId: string,
  expectedAmount?: number
): RazorpayPaymentVerificationStatus;
```

Returns an object describing whether the payment is valid and why it might not be.

```ts theme={null}
const result = verifyRazorpayPaymentStatus(
  {
    status: "captured",
    amount: 50000,
    currency: "INR",
    order_id: "order_9A33WU1c6",
  },
  "order_9A33WU1c6",
  50000
);

console.log(result);
// {
//   valid: true,
//   paymentStatus: "captured",
//   amount: 50000,
//   currency: "INR",
//   orderId: "order_9A33WU1c6"
// }
```

If the payment is not valid, `reason` is one of:

* `"order_mismatch"` — `order_id` does not match `expectedOrderId`
* `"amount_mismatch"` — `amount` does not match `expectedAmount`
* `"payment_not_captured"` — `status` is not `"captured"`

## createRazorpayWebhookSignature

Create a webhook signature from a raw request body and webhook secret. Useful for testing or for custom webhook routes.

```ts theme={null}
function createRazorpayWebhookSignature(
  rawBody: string,
  webhookSecret: string
): string;
```

Returns a hex-encoded HMAC-SHA256 of the raw body.

```ts theme={null}
const rawBody = JSON.stringify({ event: "order.paid", payload: { ... } });
const signature = createRazorpayWebhookSignature(
  rawBody,
  process.env.RAZORPAY_WEBHOOK_SECRET!
);
```

## verifyRazorpayWebhookSignature

Verify a webhook signature from the `x-razorpay-signature` header.

```ts theme={null}
function verifyRazorpayWebhookSignature(
  rawBody: string,
  signature: string,
  webhookSecret: string
): boolean;
```

Returns `true` if the signature is valid, `false` otherwise.

```ts theme={null}
const isValid = verifyRazorpayWebhookSignature(
  rawBody,
  req.headers["x-razorpay-signature"],
  process.env.RAZORPAY_WEBHOOK_SECRET!
);
```

## Custom verify endpoint

If you need a server-side verification endpoint outside the plugin's built-in flow, combine the utilities like this:

```ts verify.ts theme={null}
import {
  verifyRazorpayPaymentSignature,
  verifyRazorpayPaymentStatus,
} from "@amank-root/better-auth-razorpay";

export async function verifyPayment(
  orderId: string,
  paymentId: string,
  signature: string,
  expectedAmount: number
) {
  const sigValid = verifyRazorpayPaymentSignature(
    orderId,
    paymentId,
    signature,
    process.env.RAZORPAY_KEY_SECRET!
  );

  if (!sigValid) {
    return { valid: false, reason: "invalid_signature" };
  }

  // Fetch payment from Razorpay (using the Razorpay SDK or the plugin's get endpoint)
  const payment = await fetchPaymentFromRazorpay(paymentId);

  return verifyRazorpayPaymentStatus(payment, orderId, expectedAmount);
}
```

## Custom webhook route

If you want to handle webhooks on a custom route instead of the plugin endpoint, use the webhook utilities directly:

```ts webhook.ts theme={null}
import { verifyRazorpayWebhookSignature } from "@amank-root/better-auth-razorpay";

export async function handleWebhook(req: Request) {
  const rawBody = await req.text();
  const signature = req.headers.get("x-razorpay-signature");

  if (!signature) {
    return new Response("Missing signature", { status: 400 });
  }

  const isValid = verifyRazorpayWebhookSignature(
    rawBody,
    signature,
    process.env.RAZORPAY_WEBHOOK_SECRET!
  );

  if (!isValid) {
    return new Response("Invalid signature", { status: 400 });
  }

  const event = JSON.parse(rawBody);
  console.log("Webhook event:", event.event);

  return new Response("OK", { status: 200 });
}
```

## Test fixtures

Use `createRazorpayPaymentSignature` and `createRazorpayWebhookSignature` in tests to generate valid signatures without making real requests.

```ts signature.test.ts theme={null}
import {
  createRazorpayPaymentSignature,
  verifyRazorpayPaymentSignature,
  createRazorpayWebhookSignature,
  verifyRazorpayWebhookSignature,
} from "@amank-root/better-auth-razorpay";

describe("signature utilities", () => {
  const keySecret = "test_secret";
  const webhookSecret = "test_webhook_secret";

  it("round-trips a payment signature", () => {
    const orderId = "order_test";
    const paymentId = "pay_test";
    const signature = createRazorpayPaymentSignature(orderId, paymentId, keySecret);
    expect(verifyRazorpayPaymentSignature(orderId, paymentId, signature, keySecret)).toBe(true);
  });

  it("round-trips a webhook signature", () => {
    const body = JSON.stringify({ event: "order.paid" });
    const signature = createRazorpayWebhookSignature(body, webhookSecret);
    expect(verifyRazorpayWebhookSignature(body, signature, webhookSecret)).toBe(true);
  });
});
```


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