Identity Verification Overview

@fintech-automation/identity-verification is a branded React authentication component. It provides session management, runtime config, wrapper screens, and grouped brand, theme, localization, and callbacks options.

The flow is:

• Get the token and initialize the component with required authentication.
• The SDK decrypts and validates the authentication key.
• The backend verifies the identity and returns user data.
• Once everything is ready, the user follows the steps to authenticate and obtain the verification result.

After token validation, the flow goes through these pages:

intro -> prepare -> capture -> processing -> success | fail | error

Installation

npm install @fintech-automation/identity-verification

Usage

import React from 'react'
import { IdentityVerification } from '@fintech-automation/identity-verification'
import '@fintech-automation/identity-verification/styles.css'

export default function App() {
  return (
    <IdentityVerification
      verificationToken="YOUR_TOKEN"
      brand={{
        name: 'name',
        logoUrl: 'https://cdn.example.com/logo.svg',
      }}
      callbacks={{
        onSuccess: (result) => console.log('verified', result),
        onFail: (result) => console.log('not passed', result),
        onError: (error) => console.error(error.stage, error.message),
        onSessionStatusChange: (result) =>
          console.log('token session status', result),
      }}
    />
  )
}

Browser Bundle Usage

React and ReactDOM are bundled inside the SDK — no extra script tags needed. Use the global IdentityVerification.mount() helper to render into any container.

<html>
  <head>
    <!-- main css file  -->
    <link
      rel="stylesheet"
      href="https://cdn.accelerationcloud.com/identity-verification.min.css"
    />
    <!-- main js file  -->
    <script src="https://cdn.accelerationcloud.com/identity-verification.min.js"></script>
  </head>
  <body>
    <div id="container"></div>

    <script>
      // Mount the Identity Verification SDK into the container
      IdentityVerification.mount('#container', {
        verificationToken: 'YOUR_TOKEN',
        callbacks: {
          onSuccess: (result) => console.log('verified', result),
          onFail: (result) => console.log('not passed', result),
          onError: (error) => console.error(error.stage, error.message),
          onSessionStatusChange: (result) =>
            console.log('token session status', result),
        },
        brand: {
          name: 'Your Business Name',
          logoUrl: 'https://cdn.example.com/logo.svg',
        },
      })
    </script>
  </body>
</html>

Authentication Token

Obtain a verificationToken before rendering the component, then pass it through the verificationToken prop. For the API request and response details, refer to the Token API Reference Documentation.

Required Backend Parameters

To communicate with the Identity Verification backend, pass all of the following parameters explicitly. The verification session cannot be created or queried correctly without valid values for them.

| Parameter | Purpose | | ------------------- | --------------------------------------------------- | | verificationToken | Bearer token used to authenticate backend requests. |

Configuration

| Prop | Type | Required | Default | Description | | ------------------- | ---------------------- | -------- | ------------ | ----------------------------------------------- | | verificationToken | string | Yes | none | Bearer token used to authenticate backend APIs. | | callbacks | LivenessCallbacks | No | none | Event callbacks. | | flow | LivenessFlow | No | SDK defaults | Flow behavior. | | brand | LivenessBrand | No | SDK defaults | Brand shown in the SDK header. | | theme | LivenessTheme | No | SDK defaults | Visual system tokens. | | localization | LivenessLocalization | No | SDK defaults | SDK-owned screen copy. |

Callbacks

<IdentityVerification
  callbacks={{
    onScreenChange: (screen) => console.log('screen', screen),
    onAnalysisComplete: () => console.log('analysis complete'),
    onSessionStatusChange: (result) => {
      console.log('session status', result)
    },
    onSuccess: (result) => console.log('success', result),
    onFail: (result) => console.log('fail', result),
    onError: (error) => console.error(error.stage, error.message),
    onCancel: () => console.log('cancelled'),
    onContinue: () => console.log('continue'),
  }}
/>

| Prop | Type | Description | | ----------------------- | ------------------------------------------------------------------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | onScreenChange | (screen: 'intro' \| 'prepare' \| 'capture' \| 'processing' \| 'success' \| 'fail' \| 'error') => void | Called when the flow changes screens. | | onAnalysisComplete | () => void | Called when the capture detector finishes analysis and the SDK begins fetching backend results. | | onSessionStatusChange | (event: { status?: SessionStatus; stage?: string; message?: string; isEligible: boolean }) => void | Called after the SDK validates the token/session state. status indicates the session state, and isEligible indicates whether the session is eligible for verification. | | onSuccess | (result: VerifyResult) => void | Called after the backend returns a successful liveness result. | | onFail | (result: VerifyResult) => void | Called after the backend returns a non-passing or failed result. | | onError | (error: { stage: string; message: string; cause?: unknown }) => void | Called when a session, camera, capture, or result-fetch error occurs. | | onCancel | () => void | Called when the user cancels the live capture flow. | | onContinue | () => void | Called when the user taps Continue on the success screen. |

SessionStatus values

• COMPLETED: The token already completed the liveness check successfully.
• EXPIRED: The token has expired or the backend returned an auth/session-expired response.
• INVALID: The token is invalid, rejected, or otherwise failed validation.
• READY: Session token is valid and ready for liveness detection.
• RETRY_LIMIT_EXCEEDED: Retry limit exceeded — no further attempts allowed.

Result Object

interface VerifyResult {
  id?: string;
  status?: 'Passed' | 'Failed'
  fail_reason?: string | null;
}

Brand

<IdentityVerification
  brand={{
    name: 'AccCloud',
    logoUrl: 'https://cdn.example.com/logo.svg',
    secureLabel: 'Encrypted session',
  }}
/>

