Skip to main content

Integration Reference

This SDK allows you to embed the OrchestratorX 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/orchestratorxplatform/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)
  • OrchestratorX 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 OrchestratorX 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) → OrchestratorX API

Step 1.1: Create the Token Endpoint​

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

Required Headers for OrchestratorX 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://admin.orchestratorx.com/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('OrchestratorX 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 OrchestratorX 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 { loadOrchestratorX } from "@juspay-tech/hyperswitch-control-center-embed-core";

OR

Import (CommonJS):

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

2A.3: Example app.js Implementation

import { loadOrchestratorX } 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 = loadOrchestratorX({
    fetchToken: fetchToken
  });

  const connectorConfig = hyperswitch.create("connectors", {
    url: "https://admin.orchestratorx.com/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 { loadOrchestratorX } from '@juspay-tech/hyperswitch-control-center-embed-core';
import {
  OrchestratorXProvider,
  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 loadOrchestratorX({
      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>
      ) : (
        <OrchestratorXProvider hyperswitchInstance={hyperswitchInstance}>
          <ConnectorConfiguration url="https://admin.orchestratorx.com/api" />
        </OrchestratorXProvider>
      )}
    </div>
  );
}

export default App;

API Reference​

1. loadOrchestratorX(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. OrchestratorXProvider​

Context provider that holds the authentication state.

  • hyperswitchInstance: The object returned by loadOrchestratorX.

3. ConnectorConfiguration​

The UI Component that renders the settings form.