kalapa_ekyc_flutter 2.0.0

Flutter plugin for the Kalapa eKYC SDK — run the eKYC flow (document capture, face liveness, and NFC chip reading) on Android and iOS via one Dart API.

kalapa_ekyc_flutter

Version 2.0.0 · Android SDK vn.kalapa:ekyc:2.12.1 · iOS KalapaEkycSDK 2.8.9

Flutter plugin for the Kalapa eKYC SDK. It bridges the native Kalapa eKYC SDKs (Android + iOS) and exposes a single Dart API to run the eKYC flow (document capture, face liveness, and NFC chip reading).

What changed in this version

• iOS now consumes the SDK from CocoaPods (KalapaEkycSDK) instead of a vendored KalapaSDK.xcframework. pod install pulls it (and iProov) automatically.
• Android consumes the SDK from Maven (vn.kalapa:ekyc). You no longer need a local kalapasdk.aar module, a :kalapasdk include, or the long manual dependency list — the plugin brings its transitive dependencies.

---

Quick Start

Get the eKYC flow running in four steps. See the sections below for full detail.

1. Add the plugin to your app's pubspec.yaml, then fetch it:

dependencies:
  kalapa_ekyc_flutter:
    path: <path/to/folder/ekyc-flutter>

flutter pub get

2. Configure the platforms:

• Android — set Java 8 + minSdk 26 / targetSdk 31 in android/app/build.gradle, and add the SDK ProGuard rules. See Android.
• iOS — add the NFC/camera keys to Info.plist, enable the Near Field Communication Tag Reading capability, then run cd ios/ && pod install. See iOS.

3. Create a session server-side via the Init Session API and pass the JWT token to the SDK (valid 10 minutes by default).

4. Start the flow:

import 'package:kalapa_ekyc_flutter/kalapa_ekyc_flutter.dart';
import 'package:kalapa_ekyc_flutter/models/config.dart';
import 'package:kalapa_ekyc_flutter/models/ekyc_result.dart';

final configInfo = ConfigInfo(
  <BASE_URL>,        // prod: "https://ekyc-sdk.kalapa.vn" · sandbox: "https://ekyc-sdk-sb.kalapa.vn"
  <BG_COLOR>,
  <MAIN_COLOR>,
  <MAIN_TEXT_COLOR>,
  <BTN_TEXT_COLOR>,
  <LANGUAGE>,        // "vi" | "en" | "ko"
  <LIVENESS_VERSION>,// 0 passive .. 2 active
);

EkycResult result = await EkycFlutter.start(
  <SESSION_ID>,      // JWT token from step 3
  <SDK_FLOW>,        // "ekyc" | "nfc_ekyc" | "nfc_only"
  configInfo,
  MyHandler(),       // your KLPCallback implementation
);

---

Requirements

Android

Setting	Value
minSdkVersion	26
targetSdkVersion	31
android.useAndroidX	true
Kotlin	1.7.10+
Java	8 (source & target compatibility VERSION_1_8)

iOS

Setting	Value
iOS Deployment Target	>= 13.0
Swift	5.9

---

Get started

1. Add the SDK to your project

Reference the plugin by path in your app's pubspec.yaml:

dependencies:
  ...
  kalapa_ekyc_flutter:
    path: <path/to/folder/ekyc-flutter>

Then fetch packages:

flutter pub get

2. Platform configuration

Android

The plugin already declares the native SDK dependency (implementation 'vn.kalapa:ekyc:<version>') and its transitive dependencies, resolved from Maven Central. You only need to make sure your app module is configured for Java 8 / the correct SDK levels.

In <your-project>/android/app/build.gradle:

android {
    ...
    compileOptions {
        sourceCompatibility = JavaVersion.VERSION_1_8
        targetCompatibility = JavaVersion.VERSION_1_8
    }

    kotlinOptions {
        jvmTarget = "1.8"
    }

    defaultConfig {
        ...
        minSdk = 26
        targetSdk = 31
        ...
    }
}

Make sure mavenCentral() and google() are in your project's repositories (default in recent Flutter templates).

Add these rules to <your-project>/android/app/proguard-rules.pro (create it if it does not exist) so the SDK survives release-build obfuscation:

-keep public class kotlin.reflect.jvm.internal.impl.** { public *; }
-keep class kotlin.Metadata { *; }

-keep class vn.kalapa.ekyc.**{*;}
-keep class com.fis.ekyc.**{*;}
-keep class com.fis.nfc.**{*;}

-keepclassmembers,allowobfuscation class * {
    @com.google.gson.annotations.SerializedName <fields>;
}


# Retain generic signatures and exception types for reflection
-keepattributes Signature, InnerClasses, EnclosingMethod, Exceptions, *Annotation*

# Prevent obfuscation of Retrofit annotations and method structures
-keep class retrofit2.** { *; }
-dontwarn retrofit2.**

# Keep interfaces containing Retrofit HTTP annotations
-keepclasseswithmembers class * {
    @retrofit2.http.* <methods>;
}

# Keep the platform-specific call adapters from being stripped
-keep class retrofit2.Platform$* { *; }

