Overview of the Order APIs

These four APIs handle order processing via the Order Object on the Juspay server.

Create Order:

Creates an order that is a representation of your shopping cart.

Required: Order Details, which must include: order_id, amount,

and may include customer, address, bank info, gateway,

UDF parameters, etc. Note that different payment

gateways & aggregators have a varying set of parameters

that are mandatory. (see Order Details section below)

Optional Header: version

Returns: status, redirect info

POST https://api.juspay.in/orders

Get Order Status:

Retrieves the Order Object associated with the order_id (status).

Required: order_id Optional Header: version

Returns: Order Object

GET https://api.juspay.in/orders/:order_id

Update Order:

Updates an order that has already been created.

Required: order_id, amount

Optional: Address, UDF update info (see Order Details section below)

Returns: Order Object

POST https://api.juspay.in/orders/:order_id

Refund Order:

Creates a refund for a payment.

Required: order_id, amount, unique_request_id

Optional Header: version

Returns: Order Object (with Refund Objects)

POST https://api.juspay.in/orders/:order_id/refunds

URL Embedded (Path) Parameter:

Field	*	Type	Description
order_id	*	String	Unique Identifier for the order.

* = Required only for the Get Order Status, Update Order, and Refund Order APIs

Header:

Field	*	Type	Description
version	*	String	Pass the version as 2018-10-25.

Optional only for the Create Order, Get Order Status, and Refund Order APIs

Request (Form) Parameters:

Field	Type	Description
unique_request_id	String	Required for the Refund Order API. * Request ID that uniquely identifies the request. A good candidate for unique_request_id would be your database primary key.
amount	Double	Required for the Create Order API. * Amount that the customer has to pay with the initial order.
amount	Double	Required for the Refund Order API. * Amount that has to be refunded. Amount has to be less than or equal to the amount of the order that is not yet refunded. If this parameter is not passed, then the order is refunded entirely.
amount	Double	Required for the Update Order API. * New amount value. Note: Only the address and UDF fields can be updated also. See the Order Details parameter listing for the Create Order API below.

* = Required

Order Details - Required for the Create Order API, and optional for the

Update Order API (click to open tables)

Note 1:

Only the amount, UDF Parameters, and Billing/Shipping Address
Parameters can be sent as updates with the Update Order API

Note 2:

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

* = Required

Billing/Shipping Adress 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:

Metadata Parameters:

Field	Type	Description
subvention_amount	String	The amount for which the EMI interest should not be calculated.
{{payment_gateway:field}}	String	Customized parameter for payment gateway/aggregator/field. Insert in {{payment_gateway:field}} from the 'Metadata' table above. This is irrespective of default parameters.
bank_account_details: [(...),(....),(...),..]	Array	This is an array of Bank Accounts JSON objects that provides details of each bank account of a given customer. (See table) (Used only for TPV payments)

Bank Accounts Object:

Field		Type	Description
bank_account_number	*	String	Customer's bank account number
bank_ifsc		String	IFSC code for the bank branch
juspay_bank_code		String	Juspay bank code given from Eligibility API. e.g. JP_HDFC
bank_beneficiary_name		String	Name of account holder
bank_account_id	*	String	Bank account id provided by Juspay while storing bank account details

* =

Conditional - either bank_account_number or bank_account_id is mandatory.

Options Parameter:

Field	Type	Description
get_client_auth_token	String	Client side authenticaion token. This is required to obtain the `client_auth_token`, which is used for SDK integration and Hyper SDK calls

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

Parameter Group:

Field		Type	Description
version		String	Pass the version as 2018-10-25