Nuvei WebSDK – React Integration Guide

A practical guide for integrating Nuvei WebSDK into a React application using the @nuvei-connect/nc-websdk package.

Prerequisites

| Item | Description | Example | |---|---|---| | Backend Access Token | A valid access token required by your backend to authenticate with Nuvei services. | 634f59fa0917b38886a2a781d24362c405:79ac4c2087d6053430e6abc2734f4c42fd | | Authentication Endpoint | Backend nuvei endpoint to create the MFE session. | POST https://nuvei_backend_url/auth/micro-frontend/tokens | | Module Name | The Nuvei module to be loaded by the WebSDK. | ONBOARDING,DOC_UTILITY | | Merchant / Partner Distinguishers | Values used to identify whether the current request is for a Merchant or Partner. | Partner: isGuest: false,partnerId(optional):'your_partner_id', Merchant: isGuest: true, emailAddress: "[email protected]" |

Step 1 - Installation

Install the Nuvei WebSDK package in your React project:

npm install @nuvei-connect/nc-websdk

or:

yarn add @nuvei-connect/nc-websdk

Important: Nuvei authorization credentials should remain on the backend. They should not be exposed in the React application.

Step 2 – Import the SDK

Import NuveiSDK and ModulesNameEnum. In App.tsx.

Create a reference for the DOM container where the SDK will be rendered.

import React, { useEffect, useRef } from "react";

import NuveiSDK, { ModulesNameEnum } from "@nuvei-connect/nc-websdk";

Step 3 – Mount the Nuvei WebSDK

Initialize the SDK once the container is available. Inside App.tsx.

  const containerRef = useRef<HTMLDivElement>(null);

  useEffect(() => {
  if (!containerRef.current) {
    return;
  }

  NuveiSDK.mount({
    config: {environment: "websdk_environment"},
    container: containerRef.current.id,
    componentName: ModulesNameEnum.ONBOARDING_PARTNER,
    fetchClientSession : async() => {
        const response = await fetch(`${backendApiUrl}/api/auth/session`, { method: "POST"});
        if (!response.ok) { throw new Error(`Session error: ${response.status}`);}
          return await response.json();
     },
    onError: (error: any) => { console.error("NuveiWebSDK Error:", error)},
  }).catch((error: any) => {
    console.error("NuveiWebSDK Mount Error:", error);
  });
}, []);

return (
  <div id="nuvei-websdk-container" ref={containerRef} style={{width: "100%",height: "100%" }}/>
);

Step 4. Backend Configuration

The backend then calls the Nuvei token/session endpoint : server.ts

app.post("/api/auth/session", async (_req: Request, res: Response) => {
  try {
    const response = await fetch('nuvei_auth_endpoint_for_mfe_token', {
      method: "POST",
      headers: {
        "Content-Type": "application/json",
        Authorization: 'your_provided_backend_token',
      },
      body: JSON.stringify({
        modules: [
          {
            name: "ONBOARDING",
          },
        ],
        isGuest: false,
      }),
    });

    const data = await response.json();

    return res.json(data);
  } catch (error) {
    console.log("error", error)  
  }
});

These are the minimum requirements needed to integrate the Nuvei Web SDK.

If additional configuration or advanced options are required, please refer to the sections below in this documentation for detailed configuration references and usage examples.

Loading Different Modules

The Nuvei WebSDK supports separate modules for different use cases:

| Module | Purpose | Component | | --------------- | ------------------------------- | -------------------------------------------- | | ONBOARDING | Merchant Onboarding and Merchant Invitation | ONBOARDING_MERCHANT / ONBOARDING_PARTNER | | DOC_UTILITY | Document utility operations | DOC_UTILITY |

For Onboarding, the backend authentication request and the SDK componentName determine whether the flow is for a Merchant or Partner.

a. Merchant Invitation

For Merchant Invitation, provide the following values when authenticating with the Nuvei backend:

• Module: ONBOARDING
• isGuest: false
• partnerId(required for partnerStaff, optional for nuveiStaff): Partner ID

Backend Authentication Request:

body: JSON.stringify({
  modules: [
    {
      name: "ONBOARDING",
    },
  ],
  isGuest: false,
  partnerId: "your_partner_id",
}),

