finos-ekyc-sdk

React Native SDK for FinOS eKYC & Electronic Signature (v2.0.7).

Supports Vietnamese CCCD NFC chip reading, OCR processing, Active/Passive Liveness detection, Face matching, C06 residence verification, SMS OTP verification, and Electronic Signature (eSign / EasyCA).

Features

• Unified eKYC Flow — Complete verification flow (OCR → NFC → Liveness) with 1 method call.
• Vietnamese CCCD NFC Reading — High-speed chip scanning via native NFC adapters.
• OCR Processing — Extract card details and validate document authenticity.
• Active & Passive Liveness — Facial anti-spoofing with configurable action challenges.
• Face Matching — 1:1 facial biometric comparison.
• C06 Residence Verification — National population database cross-check.
• SMS OTP — Integrated SMS verification flow with automatic session handling.
• eSign / EasyCA — Full digital signature suite (PDF signing, device authorization).
• TypeScript Support — First-class TypeScript definitions included out-of-the-box.

Requirements

• React Native: >= 0.70.0 (hỗ trợ đầy đủ RN 0.77+ New Architecture & Bridgeless)
• Android: API Level 24+ (Android 7.0+)
• iOS: 15.0+ (Swift 5.7+ / Xcode 16+)
• Thiết bị hỗ trợ Camera và/hoặc NFC tương ứng với từng module sử dụng.

Installation

npm install finos-ekyc-sdk
# or
yarn add finos-ekyc-sdk

Platform Setup

Android

The SDK resolves underlying native dependencies (asia.finos:*) directly from Maven Central.

Ensure your android/build.gradle includes mavenCentral():

allprojects {
    repositories {
        google()
        mavenCentral()
    }
}

iOS

Run CocoaPods installation:

cd ios && pod install

Add required permissions to ios/YourApp/Info.plist:

<key>NSCameraUsageDescription</key>
<string>Camera access is required for ID card scanning and selfie liveness detection.</string>
<key>NFCReaderUsageDescription</key>
<string>NFC access is required to read Vietnamese CCCD chip data.</string>
<key>com.apple.developer.nfc.readersession.iso7816.select-identifiers</key>
<array>
    <string>A0000002471001</string>
    <string>A0000002472001</string>
    <string>00000000000000</string>
</array>

Canonical Customer Entry Points

1. eKYC Quick Start (1-Line API)

Khởi chạy quy trình eKYC trọn gói (tự động điều phối các bước xác thực):

import { FinosEKYC, EkycFlow, SDKEnv } from 'finos-ekyc-sdk';

// Khởi chạy eKYC flow
const result = await FinosEKYC.quickStart({
  appKey: 'YOUR_FINOS_APP_KEY',
  flow: [EkycFlow.ocr, EkycFlow.nfc, EkycFlow.liveness],
  language: 'vi',
  env: SDKEnv.test, // SDKEnv.test | SDKEnv.stag | SDKEnv.uat | SDKEnv.prod
  maxRetry: 3,
});

console.log('eKYC Success:', result);

2. Khởi tạo phiên từ Server (Server-to-Server)

Để bảo mật tối ưu và tránh lưu Master API Key trên ứng dụng client, bạn có thể khởi tạo phiên từ server:

import { FinosEKYC, EkycFlow, SDKEnv } from 'finos-ekyc-sdk';

// 1. Cung cấp sessionToken từ backend
await FinosEKYC.setSessionToken(
  'jwt_token_from_backend',
  'txn_id_from_backend', // Tuỳ chọn
  900                    // Mặc định: 15 phút
);

// 2. Khởi chạy luồng eKYC (không cần truyền appKey khi đã set sessionToken)
const result = await FinosEKYC.quickStart({
  flow: [EkycFlow.ocr, EkycFlow.nfc, EkycFlow.liveness],
  language: 'vi',
  env: SDKEnv.prod,
});

// Hoặc truyền thẳng sessionToken vào quickStart (1 dòng duy nhất):
const resultS2S = await FinosEKYC.quickStart({
  sessionToken: 'jwt_token_from_backend',
  transactionId: 'txn_id_from_backend',
  flow: [EkycFlow.ocr, EkycFlow.nfc, EkycFlow.liveness],
});

3. Single Module APIs

Khởi chạy từng module riêng lẻ:

