--- page_title: Refund Order API product: SmartGateway API Reference (Basic Auth) page_source: https://smartgateway.hdfc.bank.in/docs/smartgateway-api-ref-basicauth/docs/apis/refund-order-api openapi: https://smartgateway.hdfc.bank.in/docs/api/swagger?document=https%3A%2F%2Fsmartgateway.hdfc.bank.in%2Fdocs%2Fsmartgateway-api-ref-basicauth%2Fdocs%2Fapis%2Frefund-order-api llms_txt: https://smartgateway.hdfc.bank.in/docs/llms.txt product_llms_txt: https://smartgateway.hdfc.bank.in/docs/smartgateway-api-ref-basicauth/llms.txt --- ## 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://smartgateway.hdfcuat.bank.in/orders/{order_id}/refunds - Production: https://smartgateway.hdfc.bank.in/orders/{order_id}/refunds ## Request Type: POST ## Content-Type: application/json ## Authorization: #### Authorization: Base 64 encoded API Key obtained from HDFC Dashboard * API Key: **1234** (obtained from Dashboard). * Base64 Encoded API Key: `MTIzNA==` * The API key must be sent in the **Authorization** header as : **Basic MTIzNA==** - Tags: Base64 Encoded API Key, required ## Headers: #### Content-Type: application/json - Tags: string, Required #### x-merchantid: Merchant ID provided by Bank - Tags: string, Required #### x-customerid: Unique Customer ID mapped against each customer - Tags: String, Mandatory #### x-resellerid: Reseller ID provided by bank - Value: hdfc_reseller - Tags: String, Required ## Sample Code Snippets: ### Sample Request: #### Request Code Snippet: ```request curl --location --globoff 'https://smartgateway.hdfcuat.bank.in/orders/{order_id}/refunds' \ --header 'x-merchantid: merchant_id' \ --header 'x-customerid: customer_id' \ --header 'Content-Type: application/x-www-form-urlencoded' \ --header 'Authorization: Basic base_64_encoded_api_key==' \ --data-urlencode 'unique_request_id=xyz123' \ --data-urlencode 'amount=100.00' ``` ### Sample Response: #### Response: ```json //Please refer to the refunds block for refund status { "customer_email": "test@gmail.com", "customer_phone": "9999999999", "customer_id": "testcardenc1", "status_id": 21, "status": "CHARGED", "id": "ordeh_57dfd768bb7d4896bc042y0b90bc9ad77", "merchant_id": "merchant_success", "amount": 1, "currency": "INR", "order_id": "JP1636474794", "date_created": "2021-11-09T16:19:55Z", "return_url": "", "product_id": "", "payment_links": { "iframe": "https://smartgateway.hdfcuat.bank.in/merchant/ipay/ordeh_57dfd768bb7d4896bc042y0b90bc9ad77", "web": "https://smartgateway.hdfcuat.bank.in/merchant/ipay/ordeh_57dfd768bb7d4896bc042y0b90bc9ad77", "mobile": "https://smartgateway.hdfcuat.bank.in/merchant/ipay/ordeh_57dfd768bb7d4896bc042y0b90bc9ad77?mobile=true" }, "udf1": "", "udf2": "", "udf3": "", "udf4": "", "udf5": "", "udf6": "", "udf7": "", "udf8": "", "udf9": "", "udf10": "", "txn_id": "merchant_success-JP1636474794-1", "payment_method_type": "CARD", "auth_type": "THREE_DS", "card": { "expiry_year": "2024", "card_reference": "17a2ec4f27c918bd8dbc58c9ae74090e", "saved_to_locker": false, "expiry_month": "12", "name_on_card": "test", "card_issuer": "JP Morgan", "last_four_digits": "", "using_saved_card": true, "card_fingerprint": "32qqi3sv1u5237fq7ura2rgqqb", "card_isin": "411111", "card_type": "CREDIT", "card_brand": "VISA", "using_token": false }, "payment_method": "VISA", "refunded": true, "amount_refunded": 1, "effective_amount": 1, "refunds": [ { "id": "TEST1637681731", "amount": 1, "unique_request_id": "TEST1637681731", "ref": "rfnd_IP693G3wAX4ibJ", "created": "2021-11-23T15:35:32Z", "status": "SUCCESS", "error_message": "processed", "sent_to_gateway": true, "initiated_by": "API", "refund_source": "RAZORPAY", "refund_type": "STANDARD", "metadata": { "speed_processed": "normal", // only for Razorpay successful refunds "speed_requested": "normal" // only for Razorpay successful refunds }, "pg_processed_at": "2022-11-24T08:07:43Z", "error_code": "processed" } ], "resp_code": null, "resp_message": null, "bank_error_code": "", "bank_error_message": "", "txn_uuid": "eulwh5QbZSBvw35eWnH", "txn_detail": { "txn_id": "merchant_success-JP1636474794-1", "order_id": "JP1636474794", "status": "CHARGED", "error_code": null, "net_amount": 1, "surcharge_amount": null, "tax_amount": null, "txn_amount": 1, "offer_deduction_amount": null, "gateway_id": 23, "currency": "INR", "express_checkout": true, "redirect": true, "txn_uuid": "eulwh5QbZSBvw35eWnH", "gateway": "RAZORPAY", "error_message": "", "created": "2021-11-09T16:20:52Z" }, "payment_gateway_response": { "resp_code": "SUCCESS", "rrn": "156555", "created": "2021-11-09T16:21:11Z", "epg_txn_id": "pay_IJZKtTpki24ERy", "resp_message": "SUCCESS", "auth_id_code": "156555", "txn_id": "merchant_success-JP1636474794-1" }, "gateway_id": 23, "metadata": { "RAZORPAY:gateway_reference_id": "testmid" }, "gateway_reference_id": "testmid", "offers": [] } ``` ## Path Parameters: #### order_id: Order Id of the order for which you want to proceed with refund - Value: Example:- testing-order-one - Tags: String, Required ## 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 - Tags: string, Required #### amount: - Description: Amount that has to be refunded. Amount has to be less than or equal to the amount of the order that is not yet refunded. If this parameter is not passed, then the order is refunded entirely - Tags: Double, Required ## API Responses: ### 200: #### udf1-10: - Tags: string #### txn_uuid: - Description: eulwh5QbZSBvwpt7333f3 - Tags: string #### txn_id: - Description: merchant_success-JP1636474794-1 - Tags: string #### txn_detail: - Value: - **Txn_uuid**: - Description: eulwh5QbZSBvwpt7333f3 - Tags: string - **Txn_id**: - Description: merchant_success-JP1636474794-1 - Tags: string - **Txn_amount**: - Tags: integer - **Tax_amount**: - **Surcharge_amount**: - **Status**: - Description: CHARGED - Tags: string - **Redirect**: - Tags: boolean - **Order_id**: - Description: JP1636474794 - Tags: string - **Net_amount**: - Tags: integer - **Gateway_id**: - Tags: integer - **Gateway**: - Description: HDFC - Tags: string - **Express_checkout**: - Tags: boolean - **Error_message**: - Tags: string - **Error_code**: - Tags: string - **Currency**: - Description: INR - Tags: string - **Created**: - Description: 2021-11-09T16:20:52Z - Tags: string - Tags: object #### status_id: - Tags: integer #### status: - Description: CHARGED - Tags: string #### rewards_breakup: - Tags: String #### return_url: - Tags: string #### refunds: - Description: ### Payload - **Object**: - Value: - **Unique_request_id**: - Description: The unique request id that is passed during refund initiation. Do not pass any special characters. - Tags: String - **Status**: - Description: The status of the refund initiated. Initial status will always be PENDING - Tags: String - **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 bank for a max of 15minutes. - Tags: String - **Refund_type**: - Description: The type of refund. Values can be STANDARD, INSTANT - Tags: String - **Refund_source**: - Description: The name of gateway - Tags: String - **Ref**: - Description: The refund id provided by the PG - Tags: String - **Initiated_by**: - Description: The source of initiation. - Tags: String - **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 - **Error_code**: - Description: The error code provided by the PG - Tags: String - **Created**: - Description: The refund amount passed in the request - Tags: String - **Amount**: - Description: The timestamp of refund creation - Tags: integer - Tags: object - Tags: array of Objects #### refunded: - Tags: boolean #### product_id: - Tags: string #### payment_method_type: - Description: CARD - Tags: string #### payment_method: - Description: VISA - Tags: string #### payment_links: - Value: - **Web**: - Description: [https://smartgateway.hdfcuat.bank.in/merchant/ipay/ordeh_57dfd768bb7d4896bc042y0b90bc9ad77](https://smartgateway.hdfcuat.bank.in/merchant/ipay/ordeh_57dfd768bb7d4896bc042y0b90bc9ad77)" - Tags: string - **Mobile**: - Description: [https://smartgateway.hdfcuat.bank.in/merchant/ipay/ordeh_57dfd768bb7d4896bc042y0b90bc9ad77?mobile=true](https://smartgateway.hdfcuat.bank.in/merchant/ipay/ordeh_57dfd768bb7d4896bc042y0b90bc9ad77?mobile=true) - Tags: string - **Iframe**: - Description: [https://smartgateway.hdfcuat.bank.in/merchant/ipay/ordeh_57dfd768bb7d4896bc042y0b90bc9ad77](https://smartgateway.hdfcuat.bank.in/merchant/ipay/ordeh_57dfd768bb7d4896bc042y0b90bc9ad77) - Tags: string - Tags: object #### payment_gateway_response: - Value: - **Txn_id**: - Description: merchant_success-JP1636474794-1 - Tags: string - **Rrn**: - Description: 156555 - Tags: string - **Resp_message**: - Description: SUCCESS - Tags: string - **Resp_code**: - Description: SUCCESS - Tags: string - **Epg_txn_id**: - Description: pay_IJZKtTpkiYWE24 - Tags: string - **Created**: - Description: 2021-11-09T16:21:11Z - Tags: string - **Auth_id_code**: - Description: 156555 - Tags: string - Tags: object #### order_id: - Description: JP1636474794 - Tags: string #### offers: - Tags: array #### metadata: - Value: - **RAZORPAY:gateway_reference_id**: - Description: testmid - Tags: string - Tags: object #### merchant_id: - Description: merchant_success - Tags: string #### id: - Description: ordeh_57dfd768bb7d4896bc0c3f30bc9ad77 - Tags: string #### gateway_reference_id: - Description: testmid - Tags: string #### gateway_id: - Tags: integer #### effective_amount: - Tags: integer #### date_created: - Description: 2021-11-09T16:19:55Z - Tags: string #### customer_phone: - Description: 9999999999 - Tags: string #### customer_id: - Description: testcardenc1 - Tags: string #### customer_email: - Description: test@gmail.com - Tags: string #### currency: - Description: INR - Tags: string #### card: - Value: - **Using_token**: - Tags: boolean - **Using_saved_card**: - Tags: boolean - **Saved_to_locker**: - Tags: boolean - **Name_on_card**: - Description: test - Tags: string - **Last_four_digits**: - Tags: string - **Expiry_year**: - Description: 2024 - Tags: string - **Expiry_month**: - Description: 12 - Tags: string - **Card_type**: - Description: CREDIT - Tags: string - **Card_reference**: - Description: 17a2ec4f27c918ttvbc58c9ae74090e - Tags: string - **Card_issuer**: - Description: JP Morgan - Tags: string - **Card_isin**: - Description: 411111 - Tags: string - **Card_fingerprint**: - Description: 32qqi3svf5t5t37fq7ura2rgqqb - Tags: string - **Card_brand**: - Description: VISA - Tags: string - Tags: object #### bank_pg: #### bank_error_message: - Tags: string #### bank_error_code: - Tags: string #### auth_type: - Description: THREE_DS - Tags: string #### amount_refunded: - Tags: integer #### amount: - Tags: integer ### 400: #### Duplicate unique_request_id: - Value: - **Status**: - Description: ERROR - Tags: String - **Error_code**: - Description: duplicate.call - Tags: String - **Error_message**: - Description: A refund call was already completed with this unique_request_id for the order. - Tags: String - Tags: JSON #### Duplicate Refund Request within 5 seconds: - Value: - **Status**: - Description: ERROR - Tags: String - **Error_code**: - Description: duplicate.call - Tags: String - **Error_message**: - Description: A refund call was already processing with this amount for the order. - Tags: String - Tags: JSON #### Refund amount greater than refundable: - Value: - **Status**: - Description: ERROR - Tags: String - **Error_code**: - Description: invalid.amount.exceeded - Tags: String - **Error_message**: - Description: Refund amount exceeds the refundable amount. - Tags: String - Tags: JSON #### Amount/unique_request_id not passed: - Value: - **Status**: - Description: Bad Request - Tags: String - **Error_code**: - Description: Mandatory fields are missing - Tags: String - **Error_message**: - Description: Mandatory fields are missing - Tags: String - Tags: JSON #### Refund Amount is 0: - Value: - **Status**: - Description: ERROR - Tags: String - **Error_code**: - Description: invalid amount - Tags: String - **Error_message**: - Description: Amount is invalid - Tags: String - Tags: JSON #### Invalid Order id: - Value: - **Status**: - Description: NOT_FOUND - Tags: String - **Status_id**: - Description: 40 - Tags: String - **Order_id**: - Description: 66721145_keexeV8cNyb7DrYzs - Tags: String - Tags: JSON #### Unsuccessful order: - Value: - **Status**: - Description: ERROR - Tags: String - **Error_code**: - Description: invalid.order.not_successful - Tags: String - **Error_message**: - Description: Cannot process unsuccessful order - Tags: String - Tags: JSON #### Refund limit exceeds: - Description: 25 refunds per order is the default limit - Value: - **Status**: - Description: ERROR - Tags: String - **Error_code**: - Description: request.exceeded - Tags: String - **Error_message**: - Description: Refund create exceeded the limit - Tags: String - Tags: String ### 401: #### status: - Description: error - Tags: String #### error_code: - Description: access_denied - Tags: String --- ## See Also - [Order Status API](https://smartgateway.hdfc.bank.in/docs/smartgateway-api-ref-basicauth/docs/apis/order-status-api) - [Handling Payment Response](https://smartgateway.hdfc.bank.in/docs/smartgateway-api-ref-basicauth/docs/handling-payment-response/handling-payment-response)