Then, load the Partner onboarding component using:

NuveiSDK.mount({
  componentName: ModulesNameEnum.ONBOARDING_PARTNER,
});

b. Merchant Onboarding

For Merchant onboarding, provide the following values when authenticating with the Nuvei backend:

• Module: ONBOARDING
• isGuest: true
• emailAddress: Merchant email address
• partnerId(optional): Partner ID to which specific merchant belongs to

Backend Authentication Request:

body: JSON.stringify({
  modules: [
    {
      name: "ONBOARDING",
    },
  ],
  isGuest: true,
  emailAddress: "your_merchant_email_address"
}),

Then, load the Merchant onboarding component using:

NuveiSDK.mount({
  componentName: ModulesNameEnum.ONBOARDING_MERCHANT,
});

c. Document Utility

Document Utility is a separate module from Onboarding.

When using Document Utility:

• Module: DOC_UTILITY
• Component: ModulesNameEnum.DOC_UTILITY

Example:

NuveiSDK.mount({
  container: containerRef.current.id,
  componentName: ModulesNameEnum.DOC_UTILITY,
  config: {environment: "websdk_environment" , documentRequestId : 'your_document_request_id'},
});

The authentication/session request should include the module required by the Document Utility flow.

Session Lifecycle Callbacks

For applications that need full session lifecycle management, the SDK can receive:

a. fetchClientSession Creates or retrieves the each session required by the SDK to communicate with the Nuvei backend.

const fetchClientSession = async () => {
  const response = await fetch(`${apiBaseUrl}/api/auth/session`, {
    method: "POST",
  });

  if (!response.ok) {
    throw new Error(`Session error: ${response.status}`);
  }

  return await response.json();
};

b.refreshClientSession Refreshes the current session using the refresh token. The SDK can use this callback when the existing session is expired or approaching expiration

const refreshClientSession = async (refreshToken: string) => {
  const response = await fetch(`${apiBaseUrl}/api/auth/session/refresh`, {
    method: "POST",

    headers: {
      "Content-Type": "application/json",
    },

    body: JSON.stringify({
      refreshToken,
    }),
  });

  if (!response.ok) {
    throw new Error(`Session refresh error: ${response.status}`);
  }

  return await response.json();
};

c.destroySession Terminates the current session on the backend. This is typically used when the user logs out or when the SDK session needs to be explicitly invalidated.

const destroySession = async () => {
  const response = await fetch(`${apiBaseUrl}/api/auth/session/destroy`, {
    method: "POST",
  });

  if (!response.ok) {
    throw new Error(`Session destroy error: ${response.status}`);
  }

  return await response.json();
};

Modules Switching

Module switching should be implemented with one React page for each WebSDK module. In the demo project, the pages are exposed through these routes:

| Route | Page | WebSDK component | |---|---|---| | / | Redirects to the partner page | — | | /partner | Partner invitation | ModulesNameEnum.ONBOARDING_PARTNER | | /merchant | Merchant onboarding | ModulesNameEnum.ONBOARDING_MERCHANT | | /doc-utility | Document utility | ModulesNameEnum.DOC_UTILITY |

The partner page is the default page when the React application starts. The merchant and partner pages mount the onboarding modules. The document utility page is mounted separately and receives its documentRequestId from the URL.

1. Mount the partner and merchant modules

The partner page uses ONBOARDING_PARTNER and the merchant page uses ONBOARDING_MERCHANT. Both pages listen for the SWITCH_MODULE message.

NuveiSDK.mount({
  container: containerRef.current,
  componentName: ModulesNameEnum.ONBOARDING_PARTNER,
  config: { environment: "uat" },
  fetchClientSession,
  onMessage: (message: any) => {
    if (
      message.source === "NUVEI_IFRAME" &&
      message.action === "SWITCH_MODULE"
    ) {
      const documentRequestId =
        message.data?.payload?.documentRequestId;

      const query = documentRequestId
        ? `?documentRequestId=${encodeURIComponent(documentRequestId)}`
        : "";

      navigate(`/doc-utility${query}`);
    }
  },
});

For the merchant page, only the component name changes:

