> ## 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 订阅支付的接入方式、关键业务规则、上线要求和核心 API 入口，帮助你更快完成信用卡订阅集成。 HaiPay 订阅支付适用于会员、周期性服务和自动续费场景。这个页面不再堆叠完整参数大表，而是先帮助你理解接入模式、业务约束和实施顺序，再跳转到对应的 API Reference 查看详细字段与调试能力。先看接入步骤、必备能力和推荐阅读路径。对比 Apple Pay / Google Pay、信用卡组件和组合模式。直接进入订阅申请、查询、取消和退款接口。 * 提供明确的订阅入口、扣款周期说明和退订入口。 * 在订阅成功以及每次扣款前后，通过邮件或其他站外方式通知用户。 * 提供可确认的订阅协议，并在用户明确授权后再发起订阅。 * 保持客服可用，至少覆盖主要运营地区的服务时间。 * 信用卡交易在扣款后 180 天内，消费者可能发起争议。 * 每笔争议会产生 20 美元争议处理费。 * 如果选择抗辩，将额外产生 20 美元抗辩费。 * 抗辩成功时，HaiPay 会退还抗辩费；原始争议处理费默认不退。 PCI DSS 严格禁止在 `WebView` 或 `iframe` 中嵌入信用卡输入页。请始终在受信任的浏览器环境中完成卡信息采集与支付授权，避免合规风险和敏感数据泄露。 ## 快速开始先阅读 [接口说明](/docs/zh/guide/api_description_guide) 和 [订阅流程](/docs/zh/api/version2/subscription-process)，确认你的场景是自动续费而不是一次性支付。订阅支付提供两种接入模式：**PayUrl 跳转模式**（服务端获取授权链接，跳转到 HaiPay 托管页面完成支付）和 **JS CDN 嵌入模式**（使用客户端令牌在你自己的页面中嵌入支付组件）。根据你的收银台设计和前端开发能力选择合适的方式。完成订阅申请后，需要能查询订阅状态、处理扣款回调，并在用户侧提供取消订阅入口。详细字段与调试入口放在本页下方的 API Reference 卡片中。 ## 集成模式订阅支付提供两种接入模式，它们的核心区别在于支付页面由谁承载： | 对比项 | PayUrl 跳转模式 | JS 嵌入模式 | | :----- | :----------------- | :------------------- | | 支付页面 | 跳转到 HaiPay 托管的支付页面 | 在商户自己的页面中嵌入支付组件 | | 前端工作量 | 几乎为零，只需处理跳转 | 需要引入 JS 脚本并监听事件 | | UI 控制力 | 低，页面样式由 HaiPay 控制 | 高，可自定义主题、布局和交互 | | 关键返回字段 | 使用响应中的 `payUrl` | 使用响应中的 `clientToken` | | 适用场景 | 快速接入、对支付页面无定制需求 | 自建收银台、需要沉浸式支付体验 | 最简单的接入方式。商户服务端调用订阅申请接口后，使用返回的 `payUrl` 将用户跳转到 HaiPay 托管的支付页面，用户在该页面完成授权和首笔支付。 **接入流程** 商户服务端向 HaiPay 发起 [订阅申请](/docs/zh/V20260701/api-reference/subscription/api/subscriptionApply)，在请求中传入订阅金额、周期、回调地址以及可选的 `cancelUrl` 等必要参数。接口返回中包含 `payUrl` 字段，商户将用户浏览器重定向到该地址。用户在 HaiPay 托管页面完成信用卡信息填写和支付授权。支付完成后，HaiPay 会将用户重定向回商户的 `callBackUrl`；如果用户在支付页面取消支付且传递了 `cancelUrl`，则可点击返回到该地址；同时向 `notifyUrl` 发送异步通知。 **示例代码（服务端获取 payUrl 后的前端跳转）** ```javascript theme={null} // 假设你的服务端已调用订阅申请接口，并将 payUrl 返回给前端 const payUrl = response.data.payUrl; // 在当前窗口跳转 window.location.href = payUrl; // 或者在新窗口打开 // window.open(payUrl, '_blank'); ``` **适用建议** * 希望最快速度完成订阅接入，前端改动最少。 * 对支付页面的 UI 没有强定制需求。 * 移动端 H5 场景下，跳转体验通常也能满足需求。通过引入 HaiPay JS 脚本，将支付组件直接嵌入商户页面。商户服务端调用订阅申请接口获取 `clientToken`，前端使用该令牌初始化组件，用户无需跳转即可在当前页面完成订阅支付。 JS 提供以下组件形态，请根据收银台设计需求选择：与组合模式类似，但额外支持通过 `mode` 参数切换普通支付与订阅支付，适合需要统一管理多种支付场景的商户。 **引入脚本** `https://cashier.haipay.top/js/composite-component_1.0.0.min.js` **配置参数** | 参数 | 必填 | 说明 | | :-------------------- | :- | :--------------------------------------------------- | | `sandbox` | 是 | `true` 为测试环境，`false` 为生产环境 | | `clientToken` | 是 | 订阅申请接口返回的客户端令牌 | | `mode` | 是 | 支付场景：`payment`（普通支付）或 `subscription`（订阅支付） | | `showPayButton` | 否 | 是否显示信用卡提交按钮，默认 `false`（不显示） | | `themeMode` | 否 | 主题模式，可选 `light` / `dark`，默认 `light` | | `paymentMethodConfig` | 否 | 支付方式组合，默认 `["GOOGLE_PAY","APPLE_PAY","CREDIT_CARD"]` | | `applePayButtonType` | 否 | Apple Pay 按钮文案，可选 `buy`、`subscribe` 等 | | `googlePayButtonType` | 否 | Google Pay 按钮文案，可选 `buy`、`subscribe` 等 | | `cardPosition` | 否 | 信用卡放置位置，默认 `bottom`，可选：`bottom`、`top` | **事件回调** * `ready` — 组件渲染完成，可进行交互 * `error` — 初始化失败或支付过程出错 * `confirm` — 表单提交结果（成功/失败） * `paymentStatus` — 支付结果通知，失败会返回错误信息（若未监听，组件将自动处理支付结果展示） * `paymentMethodType` — 当前选中的支付方式 **适用建议** * 需要在同一套代码中同时支持普通支付和订阅支付时，推荐此模式。 * 如仅开放部分支付方式，只需传入所需的组合即可。 ```javascript theme={null}

