React Native

@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

Prop	Type	Required	Description
`widgetId`	`string`	Yes	Widget ID from the dashboard. Must match the widget’s `environment` (see Environments).
`publicKey`	`string`	Yes	Publishable key: `test_pk_…` for sandbox, `live_pk_…` for live.
`environment`	`"sandbox" \| "live"`	Yes	Must match the key prefix and widget: `"sandbox"` with `test_pk_…`, `"live"` with `live_pk_…`.
`applicant`	`ApplicantInput`	No	Pre-fill applicant fields.
`referenceId`	`string`	No	Your internal reference ID.
`sessionToken`	`string`	No	Signed server token for secure mode.
`locale`	`string`	No	Language. Default `"en"`.
`presentationStyle`	`"fullScreen" \| "modal"`	No	Presentation hint passed to the widget.
`onSuccess`	`(applicant: ApplicantResult) => void`	No	Fires on approval.
`onAbandon`	`() => void`	No	Fires when user closes early.
`onError`	`(error: WidgetError) => void`	No	Fires on unrecoverable error.
`onStepCompleted`	`(step: StepResult) => void`	No	Fires 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:

Variable	Example	Description
`EXPO_PUBLIC_API_URL`	`https://api.vouchmark.com/v1`	Vouchmark API base URL (include `/v1`). Same host for staging and production.
`EXPO_PUBLIC_VOUCHMARK_WIDGET_ID`	`kyb_…` or `wgt_…`	Widget ID from the dashboard — same environment as your key.
`EXPO_PUBLIC_VOUCHMARK_PUBLIC_KEY`	`test_pk_…` or `live_pk_…`	Publishable key from developer settings.
`EXPO_PUBLIC_VOUCHMARK_ENV`	`sandbox` or `live`	Must 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

Platform	Minimum version
iOS	13.0+
Android	API 21 (5.0)+
Expo	SDK 49+

Overview

Client SDKs

Server SDK

Installation

Peer dependencies

Quick start

Props

Permissions

iOS (`Info.plist`)

Android (`AndroidManifest.xml`)

Expo support

Environment variables

Platform support

​Installation

​Peer dependencies

​Quick start

​Props

​Modal presentation

​Permissions

​iOS (Info.plist)

​Android (AndroidManifest.xml)

​Expo support

​Environment variables

​Platform support

Installation

Peer dependencies

Quick start

Props

Modal presentation

Permissions

iOS (`Info.plist`)

Android (`AndroidManifest.xml`)

Expo support

Environment variables

Platform support