> ## 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 Test Your Integration

> Test Normal and Instant refunds on your S2S integration in Test Mode, including failures and the Instant-to-Normal fallback.

Available in
🇮🇳 India

Refunds are always issued against an existing captured payment, so you create a test payment and then refund it. The refund amount decides the outcome: use the specific amounts below for a successful refund, and the specific trigger amounts for a failure. Whether a refund is Normal or Instant depends on the `speed` you send (`normal` or `optimum`), not the amount. Everything runs on your test keys and is fully simulated: no real money moves.

## 1. Test Mode Coverage

| Area | What you can test | Available on test mode |
| - | - | - |
| Create a Normal refund (success) | Issue a Normal refund against a captured test payment, full or partial. | Available |
| Create a Normal refund (failure) | Simulate a Normal refund that moves to failed. | Coming soon |
| Create an Instant refund (success) | Instant at optimum speed; the per-refund fee is deducted from your test balance. | Coming soon |
| Instant refund failure & fallback to Normal | An instant refund that cannot be processed instantly falls back to normal speed. | Available |
| Refund API errors | Request validation errors (invalid refund amount, speed, uncaptured payment, and more). | Available |
| Fetch refunds | Query refunds with the fetch APIs (all refunds, one refund, and refunds for a payment). | Available |
| Bank movement & references | Real money transfer, actual customer credit, and real ARN / RRN / UTR. | Live only |

## 2. Test Kit

You need a captured test payment to refund. Payment first, then refund: a refund always acts on an existing captured payment, so your end-to-end flow is to create and capture a test payment, then refund it.

