HyperKYC Mobile SDK

The HyperKYC Mobile SDK enables seamless KYC workflows on mobile platforms. This page covers Android, iOS, React Native, and Flutter integrations.

Sample Apps

Platform	Download
Android	hyperkyc-android.zip
iOS	hyperkyc-ios.zip

Android

Introduction

Requirements:

Minimum SDK level: 21 (Android 5.0 – Lollipop)
Supports Play Store's 16 KB page size requirement (from 2.x.x series)
Min Kotlin version: 1.8.0

Gradle Setup

Add this to the project-level build.gradle.kts:

allprojects {
    repositories {
        google()
        mavenCentral()
        maven(url = "https://s3.ap-south-1.amazonaws.com/hvsdk/android/releases")
    }
}

SDK Size Optimization

By default, the SDK includes face detection, document detection, and other modules. Exclude unused modules to reduce app size:

implementation("co.hyperverge:hyperkyc:2.0.1") {
    isTransitive = true

    // Exclude in-house face detector (~1.3 MB)
    // SDK will fallback to a lighter detector (~300 KB)
    // exclude(group = "co.hyperverge", module = "face-detection-preview-frame")

    // Exclude document detection (~12 MB)
    // exclude(group = "co.hyperverge", module = "hyperdocdetect")
}

Module	Description	Exclusion Impact
`face-detection-preview-frame`	In-house face detector	Reduces ~1.3 MB, fallback ~300 KB
`hyperdocdetect`	Document auto-capture/detection	Reduces ~12 MB

warning

Only exclude modules if the functionality is not required by your workflow.

Core Identifiers

Parameter	Description	Notes
`appId`	Application ID issued by HyperVerge	Required in all sessions
`appKey`	Secret key for authentication	Use securely; avoid hardcoding
`accessToken`	Session token for auth	Preferred in production; overrides `appKey`
`transactionId`	Unique ID per session	Must be fresh per attempt
`workflowId`	Workflow defined in dashboard	Links to configured KYC flow

Customising HyperKYC Config

hyperKYCconfig.setInputs(hashMapOf("name" to "sample name"))
hyperKYCconfig.setUseLocation(true)
hyperKYCconfig.setDefaultLangCode("en")
hyperKYCconfig.setUniqueId("12345-abc")

Function	Purpose
`setInputs(inputs: Map<String, Any>)`	Pre-fill workflow fields with dynamic inputs
`setUseLocation(useLocation: Boolean)`	Request location consent — denial prevents workflow
`setDefaultLangCode(defaultLangCode: String)`	Set default workflow language
`setUniqueId(uuid: String)`	Add unique ID for Cross-Platform Resume

Permissions & Play Store Compliance

The SDK requires:

Camera — for document/face capture
Microphone — for video workflows
Location (optional) — if setUseLocation(true) is enabled

Play Store Policy

All apps must target Android 15 and comply with permission policies.

Error Handling Example

private val startKYCLauncher = registerForActivityResult(HyperKyc.Contract()) { result ->
    Log.d(TAG, "registerForActivityResult callback called with: result = $result")

    val dataJson = GsonBuilder().setPrettyPrinting().create().toJson(result)

    when (result.status) {
        HyperKycStatus.ERROR -> updateResult(
            "Workflow failed - " + "${result.status} \n" +
                    " ${result.transactionId} \n" +
                    " ${result.details} \n" +
                    " ${result.errorCode} \n" +
                    " ${result.errorMessage}\n\n\n" +
                    " $dataJson"
        )
        else ->
            updateResult("Workflow successful - \n$dataJson")
    }
}

Android FAQs

What permissions does the SDK require?

The SDK requests only the minimum permissions required for KYC workflows:

Camera — for face/document capture
Microphone — for video KYC workflows
Location (optional) — only if enabled via setUseLocation(true)
NFC (optional) — only if NFC workflows are used

Remove unused permissions in your AndroidManifest.xml:

<uses-permission android:name="android.permission.RECORD_AUDIO"
    tools:node="remove" />

Does the SDK support targetSdkVersion 35 (Android 15)?

Yes. From HyperKYC SDK v2.x.x onwards:

16 KB page size support (mandatory for Android 15)
Edge-to-edge support
No breaking changes for clients targeting SDK 35

If you are targeting Android 15, update to v2.x.x or above.

Why am I seeing an "Intent Redirection" security warning in Play Console?

This issue was present in HyperKYC v0.30.1 and below. Google Play flags it as an Intent Redirection vulnerability.

Solution: Upgrade to HyperKYC v0.30.2 or above. There is no workaround — updating is the only fix.

Why am I seeing a Kotlin incompatibility warning?

Older SDK versions (< 2.0.0) used Kotlin's removeFirst() and removeLast() functions, which conflict with Java functions in Android 15 and can cause crashes on Android 14 or lower.

Solution: Upgrade to HyperKYC v2.0.0 or above. If using webCore, this is not an issue.

