登录
基础
连接微信
办公当企业支付成功或者退款成功后，企业微信后台会推送支付成功或者退款成功通知到企业在『对外收款』应用配置的指令回调URL。假设企业的设置的指令回调URL为http://api.3dept.com，则请求内容如下：
请求方式：POST
请求地址 ：http://api.3dept.com/?msg_signature=ASDFQWEXZCVAQFASDFASDFSS×tamp=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
基础连接微信办公基础连接微信办公基础连接微信办公