Skip to main content
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

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

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

Scenario IDScenarioTrigger credsSteps to follow
RFND-01Create a Normal refund (success)A captured payment, a success amount (e.g. amount: 10000, ₹100), at speed: “normal”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.
RFND-02Normal refund fails (coming soon)A captured payment above ₹24.68, amount: 2468 (₹24.68) at speed: “normal”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.

3.2 Other common refund scenarios

Scenario IDScenarioTrigger credsSteps to follow
RFND-03Create an Instant refund (success) (coming soon)A captured payment, a success amount (e.g. amount: 10000, ₹100), at speed: “optimum”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.
RFND-04Instant refund falls back to NormalA captured payment above ₹25.68, amount: 2568 (₹25.68) at speed: “optimum”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.
RFND-05Fetch refundsAt least one refund on a captured test paymentGET /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).
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.

3.3 Refund error scenarios

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

4. Scenario Details

RFND-01  Create a Normal refund (success)
Before you startA captured test payment and your test API keys.
How to testPOST /v1/payments/:id/refund with amount: 10000 (₹100) and speed: “normal”.
Expected resultHTTP 200 with a refund id (rfnd_…); it moves from pending to processed, with speed_processed: “normal”.
Webhooksrefund.created, then refund.processed.
Your integration shouldMark the refund successful on the processed state or the refund.processed webhook, and store the refund id.
RFND-02  Normal refund fails
Before you startA captured test payment greater than ₹24.68.
How to testPOST /v1/payments/:id/refund with amount: 2468 (₹24.68) and speed: “normal”.
Expected resultThe refund moves from pending to failed.
Webhooksrefund.created, then refund.failed.
Your integration shouldHandle the failed state / refund.failed webhook, and retry or reconcile.
RFND-03  Create an Instant refund (success)
Before you startA captured test payment, with Instant Refunds enabled on your test account.
How to testPOST /v1/payments/:id/refund with amount: 10000 (₹100) and speed: “optimum”.
Expected resultspeed_requested: “optimum”, speed_processed: “instant”; it moves from pending to processed. The per-refund fee is deducted from your test balance.
Webhooksrefund.created, then refund.processed.
Your integration shouldRead speed_processed = instant and account for the instant-refund fee.
RFND-04  Instant refund falls back to Normal
Before you startA captured test payment greater than ₹25.68.
How to testPOST /v1/payments/:id/refund with amount: 2568 (₹25.68) and speed: “optimum”.
Expected resultThe 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.
Webhooksrefund.created, refund.speed_changed, then refund.processed.
Your integration shouldDo not assume instant always succeeds; listen for refund.speed_changed, read speed_processed, and show the normal 5-7 working day timeline.
RFND-05  Fetch refunds
Before you startAt least one refund created on a captured test payment.
How to testGET /v1/refunds, GET /v1/refunds/:id, GET /v1/payments/:id/refunds and GET /v1/payments/:id/refunds/:refund_id.
Expected resultEach call returns refund-level data: id, status, speed_requested, speed_processed, amount and references (ARN / RRN).
WebhooksNone (synchronous fetch APIs).
Your integration shouldUse the fetch APIs to reconcile refund status, and prefer webhooks over polling for live updates.

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.

6. Common Integration Gaps to Avoid

Last modified on November 18, 2026