基础支付
JSAPI支付
APP支付
H5支付
Native支付
小程序支付
合单支付
付款码支付
经营能力
微信支付分(公共API)
微信支付分(免确认预授权模式)
微信支付分(需确认模式)
支付即服务
行业方案
智慧商圈
微信支付分停车服务
电子发票
营销工具
代金券
商家券
委托营销
支付有礼
小程序发券插件
H5发券
图片上传(营销专用)
现金红包
资金应用
商家转账到零钱
分账
风险合规
消费者投诉2.0
其他能力
清关报关
图片上传
视频上传
微信支付平台证书

退款结果通知API

最新更新时间:2021.01.15 版本说明


退款状态改变后,微信会把相关退款结果发送给商户。

注意:

对后台通知交互时,如果微信收到应答不是成功或超时,微信认为通知失败,微信会通过一定的策略定期重新发起通知,尽可能提高通知的成功率,但微信不保证通知最终能成功


• 同样的通知可能会多次发送给商户系统。商户系统必须能够正确处理重复的通知。 推荐的做法是,当商户系统收到通知进行处理时,先检查对应业务数据的状态,并判断该通知是否已经处理。如果未处理,则再进行处理;如果已处理,则直接返回结果成功。在对业务数据进行状态检查和处理之前,要采用数据锁进行并发控制,以避免函数重入造成的数据混乱。

• 如果在所有通知频率后没有收到微信侧回调。商户应调用查询订单接口确认订单状态。


特别提醒:商户系统对于开启结果通知的内容一定要做签名验证,并校验通知的信息是否与商户侧的信息一致,防止数据泄露导致出现“假通知”,造成资金损失。

接口说明

适用对象:直连商户

请求方式:POST

请求URL:该链接是通过[申请退款接口]指定的notify_url,必须为https协议。如果链接无法访问,商户将无法接收到微信通知。 通知url必须为直接可访问的url,不能携带参数。示例:“https://pay.weixin.qq.com/wxpay/pay.action”

通知规则

商户退款完成后,微信会把相关退款结果和用户信息发送给清算机构,清算机构需要接收处理后返回应答成功,然后继续给异步通知到下游从业机构。

对后台通知交互时,如果微信收到应答不是成功或超时,微信认为通知失败,微信会通过一定的策略定期重新发起通知,尽可能提高通知的成功率,但微信不保证通知最终能成功。(通知频率为15s/15s/30s/3m/10m/20m/30m/30m/30m/60m/3h/3h/3h/6h/6h - 总计 24h4m)

通知报文

