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.
Request
Response
API Endpoints
Sandbox Link
POST
https://sandbox.juspay.in/orders/{order_id}/refunds
Production Link
POST
https://api.juspay.in/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
x-merchantid
*
String
Required
Merchant ID provided by Juspay
Example:-
merchant-id
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
Content-Type
String
application/x-www-form-urlencoded
Path Params
order_id
*
String
Mandatory
Max Length : 21
Order Id of the order for which you want to proceed with refund
Example:- 1418394476
Request Schema: application/json
Parameters
unique_request_id
*
string
Required
Max Length : 255
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 and alphanumeric. Special characters are not recommended as some of the underlying gateway/aggregator might have restrictions.
amount
*
Double
Required
Amount that has to be refunded. Amount has to be less than or equal to the effective_amount of the order that is not yet refunded.If this parameter is not passed, then the order is refunded entirely.
Note
The minimum amount that can be refunded is 1 INR.
metaData
String
Optional
Allows merchants to pass additional contextual information while initiating a refund.
Example:- Refund Note / Description)
metaData Details
description
String
Optional
Refund note or merchant reference text describing the reason or context for the refund.
Note
If the metaData field is included in the refund request, it is stored internally with the refund and will be returned in the Refund API response, Order Status API, and the Refund Webhook Payload.
Use Case: Merchants can use this field to:
Store refund reason
Pass internal ticket/reference number
Track refund context in reconciliation systems
200 : Success
Response Body
udf1-10
string
Max Length : 255
txn_uuid
string
Max Length : 128
eulwh5QbZSBvwpt7333f3
txn_id
string
Max Length : 255
merchant_success-JP1636474794-1
txn_detail
object
txn_uuid
string
Max Length : 128
eulwh5QbZSBvwpt7333f3
txn_id
string
Max Length : 255
merchant_success-JP1636474794-1
txn_amount
integer
tax_amount
null
surcharge_amount
null
status
string
Max Length : 255
redirect
boolean
order_id
string
Max Length : 21
JP1636474794
net_amount
integer
gateway_id
integer
gateway
string
Max Length : 128
RAZORPAY
express_checkout
boolean
error_message
string
Max Length : 255
error_code
string
Max Length : 255
currency
string
Max Length : 10
INR
created
string
2021-11-09T16:20:52Z
status_id
integer
status
string
Max Length : 255
CHARGED
refunds
Array Of Objects
object
object
unique_request_id
String
Max Length : 255
The unique request id that is passed during refund initiation. Do not pass any special characters.
status
String
Max Length : 255
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
Max Length : 255
The type of refund. Values can be STANDARD, INSTANT
refund_source
String
Max Length : 255
The name of gateway
ref
String
Max Length : 64
The refund id provided by the PG
initiated_by
String
Max Length : 100
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
Max Length : 255
The error message provided by the PG
error_code
String
Max Length : 255
The error code provided by the PG
created
String
The timestamp of refund creation
amount
integer
The refund amount passed in the request
metadata
Object
description
String
Refund note passed via metaData during refund initiation
return_url
string
Max Length : 255
rewards_breakup
String
refunded
boolean
product_id
string
Max Length : 64
payment_method_type
string
Max Length : 20
payment_method
string
Max Length : 20
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
txn_id
string
Max Length : 255
merchant_success-JP1636474794-1
rrn
string
Max Length : 64
156555
resp_message
string
Max Length : 512
SUCCESS
resp_code
string
Max Length : 64
SUCCESS
epg_txn_id
string
Max Length : 64
pay_IJZKtTpkiYWE24
created
string
2021-11-09T16:21:11Z
auth_id_code
string
156555
order_id
string
Max Length : 21
JP1636474794
offers
array
metadata
object
RAZORPAY:gateway_reference_id
string
testmid
merchant_id
string
Max Length : 255
merchant_success
id
string
ordeh_57dfd768bb7d4896bc0c3f30bc9ad77
gateway_reference_id
string
Max Length : 255
testmid
gateway_id
integer
effective_amount
integer
date_created
string
2021-11-09T16:19:55Z
customer_phone
string
Max Length : 300
9999999999
customer_id
string
Max Length : 300
testcardenc1
customer_email
string
Max Length : 300
test@gmail.com
currency
string
Max Length : 255
INR
card
object
using_token
boolean
using_saved_card
boolean
saved_to_locker
boolean
name_on_card
string
Max Length : 256
last_four_digits
string
expiry_year
string
2024
expiry_month
string
12
card_type
string
Max Length : 64
CREDIT
card_reference
string
Max Length : 256
17a2ec4f27c918ttvbc58c9ae74090e
card_issuer
string
Max Length : 256
JP Morgan
card_isin
string
Max Length : 256
411111
card_fingerprint
string
Max Length : 256
32qqi3svf5t5t37fq7ura2rgqqb
card_brand
string
VISA
bank_pg
null
bank_error_message
string
Max Length : 255
bank_error_code
string
Max Length : 255
auth_type
string
Max Length : 30
THREE_DS
amount_refunded
integer
amount
integer
maximum_eligible_refund_amount
Integer
Note
Amount that can be refunded without making the offer ineligible (for offer transactions). Calculated as the difference between the order amount and the Offer minimum order amount. For maximum allowed refund amount for a transaction , refer to the effective_amount field
400 : Invalid Input data
Response Body
Duplicate refund requests
JSON
error_code
REFUND_DUPLICATE_REQUEST
error_message (1)
String
A refund request is already being processed for this transaction id and amount combination
error_message (2)
String
A refund request is already being processed for this unique request id and order id combination
error_message (3)
String
A refund has already been processed for this order with this unique request id
COD order
String
error_code
CASH_PAYMENTS_REFUNDS_NOT_SUPPORTED
error_message
String
Refunds cannot be initiated for COD orders
Invalid amount passed
String
error_code
String
INVALID_AMOUNT
error_message
String
Amount is invalid
Invalid Order Id
String
error_code
String
INVALID_ORDERID
error_message
String
Not found
Older order
String
error_code
String
ORDER_TOO_OLD
error_message
String
Refunds cannot be initiated for orders older than 365 days
Pending/authorised order
String
error_code
String
CANNOT_PROCESS_AUTHORIZED_ORDER
error_message
String
Refunds cannot be processsed for a pending/authorised order
Order id based refund not allowed
String
error_code
String
SPLIT_PAYMENTS_ORDER_BASED_REFUND_NOT_SUPPORTED
error_message
String
Please use the txn_id-based Refund API
Refund amount exceeds the total refundable amount
String
error_code
*
String
Mandatory
INVALID_AMOUNT_REFUND
error_message
*
String
Mandatory
Refund amount exceeds the total refundable amount
Refund creation limit exceeded
String
error_code
String
REFUND_CREATE_EXCEEDED_THE_LIMIT
error_message
String
Refund creation limit exceeded
Refunds not supported by the gateway
String
error_code
String
REFUND_REJECTED
error_message
String
Refunds are not supported for the gateway with which the forward order/transaction was processed
Unsuccessful Order
String
error_code
String
UNSUCCESSFUL_ORDER_PROCESS_FAILURE
error_message
String
This refund cannot be processed as the forward order/transaction is not successful
Refund amount less than minimum amount
String
error_code
String
INVALID_AMOUNT
error_message
String
Refund cannot be initiated with amount lesser than Rs.1
Value not found
String
error_code
String
VALUE_NOT_FOUND
error_message
String
Success response ID
Transaction not found
String
error_code
String
SUCCESS_OR_PARTIAL_SUCCESS_TRANSACTION_NOT_FOUND
error_message
String
Invalid request
Invalid
String
error_code
String
INVALID
error_message
String
Bad request
401 : Authentication Failed
Response Body
status
String
error
error_code
String
access_denied