# 支付宝支付链接前端对接说明

## 1. 对接范围

本次新增的是 **C 端支付宝支付链接能力**。前端无需接入支付宝 SDK，后端会返回已签名的支付宝 WAP 支付链接。

覆盖场景：

1. 套餐订单支付
2. 钱包充值
3. 强制充值购包场景

微信支付原逻辑保持不变：微信返回 `pay_config`，支付宝返回 `payment_link`。

具体接口路径、完整请求字段、响应结构、错误码请以前端接口文档 / OpenAPI 文档为准。

## 2. 支付方式取值

前端统一使用 `payment_method` 区分支付方式：

| 值 | 含义 | 前端处理 |
| --- | --- | --- |
| `wallet` | 钱包支付 | 仅订单支付支持，无第三方跳转 |
| `wechat` | 微信支付 | 使用返回的 `pay_config` 调起微信支付 |
| `alipay` | 支付宝支付 | 使用返回的 `payment_link` 打开或展示支付链接 |

注意事项：

- `app_type` 只在微信支付时需要。
- 支付宝支付时不需要传 `app_type`。
- 支付宝支付返回的是支付链接，不是 JSAPI 参数。

## 3. 前端需要关注的响应字段

当选择支付宝支付时，接口响应中会返回 `payment_link`：

```json
{
  "payment_link": {
    "payment_no": "支付单号",
    "qr_link": "支付宝支付链接，可用于生成二维码",
    "copy_link": "支付宝支付链接，可复制或直接打开",
    "pay_expire_at": "支付链接过期时间，RFC3339 格式"
  }
}
```

字段说明：

| 字段 | 用途 |
| --- | --- |
| `payment_no` | 支付单号，问题排查 / 客服查询使用 |
| `qr_link` | 前端可用该链接生成二维码 |
| `copy_link` | 用户复制或浏览器打开的支付链接，当前与 `qr_link` 一致 |
| `pay_expire_at` | 支付链接过期时间，前端可用于倒计时展示 |

## 4. 推荐交互流程

### 4.1 支付宝支付流程

前端拿到 `payment_link` 后：

1. H5 / 浏览器场景：直接跳转 `copy_link`。

支付成功后：

- 不要只依赖支付宝返回页判断支付成功。
- 最终支付状态以服务端订单 / 充值记录状态为准。
- 用户返回页面后，前端应轮询订单详情、订单列表或充值记录接口。

## 5. 各业务场景说明

### 5.1 套餐订单支付

普通套餐下单后，如果需要支付，前端调用订单支付接口，并传：

```json
{
  "payment_method": "alipay"
}
```

支付宝支付响应示例：

```json
{
  "payment_method": "alipay",
  "payment_link": {
    "payment_no": "...",
    "qr_link": "...",
    "copy_link": "...",
    "pay_expire_at": "..."
  }
}
```

前端根据 `payment_link` 发起支付宝支付。

### 5.2 钱包充值

创建钱包充值单时传：

```json
{
  "payment_method": "alipay"
}
```

支付宝场景返回 `payment_link`；微信场景返回 `pay_config`。

### 5.3 强制充值购包

创建订单时，如果后端判断需要强制充值，前端可指定：

```json
{
  "payment_method": "alipay"
}
```

如果是支付宝强充，响应中会返回：

```json
{
  "order_type": "recharge",
  "recharge": {},
  "payment_link": {}
}
```

前端按支付宝支付链接流程处理。

## 6. 前端展示建议

支付宝支付页面建议展示：

- 支付金额
- 支付宝二维码或“去支付宝支付”按钮
- 支付链接过期倒计时
- “我已完成支付”按钮
- “重新获取支付链接”按钮

点击“我已完成支付”时，不直接判定成功，应查询服务端状态。

## 7. 注意事项

1. 金额单位仍然是 **分**。
2. 支付宝支付不需要 `app_type`。
3. `pay_config` 只用于微信支付。
4. `payment_link` 只用于支付宝支付。
5. 支付状态以服务端为准，不以前端跳转结果为准。
6. 支付链接过期后，前端应重新调用对应支付 / 充值接口获取新链接。
7. 具体接口路径、完整字段、错误码请以前端接口文档 / OpenAPI 文档为准。

