---
page_source: https://juspay.io/in/docs/ec-headless/cordova/base-sdk-integration/refund-order-api
page_title: Refund Order API
---

## API Version: default


# Refund Order API



Create a refund for an Order. Refunds can be initiated only for transactions that are CHARGED. The response of refund initiation is similar to that of order status API Response with the addition of refund block.## Endpoints:
- Sandbox: https://sandbox.juspay.in/orders/{order_id}/refunds

- Production: https://api.juspay.in/orders/{order_id}/refunds

## Request Type: 
POST

## Content-Type: 
application/json

## Authorization:

#### Basic Auth:
Consists of two parts.

* Username: API Key obtained from Juspay dashboard
* Password: Empty string
- Value:  <p>Example:- <br> Basic MUQ2QUxxxxxxxxxxxxU5QTIxQzNFNTQwNkFDMEZCOg==</p>
- Tags: Base64 Encoded Username:Password, Mandatory
## Headers:

#### x-merchantid:
Merchant ID provided by Juspay

Example:-merchant-id
- Tags: String, Required

#### x-routing-id:
We recommend passing the customer_id as the x-routing-id. If the customer is checking out as a guest, you can pass an alternative ID that helps track the payment session lifecycle. For example, this could be an Order ID or Cart ID.

> **Warning**
> This ID is associated with the customer. It plays a key role in ensuring consistency and maintaining connections across different systems. If you fail to pass the same x-routing-id for the same customer in all related API calls, it could lead to issues with API functionality. Therefore, it’s crucial that you use the same x-routing-id for all requests tied to the same customer.


- Value: customer_1122
- Tags: String, Required

#### Content-Type:
application/x-www-form-urlencoded
- Tags: String
## Sample Code Snippets:
### Sample Request:

#### Request Code Snippet:

```request
curl -X POST https://api.juspay.in/orders/1418394476/refunds \
-u your_api_key: \
-H "version:2023-06-30" \
-H 'x-routing-id: customer_1122'\
-H 'Content-Type: application/x-www-form-urlencoded'\
-H 'x-merchantid: merchant_id'\
-d "unique_request_id=xyz123" \
-d "amount=100.00"

```

### Sample Response:

