Flutter SDK

thirdfactor_kyc opens the hosted verification flow in a full-screen WebView, reads ePassport / eID NFC chips natively, and resolves a single typed VerificationResult. It speaks the same shared bridge protocol as the web, iOS, and Android SDKs — a thin shell around the same hosted flow, with one channel name (ThirdFactorFlutter) wired for both platforms.

Requirements

Installation

The package is not published to pub.dev (publish_to: none); vendor it as a git or path dependency:

# pubspec.yaml
dependencies:
  thirdfactor_kyc:
    git:
      url: https://github.com/thirdfactor/obsidian.git
      path: sdks/flutter
  # — or, if vendored locally —
  # thirdfactor_kyc:
  #   path: ../thirdfactor-obsidian/sdks/flutter

dmrtd is itself pinned to a GitHub tag inside the SDK, so no extra NFC dependency is needed in your app. The single import gives you the entire public surface:

import 'package:thirdfactor_kyc/thirdfactor_kyc.dart';

Platform setup

The flow captures a live selfie / document photos, so the host app must declare camera (and, for liveness, microphone) permissions. Granting them inside the WebView is handled for you; declaring them at the OS level is not. NFC needs a further set of permissions/entitlements on top (see NFC verification).

<uses-permission android:name="android.permission.CAMERA" />
<uses-permission android:name="android.permission.RECORD_AUDIO" />
<uses-feature android:name="android.hardware.camera" android:required="false" />

<key>NSCameraUsageDescription</key>
<string>We use the camera to verify your identity.</string>
<key>NSMicrophoneUsageDescription</key>
<string>We use the microphone during liveness checks.</string>

Quick start

import 'package:thirdfactor_kyc/thirdfactor_kyc.dart';

Future<void> runKyc(BuildContext context, String sessionUrl) async {
  final result = await ThirdFactor.verify(context, url: sessionUrl);
  if (result.status == VerificationStatus.approved) {
    showSuccess();   // UX only — confirm server-side before granting access
  }
}

verify() never throws — it always resolves a VerificationResult. Call it from a Navigator-capable BuildContext; it pushes a full-screen MaterialPageRoute (fullscreenDialog: true) and completes when that route pops.

Integration methods

final result = await ThirdFactor.verify(
  context,
  url: sessionUrl,                       // hosted URL from POST /v3/session/
  options: VerifyOptions(
    title: 'Verify your identity',
    onEvent: (e) => debugPrint('$e'),    // ready | completed | error | close
  ),
);

switch (result.status) {
  case VerificationStatus.approved:  showSuccess();
  case VerificationStatus.declined:  showFailure();
  case VerificationStatus.inReview:  showPending();
  case VerificationStatus.cancelled: /* user closed the flow */ break;
  case VerificationStatus.error:     showError(result.error);
}

ThirdFactorVerificationPage(
  url: sessionUrl,
  options: VerifyOptions(title: 'Verify your identity'),
  popOnResult: false,             // don't self-pop; you control navigation
  onResult: (result) {
    // handle result, then navigate away yourself
  },
)

Complete API reference

Every public symbol exported from package:thirdfactor_kyc/thirdfactor_kyc.dart, verified against sdks/flutter/lib/.

ThirdFactor

ThirdFactorVerificationPage

The StatefulWidget behind verify(). Use it directly only when your app owns navigation.

VerifyOptions

ThirdFactor.verify(context, {required url, options}) takes a VerifyOptions:

Result types

Lifecycle events (VerificationEvent)

A sealed hierarchy, so a switch over it is exhaustively checked by the analyzer.

NFC types (ThirdFactorNfc and friends)

Result handling

class VerificationResult {
  final VerificationStatus status;
  final String? sessionId;       // echoed from the flow when available
  final String? rawStatus;       // original server string, e.g. "abandoned"
  final ThirdFactorError? error; // when status == error
}

Branch on error.code (invalid_session | expired | load_error | unknown), never on error.message:

