Google Pay™

Google Pay™ 让客户使用保存在 Google 账号或设备中的卡付款。你可以通过 Clink Hosted Checkout 或 Elements 接收这类支付。

Clink 网关开通：下文的 clink 网关配置需要单独开通生产权限。使用前，请让 Clink 确认你的账号已经开通。现有 Google Pay 集成可能使用已关联 PSP 的网关，不要自行将它替换为 clink。

接入前准备

联系 Clink 为商户账号开通 Google Pay，并确认处理渠道、支持的卡组织、支付币种和结算国家。可用范围取决于账号和渠道；Google Pay 请求中包含某个卡组织，不代表交易一定可以处理。
与 Clink 确认 PAN_ONLY 的风控和 3D Secure（3DS）配置。策略与普通卡支付相同：按风险选择性触发 3DS，并满足交易所需的认证要求。
使用对应环境的沙盒 API Key 和接口地址。服务端使用 Secret Key，Elements 使用 Publishable Key。

使用 Hosted Checkout 或 Elements 的所有商户，都必须遵守 Google Pay and Wallet API Acceptable Use Policy，并接受 Google Pay API Terms of Service。

选择接入方式

方式	商户需要实现	Google Pay 处理
Hosted Checkout	在服务端创建 Session，将客户跳转到返回的 `url`	Clink 托管支付按钮，接收 Google Pay 返回数据、提交支付并处理所需认证
Elements	在服务端创建 Session，初始化 Elements 并挂载 `paymentMethod`	Clink 的嵌入式收银台渲染按钮，处理 Google Pay 返回数据和所需认证

本文适用于 Web 集成，不定义原生 Android 接入流程。

Hosted Checkout

使用 uiMode: "hostedPage"。这条路径不需要在你的网站代码中加载 Google Pay JavaScript、生成 Google 请求对象或配置 Google Merchant ID。跳转到 Session URL，不要将托管页面放进自建 iframe。

Elements

使用 uiMode: "elements"，并提供 returnUrl。按照 Elements 安装与挂载说明接入，并固定应用已测试的 SDK 版本。开通 clink 网关时，Clink 需要确认兼容的 SDK 版本和账号配置。 Elements 在 Clink 管理的收银台中加载 Google Pay 客户端，并生成 IsReadyToPayRequest 和 PaymentDataRequest。商户无需生成这些请求、重复加载 Google Pay 客户端，也不需要向 loadClinkElements() 传入 Google Merchant ID。如果网站通过 Content Security Policy 限制第三方内容，需要在 frame-src 中允许对应环境的 Elements iframe origin，并在 connect-src 中允许 Clink API origin。loadClinkElements() 会在创建 iframe 前，从商户页面向 API 发送初始化请求，因此两类 origin 都需要允许：

环境	Elements iframe origin（`frame-src`）	Clink API origin（`connect-src`）
沙盒	`https://uat-elements.clinkbill.com`	`https://uat-api.clinkbill.com`
生产	`https://elements.clinkbill.com`	`https://api.clinkbill.com`

将对应 origin 合并到现有策略中。例如，沙盒的指令可以包含：

frame-src 'self' https://uat-elements.clinkbill.com;
connect-src 'self' https://uat-api.clinkbill.com;

切换生产环境时，两类 origin 都需要使用生产值。Hosted Checkout 跳转使用独立的 uat-checkout.clinkbill.com 和 checkout.clinkbill.com 域名。渠道的 3DS 流程可能需要额外的 iframe origin，开通时向 Clink 获取对应要求。上线前确认收银台和认证资源能正常加载，没有 CSP 错误。容器应允许收银台和 3DS 界面扩展，参见 Elements 布局要求。

网关与商户标识

以下配置适用于已开通 Clink 网关的账号：

Google Pay 字段	配置值	获取方式
`tokenizationSpecification.type`	`PAYMENT_GATEWAY`	使用网关接入类型
`tokenizationSpecification.parameters.gateway`	`clink`	Clink 已向 Google 登记的 Gateway ID
`tokenizationSpecification.parameters.gatewayMerchantId`	Clink 为该集成分配的唯一商户标识	开通时向 Clink 获取对应环境的值
`merchantInfo.merchantId`	Google 为生产集成分配的 Merchant ID	由 Clink 为托管或嵌入式收银台配置

gatewayMerchantId 和 Google 的 merchantId 是不同的标识。不要使用订单 ID、客户 ID、API Key 或关联 PSP 的商户 ID 替代。Google onboarding 测试中的 googletest 等值不能用作商户生产标识。 Hosted Checkout 和 Elements 从 Session 获取网关配置。商户不在 Create Session API 中设置这些字段，也不在浏览器中修改它们。以下示例说明已开通 Clink 网关的 Google 请求配置，不是需要额外实现的商户 API 调用：

