Skip to main content

​
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.
FieldTypeDescription
status"Not Finished" | "Approved" | "Declined" | "In Review" | "Resub Requested"NFC-step status (see meanings above).
node_idstring | nullWorkflow graph node that produced this report. Lets you tell two NFC checks apart in a multi-step workflow.
portrait_imagestring (signed URL) | nullPortrait extracted from the chip (DG2). Short-lived presigned link — download promptly; re-fetch the decision for a fresh URL.
signature_imagestring (signed URL) | nullHolder’s signature image from the chip (DG7), when present. Same short-lived presigned behavior.
chip_dataobject | nullFlat 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_integritybooleantrue when the SOD signature chains to a valid issuing-country CSCA and the DSC is neither revoked nor expired.
authenticity.dg_integritybooleantrue 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_summaryobject | nullSummary 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[]arrayModule-level warnings, each with feature, risk, additional_data, log_type, short_description, long_description, and node_id — see NFC warnings.

​
Status values

StatusMeaningDownstream effect
ApprovedChip 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 ReviewA 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.
DeclinedA warning fired whose configured action is Decline.The session is declined unless another approved branch satisfies the workflow.
Not FinishedUser 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 RequestedA 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.