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

# Refunds

> Process full and partial refunds, list and edit refunds, and react to refund webhooks with React hooks.

This guide shows you how to refund payments using the better-auth-razorpay plugin. You can issue full or partial refunds, choose the refund speed, add notes, and handle refund webhooks to keep your system in sync.

**1. Issue a refund**

Call the refund endpoint with the payment ID. Omit `amount` for a full refund, or pass a smaller amount for a partial refund.

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

const result = await auth.api.refundRazorpayPayment({
  body: {
    paymentId: "pay_XXXX",
    amount: 25000,          // partial refund of ₹250 (omit for full)
    speed: "normal",        // or "optimum"
    receipt: "rcpt_refund_01",
    notes: { reason: "Customer request" },
  },
  headers: req.headers,
});
```

From the client:

```ts theme={null}
const { data, error } = await authClient.razorpay.payment.refund({
  paymentId: "pay_XXXX",
  amount: 25000,
  speed: "normal",
  receipt: "rcpt_refund_01",
  notes: { reason: "Customer request" },
});
```

**2. Fetch and list refunds**

Use the refund endpoints to retrieve a single refund or list refunds with pagination.

```ts theme={null}
// Fetch a single refund
const refund = await authClient.razorpay.refund.get({
  query: { refundId: "rfnd_XXXX", paymentId: "pay_XXXX" },
});

// List refunds
const refunds = await authClient.razorpay.refund.list({
  query: { count: 10, skip: 0 },
});
```

On the server:

```ts theme={null}
const refund = await auth.api.fetchRefund({
  query: { refundId: "rfnd_XXXX", paymentId: "pay_XXXX" },
  headers: req.headers,
});

const allRefunds = await auth.api.fetchAllRefunds({
  query: { count: 10, skip: 0 },
  headers: req.headers,
});
```

**3. Edit a refund**

You can update the notes on an existing refund.

```ts theme={null}
const { data, error } = await authClient.razorpay.refund.edit({
  refundId: "rfnd_XXXX",
  notes: { updatedReason: "Item out of stock" },
});
```

Server alternative:

```ts theme={null}
const result = await auth.api.editRefund({
  body: { refundId: "rfnd_XXXX", notes: { updatedReason: "Item out of stock" } },
  headers: req.headers,
});
```

**4. Handle refund webhooks**

Configure the plugin callbacks to react when Razorpay notifies you about refund state changes.

```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,
      onRefundCreated: async ({ event, refund }) => {
        console.log("Refund created:", refund.id);
      },
      onRefundProcessed: async ({ event, refund }) => {
        console.log("Refund processed:", refund.id);
        // Update order status, notify customer, etc.
      },
      onRefundFailed: async ({ event, refund }) => {
        console.log("Refund failed:", refund.id);
      },
    }),
  ],
});
```

## React hooks for refunds

If you use TanStack Query in your React app, the plugin provides query and mutation hooks for refunds.

### List refunds

```tsx refunds-list.tsx theme={null}
"use client";

import { useRazorpayRefundList } from "@amank-root/better-auth-razorpay/react";
import { authClient } from "./auth-client";

export function RefundList() {
  const { data, isLoading, error } = useRazorpayRefundList(authClient, {
    query: { count: 10 },
  });

  if (isLoading) return <p>Loading refunds...</p>;
  if (error) return <p>Error: {error.message}</p>;

  return (
    <ul>
      {data?.items.map((refund: any) => (
        <li key={refund.id}>
          {refund.id} — {refund.amount / 100} {refund.currency} ({refund.status})
        </li>
      ))}
    </ul>
  );
}
```

### Edit a refund

```tsx edit-refund.tsx theme={null}
"use client";

import { useEditRefund } from "@amank-root/better-auth-razorpay/react";
import { authClient } from "./auth-client";

export function EditRefundButton({ refundId }: { refundId: string }) {
  const mutation = useEditRefund(authClient);

  return (
    <button
      onClick={() =>
        mutation.mutate({
          refundId,
          notes: { reason: "Updated reason" },
        })
      }
      disabled={mutation.isPending}
    >
      {mutation.isPending ? "Saving..." : "Update notes"}
    </button>
  );
}
```

## Error handling

| Error code | Meaning |
| - | - |
| `REFUND_NOT_FOUND` | The requested refund does not exist. |
| `REFUND_FETCH_FAILED` | The server could not fetch the refund from Razorpay. |
| `REFUND_LIST_FAILED` | The refund list request failed. |
| `REFUND_EDIT_FAILED` | The refund could not be updated. |


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