NFC verification warnings

Overview

Warnings on the NFC report flag every condition Didit observed while reading and validating the chip. They land in the warnings[] array on each item of nfc_verifications[] (see NFC report), with feature set to "NFC". Each entry follows the shared warning object shape: feature, risk, additional_data, log_type, short_description, long_description, node_id. Every warning has three layers:

The risk code — a stable identifier you can match on in your code (the codes listed below).
The log_type — one of information, warning, or error. It is derived from the action your workflow configures for that risk: No action → information, Review → warning, Decline → error.
The decision impact — the same configured action also drives the NFC report’s status: a Review action moves it to In Review, a Decline action to Declined.

Four NFC risks are configurable this way (SKIPPED_NFC_VALIDATION, NFC_CHIP_NOT_VERIFIED, NFC_TRUST_ANCHOR_MISSING, NFC_AND_OCR_DATA_NOT_SAME). The two certificate risks (DSC_CERTIFICATE_REVOKED, DSC_CERTIFICATE_EXPIRED) are informational only: they always carry log_type: "information" and never change the NFC status by themselves. The full set of risk codes the NFC module produces is below. No other NFC risk codes exist.

Warnings produced

`risk`	Cause	Severity (`log_type`)	Affects status?	Remediation
`SKIPPED_NFC_VALIDATION`	The chip read was skipped — the workflow allows skipping (`allow_nfc_skip`) and the user tapped skip, or the client skipped because it could not read NFC. The exact reason is recorded in `additional_data.skip_reason` (see Skip reasons) and drives the warning’s `long_description`.	Follows the skip NFC action setting (`skip_nfc_action`): information / warning / error.	Configurable — No action, Review, or Decline.	If your policy requires NFC, set the skip action to Decline (or disallow skipping entirely) and instruct the user to retry from an NFC-capable device. Otherwise leave it at No action to fall back to OCR-only verification.
`NFC_CHIP_NOT_VERIFIED`	The chip was read but failed cryptographic verification for a reason other than an explicitly identified missing trust anchor. A Data Group hash, the SOD signature, or another passive-authentication check did not verify.	Follows the unverified chip action setting (`unverified_chip_action`).	Configurable — No action, Review, or Decline.	Treat this as a potentially invalid or altered chip. Inspect `authenticity` and `certificate_summary.validation` to see which check failed.
`NFC_TRUST_ANCHOR_MISSING`	The chip’s Document Signer Certificate (DSC) belongs to a Country Signing Certification Authority (CSCA) generation that is not available in Didit’s trust store (`certificate_summary.validation.csca_missing` is `true`). Didit therefore cannot establish the SOD’s chain of trust.	Follows the unverified chip action setting (`unverified_chip_action`).	Configurable — No action, Review, or Decline.	This is a trust-store coverage gap, not evidence that the chip was altered. Review the document through your fallback checks and contact Didit support with the issuing country so the missing CSCA can be investigated.
`NFC_AND_OCR_DATA_NOT_SAME`	The MRZ read from the chip does not match the MRZ OCR’d from the visible side of the document (compared after normalization, ignoring `<` filler). Strong tampering signal.	Follows the data inconsistency action setting (`inconsistent_data_action`) — the same setting that governs ID-verification data-consistency checks.	Configurable — No action, Review, or Decline.	Treat as tampering unless proven otherwise; Decline is the typical setting. The `additional_data` payload includes the OCR MRZ lines (`ocr_mrz`, array) and the chip MRZ (`nfc_mrz`, single string) for manual comparison.
`DSC_CERTIFICATE_REVOKED`	The Document Signer Certificate that signed this chip appears in the issuing country’s Certificate Revocation List (CRL).	Always `information`.	No — never changes the NFC status by itself.	Strong signal that the signing key may have been compromised; route these sessions to manual review via your own logic if needed. Note the chip will usually also fire `NFC_CHIP_NOT_VERIFIED`, which is configurable.
`DSC_CERTIFICATE_EXPIRED`	The DSC’s validity window has passed (`certificate_summary.validation.dsc_expired` is `true`).	Always `information`.	No — never changes the NFC status by itself.	Common with older documents. As with revocation, an expired DSC also fails full SOD validation, so `NFC_CHIP_NOT_VERIFIED` fires alongside it and carries your configured action.

