Google Pay 付款处理程序规范

处理程序名称： com.google.pay
版本： 2026-01-11

1. 简介

借助 com.google.pay 处理程序，商家可以通过与 UCP 兼容的平台提供 Google Pay 作为加速结账选项。借助 Google Pay API，用户可以访问存储在 Google 账号中的付款方式，从而快速完成结账。

此处理程序支持无头集成模型，在此模型中，商家提供其 Google Pay 配置（例如允许的卡网络和网关参数），而平台处理与 Google Pay API 的客户端互动以生成安全的付款令牌。

1.1 主要优势

通用配置：商家使用标准 JSON 配置 Google Pay 一次，即可让任何授权平台呈现付款界面，而无需自定义前端代码。
解耦的前端：平台负责处理 Google Pay JavaScript API 或 SDK 集成的复杂性，而商家则使用生成的令牌。
安全令牌化：利用 Google 的内置令牌化功能，将加密的凭据直接传递给商家的付款服务提供商 (PSP)。

2. 业务集成

2.1 要求

商家必须先满足以下条件，才能通过 UCP 宣传 Google Pay：

获取 Google Pay 商家 ID：在 PRODUCTION 环境中进行处理时需要此 ID（在 Google Pay 和钱包控制台中注册）。
验证 PSP 支持情况：确保您的支付服务提供商 (PSP) 在 Google Pay 令牌化的受支持处理方和网关列表中。

2.2 处理程序配置

商家通过在其付款处理程序数组中添加处理程序来宣传 Google Pay 支持。该配置严格遵循初始化 Google Pay API 所需的结构。

2.2.1 配置架构

配置对象用于定义环境、商家身份和允许的付款方式。

Google Pay 付款方式

基于 Google Pay 的 PaymentMethod。

令牌化规范

基于 Google Pay 的 TokenizationSpecification。

2.2.2 处理程序声明示例

{
  "payment": {
    "handlers": [
      {
        "id": "8c9202bd-63cc-4241-8d24-d57ce69ea31c",
        "name": "com.google.pay",
        "version": "2026-01-11",
        "spec": "https://pay.google.com/gp/p/ucp/2026-01-11/",
        "config_schema": "https://pay.google.com/gp/p/ucp/2026-01-11/schemas/config.json",
        "instrument_schemas": [
          "https://pay.google.com/gp/p/ucp/2026-01-11/schemas/card_payment_instrument.json"
        ],
        "config": {
          "api_version": 2,
          "api_version_minor": 0,
          "environment": "TEST",
          "merchant_info": {
            "merchant_name": "Example Merchant",
            "merchant_id": "01234567890123456789",
            "merchant_origin": "checkout.merchant.com"
          },
          "allowed_payment_methods": [
            {
              "type": "CARD",
              "parameters": {
                "allowed_auth_methods": ["PAN_ONLY"],
                "allowed_card_networks": ["VISA", "MASTERCARD"]
              },
              "tokenization_specification": {
                "type": "PAYMENT_GATEWAY",
                "parameters": {
                  "gateway": "example",
                  "gatewayMerchantId": "exampleGatewayMerchantId"
                }
              }
            }
          ]
        }
      }
    ]
  }
}

2.3 实体

2.3.1 乐器架构

Google Pay 支付方式 (card_payment_instrument) 扩展了基础卡支付方式。它会继承标准显示字段（例如 brand 和 last_digits），以确保收据呈现效果一致，同时优化 credential 字段以携带特定的 Google Pay 令牌化载荷。

平台行为：平台负责在将 Google Pay PaymentMethodData 响应发送给商家之前，将其映射到此结构中。

