prism_ekyc #

A Flutter package for end-to-end electronic KYC (eKYC) of Japanese IC identity cards. The package presents a self-contained UI flow, reads the card chip over NFC and returns a strongly-typed result.

Supported cards

How it works — end to end #

Welcome
  └─ Nationality selector
       └─ ID card instructions
            └─ NFC scan  ← card number / PIN entered here
                 │
                 ├─ flutter_libjeid reads chip over NFC
                 │      • card front PNG image
                 │      • holder face photo
                 │      • chip-direct text fields (DL / My Number)
                 │      • runs on card front PNG
                 │      • extracts: name, nationality, DOB, gender,
                 │        address, visa status, dates
                 │
                 └─ NfcScanResult built (chip data takes priority; OCR fills gaps)
                      │
                      ├─ Backside capture  (camera — photo of card back)
                      ├─ Face verification (liveness check + face match)
                      └─ Registration form (pre-filled, user confirms)
                               │
                               └─ onComplete(EkycResult)

NFC layer — flutter_libjeid #

Card type is auto-detected from the number the user types:

The NFC scan screen shows PIN input fields automatically when the input matches a Driver's License or My Number format.

Form auto-fill #

Once NfcScanResult is built, UserFormData.fromNfc() pre-populates the Registration Form screen. The user can review and edit every field before submitting.

Platform requirements #

Installation #

dependencies:
  prism_ekyc:
    path: ../prism_ekyc   # local
    # or git / pub.dev reference when published

iOS setup #

1 — NFC entitlement #

In Xcode: Signing & Capabilities → + Capability → Near Field Communication Tag Reading

This adds to your .entitlements file:

<key>com.apple.developer.nfc.readersession.formats</key>
<array>
  <string>TAG</string>
</array>

2 — Info.plist usage descriptions #

<key>NFCReaderUsageDescription</key>
<string>Used to read your ID card chip for identity verification.</string>

<key>NSCameraUsageDescription</key>
<string>Used to photograph your ID card and verify your face.</string>

3 — Podfile #

No extra pods are required. flutter_libjeid ships its own iOS implementation and prism_ekyc links only Apple's Vision framework (for face comparison).

Android setup #

1 — AndroidManifest.xml #

The plugin manifest already declares NFC permission. Confirm your android/app/src/main/AndroidManifest.xml has:

<uses-permission android:name="android.permission.NFC" />
<uses-feature android:name="android.hardware.nfc" android:required="false" />

Set required="false" if you want the app installable on non-NFC devices (the scan step will return an error at runtime on those devices).

Your <activity> tag must use singleTop launch mode so NFC intents are delivered to the running activity:

<activity
    android:name=".MainActivity"
    android:launchMode="singleTop"
    ...>

2 — MainActivity #

No changes required. flutter_libjeid registers its own ActivityAware plugin and handles foreground NFC dispatch internally.

Quick start #

import 'package:prism_ekyc/prism_ekyc.dart';

Navigator.push(
  context,
  MaterialPageRoute(
    builder: (_) => PrismEkyc.screen(
      PrismEkycConfig(
        onComplete: (EkycResult result) {
          print(result.formData.fullName);
          print(result.nfcData?.dateOfBirth);
          print(result.nfcData?.nationality);
        },
      ),
    ),
  ),
);

Configuration — PrismEkycConfig #

PrismEkycConfig({
  void Function(EkycResult)? onComplete,
  PrismLanguage defaultLanguage = PrismLanguage.english,
  List<PrismLanguage> availableLanguages = const [...],
  List<SupportedCountry> supportedCountries = const [...],
  bool debugBypassNfc = false,
})

Available languages #

PrismLanguage.english
PrismLanguage.japanese

Supported countries #

SupportedCountry.brazil       SupportedCountry.indonesia
SupportedCountry.philippines  SupportedCountry.vietnam
SupportedCountry.southKorea   SupportedCountry.china
SupportedCountry.malaysia     SupportedCountry.singapore
SupportedCountry.thailand

