post https://api.juspay.in/orders
Creates an order that is a representation of your shopping cart. The order contains important information like amount, customer details, shipping address, billing address, etc. Only after an order is created, payment can be started.
Notes on Subvention Amount and 'UDF' parameters:
(click to view)
(click to view)
Note:
Subvention Amount: The amount for which the EMI interest should not be calculated. For example - if the Order amount is 100, the subvention amount is 10, interest will be calculated for 100-10 = 90.
Subvention amount can be from 0 to 100. If subvention amount = order amount then its no-cost EMI.
The mechanism of running offers or subvC9C9C9">ention amount is the responsibility of merchants in collaboration with PG/Banks.
Subvention Amount: The amount for which the EMI interest should not be calculated. For example - if the Order amount is 100, the subvention amount is 10, interest will be calculated for 100-10 = 90.
Subvention amount can be from 0 to 100. If subvention amount = order amount then its no-cost EMI.
The mechanism of running offers or subvC9C9C9">ention amount is the responsibility of merchants in collaboration with PG/Banks.
'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 parameters to the payment aggregators, irrespective of default parameters, The supported parameters are: (click to open table)
NOTE:
Check table below for additional request parameters that may be required depending on the payment gateway or aggregator used on the backend.
| Payment Gateways | Fields |
|---|---|
metadata.{{payment_gateway:field}} | |
| CCAVENUE_V2 | metadata.CCAVENUE_V2:promo_code------------ |
| BILLDESK | metadata.BILLDESK:AdditionalInfo3 |
| BILLDESK | metadata.BILLDESK:AdditionalInfo4 |
| FREECHARGE | metadata.FREECHARGE:campaignCode |
| HSBC_UPI | metadata.HSBC_UPI:addInfo |
| MIGS | metadata.MIGS:vpc_AddendumData |
| MIGS | metadata.MIGS:vpc_OrderInfo |
| OLAMONEY | metadata.OLAMONEY:couponCode |
| PAYTM | metadata.PAYTM:PROMO_CAMP_ID |
| PAYTM | metadata.PAYTM:CUST_ID |
| PAYTM | metadata.PAYTM:MERC_UNQ_REF |
| PAYU | metadata.PAYU:offer_key |
| PAYU | metadata.PAYU:udf1 |
| PAYU | metadata.PAYU:udf2 |
| PAYU | metadata.PAYU:udf3 |
| PAYU | metadata.PAYU:udf4 |
| PAYU | metadata.PAYU:udf5 |
| PHONEPE | metadata.PHONEPE:merchantContext |
| RAZORPAY | metadata.RAZORPAY:notes[cust_id] |
| RAZORPAY | metadata.RAZORPAY:notes[cust_name] |
| RAZORPAY | metadata.RAZORPAY:offer_id |
| Subvention Amount | metadata.subvention_amount |
| TPSL | metadata.TPSL:shoppingCartDetails |
| TPSL | metadata.TPSL:accountNo |
| ZAAKPAY | metadata.ZAAKPAY:productDescription |
| ZAAKPAY | metadata.ZAAKPAY:product1Description |
| 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 |
| AMAZONPAY | metadata.AMAZONPAY:sellerNote |
To use multiple MID setup, please pass the gateway_reference Id as per the following format: (click to view)
Assume you have three line of businesses BUS, TRAIN and FLIGHT and using RAZORPAY and PAYU gateways.
For BUS LOB pass the following in order create request.
| Payment Gateways | Fields | Value |
|---|---|---|
| PAYU | metadata.PAYU:gateway_reference_id | "BUS" |
| RAZORPAY | metadata.RAZORPAY:gateway_reference_id | "BUS" |
For TRAIN LOB pass the following in order create request.
| Payment Gateways | Fields | Value |
|---|---|---|
| PAYU | metadata.PAYU:gateway_reference_id | "TRAIN" |
| RAZORPAY | metadata.RAZORPAY:gateway_reference_id | "TRAIN" |
For FLIGHT LOB pass the following in order create request.
| Payment Gateways | Fields | Value |
|---|---|---|
| PAYU | metadata.PAYU:gateway_reference_id | "FLIGHT" |
| RAZORPAY | metadata.RAZORPAY:gateway_reference_id | "FLIGHT" |
Status, Redirect Info (response) parameters for the Create Order API are listed here: (click to open table)
| Field | 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 “CREATED”, then the order is successfully created (see Appendix below for status mapping). If you invoke this API with an order_id which is already created, then this API will return the result of /order/status API. |
| status_id | String | Status ID is a numeric id corresponding to the status value. See Appendix below for code meaning. |
| payment_links.web | String | Link to checkout page that is optimized for Desktop for the given order. |
| payment_links.mobile | String | Link to Mobile optimized checkout page for the given order. |
| payment_links.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.
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
| Order Status | ID | Meaning |
|---|---|---|
| CREATED | 1 | This order status code in used only for the Create Order API, and is returned when order is successfully created. |
| NEW | 10 | Newly created order. |
| 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 the bank refused the transaction. |
| JUSPAY_DECLINED | 22 | User input is not accepted by the underlying PG. |
| AUTHORIZING | 28 | Transaction status is pending from bank. |
⭣Order Details - The request consists of the following Parameter Groups and Objects: (click to open tables)
Each parameter in tables is listed below:
Order Details - The request consists of the following Parameter Groups and Objects: (click to open tables)
Each parameter in tables is listed below:
Each parameter in tables is listed below:
NOTE:
Check table below for additional request parameters that may be required depending on the payment gateway or aggregator used on the backend.
Parameter Groups:
Objects:
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 |
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 |
Note: Different payment gateways & aggregators have a varying set of parameters that are mandatory. Please ensure that the mandatory parameters are sent for your backend gateway.
(click to view & move left to right)
(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 |