Installation

This section describes how to connect the WebSDK to your project, what dependencies are required, and how to get started. The full list of parameters (including schemaId, clientKey, callbacks, and theme) is in the “Parameters” section. For details on the purpose and secure handling of clientKey, see “Working with clientKey”. To process results, use the KYC session status REST API.

Quick start (plain HTML/JS)

The simplest method is to include the widget library via a <script> tag and call window.KYCWidget.setupKYC(...) on a button click.

index.html

<!DOCTYPE html>
<html lang="en">
<head>
  <meta charset="UTF-8" />
  <title>KYC Widget Example</title>
  <!-- Include widget library -->
  <script src="https://kyc.nv.global/lib/widget-lib.js" defer crossorigin="anonymous"></script>
</head>
<body>
  <button id="btn">Open KYC Widget</button>

  <!-- Widget initialization -->
  <script>
    const schemaId  = "SCHEMA_ID";            // required: ID of your verification schema
    const clientKey = "ENCRYPTED_CLIENT_KEY"; // required: client key (see clientKey)

    function openWidget() {
      if (!window.KYCWidget) {
        console.error("KYCWidget is not loaded yet");
        return;
      }

      window.KYCWidget.setupKYC({
        schemaId,                     // use schemaId (deprecated: scenarioId)
        clientKey,
        theme: "light",               // 'light' or 'dark'
        closeCb: () => console.log("CLOSE CALLBACK"),
        successCb: (payload) => {
          console.log("SUCCESS CALLBACK", payload);
          // payload contains session data; for detailed status use API /kyc/session/status
        },
      });
    }

    document.getElementById("btn").addEventListener("click", openWidget);
  </script>
</body>
</html>

Where to get schemaId? It is the ID of your verification schema (scenario) — for example “passport + selfie with document”. You’ll find it in the dashboard when configuring a schema.

Lazy loading script (plain JS)

If you want to load the library only on first use, use a dynamic loader:

<script>
  function loadKYCWidgetScript(callback) {
    if (window.KYCWidget) { callback(); return; }
    if (document.getElementById("kyc-widget-script-id")) return;

    const s = document.createElement("script");
    s.id = "kyc-widget-script-id";
    s.src = "https://kyc.nv.global/lib/widget-lib.js";
    s.defer = true;
    s.crossOrigin = "anonymous";
    s.onload = callback;
    document.head.appendChild(s);
  }

  function openKYCWidget() {
    window.KYCWidget.setupKYC({
      schemaId:  "SCHEMA_ID",
      clientKey: "ENCRYPTED_CLIENT_KEY",
      theme: "light",
      closeCb: () => console.log("CLOSE CALLBACK"),
      successCb: (payload) => console.log("SUCCESS CALLBACK", payload),
    });
  }

  document.addEventListener("DOMContentLoaded", () => {
    const button = document.getElementById("open-widget-btn");
    loadKYCWidgetScript(() => { button.disabled = false; });
    button.addEventListener("click", openKYCWidget);
  });
</script>

<button id="open-widget-btn" disabled>Open KYC Widget</button>

React: connecting via <script> (universal)

Suitable if you don’t want to use the npm package. Script is loaded dynamically:

import { useState, useEffect, useCallback } from "react";

function App() {
  const [widgetLoaded, setWidgetLoaded] = useState(false);

  const openWidgetHandler = () => {
    window.KYCWidget.setupKYC({
      schemaId:  "SCHEMA_ID",
      clientKey: "ENCRYPTED_CLIENT_KEY",
      theme: "light",
      closeCb: () => console.log("CLOSE CALLBACK"),
      successCb: (payload) => console.log("SUCCESS CALLBACK", payload),
    });
  };

  const loadWidgetScript = useCallback(() => {
    if (window.KYCWidget || document.getElementById("kyc-widget-script-id")) {
      setWidgetLoaded(true);
      return;
    }
    const script = document.createElement("script");
    script.id = "kyc-widget-script-id";
    script.src = "https://kyc.nv.global/lib/widget-lib.js";
    script.defer = true;
    script.crossOrigin = "anonymous";
    script.onload = () => setWidgetLoaded(true);
    document.head.appendChild(script);
  }, []);

  useEffect(() => {
    loadWidgetScript();
  }, [loadWidgetScript]);

  return (
    <>
      {widgetLoaded && (
        <button onClick={openWidgetHandler}>Open KYC Widget</button>
      )}
    </>
  );
}

export default App;

React: connecting via npm package

If you prefer a component approach, use the kyc-widget package.

  1. Install:
npm i kyc-widget
  1. Use component:
import { useState } from "react";
import { KycWidget } from "kyc-widget";

function App() {
  const [isOpen, setIsOpen] = useState(false);

  return (
    <>
      <button onClick={() => setIsOpen(true)}>Open</button>

      <KycWidget
        schemaId="SCHEMA_ID"
        clientKey="ENCRYPTED_CLIENT_KEY"
        isOpen={isOpen}
        closeCb={() => setIsOpen(false)}
        successCb={(payload) => console.log("SUCCESS CALLBACK", payload)}
      />
    </>
  );
}

export default App;

What to pass into setupKYC(...)

Minimum:

  • schemaId *(string, required)* — ID of your KYC schema/scenario;
  • clientKey *(string, required)* — client key used to link your user/account to the KYC session;
  • theme *(string, optional)* — 'light' or 'dark';
  • closeCb() — callback when widget closes;
  • successCb(payload) — callback when verification completes; for detailed processing retrieve status via /kyc/session/status.

Full parameter list is in the “Parameters” section.

clientKey: backend generation

clientKey is any string up to 36 characters; it’s used to associate your user ID with the KYC session. The key is encrypted on your backend using the “scenario secret key” and sent to the widget in encrypted form.

Node.js (AES-256-CBC encryption example):

const crypto = require("crypto");

let clientKey = "anyString"; // up to 36 chars
const password = "scenarioSecretKey"; // scenario secret key (backend only)

const key = crypto.createHash("sha256").update(password).digest().subarray(0, 32);
const iv  = crypto.randomBytes(16);

const cipher = crypto.createCipheriv("aes-256-cbc", key, iv);
const encrypted = Buffer.concat([cipher.update(clientKey, "utf8"), cipher.final()]);

const encryptedBase64 = Buffer.concat([iv, encrypted]).toString("base64");
console.log(`Encrypted & Base64: ${encryptedBase64}`);

Never store scenarioSecretKey in the browser; generate clientKey only on backend and pass only the encrypted value to frontend. Details are in “Working with clientKey”.

Checking the result

After successCb, you can retrieve the full session status via REST API:

  • Check session status — /kyc/session/status
  • Create session / process images — /kyc/session/create, /kyc/process

Request examples and responses are in the KYC API section.

If the widget returns errors (e.g., “[document] text fields not visible” or “[fraud] image printed”), you can find error descriptions and handling recommendations in the error reference.