react-native-kalapa-tpbank-ekyc

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

• Install pods:

cd ios && pod install

• 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

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

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

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

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

Troubleshooting

• If you encounter build issues on iOS:

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

• If you encounter build issues on Android:

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

• 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 [e-mail]

License

Kalapa JSC™ © 2025