iOS

Introduction

Requirements:

Supported iOS: iOS 12+
Xcode Requirement: 15.1+
Integration: CocoaPods

SDK Setup

In your Podfile:

pod 'HyperKYC', 'x.x.x'

Then run:

pod install --repo-update

Workflow Prefetch

To improve performance, prefetch workflow configuration before launch:

HyperKyc.prefetch("appId", "workflowId")

Launching the Workflow

let transactionId = "iOSHKYCSample_" + self.randomString(length: 10)

let hyperKYCConfig = HyperKycConfig(
    appId: "<APP_ID>",
    appKey: "<APP_KEY>",
    workflowId: "workflow-id",
    transactionId: transactionId
)

HyperKyc.launch(self, hyperKycConfig: hyperKYCConfig) { hyperKycResult in
    // Handle result
}

info

In production, prefer token-based authentication instead of embedding appKey.

iOS Configuration Options

Function	Purpose
`setInputs([:])`	Pre-fill workflow fields
`setUseLocation(true/false)`	Request location consent
`setDefaultLangCode("en")`	Set default workflow language
`setUniqueId("uuid")`	Unique ID for Cross-Platform Resume

iOS Permissions

Add required keys in Info.plist:

<key>NSCameraUsageDescription</key>
<string>Camera required for KYC</string>

<key>NSMicrophoneUsageDescription</key>
<string>Microphone required for video KYC</string>

<key>NSLocationWhenInUseUsageDescription</key>
<string>Location required for KYC workflow</string>

iOS FAQs

Why am I seeing "Unable to present on ... which is already presenting"?

This happens if the SDK is launched from a controller that is already presenting another view.

Solution: Always initialize and launch HyperKYC from your app's main/root view controller (or top-most visible controller).

Does the SDK support iOS 26 or face capture on iOS 26 devices?

Yes. HyperKYC SDK supports iOS 26 from version 0.48.0 onwards.

All workflows (document capture, liveness, NFC, etc.) are compatible on iOS 26
The face capture red overlay issue seen on earlier SDK versions has been fixed in v0.48.0

Why was my iOS app flagged for using NFC framework?

The HyperKYC SDK uses NFC only when the NFC module is enabled in your workflow, and strictly for scanning ISO7816-compliant NFC smart cards (e-passports, national ID cards).

The SDK does not use NFC for payments or financial transactions. If your workflow does not include NFC, the SDK will not invoke or require NFC functionality.

React Native

Introduction

Requirements:

React Native: 0.71+ (recommended)
Android: minSdkVersion 21
iOS: iOS 12+, Xcode 15.1+
Requires App ID and App Key (or Access Token) from HyperVerge

Installation

# Install the RN wrapper
npm install @hyperverge/hyperkyc-react-native
# or
yarn add @hyperverge/hyperkyc-react-native

# For iOS
cd ios && pod install && cd ..

info

For projects using the new RN architecture, no manual linking is required. For older setups, follow the wrapper's README.

Platform Setup

Android

Ensure minSdkVersion 21 in android/app/build.gradle. Add required permissions in AndroidManifest.xml:

<uses-permission android:name="android.permission.INTERNET" />
<uses-permission android:name="android.permission.CAMERA" />

<!-- Optional -->
<!-- <uses-permission android:name="android.permission.RECORD_AUDIO" /> -->
<!-- <uses-permission android:name="android.permission.ACCESS_COARSE_LOCATION" /> -->
<!-- <uses-permission android:name="android.permission.NFC" /> -->

iOS

Add permission descriptions in Info.plist:

<key>NSCameraUsageDescription</key>
<string>Camera required for KYC</string>
<key>NSMicrophoneUsageDescription</key>
<string>Microphone required for video KYC</string>
<key>NSLocationWhenInUseUsageDescription</key>
<string>Location required for KYC workflow</string>

Prefetch (Optional)

To reduce startup latency:

Hyperkyc.prefetch('<APP_ID>', '<WORKFLOW_ID>');

Launching a Workflow

import React from 'react';
import { Button } from 'react-native';
import { NativeModules } from 'react-native';
const { Hyperkyc } = NativeModules;

const appID = '<YOUR_APP_ID>';
const appKey = '<YOUR_APP_KEY>'; // In production, use Access Tokens

export default function HyperKYCExample() {
  const startHyperKYC = () => {
    const transactionId = generateUUID(); // must be unique per session

    const config: any = {
      appId: appID,
      appKey: appKey,
      workflowId: 'workflow-id',
      transactionId: transactionId,
      inputs: {
        panNumber: 'ABCDE1234F',
      },
    };

    // Get a uniqueId for CPR support
    Hyperkyc.createUniqueId((uniqueId: string) => {
      config.uniqueId = uniqueId;

      Hyperkyc.launch(config, (response: any) => {
        console.log('HyperKYC Response:', response);
      });
    });
  };
}

