@finos_sdk/sdk-ekyc 1.4.1 → 1.4.4

package/README.md

@@ -5,31 +5,30 @@
 
 React Native SDK for eKYC (electronic Know Your Customer) and eSign. Features include Vietnamese CCCD NFC reading, OCR, Liveness detection, Face matching, C06 residence verification, SMS OTP verification, and Electronic Signature (eSign) capabilities.
 
-**Version**: 1.4.1
+**Version**: 1.4.2
 
-## 🚀 Features
+## Features
 
--   **Unified eKYC Flow** - Complete verification flow with single method call
--   **NFC Reading** - Read Vietnamese CCCD cards with NFC chips
--   **OCR Processing** - Extract data from ID card images
--   **Liveness Detection** - Verify user presence with selfie (Active/Passive modes)
--   **Face Matching** - Compare selfie with ID card photo
--   **C06 Verification** - Residence information verification
--   **eSign** - Electronic signature support (PDF signing, Remote signing)
--   **SMS OTP** - Integrated SMS OTP verification
--   **Flexible Configuration** - Custom styling and retry options
--   **TypeScript Support** - Full type definitions included
+- **Unified eKYC Flow** - Complete verification flow with single method call
+- **NFC Reading** - Read Vietnamese CCCD cards with NFC chips
+- **OCR Processing** - Extract data from ID card images
+- **Liveness Detection** - Verify user presence with selfie (Active/Passive modes)
+- **Face Matching** - Compare selfie with ID card photo
+- **C06 Verification** - Residence information verification
+- **eSign** - Electronic signature support (PDF signing, Remote signing)
+- **SMS OTP** - Integrated SMS OTP verification
+- **Flexible Configuration** - Custom styling, capture button colors, and retry options
+- **TypeScript Support** - Full type definitions included
 
+## Requirements
 
+- React Native 0.70.0+
+- Android 24+ / API Level 24+
+- iOS 14.0+ (Swift 5.7+)
+- NFC and/or Camera hardware depending on modules used
+- Runtime permissions for Camera and/or NFC
 
-## � Requirements
-
--   React Native 0.77.0+
--   Android 24+ / API Level 24+ (Android platform only)
--   NFC and/or Camera hardware depending on modules used
--   Runtime permissions for Camera and/or NFC
-
-## �🛠️ Installation
+## Installation
 
 ```bash
 npm install @finos_sdk/sdk-ekyc
@@ -37,12 +36,22 @@ npm install @finos_sdk/sdk-ekyc
 yarn add @finos_sdk/sdk-ekyc
 ```
 
-## 📖 Quick Start
+---
+
+## Quick Start
 
 ### 1. Import the SDK
 
 ```typescript
-import { FinosEKYC, FinosESign, getEkycError } from '@finos_sdk/sdk-ekyc';
+import {
+  FinosEKYC,
+  FinosESign,
+  getEkycError,
+  SDKFaceDetectStatus,
+  SDKFlowType,
+  AppIDType,
+} from '@finos_sdk/sdk-ekyc';
+
 import type {
   NfcConfig,
   C06Config,
@@ -50,108 +59,600 @@ import type {
   LivenessConfig,
   FaceServiceConfig,
   SmsOtpConfig,
-  SDKFlowType
+  StartEkycUIResult,
+  EKYCError,
 } from '@finos_sdk/sdk-ekyc';
 ```
 