final result = await ThirdFactor.verify(
  context,
  url: sessionUrl,
  options: VerifyOptions(onEvent: (e) => debugPrint('$e')),
);
switch (result.status) {
  case VerificationStatus.approved:  proceed();               // confirm server-side first
  case VerificationStatus.declined:  showFailure();
  case VerificationStatus.inReview:  showPending();
  case VerificationStatus.cancelled: /* let them retry */ break;
  case VerificationStatus.error:
    if (result.error?.code == 'expired') reMintSession();
    else showError(result.error);
}

NFC verification

Some documents carry an ICAO-9303 contactless chip. When the hosted flow reaches an NFC step, the WebView cannot reach the radio, so this SDK reads the chip natively over the capability bridge and forwards the raw chip bytes for your backend to authenticate. This is fully automatic — no code beyond ThirdFactor.verify is required. If the device has no NFC, the SDK advertises nothing and the flow keeps its server-side fallback (NFC → manual review).

Chip reading uses dmrtd (v2.0.0) for BAC/PACE key derivation, secure messaging, and EF/DG parsing, over its bundled flutter_nfc_kit.

Setup — platform configuration

NFC needs extra configuration in the host app (the SDK is a pure Dart package and cannot declare these for you).

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

<key>NFCReaderUsageDescription</key>
<string>We read your passport chip to verify your identity.</string>

<key>com.apple.developer.nfc.readersession.iso7816.select-identifiers</key>
<array>
  <string>A0000002471001</string>          <!-- eMRTD LDS1 application — REQUIRED -->
  <string>A00000045645444C2D3031</string>  <!-- eID (optional) -->
</array>

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

Standalone read

Read a chip yourself, independent of the hosted flow — for a pre-fill step, offline enrolment, or your own KYC UI. The BAC key is derived from the MRZ your app already OCR'd (document number + the two dates), or from a 6-digit CAN for PACE-only eIDs:

import 'package:thirdfactor_kyc/thirdfactor_kyc.dart';

if (await ThirdFactorNfc.isAvailable()) {
  try {
    final chip = await ThirdFactorNfc.read(
      documentNumber: 'X1234567',
      dateOfBirth:    '900101', // YYMMDD
      dateOfExpiry:   '300101', // YYMMDD
      dataGroups: const [NfcDataGroup.dg1, NfcDataGroup.dg2, NfcDataGroup.sod],
      // canNumber: '123456',   // instead of the MRZ fields, for PACE-only eIDs
    );
    // Raw, base64 chip bytes — send to YOUR backend for passive authentication.
    final payload = chip.toBridgeData(); // { sod_b64, dg1_b64, dg2_b64, aa, chipAuth }
    await sendToBackend(payload);
  } on NfcException catch (e) {
    switch (e.code) {                    // e.code is an NfcErrorCode enum
      case NfcErrorCode.userCancelled: break;
      case NfcErrorCode.wrongKey:      showRetryMrz();  break;   // MRZ/CAN mismatch
      case NfcErrorCode.tagLost:       showHoldStill(); break;
      case NfcErrorCode.nfcDisabled:   showEnableNfc(); break;
      case NfcErrorCode.timeout:       showTryAgain();  break;
      case NfcErrorCode.unsupported:   showManualPath();break;
    }
  }
}

Signature (verified against lib/src/nfc/nfc_reader.dart):

static Future<NfcReadResult> read({
  required String documentNumber,
  required String dateOfBirth,   // YYMMDD
  required String dateOfExpiry,  // YYMMDD
  List<NfcDataGroup> dataGroups = const [NfcDataGroup.dg1, NfcDataGroup.dg2, NfcDataGroup.sod],
  String? canNumber,             // PACE-by-CAN alternative to the MRZ fields
  Duration timeout = const Duration(seconds: 60),
  String iosAlertMessage = 'Hold your phone near the photo page of your document.',
});

NfcReadResult carries the base64 elementary files (sodB64, dg1B64, dg2B64, optional dg11B64 / dg12B64 / comB64) plus aa / chipAuth ({ performed, success }) advisory signals. toBridgeData() returns the exact nfc.scan result shape.