React Native Parameters

Key	Type	Required	Description
`appId`	string	Yes	Provided by HyperVerge
`appKey`	string	Yes*	Required if not using `accessToken`
`accessToken`	string	Yes*	Preferred in production (supersedes `appKey`)
`workflowId`	string	Yes	Workflow configured in dashboard
`transactionId`	string	Yes	Unique per session
`inputs`	Record	No	Pre-fill workflow inputs
`uniqueId`	string	No	Obtained via `createUniqueId`; used for CPR

Flutter

Work in Progress

Flutter SDK is under development.

Standardised Error Codes

The SDK exposes standardized error codes for consistent handling across modules and platforms.

Code	Name	Android	iOS	Description
101	`SDK_CONFIG_ERROR`	✓	✓	Config errors (empty/invalid appId, workflowId, transactionId, accessToken, defaultLangCode)
102	`SDK_INPUT_ERROR`	✓	✓	Invalid/missing inputs, file inaccessible
103	`USER_CANCELLED_ERROR`	✓	✓	User closed/cancelled workflow
104	`WORKFLOW_ERROR`	✓	✓	Workflow execution errors (doc, face, API, encryption)
105	`SDK_VERSION_ERROR`	✓	✓	SDK version not supported by workflow
106	`PERMISSIONS_ERROR`	✓	✓	Required permission not granted
107	`HARDWARE_ERROR`	✓	✓	Device hardware/camera failure
108	`GPS_ACCESS_DENIED`	✓	✓	Location permission denied
109	`QR_SCANNER_ERROR`	✓	—	QR scanner submodule missing (Android)
110	`SSL_CONNECT_ERROR`	✓	✓	SSL handshake/pinning failure
111	`NETWORK_ERROR`	✓	✓	Connectivity/server errors
112	`SIGNATURE_FAILED_ERROR`	✓	✓	Response signature mismatch
113	`FACE_NOT_DETECTED`	✓	✓	Face not detected or blurry
114	`DEVICE_ROOTED_ERROR`	✓	—	Rooted/jailbroken device (Android only)
115	`SECURITY_ERROR`	—	✓	Screenshot/screen recording detected (iOS only)
117	`ACTIVITY_DESTROYED_ERROR`	✓	—	Low memory / "Don't keep activities" (Android only)
118	`LOW_STORAGE_ERROR`	✓	—	Free space < 1 MB (Android only)
119	`NFC_INVALID_ERROR`	✓	—	NFC SDK module missing (Android only)
120	`NFC_UNAVAILABLE_ERROR`	✓	✓	NFC not available on device
121	`NFC_AUTHENTICATION_ERROR`	✓	✓	NFC chip authentication failed
122	`NFC_CONNECTION_ERROR`	✓	✓	NFC card disconnected mid-scan
123	`WEB_FORM_ERROR`	✓	✓	Web form integration/config errors
124	`BROWSER_NOT_SUPPORTED`	✓	✓	No compatible browser installed
125	`NFC_INCOMPLETE_SCAN_ERROR`	✓	✓	NFC scan incomplete
126	`PRIVACY_CONSENT_DENIED_ERROR`	✓	✓	User denied privacy consent
127	`WEBCORE_NOT_SUPPORTED`	✓	—	Missing Play Services / WebView (Android only)
128	`SDK_EXIT_ERROR`	✓	✓	SDK closed unexpectedly / backgrounded
140	`SDK_INTERNAL_ERROR`	✓	—	Unexpected SDK state (Android only)
141	`PERMISSION_REVOKED` / `DATE_FORMAT_ERROR`	✓	✓	Android: permission revoked; iOS: invalid date format
151	`CHECK_SESSION_ERROR`	✓	✓	Session validation failed (CPR)

Sample Apps​

Android​

Introduction​

Gradle Setup​

SDK Size Optimization​

Core Identifiers​

Customising HyperKYC Config​

Permissions & Play Store Compliance​

Error Handling Example​

Android FAQs​

iOS​

Introduction​

SDK Setup​

Workflow Prefetch​

Launching the Workflow​

iOS Configuration Options​

iOS Permissions​

iOS FAQs​

React Native​

Introduction​

Installation​

Platform Setup​

Android​

iOS​

Prefetch (Optional)​

Launching a Workflow​

React Native Parameters​

Flutter​

Standardised Error Codes​

Sample Apps

Android

Introduction

Gradle Setup

SDK Size Optimization

Core Identifiers

Customising HyperKYC Config

Permissions & Play Store Compliance

Error Handling Example

Android FAQs

iOS

Introduction

SDK Setup

Workflow Prefetch

Launching the Workflow

iOS Configuration Options

iOS Permissions

iOS FAQs

React Native

Introduction

Installation

Platform Setup

Android

iOS

Prefetch (Optional)

Launching a Workflow

React Native Parameters

Flutter

Standardised Error Codes