NFC verification report

Overview

The NFC verification report captures what Didit read and validated from a document’s NFC chip — an ePassport, an electronic ID card, or another ICAO 9303 e-document. It includes the chip’s biographical data, cryptographic integrity checks (SOD and Data Group hashes), and a summary of the Document Signer Certificate (DSC) used by the issuing country. The report is produced after the user completes the NFC step in a workflow. Didit reads the chip’s Data Groups on the user’s device, verifies the Document Security Object (SOD) signature against the issuing country’s CSCA certificate, checks each Data Group hash against the values the SOD signed, and cross-checks the chip’s MRZ against the MRZ that was OCR’d off the visible side of the document. Each report carries its own status — independent of the overall session status — that reflects how the NFC step alone resolved:

Approved — the chip was read and none of the warnings that fired are configured to route the step to review or decline.
In Review — at least one warning fired whose configured action is Review (for example NFC_CHIP_NOT_VERIFIED when the unverified-chip action is set to Review).
Declined — at least one warning fired whose configured action is Decline (for example NFC_AND_OCR_DATA_NOT_SAME when the data-inconsistency action is set to Decline).
Not Finished — the user never completed the NFC step; the chip read was abandoned or the device did not support NFC.
Resub Requested — a reviewer asked the user to resubmit; the report will be superseded by a new attempt.

Where it appears in API responses

The NFC report ships inside the nfc_verifications[] array — always a JSON array, never a singular nfc object. Multiple entries appear when a workflow runs NFC more than once (for example a step-up flow); each entry carries its own node_id.

Session decision API — appears as nfc_verifications[] at the top level of GET /v3/session/{sessionId}/decision/. See Retrieve session decision.
Webhooks — status.updated payloads include the same nfc_verifications[] array once the NFC step has produced data. See Webhooks.
Standalone NFC — for direct chip submission, see the NFC overview.

Older documentation referenced a singular nfc field. That shape does not exist on the v3 decision endpoint — it only appears on destinations explicitly pinned to V2 webhooks. Always read response.nfc_verifications[0] and iterate the array.

Schema

The canonical field-by-field schema lives on the Data models reference page. The fields below mirror that canonical schema.

Field	Type	Description
`status`	`"Not Finished" \| "Approved" \| "Declined" \| "In Review" \| "Resub Requested"`	NFC-step status (see meanings above).
`node_id`	string \| null	Workflow graph node that produced this report. Lets you tell two NFC checks apart in a multi-step workflow.
`portrait_image`	string (signed URL) \| null	Portrait extracted from the chip (DG2). Short-lived presigned link — download promptly; re-fetch the decision for a fresh URL.
`signature_image`	string (signed URL) \| null	Holder’s signature image from the chip (DG7), when present. Same short-lived presigned behavior.
`chip_data`	object \| null	Flat object with the biographical data parsed from the chip. Always present after a successful read: `dgs` (list of Data Groups read), `surname`, `name`, `country`, `nationality`, `birth_date` (`YYYY-MM-DD`), `expiry_date` (`YYYY-MM-DD`), `sex` (`M`/`F`), `document_type` (MRZ document code, e.g. `P`), `document_number`, `optional_data`, the MRZ check digits (`birth_date_hash`, `expiry_date_hash`, `document_number_hash`, `optional_data_hash`, `final_hash`), `mrz_string`, and `mrz_type` (`TD1`/`TD2`/`TD3`). When the chip carries DG11, `place_of_birth` and `address` are added (and `full_name` / `full_name_non_latin` for documents with a non-Latin name); these keys are absent, not null, otherwise. `null` when the NFC step was skipped.
`authenticity.sod_integrity`	boolean	`true` when the SOD signature chains to a valid issuing-country CSCA and the DSC is neither revoked nor expired.
`authenticity.dg_integrity`	boolean	`true` when every Data Group’s hash matches the value the SOD signed. A `false` value means the chip data was tampered with or partially read.
`certificate_summary`	object \| null	Summary of the DSC that signed this chip: `issuer`, `subject`, `serial_number`, `not_valid_before`, `not_valid_after` (timestamps as `YYYY-MM-DD HH:MM:SS`), plus a `validation` object with the individual check results (`csca_verified`, `dsc_revoked`, `dsc_expired`, `csca_expired`). `null` when the SOD could not be loaded or the step was skipped.
`warnings[]`	array	Module-level warnings, each with `feature`, `risk`, `additional_data`, `log_type`, `short_description`, `long_description`, and `node_id` — see NFC warnings.

Status values

Status	Meaning	Downstream effect
`Approved`	Chip read and no warning fired with a Review or Decline action — including the case where warnings fired but their configured action is “No action”.	Counts as a successful NFC check; will not, by itself, push the session into review.
`In Review`	A warning fired whose configured action is Review (`SKIPPED_NFC_VALIDATION`, `NFC_CHIP_NOT_VERIFIED`, or `NFC_AND_OCR_DATA_NOT_SAME`, depending on your settings).	The session also moves to `In Review` until a reviewer acts.
`Declined`	A warning fired whose configured action is Decline.	The session is declined unless another approved branch satisfies the workflow.
`Not Finished`	User abandoned the NFC step, the device lacked NFC support, or the chip read never completed.	The NFC branch did not produce a result; check workflow fallbacks.
`Resub Requested`	A reviewer requested resubmission of this step.	A new attempt replaces this report once the user retries.

