回调通知

支付、退款、转账等资金类接口通常都会通过异步通知回传最终状态。业务系统需要把通知处理设计成“验签优先、幂等优先、快速返回”。

通知处理原则

1. 校验请求来源和签名。
2. 根据平台单号或商户单号做幂等判断。
3. 更新本地订单、资金流水和业务状态。
4. 成功后返回纯文本 success。
5. 失败时返回非 success 内容，让平台稍后重试。

常见通知类型

类型	来源参数	说明
支付通知	payOrderId / mchOrderNo	支付成功后回调
退款通知	refundOrderId / mchRefundNo	退款成功或失败后回调
转账通知	transferId / mchOrderNo	转账完成后回调

返回规范

网关类文档通常要求通知处理完成后返回字符串 success。为避免重试，建议注意以下细节：

• 返回体不要附带 JSON 包装。
• 不要输出额外空格、换行和 HTML。
• 业务未完成时不要提前返回成功。

处理示例

import express from 'express'

const app = express()
app.use(express.urlencoded({ extended: false }))

app.post('/pay/notify', async (req, res) => {
  const payload = req.body

  const verified = verifyNotifySign(payload)
  if (!verified) {
    res.status(400).send('fail')
    return
  }

  const processed = await hasProcessed(payload.payOrderId)
  if (!processed) {
    await savePaymentResult(payload)
  }

  res.send('success')
})

重试与幂等

• 支付网关一般会在首次失败后进行多次延迟重试。
• 幂等判断建议优先使用平台单号，其次使用商户单号。
• 入账、发券、积分、发货等后置动作也要加幂等保护。

日志建议

• 记录原始通知参数、签名结果、幂等判断结果和业务处理耗时。
• 对失败通知做告警，防止长时间堆积重试。
• 对成功但重复的通知单独打标签，便于排查业务侧重复返回问题。