-### 2. Complete eKYC Flow (Recommended)
+### 2. Initialize SDK
+
+```typescript
+// Initialize the SDK (required before using any method)
+await FinosEKYC.initialize();
+
+// Check SDK info
+const info = await FinosEKYC.getSDKInfo();
+console.log(info); // { name, version, buildNumber, platform, isInitialized }
+
+// Set transaction ID (optional)
+await FinosEKYC.setTransactionId('your-transaction-id');
+```
+
+---
+
+## Complete eKYC Flow (startEkycUI)
+
+The recommended way to use the SDK. Handles the complete verification flow with a single method call.
+
+### Method Signature
+
+```typescript
+FinosEKYC.startEkycUI(
+  appKey: string,
+  flowSDK: SDKFlowType[],
+  language: string,
+  transactionId: string,
+  appKeyConfig: AppKeyConfig,
+  optionConfig?: OptionConfig,
+  styleConfig?: StyleConfig,
+): Promise<StartEkycUIResult>
+```
+
+### Full Example with All Configs
+
+```typescript
+const result = await FinosEKYC.startEkycUI(
+  'your-main-app-key',
+
+  // --- flowSDK: verification steps to execute in order ---
+  ['OCR', 'NFC', 'LIVENESS'],
+
+  // --- language ---
+  'vi',  // 'vi' | 'en'
+
+  // --- transactionId ---
+  'txn-20260319-001',
+
+  // --- appKeyConfig: API keys for each module ---
+  {
+    appKey: 'your-main-app-key',
+    appKeyNfc: 'your-nfc-key',
+    appKeyOcr: 'your-ocr-key',
+    appKeyLiveness: 'your-liveness-key',
+    appKeyC06: 'your-c06-key',
+    appKeyFaceService: 'your-face-key',
+  },
+
+  // --- optionConfig: SDK behavior settings ---
+  {
+    baseUrl: 'https://api.example.com',       // Custom API base URL
+    countMaxRetry: 3,                          // Max retry attempts (default: 3)
+    language: 'vi',                            // Override language
+    switchFrontCamera: true,                   // Use front camera (default: false)
+    isActiveLiveness: true,                    // Active liveness mode (default: true)
+    autoCapture: true,                         // Auto capture (default: true)
+    forceCaptureTimeout: 30,                   // Force capture timeout in seconds
+    isShowCameraFont: true,                    // Show camera guide text
+    customActions: [                           // Custom liveness actions
+      SDKFaceDetectStatus.LEFT,
+      SDKFaceDetectStatus.RIGHT,
+      SDKFaceDetectStatus.STRAIGHT,
+    ],
+    activeActionCount: 3,                      // Random action count 1-10 (if customActions is null)
+    appIDType: AppIDType.VIKKI,                // App ID type: NONE | HD_BANK | VIKKI
+  },
+
+  // --- styleConfig: UI customization ---
+  {
+    // Global defaults
+    textSize: 14,                              // Default text size (sp)
+    textFont: '',                              // Font resource name (e.g. 'roboto_medium')
+    textColor: 0xFF333333,                     // Default text color (ARGB int)
+    statusBarBackground: undefined,            // Status bar drawable resource ID
+    backIcon: undefined,                       // Back button drawable resource ID
+
+    // Per-element text styles (override global defaults)
+    titleStyle: {                              // Screen title ("CHUP MAT TRUOC", "Chup chan dung")
+      textSize: 20,
+      textFont: 'roboto_bold',
+      textColor: 0xFF142630,
+    },
+    toolbarStyle: {                            // Toolbar/navigation bar title
+      textSize: 18,
+      textFont: '',
+      textColor: 0xFF007AFF,
+    },
+    instructionStyle: {                        // User instruction text
+      textSize: 16,
+      textFont: '',
+      textColor: 0xFF666666,
+    },
+    errorStyle: {                              // Error message text
+      textSize: 14,
+      textFont: '',
+      textColor: 0xFFFF3B30,
+    },
+    successStyle: {                            // Success message text
+      textSize: 14,
+      textFont: '',
+      textColor: 0xFF34C759,
+    },
+    warningStyle: {                            // Warning message text
+      textSize: 14,
+      textFont: '',
+      textColor: 0xFFFF9500,
+    },
+
+    // Capture button colors (direct color int, ARGB)
+    captureButtonColor: 0xFF00A86F,            // Capture button color when enabled
+    captureButtonDisabledColor: 0xFFCCCCCC,    // Capture button color when disabled
+  },
+);
+```
+
+### Result
+
+```typescript
+interface StartEkycUIResult {
+  status: 'success';
+  event: string;
+  data?: string;
+  transactionId?: string;
+  imageFace?: string;            // Base64 selfie/liveness image
+  imageOcrFront?: string;        // Base64 OCR front image
+  imageOcrBack?: string;         // Base64 OCR back image
+  imageFacePath?: string;        // Absolute path to selfie file
+  imageOcrFrontPath?: string;    // Absolute path to OCR front file
+  imageOcrBackPath?: string;     // Absolute path to OCR back file
+}
+```
+
+---
+
+## Configuration Reference
+
+### AppKeyConfig
 
-The SDK provides a unified method to handle the complete eKYC flow:
+API keys for each eKYC module.
+
+| Field | Type | Required | Description |
+|-------|------|----------|-------------|
+| `appKey` | `string` | Yes | Main app key |
+| `appKeyNfc` | `string` | Yes | NFC module key |
+| `appKeyOcr` | `string` | Yes | OCR module key |
+| `appKeyLiveness` | `string` | Yes | Liveness module key |
+| `appKeyC06` | `string` | Yes | C06 module key |
+| `appKeyFaceService` | `string` | Yes | Face service module key |
 
 ```typescript
-// Configure your app keys
-const AppKey = {
+const appKeyConfig = {
   appKey: 'your-main-app-key',
-  appKeyNfc: 'your-nfc-app-key',
-  appKeyC06: 'your-c06-app-key',
-  appKeyOcr: 'your-ocr-app-key',
-  appKeyLiveness: 'your-liveness-app-key',
-  appKeyFaceService: 'your-face-service-app-key',
+  appKeyNfc: 'your-nfc-key',
+  appKeyOcr: 'your-ocr-key',
+  appKeyLiveness: 'your-liveness-key',
+  appKeyC06: 'your-c06-key',
+  appKeyFaceService: 'your-face-key',
 };
+```
 
