--- page_source: https://docs.juspay.io/paytm-gateway-configuration/docs/express-checkout/transaction-id-based-and-instant-refund page_title: Transaction ID based and Instant refund --- ## API Version: default # Transaction ID based and Instant refund > **Note** > **Instant Refund** : > > * This API supports refunds for only JUSPAY orders, which are paid through cards and card details stored. > * The API retrieves card details from the card vault from the order_id/txn_id passed in the refund request and attempt a payout on that card. > * NON_JUSPAY orders and payment methods as NB, are not supported through this API, currently. > * To enable Instant refunds, you will need to configure the MORPHEUS gateway from the Juspay dashboard. Please get in touch with global@juspay.in to get the credentials. > * Please set Instant refund to TRUE from the Settings section of the Juspay dashboard. ## Endpoints: - Production: https://api.juspay.in/refunds ## Request Type: POST ## 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 ## Sample Code Snippets: ### Sample Request: #### Txn ID based refund Code Snippet: ```txn id based refund curl --location --request POST 'https://api.juspay.in/refunds' \ --header 'Authorization: Basic NTlE*****E4QzE1Og==' \ --header 'Content-Type: application/x-www-form-urlencoded' \ --data-urlencode 'unique_request_id=refund_122_3472' \ --data-urlencode 'amount=1' \ --data-urlencode 'txn_id=merchant_success-JP1636706983-2' ``` #### Instant Refund Code Snippet: ```instant refund curl -X POST \ https://api.juspay.in/refunds \ -u your_api_key: \ -H 'Content-Type: application/x-www-form-urlencoded' \ -d 'unique_request_id=rfd_1234&amount=98.20&order_id=ord_123&refund_type=INSTANT' ``` #### Instant refund with account number Code Snippet: ```instant refund with account number curl -X POST \ https://api.juspay.in/refunds \ -u your_api_key: \ -H 'Content-Type: application/x-www-form-urlencoded' \ -d “unique_request_id”:”rfd_1234” \ -d “amount”:”98.20” \ -d “order_id”:”ord_123” \ -d “refund_type”:”INSTANT” \ -d “Beneficiary_details”: { "details": { "name": "Taral Shah", "account": "026687138917581", "ifsc" : "YESB0000262" }, "type": "ACCOUNT_IFSC" } ``` #### Instant refund with VPA Code Snippet: ```instant refund with vpa curl -X POST \ https://api.juspay.in/refunds \ -u your_api_key: \ -H 'Content-Type: application/x-www-form-urlencoded' \ -d “unique_request_id”:”rfd_1234” \ -d “amount”:”98.20” \ -d “order_id”:”ord_123” \ -d “refund_type”:”INSTANT” \ -d “Beneficiary_details”: { "details": { "name": "Taral Shah", "vpa": "xyz@upi" }, "type": "UPI_ID" } ``` ### Sample Response: #### Txn ID Based Refund Response: ```plaintext { "unique_request_id": "refund_122_3472", "txn_id": "merchant_success-JP1636706983-2", "status": "PENDING", "sent_to_gateway": false, "response_code": null, "refund_type": "STANDARD", "refund_source": "STRIPE", "refund_arn": null, "reference_id": null, "order_id": "JP1636706983", "initiated_by": "API", "gateway": "STRIPE", "error_message": null, "epg_txn_id": null, "created": "2021-10-11T08:52:31Z", "authorization_id": null, "amount": 1 } ``` #### Instant Refund Response: ```json { "unique_request_id": "paytmv2_12231723_50", "status": "PENDING", "sent_to_gateway": true, "txn_id": "merchantid-ord_123-1", "refund_type": "INSTANT", "refund_source": "YESBANK_VISADIRECT", "reference_id": null, "response_code": null, "refund_arn": null, "order_id": "ord_123", "initiated_by": "API", "error_message": null, "gateway": "MORPHEUS", "epg_txn_id": null, "created": "2019-03-14T14:40:23Z", "amount": 1, "authorization_id": null } ``` ## Body Parameters: ### Parameters: #### amount: - Description: The amount to be refunded as requested by the merchant - Tags: number, Required #### unique_request_id: - Description: Unique id for the refund transaction. This cannot be re-used to avoid duplication refunds - Tags: string, Required #### order_id: - Description: An identifier for the order for which the refund has to be processed - Tags: string #### txn_id: - Description: Pass txn_id if you want to perform a refund based on txn_id. Applicable only for Juspay orders. - Tags: string #### refund_type: - Description: Required for Payouts product. Identifier to determine the refund type, taking the values ‘INSTANT’ or ‘INSTANT_WITH_FALLBACK’ or ‘GATEWAY’. **STANDARD** - This is the default. For refunds to be initiated to Gateways from where payment was done. This is a normal refund process. **INSTANT** - If passed, Juspay will attempt Instant refund when payment source (e.g. stored card) is available. If the payment source is not available, the API will return 400 bad request. **INSTANT_WITH_FALLBACK** - This will work only for orders created via juspay system i.e. JUSPAY order_type. In case if an instant refund is not eligible, this option will initiate refunds with gateway where payment was done. - Tags: string #### order_type: - Description: Values can be JUSPAY or NON_JUSPAY. Pass JUSPAY if the transaction was made through Juspay Express Checkout, otherwise NON_JUSPAY. The default is JUSPAY. - Tags: string #### beneficiary_details: - Description: Beneficiary details on which payout will be done - Value: - **Name**: - Tags: String - **Account**: - Description: Required for INSTANT REFUND WITH ACCOUNT NUMBER - Tags: String - **Ifsc**: - Description: Required for INSTANT REFUND WITH ACCOUNT NUMBER - Tags: String - **Vpa**: - Description: Required for INSTANT REFUND WITH VPA - Tags: String - Tags: Array of objects ## API Responses: ### 200: #### Txn Id Based Refund Response: - Value: - **Unique_request_id**: - Description: The unique ID provided by the merchant to identify refund object. - Tags: String - **Txn_id**: - Description: Transaction ID against which the refund was initiated. - Tags: String - **Status**: - Description: Status of the refund. Can be one of PENDING, SUCCESS, FAILURE, MANUAL_REVIEW.SUCCESS: This means that the refund has been successfully executed.PENDING: This would mean that the refund has been queued with JusPay or with the downstream system.FAILURE: We were unable to process the refund successfully. You have to try again with new unique_request_id.MANUAL_REVIEW: This would mean that the refund request was sent an ambiguous response from the payment gateway and the merchant has to manually reconcile it with the payment gateway to get the proper response. - Tags: String - **Sent_to_gateway**: - Description: This will be set to true once the refund is initiated to a gateway from Juspay - Tags: Boolean - **Response_code**: - Description: The Response code from the gateway when refund - Tags: String - **Refund_type**: - Description: ‘INSTANT’ or ‘STANDARD’ - Tags: String - **Refund_source**: - Description: Underlying gateway used to initiate the refund transaction, this will be populated in instant refund case - Tags: String - **Refund_arn**: - Description: The Reference number provided by Acquirers bank to track the refund at Issuers bank. May not be available for all the gateways - Tags: String - **Reference_id**: - Description: Reference number provided by the underlying gateway - Tags: String - **Order_id**: - Description: Order ID for which the refund was initiated. - Tags: String - **Initiated_by**: - Description: Username of the initiating user. This will be “API” in case of initiated via API - Tags: String - **Gateway**: - Description: Underlying gateway used to initiate the refund transaction - Tags: String - **Error_message**: - Description: The response message from the gateway when refund - Tags: String - **Epg_txn_id**: - Description: Refund transaction id provided by the underlying gateway - Tags: String - **Created**: - Description: Date time (ISO representation) when a refund was created - Tags: String - **Authorization_id**: - Description: Authorization Identification Code issued by the Issuer bank for a successful refund transaction. May not be available for all the gateways - Tags: String - **Amount**: - Description: Amount refunded (or to be refunded) - Tags: Integer - Tags: JSON #### Instant Refund Response: - Value: - **Unique_request_id**: - Description: The unique ID provided by the merchant to identify refund object. - Tags: String - **Status**: - Description: Status of the refund. Can be one of PENDING, SUCCESS, FAILURE, MANUAL_REVIEW.SUCCESS: This means that the refund has been successfully executed.PENDING: This would mean that the refund has been queued with JusPay or with the downstream system.FAILURE: We were unable to process the refund successfully. You have to try again with new unique_request_id.MANUAL_REVIEW: This would mean that the refund request was sent an ambiguous response from the payment gateway and the merchant has to manually reconcile it with the payment gateway to get the proper response. - Tags: String - **Sent_to_gateway**: - Description: This will be set to true once the refund is initiated to a gateway from Juspay - Tags: Boolean - **Txn_id**: - Description: Transaction ID against which the refund was initiated. - Tags: String - **Refund_type**: - Description: ‘INSTANT’ or ‘STANDARD’ - Tags: String - **Refund_source**: - Description: Underlying gateway used to initiate the refund transaction, this will be populated in instant refund case - Tags: String - **Reference_id**: - Description: Reference number provided by the underlying gateway - Tags: String - **Response_code**: - Description: The Response code from the gateway when refund - Tags: String - **Refund_arn**: - Description: The Reference number provided by Acquirers bank to track the refund at Issuers bank. May not be available for all the gateways - Tags: String - **Order_id**: - Description: Order ID for which the refund was initiated. - Tags: String - **Initiated_by**: - Description: Username of the initiating user. This will be “API” in case of initiated via API - Tags: String - **Error_message**: - Description: The response message from the gateway when refund - Tags: String - **Gateway**: - Description: Underlying gateway used to initiate the refund transaction - Tags: String - **Epg_txn_id**: - Description: Refund transaction id provided by the underlying gateway - Tags: String - **Created**: - Description: Date time (ISO representation) when a refund was created - Tags: String - **Amount**: - Description: Amount refunded (or to be refunded) - Tags: Integer - **Authorization_id**: - Description: Authorization Identification Code issued by the Issuer bank for a successful refund transaction. May not be available for all the gateways - Tags: String - Tags: JSON ### 400: #### status: - Description: invalid_request_error - Tags: string #### error_code: - Description: invalid - Tags: string #### error_message: - Description: instant refund flag is not enabled - Tags: string