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

Create Order

This is the same API used for creating order for one-time payments. It can also be used to create a mandate for your existing customers with subscription specific details like amount, subscription frequency, duration of the mandate, Required/Optional mandate flow, etc. Use the order ID from the response of this API to call the Mandate Registration API.

Prerequisite for creating a mandate is to have the customer already registered/created with you. You can use Customer APIs to create a new customer or check the status of an existing customer.
The API is not required for the merchants using Juspay's Payment Page product.

During the entire journey, a mandate once created can take up any of the following states:

Scroll inside to view more

Status	Description
CREATED	Mandate has been created, but awaiting status from PG.
ACTIVE	When PG accepts the chosen mode of payment, the mandate is set to the active state. This is a terminal state until mandate expires or customer/merchant wants to revoke the mandate.
PAUSED	Customer has an option to pause the mandate. Status changes to PAUSED when customer exercises this option.
REVOKED	Mandate is revoked by either the customer or the merchant. Revoked is a terminal state, once Revoked the status cannot be changed.
FAILURE	Mandate creation was unsuccessful. This is a terminal state, the merchant has to create a new mandate if failed.
EXPIRED	Mandate validity has expired. This is a terminal state.

Request

Response

API Endpoints

Sandbox Link

POST

https://sandbox.juspay.in/orders

Production Link

POST

https://api.juspay.in/orders

                      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

It should be application/x-www-form-urlencoded

Body

Request Schema: application/json

                      order_id
                      *
                      

String

Mandatory

Unique Identifier for the order. You can pass your native order ID here.

                      amount
                      *
                      

doube

Mandatory

This is the amount that a customer will be charged in this transaction.

NOTE: In the new card SI flow, the minimum amount to be passed is Rs 2. For enach registration with NB, Debit Card or Aadhaar verification, amount should always be passed as 1

                      currency
                      
                      

String

ISO string of the currency. Use INR for Indian Rupee. Among other accepted values are EUR, USD, GBP. Default value: INR

                      customer_id
                      *
                      

String

Mandatory

Unique ID for a customer that you get after running the Create Customer API
(Check Customer section for more details)

                      customer_email
                      
                      

String

Email address of the customer. This field is mandatory if gateway requires it.

                      customer_phone
                      
                      

String

Mobile number or fixed line number of the customer. This field is mandatory if gateway requires it.

                      description
                      
                      

String

Short description for the order. We send this information to the gateways whenever there is a provision for this.

                      product_id
                      
                      

String

An identifier for the product. Fits well for impulse purchase usecases.

                      gateway_id
                      
                      

String

Specify your preferred gateway for this order. Complete mapping for gateway_id can be found here: Gateway mapping

                      return_url
                      
                      

String

A fully qualified URL such as http://shop.merchant.com/ to which the customer will be redirected after payment completion. This URL shouldn’t contain any query parameters.
This URL takes higher precedence over the common return URL configured in your account settings.

                      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

Line 1 in the billing address

                      billing_address_line2
                      
                      

String

Line 2 in the billing address

                      billing_address_line3
                      
                      

String

Line 3 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

                      options.create_mandate
                      *
                      

String

Mandatory

For merchants who wants to set up mandates, can pass this as either “REQUIRED” or “OPTIONAL”. “REQUIRED” means that the transaction for this order has to be definitely converted to a mandate. “OPTIONAL” means that the final decision of conversion of the transaction lies at the /txns api call with the flag “should_create_mandate”

                      mandate object
                      
                      

Object

                      max_amount
                      *
                      

String

Mandatory

Maximum amount for a mandate. Required, only when amount type is variable. If amount type is fixed, amount is considered as max amount.

                      frequency
                      
                      

String

Defines the frequency of mandate execution, how often a customer should be charged.
Data type ENUM:
ONETIME (Supported only by UPI)
DAILY
WEEKLY
FORTNIGHTLY
MONTHLY
BIMONTHLY
QUARTERLY
HALFYEARLY
YEARLY
ASPRESENTED
By Default it is considered as ASPRESENTED

If frequency is selected anything other than ONETIME, DAILY, ASPRESENTED, rule_value should be passed mandatorily.

                      amount_rule
                      
                      

String

Data type ENUM: FIXED, VARIABLE. By default, it is considered as VARIABLE. In case of FIXED amount_rule.

                      revokable_by_customer
                      
                      

