API ReferenceIntegrationsKnowledge Base

Refunds

You can make full or partial refunds to customers. While issuing refunds, you can choose to process the refunds refunds instantly or at normal speed (within 5-7 working days). Razorpay provides you real-time tracking of the processing speed and the status of the initiated refund.

Refunds possible only on Captured Payments:
You can initiate refunds only on those payments that are in captured state. A payment in authorized state is auto-refunded if not captured within 5 days of creation.

Postman Collection#

We have a Postman collection to make the integration quicker and easier. Click the Download Postman Collection button below to get started.

Instructions to use the Postman Collection#

  • All Razorpay APIs are authorized using Basic Authorization.
    • Generate API Keys from the Dashboard .
    • Add your API Keys in Postman. Selected the required API → Auth → Type = Basic Auth → Username = <Your_Key_ID>; Password = <Your_Key_secret>
  • Some APIs in the collection require data specific to your account such as pay_id (Payment ID) and rfnd_id (Refund ID) as a path parameter.
    • For example, the Fetch Refunds by ID API requires you to add the rfnd_id as a path parameter.
    • Such parameters are enclosed in {} in the collection. For example, {rfnd_id}.
    • The API throws an error if these are incorrect or do not exist in your system.

Refund Entity#

The refund entity returned by Razorpay is as shown below. It is returned in JSON form by the API (or in the object form if using language SDKs).

id
string Unique identifier of the refund.
entity
string Indicates the type of entity. Here, it is refund.
amount
integer The amount to be refunded (in the smallest unit of currency).
For example, refund in INR, a value of 100 means 100 paise (equivalent to ₹1).
currency
string The currency of payment amount for which refund is initiated. Here is the list of supported currencies.
payment_id
string Unique identifier of the payment for which the refund is initiated.
speed
string Speed with which the refund is to be processed. Possible values are:
  • normal: Indicates that the refund will be processed via the normal speed. That is, the refund will take 5-7 working days.
  • optimum: Indicates that the refund will be processed at an optimal speed based on Razorpay's internal fund transfer logic. That is:
    • If the refund can be processed instantly, Razorpay will do so, irrespective of the payment method used to make the payment.
    • If an instant refund is not possible, Razorpay will initiate a refund that is processed at the normal speed. For example, in case of payments made using debit cards, netbanking or unsupported credit cards.
created_at
integer Timestamp, in Unix format, when the refund was created.
batch_id
string This parameter is populated if the refund was created as part of a batch upload. For example, batch_00000000000001
notes
json object Key-value store for storing your reference data. A maximum of 15 key-value pairs can be included.
acquirer_data
array A dynamic array consisting of a unique reference number (either RRN, ARN or UTR) that is provided by the banking partner when a refund is processed. This reference number can be used by the customer to track the status of the refund with the bank.
status
string Indicates the state of the refund. Possible values include:
  • pending: This state indicates that Razorpay is attempting to process the refund.
  • processed: This is the terminal state of 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: Indicates that the refund will be processed via the normal speed. That is, the refund will take 5-7 working days.
  • optimum: Indicates that the refund will be processed at an optimal speed based on Razorpay's internal fund transfer logic. That is:
    • If the refund can be processed instantly, Razorpay will do so, irrespective of the payment method used to make the payment.
    • If an instant refund is not possible, Razorpay will initiate a refund that is processed at the normal speed.
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. That is, the refund will take 5-7 working days.

Create a Normal Refund#

The following endpoint creates a refund for a payment.

/payments/:id/refund

Path Parameter#

id mandatory
string The unique identifier of the payment which needs to be refunded.

Request Parameters#

amount optional
integer The amount to be refunded. Amount should be in the smallest unit of the currency in which the payment was made.
  • For a partial refund, enter a value lesser than the payment amount. For example, if the payment amount is ₹1500 and you want to refund only ₹500, you must pass 50000.
  • For full refund, enter the entire payment amount. If amount parameter is not passed, the entire payment amount will be refunded.
