本文最后更新于:November 21, 2026 pm
目录
微信小程序虚拟支付实战:从下单签名到发货回调的完整闭环
微信官方从2026年开始支持个人用户虚拟支付(Virtual Payment)。 本文记录完整的对接方案,文中代码均为脱敏改写后的示例,仅用于说明方案。
一、整体架构
| ┌─────────────┐ 1.请求支付参数 ┌──────────────┐ │ 小程序前端 │ ─────────────────► │ Spring 后端 │ │ (uni-app) │ │ │ │ │ ◄─ signData+paySig │ 2.建单/签名 │ │ │ +signature │ │ └──────┬──────┘ └──────┬───────┘ │ 3.wx.requestVirtualPayment │ ▼ │ 4.发货推送(消息回调) ┌─────────────┐ ▼ │ 微信虚拟支付 │ ─────────────► 消息回调接口 │ (米大师) │ (解密→发货→更新订单) └─────────────┘ │ ▲ │ └──────── 5.定时兜底 query_order ──┘
|
关键点:
- 前端拿到的四元组(signData / paySig / signature / mode)直接透传给
wx.requestVirtualPayment。
- 发货以微信消息推送为准,前端
success 回调只刷新 UI,不做发货。
- 定时任务兜底查单,防止消息推送丢失导致用户付了钱没到账。
二、配置项
按环境区分配置文件:
| wechat: app-id: wxxxxxxxxxxxxxxx app-secret: ******************************** offer-id: 1********* sandbox-app-key: ******************************** prod-app-key: ******************************** msg-token: ******************************** msg-aes-key: *******************************************
|
配套的配置属性类(示例):
| @Data @Component @ConfigurationProperties(prefix = "wechat") public class PayProperties { private String appId; private String appSecret; private String offerId; private String sandboxAppKey; private String prodAppKey; private String msgToken; private String msgAesKey; }
|
一个实用技巧:运行环境(沙箱/现网)不写在配置文件里,而是放在数据库配置表中(如 pay_env
,0=现网,1=沙箱),好处是可以不发版直接切环境,排查问题时非常方便。
三、下单
3.1 核心流程
前端选完充值金额后,调用下单接口,后端做四件事:
- 校验用户状态与道具有效性;
- 生成商户订单号
outTradeNo,落库一条「待支付」订单;
- 按官方格式拼
signData;
- 计算
paySig 和 signature 两个签名,连同 mode 一起返回。
1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 22 23 24 25 26 27
| public PayDataVO createPayData(String productCode, Long quantity) { String orderNo = generateOrderNo(); PayOrder order = new PayOrder(); ...
Map<String, Object> signMap = new HashMap<>(); signMap.put("offerId", offerId); signMap.put("buyQuantity", quantity); signMap.put("env", env); signMap.put("currencyType", "CNY"); signMap.put("productId", product.getCode()); signMap.put("goodsPrice", product.getPrice()); signMap.put("outTradeNo", orderNo); signMap.put("attach", String.valueOf(userId)); String signData = JSON.toJSONString(signMap);
PayDataVO result = new PayDataVO(); result.setSignData(signData); result.setMode("short_series_goods"); result.setPaySig(calcPaySig("requestVirtualPayment", signData, env)); result.setSignature(calcSignature(signData, user.getSessionKey())); return result; }
|
3.2 双签名算法
微信官方文档:签名算法
微信虚拟支付要求两个签名,算法都是 HMAC-SHA256 转十六进制,但密钥和内容不同:
1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21
|
public String calcPaySig(String uri, String postBody, int env) { String appKey = (env == SANDBOX) ? props.getSandboxAppKey() : props.getProdAppKey(); return hmacSha256Hex(appKey, uri + "&" + postBody); }
public String calcSignature(String postBody, String sessionKey) { return hmacSha256Hex(sessionKey, postBody); }
private String hmacSha256Hex(String key, String msg) { return SecureUtil.hmacSha256(key.getBytes(StandardCharsets.UTF_8)) .digestHex(msg.getBytes(StandardCharsets.UTF_8)); }
|
坑点总结:
- 参与签名的
postBody 必须与实际发给微信的请求体逐字节一致。Java 里千万别用文本块 """...""" 拼
JSON——文本块会自动加末尾换行并做缩进剥离,字节变了签名就对不上,微信会返回 90010 签名错误。正确姿势:用 JSON
序列化生成一次字符串存到变量里,签名和发送复用同一个变量。
paySig 的密钥是 AppKey,signature 的密钥是用户 session_key,两者别搞混。
- 沙箱和现网的 AppKey 不同,env 传错签名必然失败。
四、前端拉起支付
1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 22 23 24 25 26
| const payData = createPayData(productCode, cnt)
const invokeVirtualPayment = (payData) => { return new Promise((resolve, reject) => { wx.requestVirtualPayment({ ...payData, success: (res) => { uni.showToast({title: '支付成功', icon: 'success'}) resolve(res) }, fail: (err) => { if (err && (err.errCode === -2 || err.errMsg?.includes('cancel'))) { uni.showToast({title: '已取消支付', icon: 'none'}) } else { uni.showToast({title: '支付失败', icon: 'none'}) } reject(err) } }) uni.showToast({title: '仅支持在微信小程序中支付', icon: 'none'}) reject(new Error('not wechat mini program')) }) }
|
注意三点:
success 只代表扣款成功,不代表发货完成,到账以服务端回调为准。
- 微信已官方支持 Windows 客户端虚拟支付,但要先检测
wx.requestVirtualPayment 是否存在(兼容旧版 3.x Windows 微信),并对
iOS 做版本校验(微信 ≥ 8.0.68 才支持):
| const checkClientVersion = () => { const sys = uni.getSystemInfoSync() if (sys.platform !== 'ios') return true const cur = String(sys.version).split('.').map(Number) const min = [8, 0, 68] for (let i = 0; i < 3; i++) { if ((cur[i] || 0) > min[i]) return true if ((cur[i] || 0) < min[i]) break } uni.showModal({title: '提示', content: '请将微信更新至最新版后再进行支付', showCancel: false}) return false }
|
五、发货回调:消息推送(安全模式)
回调接口需要有两个同名不同请求方式的接口:比如 /api/wechat/notify(GET)和/api/wechat/notify(POST)
,GET接口主要是在后台配置保存时,微信方进行确认的,只有确认后才能进行保存;而POST接口就是实际用户支付后的回调接口。
5.1 协议
在 MP 后台「开发 → 开发管理 → 消息推送配置」开启安全模式(数据格式选 JSON),微信会向配置的 URL 推送事件:
- GET:首次配置时的 URL 验证,
signature = sha1(sort(token, timestamp, nonce)),验签通过原样返回 echostr。
- POST:正式推送。先验
msg_signature = sha1(sort(token, timestamp, nonce, Encrypt)),再用 EncodingAESKey 做 *
AES-256-CBC* 解密 Encrypt 字段,明文结构为 16B 随机 + 4B 大端 msg_len + msg(JSON) + appid。
5.2 关键实现
微信官方文档:接收消息推送
官方提供了明文模式和安全模式两种解密方式,明文模式就是简单的接口对接,这里主要说安全模式。
验签/解密直接复用微信官方示例 WXBizMsgCrypt,不要自己造轮子。
1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 22 23
| @PostMapping("/notify") public String onMessage(@RequestParam Map<String, String> params, @RequestBody String body) { JSONObject bodyJson = JSON.parseObject(body); String encrypt = bodyJson.getString("Encrypt");
String plainMsg; try { plainMsg = wxBizMsgCrypt.decryptMsg( params.get("msg_signature"), params.get("timestamp"), params.get("nonce"), encrypt); } catch (AesException e) { log.warn("验签或解密失败,忽略:code={}, msg={}", e.getCode(), e.getMessage()); return "error"; }
JSONObject msg = JSON.parseObject(plainMsg); dispatch(msg.getString("Event"), msg); handleGoodsDeliver(msg); return "success"; }
|
5.3 发货事件处理
关注事件:xpay_goods_deliver_notify(现金单发货)。核心发货逻辑:
1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 22 23 24 25 26 27 28 29 30 31 32 33 34
| private void handleGoodsDeliver(JSONObject msg) { String openId = msg.getString("OpenId"); String outTradeNo = msg.getString("OutTradeNo");
PayOrder order = orderMapper.selectOne(new QueryWrapper<PayOrder>() .eq("open_id", openId) .eq("order_no", outTradeNo) .eq("status", PENDING_PAY)); if (order == null) { throw new BizException("未查询到订单"); }
JSONObject wxPayInfo = msg.getJSONObject("WeChatPayInfo"); order.setPlatformOrderNo(wxPayInfo.getString("MchOrderNo")); order.setTransactionId(wxPayInfo.getString("TransactionId")); order.setPaidAt(Instant.ofEpochSecond(wxPayInfo.getLongValue("PaidTime")) .atZone(ZoneId.of("Asia/Shanghai")).toLocalDateTime());
order.setStatus(DELIVERED); try { Product product = productMapper.selectByCode(order.getProductCode()); long amount = order.getQuantity() * product.getExchangeRatio(); boolean ok = accountService.increaseCoins(order.getUserId(), amount); if (!ok) order.setStatus(DELIVER_FAILED); } catch (Exception e) { order.setStatus(DELIVER_FAILED); log.error("发货加币异常:{}", e.getMessage(), e); } finally { orderMapper.updateById(order); } }
|
要点:
- 幂等:以平台单号
MchOrderNo(即 wx_order_id)作为唯一键;只处理「待支付」状态的订单,重复推送查不到就直接成功返回。
- PaidTime 是秒级时间戳,转
LocalDateTime 时记得指定 Asia/Shanghai 时区。
- 加币失败把订单置为「发货失败」中间态,交给兜底任务处理,订单本身不丢。
六、兜底:定时任务主动查单
微信官方文档:查询创建的订单
消息推送可能因为网络、服务重启等原因丢失。加一个定时任务,每 5 分钟扫一遍「待支付 + 发货失败」的订单,主动调微信 query_order
接口对账:
1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 22 23 24 25 26 27 28 29 30 31 32 33
| @Scheduled(cron = "0 */5 * * * *") public void reconcileOrders() { boolean locked = redisTemplate.opsForValue() .setIfAbsent("pay:reconcile:lock", "1", Duration.ofMinutes(30)); if (!locked) return;
try { List<PayOrder> orders = orderMapper.selectList(new QueryWrapper<PayOrder>() .in("status", PENDING_PAY, DELIVER_FAILED));
String accessToken = getCachedAccessToken(); for (PayOrder order : orders) { QueryOrderResp resp = queryOrder(order.getOpenId(), env, order.getOrderNo(), accessToken); if (resp == null || resp.getErrCode() != 0) continue;
Integer status = resp.getOrder().getStatus(); if (status == 0 || status == 1) continue;
order.setPlatformOrderNo(resp.getOrder().getWxOrderId()); order.setStatus(DELIVERED); if (status == 4) { deliver(order); } orderMapper.updateById(order); } } finally { redisTemplate.delete("pay:reconcile:lock"); } }
|
query_order 接口只需要 pay_sig(uri 为 /xpay/query_order),不需要用户态签名:
| String postBody = param.toJSONString(); String paySig = calcPaySig("/xpay/query_order", postBody, env); String url = "https://api.weixin.qq.com/xpay/query_order" + "?access_token=" + accessToken + "&pay_sig=" + paySig; String resp = HttpRequest.post(url).body(postBody, "application/json") .timeout(30000).execute().body();
|
另外 access_token 一定要做 Redis 缓存(官方有效期 7200 秒,缓存 1 小时左右留余量),否则高频调 token 接口会触发微信频率限制。