stefanfeng/huihuiSquare
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases 1 Wiki Activity

Verify Huihui organization payment callbacks against paid orders

Browse Source
This commit is contained in:
stefanfeng
2026-10-20 11:04:27 +08:00
parent 643abd13ea
commit ce18df29b7
4 changed files with 176 additions and 18 deletions
Download Patch File Download Diff File Expand all files Collapse all files
digital-avatar-app/docs/H5_PRODUCTION_DEPLOYMENT.md
+3 -1
View File
@@ -58,6 +58,8 @@ WECHAT_VIRTUAL_SANDBOX_APP_KEY=<沙箱AppKey>
WECHAT_VIRTUAL_APP_KEY=<正式AppKey>
WECHAT_VIRTUAL_OFFER_ID=<offer-id>
WECHAT_VIRTUAL_CALLBACK_TOKEN=<回调校验Token>
HUIHUI_ORG_CALLBACK_SECRET=<会会组织充值支付结果通知验签密钥>
HUIHUI_VIRTUAL_CALLBACK_SECRET=<微信直连虚拟支付转发通知验签密钥>
# 商品 ID 直接使用套餐 ID：Basic、Standard、Professional、Enterprise
AVATAR_DB_DIR=/srv/digital-avatar/data/db
@@ -93,7 +95,7 @@ CHAT_ATTACHMENT_CLEANUP_MINUTES=60
微信小程序虚拟支付的服务端接口为：小程序先通过 `POST /api/token/wechat/session` 交换临时登录码，再由 `POST /api/token/charge`（`payScene=LITE`）返回已签名的 `requestVirtualPayment` 参数；其中 `productId` 直接采用套餐 ID（`Basic`、`Standard`、`Professional`、`Enterprise`）。小程序原生支付页仍需调用 `wx.requestVirtualPayment`，不能仅打开上述 H5 收银台 URL 来完成虚拟支付。微信回调地址配置为 `https://digital.99hui.com/api/token/payment/wechat/virtual/notify`。回调会复核签名、OpenID、环境、商品 ID 与实付金额，退款回调确认后才扣回积分。AppKey、AppSecret、session_key 均不得下发前端或写日志。
如由会会服务端转发微信小程序虚拟支付结果，另有待双方确认的固定回调契约，见 [HUIHUI_VIRTUAL_CALLBACK.md](HUIHUI_VIRTUAL_CALLBACK.md)。该接口使用独立的 `HUIHUI_VIRTUAL_CALLBACK_SECRET`；即使接口代码部署到生产，在协议确认和联调验收前也不得将其视作已上线的支付渠道。
会会组织充值订单和由会会服务端转发的微信小程序虚拟支付结果，分别使用独立的回调地址及验签密钥，见 [HUIHUI_VIRTUAL_CALLBACK.md](HUIHUI_VIRTUAL_CALLBACK.md)。对于组织订单，回调验签后还必须向会会查单确认实付状态与订单详情。即使接口代码部署到生产，在会会发送格式确认和联调验收前也不得将其视作已上线的支付渠道。
管理后台需要配置相同的 `AVATAR_FINANCE_ADMIN_SECRET` 和 `AVATAR_BACKEND_URL=https://digital.99hui.com`。退款只支持整单原路退款；供应商受理后显示“处理中”，收到渠道成功回调（或经渠道后台核对后人工确认）才将订单置为已退款。已消费掉本订单积分时，后台会拒绝主动退款；若渠道外部退款先发生，积分账户允许形成负数以记录欠额并阻止继续消费。
digital-avatar-app/docs/HUIHUI_VIRTUAL_CALLBACK.md
+9 -10
View File
@@ -1,31 +1,30 @@
# 会会微信小程序虚拟支付回调（待双方确认）
# 会会支付回调（待双方确认）
本项目为会会服务端预留固定回调地址：
本项目为会会服务端预留两条固定回调地址：
`POST https://digital.99hui.com/api/token/payment/huihui/virtual/notify`
- 会会组织充值订单（当前 H5 收银台）：`POST https://fat-digital.99hui.com/api/token/payment/huihui/org/notify`（测试环境）
- 微信直连虚拟支付订单：`POST https://digital.99hui.com/api/token/payment/huihui/virtual/notify`（生产环境示例）
回调报文及签名协议尚未与会会确认。以下是本项目实现的拟议对接契约，双方确认并安全交换密钥后才能进行测试支付。接口代码部署与会会联调通过是两个独立状态。它不替代现有微信直连回调 `/api/token/payment/wechat/virtual/notify`。
回调报文及签名协议尚未与会会确认。以下是本项目实现的拟议对接契约，会会服务端必须按此格式发送才能完成联调。接口代码部署与会会联调通过是两个独立状态。它不替代现有微信直连回调 `/api/token/payment/wechat/virtual/notify`。
请求体为 JSON，成功支付示例：
```json
{
"orderNo": "AV202610150000000000000001",
"orderNo": "26102010414409234218",
"paymentNo": "会会侧唯一支付流水号",
"status": "SUCCESS",
"amountCents": 1000,
"productId": "Basic",
"openId": "微信小程序用户 OpenID",
"env": 1
"productId": "Basic"
}
```
`amountCents` 单位为分，`env` 为微信虚拟支付环境（0 正式、1 沙箱）。非成功结果可发送 `status: "FAILED"`，但不会入账。订单号、支付流水号和状态必填；成功结果还必须提供金额、商品 ID、OpenID、环境。仅在订单属于微信虚拟支付，且上述信息与本地订单、套餐、用户一致时入账。重复成功通知不会重复发放积分；同一支付流水号不能用于其他订单。
`amountCents` 单位为分。对于经 `/order/tokenRecharge` 创建的会会组织订单，`orderNo` 可以是会会订单号或数字分身 `AV` 订单号；成功通知必须提供 `amountCents`、`productId` 和 `paymentNo`，无需 `openId`、`env`。服务端会再次向会会查单，要求订单号、支付流水、商品 ID、用户、收费类型、金额一致，且会会支付状态为已付款，才发放积分。对于微信直连订单，仍需 `openId` 和 `env`（0 正式、1 沙箱）一致。非成功结果可发送 `status: "FAILED"`，但不会入账。重复成功通知不会重复发放积分；同一支付流水号不能用于其他订单。
请求头：
- `X-Huihui-Timestamp`：Unix 秒级时间戳，允许与本服务时间相差不超过 300 秒。
- `X-Huihui-Signature`：小写十六进制 HMAC-SHA256，密钥为双方线下安全交换、服务端配置的 `HUIHUI_VIRTUAL_CALLBACK_SECRET`（至少 32 字符），待签名数据为 `时间戳 + 换行符 + 原始请求体字节`。不要重排 JSON 后签名，也不要把密钥发给前端。
- `X-Huihui-Signature`：小写十六进制 HMAC-SHA256，待签名数据为 `时间戳 + 换行符 + 原始请求体字节`。组织充值订单使用服务端配置的 `HUIHUI_ORG_CALLBACK_SECRET`（至少 16 字符），微信直连虚拟支付订单使用独立的 `HUIHUI_VIRTUAL_CALLBACK_SECRET`（至少 32 字符）。不要重排 JSON 后签名，也不要把密钥发给前端。
成功接收返回 HTTP 200，`{"code":200,"message":"success","data":{"received":true,"paid":true}}`。重复通知返回 `duplicate: true`。验签、字段、订单或金额不符返回 HTTP 4xx，会会可按其重试策略处理。服务端未配置密钥时返回 HTTP 503。