{
  "tokenizationSpecification": {
    "type": "PAYMENT_GATEWAY",
    "parameters": {
      "gateway": "clink",
      "gatewayMerchantId": "<CLINK_ASSIGNED_GATEWAY_MERCHANT_ID>"
    }
  }
}

卡凭证与 3DS

Google Pay 可以返回两种授权方式。只启用商户账号和处理渠道已批准的方式。

方式	凭证	认证策略
`PAN_ONLY`	保存在 Google 账号中的卡信息	使用与普通卡交易相同的风险触发 3DS 规则；这种方式不能用 Google Pay 替代持卡人的额外认证
`CRYPTOGRAM_3DS`	设备 token 和支付 cryptogram	通过已开通渠道提交 token 和 cryptogram；不要当作 `PAN_ONLY` 普通卡，也不要仅因为选择 Google Pay 就套用普通 `PAN_ONLY` 的 3DS 流程

要为 PAN_ONLY 启用 3DS，请联系 Clink，将普通卡的风控和 3DS 设置应用到相应渠道的 Google Pay PAN_ONLY 交易，并在开通生产前确认配置。公开 Create Session 请求中没有 Google Pay 3DS 开关。需要额外认证时，Hosted Checkout 和 Elements 会处理客户交互。在认证及授权完成前，支付应保持未完成状态。Google Pay 弹窗关闭、SDK 事件或返回跳转都不代表支付成功；应通过服务端 Order 状态或验签后的 order.succeeded webhook 确认。两种授权方式各自支持的结算国家和币种，需要分别确认。不要从客户设备、发卡国家或 Google 的 countryCode 推断。参见 Google 的 PSP 额外认证说明。

卡组织与账单地址

Web 收银台请求中包含 Google 的 AMEX、DISCOVER、INTERAC、JCB、MASTERCARD 和 VISA。这是请求范围，不代表每个账号都支持全部卡组织的处理与结算。上线前，请让 Clink 确认渠道支持的子集和结算国家。开通 Clink 网关生产权限前，Clink 需要确认 allowedCardNetworks 和 allowedAuthMethods 符合该集成已批准的卡组织及授权方式。这是开通要求，不是商户侧的配置开关。Hosted Checkout 和 Elements 管理这些请求对象，商户不向 Create Session API 传入这两个数组。当前 Web 收银台没有在 Google Pay 弹窗中请求账单地址（未启用 billingAddressRequired）。Clink 可能在收银台中另行收集税务或处理所需的账单信息；出现这些字段时应完整填写。不要假设 Google token 包含邮寄地址或电话号码。如果渠道需要地址验证，请在开通前与 Clink 确认所需字段。若单独实现 Google 请求并收集地址，应使用 BillingAddressParameters，设置所需地址格式及是否需要电话号码。

提交交易

1. 在服务端创建 Checkout Session

两种接入方式都使用这个商户 API。示例使用沙盒配置，创建一笔 USD 19.99 的一次性购买。originalAmount 和 unitAmount 使用货币主单位。

# CLINK_SECRET_KEY 是保存在服务端的沙盒 Secret Key。
curl --request POST 'https://uat-api.clinkbill.com/api/checkout/session' \
  --header "X-API-Key: ${CLINK_SECRET_KEY}" \
  --header "X-Timestamp: $(node -p 'Date.now()')" \
  --header 'Content-Type: application/json' \
  --data '{
    "customerEmail": "customer@example.com",
    "merchantReferenceId": "merchant_order_123",
    "originalAmount": 19.99,
    "originalCurrency": "USD",
    "paymentMethodType": "GOOGLEPAY",
    "uiMode": "hostedPage",
    "successUrl": "https://merchant.example.com/success",
    "cancelUrl": "https://merchant.example.com/cancel",
    "priceDataList": [
      {
        "name": "One-time purchase",
        "quantity": 1,
        "unitAmount": 19.99,
        "currency": "USD"
      }
    ]
  }'

每次请求都需要生成新的毫秒级 X-Timestamp。认证和完整接口定义参见 API Key 与 Webhook及 Create checkout session。 paymentMethodType: "GOOGLEPAY" 会在 Google Pay 可用时默认选中它，不会开通未配置的支付方式。不要在 paymentMethodTypeBlackList 中加入 GOOGLEPAY。merchantReferenceId 用于对账，不是幂等键。如果不希望通过 Google Pay 保存的卡出现在 CARD 的已绑卡列表中，创建 Session 时传入 filterGooglePayBoundCard: true。默认值为 false。它只过滤该列表，不会关闭原本可用的 GOOGLEPAY 支付方式。 Hosted Checkout 使用返回的 data.url 跳转。Elements 将请求改为 uiMode: "elements"，提供 returnUrl，并只向前端返回 data.sessionId。

