--- page_title: Refund Order API product: API Reference page_source: https://juspay.io/br/docs/api-reference-brazil/docs/express-checkout/refund-order-api openapi: https://juspay.io/br/docs/api/swagger?document=https%3A%2F%2Fjuspay.io%2Fbr%2Fdocs%2Fapi-reference-brazil%2Fdocs%2Fexpress-checkout%2Frefund-order-api llms_txt: https://juspay.io/br/docs/llms.txt product_llms_txt: https://juspay.io/br/docs/api-reference-brazil/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.Refunds Flow Handles returning money to the customer. Covers both Full and Partial refunds. * **Step 1:** Create a unique request id (e.g., REF_ORD123_TIMESTAMP). This is mandatory for idempotency. It prevents accidental double refunds if the network times out. * **Step 2:** Call the Refund Order API * Pass the unique_request_id (Required). * For Full Refund: Do not send an amount field (or send the full order value). * For Partial Refund: Send the specific amount (e.g., "50.00") to be refunded. * **Step 3:** Parse the Response * Check the status field. * Scenario A (Success): If status is REFUNDED, the money has been initiated back to the source. * Scenario B (Pending): If status is PENDING, the bank is processing it. Rely on the Webhook or**[Order Status API](https://juspay.io/br/docs/api-reference-brazil/docs/express-checkout/order-status-api)** for final confirmation. * Scenario C (Failure): If status is FAILURE, the refund was declined.## Endpoints: - Sandbox: https://api.sandbox.juspay.io/orders/{order_id}/refunds - Production: https://api.juspay.io/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:

Example:-
Basic MUQ2QUxxxxxxxxxxxxU5QTIxQzNFNTQwNkFDMEZCOg==

