退款订单通知

通知方式

参数	说明
请求方式	POST
请求类型	application/json
应答值	大写 SUCCESS 字符串

通知规则

退款成功或失败时，系统会将支付订单状态变化通知到商户的接收地址上。商户需要接收处理该消息并返回应答。

如果收到客户系统的应答不符合规范或超时，支付网关会认为通知失败，并通过一定的策略定期重新发起通知，尽可能提高通知的成功率，但不保证通知最终能成功。 （通知频率为15s/15s/30s/3m/10m/20m/30m/30m/30m/60m/3h/3h/3h/6h/6h - 总计 24h4m）

通知时机

当支付订单状态发生变化时，系统会主动将支付订单状态变化通知到商户的接收地址上。注意：发起退款时，出现退款失败时不会触发通知

支付状态	描述	是否通知
退款中	退款中不会推送通知	否
退款成功	退款成功后会推送通知	是
退款失败	退款失败时会推送通知，但发起退款时返回的失败不会推送通知	是

注意事项

1. 回调地址必须可被支付网关访问
2. 回调地址仅支持http与https协议
3. 如果要对回调消息验签，参照签名规则文档进行验签

通知参数

字段名	变量名	必传	类型	示例值	描述
支付订单号	orderNo	是	String	1753370980523384832	系统生成的订单号
商户支付订单号	bizOrderNo	是	String	P0001	商户传输的订单号
通道支付订单号	outOrderNo	是	String	22212137757334130130	三方支付系统返回的交易号
支付标题	title	是	String
退款号	refundNo	是	String	R0001
商户退款号	bizRefundNo	是	String
通道退款交易号	outRefundNo	是	String
退款通道	channel	是	String	ali_pay
订单金额	orderAmount	是	Integer	100
退款金额	amount	是	Integer	10
退款原因	reason	否	String	测试退款
退款发起时间	refundTime	是	Long	1707317960	退款发起的时间(秒级时间戳)
退款完成时间	refundTime	否	Long	1707317960	退款完成的时间(秒级时间戳)
退款状态	status	是	String	success	见退款状态状态说明
商户扩展参数	attach		String	"{data:1234}"	回调时会原样返回
错误码(订单)	errorCode	否	Integer	0	与状态码(公共)不同，这里返回的是支付订单的错误状态
错误信息(订单)	errorCode	否	String	未启用分账	与错误信息(公共)，这里返回的是支付订单的错误信息提示
签名	sign	是	String	072695d112892e382a7093b81e6a52af
状态码(公共)	code	否	Integer	0	为0表示成功，非0表示失败
错误信息(公共)	msg	否	String	关闭失败	状态非0时会有返回值
响应时间(公共)	resTime	是	Long	123123121	服务返回请求的时间，时间戳(秒级)

通知示例

{
  "code": 0,
  "msg": null,
  "resTime": 1715867834,
  "sign": "abaa68e7e2498dc980962787d09d8a1148fe5be7476d4d550e588401fef24c5c",
  "orderNo": "DEVP24051621525063000002",
  "bizOrderNo": "P1715867447234",
  "outOrderNo": "22240516788144804521",
  "title": "测试支付",
  "refundNo": "DEVR24051621570763000004",
  "bizRefundNo": "DEVR24051621570763000003",
  "outRefundNo": "992405162157086041528",
  "channel": "union_pay",
  "orderAmount": 10000,
  "amount": 100,
  "reason": "",
  "refundTime": null,
  "finishTime": 1715867828,
  "status": "success",
  "attach": null,
  "errorCode": null,
  "errorMsg": null
}

通知接收

可以使用SDK对接收到的通知内容进行反序列和验签，简化消息通知的处理流程。可以使用RefundNoticeModel退款通知实体类来接收数据，使用PaySignUtil进行验签

接收

package org.dromara.daxpay.single.demo.controller;

import cn.bootx.platform.common.core.annotation.IgnoreAuth;
import org.dromara.daxpay.single.sdk.model.notice.PayNoticeModel;
import org.dromara.daxpay.single.sdk.model.notice.RefundNoticeModel;
import io.swagger.v3.oas.annotations.Operation;
import io.swagger.v3.oas.annotations.tags.Tag;
import lombok.RequiredArgsConstructor;
import lombok.extern.slf4j.Slf4j;
import org.springframework.web.bind.annotation.PostMapping;
import org.springframework.web.bind.annotation.RequestBody;
import org.springframework.web.bind.annotation.RequestMapping;
import org.springframework.web.bind.annotation.RestController;

import java.util.Map;

/**
 *
 * @author xxm
 * @since 2024/2/24
 */
@Slf4j
@IgnoreAuth
@Tag(name = "回调测试")
@RestController
@RequestMapping("/demo/callback")
@RequiredArgsConstructor
public class ClientNoticeReceiveController {
    private final DaxPayDemoProperties daxPayDemoProperties;
   
      @Operation(summary = "退款消息")
    @PostMapping("/refund")
    public String refund(@RequestBody Map<String,Object> map) {
        log.info("接收到退款回调消息: {}",map);
        // 转换为对象
        RefundNoticeModel model = BeanUtil.toBean(map, RefundNoticeModel.class);
        log.info("验签结果: {}", PaySignUtil.hmacSha256Sign(model, daxPayDemoProperties.getSignSecret()));
        return "SUCCESS";
    }

    @Operation(summary = "退款消息(对象)")
    @PostMapping("/refundObject")
    public String refund(@RequestBody RefundNoticeModel model) {
        log.info("接收到退款回调消息: {}",model);
        log.info("验签结果: {}", PaySignUtil.hmacSha256Sign(model, daxPayDemoProperties.getSignSecret()));
        return "SUCCESS";
    }
}

验签

// MD5方式验签
PaySignUtil.verifyMd5Sign(model, "123456", model.getSign());
// HmacSha256方式验签
PaySignUtil.verifyHmacSha256Sign(model, "123456", model.getSign());