Genarrative/docs/【技术方案】微信虚拟支付接入-2026-05-26.md

微信虚拟支付接入

更新时间：2026-05-26

接入口径

• 泥点充值在微信小程序 WebView 内走 wechat_mp_virtual，由小程序页调用 wx.requestVirtualPayment 的 short_series_coin 模式。
• 会员商品在微信小程序 WebView 内同样走 wechat_mp_virtual，由小程序页调用 wx.requestVirtualPayment 的 short_series_goods 模式，并在 signData 内带 productId 与 goodsPrice。
• H5 与桌面微信环境仍分别走 wechat_h5 / wechat_native，不进入虚拟支付链路。
• session_key 只保存在后端认证仓储内，用于计算虚拟支付用户态签名，不下发给前端。
• 客户端支付成功回调只代表已拉起支付并返回成功；最终到账仍以后端微信通知或查询确认后写入订单为准。

关键文件

• 前端渠道选择：src/services/payment/paymentPlatform.ts
• 充值入口：src/components/rpg-entry/RpgEntryHomeView.tsx
• 小程序支付承接页：miniprogram/pages/wechat-pay/index.shared.js
• API 契约：packages/shared/src/contracts/runtime.ts、server-rs/crates/shared-contracts/src/runtime.rs
• 后端下单与签名：server-rs/crates/api-server/src/runtime_profile.rs
• 微信登录态保存：server-rs/crates/platform-auth/src/lib.rs、server-rs/crates/module-auth/src/lib.rs

后端配置

生产接入虚拟支付至少需要：

WECHAT_PAY_ENABLED=true
WECHAT_PAY_PROVIDER=real
WECHAT_MINI_PROGRAM_VIRTUAL_PAYMENT_OFFER_ID=<微信虚拟支付 offerId>
WECHAT_MINI_PROGRAM_VIRTUAL_PAYMENT_APP_KEY=<现网 AppKey>
WECHAT_MINI_PROGRAM_VIRTUAL_PAYMENT_SANDBOX_APP_KEY=<沙箱 AppKey，可选>
WECHAT_MINI_PROGRAM_VIRTUAL_PAYMENT_ENV=0

WECHAT_MINI_PROGRAM_VIRTUAL_PAYMENT_ENV=0 表示现网，1 表示沙箱。后端会按 env 选择 AppKey，并生成：

• signData：传给 wx.requestVirtualPayment 的订单数据。
• paySig：HMAC-SHA256(appKey, "requestVirtualPayment&" + signData) 的小写 hex。
• signature：HMAC-SHA256(session_key, signData) 的小写 hex。
• 会员直购 signData 额外包含 productId 和 goodsPrice；goodsPrice 使用后端商品配置价，和微信后台道具价格校验保持一致。

验收命令

npm exec vitest run miniprogram/pages/wechat-pay/index.test.js src/services/payment/paymentPlatform.test.ts src/components/rpg-entry/RpgEntryHomeView.recharge.test.tsx
cargo check -p api-server --manifest-path server-rs/Cargo.toml
cargo test -p shared-contracts --manifest-path server-rs/Cargo.toml create_profile_recharge_order_response_serializes_virtual_wechat_payloads
npm run typecheck
npm run check:encoding

注意事项

• 旧微信登录快照可能没有 session_key，用户需要在小程序内重新登录后再发起虚拟支付。
• 小程序充值商品全部映射到虚拟支付；泥点使用 short_series_coin，会员使用 short_series_goods。
• 小程序页必须保留普通支付与虚拟支付双分支，按 pay params 字段判断调用 wx.requestPayment 或 wx.requestVirtualPayment。