退款结果通知API

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

接口说明

适用对象: 电商
请求方式: POST
请求 URL: 该链接是通过[商户配置]提交 service_notify_url 设置, 必须为 https 协议。如果链接无法访问, 商户将无法接收到微信通知。 通知 url 必须为直接可访问的 url, 不能携带参数。示例: “https://pay.weixin.qq.com/wxpay/pay.action”
接口规则: https://wechatpay-api.gitbook.io/wechatpay-api-v3

通知规则

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

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

通知报文

支付结果通知是以 POST 方法访问商户设置的通知 url, 通知的数据以 JSON 格式通过请求主体(BODY）传输。通知的数据包括了加密的支付结果详情。

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

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

通知参数

变量类型必填参数名/描述/示例值
idstring(32)是通知 ID 通知的唯一 ID
EV-2018022511223320873
create_timestring(16)是通知创建时间 通知创建的时间, 遵循 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_typestring(32)是通知类型:
REFUND.SUCCESS: 退款成功通知
REFUND.ABNORMAL: 退款异常通知
REFUND.CLOSED: 退款关闭通知
REFUND.SUCCESS
summarystring(16)是通知简要说明
退款成功
resource_typestring(32)是通知数据类型 通知的资源数据类型, 支付成功通知为 encrypt-resource
encrypt-resource
resourceobject是+通知数据 通知资源数据
json 格式, 见示例

通知签名

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

通知应答

分账动账通知 http 应答码为 200 且返回状态码为 SUCCESS 才会当做商户接收成功, 否则会重试。

变量类型必填参数名/描述/示例值
codestring(32)是返回状态码 错误码, SUCCESS 为接收成功, 其他错误码为失败
SUCCESS
messagestring(256)否返回信息, 如非空, 为错误原因
系统错误
{
  "code": "ERROR_NAME",
  "message": "ERROR_DESCRIPTION"
}

回调示例

退款通知

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

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

{
  "sp_mchid": "1900000100",
  "sub_mchid": "1900000109",
  "transaction_id": "1008450740201411110005820873",
  "out_trade_no": "20150806125346",
  "refund_id": "50200207182018070300011301001",
  "out_refund_no": "7752501201407033233368018",
  "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
  }
}

通知参数

变量类型必填参数名/描述/示例值
sp_mchidstring(32)是电商平台商户号 微信支付分配给电商平台的商户号
1900000100
sub_mchidstring(32)是二级商户号 微信支付分配给二级商户的商户号
1900000109
out_trade_nostring(32)是商户订单号 返回的商户订单号
1217752501201407033233368018
transaction_idstring(32)是微信订单号 微信支付订单号
1217752501201407033233368018
out_refund_nostring(64)是商户退款单号
1217752501201407033233368018
refund_idstring(32)是微信退款单号
1217752501201407033233368018
refund_statusstring(16)是退款状态, 枚举值:
SUCCESS: 退款成功
CLOSE: 退款关闭
ABNORMAL: 退款异常, 退款到银行发现用户的卡作废或者冻结了, 导致原路退款银行卡失败, 可前往【服务商平台—>交易中心】, 手动处理此笔退款
SUCCESS
success_timestring(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_accountstring(64)是退款入账账户 取当前退款单的退款入账方。
退回银行卡: {银行名称}{卡类型}{卡尾号}
退回支付用户零钱: 支付用户零钱
退还商户: 商户基本账户、商户结算银行账户
退回支付用户零钱通: 支付用户零钱通
招商银行信用卡 0403
amountobject是+金额信息

最后修改 April 12, 2020: 整理文档 (f36b91e)