The two certificate warnings (DSC_CERTIFICATE_REVOKED, DSC_CERTIFICATE_EXPIRED) are informational: they appear in warnings[] but never change the NFC status by themselves. See NFC warnings for the full behavior matrix.

Examples

Approved — chip read and cryptographically valid

{
  "nfc_verifications": [
    {
      "status": "Approved",
      "node_id": "nfc_primary",
      "portrait_image": "https://<media-host>/.../epassport/<session-id>_face.jpg?signature=...",
      "signature_image": "https://<media-host>/.../epassport/<session-id>_signature.jpg?signature=...",
      "chip_data": {
        "dgs": ["DG1", "DG2", "DG7", "DG11"],
        "surname": "DOE",
        "name": "JOHN",
        "country": "ESP",
        "nationality": "ESP",
        "birth_date": "1990-05-15",
        "expiry_date": "2030-01-01",
        "sex": "M",
        "document_type": "P",
        "document_number": "AAB000123",
        "optional_data": "",
        "birth_date_hash": "4",
        "expiry_date_hash": "7",
        "document_number_hash": "3",
        "optional_data_hash": "",
        "final_hash": "4",
        "mrz_string": "P<ESPDOE<<JOHN<<<<<<<<<<<<<<<<<<<<<<<<<<<<<AAB000123ESP9005154M3001017<<<<<<<<<<<<<<04",
        "mrz_type": "TD3",
        "place_of_birth": "MADRID, MADRID",
        "address": "CALLE MAYOR 1, MADRID"
      },
      "authenticity": {
        "sod_integrity": true,
        "dg_integrity": true
      },
      "certificate_summary": {
        "issuer": "Common Name: CSCA SPAIN, Serial Number: 3, Organization: DIRECCION GENERAL DE LA POLICIA, Country: ES",
        "subject": "Common Name: DS n-eID SPAIN 2, Organizational Unit: PASSPORT, Organization: DIRECCION GENERAL DE LA POLICIA, Country: ES",
        "not_valid_before": "2020-11-18 10:21:11",
        "not_valid_after": "2031-02-18 10:21:11",
        "serial_number": 118120836164494130086420187336801405660,
        "validation": {
          "csca_verified": true,
          "dsc_revoked": false,
          "dsc_expired": false,
          "csca_expired": false
        }
      },
      "warnings": []
    }
  ]
}

Declined — OCR / chip mismatch

{
  "nfc_verifications": [
    {
      "status": "Declined",
      "node_id": "nfc_primary",
      "portrait_image": "https://<media-host>/.../epassport/<session-id>_face.jpg?signature=...",
      "signature_image": null,
      "chip_data": {
        "dgs": ["DG1", "DG2"],
        "surname": "DOE",
        "name": "JOHN",
        "country": "ESP",
        "nationality": "ESP",
        "birth_date": "1990-05-15",
        "expiry_date": "2030-01-01",
        "sex": "M",
        "document_type": "P",
        "document_number": "AAB000254",
        "optional_data": "",
        "birth_date_hash": "4",
        "expiry_date_hash": "7",
        "document_number_hash": "6",
        "optional_data_hash": "",
        "final_hash": "6",
        "mrz_string": "P<ESPDOE<<JOHN<<<<<<<<<<<<<<<<<<<<<<<<<<<<<AAB000254ESP9005154M3001017<<<<<<<<<<<<<<06",
        "mrz_type": "TD3"
      },
      "authenticity": {
        "sod_integrity": true,
        "dg_integrity": true
      },
      "certificate_summary": {
        "issuer": "Common Name: CSCA SPAIN, Serial Number: 3, Organization: DIRECCION GENERAL DE LA POLICIA, Country: ES",
        "subject": "Common Name: DS n-eID SPAIN 2, Organizational Unit: PASSPORT, Organization: DIRECCION GENERAL DE LA POLICIA, Country: ES",
        "not_valid_before": "2020-11-18 10:21:11",
        "not_valid_after": "2031-02-18 10:21:11",
        "serial_number": 118120836164494130086420187336801405660,
        "validation": {
          "csca_verified": true,
          "dsc_revoked": false,
          "dsc_expired": false,
          "csca_expired": false
        }
      },
      "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"
        }
      ]
    }
  ]
}

Security note

NFC chip data is signed by the issuing authority, so an Approved report with sod_integrity: true and dg_integrity: true is the strongest possible identity evidence Didit can produce. Treat the signed image URLs (portrait_image, signature_image) as short-lived: download them promptly and do not cache them publicly — re-request the decision when you need fresh links.

NFC warnings — full warning enum, causes, and remediation.
Webhooks — listen for the status.updated event to receive the NFC report.
Data models — NFC verification — canonical schema with every field.
Supported documents — which e-documents Didit can read over NFC.

Authentication

Verification

Monitoring

Platform

Overview

Where it appears in API responses

Schema

Status values

Examples

Approved — chip read and cryptographically valid

Declined — OCR / chip mismatch

Security note

​Overview

​Where it appears in API responses

​Schema

​Status values

​Examples

​Approved — chip read and cryptographically valid

​Declined — OCR / chip mismatch

​Security note

​Related

Overview

Where it appears in API responses

Schema

Status values

Examples

Approved — chip read and cryptographically valid

Declined — OCR / chip mismatch

Security note

Related