#### Response:
```json
{
  "udf9": "",
  "udf8": "",
  "udf7": "",
  "udf6": "",
  "udf5": "",
  "udf4": "",
  "udf3": "",
  "udf2": "",
  "udf10": "",
  "udf1": "",
  "txn_uuid": "eulwh5QbZSBvwpt7333f3",
  "txn_id": "merchant_success-JP1636474794-1",
  "txn_detail": {
    "txn_uuid": "eulwh5QbZSBvwpt7333f3",
    "txn_id": "merchant_success-JP1636474794-1",
    "txn_amount": 1,
    "tax_amount": null,
    "surcharge_amount": null,
    "status": "CHARGED",
    "redirect": true,
    "order_id": "JP1636474794",
    "net_amount": 1,
    "gateway_id": 23,
    "gateway": "RAZORPAY",
    "express_checkout": true,
    "error_message": "",
    "error_code": "",
    "currency": "INR",
    "created": "2021-11-09T16:20:52Z"
  },
  "status_id": 21,
  "status": "CHARGED",
  "rewards_breakup": null,
  "return_url": "",
  "refunds": [
    {
      "unique_request_id": "TEST1637681731",
      "status": "PENDING",
      "sent_to_gateway": false,
      "refund_type": "STANDARD",
      "refund_source": "RAZORPAY",
      "ref": null,
      "initiated_by": "API",
      "id": null,
      "error_message": "",
      "error_code": null,
      "created": "2021-11-23T15:35:32Z",
      "amount": 1
    }
  ],
  "refunded": true,
  "product_id": "",
  "payment_method_type": "CARD",
  "payment_method": "VISA",
  "payment_links": {
    "web": "https://api.juspay.in/merchant/pay/ordeh_57dfd768bb7d4896bc0c3f30bc9ad77",
    "mobile": "https://api.juspay.in/merchant/pay/ordeh_57dfd768bb7d4896bc0c3f30bc9ad77?mobile=true",
    "iframe": "https://api.juspay.in/merchant/ipay/ordeh_57dfd768bb7d4896bc0c3f30bc9ad77"
  },
  "payment_gateway_response": {
    "txn_id": "merchant_success-JP1636474794-1",
    "rrn": "156555",
    "resp_message": "SUCCESS",
    "resp_code": "SUCCESS",
    "epg_txn_id": "pay_IJZKtTpkiYWE24",
    "created": "2021-11-09T16:21:11Z",
    "auth_id_code": "156555"
  },
  "order_id": "JP1636474794",
  "offers": [],
  "metadata": {
    "RAZORPAY:gateway_reference_id": "testmid"
  },
  "merchant_id": "merchant_success",
  "id": "ordeh_57dfd768bb7d4896bc0c3f30bc9ad77",
  "gateway_reference_id": "testmid",
  "gateway_id": 23,
  "effective_amount": 1,
  "date_created": "2021-11-09T16:19:55Z",
  "customer_phone": "9999999999",
  "customer_id": "testcardenc1",
  "customer_email": "test@gmail.com",
  "currency": "INR",
  "card": {
    "using_token": false,
    "using_saved_card": true,
    "saved_to_locker": false,
    "name_on_card": "test",
    "last_four_digits": "",
    "expiry_year": "2024",
    "expiry_month": "12",
    "card_type": "CREDIT",
    "card_reference": "17a2ec4f27c918ttvbc58c9ae74090e",
    "card_issuer": "JP Morgan",
    "card_isin": "411111",
    "card_fingerprint": "32qqi3svf5t5t37fq7ura2rgqqb",
    "card_brand": "VISA"
  },
  "bank_pg": null,
  "bank_error_message": "",
  "bank_error_code": "",
  "auth_type": "THREE_DS",
  "amount_refunded": 1,
  "amount": 1
}
```

#### Failed Response:
```plaintext
{
    "error_message": "A refund has already been processed for this order with this unique request id.",
    "status": "ERROR",
    "error_code": "duplicate.call",
    "error_info": {
        "user_message": "Invalid request params. Please verify your input.",
        "request_id": "28c1acf6-c2a6-4741-b914-2af14c73ddf1",
        "href": "NA",
        "developer_message": "A refund has already been processed for this order with this unique request id.",
        "code": "INVALID_INPUT",
        "category": "USER_ERROR"
    },
    "status_id": -1
}
```

## Path Parameters:

#### order_id:
Order Id of the order for which you want to proceed with refund
- Value: Example:- 1418394476
- Tags: String, Mandatory, Max Length : 21
## Body Parameters:
### Parameters:

#### unique_request_id:
- Description: Request ID that uniquely identifies this request. You cannot reuse the value for two different refund requests. This is to avoid processing duplicate refund requests.The length of the `unique_request_id` should be less than 21 characters and alphanumeric. Special characters are not recommended as some of the underlying gateway/aggregator might have restrictions. 
- Tags: string, Required, Max Length : 255

#### amount:
- Description: Amount that has to be refunded. Amount has to be less than or equal to the **effective_amount**  of the order that is not yet refunded.If this parameter is not passed, then the order is refunded entirely. 

> **Note**
> The minimum amount that can be refunded is 1 INR. 


- Tags: Double, Required
## API Responses:
### 200:

#### udf1-10:
- Tags: string, Max Length : 255

#### txn_uuid:
- Description: eulwh5QbZSBvwpt7333f3
- Tags: string, Max Length : 128

#### txn_id:
- Description: merchant_success-JP1636474794-1
- Tags: string, Max Length : 255

