> For the complete documentation index, see [llms.txt](https://docs.hyperswitch.io/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.hyperswitch.io/integration-guide/account-management/beta-embeddable-components/integration-reference.md).

# Integration Reference

This SDK allows you to embed the Hyperswitch connector configuration directly into your React application. It uses a provider pattern to manage authentication sessions via JWTs, ensuring your API keys never leak to the client.

Repository URL: <https://github.com/juspay/hyperswitch-control-center-embedded>

Demo URL: <https://embedded-ssr.netlify.app/>

## Prerequisites & Compatibility

Before you begin, ensure your environment meets the following requirements:

* Runtime: Node.js (v18+)
* Framework: React (v18.x - 20.x)
* Hyperswitch Credentials:
  * `API-Key` (Can be generated via Control Center)
  * `Profile-ID` (The specific merchant profile you are configuring)
* Support:
  * ✅ Vite
  * ✅ Webpack
  * ✅ Next.js
  * ✅ Create React App

## Step 1: Backend Setup (Server-Side)

Security Warning: Never expose your Hyperswitch API-Key on the frontend. You must create a backend endpoint that acts as a proxy

**Frontend → requests session → Your Backend → requests token (using API Key) → Hyperswitch API**

### Step 1.1: Create the Token Endpoint

Create a route (e.g., /embedded/hyperswitch) in your backend application.

Required Headers for Hyperswitch Call:

* api-key: Your secret API key.
* X-profile-id: The specific profile ID you want the embedded component to access.

{% code title="server.js" %}

```javascript
const express = require('express');
const cors = require('cors');
const axios = require('axios');

const app = express();
const port = 4000;

app.use(cors());
app.use(express.json());

const HYPERSWITCH_BASE_URL = 'https://app.hyperswitch.io/api';

app.get('/embedded/hyperswitch', async (req, res) => {
  try {
    const response = await axios.get(
      `${HYPERSWITCH_BASE_URL}/api/embedded/token`,
      {
        headers: {
          'api-key': 'YOUR_ACTUAL_API_KEY_HERE',
          'X-profile-id': 'YOUR_PROFILE_ID_HERE',
          'Content-Type': 'application/json'
        }
      }
    );

    console.log('Hyperswitch Token Generated:', response.data);

    res.json({
      success: true,
      message: 'Token fetched successfully',
      data: response.data
    });

  } catch (error) {
    console.error('Error fetching token:', error.message);

    res.status(500).json({
      error: 'Failed to fetch token from Hyperswitch API',
      details: error.message
    });
  }
});

app.listen(port, () => {
  console.log(`Server listening at http://localhost:${port}`);
});

```

{% endcode %}

## Step 2: Choose Your Integration Method

You must choose one:

* Core (JavaScript Only / HTML)
* React Integration

### 2A: HTML-JS Integration

**2A.1 Install the package:**

```bash
npm install @juspay-tech/hyperswitch-control-center-embed-core
```

**2A.2 Import the SDK in Your Application**

Import (ES Module):

```javascript
import { loadHyperswitch } from "@juspay-tech/hyperswitch-control-center-embed-core";
```

**OR**

Import (CommonJS):

```javascript
const { loadHyperswitch } = require("@juspay-tech/hyperswitch-control-center-embed-core");
```

**2A.3: Example app.js Implementation**

```javascript
import { loadHyperswitch } from "@juspay-tech/hyperswitch-control-center-embed-core";

document.addEventListener("DOMContentLoaded", async function () {

  const fetchToken = async () => {
    try {
      const response = await fetch(
        "http://localhost:4000/embedded/hyperswitch",
        {
          method: "GET",
          headers: {
            "Content-Type": "application/json"
          }
        }
      );

      if (!response.ok) {
        return undefined;
      }

      const responseData = await response.json();
      const token = responseData.data?.token || responseData.token;

      return token;

    } catch (err) {
      return undefined;
    }
  };

  const hyperswitch = loadHyperswitch({
    fetchToken: fetchToken
  });

  const connectorConfig = hyperswitch.create("connectors", {
    url: "https://app.hyperswitch.io/api"
  });

  connectorConfig.mount("#hyperswitch-root");

});

```

### 2B: React Integration

**2B.1 Install the package:**

```bash
npm install @juspay-tech/hyperswitch-control-center-embed-react
```

**2B.2 Import the SDK in Your Application**

```javascript
import React, { useState } from 'react';
import './App.css';
import 'tailwindcss/tailwind.css';
import { loadHyperswitch } from '@juspay-tech/hyperswitch-control-center-embed-core';
import {
  HyperswitchProvider,
  ConnectorConfiguration
} from '@juspay-tech/hyperswitch-control-center-embed-react';
```

**2B.3 Example app.js Implementation**

Key Concept: The fetchToken function is lazy. It is called:

* When the component first mounts.
* Automatically whenever the SDK detects the session has expired (auto-refresh).

```javascript
function App() {
  const [errorMessage, setErrorMessage] = useState(null);

  const [hyperswitchInstance] = useState(() => {

    const fetchToken = async () => {
      try {
        const response = await fetch(
          'http://localhost:4000/embedded/hyperswitch',
          {
            method: "GET",
            headers: {
              'Content-Type': 'application/json'
            }
          }
        );

        if (!response.ok) {
          const errorData = await response.json();
          const errorMsg = errorData.error || 'Network error fetching token';
          setErrorMessage(errorMsg);
          return undefined;
        }

        const responseData = await response.json();
        const token = responseData.data?.token || responseData.token;

        return token;

      } catch (err) {
        setErrorMessage(err.message);
        return undefined;
      }
    };

    return loadHyperswitch({
      fetchToken: fetchToken
    });

  });

  return (
    <div className="h-screen bg-gray-100 p-10 text-gray-700">
      {errorMessage ? (
        <div className="bg-red-100 border border-red-400 text-red-700 px-4 py-3 rounded mb-4">
          <strong>Error: </strong>
          <span>{errorMessage}</span>
        </div>
      ) : (
        <HyperswitchProvider hyperswitchInstance={hyperswitchInstance}>
          <ConnectorConfiguration url="https://app.hyperswitch.io/api" />
        </HyperswitchProvider>
      )}
    </div>
  );
}

export default App;

```

## API Reference

### 1. loadHyperswitch(options)

Initializes the SDK logic.

options.fetchToken () => Promise\<string | undefined>

* Required.
* A function that retrieves a fresh JWT from your backend.
* Should return the JWT string on success.
* Should return undefined on failure.

### 2. HyperswitchProvider

Context provider that holds the authentication state.

* **hyperswitchInstance**: The object returned by loadHyperswitch.

### 3. ConnectorConfiguration

The UI Component that renders the settings form.

* **url (string)**: The base URL for the Hyperswitch Dashboard API.
  * Sandbox:[ https://app.hyperswitch.io](https://app.hyperswitch.io/api)
  * Default:[ http://localhost:9000](http://localhost:9000)


---

# Agent Instructions
This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com.

## Querying This Documentation
If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter, and the optional `goal` query parameter:

```
GET https://docs.hyperswitch.io/integration-guide/account-management/beta-embeddable-components/integration-reference.md?ask=<question>&goal=<endgoal>
```

`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is optional and describes the broader end goal you are ultimately trying to accomplish on behalf of the user. GitBook uses it to tailor the answer towards what is most useful for that goal.

The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.