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

# 前端组件 - Google Pay 集成

> 在商户页面集成 Google Pay 支付的完整指南。

## 概览

Google Pay 允许用户使用其 Google 账户中保存的信用卡或借记卡快速完成支付，从而简化结账流程并提升转化率。

## 支付流程

**1. 用户点击 Google Pay 按钮**

用户在商户页面点击 Google Pay 按钮。

**2. 发起 Google Pay 请求**

商户通过 Google Pay Web API / Android SDK 发起请求。

**3. 用户选择支付方式**

用户选择支付方式，Google 返回加密的 token。

**4. 提交 token**

商户将 token 提交至商户后端。

**5. 调用 Waffo API**

商户携带 token 调用 Waffo `/api/v1/order/create`。

**6. 处理结果**

Waffo 处理支付并返回结果，商户通知用户。

## 前置条件

* 已完成 Waffo 账户开通与配置
* 从 Waffo TAM 获取 `gatewayMerchantId`（沙箱环境使用 `"googletest"`）

## 第 1 步：Google 前端集成

### Web 集成

参考 [Google Pay Web 文档](https://developers.google.com/pay/api/web/guides/setup) 并配置 `tokenizationSpecification`：

```javascript theme={null}
const tokenizationSpecification = {
  type: 'PAYMENT_GATEWAY',
  parameters: {
    gateway: 'waffo',
    gatewayMerchantId: 'googletest',
  }
};
```

### Android 集成

参考 [Google Pay Android 文档](https://developers.google.com/pay/api/android/guides/setup)。

### 说明

* 支持的支付类型：`CARD`
* 支持的卡组织：`VISA`, `MASTERCARD`, `AMEX`, `DISCOVER`
* 认证方式：`PAN_ONLY`
* 必填字段：`name`, `address`, `phone`, `email`

## 第 2 步：Waffo 后端集成

将 Google Pay 返回的 token 通过 `/api/v1/order/create` 发送至 Waffo：

```json theme={null}
{
  "paymentRequestId": "gp_a1b2c3d4e5f6a1b2c3d4e5f6",
  "merchantOrderId": "ORDER_20260325001",
  "orderAmount": "100.00",
  "orderCurrency": "HKD",
  "notifyUrl": "https://your-site.com/webhook/waffo",
  "merchantInfo": { "merchantId": "M000001" },
  "paymentInfo": {
    "productName": "ONE_TIME_PAYMENT",
    "payMethodName": "GOOGLEPAY",
    "payMethodType": "CARD"
  },
  "userInfo": {
    "userId": "user_123",
    "userFirstName": "John"
  },
  "paymentTokenData": "{ Google Pay returned encrypted token JSON }"
}
```

> [!NOTE]
>
> `paymentTokenData` 必须是一个 JSON 对象，而不是字符串。

## Web SDK 集成

通过 Waffo Web SDK 的 `createPayment()` 方法集成 Google Pay：

```javascript theme={null}
sfc.createPayment({
  sessionToken: '<sessiontoken>',
  merchantId: '<your merchantId>',
  merchantSiteId: '<your merchantSiteId>',
  paymentOption: {
    card: {
      externalToken: {
        externalTokenProvider: 'GooglePay',
        mobileToken: '<encrypted Token using Waffo open key>'
      }
    }
  },
  billingAddress: {
    email: 'user@example.com',
    county: 'HK'
  }
}, function(res) {
  console.log(res);
});
```

### 3DS 流程控制

使用 `googlePay3Dflow` 参数控制 3D Secure 认证：

* `enable`（默认）：开启 3DS 认证
* `disable`：跳过 3DS（需先联系 Waffo 进行配置）

```javascript theme={null}
sfc.createPayment({
  // ...
  googlePay3Dflow: 'enable',
});
```

## 上线检查清单

1. 申请 [Google 生产环境权限](https://services.google.com/fb/forms/googlepayAPIenable)
2. 更新生产环境的 Google 集成配置
3. 将 `gatewayMerchantId` 替换为 Waffo TAM 提供的生产值
4. 联系 Waffo TAM 确认配置无误

## 结账页内置 Google Pay

如果你不需要自定义集成，可以联系 Waffo 在结账页中启用 Google Pay：

1. 提供将处理 Google Pay 的网站域名
2. 提供需要启用的商户 ID
3. 配置完成后，结账页将自动显示 Google Pay 按钮

> [!NOTE]
>
> 在内置结账模式下，3DS 交易必须符合 SCA 要求。如适用，请联系 Waffo 启用 3DS。


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