--- page_title: Payout Refund API product: API Reference Global page_source: https://juspay.io/sea/docs/api-reference-global/docs/refunds-via-payouts/payout-refund-api openapi: https://juspay.io/sea/docs/api/swagger?document=https%3A%2F%2Fjuspay.io%2Fsea%2Fdocs%2Fapi-reference-global%2Fdocs%2Frefunds-via-payouts%2Fpayout-refund-api llms_txt: https://juspay.io/sea/docs/llms.txt product_llms_txt: https://juspay.io/sea/docs/api-reference-global/llms.txt --- ## API Version: default # Refund API Create a refund for an Order. Refunds can be initiated directly to the amount debited source or other payment modes with payouts. This API supports both refunds and Payout for Juspay orders. Refunds/Payouts can be initiated only for transactions that are CHARGED. The response of refund/payout initiation is similar to that of order status API Response with the addition of `refunds` block. > **Note** > Either `txn_id` or `order_id` has to be passed in request. ## Endpoints: - Sandbox: https://sandbox.juspay.in/refunds - Production: https://api.juspay.in/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: #### Content-Type: application/x-www-form-urlencoded - Tags: string, Required #### x-merchantid: Unique identifier for the merchant. This is the Merchant ID provided by Juspay. The value is case sensitive. > **Note** > Passing this value will help us route efficiently at network level. - Value: x-merchantid: testaccount - Tags: string, Recommended ## Sample Code Snippets: ### Sample Request: #### Refund via Payout Code Snippet: ```refund via payout curl -X POST \ https://{host}/refunds \ -u your_api_key: \ -H 'Content-Type: application/x-www-form-urlencoded' \ -H 'x-merchantid: your_merchant_id' \ -d "unique_request_id=rfd_1234" \ -d "amount=98.20" \ -d "txn_id=txn_123" \ -d "refund_type=PAYOUT" \ -d 'beneficiary_details= { "details": { "first_name": "John", "last_name" : "Wick" "account": "026687138997581", "bank_code": "JP_MY_PUBLIC", "address": { "city": "Singapore", "country_code": "SGP", "postcode": "238858", "street_address": "8, Bencoolen St", "state": "Singapore" } } , "transfer_type" : "LOCAL" , "payout_mode" : "FAST" , "type": "BANK_TRANSFER" }' ``` ### Sample Response: #### Refund via Payout: ```plaintext { "unique_request_id": "refund_122_3472", "txn_id": "Merchant-JP1636706983-2", "status": "PENDING", "sent_to_gateway": false, "response_code": null, "refund_type": "PAYOUT", "payout_gateway_details" : {"gateway" : "AIRWALLEX", "gateway_reference_id" : "bus"} "order_id": "JP1636706983", "initiated_by": "API", "epg_txn_id": null, "created": "2021-10-11T08:52:31Z", "authorization_id": null, "amount": 1, "currency": "SGD" } ``` ## 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 #### txn_id: - Description: Pass txn_id if you want to perform a refund based on txn_id. Not needed if passing order id. Its optional if txn_id is passed - Tags: String, Conditional #### order_id: - Description: An identifier for the order for which the refund has to be processed. Not needed if order_id is used. Its optional if txn_id is passed - Tags: String, Conditional #### refund_reason: - Description: Reason for the refund. Default will be “CANCELLATION” `Possible values:`GOODWILL WAIVER PRODUCT_OR_SERVICE_NOT_DELIVEREDUNSATISFACTORY_PRODUCT_OR_SERVICECANCELLATIONPARTIAL_CANCELLATIONTECHNICAL_ISSUESOFFER_OR_SUBSCRIPTION_ISSUESDUPLICATE_PAYMENTDELAYED_SUCCESS - Value: Possible Values: “GOODWILL” “WAIVER” “PRODUCT_OR_SERVICE_NOT_DELIVERED” “UNSATISFACTORY_PRODUCT_OR_SERVICE” “CANCELLATION” “PARTIAL_CANCELLATION” “TECHNICAL_ISSUES” “OFFER_OR_SUBSCRIPTION_ISSUES” “DUPLICATE_PAYMENT” “DELAYED_SUCCESS” - Tags: String, Optional #### refund_type: - Description: Its **Required** for payout case and **Optional** for back to source casesIdentifier to determine the refund type, taking the value as “**PAYOUT** ” - Tags: String, Conditional #### beneficiary_details: - Description: Its **Required** for payout case and **Optional** for back to source casesBeneficiary details on which payout will be done. Not needed if you are sending beneficiary_id - Value: - **Details**: - Description: Beneficiary Details which includes first_name, last_name, account, bank_code, address**Format** : - Value: BeneficiaryDetails = {"account" : String, "first_name" : String, "last_name" : String, "bank_code": String, "address": {"city" : String, "country_code" : String, "postcode" : String, "street_address" : String, "state" : String } } - Tags: String, Mandatory - **Transfer_type**: - Description: Type of payout - Value: Possible value: INTERNATIONAL,LOCAL - Tags: String, Mandatory - **Payout_mode**: - Value: Possible value: IBAN,FAST - Tags: String, Mandatory - **Type**: - Description: type of payout mode - Value: Possible value: BANK_TRANSFER - Tags: String, Mandatory - Tags: String, Mandatory #### preferred_gateway: - Description: Specify your preferred Payout gateway details for this refund. - Value: - **Gateway**: - Description: Specify the Payout gateway to process payouts - Value: Sample Value: 2C2P, AIRWALLEX - Tags: String, Mandatory - **Gateway_reference_id**: - Description: Pass the gateway_reference_id if the payout gateway configured with gateway_reference_id on juspay dashboard. - Value: Sample Value: Bus, Train - Tags: String, Optional - Tags: String, Conditional ## API Responses: ### 200: #### refunds: - Description: ### Payload - **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,PAYOUT - 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 - **Epg_txn_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 - **Currency**: - Description: The currency for the refund processed amount - Tags: String - **Txn_id**: - Description: Transaction ID of the refund processed - Tags: String - **Payout_gateway_details**: - Description: Payout processed gateway details - Value: - **Gateway**: - Description: Specifies the payout processed gateway - Tags: String - **Gateway_reference_id**: - Description: Specifies the gateway reference id of the payout processed gateway - Tags: String - Tags: String - Tags: array of Objects ### 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 - [List Payout Methods](https://juspay.io/sea/docs/api-reference-global/docs/refunds-via-payouts/list-payout-methods) - [Refund API(refund to source)](https://juspay.io/sea/docs/api-reference-global/docs/refunds-via-payouts/refund-apirefund-to-source)