小程序里卖虚拟商品(会员、代币、课程、点数)和卖实物是两套完全不同的体系。实物走 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', // 道具直购;代币支付用 short_series_coin
success: () => { /* 只是拉起成功,不代表已发货 */ },
fail: (e) => { /* 用户取消 or 参数错误 */ }
})

不要在前端 success 里直接加币,必须等发货回调。

三、签名规则(最容易错的地方)

虚拟支付有两个签名,用两把不同的 key,混用是最常见的 401:

  1. paySig —— 下单/拉起支付用,用 AppKey(沙箱用沙箱 key)做 HMAC-SHA256
  2. 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
// PHP
$payload = [
'offer_id' => $offerId,
'buy_quantity' => 1,
'env' => 0, // 0 正式 1 沙箱
'currency_type' => 'CNY',
'price' => 600, // 单位:分!写 6 就是 6 分钱
'goods_price' => 600,
'out_trade_no' => $orderNo, // 业务订单号,必须唯一
'attach' => json_encode(['uid' => $uid]),
];
[$body, $sig, $ts, $nonce] = makeSign($payload, $appKey);
// 返回给前端:signData=body, paySig=$sig
1
2
3
4
5
6
7
8
9
10
11
12
13
// Java
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);
// signData=r.body, paySig=r.sign, ts, nonce 一起下发

五、发货回调(这是唯一可信来源)

微信支付成功后会 POST 到你在后台配置的发货推送地址:

1
2
3
4
5
6
7
8
{
"ToUserName": "gh_xxx",
"FromUserName": "oXXXX",
"Event": "xpay_goods_deliver_notify",
"OutTradeNo": "202611180001",
"Env": 0,
"WeRunData": { }
}

处理要点:

  1. 验签 + 解密:用 signature 规则校验,业务字段在加密块里,别直接读明文
  2. 幂等:同一个 OutTradeNo 可能推多次,按订单号加唯一索引
  3. 5 秒内返回成功,超时会重试;耗时逻辑丢队列,先回 {"ErrCode":0,"ErrMsg":"OK"}
  4. 主动补偿:定时任务拿本地待发货订单去 xpay/query_order 对账,别指望推送 100% 到达
1
2
3
4
5
6
7
8
9
10
11
12
13
// PHP:幂等 + 先回包
$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
// Java:数据库唯一索引兜底
@Transactional
public String onDeliver(String outTradeNo) {
try {
deliverMapper.insertIgnore(outTradeNo); // UNIQUE(out_trade_no)
} 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 / 回调超时 定时对账 + 队列重试
账号被封 把虚拟商品包装成实物卖 老老实实走虚拟支付

七、上线前自检

  • iOS 端入口已隐藏(含二级页面、活动弹窗)
  • price 全部以分为单位,前端展示再除以 100
  • 订单号生成规则可回溯(时间 + 用户 id + 随机)
  • 发货回调验签、解密、幂等三件套齐了
  • 有对账任务:本地支付中订单 → 查询接口 → 补发或关单
  • 沙箱环境完整走通一遍(含取消支付、超时、重复回调)

写在最后

虚拟支付这块文档更新较快,字段名(mid / offerId)在不同版本里也换过。上线前一定要拿最新官方文档对一遍字段,尤其是 signature 的构造方式。

代码能跑,坑得自己踩一遍才记得住。