-const handleEkycFlow = async () => {
-  try {
-    // Initialize SDK first
-    await FinosEKYC.initialize();
-
-    // Start complete eKYC flow
-    const result = await FinosEKYC.startEkycUI(
-      AppKey.appKey,                    // Main app key
-      ['OCR', 'NFC', 'LIVENESS'],       // Flow steps
-      'vi',                             // Language ('vi' | 'en')
-      'test-transaction-123',           // Transaction ID
-      AppKey,                           // All app keys
-      { countMaxRetry: 3 },             // Option config
-      {                                 // Style config
-        textSize: 14,
-        textColor: 0xff000000,
-        toolbarStyle: {
-          textSize: 26,
-          textColor: 0xff007AFF,
-        }
-      }
-    );
-
-    console.log('eKYC Result:', result);
-  } catch (error) {
-    const err = getEkycError(error);
-    console.error('eKYC Error:', err.customCode, err.customMessage);
-  }
+### OptionConfig
+
+SDK behavior and runtime settings.
+
+| Field | Type | Default | Description |
+|-------|------|---------|-------------|
+| `baseUrl` | `string` | `undefined` | Custom API base URL |
+| `countMaxRetry` | `number` | `3` | Max retry attempts on failure |
+| `language` | `string` | `undefined` | Override language (`'vi'` or `'en'`) |
+| `switchFrontCamera` | `boolean` | `false` | Use front camera for liveness/face |
+| `isActiveLiveness` | `boolean` | `true` | Enable active liveness detection |
+| `autoCapture` | `boolean` | `true` | Auto capture when conditions met |
+| `forceCaptureTimeout` | `number` | `0` | Force capture timeout in seconds (0 = disabled) |
+| `isShowCameraFont` | `boolean` | `true` | Show instruction text on camera screen |
+| `customActions` | `SDKFaceDetectStatus[]` | `undefined` | Custom liveness action sequence |
+| `activeActionCount` | `number` | `2` | Number of random actions (1-10, used when `customActions` is null) |
+| `appIDType` | `AppIDType` | `NONE` | App ID type for branding: `NONE`, `HD_BANK`, or `VIKKI` |
+
+```typescript
+// Minimal
+const optionConfig = { countMaxRetry: 3 };
+
+// Full
+const optionConfig = {
+  baseUrl: 'https://api.example.com',
+  countMaxRetry: 3,
+  language: 'vi',
+  switchFrontCamera: true,
+  isActiveLiveness: true,
+  autoCapture: true,
+  forceCaptureTimeout: 30,
+  isShowCameraFont: true,
+  customActions: [
+    SDKFaceDetectStatus.LEFT,
+    SDKFaceDetectStatus.RIGHT,
+    SDKFaceDetectStatus.STRAIGHT,
+  ],
+  activeActionCount: 3,
+  appIDType: AppIDType.VIKKI,
+};
+```
+
+### AppIDType
+
+Determines the branding/skin of SDK screens.
+
+| Value | Description |
+|-------|-------------|
+| `NONE` | Default, no branding |
+| `HD_BANK` | HD Bank branding |
+| `VIKKI` | Vikki branding |
+
+```typescript
+import { AppIDType } from '@finos_sdk/sdk-ekyc';
+
+// In optionConfig
+{ appIDType: AppIDType.VIKKI }
+```
+
+### StyleConfig
+
+UI appearance customization. All color values use ARGB integer format (e.g., `0xFFRRGGBB`).
+
+| Field | Type | Default | Description |
+|-------|------|---------|-------------|
+| `textSize` | `number` | `14` | Default text size (sp) |
+| `textFont` | `string` | `''` | Default font resource name (e.g., `'roboto_medium'`) |
+| `textColor` | `number` | `0xFF000000` | Default text color (ARGB) |
+| `statusBarBackground` | `number` | `undefined` | Status bar background drawable resource ID |
+| `backIcon` | `number` | `undefined` | Back button icon drawable resource ID |
+| `titleStyle` | `TextStyle` | `undefined` | Style for screen titles |
+| `toolbarStyle` | `TextStyle` | `undefined` | Style for toolbar/navigation title |
+| `instructionStyle` | `TextStyle` | `undefined` | Style for instruction text |
+| `errorStyle` | `TextStyle` | `undefined` | Style for error messages |
+| `successStyle` | `TextStyle` | `undefined` | Style for success messages |
+| `warningStyle` | `TextStyle` | `undefined` | Style for warning messages |
+| `captureButtonColor` | `number` | `undefined` | Capture button color when enabled (ARGB) |
+| `captureButtonDisabledColor` | `number` | `undefined` | Capture button color when disabled (ARGB) |
+
+#### TextStyle (sub-config)
+
+Each text style can override the global defaults. `null`/`undefined` fields fall back to the parent `StyleConfig` defaults.
+
+| Field | Type | Default | Description |
+|-------|------|---------|-------------|
+| `textSize` | `number` | Parent `textSize` | Text size (sp) |
+| `textFont` | `string` | Parent `textFont` | Font resource name |
+| `textColor` | `number` | Parent `textColor` | Text color (ARGB) |
+
+```typescript
+// Minimal - just change capture button color
+const styleConfig = {
+  captureButtonColor: 0xFF00A86F,
+  captureButtonDisabledColor: 0xFFCCCCCC,
+};
+
+// Custom theme with all styles
+const styleConfig = {
+  textSize: 14,
+  textFont: 'roboto_regular',
+  textColor: 0xFF333333,
+  titleStyle: {
+    textSize: 20,
+    textFont: 'roboto_bold',
+    textColor: 0xFF142630,
+  },
+  toolbarStyle: {
+    textSize: 18,
+    textColor: 0xFF007AFF,
+  },
+  instructionStyle: {
+    textSize: 16,
+    textColor: 0xFF666666,
+  },
+  errorStyle: {
+    textColor: 0xFFFF3B30,
+  },
+  successStyle: {
+    textColor: 0xFF34C759,
+  },
+  warningStyle: {
+    textColor: 0xFFFF9500,
+  },
+  captureButtonColor: 0xFF142630,
+  captureButtonDisabledColor: 0xFFDDDDDD,
+};
+```
+
+### SDKFlowType
+
+Available flow step types for `startEkycUI`.
+
+| Value | Description |
+|-------|-------------|
+| `'OCR'` | Scan ID card with camera (front/back) |
+| `'NFC'` | Read NFC chip on CCCD |
+| `'LIVENESS'` | Liveness detection (selfie) |
+
+```typescript
+// Common flows
+const flow1 = ['OCR', 'NFC', 'LIVENESS'];          // Full eKYC
+const flow2 = ['OCR', 'LIVENESS'];                  // Without NFC
+const flow3 = ['LIVENESS'];                          // Liveness only
+```
+
+### SDKFaceDetectStatus
+
+Available liveness actions for `customActions`.
+
+| Value | Description |
+|-------|-------------|
+| `LEFT` | Turn head left |
+| `RIGHT` | Turn head right |
+| `UP` | Look up |
+| `DOWN` | Look down |
+| `STRAIGHT` | Look straight |
+| `SMILE` | Smile |
+| `BLINK` | Blink eyes |
+| `TILT_LEFT` | Tilt head left |
+| `TILT_RIGHT` | Tilt head right |
+| `WINK_LEFT` | Wink left eye |
+| `WINK_RIGHT` | Wink right eye |
+
+```typescript
+import { SDKFaceDetectStatus } from '@finos_sdk/sdk-ekyc';
+
+const customActions = [
+  SDKFaceDetectStatus.LEFT,
+  SDKFaceDetectStatus.RIGHT,
+  SDKFaceDetectStatus.SMILE,
+];
+```
+
+---
+
+## Individual Module APIs
+
+### NFC Scanning
+
+```typescript
+const config: NfcConfig = {
+  appKey: 'your-nfc-key',            // Required
+  documentNumber: '012345678012',     // Required: CCCD number
+  birthDate: '01011990',              // Required: format DDMMYYYY
+  expireDate: '01012030',             // Required: format DDMMYYYY
+  transactionId: 'txn-001',          // Optional
+  facePathStorage: '/path/to/face',  // Optional: path to save face image
+};
+
+const result = await FinosEKYC.startNfcScan(config);
+```
+
+**NfcConfig**
+
+| Field | Type | Required | Description |
+|-------|------|----------|-------------|
+| `appKey` | `string` | Yes | NFC module API key |
+| `documentNumber` | `string` | Yes | CCCD/CMND number |
+| `birthDate` | `string` | Yes | Date of birth (DDMMYYYY) |
+| `expireDate` | `string` | Yes | Expiry date (DDMMYYYY) |
+| `transactionId` | `string` | No | Transaction ID |
+| `facePathStorage` | `string` | No | File path to store extracted face image |
+
+### OCR Processing
+
+```typescript
+const config: OcrConfig = {
+  appKey: 'your-ocr-key',            // Required
+  transactionId: 'txn-001',          // Required
+  idImagePath: 'base64_image_data',  // Required: Base64 encoded image
+  expectedDocumentSide: 'front',     // Required: 'front' or 'back'
+};
+
+const result = await FinosEKYC.startOcr(config);
+```
+
+**OcrConfig**
+
+| Field | Type | Required | Description |
+|-------|------|----------|-------------|
+| `appKey` | `string` | Yes | OCR module API key |
+| `transactionId` | `string` | Yes | Transaction ID |
+| `idImagePath` | `string` | Yes | Base64 encoded ID card image |
+| `expectedDocumentSide` | `string` | Yes | `'front'` or `'back'` |
+
+### Liveness Detection
+
+```typescript
+const config: LivenessConfig = {
+  appKey: 'your-liveness-key',       // Required
+  selfieImage: 'base64_image',       // Required: Base64 encoded selfie
+  transactionId: 'txn-001',          // Optional
+  switchFrontCamera: true,           // Optional: use front camera
+  isActiveLiveness: true,            // Optional: active liveness mode
+  autoCapture: true,                 // Optional: auto capture
+  isShowCameraFont: true,            // Optional: show guide text
+  forceCaptureTimeout: 30,           // Optional: force capture timeout (seconds)
+  customActions: [                   // Optional: custom action sequence
+    SDKFaceDetectStatus.LEFT,
+    SDKFaceDetectStatus.RIGHT,
+    SDKFaceDetectStatus.SMILE,
+  ],
+  activeActionCount: 3,              // Optional: random action count (1-10)
+};
+
+const result = await FinosEKYC.startLiveness(config);
+```
+
+**LivenessConfig**
+
+| Field | Type | Default | Description |
+|-------|------|---------|-------------|
+| `appKey` | `string` | - | Liveness module API key (required) |
+| `selfieImage` | `string` | - | Base64 encoded selfie image (required) |
+| `transactionId` | `string` | `undefined` | Transaction ID |
+| `switchFrontCamera` | `boolean` | `false` | Use front camera |
+| `isActiveLiveness` | `boolean` | `false` | Enable active liveness mode |
+| `autoCapture` | `boolean` | `true` | Auto capture when conditions met |
+| `isShowCameraFont` | `boolean` | `true` | Show camera guide text |
+| `forceCaptureTimeout` | `number` | `0` | Force capture timeout in seconds |
+| `customActions` | `SDKFaceDetectStatus[]` | `undefined` | Custom action sequence (overrides random) |
+| `activeActionCount` | `number` | `2` | Random actions count 1-10 (when `customActions` is null) |
+
+### Face Comparison
+
+```typescript
+const config: FaceServiceConfig = {
+  appKey: 'your-face-key',           // Required
+  selfieImage: 'base64_selfie',      // Required: Base64 selfie image
+  idImage: 'base64_id_image',        // Required: Base64 ID card image
+  transactionId: 'txn-001',          // Optional
+  appKeyFaceService: 'alt-key',      // Optional: alternative key
+};
+
+const result = await FinosEKYC.startFaceCompare(config);
+```
+
+**FaceServiceConfig**
+
+| Field | Type | Required | Description |
+|-------|------|----------|-------------|
+| `appKey` | `string` | Yes | Face service API key |
+| `selfieImage` | `string` | Yes | Base64 encoded selfie image |
+| `idImage` | `string` | Yes | Base64 encoded ID card portrait |
+| `transactionId` | `string` | No | Transaction ID |
+| `appKeyFaceService` | `string` | No | Alternative face service key |
+
+### C06 Verification
+
+```typescript
+const config: C06Config = {
+  appKey: 'your-c06-key',            // Required
+  sod: 'nfc_sod_data',               // Required: SOD data from NFC
+  idCardNumber: '012345678012',       // Required: CCCD number
+  recentLocation: 'Ha Noi',          // Optional: recent location
+  transactionId: 'txn-001',          // Optional
+  deviceType: 'android',             // Optional
+};
+
+const result = await FinosEKYC.checkC06(config);
+```
+
+**C06Config**
+
+| Field | Type | Required | Description |
+|-------|------|----------|-------------|
+| `appKey` | `string` | Yes | C06 module API key |
+| `sod` | `string` | Yes | SOD data from NFC scan |
+| `idCardNumber` | `string` | Yes | CCCD/CMND number |
+| `recentLocation` | `string` | No | Recent location for verification |
+| `transactionId` | `string` | No | Transaction ID |
+| `deviceType` | `string` | No | Device type identifier |
+
+---
+
+## SMS OTP Integration
+
+```typescript
+const otpConfig: SmsOtpConfig = {
+  appKey: 'your-api-key',            // Required: X-FinOS-Api-Key
+  phoneNumber: '+84901234567',       // Required: with country code
+  referenceId: 'ref-001',            // Required: unique reference
+  purpose: 'transaction',            // Optional (default: 'transaction')
+  requestId: undefined,              // Required for verify/resend (from send response)
 };
+
+// 1. Send OTP
+const sendResult = await FinosEKYC.sendOtp(otpConfig);
+console.log('Request ID:', sendResult.requestId);
+
+// 2. Verify OTP (use requestId from send response)
+otpConfig.requestId = sendResult.requestId;
+const verifyResult = await FinosEKYC.verifyOtp(otpConfig, '123456');
+
+// 3. Resend OTP
+const resendResult = await FinosEKYC.resendOtp(otpConfig);
 ```
 
+**SmsOtpConfig**
 
+| Field | Type | Required | Description |
+|-------|------|----------|-------------|
+| `appKey` | `string` | Yes | SMS OTP API key (X-FinOS-Api-Key) |
+| `phoneNumber` | `string` | Yes | Phone number with country code (e.g., `+84901234567`) |
+| `referenceId` | `string` | Yes | Unique reference ID |
+| `purpose` | `string` | No | Purpose of OTP (default: `'transaction'`) |
+| `requestId` | `string` | For verify/resend | Request ID from send response |
 
-## ✍️ eSign Integration
+---
 
-The eSign module allows for electronic signature operations, including device registration, certificate management, and document signing.
+## eSign Integration
 
-### 1. Initialize eSign
+### Initialize
 
 ```typescript
-// Initialize eSign (optional: pass token and isProd flag)
-await FinosESign.initializeESign("your-access-token", false);
+// Initialize eSign SDK
+await FinosESign.initializeESign('your-finos-token', false); // token, isProd
+
+// Get SDK token
+const token = await FinosESign.getSdkToken(
+  '012345678012',     // CCCD number
+  'Nguyen Van A',     // Full name
+  'device-id-123',    // Device ID
+);
 ```
 
-### 2. Device Registration
+### Open Session
+
+```typescript
+const session = await FinosESign.openSessionId(
+  'access-token',     // Access token (or null)
+  'username',         // Username (or null)
+  true,               // Remember me (or null)
+);
+console.log(session.deviceState, session.code, session.message);
+```
 
-Register a device to perform signing operations.
+### Device Registration
 
 ```typescript
 const result = await FinosESign.registerDevice(
-  "12345678", // 8-digit recovery code
-  "123456",   // 6-digit PIN code
-  "fcm-token" // Optional FCM token
+  '12345678',         // 8-digit recovery code
+  '123456',           // 6-digit PIN code
+  'fcm-token',        // Optional FCM token
 );
-console.log(result.message);
 ```
 
-### 3. Manage Certificates
+### Certificate Management
 
 ```typescript
 // List certificates
-const certs = await FinosESign.listCerts(1, 10);
+const { certs } = await FinosESign.listCerts(1, 10);
+// certs: [{ serial, subject, validFrom, validTo }]
 
-// Verify specific certificate
-const verifyResult = await FinosESign.verifyCert("serial-number");
+// Verify certificate
+const verifyResult = await FinosESign.verifyCert('cert-serial');
 ```
 
-### 4. Sign Documents
+### Sign Documents
 
 ```typescript
-// Sign a PDF document
+// Sign a PDF
 const signResult = await FinosESign.signPdf(JSON.stringify(signRequest));
 
-// Sign and Confirm (Composite API)
-const result = await FinosESign.confirmSign(
-    "sign-request-id",
-    "123456" // PIN code
+// Sign PDF at multiple positions
+const multiResult = await FinosESign.signPdfMultiplePositions(JSON.stringify(signRequest));
+
+// Confirm signature
+const confirmResult = await FinosESign.confirmSign(
+  'sign-request-id',  // Sign request ID
+  '123456',           // PIN code
+  'auth-id',          // Optional auth ID
+  'auth-data',        // Optional auth data
+  true,               // Confirm (default: true)
 );
 ```
 
-### 5. Remote Signing
-
-Supported flows for remote signing:
+### Remote Signing
 
 ```typescript
 // Register for remote signing
@@ -159,111 +660,199 @@ const regResult = await FinosESign.registerRemoteSigning(JSON.stringify(requestB
 
 // Register and Confirm in one step
 const compositeResult = await FinosESign.registerAndConfirm(
-    JSON.stringify(requestBody),
-    "base64-confirmation-doc"
+  JSON.stringify(requestBody),
+  'base64-confirmation-doc',
+);
+
+// Send confirmation document
+const docResult = await FinosESign.sendConfirmationDocument(JSON.stringify(requestBody));
+```
+
+### Authorization Management
+
+```typescript
+// Initialize authorize request
+await FinosESign.initAuthorize(
+  'cert-serial',      // Certificate serial
+  10,                 // Quantity (signing count)
+  3600,               // Time (seconds until expiry)
+  'Authorization msg',// Message
+);
+
+// List authorize requests
+const { requests } = await FinosESign.listAuthorize(1, 10, 'ACTIVE');
+
+// Register/Confirm authorize
+await FinosESign.registerAuthorize(
+  'auth-id',
+  'auth-data',
+  'authorize-request-id',
+  '123456',           // PIN code
+  true,               // Confirm
 );
 ```
 
-## 📨 SMS OTP Integration
+---
+
+## Event Listeners
 
-Integrated SMS OTP verification for multi-factor authentication.
+### NFC Events
 
 ```typescript
-const otpConfig: SmsOtpConfig = {
-    phone: "0901234567",
-    // other config params
-};
+FinosEKYC.onNfcScanStart((data) => console.log('NFC scan started', data));
+FinosEKYC.onNfcScanSuccess((data) => console.log('NFC data:', data));
+FinosEKYC.onNfcError((error) => console.error('NFC error:', error.code, error.message));
+```
 
-// 1. Send OTP
-const sendResult = await FinosEKYC.sendOtp(otpConfig);
+### OCR Events
 
-// 2. Verify OTP
-const verifyResult = await FinosEKYC.verifyOtp(otpConfig, "123456");
+```typescript
+FinosEKYC.onOcrSuccess((data) => console.log('OCR result:', data));
+FinosEKYC.onOcrError((error) => console.error('OCR error:', error.code, error.message));
+```
 
-// 3. Resend OTP
-const resendResult = await FinosEKYC.resendOtp(otpConfig);
+### Liveness Events
+
+```typescript
+FinosEKYC.onLivenessSuccess((data) => console.log('Liveness result:', data));
+FinosEKYC.onLivenessError((error) => console.error('Liveness error:', error.code, error.message));
 ```
 
-## 🎯 Individual Module APIs (Advanced)
+### Face Compare Events
 
-### Liveness Detection (Updated)
+```typescript
+FinosEKYC.onFaceCompareSuccess((data) => console.log('Face match:', data));
+FinosEKYC.onFaceCompareError((error) => console.error('Face error:', error.code, error.message));
+```
 
-Refined configuration options for Active Liveness and Custom Actions.
+### C06 Events
 
 ```typescript
-import { FinosEKYC, FinosESign, getEkycError, SDKFaceDetectStatus } from '@finos_sdk/sdk-ekyc';
+FinosEKYC.onC06Success((data) => console.log('C06 result:', data));
+FinosEKYC.onC06Error((error) => console.error('C06 error:', error.code, error.message));
+```
 
-const config: LivenessConfig = {
-  appKey: 'your_app_key',
-  isActiveLiveness: true,       // Enable active liveness
-  autoCapture: true,            // Auto capture when conditions met
-  isShowCameraFont: true,       // Show instructions on camera
-  customActions: [              // Custom action sequence using Enum
-    SDKFaceDetectStatus.LEFT,
-    SDKFaceDetectStatus.RIGHT,
-    SDKFaceDetectStatus.SMILE
-  ],
-  // activeActionCount: 2,      // Or specify number of random actions
-  switchFrontCamera: true       // Use front camera
-};
+### SMS OTP Events
 
-await FinosEKYC.startLiveness(config);
+```typescript
+FinosEKYC.onSmsOtpSendSuccess((data) => console.log('OTP sent:', data));
+FinosEKYC.onSmsOtpResendSuccess((data) => console.log('OTP resent:', data));
+FinosEKYC.onSmsOtpError((error) => console.error('OTP error:', error.code, error.message));
 ```
 
-### OCR Processing
+### eSign Events
+
 ```typescript
-const config: OcrConfig = {
-  appKey: 'your_app_key',
-  idImagePath: 'base64_image_data',
-  expectedDocumentSide: 'front',
-};
+FinosESign.onESignInitSuccess((data) => console.log('eSign init:', data));
+FinosESign.onESignOpenSessionSuccess((data) => console.log('Session:', data));
+FinosESign.onESignRegisterDeviceSuccess((data) => console.log('Device registered:', data));
+FinosESign.onESignListCertsSuccess((data) => console.log('Certs:', data));
+FinosESign.onESignSignPdfSuccess((data) => console.log('PDF signed:', data));
+FinosESign.onESignError((error) => console.error('eSign error:', error.code, error.message));
+```
 
-await FinosEKYC.startOcr(config);
+### Cleanup
+
+```typescript
+// Remove all event listeners when done
+FinosEKYC.removeAllListeners();
+FinosESign.removeAllListeners();
 ```
 
-### NFC Scanning
+---
+
+## Error Handling
+
+All errors follow a unified `EKYCError` format:
+
 ```typescript
-const config: NfcConfig = {
-  appKey: 'your_app_key',
-  documentNumber: '123456789',
-  birthDate: '01011990',
-  expireDate: '01012030',
-};
+interface EKYCError {
+  event: string;     // Error event name (e.g., 'FACE_ERROR', 'NFC_ERROR')
+  code: string;      // Error code (e.g., '110', '200', '999')
+  message: string;   // Human-readable message
+}
+```
+
+### Usage
 
-await FinosEKYC.startNfcScan(config);
+```typescript
+import { getEkycError, fromCode, getLocalizedMessage, USER_CANCEL } from '@finos_sdk/sdk-ekyc';
+
+try {
+  const result = await FinosEKYC.startEkycUI(/* ... */);
+} catch (error) {
+  const err = getEkycError(error);
+  console.error(`[${err.event}] Code: ${err.code}, Message: ${err.message}`);
+
+  // Check for user cancellation
+  if (err.code === '999' || err.code === USER_CANCEL.code) {
+    console.log('User cancelled the flow');
+    return;
+  }
+
+  // Lookup error details by code
+  const errorInfo = fromCode(err.code);
+  if (errorInfo) {
+    console.log('VI:', getLocalizedMessage(errorInfo, 'vi'));
+    console.log('EN:', getLocalizedMessage(errorInfo, 'en'));
+  }
+}
 ```
 
-## ⚙️ Configuration Options
+### Common Error Codes
 
-### Style Configuration
+| Code | Constant | Description |
+|------|----------|-------------|
+| `999` | `USER_CANCEL` | User cancelled the flow |
+| `000` | `ERROR_UNKNOWN` | Unknown error |
+| `0` | `SDK_START_ERROR` | Failed to start SDK (check key) |
+| `001` | `OCR_UNRECOGNIZED_ID_CARD` | Cannot recognize ID card |
+| `110` | `LIVENESS_ERROR` | Liveness detection error |
+| `109` | `FACE_ERROR` | Face comparison failed |
+| `200` | `SCAN_NFC_ERROR` | NFC scan failed |
+| `203` | `C06_ERROR` | C06 verification error |
+| `209` | `NFC_USER_CANCEL` | User cancelled NFC scan |
+| `300` | `SMS_OTP_ERROR` | SMS OTP error |
 
-Customize the UI appearance:
+---
+
+## Lifecycle Management
+
+Handle app lifecycle events for NFC:
 
 ```typescript
-const styleConfig = {
-  textSize: 14,
-  textColor: 0xff000000,
-  statusBarBackground: 0,
-  titleStyle: {
-    textSize: 26,
-    textColor: 0xff34C759,
-  },
-  instructionStyle: {
-    textSize: 24,
-    textColor: 0xffFF6B35,
-  },
-   // New styles for error/success/warning states
-  errorStyle: { textColor: 0xffFF0000 },
-  successStyle: { textColor: 0xff00FF00 }
-};
+import { AppState } from 'react-native';
+
+useEffect(() => {
+  const subscription = AppState.addEventListener('change', (state) => {
+    if (state === 'active') {
+      FinosEKYC.onResume();
+    } else if (state === 'background') {
+      FinosEKYC.onPause();
+    }
+  });
+
+  return () => {
+    subscription.remove();
+    FinosEKYC.removeAllListeners();
+  };
+}, []);
 ```
 
+---
 
+## What's New
 
-## 🆕 What's New in v1.3.8
+### v1.4.2
+- `AppIDType` enum (NONE, HD_BANK, VIKKI) for branding/skin selection
+- `captureButtonColor` and `captureButtonDisabledColor` in StyleConfig
+- `USER_CANCEL` error code (999) for user cancellation detection
+- User cancellation callback support across all modules
+- Android responsive layouts for camera preview screens
+- Refactored StyleConfig JSON parsing with proper JSONObject
 
--   ✨ **eSign Module**: Complete electronic signature support (Sign, Verify, Certs)
--   📱 **SMS OTP**: Integrated SMS OTP verification
--   🔄 **Composite APIs**: `registerAndConfirm` for streamlined remote signing
--   👁️ **Enhanced Liveness**: improved Active Liveness configuration with custom actions
--   🛠️ **Bug Fixes**: Improved error handling and stability improvements
+### v1.4.1
+- Full iOS native bridge support
+- eSign module with PDF signing, remote signing, authorization
+- SMS OTP integration
+- Active Liveness with custom actions