> ## Documentation Index
> Fetch the complete documentation index at: https://docs.clinkbill.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Google Pay™

> 通过 Clink Hosted Checkout 或 Elements 接入 Google Pay，了解网关配置及 PAN_ONLY 的认证要求。

Google Pay™ 让客户使用保存在 Google 账号或设备中的卡付款。你可以通过 Clink [Hosted Checkout](/cn/build-integration) 或 [Elements](/cn/elements) 接收这类支付。

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

## 接入前准备

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

<Note>
  使用 Hosted Checkout 或 Elements 的所有商户，都必须遵守 [Google Pay and Wallet API Acceptable Use Policy](https://payments.developers.google.com/terms/aup)，并接受 [Google Pay API Terms of Service](https://payments.developers.google.com/terms/sellertos)。
</Note>

## 选择接入方式

| 方式 | 商户需要实现 | 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 安装与挂载说明](/cn/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 合并到现有策略中。例如，沙盒的指令可以包含：

```text theme={null}
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 布局要求](/cn/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 调用：

```json theme={null}
{
  "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 额外认证说明](https://developers.googleblog.com/en/when-to-step-up-your-google-pay-transactions-as-a-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`](https://developers.google.com/pay/api/web/reference/request-objects#BillingAddressParameters)，设置所需地址格式及是否需要电话号码。

## 提交交易

### 1. 在服务端创建 Checkout Session

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

```bash theme={null}
# 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](/cn/integration)及 [Create checkout session](/api-reference/endpoint/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 初始化：

```javascript theme={null}
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 按钮可用状态](/cn/elements#获取-sdk-按钮可用状态)。

SDK 渲染 Google 官方按钮并接管点击。不要再绘制一套 Google Pay 按钮，也不要对该按钮调用 `clink.submit()`。完整前端及事件处理见 [Elements](/cn/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](/cn/integration#webhook)或服务端 [Order 查询](/api-reference/endpoint/get-order)确认最终支付结果。`pending`、失败和额外认证都按所选接入方式的标准状态流程处理。

## Google 资源与生产检查

使用官方 Google Pay Logo 和按钮素材，不修改颜色、比例或外观。在网站中展示 Google Pay 或设置收银台样式时，遵守 [Web 品牌规范](https://developers.google.com/pay/api/web/guides/brand-guidelines)。

Elements 的按钮主题、类型、高度和圆角，通过 `presetOptions.sdkButtons.googlePay` 配置。允许的取值范围见 [Elements 按钮样式](/cn/elements#配置-sdk-按钮样式)。不要用自定义 CSS 覆盖 SDK 渲染的按钮。

* [Google Pay Web 开发文档](https://developers.google.com/pay/api/web/)
* [Web 集成检查清单](https://developers.google.com/pay/api/web/guides/test-and-deploy/integration-checklist)
* [Web 生产权限申请](https://developers.google.com/pay/api/web/guides/test-and-deploy/request-prod-access)
* [Google Pay & Wallet Business Console](https://pay.google.com/business/console)

如果在 Clink 托管或嵌入式收银台之外自行实现 Google Pay 请求，需要另行约定 Clink 接入方式，并具有受支持的 token 提交接口。此时需要加载 [Google Pay JavaScript 客户端](https://developers.google.com/pay/api/web/guides/tutorial#js-load)，通过 Business Console 获取自己的生产 Google Merchant ID，并完成 Google 对该集成的生产审核。仅使用前面的配置示例不能开通这种接入路径。

上线前，确认适用的 Clink 网关已开通、卡组织及结算国家已批准、两种凭证流程可用、`PAN_ONLY` 能按风险触发 3DS、账单地址要求明确，以及服务端能确认支付结果。同时完成 [Clink 上线检查](/cn/go-live)和 Google 的集成检查清单。


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.