device-voice-h5/docs/新增支付宝支付.md

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

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：

{
  "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 套餐订单支付

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

{
  "payment_method": "alipay"
}

支付宝支付响应示例：

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

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

5.2 钱包充值

创建钱包充值单时传：

{
  "payment_method": "alipay"
}

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

5.3 强制充值购包

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

{
  "payment_method": "alipay"
}

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

{
  "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：

{
  "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 套餐订单支付

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

{
  "payment_method": "alipay"
}

支付宝支付响应示例：

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

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

5.2 钱包充值

创建钱包充值单时传：

{
  "payment_method": "alipay"
}

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

5.3 强制充值购包

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

{
  "payment_method": "alipay"
}

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

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

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

6. 前端展示建议

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

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

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

7. 注意事项

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