Skip to main content
@vouchmark/widget-react-native wraps the Vouchmark widget in a native WebView, with camera and microphone access enabled for document scans and liveness checks. It ships both a full-screen VouchmarkWidget and a VouchmarkModal.

​
Installation

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

​
Peer dependencies

The package requires react-native-webview: 
npm install react-native-webview
For iOS, run cd ios && pod install after installation.

​
Quick start

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

export function KybScreen() {
  return (
    <VouchmarkWidget
      widgetId="wgt_your_widget_id"
      publicKey="live_pk_your_public_key"
      environment="live"
      applicant={{
        email: "applicant@example.com",
        businessName: "Acme Ltd",
      }}
      onSuccess={(applicant) => {
        navigation.navigate("Dashboard", { applicantId: applicant.id });
      }}
      onAbandon={() => {
        navigation.goBack();
      }}
      onError={(error) => {
        Alert.alert("Verification error", error.message);
      }}
    />
  );
}

​
Props

PropTypeRequiredDescription
widgetIdstringYesWidget ID from the dashboard. Must match the widget’s environment (see Environments).
publicKeystringYesPublishable key: test_pk_… for sandbox, live_pk_… for live.
environment"sandbox" | "live"YesMust match the key prefix and widget: "sandbox" with test_pk_…, "live" with live_pk_….
applicantApplicantInputNoPre-fill applicant fields.
referenceIdstringNoYour internal reference ID.
sessionTokenstringNoSigned server token for secure mode.
localestringNoLanguage. Default "en".
presentationStyle"fullScreen" | "modal"NoPresentation hint passed to the widget.
onSuccess(applicant: ApplicantResult) => voidNoFires on approval.
onAbandon() => voidNoFires when user closes early.
onError(error: WidgetError) => voidNoFires on unrecoverable error.
onStepCompleted(step: StepResult) => voidNoFires after each module.
To show the widget as a modal instead of full-screen: 
import { useState } from "react";
import { VouchmarkModal } from "@vouchmark/widget-react-native";

export function KybButton() {
  const [visible, setVisible] = useState(false);

  return (
    <>
      <Button title="Start KYB" onPress={() => setVisible(true)} />
      <VouchmarkModal
        visible={visible}
        widgetId="wgt_..."
        publicKey="live_pk_..."
        environment="live"
        onSuccess={(applicant) => {
          setVisible(false);
          // handle success
        }}
        onAbandon={() => setVisible(false)}
        onDismiss={() => setVisible(false)}
      />
    </>
  );
}

​
Permissions

The widget may need camera access for liveness checks and document scans. Add to your app config:

​
iOS (Info.plist)

<key>NSCameraUsageDescription</key>
<string>Camera access is needed for identity verification</string>
<key>NSPhotoLibraryUsageDescription</key>
<string>Photo library access is needed for document upload</string>

​
Android (AndroidManifest.xml)

<uses-permission android:name="android.permission.CAMERA" />
<uses-permission android:name="android.permission.READ_EXTERNAL_STORAGE" />

​
Expo support

The package works with Expo (managed workflow) when react-native-webview is installed via expo install: 
npx expo install react-native-webview
npm install @vouchmark/widget-react-native

​
Environment variables

Copy .env.example to .env and set:
VariableExampleDescription
EXPO_PUBLIC_API_URLhttps://api.vouchmark.com/v1Vouchmark API base URL (include /v1). Same host for staging and production.
EXPO_PUBLIC_VOUCHMARK_WIDGET_IDkyb_… or wgt_…Widget ID from the dashboard — same environment as your key.
EXPO_PUBLIC_VOUCHMARK_PUBLIC_KEYtest_pk_… or live_pk_…Publishable key from developer settings.
EXPO_PUBLIC_VOUCHMARK_ENVsandbox or liveMust match the key and widget: sandbox with test_pk_…, live with live_pk_….
EXPO_PUBLIC_API_URL=https://api.vouchmark.com/v1
EXPO_PUBLIC_VOUCHMARK_WIDGET_ID=kyb_your_widget_id
EXPO_PUBLIC_VOUCHMARK_PUBLIC_KEY=test_pk_your_key
EXPO_PUBLIC_VOUCHMARK_ENV=sandbox
The WebView loads the widget from https://widget.vouchmark.com by default. That page bootstraps against https://api.vouchmark.com/v1. All three widget credentials must align — see Environments. After changing .env, restart Metro with a clean cache: npx expo start -c.

​
Platform support

PlatformMinimum version
iOS13.0+
AndroidAPI 21 (5.0)+
ExpoSDK 49+