JavaScript is disabled. Some features may not work. You can also read the static version: View text version

Create Order API

The Create Order API is a server-to-server API that takes order parameters as an input and creates an order in the Juspay system and fetches the corresponding client_auth_token, which is required for further operations.

The API key used for authentication must be Base64 encoded

Key Parameters

Mandatory
- amount – The payment amount for the order.
- order_id – A unique identifier for the order, generated by you (the merchant).
Conditional
- Customer details such as email, phone_number, and customer_id are optional. However, their usage depends on the payment gateway or aggregator configured.

UDF (User Defined Fields)

UDFs let you send additional information that is required to be stored at Juspay for any analytics, reporting, or operational purposes. In some cases, these UDFs are passed to the downstream gateways as well.
Juspay supports 10 UDFs: udf1 through udf10.
Behavior:
- The values passed in UDFs are returned back in the order status response and also included in webhooks sent to the merchant.
Special Characters:
- Use udf1 to udf5 for values without special characters.
- Use udf6 to udf10 if the values contain special characters.

Metadata

metadata is used to send custom parameters to the payment aggregators. aggregators.
These parameters are sent in addition to Juspay’s default parameters.
Use this field if you need to pass aggregator-specific values that are not covered by standard fields.

Scroll inside to view more

Payment Gateways	Fields
CCAVENUE_V2	metadata.CCAVENUE_V2:promo_code
BILLDESK	metadata.BILLDESK:AdditionalInfo3
BILLDESK	metadata.BILLDESK:AdditionalInfo4
FREECHARGE	metadata.FREECHARGE:campaignCode
GOCASHFREE	metadata.CASHFREE:metadata1
HSBC_UPI	metadata.HSBC_UPI:addInfo
MIGS	metadata.MIGS:vpc_AddendumData
MIGS	metadata.MIGS:vpc_OrderInfo
OLAMONEY	metadata.OLAMONEY:couponCode
PAYTM	metadata.PAYTM:PROMO_CAMP_ID
PAYTM	metadata.PAYTM:CUST_ID
PAYTM	metadata.PAYTM:MERC_UNQ_REF
PAYTM_V2	metadata.PAYTM_V2:MERC_UNQ_REF
PAYTM_V2	metadata.PAYTM_V2:CUST_ID
TATAPAY	metadata.TATAPAY: merchantTxnMetadata
PAYU	metadata.PAYU:offer_key
PAYU	metadata.PAYU:offer_auto_apply
PAYU	metadata.PAYU:udf1
PAYU	metadata.PAYU:udf2
PAYU	metadata.PAYU:udf3
PAYU	metadata.PAYU:udf4
PAYU	metadata.PAYU:udf5
PHONEPE	metadata.PHONEPE:merchantContext
RAZORPAY	metadata.RAZORPAY:notes[cust_id]
RAZORPAY	metadata.RAZORPAY:notes[cust_name]
RAZORPAY	metadata.RAZORPAY:offer_id
RAZORPAY	metadata.razorpay:PNR
RAZORPAY	metadata.razorpay:PaymentID
RAZORPAY	metadata.razorpay:lob
RAZORPAY	metadata.RAZORPAY:notes Ex: metadata.RAZORPAY:notes={"key1":"value1","key2":"value2","key3":"value3"}
Subvention Amount	metadata.subvention_amount
TPSL	metadata.TPSL:shoppingCartDetails
TPSL	metadata.TPSL:accountNo
ZAAKPAY	metadata.ZAAKPAY:productDescription
ZAAKPAY	metadata.ZAAKPAY:product1Description
PAYPAL	metadata.PAYPAL:landing_page
PAYPAL	metadata.PAYPAL:phone_number
PAYPAL	metadata.PAYPAL:country_code
PAYPAL	metadata.PAYPAL:first_name
PAYPAL	metadata.PAYPAL:last_name
PAYPAL	metadata.PAYPAL:experience_id
PAYPAL	metadata.PAYPAL:brand_name
PAYPAL	metadata.PAYPAL:additional_data
PAYPAL - For Link and Pay	metadata.PAYPAL:lnp_product_name
PAYPAL - For Link and Pay	metadata.PAYPAL:lnp_product_code
PAYPAL - For Link and Pay	metadata.PAYPAL:lnp_charge_pattern
PAYPAL - For Link and Pay	metadata.PAYPAL:direct_wallet_version
PAYPAL - For Link and Pay	metadata.PAYPAL:purchase_category
AMAZONPAY	metadata.AMAZONPAY:sellerNote

Subvention Amount

It is the interest component of a "No-Cost EMI" offer that is covered by a merchant or manufacturer. Therefore this amount is not considered for EMI calculation.