| Field | Default | Description | | ------------- | --------------------- | --------------------------------------------------------------------- | | name | '' | Your business name. | | logo | none | Optional React node brand mark for React consumers. | | logoUrl | none | Optional image URL brand mark; preferred for hosted/runtime wrappers. | | secureLabel | 'Encrypted session' | Top-right security label; pass '' to hide. |

Friendly Note 📝

Note: The brand mark is rendered with the following priority:

1. logo – If you pass a custom React node, it takes full precedence.
2. logoUrl – If no logo is provided, we'll display your image.
3. name – As a last resort, we'll generate a clean initials-based mark (e.g., "Company Name" → "CN") to keep the UI tidy.

This ensures your brand identity always appears — whether as a rich component, an image, or a simple text abbreviation. ✨

Flow

<IdentityVerification
  flow={{
    skipIntro: false,
    skipPrepare: false,
  }}
/>

| Field | Default | Description | | ------------- | ------- | ----------------------------------------------------------------------------------- | | skipIntro | false | Starts at Prepare instead of Intro. | | skipPrepare | false | Goes straight to capture after Intro, or immediately when skipIntro is also true. |

Theme

<IdentityVerification
  theme={{
    colors: {
      primary: '#1634A4',
      secondary: '#1A3DBF',
      heading: '#111827',
    },
    shape: {
      radius: 22,
    },
    typography: {
      fontFamily: "'Inter', system-ui, sans-serif",
    },
    layout: {
      width: 600,
      fullscreen: true,
    },
  }}
/>

| Field | Default | Description | | ----------------------- | ------------------ | ------------------------------------------------------ | | colors.primary | '#1634A4' | Main brand color. | | colors.secondary | '#1A3DBF' | Secondary brand accent color. | | colors.heading | '#111827' | Main heading and strong text color. | | shape.radius | 22 | Root/card corner radius in pixels. | | typography.fontFamily | Inter/system stack | Font family used by wrapper screens and capture theme. | | layout.width | 600 | Root card width. Number values are treated as pixels. | | layout.fullscreen | true | Uses a full-height mobile/portrait tablet layout. |

Localization

localization customizes SDK-owned screens text and is grouped by screen.

<IdentityVerification
  localization={{
    intro: {
      eyebrow: 'Identity check',
      title: "Let's confirm it's really you",
      body: 'A quick face scan helps protect your account.',
      cta: 'Start face scan',
      trustLabel: 'Bank-grade liveness detection',
    },
    prepare: {
      eyebrow: 'Before we start',
      title: 'Three things for a clean scan',
      tips: [
        { title: 'Find good light', body: 'Avoid strong backlight.' },
        { title: 'Clear your face', body: 'Remove sunglasses or masks.' },
        { title: 'Hold steady', body: 'Keep the device at eye level.' },
      ],
      cta: "I'm ready",
      backLabel: 'Back',
    },
    starting: {
      title: 'Starting camera',
      body: 'Creating a secure liveness session.',
    },
    processing: {
      title: 'Verifying your scan',
      body: 'This usually takes just a moment.',
    },
    success: {
      title: "You're verified",
      body: 'Thanks. The liveness check was completed.',
      cta: 'Continue',
    },
    fail: {
      title: "We couldn't complete the scan",
      body: 'Move somewhere brighter and try again.',
      cta: 'Try again',
    },
    cameraPermission: {
      title: 'Camera access is required',
      body: 'Allow camera access, then try again.',
    },
  }}
/>

Localization props reference

| Prop path | Type | Description | | ------------------------ | ------------------------------------ | ---------------------------------------------------- | | intro.eyebrow | string | Small overline text above the intro title. | | intro.title | string | Main heading shown on the intro screen. | | intro.body | string | Paragraph explaining the check on the intro screen. | | intro.cta | string | Primary call-to-action on the intro screen. | | intro.trustLabel | string | Small security/trust label shown in header. | | prepare.eyebrow | string | Overline text for the prepare screen. | | prepare.title | string | Main heading for the prepare screen. | | prepare.tips | Array<{title:string, body:string}> | Array of tip objects displayed as a short checklist. | | prepare.cta | string | Primary action label on the prepare screen. | | prepare.backLabel | string | Back button label on the prepare screen. | | starting.title | string | Title shown while the camera is starting. | | starting.body | string | Supporting text while a session is being created. | | processing.title | string | Title shown while verification is in progress. | | processing.body | string | Supporting text shown during result fetch. | | success.title | string | Title for the success screen. | | success.body | string | Supporting success text. | | success.cta | string | Continue/acknowledge button text on success. | | fail.title | string | Title shown when a scan cannot complete. | | fail.body | string | Guidance text shown on failure. | | fail.cta | string | Retry button label on fail screen. | | cameraPermission.title | string | Title when camera permission is required. | | cameraPermission.body | string | Instructional text for granting camera permission. |

Localization Notes:

• All values are optional; the SDK falls back to built-in defaults when omitted.
• prepare.tips items should be objects shaped like { title: string, body: string }.

SDK Notes

• Token has a limited validity period. We recommend obtaining a new token for each liveness detection session.
• After initialization, the SDK automatically handles all communication with the Identity Verification backend during the liveness detection process. Your application does not need to call any additional Identity Verification APIs during this flow. In production environments, the SDK requires HTTPS. Camera access requires secure origins (HTTPS or localhost for development).
• The camera capture step requires browser camera permission, HTTPS in production, WebGL support, and network access to liveness assets.

License

This repository includes the FinTech Identity Verification SDK, which is licensed under a Commercial License Agreement. See COMMERCIAL-LICENSE.md for full terms.

Use of this SDK requires explicit permission from FinTech Automation.