第 1 步：设置沙盒

沙盒是 Google 钱包身份服务的测试环境。它使用测试 ID 而非真实 ID，因此您可以在不接触生产数据的情况下构建和调试集成。

默认情况下，Google 钱包在生产模式下运行，使用真实身份证件。在此步骤中，您需要将测试设备切换到沙盒模式，并为沙盒请求和响应配置服务器。

开始

选择适合您的路径 RP、VR 或面对面

1Here
设置沙盒 将账号列入许可清单并切换设备
2
创建测试 ID 向 Google 钱包添加测试身份证件
3
集成 按您的路径构建：
Relying Party→ Verifier Registrar→
4
测试集成 运行端到端核对清单并录制视频
5
上线 根据您的路径发布：
Relying Party→ Verifier Registrar→

本页中的步骤

A 请求沙盒访问权限将您的测试 Google 账号列入许可清单 B 将设备切换到沙盒在 TapAndPay 设置中启用沙盒 C 确认沙盒模式在 Google 钱包中验证“沙盒”标志 D 配置服务器密钥和 IACA 根证书设置测试签名密钥和 Utopia IACA 根证书

前期准备

第 A 步：为您的测试账号申请沙盒访问权限

默认情况下，用于在沙盒和生产环境之间切换的选项处于隐藏状态。如需在测试设备上启用该切换开关，您必须将自己的 Google 账号添加到沙盒许可清单中：

  1. 使用您在 Google 钱包中使用的 Google 账号填写 Google Pay 沙盒访问权限请求表单。
  2. 如果您在尚未正式推出数字身份证件的国家或地区进行测试，请同时将测试账号的 Gmail 邮箱发送到 wallet-identity-rp-support@google.com。

第 B 步：将设备切换到沙盒模式

  1. 在 Android 测试设备上打开设置应用。
  2. 点按屏幕最顶部的 Google 账号 / 个人资料照片（其中会显示您的姓名和“Google 服务和偏好设置”）。
  3. 如果系统提示，请选择您的个人资料，然后点按所有服务。
  4. 前往其他类别，然后点按 TapAndPay 环境。如果您没有看到 TapAndPay Environment，请重启设备，然后从第 1 步开始重新操作。如果仍然缺失，请验证您的账号是否在沙盒许可清单中（步骤 A）。

  5. 点按下拉菜单，然后选择SANDBOX。

    TapAndPay 环境选择器

  6. 系统会显示一个对话框，通知您环境已更改。点按确定，然后重启设备。

    环境更改确认屏幕截图

  7. 重启后打开 Google 钱包。如果您看到以下对话框，请强行停止并重新打开 Google 钱包，以便其同步到沙盒环境：

    “强行停止 Google 钱包”对话框

第 C 步：确认您的设备处于沙盒模式

  1. 打开 Google 钱包应用 。
  2. 在右上角，依次点按您的个人资料照片或账号 > 钱包设置。
  3. 转到页面底部。如果您看到一条显示 SANDBOX 的确认消息，则表示您的设备已配置为进行沙盒调用。如果您没有看到消息，则表示该应用处于生产模式。
生产模式
图 1：生产模式
沙盒模式
图 2：沙盒模式

部分设备不会在 Google 设置中显示 Google 钱包。如需在这些设备上打开 Google 钱包设置，请使用 adb 运行以下命令：

adb shell am start -n com.google.android.gms/com.google.android.gms.tapandpay.settings.TapAndPaySettingsActivity

切换回正式版

重复步骤 B，但选择 PRODUCTION，而不是 SANDBOX。

Wear OS 设备

如需在已连接的 Wear OS 设备上启用沙盒模式，请添加一个空文件并重启：

adb shell touch /sdcard/Download/android_pay_env_override_sandbox
adb reboot

如需切换回正式版，请删除该文件并重新启动：

adb shell rm /sdcard/Download/android_pay_env_override_sandbox
adb reboot

第 D 步：为沙盒配置服务器

双向沙盒配置，显示出站签名 OpenID4VP 请求和入站 Utopia 测试凭证验证

