234 lines
9.6 KiB
Markdown
234 lines
9.6 KiB
Markdown
# 抖音支付：前端调用商城后端接口文档
|
||
|
||
日期：2026-09-05。适用：商城 App 前端。本文只描述前端调用我们后端的接口，不涉及抖音官方服务端接口、证书配置或插件开发。
|
||
|
||
## 一、公共约定
|
||
|
||
测试环境 Base URL：`https://api.o.tbmall.xin`。生产环境沿用项目正式用户端 API 配置，不要使用后台管理 API 地址。
|
||
|
||
请求头沿用现有登录请求封装：
|
||
|
||
```http
|
||
Authorization: <项目当前环境的应用授权值>
|
||
HSM-AUTH: <当前用户登录令牌>
|
||
Content-Type: application/x-www-form-urlencoded
|
||
```
|
||
|
||
POST 参数以表单提交，不是 JSON body；GET 使用 URL 查询参数。不要把后台管理 Token 填到 HSM-AUTH。
|
||
|
||
业务响应统一格式：
|
||
|
||
```json
|
||
{ "bizcode": 100, "errcode": 0, "msg": "成功", "data": {} }
|
||
```
|
||
|
||
`bizcode=100` 表示本次接口调用成功，不等于用户已付款。其他业务码按 msg 提示；HTTP 错误、超时或网络失败不能视作付款成功。以下所有 ID、金额、签名均为示例。
|
||
|
||
## 二、调用顺序
|
||
|
||
1. 调用 `/cart/getSupportPay`，判断返回列表是否包含 `type=douyin`。
|
||
2. 根据业务场景选择一个下单/支付接口，提交 `payway=douyin`。
|
||
3. 保存返回的 `data.orderNum`，把 `data.douyin` 中的支付参数交给 App 支付能力拉起抖音。
|
||
4. 用户返回 App 后调用 `/payment/queryResult` 查询结果，只有 `data.state=2` 才提示支付成功。
|
||
|
||
**重点：支付方式筛选传 `types=6`；实际支付传 `payway=douyin`，不是 `payway=6`。**
|
||
|
||
## 三、查询支付方式
|
||
|
||
**POST `/cart/getSupportPay`**
|
||
|
||
| 参数 | 类型 | 必填 | 说明 |
|
||
| ----------- | ------- | ---- | -------------------------------------------- |
|
||
| types | string | 否 | 只查抖音传 `6`；多种传 `1,2,6`；全部传 `ALL` |
|
||
| isDeduction | boolean | 否 | 默认 false，沿用现有抵扣券结算逻辑 |
|
||
|
||
请求表单：
|
||
|
||
```text
|
||
types=6&isDeduction=false
|
||
```
|
||
|
||
已启用抖音支付时的响应示例：
|
||
|
||
```json
|
||
{
|
||
"bizcode": 100,
|
||
"errcode": 0,
|
||
"msg": "成功",
|
||
"data": [{ "type": "douyin", "name": "抖音支付", "balance": 0 }]
|
||
}
|
||
```
|
||
|
||
没有启用对应配置时，列表可能为空。显示名称使用 name，提交支付方式使用 type；balance 不是抖音钱包余额。
|
||
|
||
## 四、发起支付（按场景选一个）
|
||
|
||
### 4.1 已创建订单，继续支付
|
||
|
||
**POST `/order/payment`**
|
||
|
||
| 参数 | 类型 | 必填 | 说明 |
|
||
| ------ | ------ | ---- | ----------------------- |
|
||
| id | long | 是 | 待支付的商城业务订单 ID |
|
||
| payway | string | 是 | 固定 `douyin` |
|
||
|
||
```text
|
||
id=123456&payway=douyin
|
||
```
|
||
|
||
后端接口还接受可选 password/code，但抖音支付不需要提交。成功响应见第五节。
|
||
|
||
### 4.2 商品直接购买并支付
|
||
|
||
**POST `/cart/settlementOrder`**
|
||
|
||
| 参数 | 类型 | 必填 | 说明 |
|
||
| ------------ | ------- | -------- | ------------------------------------ |
|
||
| addrId | long | 是 | 收货地址 ID |
|
||
| goodsId | long | 是 | 商品 ID |
|
||
| specsId | long | 是 | 规格 ID |
|
||
| goodsNum | decimal | 是 | 购买数量 |
|
||
| payway | string | 本流程是 | `douyin` |
|
||
| payway2 | string | 否 | `vcoin` 表示抵扣券，沿用现有结算选择 |
|
||
| couponUserId | long | 否 | 已选用户优惠券 ID |
|
||
| remark | string | 否 | 现有分组备注 JSON 字符串 |
|
||
|
||
```text
|
||
addrId=10001&goodsId=20001&specsId=30001&goodsNum=1&payway=douyin
|
||
```
|
||
|
||
remark 格式为 `[{"gkey":"结算返回的分组标识","rmk":"备注内容"}]`，通过现有请求封装表单编码。金额由后端计算，不传前端自算金额。优惠券、抵扣券沿用结算规则，不因选择抖音改变适用范围。
|
||
|
||
### 4.3 购物车结算并支付
|
||
|
||
**POST `/cart/settle`**
|
||
|
||
| 参数 | 类型 | 必填 | 说明 |
|
||
| ------------ | ------ | ---- | ---------------------------------- |
|
||
| addrId | long | 是 | 收货地址 ID |
|
||
| cartIds | string | 是 | 购物车 ID 逗号分隔，`ALL` 表示全选 |
|
||
| payway | string | 是 | `douyin` |
|
||
| couponUserId | long | 否 | 用户优惠券 ID |
|
||
| remark | string | 否 | 分组备注 JSON 字符串，同上一接口 |
|
||
|
||
```text
|
||
addrId=10001&cartIds=40001,40002&payway=douyin
|
||
```
|
||
|
||
购物车可能拆分业务订单并合并支付，查询支付结果仍使用本次返回的 orderNum。
|
||
|
||
### 4.4 余额充值
|
||
|
||
**POST `/finance/recharge`**
|
||
|
||
| 参数 | 类型 | 必填 | 说明 |
|
||
| -------- | ------- | ---- | -------------------- |
|
||
| category | string | 是 | 余额充值传 `balance` |
|
||
| amount | decimal | 是 | 充值金额，单位元 |
|
||
| payway | string | 是 | `douyin` |
|
||
|
||
```text
|
||
category=balance&amount=1.00&payway=douyin
|
||
```
|
||
|
||
注意：上述四个 POST 都可能创建支付单，请勿反复点击或自动重试创建。新下单接口已经返回支付参数时，不要紧接着再调用 `/order/payment`。
|
||
|
||
## 五、下单/支付接口统一返回
|
||
|
||
上述四个接口均返回 PayInfoDto。抖音待支付响应示例（省略其他业务字段）：
|
||
|
||
```json
|
||
{
|
||
"bizcode": 100,
|
||
"errcode": 0,
|
||
"msg": "成功",
|
||
"data": {
|
||
"orderId": 123456,
|
||
"orderNum": "PAY_EXAMPLE_001",
|
||
"amount": 1.0,
|
||
"status": 0,
|
||
"douyin": {
|
||
"appId": "EXAMPLE_APP_ID",
|
||
"mchId": "EXAMPLE_MERCHANT_ID",
|
||
"prepayId": "EXAMPLE_PREPAY_ID",
|
||
"callbackScheme": "trustbridgeapp",
|
||
"packageValue": "Sign=DYPay",
|
||
"nonceStr": "0123456789abcdef0123456789abcdef",
|
||
"timeStamp": "1788585600",
|
||
"sign": "EXAMPLE_BASE64_SIGNATURE"
|
||
}
|
||
}
|
||
}
|
||
```
|
||
|
||
| 字段 | 类型 | 前端用途 |
|
||
| --------------------- | ------- | ---------------------------------------------- |
|
||
| orderId | long | 后端返回的订单 ID |
|
||
| orderNum | string | 保存下来，支付结果查询必须用它 |
|
||
| amount | decimal | 实际支付金额（元） |
|
||
| status | integer | 此 DTO 中 0=待支付、1=已支付；不同于查单 state |
|
||
| douyin | object | App 拉起抖音所需参数 |
|
||
| douyin.appId | string | 抖音应用 ID |
|
||
| douyin.mchId | string | 抖音商户 ID |
|
||
| douyin.prepayId | string | 预支付 ID |
|
||
| douyin.callbackScheme | string | App 返回 Scheme |
|
||
| douyin.packageValue | string | `Sign=DYPay` |
|
||
| douyin.nonceStr | string | 随机字符串 |
|
||
| douyin.timeStamp | string | 秒级时间戳，保留字符串类型 |
|
||
| douyin.sign | string | 后端生成的签名，原样使用 |
|
||
|
||
后端已处理签名，前端无需请求商户私钥或另调签名接口。参数缺失时停止拉起，提示支付参数异常并反馈后端，不要自行伪造字段。
|
||
|
||
若 App 支付桥接要求 SDK 小写字段，映射如下；这不是另一个 HTTP 请求：
|
||
|
||
```js
|
||
const d = response.data.douyin;
|
||
const payInfo = {
|
||
appid: d.appId,
|
||
partnerid: d.mchId,
|
||
prepayid: d.prepayId,
|
||
package: d.packageValue,
|
||
noncestr: d.nonceStr,
|
||
timestamp: d.timeStamp,
|
||
sign: d.sign,
|
||
};
|
||
```
|
||
|
||
## 六、查询支付结果
|
||
|
||
**GET `/payment/queryResult`**
|
||
|
||
| 参数 | 类型 | 必填 | 说明 |
|
||
| -------- | ------ | ---- | ------------------------------------------------------- |
|
||
| orderNum | string | 是 | 发起支付接口返回的 data.orderNum，不是 orderId/prepayId |
|
||
|
||
```http
|
||
GET https://api.o.tbmall.xin/payment/queryResult?orderNum=PAY_EXAMPLE_001
|
||
```
|
||
|
||
```json
|
||
{
|
||
"bizcode": 100,
|
||
"errcode": 0,
|
||
"msg": "成功",
|
||
"data": { "state": 2 }
|
||
}
|
||
```
|
||
|
||
| state | 含义 | 前端处理 |
|
||
| ----- | ---------- | -------------------------------- |
|
||
| 0 | 订单不存在 | 核对支付编号及环境，不能提示成功 |
|
||
| 1 | 支付处理中 | 稍后再次查询 |
|
||
| 2 | 支付成功 | 展示成功，刷新订单或充值余额 |
|
||
| 3 | 支付失败 | 提示失败，刷新订单状态 |
|
||
|
||
当前 App 采用最多 5 次、间隔 1.5 秒的查询；这属于前端策略，不是后端强制限制。暂未确认、断网或超时应显示“支付结果确认中”，保存编号以便回前台再次查询，避免直接重复付款。
|
||
|
||
用户取消或支付 SDK 提示成功后，都需要以服务端查询结果为准。不要调用 `/payment/feedback` 上报成功来替代查单；前端也不需要调用后端的抖音通知/退款回调接口。
|
||
|
||
## 七、对接范围与发布注意
|
||
|
||
- 本文按当前工作区后端代码整理；SDK 签名新增字段（packageValue、nonceStr、timeStamp、sign）尚未确认已部署到测试/生产服务器。
|
||
- 后台配置已完成不代表预下单、签名、支付回调均验收通过，实际支付链路仍需联调。
|
||
- 本次抖音支付是 App 原生支付；H5 仅可检查适用的后端业务请求，不能凭网页调用拉起此原生能力。
|