SurePass Video KYC React Native SDK

A React Native SDK for integrating SurePass Video KYC verification into your app. It runs the entire video-based KYC flow inside a secure WebView on Android and iOS, exposed as a single imperative call.

Installation

npm install @surepass/videokyc-rn-sdk react-native-webview react-native-permissions react-native-safe-area-context
# iOS
cd ios && pod install

react-native-webview, react-native-permissions, and react-native-safe-area-context are peer dependencies — install them in your app.

Platform setup

The SDK requests camera, microphone, and location at runtime, but it cannot declare them for you.

Android

Add to android/app/src/main/AndroidManifest.xml:

<uses-permission android:name="android.permission.INTERNET" />
<uses-permission android:name="android.permission.CAMERA" />
<uses-permission android:name="android.permission.MODIFY_AUDIO_SETTINGS" />
<uses-permission android:name="android.permission.RECORD_AUDIO" />
<uses-permission android:name="android.permission.ACCESS_FINE_LOCATION" />
<uses-permission android:name="android.permission.ACCESS_COARSE_LOCATION" />

MODIFY_AUDIO_SETTINGS is required — the WebView's microphone capture (WebRTC) needs it in addition to RECORD_AUDIO. Without it, the verification page reports "microphone access required" even when the OS permission is granted.

Ensure minSdkVersion is 24 or higher in android/build.gradle.

iOS

Add the usage descriptions to ios/<App>/Info.plist:

<key>NSCameraUsageDescription</key>
<string>Camera access is required for video KYC verification.</string>
<key>NSMicrophoneUsageDescription</key>
<string>Microphone access is required for video KYC verification.</string>
<key>NSLocationWhenInUseUsageDescription</key>
<string>Location access is required for video KYC verification.</string>

Enable the react-native-permissions handlers you use by adding this to the top of your ios/Podfile (see the react-native-permissions setup):

require_relative '../node_modules/react-native-permissions/scripts/setup'

setup_permissions([
  'Camera',
  'Microphone',
  'LocationWhenInUse',
])

Set the iOS deployment target to 13.0+ (WKWebView getUserMedia needs a recent iOS; 14.3+ recommended).

Usage

First, mount VideoKycProvider once at your app root (it hosts the verification modal):

import { VideoKycProvider } from '@surepass/videokyc-rn-sdk';

export default function App() {
  return (
    <VideoKycProvider>
      {/* the rest of your app */}
    </VideoKycProvider>
  );
}

Then start the flow from anywhere:

import {
  startSurepassVideoKyc,
  Env,
  VideoKycStatus,
  type VideoKycModel,
} from '@surepass/videokyc-rn-sdk';

const result = await startSurepassVideoKyc({
  token: 'your_surepass_api_token',
  env: Env.sandbox, // or Env.prod
  workflowId: 'your_workflow_id',
  email: '[email protected]',
  fullName: 'John Doe',
  mobileNumber: '9876543210', // 10-digit number, no country-code prefix
  scriptParameterValue: {
    // Optional — custom params forwarded to your workflow script. Use the keys
    // your workflow expects; omit entirely if it takes none.
    name: 'john doe',
    loan_type: 'home loan',
    company: 'spaceX',
  },
  onInitialized: (model: VideoKycModel) => {
    // Fired once the Video KYC session is initialized.
    console.log(`User: ${model.userId}, session: ${model.sessionId}`);
  },
});

switch (result?.status) {
  case VideoKycStatus.success:
    console.log(`KYC completed — session ${result.sessionId}`);
    break;
  case VideoKycStatus.cancelled:
    console.log('KYC cancelled by the user');
    break;
  case VideoKycStatus.error:
    console.log(`KYC error: ${result.errorMessage}`);
    break;
  default: // undefined/null — dismissed before a terminal status
    console.log('Flow dismissed before reaching a terminal status');
}

startSurepassVideoKyc presents the flow in a full-screen modal (hosted by VideoKycProvider) and resolves when it ends. If the provider isn't mounted, the call resolves with VideoKycStatus.error.

Parameters

| Parameter | Required | Description | | --------------- | :------: | -------------------------------------------------------- | | token | ✅ | Your SurePass API authentication token. | | env | ✅ | Env.sandbox or Env.prod. | | workflowId | ✅ | Your SurePass workflow id. | | email | ✅ | User's email address. | | fullName | ✅ | User's full name. | | mobileNumber | ✅ | User's 10-digit mobile number (no country-code prefix). | | scriptParameterValue | — | Custom key/value params forwarded to your workflow script (sent as script_parameter_value). Keys are defined by your workflow. | | onInitialized | — | Callback receiving the VideoKycModel on initialization.|

The VideoKycModel contains userId, workflowId, sessionId, videoKycUrl, and the optional workflowSessionId, eventType, and signature.

scriptParameterValue is send-only: it is forwarded to your workflow script via the create-user call and is not returned through onInitialized or the result. Your app already supplies these values, so keep them in your own state if you need them after the flow.

Result

startSurepassVideoKyc() resolves to a SurepassVideoKycResult | null. It is null if dismissed before a terminal status; otherwise:

• status — VideoKycStatus.success, cancelled, or error. (VideoKycStatus.failed exists in the enum but is reserved and not currently emitted — failures surface as error.)
• sessionId — the session id for tracking (when available).
• errorMessage — populated for setup/API failures when status is error.

Verify completion server-side. A success result means the in-flow verification reached its completion redirect on the device. Treat it as advisory and confirm the final KYC outcome server-side (via the SurePass APIs/webhooks using sessionId) before granting access.

How it works

When you call startSurepassVideoKyc, the SDK requests permissions, makes two authenticated SurePass API calls (create-user, then initiate-video-kyc), and only then opens the WebView. If permissions are denied or either call fails, it resolves with VideoKycStatus.error before any WebView appears — so token and workflowId must be valid for the selected env.

License

Released under the MIT License — see LICENSE.