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

# 生成令牌

> 发起绑卡请求并获取 `tokenSessionId`，供前端 SDK 使用。

```
POST /api/v1/tokenization/generate
```

## 请求参数

| 参数               | 类型     | 必填 | 说明                    |
| ---------------- | ------ | -- | --------------------- |
| `tokenRequestId` | String | 是  | 绑卡请求的幂等键              |
| `merchantUserId` | String | 是  | 商户侧用户 ID              |
| `tokenType`      | String | 是  | 令牌类型，固定为 `"CARD"`     |
| `merchantInfo`   | Object | 是  | 商户信息（包含 `merchantId`） |
| `notifyUrl`      | String | 是  | 绑卡结果的 Webhook 回调 URL  |
| `tokenData`      | Object | 否  | 卡数据（仅 PCI-DSS 商户）     |

### tokenData（仅 PCI-DSS 商户）

| 参数       | 类型     | 说明           |
| -------- | ------ | ------------ |
| `pan`    | String | 卡号           |
| `name`   | String | 持卡人姓名        |
| `expiry` | String | 有效期（MM/YYYY） |
| `cvv`    | String | CVV          |

## 响应参数

| 参数               | 类型     | 说明                                    |
| ---------------- | ------ | ------------------------------------- |
| `tokenSessionId` | String | 会话 ID，传给前端 SDK 的 `tokenizationSubmit` |
| `tokenId`        | String | 令牌 ID（仅当 PCI-DSS 商户直接提交时返回）           |

## 请求示例

### 标准流程（通过前端 SDK 提交）

```json theme={null}
{
  "tokenRequestId": "treq_a1b2c3d4e5f6",
  "merchantUserId": "user_123",
  "tokenType": "CARD",
  "merchantInfo": { "merchantId": "M000001" },
  "notifyUrl": "https://your-site.com/webhook/tokenization"
}
```

### 响应示例

```json theme={null}
{
  "code": "0",
  "msg": "Success",
  "data": {
    "tokenSessionId": "tsess_xxxxxxxxxxxx"
  }
}
```

获取 `tokenSessionId` 后，将其传给前端 SDK 方法 `tokenizationSubmit` 以完成卡信息提交。

## 绑卡结果通知

绑卡完成后，Waffo 会向 `notifyUrl` 发送包含 `tokenId` 的 Webhook 通知。商户必须保存该 `tokenId` 以用于后续支付。