@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

``bash
npm install @finos_sdk/sdk-ekyc


or


yarn add @finos_sdk/sdk-ekyc
`

📖 Quick Start

$3

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

$3

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

`typescript
// 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.

$3

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

$3

Register a device to perform signing operations.

`typescript
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

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

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

$3

`typescript
// 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
);
`

$3

Supported flows for remote signing:

`typescript
// 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.

`typescript
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)

$3

Refined configuration options for Active Liveness and Custom Actions.

`typescript
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);
`

$3


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

await FinosEKYC.startOcr(config);
`

$3


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

await FinosEKYC.startNfcScan(config);
`

⚙️ Configuration Options

$3

Customize the UI appearance:

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

🆕 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