异步通知（notify_url）

说明

  • 调用方向：宝付 → 商户（POST 至进线时传入的 notify_url）
  • 通知格式：JSON Body，Content-Type: application/json
  • 安全：商户须验签；含敏感字段时按统一网关规范解密
  • 地址约定：
    • 扣款通知、状态变更通知：使用签约时上送的 notify_url
    • 退款通知：使用退款发起时上送的 notify_url；未上送则不通知，不回落签约通知地址
    • 绑卡成功通知：使用 190 绑卡 H5 收银台上送的 notify_url，与签约 notify_url 相互独立
  • 失败重试：商户须应答 HTTP 状态码 200，响应体为字符串 OK；否则系统按固定频率重试。幂等键须按 event_type + 业务主键（见 §2.5），禁止仅用签约 out_trade_no 覆盖全部通知类型

Header 参数

参数名 类型 必填 描述
Baofu-Timestamp string true 秒级 Unix 时间戳
Baofu-Nonce string true 随机串
Baofu-Serial string true 证书序列号
Request-ID string true 通知链路 ID
Baofu-Signature-Type string true 签名算法
Baofu-Signature string true 签名值

商户身份 Header（不在 Body 中重复）：通知随请求回传进线时的 Baofu-Mch-ID；若进线时上送了 Baofu-App-ID 则一并回传，未上送则通知中不出现该头。

商户验签（待签串）

与开放网关应答侧约定一致：

  1. 取 Header 中秒级时间戳、随机串；数字信封若本次通知无则传空串（拼接时仍保留单独一行）。
  2. 取 HTTP Body 原始字节 对应的 JSON 字符串（与接收到的完全一致，勿重新格式化）。
  3. 按 「时间戳 + \n + 随机串 + \n + 数字信封 + \n + Body + \n」 拼接（每行以换行结束，包括最后一行）。
  4. 按 Baofu-Signature-Type 使用约定证书验签 Baofu-Signature。

对应 Header 分别为 Baofu-Timestamp、Baofu-Nonce；数字信封无则空串，拼接时仍占一行。

商户应答

验签通过后处理业务。须应答 HTTP 状态码 200，响应体为字符串 OK；否则系统按固定频率重试。幂等键按通知类型区分（绑卡成功可用 out_trade_no；扣款用 deduction_no；订阅用 subscription_no+状态；退款用 out_refund_no/refund_no），禁止仅用签约 out_trade_no 覆盖全部通知类型。

应答示例

200 OK

OK

商户处理建议

2.5 商户处理建议

  1. 验签、解密通过后更新本地状态，与查单结果按对应业务主键幂等合并。
  2. 须应答 HTTP 状态码 200，响应体为字符串 OK；否则系统按固定频率重试。
  3. 本地幂等按 event_type + 业务主键：PAYMENT→deduction_no；SUBSCRIPTION→subscription_no+状态；REFUND→out_refund_no/refund_no；绑卡成功→out_trade_no。禁止只用签约 out_trade_no 覆盖全部通知。
  4. 绑卡成功通知：解密 payment_protocol_no 后用于签约；与扣款/状态变更通知相互独立。