> ## 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.

# Apple Pay 与 Google Pay 的接入方式

> 解答商户接入 Apple Pay 和 Google Pay 时最常见的问题：四种 Apple Pay 接入方式怎么选、iframe 与域名注册、直连时的解密与提交、Google Pay 的接入、上线与 3DS，以及可用国家怎么确认。

本页回答商户在接入 Apple Pay 和 Google Pay 时最常问的问题：有哪几种接法、我自己能不能接、需要提前准备什么、怎么上线、覆盖哪些国家。完整的步骤和字段以官网对应页面为准，本页给出选择依据和关键结论。

## Apple Pay 有几种接入方式，我该选哪种？

共四种。官网的建议是：除非产品体验或合规边界要求由商户自己处理 Apple Pay token，否则一律用 Waffo 托管收银台，不需要申请 Apple 开发者账号、管理 Apple Pay 证书或自己解密 token。

| 方式 | 适合场景 | 支持的终端 | 你要做的事 | 额外前提 |
| - | - | - | - | - |
| 跳转到 Waffo 收银台 | 能打开独立支付页，成本最低 | 桌面网页、手机网页、能打开外部浏览器或顶层支付页的 iOS App | 创建订单，把用户跳转到 `orderAction.webUrl` | 无 |
| 在 App WebView 里加载 Waffo 收银台 | 要把用户留在 App 内 | 原生或混合开发的 iOS App | 加 WebView 和外部跳转处理；下单时传 `userTerminal=APP`；传递 URL 时保留完整 query string | 无 |
| 在 iframe 里加载 Waffo Apple Pay 收银台 | 要把用户留在当前网页或 H5 页 | 桌面网页、手机网页 | 使用 Waffo 前端 SDK `@waffo/payment-sdk` 渲染 iframe，并满足 iframe 要求 | **提前联系技术支持完成域名验证和注册** |
| 商户直连 Apple Pay | 必须完全控制 Apple Pay 界面和 token | 支持 Apple Pay JS 的网页，或使用 PassKit 的 iOS App | 自建前端、管理证书、在服务端验签并解密 token，再按 Waffo 的格式提交 | 有 Apple 开发者账号、Merchant ID、证书和所需的 PCI DSS 合规状态 |

说明：

* 前三种由 Waffo 处理 Apple Pay token。第四种由你的服务端解密。
* Android 终端不适用 Apple Pay。Android App 可以复用 WebView 加载收银台的做法来支持其他支付方式。
* 不论哪种方式，支付结果都以 Webhook 或订单查询接口为准，不要只看用户跳转回来的页面。

## 能不能把收银台链接直接放进普通 iframe 来用 Apple Pay？

不能。iframe 方式**必须**使用 Waffo 前端 SDK，并在集成**之前**联系技术支持完成 Apple Pay 的域名验证和注册。不要把 `orderAction.webUrl` 放进普通 `<iframe>`。域名验证和注册完成之前就上线 iframe Apple Pay，Apple Pay 按钮可能不显示，或者授权无法继续。

