Read NFC

Submits the raw data groups read from a NID chip and returns the parsed cardholder identity, the chip portrait, and a verification_key your backend needs to complete the flow. Called by the Mobile SDK.

Endpoint

POST /v1/read_nfc
Content-Type: application/json

{
  "sod": "d4IG/TCCBvkGCSqGSIb3DQEHAqCC…",
  "dg1": "YV1fH1pJRFZOTTAwMXh4eHh4eHh4eA…",
  "dg2": "dYIx1n9hgjHRAgEBf2CCMcmhDoEB…",
  "dg13": "bYIBmzCCAZcCAQEGBijTFgEACDGC…",
  "dg14": "boIBfjGCAXowDQYIBAB/AAcCAgIC…",
  "dg15": "b4IBJjCCASIwDQYJKoZIhvcNAQEB…",
  "document_id": "001xxxxxxxxx",
  "ref_id": "ref_00000001"
}

Parameters:

Param	Type	Required	Default	Description
sod	string	Yes	—	Document Security Object extracted from the NFC chip. Base64.
dg1	string	Yes	—	Data group 1 — the MRZ. Extracted from the NFC chip. Base64.
dg2	string	Yes	—	Data group 2 — the facial image. Extracted from the NFC chip. Base64.
dg13	string	Yes	—	Data group 13 — additional personal details. Extracted from the NFC chip. Base64.
dg14	string	Yes	—	Data group 14 — security options for chip authentication. Extracted from the NFC chip. Base64.
dg15	string	Yes	—	Data group 15 — the active authentication public key. Extracted from the NFC chip. Base64.
document_id	string	Yes	—	NID number of the person whose chip is being verified.
ref_id	string	Yes	—	The transaction reference ID from Create Transaction.

Returns: ReadNfcResponse

Authenticate this call with the JWT token from Create Transaction, as Authorization: Bearer {token} — not with HMAC.

Sample Request

curl --location '<BASE_URL>/v1/read_nfc' \
  --header 'Authorization: Bearer <JWT_TOKEN>' \
  --header 'X-TV-Timestamp: <TIMESTAMP>' \
  --header 'Content-Type: application/json' \
  --data '{
    "sod": "d4IG/TCCBvkGCSqGSIb3DQEHAqCC…",
    "dg1": "YV1fH1pJRFZOTTAwMXh4eHh4eHh4eA…",
    "dg2": "dYIx1n9hgjHRAgEBf2CCMcmhDoEB…",
    "dg13": "bYIBmzCCAZcCAQEGBijTFgEACDGC…",
    "dg14": "boIBfjGCAXowDQYIBAB/AAcCAgIC…",
    "dg15": "b4IBJjCCASIwDQYJKoZIhvcNAQEB…",
    "document_id": "001xxxxxxxxx",
    "ref_id": "ref_00000001"
  }'

Response

{
  "success": true,
  "code": 0,
  "message": "success",
  "request_id": "request_id",
  "data": {
    "citizen_identify": "001xxxxxxxxx",
    "old_citizen_identify": "xxxxxxxxx",
    "full_name": "Nguyễn Văn A",
    "date_of_birth": "12/12/1990",
    "date_of_expiry": "12/12/2030",
    "gender": "Nam",
    "nationality": "Việt Nam",
    "ethnic": "Kinh",
    "religion": "Không",
    "place_of_origin": "Xã An Khánh, Huyện Châu Thành, Tỉnh Bến Tre",
    "place_of_residence": "Tổ 1, Phường Bến Nghé, Quận 1, TP. Hồ Chí Minh",
    "personal_identification": "Sẹo chấm cách 1cm trên đuôi mày trái",
    "date_provide": "01/01/2021",
    "father_name": "Nguyễn Văn B",
    "mother_name": "Trần Thị C",
    "partner_name": "",
    "face_image": "/9j/4AAQSkZJRgABAQA…",
    "is_verified": true,
    "verification_key": "<VERIFICATION_KEY>"
  }
}

NFCData

Field	Type	Description
citizen_identify	string	The 12-digit NID number.
old_citizen_identify	string	The legacy 9-digit CMND number, when the citizen previously held one.
full_name	string	Full legal name of the cardholder.
date_of_birth	string	Date of birth, DD/MM/YYYY.
date_of_expiry	string	Card expiry date, DD/MM/YYYY.
gender	string	Nam (male) or Nữ (female).
nationality	string	Nationality, e.g. Việt Nam.
ethnic	string	Ethnicity, e.g. Kinh.
religion	string	Religion, e.g. Không (none).
place_of_origin	string	Quê quán — the citizen's registered birthplace.
place_of_residence	string	Registered permanent residence address.
personal_identification	string	Distinguishing physical characteristics printed on the card.
date_provide	string	Card issue date, DD/MM/YYYY.
father_name	string	Father's full name.
mother_name	string	Mother's full name.
partner_name	string	Spouse's full name, empty when not recorded.
face_image	string	Base64-encoded JPEG portrait read from DG2.
is_verified	bool	Whether the chip data passed the read-time integrity check.
verification_key	string	Key your backend passes to Verify NFC. Max length 128.

WARNING

The is_verified returned here reflects the chip read only, not a C06 check. Do not approve an onboarding on this value — the SDK is running on a device you do not control. Complete the flow with Verify NFC and decide on that server-side result.

Errors

Code	Description
2001002	internal_bad_gateway
2001019	Transaction not found.
2001020	Transaction lock failed.
2001021	Invalid transaction request.
2001022	Transaction already verified.
2001027	Token invalid.
2001030	Invalid document id.
4001000	Input parameter violates a constraint.
4291000	The number of requests exceeded throughput limit.
5001000	internal_server_error

Code	Description
401	You are not authorized to perform the action.
500	Some unexpected error occurs while processing the request.

Next Steps

• Verify NFC — turn the verification_key into a C06-backed verdict
• NID Field Definitions — formats, validation rules and normalization for every field above