@finos_sdk/sdk-ekyc

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.3.8

🚀 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

� 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

npm install @finos_sdk/sdk-ekyc
# or
yarn add @finos_sdk/sdk-ekyc

📖 Quick Start

1. Import the SDK

import { FinosEKYC, FinosESign, getEkycError } from '@finos_sdk/sdk-ekyc';
import type {
  NfcConfig,
  C06Config,
  OcrConfig,
  LivenessConfig,
  FaceServiceConfig,
  SmsOtpConfig,
  SDKFlowType
} from '@finos_sdk/sdk-ekyc';

2. Complete eKYC Flow (Recommended)

The SDK provides a unified method to handle the complete eKYC flow:

// Configure your app keys
const AppKey = {
  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',
};

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);
  }
};

✍️ eSign Integration

The eSign module allows for electronic signature operations, including device registration, certificate management, and document signing.

1. Initialize eSign

// Initialize eSign (optional: pass token and isProd flag)
await FinosESign.initializeESign("your-access-token", false);

2. Device Registration

Register a device to perform signing operations.

const result = await FinosESign.registerDevice(
  "12345678", // 8-digit recovery code
  "123456",   // 6-digit PIN code
  "fcm-token" // Optional FCM token
);
console.log(result.message);

3. Manage Certificates

// List certificates
const certs = await FinosESign.listCerts(1, 10);

// Verify specific certificate
const verifyResult = await FinosESign.verifyCert("serial-number");

4. Sign Documents

// Sign a PDF document
const signResult = await FinosESign.signPdf(JSON.stringify(signRequest));

// Sign and Confirm (Composite API)
const result = await FinosESign.confirmSign(
    "sign-request-id",
    "123456" // PIN code
);

5. Remote Signing

Supported flows for remote signing:

// Register for remote signing
const regResult = await FinosESign.registerRemoteSigning(JSON.stringify(requestBody));

// Register and Confirm in one step
const compositeResult = await FinosESign.registerAndConfirm(
    JSON.stringify(requestBody),
    "base64-confirmation-doc"
);

📨 SMS OTP Integration

Integrated SMS OTP verification for multi-factor authentication.

const otpConfig: SmsOtpConfig = {
    phone: "0901234567",
    // other config params
};

// 1. Send OTP
const sendResult = await FinosEKYC.sendOtp(otpConfig);

// 2. Verify OTP
const verifyResult = await FinosEKYC.verifyOtp(otpConfig, "123456");

// 3. Resend OTP
const resendResult = await FinosEKYC.resendOtp(otpConfig);

🎯 Individual Module APIs (Advanced)

Liveness Detection (Updated)

Refined configuration options for Active Liveness and Custom Actions.

import { FinosEKYC, FinosESign, getEkycError, SDKFaceDetectStatus } from '@finos_sdk/sdk-ekyc';

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
};

await FinosEKYC.startLiveness(config);

OCR Processing

const config: OcrConfig = {
  appKey: 'your_app_key',
  idImagePath: 'base64_image_data',
  expectedDocumentSide: 'front',
};

await FinosEKYC.startOcr(config);

NFC Scanning

const config: NfcConfig = {
  appKey: 'your_app_key',
  documentNumber: '123456789',
  birthDate: '01011990',
  expireDate: '01012030',
};

await FinosEKYC.startNfcScan(config);

⚙️ Configuration Options

Style Configuration

Customize the UI appearance:

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 }
};

🆕 What's New in v1.3.8

• ✨ 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