🧩 WebSDK

The Nuvei WebSDK allows third-party applications to easily embed Micro Frontends into their applications.

📦 Installation

Install the SDK from npm:

npm install @nuvei-connect/nc-websdk

🚀 Usage

Import and mount the SDK. The container must be mounted in the DOM before calling NuveiSDK.mount():

import NuveiSDK from "@nuvei-connect/nc-websdk";

const instance = await NuveiSDK.mount({
  componentName: moduleName,
  container: containerRef.current,

  config: {
    environment: "preprod",
  },
});

The mount() call returns an SDK instance. Keep the instance and call destroy() when the host component is unmounted or the integration is no longer needed.

⚛️ React example

Keep the SDK container rendered independently from the loading state. If a loader conditionally replaces the container, containerRef.current will be null when the SDK is initialized.

"use client";

import { useEffect, useRef, useState } from "react";
import NuveiSDK from "@nuvei-connect/nc-websdk";

async function fetchClientSession() {
  const response = await fetch("/api/sdk/session", { method: "POST" });
  return response.json();
}

async function refreshClientSession(payload: {
  accessToken: string;
  refreshToken: string;
}) {
  const response = await fetch("/api/sdk/session/refresh", {
    method: "POST",
    headers: { "Content-Type": "application/json" },
    body: JSON.stringify(payload),
  });
  return response.json();
}

async function destroySession() {
  const response = await fetch("/api/sdk/session", { method: "POST" });
  return response.ok;
}

export function MicroFrontend({ componentName }: { componentName: string }) {
  const containerRef = useRef<HTMLDivElement>(null);
  const instanceRef = useRef<any>(null);
  const [isLoading, setIsLoading] = useState(true);

  useEffect(() => {
    let isMounted = true;

    async function initialize() {
      if (!containerRef.current) return;

      const instance = await NuveiSDK.mount({
        componentName,
        container: containerRef.current,
        fetchClientSession,
        refreshClientSession,
        destroySession,
        config: { environment: "preprod" },
      });

      if (!isMounted) {
        instance.destroy();
        return;
      }

      instanceRef.current = instance;
      setIsLoading(false);
    }

    void initialize();

    return () => {
      isMounted = false;
      instanceRef.current?.destroy();
      instanceRef.current = null;
    };
  }, [componentName]);

  return (
    <>
      {isLoading && <div>Loading…</div>}
      <div ref={containerRef} />
    </>
  );
}

🔐 Authentication

By default, the SDK handles authentication automatically. No authentication configuration is required from the consuming application.

If the consuming application wants to manage authentication itself, it can provide authentication callbacks. These callbacks override the SDK's default authentication behavior.

const instance = await NuveiSDK.mount({
  componentName: moduleName,
  container: containerRef.current,

  config: {
    environment: "preprod",
  },

  fetchClientSession: getSessionId,
  refreshClientSession: refreshSessionId,
  destroySession: handleSessionDestroy,
});

⚙️ Configuration

| Property | Required | Description | | ---------------------- | -------- | --------------------------------------------------- | | componentName | Yes | Micro Frontend component to load | | container | Yes | DOM element where the component will be mounted | | config.environment | Yes | SDK environment (local, dev, preprod, prod) | | fetchClientSession | No | Custom authentication/session callback | | refreshClientSession | No | Custom session refresh callback | | destroySession | No | Custom session destroy/logout callback | | config.requestId | No | Onboarding request ID; falls back to the host URL | | config.documentRequestId | No | Document Utility request ID; falls back to the host URL |

Note: Authentication callbacks are optional. If they are not provided, the SDK uses its built-in authentication flow.