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

# Apple Pay 与 Google Pay

> 了解 HaiPay Apple Pay 与 Google Pay 移动钱包支付集成方案，包括设备与浏览器要求、支持地区、编码限额与接入方式。

> [!WARNING]
>
> 阅读本文档前，请务必先查看 [**接口说明与公共规则**](https://doc.haipay.net/zh/guide/api-conventions.md)。

> [!TIP]
>
> Apple Pay 与 Google Pay 均支持通过 [**收银台模式（`payUrl` 跳转）**](https://doc.haipay.net/zh/payments/payment-link) 或 [**前置组件模式（`clientToken` 嵌入）**](https://doc.haipay.net/zh/payments/frontend-payment-element) 接入，并涵盖单次代收（CIT）、[MIT 代扣](https://doc.haipay.net/zh/payments/card-mit.md) 与 [固定周期订阅](https://doc.haipay.net/zh/payments/subscription.md)。

## 设备与浏览器环境要求

如果您在支付页面或前置组件中看不到 Apple Pay 或 Google Pay 按钮，请按下方对应钱包的检查清单核实设备、系统与浏览器设置：

> [tab] Apple Pay 环境要求
>
> **设备与钱包检查清单**
>
> * 系统的 Apple 钱包（Wallet）中**至少已绑定一张支持的银行卡**。
> * 必须使用兼容的 [Apple Pay 设备](https://support.apple.com/zh-cn/102896)，且设备支持[生物识别身份验证（Face ID / Touch ID）](https://support.apple.com/zh-cn/102626)。
> * 必须使用 **HTTPS** 协议及下方支持的 Safari 浏览器访问。
> * 允许 Safari 检查 Apple Pay：**设置** > **高级** > **允许网站检查 Apple Pay 和 Apple 卡**。
> * **请勿使用** Safari 私人浏览窗口（无痕模式）。
> * 确认当前设备地区位于 [支持的国家和地区列表](https://doc.haipay.net/zh/payments/supported-regions.md) 内。
>
> **支持的浏览器**
>
> * **桌面端**：macOS Safari 10.1+
> * **移动端**：iOS Safari 9+，以及其他使用系统提供的 WebKit 引擎的浏览器和受信任视图

> [tab] Google Pay 环境要求
>
> **设备与钱包检查清单**
>
> * Google 账号的 Google Pay 钱包中**至少已保存一张支持的付款卡**。
> * 必须使用兼容的 [Google Pay 设备](https://developers.google.com/pay/issuers/overview/supported-devices#compatibility_requirements)。
> * 必须使用 **HTTPS** 协议及下方支持的现代浏览器访问。
> * 允许 Chrome 检查已保存付款方式：**设置** > **自动填充和密码** > **付款方式** > **允许网站检查您是否已保存付款方式**。
> * **请勿使用** Chrome 隐身窗口。
> * 确认当前账号与设备地区位于 [支持的国家和地区列表](https://doc.haipay.net/zh/payments/supported-regions.md) 内。
>
> **支持的浏览器**
>
> * **桌面端**：Chrome 38+、Safari 10.1+、Edge 15+、Firefox 29+、Opera 25+
> * **移动端**：Android Chrome 38+、iOS Safari 9+、三星浏览器（Samsung Internet）7.1+

> [!NOTE]
>
> **通用技术要求**：对于未明确列出的现代浏览器，需支持 **TLS 1.2+** 及原生 JavaScript **Promises**。

## 地区可用性

Apple Pay 与 Google Pay 仅在受支持的 62 个国家和地区可用。接入前请查阅 [**支持与不支持地区列表**](https://doc.haipay.net/zh/payments/supported-regions.md) 确认您的目标市场是否支持。

## 支付编码、限额与特殊规则

| 币种 | 支付类型 (`payType`) | 支付编码 (`inBankCode`) | 单笔限额 (USD) | 状态 | 适用说明 |
| :- | :- | :- | :- | :- | :- |
| USD | `EWALLET` | `APPLE_PAY` | 0.99 - 1000 | 可用 | Apple Pay |
| USD | `EWALLET` | `GOOGLE_PAY` | 0.99 - 1000 | 可用 | Google Pay |

> [!WARNING]
>
> 1. **`inBankCode` 与 `paymentMethods` 互斥二选一**：
>    * 若仅拉起单个钱包，传 `payType: "EWALLET"` 与 `inBankCode: "APPLE_PAY"`（或 `"GOOGLE_PAY"`），此时 `paymentMethods` 不填。
>    * 若需与信用卡同时展示并控制由上至下的展示顺序，传 `paymentMethods`（如 `"GOOGLE_PAY,APPLE_PAY,CREDIT_CARD"`），此时 `inBankCode` 不填。
> 2. **Apple Pay 订阅周期限制**：在 [订阅支付（`/subscription/apply`）](https://doc.haipay.net/zh/payments/subscription) 中，**Apple Pay 不支持周维度周期编码 `W`**；如需实现按周扣款订阅，请改用天维度 **`recurringInterval: "D"` + `recurringIntervalCount: 7`**。

## 核心 API 与请求示例

移动钱包与信用卡共用同一套代收、MIT、订阅与退款接口，仅通过 `payType` / `inBankCode`（或 `paymentMethods`）区分：

> [card] [代收申请 (/usd/collect/apply)](https://doc.haipay.net/zh/api-reference/card/collect-apply.md)
>
> 创建 Apple Pay / Google Pay 单次代收订单，返回 `payUrl` 与 `clientToken`。

> [card] [MIT 代收申请 (/usd/mit/apply)](https://doc.haipay.net/zh/api-reference/card/mit-apply.md)
>
> 通过 Apple Pay / Google Pay 完成首次授权扣款并在后续发起 MIT 代扣。

> [card] [订阅申请 (/subscription/apply)](https://doc.haipay.net/zh/api-reference/subscription/subscription-apply.md)
>
> 创建固定套餐期限的周期订阅订单。

> [card] [订单查询与退款](https://doc.haipay.net/zh/api-reference/card/collect-query.md)
>
> 查询订单终态（`/usd/collect/query`）或发起[全额/部分退款（`/usd/refund/apply`）](https://doc.haipay.net/zh/api-reference/card/refund-apply)。

### 请求示例（`/usd/collect/apply`）

> [tab] Apple Pay 单一方式请求
>
> ```json theme={null}
> {
>   "appId": 1054,
>   "orderId": "M233323000061",
>   "amount": "299.99",
>   "phone": "+12025551234",
>   "email": "robert.taylor@gmail.com",
>   "name": "Robert Taylor",
>   "payType": "EWALLET",
>   "inBankCode": "APPLE_PAY",
>   "callBackUrl": "https://merchant.com/payment/success",
>   "callBackFailUrl": "https://merchant.com/payment/fail",
>   "cancelUrl": "https://merchant.com/payment/cancel",
>   "notifyUrl": "https://merchant.com/api/notify",
>   "subject": "Apple Pay Order",
>   "partnerUserId": "149597870",
>   "sign": "af0gAHkUOyYHu9owQp8NJ4mPEeUW4vuJcjdxqLIzrVw8AvpLSjD1DXupReSG..."
> }
> ```

> [tab] Google Pay 单一方式请求
>
> ```json theme={null}
> {
>   "appId": 1054,
>   "orderId": "M233323000062",
>   "amount": "299.99",
>   "phone": "+12025551234",
>   "email": "robert.taylor@gmail.com",
>   "name": "Robert Taylor",
>   "payType": "EWALLET",
>   "inBankCode": "GOOGLE_PAY",
>   "callBackUrl": "https://merchant.com/payment/success",
>   "callBackFailUrl": "https://merchant.com/payment/fail",
>   "cancelUrl": "https://merchant.com/payment/cancel",
>   "notifyUrl": "https://merchant.com/api/notify",
>   "subject": "Google Pay Order",
>   "partnerUserId": "149597870",
>   "sign": "af0gAHkUOyYHu9owQp8NJ4mPEeUW4vuJcjdxqLIzrVw8AvpLSjD1DXupReSG..."
> }
> ```

## 相关主题

* [银行卡支付概览](https://doc.haipay.net/zh/payments/card.md)
* [集成方式概览（Checkout Mode vs. Component Mode）](https://doc.haipay.net/zh/payments/integration-modes.md)
* [支持与不支持地区列表](https://doc.haipay.net/zh/payments/supported-regions.md)
* [CIT 与 MIT 交易模式](https://doc.haipay.net/zh/payments/cit-mit.md)


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