---
page_source: https://juspay.io/sea/docs/hyper-checkout-sea/web/base-sdk-integration/session
page_title: Session API
---

## API Version: default


# Session API



This is a Server-to-Server API that takes order parameters as an input and returns the SDK payload and the payment link. This also creates order in the Juspay system.



<div class="buttons">
  <a target="_blank"        href="https://app.getpostman.com/run-collection/c8aefd7595e3e2efd760?action=collection%2Fimport">
          <span aria-label="Run in Postman" class="img"
           role="button" tabindex="0">
              <img src="https://run.pstmn.io/button.svg"
              alt="Run in Postman"
              height="auto"
              width="auto"/>
          </span>        <br/><br/>
  </a>
</div>

## Endpoints:
- Sandbox: https://sandbox.juspay.in/session

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

## 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 LIR2UUZEQzhFQTY0OUU5QTIxQzNFNTQwNkFDMEZCOg==</p>
- Tags: Base64 Encoded username:password, required
## Headers:

#### x-merchantid:
Merchant ID provided by Juspay
- Tags: String, Required

#### Content-Type:
Value: application/json
- Tags: String, Required

#### x-routing-id:
* We recommend passing `customer_id`as `x-routing-id`
* For **guest checkout** , pass alternative identifier such as an `order_id` or `cart_id` to track the payment session lifecycle.

> **Note**
> You must pass the **same** `x-routing-id`**value in all related API calls**  for a given **customer/session** .



> **Warning**
> Failing to pass `x-routing-id` may lead to inconsistent behavior or API failures.


- Tags: String, Required
## Sample Code Snippets:
### Code Snippets:

#### Shell Code Snippet:

```shell
curl --location --request POST 'https://api.juspay.in/session' \
--header 'Authorization: Basic base_64_encoded_api_key==' \
--header 'x-merchantid: your_merchant_id' \
--header 'x-routing-id: customer_1122'\
--header 'Content-Type: application/json' \
--data-raw '{
    "order_id": "testing-order-one",
    "amount": "1.0",
    "customer_id": "testing-customer-one",
    "customer_email": "test@mail.com",
    "customer_phone": "9876543210",
    "payment_page_client_id": "your_client_id",
    "action": "paymentPage",
    "return_url": "https://shop.merchant.com",
    "description": "Complete your payment",
    "first_name": "John",
    "last_name": "wick"
}'

```

#### Javascript Code Snippet:

```javascript
import fetch from 'node-fetch';

const apiKey = "<your_api_key>";
const merchantId = "<your_merchant_id>";
const clientId = "<your_client_id>";
const xRoutingId = "<your_routing_id>";
const authorization = "Basic " + Buffer.from(apiKey + ":").toString("base64");

var requestPayload = JSON.stringify({
  "order_id": "testing-order-one",
  "amount": "1.0",
  "customer_id": "testing-customer-one",
  "customer_email": "test@mail.com",
  "customer_phone": "9876543210",
  "payment_page_client_id": clientId,
  "action": "paymentPage",
  "return_url": "https://shop.merchant.com",
  "description": "Complete your payment",
  "theme": "dark",
  "first_name": "John",
  "last_name": "wick"
});

var requestOptions = {
  method: 'POST',
  headers: {
    'Authorization': authorization,
    'x-merchantid': merchantId,
    'Content-Type': 'application/json',
    'x-routing-id': xRoutingId
  },
  body: requestPayload
};

fetch("https://api.juspay.in/session", requestOptions)
  .then(response => response.text())
  .then(result => console.log(result))
  .catch(error => console.log('error', error));

```

#### Java Code Snippet:

