Body
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
for final confirmation.Scenario C (Failure): If status is FAILURE, the refund was declined.
Request
Response
API Endpoints
Sandbox Link
POST
https://api.sandbox.juspay.io/orders/{order_id}/refunds
Production Link
POST
https://api.juspay.io/orders/{order_id}/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
version
*
string
Required
Pass the current date in YYYY-MM-DD format
Content-Type
*
string
Required
application/x-www-form-urlencoded
x-merchantid
*
string
Required
The merchant_id/username that you hold at Juspay
Request Schema: application/json
Parameters
unique_request_id
*
string
Required
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
amount
Double
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
200 : Success
Response Body
txn_uuid
string
Transaction UUID
txn_id
*
string
Required
Transaction ID
txn_detail
object
txn_uuid
string
Transaction UUID
Example :eulwh5QbZSBvwpt7333f3
txn_id
string
Transaction id
Example :merchant_success-JP1636474794-1
txn_amount
Integer
tax_amount
Integer
surcharge_amount
Integer
status
string
redirect
boolean
order_id
string
Order Id passed during order creation
Example JP1636474794
net_amount
Integer
gateway_id
integer
gateway
string
The gateway field indicates which payment processor was responsible for the original transaction and will handle the refund processing.
express_checkout
boolean
error_message
string
error_code
string
currency
string
ISO string of the currency.
created
string
Timestamp
2021-11-09T16:20:52Z
txn_flow_type
String
is_cvv_less_txn
String
status_id
integer
Status ID is a numeric id corresponding to the status value
status
*
string
Required
Status of the order. For information on different order status and handling, refer here
rewards_breakup
String
return_url
string
refunds
array of Objects
object
object
unique_request_id
String
The unique request id that is passed during refund initiation. Do not pass any special characters.
status
String
The status of the refund initiated. Initial status will always be PENDING
sent_to_gateway
String
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.
refund_type
String
The type of refund. Values can be STANDARD, INSTANT
refund_source
String
The name of gateway
ref
String
The refund id provided by the PG
initiated_by
String
The source of initiation.
id
String
The reference id provided by PG, if not available then its mapped to unique request id.
error_message
String
The error message provided by the PG
error_code
String
The error code provided by the PG
created
String
The refund amount passed in the request
amount
integer
The timestamp of refund creation
refunded
boolean
product_id
string
payment_method_type
string
payment_method
string
payment_links
object
web
string
https://api.juspay.in/merchant/pay/ordeh_57dfd768bb7d4896bc0c3f30bc9ad77
mobile
string
https://api.juspay.in/merchant/pay/ordeh_57dfd768bb7d4896bc0c3f30bc9ad77?mobile=true
iframe
string
https://api.juspay.in/merchant/ipay/ordeh_57dfd768bb7d4896bc0c3f30bc9ad77
payment_gateway_response
object
The json object with the details receive from PG
txn_id
string
Transaction ID for the payment attempt.
Example : merchant_success-JP1636474794-1
rrn
string
The bank reference number provided by the gateway
Example : 156555
resp_message
string
The response message provided by the gateway
Example : SUCCESS
resp_code
string
The response code provided by the gateway
epg_txn_id
string
The gateway transaction id
Example pay_IJZKtTpkiYWE24
created
string
The transaction creation timestamp
Example : 2021-11-09T16:21:11Z
auth_id_code
string
Auth code provided by the gateway for the transaction.
Example : 156555
eci
String
order_id
*
string
Required
OrderId provided in the request
offers
array
metadata
object
RAZORPAY:gateway_reference_id
string
testmid
merchant_id
string
The merchant id provided by Juspay
id
string
Unique ID generated by JusPay for the given order
gateway_reference_id
string
testmid
gateway_id
integer
effective_amount
Integer
date_created
string
Order creation timestamp in UTC
Example: 2021-11-09T16:19:55Z
customer_phone
string
The phone number of the customer provided during order creation
customer_id
string
The customer id provided during order creation
customer_email
string
The email Id of the customer provided during order creation
currency
string
The currency provided during order creation.
card
object
The json containing the details of the card used for the transaction.
using_token
boolean
using_saved_card
boolean
true if transaction was done via a saved card
false if transaction via new card/unsaved card
saved_to_locker
boolean
true if card was saved to locker, else false
name_on_card
string
The name on card used for the transaction
last_four_digits
string
The last four digit of the card used
expiry_year
string
The expiry year of the card used for the transaction
2024
expiry_month
string
The expiry month of the card used for the transaction
card_type
string
Indicates if the card is either CREDIT or DEBIT
card_reference
string
17a2ec4f27c918ttvbc58c9ae74090e
card_issuer
string
Indicates the bank which issued the card
Example : JP Morgan
card_isin
string
The first six digit of the card used for the transaction
example :411111
card_fingerprint
string
The unique identifier for the card
Example : 32qqi3svf5t5t37fq7ura2rgqqb
card_brand
string
The provider of the card, can be VISA, RUPAY etc.
extended_card_type
String
Detailed card type classification (e.g. CREDIT, DEBIT)
token_type
String
Indicates the type of token used for the transaction (e.g. CARD)
tokens
Array
List of tokens associated with the card, if any
card_issuer_country
String
Country where the card issuing bank is registered
Example:Brazil
bank_pg
String
bank_error_message
string
bank_error_code
string
auth_type
string
Authentication type used for the transaction (e.g. THREE_DS)
amount_refunded
integer
amount
*
integer
Required
udf1
String
The user defined fields passed during order creation. Empty in case not passed
udf2
String
The user defined fields passed during order creation. Empty in case not passed
udf3
String
The user defined fields passed during order creation. Empty in case not passed
udf4
String
The user defined fields passed during order creation. Empty in case not passed
udf5
String
The user defined fields passed during order creation. Empty in case not passed
udf6
String
The user defined fields passed during order creation. Empty in case not passed
udf7
String
The user defined fields passed during order creation. Empty in case not passed
udf8
String
The user defined fields passed during order creation. Empty in case not passed
udf9
String
The user defined fields passed during order creation. Empty in case not passed
udf10
String
The user defined fields passed during order creation. Empty in case not passed
maximum_eligible_refund_amount
Integer
400 : Invalid Input data
Response Body
Duplicate unique_request_id
JSON
status
String
ERROR
error_code
String
duplicate.call
error_message
String
A refund call was already completed with this unique_request_id for the order.
Duplicate Refund Request within 5 seconds
JSON
status
String
ERROR
error_code
String
duplicate.call
error_message
String
A refund call was already processing with this amount for the order.
Refund amount greater than refundable
JSON
status
String
ERROR
error_code
String
invalid.amount.exceeded
error_message
String
Refund amount exceeds the refundable amount.
Amount/unique_request_id not passed
JSON
status
String
Bad Request
error_code
String
Mandatory fields are missing
error_message
String
Mandatory fields are missing
Refund Amount is 0
JSON
status
String
ERROR
error_code
String
invalid amount
error_message
String
Amount is invalid
Invalid Order id
JSON
status
String
NOT_FOUND
status_id
String
40
order_id
String
66721145_keexeV8cNyb7DrYzs
Unsuccessful order
JSON
status
String
ERROR
error_code
String
invalid.order.not_successful
error_message
String
Cannot process unsuccessful order
Refund limit exceeds
String
25 refunds per order is the default limit
status
String
ERROR
error_code
String
request.exceeded
error_message
String
Refund create exceeded the limit
401 : Authentication Failed
Response Body
status
String
error
error_code
String
access_denied