Body
Order Create
API is used to create a payout request with Juspay for account + IFSC, UPI, Tokenized Card (Juspay as token requestor), Wallet, and Beneficiary ID based payouts
Note
Merchants can use the Pause Payout/Weblabs
feature to handle scenarios such as low account balance or gateway downtime.This feature allows merchants to temporarily pause payout transactions for a specified duration, which can be defined as per their requirements.
Request
Response
API Endpoints
Sandbox Link
POST
https://sandbox.juspay.in/payout/merchant/v1/orders
Production Link
POST
https://api.juspay.in/payout/merchant/v1/orders
Authorization Header
Basic Auth
*
String
Mandatory
Consists of two parts.
Username: API Key obtained from Juspay dashboard
Password: Empty string
Example:- Basic MUQ2QUxxxxxxxxxxxxU5QTIxQzNFNTQwNkFDMEZCOg==
Headers
x-merchantid
string
Pass 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
orderId
*
string
Mandatory
Unique Reference for the order. This will be the ID for any subsequent communications.
Min length = 4, Max length = 64
orderId can contain alphanumeric values. It can also contain special characters _ , - and @
amount
*
Double
Mandatory
Total order amount. Amount can be passed up to 2 decimal points.
Minimum amount of Rs 1
Example: 1,2.5,3.80
customerId
*
string
Mandatory
Unique ID for the customer generated by the merchant.
Max length = 64
For CARD payouts, please provide same customer ID used while adding / tokenizing card.
For BENE ID payouts please use same customer ID passed while creating / validating beneficiary.
customerPhone
*
string
Mandatory
Customer mobile number - you may pass a dummy value in case this information is not available at your end
customerEmail
*
string
Mandatory
Customer email address - you may pass a dummy value in case this information is not available at your end
type
*
string
Mandatory
Pass FULFILL_ONLY for payout order creation
fulfillments
object
fulfilment related details
preferredMethodList
array
Optional
Note: This is an optional param and should be used only in some specific cases and routing requirements.Please do not pass this field unless there is an specific routing need.
This will define the list of methods to be used for fulfillments for instance - [“DUMMY_IMPS”]
preferredMethodList carries a higher priority than distribution logic set on Juspay dashboard.
amount
*
Double
Mandatory
Amount to be processed for the particular fulfillment. Sum of all the fulfilment amount should be equal to order amount,
Minimum amount of Rs 1
beneficiaryDetails
object
type
*
String
Mandatory
Pass “CARD” / “UPI_ID” / “ACCOUNT_IFSC” / "WALLET" / "BENE_ID" / “PAYOUT_LINK“ based on required method. CARD for card transfer on tokenized cards where Juspay is the token requester, UPI_ID for transfer to vpa, and ACCOUNT_IFSC for transfer to bank account, WALLET for transfer to Paytm Wallet, BENE_ID for transfer to beneficiary already created / validated with Juspay, PAYOUT_LINK for creating a payout link.
details
Object
name
String
Name of beneficiary
Required in case of NEFT / RTGS rails due to beneficiary name check done by beneficiary banks.
account
String
Account of beneficiary. Required for payout of type ACCOUNT_IFSC
ifsc
String
IFSC of beneficiary. Required for payout of type ACCOUNT_IFSC
cardReference
String
CardReference to the card details stored in Juspay Card Vault. Required for payout type CARD
bankCode
String
IIN of the card issuer - a list of bankCode & bankNames is provided. Required for payout type CARD. Please refer to Resources section for the list of bank codes
brand
String
Card brand - VISA / MASTERCARD / AMEX etc. Required for payout type CARD
Wallet brand supported - PAYTM. Required for payout type WALLET
cardType
String
CREDIT / DEBIT. Required for payout type CARD
vpa
String
UPI id of beneficiary. Required for payout type UPI_ID
walletIdentifier
String
Number with which user has registered Paytm Wallet.
id
String
Beneficiary ID passed in the request while creating / validating beneficiary. Required for payout type BENE_ID
mobileNo
String
Required for payout type UPI_ID / PAYOUT_LINK.
UPI_ID : Mobile number on which payout should be attempted. Juspay will fetch the primary vpa linked to the mobile number and attempt UPI Payout.
PAYOUT_LINK : Payout link will be sent to the provided mobile number.
payeeAdditionalDetails
*
JSON-Object
Mandatory
These fields are required for merchants using YESNODAL_FTx gateway.
documents
*
Array of JSON objects
mandatory
docId
String
Example: "OACPS2488J"
docType
String
Example:- Possible values: "PAN"
payeeType
*
String
mandatory
Example:- Ex: PARTNER | PUBLTD | PVTLTD | PROP | SOC | TRUST | GOVT
businessModel
*
String
Mandatory
Example:- Ex: Ecommerce
udf1-5
String
Fulfillment level user defined fields. These fields can be used for analytics and routing of fulfillment of the order
additionalInfo
Object
remark
String
The parameter will be passed as narration to the downstream gateways (if supported)
scheduleTime
String
Time at which fulfillment should be attempted by Juspay. This is UTC format. Example: “2025-02-05T11:53:40Z”
attemptThreshold
Integer
Optional
This is the time after which juspay will not initiate attempt with underlying gateway.
Merchants can use this field to set custom attempt threshold for an order. This is in minutes.
Attempt threshold can be set on the dashboard as well.
isRetriable
Boolean
Merchants can pass true / false depending upon whether order should be retried on technical failure. Applicable only for PLAIN_CARD
webhookDetails
Object
Optional
Merchants can provide dynamic webhook details for the order if required. This is an optional field.
Use this field only if you want to receive webhooks on seperate URLs for orders.
If you want to use only one URL for webhooks, please set webhook URL on payouts Dashboard.
url
String
https URL corresponding to webhook endpoint to which webhook events should be triggered for this order
username
String
Input values of username and password in corresponding fields. Base 64 encoded value of username:password will be sent as Authorization for webhook
customHeader
String
Optional
Merchant can pass custom headers in below mentioned format:
{ "<name of field1>" : "<value1>", "<name of field 2>" : "<value 2>" }
Example:
{ "X-MerchantId" : "testMerchant", "X-App" : "testApp" }
password
String
Input values of password in corresponding fields. Base 64 encoded value of username:password will be sent as Authorization for webhook
originalTxnRef
String
Transaction Reference pointing to original transaction for refund payout.This field is applicable only for Card refunds on Visa Direct / Mastercard Send rails
payoutLinkClientId
*
String
Mandatory
Unique Identifier for each client. Mandatory for creating Payout link orders.
udf1-5
string
Order level user defined field. Field can be used for analytics.
200 : Success
Response Body
200 : Payout Response
Object
type
String
Payout type passed in order create request
Example:- FULFILL_ONLY
status
String
Relays the current status of order created at Juspay end
Example:- READY_FOR_FULFILLMENT
orderid
String
orderId passed during order creation
Example:- 1703593449
fullfilments
Array
amount
String
Amount passed in the fulfillment block
Example:- 1.0
updatedBy
String
Medium via which payout status was updated. Will be DEFAULT in response of create order
Example:- DEFAULT
updatedAt
String
Timestamp at which fulfillment payload was last updated at Juspay end
Example:- 2023-12-23T16:54:27Z
udf1-5
String
Fulfillment level user defined fields passed in order creation request
status
String
Relays the current status of fulfillment created at Juspay end
Example:- CREATED
preferredMethodList
Array of Strings
Array passed during order create for preferredMethodList
Example:- DUMMY_IMPS
id
String
Fulfillment ID created by Juspay for fulfillment payload received in order create request
Example:- 25cbcf3454a445789309dc0b54e681-f1
statusUpdatedAt
String
Timestamp at which status of fulfillment was updated at Juspay end
Example:- 2023-12-26T12:24:08Z
beneficiaryDetails
Object
Beneficiary details provided in order create by merchant
type
String
Payout type initiated by merchant
Example:- ACCOUNT_IFSC | UPI_ID | PAYOUT_LINK | BENE_ID | WALLET
details
String
payoutLinks
String
Payout links to be forwarded to the customer
web
String
Short length payout_link Url
webLong
String
Long length payout_link Url
name
String
name of the beneficiary passed in order create
link_expiry
String
Expiry time of the payout link
payout_process_payload
JSON
Optional
Note: This field is optional and should not be used to drive any internal logic.
mobileNo
String
mobile number passed in order create
payoutLink
String
Payout link to be forwarded to the customer
additionalInfo
Object
Additional Information sent by merchant in create order request
payoutLinkClientId
String
PaymentPage corresponding client-id
webhookDetails
String
webhook endpoint url sent by merchant in order create request
url
String
url to which the webhook notifications of this particular order should be sent
username
String
password
String
customerId
String
Customer ID passed during order creation
Example:- cth_59Yibs1JauYP6WJP
amount
String
Amount passed for the order
Example:- 1.0
udf1-5
String
Order level udfs passed in order create request
400 : Invalid Input data
Response Body
error
Boolean
Boolean reflecting error in request of create order API
Example:- true
errorCode
String
Error code provided by Juspay
Example:- E01
errorMessage
String
Error message provided by Juspay. Share this message with Juspay POC for debugging
Example:- Amount0.0 cannot be less than 1.0Amount0.0 cannot be less than 1.0
userMessage
String
Error message that will be shown on dashboard / analytics
401 : Authentication Failed
Response Body
error
String
Boolean reflecting error in request of create order API
Example:- true
errorCode
String
Error code provided by Juspay
Example:- E02
errorMessage
String
Error message provided by Juspay. Share this message with Juspay POC for debugging
Example:- Invalid API key passed in request.
userMessage
*
String
Mandatory
Error message that will be shown on dashboard / analytics
Example:- Invalid API Key
Have questions?
- Need help? Contact support
- LLM? Read llms.txt