名称	类型	是否必需	说明
id	字符串	是	平台为此付款方式分配的唯一标识符。
handler_id	字符串	是	Google Pay 处理程序的标识符。
类型	字符串	是	常量 = `card`。表示相应乐器的行为类似于卡片（继承了卡片显示字段）。
brand	字符串	是	支付卡网络（例如，`visa`，`mastercard`）。从 Google Pay 的 `info.cardNetwork` 映射而来。
last_digits	字符串	是	卡号的后 4 位数字。从 Google Pay 的 `info.cardDetails` 映射而来。
rich_text_description	字符串	否	卡片的可选富文本说明（例如，“Visa - 1234，有效期至 2025 年 12 月”）。
rich_card_art	string (uri)	否	表示卡片的富媒体图片的可选 URI（例如，发卡机构卡片图片）。
billing_address	邮寄地址	否	与卡关联的账单邮寄地址。
凭据	凭据载荷	否	Google Pay 返回的安全令牌化数据。

凭据载荷

此对象用作乐器的 credential。它直接映射到 Google Pay 令牌化数据。

邮政地址

此对象用作 address 字段。它直接映射到 PostalAddress。

3. 平台集成

3.1 要求

在处理 com.google.pay 付款之前，平台必须：

能够加载 Google Pay API for Web（或 Android 等效 API）。
在呈现付款按钮时，请遵守 Google Pay 品牌推广指南。

3.2 付款协议

平台必须遵循以下流程来处理处理程序：

第 1 步：发现和配置

平台会初始化客户端以管理 API 生命周期。

参考： PaymentsClient

第 2 步：检查“准备就绪，随时付款”状态

平台会在显示按钮之前检查用户是否能够使用指定的付款方式进行付款。

参考： isReadyToPay

第 3 步：构建付款请求

平台会组装付款数据请求对象，包括商家配置、付款方式和交易详情（价格和币种）。

参考： PaymentDataRequest

第 4 步：调用用户互动

当用户与付款按钮互动时，平台会触发付款表单显示。

参考： loadPaymentData

第 5 步：完成结账

在用户成功互动后，Google Pay API 会在 payment_data 键下返回一个 PaymentInstrument 对象。平台会将此响应映射到 card_payment_instrument 架构，并提交结账完成请求。

POST /checkout-sessions/{checkout_id}/complete

{
  "payment_data": {
    "id": "pm_1234567890abc",
    "handler_id": "8c9202bd-63cc-4241-8d24-d57ce69ea31c",
    "type": "card",
    "brand": "visa",
    "last_digits": "4242",
    "billing_address": {
      "street_address": "123 Main Street",
      "extended_address": "Suite 400",
      "address_locality": "Charleston",
      "address_region": "SC",
      "postal_code": "29401",
      "address_country": "US",
      "first_name": "Jane",
      "last_name": "Smith"
    },
    "credential": {
      "type": "PAYMENT_GATEWAY",
      "token": "{\"signature\":\"...\",\"protocolVersion\":\"ECv2\"...}"
    }
  },
  "risk_signals": {
      ...
  }
}

4. 业务处理

收到 Google Pay 支付工具后，商家必须：

验证处理程序：确认 handler_id 与 Google Pay 处理程序相对应。
提取令牌：从 payment_data.credential.token 中检索令牌字符串。
处理付款：将令牌字符串和交易详情传递给 PSP 的端点。
- 注意：大多数 PSP 都有一个用于“Google Pay 载荷”或“网络令牌”的特定字段。
返回响应：以最终结账状态（成功/失败）进行响应。

5. 安全注意事项

5.1 令牌安全性

PAYMENT_GATEWAY:：使用此令牌化类型时，令牌会专门针对令牌化方进行加密。透传方无法解密此令牌，应按原样将其透传给令牌化方。
直接：如果使用 DIRECT 令牌化，商家会收到必须解密的加密卡数据。这会大幅增加 PCI DSS 合规性范围，除非企业是 1 级 PCI 合规服务提供商，否则一般不建议这样做。

5.2 环境隔离

测试模式：在 TEST 环境中，Google Pay 会返回虚拟令牌。这些费用无法收取。
生产模式：使用真实卡片。商家必须确保 config.allowed_payment_methods 中的 PSP 凭据与环境相符。

Google Pay 付款处理程序规范 使用集合让一切井井有条 根据您的偏好保存内容并对其进行分类。