frontend-app/utils/1.md

抖音支付：前端调用商城后端接口文档

日期：2026-09-05。适用：商城 App 前端。本文只描述前端调用我们后端的接口，不涉及抖音官方服务端接口、证书配置或插件开发。

一、公共约定

测试环境 Base URL：https://api.o.tbmall.xin。生产环境沿用项目正式用户端 API 配置，不要使用后台管理 API 地址。

请求头沿用现有登录请求封装：

Authorization: <项目当前环境的应用授权值>
HSM-AUTH: <当前用户登录令牌>
Content-Type: application/x-www-form-urlencoded

POST 参数以表单提交，不是 JSON body；GET 使用 URL 查询参数。不要把后台管理 Token 填到 HSM-AUTH。

业务响应统一格式：

{ "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，沿用现有抵扣券结算逻辑

请求表单：

types=6&isDeduction=false

已启用抖音支付时的响应示例：

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

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 字符串

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 字符串，同上一接口

addrId=10001&cartIds=40001,40002&payway=douyin

购物车可能拆分业务订单并合并支付，查询支付结果仍使用本次返回的 orderNum。

4.4 余额充值

POST /finance/recharge

参数	类型	必填	说明
category	string	是	余额充值传 balance
amount	decimal	是	充值金额，单位元
payway	string	是	douyin

category=balance&amount=1.00&payway=douyin

注意：上述四个 POST 都可能创建支付单，请勿反复点击或自动重试创建。新下单接口已经返回支付参数时，不要紧接着再调用 /order/payment。

五、下单/支付接口统一返回

上述四个接口均返回 PayInfoDto。抖音待支付响应示例（省略其他业务字段）：

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

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

GET https://api.o.tbmall.xin/payment/queryResult?orderNum=PAY_EXAMPLE_001

{
  "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 仅可检查适用的后端业务请求，不能凭网页调用拉起此原生能力。