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

# Marketplace transfers

> Split payments across linked accounts using Razorpay Route, hold settlements, edit transfers, and reverse them when needed.

This guide shows you how to split incoming payments across multiple sellers or service providers using Razorpay Route. You will create transfers to linked accounts, place settlements on hold, edit transfers, reverse them, and list transfer history.

> [!NOTE]
>
> Razorpay Route must be enabled on your Razorpay account before you can use transfer endpoints. Contact Razorpay support to enable Route if it is not already active.

**1. Create a transfer**

After a payment is captured, call the transfer endpoint to split the amount across linked accounts. Each transfer entry needs an `account` (the linked account ID), an `amount`, and optional fields such as `notes`, `onHold`, and `onHoldUntil`.

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

const result = await auth.api.createRazorpayTransfer({
  body: {
    paymentId: "pay_XXXX",
    transfers: [
      {
        account: "acc_SellerA",
        amount: 30000,          // ₹300
        currency: "INR",
        notes: { seller: "A" },
      },
      {
        account: "acc_SellerB",
        amount: 20000,          // ₹200
        currency: "INR",
        onHold: true,
        onHoldUntil: Math.floor(Date.now() / 1000) + 86400, // hold 1 day
        linkedAccountNotes: ["Pending delivery"],
      },
    ],
  },
  headers: req.headers,
});
```

From the client:

```ts theme={null}
const { data, error } = await authClient.razorpay.transfer.create({
  paymentId: "pay_XXXX",
  transfers: [
    { account: "acc_SellerA", amount: 30000, currency: "INR" },
    { account: "acc_SellerB", amount: 20000, currency: "INR" },
  ],
});
```

**2. Fetch and list transfers**

Retrieve a single transfer by ID, or list transfers filtered by payment ID, date range, and pagination.

```ts theme={null}
// Fetch one transfer
const transfer = await authClient.razorpay.transfer.get({
  query: { id: "trf_XXXX" },
});

// List transfers for a payment
const transfers = await authClient.razorpay.transfer.list({
  query: { paymentId: "pay_XXXX", limit: 10 },
});
```

Server alternative:

```ts theme={null}
const transfer = await auth.api.getRazorpayTransfer({
  query: { id: "trf_XXXX" },
  headers: req.headers,
});

const list = await auth.api.listRazorpayTransfers({
  query: { paymentId: "pay_XXXX", limit: 10 },
  headers: req.headers,
});
```

**3. Edit a transfer**

You can change the `onHold` status and `onHoldUntil` timestamp on an existing transfer.

```ts theme={null}
const { data, error } = await authClient.razorpay.transfer.edit({
  transferId: "trf_XXXX",
  onHold: false,
});
```

Server:

```ts theme={null}
const result = await auth.api.editRazorpayTransfer({
  body: { transferId: "trf_XXXX", onHold: false },
  headers: req.headers,
});
```

**4. Reverse a transfer**

Reverse a transfer to pull funds back from a linked account. You can reverse the full amount or a partial amount.

```ts theme={null}
const { data, error } = await authClient.razorpay.transfer.reverse({
  transferId: "trf_XXXX",
  amount: 10000, // optional: partial reverse
});
```

Server:

```ts theme={null}
const result = await auth.api.reverseRazorpayTransfer({
  body: { transferId: "trf_XXXX", amount: 10000 },
  headers: req.headers,
});
```

## React hooks for transfers

The plugin provides TanStack Query mutation and query hooks for transfers.

### Create a transfer

```tsx create-transfer.tsx theme={null}
"use client";

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

export function CreateTransferButton({ paymentId }: { paymentId: string }) {
  const mutation = useCreateTransfer(authClient);

  return (
    <button
      onClick={() =>
        mutation.mutate({
          paymentId,
          transfers: [
            { account: "acc_SellerA", amount: 30000, currency: "INR" },
            { account: "acc_SellerB", amount: 20000, currency: "INR" },
          ],
        })
      }
      disabled={mutation.isPending}
    >
      {mutation.isPending ? "Creating..." : "Split payment"}
    </button>
  );
}
```

### List transfers

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

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

export function TransferList({ paymentId }: { paymentId: string }) {
  const { data, isLoading, error } = useRazorpayTransferList(authClient, {
    paymentId,
    limit: 10,
  });

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

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

## Error handling

| Error code | Meaning |
| - | - |
| `TRANSFER_CREATE_FAILED` | The transfer could not be created. |
| `TRANSFER_FETCH_FAILED` | The server could not fetch the transfer. |
| `TRANSFER_LIST_FAILED` | The transfer list request failed. |
| `TRANSFER_EDIT_FAILED` | The transfer could not be updated. |
| `TRANSFER_REVERSE_FAILED` | The transfer reversal failed. |


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