读取芯片。
验证签名。

# Didit NFC Verification — integrate in 5 minutes

You are integrating Didit's NFC Verification (cryptographic e-passport
and e-ID chip reading) module into <my_stack>. Follow these steps exactly.
Every URL, header, and enum value below is canonical — do not paraphrase
or "improve" them.

## 1. Provision an account
- Sign up: https://business.didit.me (no credit card required).
- Or provision programmatically: POST https://apx.didit.me/auth/v2/programmatic/register/
  (returns an API key bound to the workspace + application).

## 2. What NFC Verification actually does
NFC Verification reads the secure contact-less chip embedded in modern
e-passports and e-IDs (the small chip-and-antenna sticker symbol on the
cover) and runs four cryptographic checks against the data it extracts:

1. Passive Authentication — every Data Group (DG1 personal data, DG2
   facial image, etc.) is hashed and compared against the signed hash
   stored in the Document Security Object (SOD). Catches any single-bit
   tampering of the chip contents.
2. Certificate chain validation — Document Signer Certificate (DSC) →
   Country Signing Certificate Authority (CSCA) → ICAO Public Key
   Directory (PKD) root. Proves the chip was signed by the issuing
   government, not a clone.
3. Certificate Revocation List (CRL) check — DSCs revoked by the issuing
   country are caught and flagged.
4. Chip Authentication — where the document supports it, prevents chip
   cloning by challenging the chip with a key-pair handshake.

PACE (Password Authenticated Connection Establishment) or BAC (Basic
Access Control) is used to derive the session key from the Machine-Readable Zone (MRZ); Didit
handles that automatically. All of this is ICAO 9303 standard.

## 3. Two integration paths — pick one

### Path A — Workflow Builder (hosted UI, REQUIRED for NFC)
NFC Verification has no server-to-server standalone endpoint. The chip
has to be read by a device with NFC hardware, so you always integrate
through the Workflow + native SDK (or hosted mobile web that falls back).

1. Create a workflow that contains the NFC feature:
   POST https://verification.didit.me/v3/workflows/
   Authorization header:  x-api-key: <your-api-key>
   Body: workflow_label, features array with the entries
         { feature: "ID_VERIFICATION" }
         { feature: "NFC" }
         (UPPERCASE — strict enum)
   You should always pair NFC with ID_VERIFICATION so the MRZ is captured
   for the chip handshake AND so an OCR cross-validation is available.

2. Create a verification session for an end user:
   POST https://verification.didit.me/v3/session/
   Body: workflow_id (from step 1), vendor_data (your own user id).
   Response: session_url — redirect the user to it (or open it in the
   native SDK with shared.startVerification(with: sessionId)).

3. Listen for webhook callbacks (see "Webhooks" below).

### Path B — Native SDKs (drop-in, recommended for mobile apps)
Same workflow + session above, but launch the verification flow in your
own iOS or Android app via the Didit SDK. The SDK wires the NFC reader,
the entitlements, and the chip-reading UI for you.

- iOS: DiditSdk.shared.startVerification(with: sessionId, configuration:)
  Required entitlements (handled by the SDK):
    - com.apple.developer.nfc.readersession.formats = ["TAG"]
    - ISO7816 application identifiers for ePassports
- Android: DiditSdk.startVerification(sessionId, config) — uses
  IsoDep (android.nfc.tech.IsoDep) under the hood.
- React Native / Flutter: the same SDK, exposed through the cross-
  platform module — see docs.didit.me/integration/native-sdks/.

### Web browsers — NFC is unavailable
Web NFC API is not generally available. Chrome on Android has an
experimental Web NFC that is unstable and requires explicit permissions;
Safari on iOS has no support. For web integrations, NFC is automatically
skipped and the user proceeds with standard ID + selfie. If you require
NFC, deep-link the user into the Didit App or your own native app.

## 4. Webhooks
- Register a webhook destination once via
  POST https://verification.didit.me/v3/webhook/destinations/
  Body: url, subscribed_events: ["session.verified", "session.review_started",
                                  "session.declined"]
