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.

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}`);
});

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:

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

2A.2 Import the SDK in Your Application

Import (ES Module):

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

OR

Import (CommonJS):

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

2A.3 : Example app.js Implementation

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:

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

2B.2 Import the SDK in Your Application

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).

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\

• 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
  • Default: http://localhost:9000