import { FinosEKYC } from 'finos-ekyc-sdk';

// 1. Chỉ quét OCR
await FinosEKYC.startOcr('YOUR_APP_KEY', { language: 'vi' });

// 2. Chỉ đọc NFC
await FinosEKYC.startNfc('YOUR_APP_KEY', { language: 'vi' });

// 3. Chỉ nhận diện Liveness
await FinosEKYC.startLiveness('YOUR_APP_KEY', { language: 'vi' });

// 4. Chỉ so khớp khuôn mặt Face Service
await FinosEKYC.startFaceService('YOUR_APP_KEY', { language: 'vi' });

// 5. Chỉ xác thực C06
await FinosEKYC.startC06('YOUR_APP_KEY', { language: 'vi' });

4. Builder Pattern (EkycConfigBuilder)

import { EkycConfigBuilder, EkycFlow, SDKEnv } from 'finos-ekyc-sdk';

const result = await new EkycConfigBuilder()
  .appKey({
    appKey: 'YOUR_FINOS_APP_KEY',
    appKeyOcr: 'YOUR_OCR_KEY',
    appKeyNfc: 'YOUR_NFC_KEY',
    appKeyLiveness: 'YOUR_LIVENESS_KEY',
  })
  .flow(EkycFlow.ocr, EkycFlow.nfc, EkycFlow.liveness)
  .language('vi')
  .maxRetry(3)
  .style({ captureButtonColor: 0xFF00A86F })
  .start();

5. Cấu hình Logging & Chẩn đoán

// Bật/tắt log mạng dạng cURL request/response (mặc định tắt)
FinosEKYC.setNetworkLoggingEnabled(true);

// Bật/tắt log debug nội bộ SDK (mặc định tắt)
FinosEKYC.setDebugLoggingEnabled(true);

SMS OTP Verification

Sử dụng SmsOtpSession (Quản lý tự động)

import { SmsOtpSession } from 'finos-ekyc-sdk';

const session = new SmsOtpSession({
  apiKey: 'YOUR_SMS_OTP_KEY',
  phoneNumber: '+84901234567',
});

// 1. Gửi OTP
await session.sendOtp();

// 2. Xác thực OTP
await session.verifyOtp('123456');

// 3. Gửi lại OTP
await session.resendOtp();

Sử dụng FinosOTP (Cấu hình thủ công)

import { FinosOTP } from 'finos-ekyc-sdk';

// 1. Gửi OTP
const sendRes = await FinosOTP.sendOtp({
  appKey: 'YOUR_SMS_OTP_KEY',
  phoneNumber: '+84901234567',
  referenceId: 'ref-001',
  purpose: 'transaction',
});

// 2. Xác thực OTP
const verifyRes = await FinosOTP.verifyOtp(
  {
    appKey: 'YOUR_SMS_OTP_KEY',
    phoneNumber: '+84901234567',
    referenceId: 'ref-001',
    requestId: sendRes.requestId,
  },
  '123456'
);

Electronic Signature (eSign / EasyCA)

Sử dụng ESignFlow (Đơn giản hóa)

import { ESignFlow, SDKEnv } from 'finos-ekyc-sdk';

// Bước 1: Khởi tạo
await ESignFlow.setup('YOUR_AUTH_TOKEN', SDKEnv.test);

// Bước 2: Ký tài liệu PDF
await ESignFlow.sign(JSON.stringify(signPayload));

// Bước 3: Đăng ký thiết bị và ký trong 1 bước
await ESignFlow.registerAndSign(JSON.stringify(signPayload), '123456');

Sử dụng FinosESign (Nâng cao)

import { FinosESign, SDKEnv } from 'finos-ekyc-sdk';

// Khởi tạo eSign
await FinosESign.initialize(SDKEnv.test);
await FinosESign.initializeESign('YOUR_FINOS_TOKEN');

// Lấy SDK token
const token = await FinosESign.getSdkToken('012345678012', 'Nguyen Van A', 'device-id-123');

// Mở session
const session = await FinosESign.openSessionId(token, 'username', true);

// Đăng ký thiết bị
await FinosESign.registerDevice('12345678', '123456');

// Ký PDF
const signResult = await FinosESign.signPdf(JSON.stringify(signPayload));

Xử lý Lỗi & Danh mục Error Codes (EkycErrors)