```java
import okhttp3.*;
import org.json.JSONObject;

public JSONObject createSession() {
  JSONObject payload = new JSONObject();
  try {
    String apiKey = "<your_api_key>";
    String clientId = "<your_client_id>";
    String merchantId = "<your_merchant_id>";
    String xRoutingId = "<your_routing_id>";


    payload.put("order_id", "testing-order-id-four");
    payload.put("amount", "1.0");
    payload.put("customer_id", "9876543201");
    payload.put("customer_email", "test@mail.com");
    payload.put("customer_phone", "9876543201");
    payload.put("payment_page_client_id", clientId);
    payload.put("action", "paymentPage");
    payload.put("offer_code", "testingCode");
    payload.put("first_name", "john");
    payload.put("last_name", "wick");
    payload.put("description", "Order Description");

    OkHttpClient okHttpClient = new OkHttpClient();

    MediaType mediaType = MediaType.parse("application/json");
    RequestBody requestBody = RequestBody.create(mediaType, payload.toString());

    String authorization = "Basic " + Base64.getEncoder()
      .encodeToString(apiKey.concat(":").getBytes());

    Request request =
        new Request.Builder()
            .url("https://api.juspay.in/session")
            .method("POST", requestBody)
            .addHeader("x-merchantid", merchantId)
            .addHeader("Authorization", authorization)
            .addHeader("Content-Type", "application/json")
            .addHeader("x-routing-id", xRoutingId)
            .build();
    Response response = okHttpClient.newCall(request).execute();
    JSONObject responseJSON = new JSONObject(response.body().string());
    return responseJSON;

  } catch (Exception e) {
    e.printStackTrace();
  }

}

```

#### PHP - pecl_http Code Snippet:

```php - pecl_http
<?php
$client = new http\Client;
$request = new http\Client\Request;
$request->setRequestUrl('https://api.juspay.in/session');
$request->setRequestMethod('POST');
$body = new http\Message\Body;
$body->append('{
    "order_id": "testing-order-one",
    "amount": "1.0",
    "customer_id": "testing-customer-one",
    "customer_email": "test@mail.com",
    "customer_phone": "9876543210",
    "payment_page_client_id": "your_client_id",
    "action": "paymentPage",
    "return_url": "https://shop.merchant.com",
    "description": "Complete your payment",
    "first_name": "John",
    "last_name": "wick"
}');
$request->setBody($body);
$request->setOptions(array());
$request->setHeaders(array(
  'Authorization' => 'Basic base_64_encoded_api_key==',
  'x-merchantid' => 'your_merchant_id',
  'Content-Type' => 'application/json',
  'x-routing-id' => 'your_x_routing_id'
));
$client->enqueue($request)->send();
$response = $client->getResponse();
echo $response->getBody();

```

#### PHP - http_Request2 Code Snippet:

```php - http_request2
<?php
require_once 'HTTP/Request2.php';
$request = new HTTP_Request2();
$request->setUrl('https://api.juspay.in/session');
$request->setMethod(HTTP_Request2::METHOD_POST);
$request->setConfig(array(
  'follow_redirects' => TRUE
));
$request->setHeader(array(
  'Authorization' => 'Basic base_64_encoded_api_key==',
  'x-merchantid' => 'your_merchant_id',
  'Content-Type' => 'application/json',
  'x-routing-id' => 'your_x_routing_id'
));
$request->setBody('{\n    
    "order_id": "testing-order-one",\n    
    "amount": "1.0",\n    "customer_id": "testing-customer-one",\n    
    "customer_email": "test@mail.com",\n    
    "customer_phone": "9876543210",\n    
    "payment_page_client_id": "your_client_id",\n    
    "action": "paymentPage",\n    
    "return_url": "https://shop.merchant.com",\n    
    "description": "Complete your payment",\n    
    "first_name": "John",\n    
    "last_name": "wick"\n
}');
try {
  $response = $request->send();
  if ($response->getStatus() == 200) {
    echo $response->getBody();
  }
  else {
    echo 'Unexpected HTTP status: ' . $response->getStatus() . ' ' .
    $response->getReasonPhrase();
  }
}
catch(HTTP_Request2_Exception $e) {
  echo 'Error: ' . $e->getMessage();
}

```

### Sample Request & Response:

#### Request:
```json
{
  "order_id": "testing-order-one",
  "amount": "1.0",
  "customer_id": "testing-customer-one",
  "customer_email": "test@mail.com",
  "customer_phone": "9876543210",
  "payment_page_client_id": "yourClientId",
  "action": "paymentPage",
  "return_url": "https://shop.merchant.com",
  "description": "Complete your payment",
  "first_name": "John",
  "last_name": "wick",
  "metadata.JUSPAY:gateway_reference_id": "Merchant_test"
}

```

