小程序里卖虚拟商品(会员、代币、课程、点数)和卖实物是两套完全不同的体系。实物走 wx.requestPayment,虚拟商品走微信虚拟支付(俗称道具直购 / 代币支付),而且iOS 端不允许在应用内直接完成虚拟支付。
这篇把接入流程、签名规则、发货回调,以及 PHP / Java 两套后端实现写清楚,坑放在最后。

一、先搞清楚能力边界
| 项目 |
说明 |
| 适用端 |
仅 Android。iOS 端不允许虚拟支付,只能在 UI 上隐藏入口或引导到 H5/客服 |
| 主体要求 |
企业/个体工商户,需在「小程序后台 → 功能 → 虚拟支付」申请开通 |
| 核心凭证 |
offerId(老文档叫 mid)、AppKey、沙箱 AppKey |
| 前端 API |
wx.requestVirtualPayment(基础库 2.19.2+) |
一句话记住:金额、余额、发货全部由服务端说了算,前端只负责拉起支付框。
二、端上如何判断
1 2 3 4 5 6 7 8 9 10 11 12 13
| const { platform } = wx.getSystemInfoSync() if (platform === 'ios') { return } wx.requestVirtualPayment({ signData: res.signData, paySig: res.paySig, signature: res.signature, mode: 'short_series_goods', success: () => { }, fail: (e) => { } })
|
不要在前端 success 里直接加币,必须等发货回调。
三、签名规则(最容易错的地方)
虚拟支付有两个签名,用两把不同的 key,混用是最常见的 401:
paySig —— 下单/拉起支付用,用 AppKey(沙箱用沙箱 key)做 HMAC-SHA256
signature —— 调用 OpenAPI(查询余额、扣币、发货)用,用 access_token 体系 + 用户 SessionKey
待签串格式:POST\n/appid/path\n时间戳\n随机串\nbody,再做 HMAC-SHA256 后 hex 小写。
PHP 版签名
1 2 3 4 5 6 7 8 9 10 11
| function makeSign(array $payload, string $appKey): array { $ts = time(); $nonce = bin2hex(random_bytes(8)); $body = json_encode($payload, JSON_UNESCAPED_UNICODE | JSON_UNESCAPED_SLASHES);
$signStr = "POST\n/appid/xpay/pay\n{$ts}\n{$nonce}\n{$body}"; $sig = hash_hmac('sha256', $signStr, $appKey);
return [$body, $sig, $ts, $nonce]; }
|
Java 版签名
1 2 3 4 5 6 7 8 9 10 11 12 13 14
| public static SignResult sign(String path, Map<String,Object> payload, String appKey) throws Exception { long ts = System.currentTimeMillis() / 1000; String nonce = UUID.randomUUID().toString().replace("-", "").substring(0, 16); String body = new ObjectMapper().writeValueAsString(payload);
String signStr = "POST\n" + path + "\n" + ts + "\n" + nonce + "\n" + body; Mac mac = Mac.getInstance("HmacSHA256"); mac.init(new SecretKeySpec(appKey.getBytes(StandardCharsets.UTF_8), "HmacSHA256")); byte[] raw = mac.doFinal(signStr.getBytes(StandardCharsets.UTF_8));
StringBuilder hex = new StringBuilder(); for (byte b : raw) hex.append(String.format("%02x", b)); return new SignResult(body, hex.toString(), ts, nonce); }
|
四、服务端下单(道具直购)
1 2 3 4 5 6 7 8 9 10 11 12 13
| $payload = [ 'offer_id' => $offerId, 'buy_quantity' => 1, 'env' => 0, 'currency_type' => 'CNY', 'price' => 600, 'goods_price' => 600, 'out_trade_no' => $orderNo, 'attach' => json_encode(['uid' => $uid]), ]; [$body, $sig, $ts, $nonce] = makeSign($payload, $appKey);
|
1 2 3 4 5 6 7 8 9 10 11 12 13
| Map<String,Object> payload = new LinkedHashMap<>(); payload.put("offer_id", offerId); payload.put("buy_quantity", 1); payload.put("env", 0); payload.put("currency_type", "CNY"); payload.put("price", 600); payload.put("goods_price", 600); payload.put("out_trade_no", orderNo); payload.put("attach", "{\"uid\":" + uid + "}");
SignResult r = SignUtil.sign("/appid/xpay/pay", payload, appKey);
|
五、发货回调(这是唯一可信来源)
微信支付成功后会 POST 到你在后台配置的发货推送地址:
1 2 3 4 5 6 7 8
| { "ToUserName": "gh_xxx", "FromUserName": "oXXXX", "Event": "xpay_goods_deliver_notify", "OutTradeNo": "202611180001", "Env": 0, "WeRunData": { } }
|
处理要点:
- 验签 + 解密:用
signature 规则校验,业务字段在加密块里,别直接读明文
- 幂等:同一个
OutTradeNo 可能推多次,按订单号加唯一索引
- 5 秒内返回成功,超时会重试;耗时逻辑丢队列,先回
{"ErrCode":0,"ErrMsg":"OK"}
- 主动补偿:定时任务拿本地待发货订单去
xpay/query_order 对账,别指望推送 100% 到达
1 2 3 4 5 6 7 8 9 10 11 12 13
| $orderNo = $data['OutTradeNo'] ?? ''; if (!$orderNo) { echo json_encode(['ErrCode'=>0,'ErrMsg'=>'OK']); exit; }
$affected = $pdo->prepare( "INSERT IGNORE INTO pay_deliver(out_trade_no, created_at) VALUES (?, NOW())" )->execute([$orderNo]);
if ($affected) { Queue::push('deliver', $orderNo); } echo json_encode(['ErrCode'=>0,'ErrMsg'=>'OK']);
|
1 2 3 4 5 6 7 8 9 10 11
| @Transactional public String onDeliver(String outTradeNo) { try { deliverMapper.insertIgnore(outTradeNo); } catch (DuplicateKeyException e) { return "ok"; } mqTemplate.send("deliver", outTradeNo); return "ok"; }
|

六、常见问题清单
| 现象 |
原因 |
处理 |
前端拉起失败 -1 |
signData 不是原样字符串下发,被 JSON 再包了一层 |
下发原字符串,别二次序列化 |
| 401 / 签名错误 |
paySig 用了 SessionKey,或 signature 用了 AppKey |
两把 key 分清 |
| 沙箱能付、正式 400 |
env 字段与实际 key 不匹配 |
沙箱 key 配 env=1 |
| 金额差了 100 倍 |
单位是分,不是元 |
price 传分 |
| iOS 能点充值 |
没按 platform 隐藏入口 |
iOS 直接隐藏 |
| 重复加币 |
没做幂等 |
订单号唯一索引 |
| 发货丢了 |
依赖前端 success / 回调超时 |
定时对账 + 队列重试 |
| 账号被封 |
把虚拟商品包装成实物卖 |
老老实实走虚拟支付 |
七、上线前自检
写在最后
虚拟支付这块文档更新较快,字段名(mid / offerId)在不同版本里也换过。上线前一定要拿最新官方文档对一遍字段,尤其是 signature 的构造方式。
代码能跑,坑得自己踩一遍才记得住。