在入驻流程中接入 Google Wallet ID:集成指南
如何通过 Didit 接入 Google Wallet ID:先使用沙盒环境,向 Google 注册一次,选择托管流程或独立 API,支持 Android 应用,证件回退机制以及读取验证结果。

简而言之
要在入驻流程中接入 Google Wallet ID,请先在沙盒环境中构建,在 Didit 控制台中为每个生产应用向 Google 完成一次注册,然后在工作流中为某个国家/地区开启 Google Wallet,或直接从您自己的页面或 Android 应用调用独立 API。
- 托管流程:在身份验证步骤中开启 Google Wallet,并保留证件采集作为回退方案。
- 独立 API:由您的后端发起,在用户点击操作中向钱包发起请求,并仅提交一次钱包响应。
- 仅将从后端读取的已完成且已验证的结果作为身份证明。
本指南面向负责编写集成的开发者,以及负责将其接入注册流程的产品经理。指南涵盖通过 Didit 接入 Google Wallet ID 的两种方式:托管流程和独立 API。如需了解已发布的功能及其重要性,请阅读Google Wallet ID 验证。如需了解底层浏览器标准,请阅读我们的Digital Credentials API指南。
用户可共享由护照创建的 ID 通行证,或在美国共享来自支持州的移动驾照;这些凭证来自 Google Wallet 或其他兼容的 Android 钱包。Didit 在五个国家/地区接受该凭证:美国、英国、巴西、新加坡和台湾。[1]
接入 Google Wallet ID 的两种方式
两者均返回相同的已验证属性和相同的 signature_valid 判定结果。[1]
上线速度最快
托管流程(Sessions API)
- Didit 仅在浏览器和设备支持时显示“使用数字身份验证”
- 工作流规则和证件回退在同一会话中运行
- 通过 Web SDK 或 iframe 嵌入
界面由 Didit 承载
完全控制
独立 API
- 您的页面或 Android 应用直接向钱包发起请求
- 无需工作流,无需
workflow_id,无需return_url - 您需要自行构建按钮、重试和任何回退方案
界面由您的 UI 承载
托管流程已预先配置了证件回退功能。原生 Android 应用或自定义注册界面则适合对接独立 API。
开始之前
在编写代码前请确认以下事项。
- 创建沙盒应用:无需向 Google 注册,也不扣除额度。[2]
- 记下将向钱包发起请求的 HTTPS 源,例如
https://app.example.com。 - 将该源的主机名注册为应用的返回主机名,或使用您的白标域名。[2]
- 将 API 密钥保存在后端:每次 Didit 调用都包含
x-api-key并在服务端发起。
钱包会拒绝来自您最初使用源之外的任何源的请求,因此源并不是可以留到以后再处理的细节。[2] Didit 在五个国家/地区支持 Google Wallet。
| 国家/地区 | API 取值 | 用户可共享的凭证 |
|---|---|---|
| 美国 | USA | 由护照创建的 ID 通行证;美国支持州的移动驾照 |
| 英国 | GBR | 由护照创建的 ID 通行证 |
| 巴西 | BRA | 由护照创建的 ID 通行证 |
| 新加坡 | SGP | 由护照创建的 ID 通行证 |
| 台湾 | TWN | 由护照创建的 ID 通行证 |
Didit 上 Google Wallet 的支持国家/地区和 API 取值。[1][2]
选项 1:托管流程
在托管流程中,Google Wallet 是工作流中“身份验证”步骤的又一种方式。在控制台中,打开工作流,进入“身份验证”,选择受支持的国家/地区,并在已接受的钱包中开启 Google Wallet。通过 API 配置时,它是按国家/地区提供的 wallet 配置块:
{"USA": {"document": {"enabled": true}, "wallet": {"enabled": true, "providers": ["google_wallet"], "on_failure": "fallback_to_document"}}}
wallet.providers 是一个准入列表,而非优先级排序:用户可以从您所接受的钱包中自行选择。[1] wallet.on_failure 决定钱包步骤未以已验证结果结束时的处理方式。
1创建会话
您的后端携带工作流调用 Sessions API。
2Didit 检查浏览器
仅在浏览器和设备能够请求钱包时,才会提供此方式。
用户共享数字身份
已验证
签名属性写入该会话。
遵循 on_failure
证件采集,或被拒绝的身份验证。
3读取决定
在您的后端接收 Webhook 或读取会话结果。
以 Google Wallet 作为第一种方式的托管流程。
在 iframe 中嵌入托管流程
如果托管流程在您自己的页面内打开,必须允许浏览器在 iframe 内部请求钱包。请使用 Web SDK 0.5.1 或更高版本,或者将 digital-credentials-get 添加到 iframe 的 allow 属性中。[1][5]
注意事项
如果没有 digital-credentials-get,浏览器将拒绝 iframe 内部的钱包请求。
托管流程向您的用户展示的内容
不会发生重定向。用户在浏览器或 Android 自带钱包的提示框中确认,提示框中会显示贵公司的名称和徽标。在桌面浏览器上,浏览器会自行生成二维码,方便用户通过手机上的钱包完成响应。[1][2] 按钮显示“使用数字身份验证”,因为任何兼容的 Android 钱包都可以响应,并且按钮使用通用钱包图标。
步骤 1
在身份验证步骤中,用户选择标有“使用数字身份验证”的选项。
1用户选择数字身份选项。
步骤 2
浏览器或 Android 会打开自带的钱包提示框,其中包含您的名称和徽标,用户在手机上批准共享。
2钱包提示框属于浏览器或 Android。
步骤 3
如果用户关闭提示框,页面将显示“您的钱包未完成操作”,并提供“重试”或“改为扫描身份证件”。
3提示被取消后,会进入重试或证件扫描。
以上为文字版步骤说明。这是示意图,并非任何真实屏幕的截图;引号中的标签沿用托管流程自身的文案。
选项 2:独立 API,分步说明
使用独立 API 时,您的页面或 Android 应用会通过 W3C Digital Credentials API 直接向钱包发起请求。[7] 没有 Didit 托管页面,也没有 Didit 二维码。[2]
用户点击共享
独立的 Google Wallet 请求。API 密钥绝不离开您的后端。
步骤 1:以您的源(origin)发起请求
您的后端调用 POST /v3/id-verification/wallets/google-wallet/,并附带 x-api-key、Idempotency-Key 以及包含 country 和 origin 的 JSON 请求体。您可以添加 vendor_data(您的客户参考标识,最多 2,000 个 UTF-8 字节)和 metadata。[2][3]
{"country": "USA", "origin": "https://app.example.com", "vendor_data": "your-customer-reference"}
响应包含 request_id、wallet_verification.interaction = "digital_credentials" 以及 next_action.type = "request_digital_credential"。将 next_action.digital_credentials.request 传递给前端页面。
步骤 2:在用户手势内请求钱包
在您发起验证时所用的源上,从“使用数字身份验证”按钮的点击处理程序中调用 navigator.credentials.get({digital: request})。此调用必须在用户手势内执行,因此不要在点击与调用之间插入异步步骤:请在点击之前预先取回请求。[2] 仅在浏览器支持该操作时显示该按钮,例如当 "DigitalCredential" in window 为 true 时。
注意
已取消的提示会以 NotAllowedError 或 AbortError 拒绝;NotSupportedError 表示该浏览器无法向钱包发起请求。请将取消处理为重试和证件流程;如果浏览器无法向钱包发起请求,请隐藏该选项。[2]
步骤 3:提交钱包响应
将钱包返回的内容 {protocol, data} 发送到您的后端。从后端调用 POST /v3/id-verification/wallets/verifications/{request_id}/response/,请求体为 {"response": {...}}。仅提交一次:二次提交将直接返回已判定的验证结果。[2][4]
在该调用背后,Didit 会根据受信任的签发方根证书核对签发方签名,比对每个返回的值与其已签名的摘要,并验证覆盖您的源及此请求的设备签名。[4]
Android 应用
原生 Android 应用使用 Jetpack Credential Manager 并传入相同的请求。[2][8] 根据 next_action.digital_credentials.request 构建 GetDigitalCredentialOption,调用 getCredential,并将返回的 credentialJson 作为 response 请求体发送到您的后端。[2]
这里的源(origin)不同:不用 HTTPS 源,而是发送 android:apk-key-hash: 后接您应用签名证书的不带填充的 Base64 SHA-256 哈希。[2]
| 错误 | 位置 | 处理方法 |
|---|---|---|
origin_invalid | 发起请求,400 | 发送 HTTPS 源或 Android 应用源 |
origin_not_allowed | 发起请求,400 | 将该主机注册为返回主机名 |
not_a_digital_credentials_wallet | 提交,409 | 此验证不接受钱包响应 |
独立集成中需要处理的三种错误。[2]
处理结果与 Webhook
提交响应即为已裁决的验证结果。您也可以通过 GET /v3/id-verification/wallets/verifications/{request_id}/ 读取,或在带有 webhook_version: "v3" 的 status.updated Webhook 中接收。Webhook 的 session_id 与 request_id 一致,钱包身份会显示 verification_method: "wallet"。[2] 请验证 Webhook 签名并确保处理程序具备幂等性:投递失败会自动重试。
| 字段 | 说明 |
|---|---|
full_name, date_of_birth | 身份验证结果中的规范化身份字段 |
wallet_verification.attributes | document_number、document_expiry_date 以及其他共享声明 |
signature_valid | Didit 对已签名断言的裁决结果,该断言在 Didit 内部完成校验且不向外回传 |
assurance | cryptographic:证据为已签名的凭据 |
| 保障级别 | 实质级 |
portrait | null:Google Wallet 不共享头像照片,因此无法与其进行人脸比对 |
已完成的 Google Wallet 验证返回的内容。国籍仅对 ID 通行证返回。[1]
验证失败的凭据不属于错误响应。它是一个结果为 failed 的已裁决验证。[2] 在托管流程中,相同的结果会触发 wallet.on_failure。
| 结果 | 含义 | 计费 |
|---|---|---|
verified | 用户共享了身份证件,且签名属性校验通过 | 是 |
cancelled | 用户退出了钱包提示 | 否 |
timeout | 登录窗口已过期(钱包默认为 10 分钟) | 否 |
failed | 登录未完成或断言未通过验证 | 否 |
钱包结果与计费。[1]
注意事项
浏览器跳转返回的结果,或您自己的页面提交的值,都不能作为身份证明。只有当您的后端通过 API 或已签名的 Webhook 从 Didit 读取到已完成的 verified 结果时,才可批准该账户。[2]
配置证件回退
并非所有人都拥有数字身份,也并非所有浏览器都能向钱包发起请求。托管流程会在浏览器无法发起请求时隐藏该方式,并保留证件采集。[1] 当 on_failure 设置为 fallback_to_document 时,已取消、已过期或失败的钱包尝试会将用户引导至同一会话中的证件采集。若设置为 decline,会话将以被拒绝的身份验证结束。如果该国家/地区未开启证件采集,fallback_to_document 也会直接拒绝,因为没有可回退的目标。[1]

