React Native Kalapa eKYC SDK

A React Native SDK for implementing eKYC (Electronic Know Your Customer) functionality in your mobile applications. This SDK provides a seamless integration for identity verification and document scanning.

Changelog

• Add more error result code to handle
• Add webview callback
• Maintain and optimize

Requirements

• React Native >= 0.66.4
• iOS >= 13.0
• Android API Level >= 26

Features

• Document scanning and verification
• Face liveness detection
• Customizable UI
• Multi-language support (English and Vietnamese)
• Comprehensive error handling
• Secure data transmission

Installation

npm install react-native-kalapa-tpbank-ekyc react-native-reanimated
# or
yarn add react-native-kalapa-tpbank-ekyc react-native-reanimated

Alternatively, you can manually add the following line to your app/package.json:

"dependencies": {
    "react-native-kalapa-tpbank-ekyc": "^1.0.5",
    "react-native-reanimated": "^1.9.0"
}

iOS Setup

1. Install pods:

cd ios && pod install

2. Declare camera and NFC permission

• Update the Info.plist by adding these lines:

<key>LSApplicationQueriesSchemes</key>
<array>
	<string>undecimus</string>
	<string>sileo</string>
	<string>zbra</string>
	<string>filza</string>
</array>
<key>NFCReaderUsageDescription</key>
<string>This eKYC app needs NFC reader to scan chip</string>
<key>com.apple.developer.nfc.readersession.iso7816.select-identifiers</key>
<array>
<string>A0000002471001</string>
<string>A0000002472001</string>
<string>00000000000000</string>
</array>
<key>NSCameraUsageDescription</key>
<string>This eKYC app needs to use camera to scan document</string>

• Add the Near Field Communication Tag Reading capability to your project target

Usage

import { KalapaSDK } from 'react-native-kalapa-tpbank-ekyc';

const YourComponent = () => {
  const handleComplete = (result) => {
    console.log('eKYC completed:', result);
  };

  const handleError = (error) => {
    console.error('eKYC error:', error);
  };

  const handleClose = () => {
    console.log('eKYC closed');
  };

  const config = {
    domain: "https://ekyc-sdk.kalapa.vn", // For production
    main_color: '#A167D8',
    main_text_color: "#000000",
    btn_text_color: "#FFFFFF",
    background_color: '#FFFFFF'
  };

  return (
    <KalapaSDK
      dopBaseURL="YOUR_DOP_BASE_URL"
      accessToken="YOUR_ACCESS_TOKEN"
      phoneNumber="USER_PHONE_NUMBER"
      appconfig={config}
      onComplete={handleComplete}
      onError={handleError}
      onClose={handleClose}
    />
  );
};

Error Handling

The SDK provides comprehensive error handling through the onError callback:

import { KalapaSDKResultCode } from 'react-native-kalapa-tpbank-ekyc';

const handleError = (error) => {
      console.error("Unknown error:", KalapaSDKResultCode.getMessage(error.code));
};

Result Format

The onComplete callback receives a JSON string with the following structure:

Front Side (frontResult)

| Property | Type | Description | |----------|------|-------------| | type | string | Type of ID card | | name | string | Full name | | id_number | string | ID number | | gender | string | Gender | | birthday | string | Birthday | | home | string | Home town | | resident | string | Resident address | | features | string | Personal features | | doi | string | Date of issued | | poi | string | Place of issued | | doe | string | Date of expiry | | qr_code | object | QR code data if present | | mrz_data | object | Machine Readable Zone data | | nfc_data | object | Data in NFC chip |

QR Code (qr_code)

| Property | Type | Description | |----------|------|-------------| | data.decoded_text | string | Decoded QR code text |

MRZ Data (mrz_data)

| Property | Type | Description | |----------|------|-------------| | data.raw_mrz | string | Raw MRZ text |

NFC Data (nfc_data)

| Property | Type | Description | |----------|------|-------------| | name | string | Full name from NFC | | id_number | string | ID number from NFC | | gender | string | Gender from NFC | | nation | string | Ethnicity from NFC | | date_of_birth | string | Birthday from NFC | | date_of_issuance | string | Date of issued from NFC | | date_of_expiry | string | Expired date from NFC | | hometown | string | Home town from NFC | | address | string | Resident address from NFC | | personal_identification | string | Personal features from NFC | | father_name | string | Father's name from NFC | | mother_name | string | Mother's name from NFC | | mrz | string | MRZ data from NFC |

Additional Notes

1. The SDK requires internet permission. Add to your Android manifest:

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

2. For iOS, ensure you have the following in your Info.plist:

<key>NSCameraUsageDescription</key>
<string>Camera access is required for eKYC verification</string>

Troubleshooting

1. If you encounter build issues on iOS:

   • Clean the build folder: cd ios && xcodebuild clean
   • Remove pods: rm -rf Pods && pod install

2. If you encounter build issues on Android:

   • Clean the project: cd android && ./gradlew clean
   • Rebuild: ./gradlew assembleDebug

3. Common issues:

   • Make sure all required permissions are properly set
   • Verify your credentials (accessToken) are correct
   • Check your internet connection
   • Ensure the device meets the minimum requirements

Support

For support, please contact [email protected]

License

Kalapa JSC™ © 2025