> ## Documentation Index
> Fetch the complete documentation index at: https://razorpay.com/docs/llms.txt
> Use this file to discover all available pages before exploring further.

# Refunds: How to Integrate

> Integrate the Refunds API on your server: create refunds, track states, fetch refunds and handle webhooks.

Available in
🇮🇳 India
🇲🇾 Malaysia

Refunds return money to your customers for a captured payment, using the Refunds API. You can issue full or partial refunds, at normal or instant speed, and track each refund through its states and webhooks. This guide covers the live integration. Once you have built it, validate it end to end with [Refunds: Test your integration](https://razorpay.com/docs/payments/payment-gateway/s2s-integration/test-s2s/refunds.md).

## How refunds work

A refund returns money to a customer for a payment that is already `captured`. Refunds are paid out from your Razorpay balance and credited back to the customer's original payment method.

* **Full or partial:** refund the entire payment or part of it. You can issue multiple partial refunds, as long as their total does not exceed the captured payment amount.
* **Normal or instant:** set `speed` to `normal` (5-7 working days) or `optimum` (processed instantly when possible, otherwise it falls back to normal).
* **States:** a refund is `pending` while being processed, then `processed` on success, or `failed`.

## Before you begin

* Generate your **live** API keys from the Dashboard. Keys that start with `rzp_live_` send requests to live mode.
* A refund always acts on an existing payment in the `captured` state, so capture the payment first.
* Configure a webhook URL subscribed to the refund events listed under [Handle webhooks](#handle-webhooks).

## How to integrate

### Create a refund

Call `POST /v1/payments/:id/refund` with the amount and speed. Omit `amount` for a full refund; pass it in the smallest currency unit (paise) for a partial refund.

| Parameter | Type | Description |
| - | - | - |
| `amount` | integer | Amount to refund, in paise. Omit for a full refund. |
| `speed` | string | `normal` or `optimum`. `normal` settles in 5-7 working days; `optimum` is processed instantly when possible, otherwise it falls back to normal. |
| `notes` | object | Up to 15 key-value pairs for your reference. |
| `receipt` | string | Your unique internal reference. |

```bash theme={null}
curl -u [KEY_ID]:[KEY_SECRET] \
  -X POST https://api.razorpay.com/v1/payments/pay_123/refund \
  -H 'Content-Type: application/json' \
  -d '{ "amount": 10000, "speed": "optimum" }'
```

A normal refund must fall within the payment's refund window (a 180-day default, configured per country and gateway). A refund on an older payment is rejected at create time with an error.

> [!NOTE]
>
> **Idempotency**
>
> Add the `X-Refund-Idempotency` header with a key of at least 10 characters so that retrying a request after a timeout or network error never creates a duplicate refund. Supported for both Normal and Instant refunds, and available today in select countries (Normal refunds: 🇮🇳 India and 🇲🇾 Malaysia, Instant refunds: 🇮🇳 India).

### Track the refund state

A refund moves `pending` → `processed`, or ends in `failed`.

| State | Meaning |
| - | - |
| `pending` | Razorpay is attempting to process the refund. |
| `processed` | Final success state. The money has left Razorpay. |
| `failed` | The refund could not be processed (for example, an instant refund blocked by bank or account issues). |

Read `speed_requested` (`optimum` or `normal`, what you asked for) and `speed_processed` (`instant` or `normal`, what actually happened). You can also fetch a refund at any time (see **Fetch refunds** below), but prefer webhooks over polling for status.

> [!WARNING]
>
> **Not seeing the `pending` state?**
>
> Whether a refund shows the `pending` state depends on your account. It is enabled by default for merchants onboarded on or after **28 April 2026**, and for some onboarded earlier. If it is not enabled for your account, refunds move straight to `processed` or `failed`, with no `pending` state in between. To enable it on your account, raise a [Support request](https://razorpay.com/support/#request).

### Fetch refunds

Fetch refunds at any time. These APIs are available in both test mode and live.

* `GET /v1/refunds` lists all refunds.
* `GET /v1/refunds/:id` returns one refund by ID.
* `GET /v1/payments/:id/refunds` lists the refunds for a payment.
* `GET /v1/payments/:id/refunds/:refund_id` returns one refund of a payment.

Each returns refund-level data: `status`, `speed_requested`, `speed_processed`, amount and references (ARN / RRN).

### Handle webhooks

Subscribe to these events and act on what each one entitles you to do.

| Event | What it means | What to do |
| - | - | - |
| `refund.created` | The refund is accepted, not settled. | Do not tell the customer the money is back yet. |
| `refund.processed` | The money has left Razorpay. | Confirm the refund to the customer. |
| `refund.failed` | The refund did not go through. | Retry or reconcile; it will not resolve itself. |
| `refund.speed_changed` | An instant refund fell back to normal speed. | Update the ETA you quoted the customer and read `speed_processed`. |

Verify the webhook signature on every event before acting on it.

## Best practices

* Prefer webhooks over polling to track refund status.
* Verify the webhook signature on every event, and make your handler idempotent.
* Use the `X-Refund-Idempotency` header so a retried request never creates a duplicate refund.
* Act on `speed_processed`, not just `speed_requested`, so you know how a refund actually went out.
* Reconcile refunds against your settlements and internal records.

## Common mistakes to avoid

| Mistake | What goes wrong | What to do |
| - | - | - |
| Not handling the `failed` state | A failed refund is treated as done; the customer never gets the money back. | Listen for `refund.failed` and reconcile or retry. |
| Assuming an instant refund is always instant | You tell the customer "refunded instantly" when it actually fell back to normal speed. | Listen for `refund.speed_changed` and read `speed_processed`, not just `speed_requested`. |
| Ignoring the instant-refund fee | Settlement and books do not match because the per-refund fee was not accounted for. | Account for the fee on instant refunds; expect it credited back on fallback. |
| Refunding more than captured, or an uncaptured payment | The API call fails with a validation error your code does not handle. | Validate the refund amount is within the captured amount and the payment `status` is `captured` before refunding. |

## Test your integration

Before going live, run the full flow in test mode: successful and failed Normal refunds, Instant refund success and fallback, and the error scenarios. See [Refunds: Test your integration](https://razorpay.com/docs/payments/payment-gateway/s2s-integration/test-s2s/refunds.md).

## Go-live checklist

* Switch to live keys (`rzp_live_`).
* Handle the `failed` and `refund.speed_changed` cases, not just the happy path.
* Verify webhook signatures and make your handler idempotent.
* Reconcile refunds against your settlements and records.

## Related information

* [Refunds overview](https://razorpay.com/docs/payments/refunds)
* [Refunds API reference](https://razorpay.com/docs/api/refunds.md)
* [Refund webhooks](https://razorpay.com/docs/webhooks/refunds.md)
* [Refunds: Test your integration](https://razorpay.com/docs/payments/payment-gateway/s2s-integration/test-s2s/refunds.md)
