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
Request
Response
API Endpoints
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
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
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
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. This is an optional param and should be used only in case of unique routing requirements
amount
*
Double
Mandatory
Amount to be processed for the particular fulfillment. Sum of all the fulfilment amount should be equal to order amount,
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
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
brand
String
Card brand - VISA / MASTERCARD / AMEX etc. Required for payout type CARD
Wallet brand - 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.
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)
useThisAsTR
String
Merchants can use this field to pass custom transaction reference for the attempt
scheduleTime
String
Time at which fulfillment should be attempted by Juspay
attemptThreshold
Integer
Merchants can use this field to set custom attempt threshold for an order
isRetriable
Boolean
Merchants can pass true / false depending upon whether order should be retried on technical failure. Applicable only for PLAIN_CARD
webhookDetails
Object
Merchants can provide dynamic webhook URL for the order if required
url
String
https URL corresponding to webhook endpoint to which webhook events should be triggered for this order
username / password
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
Merchant can pass custom header if required for webhook to be triggered
originalTxnRef
String
Transaction Reference pointing to original transaction for refund payout. Applicable only for Visa Direct / Mastercard Send rails
senderName
String
Name of sender paying the credit card bill. Applicable only for Visa Direct / Mastercard Send rails for Credit Card Bill Payments
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
Fulfilment 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 | CARD | BENE_ID | WALLET
additionalInfo
Object
Additional Information sent by merchant in create order request
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