- Response includes secret_shared_key — store it.
- Every webhook delivery carries an X-Signature-V2 header you MUST verify
  before trusting the payload.  HMAC-SHA256 verification MUST run against the raw body bytes (the raw payload as Didit sent it) BEFORE any JSON parsing — re-serialising the parsed body changes whitespace and key order, which invalidates the signature.Algorithm:
    1. sortKeys(payload) recursively
    2. shortenFloats (truncate trailing zeros after the decimal point)
    3. JSON.stringify the result
    4. HMAC-SHA256 with the secret_shared_key
    5. Hex-encode, compare to the X-Signature-V2 header.

## 5. Reading the report
The session report includes an nfc object alongside the id_verification
object. Top-level fields on nfc:

- status: "Approved" | "Declined" | "In Review" | "Not Finished"
- portrait_image: signed URL to the chip-extracted DG2 facial image
- signature_image: signed URL to the chip-extracted DG7 signature
- chip_data:
    document_type, issuing_country (ISO 3166-1 alpha-3),
    document_number, expiration_date (YYYY-MM-DD),
    first_name, last_name, birth_date, gender ("M" | "F" | "U"),
    nationality (ISO 3166-1 alpha-3), address, place_of_birth.
- authenticity:
    sod_integrity (boolean — every Data Group hash matched the SOD)
    dg_integrity (boolean — Data Group binary integrity check passed)
- certificate_summary:
    issuer (CSCA Common Name + serial + organization + country)
    subject (DSC Common Name)
    serial_number
    not_valid_after (YYYY-MM-DD HH:MM:SS)
    not_valid_before (YYYY-MM-DD HH:MM:SS)
- warnings: Array of { risk, additional_data, log_type,
                       short_description, long_description }

### Auto-decline (always enforced, never configurable)
- NFC_AND_OCR_DATA_NOT_SAME — Optical Character Recognition (OCR) data
  and chip data differ. Indicates document tampering or fake chip.

### Configurable warnings (per-workflow action: Decline / Review / Approve)
- SKIPPED_NFC_VALIDATION       — chip not read (no NFC hardware, no
                                  permissions, document has no chip)
- NFC_CHIP_NOT_VERIFIED        — chip read but signature could not be
                                  verified (missing CSCA, older document)
- DSC_CERTIFICATE_REVOKED      — Document Signer Certificate listed on
                                  the issuing country's CRL
- DSC_CERTIFICATE_EXPIRED      — Document Signer Certificate past its
                                  validity period

## 6. Hard rules — do not change
- Base URL for /v3/* endpoints is verification.didit.me (NOT apx.didit.me).
- Feature enum is UPPERCASE: NFC, ID_VERIFICATION, LIVENESS, FACE_MATCH.
- Auth header is x-api-key (lowercase, hyphenated).
- Webhook signature header is X-Signature-V2 (NOT X-Signature).
- Always verify webhook signatures before trusting payload data.
- Always pair NFC with ID_VERIFICATION in the workflow — NFC alone
  cannot derive the chip key without the MRZ from the document photo.
- Status casing matches exactly: "Approved", "Declined", "In Review",
  "Not Finished" (title-cased, space-separated).
- Treat NFC as an additive confidence boost, not a hard gate, unless
  your risk policy explicitly requires it (regulated remote
  onboarding under PSD3, AMLD6 high-risk customer flows, etc.).

## 7. Pricing reference (public)
- NFC Verification: $0.15 per chip read (standalone module).
- Bundled inside a full Know Your Customer (KYC) workflow (ID + Liveness + Face Match + NFC):
  priced as the underlying KYC bundle ($0.33) + $0.15 NFC if enabled.
- 500 free checks every month, forever, on every account.

## 8. Verify your integration
- Sandbox starts on signup at https://business.didit.me — no separate flag.
- Test documents: use the Didit App on a real iOS or Android device with
  any ICAO 9303 e-passport issued after 2006 (most modern passports).
- Sandbox webhook events fire the same shape as production; verify the
  X-Signature-V2 header in dev too.
- Switch to live: flip the application's environment toggle in console.

When in doubt: https://docs.didit.me/core-technology/nfc-verification/overview