#### Response:
```json
{
  "status": "NEW",
  "id": "ordeh_xxxxxxxxxxxxxxxxxxxx",
  "order_id": "testing-order-one",
  "payment_links": {
      "web": "https://api.juspay.in/orders/ordeh_xxxxxxxxxxxxxxxxxxxx/payment-page"
  },
  "sdk_payload": {
      "requestId": "12398b5571d74c3388a74004bc24370c",
      "service": "in.juspay.hyperpay",
      "payload": {
          "clientId": "yourClientId",
          "amount": "1.0",
          "merchantId": "yourMerchantId",
          "clientAuthToken": "tkn_xxxxxxxxxxxxxxxxxxxxx",
          "clientAuthTokenExpiry": "2022-03-12T20:29:23Z",
          "environment": "production",
          "options.getUpiDeepLinks": "true",
          "lastName": "wick",
          "action": "paymentPage",
          "customerId": "testing-customer-one",
          "returnUrl": "https://shop.merchant.com",
          "currency": "INR",
          "firstName": "John",
          "customerPhone": "9876543210",
          "customerEmail": "test@mail.com",
          "orderId": "testing-order-one",
          "description": "Complete your payment"
      }
  }
}

```

## Body Parameters:
### Basic Parameters:

#### order_id:
- Description: Unique Identifier for the order. Should be Alphanumeric with character length less than 21. 

