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

# 前端组件 - 组件使用

> 如何集成前端组件，将支付能力嵌入商户页面。

Waffo 提供前端 SDK `@waffo/payment-sdk`，支持在商户页面内直接集成支付和绑卡功能。

## 安装

```bash theme={null}
npm install @waffo/payment-sdk
```

## 初始化

```typescript theme={null}
import WaffoSDK from '@waffo/payment-sdk';

const sdk = new WaffoSDK('your-client-api-key', {
  env: 'prod',    // 'prod' | 'testing' | 'sandbox'
  locale: 'en'    // 可选，默认 'en'
});
```

## 功能一览

| 功能                    | 方法                         | 说明                         |
| --------------------- | -------------------------- | -------------------------- |
| 绑卡（Card Tokenization） | `sdk.tokenizationSubmit()` | 安全提交卡片信息，生成 Token          |
| 嵌入式收银台                | `WaffoSDK.renderIframe()`  | 将 Waffo 收银台以 iframe 嵌入商户页面 |

## 绑卡（tokenizationSubmit）

将用户卡片信息加密后提交到 Waffo，商户服务器不接触明文卡号。

### 前置步骤

商户后端先调用 [Generate API](/docs/zh/developer-docs/integration/tokenization/generate) 获取 `tokenSessionId`。

### 提交卡片

```typescript theme={null}
const result = await sdk.tokenizationSubmit('tokenSessionId', {
  tokenData: {
    pan: '4111111111111111',  // 卡号
    name: 'John Doe',         // 持卡人姓名
    expiry: '12/2025',        // 有效期 MM/YYYY
    cvv: '123'                // CVV（可选）
  },
  billingAddress: {            // 可选
    countryCode: 'USA',
    region: 'CA',
    city: 'San Francisco',
    postalCode: '94102',
    address: '123 Main St'
  }
});
```

### 处理结果

```typescript theme={null}
if (result.success) {
  if (result.data.validateUrl) {
    // 需要 3DS 验证，重定向用户
    window.location.href = result.data.validateUrl;
  } else {
    // 绑卡成功，等待 Webhook 获取 tokenId
  }
}
```

完整流程参见 [绑卡与 Token 管理](/docs/zh/developer-docs/integration/tokenization/overview)。

## 嵌入式收银台（renderIframe）

将 Waffo 收银台以 iframe 嵌入商户页面，适合不想自建收银台 UI 的商户。

```typescript theme={null}
WaffoSDK.renderIframe({
  // 自定义主题颜色、Logo、Apple Pay 等
});
```

支持：

* 自定义主题颜色
* 自定义 Logo
* Apple Pay / Google Pay 按钮
* 多语言

## 收银台外观定制

收银台的外观主题（`cashierAppearance`）、语言（`cashierLanguage`）与支付方式过滤，通过订单创建参数 `paymentInfo` 配置。完整的取值、格式与示例见 [收银台客制化](/docs/zh/developer-docs/integration/checkout/customization)。