#### txn_detail:
- Value:
  - **Txn_uuid**:
    - Description: eulwh5QbZSBvwpt7333f3
    - Tags: string, Max Length : 128
  - **Txn_id**:
    - Description: merchant_success-JP1636474794-1
    - Tags: string, Max Length : 255
  - **Txn_amount**:
    - Tags: integer
  - **Tax_amount**:
  - **Surcharge_amount**:
  - **Status**:
    - Description: CHARGED
    - Tags: string, Max Length : 255
  - **Redirect**:
    - Tags: boolean
  - **Order_id**:
    - Description: JP1636474794
    - Tags: string, Max Length : 21
  - **Net_amount**:
    - Tags: integer
  - **Gateway_id**:
    - Tags: integer
  - **Gateway**:
    - Description: RAZORPAY
    - Tags: string, Max Length : 128
  - **Express_checkout**:
    - Tags: boolean
  - **Error_message**:
    - Tags: string, Max Length : 255
  - **Error_code**:
    - Tags: string, Max Length : 255
  - **Currency**:
    - Description: INR
    - Tags: string, Max Length : 10
  - **Created**:
    - Description: 2021-11-09T16:20:52Z
    - Tags: string
- Tags: object

#### status_id:
- Tags: integer

#### status:
- Description: CHARGED
- Tags: string, Max Length : 255

#### refunds:
- Value:
  - **Object**:
    - Value:
      - **Unique_request_id**:
        - Description: The unique request id that is passed during refund initiation. Do not pass any special characters.
        - Tags: String, Max Length : 255
      - **Status**:
        - Description: The status of the refund initiated. Initial status will always be PENDING
        - Tags: String, Max Length : 255
      - **Sent_to_gateway**:
        - Description: The flag denotes if the refund was initiated to gateway. The initial status is always false, as refunds are queued at juspay for a max of 15minutes.
        - Tags: String
      - **Refund_type**:
        - Description: The type of refund. Values can be STANDARD, INSTANT
        - Tags: String, Max Length : 255
      - **Refund_source**:
        - Description: The name of gateway
        - Tags: String, Max Length : 255
      - **Ref**:
        - Description: The refund id provided by the PG
        - Tags: String, Max Length : 64
      - **Initiated_by**:
        - Description: The source of initiation.
        - Tags: String, Max Length : 100
      - **Id**:
        - Description: The reference id provided by PG, if not available then its mapped to unique request id.
        - Tags: String
      - **Error_message**:
        - Description: The error message provided by the PG
        - Tags: String, Max Length : 255
      - **Error_code**:
        - Description: The error code provided by the PG
        - Tags: String, Max Length : 255
      - **Created**:
        - Description: The timestamp of refund creation
        - Tags: String
      - **Amount**:
        - Description: The refund amount passed in the request
        - Tags: integer
    - Tags: object
- Tags: Array Of Objects

#### return_url:
- Tags: string, Max Length : 255

#### rewards_breakup:
- Tags: String

#### refunded:
- Tags: boolean

#### product_id:
- Tags: string, Max Length : 64

#### payment_method_type:
- Description: CARD
- Tags: string, Max Length : 20

#### payment_method:
- Description: VISA
- Tags: string, Max Length : 20

#### payment_links:
- Value:
  - **Web**:
    - Description: https://api.juspay.in/merchant/pay/ordeh_57dfd768bb7d4896bc0c3f30bc9ad77
    - Tags: string
  - **Mobile**:
    - Description: https://api.juspay.in/merchant/pay/ordeh_57dfd768bb7d4896bc0c3f30bc9ad77?mobile=true
    - Tags: string
  - **Iframe**:
    - Description: https://api.juspay.in/merchant/ipay/ordeh_57dfd768bb7d4896bc0c3f30bc9ad77
    - Tags: string
- Tags: object

