微信小程序虚拟支付实战:从下单签名到发货回调的完整闭环

本文最后更新于:November 21, 2026 pm

目录

微信小程序虚拟支付实战:从下单签名到发货回调的完整闭环

微信官方从2026年开始支持个人用户虚拟支付(Virtual Payment)。 本文记录完整的对接方案,文中代码均为脱敏改写后的示例,仅用于说明方案。


一、整体架构

1
2
3
4
5
6
7
8
9
10
11
12
13
14
┌─────────────┐   1.请求支付参数    ┌──────────────┐
│ 小程序前端 │ ─────────────────► │ Spring 后端 │
│ (uni-app) │ │ │
│ │ ◄─ signData+paySig │ 2.建单/签名 │
│ │ +signature │ │
└──────┬──────┘ └──────┬───────┘
│ 3.wx.requestVirtualPayment │
▼ │ 4.发货推送(消息回调)
┌─────────────┐ ▼
│ 微信虚拟支付 │ ─────────────► 消息回调接口
│ (米大师) │ (解密→发货→更新订单)
└─────────────┘ │
▲ │
└──────── 5.定时兜底 query_order ──┘

关键点:

  1. 前端拿到的四元组(signData / paySig / signature / mode)直接透传给 wx.requestVirtualPayment。
  2. 发货以微信消息推送为准,前端 success 回调只刷新 UI,不做发货。
  3. 定时任务兜底查单,防止消息推送丢失导致用户付了钱没到账。

二、配置项

按环境区分配置文件:

1
2
3
4
5
6
7
8
9
wechat:
app-id: wxxxxxxxxxxxxxxx # 小程序 AppId
app-secret: ******************************** # 小程序密钥
offer-id: 1********* # 虚拟支付 offerId(MP 后台开通后分配)
sandbox-app-key: ******************************** # 沙箱环境 AppKey
prod-app-key: ******************************** # 现网环境 AppKey
# 消息推送配置 - 安全模式
msg-token: ******************************** # 自定义 Token(签名校验用)
msg-aes-key: ******************************************* # 43 位,微信后台生成

配套的配置属性类(示例):

1
2
3
4
5
6
7
8
9
10
11
12
13

@Data
@Component
@ConfigurationProperties(prefix = "wechat")
public class PayProperties {
private String appId;
private String appSecret;
private String offerId;
private String sandboxAppKey; // 沙箱 AppKey
private String prodAppKey; // 现网 AppKey
private String msgToken; // 消息推送 Token
private String msgAesKey; // 消息推送 EncodingAESKey
}

一个实用技巧:运行环境(沙箱/现网)不写在配置文件里,而是放在数据库配置表中(如 pay_env
,0=现网,1=沙箱),好处是可以不发版直接切环境,排查问题时非常方便。


三、下单

3.1 核心流程

前端选完充值金额后,调用下单接口,后端做四件事:

  1. 校验用户状态与道具有效性;
  2. 生成商户订单号 outTradeNo,落库一条「待支付」订单;
  3. 按官方格式拼 signData;
  4. 计算 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) {
// 1. 用户、环境、道具校验(略)
// 2. 生成订单号并落库
String orderNo = generateOrderNo();
PayOrder order = new PayOrder();
...

// 3. 拼 signData(注意:这个 JSON 字符串就是后续参与签名的 postBody)
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);

// 4. 双签名后返回
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
/**
* 支付签名:pay_sig = to_hex(hmac_sha256(app_key, uri + '&' + post_body))
* 注意 uri 不带 query;下单时是固定值 "requestVirtualPayment"(特殊值,不带斜杠)
*/
public String calcPaySig(String uri, String postBody, int env) {
String appKey = (env == SANDBOX) ? props.getSandboxAppKey() : props.getProdAppKey();
return hmacSha256Hex(appKey, uri + "&" + postBody);
}

/**
* 用户态签名:signature = to_hex(hmac_sha256(session_key, post_body))
* 密钥是登录 code2Session 返回的 session_key(随用户登录态保存)
*/
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) // 根据选择的道具请求后端就可生成payData

// 再根据payData拉起支付弹窗
const invokeVirtualPayment = (payData) => {
return new Promise((resolve, reject) => {
wx.requestVirtualPayment({
...payData, // signData / mode / paySig / signature 原样透传
success: (res) => {
uni.showToast({title: '支付成功', icon: 'success'})
resolve(res)
},
fail: (err) => {
// 用户取消也会进 fail:errCode=-2 或 errMsg 含 cancel
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'))
})
}

注意三点:

  1. success 只代表扣款成功,不代表发货完成,到账以服务端回调为准。
  2. 微信已官方支持 Windows 客户端虚拟支付,但要先检测 wx.requestVirtualPayment 是否存在(兼容旧版 3.x Windows 微信),并对
    iOS 做版本校验(微信 ≥ 8.0.68 才支持):
1
2
3
4
5
6
7
8
9
10
11
12
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) {
// -40001 签名错;-40004 AesKey 非法;-40005 appid 不匹配;-40007 解密失败
log.warn("验签或解密失败,忽略:code={}, msg={}", e.getCode(), e.getMessage());
return "error";
}

JSONObject msg = JSON.parseObject(plainMsg);
dispatch(msg.getString("Event"), msg); // 异常时抛出 → 框架返回 500 → 微信自动重试
handleGoodsDeliver(msg); // 订单信息处理逻辑
return "success"; // 回包纯文本 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");

// 1. 定位待支付订单(条件里带状态,天然幂等)
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("未查询到订单"); // 触发微信重试
}

// 2. 回填平台单号与支付时间
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());

// 3. 发货:按道具兑换比例给用户加虚拟币
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(); // Redis 缓存,避免触发微信频率限制
for (PayOrder order : orders) {
QueryOrderResp resp = queryOrder(order.getOpenId(), env, order.getOrderNo(), accessToken);
if (resp == null || resp.getErrCode() != 0) continue;

// status: 0/1=未支付 2=已支付待发货 4=已发货
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),不需要用户态签名:

1
2
3
4
5
6
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 接口会触发微信频率限制。