DEV Community: doc.cheap

EU Digital Identity Wallets are due by 24 December 2026: what changes for apps that scan passports

Teoh Chin Heng — Fri, 09 Oct 2026 00:39:30 +0000

Originally published at EU Digital Identity Wallets are due by 24 December 2026: what changes for apps that scan passports

"EU wallets are coming at the end of 2026" has been in a lot of product roadmaps this year. If your signup or onboarding flow asks for a photo of a passport or ID card, it is worth knowing what that sentence actually means. The short version: the date is exact (24 December 2026), it binds the Member States, not you, and it does not switch off document scans.

Below: where the date comes from (with the arithmetic), what a wallet actually hands over (from the attribute tables in the rules), and a design that accepts a wallet when the user has one and falls back to a document scan when they do not.

Disclosure: this was written for the blog of doc.cheap, which reads document images. It does not read wallets, and nothing in the first half of the post depends on it.

Where 24 December 2026 comes from

The obligation is Art. 5a(1) of Reg. (EU) No 910/2014, inserted by Reg. (EU) 2024/1183, the eIDAS amendment. Each Member State "shall provide at least one European Digital Identity Wallet within 24 months of the date of entry into force of the implementing acts referred to in paragraph 23 of this Article and in Article 5c(6)".

So the clock starts with the Commission's implementing acts, not with the amendment. The Art. 5a(23) acts are four implementing acts dated 28 November 2024, among them Implementing Reg. (EU) 2024/2979 on the integrity and core functionalities of wallets. It was published in the Official Journal on 4 December 2024, and its Art. 15 says it "shall enter into force on the twentieth day following that of its publication".

Step	Date
Published in the Official Journal	4 December 2024
Day 1 after publication	5 December 2024
Day 20 after publication: entry into force	24 December 2024
Plus 24 months (Art. 5a(1)): wallets due	24 December 2026
Plus 36 months (Art. 5f(2)): some private relying parties must accept wallets	24 December 2027

The "twentieth day following" counts from the day after publication, so it lands on the 24th, not the 23rd.

What a wallet hands over

A wallet does not send a picture of a passport. It presents signed data. For a natural person the data set is fixed in the Annex to Implementing Reg. (EU) 2024/2977: "person identification data" (PID), issued in two formats, ISO/IEC 18013-5:2021 and the W3C "Verifiable Credentials Data Model 1.1".

