NFC Verification Warnings & Error Codes

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), plus the five Japan My Number Card risks, each with its own setting. 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.
`JPKI_CERTIFICATE_INVALID`	Japan My Number Card: a certificate read from the card does not chain to the JPKI certification authority of its type, is outside its validity period, or is not a My Number Card certificate of that type. `additional_data.certificate_types` lists the certificates that failed; `jpki.certificates[].failure` says why.	Follows `jpki_certificate_invalid_action` (default Decline).	Configurable: No action, Review, or Decline.	Treat as an invalid or altered card. An expired card certificate also lands here: the holder renews it at their municipality.
`JPKI_SIGNATURE_INVALID`	Japan My Number Card: the card’s signature over the one-time challenge does not verify against its certificate, so possession of the card and knowledge of its PIN are not proven. Also raised when the NFC step closed without any card read (`additional_data.certificate_types` is then empty).	Follows `jpki_signature_invalid_action` (default Decline).	Configurable: No action, Review, or Decline.	Do not accept the card read as proof. Ask the person to retry with the physical card.
`JPKI_CERTIFICATE_REVOKED`	Japan My Number Card: the revocation check reports a certificate as revoked, for example because the card was reported lost or the holder’s registration changed (`jpki.revocation_status` is `revoked`).	Follows `jpki_certificate_revoked_action` (default Decline).	Configurable: No action, Review, or Decline.	Do not accept the card.
`JPKI_REVOCATION_UNCHECKED`	Japan My Number Card: the certificates and the signature were verified, but no revocation answer was available (`jpki.revocation_status` is `unchecked`), so a revoked card cannot be ruled out. Not raised when the chain or the signature already failed.	Follows `jpki_revocation_unchecked_action` (default Review).	Configurable: No action, Review, or Decline.	Decide how much a verified card without a revocation answer is worth to you, and set the action accordingly.
`JPKI_AND_OCR_DATA_NOT_SAME`	Japan My Number Card: the name, date of birth, sex or address in the signature certificate differs from the data read from the photo of the same card. `additional_data.fields` names the attributes that differ, never their values.	Follows `jpki_inconsistent_data_action` (default Review).	Configurable: No action, Review, or Decline.	Compare `jpki.attributes` with the ID verification data before deciding. A name with an uncommon character can differ because the certificate holds a substitute character (`jpki.attributes.name_substitute_characters`).

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.
`JPKI_CERTIFICATE_INVALID`	My Number Card certificate not valid	A certificate read from the My Number Card chip is not valid: it does not chain to the Japanese public key infrastructure (JPKI) certification authority, it is outside its validity period, or it is not a My Number Card certificate of the requested type.
`JPKI_SIGNATURE_INVALID`	My Number Card signature not valid	The signature the My Number Card made over the one-time verification challenge does not verify against the card’s certificate, so possession of the card and knowledge of its PIN are not proven.
`JPKI_CERTIFICATE_REVOKED`	My Number Card certificate revoked	The revocation check reports that a certificate read from the My Number Card has been revoked, for example because the card was reported lost or the holder’s registration changed.
`JPKI_REVOCATION_UNCHECKED`	My Number Card revocation status not checked	The certificate and signature of the My Number Card were verified, but its revocation status could not be checked, so a revoked card cannot be ruled out.
`JPKI_AND_OCR_DATA_NOT_SAME`	My Number Card chip and OCR data not same	The name, date of birth, sex or address in the My Number Card’s signature certificate does not match the data read from the card’s image (OCR), indicating a possible substitution or data inconsistency.

Skip reasons

SKIPPED_NFC_VALIDATION warnings carry additional_data.skip_reason, one of seven 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).
`JPKI_UNAVAILABLE`	The document is a Japan My Number Card, whose chip is read through JPKI, and JPKI was not available for this verification: it is not enabled, or the app’s native SDK release cannot read My Number Cards. A My Number Card verified in a browser gets `INTEGRATION_WITHOUT_NFC_ACCESS`, and one on a phone without NFC gets `DEVICE_WITHOUT_NFC`, as for any chip.	NFC verification could not be performed because this My Number Card is read through JPKI, which was not available for this verification: it is not enabled, or the app’s SDK cannot read My Number Cards.

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, JPKI unavailable — 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. The Japan My Number Card risks have five more settings, listed in the next section.

Japan My Number Card (JPKI)

A Japan My Number Card is read through JPKI instead of ICAO 9303 (chip_protocol: "jpki"), so the ICAO risks above never fire for it. Its read raises these five risks instead, each with its own setting on the NFC node:

Setting	Risk	Default
`jpki_certificate_invalid_action`	`JPKI_CERTIFICATE_INVALID`	Decline
`jpki_signature_invalid_action`	`JPKI_SIGNATURE_INVALID`	Decline
`jpki_certificate_revoked_action`	`JPKI_CERTIFICATE_REVOKED`	Decline
`jpki_revocation_unchecked_action`	`JPKI_REVOCATION_UNCHECKED`	Review
`jpki_inconsistent_data_action`	`JPKI_AND_OCR_DATA_NOT_SAME`	Review

A skipped My Number Card read raises SKIPPED_NFC_VALIDATION and follows skip_nfc_action, like any chip. See Japan My Number Card (JPKI) for how the read works.

My Number Card reading through JPKI is not enabled in production yet. Until it is, a My Number Card skips the NFC step with skip reason JPKI_UNAVAILABLE and none of these risks are raised.

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.

In Review: My Number Card without a revocation answer

{
  "warnings": [
  {
    "feature": "NFC",
    "risk": "JPKI_REVOCATION_UNCHECKED",
    "additional_data": null,
    "log_type": "warning",
    "short_description": "My Number Card revocation status not checked",
    "long_description": "The certificate and signature of the My Number Card were verified, but its revocation status could not be checked, so a revoked card cannot be ruled out.",
    "node_id": "nfc_primary"
  }
]
}

Here jpki_revocation_unchecked_action keeps its default, Review, so the warning carries log_type: "warning" and the NFC report’s status is In Review. The card itself was proven: jpki.chain_valid and jpki.signature_valid are both true.

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

NFC Verification Warnings & Error Codes

Overview

Warnings produced

Exact description strings

Skip reasons

Configuration

Japan My Number Card (JPKI)

Examples

In Review — chip could not be verified

Declined — chip / OCR mismatch

In Review: My Number Card without a revocation answer

Warning types

Overview

Warnings produced

Exact description strings

Skip reasons

Configuration

Japan My Number Card (JPKI)

Examples

In Review — chip could not be verified

Declined — chip / OCR mismatch

In Review: My Number Card without a revocation answer

Warning types

Related