Flutter SDK

thirdfactor_kyc opens the hosted verification flow in a full-screen WebView and resolves a single typed VerificationResult; with the optional thirdfactor_kyc_nfc companion package it also reads ePassport / eID NFC chips natively. 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

# pubspec.yaml
dependencies:
  thirdfactor_kyc: ^1.3.0

or flutter pub add thirdfactor_kyc.

Optional — native NFC chip reading. The chip reader depends on dmrtd, which only exists as a git dependency, and pub.dev rejects packages with git dependencies — so the reader ships in the separate, git-distributed thirdfactor_kyc_nfc companion package:

dependencies:
  thirdfactor_kyc: ^1.3.0
  thirdfactor_kyc_nfc:
    git:
      url: https://github.com/thirdfactorai/thirdfactor-flutter.git
      path: nfc

Then inject it: ThirdFactor.verify(context, url: …, nfcReader: const ThirdFactorNfc()). Without the companion the SDK works with zero configuration — the hosted flow keeps its server-side NFC fallback (NFC step → manual review). 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" />

<uses-permission android:name="android.permission.ACCESS_FINE_LOCATION" />
<uses-permission android:name="android.permission.ACCESS_COARSE_LOCATION" />

options: VerifyOptions(
  requestLocationPermission: () async =>
      (await Permission.locationWhenInUse.request()).isGranted,
),

<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>

<key>NSLocationWhenInUseUsageDescription</key>
<string>We use your location to verify your identity.</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, nfcReader}) takes a VerifyOptions:

Result types

Lifecycle events (VerificationEvent)

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

NFC types (NfcChipReader and friends)

Chip reading is injected: this package defines the NfcChipReader interface and the value types below, and the implementation — ThirdFactorNfc — lives in the git-distributed companion package:thirdfactor_kyc_nfc/thirdfactor_kyc_nfc.dart (see NFC verification).

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 the SDK reads the chip natively over the capability bridge and forwards the raw chip bytes for your backend to authenticate.

Chip reading is injected. The core package is on pub.dev, which rejects git dependencies, and the ICAO-9303 implementation (dmrtd v2.0.0 — BAC/PACE key derivation, secure messaging, EF/DG parsing, over its bundled flutter_nfc_kit) only exists as a git tag. So the reader, ThirdFactorNfc, ships in the git-distributed companion package thirdfactor_kyc_nfc, and you hand it to the SDK:

# pubspec.yaml
dependencies:
  thirdfactor_kyc: ^1.3.0
  thirdfactor_kyc_nfc:
    git:
      url: https://github.com/thirdfactorai/thirdfactor-flutter.git
      path: nfc

import 'package:thirdfactor_kyc/thirdfactor_kyc.dart';
import 'package:thirdfactor_kyc_nfc/thirdfactor_kyc_nfc.dart';

final result = await ThirdFactor.verify(
  context,
  url: sessionUrl,
  nfcReader: const ThirdFactorNfc(),
);

(ThirdFactorVerificationPage(url: …, nfcReader: const ThirdFactorNfc()) works the same way.) From there it is automatic: the SDK advertises nfc only when a reader is passed and the device's NFC is on, and the flow sends nfc.scan only when it was advertised. Without a reader — or on a device without NFC — the flow keeps its server-side fallback (NFC → manual review); everything else works unchanged.

Setup — platform configuration

NFC needs extra configuration in the host app (the SDK packages are Dart packages 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. ThirdFactorNfc comes from the companion package; the value types (NfcDataGroup, NfcException, NfcErrorCode, …) from the core:

import 'package:thirdfactor_kyc/thirdfactor_kyc.dart';
import 'package:thirdfactor_kyc_nfc/thirdfactor_kyc_nfc.dart';

const nfc = ThirdFactorNfc();
if (await nfc.isAvailable()) {
  try {
    final chip = await nfc.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 sdks/flutter_nfc/lib/src/nfc_reader.dart; the same shape as NfcChipReader.read):

// final class ThirdFactorNfc implements NfcChipReader { const ThirdFactorNfc(); … }
@override
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 (it passes nfcReader: ThirdFactorNfc()), 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