* Create a test payment on an order and capture it, see [Orders](https://razorpay.com/docs/payments/payment-gateway/s2s-integration/test-s2s/orders.md) and the method pages, then capture with the Capture Payment API (`POST /v1/payments/:id/capture`).
* Keep the captured payment amount greater than the refund amount you are testing. A captured payment greater than ₹1,000 covers every success and failure amount below.
* Refund it with `POST /v1/payments/:id/refund` (see the scenarios below).

| Use it to test | Refund amount (₹) | Notes |
| - | - | - |
| A successful Normal refund | ₹10, ₹100, ₹1,000, ₹99.50 or ₹249.75 | `speed: "normal"` |
| A failed Normal refund | ₹24.68 | `speed: "normal"` |
| A successful Instant refund | ₹10, ₹100, ₹1,000, ₹99.50 or ₹249.75 | `speed: "optimum"` |
| Instant refund failed and fallback to Normal | ₹25.68 | `speed: "optimum"` |

## 3. Scenarios to Test Your Integration

Grouped into must-have refund flows, other common refund flows, and error scenarios. Click a Scenario ID for its details.

### 3.1 Must-have refund scenarios

<table>
  <colgroup>
    <col width="10%" />

    <col width="24%" />

    <col width="24%" />

    <col width="42%" />
  </colgroup>

  <thead><tr><th>Scenario ID</th><th>Scenario</th><th>Trigger creds</th><th>Steps to follow</th></tr></thead>

  <tbody>
    <tr><td>RFND-01</td><td>Create a Normal refund (success)</td><td>A captured payment, a success amount (e.g. `amount: 10000`, ₹100), at `speed: "normal"`</td><td>`POST /v1/payments/:id/refund` with test keys, `amount: 10000` (₹100) and `speed: "normal"`. Confirm it moves from `pending` to `processed`, with `speed_processed: "normal"`. Store the refund `id` against your payment or order.</td></tr>
    <tr><td>RFND-02</td><td>Normal refund fails (coming soon)</td><td>A captured payment above ₹24.68, `amount: 2468` (₹24.68) at `speed: "normal"`</td><td>`POST /v1/payments/:id/refund` with `amount: 2468` and `speed: "normal"`. Confirm it moves from `pending` to `failed`. Handle the `refund.failed` webhook and reconcile.</td></tr>
  </tbody>
</table>

### 3.2 Other common refund scenarios

<table>
  <colgroup>
    <col width="10%" />

    <col width="24%" />

    <col width="24%" />

    <col width="42%" />
  </colgroup>

  <thead><tr><th>Scenario ID</th><th>Scenario</th><th>Trigger creds</th><th>Steps to follow</th></tr></thead>

  <tbody>
    <tr><td>RFND-03</td><td>Create an Instant refund (success) (coming soon)</td><td>A captured payment, a success amount (e.g. `amount: 10000`, ₹100), at `speed: "optimum"`</td><td>`POST /v1/payments/:id/refund` with `amount: 10000` (₹100) and `speed: "optimum"`. Confirm `speed_requested: "optimum"`, `speed_processed: "instant"`, and it moves from `pending` to `processed`. The per-refund fee is deducted from your test balance.</td></tr>
    <tr><td>RFND-04</td><td>Instant refund falls back to Normal</td><td>A captured payment above ₹25.68, `amount: 2568` (₹25.68) at `speed: "optimum"`</td><td>`POST /v1/payments/:id/refund` with `amount: 2568` and `speed: "optimum"`. Confirm it moves from `pending` to `processed` with `speed_requested: "optimum"` and `speed_processed: "normal"`. The instant fee is credited back to your test balance.</td></tr>
    <tr><td>RFND-05</td><td>Fetch refunds</td><td>At least one refund on a captured test payment</td><td>`GET /v1/refunds` to list all refunds, or `GET /v1/refunds/:id` for one.\
    `GET /v1/payments/:id/refunds` to list refunds for a payment, or `GET /v1/payments/:id/refunds/:refund_id` for one.\
    Confirm each refund's `status`, `speed_requested`, `speed_processed` and references (ARN / RRN).</td></tr>
  </tbody>
</table>

> [!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).

### 3.3 Refund error scenarios

Trigger each with a bad request and read the error object to handle it.

| Trigger | `error.code` | `error.reason` | `error.description` |
| - | - | - | - |
| Refund a payment that belongs to a different account | BAD\_REQUEST\_ERROR | input\_validation\_failed | Payment does not belong to the merchant |
| Call the API with invalid credentials | BAD\_REQUEST\_ERROR | not returned | Authentication failed |
| Refund a payment that is not captured | BAD\_REQUEST\_ERROR | NA | The payment status should be captured for action to be taken |
| Refund an amount less than ₹1.00 | BAD\_REQUEST\_ERROR | input\_validation\_failed | The amount must be atleast INR 1.00 |
| Pass an unsupported `speed` value | BAD\_REQUEST\_ERROR | input\_validation\_failed | The selected speed is invalid. |
| Refund a payment that is already fully refunded | BAD\_REQUEST\_ERROR | NA | The payment has been fully refunded already |
| Refund more than the payment amount | BAD\_REQUEST\_ERROR | NA | The total refund amount is greater than the refund payment amount |
| Pass a non-integer `amount` | BAD\_REQUEST\_ERROR | input\_validation\_failed | The amount must be an integer. |
| Refund a payment older than the allowed refund window | BAD\_REQUEST\_ERROR | input\_validation\_failed | The payment is too old to be refunded. The age limit is a 180-day default and is configured per country and gateway; the request is rejected at create time, so no refund is created. |

## 4. Scenario Details

RFND-01  Create a Normal refund (success)

<table>
  <tbody>
    <tr><th>Before you start</th><td>A captured test payment and your test API keys.</td></tr>
    <tr><th>How to test</th><td>`POST /v1/payments/:id/refund` with `amount: 10000` (₹100) and `speed: "normal"`.</td></tr>
    <tr><th>Expected result</th><td>HTTP 200 with a refund `id` (`rfnd_…`); it moves from `pending` to `processed`, with `speed_processed: "normal"`.</td></tr>
    <tr><th>Webhooks</th><td>`refund.created`, then `refund.processed`.</td></tr>
    <tr><th>Your integration should</th><td>Mark the refund successful on the `processed` state or the `refund.processed` webhook, and store the refund `id`.</td></tr>
  </tbody>
</table>

RFND-02  Normal refund fails

<table>
  <tbody>
    <tr><th>Before you start</th><td>A captured test payment greater than ₹24.68.</td></tr>
    <tr><th>How to test</th><td>`POST /v1/payments/:id/refund` with `amount: 2468` (₹24.68) and `speed: "normal"`.</td></tr>
    <tr><th>Expected result</th><td>The refund moves from `pending` to `failed`.</td></tr>
    <tr><th>Webhooks</th><td>`refund.created`, then `refund.failed`.</td></tr>
    <tr><th>Your integration should</th><td>Handle the `failed` state / `refund.failed` webhook, and retry or reconcile.</td></tr>
  </tbody>
</table>

RFND-03  Create an Instant refund (success)

<table>
  <tbody>
    <tr><th>Before you start</th><td>A captured test payment, with Instant Refunds enabled on your test account.</td></tr>
    <tr><th>How to test</th><td>`POST /v1/payments/:id/refund` with `amount: 10000` (₹100) and `speed: "optimum"`.</td></tr>
    <tr><th>Expected result</th><td>`speed_requested: "optimum"`, `speed_processed: "instant"`; it moves from `pending` to `processed`. The per-refund fee is deducted from your test balance.</td></tr>
    <tr><th>Webhooks</th><td>`refund.created`, then `refund.processed`.</td></tr>
    <tr><th>Your integration should</th><td>Read `speed_processed` = `instant` and account for the instant-refund fee.</td></tr>
  </tbody>
</table>

RFND-04  Instant refund falls back to Normal

<table>
  <tbody>
    <tr><th>Before you start</th><td>A captured test payment greater than ₹25.68.</td></tr>
    <tr><th>How to test</th><td>`POST /v1/payments/:id/refund` with `amount: 2568` (₹25.68) and `speed: "optimum"`.</td></tr>
    <tr><th>Expected result</th><td>The instant refund cannot be processed instantly, so it falls back to normal speed. It moves from `pending` to `processed` with `speed_requested: "optimum"` and `speed_processed: "normal"`; the instant fee is credited back.</td></tr>
    <tr><th>Webhooks</th><td>`refund.created`, `refund.speed_changed`, then `refund.processed`.</td></tr>
    <tr><th>Your integration should</th><td>Do not assume instant always succeeds; listen for `refund.speed_changed`, read `speed_processed`, and show the normal 5-7 working day timeline.</td></tr>
  </tbody>
</table>

RFND-05  Fetch refunds

<table>
  <tbody>
    <tr><th>Before you start</th><td>At least one refund created on a captured test payment.</td></tr>
    <tr><th>How to test</th><td>`GET /v1/refunds`, `GET /v1/refunds/:id`, `GET /v1/payments/:id/refunds` and `GET /v1/payments/:id/refunds/:refund_id`.</td></tr>
    <tr><th>Expected result</th><td>Each call returns refund-level data: `id`, `status`, `speed_requested`, `speed_processed`, amount and references (ARN / RRN).</td></tr>
    <tr><th>Webhooks</th><td>None (synchronous fetch APIs).</td></tr>
    <tr><th>Your integration should</th><td>Use the fetch APIs to reconcile refund status, and prefer webhooks over polling for live updates.</td></tr>
  </tbody>
</table>

## 5. Webhooks: What Fires, and What It Lets You Decide

Every scenario above delivers a specific set of events, in a specific order. This table is the one place that says which events fire and, more importantly, what each one entitles you to do. Most integration bugs that reach production are not missing webhooks; they are acting on the wrong one.

| Scenario | What it is | Events, in order | What it lets you decide |
| - | - | - | - |
| RFND-01 | Create a Normal refund (success) | `refund.created`, `refund.processed` | <ul><li>`refund.created`: the refund is accepted, not settled. Do not tell the customer the money is back yet.</li><li>`refund.processed`: the money has left Razorpay. This is when you confirm the refund to the customer.</li></ul> |
| RFND-02 | Normal refund fails | `refund.created`, `refund.failed` | <ul><li>`refund.created`: the refund is accepted, not settled. Do not tell the customer the money is back yet.</li><li>`refund.failed`: the refund did not go through. It needs a retry or a manual payout. It will not resolve itself.</li></ul> |
| RFND-03 | Create an Instant refund (success) | `refund.created`, `refund.processed` | <ul><li>`refund.created`: the refund is accepted, not settled. Do not tell the customer the money is back yet.</li><li>`refund.processed`: the money has left Razorpay. This is when you confirm the refund to the customer.</li></ul> |
| RFND-04 | Instant refund falls back to Normal | `refund.created`, `refund.speed_changed`, `refund.processed` | <ul><li>`refund.created`: the refund is accepted, not settled. Do not tell the customer the money is back yet.</li><li>`refund.speed_changed`: the refund fell back from Instant to Normal. The customer-facing ETA you quoted is now wrong.</li><li>`refund.processed`: the money has left Razorpay. This is when you confirm the refund to the customer.</li></ul> |

## 6. Common Integration Gaps to Avoid

| Gap | What goes wrong in production | What to do | Test with |
| - | - | - | - |
| Not handling the failed refund state | A refund that fails is treated as done; the customer never gets the money back. | Listen for the `failed` state / `refund.failed` webhook and reconcile. | RFND-02 (₹24.68) |
| Assuming an instant refund is always instant | You tell the customer "refunded instantly" when it actually fell back to normal speed. | Listen for the `refund.speed_changed` webhook and read `speed_processed`, not just `speed_requested`. | RFND-04 (₹25.68) |
| Ignoring the instant-refund fee | Settlement and books don't match because the per-refund fee was not accounted for. | Account for the fee on instant refunds; expect it credited back on fallback. | RFND-03 / RFND-04 |
| Refunding more than captured, or an uncaptured payment | Live refund calls fail with validation errors your code doesn't handle. | Validate the refund amount ≤ captured amount and payment `status` = `captured` before refunding. | Refund error scenarios (3.3) |

### Related Information

* [Test Your S2S Integration](https://razorpay.com/docs/payments/payment-gateway/s2s-integration/test-s2s.md)
* [Orders](https://razorpay.com/docs/payments/payment-gateway/s2s-integration/test-s2s/orders.md)
* [Best Practices](https://razorpay.com/docs/payments/payment-gateway/s2s-integration/test-s2s/best-practices)