2. 渲染支付界面

Elements 使用应用配置中的 Publishable Key 初始化：

import { loadClinkElements } from '@clink-ai/clink-elements';

const clink = await loadClinkElements({
  sessionId, // 由服务端创建
  publishKey: PUBLIC_CLINK_PUBLISHABLE_KEY, // 沙盒：pk_uat_…
  environment: 'sandbox',
});

clink.on('submit-visible', (visible) => {
  merchantPayButton.hidden = !visible;
});

// 在挂载前注册，避免错过首次可用状态事件。
clink.on('sdk-button-initialized', ({ googlePay }) => {
  const googlePayHint = document.getElementById('google-pay-hint');
  if (googlePayHint) googlePayHint.hidden = googlePay !== true;
});

const paymentMethod = clink.createElement('paymentMethod');
paymentMethod.mount('#payment-method');

示例中可选的 google-pay-hint 元素是商户自己的提示文案，不是支付按钮。googlePay === true 表示初始化后按钮可用；false 表示设备不支持、配置或 SDK 加载失败，或初始化超时；字段缺省表示当前 Session 未提供 Google Pay。可用状态在收银台交互中可能变化，应持续保留监听。Google Pay 不可用时，客户可以选择 Session 中其他可用方式，例如已开通的 CARD。详见 SDK 按钮可用状态。 SDK 渲染 Google 官方按钮并接管点击。不要再绘制一套 Google Pay 按钮，也不要对该按钮调用 clink.submit()。完整前端及事件处理见 Elements。

3. 处理加密数据与支付结果

Google 在 PaymentData 响应的 paymentMethodData.tokenizationData.token 中返回加密 payload。Hosted Checkout 和 Elements 接收这个值，将它与 Session 的交易上下文一起转交给 Clink 收银台服务。商户服务端通过 Create Session 提交金额、币种、客户和商户订单引用，不需要另行提取、解密或通过公开 charge API 提交 Google token。公开 POST /payment 和 Payment Instrument API 不是 Google Pay token 的直传接口。不要向这些接口发送 blob 或解密后的卡数据。在已开通的 Clink 网关渠道上，Clink 负责验签、过期检查、解密，以及在处理支付前核对 gatewayMerchantId 与商户是否匹配。Clink 调整下游处理渠道时，商户的前端接入保持不变。使用验签后的 webhook或服务端 Order 查询确认最终支付结果。pending、失败和额外认证都按所选接入方式的标准状态流程处理。

Google 资源与生产检查

使用官方 Google Pay Logo 和按钮素材，不修改颜色、比例或外观。在网站中展示 Google Pay 或设置收银台样式时，遵守 Web 品牌规范。 Elements 的按钮主题、类型、高度和圆角，通过 presetOptions.sdkButtons.googlePay 配置。允许的取值范围见 Elements 按钮样式。不要用自定义 CSS 覆盖 SDK 渲染的按钮。

如果在 Clink 托管或嵌入式收银台之外自行实现 Google Pay 请求，需要另行约定 Clink 接入方式，并具有受支持的 token 提交接口。此时需要加载 Google Pay JavaScript 客户端，通过 Business Console 获取自己的生产 Google Merchant ID，并完成 Google 对该集成的生产审核。仅使用前面的配置示例不能开通这种接入路径。上线前，确认适用的 Clink 网关已开通、卡组织及结算国家已批准、两种凭证流程可用、PAN_ONLY 能按风险触发 3DS、账单地址要求明确，以及服务端能确认支付结果。同时完成 Clink 上线检查和 Google 的集成检查清单。

开始使用

接入

配置与上线

介绍

财务信息

接入前准备

选择接入方式

Hosted Checkout

Elements

网关与商户标识

卡凭证与 3DS

卡组织与账单地址

提交交易

1. 在服务端创建 Checkout Session

2. 渲染支付界面

3. 处理加密数据与支付结果

Google 资源与生产检查

​接入前准备

​选择接入方式

​Hosted Checkout

​Elements

​网关与商户标识

​卡凭证与 3DS

​卡组织与账单地址

​提交交易

​1. 在服务端创建 Checkout Session

​2. 渲染支付界面

​3. 处理加密数据与支付结果

​Google 资源与生产检查

接入前准备

选择接入方式

Hosted Checkout

Elements

网关与商户标识

卡凭证与 3DS

卡组织与账单地址

提交交易

1. 在服务端创建 Checkout Session

2. 渲染支付界面

3. 处理加密数据与支付结果

Google 资源与生产检查