Hey! These docs are for version 3.2, which is no longer officially supported. Click here for the latest version, 1.0!

Transaction ID based and Instant refund

If enabled, the user can choose the "INSTANT" refund type, where the refund is attempted on the payment source (e.g. stored card), if available. "STANDARD" is the default payment type, where refunds are to be initiated to Gateways from where the payment was done. "INSTANT_WITH_FALLBACK" is another user option, which defaults to the STANDARD type if the INSTANT refund fails.



  • This API currently supports refunds only for JUSPAY orders, which are paid through cards and stored card details.
  • 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 [email protected] to get the credentials.
  • Please set Instant refund to TRUE from the Settings section of the Juspay dashboard.
The response for the Instant Refund API consists of the following parameters:       (click to open table)
unique_request_idStringThe unique ID provided by the merchant to identify refund object.
reference_idStringReference number provided by the underlying gateway.
order_idStringOrder ID for which the refund was initiated.
txn_idStringTransaction ID against which the refund was initiated.
amountDoubleAmount refunded (or to be refunded).
Date time (ISO representation) when a refund was created.
refund_typeString‘INSTANT’ or ‘STANDARD’
refund_sourceStringUnderlying gateway used to initiate the refund transaction, this will be populated in instant refund case.
gatewayStringUnderlying gateway used to initiate the refund transaction.
epg_txn_idStringRefund transaction id provided by the underlying gateway.
statusStringStatus of the refund.
"SUCCESS" unless otherwise indicated:
  Status codes and meaning
    This means that the refund has been
    successfully executed.
    This would mean that the refund has
    been queued with JusPay or with the
    downstream system.
    We were unable to process the refund
    successfully. You have to try again
    with a new unique_request_id.
    This would mean that the refund was
    sent an ambigious response from the
    payment gateway, and the merchant
    has to manually reconcile it with the
    payment gateway to get the proper
    response. Also, any refunds which are
    in pending for more than 10 days
    are sent for manual review.
response_codeStringThe Response code from the gateway when refund is initiated.
error_messageStringThe response message from the gateway when refund is initiated.
refund_arnStringThe Reference number provided by Acquirers bank to track the refund at Issuers bank. May not be available for all the gateways.
authorization_idStringAuthorization Identification Code issued by the Issuer bank for a successful refund transaction. May not be available for all the gateways
sent_to_gatewayStringThis will be set to true once the refund is initiated to a gateway from Juspay.
initiated_byStringUsername of the initiating user. This will be “API” in case of initiation via API.
idStringID generated for the refund
The request for this API must include the parameters:  amount and unique_request_id. Refund can be based on either  order_id   or  txn_id, as shown in the examples.       (click to open tables)
amount*DoubleThe amount to be refunded as requested by the merchant.
unique_request_id*StringUnique id for the refund transaction. This cannot be re-used to avoid duplication refunds.
order_id*StringAn identifier for the order for which the refund has to be processed. Required if the refund is to be based on order_id
txn_id*StringPass txn_id if you want to perform a refund based on txn_id. Applicable only for Juspay orders.
refund_typeStringIdentifier to determine the refund type. Possible values are ‘INSTANT’ or ‘INSTANT_WITH_FALLBACK’ or ‘STANDARD'.
  Identifiers for Refund Type:
    This is the default. This is the normal
    refund process, where refunds are to
    be initiated to Gateways from where
    the payment was done.
    If passed, Juspay will attempt an
    Instant refund when the payment
    source (e.g. stored card) is available.
    If the payment source is not available,
    the API will return 400 bad request.
    This will work only for orders created
    via the Juspay system i.e. JUSPAY
    order_type. In case an instant refund is
    not eligible, this option will initiate
    refunds with the gateway where the
    payment was done.
order_typeStringValues can be JUSPAY or NON_JUSPAY. Pass JUSPAY if the transaction was made through Juspay Express Checkout, otherwise NON_JUSPAY. The default is JUSPAY.
   {amount, currency}
ObjectThese two string values are mandatory in case order_type = NON_JUSPAY.
  Order object:
    Amount to be refunded.
    ISO string of the currency. Use INR
    for Indian Rupee. Among other
    accepted values USD, GBP, and EUR
payout_methodStringMandatory If order_type=NON_JUSPAY.
ENUM: bank / upi / card
bank_account_numberStringMandatory If a merchant wants to perform an instant refund for a net banking transaction
bank_ifscStringMandatory If a merchant wants to perform an instant refund for a net banking transaction.
vpaStringMandatory If a merchant wants to perform an instant refund to a VPA.
* = Required
* = Conditionally required
Click Try It! to start a request and see the response here!