@vouchmark/widget-react

React SDK for embedding the Vouchmark KYB (Know Your Business) verification widget.

Installation

npm install @vouchmark/widget-react
# or
pnpm add @vouchmark/widget-react
# or
yarn add @vouchmark/widget-react

Quick Start

Component Usage

Drop in the <VouchmarkWidget /> component to render a trigger button that opens the verification widget on click.

import { VouchmarkWidget } from "@vouchmark/widget-react";

function App() {
  return (
    <VouchmarkWidget
      widgetId="wgt_abc123"
      publicKey="pk_live_xxx"
      environment="live"
      applicant={{ email: "[email protected]", businessName: "Acme Inc" }}
      onSuccess={(result) => {
        console.log("Verification complete:", result);
      }}
      onError={(error) => {
        console.error("Widget error:", error);
      }}
    />
  );
}

Custom Trigger

Pass any React element as the trigger prop to use your own button or link.

<VouchmarkWidget
  widgetId="wgt_abc123"
  publicKey="pk_live_xxx"
  environment="live"
  trigger={<button className="my-btn">Start KYB</button>}
  onSuccess={(result) => console.log(result)}
/>

Hook Usage

Use useVouchmark() for imperative control without rendering a trigger element.

import { useVouchmark } from "@vouchmark/widget-react";

function VerifyButton() {
  const { open, close, isReady } = useVouchmark({
    widgetId: "wgt_abc123",
    publicKey: "pk_live_xxx",
    environment: "sandbox",
    onSuccess: (result) => console.log(result),
    onAbandon: () => console.log("User abandoned"),
  });

  return (
    <button onClick={open} disabled={!isReady}>
      Verify Business
    </button>
  );
}

API Reference

<VouchmarkWidget />

| Prop | Type | Required | Description | | --- | --- | --- | --- | | widgetId | string | Yes | Your Vouchmark widget ID | | publicKey | string | Yes | Your public API key | | environment | "sandbox" \| "live" | Yes | Target environment | | applicant | ApplicantInput | No | Pre-fill applicant data | | referenceId | string | No | Your internal reference ID | | sessionToken | string | No | Session token for resuming | | locale | string | No | Widget locale | | scriptSrc | string | No | Override the widget script URL (defaults to the jsDelivr CDN; set this to self-host or use the branded Vouchmark CDN) | | trigger | ReactNode | No | Custom trigger element | | autoOpen | boolean | No | Open widget on mount | | onSuccess | (applicant: ApplicantResult) => void | No | Called on successful verification | | onAbandon | () => void | No | Called when user closes widget | | onError | (error: WidgetError) => void | No | Called on error | | onStepCompleted | (step: StepResult) => void | No | Called when a step completes | | onReady | () => void | No | Called when widget is ready |

useVouchmark(config)

Returns { open, close, isReady } for imperative widget control.

Accepts the same props as <VouchmarkWidget /> except trigger, autoOpen, and onReady.

Types

All types are exported from the package:

import type {
  VouchmarkWidgetProps,
  UseVouchmarkConfig,
  UseVouchmarkReturn,
  ApplicantInput,
  ApplicantResult,
  WidgetError,
  StepResult,
} from "@vouchmark/widget-react";

License

MIT