Here are the attributes and their presence (Tables 1, 2 and 5 of the Annex as published on 4 December 2024), next to the nearest field in a typical passport scan response (the field names are doc.cheap's, but most scan APIs have an equivalent):

PID attribute	Presence	Nearest field in a document scan
`family_name`	mandatory	`holder.surname`
`given_name`	mandatory	`holder.given_names`
`birth_date`	mandatory	`holder.birth_date` (ISO 8601)
`birth_place`	mandatory	a `birth_place` field, when the document prints one
`nationality`	mandatory (alpha-2, one or more)	`holder.nationality` (alpha-3, one)
`resident_address` and the other `resident_*` attributes	optional	none on a passport data page
`personal_administrative_number`	optional	not the same thing; a document may print a `personal_number`
`portrait`	optional	the portrait image
`family_name_birth`, `given_name_birth`	optional	no curated field
`sex`	optional (codes 0, 1, 2, 3, 4, 5, 6, 9)	`holder.sex` (`M`, `F`, `X`)
`email_address`, `mobile_phone_number`	optional	not on a document
`expiry_date` (metadata)	mandatory	`document.expiry_date`, but of the document, not of the PID
`issuing_authority` (metadata)	mandatory	an `authority` field, when printed
`issuing_country` (metadata)	mandatory (alpha-2)	`document.issuing_state` (alpha-3)
`document_number` (metadata)	optional	not the same thing: assigned by the PID provider, not the passport's number
`issuing_jurisdiction`, `location_status` (metadata)	optional	none

Three things bite when you write the mapping code:

Country codes differ. PID uses ISO 3166-1 alpha-2 (DE); passports and the machine-readable zone use alpha-3 (DEU). Keep one internal form and convert at the edge.
"Mandatory" does not mean "always known". The Annex adds that where a value "is not known for the person or cannot otherwise be issued", Member States "shall use an attribute value appropriate to the situation instead". Expect placeholders, not missing keys.
Only five attributes about the person are mandatory. Address, portrait, sex and birth names are optional. If your flow needs one of them, a given user's wallet may not carry it.

Who still shows up with a document

The deadline obliges each Member State to provide a wallet, not anyone to use one. Art. 5a(15): "The use of European Digital Identity Wallets shall be voluntary." And: "It shall remain possible to access public and private services by other existing identification and authentication means."

So after 24 December 2026 you will still see:

Customers from outside the EU. The recitals tie the wallet to "the legal identity of Union citizens, residents in the Union or legal persons". A visitor with a passport from elsewhere has no EU wallet.
People who have not installed one, or cannot, or would rather not.
Flows that need the document itself: its image, its number or its machine-readable zone, not an attestation about the person.
The months before a given country's wallet is live. The legal deadline and the day a national wallet reaches users are different questions; the only reliable answer for one country is its own announcement or the Commission's.

A design that takes both

Ask for a wallet presentation when the user has one, fall back to a document scan when they do not, and end both paths in the same internal record.

user starts verification
        |
        v
  offers a wallet? --yes--> wallet presentation --> verify signature --> map PID
        |                                                               |
        no                                                              v
        |                                                      internal identity
        v                                                          record
  document photo --> scan API --> map scan fields ----------------------^

Four rules keep the paths interchangeable:

One record, your own field names. Use the table above as the mapping.
Keep the source. Store whether a record came from a wallet or a scan; they carry different evidence.
Normalise empties. A scan may return null for an unknown value; a wallet may send a placeholder. Pick one convention.
Store as little as the flow needs.

Here is the fallback in Node with plain fetch, against the public sandbox key sk_sandbox_public (printed in the docs, no signup, rate limited per client address):

import { readFileSync } from "node:fs";
import { randomUUID } from "node:crypto";

async function scanDocument(path, apiKey = "sk_sandbox_public") {
  const response = await fetch("https://api.doc.cheap/v1/scans", {
    method: "POST",
    headers: {
      Authorization: `Bearer ${apiKey}`,
      "Content-Type": "application/json",
      "Idempotency-Key": randomUUID(), // a retry returns the first result
    },
    body: JSON.stringify({
      image: readFileSync(path).toString("base64"),
      options: { retain_hours: 0, return_portrait: false }, // nothing stored
    }),
  });
  if (!response.ok) throw new Error(`scan failed: HTTP ${response.status}`);
  return response.json();
}

// Map a scan into the same record a wallet presentation would fill.
function fromScan(scan) {
  if (scan.meta.status !== "recognized") return null;
  const field = (name) => scan.fields.find((f) => f.id === `${name}@0`)?.value ?? null;
  return {
    source: "document_scan",
    family_name: scan.holder?.surname ?? null,
    given_name: scan.holder?.given_names ?? null,
    birth_date: scan.holder?.birth_date ?? null,
    birth_place: field("birth_place"),
    nationality_alpha3: scan.holder?.nationality ?? null,
    issuing_country_alpha3: scan.document?.issuing_state ?? null,
    document_number: scan.document?.number ?? null,
    mrz_status: scan.mrz.status, // "passed", "failed" or "absent"
  };
}

meta.status is one of recognized, no_document_found, unreadable, unsupported_document or rejected. Only the first should fill a record; the rest should send the user back to retake the photo. A passport data page carries its MRZ as two lines in the TD3 layout; the doc.cheap MRZ formats page shows TD1, TD2 and TD3 side by side.

One caveat that matters for compliance people: a scan like this is recognition. It reads what is printed and checks the MRZ check digits; the response says authenticity.overall: "not_checked". It is not forgery detection, and not the same assurance as a signed wallet presentation. If your process needs more on the scan path, it has to come from elsewhere in the flow – the doc.cheap passport OCR API comparison lists providers, including ones that do more than recognition.

What to watch next

24 December 2026 – wallets due (Art. 5a(1)).
24 December 2027 – private relying parties. Art. 5f(2): those that must use strong user authentication for online identification, by law or by contract, "shall ... only upon the voluntary request of the user, also accept European Digital Identity Wallets". The text names transport, energy, banking, financial services, social security, health, drinking water, postal services, digital infrastructure, education and telecommunications, and excludes micro and small businesses.
Very large online platforms. Art. 5f(3) makes them accept wallets for user authentication, again on the user's voluntary request and for the minimum data needed.
Changes to the implementing acts. Recital 4 of 2024/2979 says the Commission "should review and update" it where necessary. Re-read the 2024/2977 attribute tables before you freeze a mapping.

Takeaway: build the wallet path when your users' countries ship their wallets, keep the document path, and map both into one record from day one.

This is an engineering summary, not legal advice. Is your team planning to accept the wallet, keep the scan, or both? I would like to hear how others are approaching it in the comments.

Letting an AI agent read identity documents over MCP

Teoh Chin Heng — Thu, 24 Sep 2026 06:56:33 +0000

Originally published at doc.cheap/blog/ai-agent-read-identity-documents-mcp.

Sooner or later someone drops a photo of a passport into a chat with an assistant and asks it to "just fill in the form". A general-purpose vision model will have a go. It may even get the name right. What it will not do is tell you whether the machine-readable zone's check digits passed, return dates in one format every time, or say "I could not read this" instead of guessing.

That gap is a good fit for a tool. The Model Context Protocol lets an agent call one, and this post shows how to give Claude Desktop, Claude Code, Cursor and other clients a document-recognition tool, what the agent gets back, how to keep the cost bounded, and what to think about before you point an agent at identity documents at all.

This is the blog of doc.cheap, the API behind the MCP server used here. The server is MIT-licensed, and the setup questions apply to any tool of this kind.

What the agent gets

The server is @doc-cheap/mcp on npm (MIT, Node 20 or later), and it exposes three tools:

Tool	What it does	Spends credit?
`scan_document`	Recognises a passport, national ID card or driver's licence from a photo or scan and returns the structured result	Yes, only when a document is recognised
`check_balance`	Reads the remaining credits and this month's counters	No (read-only)
`search_docs`	Searches the API documentation bundled with the server, offline	No (read-only)

Each tool carries a title, a description (the two that touch the account state the price), and the MCP behaviour hints a client reads before deciding whether to ask you first: scan_document is marked not read-only, the other two read-only. The server also sends instructions the model reads before any call, saying what it recognises and what a call costs. On top of the tools there are four prompts (scan_document_to_json, check_document_expiry, batch_scan, explain_error), and every docs page is exposed as a read-only resource, such as doccheap://docs/reference/fields.

scan_document answers with the full result as structured JSON plus a one-line summary, for example:

Scan 01a0af18-cd8d-7a61-9f2d-4c7b8e105da3: recognized · passport (GRC) · PARADEIGMA ELENI SOFIA · billed · 684 ms

(An invented specimen holder from the docs.) The JSON behind it has the holder, the document number and dates in ISO 8601, every field with a confidence band, the MRZ lines with a passed / failed / absent verdict, and a billed flag. That structure is the point: the agent does not have to interpret pixels, it reads fields.

Install: the local server

Every client below launches the server with npx. With no key set, it uses the public sandbox key, which gives 10 free recognised documents per IP address in total and at most 10 requests an hour. That is enough to try it. Registering gives 20 free credits; after that a recognised document costs $0.01.

Claude Desktop, Cursor and Windsurf read the same block, in claude_desktop_config.json, ~/.cursor/mcp.json and ~/.codeium/windsurf/mcp_config.json respectively:

{
  "mcpServers": {
    "doc-cheap": {
      "command": "npx",
      "args": ["-y", "@doc-cheap/mcp"],
      "env": { "DOC_CHEAP_API_KEY": "sk_live_your_key" }
    }
  }
}

Leave out the env line to run on the sandbox key.

Claude Code:

claude mcp add-json doc-cheap '{"command":"npx","args":["-y","@doc-cheap/mcp"],"env":{"DOC_CHEAP_API_KEY":"sk_live_your_key"}}'

VS Code:

code --add-mcp '{"name":"doc-cheap","command":"npx","args":["-y","@doc-cheap/mcp"]}'

Gemini CLI and Kiro use the same mcpServers block in their own settings files; the MCP guide has each path. Restart the client after editing: the server picks up a changed environment only on a fresh launch.

Install: the hosted server

If your client connects to a URL instead of launching a command, the same three tools are hosted at https://mcp.doc.cheap/mcp over Streamable HTTP, with no login. The key goes in a header, X-Doc-Cheap-Api-Key or Authorization: Bearer (the named header wins if both are sent); with no key the sandbox key is used.

Claude Code:

claude mcp add --transport http doc-cheap https://mcp.doc.cheap/mcp --header "Authorization: Bearer sk_live_your_key"

Cursor:

{
  "mcpServers": {
    "doc-cheap": {
      "url": "https://mcp.doc.cheap/mcp",
      "headers": { "Authorization": "Bearer sk_live_your_key" }
    }
  }
}

In Claude Desktop and claude.ai, add it under Settings → Connectors as a custom connector with that URL.

The hosted server cannot see files on your machine, so there scan_document takes the image as image_base64 or as a public image_url.

Local files and URLs are fenced on purpose

A tool argument is chosen by a model, and a model can be talked into things. So the local server does not read arbitrary paths:

image_path is off until you set DOC_CHEAP_IMAGE_ROOT to one directory. Paths are resolved through symlinks first, and .. or a link pointing out of the directory is refused. A missing file and an out-of-bounds file get the same message, so the tool cannot be used to probe whether a file exists.
image_url must be https:, must resolve only to public addresses (loopback, private, link-local and similar ranges are refused), follows at most three redirects with every hop re-checked, and is capped at 25 MB.

If you have wired up a file-reading tool for an agent before, compare it with this list. "The model will only pass sensible paths" is not a security boundary.

Keeping the cost bounded

Two properties make agent use predictable:

Only recognised documents are billed. A call is charged when the document type was determined and data was actually extracted: an MRZ whose check digits pass, at least five printed fields, or a correctly decoded barcode. No document found, an unreadable image, an unsupported type, an internal error or a timeout costs nothing. The result's billed flag says which happened, every time. On the sandbox key nothing is charged at all, and the flag then says whether the same scan would have been billed on a live key.
Retries can be made free. scan_document accepts an idempotency_key; on a live key, a repeat with the same key returns the stored first result instead of charging again. A retry without a key is a second scan. The key is remembered only as long as the result is kept, so retain_hours: 0 and replayable retries are one or the other.

In practice:

Have the agent call check_balance before a batch. The server's own instructions tell the model to do this, and the batch_scan prompt does it first. Under the sandbox key the balance is null, and the tool says there is no balance rather than showing zeros.
Auto-approve only the read-only tools. Kiro's config, for example, supports "autoApprove": ["check_balance", "search_docs"]. Leave scan_document behind a confirmation prompt, since it is the one that spends.
Let the agent look things up. search_docs works offline against the bundled docs, so "what does unsupported_document mean" costs nothing and does not rely on the model's memory.

Privacy: questions to ask before you do this

Identity documents are about as sensitive as data gets, and an agent adds parties to the flow. Here is what is true on the API side, and what depends on your setup.

On the API side (as documented):

The uploaded image is held in memory for the request and never written to durable storage.
The recognition result is kept so it can be read back later, for a window set on the account (24 hours, 7 days, 30 days or one year). The default for a new account is one year. Per call, retain_hours: 0 writes no row at all, and scan_document accepts retain_hours too. If the agent only needs the answer once, set it.
Processing happens in the European Union. The data is not used to train models.
return_portrait: false leaves out images.main_photo, the crop of the holder's photo. The crop of the whole page still comes back, and so does the faint second copy of the face some documents print into the page.

On your side:

The result goes into the model's context. Whatever scan_document returns (names, numbers, dates) is now in the conversation, and is processed by whichever LLM provider runs your client under that provider's terms. That is inherent to any MCP tool, not specific to this one.
How the image travels matters. With image_path on the local server, the server reads the file and sends it straight to the API. With image_base64, the image bytes are in the model's tool-call arguments. If you want the pixels to stay out of the model's context, use a fenced local directory.
This is recognition, not verification. The result's authenticity group reads not_checked. A passing MRZ means the zone was read and is internally consistent, not that the document is genuine. There is no liveness or face-match step. If your use case is KYC, this is one input, not the decision.
Use synthetic documents while you build. Specimens and generated MRZs are enough to wire everything up.

A short session

With the server installed, a prompt like "Read this passport scan and tell me whether it expires in the next six months" with a synthetic specimen attached is enough. A well-behaved agent calls scan_document, reads document.expiry_date and document.days_remaining from the result, and answers from those fields rather than from its impression of the image. If the scan comes back unreadable, it should say so and ask for a better photo, and you were not charged for it.

That last behaviour is the real reason to use a tool here: the agent gets an explicit "could not read" instead of the temptation to fill a gap.

Passport OCR in Node.js: image to JSON with fetch, idempotency and the billed flag

Teoh Chin Heng — Thu, 24 Sep 2026 06:51:13 +0000

Originally published at doc.cheap/blog/passport-ocr-nodejs.

Reading a passport photo into structured data is one of those jobs that looks like "call an OCR API" and turns into three follow-up questions the moment it runs in production. What happens when the photo is blurry? What happens when the request times out and you retry: did you just pay twice? And how do your own records know which calls cost money?

This tutorial answers those three with plain Node.js 18+ and the built-in fetch, no SDK. It uses doc.cheap, and this is doc.cheap's own blog, so treat the product choices with appropriate suspicion. The patterns (idempotency keys, branching on a stable error code, keeping a per-call cost flag) apply to any paid API.

The first call, with no account

The API has a public sandbox key printed in its docs, sk_sandbox_public. It runs the same recognition as a paid key and needs no signup: 10 free recognised documents per IP address in total, and at most 10 requests an hour, whatever their answer. That is enough to try everything below. Registering later adds 20 free credits, with no card.

import { readFileSync } from "node:fs";

const image = readFileSync("specimen.jpg").toString("base64");

const response = await fetch("https://api.doc.cheap/v1/scans", {
  method: "POST",
  headers: {
    Authorization: "Bearer sk_sandbox_public",
    "Content-Type": "application/json",
  },
  body: JSON.stringify({ image }),
});

const scan = await response.json();
console.log(scan.meta.status, scan.holder?.full_name, scan.mrz.status);

Save it as first.mjs and run node first.mjs. The call is synchronous: no job id, no polling, no webhook. The recognition happens inside the request and the fields come back in its response.

Use a synthetic specimen for testing, not your own passport. Many issuers publish specimen pages, and ICAO's fictitious "Utopia" documents exist for exactly this.

Image size matters more than you would think. A phone photo straight off the camera can be several megabytes, which base64 inflates by about a third. The docs recommend about 1600 px on the long edge at JPEG quality 85. If a first call feels slow, look at meta.timing.upload_ms before blaming anyone's servers.

What comes back

One JSON shape, eight groups, and every key is always present. A value that is not known is null, never a missing key. An abridged, recognised response looks like this:

{
  "meta": {
    "schema_version": "1.0",
    "id": "01a0af18-cd8d-7a61-9f2d-4c7b8e105da3",
    "status": "recognized",
    "billed": true,
    "confidence": "high",
    "timing": { "upload_ms": 214, "processing_ms": 843, "total_ms": 1074 },
    "created_at": "2026-09-17T09:41:12Z",
    "reference": null
  },
  "document": {
    "kind": "passport", "country": "GRC", "country_name": "Greece",
    "number": "AM7304518", "issue_date": "2022-03-10", "expiry_date": "2032-03-10",
    "is_expired": false, "days_remaining": 2001
  },
  "holder": {
    "given_names": "ELENI SOFIA", "surname": "PARADEIGMA", "full_name": "PARADEIGMA ELENI SOFIA",
    "birth_date": "1994-03-08", "sex": "F", "nationality": "GRC"
  },
  "fields": [],
  "mrz": { "status": "passed", "reason": null, "lines": ["P<GRC…", "AM7304518…"], "text": "P<GRC…" },
  "images": { "document_crop": "data:image/jpeg;base64,…", "main_photo": "data:image/jpeg;base64,…" },
  "quality": { "overall": "pass" },
  "authenticity": { "overall": "not_checked", "checks": [] }
}

(The holder is an invented specimen from the docs; fields and images are trimmed.) The parts worth knowing:

document and holder are the curated values. Dates are ISO 8601, countries ISO 3166-1 alpha-3. Each group is null as a whole when the scan produced nothing for it, which is why the snippet above uses ?..
fields[] is every individual reading, with its own confidence band (high, medium, low, not a fake-precise percentage). A name printed in Greek comes back twice, once in Greek and once transliterated, and the Greek reading is tagged with its language.
mrz.status is passed, failed or absent, and mrz.text is the raw zone so you can re-run the check digits yourself.
authenticity.overall is not_checked. This is recognition, not forgery detection. Do not sell it to your compliance team as ID verification.

A blurry photo is not an exception

The single most useful thing to internalise: a photo that could not be read is a 200, not an error. meta.status is one of exactly five strings:

`status`	Meaning	What to do
`recognized`	Read successfully	Use the data
`no_document_found`	Nothing document-shaped in the frame	Ask the user to re-frame
`unreadable`	A document, but no usable text	Better light, focus, angle
`unsupported_document`	Found, but not a type the API knows	Stop, a retry reads the same
`rejected`	Failed on the service side	Retry once

So your code branches twice: on HTTP status for errors, and on meta.status for outcomes. Treat no_document_found as an exception and you retry a photo that will never read. Treat it as success and you store a document with no fields.

Who pays for the blurry photo

Every response carries meta.billed. On a live key it is true when the document type was determined and data was actually extracted: an MRZ whose check digits pass, at least five fields of the printed zone, or a correctly decoded barcode. Everything else (no document found, unreadable image, unsupported type, internal error, timeout) costs nothing. The price for a billed document is $0.01, flat, at any volume.

On either sandbox key nothing is charged at all. billed still says whether the same scan would have been billed on a live key, which is what makes the sandbox useful for testing the flag.

The flag is per call, so store it next to the result. For a live key, your own count of billed: true rows in a calendar month (UTC) is then the same number GET /v1/usage reports as scans.billed for that month, with no reconciliation step.

Retries that cannot double-charge

The dangerous retry is the one after a timeout: you do not know whether the first request landed. The API accepts an Idempotency-Key header on POST /v1/scans (1 to 255 characters). On a live key, a retry under the same key with the same body returns the stored first result (without the image crops) instead of running recognition and charging again.

Three details from the reference that change how you write the client:

The key is matched together with a fingerprint of the whole body. Same key, different image is a 409 idempotency_conflict, not a silent replay.
A key is remembered only as long as the result is stored. If you send retain_hours: 0 (keep nothing), a later retry under the same key gets 409 idempotency_replay_unavailable: the scan is never run twice, but there is nothing to hand back. Zero retention and replayable retries are mutually exclusive, so pick one per use case.
On the sandbox key the header is accepted but has no effect, because nothing is billed there. You can still write and test the code path.

The whole client

This is the version we would put in a service. It generates one key per image and reuses it on every retry, retries only the error codes the docs say are retryable, honours Retry-After up to a minute and gives up rather than wait longer, and returns the raw scan so you keep every field.

// scan.mjs
import { readFile } from "node:fs/promises";
import { randomUUID } from "node:crypto";

const API = "https://api.doc.cheap/v1/scans";
const KEY = process.env.DOC_CHEAP_API_KEY ?? "sk_sandbox_public";
const RETRY = new Set([
  "rate_limited", "document_repeated", "internal_error", "engine_unavailable",
  "service_unavailable", "maintenance", "idempotency_in_progress",
]);

export class ScanError extends Error {
  constructor(status, error) {
    super(`${error.code} (${status}): ${error.message}`);
    this.code = error.code;
    this.docsUrl = error.docs_url;
    this.requestId = error.request_id;
  }
}

const sleep = (ms) => new Promise((resolve) => setTimeout(resolve, ms));

export async function scan(path, { reference = null, attempts = 4 } = {}) {
  const image = (await readFile(path)).toString("base64");
  const body = JSON.stringify({ image, reference, options: { return_portrait: false } });
  const idempotencyKey = randomUUID(); // one key for this image, reused on every retry

  for (let attempt = 1; ; attempt++) {
    let response;
    try {
      response = await fetch(API, {
        method: "POST",
        headers: {
          Authorization: `Bearer ${KEY}`,
          "Content-Type": "application/json",
          "Idempotency-Key": idempotencyKey,
        },
        body,
        signal: AbortSignal.timeout(60_000),
      });
    } catch (networkError) {
      if (attempt >= attempts) throw networkError;
      await sleep(1000 * 2 ** attempt);
      continue;
    }

    // A proxy in the way can answer with HTML; treat that like a network error.
    const payload = await response.json().catch(() => null);
    if (payload === null) {
      if (attempt >= attempts) throw new Error(`HTTP ${response.status} without a JSON body`);
      await sleep(1000 * 2 ** attempt);
      continue;
    }
    if (response.ok) return payload;

    const { error } = payload;
    if (!RETRY.has(error.code) || attempt >= attempts) throw new ScanError(response.status, error);
    // The sandbox's hourly limit asks for up to an hour; waiting that long
    // inside one call helps nobody, so anything over a minute is an error.
    const retryAfter = Number(response.headers.get("Retry-After"));
    const wait = retryAfter > 0 ? retryAfter : 2 ** attempt;
    if (wait > 60) throw new ScanError(response.status, error);
    await sleep(1000 * wait);
  }
}

export function summarise({ meta, document, holder, mrz }) {
  if (meta.status !== "recognized") {
    return { ok: false, status: meta.status, billed: meta.billed };
  }
  return {
    ok: true,
    billed: meta.billed,
    confidence: meta.confidence,
    kind: document?.kind ?? null,
    country: document?.country ?? null,
    number: document?.number ?? null,
    expiryDate: document?.expiry_date ?? null,
    isExpired: document?.is_expired ?? null,
    surname: holder?.surname ?? null,
    givenNames: holder?.given_names ?? null,
    birthDate: holder?.birth_date ?? null,
    mrz: mrz.status,
    mrzReason: mrz.reason,
  };
}

if (import.meta.url === `file://${process.argv[1]}`) {
  try {
    const result = await scan(process.argv[2], { reference: "demo-1" });
    console.log(summarise(result), result.meta.timing);
  } catch (err) {
    if (err instanceof ScanError) console.error(err.message, err.docsUrl, err.requestId);
    else throw err;
    process.exitCode = 1;
  }
}

Run it with node scan.mjs specimen.jpg. This is what it printed for a generated test passport on the public sandbox key on 24 September 2026. The values read off the document are replaced with …; everything else is exactly as printed:

{
  ok: true,
  billed: true,
  confidence: 'medium',
  kind: 'passport',
  country: '…',
  number: '…',
  expiryDate: '…',
  isExpired: false,
  surname: '…',
  givenNames: '…',
  birthDate: '…',
  mrz: 'passed',
  mrzReason: null
} { upload_ms: 271, processing_ms: 410, total_ms: 691 }

billed: true on a sandbox key is not a charge: it says this scan would have cost one credit on a live key.

A few choices worth explaining:

fetch does not throw on a 4xx or 5xx. It throws only on network failure, so the client checks response.ok and reads the JSON error body either way.
Branch on error.code, never on the HTTP status. On POST /v1/scans, three idempotency codes share 409 and three different outages share 503, and they need different handling. Every error body has the same shape: code, message, docs_url, request_id, event_id. Log the request_id; it is what support needs. The full table is in handle errors.
Not everything is retryable. validation_failed, payload_too_large, unauthorized and insufficient_credits need a fix, not a loop. On the sandbox you will also meet registration_required (the free allowance is spent; waiting does not refill it) and document_repeated (the same image sent too often in an hour).
Do not log the request body. It is an identity document.
reference is echoed back as meta.reference (up to 128 characters), which is the easy way to join a scan to your own order or user record. Two sides of an ID card are two calls; give them the same reference.

Keeping less data

The uploaded image is held in memory for the request and never written to durable storage. The result is a different matter: it is kept so you can read it back with GET /v1/scans/{id}, for a window you choose. The account setting offers 24 hours, 7 days, 30 days or one year, and the default for a new account is one year. Per request, options.retain_hours takes 0 to 8760; 0 writes no row at all. If you only need the JSON once, send retain_hours: 0, and accept the idempotency trade-off above. Processing happens in the EU.

return_portrait: false, used in the client above, leaves out images.main_photo, the crop of the holder's photo, which is one less thing to handle carefully in your own logs and storage. The crop of the whole page still comes back.

Going live

Swap sk_sandbox_public for your own key through DOC_CHEAP_API_KEY and nothing else changes: same endpoint, same shape. A registered key allows 60 requests a minute. Credits are bought with cryptocurrency (BTC, ETH, TRX, or USDT on Ethereum or Tron) with a $1 minimum; there is no card checkout today, which is worth knowing before you plan a demo for a finance team. Pricing has the one price and the billed-only-on-success rule, and the free passport OCR API page has the no-signup first call as a single curl.

If you try it and something in the response shape is awkward to work with in Node, write to admin@doc.cheap. That is the feedback we are after.

Written with the help of AI. The client above was run against the live sandbox and its output is pasted as printed; every statement about doc.cheap was checked against its code.

How passport MRZ check digits work (with a validator in Python and JavaScript)

Teoh Chin Heng — Thu, 24 Sep 2026 06:49:26 +0000

Originally published at doc.cheap/blog/how-mrz-check-digits-work.

Every passport has two lines of angry-looking text at the bottom of the photo page: capital letters, digits and a lot of < signs. That is the machine-readable zone, or MRZ, and it is defined by ICAO Doc 9303, the standard for travel documents. It holds the same core facts as the printed page (name, document number, nationality, date of birth, sex, expiry date), in a form a scanner can read without guessing at fonts or layouts.

It also carries its own error detection. A few of the characters are check digits: each one is computed from a specific field, and one final digit covers several fields at once. If a single character is misread, the digit that protects it usually stops matching. That makes the MRZ one of the few things in identity-document processing you can verify yourself, with twenty lines of code and no trust in anybody's OCR.

This post walks through the algorithm, where the digits sit in each of the three MRZ formats, and a validator in Python and JavaScript that you can paste into a project. Every example uses ICAO's own fictitious specimen, Anna Maria Eriksson of "Utopia" (UTO, a country code that exists only in specimens). No real document appears anywhere.

This is the blog of doc.cheap, a document-recognition API that reads the MRZ and re-checks these digits on the server. Nothing below needs it; the code runs offline.

The alphabet

An MRZ uses exactly 37 characters: 0-9, A-Z and the filler <. There are no lower-case letters, no spaces and no punctuation. Names with accents or non-Latin scripts are transliterated, and spaces inside a field become <. The filler also pads every field to its fixed width, so ERIKSSON<<ANNA<MARIA<<<<<<< is "surname ERIKSSON, given names ANNA MARIA", with the double << separating surname from given names.

The algorithm: weights 7, 3, 1

A check digit is computed the same way for every field of every format:

Turn each character into a number. A digit is its own value. A letter is its position in the alphabet plus 9, so A = 10, B = 11, … Z = 35. The filler < is 0.
Multiply by a repeating weight of 7, 3, 1, 7, 3, 1, … starting from the first character of the field.
Add the products and take the remainder modulo 10. That single digit is the check digit.

Worked through on the specimen passport number, L898902C3, whose printed check digit is 6:

character   L    8    9    8    9    0    2    C    3
value      21    8    9    8    9    0    2   12    3
weight      7    3    1    7    3    1    7    3    1
product   147   24    9   56   27    0   14   36    3

sum = 316        316 mod 10 = 6        the zone prints 6

Why 7-3-1? The weights are chosen so that the most common reading errors change the sum: a single wrong character, and many swaps of two adjacent characters. It is not a cryptographic checksum. Anyone can compute it, so a matching digit proves only that the zone is internally consistent, not that the document is genuine.

The three formats

ICAO 9303 defines three MRZ layouts. The number of lines and the characters per line tell them apart:

Format	Lines × characters	Where you meet it
TD1	3 × 30	ID cards, residence permits
TD2	2 × 36	Older ID cards and some travel documents
TD3	2 × 44	Passport booklets

The specimens used below:

TD3  P<UTOERIKSSON<<ANNA<MARIA<<<<<<<<<<<<<<<<<<<
     L898902C36UTO7408122F1204159ZE184226B<<<<<10

TD2  I<UTOERIKSSON<<ANNA<MARIA<<<<<<<<<<<
     D231458907UTO7408122F1204159<<<<<<<6

TD1  I<UTOD231458907<<<<<<<<<<<<<<<
     7408122F1204159UTO<<<<<<<<<<<6
     ERIKSSON<<ANNA<MARIA<<<<<<<<<<

Read the TD3 second line left to right: L898902C3 document number, 6 its check digit, UTO nationality, 740812 date of birth (YYMMDD), 2 its check digit, F sex, 120415 expiry date, 9 its check digit, ZE184226B<<<<< optional data (often a personal number), 1 its check digit, and finally 0, the composite check digit.

The MRZ parser has the position of every field and check digit in all three as a reference table, and the MRZ formats page walks through each layout.

Where each check digit sits

Positions are 0-based, so they drop straight into slice. Each field's check digit sits immediately after the field.

Field	TD3 (line 2)	TD2 (line 2)	TD1
Document number	0–8, digit at 9	0–8, digit at 9	line 1: 5–13, digit at 14
Date of birth	13–18, digit at 19	13–18, digit at 19	line 2: 0–5, digit at 6
Expiry date	21–26, digit at 27	21–26, digit at 27	line 2: 8–13, digit at 14
Optional data	28–41, digit at 42	none	none
Composite	digit at 43	digit at 35	line 2: digit at 29

The composite digit is where most home-made validators go wrong, because it does not cover the whole line:

TD3: positions 0–9, 13–19 and 21–42 of line 2. It skips the nationality (10–12) and the sex (20).
TD2: positions 0–9, 13–19 and 21–34 of line 2. Same skips.
TD1: it spans two lines: line 1 positions 5–29, then line 2 positions 0–6, 8–14 and 18–28.

Each range includes the per-field check digits inside it, which is what makes the composite catch errors in the digits themselves.

A validator in Python

No dependencies. It detects the format from the shape, checks every field digit and the composite, and returns a dict of results.

WEIGHTS = (7, 3, 1)

def char_value(c):
    if c.isdigit():
        return int(c)
    if "A" <= c <= "Z":
        return ord(c) - ord("A") + 10
    if c == "<":
        return 0
    raise ValueError(f"not an MRZ character: {c!r}")

def check_digit(data):
    return sum(char_value(c) * WEIGHTS[i % 3] for i, c in enumerate(data)) % 10

def digit_ok(data, printed):
    # A field made only of fillers may print "<" as its check digit.
    expected = 0 if printed == "<" else int(printed)
    return check_digit(data) == expected

# (name, line index, start, end, check-digit position) per format
LAYOUTS = {
    "TD3": [("document number", 1, 0, 9, 9), ("birth date", 1, 13, 19, 19),
            ("expiry date", 1, 21, 27, 27), ("personal number", 1, 28, 42, 42)],
    "TD2": [("document number", 1, 0, 9, 9), ("birth date", 1, 13, 19, 19),
            ("expiry date", 1, 21, 27, 27)],
    "TD1": [("document number", 0, 5, 14, 14), ("birth date", 1, 0, 6, 6),
            ("expiry date", 1, 8, 14, 14)],
}

def composite(fmt, lines):
    if fmt == "TD3":
        l = lines[1]
        return l[0:10] + l[13:20] + l[21:43], l[43]
    if fmt == "TD2":
        l = lines[1]
        return l[0:10] + l[13:20] + l[21:35], l[35]
    a, b = lines[0], lines[1]
    return a[5:30] + b[0:7] + b[8:15] + b[18:29], b[29]

def detect(lines):
    shape = (len(lines), len(lines[0]))
    fmt = {(2, 44): "TD3", (2, 36): "TD2", (3, 30): "TD1"}.get(shape)
    if fmt is None or any(len(l) != shape[1] for l in lines):
        raise ValueError(f"unknown MRZ shape: {[len(l) for l in lines]}")
    return fmt

def validate(lines):
    fmt = detect(lines)
    results = {}
    for name, li, start, end, pos in LAYOUTS[fmt]:
        results[name] = digit_ok(lines[li][start:end], lines[li][pos])
    data, printed = composite(fmt, lines)
    results["composite"] = digit_ok(data, printed)
    return fmt, results

if __name__ == "__main__":
    print(*validate(["P<UTOERIKSSON<<ANNA<MARIA<<<<<<<<<<<<<<<<<<<",
                     "L898902C36UTO7408122F1204159ZE184226B<<<<<10"]))
    print(*validate(["I<UTOERIKSSON<<ANNA<MARIA<<<<<<<<<<<",
                     "D231458907UTO7408122F1204159<<<<<<<6"]))
    print(*validate(["I<UTOD231458907<<<<<<<<<<<<<<<",
                     "7408122F1204159UTO<<<<<<<<<<<6",
                     "ERIKSSON<<ANNA<MARIA<<<<<<<<<<"]))
    # One misread character: 3 read as 4 in the document number
    print(*validate(["P<UTOERIKSSON<<ANNA<MARIA<<<<<<<<<<<<<<<<<<<",
                     "L898902C46UTO7408122F1204159ZE184226B<<<<<10"]))

Output:

TD3 {'document number': True, 'birth date': True, 'expiry date': True, 'personal number': True, 'composite': True}
TD2 {'document number': True, 'birth date': True, 'expiry date': True, 'composite': True}
TD1 {'document number': True, 'birth date': True, 'expiry date': True, 'composite': True}
TD3 {'document number': False, 'birth date': True, 'expiry date': True, 'personal number': True, 'composite': False}

The last line is the point of the whole exercise: one character misread as a neighbour, and both the field digit and the composite flag it.

The same validator in JavaScript

Plain ES module, runs in Node or a browser.

const WEIGHTS = [7, 3, 1];

function charValue(c) {
  if (c >= "0" && c <= "9") return c.charCodeAt(0) - 48;
  if (c >= "A" && c <= "Z") return c.charCodeAt(0) - 55; // A = 10
  if (c === "<") return 0;
  throw new Error(`not an MRZ character: ${JSON.stringify(c)}`);
}

export function checkDigit(data) {
  let sum = 0;
  for (let i = 0; i < data.length; i++) sum += charValue(data[i]) * WEIGHTS[i % 3];
  return sum % 10;
}

const digitOk = (data, printed) => checkDigit(data) === (printed === "<" ? 0 : Number(printed));

const LAYOUTS = {
  TD3: [["document number", 1, 0, 9], ["birth date", 1, 13, 19], ["expiry date", 1, 21, 27], ["personal number", 1, 28, 42]],
  TD2: [["document number", 1, 0, 9], ["birth date", 1, 13, 19], ["expiry date", 1, 21, 27]],
  TD1: [["document number", 0, 5, 14], ["birth date", 1, 0, 6], ["expiry date", 1, 8, 14]],
};

function composite(fmt, [a, b]) {
  if (fmt === "TD3") return [b.slice(0, 10) + b.slice(13, 20) + b.slice(21, 43), b[43]];
  if (fmt === "TD2") return [b.slice(0, 10) + b.slice(13, 20) + b.slice(21, 35), b[35]];
  return [a.slice(5, 30) + b.slice(0, 7) + b.slice(8, 15) + b.slice(18, 29), b[29]];
}

export function validate(lines) {
  const fmt = { "2x44": "TD3", "2x36": "TD2", "3x30": "TD1" }[`${lines.length}x${lines[0].length}`];
  if (!fmt || lines.some((l) => l.length !== lines[0].length)) throw new Error("unknown MRZ shape");
  const results = {};
  // The check digit sits right after the field it protects.
  for (const [name, li, start, end] of LAYOUTS[fmt]) {
    results[name] = digitOk(lines[li].slice(start, end), lines[li][end]);
  }
  const [data, printed] = composite(fmt, lines);
  results.composite = digitOk(data, printed);
  return { format: fmt, results };
}

console.log(validate([
  "P<UTOERIKSSON<<ANNA<MARIA<<<<<<<<<<<<<<<<<<<",
  "L898902C36UTO7408122F1204159ZE184226B<<<<<10",
]));

node mrz.mjs prints format: 'TD3' and true for all five checks.

The traps

Do not trim the fillers. The < characters are part of the data the digits are computed over. Strip trailing < from a line and the composite fails on a perfectly good document.

Do not rebuild the zone from parsed fields. If you parse the MRZ into fields, normalise them (dates to ISO, names with spaces) and then re-serialise to check the digits, you are checking your own serialiser. Check the raw lines as they were read.

Normalise OCR output before you validate, carefully. OCR engines like to return lower-case letters, spaces, or « for <. Upper-casing and stripping whitespace is safe. Replacing O with 0 "because document numbers are numeric" is not: document numbers can contain letters, which is exactly what L898902C3 shows.

A passing digit is not a real date. 740812 passes its check digit whether or not the 12th of August 1974 is plausible, and YYMMDD has no century. Decide the century from context: a birth date is in the past, an expiry date usually in the future.

Long document numbers on TD1. ICAO lets a TD1 document number longer than nine characters overflow into the optional-data field, with a < in the normal check-digit position and the check digit after the last character of the number. The validator above does not handle that case. If you process ID cards from issuers that use it, add a branch; the MRZ parser handles it, if you want something to compare against.

Check digits are not authenticity. Anyone who can edit an image can compute a valid digit. The MRZ tells you the zone was read correctly and is internally consistent, not that the document is genuine. Comparing the MRZ against the printed visual zone is a stronger signal, and even that is not a forgery check.

Test data without real passports

You should never need a real person's passport to test this code. Two options:

The ICAO specimens above, which are published for exactly this purpose.
Generate your own: the MRZ generator builds a synthetic TD3 zone with correct check digits from values you type, in the browser. Change one character afterwards and you have a failing case.

For the opposite direction, paste any zone (TD1, TD2 or TD3) into the MRZ parser: it detects the format, reads every field and shows each computed check digit beside the printed one, all in the browser. That is handy when your implementation and someone else's disagree.

Where this fits in a real pipeline

If you read MRZs with your own OCR, run these checks on every read and treat a failure as "re-photograph", not "reject the person": glare over one character, a worn laminate or a creased page are far more common than fraud.

If you use a hosted recognition API instead, re-run the digits yourself anyway when the result decides money or access. It is the one part of the answer you can check without trusting the vendor. That includes us: the doc.cheap response publishes the zone verbatim as mrz.lines and mrz.text (the lines joined with nothing between them) next to its own mrz.status verdict, precisely so you can feed it to a function like the one above. Check an MRZ in the docs covers that flow.

If you spot a case the validator gets wrong, write to admin@doc.cheap.

Written with the help of AI. Both code blocks were run and their output is pasted as printed; every statement about doc.cheap was checked against its code.