--- page_source: https://juspay.io/sea/docs/express-checkout-sdk-global/capacitor/mandates/mandates-create-order-api page_title: Mandates Create Order API --- ## API Version: default # 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: | 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. | ## Endpoints: - Sandbox: https://sandbox.juspay.in/orders - Production: https://api.juspay.in/orders ## Request Type: POST ## Content-Type: application/json ## Headers: #### x-merchantid: Unique identifier for the merchant. This is the Merchant ID provided by Juspay. The value is case sensitive. > **Note** > Passing this value will help us route efficiently at network level. - Value: x-merchantid: testaccount - Tags: String, Recommended #### Content-Type: It should be application/x-www-form-urlencoded - Tags: String ## Sample Code Snippets: ### Code Snippets: #### Request Code Snippet: ```request curl POST \ https://api.juspay.in/orders \ -H 'Authorization: Basic ' \ -H 'Content-Type: application/x-www-form-urlencoded'\ -d "order_id=152664118690577-910" \ -d "amount=5.00" \ -d "currency=SGD" \ -d "customer_id=test_juspay" \ -d "customer_email=test@gmail.com" \ -d "customer_phone=987654321" \ -d "billing_address_first_name=Parth" \ -d "billing_address_city=Bengaluru" \ -d "shipping_address_city=Mumbai" \ -d "mandate.amount_rule=VARIABLE" \ -d "shipping_address_first_name=Parth" \ -d "options.create_mandate=REQUIRED" \ -d "mandate_max_amount=1000.00" ``` ### Sample Request and Response: #### 200 - Success: ```plaintext { "status": "CREATED", "status_id": 1, "id": "ord_e294a26e66ad4336a992ceab81ad704c", "order_id": "1478851764", "payment_links": { "web": "https://api.juspay.in/guest/pay/ord_e294a26e66ad4336a992ceab81ad704c", "mobile": "https://api.juspay.in/guest/pay/ord_e294a26e66ad4336a992ceab81ad704c?mobile=true", "iframe": "https://api.juspay.in/guest/ipay/ord_e294a26e66ad4336a992ceab81ad704c" } } ``` #### 400 - Bad Request: ```plaintext { "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" } ], "request_id": "9df7c87f-1c94-4ced-9dad-2fb8572b4146", "href": "NA", "developer_message": "Invalid input data", "code": "INVALID_INPUT", "category": "USER_ERROR" }, "status_id": -1 } ``` #### 401 - Unauthorized: ```plaintext { "status": "error", "error_code": "access_denied", "error_info": { "user_message": "Unauthorized.", "request_id": "d2deeaf7-edde-4b29-b654-0fdb98c9da82", "href": "NA", "developer_message": "Invalid API Key. Please pass a valid and active api key.", "code": "UNAUTHORIZED", "category": "USER_ERROR" } } ``` ## Body Parameters: ### Request Parameters: #### order_id: - Description: Unique Identifier for the order. You can pass your native **order ID** here. - Value: value - Tags: String, Mandatory #### amount: - Description: 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 - Tags: doube, Mandatory #### currency: - Description: ISO string of the currency. Use **INR** for Indian Rupee. Among other accepted values are EUR, USD, GBP. Default value: `INR` - Tags: String #### customer_id: - Description: Unique ID for a customer that you get after running the **Create Customer API** (Check Customer section for more details) - Tags: String, Mandatory #### customer_email: - Description: Email address of the customer. This field is mandatory if gateway requires it. - Tags: String #### customer_phone: - Description: Mobile number or fixed line number of the customer. This field is mandatory if gateway requires it. - Tags: String #### description: - Description: Short description for the order. We send this information to the gateways whenever there is a provision for this. - Tags: String #### product_id: - Description: An identifier for the product. Fits well for impulse purchase usecases. - Tags: String #### gateway_id: - Description: Specify your preferred gateway for this order. Complete mapping for **gateway_id** can be found here: [Gateway mapping](/resources-global/docs/dynamic-routing/dynamic-routing#Enforce-Gateway-Routing) - Tags: String #### return_url: - Description: A fully qualified URL such as [http://shop.merchant.com/](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. - Tags: String #### billing_address_first_name: - Description: First name in the billing address - Tags: String #### billing_address_last_name: - Description: Last name in the billing address - Tags: String #### billing_address_line1: - Description: Line 1 in the billing address - Tags: String #### billing_address_line2: - Description: Line 2 in the billing address - Tags: String #### billing_address_line3: - Description: Line 3 in the billing address - Tags: String #### billing_address_city: - Description: Billing address city - Tags: String #### billing_address_state: - Description: Billing address state - Tags: String #### billing_address_country: - Description: Billing address country - Tags: String #### billing_address_postal_code: - Description: Billing address postal code or zip code - Tags: String #### billing_address_phone: - Description: Mobile or phone number in the billing address - Tags: String #### billing_address_country_code_iso: - Description: ISO Country code Default value: `IND` - Tags: String #### shipping_address_first_name: - Description: First name in the shipping address - Tags: String #### shipping_address_last_name: - Description: Last name in the shipping address - Tags: String #### shipping_address_line1: - Description: Line1 in the shipping address - Tags: String #### shipping_address_line2: - Description: Line2 in the shipping address - Tags: String #### shipping_address_line3: - Description: Line3 in the shipping address - Tags: String #### shipping_address_city: - Description: Shipping address city - Tags: String #### shipping_address_state: - Description: Shipping address state - Tags: String #### shipping_address_country: - Description: Shipping address country - Tags: String #### shipping_address_postal_code: - Description: Shipping address postal code or zip code - Tags: String #### shipping_address_phone: - Description: Mobile or phone number in the shipping address - Tags: String #### shipping_address_country_code_iso: - Description: ISO Country code Default value: `IND` - Tags: String #### options.create_mandate: - Description: 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”** - Tags: String, Mandatory #### mandate object: - Value: - **Max_amount**: - Description: Maximum amount for a mandate. Required, only when amount type is variable. If amount type is fixed, amount is considered as max amount. - Tags: String, Mandatory - **Frequency**: - Description: 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. - Tags: String - **Amount_rule**: - Description: Data type **ENUM: FIXED, VARIABLE** . By default, it is considered as VARIABLE. In case of FIXED **amount_rule** . - Tags: String - **Revokable_by_customer**: - Description: 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 - Tags: boolean - **Block_funds**: - Description: 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. - Tags: Boolean - **Rule_value**: - Description: **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** . - Tags: String - Tags: Object #### udf1-10: - Tags: String ## API Responses: ### 200: #### 200 : UPI: - Value: - **Status_id**: - Tags: integer - **Status**: - Tags: String - **Payment_links**: - Value: - **Web**: - Tags: String - **Mobile**: - Tags: String - **Iframe**: - Tags: String - Tags: object - **Order_id**: - Tags: String - **Id**: - Tags: String - Tags: Object #### 200 : Card: - Value: - **Status**: - Tags: String - **Status_id**: - Tags: integer - **Id**: - Tags: String - **Order_id**: - Tags: String - **Payment_links**: - Value: - **Web**: - Tags: String - **Mobile**: - Tags: String - **Iframe**: - Tags: String - Tags: object - Tags: object #### 200 : Netbanking: - Value: - **Status**: - Tags: String - **Status_id**: - Tags: Integer - **Id**: - Tags: String - **Order_id**: - Tags: String - **Payment_links**: - Value: - **Web**: - Tags: String - **Mobile**: - Tags: String - **Iframe**: - Tags: String - Tags: object - Tags: object ### Error Codes | 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"}} |