speed optional
string The speed at which the refund is to be processed. The default value is normal. Refund will be processed via the normal speed and the customer will receive the refund within 5-7 working days.
notes optional
json object Key-value pairs used to store additional information. A maximum of 15 key-value pairs can be included.
receipt optional
string A unique identifier provided by you for your internal reference.

Create an Instant Refund#

If you want to process refunds instantaneously to your customers, you can do so by passing the speed with value as optimum in the request body.

/payments/:id/refund

Refunds will be processed at an optimal speed based on Razorpay's internal fund transfer logic. That is, if the refund can be processed instantly, Razorpay will do so irrespective of the payment method used to make the payment. If an Instant Refund is not possible, Razorpay will initiate a refund that is processed at the normal speed.

For information about the transaction fees and different payment methods that support Instant Refunds, refer to the product documentation.

Path Parameter#

id mandatory
string The unique identifier of the payment which needs to be refunded.

Request Parameters#

amount optional
integer The amount to be refunded. Amount should be in the smallest unit of the currency in which the payment was made. Required in case of partial refund.
  • For a partial refund, enter a value lesser than the payment amount. For example, if the payment amount is ₹1200 and you want to refund only ₹200, you must pass 20000.
  • For full refund, enter the entire payment amount. If amount parameter is not passed, the entire payment amount will be refunded.
speed mandatory
string Here, it must be optimum.

Refund will be processed at an optimal speed based on Razorpay's internal fund transfer logic. If the refund can be processed instantly, Razorpay will do so, irrespective of the payment method used to make the payment. If an instant refund is not possible, Razorpay will initiate a normal refund.

Examples#

The possible 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

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

optimum

instant

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

Note:
Once the Refund moves to the processed state, the refund response displays the speed_processed parameter, the terminal state of the refund.

Fetch Multiple Refunds for a Payment#

The following endpoint retrieves multiple refunds for a payment. By default, only the last 10 refunds are returned. You can use count and skip parameters to change that behavior.

/payments/:id/refunds

Path Parameter#

id mandatory
string Unique identifier of the payment for which refund has been requested.

Query Parameters#

from optional
integer Unix timestamp at which the refunds were created.
to optional
integer Unix timestamp till which the refunds were created.
count optional
integer The number of refunds to fetch for the payment.
skip optional
integer The number of refunds to be skipped for the payment.

Fetch a Specific Refund for a Payment#

The following endpoint retrieves details of a specific refund made for a payment.

/payments/:payment_id/refunds/:refund_id

Path Parameters#

payment_id mandatory
string Unique identifier of the payment for which the refund has been made.
refund_id mandatory
string Unique identifier of the refund to be retrieved.

Fetch All Refunds#

The following endpoint retrieves details of all refunds. However, by default, only the last 10 refunds are returned. You can use count and skip query parameters to change that behavior.

/refunds/

Query Parameters#

from optional
integer Unix timestamp at which the refunds were created.
to optional
integer Unix timestamp till which the refunds were created.
count optional
integer The number of refunds to fetch. You can fetch a maximum of 100 refunds.
skip optional
integer The number of refunds to be skipped.

Fetch Refund by ID#

The following endpoint retrieves the refund using the ID.

/refunds/:id

Path Parameter#

id mandatory
string Unique identifier of the refund which is to be retrieved.

Update the Refund#

You can modify an existing refund to update the notes field only. Notes can be used to record additional information about the payment. You can add up to 15 key-value pairs with each value of the key not exceeding 256 characters.

Using the PATCH operation, you can replace the entire notes object for the entity.

The following endpoint updates the notes parameter for a refund.

/refunds/:id/

Path Parameter#

id mandatory
string Unique identifier of the refund for which the Notes field should be updated.

Request Parameter#

notes mandatory
json object Additional information to be modified or added as part of Notes field in key-pair format. Learn more about notes.
×