分账动账通知API

1.此功能仅针对分账接收方。
2.分账动账金额变动后, 微信会把相关变动结果发送给需要实时关注的分账接收方。

接口说明

适用对象: 直联商户电商服务商 服务商
请求 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)是通知类型 通知的类型:
PROFITSHARING: 分账
PROFITSHARING_RETURN: 分账回退
PROFITSHARING
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": "PROFITSHARING",
  "summary": "分账",
  "resource": {
    "algorithm": "AEAD_AES_256_GCM",
    "original_type": "profitsharing",
    "ciphertext": "...",
    "nonce": "...",
    "associated_data": ""
  }
}

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

{
  "mchid": "1900000100",
  "sp_mchid": "1900000100",
  "sub_mchid": "1900000100",
  "transaction_id": "4200000000000000000000000000",
  "order_id": "1217752501201407033233368018",
  "out_order_no": "P20150806125346",
  "receivers": [
    {
      "type": "MERCHANT_ID",
      "account": "1900000100",
      "amount": "888",
      "description": "运费/交易分账/及时奖励"
    }
  ],
  "success_time": "2018-06-08T10:34:56+08:00"
}

通知参数

变量类型必填参数名/描述/示例值
mchidstring(32)否直连商户号 直连模式分账发起和出资商户。
1900000100
sp_mchidstring(32)否服务商商户号 服务商模式分账发起商户。
1900000100
sub_mchidstring(32)否子商户号 服务商模式分账出资商户。
1900000100
transaction_idstring(32)是微信订单号 微信支付订单号。
4200000000000000000000000000
order_idstring(64)是微信分账/回退单号。
1217752501201407033233368018
out_order_nostring(64)是商户分账/回退单号 分账方系统内部的分账/回退单号。
P20150806125346
receiversarray是+分账接收方列表 分账接收方对象
success_timestring(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

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