Result types #

EkycResult #

class EkycResult {
  final NfcScanResult?  nfcData;              // chip + OCR extracted data
  final Uint8List?      backsideImage;        // card back photo (JPEG bytes)
  final bool            faceVerified;         // liveness challenges passed
  final double?         faceMatchConfidence;  // 0.0–1.0, null if no face photo
  final UserFormData    formData;             // confirmed form values
}

NfcScanResult — chip + OCR extracted fields #

RC = Residence Card fields are populated via OCR because the free-tier libjeid API does not expose personal text fields (name, DOB, nationality) directly from the chip. The card front image is read from the chip and OCR is run on it.

UserFormData — confirmed form values #

Face match confidence #

faceMatchConfidence is derived from the feature-print distance between the chip face photo and the live selfie captured during face verification:

faceVerified is always true when onComplete fires — a mismatch blocks progression and the user must retake the selfie.

Debug mode #

Set debugBypassNfc: true to skip the NFC step entirely and inject a mock NfcScanResult. This is useful for testing the UI flow and form auto-fill without a physical card or NFC device.

PrismEkyc.screen(
  PrismEkycConfig(
    debugBypassNfc: true,
    onComplete: (result) { ... },
  ),
)

Full example #

import 'package:flutter/material.dart';
import 'package:prism_ekyc/prism_ekyc.dart';

class VerifyPage extends StatelessWidget {
  const VerifyPage({super.key});

  @override
  Widget build(BuildContext context) {
    return Scaffold(
      body: Center(
        child: ElevatedButton(
          onPressed: () => _start(context),
          child: const Text('Start Identity Verification'),
        ),
      ),
    );
  }

  void _start(BuildContext context) {
    Navigator.push(
      context,
      MaterialPageRoute(
        builder: (_) => PrismEkyc.screen(
          PrismEkycConfig(
            defaultLanguage: PrismLanguage.english,
            availableLanguages: const [
              PrismLanguage.english,
              PrismLanguage.japanese,
            ],
            supportedCountries: const [
              SupportedCountry.vietnam,
              SupportedCountry.philippines,
              SupportedCountry.indonesia,
            ],
            onComplete: (EkycResult result) {
              _submit(result);
            },
          ),
        ),
      ),
    );
  }

  Future<void> _submit(EkycResult result) async {
    final payload = {
      'name':            result.formData.fullName,
      'cardNumber':      result.formData.cardNumber,
      'dob':             result.nfcData?.dateOfBirth,
      'nationality':     result.nfcData?.nationality,
      'visaStatus':      result.nfcData?.status,
      'expiryDate':      result.nfcData?.expiryDate,
      'faceConfidence':  result.faceMatchConfidence,
      // Images — send as base64 or multipart
      'facePhoto':       result.nfcData?.facePhotoJpeg2000,
      'cardFront':       result.nfcData?.cardFrontPng,
      'cardBack':        result.backsideImage,
    };
    // ... POST to your API
  }
}

Error handling #

All errors during NFC, OCR, camera, and face verification are handled internally. The user gets a descriptive message and up to 3 retry attempts per step. After exhausting retries a Return to Start button appears.

onComplete is only invoked on full success. If the user backs out or quits at any step, onComplete is never called — treat its absence as abandonment.

Package dependencies #

Known limitations #

• Residence Card personal fields via OCR: OCR accuracy depends on card condition, lighting during NFC capture, and ML Kit model quality on the device. Fields that fail to parse are returned as empty strings; the user can fill them manually in the Registration Form.
• iOS Simulator: NFC is unavailable. Use debugBypassNfc: true during simulator development.
• Android NFC sensitivity: Some Android devices require the card to be held very still during the ~3-second read. A TAG_LOST error triggers a retry.

License #

Proprietary — RubiLabs. See LICENSE for details.