Body
Refund API
Create a refund for an Order.
Refunds can be initiated directly to the amount debited source or other payment modes with payouts. This API supports both refunds and Payout for Juspay orders.
Refunds/Payouts can be initiated only for transactions that are CHARGED. The response of refund/payout initiation is similar to that of order status API Response with the addition of refunds block.
Note
Either txn_id or order_id has to be passed in request.
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
Required
application/x-www-form-urlencoded
x-merchantid
string
Recommended
Unique identifier for the merchant. This is the Merchant ID provided by Juspay. The value is case sensitive.
Note
Passing this value will help us route efficiently at network level.
Example:- x-merchantid: testaccount
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
Required
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
txn_id
String
Conditional
Pass txn_id if you want to perform a refund based on txn_id. Not needed if passing order id.
Its optional if txn_id is passed
order_id
String
Conditional
An identifier for the order for which the refund has to be processed. Not needed if order_id is used.
Its optional if txn_id is passed
refund_reason
String
Optional
Reason for the refund. Default will be “CANCELLATION”
Possible values:
GOODWILL
WAIVER
PRODUCT_OR_SERVICE_NOT_DELIVERED
UNSATISFACTORY_PRODUCT_OR_SERVICE
CANCELLATION
PARTIAL_CANCELLATION
TECHNICAL_ISSUES
OFFER_OR_SUBSCRIPTION_ISSUES
DUPLICATE_PAYMENT
DELAYED_SUCCESS
refund_type
String
Conditional
Its Required for payout case and Optional for back to source cases
Identifier to determine the refund type, taking the value as “PAYOUT”
beneficiary_details
*
String
Mandatory
Its Required for payout case and Optional for back to source cases
Beneficiary details on which payout will be done. Not needed if you are sending beneficiary_id
details
*
String
Mandatory
Beneficiary Details which includes first_name, last_name, account, bank_code, address
Format:
Example:- BeneficiaryDetails = {"account" : String, "first_name" : String, "last_name" : String, "bank_code": String, "address": {"city" : String, "country_code" : String, "postcode" : String, "street_address" : String, "state" : String } }
transfer_type
*
String
Mandatory
Type of payout
Example:- Possible value: INTERNATIONAL,LOCAL
payout_mode
*
String
Mandatory
Example:- Possible value: IBAN,FAST
type
*
String
Mandatory
type of payout mode
Example:- Possible value: BANK_TRANSFER
preferred_gateway
String
Conditional
Specify your preferred Payout gateway details for this refund.
gateway
*
String
Mandatory
Specify the Payout gateway to process payouts
Example:- Sample Value: 2C2P, AIRWALLEX
gateway_reference_id
String
Optional
Pass the gateway_reference_id if the payout gateway configured with gateway_reference_id on juspay dashboard.
Example:- Sample Value: Bus, Train
200 : Success
Response Body
refunds
array of Objects
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,PAYOUT
refund_source
String
The name of gateway
ref
String
The refund id provided by the PG
initiated_by
String
The source of initiation.
epg_txn_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
currency
String
The currency for the refund processed amount
txn_id
String
Transaction ID of the refund processed
payout_gateway_details
String
Payout processed gateway details
gateway
String
Specifies the payout processed gateway
gateway_reference_id
String
Specifies the gateway reference id of the payout processed gateway
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
Have questions?
- Need help? Contact support
- LLM? Read llms.txt