For example : If the Order amount is 100 and the subvention amount is 10, interest will be calculated on 100-10 that comes to 90. subvention_amount can be any value between 0 and the total order amount.

If subvention_amount = order_amount, the EMI is a no-cost EMI (the customer pays only the principal).
This mechanism of running offers or subvention amount is the responsibility of merchants in collaboration with PG/Banks.

Payment Links

When you create an order, the API response includes payment links for web, mobile, and iFrame.

Web and mobile links can be shared directly with customers, for example through email or SMS.
The iFrame link can be embedded in your own site or app if you want to maintain your brand’s checkout experience.

Payment links are valid only until the order expires. You can configure the order expiry in the [Juspay Dashboard]. After expiry, all associated links stop working.

Request

Response

API Endpoints

Sandbox Link

POST

https://sandbox.juspay.in/orders

Production Link

POST

https://api.juspay.in/orders

                      Basic Auth
                      *
                      

Base64 Encoded username:password

required

Consists of two parts.

Username: API Key obtained from Juspay dashboard
Password: Empty string

Example:-
Basic MUQ2QUxxxxxxxxxxxxU5QTIxQzNFNTQwNkFDMEZCOg==

                      x-merchantid
                      *
                      

string

required

Merchant ID provided by Juspay

Example:-
merchant-id

                      Content-Type
                      
                      

String

application/x-www-form-urlencoded

                      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.

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

Body

Request Schema: application/json

                      order_id
                      *
                      

string

required

Unique Identifier for the order. Should be Alphanumeric with character length less than 21.

Example:-
orderid9876580

                      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

Required

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

Email address of the customer. If the backend gateway requires it, then you must send this value.

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:-
9999999912

                      currency
                      
                      

string

ISO string of the currency. Use INR for Indian Rupee. Among other accepted values are EUR, USD, GBP. 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
                      
                      

Number

Tag

Specify your preferred gateway for this order. Refer to mapping here.

Example:-
15

                      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

                      order_type
                      
                      

String

Conditional

TPV_PAYMENT. Applicable only for TPV Orders.

                      metadata.JUSPAY:gateway_reference_id
                      
                      

string

Optional

Use this parameter only when you have use case of gateway reference ID. For detailed information check here.

                      metadata.subvention_amount
                      
                      

String

Optional

The amount for which the EMI interest should not be calculated. Ex: metadata.subvention_amount=90

                      metadata.webhook_url
                      
                      

String

Optional

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.bank_account_details
                      
                      

Array

Conditional

Applicable for TPV Orders.

Either bank_account_number or bank_account_id is mandatory

                      bank_account_number
                      
                      

String

Conditional

Customer Bank account

                      bank_ifsc
                      
                      

String

Optional

IFSC code of bank

                      juspay_bank_code
                      
                      

String

Optional

juspay bank code given in eligibility API. e.g. JP_HDFC

                      bank_beneficiary_name
                      
                      

String

Optional

Name of account holder

                      bank_account_id
                      
                      

String

Conditional

bank account id provided by Juspay while storing bank account details

                      bank_account_type
                      
                      

String

Conditional

Account type of the Customer Account

Example:- CURRENT or SAVINGS

                      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

                      mutual_fund_details
                      
                      

List

Optional

Contains the details of Mutual Fund.

                      memberId
                      *
                      

String

Mandatory

Member Id with ICCL or ARN_RIA with RTA.

                      userId
                      *
                      

String

Mandatory

Client Id with ICCL or USER_CODE with RTA.

                      mfPartner
                      *
                      

String

Mandatory

NSE/BSE/KFIN/CAMS.

                      orderNumber
                      *
                      

String

Mandatory

Unique order number of each MF. Oder Number in ICCL or APPL_NO in RTA.

                      amount
                      *
                      

String

Mandatory

Individual MF amount within the array of MF being purchased.

                      investmentType
                      *
                      

String

Mandatory

LUMPSU/ SIP

                      folioNumber
                      
                      

String

Optional

Folio Number of the MF, used for RTA reporting. Mandatory for RTA reporting.

                      panNumber
                      
                      

String

Optional

PAN Number of the user, used for RTA reporting. Mandatory for RTA reporting.

                      amcCode
                      
                      

String

Optional

AMC Code of the MF, used for RTA reporting. Mandatory for RTA reporting.

                      schemeCode
                      
                      

String

Optional

Scheme Code of the MF, used for RTA reporting. Mandatory for RTA reporting.

                      ihNumber
                      
                      

String

Conditional

In-house Number of the SIP (Mandatory for K-Fin RTA)

                      cross_border_details
                      
                      

String

Optional

