Body
Create Order API
This is a server-to-server API that creates an order in the Juspay system and retrieves the client_auth_token.
Amount and order id are the mandatory fields, the contact details like email, phone number, customer id's are conditional and depends on the underlying payment gateway/ aggregator used.
'UDF' is used to pass any additional information that is required to be stored at Juspay for any analysis or other operations. In some cases, these UDFs are passed to the downstream gateways as well.
Juspay supports 10 UDFs (UDF1 to UDF10). The values passed in UDFs are reflected back in the order status response and in webhooks back to the merchant. If there are any special characters that need to be passed in UDF values, please use UDF 6 to 10 for passing the same. UDF 1 to 5 can be used to pass values which do not have any special characters.
Note: Auth api key should be Base64 encoded.
Mandatory Fields:
Amount and Order ID are required.
Contact details (e.g., email, phone number) are conditional, depending on the payment gateway used.
UDF (User-Defined Fields):
Juspay supports 10 UDFs (UDF1 to UDF10) for storing custom information.
Special characters can be passed using UDF6 to UDF10.
UDF values are included in order status responses and webhooks.
Metadata:
Use to send custom parameters to payment aggregators, beyond the default.
Payment Links:
The response includes web, mobile, and iFrame payment links. If you wish to use your own branding, then you can embed the iframe link into your page.
These can be shared directly with customers but expire based on order validity (modifiable via the dashboard
).
Note: API keys must be Base64-encoded for authentication.
Note
Ensure your system never sends the same order_id twice.
Explicitly set currency in the ISO(4217) 3-digit format.
Send amount as a String ("10.00") to prevent floating point issues.
Always pass options.get_client_auth_token: "true" if you are using the Android/iOS SDK, as this generates the token needed to initialize the UI.
If the customer is created, pass the customer_id in the order.
Request
Response
API Endpoints
Sandbox Link
POST
https://api.sandbox.juspay.io/orders
Production Link
POST
https://api.juspay.io/orders
Authorization Header
Basic Auth
*
Base64 Encoded username:password
required
Consists of two parts.
Username: API Key obtained from Juspay dashboard
Password: Empty string
Example:-
Basic MUQ2QUxxxxxxxxxxxxU5QTIxQzNFNTQwNkFDMEZCOg==
Headers
x-merchantid
*
string
required
Merchant ID provided by Juspay
Example:-
merchant-id
version
string
Pass the date in YYYY-MM-DD format
Example:-
2023-01-01
Content-Type
String
application/x-www-form-urlencoded
Request Schema: application/json
Basic Parameters
order_id
*
string
required
Unique Identifier for the order. Should be Alphanumeric with character length less than 21.
Example:-
order-id-9876580
amount
*
Double
required
Amount that the customer has to pay. Will accept stringified double or integer values with upto two decimal places. For example, "100.15" and "100" are valid input but "100.1532" is not valid.
Example:-
1.00
options.get_client_auth_token
string
Client side authenticaion token required for Hyper SDK calls
Example:- Value : true
customer_id
string
It is the ID with which merchant refers to a customer object. This id is used to access the stored payment methods, allow EMI transactions and setup subscriptions.
In case of guest login it should be an empty string.
Example:-
customer-id-007
customer_email
string
Highly recommended to provide whenever available, as many payment gateways rely on it for risk assessment, authentication flows, and customer communication.
Example:-
test@gmail.com
customer_phone
string
Mobile number or fixed line number of the customer. If the backend gateway requires it, then you must send this value.
Example:-
99999999
currency
string
ISO string of the currency. Use BRL for Brazilian Real. Among other accepted values are EUR, USD, GBP, SGD, IDR etc. Default value: INR
description
string
Short description for the order. We send this information to the backend gateways whenever there is a provision for this.
return_url
string
A fully qualified URL which the customer will be redirected after payment completion. It is also required to provide the control back to SDK after the completion of transaction. This URL shouldn't contain any query parameters or Ip address. This URL takes higher precedence over the common return URL configured in your account settings.
Example:-
https://shop.merchant.com
product_id
string
An identifier for the product. Fits well for impulse purchase usecases.
Example:-
John
gateway_id
string
Specify your preferred gateway for this order.
Example:-
Wick
billing_address_first_name
string
First name in the billing address
billing_address_last_name
string
Last name in the billing address
billing_address_line1
string
Line1 in the billing address
billing_address_line2
string
Line2 in the billing address
billing_address_line3
string
Line3 in the billing address
billing_address_city
string
Billing address city
billing_address_state
string
Billing address state
billing_address_country
string
Billing address country
billing_address_postal_code
string
Billing address postal code or zip code
billing_address_phone
string
Mobile or phone number in the billing address
billing_address_country_code_iso
string
ISO Country code Default value: IND
shipping_address_first_name
string
First name in the shipping address
shipping_address_last_name
string
Last name in the shipping address
shipping_address_line1
string
Line1 in the shipping address
shipping_address_line2
string
Line2 in the shipping address
shipping_address_line3
string
Line3 in the shipping address
shipping_address_city
string
Shipping address city
shipping_address_state
string
Shipping address state
shipping_address_country
string
Shipping address country
shipping_address_postal_code
string
Shipping address postal code or zip code
shipping_address_phone
string
Mobile or phone number in the shipping address
shipping_address_country_code_iso
string
ISO Country code Default value: IND
Metadata Object
metadata.JUSPAY:gateway_reference_id
string
Use this parameter only when you have use case of gateway reference ID. For detailed information check here.
subvention_amount
String
The amount for which the EMI interest should not be calculated.
webhook_url
String
Merchant can pass dynamic webhook URL in this field. The webhook authentication would be same as the one configured on the dashboard. Ex: metadata.webhook_url=https://merchant.juspay/response
metadata.txns.auto_capture
Bool
The default is set to true. Pass false to for pre-auth orders.
metadata.CHECKOUT:force_3DS_Challenge
Boolean
Optional
Set it to true if you need to mandate the 3DS challenge for a new card.
metadata.expiryInMins
*
String
Mandatory
Expiry Time in Minutes post which the payment link will expire
User Defined Parameters (UDF)
udf1 , udf2 , udf3 , udf4, udf5
string (Upto 255 characters)
No special characters supported
User Defined Parameter (UDF)
This field can be used to send any user defined parameters
The UDF parameters for orders can be seen in the JUSPAY dashboard under each order
Example:-
user5349
udf6 , udf7 , udf8 , udf9 , udf10
string (Upto 255 characters)
Special characters supported
User Defined Parameter (UDF)
This field can be used to send any user defined parameters
The UDF parameters for orders can be seen in the JUSPAY dashboard under each order
Example:-
user_5349
200 : Success
Response Body
status
*
string
Required
Status of order
Example:- NEW
status_id
*
integer
Required
Status ID is a numeric id corresponding to the status value.
id
*
Integer
Required
Unique ID generated by Juspay for the given order
order_id
*
string
Required
Order Id passed during order creation
payment_links
*
JSON
Required
Https link using which user can open payment page and perform transaction against the order created
web
string
mobile
string
iframe
string
juspay
JSON
client_auth_token_expiry
string
client_auth_token
string
400 : Invalid Input data
Response Body
status
string
Bad Request
error_code
string
Details of keys missing
Example:-
Mandatory fields are missing
error_message
string
Further Details of keys missing
Have questions?
- Need help? Contact support
- LLM? Read llms.txt