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

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.

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

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

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.

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.
Last modified on November 18, 2026