SKIPPED_NFC_VALIDATION is mutually exclusive with NFC_CHIP_NOT_VERIFIED and NFC_TRUST_ANCHOR_MISSING: chip-verification warnings are only evaluated when the chip read was not skipped. The two chip-verification warnings are also mutually exclusive.

Exact description strings

The API returns these exact short_description and long_description strings for each risk:

`risk`	`short_description`	`long_description`
`SKIPPED_NFC_VALIDATION`	Skipped NFC Validation	Reason-specific — see Skip reasons. Falls back to “The Near Field Communication (NFC) chip validation process was not completed, potentially due to technical issues or lack of NFC support.” on legacy sessions recorded before skip reasons existed.
`NFC_CHIP_NOT_VERIFIED`	NFC chip not verified	The Near Field Communication (NFC) chip failed passive authentication for a reason other than an explicitly identified missing trust anchor. The chip data or signature could be invalid or altered.
`NFC_TRUST_ANCHOR_MISSING`	NFC trust anchor unavailable	The Near Field Communication (NFC) chip could not be verified because the issuing country’s Country Signing Certification Authority (CSCA) trust anchor is not available. This is a trust-store coverage gap, not evidence that the chip was altered.
`NFC_AND_OCR_DATA_NOT_SAME`	NFC and OCR data not same	The Near Field Communication (NFC) chip data and the OCR data don’t match, indicating potential document tampering or data inconsistency.
`DSC_CERTIFICATE_REVOKED`	Document Signer Certificate revoked	The Document Signer Certificate (DSC) used to sign the ePassport chip data has been revoked by the issuing country’s Certificate Revocation List (CRL), indicating the signing key may have been compromised.
`DSC_CERTIFICATE_EXPIRED`	Document Signer Certificate expired	The Document Signer Certificate (DSC) used to sign the ePassport chip data has expired, meaning the certificate’s validity period has passed.

Skip reasons

SKIPPED_NFC_VALIDATION warnings carry additional_data.skip_reason, one of six stable codes stating exactly why NFC did not run (on sessions recorded before skip reasons existed, additional_data may be null — treat the field as optional when processing historical decisions). The same taxonomy appears at the session level as nfc_skip_reason on the decision payload — including for sessions where NFC could never run at all (chipless document, web integration) and therefore no NFC report or warning exists.

`skip_reason`	Meaning	`long_description`
`USER_SKIPPED`	NFC was offered on a compatible device and the user chose to skip.	The NFC chip reading step was offered on a compatible device, but the user chose to skip it (skipping is allowed by the workflow configuration).
`DOCUMENT_WITHOUT_CHIP`	The document design has no readable NFC chip (not an ICAO 9303 electronic document).	NFC verification could not be performed because this document does not have a readable NFC chip: it is not an ICAO 9303 electronic document.
`CHIP_CERTIFICATE_UNAVAILABLE`	The chip exists, but no issuing-country signing certificate (CSCA) covers the document’s issue period, so the signature cannot be verified.	NFC verification could not be performed because the issuing country’s signing certificate (CSCA) covering this document’s issue period is not available, so the chip’s signature cannot be verified.
`DEVICE_WITHOUT_NFC`	A native SDK reported the phone has no NFC reader available.	NFC verification could not be performed because the user’s device reported that it has no NFC reader available.
`INTEGRATION_WITHOUT_NFC_ACCESS`	The verification ran without a native SDK (for example in a web browser), which has no access to the phone’s NFC reader.	NFC verification could not be performed because the verification did not run through a native mobile SDK, so there was no access to the phone’s NFC reader (web browsers cannot read NFC chips).
`MRZ_KEY_UNAVAILABLE`	The chip access key (BAC/PACE seed) could not be derived from the document’s MRZ.	NFC verification could not be performed because the chip access key could not be derived from the document’s machine-readable zone (MRZ).

