Body
Order Create [Encrypted]
This API is used to create a payout request with Juspay for plain card and tokenized card where Juspay is not the token requester
Warning
Request data has to be sent in encrypted format. Please follow the steps mentioned here
The below params have to be stringified before encryption:
Request
Response
API Endpoints
Sandbox Link
POST
https://sandbox.juspay.in/payout/merchant/v1.1/orders
Production Link
POST
https://api.juspay.in/payout/merchant/v1.1/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
Please pass merchant-id given for your merchant
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
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" / “PLAIN_CARD” / “PAYOUT_LINK“ based on required method. CARD for card transfer of tokenized cards with Juspay as 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. PLAIN_CARD for direct card based payout / token based payouts where Juspay will not be the token requester, PAYOUT_LINK for generating 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. One of the below two fields is required for payout type CARD: tempToken or cardReference .
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
Conditional
Card brand - VISA / MASTERCARD / AMEX etc. Required for payout type CARD
Wallet brand - PAYTM. Required for payout type WALLET
cardType
String
Conditional
CREDIT / DEBIT. Required for payout type CARD
vpa
String
Conditional
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.
cardNumber
String
Conditional
Value of actual card number to be passed. Required for payout type PLAIN_CARD.
If payout type is PLAIN_CARD, one of the below fields are required:
cardNumber/cardToken.
cardToken
String
Conditional
Value of actual card token to be passed. Required for payout type PLAIN_CARD.
Value of actual card number to be passed. Required for payout type PLAIN_CARD.
If payout type is PLAIN_CARD, one of the below fields are required:
cardNumber/cardToken.
cardExpiry
String
Expiry details for user’s card. This will be used for creation of alt ID for PLAIN_CARD transactions where merchant is passing non-tokenized card details
month
String
Expiry month for users card (MM)
year
String
Expiry year for users card (YYYY)
tempToken
String
Temporary Token generated against card details. One of the below two fields is required for payout type CARD: tempToken or cardReference .
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
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 payout type 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 / 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 .
This field is mandatory if you want to initiate a refund transaction on Mastersend rail.
Please pass the value in this field as mentioned below:
1. For Mastercard Refund Transactions:
It should be a 19 characters string as mentioned below:
If Purchase transaction originated on the Dual Message System:
[POS 1] Origination system for purchase transaction: ‘D’ for Dual Message.
[POS 2-5] DE 15 (Date, Settlement). Example: 1209
[POS 6-8] DE 63, subfield 1 (Financial Network Code). Example: MCW
[POS 9 -14] DE 63, subfield 2 (BankNet Reference Number). Example: WTDPHE
[POS 15-19] 00000
If Purchase transaction originated on the Single Message System:
[POS 1]: Origination system for purchase transaction: ‘S’ for Single Message
[POS 2-5] DE 15 (Date, Settlement). Example: 1209
[POS 6-14] DE 63, subfield 3 (Network Reference Number)
[POS 15-19] 00000
2. For Visa Refund Transactions:
Please pass Transaction Identifier of original purchase transaction. Example : 394030104165147
senderDetails
Object
This will consist sender details. This is Mandatory fields for Credit Card Bill Payment Transactions via MASTERSEND Rail
type
String
Indicates the type of the payment done
Allowed Values : PAY_CARD, NETBANKING, UPI
details
Object
name
String
Name of the sender
account
String
Please populate this field with the accountNumber of the remitter if the paymentType is NETBANKING
pan
String
Please populate this with the card number or Token if the Type is PAY_CARD
expiry
JSON Object
Optional
Expiry details for sender’s card. This is an optional field
month
String
Expiry month for sender’s card (MM)
year
String
Expiry year for sender’s card (YYYY)
cardSecurityCode
String
Optional
Please populate this with the card security code if the paymentType is PAY_CARD
transactionReference
String
Please populate this filed with the unique transaction reference number if the paymentType is UPI
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_VISADIRECT
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 | PLAIN_CARD | 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