# 支付宝支付链接前端对接说明

## 1. 对接范围

本次新增的是 **C 端支付宝支付链接能力**。前端无需接入支付宝 SDK，后端会返回已签名的支付宝 WAP 支付链接。

覆盖场景：

1. 套餐订单支付
2. 钱包充值
3. 强制充值购包场景

微信支付原逻辑保持不变：微信返回 `pay_config`，支付宝返回 `payment_link`。

具体接口路径、完整请求字段、响应结构、错误码请以前端接口文档 / OpenAPI 文档为准。

## 2. 支付方式取值

前端统一使用 `payment_method` 区分支付方式：

| 值 | 含义 | 前端处理 |
| --- | --- | --- |
| `wallet` | 钱包支付 | 仅订单支付支持，无第三方跳转 |
| `wechat` | 微信支付 | 使用返回的 `pay_config` 调起微信支付 |
| `alipay` | 支付宝支付 | 使用返回的 `payment_link` 打开或展示支付链接 |

注意事项：

- `app_type` 只在微信支付时需要。
- 支付宝支付时不需要传 `app_type`。
- 支付宝支付返回的是支付链接，不是 JSAPI 参数。

## 3. 前端需要关注的响应字段

当选择支付宝支付时，接口响应中会返回 `payment_link`：

```json
{
  "payment_link": {
    "payment_no": "支付单号",
    "qr_link": "支付宝支付链接，可用于生成二维码",
    "copy_link": "支付宝支付链接，可复制或直接打开",
    "pay_expire_at": "支付链接过期时间，RFC3339 格式"
  }
}
```

字段说明：

| 字段 | 用途 |
| --- | --- |
| `payment_no` | 支付单号，问题排查 / 客服查询使用 |
| `qr_link` | 前端可用该链接生成二维码 |
| `copy_link` | 用户复制或浏览器打开的支付链接，当前与 `qr_link` 一致 |
| `pay_expire_at` | 支付链接过期时间，前端可用于倒计时展示 |

## 4. 推荐交互流程

### 4.1 支付宝支付流程

前端拿到 `payment_link` 后：

1. H5 / 浏览器场景：直接跳转 `copy_link`。

支付成功后：

- 不要只依赖支付宝返回页判断支付成功。
- 最终支付状态以服务端订单 / 充值记录状态为准。
- 用户返回页面后，前端应轮询订单详情、订单列表或充值记录接口。

## 5. 各业务场景说明

### 5.1 套餐订单支付

普通套餐下单后，如果需要支付，前端调用订单支付接口，并传：

```json
{
  "payment_method": "alipay"
}
```

支付宝支付响应示例：

```json
{
  "payment_method": "alipay",
  "payment_link": {
    "payment_no": "...",
    "qr_link": "...",
    "copy_link": "...",
    "pay_expire_at": "..."
  }
}
```

前端根据 `payment_link` 发起支付宝支付。

### 5.2 钱包充值

创建钱包充值单时传：

```json
{
  "payment_method": "alipay"
}
```

支付宝场景返回 `payment_link`；微信场景返回 `pay_config`。

### 5.3 强制充值购包

创建订单时，如果后端判断需要强制充值，前端可指定：

```json
{
  "payment_method": "alipay"
}
```

如果是支付宝强充，响应中会返回：

```json
{
  "order_type": "recharge",
  "recharge": {},
  "payment_link": {}
}
```

前端按支付宝支付链接流程处理。

## 6. 前端展示建议

支付宝支付页面建议展示：

- 支付金额
- 支付宝二维码或“去支付宝支付”按钮
- 支付链接过期倒计时
- “我已完成支付”按钮
- “重新获取支付链接”按钮

点击“我已完成支付”时，不直接判定成功，应查询服务端状态。

## 7. 注意事项

1. 金额单位仍然是 **分**。
2. 支付宝支付不需要 `app_type`。
3. `pay_config` 只用于微信支付。
4. `payment_link` 只用于支付宝支付。
5. 支付状态以服务端为准，不以前端跳转结果为准。
6. 支付链接过期后，前端应重新调用对应支付 / 充值接口获取新链接。
7. 具体接口路径、完整字段、错误码请以前端接口文档 / OpenAPI 文档为准。