Body
Order Create
API is used to create a payout request with Juspay for account , Tokenized Card (Juspay as token requestor), Wallet, and Beneficiary ID based payouts
Request
Response
API Endpoints
Sandbox Link
POST
https://api.sandbox.juspay.io/payout/merchant/v1/orders
Production Link
POST
https://api.juspay.io/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
Content-Type
String
application/json
Parameters
orderId
*
string
Mandatory
Min Length : 4
Max Length : 64
Unique Reference for the order. This will be the ID for any subsequent communications.
orderId can contain alphanumeric values. It can also contain special characters _ , - and @
amount
*
Double
Mandatory
Total order amount
customerId
*
string
Mandatory
Max Length : 64
Unique ID for the customer generated by the merchant.
For BENE ID payouts please use same customer ID passed while creating / validating beneficiary.
customerPhone
*
string
Mandatory
Customer mobile number - If the actual number is unavailable, you may use a placeholder or dummy value. The number should contain only the digits without any country code or special characters.
For instance, a valid entry for a Brazilian phone number would be: 4112345678.
customerEmail
*
string
Mandatory
Customer email address - you may pass a dummy value in case this information is not available at your end
For example, example@mail.com, "example" is the email prefix, and "mail.com" is the email domain.
type
*
string
Mandatory
Pass FULFILL_ONLY for payout order creation
fulfillments
*
object
Required
fulfilment related details
preferredMethodList
array
This will define the list of methods to be used for fulfillments for instance -[“EBANX_WALLET”, PAYPAL_WALLET”, “PAGSEGURO_WALLET”, ”TAZAPAY_BT”]
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
If you have gatewayReferenceId then you have pass in array like “EBANX_WALLET.gatewayReferenceId”
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
Required
type
*
String
Mandatory
Pass “WALLET”, “BANK_TRANSFER“ based on required method
WALLET for transfer to Mercadopago, PAGBANK and Paypal Wallet Id
BANK_TRANSFER is used when you have TAXID (CPF), BANK TRANSFER, and PIX TRANSFER .
details
*
Object
Required
walletIdentifier
String
Value related to beneficiary’s brand you are selecting.
Required in case of Wallet only.
Example :-
Brand WalletIdentifier
MERCADOPAGO your@email.com
brand
String
Brand name of the wallet
Required in case of Wallet only.
Values :- MERCADOPAGO | PAGBANK | PAYPAL | VENMO
MERCADOPAGO, used for Ebanx
PAYPAL used for Paypal
PAGBANK used for Pagseguro
VENMO used for Venmo
payeeAdditionalDetails
Object
documents
*
Array
Required
An array containing the object of beneficiary’s national identification Number along with its type.
docId (string): The beneficiary’s national identification number.
docType (string): The type of the national identification number.
Values: CPF | CNPJ
CPF is 11 digit number formatted as
Format for CPF : XXX.XXX.XXX-XX
CNPJ is 14 digit number formatted as
Format for CNPJ: XX.XXX.XXX/XXX-XX
example :-[ { "docId" : "853.513.468-93", "docType" : "CPF" } ]
[ { "docId" : "00.623.904/0001-73", "docType" : "CNPJ" } ]
payeeType
String
Pass the type of payee
Values: business or individual
bankCountryCode
String
Provide bank country code.
Mandatory in case of BANK_TRANSFER
firstName
String
Provide your payee First name
Mandatory for PAYAMIGOS
lastName
String
Provide your payee Last name
Mandatory for PAYAMIGOS
payoutMode
*
String
Tag
Required
Rail to be used for the domestic or international payout
Current Available Mode : PIX
Required in case of BANK_TRANSFER
transferType
*
String
Required
Denotes the type of the transfer - whether local or international
Values : LOCAL , INTERNATIONAL
Local denotes the transfer is a domestic transaction while international denotes the transfer is a cross border transaction
Required in BANK_TRANSFER
payeeAccountIdentifier
String
Provide the account identifier of the payee’s bank account.
Required in case of BANK TRANSFER
In case of PIX all the valid PIX values can be passed in this field
walletIdentifierType
String
Brand Type name of the wallet
Required in case of Wallet only.
Values :- PAYPAL_ID | EMAIL | PHONE | VENMO_ID
PAYPAL_ID | EMAIL | PHONE —> For Paypal
EMAIL | PHONE | VENMO_ID —> For Venmo
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
attemptThreshold
Integer
Merchants can use this field to set custom attempt threshold for an order
transactionType
String
Value :- B2B or B2C
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
payoutMethodType
String
This is specific to PayPal.
To create a beneficiary of type WALLET for PayPal, you can use either the beneficiary creation API or the LinkWallet API. While you can choose EMAIL or PAYPAL_ID as the primary payout method, payouts can still be processed with either option by updating the value in the field as needed.
fulfillmentCurrency
*
String
Mandatory
values are ISO 4217 Standard.
Example :- ARS, BRL, CLP, COP, MXN, BOB, CRC, PYG, PEN, UYU, DOP, KES, ZAR, MAD, EGP, INR, IDR, NGN, USD
Max length = 3
sourceCurrency
String
values are ISO 4217 Standard.
Example :- ARS, BRL, CLP, COP, MXN, BOB, CRC, PYG, PEN, UYU, DOP, KES, ZAR, MAD, EGP, INR, IDR, NGN, USD
Max length = 3
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:- BENE_ID | WALLET | BANK_TRANSFER
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