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 alreadycaptured. 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
speedtonormal(5-7 working days) oroptimum(processed instantly when possible, otherwise it falls back to normal). - States: a refund is
pendingwhile being processed, thenprocessedon success, orfailed.
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
capturedstate, so capture the payment first. - Configure a webhook URL subscribed to the refund events listed under Handle webhooks.
How to integrate
Create a refund
CallPOST /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.
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 movespending → 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.
Fetch refunds
Fetch refunds at any time. These APIs are available in both test mode and live.GET /v1/refundslists all refunds.GET /v1/refunds/:idreturns one refund by ID.GET /v1/payments/:id/refundslists the refunds for a payment.GET /v1/payments/:id/refunds/:refund_idreturns one refund of a payment.
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-Idempotencyheader so a retried request never creates a duplicate refund. - Act on
speed_processed, not justspeed_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
failedandrefund.speed_changedcases, not just the happy path. - Verify webhook signatures and make your handler idempotent.
- Reconcile refunds against your settlements and records.