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

# 前置组件模式

> 前置组件——统一的支付 UI 解决方案，支持信用卡、Apple Pay、Google Pay、MIT 支付等方式。

HaiPay 前置组件是预先构建的支付 UI 解决方案，用于在商户网站上安全地接受付款。使用前置组件，敏感信息（卡号、CVV 等）由 HaiPay 组件收集托管，商户不需要自行申请 PCI DSS 认证资质。后续如需添加新的支付方式，仅需签约即可，不需要额外开发。

## 前置组件

商户可直接将**支付组件**嵌入自有页面。通过在服务端调用代收申请 API 获取 `clientToken`，前端使用该令牌初始化组件，用户无需跳转即可在当前页面完成支付。

在一个容器中同时展示 Google Pay、Apple Pay 和信用卡，支持通过 `mode` 参数在代收支付和MIT支付之间切换。适合需要统一管理多种支付场景的商户。

### 脚本

`https://cashier.haipay.top/js/composite-component_1.0.0.min.js`

### 参数

| 参数名 | 必选 | 说明 |
| :- | :- | :- |
| `sandbox` | 是 | `true` 为测试环境，`false` 为生产环境 |
| `clientToken` | 是 | 代收申请 API 返回的客户端令牌 |
| `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}
<script src="https://cashier.haipay.top/js/composite-component_1.0.0.min.js"></script>

<div>
  <div id="paymentId"></div>
</div>

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('渲染成功:', event);
});

elements.on('error', (event) => {
  console.error('支付错误:', event);
});

elements.on('paymentMethodType', (event) => {
  console.log('支付方式类型', event);
});

elements.submitCardPayment();

elements.on('confirm', (event) => {
  console.log('确认:', event);
});

elements.on('paymentStatus', (event, message) => {
  console.log('支付状态:', event, message);
});

```

### 常见错误

| 错误信息 | 错误原因 | 解决方案 |
| :- | :- | :- |
| Missing required parameters: env, orderNo | 缺少必要的初始化参数 | 检查 `clientToken` 等参数是否正确传入 |
| Unsupported region: CN | 生产环境不支持中国大陆地区 | 核实商户配置和目标市场 |

## 相关主题

* [支付链接](https://doc.haipay.net/zh/history/V20260701/payments/cards/payment-links.md)
* [VISA/MASTER 支付](https://doc.haipay.net/zh/history/V20260701/payments/cards/overview.md)
* [Apple Pay](https://doc.haipay.net/zh/history/V20260701/payments/cards/apple-pay.md)
* [Google Pay](https://doc.haipay.net/zh/history/V20260701/payments/cards/google-pay.md)
* [使用测试卡号模拟支付成功、拒付与争议场景](https://doc.haipay.net/zh/history/V20260701/testing/test-cards.md)


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