If the requirement is to send details across cross border, then these details need to be sent, it can change based on PG to PG , so please confirm with them , what is mandatory for them for this requirement.

                      invoice_number
                      *
                      

String

Mandatory

Invoice number required for transaction.

                      goods_description
                      
                      

String

Optional

Description of goods

Example:- Tubelight

                      shipping_addreess
                      
                      

String

Optional

Shipping address of customer

                      line1
                      *
                      

String

Mandatory

Example:- Mantri apartment

                      line2
                      *
                      

String

Mandatory

Example:- Koramangala

                      city
                      *
                      

String

Mandatory

Example:- Bangaluru

                      country
                      *
                      

String

Mandatory

                      state_name
                      *
                      

String

Mandatory

Example:- Karnataka

                      zipcode
                      *
                      

String

Mandatory

Example:- 560032

                      latitude
                      
                      

String

Optional

Example:- 123123

                      longitude
                      
                      

String

Optional

Example:- 1231231

                      country_iso
                      
                      

String

Optional

                      customer_info
                      
                      

String

Optional

                      customer_name
                      *
                      

String

Mandatory

Example:- ABCDEFGHIJ

                      customer_email
                      
                      

String

Optional

Example:- test@test.com

                      customer_reference_id
                      
                      

String

Optional

A specific customer reference number based on Id created at merchant’s end

Example:- cust_zer12345ssss

                      customer_national_id
                      
                      

String

Optional

Example:- ABCDE123

                      customer_dob
                      
                      

String

Optional

DD/MM/YYYY format

Example:- 06/08/1995

                      customer_pan_number
                      
                      

String

Conditional

Required for amount > 2.5 Lakhs

                      customer_account_debit_reference
                      
                      

String

Optional

Example:- LUMPSUM

                      customer_mobile_number
                      
                      

String

Optional

Example:- 9988776655

                      seller_info
                      
                      

String

Optional

                      seller_name
                      
                      

String

Optional

                      seller_bank_account_number
                      
                      

String

Optional

                      seller_registered_address
                      
                      

String

Optional

                      billing_address
                      
                      

String

Optional

                      line1
                      
                      

String

Optional

                      line2
                      
                      

String

Optional

                      city
                      
                      

String

Optional

                      country
                      
                      

String

Optional

                      state_name
                      
                      

String

Optional

                      zipcode
                      
                      

String

Optional

                      latitude
                      
                      

String

Optional

                      longitude
                      
                      

String

Optional

                      country_iso
                      
                      

String

Optional

                      payment_rules
                      
                      

Object

Optional

                      payment_flows
                      *
                      

Object

Mandatory

                      reverse_penny_drop
                      
                      

Object

Optional

                      status
                      
                      

String

Optional

Example:- DISABLED - Juspay will ignore the parameter| REQUIRED - Juspay will consider the parameter | OPTIONAL - Juspay will ignore the parameter

Response Body

                      status
                      
                      

string

Status of order

Example:- NEW

                      status_id
                      
                      

integer

Status ID is a numeric id corresponding to the status value.

id

string

Unique ID generated by Juspay for the given order

                      order_id
                      
                      

string

Order Id passed during order creation

                      payment_links
                      
                      

JSON

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

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

API Latency Guidelines

What is API Latency?

Time taken by the server to respond to the API request.

Average API Percentile Metrics and Recommended Timeout

TP50 (ms): This represents the median latency, meaning 50% of all requests are completed in this time or less. It indicates the typical performance experienced by the majority of users.

TP90 (ms): This value shows that 90% of requests are completed within this time, leaving 10% of requests that take longer. It gives insight into the performance for a broader set of users, beyond the median.

TP99 (ms): This value indicates that 99% of requests finish within this time, with only 1% of requests taking longer. It helps identify outlier cases where latency may become an issue for a small group of users.

TP99.9 (ms): This metric captures extreme latency outliers, where only 0.1% of requests take longer than this value. It’s useful for understanding edge cases where performance degrades for very few users.

TP99.99 (ms): This measures the most rare and severe performance outliers, where just 0.01% of requests exceed this time. Monitoring this helps in addressing the rarest and most critical latency issues that may impact user experience in exceptional scenarios.

Scroll inside to view more

Transaction Percentile	Latency (ms)
TP50 (ms)	46.14
TP90 (ms)	68.42
TP99 (ms)	583
TP99.9 (ms)	1511.28
Recommended Timeout(ms)	2000

The recommended timeouts are based on TP99.9 data, though edge cases (0.01% of requests) may still exceed these limits and are captured in the TP99.99 data as shown below.

Scroll inside to view more

Transaction Percentile	Latency (ms)
TP99.99 (ms)	2398.42
Recommended Timeout(ms)	3000