vishwam-react-sdk

React SDK for Vishwam re-verification in the browser: face liveness, ID document capture, and face match.

The SDK handles camera access, on-device face guidance, image capture, Vishwam API calls, and an ORN / referenceId check before it treats a backend success as verified. Document payloads may be encrypted; decryption is the host app’s job, not the SDK’s. Checksum helpers remain in the package but are not applied.

npm package: vishwam-react-sdk

Requirements

• React 17 (react ^17.0.1)
• A modern browser with camera access (Chrome, Safari, Firefox, Edge)
• HTTPS in production (camera access). localhost is allowed.

Install

npm install vishwam-react-sdk

npm install [email protected]

yarn add vishwam-react-sdk

Quick start

Call Init() once when the page loads so face-detection models are ready. Then render the capture component you need.

import React, { useEffect } from 'react'
import {
  Init,
  CheckLiveness,
  ReadDocument,
  faceMatch
} from 'vishwam-react-sdk'

function Verification() {
  useEffect(() => {
    Init()
  }, [])

  function handleLiveness(response) {
    if (response.status === 'failed') {
      // Camera, backend, or ORN / referenceId failure — do not continue as verified
      console.error(response.error, response.message)
      return
    }
    console.log(response.result)
  }

  return (
    <CheckLiveness
      url="https://your-vishwam-api.example.com/v1"
      appId="your_app_id"
      userId="user-123"
      referenceId="session-abc"
      captureType="1"
      eyesCheck="1"
      storeId="store-1"
      whiteBackground="1"
      expiryIn="1h"
      sessionId="optional-session-id"
      getLivenessResponse={handleLiveness}
    />
  )
}

export default Verification

Exports

| Export | Type | Use it for | | --- | --- | --- | | Init | function | Preload face-detection models. Call once on page load. | | CheckLiveness | component | Live selfie capture and POST /check_liveness. | | ReadDocument | component | Camera capture for an ID, then POST /read_document. | | faceMatch | function | Compare two face images through POST /v1/face_match. |

Common props

These apply to CheckLiveness and ReadDocument.

| Prop | Required | Description | | --- | --- | --- | | url | Yes | Vishwam API base URL, including the version path (for example /v1). | | appId | Yes | Application identifier (app_id). | | userId | Yes | User identifier (user_id). | | referenceId | Yes | Order / session reference (ORN). Must match referenceId in a successful liveness or face-match response. | | expiryIn | Yes | Auth token expiry (for example "1h"). | | sessionId | No | Optional correlation id sent as session_id. Omit the prop to leave it off the request (backward compatible). |

CheckLiveness

Additional props

| Prop | Description | | --- | --- | | captureType | Passed to /check_liveness as capture_type. | | eyesCheck | Passed as eyesCheck. | | storeId | Passed as store_id. | | whiteBackground | Passed as whiteBackground. | | getLivenessResponse | Callback with the final result or error. |

Backend APIs used

• POST {url}/get_auth_token
• POST {url}/check_liveness

Success (via getLivenessResponse)

Typical backend shape when liveness passes. The SDK also attaches the captured preview:

{
  "status": "success",
  "statusCode": "200",
  "referenceId": "session-abc",
  "checksum": "…",
  "result": {
    "live": "yes",
    "liveness-score": "99",
    "to-be-reviewed": "no"
  },
  "livenessImage": "<base64>",
  "livenessImageType": "image/jpeg"
}

livenessImage and livenessImageType are added by the SDK after a backend success that also passes the ORN / referenceId check.

A successful liveness response must include referenceId equal to the referenceId prop you passed. If it is missing or different, the host gets a failed object instead of this success payload. The SDK does not validate or decrypt checksum.

ReadDocument

Additional props

| Prop | Description | | --- | --- | | docType | addhar, pan, passport, voter, pwd, others | | documentType | Passed as document. | | decision | Passed as decision. | | isBack | "0" or "1" for front/back. | | getReadDocumentImage | Callback with the final result or error. |

Backend APIs used

• POST {url}/get_auth_token
• POST {url}/read_document

Success (via getReadDocumentImage)

The SDK attaches the captured image:

{
  "status": "success",
  "referenceId": "session-abc",
  "result": [
    {
      "details": {},
      "checksum": "…"
    }
  ],
  "image": "<base64>",
  "type": "image/jpeg"
}

ORN / referenceId is required on success, same as liveness. Encrypted result / details are passed through to the host; the SDK does not decrypt them or check checksums.

faceMatch

const response = await faceMatch(
  url,
  referenceId,
  userId,
  appId,
  matchType,
  imageBase64,
  image2Base64,
  imageType,
  sessionId // optional
)

Backend APIs used

• POST {url}/v2/get_auth_token
• POST {url}/v1/face_match

Returns the backend payload, or a session_mismatch object if ORN / referenceId fails. Same fail-closed rule as CheckLiveness.

Security validation

On a backend status: "success" for liveness, document, and face match, the SDK blocks the user unless referenceId matches.

ORN / session identity

Compares the referenceId you passed with response.referenceId. Missing or different values fail.

{
  "status": "failed",
  "error": "session_mismatch",
  "message": "Identity validation failed. Session mismatch detected."
}

The SDK does not run checksum validation. Encrypted document (and any other) payloads should be decrypted in the host app, not in this SDK. generateChecksum / validateChecksum remain exported if you need them outside the capture flow.

session_mismatch is delivered through getLivenessResponse, getReadDocumentImage, or the faceMatch return value. It is not thrown to React error boundaries. Do not continue the journey as verified.

sessionId is sent as session_id when provided. It is not required for existing integrations.

Error handling

Errors use this SDK’s existing callback / return shape (status: "failed").

| Scenario | status | Typical fields | | --- | --- | --- | | Camera permission denied | failed | error: NotAllowedError, message: Camera Permission Denied | | Backend liveness / document / match rejection | failed | Backend error / message / result | | ORN mismatch or missing referenceId on success | failed | error: session_mismatch |

Host apps should stop the re-verification journey on session_mismatch.

Typical re-verification flow

1. Init()
2. <CheckLiveness sessionId={id} getLivenessResponse={…} />
3. faceMatch(url, referenceId, …, sessionId)   // if required
4. <ReadDocument sessionId={id} getReadDocumentImage={…} />  // if required

Each step is a separate mount or function call. If a callback returns status: "failed", do not proceed to the next step as verified.