异步通知接收文档

1. 概述

当支付状态或退款状态发生变化时，系统会主动向商户指定的回调地址发送异步通知，确保商户及时获得交易结果。

配置说明： 需要在商户后台配置通知地址才能接收通知

登录商户后台 → 支付管理 → 收银台 → 开发对接 → 异步通知

配置你的通知接收地址

2. 通知格式

2.1 HTTP请求信息

请求方式：POST

Content-Type：application/json

超时设置：15秒

重试机制：失败时会重试，间隔递增（1分钟、5分钟、10分钟、30分钟、1小时）

2.2 请求头参数

参数名称	说明	示例
client-id	应用ID	EW_N5119728343
client-time	时间戳（秒级）	1726647994
client-sign	签名验证	7234A7113E95D263F9B69D27994B5FDC

3. 通知类型

3.1 支付通知 (type: "pay")

通知内容：

{
    "type": "pay",
    "data": {
        "merchant_code": "EW_N8253365987",
        "order_no": "20250918152628442000545544",
        "order_amt": 100.00,
        "discount_amt": 0.00,
        "pay_amt": 100.00,
        "pay_status": 1,
        "pay_type": 0,
        "pay_time": "2025-09-18 15:26:34",
        "pay_fee": 0.30,
        "goods": "测试商品",
        "remark": "订单备注",
        "third_trade_no": "4200002822202509268881118206",
        "shop_trade_no": "2509260660126077227487233"
    }
}

字段说明：

字段名	类型	说明
merchant_code	String	门店编号
order_no	String	订单编号
order_amt	BigDecimal	订单金额
discount_amt	BigDecimal	优惠金额
pay_amt	BigDecimal	支付金额
pay_status	Integer	支付状态：0未支付 1已支付 2支付失败 3支付中
pay_type	Integer	支付方式：0微信 1支付宝
pay_time	String	支付时间
pay_fee	BigDecimal	支付手续费
goods	String	商品名称
remark	String	订单备注
third_trade_no	String	微信、支付宝交易单号
shop_trade_no	String	支付通道单号（支付凭证中商户单号）

3.2 退款通知 (type: "refund")

通知内容：

{
    "type": "refund", 
    "data": {
        "merchant_code": "EW_N8253365987",
        "order_no": "20250918152628442000545544",
        "refund_no": "20250918152628442000545545",
        "refund_amt": 50.00,
        "refund_fee": 0.15,
        "refund_status": 0,
        "refund_type": 0,
        "refund_time": "2025-09-18 16:30:25",
        "goods": "测试商品",
        "remark": "用户申请退款",
        "third_trade_no": "2509260660166428847886336"
    }
}

字段说明：

字段名	类型	说明
merchant_code	String	门店编号
order_no	String	支付单号
refund_no	String	退款单号
refund_amt	BigDecimal	退款金额
refund_fee	BigDecimal	退款手续费（交易退回手续费）
refund_status	Integer	退款状态：0退款成功 1退款失败
refund_type	Integer	支付方式：0微信 1支付宝
refund_time	String	退款时间
goods	String	商品名称
remark	String	退款备注
third_trade_no	String	微信、支付宝交易单号

4. 签名验证

4.1 验证算法

签名原文 = client-id + client-time + client-key + body
验证签名 = MD5(签名原文).toUpperCase()

验证步骤：

获取请求头中的 client-sign

使用你的 client-key 重新计算签名

对比两个签名是否一致

4.2 代码示例

Python 验证示例：

Java 验证示例：

Node.js 验证示例：

5. 响应要求

5.1 成功响应

商户接收到通知后，需返回以下内容表示接收成功：

HTTP状态码：200

响应内容：ok（纯文本）

5.2 失败处理

如果返回非200状态码或响应内容不是"ok"，系统会认为通知失败并进行重试。

6. 业务处理建议

6.1 幂等性处理

由于网络问题可能导致重复通知，建议在业务层面做幂等性处理：

6.2 异步处理

建议将耗时的业务逻辑放到异步队列中处理：

7. 开发调试

7.1 本地测试工具

推荐使用 ngrok 将本地服务暴露到公网进行测试：

7.2 日志记录建议

7.3 常见问题

Q: 收到重复通知怎么办？

建议在业务层面做幂等性处理，同一订单号的通知只处理一次

Q: 签名验证总是失败？

检查 client-key 是否正确

确认body内容完全一致（包括空格、换行）

验证字符编码是否为UTF-8

Q: 如何区分支付和退款通知？

通过 type 字段区分：pay 为支付通知，refund 为退款通知

Q: 退款通知中的退款状态含义？

0 表示退款成功，1 表示退款失败

8. 安全建议

✅ 必须验证签名，拒绝未通过验证的通知

✅ 建议设置白名单IP（如需要可联系技术支持获取）

✅ 敏感操作建议增加二次验证（如调用查询接口确认）

✅ 记录所有通知日志，便于问题排查

✅ 实现幂等性处理，避免重复处理同一通知

⚠️ 不要在通知处理中执行耗时操作，建议异步处理

异步通知

异步通知接收文档#

1. 概述#

2. 通知格式#

2.1 HTTP请求信息#

2.2 请求头参数#

3. 通知类型#

3.1 支付通知 (type: "pay")#

3.2 退款通知 (type: "refund")#

4. 签名验证#

4.1 验证算法#

4.2 代码示例#

5. 响应要求#

5.1 成功响应#

5.2 失败处理#

6. 业务处理建议#

6.1 幂等性处理#

6.2 异步处理#

7. 开发调试#

7.1 本地测试工具#

7.2 日志记录建议#

7.3 常见问题#

8. 安全建议#