HyperKYC WebSDK

Overview

This documentation covers the HyperKYC WebSDK implementation, including SDK initialization, configuration options, response handling, and error management.

Step 1: Include the SDK Script

Add the following script to your HTML page:

<script src="https://hv-camera-web-sg.s3.ap-southeast-1.amazonaws.com/hyperverge-web-sdk@<SDK_VERSION>/src/sdk.min.js"></script>

Step 2: Launch the SDK

You have two ways to initialise and launch the HyperKYC SDK.

Option 1: Passing workflowId and transactionId directly

const hyperKycConfig = new HyperKycConfig(
  "<jwtToken>",        // JWT token generated from your backend
  "<workflowID>",      // Workflow identifier
  "<transactionId>",   // Unique transaction identifier
  true                 // Optional: true to show landing page, default is false
);

await HyperKYCModule.launch(hyperKycConfig, callback);

Option 2: Passing only the authToken

Generate the token from your backend:

curl --location 'https://auth.hyperverge.co/login' \
--header 'Content-Type: application/json' \
--data '{
  "appId": "<appId>",
  "appKey": "<appKey>",
  "expiry": "<token-expiry-time-in-seconds>",
  "transactionId": "<transactionId>",
  "workflowId": "<workflowId>"
}'

Initialise the SDK using the generated token:

const hyperKycConfig = new HyperKycConfig(
  "<jwtToken>", // JWT token with workflowId and transactionId in payload
  true          // Optional: true to show landing page, default is false
);

await HyperKYCModule.launch(hyperKycConfig, callback);

Understanding the Parameters

jwtToken — Secure JWT token generated from your backend to authenticate requests
workflowID — Name/ID of the workflow you're launching
transactionId — Unique ID for tracking individual transactions
Landing Page Flag — If true, shows a landing page before the workflow begins

warning

Always generate JWT tokens securely from your backend to protect your appId and appKey.

Optional Setter Functions

`setInputs`

Pass additional inputs required by your workflow:

hyperKycConfig.setInputs({
  "input_key": "input_value"
});

`supportDarkMode`

Enable automatic dark mode detection:

hyperKycConfig.supportDarkMode(true);

By default, the SDK always launches in light mode regardless of system settings.

`setUniqueId` (Deprecated)

For cross-platform resume workflows:

hyperKycConfig.setUniqueId('<unique_id>');

`setCustomFontStylesheet`

Required only for SDK versions older than 8.11.5. For newer versions, font URLs can be included directly in the workflow's UI config.

hyperKycConfig.setCustomFontStylesheet('https://fonts.googleapis.com/css2?family=Roboto');

`setDefaultLangCode`

Set the default language when multiple languages are configured:

hyperKycConfig.setDefaultLangCode('en');

If not specified, the SDK defaults to the first language listed in the workflow config.

`setInitialLoaderColor`

Sets the loader colour displayed immediately when the SDK is launched:

hyperKycConfig.setInitialLoaderColor('#ff5733');

`setUseLocation`

Enables location consent before workflow execution. If denied, the user cannot proceed.

hyperKycConfig.setUseLocation(true); // default is false

Understanding HyperKycResult

Upon workflow completion, the SDK returns a HyperKycResult object:

Field	Description
`status`	Status of workflow: `auto_approved`, `auto_declined`, `needs_review`, `error`, `user_cancelled`
`details`	Data points from workflow execution (based on `sdkResponse` in workflow config)
`transactionId`	Transaction ID provided at start
`errorMessage`	Error description (only if status is `error` or `user_cancelled`)
`errorCode`	Error code (only if status is `error` or `user_cancelled`)
`latestModule`	Last executed module (only if status is `error` or `user_cancelled`)
`transactionAlreadyProcessed`	Indicates end state already reached for the given transactionId

Sample Response Structures

auto_approved / needs_review / auto_declined

{
  "transactionId": "123456",
  "status": "auto_approved/auto_declined/needs_review",
  "details": {
    "fullName": "Jose",
    "countrySelected": "ind",
    "dateOfBirth": "06-01-1993",
    "dateOfIssue": "03-01-2003",
    "selfieImage": "",
    "idFrontImage": "",
    "idBackImage": ""
  }
}

When exitOnEndStates is enabled

If the user who has already reached an end state resumes again:

{
    "transactionId": "ab_14may_test02",
    "status": "auto_approved/auto_declined/needs_review",
    "details": {},
    "transactionAlreadyProcessed": true
}

error

