Create Order

post https://sandbox.juspay.in/orders

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 this set of 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.

Mandate Status - During the entire journey, a mandate once created can take up any of the following states: (click to open table)

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. The state remains ACTIVE (except when PAUSED temporarily) until terminated (either when mandate expires or customer/merchant decides 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.
PENDING	Mandate is in a pending state. Note: This state has been deleted in main document.
EXPIRED	Mandate validity has expired. This is a terminal state.

Response Parameters for the Create Mandate Order API: (click to view)

Note:

Response parameters are the same as for the Create Order API (Status, Redirect Info).

Parameter	Type	Description
id	String	Unique ID generated by Juspay for the given order.
order_id	String	Given order ID.
status	String	Status of the order. If you receive “NEW”, then the mandate is successfully created. See Appendix below for status mapping. If you invoke this API with an `order_id` which already has a mandate created, then this API will return the result of the Get Mandate Order Status API.
status_id	Integer	Status ID is a numeric ID corresponding to the status value. See Appendix below for code meaning.
payment_links:wwwwwwni {web, mobile, iframe}	Object String	Three links for a Desktop , Mobile, and iFrame checkout screen for the given order (Parameters listed in table below - click to open)

Payment Links Object Parameters:

Field	Type	Description
web	String	Link to checkout page that is optimized for Desktop for the given order.
mobile	String	Link to Mobile optimized checkout page for the given order.
iframe	String	Link to iFrame checkout screen. This is typically embedded inside of your own page.

Payment Links
Order create response now has payment links for web, mobile & iFrame. These links can directly be emailed or messaged to your customers. They will be redirected using a link to enter payment information. If you wish to use your own branding, then you can embed the iframe link into your page. Note that, these links are not valid perpetually. As soon as your order expires (this can be changed via our dashboard), the link will cease to work.

APPENDIX Order status codes and meaning

Status	ID	Meaning
NEW	10	Newly created mandate
PENDING_VBV	23	Authentication is in progress. The customer has to approve the mandate through the PSP App of their choice.
CHARGED	21	Successful transaction. The subscription cost of the period has been charged.
AUTHENTICATION_FAILED	26	User did not complete authentication
AUTHORIZATION_FAILED	27	User completed authentication, but bank refused the transaction
JUSPAY_DECLINED	22	User input is not accepted by the underlying PG
AUTHORIZING	28	Transaction status is pending from bank

The request for the Create Mandate Order API consists of the following Parameter Groups and Objects:
(click to open tables) Each parameter is also listed below:

Note:

Check table here for additional request parameters that may be required depending on the payment gateway or aggregator used on the backend.
(click to view & move left to right)

Parameter	HDFC	ICICI	Axis	PayU	Citrus	PayTM	EBS	RazorPay	CCAvenue
order_id	Yes	Yes	Yes	Yes	Yes	Yes	Yes	Yes	Yes
amount	Yes	Yes	Yes	Yes	Yes	Yes	Yes	Yes	Yes
customer_id	Yes	Yes	Yes	Yes	Yes	Yes	Yes	Yes	Yes
customer_email	Yes	Yes	Yes	Yes	Yes	Yes	Yes	Yes	Yes
customer_phone	Optional	Optional	Optional	Yes	Yes	Yes	Yes	Yes	Yes
description	Optional	Optional	Yes	Yes	Yes	Yes	Yes	Yes	Yes
product_id	No	No	No	No	No	No	No	No	No
billing_address_first_name	No	No	No	Optional	Optional	No	Yes	No	Yes
billing_address_last_name	No	No	No	Optional	Optional	No	Yes	No	Yes
billing_address_line1	No	No	No	Optional	Optional	No	Yes	No	Yes
billing_address_line2	No	No	No	Optional	Optional	No	Yes	No	Yes
billing_address_line3	No	No	No	Optional	Optional	No	Yes	No	Yes
billing_address_city	No	No	No	Optional	Optional	No	Yes	No	Yes
billing_address_state	No	No	No	Optional	Optional	No	Yes	No	Yes
billing_address_country	No	No	No	Optional	Optional	No	Yes	No	Yes
billing_address_postal_code	No	No	No	Optional	Optional	No	Yes	No	Yes
billing_address_phone	No	No	No	Optional	Optional	No	Yes	No	Yes
billing_address_country_code_iso	No	No	No	Optional	Optional	No	Yes	No	Yes
shipping_address_first_name	No	No	No	Optional	Optional	No	Yes	No	Yes
shipping_address_last_name	No	No	No	Optional	Optional	No	Yes	No	Yes
shipping_address_line1	No	No	No	Optional	Optional	No	Yes	No	Yes
shipping_address_line2	No	No	No	Optional	Optional	No	Yes	No	Yes
shipping_address_line3	No	No	No	Optional	Optional	No	Yes	No	Yes
shipping_address_city	No	No	No	Optional	Optional	No	Yes	No	Yes
shipping_address_state	No	No	No	Optional	Optional	No	Yes	No	Yes
shipping_address_country	No	No	No	Optional	Optional	No	Yes	No	Yes
shipping_address_postal_code	No	No	No	Optional	Optional	No	Yes	No	Yes
shipping_address_phone	No	No	No	Optional	Optional	No	Yes	No	Yes
shipping_address_country_code_iso	No	No	No	Optional	Optional	No	Yes	No	Yes

Parameter Groups:

Order Info Parameters:

Field		Type	Description
order_id	*	String	Unique Identifier for the order. You can pass your native order ID here. It is suggested to keep the order id length as a maximum of 21 characters.
amount	*	String	Amount that the customer has to pay. Will accept double values with upto two decimal places. For example, 100.15 is valid, but 100.1532 is not valid.
order_type		String	Set to “TPV_PAYMENT” if using Third-Party Validation.
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	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.
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.
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

* = Required

Billing/Shipping Address Parameters:

Field	Type	Description
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)

