轻触电子护照芯片，实现银行级身份验证。

You are integrating Didit's NFC e-passport reading into a regulated onboarding flow (bank, fintech, crypto exchange, eIDAS-grade public service). NFC chip reading lifts onboarding from document-scan-grade to bank-grade in one extra step on the user's phone.

Five obligations on every onboarding:

  1. Read the e-passport / e-ID chip via NFC — DG1 (MRZ), DG2 (portrait), DG11 (personal details).
  2. Verify the government signature chain — Passive Authentication (PA) against the ICAO Public Key Directory, Chip Authentication (CA), Active Authentication (AA).
  3. Match the live selfie to the high-resolution DG2 portrait extracted from the chip.
  4. Run Passive Liveness on the selfie — iBeta Level 1 anti-spoof certified, defeats printed photos, screen replays, masks, and deepfakes.
  5. Screen the chip-verified identity against sanctions, Politically Exposed Persons (PEP), and adverse-media lists.

Fallback automatically when NFC is unavailable (no chip, NFC blocked by iOS or by user permission, chip damaged): the workflow drops to high-accuracy MRZ + OCR on the visual page using ID Verification.

Pricing (verified live):
  - NFC Reading: $0.15 per chip read
  - ID Verification (fallback or always-on belt-and-braces): $0.15 per check
  - Passive Liveness: $0.10 per check
  - Face Match 1:1: $0.05 per match
  - AML Screening: $0.20 per check
  - Bundle (NFC + Liveness + Face Match + AML): $0.50 per onboarded user when NFC succeeds; $0.50 also when the workflow falls back to ID Verification
  - First 500 KYC verifications free every month, forever

PRE-REQUISITES
  - Production API key from https://business.didit.me (sandbox key in 60s, no card).
  - Webhook endpoint with HMAC SHA-256 verification using the X-Signature-V2 header and your webhook secret.
  - A workflow_id from the Workflow Builder bundling NFC Reading + ID Verification (fallback) + Passive Liveness + Face Match 1:1 + AML Screening.
  - The Didit hosted flow or the native SDKs (web SDK, iOS, Android, React Native, Flutter) — NFC chip reading requires the native NFC stack, so plain web-only deployments fall back to MRZ + OCR automatically.

STEP 1 — Create the NFC session

  POST https://verification.didit.me/v3/session/
  Headers:
    x-api-key: <your api key>
    Content-Type: application/json
  Body:
    {
      "workflow_id": "<your nfc onboarding workflow id>",
      "vendor_data": "<your user id, max 256 chars>",
      "callback_url": "https://<your-app>/onboarding/kyc/callback",
      "expected_country": "ES",
      "metadata": {
        "channel": "native_ios",
        "purpose": "high_assurance_onboarding"
      }
    }

  Response: 201 Created with the hosted session URL. Open it via the native SDK (iOS NFC requires CoreNFC entitlement) or in the hosted webview; the user taps the e-passport against the phone's NFC reader, the chip data is read in 2-4 seconds.

STEP 2 — The chip-read sequence (handled by the SDK / hosted flow)

  Inside the hosted flow, in this order:
    a. The user presents the data page so the device camera reads the Machine-Readable Zone (MRZ). The MRZ provides the BAC / PACE key needed to handshake with the chip.
    b. The user taps the passport to the phone. PACE (preferred) or BAC handshake establishes a secure session with the chip.
    c. The chip returns Data Group 1 (MRZ data — name, DOB, expiry, document number), Data Group 2 (the high-resolution portrait), and Data Group 11 (personal details where available).
    d. Passive Authentication verifies the Document Signer Certificate against the country's Country Signing CA via the ICAO Public Key Directory. Chip Authentication and Active Authentication run if supported by the issuing country.
    e. The user takes a single selfie (Passive Liveness, no challenge prompts).
    f. The selfie is matched 1:1 against the DG2 portrait.

STEP 3 — Read the signed webhook on completion

  Didit POSTs to your callback. Session statuses are Title Case With Spaces:

  Body (excerpted):
    {
      "session_id": "<uuid>",
      "vendor_data": "<your user id>",
      "status": "Approved",
      "nfc_verification": {
        "status": "Approved",
        "passive_authentication": "Approved",
        "chip_authentication": "Approved",
        "active_authentication": "Approved",
        "data_groups_read": [1, 2, 11]
      },
      "id_verification": { "status": "Approved", "document_type": "passport", "country_code": "ES" },
      "liveness": { "status": "Approved" },
      "face": { "status": "Approved", "similarity_score": 0.94, "matched_against": "chip_portrait" },
      "aml": { "status": "Approved", "hits": [] }
    }

  Session status enum (exact case):
    Approved | Declined | In Review | Resubmitted | Expired | Not Finished | Kyc Expired | Abandoned

  Verify the X-Signature-V2 header BEFORE reading the body — HMAC SHA-256 of the raw bytes with your webhook secret.

STEP 4 — Decide

  Branch logic:
    Approved    → onboard the user with bank-grade assurance.
    In Review   → hold the account, wait for analyst webhook update.
    Declined    → refuse onboarding, log the decline reason.
    Resubmitted → user updated something; re-read the decision.

  When face.matched_against === "chip_portrait", you can mark the identity as eIDAS High-grade (Substantial / High depending on your local regulator's reading). When it falls back to "id_document_portrait" (the visual page), it's still bank-grade by document-scan standards but not chip-anchored.

STEP 5 — Fallback paths

  iPhones below iPhone 7, or any phone with NFC disabled, or a document without a chip (pre-2014 in some countries) → the workflow surfaces "NFC unavailable" and routes to the ID Verification + MRZ + OCR path. Same hosted URL, same webhook, same statuses. The fallback is configured in the Workflow Builder, not in your code.

  Some Android devices won't read every chip due to NFC antenna placement — Didit's iOS / Android SDKs surface a graceful retry hint before failing over to OCR.

STEP 6 — Ongoing monitoring

  Enable Ongoing AML at $0.07/user/year to keep the identity fresh. NFC re-reads aren't required for ongoing — the chip data was captured at onboarding and the binding is permanent for the document's validity period.

WEBHOOK EVENT NAMES
  - status.updated — session status changed.
  - data.updated — session data changed (resubmission, NFC retry, ongoing AML hit).

  Verify X-Signature-V2 on every payload. The webhook secret is per-environment — sandbox key is separate from production.

CONSTRAINTS
  - Session statuses use Title Case With Spaces (Approved, In Review).
  - NFC chip reading requires the native NFC stack — iOS, Android, React Native, Flutter SDKs handle it; pure web falls back to MRZ + OCR.
  - The chip portrait (DG2) is far higher-resolution than the visual page — matching the selfie to it is meaningfully more accurate than matching to a phone-camera-captured ID photo.
  - Document Signer Certificate trust is anchored to the ICAO Public Key Directory; some countries (eg. small island states) do not publish to the PKD and will return a Passive Authentication warning rather than Approved.
  - Default record retention is 5 years post-relationship per the EU AML package.

Read the docs:
  - https://docs.didit.me/sessions-api/create-session
  - https://docs.didit.me/sessions-api/retrieve-session
  - https://docs.didit.me/core-technology/nfc-verification/overview
  - https://docs.didit.me/core-technology/face-match/overview
  - https://docs.didit.me/integration/webhooks

Start free at https://business.didit.me — sandbox key in 60 seconds, 500 verifications free every month, no credit card.