> ## 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                    | 生产环境不支持中国大陆地区 | 核实商户配置和目标市场                |

## 相关主题

* [支付链接](/docs/zh/V20260628/api/version2/payment-link)
* [VISA/MASTER 支付](/docs/zh/V20260628/api/version2/creditcard)
* [Apple Pay](/docs/zh/V20260628/api/version2/ApplePay)
* [Google Pay](/docs/zh/V20260628/api/version2/GooglePay)