NFC verification

Reading an ePassport / eID chip over NFC is the one capability a WebView cannot do — it needs the device NFC radio. So ThirdFactor uses a hybrid: the hosted flow keeps handling document capture, liveness, and face match in the WebView, and the native SDK supplies the NFC read over the capability bridge. This mirrors how Didit and other providers split the work — read on device, validate on server. The SDK reads raw data groups; the backend does the cryptography.

End-to-end sequence

Applicant scans document (WebView)  ──►  MRZ OCR'd by the engine
        │
        ▼  flow reaches the NFC step AND window.__thirdfactorHost.capabilities includes "nfc"
Flow  ── nfc.scan { documentNumber, dateOfBirth, dateOfExpiry } ─►  Native SDK
        │                                                             │
        │                         BAC/PACE + read DG1/DG2/EF.SOD      │
Flow  ◄── resolveCommand(id, { ok, data:{ sod_b64, dg1_b64, dg2_b64 }}) ─┘
        │
        ▼  POST /api/verify/<token>/nfc/
Backend ── passive authentication ──►  resolve NFC_VERIFICATION module

Web (iframe/popup) hosts advertise no capabilities, so the flow keeps the server-side fallback: NFC_VERIFICATION → manual review (nfc_not_available).

What each layer does

Native SDK (device) — reads, does not validate

• Advertises capabilities: ["nfc"] via window.__thirdfactorHost only when the device NFC radio is available.
• Handles the nfc.scan command: derives the BAC key from the MRZ (documentNumber + dateOfBirth + dateOfExpiry) or a CAN for PACE, opens secure messaging, and reads DG1 (MRZ), DG2 (face), and EF.SOD (the signed hash set). Returns them base64 — raw bytes only.
• Also exposes a standalone read(...) API for apps that want NFC outside the hosted flow.

Backend (server) — validates, decides

POST /api/verify/<token>/nfc/ runs passive authentication:

Decision mapping:

Two integration paths

Flow-delegated (automatic)

If your workflow includes an NFC_VERIFICATION step and you launch the hosted flow with the SDK on an NFC device, the chip read just works — the flow sends nfc.scan with the MRZ it OCR'd, the SDK reads and forwards, and the backend validates. On Android and Flutter this needs no extra code beyond verify. On iOS you opt in by setting a native command handler:

var options = VerifyOptions()
if #available(iOS 15, *) {
    options.nativeCommandHandler = ThirdFactorNFC.commandHandler()
}
let result = await ThirdFactor.verify(from: self, url: sessionURL, options: options)

Without a handler (or on a device without NFC), the flow keeps the server-side fallback (NFC step → manual review). The delegation is entirely driven by the capability handshake: the SDK advertises ["nfc"] only when the radio is on, and the flow calls nfc.scan only when the host advertised it.

Standalone (read outside the flow)

Each mobile SDK exposes a standalone read for custom UI, offline enrolment, or re-verification. All three return the same nfc.scan data shape — base64 DGs plus aa / chipAuth { performed, success } — which you POST to your own backend for passive authentication.

import ThirdFactorKYCNFC

let key = MRZKey(documentNumber: "L898902C3", dateOfBirth: "740812", dateOfExpiry: "120415") // YYMMDD
let result = await ThirdFactorNFC.read(mrzKey: key, dataGroups: [.DG1, .DG2, .SOD])
if result.success, let data = result.data {
    upload(data.asDictionary())  // { sod_b64, dg1_b64, dg2_b64, aa, chipAuth }
} else {
    // result.errorCode ∈ user_cancelled | tag_lost | wrong_key | unsupported | nfc_disabled | timeout
}

static func read(mrzKey: MRZKey, dataGroups: [DataGroupId] = [.DG1, .DG2, .SOD]) async -> NfcReadResult
static func commandHandler() -> NativeCommandHandler   // pass to VerifyOptions.nativeCommandHandler

MRZKey(rawKey: String)                                             // precomputed BAC key
MRZKey(documentNumber: String, dateOfBirth: String, dateOfExpiry: String)  // dates YYMMDD; SDK computes check digits

// NfcReadResult { success: Bool; data: NfcData?; errorCode: String?; errorMessage: String? }
// NfcData.asDictionary() -> [String: Any]

val result = ThirdFactorNfc.read(
    activity = this@MyActivity,
    accessKey = NfcAccessKey.Mrz(documentNumber = "L898902C3", dateOfBirth = "740812", dateOfExpiry = "301001"),
    dataGroups = listOf(NfcDataGroup.DG1, NfcDataGroup.DG2, NfcDataGroup.SOD),
    overallTimeoutMs = 60_000,
)
when (result) {
    is NfcReadResult.Success -> { /* result.dataGroups[NfcDataGroup.SOD] → base64 → backend */ }
    is NfcReadResult.Failure -> showError(result.code)   // NfcErrorCode.*
}

suspend fun read(
    activity: Activity,
    accessKey: NfcAccessKey,                       // NfcAccessKey.Mrz(...) or NfcAccessKey.Can(...)
    dataGroups: List<NfcDataGroup> = listOf(NfcDataGroup.DG1, NfcDataGroup.DG2, NfcDataGroup.SOD),
    overallTimeoutMs: Long = 60_000,
): NfcReadResult
// NfcReadResult = Success(dataGroups, aa, chipAuth) | Failure(code: NfcErrorCode, message)

if (await ThirdFactorNfc.isAvailable()) {
  final chip = await ThirdFactorNfc.read(
    documentNumber: 'X1234567',
    dateOfBirth: '900101',  // YYMMDD
    dateOfExpiry: '300101', // YYMMDD
    dataGroups: const [NfcDataGroup.dg1, NfcDataGroup.dg2, NfcDataGroup.sod],
    // canNumber: '123456', // for PACE-only eIDs
  );
  await sendToBackend(chip.toBridgeData()); // { sod_b64, dg1_b64, dg2_b64, aa, chipAuth }
}

static Future<bool> isAvailable();
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.toBridgeData() → the nfc.scan data map; throws NfcException(code) on failure.

Per-platform setup

NFC needs entitlements/permissions and a dependency the core SDK doesn't pull in by default. Full details live in each SDK page; the essentials:

Data groups

The chip is an ICAO-9303 Logical Data Structure. Only a handful of elementary files matter for KYC; the SDKs default to the three the backend needs and let you request more:

Error codes

The nfc.scan result (and the standalone read failures) use a stable set of codes — branch on the code, never the message:

Troubleshooting

FAQ

Related