Portal 里没有域名页面，域名注册只能通过技术支持处理。如果你更换了收银台所在域名，需要提前提出，不要等切换之后，详见[商户 Portal 里哪些设置我可以自己改？](https://waffo.com/docs/zh/support/self-service-boundaries-faq.md)。iframe 本身的要求（`allow="payment"`、Referrer Policy、CSP、响应式宽度）见[接入方式怎么选，以及把收银台嵌进我的页面](https://waffo.com/docs/zh/support/checkout-integration-mode-and-embedding-faq.md)。

## Apple Pay 商户直连：我要传什么？需要自己解密吗？

需要。目前直连方式**只支持你在服务端解密后，把解密结果传给 Waffo**。你要自己负责：

* Apple 开发者账号和 Merchant ID；
* Payment Processing Certificate 及其私钥；
* Apple Pay on the Web 的域名验证；
* Apple Pay JS 或 PassKit 的前端集成；
* token 的验签、解密、防重放，以及敏感数据的合规。

开始之前请先联系技术支持，确认商户和支付方式的配置。

**服务端的处理顺序：**

1. 选用与 Payment Processing Certificate 对应的私钥；
2. 按 Apple 的规范验证 token 签名和证书链；
3. 按 token 的 `version` 解密 `token.paymentData.data`，把结果按 UTF-8 解析成 JSON；
4. 确认该 `transactionId` 没有被处理过，并核对解密出的币种、金额与订单一致；
5. 把解密后的 JSON 放进 `token.decryptedPaymentData`，再提交给 Waffo。

**提交给 Waffo 时：**

* 内容放在 `/api/v1/order/create` 的 `paymentTokenData` 字段里。该字段在接口里是 **`String`**，需要把整个对象序列化成 JSON 字符串后再提交，不是 JSON 对象。
* 只传解密后的内容不够：它不含卡组织，`billingContact`（持卡人姓名和账单地址的唯一来源）也在加密数据之外。所以要**保留 Apple Pay 返回的外层结构**，在 `token` 里增加 `decryptedPaymentData`。你也可以同时保留 `token.paymentData`，但不能只传它。
* Waffo 检测到 `token.decryptedPaymentData` 时，优先使用解密后的 token，不再做平台解密。

| 字段 | 要求 | 说明 |
| - | - | - |
| `token.decryptedPaymentData.applicationPrimaryAccountNumber` | 必填 | 设备账号（DPAN） |
| `token.decryptedPaymentData.applicationExpirationDate` | 必填 | 六位 `YYMMDD` |
| `token.paymentMethod.network` | 必填 | 卡组织，从原始 token 的外层结构原样复制 |
| `billingContact` | 建议 | 持卡人姓名和账单地址来源；Apple Pay 返回时请整体传入 |
| `token.decryptedPaymentData.paymentData.onlinePaymentCryptogram` | 可选 | 3DS 支付密文；有就原样传 |
| `token.decryptedPaymentData` 里的其他字段 | 可选 | 例如 `paymentDataType`、`deviceManufacturerIdentifier`、`eciIndicator`、`merchantTokenIdentifier`，有就原样传 |

字段的完整结构和示例见官网[直连 Apple Pay](https://waffo.com/docs/zh/developer-docs/integration/apple-pay/merchant-direct-integration.md)。直连时下单请求还需要按[按支付方式划分的条件必填字段](https://waffo.com/docs/zh/support/conditional-required-fields-faq.md)提供 `userBrowserIp`、`userAgent` 等信息。

## Google Pay 有几种接入方式？

| 方式 | 说明 |
| - | - |
| Waffo 收银台内置 | 不需要自己做前端。联系技术支持，提供**你用来收款的网站域名**和**要启用的商户 ID**；配置完成后，符合条件的用户在 Waffo 收银台上会看到 Google Pay 按钮 |
| 商户自己集成 Google Pay，把 token 交给 Waffo | 你按 Google 的文档（Web 或 Android）在自己的页面或 App 里集成 Google Pay，拿到加密 token 后，通过下单接口提交给 Waffo |

### 商户自己集成时，要怎么配置和提交？

* 在 Google 的 `tokenizationSpecification` 里，`type` 为 `PAYMENT_GATEWAY`，`gateway` 填 `waffo`，`gatewayMerchantId` 沙箱填 `googletest`，生产环境的值向 Waffo 的技术客户经理（TAM）获取。
* 支持的支付类型是 `CARD`；卡组织为 `VISA`、`MASTERCARD`、`AMEX`、`DISCOVER`；认证方式为 `PAN_ONLY`。
* 需要收集的信息：姓名、地址、电话、邮箱。
* 调用 `/api/v1/order/create`，`paymentInfo.payMethodName` 为 `GOOGLEPAY`，`payMethodType` 为 `CARD`，并在 `paymentTokenData` 里放 Google Pay 返回的加密 token。官网特别强调：**`paymentTokenData` 要按 JSON 字符串提交**。
* 支持订阅（循环扣款）的前提：你必须遵守卡组织规则，特别是商户发起交易（MIT）的规则；并在你的购买流程里披露「付款条款」，且让客户接受。
* 如果使用 Waffo Web SDK 的非 3DS 流程，需要先联系技术支持为你的账户配置。

### Google Pay 怎么上线？

官网的上线清单：

1. 向 Google 申请生产访问权限（Google Production Access）；
2. 把 Google 集成配置更新为生产环境；
3. 把 `gatewayMerchantId` 换成技术客户经理提供的生产值；
4. 联系技术客户经理确认配置无误。

使用 Waffo 收银台内置模式时，如果 3DS 适用于你的市场，Google Pay 交易需要符合强客户认证（SCA）要求，请联系 Waffo 为你的商户开启 3DS。

### Google Pay 的 3DS 怎么控制？

用 Waffo Web SDK 的 `createPayment()` 集成时，通过 `googlePay3Dflow` 参数控制：`enable`（默认）启用 3DS；`disable` 跳过 3DS，需要先联系 Waffo 完成配置。

## Apple Pay 和 Google Pay 在哪些国家能用？

Apple Pay 和 Google Pay 在目录里是**各自独立**的条目（`APPLEPAY`、`GOOGLEPAY`），每个市场有自己的条目，需要各自开通，卡已经上线不代表它们上线。可用国家请以你账户的 Portal → **Service → Payin** 目录里这两行为准，也可以用支付方式配置查询接口（`/api/v1/paymethodconfig/inquiry`）确认。目录里没有，就是你的账户上尚未启用，请联系客户经理。国家清单会变化，本页不列。

## 相关入口

* 官网 Apple Pay 接入：[https://waffo.com/docs/zh/developer-docs/integration/apple-pay/overview.md](https://waffo.com/docs/zh/developer-docs/integration/apple-pay/overview.md)
* 官网直连 Apple Pay：[https://waffo.com/docs/zh/developer-docs/integration/apple-pay/merchant-direct-integration.md](https://waffo.com/docs/zh/developer-docs/integration/apple-pay/merchant-direct-integration.md)
* 官网 Google Pay：[https://waffo.com/docs/en/developer-docs/integration/google-pay/google-pay.md](https://waffo.com/docs/en/developer-docs/integration/google-pay/google-pay.md)
* 官网前端组件 - Google Pay 集成：[https://waffo.com/docs/zh/developer-docs/integration/elements/frontend-integration.md](https://waffo.com/docs/zh/developer-docs/integration/elements/frontend-integration.md)
* 官网支付方式集成注意事项：[https://waffo.com/docs/zh/developer-docs/tools-and-references/references/payment-method-integration-notes.md](https://waffo.com/docs/zh/developer-docs/tools-and-references/references/payment-method-integration-notes.md)
* [我可以接受哪些支付方式和市场？](https://waffo.com/docs/zh/support/payment-method-coverage-faq.md)


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