在沙盒中，您的服务器需要满足以下两个条件：

  1. 请求 Google 钱包沙盒信任的签名凭据：
    • 依赖方：使用 Google 预先信任的沙盒测试密钥对和以下示例元数据。您无需提交表单。
    • 验证者注册机构：使用您自己的沙盒根 CA 颁发的叶证书对请求进行签名（在 Google 将其添加到沙盒受信任证书存储区之后），并按照第 3.A 步：配置 CA 证书配置文件和 CBOR 元数据中的说明生成您自己的 gw_rp_metadata_bytes。
  2. 响应验证信任锚：依赖方和验证方注册机构都必须将 Utopia 沙盒证书添加到其服务器的受信任证书存储区，以验证来自沙盒测试 ID 的响应。

沙盒测试密钥和元数据（信赖方）

如需在沙盒环境中测试签名请求，而无需注册自己的生产密钥，您可以使用以下测试密钥对。这些密钥在沙盒环境中是预先受信任的。

操作说明

  1. 使用测试私钥对请求 (JWS) 进行签名。
  2. 将测试公开证书嵌入到请求的 x5c 标头中。
  3. 将 client_id 设置为此证书的 x509_hash。如需详细了解如何计算哈希值，请参阅签名请求。
  4. 将 client_metadata 中的 gw_rp_metadata_bytes 设置为以下测试信赖方元数据 (Base64url CBOR)。

私钥 (PEM)：

-----BEGIN PRIVATE KEY-----
MIGHAgEAMBMGByqGSM49AgEGCCqGSM49AwEHBG0wawIBAQQggRmIZIHQhXcYIeZ7
KSqS/WwJrsOetdI8ZE4HG0fd+3uhRANCAAR3GR6mdt/NOErO7+XtKqo7orgXWPMI
jEQDeE1PP4KWXTBAhuewPvF8uOiYakz5Jqd1kEFKfiecZEZRrLnC7U+e
-----END PRIVATE KEY-----

信赖方元数据（Base64url CBOR）：

2BhY56Juc2NoZW1hX3ZlcnNpb25idjFnZGlzcGxheaNsZGlzcGxheV9uYW1leBhURVNUIFVTRSBPTkxZIFNhbmRib3ggUlBobG9nb191cml4YWh0dHBzOi8vZm9udHMuZ3N0YXRpYy5jb20vcy9pL3Byb2R1Y3Rsb2dvcy9nb29nbGVnL3Y2L3dlYi02NGRwL2xvZ29fZ29vZ2xlZ19jb2xvcl8xeF93ZWJfNjRkcC5wbmdycHJpdmFjeV9wb2xpY3lfdXJpeCNodHRwczovL3BvbGljaWVzLmdvb2dsZS5jb20vcHJpdmFjeQ

信赖方元数据（CBOR 转储）：

#24# .bstr

{
  "schema_version": "v1",
  "display": {
    "display_name": "TEST USE ONLY Sandbox RP",
    "logo_uri": "https://fonts.gstatic.com/s/i/productlogos/googleg/v6/web-64dp/logo_googleg_color_1x_web_64dp.png",
    "privacy_policy_uri": "https://policies.google.com/privacy"
  }
}

公开证书 (PEM)：