退款结果通知是以POST 方法访问商户设置的通知url,通知的数据以JSON 格式通过请求主体(BODY)传输。通知的数据包括了加密的支付结果详情
(注:由于涉及到回调加密和解密,商户必须先设置好apiv3密钥后才能解密回调通知,apiv3密钥设置文档指引详见APIv3密钥设置指引

参数解密

下面详细描述对通知数据进行解密的流程:

  1. 1、用商户平台上设置的APIv3密钥 【微信商户平台—>账户设置—>API安全—>设置APIv3密钥】 ,记为key;
  2. 2、针对resource.algorithm中描述的算法(目前为AEAD_AES_256_GCM),取得对应的参数nonce和associated_data;
  3. 3、使用key、nonce和associated_data,对数据密文resource.ciphertext进行解密,得到JSON形式的资源对象。

注: AEAD_AES_256_GCM算法的接口细节,请参考rfc5116。微信支付使用的密钥key长度为32个字节,随机串nonce长度12个字节,associated_data长度小于16个字节并可能为空字符串。

通知参数

参数名 变量 类型[长度限制] 必填 描述
通知ID id string[1,36] 通知的唯一ID
示例值:EV-2018022511223320873
通知创建时间 create_time string[1,32] 通知创建的时间,遵循rfc3339标准格式,格式为yyyy-MM-DDTHH:mm:ss+TIMEZONE,yyyy-MM-DD表示年月日,T出现在字符串中,表示time元素的开头,HH:mm:ss表示时分秒,TIMEZONE表示时区(+08:00表示东八区时间,领先UTC 8小时,即北京时间)。例如:2015-05-20T13:29:35+08:00表示,北京时间2015年5月20日13点29分35秒。
示例值:2018-06-08T10:34:56+08:00
通知类型 event_type string[1,32] 通知的类型:
REFUND.SUCCESS:退款成功通知
REFUND.ABNORMAL:退款异常通知
REFUND.CLOSED:退款关闭通知
示例值:REFUND.SUCCESS
通知简要说明 summary string[1,16] 通知简要说明
示例值:退款成功
通知数据类型 resource_type string[1,32] 通知的资源数据类型,支付成功通知为encrypt-resource
示例值:encrypt-resource
+通知数据 resource object 通知资源数据
json格式,见示例
参数名 变量 类型[长度限制] 必填 描述
加密算法类型 algorithm string[1,32] 对开启结果数据进行加密的加密算法,目前只支持AEAD_AES_256_GCM
示例值:AEAD_AES_256_GCM
加密前的对象类型 original_type string[1,32] 加密前的对象类型,退款通知的类型为refund
示例值:refund
数据密文 ciphertext string[1,1048576] Base64编码后的开启/停用结果数据密文
示例值:fdasfsadsadsalkja484w
附加数据 associated_data string[1,16] 附加数据
示例值:fdasdsadsafcsflkja484w
随机串 nonce string[1,16] 加密使用的随机串
示例值:fdasfjihihihlkja484w

通知签名

加密不能保证通知请求来自微信。微信会对发送给商户的通知进行签名,并将签名值放在通知的HTTP头Wechatpay-Signature。商户应当验证签名,以确认请求来自微信,而不是其他的第三方。签名验证的算法请参考 《微信支付API v3签名验证》

回调示例

退款通知


{
    "id":"EV-2018022511223320873",
    "create_time":"2018-06-08T10:34:56+08:00",
    "resource_type":"encrypt-resource",
    "event_type":"REFUND.SUCCESS",
    "summary":"退款成功",
    "resource" : {
        "original_type": "refund",
        "algorithm":"AEAD_AES_256_GCM",
        "ciphertext": "...",
        "associated_data": "",
        "nonce": "..."
    }
}

商户对resource对象进行解密后,得到的资源对象示例


{
    "mchid": "1900000100",
    "transaction_id": "1008450740201411110005820873",
    "out_trade_no": "20150806125346",
    "refund_id": "50200207182018070300011301001",
    "out_refund_no": "7752501201407033233368018",
    "refund_status": "SUCCESS",
    "success_time": "2018-06-08T10:34:56+08:00",
    "user_received_account": "招商银行信用卡0403",
    "amount" : {
        "total": 999,
        "refund": 999,
        "payer_total": 999,
        "payer_refund": 999
    }
}

通知参数

参数名 变量 类型[长度限制] 必填 描述
直连商户号 mchid string[1,32] 直连商户的商户号,由微信支付生成并下发。
示例值:1900000100
商户订单号 out_trade_no string[1,32] 返回的商户订单号
示例值: 1217752501201407033233368018
微信支付订单号 transaction_id string[1,32] 微信支付订单号
示例值: 1217752501201407033233368018
商户退款单号 out_refund_no string[1,64] 商户退款单号
示例值: 1217752501201407033233368018
微信支付退款单号 refund_id string[1,32] 微信退款单号
示例值: 1217752501201407033233368018
退款状态 refund_status string[1,32]

退款状态,枚举值:
SUCCESS:退款成功
CLOSED:退款关闭
ABNORMAL:退款异常,退款到银行发现用户的卡作废或者冻结了,导致原路退款银行卡失败,可前往【商户平台—>交易中心】,手动处理此笔退款
示例值:SUCCESS

退款成功时间 success_time string[1,64] 1、退款成功时间,遵循rfc3339标准格式,格式为yyyy-MM-DDTHH:mm:ss+TIMEZONE,yyyy-MM-DD表示年月日,T出现在字符串中,表示time元素的开头,HH:mm:ss表示时分秒,TIMEZONE表示时区(+08:00表示东八区时间,领先UTC 8小时,即北京时间)。例如:2015-05-20T13:29:35+08:00表示,北京时间2015年5月20日13点29分35秒。
2、当退款状态为退款成功时返回此参数。
示例值:2018-06-08T10:34:56+08:00
退款入账账户 user_received_account string[1,64] 取当前退款单的退款入账方。
1、退回银行卡:{银行名称}{卡类型}{卡尾号}
2、退回支付用户零钱: 支付用户零钱
3、退还商户: 商户基本账户、商户结算银行账户
4、退回支付用户零钱通:支付用户零钱通
示例值:招商银行信用卡0403
+金额信息 amount object 金额信息
参数名 变量 类型[长度限制] 必填 描述
订单金额 total int 订单总金额,单位为分,只能为整数,详见支付金额
示例值:999
退款金额 refund int 退款金额,币种的最小单位,只能为整数,不能超过原订单支付金额,如果有使用券,后台会按比例退。
示例值:999
用户支付金额 payer_total int 用户实际支付金额,单位为分,只能为整数,详见支付金额
示例值:999
用户退款金额 payer_refund int 退款给用户的金额,不包含所有优惠券金额
示例值:999

通知应答

接收成功:HTTP应答状态码需返回200或204,无需返回应答报文。

接收失败:HTTP应答状态码需返回5XX或4XX,同时需返回应答报文,格式如下:

注意:重试过多会导致微信支付端积压过多通知而堵塞,影响其他正常通知。


参数名 变量 类型[长度限制] 必填 描述
返回状态码 code string[1,32] 错误码,SUCCESS为接收成功,其他错误码为失败
示例值:SUCCESS
返回信息 message string[1,256] 返回信息,如非空,为错误原因
示例值:系统错误

{   
    "code": "SUCCESS"
}


技术咨询

文档反馈