Document chip (NFC)

Read the ICAO 9303 chip of passports and identity cards from the Android and iOS SDKs.

Passports and many identity cards carry a contactless chip (ICAO 9303 eMRTD). The chip holds the holder's data and a portrait signed by the issuer. When you turn chip reading on, the Sekyro Android and iOS SDKs read the chip after the document photo. Sekyro then:

compares the chip data with the printed MRZ;
uses the chip portrait for the face match (see Face-match reference below).

Only native apps read chips. A web or hosted-page session never does (see What happens on the web).

Any issuer's eMRTD is read the same way:

access: PACE with the key from the printed MRZ, then BAC as the fallback, then the card access number (CAN) when the card refuses both;
files: COM, DG1 (MRZ data), DG2 (portrait) and SOD (security object), plus DG11/DG12/DG13 when the chip has them. A missing optional group is never an error.

The Mauritanian carte_identite (CNI) is confirmed to have a chip. Passports are expected to have one. Other identity cards and residence permits vary by issuer: the SDK learns whether a chip is there when it tries to read it.

1. Turn it on (Sekyro dashboard → Apps → your app → eKYC → Document)

Document chip reading is not available in production yet. You can try it in the staging sandbox (https://api-staging.sekyro.ai, sk_test_… keys). See Availability.

Chip reading is part of the document step. It is unavailable while the document is off, and it never counts as a capability on its own.

Setting	Behaviour
Off (default)	No chip read.
Preferred	Native apps with NFC read the chip. If the device has no NFC, the document has no chip, or the read fails after the last attempt, the verification continues on the document photo. Web sessions skip the chip.
Mandatory	The chip must be read. A device without NFC, a document without a chip, or the last failed read rejects the verification. A web session stops with "This verification needs a phone app".
Attempts	Chip reads per session, 1 to 5 (default 3).

In the eKYC profile the dashboard saves, this is "nfc": { "mode": "off" | "preferred" | "mandatory", "maxAttempts": 3 }. Leaving nfc out means off. Chip reading is being rolled out per platform: while it is not available for your organization, saving any mode other than off returns nfc_not_available.

2. Android setup

The sekyro-nfc module declares these in its manifest; your merged manifest must keep them:

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

required="false" keeps your app installable on phones without NFC. On those phones the SDK reports nfc_unavailable. If NFC is present but turned off, the SDK offers a shortcut to the NFC settings.

3. iOS setup

In Xcode → Signing & Capabilities, add Near Field Communication Tag Reading, then add to Info.plist:

<key>NFCReaderUsageDescription</key>
<string>Read your identity document's chip to verify your identity.</string>
<key>com.apple.developer.nfc.readersession.iso7816.select-identifiers</key>
<array>
  <string>A0000002471001</string>
  <string>A0000002472001</string>
</array>

The entitlement file gets com.apple.developer.nfc.readersession.formats = TAG (Xcode adds it with the capability). Without NFCReaderUsageDescription the SDK treats the device as having no NFC. Chip reading needs an iPhone 7 or later.

4. What the person sees

The document photo. The MRZ it reads is the chip's access key. When the person chose "Read my document's chip", the doc_ocr step carries docCapture: { mode: "mrz_for_chip" }: the SDK reads the MRZ for the chip key and still uploads the document sides as for a photo.
"Place the document on the back of the phone", with a progress line per file (identity data, photo, security data).
If the chip refuses the MRZ key, the SDK asks for the card access number (CAN): the 6-digit number printed on the photo page. This happens only on cards that need it.

The SDKs send the device's NFC capability with every request (the sekyro-client-device header, caps: ["nfc"]). Sekyro uses it to decide whether to offer the chip:

In an optional-document profile, a phone with NFC also sees the method "Read my document's chip" (document_chip). It is never offered to the web or to a phone without NFC; choosing it anyway returns 400 method_not_offered.
With Preferred, a phone without NFC skips the chip (nfc_unavailable).
With the profile's summary and confirm on (identity.confirmSummary), the person then sees the details read from the chip (masked document number, the chip photo) and confirms them or retakes the document before the live photo.

5. What happens on the web

The web SDK and the hosted page never read chips:

Preferred: the chip step is skipped with reason platform_unsupported, and the flow continues.
Mandatory: the hosted view returns failureReason: "platform_unsupported" while the session status stays created / in_progress. The page shows "This verification needs a phone app". The session stays open, so the same link can still be finished in your native app. Your server sees the session as in progress until it is completed or expires.

6. Outcomes (`nfc_chip` step `reason`)

Reason	Meaning	Retry?
`chip_read_failed`	Contact lost or the read timed out	Yes, while attempts remain
`chip_access_denied`	The chip refused the MRZ key / CAN	Yes (rescan the MRZ or enter the CAN)
`chip_parse_failed`	The chip data could not be decoded	Yes
`chip_not_present`	No chip on this document	No: Preferred skips the step, Mandatory rejects ("Use a document with a chip")
`nfc_unavailable`	The device has no NFC	No: Preferred skips the step, Mandatory rejects
`chip_document_mismatch`	The chip and the printed MRZ disagree on a check-digit-protected field (document number, birth date, expiry, MR NNI)	No: `review` in review-mode apps, `failed` in automatic apps
`chip_integrity_failed`	A chip file does not match the security object's hash	No: as above
`registry_mismatch`	A Mauritanian chip disagrees with the civil registry	No
`document_nni_mismatch`	The chip NNI differs from the NNI bound to the session	No
`platform_unsupported`	Skipped on a web client (Preferred)	—

With Preferred, after the last attempt a retryable reason also ends as skipped, and the verification continues on the document photo.

Name, sex or nationality differences between the chip and the OCR'd document are never a mismatch. The chip value wins in the session's subject (source chip).

Face-match reference. The face-match reference follows your profile's reference setting ("Identity data comes from"):

registry (the default): the registry portrait when there is one, else the chip portrait, else the document photo;
document: the chip portrait, else the document photo.

Signature check. The chip's signature (SOD against the issuer's CSCA certificate) is not verified yet. Every read reports chipAuthenticity: "not_verified". Sekyro does check that the chip files match the hashes in the SOD.

7. Billing

A chip read is billed (meter nfc_chip) once, when it ends passed or review. Failed and skipped reads are not billed, and neither are reads on web sessions. The price is in your plan.

8. Third-party notices

Android: chip reading uses JMRTD (GNU LGPL v2.1 or later). It is linked as a separate, unmodified Maven dependency, and its notice ships in the sekyro-nfc artifact (META-INF/NOTICE.sekyro-nfc.txt). Keep that notice in your app's open-source licenses screen.
iOS: SekyroKit reads chips with Apple Core NFC and its own ICAO 9303 code. No third-party chip library is bundled (NFCPassportReader, MIT, is not used), so there is no extra notice to ship.

1. Turn it on (Sekyro dashboard → Apps → your app → eKYC → Document)Copy Anchor Link

2. Android setupCopy Anchor Link

3. iOS setupCopy Anchor Link

4. What the person seesCopy Anchor Link

5. What happens on the webCopy Anchor Link

6. Outcomes (nfc_chip step reason)Copy Anchor Link

7. BillingCopy Anchor Link

8. Third-party noticesCopy Anchor Link

On this page