Certificate:
    Data:
        Version: 3 (0x2)
        Serial Number:
            97:99:aa:8b:09:93:5a:20:c1:8b:27:6c:e2:da:91:97:f2:b7:79:8d
        Signature Algorithm: ecdsa-with-SHA256
        Issuer: O=Google, OU=Wallet, CN=TEST USE ONLY Sandbox RP
        Validity
            Not Before: Jun  2 00:39:54 2026 GMT
            Not After : Jun  2 00:39:54 2027 GMT
        Subject: O=Google, OU=Wallet, CN=TEST USE ONLY Sandbox RP
        Subject Public Key Info:
            Public Key Algorithm: id-ecPublicKey
                Public-Key: (256 bit)
                pub:
                    04:77:19:1e:a6:76:df:cd:38:4a:ce:ef:e5:ed:2a:
                    aa:3b:a2:b8:17:58:f3:08:8c:44:03:78:4d:4f:3f:
                    82:96:5d:30:40:86:e7:b0:3e:f1:7c:b8:e8:98:6a:
                    4c:f9:26:a7:75:90:41:4a:7e:27:9c:64:46:51:ac:
                    b9:c2:ed:4f:9e
                ASN1 OID: prime256v1
                NIST CURVE: P-256
        X509v3 extensions:
            X509v3 Subject Key Identifier:
                29:CA:DA:07:9B:1F:68:FA:80:01:E1:68:E3:38:E8:5A:5C:28:B1:6A
            X509v3 Authority Key Identifier:
                29:CA:DA:07:9B:1F:68:FA:80:01:E1:68:E3:38:E8:5A:5C:28:B1:6A
            X509v3 Basic Constraints: critical
                CA:TRUE
            1.3.6.1.4.1.11129.10.1:
                . ...?..!H.Z\j...uT2. .u.:.O.... 0
    Signature Algorithm: ecdsa-with-SHA256
    Signature Value:
        30:46:02:21:00:91:94:fa:b9:85:82:92:bd:6a:98:44:73:ec:
        30:26:1f:92:01:8f:5b:06:d7:8f:21:34:dc:76:f0:89:3c:04:
        8c:02:21:00:ae:3e:9d:46:99:bd:63:7a:cc:59:30:66:48:d0:
        75:cc:c9:82:07:ca:39:f1:f0:df:2b:07:7b:32:b9:5b:3f:0a

-----BEGIN CERTIFICATE-----
MIICFDCCAbmgAwIBAgIVAJeZqosJk1ogwYsnbOLakZfyt3mNMAoGCCqGSM49BAMC
MEUxDzANBgNVBAoMBkdvb2dsZTEPMA0GA1UECwwGV2FsbGV0MSEwHwYDVQQDDBhU
RVNUIFVTRSBPTkxZIFNhbmRib3ggUlAwHhcNMjYwNjAyMDAzOTU0WhcNMjcwNjAy
MDAzOTU0WjBFMQ8wDQYDVQQKDAZHb29nbGUxDzANBgNVBAsMBldhbGxldDEhMB8G
A1UEAwwYVEVTVCBVU0UgT05MWSBTYW5kYm94IFJQMFkwEwYHKoZIzj0CAQYIKoZI
zj0DAQcDQgAEdxkepnbfzThKzu/l7SqqO6K4F1jzCIxEA3hNTz+Cll0wQIbnsD7x
fLjomGpM+SandZBBSn4nnGRGUay5wu1PnqOBhTCBgjAdBgNVHQ4EFgQUKcraB5sf
aPqAAeFo4zjoWlwosWowHwYDVR0jBBgwFoAUKcraB5sfaPqAAeFo4zjoWlwosWow
DwYDVR0TAQH/BAUwAwEB/zAvBgkrBgEEAdZ5CgEEIgQg5taUP70bIUiJWlxqkwYP
dVQyoyCvdaw62E8u4ASBIDAwCgYIKoZIzj0EAwIDSQAwRgIhAJGU+rmFgpK9aphE
c+wwJh+SAY9bBtePITTcdvCJPASMAiEArj6dRpm9Y3rMWTBmSNB1zMmCB8o58fDf
Kwd7MrlbPwo=
-----END CERTIFICATE-----

沙盒 IACA 根证书（所有合作伙伴）

在沙盒中预配的测试 ID 由 Google 的沙盒签发机构 (Utopia) 签名。如需通过加密方式验证沙盒测试身份证件返回的响应中的 issuerAuth 签名，请将此根证书添加到验证器的受信任证书存储区（请勿在生产环境中信任此证书）：

环境 签发机构/国家/地区 凭证类型 IACA 根证书
沙盒 Utopia 身份证件 (com.google.wallet.idcard.1) 下载 Utopia 沙盒证书

如需查看美国各州和各个国家/地区支持的生产 IACA 根证书，请参阅支持的签发机构和 IACA 证书。

沙盒正常运行时间

沙盒环境没有像生产环境那样的正常运行时间服务等级协议 (SLA)。如果您遇到疑似与沙盒服务中断相关的错误，请等待一个美国工作日，然后再与我们联系。中断通常会在该时间段内自行解决。由于可能出现停机，因此请勿将任何关键发布流程设计为依赖于沙盒环境。

下一步

第 2 步：创建测试 ID →