componentName: ModulesNameEnum.ONBOARDING_MERCHANT

The session request must also use the correct onboarding details for the page. For example, partner invitation uses isGuest: false, while merchant onboarding uses isGuest: true:

body: JSON.stringify({
  modules: [{ name: "ONBOARDING" }],
  isGuest: false,
}),

2. Mount Document Utility on its own page

The document utility page reads documentRequestId from the current URL and passes it to the SDK configuration:

const documentRequestId = new URLSearchParams(
  window.location.search,
).get("documentRequestId");

NuveiSDK.mount({
  container: containerRef.current,
  componentName: ModulesNameEnum.DOC_UTILITY,
  config: {
    environment: "uat",
    documentRequestId: documentRequestId ?? undefined,
  },
  fetchClientSession,
  onMessage: (message: any) => {
    if (
      message.source === "NUVEI_IFRAME" &&
      message.action === "SWITCH_MODULE"
    ) {
      navigate("/partner");
    }
  },
});

When an onboarding module sends SWITCH_MODULE, the app navigates to a URL such as:

/doc-utility?documentRequestId=your_document_request_id

The document utility page then uses that value to initialize the requested document flow. The backend session request for this page must include the DOC_UTILITY module:

body: JSON.stringify({
  modules: [{ name: "DOC_UTILITY" }],
  isGuest: true,
}),

Each page is responsible for mounting its own SDK component. The partner and merchant pages navigate to Document Utility with documentRequestId. The Document Utility page listens for SWITCH_MODULE and navigates back to the partner page.

Configuration References

| Property | Type | Example / Default | Configure in | Description | |---|---|---|---|---| | componentName | ModulesNameEnum | ModulesNameEnum.ONBOARDING_MERCHANT | NuveiSDK.mount() | SDK component to render. Use ONBOARDING_MERCHANT, ONBOARDING_PARTNER, or DOC_UTILITY. | | config.environment | "uat" \| "prod" | config inside NuveiSDK.mount() | Nuvei environment used by the WebSDK. This value must be provided inside the config object. | | config.requestId | string | "onboarding-request-123" | config inside NuveiSDK.mount() | Optional onboarding application or request identifier. Provide this inside config when continuing or loading a specific onboarding request. | | config.documentRequestId | string | "document-request-456" | config inside NuveiSDK.mount() | Optional Document Utility request identifier. Provide this inside config when operating on a specific document request. | | container | HTMLElement \| string | "nuvei-websdk-container" | NuveiSDK.mount() | DOM element or element ID where the SDK iframe will be rendered. | | fetchClientSession | () => Promise<IClientSession> | fetchClientSession | NuveiSDK.mount() | Required callback that requests a client session from your backend. | | refreshClientSession | (params: { refreshToken: string; accessToken: string }) => Promise<IClientRefreshSession> | refreshClientSession | NuveiSDK.mount() | Optional callback used to refresh an expired or expiring client session. | | destroySession | () => Promise<boolean> | destroySession | NuveiSDK.mount() | Optional callback used to invalidate or destroy the backend session. | | onReady | (instance) => void | onReady | NuveiSDK.mount() | Optional callback invoked when the SDK is initialized and ready. | | onError | (error: unknown) => void | onError | NuveiSDK.mount() | Optional callback invoked when the SDK encounters an error. | | onMessage | (message: unknown) => void | onMessage | NuveiSDK.mount() | Optional callback for messages received from the SDK iframe. Use this if the SDK integration provides completion events through messages. | | apiBaseUrl | string | "/api" | Frontend application configuration | Base URL of your own backend API. This is not a Nuvei SDK configuration property. | | nuveiBackendUrl | string | "https://<nuvei-host>/dev2/v1/auth/micro-frontend/tokens" | Backend environment configuration | Nuvei session endpoint called by your backend. Keep this value on the server. | | isGuest | boolean | true or false | Backend session request | Indicates whether the session is being created for a guest merchant or an authenticated partner. | | emailAddress | string | "[email protected]" | Backend session request | Email address used by Nuvei to identify the current user or merchant. | | partnerId | string | "partner_123" | Backend session request | Optional partner identifier used for partner-related onboarding flows. |