身份证件验证方式：证件拍摄、数据库核验与数字身份钱包

身份证件验证（ID Verification）是一项包含三种方式的功能。您可以选择某个国家/地区可以使用哪些方式；终端用户会看到适用于其所选国家/地区的方式，会话则会记录实际生成结果的方式。

方式	用户操作	保证等级
拍摄证件	拍摄其护照、身份证、驾照或居留许可	证件证明（Documentary）
无证件核验	输入其国民身份证号和少量个人信息，系统对照政府或其他权威数据源进行核验	数据匹配（Data match）
钱包	使用政府或银行数字身份登录，例如 MitID、BankID 或 itsme	密码学证明（Cryptographic）

拍摄证件方式保持不变。您之前通过 documents_allowed 配置的所有内容（支持的类型、子类型、拍摄规则、阈值、警告）均一如既往地正常工作，未指定任何方式的工作流仍仅使用拍摄证件方式。

各种方式的工作原理

拍摄证件

本节其余部分所介绍的内容：用户拍摄证件，Didit 读取证件、检查其真实性并返回提取的字段。适用于 Didit 支持的每个国家/地区，费用为每次核验 $0.15。请从身份证件验证概述开始了解。

无证件核验

用户输入其国民身份证号和少量个人信息，Didit 对照该国家/地区的权威数据源进行核验。整个过程无需拍摄证件照片。在大多数国家/地区，该数据源是政府登记记录，但并非全部如此：在加拿大、法国、印度尼西亚、荷兰、挪威、新加坡、英国和美国，该数据源是征信机构记录、金融服务记录、公用事业记录或居民登记记录档案。由于数据来源以及适用的同意机制各不相同，具体数据源已在下表以及无证件核验中按国家/地区分别列出，绝无泛化。如果数据源返回头像照片（目前包括南非、尼日利亚、阿根廷和巴拿马，四者均为政府登记记录），系统还会要求用户拍摄一张自拍照。系统会对该自拍照执行被动活体检测，并将其与登记记录中的头像进行人脸比对，所有这些均在核验内部完成，且包含在核验价格中。如果数据源仅返回数据，则没有可供人脸比对的对象，因此不会采集自拍照；如果您需要这些功能，请将活体检测和人脸比对作为独立的工作流步骤运行。各国家/地区完整的请求字段、格式规则和同意机制，请参阅无证件核验。

钱包

用户使用其已有的数字身份登录，例如国民电子身份（eID）或银行身份。钱包对用户进行身份认证，然后与 Didit 共享经过签名的身份属性。根据所用钱包的不同，用户可能会输入个人身份识别码或电话号码；钱包核验无需证件照片。登录体验取决于钱包本身：应用跳转、二维码或在用户手机上确认比对码。 Smart-ID 和 Mobile-ID 使用比对码。各钱包支持的属性、生产环境可用性及失败处理方式，请参阅数字 ID 钱包。

保证等级

每个身份证件验证结果都带有一个源自生成该结果的方式的保证等级。该等级是对实际证明内容的如实描述，而非优劣排名：

等级	会话上的值	含义
证件证明	`documentary`	已拍摄、读取实体证件，并检查了其真实性。
数据匹配	`data_match`	用户提供的信息与所查询数据源中的记录一致。未检查任何证件。
密码学证明	`cryptographic`	数字身份提供商已对用户进行身份认证，并对其共享的属性进行了签名。

保证等级是面向管理员的标识。它们会显示在会话 payload、控制台以及导出数据中。终端用户绝不会看到保证等级、价格或所查询数据源的名称。

按国家/地区配置核验方式

核验方式位于身份证件验证（OCR）功能配置的 methods 键下，以 ISO 3166-1 alpha-3 国家/地区代码作为键名。若省略该键、省略某个国家/地区，或省略国家/地区内的某种方式，则该国家/地区仅使用拍摄证件。