UDF Parameters:

udf1 to udf10 - Optional user defined fields which will be echoed back in the response from Juspay with a Max character limit of 255. These fields may be 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.

Field	Type	Description
udf1	String	User Defined Field
udf2	String
udf3	String
udf4	String
udf5	String
udf6	String
udf7	String
udf8	String
udf9	String
udf10	String

Objects:

Mandate Object Parameters:

Field		Type	Description
max_amount	*	String	Maximum amount for a mandate. Mandatory only if `mandate.amount_rule` = VARIABLE.
frequency		String	Defines the frequency of mandate execution, or how often a customer should be charged. (see description for `mandate.frequency` below.)
amount_rule		String	Data type ENUM Possible values: FIXED, VARIABLE. By Default it is considered as VARIABLE. In case of FIXED, `max amount` will be equal to `amount`
start_date	*	String	Mandate start date in UNIX EPOCH timestamp (UTC timezone). In case of UPI mandate, the start date has to be today’s date. Mandatory only for UPI Mandate
end_date	*	String	Mandate end date in UNIX EPOCH timestamp (UTC timezone), from when a mandate will move to EXPIRED state and recurring mandate will not be allowed. Mandatory only for UPI Mandate.
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	Determines the day of week or month that a mandate will be executed, depending on the mandate.frequency. (see description for `mandate.rule_value` below.)
rule_type		String	ON / BEFORE / AFTER For Razorpay, rule_type will be updated to BEFORE. For Paytm, rule_type will be updated to AFTER


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

* = Required

Metadata Object Parameters:

Field	Type	Description
PAYTM_V2: SUBSCRIPTION_GRACE_DAYS	String	Number of days after renewal cycle start date for which merchant can send renewal request. By default 0 for DAILY and ASPRESENTED and 7 for remaining frequencies.
PAYTM_V2: SUBSCRIPTION_RETRY_COUNT	String	Applicable only for Paytm. By default 2 for UPI mandate.
PAYTM_V2: GATEWAY_REFERENCE_ID	String	Customized PAYTM_V2 parameter for the payment aggregators. This was found in request, but not in parameter list.
bank_account_details: [{...},{...},..}	Array of Objects	Applicable for TPV Mandate. If a merchant uses the Juspay `bank_account feature` APIs, then sending `bank_account_id` is sufficient.

Parameters for each object in the bank_account_details array: (click to open)

Field	Type	Description
bank_account_number	String	Bank account number of VPA used. Used only if downstream supports third party validation.
bank_ifsc	String	IFSC code for a bank branch.
juspay_bank_code	String	Code provided by Juspay for identifying the bank. Example: "JP_HDFC"
bank_beneficiary_name	String	Account holder name. Should contain alphabetical characters only. Required for emandate/e-NACH.
bank_account_type	String	Type of bank account
bank_account_id	String	ID generated by Juspay for bank account

Other Parameters sent by API, but not included in an Object or Parameter Group:

HEADERS:

Field		Type	Description
x-merchantid-----	*	String	Merchant ID which would have been issued while registering with Juspay
Content-Type		String	It should be application/x-www-form-urlencoded

* = Required

mandate.frequency / mandate.rule_value definitions: (click to view)

mandate.frequency

Description: Defines the frequency of mandate execution, or how often a customer should be charged.

Data type: String (ENUM format)

Possible values:

ONETIME, DAILY, WEEKLY, FORTNIGHTLY, MONTHLY, BIMONTHLY, QUARTERLY, HALFYEARLY, YEARLY, ASPRESENTED

Default: ASPRESENTED

mandate.rule_value

Description: This value determines the day of week or month that a mandate will be executed, depending on the mandate.frequency.

Data type: String (Integer format)

Possible values:

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, orYEARLY.

Not required when frequency is ONETIME, DAILY, or ASPRESENTED. For Razorpay, rule_value will be considered as the last date of the week/month/year. For Paytm, rule_value will be considered as today’s date/day.

Special considerations for certain values of the mandate.rule_value /mandate.frequency parameters: (click to view)

Calculating the day of mandate exectution for certain values of mandate.rule_value when mandate.frequency is set to 'FORTNIGHTLY' or 'MONTHLY'.

mandate.frequency = FORTNIGHTLY:

1. If the value is ‘14’, ‘15’, or ‘16’, and falls on the latter half of February (16th to 28th), then the mandate shall execute on the last day of February.

2. If the mandate start date is 24th January 2018 with value ‘16’, then the first

debit will be on 31st January, followed by 15th February, 28th February,

15th March, 31st March, and so on.

3. If the value is ‘16’, and the month has only 30 days, then the mandate should execute on 30th.

4. If the mandate start date is 29th January, and the value is ‘4’, then the first debit will be on 4th February, followed by 19th February, 4th March, and so on.

mandate.frequency = MONTHLY:

1. If the value is ‘29’, ‘30’, or ‘31’, and falls in February, then the mandate shall

execute on the last day of February.

2. If the value is ‘31’, and the next executable month has 30 days, then the

mandate will execute on the 30th.

3. If the mandate start date is 29th January and the value is ‘17’, then the first

debit will be on 17th February.