The legacy setup (a local android/kalapasdk/build.gradle module pointing at kalapasdk.aar, include ":kalapasdk" in settings.gradle, and manually listing Retrofit/CameraX/TensorFlow/etc.) is no longer required and can be removed.

iOS

Add the following to your ios/Runner/Info.plist:

<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 app target in Xcode (Signing & Capabilities).

Then install the pods:

cd ios/
pod install

This resolves KalapaEkycSDK and its iProov dependency from CocoaPods — no framework needs to be embedded manually.

---

Use the SDK in your code

Initialize a session

Each eKYC profile is associated with a unique session ID, which is a JWT access token. The SDK must use a single session ID to perform the eKYC steps. Failing to provide the session ID, or using an expired session, results in an unauthorized error. A session is valid for 10 minutes by default (adjustable).

Create a session server-side via the Init Session API and pass the token to the SDK.

Define the SDK configuration

import 'package:kalapa_ekyc_flutter/models/config.dart';

ConfigInfo configInfo = ConfigInfo(
    <BASE_URL>,
    <BG_COLOR>,
    <MAIN_COLOR>,
    <MAIN_TEXT_COLOR>,
    <BTN_TEXT_COLOR>,
    <LANGUAGE>,
    <LIVENESS_VERSION>,
    // optional named parameters (see table below):
    // requireQRCode: false,
    // customer: null,
    // nfcTimeoutInSeconds: 180,
    // skipConfirm: false,
);

Positional parameters

Name	Description
BASE_URL	Where the SDK sends its requests (all SDK APIs except Init Session), e.g. <BASE_URL>/api/kyc/scan-front. Use "https://ekyc-sdk.kalapa.vn" for Kalapa production or "https://ekyc-sdk-sb.kalapa.vn" for the sandbox/dev environment, or your own gateway for on-premise/proxy deployments.
BG_COLOR	Hex color of the SDK background.
MAIN_COLOR	Hex color of buttons and functional texts.
MAIN_TEXT_COLOR	Hex color of main texts.
BTN_TEXT_COLOR	Hex color of texts inside filled buttons.
LANGUAGE	"vi", "en", or "ko".
LIVENESS_VERSION	Liveness detection version. 0: no action (passive). 1: move face towards camera (semi-active). 2: 3 random actions — turn left/right/up/down, tilt left/right (active). Valid range: 0..3.

Optional named parameters

Name	Default	Description
mrz	null	Pre-supplied MRZ string (e.g. resuming an NFC flow).
faceDataBase64String	null	Pre-captured face image (base64) to reuse.
requireQRCode	false	Require the QR-code scan step for EID cards.
customer	null	Customer id used to load a customer-specific language pack.
nfcTimeoutInSeconds	180	NFC read timeout in seconds.
skipConfirm	false	Skip the confirmation screen.

Define the callback

During the eKYC process the SDK triggers events. Implement KLPCallback to handle them:

import 'package:kalapa_ekyc_flutter/models/ekyc_callback.dart';
import 'package:kalapa_ekyc_flutter/models/ekyc_result.dart';
import 'package:flutter/foundation.dart';

class MyHandler implements KLPCallback {
  @override
  void onKycCompletion(EkycResult? result) {
    debugPrint("onKycCompletion: ${result?.toJson()}");
  }

  @override
  void onPreComplete() {
    debugPrint("onPreComplete");
  }

  @override
  void onComplete() {
    debugPrint("onComplete");
  }

  @override
  void onEndSession() {
    debugPrint("onEndSession");
  }

  @override
  void onExpired() {
    debugPrint("onExpired");
  }
}

• onKycCompletion(result): delivers the parsed EkycResult when the flow finishes successfully.
• onComplete: the user finished all eKYC steps.
• onPreComplete: fired just before completion.
• onExpired: the session expired (10-minute default); if the user taps Retry, the SDK calls this.
• onEndSession: the user cancelled the flow.

Define the SDK flow

There are three main eKYC steps: (1) scan the document, (2) scan the face, (3) scan the NFC chip. Three flows combine them:

Flow	Scan document	Scan face	Scan NFC chip
ekyc	✅	✅
nfc_ekyc	✅	✅	✅
nfc_only		✅	✅

The flow usually matches the flow set when creating the session. In special cases they differ — e.g. a user who completed the ekyc flow but never scanned the NFC chip can reuse the same session ID with flow nfc_only to add just that step.

Start the SDK

import 'package:kalapa_ekyc_flutter/kalapa_ekyc_flutter.dart';
import 'package:kalapa_ekyc_flutter/models/ekyc_result.dart';

// SOMEWHERE IN YOUR CODE
EkycResult result = await EkycFlutter.start(
  <SESSION_ID>,
  <SDK_FLOW>,
  configInfo,
  MyHandler(),
);

start returns an EkycResult object containing the eKYC data (OCR fields, nfcResult, selfieData, decision, session, …). The same result is also delivered through MyHandler.onKycCompletion.

Fetch captured images (optional)

import 'package:kalapa_ekyc_flutter/models/ekyc_images.dart';

EkycImages images = await EkycFlutter.getImages(
  <BASE_URL>,
  result.session,
  result.nfcResult.face_image,
);
// images.frontImg / images.backImg / images.selfieImg / images.nfcImg  (base64)