An NFC report and its SKIPPED_NFC_VALIDATION warning only exist when the client reached the NFC step and explicitly skipped it (typically USER_SKIPPED, or DEVICE_WITHOUT_NFC when the reader turned out to be unavailable at scan time). When the NFC step was bypassed before it could ever be offered — chipless document, missing certificate, no NFC capability reported, unreadable MRZ key — no report or warning is created and the reason surfaces only in the session-level nfc_skip_reason field, without affecting the session status.

Configuration

Three workflow settings control how NFC warnings route. Each can be set to No action, Review, or Decline:

Skip NFC action (skip_nfc_action) — applies to SKIPPED_NFC_VALIDATION. Skipping is only offered to users when allow_nfc_skip is enabled.
Unverified chip action (unverified_chip_action) — applies to both NFC_CHIP_NOT_VERIFIED and NFC_TRUST_ANCHOR_MISSING, so the session status behavior remains the same while the risk code explains why verification failed.
Data inconsistency action (inconsistent_data_action) — applies to NFC_AND_OCR_DATA_NOT_SAME. This is the same data-inconsistency setting used by ID verification.

The two DSC_CERTIFICATE_* risks have no action setting — they are always informational.

Examples

In Review — chip could not be verified

{
  "warnings": [
  {
    "feature": "NFC",
    "risk": "NFC_CHIP_NOT_VERIFIED",
    "additional_data": null,
    "log_type": "warning",
    "short_description": "NFC chip not verified",
    "long_description": "The Near Field Communication (NFC) chip failed passive authentication for a reason other than an explicitly identified missing trust anchor. The chip data or signature could be invalid or altered.",
    "node_id": "nfc_primary"
  },
  {
    "feature": "NFC",
    "risk": "DSC_CERTIFICATE_EXPIRED",
    "additional_data": null,
    "log_type": "information",
    "short_description": "Document Signer Certificate expired",
    "long_description": "The Document Signer Certificate (DSC) used to sign the ePassport chip data has expired, meaning the certificate's validity period has passed.",
    "node_id": "nfc_primary"
  }
]
}

Here the unverified-chip action is set to Review, so NFC_CHIP_NOT_VERIFIED carries log_type: "warning" and the NFC report’s status is In Review. The expired-DSC entry is purely informational.

Declined — chip / OCR mismatch

{
  "warnings": [
  {
    "feature": "NFC",
    "risk": "NFC_AND_OCR_DATA_NOT_SAME",
    "additional_data": {
      "ocr_mrz": ["P<ESPDOE<<JOHN<<<<<<<<<<<<<<<<<<<<<<<<<<<<<", "AAB000123ESP9005154M3001017<<<<<<<<<<<<<<04"],
      "nfc_mrz": "P<ESPDOE<<JOHN<<<<<<<<<<<<<<<<<<<<<<<<<<<<<AAB000254ESP9005154M3001017<<<<<<<<<<<<<<06"
    },
    "log_type": "error",
    "short_description": "NFC and OCR data not same",
    "long_description": "The Near Field Communication (NFC) chip data and the OCR data don't match, indicating potential document tampering or data inconsistency.",
    "node_id": "nfc_primary"
  }
]
}

Here the data-inconsistency action is set to Decline, so the warning carries log_type: "error" and the NFC report’s status is Declined. Note that ocr_mrz is an array of MRZ lines while nfc_mrz is the chip’s single concatenated MRZ string.

Warning types

Each risk is assigned a severity based on your application’s configuration. The three severities are:

NFC report — full report schema and statuses.
Webhooks — status.updated fires on session status changes; the decision payload (including NFC warnings) is attached when the session reaches Approved, Declined, In Review, or Abandoned.
Data models — NFC verification — canonical field-by-field schema.
Data models — Warning object — the shape of every entry in warnings[].

Authentication

Verification

Monitoring

Platform

Overview

Warnings produced

Exact description strings

Skip reasons

Configuration

Examples

In Review — chip could not be verified

Declined — chip / OCR mismatch

Warning types

​Overview

​Warnings produced

​Exact description strings

​Skip reasons

​Configuration

​Examples

​In Review — chip could not be verified

​Declined — chip / OCR mismatch

​Warning types

​Related

Overview

Warnings produced

Exact description strings

Skip reasons

Configuration

Examples

In Review — chip could not be verified

Declined — chip / OCR mismatch

Warning types

Related