Toàn bộ mã lỗi được phân nhóm tường minh qua catalog EkycErrors:

import { FinosEKYC, EkycErrors, getEkycError } from 'finos-ekyc-sdk';

try {
  const result = await FinosEKYC.quickStart({ appKey: 'YOUR_KEY' });
} catch (error) {
  const err = getEkycError(error);

  if (err.code === EkycErrors.General.USER_CANCEL.code) {
    console.log('Người dùng chủ động hủy');
    return;
  }

  switch (err.code) {
    case EkycErrors.OCR.BLURRY.code:
      console.warn('Ảnh chụp bị mờ, vui lòng chụp lại');
      break;
    case EkycErrors.Face.LIVENESS_FAIL.code:
      console.warn('Xác thực khuôn mặt không đạt');
      break;
    case EkycErrors.NFC.SCAN_ERROR.code:
      console.warn('Đọc chip NFC thất bại');
      break;
    default:
      console.error(`Lỗi [${err.event}] (${err.code}): ${err.message}`);
  }
}

Bảng Mã lỗi Phổ biến

| Mã lỗi | Hằng số EkycErrors | Mô tả | |---|---|---| | 999 | General.USER_CANCEL | Người dùng chủ động đóng SDK / hủy flow | | 000 | General.ERROR_UNKNOWN | Lỗi không xác định | | 001 | OCR.UNRECOGNIZED_ID_CARD | Không nhận dạng được thẻ CCCD | | 008 | OCR.BLURRY | Ảnh chụp thẻ bị mờ nhòe | | 009 | OCR.GLARE | Ảnh chụp thẻ bị lóa sáng | | 109 | Face.FACE_ERROR | Khuôn mặt không khớp giữa selfie và CCCD | | 110 | Face.LIVENESS_ERROR | Lỗi trong quá trình liveness | | 111 | Face.LIVENESS_FAIL | Phát hiện gian lận liveness / giả mạo | | 200 | NFC.SCAN_ERROR | Đọc dữ liệu chip NFC thất bại | | 203 | NFC.C06_ERROR | Đối soát dữ liệu C06 không khớp | | 300 | SmsOtp.SMS_OTP_ERROR | Lỗi gửi hoặc xác thực SMS OTP |

Danh mục Tài liệu Module chi tiết (Documentation)

| Module | Tài liệu Tiếng Anh | Tài liệu Tiếng Việt | |---|---|---| | OCR (Nhận diện CCCD) | DOC_OCR_SDK_Integration_ReactNative.md | DOC_OCR_SDK_Integration_ReactNative_vi.md | | NFC (Đọc chip CCCD) | DOC_NFC_SDK_Integration_ReactNative.md | DOC_NFC_SDK_Integration_ReactNative_vi.md | | Liveness (Kiểm tra sống) | DOC_Liveness_SDK_Integration_ReactNative.md | DOC_Liveness_SDK_Integration_ReactNative_vi.md | | Face Match (So khớp mặt) | DOC_FaceService_SDK_Integration_ReactNative.md | DOC_FaceService_SDK_Integration_ReactNative_vi.md | | SMS OTP | DOC_SMS_OTP_SDK_Integration_ReactNative.md | DOC_SMS_OTP_SDK_Integration_ReactNative_vi.md | | eSign (Chữ ký số) | DOC_eSign_SDK_Integration_ReactNative.md | DOC_eSign_SDK_Integration_ReactNative_vi.md | | Cài đặt & Cấu hình | installation-reactnative.md | configuration-reactnative.md | | Mã lỗi & Sự kiện | error-codes.md | events.md |

Quản lý Vòng đời Ứng dụng (Lifecycle)

Khi sử dụng quét chip NFC trên Android, liên kết vòng đời Activity để tối ưu tài nguyên phần hardware:

import React, { useEffect } from 'react';
import { AppState } from 'react-native';
import { FinosEKYC } from 'finos-ekyc-sdk';

export function EkycScreen() {
  useEffect(() => {
    const subscription = AppState.addEventListener('change', (nextState) => {
      if (nextState === 'active') {
        FinosEKYC.onResume();
      } else if (nextState === 'background') {
        FinosEKYC.onPause();
      }
    });

    return () => {
      subscription.remove();
      FinosEKYC.removeAllListeners();
    };
  }, []);

  return null;
}