> ## Documentation Index
> Fetch the complete documentation index at: https://telr-docs.cashfree.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Telr Hosted Checkout

> Learn about the web integration for a Telr hosted payment page

## Telr Web Integration Guide

✅ Simplified Checkout: Telr Checkout is a pre-built Checkout Page by Telr to provide the most optimal payment experience. Accept payments from 120+ payment methods easily, and securely. Your customers are redirected to Telr Checkout to complete the Payment.

✅ Secure and PCI Compliant: Telr Checkout collects the data and submits to Telr servers securely, so, no PCI compliance requirements are required at your end.

✅ Personalised: Customise payment methods, branding, and much more to match the theme of your company.

### Requirements

* Create a Telr Merchant Account.
* Log in to the [merchant dashboard](https://telr.cashfree.com/merchants) and generate test keys from [Telr](https://telr.cashfree.com/merchants/pg/developers/api-keys).
* Generate API Keys - Client ID & Secret Key.
* Ensure you have whitelisted your website domain for integration. Read more [about Domain Whitelisting](/payments/online/go-live/whitelist).

Integration process consists of three essential steps: creating an order, opening the checkout page, and confirming the order. Below is a step-by-step guide for each part of the integration process.

### Step 1: Creating an Order

To integrate the Telr Payment Gateway, the first step is to create an Order. This must be done before any payment processing can occur.
Set up an endpoint on your server to handle order creation as you cannot call this api from client side.

##### API Request for Creating an Order

Here's a sample request for creating an order using your desired backend language. Telr offers backend SDKs to simplify the integration process.

You can find the SDKs [here](/api-reference/payments/sdk#payment-sdk).

<CodeGroup>
  ```javascript javascript theme={null}
  import { Cashfree } from "cashfree-pg";

  Cashfree.XClientId = {Client ID};
  Cashfree.XClientSecret = {Client Secret Key};
  Cashfree.XEnvironment = Cashfree.Environment.PRODUCTION;

  function createOrder() {
    var request = {
      "order_amount": "1",
      "order_currency": "INR",
      "customer_details": {
        "customer_id": "node_sdk_test",
        "customer_name": "",
        "customer_email": "example@gmail.com",
        "customer_phone": "9999999999"
      },
      "order_meta": {
        "return_url": "https://test.cashfree.com/pgappsdemos/return.php?order_id=order_123"
      },
      "order_note": ""
    }

  	Cashfree.PGCreateOrder("2023-08-01", request).then((response) => {
      var a = response.data;
      console.log(a)
    })
      .catch((error) => {
        console.error('Error setting up order request:', error.response.data);
      });
  }
  ```

  ```python python theme={null}
  from cashfree_pg.models.create_order_request import CreateOrderRequest
  from cashfree_pg.api_client import Cashfree
  from cashfree_pg.models.customer_details import CustomerDetails


  Cashfree.XClientId = {Client ID}
  Cashfree.XClientSecret = {Client Secret Key}
  Cashfree.XEnvironment = Cashfree.XSandbox
  x_api_version = "2023-08-01"

  def create_order():
          customerDetails = CustomerDetails(customer_id="123", customer_phone="9999999999")
          createOrderRequest = CreateOrderRequest(order_amount=1, order_currency="INR", customer_details=customerDetails)
          try:
              api_response = Cashfree().PGCreateOrder(x_api_version, createOrderRequest, None, None)
              print(api_response.data)
          except Exception as e:
              print(e)
  ```

  ```java java theme={null}
  import com.cashfree.*;

  Cashfree.XClientId = {Client Key};
  Cashfree.XClientSecret = {Client Secret Key};
  Cashfree.XEnvironment = Cashfree.SANDBOX;

  static void createOrder() {
    CustomerDetails customerDetails = new CustomerDetails();
    customerDetails.setCustomerId("123");
    customerDetails.setCustomerPhone("9999999999");

    CreateOrderRequest request = new CreateOrderRequest();
    request.setOrderAmount(1.0);
    request.setOrderCurrency("INR");
    request.setCustomerDetails(customerDetails);
    try {
  		Cashfree cashfree = new Cashfree();
      ApiResponse<OrderEntity> response = cashfree.PGCreateOrder("2023-08-01", request, null, null, null);
      System.out.println(response.getData().getOrderId());

    } catch (ApiException e) {
      throw new RuntimeException(e);
    }
  }
  ```

  ```go go theme={null}
  import (
    cashfree "github.com/cashfree/cashfree-pg/v3"
  )

  func createOrder() {

  clientId := {Client ID}
  clientSecret := {Client Secret Key}
  cashfree.XClientId = &clientId
  cashfree.XClientSecret = &clientSecret
  cashfree.XEnvironment = cashfree.SANDBOX

  request := cashfree.CreateOrderRequest{
  		OrderAmount: 1,
  		CustomerDetails: cashfree.CustomerDetails{
  			CustomerId:    "1",
  			CustomerPhone: "9999999999",
  		},
  		OrderCurrency: "INR",
  		OrderSplits:   []cashfree.VendorSplit{},
  	}
  	version := "2023-08-01"
  	response, httpResponse, err := cashfree.PGCreateOrder(&version, &request, nil, nil, nil)
  	if err != nil {
  		fmt.Println(err.Error())
  	} else {
  		fmt.Println(httpResponse.StatusCode)
  		fmt.Println(response)
      }   
  }
  ```

  ```csharp csharp theme={null}
  using cashfree_pg.Client;
  using cashfree_pg.Model;

  Cashfree.XClientId = {Client ID};
  Cashfree.XClientSecret = {Client Secret Key};
  Cashfree.XEnvironment = Cashfree.PRODUCTION;
  var cashfree = new Cashfree();
  var xApiVersion = "2023-08-01";

  void CreateOrder() {
      var customerDetails = new CustomerDetails("123", null, "9999999999");
      var createOrdersRequest = new CreateOrderRequest(null, 1.0, "INR", customerDetails);
      try {
          // Create Order
          var result = cashfree.PGCreateOrder(xApiVersion, createOrdersRequest, null, null, null);
          Console.WriteLine(result);
          Console.WriteLine(result.StatusCode);
          Console.WriteLine((result.Content as OrderEntity));
      } catch (ApiException e) {
          Console.WriteLine("Exception when calling PGCreateOrder: " + e.Message);
          Console.WriteLine("Status Code: " + e.ErrorCode);
          Console.WriteLine(e.StackTrace);
      }
  }
  ```

  ```php php theme={null}
  \Cashfree\Cashfree::$XClientId = "<x-client-id>";
  \Cashfree\Cashfree::$XClientSecret = "<x-client-secret>";
  \Cashfree\Cashfree::$XEnvironment = Cashfree\Cashfree::$SANDBOX;

  $cashfree = new \Cashfree\Cashfree();

  $x_api_version = "2023-08-01";
  $create_orders_request = new \Cashfree\Model\CreateOrdersRequest();
  $create_orders_request->setOrderAmount(1.0);
  $create_orders_request->setOrderCurrency("INR");
  $customer_details = new \Cashfree\Model\CustomerDetails();
  $customer_details->setCustomerId("123");
  $customer_details->setCustomerPhone("9999999999");
  $create_orders_request->setCustomerDetails($customer_details);

  try {
      $result = $cashfree->PGCreateOrder($x_api_version, $create_orders_request);
      print_r($result);
  } catch (Exception $e) {
      echo 'Exception when calling PGCreateOrder: ', $e->getMessage(), PHP_EOL;
  }
  ```

  ```bash curl theme={null}
  curl --location 'https://sandbox.cashfree.com/pg/orders' \
  --header 'X-Client-Secret: {{clientKey}}' \
  --header 'X-Client-Id: {{clientId}}' 
  --header 'x-api-version: 2023-08-01' \
  --header 'Content-Type: application/json' \
  --header 'Accept: application/json' \
  --data-raw '{
    "order_amount": 10.10,
    "order_currency": "INR",
    "customer_details": {
      "customer_id": "USER123",
      "customer_name": "joe",
      "customer_email": "joe.s@cashfree.com",
      "customer_phone": "+919876543210"
    },
    "order_meta": { 
      "return_url": "https://b8af79f41056.eu.ngrok.io?order_id=order_123",
    }

  }'
  ```
</CodeGroup>

After successfully creating an order, you will receive a unique `order_id` and `payment_session_id` that you need for subsequent steps.

You can view all the complete api request and response for `/orders` [here](/api-reference/payments/latest/orders/create).

### Step 2: Opening the Checkout Page

<Warning>This step requires you to whitelist your domain with Telr. Read more [here](/payments/online/go-live/whitelist)</Warning>

#### 1. Include JS SDK in your client code

To integrate the Telr Checkout, you must include our JavaScript SDK within your JS file.

<CodeGroup>
  ```javascript CDN theme={null}
  <script src="https://sdk.cashfree.com/js/v3/cashfree.js"></script>
  ```

  ```javascript NPM theme={null}
  npm install @cashfreepayments/cashfree-js
  ```
</CodeGroup>

#### 2. Initialize the SDK

You need to initialise the variable using the Telr() function.

There are two modes applicable for this - `sandbox` or `production`.

Sandbox is used for test environment, whereas production is used for production mode.

<CodeGroup>
  ```javascript CDN theme={null}
  const cashfree = Cashfree({
      mode:"sandbox" //or production
  });
  ```

  ```javascript NPM theme={null}
  const cashfree = await load({
  	mode: "sandbox" //or production
  });
  //This load function returns a Promise that resolves with a newly created Cashfree object once Cashfree.js has loaded. If you call load in a server environment it will resolve to null.
  ```
</CodeGroup>

#### 3. Open Telr Checkout

To open the checkout, you can use `cashfree.checkout()` method. This method can take in following parameters -

<li>`paymentSessionId`(required) - Received from Create Order Response</li>
<li>`redirectTarget`(optional) - This parameter decides how the payment page will open up. You can provide the following values: </li>

| Property Value  | Description                                                     |
| --------------- | --------------------------------------------------------------- |
| \_self(default) | Opens the payment link in the same frame as it was clicked.     |
| \_blank         | Opens the payment link in a new window or tab.                  |
| \_top           | Opens the linked document in the full body of the window.       |
| \_modal         | Opens the payment link in a pop-up window on the current page.  |
| DOM element     | Opens the payment link directly within a specified DOM element. |

**Checkout Variants**
<li>`Redirect Checkout` - For redirectTarget `_self`, `_blank`, `_top` </li>
<li>`Popup Checkout` - For redirectTarget `_modal` </li>
<li>`Inline Checkout` - For redirectTarget `DOM element` </li>

**Note:** For Popup & Inline Checkout the usage differs slightly as you should handle the promise returned by cashfree.checkout() to execute additional code after the payment attempt

<CodeGroup>
  ```javascript Redirect - javascript {14-25} theme={null}
  <!DOCTYPE html>
  <html lang="en">
      <head>
          <meta charset="UTF-8">
          <meta name="viewport" content="width=device-width, initial-scale=1.0">
          <title>Telr Checkout Integration</title>
          <script src="https://sdk.cashfree.com/js/v3/cashfree.js"></script>
      </head>
      <body>
          <div class="row">
              <p>Click below to open the checkout page in current tab</p>
              <button id="renderBtn">Pay Now</button>
          </div>
          <script>
              const cashfree = Cashfree({
                  mode: "production",
              });
              document.getElementById("renderBtn").addEventListener("click", () => {
                  let checkoutOptions = {
                      paymentSessionId: "your-payment-session-id",
                      redirectTarget: "_self",
                  };
                  cashfree.checkout(checkoutOptions);
              });
          </script>
      </body>
  </html>
  ```

  ```javascript Redirect - React {4-18} theme={null}
  import { load } from "@cashfreepayments/cashfree-js";

  function Checkout() {
    let cashfree;
    var initializeSDK = async function () {
      cashfree = await load({
        mode: "production",
      });
    };
    initializeSDK();

    const doPayment = async () => {
      let checkoutOptions = {
        paymentSessionId: "your-payment-session-id",
        redirectTarget: "_self",
      };
      cashfree.checkout(checkoutOptions);
    };

    return (
      <div class="row">
        <p>Click below to open the checkout page in current tab</p>
        <button type="submit" class="btn btn-primary" id="renderBtn" onClick={doPayment}>
          Pay Now
        </button>
      </div>
    );
  }
  export default Checkout;
  ```

  ```javascript Popup - JavaScript {15-41} theme={null}
  <!DOCTYPE html>
  <html lang="en">
      <head>
          <meta charset="UTF-8">
          <meta name="viewport" content="width=device-width, initial-scale=1.0">
          <title>Telr Checkout Integration</title>
          <script src="https://sdk.cashfree.com/js/v3/cashfree.js"></script>
      </head>
      <body>
          <div class="row">
              <p>Click below to open the checkout page in popup</p>
              <button id="renderBtn">Pay Now</button>
          </div>
          <script>
              const cashfree = Cashfree({
                  mode: "production",
              });
              document.getElementById("renderBtn").addEventListener("click", () => {
                  let checkoutOptions = {
                      paymentSessionId: "your-payment-session-id",
                      redirectTarget: "_modal",
                  };
                  cashfree.checkout(checkoutOptions).then((result) => {
                      if(result.error){
                          // This will be true whenever user clicks on close icon inside the modal or any error happens during the payment
                          console.log("User has closed the popup or there is some payment error, Check for Payment Status");
                          console.log(result.error);
                      }
                      if(result.redirect){
                          // This will be true when the payment redirection page couldnt be opened in the same window
                          // This is an exceptional case only when the page is opened inside an inAppBrowser
                          // In this case the customer will be redirected to return url once payment is completed
                          console.log("Payment will be redirected");
                      }
                      if(result.paymentDetails){
                          // This will be called whenever the payment is completed irrespective of transaction status
                          console.log("Payment has been completed, Check for Payment Status");
                          console.log(result.paymentDetails.paymentMessage);
                      }
                  });
              });
          </script>
      </body>
  </html>
  ```

  ```javascript Popup - React {4-35} theme={null}
  import { load } from "@cashfreepayments/cashfree-js";

  function Checkout() {
    let cashfree;
    var initializeSDK = async function () {
      cashfree = await load({
        mode: "production",
      });
    };
    initializeSDK();

    const doPayment = async () => {
      let checkoutOptions = {
        paymentSessionId: "your-payment-session-id",
        redirectTarget: "_modal",
      };
      cashfree.checkout(checkoutOptions).then((result) => {
        if (result.error) {
          // This will be true whenever user clicks on close icon inside the modal or any error happens during the payment
          console.log("User has closed the popup or there is some payment error, Check for Payment Status");
          console.log(result.error);
        }
        if (result.redirect) {
          // This will be true when the payment redirection page couldnt be opened in the same window
          // This is an exceptional case only when the page is opened inside an inAppBrowser
          // In this case the customer will be redirected to return url once payment is completed
          console.log("Payment will be redirected");
        }
        if (result.paymentDetails) {
          // This will be called whenever the payment is completed irrespective of transaction status
          console.log("Payment has been completed, Check for Payment Status");
          console.log(result.paymentDetails.paymentMessage);
        }
      });
    };

    return (
      <div class="row">
        <p>Click below to open the checkout page in popup</p>
        <button type="submit" class="btn btn-primary" id="renderBtn" onClick={doPayment}>
          Pay Now
        </button>
      </div>
    );
  }
  export default Checkout;
  ```

  ```javascript Inline - Javascript {16-46} theme={null}
  <!DOCTYPE html>
  <html lang="en">
      <head>
          <meta charset="UTF-8">
          <meta name="viewport" content="width=device-width, initial-scale=1.0">
          <title>Telr Checkout Integration</title>
          <script src="https://sdk.cashfree.com/js/v3/cashfree.js"></script>
      </head>
      <body>
          <div class="row">
              <p>Click below to open the checkout page here</p>
              <button id="renderBtn">Pay Now</button>
              <div id="cf_checkout"></div>
          </div>
          <script>
              const cashfree = Cashfree({
                  mode: "production",
              });
              document.getElementById("renderBtn").addEventListener("click", () => {
                  let checkoutOptions = {
                      paymentSessionId: "your-payment-session-id",
                      redirectTarget: document.getElementById("cf_checkout"),
                      appearance: {
                          width: "425px",
                          height: "700px",
                      },
                  };
                  cashfree.checkout(checkoutOptions).then((result) => {
                      if(result.error){
                          // This will be true when there is any error during the payment
                          console.log("There is some payment error, Check for Payment Status");
                          console.log(result.error);
                      }
                      if(result.redirect){
                          // This will be true when the payment redirection page couldnt be opened in the same window
                          // This is an exceptional case only when the page is opened inside an inAppBrowser
                          // In this case the customer will be redirected to return url once payment is completed
                          console.log("Payment will be redirected");
                      }
                      if(result.paymentDetails){
                          // This will be called whenever the payment is completed irrespective of transaction status
                          console.log("Payment has been completed, Check for Payment Status");
                          console.log(result.paymentDetails.paymentMessage);
                      }
                  });
              });
          </script>
      </body>
  </html>
  ```

  ```javascript Inline - React {4-39} theme={null}
  import { load } from "@cashfreepayments/cashfree-js";

  function Checkout() {
      let cashfree;
      var initializeSDK = async function () {          
          cashfree = await load({
              mode: "production"
          });
      }
      initializeSDK();

      const doPayment = async () => {
          let checkoutOptions = {
              paymentSessionId: "your-payment-session-id",
              redirectTarget: document.getElementById("cf_checkout"),
              appearance: {
                  width: "425px",
                  height: "700px",
              },
          };
          cashfree.checkout(checkoutOptions).then((result) => {
              if(result.error){
                  // This will be true when there is any error during the payment
                  console.log("There is some payment error, Check for Payment Status");
                  console.log(result.error);
              }
              if(result.redirect){
                  // This will be true when the payment redirection page couldnt be opened in the same window
                  // This is an exceptional case only when the page is opened inside an inAppBrowser
                  // In this case the customer will be redirected to return url once payment is completed
                  console.log("Payment will be redirected");
              }
              if(result.paymentDetails){
                  // This will be called whenever the payment is completed irrespective of transaction status
                  console.log("Payment has been completed, Check for Payment Status");
                  console.log(result.paymentDetails.paymentMessage);
              }
          });
      };

      return (
          <div class="row">
              <p>Click below to open the checkout page here</p>
              <button type="submit" class="btn btn-primary" id="renderBtn" onClick={doPayment}>
                  Pay Now
              </button>
              <div id="cf_checkout"></div>
          </div>
      );
  }
  export default Checkout;
  ```
</CodeGroup>

### Step 3: Confirming the Payment

Once the payment is completed, you need to confirm whether the payment was successful by checking the order status.

<li>**Redirect Checkout**</li>

Once the payment process finishes, the user will be redirected to the return URL you provided during order creation (Step 1).
If no return URL is provided, customers will be redirected to a Telr's default page.

<Note>
  We recommend you to provide a return URL while creating an order. This will improve the overall user experience by ensuring your customers don’t land on
  broken or duplicated pages. Also, remember to add context of the order in your return url so that you can identify the order once customer has returned on
  this url.
</Note>

<li>**Popup & Inline Checkout**</li>

Once the payment process finishes, `cashfree.checkout()` function returns a promise which should be handled by the merchant

**Order Status - Verification**

To verify an order you can call our `/pg/orders` endpoint from your backend. You can also use our SDK to achieve the same.

<CodeGroup>
  ```go golang theme={null}
  version := "2023-08-01"
  response, httpResponse, err := cashfree.PGFetchOrder(&version, "<order_id>", nil, nil, nil)
  if err != nil {
  	fmt.Println(err.Error())
  } else {
  	fmt.Println(httpResponse.StatusCode)
  	fmt.Println(response)
  }
  ```

  ```javascript javascript theme={null}
  let version = "2023-08-01"
  Telr.PGFetchOrder(version, "<order_id>").then((response) => {
      console.log('Order fetched successfully:', response.data);
  }).catch((error) => {
      console.error('Error:', error.response.data.message);
  });

  ```

  ```php php theme={null}
  $x_api_version = "2023-08-01";
  try {
      $response = $cashfree->PGFetchOrder($x_api_version, "<order_id>");
      print_r($response);
  } catch (Exception $e) {
      echo 'Exception when calling PGFetchOrder: ', $e->getMessage(), PHP_EOL;
  }
  ```

  ```java java theme={null}
  import com.cashfree.*;
  //other code

  try {
      Cashfree.XClientId = "<x-client-id>";
      Cashfree.XClientSecret = "<x-client-secret>";
      Cashfree.XEnvironment = Telr.SANDBOX;

      Telr cashfree = new Telr();
      String xApiVersion = "2023-08-01";

      ApiResponse<OrderEntity> responseFetchOrder = cashfree.PGFetchOrder(xApiVersion, "<order_id>", null, null, null);
      System.out.println(response.getData().getOrderId());
  } catch (ApiException e) {
      throw new RuntimeException(e);
  }
  ```

  ```python python theme={null}
  from cashfree_pg.models.create_order_request import CreateOrderRequest
  from cashfree_pg.api_client import Telr
  from cashfree_pg.models.customer_details import CustomerDetails
  from cashfree_pg.models.order_meta import OrderMeta

  Cashfree.XClientId = "<x-client-id>"
  Cashfree.XClientSecret = "<x-client-secret>"
  Cashfree.XEnvironment = Telr.SANDBOX
  x_api_version = "2023-08-01"

  try:
      api_response = Telr().PGFetchOrder(x_api_version, "order_3242X4jQ5f0S9KYxZO9mtDL1Kx2Y7u", None)
      print(api_response.data)
  except Exception as e:
      print(e)

  ```

  ```csharp csharp theme={null}
  using cashfree_pg.Client;
  using cashfree_pg.Model;

  Cashfree.XClientId = "<x-client-id>";
  Cashfree.XClientSecret = "<x-client-secret>";
  Cashfree.XEnvironment = Telr.SANDBOX;
  var cashfree = new Telr();
  var xApiVersion = "2023-08-01";

  try {
      var result = cashfree.PGFetchOrder(xApiVersion, "<order_id>>", null, null);
      Console.WriteLine(result);
      Console.WriteLine(result.StatusCode);
      Console.WriteLine((result.Content as OrderEntity));
  } catch (ApiException e) {
      Console.WriteLine("Exception when calling PGFetchOrder: " + e.Message);
      Console.WriteLine("Status Code: " + e.ErrorCode);
      Console.WriteLine(e.StackTrace);
  }
  ```

  ```bash curl theme={null}
  curl --request GET \
       --url https://sandbox.cashfree.com/pg/orders/{order_id} \
       --header 'accept: application/json' \
       --header 'x-api-version: 2023-08-01'
       --header 'x-client-id: "YOUR APP ID GOES HERE"'
       --header 'x-client-secret: "YOUR SECRET KEY GOES HERE'
  ```
</CodeGroup>

**Note:** Prior to delivering your services to customers, it is crucial to verify the status of your order. Order should be verified using the Get Order API. When the order\_status is PAID you can consider that payment was successful.

### Testing

You should now have a working checkout button that opens Telr hosted payment page. If your integration isn’t working:

1. Open the Network tab in your browser’s developer tools.
2. Click the button and check the console logs.
3. Ensure correct environment and payment session id is being passed.
4. Use console.log() inside your button click listener to confirm whether the data is being passed correctly or not.