支付与交易:多端支付集成与对账
本篇要点:把下单、调起、回调、对账四段串成一条能在小程序、App、鸿蒙上跑通并验收的支付链路。 前置文章:《uni-app x:原生渲染路线与 UTS》讲的是 uni-app x 与 UTS 的编译路线,讨论的是界面怎么渲染;这一章不碰渲染,只讨论钱怎么进账、状态怎么不失真。
为什么需要它
先看一张真实的工单。用户在小程序里付了 39 元,页面转了两秒弹回「待支付」,他以为没付上,又付了一次。第二天财务发现同一订单有两笔支付记录,仓库只发了一次货;客服去退多付的那一笔,退款按钮被点了三次,产生了三张退款单。
这四句话里是四个互相独立的问题:调起之后客户端没拿到可信结果、回调重复触发、退款没有中间态、没有任何机制发现账目差异。四者的失败模式互不重叠,所以不能塞进一个函数里靠 try/catch 兜住。
支付链路的工程风险集中在三处,都不在「调起」这一步:三端下单与调起参数结构不一致;回调由微信主动发起且会重试十五次;对账缺失会让差异永远不被发现。截至 2026 年 11 月,微信支付 v3 是唯一在维护的接口版本,v2 仅存量在用;uni.requestPayment 对鸿蒙(HarmonyOS NEXT)的支持自 HBuilderX 4.26 起提供,且鸿蒙端微信支付的 orderInfo 必须传字符串。这两条构成本篇的技术基线。
四段链路的责任划分如图 8-1。注意每个环节下方的虚线分支,它们是四类不同的故障,不该合并处理。
图 8-1 支付四段链路与各自的失败分支
核心概念
统一下单:金额与订单号只能由服务端产生
统一下单(unified order)是向微信支付服务端申请一笔预支付交易,拿回 prepay_id,客户端再拿这个凭证调起收银台。可以把它理解成取餐号:客户端只负责把号递给收银台,没有资格自己写金额。
反例是下单接口接收前端传来的 amount 并直接透传。攻击者把 39 改成 0.01,签名照样能过——签的本来就是恶意客户端递上来的数字。金额只能由服务端按商品表重算,数据库用整数分存储,绕开浮点误差。
回调与验签:资金方主动通知,且会重试十五次
回调(callback)是微信在支付完成后向 notify_url 发起的 POST 请求。它不是「客户端告诉服务端付好了」,而是资金方来通知你。验签(signature verification)用来确认这条请求确实来自微信。
两条约束必须记住:验签要用原始请求体(raw body),不能用框架解析后重新序列化的结果;应答要在业务处理之前完成,5 秒内返回 200 或 204 且无应答体。失败后微信按 15s/15s/30s/3m/10m/20m/30m/30m/30m/60m/3h/3h/3h/6h/6h 的阶梯重试,最多 15 次。
反例是把 notify_url 配成 HTTP 地址、由反向代理 302 跳到 HTTPS。微信的 POST 在跳转后丢掉请求体,验签必然失败,日志上表现成「回调偶发全丢」,实际一次都没成功。
幂等:让状态条件本身成为锁
幂等(idempotency)指同一个请求执行一次和执行多次,结果相同。支付场景里的做法不是先查状态再更新,而是把状态写进更新的 where 条件:where({ out_trade_no, status: 'paying' })。两个回调同时到达时,只有一条能把 paying 改成 paid,另一条影响行数为 0。
反例是「先 get 判断状态,再 update」。查和改之间有一个窗口,两次回调都能通过判断,于是重复发货、库存被扣成负数。这个窗口在平时测不出来,只在大促并发时出现。
订单状态机:用枚举,不用布尔字段
订单状态机(state machine)是把订单的所有合法状态和迁移路径显式写出来。支付至少要六个状态:created、paying、paid、closed、refunding、refunded。退款必须有 refunding 这个中间态,否则「受理成功」会被当成「退款完成」。
反例是用 isPaid、isRefunded 两个布尔字段拼装状态。四个组合里至少有一个是非法的(既已退款又未支付),而代码里没有任何地方拦得住它。
对账:唯一能发现状态失真的机制
对账(reconciliation)是每天把微信侧的交易账单拉下来,逐笔和本地订单表比对。它存在的理由很朴素:回调可能全丢,微信官方明确要求不能只依赖回调拿结果,必须结合查询接口与账单。
反例是把对账设计成「发现差异就告警」。告警疲劳之后,真正的长短款会被当成噪音忽略。可自动修补的项要自动修补,只有需要人决策的才推给人。
动手实践
第一步:服务端只暴露一个下单入口
对外只留 createPayment({ orderId, channel }),内部按渠道组装请求。out_trade_no、金额、notify_url 三项由服务端持有。微信支付 v3 按场景分接口:JSAPI/小程序走 /v3/pay/transactions/jsapi,App 走 /v3/pay/transactions/app,请求体接近,但 payer.openid 只有 JSAPI 必填。
v3 的签名串是五行定长格式,少一个换行就 401。
// uniCloud-aliyun/cloudfunctions/pay-create/index.js
// 前提:Node 18+,商户 API 证书与 APIv3 密钥放在云函数私有 config 目录,不下发前端
'use strict'
const crypto = require('crypto')
const { mchid, serialNo, privateKey, notifyUrl } = require('./config.json')
function buildAuth(method, urlPath, body) {
const timestamp = Math.floor(Date.now() / 1000).toString()
const nonceStr = crypto.randomBytes(16).toString('hex')
// v3 签名串:请求方法\nURL\n时间戳\n随机串\n报文主体\n
const message = `${method}\n${urlPath}\n${timestamp}\n${nonceStr}\n${body}\n`
const signature = crypto.createSign('RSA-SHA256').update(message).sign(privateKey, 'base64')
return `WECHATPAY2-SHA256-RSA2048 mchid="${mchid}",nonce_str="${nonceStr}",` +
`signature="${signature}",timestamp="${timestamp}",serial_no="${serialNo}"`
}
exports.main = async (event) => {
// 金额不取 event.amount,按 orderId 从商品表重算,单位为分
const order = await getOrder(event.orderId)
if (!order || order.status !== 'created') return { code: 'ORDER_INVALID' }
const body = JSON.stringify({
appid: event.channel === 'mp-weixin' ? WX_MP_APPID : WX_APP_APPID,
mchid, description: order.title, out_trade_no: order.outTradeNo,
notify_url: notifyUrl, amount: { total: order.amountFen, currency: 'CNY' },
payer: event.channel === 'mp-weixin' ? { openid: order.openid } : undefined
})
const auth = buildAuth('POST', '/v3/pay/transactions/jsapi', body)
return { code: 0, auth, body }
}运行结果:构造 amount=1 的请求打进来,返回 { code: 'ORDER_INVALID' } 或按商品表重算后的金额下单,前端传的数字被完全忽略。此时 out_trade_no 是 32 位以内的服务端单号,回调能凭它找回本地订单。
第二步:客户端调起,按端适配参数
三端参数差异是联调阶段的主要排错依据,先看表再写代码。
| 端 | provider | 关键参数 | 类型 | 注意事项 |
|---|---|---|---|---|
| 微信小程序 | wxpay | 五个字段平铺 | Object 平铺 | signType 用 RSA(仅 v3),package 形如 prepay_id=xxx |
| App(Android/iOS) | wxpay | orderInfo | Object | 键名全小写:appid/noncestr/package/partnerid/prepayid/timestamp/sign |
| App(鸿蒙) | wxpay | orderInfo | String | 必须 JSON.stringify(orderInfo) |
| 支付宝小程序 | alipay | tradeNO | String | 传支付宝交易号 |
| App 支付宝 | alipay | orderInfo | String | 服务端签名后的订单串 |
鸿蒙那一行是最容易漏的。同一份对象在 Android 上正常,在鸿蒙上直接失败,而报错信息只写着参数错误。把它收进一个 UTS 插件,让类型在编译期就分开。
// uni_modules/pay-adapt/utssdk/app-harmony/pay.uts
// 只在鸿蒙端编译:把统一下发的预支付对象转成字符串
export type Prepay = {
appid : string
noncestr : string
package : string
partnerid : string
prepayid : string
timestamp : number
sign : string
}
export function buildWxOrderInfo(prepay : Prepay) : string {
return JSON.stringify(prepay)
}
export function buildAliOrderInfo(signedOrderStr : string) : string {
return signedOrderStr
}运行结果:鸿蒙真机上调用 uni.requestPayment({ provider: 'wxpay', orderInfo: buildWxOrderInfo(prepay) }),收银台正常拉起;把对象直接传进去则回调 fail,errMsg 提示参数类型不符。Android 与 iOS 仍传对象,不受影响。
第三步:回调三步走——验签、应答、幂等
验签用原始 body;应答在业务处理之前完成;幂等靠带状态条件的更新。三步顺序不能换,尤其不能把慢查询放在应答之前。
// 回调幂等:状态条件更新,影响行数为 0 时区分重复回调与金额不一致
// 前提:WXPAY_PUBLIC_KEY、API_V3_KEY 从私有配置加载
const res = await db.collection('order')
.where({ out_trade_no: tx.out_trade_no, status: 'paying' })
.update({ status: 'paid', transaction_id: tx.transaction_id, paid_at: Date.now() })
if (res.updated === 0) {
// 两种含义必须分开:重复回调(正常)与金额不一致(安全事件)
const { data: [order] } = await db.collection('order')
.where({ out_trade_no: tx.out_trade_no }).get()
if (!order || order.amount !== tx.amount.total) {
await db.collection('pay-anomaly').add({ type: 'AMOUNT_MISMATCH', tx })
return { status: 500, body: { code: 'FAIL', message: '金额不一致' } }
}
}
return { status: 200 } // 无应答体运行结果:同一个回调重放 10 次,订单表只发生一次状态变更,其余 9 次 updated 为 0 且金额一致,日志里记为重复回调,接口返回 200。若把金额改成 1 分再放进来,落在 pay-anomaly 表并返回 500,微信继续重试,人能看到告警。
第四步:把对账跑起来
每日定时拉 /v3/bill/tradebill(交易账单)与 /v3/bill/fundflowbill(资金账单),下载后先校验 hash_value(SHA1)再解析。差异落表,不能只发通知。退款同理:申请成功只代表受理,最终状态以 REFUND.SUCCESS 回调或主动查询为准。
| 差异类型 | 表现 | 处置方式 | 需人工确认 |
|---|---|---|---|
| 长款 | 微信有、本地无 | 按账单补单,置为 paid | 是 |
| 短款 | 本地有、微信无 | 立即冻结发货,调查询接口二次确认 | 是 |
| 金额不一致 | 前端传的金额被采纳 | 视为安全事件,落 pay-anomaly 并告警 | 是 |
| 状态不一致 | 已退款仍显示已支付 | 以退款单状态为准反向修正 | 否 |
| 账单文件损坏 | SHA1 校验不通过 | 重新申请下载,本期对账顺延 | 否 |
对账任务的工程要求只有两条:幂等(同一账单日重跑不产生重复数据)与可回溯(原始文件与解析结果保留至少 6 个月)。
常见误解
以为客户端 success 就代表支付成功。 其实它只代表 SDK 调起流程走完,用户可能只是切了后台、可能支付中取消。最终状态只能以服务端回调或主动查询为准,客户端的 success 最多用来触发一次「正在确认」的过渡界面。
以为 notify_url 用 302 跳到 HTTPS 没关系。 其实微信的 POST 在跳转后会丢请求体,验签拿不到原文必然失败。必须配 HTTPS 直连且不允许重定向,这一条在网关配置里改一行就能避免后面几周的排查。
以为退款是同步的。 其实申请接口返回成功只表示受理,钱到账要等退款回调。没有 refunding 中间态时,用户连点三次就会产生三张退款单,而每张都要单独去微信侧对状态。
小结
- 支付分四段:下单、调起、回调、对账。四段的失败模式独立,代码要分开写、分开测。
- 金额与
out_trade_no只能由服务端产生,数据库用整数分。 - 回调先验签(原始 body)、立即应答(5 秒内、无应答体),再用状态条件更新做幂等。
- 退款必须有
refunding中间态;对账是唯一能发现长款短款的机制,差异要落表。 - 三端调起参数三张脸,鸿蒙的
orderInfo是字符串——这是《uni-app x:原生渲染路线与 UTS》讲过的「多端差异收进适配层」在支付上的具体样子。
相关主题
支付成功后,用户最关心的是「东西什么时候到」。这条通知要穿过三条完全不同的链路:微信订阅消息、uni-push 的 socket 下行、厂商通道。相关文章拆开这三条链路,讲清为什么日志里四千多条 success 里,只有一部分人真的看见了消息。