For the full NFC architecture and passive-auth decision mapping, see the NFC deep-dive.

Full end-to-end example

A complete integration: a server call that mints the session (any backend, shown as cURL), and a Flutter screen that opens it and reports the result.

curl -X POST https://<your-domain>/v3/session/ \
  -H "x-api-key: $TF_API_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: kyc-user-123" \
  -d '{
    "vendor_data": "user-123",
    "callback_url": "https://app.acme.com/kyc/done",
    "contact_email": "[email protected]",
    "prefill": { "full_name": "Aarav Sharma", "nationality": "NP" }
  }'
# 201 → { "id": "6f0e…", "status": "not_started",
#         "url": "https://<your-domain>/verify/<token>", ... }

import 'dart:convert';
import 'package:flutter/material.dart';
import 'package:http/http.dart' as http;
import 'package:thirdfactor_kyc/thirdfactor_kyc.dart';

class KycScreen extends StatefulWidget {
  const KycScreen({super.key});
  @override
  State<KycScreen> createState() => _KycScreenState();
}

class _KycScreenState extends State<KycScreen> {
  String _status = 'Not verified';
  bool _running = false;

  /// Fetch the hosted session URL from YOUR API, which calls POST /v3/session/
  /// server-side with the secret key. Never call the Obsidian API from the app.
  Future<String?> _fetchSessionUrl() async {
    final res = await http.post(Uri.parse('https://api.acme.com/kyc/session'));
    if (res.statusCode != 200) return null;
    return (jsonDecode(res.body) as Map<String, dynamic>)['url'] as String?;
  }

  Future<void> _startVerification() async {
    setState(() => _running = true);
    final url = await _fetchSessionUrl();
    if (url == null || !mounted) {
      setState(() => _running = false);
      return;
    }

    final result = await ThirdFactor.verify(
      context,
      url: url,
      options: VerifyOptions(
        title: 'Verify your identity',
        onEvent: (e) => debugPrint('[kyc] $e'),
      ),
    );

    if (!mounted) return;
    setState(() {
      _running = false;
      _status = switch (result.status) {
        // UX only — grant real access once your webhook handler flips the
        // user's server-side status.
        VerificationStatus.approved  => 'Approved (pending server confirmation)',
        VerificationStatus.declined  => 'Declined',
        VerificationStatus.inReview  => 'Under review',
        VerificationStatus.cancelled => 'Cancelled',
        VerificationStatus.error     => 'Error: ${result.error?.code ?? "unknown"}',
      };
    });

    if (result.status == VerificationStatus.error &&
        result.error?.code == 'expired') {
      // Re-fetch a fresh session URL and let the user retry.
    }
  }

  @override
  Widget build(BuildContext context) {
    return Scaffold(
      appBar: AppBar(title: const Text('Verify')),
      body: Center(
        child: Column(
          mainAxisSize: MainAxisSize.min,
          children: [
            Text(_status),
            const SizedBox(height: 16),
            FilledButton(
              onPressed: _running ? null : _startVerification,
              child: Text(_running ? 'Running…' : 'Verify identity'),
            ),
          ],
        ),
      ),
    );
  }
}

A runnable version lives in sdks/flutter/example/ — paste a hosted session URL and tap Start verification, or tap Read passport NFC (standalone) to exercise ThirdFactorNfc.read on a device.

Troubleshooting

FAQ

How it works

verify() opens the flow with ?embed=1&sdk=flutter appended. In embed mode the flow reports lifecycle over the ThirdFactorFlutter JavaScript channel (one channel name on both iOS and Android) instead of redirecting. The SDK validates that every message is a thirdfactor bridge event on the expected origin, maps the raw status via StatusMapper (PROTOCOL §5), and resolves exactly one result. On page load it injects the window.__thirdfactorHost handshake (PROTOCOL §8.1) so the flow can delegate native-only steps — currently nfc.scan — to the SDK over the same channel. See the bridge protocol for the full contract.

Related