用户点击“改为扫描身份证件”后进入的证件采集步骤。
在独立 API 中,此步骤由您控制:当结果不为 verified 时,提供证件核验。
在沙盒中测试
沙盒应用通过模拟钱包运行与生产环境相同的步骤。响应包含 simulated: true,任何提交的响应均可决定核验结果,且不扣除额度。模拟批准仅为示例数据,并非已验证的身份。[2]
sandbox_scenario | 测试内容 |
|---|---|
wallet_cancelled | 用户取消时的重试与回退机制 |
wallet_timeout | 请求已过期 |
wallet_provider_error | 未能完成的钱包流程 |
沙盒场景。生产应用会拒绝 sandbox_scenario。[2]
上线准备:向 Google 注册
每个生产应用只需向 Google 注册一次。在沙盒应用中,控制台会显示“现在可在沙盒中使用。上线前请向 Google 注册。”在生产应用完成注册之前,保存启用 Google Wallet 的工作流会被拒绝,并提示“启用 Google Wallet 前,请先为此应用向 Google 注册。”[1]
1打开身份验证步骤
在控制台中,找到支持国家/地区的 Google Wallet 行。
2选择“向 Google 注册”
系统会打开“向 Google Wallet 注册”对话框。只有管理员可以提交。
3填写五个字段
法人实体名称、在 Google Wallet 中显示的名称、正方形徽标、隐私政策 URL 以及用途。
4已注册
状态标签依次从“需要注册”变为“注册中”,再变为“已注册”。
一次性设置约需 1 分钟;控制台显示通常会在几分钟内准备就绪。[1]
对话框用一句话说明该步骤:“Didit 会将您的公司作为验证方向 Google 注册。Google 需要先完成这一次注册,您的用户才能与您共享其 Google Wallet ID。”在 Google Wallet 中显示的名称最多 64 个字符;徽标须为至少 256 x 256 px 的正方形 PNG 或 JPG。对话框还会预览用户将共享的内容。
Didit 如何帮助您接入 Google Wallet ID
Didit 与其他受支持的数字身份钱包一起,通过一个 API 处理钱包请求、Google 注册、各项校验和回退。Google Wallet ID 验证的标价为每次完成的验证 $0.20。已取消、已过期、被拒绝或未完成的登录均不收费;证件回退属于另一项核验,按证件验证的价格计费(价格)。[6]在控制台中:工作流 > 身份验证 > 国家/地区 > 接受的钱包。
Didit 提供
- 已签名的钱包请求和 Google 注册
- 签发方、摘要和设备签名核验
- 托管流程、沙盒和证件回退
- 通过 API 和 Webhook 返回已判定的验证结果
由您负责
- 您的源(origin)、返回主机名和 API 密钥
- 您自己的 UI 中的按钮、重试和文案
- 您接受的国家/地区和结果
- 准入决策和您的合规政策
核心要点
- 沙盒无需注册;每个生产应用只需在控制台中向 Google 注册一次。
- 托管流程仅在可用的情况下提供“使用数字身份验证”,并保留证件采集作为回退方案。
- 在 iframe 中,允许
digital-credentials-get或使用 Web SDK 0.5.1 或更高版本。 - 仅从您的后端读取到的已完成
verified结果才构成身份证明。
常见问题
使用 Google Wallet 需要工作流吗?
不需要。独立 API 不需要工作流,也不需要 workflow_id。托管流程使用工作流,其中按国家/地区开启 Google Wallet。
Android 应用应发送什么源(origin)?
发送 android:apk-key-hash:,后接应用签名证书的 Base64 SHA-256 哈希值(不带填充)。网站则发送其页面的 HTTPS 源。
为什么 iframe 内的钱包请求会失败?
除非 iframe 明确允许,否则浏览器会拒绝该请求。在 iframe 的 allow 属性中添加 digital-credentials-get,或使用 Web SDK 0.5.1 或更高版本。
我可以提交两次钱包响应吗?
响应只能提交一次。第二次提交会返回已裁决的验证结果。
失败的凭证在 API 中是什么样的?
它是结果为 failed 的已裁决验证,而不是错误响应。在托管流程中,它遵循 wallet.on_failure。
没有真实的 Google Wallet ID 该如何测试?
使用沙盒应用。它模拟相同的步骤,返回 simulated: true,不扣除额度,并可通过 sandbox_scenario 测试失败情况。
Webhook 如何识别钱包验证?
status.updated Webhook 的 session_id 与钱包 API 的 request_id 一致,且钱包身份带有 verification_method: "wallet"。请使用 webhook_version: "v3" 并验证签名。
如果我页面的源(origin)与发起时使用的源不同,会怎样?
钱包会拒绝该请求。请以实际向钱包发起请求的那个确切源(origin)启动验证,并将该源的主机名注册为应用的返回主机名。
来源
- 数字身份钱包:Google Wallet、失败与回退机制、定价,Didit 文档,查阅于 2026年11月20日。
- 数字身份钱包 API:Digital Credentials 钱包(Google Wallet)、Webhook、沙盒,Didit 文档,查阅于 2026年11月20日。
- API 参考:Google Wallet,Didit 文档,查阅于 2026年11月20日。
- 提交数字身份钱包响应,Didit 文档,查阅于 2026年11月20日。
- 内嵌式 iframe 集成,Didit 文档,查阅于 2026年11月20日。
- 定价,Didit 文档,查阅于 2026年11月20日。
- Digital Credentials API:Web 上安全而私密的数字身份,Chrome for Developers,2025年10月3日。
- 验证数字凭证,Android Developers。
这些模式同样适用于 eID 验证。要查看可接受的所有钱包,请从 Didit 上的数字身份钱包开始。