---
page_source: https://juspay.io/sea/docs/express-checkout-sdk-global/capacitor/base-sdk-integration/1-create-order-api
page_title: 5.1 Create Order API
---

## API Version: default


# Create Order API 



This is a Server-to-Server API that takes order parameters as an input and creates an order in the Juspay system and fetches the corresponding client_auth_token. 


---


Amount and order id are the mandatory fields, the contact details like email, phone number, customer id's are conditional and depends on the underlying payment gateway/ aggregator used.  

'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 params to the payment aggregators, irrespective of default parameters, The supported parameters

Note: Auth api key should be Base64 encoded.

> **Note**
> If merchants choose not to call the Juspay Customer API, the Customer ID can be implicitly created during order creation. Please ensure the following,
> 
> * Include all required customer-related parameters in the order creation request.
> * Juspay internal enablement is necessary for implicit customer creation. Please contact the Juspay team for this enablement.




| Payment Gateways | Fields |
|---|---|
| PG1 | metadata.PG1:promo_code |
| PG2 | metadata.PG2:AdditionalInfo3 |
| PG3 | metadata.PG3:campaignCode |
| PG4 | metadata.PG4:OrderInfo |
| 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 |
## Endpoints:
- Sandbox: https://sandbox.juspay.in/orders

- Production: https://api.juspay.in/orders

## Request Type: 
POST

## Content-Type: 
application/json

## Authorization:

#### Basic Auth:
Consists of two parts.

* Username: API Key obtained from Juspay dashboard
* Password: Empty string
- Value: <p>Example:- <br> Basic MUQ2QUxxxxxxxxxxxxU5QTIxQzNFNTQwNkFDMEZCOg==</p>
- Tags: Base64 Encoded username:password, required
## 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:
application/x-www-form-urlencoded
- Tags: String
## Sample Code Snippets:
### Sample Request:

#### Request Code Snippet:

```request
curl --location --request POST 'https://api.juspay.in/orders' \
--header 'Content-Type: application/x-www-form-urlencoded' \
--header 'x-merchantid: merchant_id'\
--header 'Authorization: Basic QTA0QT*******ODg1Og==' \
--data-urlencode 'order_id=14183944763' \
--data-urlencode 'amount=100.00' \
--data-urlencode 'currency=HKD' \
--data-urlencode 'customer_id=guest_user_101' \
--data-urlencode 'customer_email=customer@gmail.com' \
--data-urlencode 'customer_phone=9988665522' \
--data-urlencode 'mobile_country_code=91'\
--data-urlencode 'product_id=prod-141833' \
--data-urlencode 'return_url=http://shop.merchant.com/payments/handleResponse' \
--data-urlencode 'description=Sample description' \
--data-urlencode 'billing_address_first_name=Juspay' \
--data-urlencode 'billing_address_last_name=Technologies' \
--data-urlencode 'billing_address_line1=Building1' \
--data-urlencode 'billing_address_line2= HKD Road' \
--data-urlencode 'billing_address_city=city1' \
--data-urlencode 'billing_address_state=Saudi State1' \
--data-urlencode 'billing_address_country=Saudi Arabia' \
--data-urlencode 'billing_address_postal_code=12627' \
--data-urlencode 'billing_address_phone=9988775566' \
--data-urlencode 'billing_address_country_code_iso=HKD' \
--data-urlencode 'shipping_address_first_name=Juspay' \
--data-urlencode 'shipping_address_last_name=Technologies' \
--data-urlencode 'shipping_address_line1=Building 20' \
--data-urlencode 'shipping_address_line2=Road 50' \
--data-urlencode 'shipping_address_city=city50' \
--data-urlencode 'shipping_address_state=Saudi 50' \
--data-urlencode 'shipping_address_postal_code=22233' \
--data-urlencode 'shipping_address_phone=9962761222' \
--data-urlencode 'shipping_address_country_code_iso=HKD' \
--data-urlencode 'shipping_address_country=Saudi Arabia' \
--data-urlencode 'metadata.APPLEPAY%3Agateway_reference_id=test' \
--data-urlencode 'metadata.webhook_url=https://webhook.site/50c490d0-32d3-4b2f-8542-14325fdd2047' \
--data-urlencode 'metadata.txns.auto_capture=true' \
--data-urlencode 'metadata.txns.allow_card_no_3ds=true' \
--data-urlencode 'udf1=business1' \
--data-urlencode 'udf2=customer' \
--data-urlencode 'udf3=offer' \
--data-urlencode 'udf4=extrainfo1' \
--data-urlencode 'udf5=extrainfo2' \
--data-urlencode 'udf6=extrainfo3' \
--data-urlencode 'udf7=extrainfo4' \
--data-urlencode 'udf8=extrainfo5' \
--data-urlencode 'udf9=extrainfo6' \
--data-urlencode 'udf10=extrainfo7' 
```

