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

## API Version: default


# Session API  



This is a Server-to-Server API which accepts order parameters as an input to create order in the Juspay systems and returns SDK payload and payment links.

‘Metadata’ is used to send custom params to the payment aggregators, irrespective of default parameters, The supported parameters


| Payment Gateways | Fields |
|---|---|
| CCAVENUE_V2 | metadata.CCAVENUE_V2:promo_code |
| BILLDESK | metadata.BILLDESK:AdditionalInfo3 |
| BILLDESK | metadata.BILLDESK:AdditionalInfo4 |
| FREECHARGE | metadata.FREECHARGE:campaignCode |
| GOCASHFREE | metadata.CASHFREE:metadata1 |
| HSBC_UPI | metadata.HSBC_UPI:addInfo |
| MIGS | metadata.MIGS:vpc_AddendumData |
| MIGS | metadata.MIGS:vpc_OrderInfo |
| OLAMONEY | metadata.OLAMONEY:couponCode |
| PAYTM | metadata.PAYTM:PROMO_CAMP_ID |
| PAYTM | metadata.PAYTM:CUST_ID |
| PAYTM | metadata.PAYTM:MERC_UNQ_REF |
| PAYTM_V2 | metadata.PAYTM_V2:MERC_UNQ_REF |
| PAYTM_V2 | metadata.PAYTM_V2:CUST_ID |
| TATAPAY | metadata.TATAPAY: merchantTxnMetadata |
| PAYU | metadata.PAYU:offer_key |
| PAYU | metadata.PAYU:offer_auto_apply |
| PAYU | metadata.PAYU:udf1 |
| PAYU | metadata.PAYU:udf2 |
| PAYU | metadata.PAYU:udf3 |
| PAYU | metadata.PAYU:udf4 |
| PAYU | metadata.PAYU:udf5 |
| PHONEPE | metadata.PHONEPE:merchantContext |
| RAZORPAY | metadata.RAZORPAY:notes[cust_id] |
| RAZORPAY | metadata.RAZORPAY:notes[cust_name] |
| RAZORPAY | metadata.RAZORPAY:offer_id |
| RAZORPAY | metadata.razorpay:PNR |
| RAZORPAY | metadata.razorpay:PaymentID |
| RAZORPAY | metadata.razorpay:lob |
| RAZORPAY | metadata.RAZORPAY:notes <br> Ex: metadata.RAZORPAY:notes={"key1":"value1","key2":"value2","key3":"value3"} |
| Subvention Amount | metadata.subvention_amount |
| TPSL | metadata.TPSL:shoppingCartDetails |
| TPSL | metadata.TPSL:accountNo |
| ZAAKPAY | metadata.ZAAKPAY:productDescription |
| ZAAKPAY | metadata.ZAAKPAY:product1Description |
| PAYPAL | metadata.PAYPAL:landing_page |
| PAYPAL | metadata.PAYPAL:phone_number |
| PAYPAL | metadata.PAYPAL:country_code |
| PAYPAL | metadata.PAYPAL:first_name  |
| PAYPAL | metadata.PAYPAL:last_name  |
| PAYPAL | metadata.PAYPAL:experience_id |
| PAYPAL | metadata.PAYPAL:brand_name |
| PAYPAL | metadata.PAYPAL:additional_data |
| PAYPAL - For Link and Pay  | metadata.PAYPAL:lnp_product_name |
| PAYPAL - For Link and Pay  | metadata.PAYPAL:lnp_product_code |
| PAYPAL - For Link and Pay  | metadata.PAYPAL:lnp_charge_pattern |
| PAYPAL - For Link and Pay  | metadata.PAYPAL:direct_wallet_version |
| PAYPAL - For Link and Pay  | metadata.PAYPAL:purchase_category |
| AMAZONPAY | metadata.AMAZONPAY:sellerNote |




<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


#### Javascript Code Snippet:

```javascript
const authorization = "Basic " + Buffer.from(apiKey + ":").toString("base64");
```

#### Java Code Snippet:

```java
import java.util.Base64; String apiKey = "your_api_key"; String authorization = "Basic " + Base64.getEncoder().encodeToString((apiKey + ":").getBytes());
```

#### Node JS Code Snippet:

