# 微信个人主体虚拟支付验收

依据：[微信开放文档：虚拟支付（个人）](https://developers.weixin.qq.com/miniprogram/dev/platform-capabilities/business-capabilities/virtual-payment/person)

核对日期：2026-10-01。当前仓库是小程序客户端和本地管理台，不含 `api.duolapi.cn` 支付服务端。`useMock` 仍为 `true`，以下状态严格按可见代码和配置判定，不以模拟器成功代替真实支付验收。

## 部署前检查清单

| # | 官方检查项 | 状态 | 证据 / 未完成原因 |
|---|---|---|---|
| 1 | 个人主体、中国大陆居民身份证、「工具」类目、认证和备案均符合开放条件 | 用户报告已认证；其余待平台核验 | 项目仅配置 AppID `wx2b8510385d13d88c`。用户此前报告已完成认证/开通，但本次没有微信 MP 后台证据；主体证件、类目和备案状态仍须在目标账号核对。 |
| 2 | 已了解并告知全终端月支付限额 10 万元 | 代码已展示 | 套餐页显示 10 万元限额；发布后还需确认文案对用户可见。 |
| 3 | MP 后台虚拟支付已开通 | 待平台操作 | 需在小程序 MP 平台「支付与交易 - 虚拟支付」确认审核及签约状态。 |
| 4 | 已取得 AppID、OfferID、现网 AppKey | 部分完成 | AppID 已配置；OfferID、现网 AppKey 未在本项目暴露或提供证据。AppKey 必须只配置在服务端密钥设置中。 |
| 5 | 如需 iOS 支付，已配置小程序简称 | 待平台核验 | 需在账号设置配置简称，并在虚拟支付基本配置开通 Apple IAP。客户端已限制 iOS 微信版本至少 8.0.68。 |
| 6 | 消息推送接收服务已部署 | 后端已部署；微信侧接入待完成 | New API 部署记录显示 `/api/wechat-virtualpay/notify` 已部署，通知验签/解密和本地测试已实现。目标小程序后台 URL 配置、平台握手及真实消息接收尚无证据。 |
| 7 | MP 后台已配置发货推送 URL，并完成测试支付 | 未完成 | 需要在目标 MP 后台配置已部署 URL，并由该 AppID、已发布商品完成测试支付和通知验收。 |
| 8 | 服务端验签与官方签名示例一致 | 本地/隔离测试通过；微信真通知待验 | New API 验收记录包含官方 HMAC/AES 样例、原文签名、篡改及 AppID 不匹配拒绝测试；真实目标小程序加密通知联调未完成。小程序端仅验证服务端签名字段格式与订单快照。 |
| 9 | 发货推送按 `wx_order_id` 幂等 | 本地/隔离数据库测试通过；真实通知待验 | New API 记录显示已做唯一平台单号、并发入账、事务回滚、租约/缓存恢复测试。真实微信重复通知仍待实测。 |
| 10 | 前端 `wx.requestVirtualPayment` 已打通，支付成功并收到发货推送 | 客户端已对接；真机闭环未验 | 前端使用已部署服务端的 `scene -> mini/session -> mini/pay`，校验签名数据与订单快照后原样调用；真实付款与发货推送尚未验证。当前 `useMock: true`，不发起真实扣款。 |
| 11 | `query_order` 兜底查单已就绪 | 后端已部署且隔离测试通过；真实漏通知待验 | New API 记录包含模拟查单入账、补发货和缓存修复测试；客户端轮询 scoped `/mini/status`。真实微信漏通知后的 `xpay/query_order` 补偿尚未实测。 |
| 12 | 已告知退款规则、结算周期和费率（Android 等 1%、iOS 12%） | 代码已展示 | 套餐页显示费率、结算周期及 Android / iOS 退款差异。 |
| 13 | 上线后小额真单验证「支付 - 推送 - 发货 - 账单一致」 | 未完成 | 必须使用已签约的目标 AppID/OfferID、已发布商品、生产服务端及真实设备完成。 |

## 代码核验

- 已配置目标 AppID：`project.config.json`。
- 客户端按已部署的 `/api/user/wechat-virtualpay/orders`、`/mini/session`、`/mini/pay`、`/mini/status` 合同实现：`config/index.js`。
- 创建订单仅提交服务端预设金额和幂等 `request_id`；服务端订单快照决定产品、价格和到账额度。
- 客户端验证 `mode=short_series_goods`、CNY、`env=0`、道具、单笔分价、64 位 HMAC 格式，并核对签名中的 `outTradeNo/goodsPrice` 与 scoped session 订单快照一致。
- `signData` 不会在客户端重序列化；按原字节传给 `wx.requestVirtualPayment`。支付完成/取消均以 scoped `/mini/status` 返回为准。
- iOS 微信低于 8.0.68 时阻止调起。
- 支付页 scene 校验为 32 位小写十六进制能力串；仅持有有效 scoped session 的入口可显示付款按钮。单独通过订单号进入只读订单详情并可刷新服务端状态。
- 套餐页向用户展示月限额、平台费率和退款规则。
- 语法、客户端契约模拟测试通过；这不代表微信支付、发货回调或账务验收通过。

## 上线阻断项

1. 当前套餐是积分/额度形式。官方个人主体指南限定 `short_series_goods` 道具直购并提示不要引入代币模式。必须先确认微信平台审核通过的商品与实际 AI 服务权益映射，不得将钱包余额或代币充值改名伪装为道具。
2. New API 部署记录显示虚拟支付模块、加密推送验签、`wx_order_id` 幂等和查单补偿已部署，相关本地/隔离测试通过；当前业务 gate 关闭、OfferID/AppKey 和实际商品映射未配置。小程序用户态下单依赖的 `/api/wechat-virtualpay/mini/auth` 路由也尚未证实存在，因此需先确认或补齐官方 `wx.login code -> UserAuth` 登录桥接。凭据只在 New API RootAuth 支付设置中写入，不放入小程序。
3. 按微信后台配置消息推送 URL，完成真实签名/加密通知校验、`wx_order_id` 幂等发货和漏通知查单补偿，再执行小额真单和账单核对。
4. 在以上步骤完成前保持 `useMock: true`，不要开放真实收款。