# 会会组织充值支付回调

当前 H5 收银台组织充值订单，对会会提供的测试环境回调地址只有：

`POST https://fat-digital.99hui.com/api/token/payment/huihui/org/notify`

其他历史接收路由仅供服务端兼容旧请求，不作为提供给会会的回调地址，也不应配置为新订单的通知地址。

回调报文及签名协议仍须按双方联调结果确认。以下是本项目实现的接收契约；接口部署与完整支付联调通过是两个独立状态。微信直连虚拟支付回调属于另一条支付链路，不使用本文的组织充值回调地址。

请求体为 JSON，成功支付示例：

```json
{
  "orderNo": "26102010414409234218",
  "paymentNo": "会会侧唯一支付流水号",
  "status": "SUCCESS",
  "amountCents": 1000,
  "productId": "Basic"
}
```

`amountCents` 单位为分。对于经 `/order/tokenRecharge` 创建的会会组织订单，`orderNo` 可以是会会订单号或数字分身 `AV` 订单号；成功通知必须提供 `amountCents`、`productId` 和 `paymentNo`，无需 `openId`、`env`。服务端会再次向会会查单，要求订单号、支付流水、商品 ID、用户、收费类型、金额一致，且会会支付状态为已付款，才发放积分。非成功结果可发送 `status: "FAILED"`，但不会入账。重复成功通知不会重复发放积分；同一支付流水号不能用于其他订单。

请求头：

- `X-Huihui-Timestamp`：Unix 秒级时间戳，允许与本服务时间相差不超过 300 秒。
- `X-Huihui-Signature`：小写十六进制 HMAC-SHA256，待签名数据为 `时间戳 + 换行符 + 原始请求体字节`。组织充值订单使用服务端配置的 `HUIHUI_ORG_CALLBACK_SECRET`（至少 16 字符）。不要重排 JSON 后签名，也不要把密钥发给前端。

成功通知经签名及本地订单信息核对后，先持久保存并立即返回 HTTP 200、`{"received":true,"paid":false,"awaitingProvider":true}`；回调入口**不等待会会查单**，也**不立即发放积分**。后台仅针对已保存的通知做有上限的延迟复核，待会会查单确认已支付、订单号与支付流水等字段一致后才入账。已入账订单的重复通知返回 `duplicate: true`，不会重复发放积分。验签、字段、订单或金额不符返回 HTTP 4xx。服务端未配置密钥时返回 HTTP 503。

上线前需由会会确认：其服务端是否能按此格式签名并发送通知、支付成功状态与支付流水号字段的正式定义、失败通知及重试/超时策略。小程序支付发起和退款仍需独立对接和验收；仅完成此回调不代表虚拟支付全流程已可用。