#### payment_gateway_response:
- Value:
  - **Txn_id**:
    - Description: merchant_success-JP1636474794-1
    - Tags: string, Max Length : 255
  - **Rrn**:
    - Description: 156555
    - Tags: string, Max Length : 64
  - **Resp_message**:
    - Description: SUCCESS
    - Tags: string, Max Length : 512
  - **Resp_code**:
    - Description: SUCCESS
    - Tags: string, Max Length : 64
  - **Epg_txn_id**:
    - Description: pay_IJZKtTpkiYWE24
    - Tags: string, Max Length : 64
  - **Created**:
    - Description: 2021-11-09T16:21:11Z
    - Tags: string
  - **Auth_id_code**:
    - Description: 156555
    - Tags: string
- Tags: object

#### order_id:
- Description: JP1636474794
- Tags: string, Max Length : 21

#### offers:
- Tags: array

#### metadata:
- Value:
  - **RAZORPAY:gateway_reference_id**:
    - Description: testmid
    - Tags: string
- Tags: object

#### merchant_id:
- Description: merchant_success
- Tags: string, Max Length : 255

#### id:
- Description: ordeh_57dfd768bb7d4896bc0c3f30bc9ad77
- Tags: string

#### gateway_reference_id:
- Description: testmid
- Tags: string, Max Length : 255

#### gateway_id:
- Tags: integer

#### effective_amount:
- Tags: integer

#### date_created:
- Description: 2021-11-09T16:19:55Z
- Tags: string

#### customer_phone:
- Description: 9999999999
- Tags: string, Max Length : 300

#### customer_id:
- Description: testcardenc1
- Tags: string, Max Length : 300

#### customer_email:
- Description: test@gmail.com
- Tags: string, Max Length : 300

#### currency:
- Description: INR
- Tags: string, Max Length : 255

#### card:
- Value:
  - **Using_token**:
    - Tags: boolean
  - **Using_saved_card**:
    - Tags: boolean
  - **Saved_to_locker**:
    - Tags: boolean
  - **Name_on_card**:
    - Description: test
    - Tags: string, Max Length : 256
  - **Last_four_digits**:
    - Tags: string
  - **Expiry_year**:
    - Description: 2024
    - Tags: string
  - **Expiry_month**:
    - Description: 12
    - Tags: string
  - **Card_type**:
    - Description: CREDIT
    - Tags: string, Max Length : 64
  - **Card_reference**:
    - Description: 17a2ec4f27c918ttvbc58c9ae74090e
    - Tags: string, Max Length : 256
  - **Card_issuer**:
    - Description: JP Morgan
    - Tags: string, Max Length : 256
  - **Card_isin**:
    - Description: 411111
    - Tags: string, Max Length : 256
  - **Card_fingerprint**:
    - Description: 32qqi3svf5t5t37fq7ura2rgqqb
    - Tags: string, Max Length : 256
  - **Card_brand**:
    - Description: VISA
    - Tags: string
- Tags: object

#### bank_pg:

#### bank_error_message:
- Tags: string, Max Length : 255

#### bank_error_code:
- Tags: string, Max Length : 255

#### auth_type:
- Description: THREE_DS
- Tags: string, Max Length : 30

#### amount_refunded:
- Tags: integer

#### amount:
- Tags: integer

#### maximum_eligible_refund_amount:
- Description: > **Note**
> Amount that can be refunded without making the offer ineligible (for offer transactions). Calculated as the difference between the order amount and the Offer minimum order amount. For maximum allowed refund amount for a transaction , refer to the effective_amount field


- Tags: Integer
### 400:

#### Duplicate refund requests:
- Value:
  - **Error_code**:
    - Description: REFUND_DUPLICATE_REQUEST
    - Value:
      - **Error_message (1)**:
        - Description: A refund request is already being processed for this transaction id and amount combination
        - Tags: String
      - **Error_message (2)**:
        - Description: A refund request is already being processed for this unique request id and order id combination
        - Tags: String
      - **Error_message (3)**:
        - Description: A refund has already been processed for this order with this unique request id
        - Tags: String
- Tags: JSON

