Hey! These docs are for version 3.2, which is no longer officially supported. Click here for the latest version, 1.0!

Overview of the Order APIs

An order is a representation of your shopping cart. An Order Object can be created for it in Juspay, which contains important information like amount, customer details, transaction details, etc. The payment process can be started only after an Order Object is created.

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
  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)
ParameterHDFCICICIAxisPayUCitrusPayTMEBSRazorPayCCAvenue
order_idYesYesYesYesYesYesYesYesYes
amountYesYesYesYesYesYesYesYesYes
customer_idYesYesYesYesYesYesYesYesYes
customer_emailYesYesYesYesYesYesYesYesYes
customer_phoneOptionalOptionalOptionalYesYesYesYesYesYes
descriptionOptionalOptionalYesYesYesYesYesYesYes
product_idNoNoNoNoNoNoNoNoNo
billing_address_first_nameNoNoNoOptionalOptionalNoYesNoYes
billing_address_last_nameNoNoNoOptionalOptionalNoYesNoYes
billing_address_line1NoNoNoOptionalOptionalNoYesNoYes
billing_address_line2NoNoNoOptionalOptionalNoYesNoYes
billing_address_line3NoNoNoOptionalOptionalNoYesNoYes
billing_address_cityNoNoNoOptionalOptionalNoYesNoYes
billing_address_stateNoNoNoOptionalOptionalNoYesNoYes
billing_address_countryNoNoNoOptionalOptionalNoYesNoYes
billing_address_postal_codeNoNoNoOptionalOptionalNoYesNoYes
billing_address_phoneNoNoNoOptionalOptionalNoYesNoYes
billing_address_country_code_isoNoNoNoOptionalOptionalNoYesNoYes
shipping_address_first_nameNoNoNoOptionalOptionalNoYesNoYes
shipping_address_last_nameNoNoNoOptionalOptionalNoYesNoYes
shipping_address_line1NoNoNoOptionalOptionalNoYesNoYes
shipping_address_line2NoNoNoOptionalOptionalNoYesNoYes
shipping_address_line3NoNoNoOptionalOptionalNoYesNoYes
shipping_address_cityNoNoNoOptionalOptionalNoYesNoYes
shipping_address_stateNoNoNoOptionalOptionalNoYesNoYes
shipping_address_countryNoNoNoOptionalOptionalNoYesNoYes
shipping_address_postal_codeNoNoNoOptionalOptionalNoYesNoYes
shipping_address_phoneNoNoNoOptionalOptionalNoYesNoYes
shipping_address_country_code_isoNoNoNoOptionalOptionalNoYesNoYes



    Parameter Groups:
  Order Info Parameters:
FieldTypeDescription
order_id*StringUnique 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*StringAmount 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_typeStringSet to “TPV_PAYMENT” if using Third-Party Validation.
currencyStringISO string of the currency. Use INR for Indian Rupee. Among other accepted values are EUR, USD, GBP. Default value: INR
customer_idStringUnique ID for a customer that you get after running the Create Customer API (Check Customer section for more details)
customer_emailStringEmail address of the customer.
This field is mandatory if gateway requires it.
customer_phoneStringMobile number or fixed line number of the customer.
This field is mandatory if gateway requires it.
descriptionStringShort description for the order. We send this information to the gateways whenever there is a provision for this.
product_idStringAn identifier for the product. Fits well for impulse purchase usecases.
gateway_idStringSpecify your preferred gateway for this order. Complete mapping for “gateway_id” can be found here: Gateway mapping
return_urlStringA 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:
FieldTypeDescription
billing_address_first_nameStringFirst name in the billing address
billing_address_last_nameStringLast name in the billing address
billing_address_line1StringLine1 in the billing address
billing_address_line2StringLine2 in the billing address
billing_address_line3StringLine3 in the billing address
billing_address_cityStringBilling address city
billing_address_stateStringBilling address state
billing_address_countryStringBilling address country
billing_address_postal_codeStringBilling address postal code or zip code
billing_address_phoneStringMobile or phone number in the billing address
billing_address_country_code_iso---StringISO Country code
(Default value: IND)
shipping_address_first_nameStringFirst name in the shipping address
shipping_address_last_nameStringLast name in the shipping address
shipping_address_line1StringLine1 in the shipping address
shipping_address_line2StringLine2 in the shipping address
shipping_address_line3StringLine3 in the shipping address
shipping_address_cityStringShipping address city
shipping_address_stateStringShipping address state
shipping_address_countryStringShipping address country
shipping_address_postal_codeStringshipping address postal code or zip code
shipping_address_phoneStringMobile or phone number in the shipping address
shipping_address_country_code_isoStringISO 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.
FieldTypeDescription
udf1StringUser Defined Field
udf2String
udf3String
udf4String
udf5String
udf6String
udf7String
udf8String
udf9String
udf10String
    Objects:
  Metadata Parameters:
FieldTypeDescription
subvention_amountStringThe amount for which the EMI interest should not be calculated.
{{payment_gateway:field}}StringCustomized 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:
   [(...),(....),(...),..]
ArrayThis 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:
FieldTypeDescription
bank_account_number*StringCustomer's bank account number
bank_ifscStringIFSC code for the bank branch
juspay_bank_codeStringJuspay bank code given from Eligibility API.     e.g. JP_HDFC
bank_beneficiary_nameStringName of account holder
bank_account_id*StringBank account id provided by Juspay while storing bank account details

* =
Conditional - either bank_account_number or bank_account_id is mandatory.
  Options Parameter:
FieldTypeDescription
get_client_auth_tokenStringClient 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:
FieldTypeDescription
versionStringPass the version as 2018-10-25



What’s Next