- Tags: Base64 Encoded Username:Password, Mandatory ## Headers: #### version: Pass the current date in YYYY-MM-DD format - Tags: string, Required #### Content-Type: application/x-www-form-urlencoded - Tags: string, Required #### x-merchantid: The merchant_id/username that you hold at Juspay - Tags: string, Required ## Sample Code Snippets: ### Sample Request: #### Request Code Snippet: ```request curl -X POST https://api.juspay.io/orders/1418394476/refunds \ -u your_api_key: \ -H "version:2023-06-30" \ -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": "STRIPE", "express_checkout": true, "error_message": "", "error_code": "", "currency": "BRL", "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": "STRIPE", "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.io/merchant/pay/ordeh_57dfd768bb7d4896bc0c3f30bc9ad77", "mobile": "https://api.juspay.io/merchant/pay/ordeh_57dfd768bb7d4896bc0c3f30bc9ad77?mobile=true", "iframe": "https://api.juspay.io/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": { "STRIPE: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": "99999999", "customer_id": "testcardenc1", "customer_email": "test@gmail.com", "currency": "BRL", "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 } ``` ## 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 ## API Responses: ### 200: #### txn_uuid: - Description: Transaction UUID - Tags: string #### txn_id: - Description: Transaction ID - Tags: string, Required #### txn_detail: - Value: - **Txn_uuid**: - Description: Transaction UUIDExample :eulwh5QbZSBvwpt7333f3 - Tags: string - **Txn_id**: - Description: Transaction idExample :merchant_success-JP1636474794-1 - Tags: string - **Txn_amount**: - Tags: Integer - **Tax_amount**: - Tags: Integer - **Surcharge_amount**: - Tags: Integer - **Status**: - Tags: string - **Redirect**: - Tags: boolean - **Order_id**: - Description: Order Id passed during order creationExample JP1636474794 - Tags: string - **Net_amount**: - Tags: Integer - **Gateway_id**: - Tags: integer - **Gateway**: - Description: The gateway field indicates which payment processor was responsible for the original transaction and will handle the refund processing. - Tags: string - **Express_checkout**: - Tags: boolean - **Error_message**: - Tags: string - **Error_code**: - Tags: string - **Currency**: - Description: ISO string of the currency. - Tags: string - **Created**: - Description: Timestamp 2021-11-09T16:20:52Z - Tags: string - **Txn_flow_type**: - Tags: String - **Is_cvv_less_txn**: - Tags: String - Tags: object #### status_id: - Description: Status ID is a numeric id corresponding to the status value - Tags: integer #### status: - Description: Status of the order. For information on different order status and handling, refer [here](https://docs.juspay.in/resources/docs/common-resources/transaction-status) - Tags: string, Required #### 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 juspay 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://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: - Description: The json object with the details receive from PG - Value: - **Txn_id**: - Description: Transaction ID for the payment attempt.Example : merchant_success-JP1636474794-1 - Tags: string - **Rrn**: - Description: The bank reference number provided by the gatewayExample : 156555 - Tags: string - **Resp_message**: - Description: The response message provided by the gatewayExample : SUCCESS - Tags: string - **Resp_code**: - Description: The response code provided by the gateway - Tags: string - **Epg_txn_id**: - Description: The gateway transaction idExample pay_IJZKtTpkiYWE24 - Tags: string - **Created**: - Description: The transaction creation timestampExample : 2021-11-09T16:21:11Z - Tags: string - **Auth_id_code**: - Description: Auth code provided by the gateway for the transaction.Example : 156555 - Tags: string - **Eci**: - Tags: String - Tags: object #### order_id: - Description: OrderId provided in the request - Tags: string, Required #### offers: - Tags: array #### metadata: - Value: - **RAZORPAY:gateway_reference_id**: - Description: testmid - Tags: string - Tags: object #### merchant_id: - Description: The merchant id provided by Juspay - Tags: string #### id: - Description: Unique ID generated by JusPay for the given order - Tags: string #### gateway_reference_id: - Description: testmid - Tags: string #### gateway_id: - Tags: integer #### effective_amount: - Tags: Integer #### date_created: - Description: Order creation timestamp in UTC **Example** : 2021-11-09T16:19:55Z - Tags: string #### customer_phone: - Description: The phone number of the customer provided during order creation - Tags: string #### customer_id: - Description: The customer id provided during order creation - Tags: string #### customer_email: - Description: The email Id of the customer provided during order creation - Tags: string #### currency: - Description: The currency provided during order creation. - Tags: string #### card: - Description: The json containing the details of the card used for the transaction. - Value: - **Using_token**: - Tags: boolean - **Using_saved_card**: - Description: **true** if transaction was done via a saved card **false** if transaction via new card/unsaved card - Tags: boolean - **Saved_to_locker**: - Description: true if card was saved to locker, else false - Tags: boolean - **Name_on_card**: - Description: The name on card used for the transaction - Tags: string - **Last_four_digits**: - Description: The last four digit of the card used - Tags: string - **Expiry_year**: - Description: The expiry year of the card used for the transaction2024 - Tags: string - **Expiry_month**: - Description: The expiry month of the card used for the transaction - Tags: string - **Card_type**: - Description: Indicates if the card is either CREDIT or DEBIT - Tags: string - **Card_reference**: - Description: 17a2ec4f27c918ttvbc58c9ae74090e - Tags: string - **Card_issuer**: - Description: Indicates the bank which issued the cardExample : JP Morgan - Tags: string - **Card_isin**: - Description: The first six digit of the card used for the transactionexample :411111 - Tags: string - **Card_fingerprint**: - Description: The unique identifier for the cardExample : 32qqi3svf5t5t37fq7ura2rgqqb - Tags: string - **Card_brand**: - Description: The provider of the card, can be VISA, RUPAY etc. - Tags: string - **Extended_card_type**: - Description: Detailed card type classification (e.g. CREDIT, DEBIT) - Tags: String - **Token_type**: - Description: Indicates the type of token used for the transaction (e.g. CARD) - Tags: String - **Tokens**: - Description: List of tokens associated with the card, if any - Tags: Array - **Card_issuer_country**: - Description: Country where the card issuing bank is registered Example:Brazil - Tags: String - Tags: object #### bank_pg: - Tags: String #### bank_error_message: - Tags: string #### bank_error_code: - Tags: string #### auth_type: - Description: Authentication type used for the transaction (e.g. THREE_DS) - Tags: string #### amount_refunded: - Tags: integer #### amount: - Tags: integer, Required #### udf1: - Description: The user defined fields passed during order creation. Empty in case not passed - Tags: String #### udf2: - Description: The user defined fields passed during order creation. Empty in case not passed - Tags: String #### udf3: - Description: The user defined fields passed during order creation. Empty in case not passed - Tags: String #### udf4: - Description: The user defined fields passed during order creation. Empty in case not passed - Tags: String #### udf5: - Description: The user defined fields passed during order creation. Empty in case not passed - Tags: String #### udf6: - Description: The user defined fields passed during order creation. Empty in case not passed - Tags: String #### udf7: - Description: The user defined fields passed during order creation. Empty in case not passed - Tags: String #### udf8: - Description: The user defined fields passed during order creation. Empty in case not passed - Tags: String #### udf9: - Description: The user defined fields passed during order creation. Empty in case not passed - Tags: String #### udf10: - Description: The user defined fields passed during order creation. Empty in case not passed - Tags: String #### maximum_eligible_refund_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 - [Update Order API](https://juspay.io/br/docs/api-reference-brazil/docs/express-checkout/update-order-api) - [Transaction ID based and Instant refund](https://juspay.io/br/docs/api-reference-brazil/docs/express-checkout/transaction-id-based-and-instant-refund)