307 lines
7.7 KiB
Markdown
307 lines
7.7 KiB
Markdown
# 支付宝支付链接前端对接说明
|
||
|
||
## 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 文档为准。 |