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

# 银行卡支付概览

> 了解 HaiPay 银行卡（支持信用卡与借记卡：VISA / MasterCard / JCB / AMEX / Diners / Discover）及移动钱包（Apple Pay、Google Pay）的支付能力、交易模式、限额编码与快速接入路径。

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

HaiPay 银行卡支付解决方案同时支持**信用卡（Credit Card）与借记卡（Debit Card）**，涵盖全球主流卡组织（**VISA、MasterCard、JCB、American Express、Diners Club、Discover**）以及主流移动钱包（**Apple Pay、Google Pay**），目前已覆盖全球 [62 个国家和地区](https://doc.haipay.net/zh/payments/supported-regions.md)，支持单次代收（CIT）、商户发起代扣（MIT）与固定周期订阅三种业务模式。

> [card] [1. 选择收银台集成方式](https://doc.haipay.net/zh/payments/integration-modes.md)
>
> 对比 **收银台模式（Checkout Mode）** 与 **前置组件模式（Component Mode）**，确定前端呈现方案。

> [card] [2. 选择交易模式](https://doc.haipay.net/zh/payments/cit-mit.md)
>
> 区分 **单次 CIT 代收**、**MIT 按需代扣** 与 **固定套餐订阅**，匹配您的计费模型。

> [card] [3. 联调与测试卡号](https://doc.haipay.net/zh/payments/test-cards.md)
>
> 使用沙盒测试卡号模拟支付成功、发卡行拒付及争议场景。

## 交易模式与能力矩阵

根据您的业务是「单次买断」、「首次绑卡后按需/按量扣款」还是「固定周期会员续费」，选择对应的接口：

| 交易模式 | 发起方与会话状态 | 服务端核心接口 | 前端集成方式 | 典型场景 |
| :- | :- | :- | :- | :- |
| **常规单次代收（CIT）** | 持卡人在场主动支付（On-Session） | [`POST /usd/collect/apply`](https://doc.haipay.net/zh/api-reference/card/collect-apply) | [收银台模式](https://doc.haipay.net/zh/payments/payment-link.md) 或 [前置组件模式（`mode: 'payment'`）](https://doc.haipay.net/zh/payments/frontend-payment-element) | 电商零售、单次购买、手动充值 |
| **MIT 商户发起交易** | 首笔用户在场授权（CIT），后续商户后台静默扣款（Off-Session） | [`POST /usd/mit/apply`](https://doc.haipay.net/zh/api-reference/card/mit-apply) （详见 [MIT 支付指南](https://doc.haipay.net/zh/payments/card-mit.md)） | 首笔支持收银台模式或前置组件模式（**`mode: 'payment'`**）；后续由服务端传 `tokenID` 发起 | 按量计费、自动续充、自定义周期扣款 |
| **固定周期订阅** | 首笔用户在场授权，后续由 HaiPay 按周期自动调度扣款 | [`POST /subscription/apply`](https://doc.haipay.net/zh/api-reference/subscription/subscription-apply) （详见 [订阅支付指南](https://doc.haipay.net/zh/payments/subscription.md)） | [收银台模式](https://doc.haipay.net/zh/payments/payment-link.md) 或 [前置组件模式（**`mode: 'subscription'`**）](https://doc.haipay.net/zh/payments/frontend-payment-element) | 月度/年度 VIP 会员、SaaS 标准套餐 |

## 收银台集成方式速览

HaiPay 将「支付方式」与「收银台集成方式」完全解耦，所有下单申请接口均同时返回 `payUrl` 与 `clientToken`：

* **[收银台模式（Checkout Mode）](https://doc.haipay.net/zh/payments/payment-link.md)**：使用响应中的 `payUrl` 将用户重定向至 HaiPay 托管页面完成付款，前端几乎零开发量，适合快速验证与上线。
* **[前置组件模式（Component Mode）](https://doc.haipay.net/zh/payments/frontend-payment-element.md)**：使用响应中的 `clientToken` 将组合组件嵌入商户自有页面，用户无需跳转即可完成银行卡、Apple Pay 或 Google Pay 付款。

完整的架构图示、开发量、UI 定制度、PCI DSS 范围对比及代码示例，请查阅 [**收银台集成方式对比**](https://doc.haipay.net/zh/payments/integration-modes.md)。

## 支付方式、编码与限额

银行卡（含信用卡与借记卡）及移动钱包交易默认以 **USD（美元）** 计价结算（需使用美元对应的 `appId`），单笔代收限额统一为 **0.99 – 1000 USD**：

| 币种 | 支付类型 (`payType`) | 支付编码 (`inBankCode`) | 单笔限额 (USD) | 状态 | 支持卡组织 / 钱包说明 |
| :- | :- | :- | :- | :- | :- |
| USD | `BANK_TRANSFER` | `CREDIT_CARD` | 0.99 - 1000 | 可用 | VISA |
| USD | `BANK_TRANSFER` | `CREDIT_CARD` | 0.99 - 1000 | 可用 | MasterCard |
| USD | `BANK_TRANSFER` | `CREDIT_CARD` | 0.99 - 1000 | 可用 | JCB |
| USD | `BANK_TRANSFER` | `CREDIT_CARD` | 0.99 - 1000 | 可用 | American Express (AMEX) |
| USD | `BANK_TRANSFER` | `CREDIT_CARD` | 0.99 - 1000 | 可用 | Diners Club (DINERS) |
| USD | `BANK_TRANSFER` | `CREDIT_CARD` | 0.99 - 1000 | 可用 | Discover (DISCOVER) |
| USD | `EWALLET` | `GOOGLE_PAY` | 0.99 - 1000 | 可用 | Google Pay |
| USD | `EWALLET` | `APPLE_PAY` | 0.99 - 1000 | 可用 | Apple Pay |

> [!NOTE]
>
> **`inBankCode` 与 `paymentMethods` 互斥二选一规则**：
>
> * 当指定单一支付方式时，传递 `inBankCode`（此时 `paymentMethods` 不填）。
> * 当需要动态控制展示的支付方式组合及**由上至下的展示顺序**时，传递 `paymentMethods`（英文逗号分隔，例如 `"GOOGLE_PAY,CREDIT_CARD"` 将仅展示这两项且按此顺序自上而下排列；此时 `inBankCode` 不填）。
> * 该动态排序与展示能力同样支持映射至 [全球收银台](https://doc.haipay.net/zh/payments/global-cashier.md)。

## 核心 API 与调试入口

完整的请求参数、签名说明、响应示例及在线调试（API Playground），请直接进入 API Reference：

> [card] [银行卡代收申请](https://doc.haipay.net/zh/api-reference/card/collect-apply.md)
>
> `POST /usd/collect/apply` — 创建单次 CIT 代收订单，支持信用卡、借记卡、Apple Pay 与 Google Pay。

> [card] [MIT 代收申请](https://doc.haipay.net/zh/api-reference/card/mit-apply.md)
>
> `POST /usd/mit/apply` — 首次绑卡授权扣款（不传 `tokenID`）或后续商户主动代扣（传 `tokenID`）。

> [card] [代收订单查询](https://doc.haipay.net/zh/api-reference/card/collect-query.md)
>
> `POST /usd/collect/query` — 查询单次代收或 MIT 代收订单的最终支付状态与手续费明细。

> [card] [退款申请与查询](https://doc.haipay.net/zh/api-reference/card/refund-apply.md)
>
> `POST /usd/refund/apply` 及 [退款查询 `/usd/refund/refundQuery`](https://doc.haipay.net/zh/api-reference/card/refund-query) — 支持全额退款与指定 `refundAmount` 部分退款。

### 正确请求示例（代收申请 `/usd/collect/apply`）

> [tab] 方式一：指定单一支付方式（传 inBankCode）
>
> 当仅需拉起银行卡支付时，传入 `payType: "BANK_TRANSFER"` 与 `inBankCode: "CREDIT_CARD"`（此时 `paymentMethods` 不填）：
>
> ```json theme={null}
> {
>   "appId": 1054,
>   "orderId": "M233323000059",
>   "amount": "299.99",
>   "phone": "+12025551234",
>   "email": "robert.taylor@gmail.com",
>   "name": "Robert Taylor",
>   "payType": "BANK_TRANSFER",
>   "inBankCode": "CREDIT_CARD",
>   "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": "Order M233323000059",
>   "partnerUserId": "149597870",
>   "sign": "af0gAHkUOyYHu9owQp8NJ4mPEeUW4vuJcjdxqLIzrVw8AvpLSjD1DXupReSG..."
> }
> ```

> [tab] 方式二：动态控制展示方式与顺序（传 paymentMethods）
>
> 当需要同时展示多种支付方式并控制由上至下的排列顺序时，传入 `paymentMethods`（此时 `inBankCode` 不填）。例如以下请求将按顺序自上而下展示 Google Pay 与银行卡：
>
> ```json theme={null}
> {
>   "appId": 1054,
>   "orderId": "M233323000060",
>   "amount": "299.99",
>   "phone": "+12025551234",
>   "email": "robert.taylor@gmail.com",
>   "name": "Robert Taylor",
>   "payType": "BANK_TRANSFER",
>   "paymentMethods": "GOOGLE_PAY,CREDIT_CARD",
>   "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": "Order M233323000060",
>   "partnerUserId": "149597870",
>   "sign": "af0gAHkUOyYHu9owQp8NJ4mPEeUW4vuJcjdxqLIzrVw8AvpLSjD1DXupReSG..."
> }
> ```

## 合规、争议与安全要求

> [!TIP]
>
> * **争议有效期与处理费**：消费者有权在交易发生后 **180 天内**发起争议申请。每笔争议将产生 **20 美元**的争议处理费。
> * **应对方式**：收到争议通知后，您有两种选择：
>   * **接受争议**：向发卡银行确认不对退款金额提出异议。
>   * **抗辩（Rebuttal）**：根据引导流程提交证据与支持性文件阐述立场，将额外收取 **20 美元**抗辩费。若发卡银行判定消费者胜诉，抗辩费将被扣除且交易款项退还给消费者。
> * **费用退还政策**：若您赢得争议，HaiPay 将退还抗辩费；但除非合同另有约定，最初收取的争议处理费均不予退还。

> [!CAUTION]
>
> 1. **PCI 合规性**：直接违反 PCI DSS（支付卡行业数据安全标准）要求。
> 2. **安全隔离不足**：第三方 `WebView` 或外层 `iframe` 可能无法提供足够的安全隔离。
> 3. **中间人攻击风险**：宿主环境可能拦截或篡改持卡人敏感支付数据。
> 4. **钓鱼风险**：无法向用户证明当前处于受信任的持卡人数据采集环境。
>
> 请始终在标准受信任浏览器中使用 [收银台模式（Checkout Mode）](https://doc.haipay.net/zh/payments/payment-link.md) 或官方 [前置组件模式（Component Mode）](https://doc.haipay.net/zh/payments/frontend-payment-element.md) 完成卡信息采集与支付授权。

## 扩展阅读与专项板块

> [card] [Apple Pay 与 Google Pay](https://doc.haipay.net/zh/payments/apple-pay-google-pay.md)
>
> 查看移动钱包的设备、系统、浏览器环境要求（`#supported-browsers`）与配置要点。

> [card] [CIT 与 MIT 交易模式说明](https://doc.haipay.net/zh/payments/cit-mit.md)
>
> 深入理解首次在场授权（CIT）与后续商户离线扣款（MIT）的合规机制，以及与周期订阅的选型对比。

> [card] [MIT 支付与订阅支付](https://doc.haipay.net/zh/payments/card-mit.md)
>
> 接入 [MIT 支付（`/usd/mit/apply`）](https://doc.haipay.net/zh/payments/card-mit) 或 [固定周期订阅（`/subscription/apply`）](https://doc.haipay.net/zh/payments/subscription)。

> [card] [支持地区与测试卡号](https://doc.haipay.net/zh/payments/supported-regions.md)
>
> 查看 [支持的 62 个国家/地区](https://doc.haipay.net/zh/payments/supported-regions.md) 及 [沙盒测试卡号](https://doc.haipay.net/zh/payments/test-cards.md)。


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