Body
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 and UPI refunds 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 biz@juspay.in
to get the credentials.Please set Instant refund to TRUE from the Settings section of the Juspay dashboard.
Request
Response
API Endpoints
Sandbox Link
POST
https://sandbox.juspay.in/refunds
Production Link
POST
https://api.juspay.in/refunds
Authorization Header
Basic Auth
*
Base64 Encoded Username:Password
Mandatory
Consists of two parts.
Username: API Key obtained from Juspay dashboard
Password: Empty string
Example:-
Basic MUQ2QUxxxxxxxxxxxxU5QTIxQzNFNTQwNkFDMEZCOg==
Headers
Content-Type
string
application/x-www-form-urlencoded
x-merchantid
*
String
Mandatory
Merchant ID provided by Juspay
x-routing-id
*
String
Required
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.
Example:- customer_1122
Parameters
amount
*
number
Required
The amount to be refunded as requested by the merchant
unique_request_id
*
string
Required
Unique id for the refund transaction. This cannot be re-used to avoid duplication refunds
order_id
string
An identifier for the order for which the refund has to be processed
txn_id
string
Pass txn_id if you want to perform a refund based on txn_id. Applicable only for Juspay orders.
refund_type
string
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.
order_type
string
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.
beneficiary_details
Array of objects
Beneficiary details on which payout will be done
name
String
account
String
Required for INSTANT REFUND WITH ACCOUNT NUMBER
ifsc
String
Required for INSTANT REFUND WITH ACCOUNT NUMBER
vpa
String
Required for INSTANT REFUND WITH VPA
200 : Success
Response Body
Txn Id Based Refund Response
JSON
unique_request_id
String
The unique ID provided by the merchant to identify refund object.
txn_id
String
Transaction ID against which the refund was initiated.
status
String
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.
sent_to_gateway
Boolean
This will be set to true once the refund is initiated to a gateway from Juspay
response_code
String
The Response code from the gateway when refund
refund_type
String
‘INSTANT’ or ‘STANDARD’
refund_source
String
Underlying gateway used to initiate the refund transaction, this will be populated in instant refund case
refund_arn
String
The Reference number provided by Acquirers bank to track the refund at Issuers bank. May not be available for all the gateways
reference_id
String
Reference number provided by the underlying gateway
order_id
String
Order ID for which the refund was initiated.
initiated_by
String
Username of the initiating user. This will be “API” in case of initiated via API
gateway
String
Underlying gateway used to initiate the refund transaction
error_message
String
The response message from the gateway when refund
epg_txn_id
String
Refund transaction id provided by the underlying gateway
created
String
Date time (ISO representation) when a refund was created
authorization_id
String
Authorization Identification Code issued by the Issuer bank for a successful refund transaction. May not be available for all the gateways
amount
Integer
Amount refunded (or to be refunded)
Instant Refund Response
JSON
unique_request_id
String
The unique ID provided by the merchant to identify refund object.
status
String
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.
sent_to_gateway
Boolean
This will be set to true once the refund is initiated to a gateway from Juspay
txn_id
String
Transaction ID against which the refund was initiated.
refund_type
String
‘INSTANT’ or ‘STANDARD’
refund_source
String
Underlying gateway used to initiate the refund transaction, this will be populated in instant refund case
reference_id
String
Reference number provided by the underlying gateway
response_code
String
The Response code from the gateway when refund
refund_arn
String
The Reference number provided by Acquirers bank to track the refund at Issuers bank. May not be available for all the gateways
order_id
String
Order ID for which the refund was initiated.
initiated_by
String
Username of the initiating user. This will be “API” in case of initiated via API
error_message
String
The response message from the gateway when refund
gateway
String
Underlying gateway used to initiate the refund transaction
epg_txn_id
String
Refund transaction id provided by the underlying gateway
created
String
Date time (ISO representation) when a refund was created
amount
Integer
Amount refunded (or to be refunded)
authorization_id
String
Authorization Identification Code issued by the Issuer bank for a successful refund transaction. May not be available for all the gateways
400 : Invalid Input data
Response Body
status
string
invalid_request_error
error_code
string
invalid
error_message
string
instant refund flag is not enabled