{
    "transactionId": "d00890a507",
    "status": "error",
    "errorMessage": "<error_message>",
    "errorCode": "<error_code>",
    "latestModule": "<module_id>"
}

user_cancelled

{
    "transactionId": "fd6aa8af4a",
    "status": "user_cancelled",
    "errorCode": 103,
    "errorMessage": "Workflow cancelled by user",
    "latestModule": "<module_id>"
}

Error Codes

SDK Config Errors (101)

Error Message	Description
`Unable to Fetch workFlow with workflowId`	Workflow ID not found for the provided app ID
`Unable to Fetch Text Config`	Custom text config source configured but file not found
`accessToken cannot be empty`	Access token not provided during SDK initialization
`workflowId cannot be empty`	Workflow ID not provided during SDK initialization
`transactionId cannot be empty`	Transaction ID not provided during SDK initialization
`Invalid Request Headers / Request Body`	Get Transaction State API returning 4xx error (for CPR)
`uniqueId invalid`	Unique ID not in standard UUID format
`Local data not supported by cross platform resume`	Workflow passing module variables with local file references in CPR mode

Workflow Input Errors (102)

Error Message	Description
`<input> is not found in inputs`	Required input missing in `setInputs` call
`value <value> for key <key> is not of the expected type`	Input data type mismatch with workflow spec
`Unexpected param <key> passed as input`	Input not defined in `inputsRequired`

User Cancelled Errors (103)

Error Message	Description
`Workflow cancelled by user`	User clicked close button
`Internet is down`	No internet connection
`Domain is not CORS whitelisted`	CORS issue
`Network error occured`	Network issues

Workflow Errors (104)

Error Message	Description
`Invalid previous step`	Module has previous step configured but it was not executed
`Request payload size exceeds maximum limit for finish transaction api`	Payload > 12MB
`Media stream not present`	MediaRecorder API initialization issue
`Media recorder not present`	MediaRecorder API not supported in browser
`Recording not started`	MediaRecorder API access issue
`Could not start recording`	Recording start failure
`logVideoStatementUrl not defined in workflow`	Missing API URL in workflow

Other Error Codes

Code	Category	Description
106	Camera Permissions Denied	Camera permission not granted
107	Hardware Error	Camera/media recorder initialization failure
111 or 4xx-5xx	Network error	API error
112	Signature Failed	Request/response signature validation failure (possible MITM)
126	Privacy Consent Denied	User denied BIPA compliance consent (USA clients only)
151	Session Conflict	Parallel ongoing session validation failure (CPR-related)
500-505	WebBundle Module Error	Various webBundle module configuration/initialization errors

Complete Sample Implementation

<!DOCTYPE html>
<html lang="en">
<head>
    <meta charset="UTF-8">
    <meta name="viewport" content="width=device-width, initial-scale=1.0">
    <title>HyperKYC Integration</title>
    <script src="https://hv-web-sdk-cdn.hyperverge.co/hyperverge-web-sdk@<SDK_VERSION>/src/sdk.min.js"></script>
</head>
<body>
    <button type="button" onclick="runGlobal();">Launch Workflow</button>
    <div class="result" style="width: 40%;"></div>

    <script>
        async function runGlobal() {
            const hyperKycConfig = new HyperKycConfig(
                '<jwt_token>',
                false,
            );

            hyperKycConfig.setInputs({
                "input_key": "input_value"
            });

            hyperKycConfig.supportDarkMode(false);
            hyperKycConfig.setCustomFontStylesheet('https://fonts.googleapis.com/css2?family=Roboto');
            hyperKycConfig.setInitialLoaderColor('<color>');
            hyperKycConfig.setDefaultLangCode('<language>');
            hyperKycConfig.setUseLocation(false);

            await HyperKYCModule.launch(hyperKycConfig, callback);
        }

        const callback = (HVResponse) => {
            console.log(HVResponse);
        };
    </script>
</body>
</html>

Overview​

Step 1: Include the SDK Script​

Step 2: Launch the SDK​

Option 1: Passing workflowId and transactionId directly​

Option 2: Passing only the authToken​

Understanding the Parameters​

Optional Setter Functions​

setInputs​

supportDarkMode​

setUniqueId (Deprecated)​

setCustomFontStylesheet​

setDefaultLangCode​

setInitialLoaderColor​

setUseLocation​

Understanding HyperKycResult​

Sample Response Structures​

Error Codes​

SDK Config Errors (101)​

Workflow Input Errors (102)​

User Cancelled Errors (103)​

Workflow Errors (104)​

Other Error Codes​

Complete Sample Implementation​