boolean

If false, the mandate cannot be revoked by the customer once set. Applicable only for UPI mandate. It should be true for Recurring and true/false for ONETIME. By default value will be true

                      block_funds
                      
                      

Boolean

Set to true if funds have to be blocked while a mandate is being created. Should be true for ONETIME and false for Recurring. By default value will be TRUE for ONETIME and FALSE for Recurring.

                      rule_value
                      
                      

String

1-7 when frequency is WEEKLY. In weekly, serial numbers start from Monday. Monday represents 1 and Sunday represents 7.

1-16 when frequency is FORTNIGHTLY. This mandate is executed twice a month. First day of the month is represented by value ‘1’ and ends with ‘15’ on 15th day of the month. Then again starts with ‘1’ for 16th of the month and ends with the last day of the month.

1-31 when frequency is MONTHLY, BIMONTHLY, QUARTERLY, HALFYEARLY, or YEARLY.

Not required when frequency is ONETIME, DAILY, ASPRESENTED.

                      udf1-10
                      
                      

String

Response Body

                      200 : UPI
                      
                      

Object

                      status_id
                      
                      

integer

                      status
                      
                      

String

                      payment_links
                      
                      

object

web

String

                      mobile
                      
                      

String

                      iframe
                      
                      

String

                      order_id
                      
                      

String

id

String

                      200 : Card
                      
                      

object

                      status
                      
                      

String

                      status_id
                      
                      

integer

id

String

                      order_id
                      
                      

String

                      payment_links
                      
                      

object

web

String

                      mobile
                      
                      

String

                      iframe
                      
                      

String

                      200 :  Netbanking
                      
                      

object

                      status
                      
                      

String

                      status_id
                      
                      

Integer

id

String

                      order_id
                      
                      

String

                      payment_links
                      
                      

object

web

String

                      mobile
                      
                      

String

                      iframe
                      
                      

String

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 value	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"}}
Not Passing customer_id	400	{"error_message":"pass valid customer_id","status":"ERROR","error_code":"INVALID_CUSTOMER_ID","error_info":{"user_message":"INVALID_CUSTOMER_ID","fields":[{"field_name":"customer_id","reason":"Invalid Value"}],"developer_message":"pass valid customer_id","code":"INVALID_INPUT","category":"USER_ERROR"},"status_id":-1}
Invalid gateway_id	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 supporting this transaction.","code":"GATEWAY_NOT_FOUND","category":"CONFIG_ERROR"}}
Not passing mandate_max_amount	400	{"error_message":"Bad Request.","status":"ERROR","error_code":"INVALID_REQUEST","error_info":{"user_message":"Invalid input data","fields":[{"field_name":"mandate","reason":"mandate_max_amount is not passed or is invalid"}],"developer_message":"Invalid input data","code":"INVALID_INPUT","category":"USER_ERROR"},"status_id":-1}
Passing mandate_max_amount as '0'	400	{"error_message":"mandate_max_amount should be greater than or equal to 1","status":"ERROR","error_code":"INVALID_REQUEST","error_info":{"user_message":"INVALID_REQUEST","fields":[{"field_name":"mandate.max_amount","reason":"Invalid Value"}],"developer_message":"mandate_max_amount should be greater than or equal to 1","code":"INVALID_INPUT","category":"USER_ERROR"},"status_id":-1}
Passing any date greater than today as a start date	200	By default taking today's date
Not Passing start date of mandate	200	By default taking today's date
Not passing end date	200	By default taking 10 years
Passing end date as the same day with difference of few hours	400	{"error_message":"End date passed is invalid","status":"ERROR","error_code":"INVALID_END_DATE","error_info":{"user_message":"INVALID_END_DATE","fields":[{"field_name":"mandate.end_date","reason":"Invalid Value"}],"developer_message":"End date passed is invalid","code":"INVALID_INPUT","category":"USER_ERROR"},"status_id":-1}
Not Passing mandate.frequency field	200	By default it is taking as ASPRESENTED
Passing invalid gateway_reference_id	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 gateways are configured with the referenceIds {\"RAZORPAY:gateway_reference_id\":\"test\"} to proceed transaction ","code":"GATEWAY_NOT_FOUND","category":"CONFIG_ERROR"}}

Have questions?
Need help? Contact support
LLM? Read llms.txt