@vouchmark/widget-js

Lightweight JavaScript SDK for embedding the Vouchmark KYB verification widget into any web application.

Installation

Script Tag (UMD)

<script src="https://cdn.jsdelivr.net/npm/@vouchmark/widget-js@1/dist/vouchmark.umd.js"></script>

The @1 pin tracks the latest 1.x release. Pin an exact version (for example @1.0.0) if you need byte-stable caching. Vouchmark also serves the bundle from its own CDN at https://js.vouchmark.com/v1/vouchmark.js — use that once it is provisioned for your account.

Package Manager

npm install @vouchmark/widget-js
# or
pnpm add @vouchmark/widget-js

Usage

Script Tag

<script src="https://cdn.jsdelivr.net/npm/@vouchmark/widget-js@1/dist/vouchmark.umd.js"></script>
<script>
  document.getElementById("verify-btn").addEventListener("click", function () {
    Vouchmark.open({
      widgetId: "wgt_abc123",
      publicKey: "pk_live_xyz",
      environment: "live",
      applicant: {
        email: "[email protected]",
        businessName: "Acme Corp",
      },
      onSuccess: function (result) {
        console.log("Verification complete:", result.status);
      },
      onAbandon: function () {
        console.log("User closed the widget");
      },
      onError: function (error) {
        console.error("Widget error:", error.code, error.message);
      },
      onStepCompleted: function (step) {
        console.log("Step completed:", step.moduleId, step.status);
      },
      onReady: function () {
        console.log("Widget is ready");
      },
    });
  });
</script>

ES Module

import { Vouchmark } from "@vouchmark/widget-js";
import type { VouchmarkConfig, ApplicantResult } from "@vouchmark/widget-js";

const config: VouchmarkConfig = {
  widgetId: "wgt_abc123",
  publicKey: "pk_live_xyz",
  environment: "live",
  onSuccess: (result: ApplicantResult) => {
    console.log("Verification complete:", result.status);
  },
  onAbandon: () => {
    console.log("User closed the widget");
  },
};

Vouchmark.open(config);

API

Vouchmark.open(config)

Opens the verification widget in a full-screen overlay.

Vouchmark.close()

Programmatically closes the widget overlay.

Vouchmark.isReady()

Returns true if the widget iframe has finished loading and is ready to interact.

Configuration

| Option | Type | Required | Description | |--------|------|----------|-------------| | widgetId | string | Yes | Widget ID from your Vouchmark dashboard | | publicKey | string | Yes | Publishable key (starts with pk_) | | environment | "sandbox" \| "live" | Yes | Target environment | | applicant | object | No | Pre-fill applicant information | | referenceId | string | No | Your internal reference ID | | sessionToken | string | No | Signed session token for secure mode | | locale | string | No | Locale code (default: "en") | | onSuccess | function | No | Called when verification completes | | onAbandon | function | No | Called when user closes the widget | | onError | function | No | Called on widget errors | | onStepCompleted | function | No | Called when a verification step completes | | onReady | function | No | Called when widget iframe is loaded |

Applicant Pre-fill

{
  applicant: {
    email: "[email protected]",
    businessName: "Acme Corp",
    registrationNumber: "RC12345",
    phone: "+2341234567890",
    tin: "1234567890",
    jurisdiction: "NG",
    industry: "fintech"
  }
}

Callbacks

onSuccess(result: ApplicantResult)

interface ApplicantResult {
  id: string;
  status: "approved" | "rejected" | "requires_review";
  riskScore: number | null;
  decisionReason: string | null;
  subject: Record<string, string>;
}

onError(error: { code: string; message: string })

Called when the widget encounters an error. The widget closes automatically.

onStepCompleted(step: { moduleId: string; status: string })

Called after each verification module completes (e.g., document upload, liveness check).

Keyboard Support

• Press Escape to close the widget (triggers onAbandon)

Browser Support

Works in all modern browsers (Chrome, Firefox, Safari, Edge).