---
page_title: Session API
product: Hypercheckout
platform: iFrame Web
page_source: https://juspay.io/in/docs/hyper-checkout/iframe-web/base-sdk-integration/session
openapi:
  default: https://juspay.io/in/docs/api/swagger?document=https%3A%2F%2Fjuspay.io%2Fin%2Fdocs%2Fhyper-checkout%2Fiframe-web%2Fbase-sdk-integration%2Fsession%3Fversion%3Ddefault
  v1: https://juspay.io/in/docs/api/swagger?document=https%3A%2F%2Fjuspay.io%2Fin%2Fdocs%2Fhyper-checkout%2Fiframe-web%2Fbase-sdk-integration%2Fsession%3Fversion%3Dv1
llms_txt: https://juspay.io/in/docs/llms.txt
product_llms_txt: https://juspay.io/in/docs/hyper-checkout/llms.txt
---

## Available API Versions

- [default](#api-version-default)
- [v1](#api-version-v1)

## 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:
- 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 the customer_id as the `x-routing-id`. If the customer is checking out as a guest, you can pass an alternative ID that helps track the payment session lifecycle. For example, this could be an Order ID or Cart ID.

> **Warning**
> This ID is associated with the customer. It plays a key role in ensuring consistency and maintaining connections across different systems. If you fail to pass the same `x-routing-id` for the same customer in all related API calls, it could lead to issues with API functionality. Therefore, it’s crucial that you use the same x-routing-id for all requests tied to the same customer.


- Value: customer_1122
- 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": "payu_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://docs.juspay.in/resources/docs/common-resources/order--transaction)
- Value: <p>Example:- <br> order-id-9876580 </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.
- Value: <p>Example:- <br> 1.00 </p>
- Tags: string, 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 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.**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

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

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

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

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

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

#### currency:
- Description: Currency for the order. Should only be passed when supported by the Payment Gateway and enabled in the Juspay Dashboard within EC Operations → PGCC → Select PG → Edit → Supported Currencies.

**Default Value if not passed:** INR**Note:** The value must be in Uppercase

Example: USD
- Tags: String, Case Sensitive
### 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
### 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: string, Required

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

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

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

#### 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:

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


---

## API Version: v1


# Session API



This is a Server-to-Server API that takes order parameters as an input and returns the SDK payload and the upi deep 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:
- 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 the customer_id as the `x-routing-id`. If the customer is checking out as a guest, you can pass an alternative ID that helps track the payment session lifecycle. For example, this could be an Order ID or Cart ID.

> **Warning**
> This ID is associated with the customer. It plays a key role in ensuring consistency and maintaining connections across different systems. If you fail to pass the same `x-routing-id` for the same customer in all related API calls, it could lead to issues with API functionality. Therefore, it’s crucial that you use the same x-routing-id for all requests tied to the same customer.


- Value: customer_1122
- 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",
    "options.get_upi_deep_links": "true"
}'

```

#### 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",
  "options.get_upi_deep_links": "true"
});

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");
    payload.put("options.get_upi_deep_links", "true");

    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",
    "options.get_upi_deep_links": "true"
}');
$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
    "options.get_upi_deep_links": "true"\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",
  "options.get_upi_deep_links": "true"
}
```

#### Response:
```json
{
  "status": "NEW",
  "id": "ordeh_xxxxxxxxxxxxxxxxxxxx",
  "order_id": "testing-order-one",
  "payment_links": {
    "web": "https://api.juspay.in/orders/ordeh_xxxxxxxxxxxxxxxxxxxx/payment-page",
    "expiry" : "null",
    "deep_link": "upi://pay?tr=3xxxxxxxxx&tid=PYxxxxx&mc=xxx&pa=pxxxxx&pn=xxxxxxx&am=1&cu=INR"
  },
  "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://docs.juspay.in/resources/docs/common-resources/order--transaction)
- Value: <p>Example:- <br> order-id-9876580 </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.
- Value: <p>Example:- <br> 1.00 </p>
- Tags: string, 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 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.**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

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

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

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

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

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

#### options.get_upi_deep_links:
- Description: Value "true" is to get the upi deep link in the response<p>Example:- <br> true </p>
- Tags: String
### 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
### 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: string, Required

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

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

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

#### 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:

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


---

## See Also

- [Pre-Requisites](https://juspay.io/in/docs/hyper-checkout/iframe-web/overview/pre-requisites)
- [Order Status API](https://juspay.io/in/docs/hyper-checkout/iframe-web/base-sdk-integration/order-status-api)