Create an Instant Refund (Idempotent Request)

• When you try to create an instant refund, in some cases due to network downtimes, you may not get a response from our servers. As a consequence, you will not be aware of the refund id or its state. In such cases, you can safely retry the transaction using the same idempotency key without risk of double-refund or duplication.
• To make an instant refund request idempotent, add the header X-Refund-Idempotency to the request and pass an idempotency key against it. The idempotency key must be at least 10 character long and can contain alphabets, numbers, hyphens and underscores only. For example, 550e8400-e29b-41d4-a716-446655440000.
• Idempotency is supported for both Normal and Instant Refunds APIs.

• When retrying a request, the request body must be the same as the first request for idempotency to work. A different payload will be rejected as a BAD_REQUEST.
• The idempotency key in retries must be the same as the original request.
• Use unique idempotency keys for each unique request.
• If a request is received while a prior request is still being processed, the system will return a 409 Conflict status code. You may retry the request upon receiving this response.

​

Request

curl -u [YOUR_KEY_ID]:[YOUR_KEY_SECRET] \
-X POST https://api.razorpay.com/v1/payments/pay_29QQoUBi66xm2f/refund \
-H 'Content-Type: application/json' \
-H 'X-Refund-Idempotency: 550e8400-e29b-41d4-a716-446655440000' \
-d '{
  "amount":500100,
  "speed":"optimum",
  "receipt":"Receipt No. 31",
  "notes":{
    "notes_key_1":"Tea, Earl Grey, Hot",
    "notes_key_2":"Tea, Earl Grey… decaf."
  }
}'

​

Response

{
  "id": "rfnd_FP8R8EGjGbPkVb",
  "entity": "refund",
  "amount": 500100,
  "currency": "INR",
  "payment_id": "pay_29QQoUBi66xm2f",
  "notes": {
    "notes_key_1": "Tea, Earl Grey, Hot",
    "notes_key_2": "Tea, Earl Grey… decaf."
  },
  "receipt": "Receipt No. 31",
  "acquirer_data": {
    "arn": null
  },
  "created_at": 1597078914,
  "batch_id": null,
  "status": "processed",
  "speed_processed": "normal",
  "speed_requested": "optimum"
}
```json: Failure
{
  "error": {
    "code": "BAD_REQUEST_ERROR",
    "description": "Different request with the same idempotency key has already been processed.",
    "source": "NA",
    "step": "NA",
    "reason": "NA",
    "metadata": {}
  }
}

​

Parameters

​

Parameters

• 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.
• In case of a full refund, enter the full payment amount. If amount parameter is not passed, the entire payment amount will be refunded.

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

​

Parameters

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

• normal: Indicates that the refund will be processed via the normal speed. 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.
  • 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.

• instant: Indicates that the refund has been processed instantly via fund transfer.
• normal: Indicates that the refund has been processed by the payment processing partner. The refund will take 5-7 working days.

​

Errors

• code: 409
• description: Another refund request with different parameters has been processed using the same idempotency key.
• solution: Use a unique idempotency key for the new request and retry.

• code: 409
• description: A refund request with the same idempotency key is currently being processed and has not yet returned a response.
• solution: Wait for the previous request to complete or use a different idempotency key.

• code: 500
• description: The server encountered an error while retrieving the idempotency record.
• solution: Retry the request after some time. If the issue persists, contact Razorpay Support.

• code: 500
• description: The server failed to parse the request body to generate the request hash.
• solution: Ensure the request body is properly formatted as valid JSON. If the issue persists, contact Razorpay Support.

• code: 400
• description: The idempotency key provided is less than 10 characters in length.
• solution: Use an idempotency key that is at least 10 characters long.

• code: 400
• description: The idempotency key contains invalid special characters.
• solution: Ensure the idempotency key only contains alphanumeric characters (A-Z, a-z, 0-9), underscores (_) and hyphens (-).

• code: 500
• description: The request contains an idempotency key but the merchant authentication is invalid or missing.
• solution: Ensure you are using valid API credentials (Key ID and Key Secret) for authentication. If the issue persists, Razorpay Support.