{
  "feature": "OCR",
  "config": {
    "methods": {
      "ZAF": {
        "document": { "enabled": true },
        "id_lookup": {
          "enabled": true,
          "max_attempts": 2,
          "skip_liveness_and_face_match": true,
          "on_partial_match": "fallback_to_document",
          "on_no_match": "fallback_to_document",
          "on_provider_error": "fallback_to_document"
        },
        "wallet": { "enabled": false, "providers": [], "on_failure": "fallback_to_document" }
      },
      "DNK": {
        "document": { "enabled": true },
        "id_lookup": { "enabled": true, "on_no_match": "decline" }
      }
    }
  }
}

上述两个国家/地区均已在已发布的目录中标记为可进行无证件核验的 available 状态。该示例未启用钱包，因此不依赖于您的环境中是否已启用钱包。若工作流启用了标记为即将推出的钱包，该工作流将被拒绝，本次保存中的其他配置也将一并被拒绝。目录将某个国家/地区的钱包标记为 available 后，该国家/地区的钱包配置块如下所示：

{
  "DNK": {
    "document": { "enabled": true },
    "wallet": { "enabled": true, "providers": ["mitid"], "on_failure": "fallback_to_document" }
  }
}

发送配置前请检查目录。前提条件：该钱包在该国家/地区显示为可用，具体列于数字 ID 钱包。 API 在保存时强制执行两条规则：

可用性由服务端控制。如果能力目录未将某种方式或某个钱包标记为针对该国家/地区 available，则会被拒绝。请先查阅目录：可以通过控制台的国家选项卡，或使用 didit_workflow_get_id_verification_methods_catalog MCP 工具。
钱包是准入名单，绝非优先级排序。providers 指定了某个国家/地区可以提供哪些钱包。您发送的顺序没有任何意义，会被标准化处理而不保留；由终端用户自行选择。

完整的逐字段参考（包括默认值和验证），请参阅工作流功能配置。

回退: 非证件方式未成功时的处理机制

有四个开关用于决定后续操作。每个开关均可设为 fallback_to_document（引导用户进入证件采集）或 decline（以身份证件验证已拒绝的状态结束会话）；wallet.on_failure 还支持 retry（下文详述）。这四个开关的默认值均为 fallback_to_document。

开关	触发时机
`id_lookup.on_partial_match`	登记数据库已响应，但部分字段不匹配。
`id_lookup.on_no_match`	登记数据库已响应，但未找到匹配记录。
`id_lookup.on_provider_error`	无法连接到登记数据库或其未响应。
`wallet.on_failure`	钱包登录已取消、超时或失败。

对于仅支持钱包（已关闭证件采集）的国家/地区，wallet.on_failure 还接受第三个值 retry：

值	未完成的登录处理方式
`fallback_to_document`	引导用户进入证件采集。
`decline`	以身份证件验证已拒绝的状态结束会话。
`retry`	将用户保留在钱包步骤，显示“ 未完成”以及主要操作按钮“再次尝试 ”。不提供证件核验选项，会话绝不会因此被拒绝，并将保持开启状态，直至用户完成或会话过期。

retry 仅适用于钱包：查验开关仅接受 fallback_to_document 或 decline，因为返回“无匹配”的登记数据库没有可重试的内容。该值不能与 document.fallback_only 同时配置，因为后者需要在失败后流转至证件采集。如果钱包已成功登录并返回数据，但该数据未能通过工作流的检查（如年龄、姓名比对等），这仍属于已核验的登录：此时由工作流的规则进行决策，wallet.on_failure 并不适用。若登录所使用的 token 真实有效但不可接受（保障级别错误、签名无效、缺失必要声明），则计为失败，并遵循 wallet.on_failure 的逻辑。 id_lookup.max_attempts（1 到 5，默认值为 1）表示在开关触发前，用户可获得的已响应查验次数。未能通过客户端格式校验的号码绝不会发送至登记数据库，因此不会消耗尝试次数，系统只会提示用户进行更正。钱包或查验仅在该国家/地区已启用证件采集且至少接受一种证件类型时，才能回退至证件采集。若证件采集处于关闭状态，或该国家/地区不接受任何证件类型，即使开关设置为 fallback_to_document，失败的登录或未匹配的查验也会拒绝该会话。唯一的例外是 wallet.on_failure: retry，它绝不会拒绝：用户将停留在钱包步骤。这是因为此时没有可回退的目标。 哪种方式生成了结果: fallback_from verification_method 始终指示生成已验证结果的具体方式：wallet、id_lookup 或 document。 fallback_from 则用于在这两种结果中解释为何非证件方式未能结束身份证件验证步骤：

