@surtai/idv

Official web SDK for Surt IDV: KYC identity verification.

The SDK opens the verify app in an overlay iframe. On mobile devices it goes straight to the camera flow (/intro); on desktop it shows a QR code so the user can hand off to their phone (/qrcode). It listens for postMessage events from the verify app and dispatches them to typed callbacks.

Install

npm install @surtai/idv
# or
pnpm add @surtai/idv
# or
yarn add @surtai/idv

No peer dependencies. Works in any browser bundle (React, Vue, Svelte, vanilla JS).

Quickstart

Callback API

import { SurtIDV } from '@surtai/idv';

const session = SurtIDV.init({
  token: 'PORTAL_JWT',
  onApproved: () => console.log('verified'),
  onRejected: () => console.log('rejected'),
  onCanceled: () => console.log('user closed'),
  onError: (e) => console.error(e.message),
});

// close programmatically
session.destroy();

Promise API

const result = await SurtIDV.verify({ token });

switch (result.status) {
  case 'approved':       /* user passed verification */ break;
  case 'rejected':       /* user failed verification */ break;
  case 'manual_review':  /* queued for human review */ break;
  case 'support':        /* user requested support */ break;
  case 'canceled':       /* user closed the modal */ break;
  case 'expired':        /* session expired */ break;
  case 'error':          /* console.error(result.error) */ break;
}

Options

| Option | Type | Default | Notes | |---|---|---|---| | token | string | required | Portal JWT issued by core-dd. | | baseUrl | string | https://identity.surt.com | Override the verify app origin. | | mode | 'mobile' \| 'desktop' | auto-detect | Force the mobile (/intro) or desktop (/qrcode) flow regardless of the device. | | container | HTMLElement | document.body | Mount target for the overlay. | | lang | string | from token | Locale override. Supported: en, es, pt. |

Callbacks

All callbacks are optional. Each maps directly to a postMessage event from the verify app.

| Callback | Fires when | |---|---| | onReady() | The verify app loaded inside the iframe. | | onApproved() | Verification passed ({ action: 'close', reason: 'approved' }). | | onRejected() | Verification failed. | | onManualReview() | Result deferred to human review. | | onSupport() | User requested support / session abandoned. | | onCanceled() | User tapped the close (X) button. | | onExpired() | Session expired. | | onError(e) | Network error, malformed token, unknown reason. e.message has details. |

How device detection works

The SDK picks mobile (direct camera flow) vs desktop (QR handoff) using the same heuristic as @surtai/faceguard:

1. No touch input → desktop.
2. Touch + viewport ≤ 1024px → mobile.
3. Touch + UA looks like an iPad (Macintosh UA, maxTouchPoints > 2) → mobile.
4. Touch + Android tablet (Android UA without Mobile) → mobile.
5. Everything else (touch laptops, Surface) → desktop.

Override with mode: 'mobile' | 'desktop' if you need to force one.

Overlay styling

| Mode | Layout | |---|---| | Mobile | Fullscreen overlay, solid #0D141A background. | | Desktop | Centered modal, 420×760, rgba(0,0,0,0.6) backdrop, 24px rounded corners. |

The iframe is created with allow="camera; microphone; geolocation", no sandbox attribute (cross-origin embedding is supported by the verify app's CSP).

Environments

| Env | Default origin | |---|---| | Production | https://identity.surt.com |

For QA/staging, pass baseUrl explicitly. For local development against pnpm dev:web from the surt-verify monorepo, use baseUrl: 'http://localhost:3000'.

Browser support

Modern Chromium, Firefox, and Safari. Camera in iframes only works on https:// or http://localhost. iOS Safari requires the iframe allow="camera" attribute (set by the SDK).

Related

• @surtai/idv-rn: same API for React Native (uses react-native-webview).
• The verify app itself is at identity.surt.com.