### Sample Response:

#### 200 - Success:
```json
{
  "status": "CREATED",
  "status_id": 1,
  "id": "ord_e294a26e66ad4336a992ceab81ad704c",
  "order_id": "14183944763",
  "payment_links": {
    "web": "https://api.juspay.in/merchant/pay/ord_e294a26e66ad4336a992ceab81ad704c",
    "mobile": "https://api.juspay.in/merchant/pay/ord_e294a26e66ad4336a992ceab81ad704c?mobile=true",
    "iframe": "https://api.juspay.in/merchant/ipay/ord_e294a26e66ad4336a992ceab81ad704c"
  }
}

```

#### 400 - Bad Request:
```plaintext
{
    "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"
            }
        ],
        "request_id": "aa57a749-428b-41e7-b3e7-34c26cf05e50",
        "href": "NA",
        "developer_message": "Invalid input data",
        "code": "INVALID_INPUT",
        "category": "USER_ERROR"
    }
}
```

#### 403 - Forbidden:
```plaintext
{
    "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",
        "href": "NA",
        "request_id": "1e515677-6134-4d9a-9279-c2926b4304bb",
        "user_message": "Access Denied",
        "developer_message": "No valid API key or client auth token is present in Authorization header or client_auth_token query parameter"
    }
}
```

#### 401 - Unauthorized:
```plaintext
{
    "status": "error",
    "error_code": "access_denied",
    "error_info": {
        "user_message": "Unauthorized.",
        "request_id": "c59e41ad-f3cf-4232-8a23-b58f4322466e",
        "href": "NA",
        "developer_message": "Invalid API Key. Please pass a valid and active api key.",
        "code": "UNAUTHORIZED",
        "category": "USER_ERROR"
    }
}
```

## Body Parameters:
### Basic Parameters:

#### order_id:
- Description: Unique Identifier for the order. Should be Alphanumeric with character length less than 21.
- Value: <p>Example:- <br> orderid9876580 </p>
- Tags: string, required

#### amount:
- Description: Amount that the customer has to pay. Will accept stringified double or integer values with upto two decimal places. For example, "100.15" and "100" are valid input but "100.1532" is not valid.

> **Note**
> Creating an order with a "0" amount is feasible. Please contact the Juspay team for internal enablement.


- Value: <p>Example:- <br> 1.00 </p>
- Tags: Double, required

#### options.get_client_auth_token:
- Description: Client side authenticaion token required for Hyper SDK calls
- Value: Value : true
- Tags: string

#### customer_id:
- Description: It is the ID with which merchant refers to a customer object. This id is used to access the stored payment methods, allow EMI transactions and setup subscriptions. 

In case of guest login it should be an empty string.
- Value: <p>Example:- <br> customer-id-007 </p>
- Tags: string, Required

#### customer_email:
- Description: Email address of the customer. If the backend gateway requires it, then you must send this value.
- Value: <p>Example:- <br> test@gmail.com</p>
- Tags: string

#### customer_phone:
- Description: Mobile number or fixed line number of the customer. If the backend gateway requires it, then you must send this value.
- Value: <p>Example:- <br> 9999999912</p>
- Tags: string

#### mobile_country_code:
- Description: Specifies the customer's mobile country code. This should be a numeric value without the '+' prefix.

> **Warning**
> Providing a non-numeric or alphanumeric value (e.g., `"12abcd"`) will cause the request to fail with a **Bad Request**  error.


- Value:  91
- Tags: String

#### currency:
- Description: ISO string of the currency. e. Accepted values are HKD,EUR, USD, GBP,INR. Default value: INR
- Tags: string

#### description:
- Description: Short description for the order. We send this information to the backend gateways whenever there is a provision for this.
- Tags: string

#### return_url:
- Description: A fully qualified URL which the customer will be redirected after payment completion. It is also required to provide the control back to SDK after the completion of transaction. This URL shouldn't contain any query parameters or Ip address. This URL takes higher precedence over the common return URL configured in your account settings.
- Value: <p>Example:- <br> https://shop.merchant.com </p>
- Tags: string

#### product_id:
- Description: An identifier for the product. Fits well for impulse purchase usecases.
- Value: <p>Example:- <br> John </p>
- Tags: string

