Body
Create Order API
This 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.
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.
‘Metadata’ is used to send custom params to the payment aggregators, irrespective of default parameters.
Note: Auth api key should be Base64 encoded.
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
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:-
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 instalment 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
Required
ISO string of the currency. Accepted values are BRL, HKD,EUR, USD, GBP,INR.
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
pre_auth_enabled
Bool
Will be set to true for pre-auth txns.
identity_credentials
Object
Conditional
This field should be used to pass cpf or cnpj values in the json format.
cpf
String
Conditional
This field should be used to pass cpf or cnpj values in the json format.
cnpj
String
Conditional
Brazilian identity number for companies without punctuation
pix_key
String
Conditional
Nickname that identifies a user's transactional account in Brazil
Metadata Object
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.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.PAYPAL:skipShippingAddress
Bool
Merchant can pass this field to skip sending shipping address for Paypal wallet flow.
metadata.txns.allow_card_no_3ds
Bool
Optional
Merchant can pass this field to enable NO_THREE_DS transactions in Card Payments Flow
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.
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
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
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