Make sure to go through [Best Practices for OrderId](https://juspay.io/sea/docs/hypercheckout-global/android/resources/order--transaction/edit)
- Value: <p>Example:- <br> order-id-9876580 </p>
- Tags: string, required, Max Length :21 

#### 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.
- Value: <p>Example:- <br> 1.00 </p>
- Tags: Double, required

#### 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 installment payments 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, Max Length :300 

#### customer_email:
- Description: Email address of the customer. If the backend gateway requires it, then you must send this value.**Constraints :** You are allowed to use alphanumeric characters and the following special characters:`!#$%&'*+-/=?^_.{|}~`@`

`_`and `.` cannot appear at the beginning or end of the local part of the email address (before and after the `@`symbol).
- Value: <p>Example:- <br> test@gmail.com</p>
- Tags: string, required, Max Length :300 

#### customer_phone:
- Description: Mobile number or fixed line number of the customer. If the backend gateway requires it, then you must send this value. We recommend passing a 10-digit number without including the "+91" or any mobile country code at the beginning. 
- Value: <p>Example:- <br> 9999999912</p>
- Tags: string, required, Max Length :300 

#### payment_page_client_id:
- Description: A unique identifier of merchant. This is available in welcome e-mail shared by Juspay
- Value: <p>Example:- <br> sampleMerchantId </p>
- Tags: string, required

#### action:
- Description: Value "paymentPage" is to start the Hypercheckout interface.Value "paymentManagement" for deleting saved cards and linking/unlinking wallets.
- Value: <p>Example:- <br> paymentPage </p>
- Tags: string, required

#### return_url:
- Description: A fully qualified URL on 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 takes higher precedence over the common return URL configured in your account settings.

**NOTE** :

1. URL shouldn't contain any query parameters or Ip address.
2. URL should be a valid HTTPS endpoint that is reachable from Juspay servers.
3. Return URL should not redirect to a different URL.
4. Please ensure to pass a valid return URL in the session API call or configure it on the Juspay Dashboard. Not doing the same will lead the SDK not being closed post transaction completion.
- Value: <p>Example:- <br> https://shop.merchant.com </p>
- Tags: string, required, Max Length :255 

#### first_name:
- Description: First Name of customer. This value will be used for customer identification.**Constraints :** You are allowed to use alphanumeric characters and the following special characters: `().-_`
- Value: <p>Example:- <br> John </p>
- Tags: string, Max Length :255 

#### last_name:
- Description: Last name of customer. This value will be used for customer identification.**Constraints :** You are allowed to use alphanumeric characters and the following special characters: `().-_`
- Value: <p>Example:- <br> Wick </p>
- Tags: string, Max Length :255 

#### Currency:
- Description: Currency code of the transaction
- Value:  AED
- Tags: String, Optional

#### description:
- Description:  Description for order to be displayed to the user on amountBar. 
- Value:   <p>Example:- <br> Complete your payment </p>
- Tags: String, Max Length :255 

#### language:
- Description: This field specifies the language in which the payment page will be displayed.

> **Note**
> The default language is **English (EN)** .
> 
> To display the payment page in another language, first configure the required strings in the Studio Dashboard. Then pass the corresponding language key:
> 
> “EN” English“TH” Thai“VI” Vietnamese“ID” Bahasa“KO” Korean


- Tags: String, Optional
### Metadata Object:

#### metadata.JUSPAY:gateway_reference_id:
- Description: **Use this parameter only when you have use case of gateway reference ID.** For detailed information check [here](https://docs.juspay.in/resources/docs/common-resources/gateway-reference-id).
- Value: <p>Example:- <br> BUS </p>
- Tags: string, Max Length :255 
### Mandate Parameters:

#### options.create_mandate:
- Description: Enum: 'REQUIRED' , "OPTIONAL'.

Defines what kind mandate support is available during a session. Required to create a Mandate.

Chose between the follow values based upon requirements :-

* REQUIRED : Mandate is must for completing transaction. Only instruments which support Mandate will be shown
* OPTIONAL : Mandate is a user choice for completing transaction.
- Value: <p>Example:- <br>OPTIONAL </p>
- Tags: string, Required

#### mandate.max_amount:
- Description: This is the maximum amount which can be debited via mandate. Required, only when amount type is variable. If amount type is fixed, amount parameter itself will be considered as max amount.
- Value: <p>Example:- <br>1000.0</p>
- Tags: Double, Required, Max Length :8 

#### mandate.start_date:
- Description: Mandate start date in UNIX EPOCH timestamp (UTC timezone). The start date has to be today's date
- Value: <p>Example:- <br>1633087969</p>
- Tags: string, Required, Max Length :10 

#### mandate.end_date:
- Description: Mandate end date in UNIX EPOCH timestamp (UTC timezone). Post end date, mandate will move to **EXPIRED**  state and recurring mandate will not be allowed. By default value will be Mandate start date + 30 years


- Value: <p>Example:- <br>1633088989</p>
- Tags: string, Required, Max Length :10 

#### mandate.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** 

**Default:** `ASPRESENTED`

**Note:** 1. Daily is not supported by Billdesk and Paytm (For cards)2. In UPI AutoPay, ONETIME frequency, Mandate is valid only for 90 Days
- Value: <p>Example:- <br>ASPRESENTED</p>
- Tags: string

#### mandate.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. For Razorpay, rule_value will be considered as the last date of the week/month/year. For Paytm, rule_value will be considered as today's date/day
- Value: <p>Example:- <br>1</p>
- Tags: string

#### mandate.amount_rule:
- Description: Data type **ENUM: FIXED, VARIABLE** . By default, it is considered as VARIABLE. In case of FIXED **amount_rule** 
- Value: <p>Example:- <br>FIXED</p>
- Tags: string

#### mandate.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
- Value: <p>Example:- <br>false</p>
- Tags: Boolean

#### mandate.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.
- Value: <p>Example:- <br>false</p>
- Tags: Boolean
### 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, Max Length :255 

#### 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, Max Length :255 
## API Responses:
### 200:

#### sdk_payload:
- Description: Process SDK Call Payload. This is supposed to be passed to your frontend application to open the Hypercheckout screen.
- Tags: JSON

#### payment_links:
- Description: Https link using which user can open the Hypercheckout screen and perform transaction against the order created
- Tags: string

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

#### status:
- Description: Status of order
- Value: <p>Example:- <br> NEW </p>
- Tags: string
### 400:

#### status:
- Description: Bad Request
- Tags: string

#### error_code:
- Description: Details of keys missing
- Value: <p>Example:- <br> Mandatory fields are missing </p>
- Tags: string

#### error_message:
- Description: Further Details of keys missing
- Tags: string
### 401:

#### status:
- Description: error
- Tags: string

#### error_code:
- Description: access_denied
- Tags: string
### 404:

#### status:
- Description: error
- Tags: string

#### error_code:
- Description: Internal server Error
- Tags: string
### 500:

#### status:
- Description: error
- Tags: string

#### error_code:
- Description: Internal server Error
- Tags: string