#### gateway_id:
- Description: Specify your preferred gateway for this order. Refer to mapping [here](https://docs.juspay.in/resources/docs/dynamic-routing/dynamic-routing#enumerations-and-gateway-ids).
- Value: <p>Example:- <br> 15 </p>
- Tags: Number, Tag

#### 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: Line1 in the billing address
- Tags: string

#### billing_address_line2:
- Description: Line2 in the billing address
- Tags: string

#### billing_address_line3:
- Description: Line3 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
### Metadata Object:

#### metadata.JUSPAY:gateway_reference_id:
- Description: You will have to mandatorily pass this reference id if you created a gateway with gateway reference id on Juspay's dashboard.**** For detailed information check [here](https://juspay.io/sea/docs/ec-api-global/docs/resources/gateway-reference-id).
- Value: <p>Example:- <br> BUS </p>
- Tags: string, conditional

#### metadata.webhook_url:
- Description: Merchant can pass dynamic webhook URL in this field. The webhook authentication would be same as the one configured on the dashboard. Ex: **metadata.webhook_url=** **[https://merchant.juspay/response](https://merchant.juspay/response)** 
- Tags: String, Optional

#### metadata.txns.auto_capture:
- Description: A parameter to determine the capture method,

* Set to `false` for pre-auth and capture.
* Set to `true` for automatic capture.
- Tags: Boolean

#### metadata.txns.allow_card_no_3ds:
- Description: Parameter to define the authentication method,

* Set to `true` for no Two Factor Authentication(2FA) where transaction gets successful once it is initiated..
* Set to `false` for standard Two Factor Authentication(2FA).
- Tags: Boolean

#### txn_type:
- Description: Type of the transaction, please pass the following details1. AUTHENTICATION => To perform authentication only2. AUTHORIZATION => To perform authorization only3. CAPTURE => To Perform Standalone capture4. AUTHN_AUTHZ => To Perform Authentication and Authorization5. AUTHZ_CAPTURE => To Perform Authorization and capture
- Tags: String, Conditional
### User Defined Parameters (UDF):

#### udf1 , udf2 , udf3 , udf4, udf5:
- Description: User Defined Parameter (UDF)

This field can be used to send any user defined parameters

The UDF parameters for orders can be seen in the JUSPAY dashboard under each order
- Value: <p>Example:- <br>user5349</p>
- Tags: string (Upto 255 characters), No special characters supported

#### udf6 , udf7 , udf8 , udf9 , udf10:
- Description: User Defined Parameter (UDF)

This field can be used to send any user defined parameters

The UDF parameters for orders can be seen in the JUSPAY dashboard under each order
- Value: <p>Example:-<br>user_5349</p>
- Tags: string (Upto 255 characters), Special characters supported
## API Responses:
### 200:

#### status:
- Description: Status of order Example:- NEW
- Tags: string

#### status_id:
- Description: Status ID is a numeric id corresponding to the status value.
- Tags: integer

#### id:
- Description: Unique ID generated by Juspay for the given order
- Tags: string

#### order_id:
- Description: Order Id passed during order creation
- Tags: string

#### payment_links:
- Description: Https link using which user can open payment page and perform transaction against the order created
- Value:
  - **Web**:
    - Description: Deeplink for web payments
    - Tags: string
  - **Mobile**:
    - Description: Deeplink for mobile payments
    - Tags: string
  - **Iframe**:
    - Description: Deeplink for iframe payment
    - Tags: string
- Tags: JSON
### 400:

#### error_message:
- Description: Error message of the API response
- Value: sample response: Bad Request
- Tags: String

#### status:
- Description: Denotes what type of error message
- Value: Response: Bad Request
- Tags: String

#### error_info:
- Description: Detailed information on the error message
- Value:
  - **User_message**:
    - Description: Error message can be displayed to the user
    - Value: sample response: Mandatory fields are missing.
    - Tags: String
  - **Fields**:
    - Description: Denotes what exact parameter is missing in the request
    - Tags: Array
  - **Developer_message**:
    - Description: Accurate detailed information on the error message to the user
    - Value: sample response: Missing object reference id. Please pass valid object reference id.
    - Tags: String
  - **Category**:
    - Description: Denotes the type of category the error
    - Value: sample response: USER_ERROR
    - Tags: String
- Tags: JSON
### 401:

#### error_code:
- Description: Error code of the API response
- Value: sample response: access_denied
- Tags: String

#### status:
- Description: Denotes what type of error message
- Value: Response: error
- Tags: String

#### error_info:
- Description: Detailed information on the error message
- Value:
  - **User_message**:
    - Description: Error message can be displayed to the user
    - Value: sample response: Unauthorized fields are missing.
    - Tags: String
  - **Developer_message**:
    - Description: Accurate detailed information on the error message to the user
    - Value: sample response: Invalid API Key
    - Tags: String
  - **Category**:
    - Description: Denotes the type of category the error
    - Value: sample response: USER_ERROR
    - Tags: String
- Tags: JSON



## 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 | 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"}} |