Mobile SDK Overview
The eKYC Mobile SDK wraps the capture, quality-check and verification flow into two calls: takeNID for the identity card and takeFaces for the selfie. It ships for Android, iOS and Flutter, with the same concepts and error codes across all three.
Platforms
| What | Description |
|---|---|
| Android | Kotlin. Gradle 7.4, minSdk 21, targetSdk 33. Current version 1.1.9. |
| iOS | Swift 5. Xcode 16.0+, iOS 13+. Current version 1.1.9. |
| Flutter | Dart. Flutter SDK >=3.0.0 <4.0.0. Current version 1.0.0. |
All three call the same API underneath, so the verdicts, image labels and response shapes documented there apply unchanged.
What the SDK Does For You
Each entry point runs a pipeline rather than a single action.
| What | Description |
|---|---|
takeNID | Captures the card → uploads the image → checks sanity → checks tampering → extracts card info. |
takeFaces | Captures the selfie → uploads the images → checks face sanity → checks liveness. |
If any step fails the pipeline stops and returns the error; it does not continue with a bad image. Each SDK also exposes the individual API calls (upload, checkNIDSanity, checkNIDTampering, readNIDInfo, checkFaceSanity, checkFaceLiveness, compareFaces) when you need to drive the steps yourself.
WARNING
The SDK's result object is for driving the UI only. Base the onboarding decision on results your backend fetches from the eKYC server (or on responses whose X-Signature your backend has verified) — never on verdicts reported by the app or browser, which a modified client can change.
Common Configuration
Every platform builds a config object with the same four concerns.
| Param | Type | Required | Default | Description |
|---|---|---|---|---|
baseUrl | string | Yes | — | Base URL for API requests. See Overview § Prerequisites. |
languageCode | string | No | vi | vi for Vietnamese, en for English. |
tokenProvider | TokenProvider | Yes | — | Supplies the authentication token. Called with timestamp, path and method. |
logger | Logger | No | — | Receives info, error and warning messages from the SDK. |
WARNING
TokenProvider.getToken(timestamp, path, method) takes the request method and path precisely because the token is a per-request signature, not a static string. Never hardcode a token in the app — compute it on your backend. See Request Signing for the scheme.
Capture Options
Both entry points accept flags that switch off parts of the pipeline.
| Param | Type | Required | Default | Description |
|---|---|---|---|---|
captureOnly | bool | No | false | Capture the image only — no upload, no quality check, no OCR. |
requiredReview | bool | No | true | Show the confirmation screen after capture. NID only. |
autoCaptureEnable | bool | No | true | Capture automatically once image quality passes. Set false for a manual shutter. NID only. |
requiredScanQR | bool | No | false | Scan the QR code on the front of the card. NID only. |
cardSides | CardSide[] | No | [front, back] | Which sides to capture. |
otherSideImages | Map | No | — | The already-captured other side, so quality checks can run across both. |
INFO
Sanity and tampering checks are more accurate with both sides of the card. If your flow captures one side per call, pass the other side through otherSideImages rather than checking each side in isolation.
Image Labels
When calling upload directly, label MUST be one of:
| Field | Type | Description |
|---|---|---|
portrait | string | The portrait photo. |
qr_code | string | The QR code image. |
id_card.vn.national_id.front | string | Front side of a Vietnam card (CMND old/new, CCCD, Passport). |
id_card.vn.national_id.back | string | Back side of a Vietnam card. |
doc.vn.business_license | string | The business licence image. |
SDK Error Codes
These are raised by the SDK itself, and are separate from the numeric API error codes.
| Field | Type | Description |
|---|---|---|
40000 | string | Timeout. |
40001 | string | User cancelled — pressed the device back button or the in-screen back button. |
40002 | string | Required permissions were not granted. |
40003 | string | Opening the camera device failed. Android and Flutter only. |
50000 | string | Unexpected runtime exception. |
60000 | string | NID sanity check failed. |
60001 | string | NID tampering check failed. |
60002 | string | Face sanity check failed. |
60003 | string | Face liveness check failed. |
The constant names differ per platform — EkycError.NID_SANITY_FAILED on Android, kErrorCodeNidSanityFailed on iOS, EkycFailure.nidSanityFailed on Flutter — but the numeric values are identical.
APIs Used
| What | Description |
|---|---|
| Upload Image | Every captured image is uploaded before any check runs. |
| Verify ID Card Sanity | Checks the authenticity and validity of the card. |
| Detect ID Card Tampering | Forgery and alteration detection. |
| Read ID Card Info | OCR, MRZ and QR extraction. |
| Verify Face Sanity · Verify Face Liveness | Selfie quality and liveness. |
| Compare Faces | Matches the selfie against the card portrait. |
Next Steps
- Android SDK Integration — integration guide for Kotlin
- iOS SDK Integration — integration guide for Swift
- Flutter SDK Integration — integration guide for Dart, including UI theming
- Error Codes — the API error codes the SDK surfaces