支付通知

腾讯公益通过支付通知接口将用户支付成功消息通知给商户。

注意: 腾讯公益对后台通知交互时，如果腾讯公益侧收到应答不是成功或超时，认为通知失败，会通过一定的策略定期重新发起通知，尽可能提高通知的成功率，但不保证通知最终能成功

• 同样的通知可能会多次发送给业务系统。业务系统必须能够正确处理重复的通知。 推荐的做法是，当业务系统收到通知进行处理时，先检查对应业务数据的状态，并判断该通知是否已经处理。如果未处理，则再进行处理；如果已处理，则直接返回结果成功。在对业务数据进行状态检查和处理之前，要采用数据锁进行并发控制，以避免函数重入造成的数据混乱。
• 如果在所有通知频率后没有收到腾讯公益侧回调。业务应调用可通过主动查询订单接口确认订单状态; 或者通过隔天对账来保证最终一致性

特别提醒： 业务系统对于开启结果通知的内容一定要做签名验证，并校验通知的信息是否与业务侧的信息一致，防止数据泄露导致出现“假通知”，造成业务混乱或其他损失

接入前工作： 先确认是否在申请接入时，已准确配置好对应的业务回调url ，只有正确配置，才能收到支付成功的回调信息

1. 接口说明

请求方式： 【POST】

回调URL： 该链接是在申请业务接入时，分配bid信息是设置的，外部业务要求必须为HTTPS地址。请确保回调URL是外部可正常访问的，且不能携带后缀参数，否则可能导致业务无法接收到腾讯公益的回调通知信息。回调URL示例："https://pay.gongyi.qq.com/pay/callback"

注意：目前仅支持域名寻址，https域名建议使用443端口（仅腾讯内网环境下可使用http，http域名建议使用80端口）

2. 通知规则

用户支付完成后，腾讯公益会把相关支付结果和用户信息发送给业务，业务需要接收处理该消息，并返回应答。

对后台通知交互时，如果腾讯公益侧收到商户的应答不符合规范或超时，腾讯公益侧认为通知失败，会通过一定的策略定期重新发起通知，尽可能提高通知的成功率，但微信不保证通知最终能成功。

3. 通知报文

支付结果通知是以POST 方法访问业务(即应用)设置的通知URL，通知的数据以JSON 格式通过请求主体（BODY）传输。通知的数据包括了加密的支付结果详情。

注意： 由于涉及签名，业务必须在申请时设置好密钥，并在签名时，保证密钥的正确性。

另外，需注意的是，根据《个保法》要求，非用户授权模式，仅能收到以下部分回调字段:

• transcode
• bid
• busi_code
• trans_time
• trans_state

字段说明：

支付状态(trans_state)说明：

• 11： 支付成功
• 其他：支付失败

业务第1次接入，需要联系对接产品或运营同学，申请以下信息

• appid： 公益应用，用于接入公益开发平台。
• bid：公益支付业务标识，在申请公益应用(appid)时，备注需要接入公益支付，将一并分配；若已有appid，则备注绑定的appid，
• key：签名密钥，用于回调信息签名，无需单独申请，在申请bid时，将自动分配；业务务必妥善保管，避免泄露造成业务损失。

4. 签名步骤说明

4.1 算法规则

设所有发送或接收到的数据为集合 M，将集合M内非空参数值的参数按照参数名ASCII码从小到大排序（字典序），使用URL键值对的格式（即key1=value1&key2=value2…）拼接成字符串stringA，特别注意 以下重要规则：

• 参数名ASCII码从小到大排序（字典序）
• 如果参数的值为空不参与签名
• 参数名区分大小写
• 验证调用返回或微信主动通知签名时，传送的sign参数不参与签名，将生成的签名与该sign值作校验
• 接口可能增加字段，验证签名时必须支持增加的扩展字段: 即推荐按收到的字段进行签名验证

4.2 签名示例

在 stringA 最后拼接上 key 得到 stringSignTemp 字符串，并对 stringSignTemp 进行 MD5 运算，再将得到的字符串所有字符转换为大写，得到 sign 值 signValue。 如果没有特别需求，默认使用md5加密

假设回调的参数如下：

bid=10000123
busi_code=12345678900987654321abcdefgh
transcode=123456789020231220ABCD88dcba
pid=1008899
money=10234
bt=WXL
trans_state=11
trans_time=2023-12-20T07:08:09+08:00

第一步：对参数按照key=value的格式，并按照参数名ASCII字典序排序如下：

bid=10000123&bt=WXL&busi_code=12345678900987654321abcdefgh&money=10234&pid=1008899&trans_state=11&trans_time=2023-12-20T07:08:09+08:00&transcode=123456789020231220ABCD88dcba

第二步：拼接API密钥：

// 注：key为应用侧在公益侧设置的密钥key, 这里假设密钥为12233344445555566666677777778888，拼接结果如下
bid=10000123&bt=WXL&busi_code=12345678900987654321abcdefgh&money=10234&pid=1008899&trans_state=11&trans_time=2023-12-20T07:08:09+08:00&transcode=123456789020231220ABCD88dcba&key=12233344445555566666677777778888

第三步：生成sign并转成大写

// 若使用MD5签名方式，生成结果如下
A85E2E2C380A302C6C2E91DDD3670E6B

4.3 常见问题

1、注意参数是否区分大小写，参数大小写不正确将会导致签名错误

2、检查所有参数是否与文档完全一致

3、请求数据的编码是否正确，编码要求统一为UTF-8

4、签名原串是否存在被URLencode编码的参数，签名原串要求使用参数的原值进行签名

5. 通知应答

推荐用法：业务侧收到回调请求后，HTTP状态码(即HTTP Status Code)设置为200，业务侧的相关错误，赋值到包体中的code和message字段，返回给公益侧。 公益侧收到应答后，会进行校验，校验失败则认为通知失败(HTTP状态码非200，或包体中的code非0)，会在一定时间内(策略详见上文中的通知规则)继续通知，直到校验成功。

返回状态码

• 回200：接收成功时，返回HTTP应答状态码。
• 5XX或4XX：接收失败时，返回HTTP应答状态码。

应答报文，格式如下：

字段说明

超时说明： 腾讯公益侧在回调通知发出后，2s内未收到应答，会认为请求超时; 考虑到各自网络延迟，建议业务侧在收到请求后的1s内完成应答。

示例：

{  
"code": 100001,
"message": "参数校验失败"
}