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

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.

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, The supported parameters

Note: Auth api key should be Base64 encoded.

Scroll inside to view more

Payment Gateways	Fields
PG1	metadata.PG1:promo_code
PG2	metadata.PG2:AdditionalInfo3
PG3	metadata.PG3:campaignCode
PG4	metadata.PG4:OrderInfo
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

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

Recommended

Unique identifier for the merchant. This is the Merchant ID provided by Juspay. The value is case sensitive.

Passing this value will help us route efficiently at network level.

Example:- x-merchantid: testaccount

                      Content-Type
                      
                      

String

application/x-www-form-urlencoded

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.

Creating an order with "0" amount is feasible. Please contact the Juspay team for internal enablement.

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

                      mobile_country_code
                      
                      

String

Specifies the customer's mobile country code. This should be a numeric value without the '+' prefix.

Providing a non-numeric or alphanumeric value (e.g., "12abcd") will cause the request to fail with a Bad Request error.

                      currency
                      
                      

string

ISO string of the currency. e. Accepted values are 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

                      metadata.JUSPAY:gateway_reference_id
                      
                      

string

conditional

You will have to mandatorily pass this reference id if you created a gateway with gateway reference id on Juspay's dashboard. 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.txns.auto_capture
                      
                      

Boolean

A parameter to determine the capture method,

Set to false for pre-auth and capture.
Set to true for automatic capture.

                      metadata.txns.allow_card_no_3ds
                      
                      

Boolean

Parameter to define the authentication method,

Set to true for no Two Factor Authentication(2FA) where transaction gets successful once it is initiated..
Set to false for standard Two Factor Authentication(2FA).

                      txn_type
                      
                      

String

Conditional

Type of the transaction, please pass the following details
1. AUTHENTICATION => To perform authentication only
2. AUTHORIZATION => To perform authorization only
3. CAPTURE => To Perform Standalone capture
4. AUTHN_AUTHZ => To Perform Authentication and Authorization
5. AUTHZ_CAPTURE => To Perform Authorization and capture

                      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

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

Deeplink for web payments

                      mobile
                      
                      

string

Deeplink for mobile payments

                      iframe
                      
                      

string

Deeplink for iframe payment

Response Body

                      error_message
                      
                      

String

Error message of the API response

Example:- sample response: Bad Request

                      status
                      
                      

String

Denotes what type of error message

Example:- Response: Bad Request

                      error_info
                      
                      

JSON

Detailed information on the error message

                      user_message
                      
                      

String

Error message can be displayed to the user

Example:- sample response: Mandatory fields are missing.

                      fields
                      
                      

Array

Denotes what exact parameter is missing in the request

                      developer_message
                      
                      

String

Accurate detailed information on the error message to the user

Example:- sample response: Missing object reference id. Please pass valid object reference id.

                      category
                      
                      

String

Denotes the type of category the error

Example:- sample response: USER_ERROR

Response Body

                      error_code
                      
                      

String

Error code of the API response

Example:- sample response: access_denied

                      status
                      
                      

String

Denotes what type of error message

Example:- Response: error

                      error_info
                      
                      

JSON

Detailed information on the error message

                      user_message
                      
                      

String

Error message can be displayed to the user

Example:- sample response: Unauthorized fields are missing.

                      developer_message
                      
                      

String

Accurate detailed information on the error message to the user

Example:- sample response: Invalid API Key

                      category
                      
                      

String

Denotes the type of category the error

Example:- sample response: USER_ERROR

Error Codes:

Scroll inside to view more

Scenario	Error Codes	Sample Error Message
Not passing the currency value	400	{"error_message":"Bad Request.","status":"Bad Request","error_code":"INVALID_REQUEST","error_info":{"user_message":"Invalid input data","fields":[{"field_name":"currency","reason":"Missing field or Invalid Value"}],"developer_message":"Invalid input data","code":"INVALID_INPUT","category":"USER_ERROR"}}
Not passing the amount value	400	{"error_message":"Bad Request.","status":"Bad Request","error_code":"INVALID_REQUEST","error_info":{"user_message":"Invalid input data","fields":[{"field_name":"amount","reason":"Missing field or Invalid Value"}],"developer_message":"Invalid input data","code":"INVALID_INPUT","category":"USER_ERROR"}
Passing the amount in negative Integer	400	{"error_message":"Bad Request.","status":"Bad Request","error_code":"INVALID_REQUEST","error_info":{"user_message":"Invalid input data","fields":[{"field_name":"amount","reason":"Invalid amount"}],"developer_message":"Invalid input data","code":"INVALID_INPUT","category":"USER_ERROR"}}
Passing the amount in Positive Integer	400	{"error_message":"BadRequest.","status":"Bad Request","error_code":"INVALID_REQUEST","error_info":{"user_message":"Invalid input data","fields":[{"field_name":"amount","reason":"Missing field or Invalid Value"}],"developer_message":"Invalid input data","code":"INVALID_INPUT","category":"USER_ERROR"}}
Not passing the customer_email	400	{"status":"error","error_code":"invalid_request","error_info":{"user_message":"Invalid customer Email","fields":[{"field_name":"customerEmail","reason":"Invalid value."}],"developer_message":"customerEmail shouldn't have any special chars","code":"INVALID_INPUT","category":"USER_ERROR"}}
Not sending the orderId	400	{"error_message":"order_id is missing","status":"Bad Request","error_code":"order_id is missing","error_info":{"user_message":"Please pass order_id in request","fields":[{"field_name":"order_id","reason":"Missing field."}],"developer_message":"order_id is missing in request","code":"MISSING_MANDATORY_PARAMETER","category":"USER_ERROR"}}
Not passing API key	403	{"error":true,"error_message":"Forbidden.No valid API key or client auth token is present in Authorization header or client_auth_token query parameter","user_message":"Access Denied.Unable to proceed.","userMessage":"Access Denied.Unable to proceed.","error_info":{"code":"UNAUTHORIZED","category":"USER_ERROR","user_message":"AccessDenied","developer_message":"No valid API key or client auth token is present in Authorization header or client_auth_token query parameter"}}
Invalid API key	401	{"status":"error","error_code":"access_denied","error_info":{"user_message":"Unauthorized.","developer_message":"Invalid API Key.Please pass a valid and active apikey.","code":"UNAUTHORIZED","category":"USER_ERROR"}}
Whitelisting of IP in dashboard	403	{"error":true,"error_message":"Internal Server error.","user_message":"Bad Origin.","error_info":{"code":"BAD_ORIGIN","category":"USER_ERROR","user_message":"Bad Origin.","developer_message":"IP Verification Failed"}}
Passing amount as 0(without Juspay internal enablement)	400	{"error_message":"Bad Request.","status":"ERROR","error_code":"INVALID_REQUEST","error_info":{"user_message":"Invalid input data","fields":[{"field_name":"amount","reason":"Invalid amount"}],"developer_message":"Invalid input data","code":"INVALID_INPUT","category":"USER_ERROR"}}'
Passing a non configured currency	400	{"error_message":"Can't find a suitable gateway to process the transaction","status":"Bad Request","error_code":"invalid_request_error","error_info":{"user_message":"Gateway not found to process the transaction request.","developer_message":"No functional gateways after filtering for currency THB","code":"GATEWAY_NOT_FOUND","category":"CONFIG_ERROR"}}