```node js
const apiKey = "your_api_key"; const authorization = "Basic " + Buffer.from(apiKey + ":").toString("base64");
```

#### Python Code Snippet:

```python
import base64 api_key = "your_api_key" authorization = "Basic " + base64.b64encode(f"{api_key}:".encode("utf-8")).decode("utf-8")
```

#### Ruby Code Snippet:

```ruby
require 'base64' api_key = "your_api_key" authorization = "Basic " + Base64.strict_encode64("#{api_key}:")
```

#### C# Code Snippet:

```c#
using System; using System.Text; string apiKey = "your_api_key"; string authorization = "Basic " + Convert.ToBase64String(Encoding.UTF8.GetBytes(apiKey + ":"));
```

#### PHP Code Snippet:

```php
$api_key = "your_api_key"; $authorization = "Basic " . base64_encode($api_key . ":");
```

- 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 '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 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'
  },
  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>";


    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")
            .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'
));
$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'
));
$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.io/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": "BRL",
          "firstName": "John",
          "customerPhone": "9876543210",
          "customerEmail": "test@mail.com",
          "orderId": "testing-order-one",
          "description": "Complete your payment"
      }
  }
}
```

## Body Parameters:
### Basic Parameters:

#### order_id:
- Description: It is a unique Identifier for the order. It should be Alphanumeric with character length less than 21. 

Make sure to go through [best practices for order_id](https://docs.juspay.in/resources/docs/common-resources/order--transaction)
- Value: <p>Example:- <br> order-id-9876580 </p>
- Tags: string, required, Max Length : 21 

#### amount:
- Description: It is the amount that the customer has to pay. It accepts 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.Minimum value of amount should be INR 1.
- Value: <p>Example:- <br> 1.00 </p>
- Tags: string, required

#### customer_id:
- Description: It is the unique identifier with which merchant refers to a customer object. It is used to access the saved payment methods, allow EMI transactions and setup subscriptions. In case of a guest login, it should be an empty string.
- Value: <p>Example:- <br> customer-id-007 </p>
- Tags: string, required, Max Length : 128

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

#### mobile_country_code:
- Description: Your mobile's country code. No need to add prefix ‘+’ in front of it.
- Value:  65
- Tags: String, Optional, Max Length :64

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

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

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

#### order_type:
- Description: Applicable only for TPV Orders.
- Value: TPV_PAYMENT
- Tags: String, Conditional

#### language:
- Description: This field tells which language the payment page should be displayed in.Example: english
- Tags: String

#### order_fullfillment_threshold_in_mins:
- Description: It only accepts integer values. For example, "60" is valid input but "60.00" is not valid.Minimum value of amount should be 1.
- 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

#### 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.
- Tags: String

#### metadata.bank_account_details:
- Description: Applicable for TPV Orders.

Either bank_account_number or bank_account_id is mandatory
- Value:
  - **Bank_account_number**:
    - Description: Customer Bank account
    - Tags: String, Required
  - **Bank_ifsc**:
    - Description: IFSC code of bank
    - Tags: String, Required
  - **Juspay_bank_code**:
    - Description: juspay bank code given in eligibility API. e.g. JP_HDFC
    - Tags: String, Optional
  - **Bank_beneficiary_name**:
    - Description: Name of account holder
    - Tags: String, Optional
  - **Bank_account_id**:
    - Description: bank account id provided by Juspay while storing bank account details
    - Tags: String, Conditional
  - **Bank_account_type**:
    - Description: Account Type of the Customer Account
    - Value: CURRENT or SAVINGS
    - Tags: String, Conditional
- Tags: Array, Conditional

#### metadata.expiryInMins:
- Description: Applicable for international merchants
- Tags: String

#### metadata.txns.allow_card_no_3ds:
- Description: Applicable for international merchants
- Tags: boolean
### 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.Please be informed that the value assigned to "**mandate.max_amount** " will be displayed to the user when they open any UPI apps for payment. The value assigned to "**amount** " field will be used to show the amount on our Hypercheckout page
- Value: <p>Example:- <br>1000.0</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. **Default:**  will be Mandate start date + 30 years
- Value: <p>Example:- <br>1633088989</p>
- Tags: string, Optional

#### 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: When frequency is passed as WEEKLY, FORTNIGHTLY, MONTHLY, BIMONTHLY, QUARTERLY, HALFYEARLY, or YEARLY then is it required that the exact day of the period should be passed. 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.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
### Mutual Fund Details:

#### mutual_fund_details:
- Description: This block contains the details of the Mutual Fund

NOTE: mutual_fund_details needs to be passed in a stringified format
- Value:
  - **MemberId**:
    - Description: Member Id with ICCL or ARN_RIA with RTA
    - Tags: String, Mandatory
  - **UserId**:
    - Description: Client Id with ICCL or USER_CODE with RTA
    - Tags: String, Mandatory
  - **MfPartner**:
    - Description: NSE/BSE/KFIN/CAMS
    - Tags: String, Mandatory
  - **OrderNumber**:
    - Description: Unique order number or application number of each MF
    - Tags: String, Mandatory
  - **Amount**:
    - Description: Individual MF amount within the array of MF being purchased in a single basket
    - Tags: String, Mandatory
  - **InvestmentType**:
    - Description: LUMPSUM/SIP
    - Tags: String, Mandatory
  - **SchemeCode**:
    - Description: Scheme Code of the MF (Mandatory for RTA reporting)
    - Tags: String, Optional
  - **FolioNumber**:
    - Description: Folio Number of the MF (Mandatory for RTA reporting)
    - Tags: String, Optional
  - **PanNumber**:
    - Description: PAN Number of the user, to be passed in UPPERCASE only (Mandatory for RTA reporting)
    - Tags: String, Optional
  - **AmcCode**:
    - Description: AMC Code of the MF
    - Tags: String, Optional
  - **IhNumber**:
    - Description: In-house Number of the SIP (Mandatory for K-Fin RTA)
    - Tags: String, Conditional
- Tags: List, Optional
## 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, Max Length : 21 

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

#### status:
- Description: Bad Request
- Tags: string, Max Length : 255

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

#### error_message:
- Description: Further Details of keys missing
- Tags: string, Max Length : 255
### 401:

#### status:
- Description: error
- Tags: string, Max Length : 255

#### error_code:
- Description: access_denied
- Tags: string, Max Length : 255
### 404:

#### status:
- Description: error
- Tags: string, Max Length : 255

#### error_code:
- Description: Internal server Error
- Tags: string, Max Length : 255
### 500:

#### status:
- Description: error
- Tags: string, Max Length : 255

#### error_code:
- Description: Internal server Error
- Tags: string, Max Length : 255


---

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


---

## API Version: enach


# 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


#### Javascript Code Snippet:

```javascript
const authorization = "Basic " + Buffer.from(apiKey + ":").toString("base64");
```

#### Java Code Snippet:

```java
import java.util.Base64; String apiKey = "your_api_key"; String authorization = "Basic " + Base64.getEncoder().encodeToString((apiKey + ":").getBytes());
```

#### Node JS Code Snippet:

```node js
const apiKey = "your_api_key"; const authorization = "Basic " + Buffer.from(apiKey + ":").toString("base64");
```

#### Python Code Snippet:

```python
import base64 api_key = "your_api_key" authorization = "Basic " + base64.b64encode(f"{api_key}:".encode("utf-8")).decode("utf-8")
```

#### Ruby Code Snippet:

```ruby
require 'base64' api_key = "your_api_key" authorization = "Basic " + Base64.strict_encode64("#{api_key}:")
```

#### C# Code Snippet:

```c#
using System; using System.Text; string apiKey = "your_api_key"; string authorization = "Basic " + Convert.ToBase64String(Encoding.UTF8.GetBytes(apiKey + ":"));
```

#### PHP Code Snippet:

```php
$api_key = "your_api_key"; $authorization = "Basic " . base64_encode($api_key . ":");
```

- 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 "enach" for loading eNACH registration page
- 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

#### service:
- Description: Pass this value only if you wish to load eNACH registration page.
- Value:  Value  = in.juspay.ec
- Tags: String, Conditional
### 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, Optional

#### 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. **Default:**  will be Mandate start date + 30 years
- Value: <p>Example:- <br>1633088989</p>
- Tags: string, Optional

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