#### COD order:
- Value:
  - **Error_code**:
    - Description: CASH_PAYMENTS_REFUNDS_NOT_SUPPORTED
    - Value:
      - **Error_message**:
        - Description: Refunds cannot be initiated for COD orders
        - Tags: String
- Tags: String

#### Invalid amount passed:
- Value:
  - **Error_code**:
    - Description: INVALID_AMOUNT
    - Value:
      - **Error_message**:
        - Description: Amount is invalid
        - Tags: String
    - Tags: String
- Tags: String

#### Invalid Order Id:
- Value:
  - **Error_code**:
    - Description: INVALID_ORDERID
    - Value:
      - **Error_message**:
        - Description: Not found
        - Tags: String
    - Tags: String
- Tags: String

#### Older order:
- Value:
  - **Error_code**:
    - Description: ORDER_TOO_OLD
    - Value:
      - **Error_message**:
        - Description: Refunds cannot be initiated for orders older than 365 days
        - Tags: String
    - Tags: String
- Tags: String

#### Pending/authorised order:
- Value:
  - **Error_code**:
    - Description: CANNOT_PROCESS_AUTHORIZED_ORDER
    - Value:
      - **Error_message**:
        - Description: Refunds cannot be processsed for a pending/authorised order
        - Tags: String
    - Tags: String
- Tags: String

#### Order id based refund not allowed:
- Value:
  - **Error_code**:
    - Description: SPLIT_PAYMENTS_ORDER_BASED_REFUND_NOT_SUPPORTED
    - Value:
      - **Error_message**:
        - Description: Please use the txn_id-based Refund API
        - Tags: String
    - Tags: String
- Tags: String

#### Refund amount exceeds the total refundable amount:
- Value:
  - **Error_code**:
    - Description: INVALID_AMOUNT_REFUND
    - Value:
      - **Error_message**:
        - Description: Refund amount exceeds the total refundable amount
        - Tags: String, Mandatory
    - Tags: String, Mandatory
- Tags: String

#### Refund creation limit exceeded:
- Value:
  - **Error_code**:
    - Description: REFUND_CREATE_EXCEEDED_THE_LIMIT
    - Value:
      - **Error_message**:
        - Description: Refund creation limit exceeded
        - Tags: String
    - Tags: String
- Tags: String

#### Refunds not supported by the gateway:
- Value:
  - **Error_code**:
    - Description: REFUND_REJECTED
    - Value:
      - **Error_message**:
        - Description: Refunds are not supported for the gateway with which the forward order/transaction was processed
        - Tags: String
    - Tags: String
- Tags: String

#### Unsuccessful Order:
- Value:
  - **Error_code**:
    - Description: UNSUCCESSFUL_ORDER_PROCESS_FAILURE
    - Value:
      - **Error_message**:
        - Description: This refund cannot be processed as the forward order/transaction is not successful
        - Tags: String
    - Tags: String
- Tags: String

#### Refund amount less than minimum amount:
- Value:
  - **Error_code **:
    - Description: INVALID_AMOUNT
    - Value:
      - **Error_message**:
        - Description: Refund cannot be initiated with amount lesser than Rs.1
        - Tags: String
    - Tags: String
- Tags: String

#### Value not found:
- Value:
  - **Error_code**:
    - Description: VALUE_NOT_FOUND
    - Value:
      - **Error_message**:
        - Description: Success response ID
        - Tags: String
    - Tags: String
- Tags: String

#### Transaction not found:
- Value:
  - **Error_code **:
    - Description: SUCCESS_OR_PARTIAL_SUCCESS_TRANSACTION_NOT_FOUND
    - Value:
      - **Error_message**:
        - Description: Invalid request
        - Tags: String
    - Tags: String
- Tags: String

#### Invalid:
- Value:
  - **Error_code **:
    - Description: INVALID
    - Value:
      - **Error_message**:
        - Description: Bad request
        - Tags: String
    - Tags: String
- Tags: String
### 401:

#### status:
- Description: error
- Tags: String

#### error_code:
- Description: access_denied
- Tags: String