API ReferenceIntegrationsKnowledge Base

Razorpay Instant Refunds

To understand the Instant Refunds feature and how to enable it on your account, refer the Instant Refunds Overview.

Using the Instant Refunds API, you can perform real-time tracking of the processing speed and the status of the initiated refund.

Refund Entity#

A refund can be processed instantly by passing the parameter speed in the API request. This attribute will be reflected as speed_requested and speed_processed in the response body.

id
string Unique identifier of the refund.
entity
string Indicates type of entity.
amount
integer The amount to be refunded (in smallest unit of currency).
For example, an amount of 100 means 100 paise (equivalent to ₹1).
currency
string The currency of refund. Currently only INR is supported.
payment_id
string Payment ID for which this refund is initiated.
created_at
integer Timestamp, in UNIX format, when the refund was created.
notes
json object Key-value store for storing your reference data.
A maximum of 15 key-value pairs can be included. For more information, refer Notes.
status
string Indicates the state of the refund. Possible values include:
  • pending: This state is applicable when Razorpay is attempting to process the refund via the optimum speed.
  • processed: This state is the terminal state of the refund. All the refunds are eventually expected to be Processed.
  • failed: Indicates that the refund processing was not successful.
    You will need to retry the refund.
speed_requested
string The processing mode of the refund seen in the refund response.
This attribute is seen in the refund response only if the speed parameter is set in the refund request.
Possible values are:
  • normal: This value indicates the refunds will be processed via the normal speed, where the refund will take 5-7 working days.
  • optimum:This value indicates that the refunds will be processed at a speed based on Razorpay's internal fund transfer logic. Razorpay attempts a refund when this parameter is passed in the refund request in the following ways:
    • If the refund can be processed instantly, Razorpay will process the refund in the same manner, irrespective of the payment method used to make the payment.
    • If a faster speed for that refund is not available, for example, in case of payments made using any of the other payment methods such as debit cards, netbanking or unsupported credit cards, Razorpay will initiate a normal refund for the same.
speed_processed
string This is a parameter in the response which describes the mode used to process a refund.
This attribute is seen in the refund response only if the speed parameter is set in the refund request. Possible values include:
  • instant: This means that the refund has been processed instantly via fund transfer.
  • normal: This means that the refund has been processed by the payment processing partner.

Create a Refund#

The following endpoint refunds a payment using the payment ID.

/payments/:id/refund

Path Parameters#

id mandatory
string ID of the payment for which a refund is requested.

Request Parameters#

Include the parameter, speed to indicate the mode of the refund.

Note:
Instant Refund from Razorpay's end on supported cards can fail due to various technical reasons in the upstream Fund Transfer layer. In cases of refunds failures, Razorpay will initiate a refund via the normal speed and the refund will be credited to the customer within 5-7 working days.

Response Parameters#

The following parameters can be seen in the response body:

  • status
  • speed_processed
  • speed_requested

Note:
Once the Refund moves to the processed state, the refund response displays the speed_processed state, which is the final state in processing the refund.

The different combinations of speed in request and response are listed below:

speed attribute in Request

speed_processed attribute in Response

Description

normal

normal

Refund processed via normal speed

optimum

normal

Refund processed. A faster speed was not available, so processed via normal speed

optimum

instant

Refund processed. A faster speed was available and the refund was processed immediately.

Verifying the Refund Status#

You can verify the status of the refund either by polling the Razorpay server using APIs or configuring Webhooks to be notified of the events asynchronously.

Fetching the Refund Status#

You can poll the Razorpay API servers to retrieve the status of a refund:

/refunds/:id

Path Parameters#

id mandatory
string ID is the unique identifier of the refund.

Configuring Webhooks#

You can be notified of the events related to instant refunds by subscribing to the Webhooks available on the Dashboard.

  1. Login to the Dashboard and navigate to Settings > Webhooks > Edit your Live Webhook
  2. Enter the URL or the server address at which you want to receive these generated events.
  3. Subscribe to the Webhook events of your choice.
    The payload that is generated when an event is triggered on the Razorpay server is submitted as a POST request to the URL configured on your server.
refund.speed_changed
This event is triggered when the processing speed changes from instant to normal and the requested speed was set to optimum
refund.processed
This event is triggered when the refund is successfully processed.