概述 - 接口文档 - 企业微信开发者中心

开发者中心

首页

教程

接口

社区

工具

企业内部开发

快速入门服务端API 客户端API 附录更新日志联系我们

企业内部开发服务端API 小程序接入对外收款回调通知概述

概述

最后更新：2022/11/29

当企业支付成功或者退款成功后，企业微信后台会推送支付成功或者退款成功通知到企业在『对外收款』应用配置的指令回调URL。假设企业的设置的指令回调URL为http://api.3dept.com，则请求内容如下：

请求方式：POST
请求地址：http://api.3dept.com/?msg_signature=ASDFQWEXZCVAQFASDFASDFSS&timestamp=13500001234&nonce=123412323

请求数据格式：

// json示例
{
	"tousername": "wwa8e92837bee4db94",
	"encrypt": "3N0+mFHrD1uneqxYeC===",
	"agentid": "3010115"
}

// XML示例
<xml> 
   <ToUserName><![CDATA[toUser]]></ToUserName>
   <AgentID><![CDATA[toAgentID]]></AgentID>
   <Encrypt><![CDATA[msg_encrypt]]></Encrypt>
</xml>

说明
默认回调的数据格式为XML，可以将『对外收款』应用的指令回调URL加上参数callback_format=json指定接收json格式的回调数据，例如将指令回调URL配置成：http://api.3dept.com/?callback_format=json

参数说明：

参数	类型	说明
msg_signature	String	企业微信加密签名，msg_signature结合了企业填写的token、请求中的timestamp、nonce参数、加密的消息体
timestamp	Integer	时间戳。与nonce结合使用，用于防止请求重放攻击。
nonce	String	随机数。与timestamp结合使用，用于防止请求重放攻击。
tousername	String	企业微信的CorpID
agentid	String	接收的应用id，可在应用的设置页面获取。
encrypt	String	消息结构体加密后的字符串，解密的方法可以参考解密回调数据。对于Json和XML我们都提供了对应的解密代码示例，开发者也可以根据加解密原理自行实现。

解密得到的结构体示例：

// json示例
{
    "notify_type": "NORMALPAY",
    "id":"EV-2018022511223320873",
    "create_time":"2015-05-20T13:29:35+08:00",
    "resource_type":"encrypt-resource",
    "event_type":"TRANSACTION.SUCCESS",
    "resource" : {
        "algorithm":"AEAD_AES_256_GCM",
        "ciphertext": "...",
        "nonce": "...",
        "associated_data": ""
    },
    "summary":"支付成功"
}

// XML示例
<xml>
    <notify_type><![CDATA[NORMALPAY]]></notify_type>
    <id><![CDATA[501848e5-88fd-56b3-874d-85c4451afac6]]></id>
    <create_time><![CDATA[2022-11-25T20:09:15+08:00]]></create_time>
    <event_type><![CDATA[TRANSACTION.SUCCESS]]></event_type>
    <resource_type><![CDATA[encrypt-resource]]></resource_type>
    <resource>
        <algorithm><![CDATA[AEAD_AES_256_GCM]]></algorithm>
        <ciphertext><![CDATA[qE1Xz0pVa5WX60imcQMZ]]></ciphertext>
        <associated_data><![CDATA[transaction]]></associated_data>
        <nonce><![CDATA[uRQLUOVVenok]]></nonce>
    </resource>
    <summary><![CDATA[支付成功]]></summary>
</xml>

参数说明：

参数	类型	说明
notify_type	string	场景类型，目前支持3种场景：普通支付通知（NORMALPAY），合单支付通知（COMBINEPAY），退款通知（REFUND）。
id	string	通知的唯一ID，示例值：EV-2018022511223320873。
create_time	string	通知创建的时间，遵循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年05月20日13点29分35秒。示例值：2015-05-20T13:29:35+08:00。
event_type	string	通知的类型，包括，支付成功通知：TRANSACTION.SUCCESS；退款成功通知：REFUND.SUCCESS；退款异常通知：REFUND.ABNORMAL；退款关闭通知：REFUND.CLOSED
resource_type	string	通知的资源数据类型，支付和退款回调时这个值均为：encrypt-resource
summary	string	回调摘要，示例值：支付成功。

Resource结构体说明：

参数	类型	说明
algorithm	string	对结果数据进行加密的加密算法，目前只支持AEAD_AES_256_GCM，示例值：AEAD_AES_256_GCM。
ciphertext	string	各个业务结构体加密后再进行Base64编码得到的字符串。获取明文结构参考获取业务回调结构体流程
associated_data	string	附加数据，示例值：fdasfwqewlkja484w。
nonce	string	加密使用的随机串，示例值：fdasflkja484w。

获取业务回调结构体流程：

1. 获取『对外收款』应用中配置的callback_aeskey，根据加解密方案说明中的方法获得aeskey
2. 针对resource.algorithm中描述的算法（目前为AEAD_AES_256_GCM），取得对应的参数nonce和associated_data
3. 对resource.ciphertext进行Base64解码
4. 使用aeskey、nonce和associated_data，对Base64解码后的数据进行解密，得到JSON形式的业务结构体
注：AEAD_AES_256_GCM算法的接口细节，请参考rfc5116

查询退款

支付通知

本节内容

概述