Getting Started

The iApp eKYC SDK is a free, open-source (Apache-2.0) client for the iApp eKYC APIs. It captures a Thai ID card, passport or official document from the camera, runs face liveness and verification, and calls the API for you; each call is billed to your API key at the same price as calling the API directly. Source code: github.com/iapp-technology/iapp-ekyc-sdk. Try it in your browser on the live camera demo.

Install and capture

Get an API key from API Key Management. Flutter and Web run the capture engine on the device. The native wrappers for iOS, Android and React Native run the same engine, loaded from https://iapp.co.th/sdk/webview.html at runtime, so capture is identical on every platform and the app needs internet access.

Flutter

1. Requires Flutter ≥ 3.32 and Dart ≥ 3.8; Android minSdk 24; iOS 15.5+ with NSCameraUsageDescription in Info.plist (the repository's flutter/example app has the permission strings).
2. Add the SDK as a git dependency in pubspec.yaml.
3. Create the client and capture the front of a Thai ID card.

dependencies:
  iapp_ekyc_sdk:
    git:
      url: https://github.com/iapp-technology/iapp-ekyc-sdk.git
      path: flutter

import 'package:iapp_ekyc_sdk/iapp_ekyc_sdk.dart';

final client = IappEkycClient(apiKey: 'YOUR_API_KEY');

final front = await DocumentCaptureView.start(
  context,
  client: client,
  documentType: DocumentType.thaiIdFront,
  locale: EkycLocale.th,
);

Web

1. Use a browser with WebAssembly and getUserMedia, served over HTTPS or localhost; browsers block the camera on insecure origins.
2. Install the package.
3. Create the client and capture the front of a Thai ID card. locale is 'en', 'th' or 'zh'.

npm install @iapp-technology/ekyc-sdk

import { IappEkyc } from '@iapp-technology/ekyc-sdk';

const ekyc = new IappEkyc({ apiKey: 'YOUR_API_KEY' });

const front = await ekyc.captureDocument({
  mount: document.getElementById('ekyc-mount'),
  documentType: 'thaiIdFront',
  locale: 'th',
});

Without a bundler, load the UMD bundle. It exposes the window.IappEkyc namespace, and the class lives inside it:

<script src="https://unpkg.com/@iapp-technology/ekyc-sdk"></script>
<script>
  const ekyc = new window.IappEkyc.IappEkyc({ apiKey: 'YOUR_API_KEY' });
</script>

The capture engine's assets load only when a flow starts. If your Content Security Policy blocks CDN requests, self-host them and set the assetBaseUrl option.

iOS

1. Requires iOS 15+ and NSCameraUsageDescription in Info.plist.
2. In Xcode choose File → Add Package Dependencies…, enter https://github.com/iapp-technology/iapp-ekyc-sdk and add the product IappEkyc.
3. Present a flow.

import IappEkyc

let config = IappEkycConfig(apiKey: "YOUR_API_KEY", flow: .documentCapture)
config.documentType = .thaiIdFront
IappEkycSdk.present(from: self, config: config) { result in /* ... */ }

Results, liveness and Objective-C: Native SDKs.

Android

1. Requires minSdk 24 and an up-to-date Android System WebView (Chrome/WebView ≥ 100 recommended).
2. Add the dependency from JitPack.
3. Register the contract and launch a flow.

// app/build.gradle.kts — plus maven("https://jitpack.io") in repositories
dependencies { implementation("com.github.iapp-technology:iapp-ekyc-sdk:v0.2.0") }

val ekyc = registerForActivityResult(IappEkycContract()) { result -> /* ... */ }
ekyc.launch(IappEkycRequest.DocumentCapture(config, EkycDocumentType.THAI_ID_FRONT))

Configuration, results and Java: Native SDKs.

React Native

1. Requires React Native ≥ 0.72 and react-native-webview ≥ 13.6.
2. Install from a checkout of the repository.
3. Render the flow.

git clone https://github.com/iapp-technology/iapp-ekyc-sdk
npm install ./iapp-ekyc-sdk/react-native react-native-webview

<IappEkycFlow flow="documentCapture" documentType="thaiIdFront"
  apiKey="YOUR_API_KEY" onResult={...} onError={...} onCancel={...} />

Camera permissions and a full-screen Modal: Native SDKs.

API key

A key shipped inside an app can be extracted, from a decompiled APK or the browser's developer tools. In production, point the SDK at your own backend and keep the iApp key there:

IappEkycClient(apiKey: '', baseUrl: 'https://your-backend.example.com/ekyc')

With an empty apiKey the SDK sends no apikey header; your backend adds the real key and forwards the call to https://api.iapp.co.th. At minimum, give each app its own restricted key so a leaked one can be revoked on its own. Details: SECURITY.md.

Flows and prices

Each flow calls one API and is billed at that API's price.

• ID card capture: finds the card, waits for a sharp, steady frame, corrects perspective and submits. 1.25 IC front, 0.75 IC back.
• Passport capture: the same engine, tuned for the passport data page (MRZ). 0.75 IC.
• Official card capture: driver license, bank book, ID card with signature. 1.25 IC per page.
• Face Active Liveness: randomized on-device challenges, best-frame selection and a server-signed verdict. 1 IC.
• Face Verification: compares two face images in one call. 0.3 IC.
• Face Passive Liveness: a spoof check on a single image. 0.3 IC.

Theme and language

Every platform ships a light-blue default theme and accepts overrides under the same token names; the native wrappers take them through their config objects. Screen text ships in English, Thai and Chinese: locale: 'th' on Web, EkycLocale.th on Flutter, config.locale = .th on iOS, .locale(EkycLocale.TH) on Android and locale="th" on React Native.

Flutter

EkycTheme is a plain immutable class with no dependency on Theme.of:

const theme = EkycTheme.lightBlue;             // default
final custom = EkycTheme.lightBlue.copyWith(
  primary: Color(0xFF113F7B),
  borderRadius: 12,
);
DocumentCaptureView.start(context, theme: custom, ...);

Web

Tokens are set as CSS custom properties on the mount element:

new IappEkyc({ apiKey, theme: { primary: '#113F7B', borderRadius: 12 } });

/* or override with plain CSS */
#ekyc-mount { --iapp-ekyc-primary: #113f7b; --iapp-ekyc-border-radius: 12px; }

Theme tokens and defaults

Token	Default	Used for
primary	#0284C7	buttons, active guide frame, progress
primaryDark	#0C4A6E	headings, instruction text
primaryLight	#BAE6FD	idle guide frame, subtle accents
surface	#F0F9FF	sheets, instruction chips
onPrimary	#FFFFFF	text and icons on primary
success	#22C55E	quad locked, challenge passed
warning	#F59E0B	hold still, too blurry
error	#EF4444	failures
overlayScrim	#0C4A6E at 60%	camera overlay outside the guide
brandDeep	#113F7B	optional iApp brand accent
borderRadius	16	chips, buttons, result cards
guideStrokeWidth	3	guide frame stroke
fontFamily	platform default	optional override

More: THEMING.md.