已执行回退。 用户被引导至证件采集。随后的证件验证将包含 verification_method: "document"，并在 fallback_from 中指明失败的方式，例如 { "method": "wallet", "reason": "cancelled", "action": "fallback_to_document" }。通过钱包完成核验的会话具有 verification_method: "wallet" 和 fallback_from: null。
拒绝。 开关设置为 decline，或者没有可供回退的证件。已被拒绝的身份证件验证在 fallback_from 中包含 "action": "decline"。

method 为 wallet 或 id_lookup，而 reason 是导致其终止的结果（cancelled、timeout、no_match、provider_error 等）。相同的字段会出现在会话决策以及 status.updated Webhook 中。未响应的登记数据库（超时或服务中断）属于特例：它本身绝不会直接拒绝用户。该查验不会计费，也不会消耗尝试次数；系统会提示用户重试。在该步骤出现三次未响应的查验后，将应用 id_lookup.on_provider_error：若为 decline 则拒绝，若为 fallback_to_document 则引导用户进入证件采集。当该开关为 fallback_to_document 但该国家/地区没有可供回退的证件时，查验将保持开启状态，用户可以继续尝试；会话不会被拒绝。

仅将证件采集作为回退选项

默认情况下，同时提供钱包或身份查验与证件采集的国家/地区会在首屏并排展示这些选项。将 document.fallback_only 设为 true 可以在为该国家/地区保持启用证件采集的同时，不在初始界面展示该选项。用户将从该国家/地区的钱包或身份查验开始。如果仅配置了单个钱包，用户将直接进入该钱包。只有钱包登录失败、已取消或超时，或者查验不匹配的用户，才会被引导至证件采集。哪些结果会导致流转至证件采集仍由上述开关决定，因此其中至少必须有一个开关设为 fallback_to_document。

{
  "FIN": {
    "document": { "enabled": true, "fallback_only": true },
    "wallet": { "enabled": true, "providers": ["ftn"], "on_failure": "fallback_to_document" }
  }
}

fallback_only 为选填项，默认值为 false。除非 document.enabled 为 true 且该国家/地区中至少有一个钱包或身份查验配置了回退至证件采集，否则该设置会被拒绝。请在 documents_allowed 中启用回退时应提供的证件类型，例如芬兰的护照和身份证。

每种方法的费用

方法	价格
证件采集	每次检查 $0.15
非证件查询	按国家/地区和标识符划分的公开美元费率

这些是标价：您的套餐折扣同时适用于这两种方法。查询根据其运行的服务采用公开的数据库核验零售费率；一次尝试可能涉及多个服务。尼日利亚会选择 NIN 或 BVN 之一。国家/地区表格显示了完整的已配置尝试价格，每次收到响应的重试都会单独计费。

计费规则

已响应的登记库会为查询计费。完全匹配、部分匹配和未匹配均计费：查询已执行，返回的结果即为服务产品。
未响应的登记库不计费。提供商错误不会产生任何费用。
未通过客户端格式检查的号码绝不计费，且绝不会计入 max_attempts，因为它从未到达登记库。
当用户回退时，证件采集会额外计费。已响应查询后回退到证件的情况会收取两次费用，因为共运行了两次检查。

覆盖范围

证件采集在 Didit 支持的每个国家/地区均可用，费用为每次核验 $0.15，以下不再重复列出。本表仅列出存在非证件方式的国家/地区。未列出的国家/地区，或显示为“暂无计划”的单元格，仅支持证件采集。

