API ReferenceIntegrationsKnowledge Base

Refunds

You can make full or partial refunds to customers. While issuing refunds, you can choose to process the 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 Can be Made 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 Postman CollectionπŸ”—

Generate API Keys

- 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 has the following fields:

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:
  • 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.
receipt
string A unique identifier provided by you for your internal reference.
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:
  • pending: This state indicates that Razorpay is attempting to process the refund.
  • processed: This is the final state of the refund.
  • failed: A refund can attain the failed state in the following scenarios:
    • Normal refund not possible for a payment which is more than 6 months old.
    • Instant Refund can sometimes fail because of customer's account or bank-related issues.
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:
  • 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:
  • 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 normal 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 platform 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.
receipt optional
string A unique identifier provided by you for your internal reference.

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 final 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 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. Know more about notes.
×