const elements = haiPay.create({ mode: 'payment', sandbox: true, clientToken: 'your-client-token', themeMode: 'light', paymentMethodConfig: ['GOOGLE_PAY', 'APPLE_PAY', 'CREDIT_CARD'] }); elements.mount('#paymentId'); elements.on('ready', (event) => { console.log('rendered successfully:', event); }); elements.on('error', (event) => { console.error('Payment error:', event); }); elements.on('paymentMethodType', (event) => { console.log('payment method type', event); }); elements.submitCardPayment(); elements.on('confirm', (event) => { console.log('confirm:', event); }); elements.on('confirm', (event) => { console.log('confirm:', event); }); elements.on('paymentStatus', (event, message) => { console.log('payment status:', event, message); }); ``` 该组件即将废弃，推荐使用「自定义组合模式」替代。适合已具备钱包支付入口、希望快速拉起 Apple Pay / Google Pay 授权的场景。 **引入脚本** `https://cashier.haipay.top/js/applePayGooglePaySubscribe_1.0.0.min.js` **配置参数** | 参数 | 必填 | 说明 | | :------------- | :- | :---------------------------- | | `sandbox` | 是 | `true` 为测试环境，`false` 为生产环境 | | `clientToken` | 是 | 订阅申请接口返回的客户端令牌 | | `buttonType` | 否 | 按钮文案类型，可选 `buy`、`subscribe` 等 | | `buttonTheme` | 否 | 按钮主题色，可选 `black`、`white` | | `buttonHeight` | 否 | 按钮高度（px），默认 `50` | **事件回调** * `ready` — 按钮渲染完成，可进行交互 * `error` — 初始化失败或支付过程出错 * `paymentStatus` — 支付结果通知（若未监听，组件将自动处理支付结果展示） * `paymentMethodType` — 当前选中的支付方式 ```javascript theme={null}

const elements = applePayGooglePaySubscribe.create('applePayGooglePaySubscribe', { sandbox: true, clientToken: 'your-client-token', buttonType: 'subscribe', buttonTheme: 'black', buttonHeight: 50 }); elements.mount('#applePayGooglePayId'); elements.on('ready', (data) => { console.log('Button rendered successfully:', data); }); elements.on('error', (data) => { console.error('Payment error:', data); }); elements.on('paymentMethodType', (event) => { console.log('payment method type', event); }); elements.on('paymentStatus', (data) => { console.log('payment status:', data); }); ``` 该组件即将废弃，推荐使用「自定义组合模式」替代。适合需要直接展示信用卡订阅表单、并由商户自行控制提交时机的场景。 **引入脚本** `https://cashier.haipay.top/js/creditCardSubscription_1.0.0.min.js` **配置参数** | 参数 | 必填 | 说明 | | :------------ | :- | :------------------------- | | `sandbox` | 是 | `true` 为测试环境，`false` 为生产环境 | | `clientToken` | 是 | 订阅申请接口返回的客户端令牌 | | `cardTheme` | 否 | 表单主题色，默认 `white` | **事件回调** * `ready` — 信用卡表单渲染完成，可进行交互 * `confirm` — 表单提交结果（成功/失败） * `paymentStatus` — 支付结果通知（若未监听，组件将自动处理支付结果展示） ```javascript theme={null}