国家/地区	代码	非证件查询	数字身份钱包
阿根廷	`ARG`	可用 — RENAPER	暂无计划
澳大利亚	`AUS`	暂无计划	ConnectID（即将推出）
奥地利	`AUT`	暂无计划	EUDI Wallet（即将推出）
比利时	`BEL`	暂无计划	itsme（即将推出）、Smart-ID（可用）、EUDI Wallet（即将推出）
玻利维亚	`BOL`	可用 — SEGIP	暂无计划
巴西	`BRA`	可用 — Receita Federal	gov.br（即将推出）、Google Wallet（可用）
保加利亚	`BGR`	暂无计划	EUDI Wallet（即将推出）
柬埔寨	`KHM`	可用 — 内政部选民登记名册	暂无计划
加拿大	`CAN`	可用 — 加拿大征信机构记录（FINTRAC 双重流程）	暂无计划
智利	`CHL`	可用 — Servicio de Registro Civil e Identificación	暂无计划
中国	`CHN`	可用 — 全国公民身份信息中心（NCIIC）	暂无计划
哥伦比亚	`COL`	可用 — Registraduría General de la Nación / ANI	暂无计划
哥斯达黎加	`CRI`	可用 — Tribunal Supremo de Elecciones	暂无计划
克罗地亚	`HRV`	暂无计划	EUDI Wallet（即将推出）
塞浦路斯	`CYP`	暂无计划	EUDI Wallet（即将推出）
捷克	`CZE`	暂无计划	Bank iD（即将推出）、MojeID（即将推出）、EUDI Wallet（即将推出）
丹麦	`DNK`	可用 — CPR 登记系统	MitID（可用）、EUDI Wallet（即将推出）
多米尼加共和国	`DOM`	可用 — Junta Central Electoral	暂无计划
厄瓜多尔	`ECU`	可用 — Registro Civil del Ecuador	暂无计划
萨尔瓦多	`SLV`	可用 — RNPN	暂无计划
爱沙尼亚	`EST`	暂无计划	Smart-ID（可用）、Mobile-ID（可用）、爱沙尼亚身份证（即将推出）、EUDI Wallet（即将推出）
芬兰	`FIN`	可用 — DVV 人口登记系统	Finnish Trust Network（可用）、EUDI Wallet（即将推出）
法国	`FRA`	可用 — 法国居住与公共事业记录	FranceConnect（即将推出）、EUDI Wallet（即将推出）
德国	`DEU`	暂无计划	Personalausweis（即将推出）、EUDI Wallet（即将推出）
希腊	`GRC`	暂无计划	EUDI Wallet（即将推出）
危地马拉	`GTM`	可用 — RENAP	暂无计划
洪都拉斯	`HND`	可用 — CNE	暂无计划
匈牙利	`HUN`	暂无计划	EUDI Wallet（即将推出）
冰岛	`ISL`	暂无计划	Auðkenni（即将推出）、EUDI Wallet（即将推出）
印度	`IND`	可用 — UIDAI (Aadhaar)	暂无计划
印度尼西亚	`IDN`	可用 — 通过居民记录核验印尼人口登记库	暂无计划
爱尔兰	`IRL`	暂无计划	EUDI Wallet（即将推出）
意大利	`ITA`	暂无计划	EUDI Wallet（即将推出）
肯尼亚	`KEN`	可用 — IPRS (Integrated Population Registration System)	暂无计划
拉脱维亚	`LVA`	暂无计划	Smart-ID（可用）、eParaksts mobile（即将推出）、EUDI Wallet（即将推出）
列支敦士登	`LIE`	暂无计划	EUDI Wallet（即将推出）
立陶宛	`LTU`	暂无计划	Smart-ID（可用）、Mobile-ID（可用）、EUDI Wallet（即将推出）
卢森堡	`LUX`	暂无计划	itsme（即将推出）、EUDI Wallet（即将推出）
马来西亚	`MYS`	可用 — JPN (National Registration Department)	暂无计划
马耳他	`MLT`	暂无计划	EUDI Wallet（即将推出）
墨西哥	`MEX`	可用 — RENAPO	暂无计划
荷兰	`NLD`	可用 — 荷兰居民记录	itsme（即将推出）、iDIN（可用）、EUDI Wallet（即将推出）
尼日利亚	`NGA`	可用 — NIMC / NIBSS	暂无计划
挪威	`NOR`	可用 — 挪威居民记录	BankID（即将推出）、Vipps（即将推出）、Buypass ID（即将推出）、EUDI Wallet（即将推出）
巴拿马	`PAN`	可用 — Tribunal Electoral / SIB	暂无计划
巴拉圭	`PRY`	可用 — Tribunal Superior de Justicia Electoral	暂无计划
秘鲁	`PER`	可用 — RENIEC	暂无计划
波兰	`POL`	暂无计划	EUDI Wallet（即将推出）
葡萄牙	`PRT`	暂无计划	EUDI Wallet（即将推出）
罗马尼亚	`ROU`	暂无计划	EUDI Wallet（即将推出）
新加坡	`SGP`	可用 — 新加坡征信机构与公用事业记录	Google Wallet（可用）
斯洛伐克	`SVK`	暂无计划	EUDI Wallet（即将推出）
斯洛文尼亚	`SVN`	暂无计划	EUDI Wallet（即将推出）
南非	`ZAF`	可用 — Department of Home Affairs	暂无计划
西班牙	`ESP`	暂无计划	EUDI Wallet（即将推出）
瑞典	`SWE`	可用 — Skatteverket 人口登记库	BankID（可用）、Freja eID（即将推出）、EUDI Wallet（即将推出）
台湾	`TWN`	暂无计划	Google Wallet（可用）
泰国	`THA`	可用 — DOPA 民事登记	暂无计划
乌克兰	`UKR`	暂无计划	Diia（即将推出）
阿拉伯联合酋长国	`ARE`	暂无计划	UAE PASS（即将推出）
英国	`GBR`	可用 — 英国征信机构和金融服务记录	OneID（即将推出）、Google Wallet（可用）、GOV.UK Wallet（即将推出）
美国	`USA`	可用 — 美国征信机构和金融服务记录	Google Wallet（可用）
乌拉圭	`URY`	可用 — Dirección Nacional del Registro de Estado Civil	暂无计划
委内瑞拉	`VEN`	可用 — CNE	暂无计划
赞比亚	`ZMB`	可用 — Zambia Revenue Authority	暂无计划

支持范围由后端提供的功能目录生成，因此该表格与控制台和 API 验证所依据的来源完全一致。即将推出表示该条目在控制台中可见但尚无法启用；它不是已上线的功能，也不附带承诺的上线日期。

会话中包含的内容

每个身份证件验证结果都会包含生成该结果的方法、其担保等级，以及在运行非证件核验方法时针对该方法的佐证数据块。证件会话的数据结构与以往完全一致，新字段的值为 null。

字段	类型	说明
`verification_method`	string	`document`、`id_lookup` 或 `wallet`。
`assurance`	string	`documentary`、`data_match` 或 `cryptographic`。
`wallet_provider`	string \| null	由钱包生成验证结果时对应的目录钱包 ID。
`id_lookup`	object \| null	登记处核验凭证：来源、核验时间、尝试次数、各字段比对结果、登记处肖像照片。
`wallet_verification`	object \| null	凭证佐证信息：提供商、签发机构、担保等级、签名有效性、共享属性。
`fallback_from`	object \| null	非证件核验方法失败时的 `{ "method": ..., "reason": ..., "action": ... }`：在用户继续进行的证件验证上，`action` 为 `fallback_to_document`，在已拒绝的身份证件验证上为 `decline`。未发生回退时为 `null`。

这三种方法的逐字段类型和示例请参见身份证件验证数据模型，且相同的键也会通过 status.updated Webhook 发送。

身份认证

验证

监控

平台

身份证件验证方式：证件拍摄、数据库核验与数字身份钱包

各种方式的工作原理

拍摄证件

无证件核验

钱包

保证等级

按国家/地区配置核验方式

回退: 非证件方式未成功时的处理机制

仅将证件采集作为回退选项

每种方法的费用

计费规则

覆盖范围

会话中包含的内容

相关内容

​各种方式的工作原理

​拍摄证件

​无证件核验

​钱包

​保证等级

​按国家/地区配置核验方式

​回退: 非证件方式未成功时的处理机制

​仅将证件采集作为回退选项

​每种方法的费用

​计费规则

​覆盖范围

​会话中包含的内容

​相关内容

各种方式的工作原理

拍摄证件

无证件核验

钱包

保证等级

按国家/地区配置核验方式

回退: 非证件方式未成功时的处理机制

仅将证件采集作为回退选项

每种方法的费用

计费规则

覆盖范围

会话中包含的内容

相关内容