最新更新时间:2020.1.08 版本说明
由于证书有效期限制和交易安全原因,微信支付会不定期的更换平台证书。微信支付提供了一系列接口,帮助商户后台系统实现平滑的证书更换。
使用指引:
● 建议开发者使用中控服务器(即统一管理和分发,注意证书的保密和安全性)统一下载和管理微信支付平台证书。其他业务逻辑服务器通过该中控服务器进行报文的验签和解密。
● 在微信支付更换平台证书之前,待更换的证书会提前24小时加入商户的平台证书列表。中控服务器需要定时查询商户的平台证书列表,并及时下载新的平台证书。
● 在微信支付更换平台证书期间,商户收到的应答请求和回调通知中会同时存在不同的证书序列号,商户要能正确处理这种情况。
● 获取平台证书的接口频率限制规则: 单个商户号 1000次/s 。
● 敏感信息加密时,建议使用最新的平台证书(即:证书有效期较大的证书)进行加密。
最佳实践:
● 在中控服务器单上调用;
● 定时调用,间隔应小于12小时;
● 与本地证书序列表对比,如果发现有新增证书序列号,那就是需要新换的证书。老证书需要在被弃用前及时清理掉;
● 获取到证书后,分发到各业务接口服务器。
适用对象:直连模式机构模式
请求URL: https://api.mch.weixin.qq.com/hk/v3/certificates
请求方式: GET
接口规则: https://wechatpay-api.gitbook.io/wechatpay-api-v3/wei-xin-zhi-fu-api-v3-jie-kou-gui-fan
path 指该参数为路径参数
query 指该参数为URL参数
body 指该参数需在请求JSON传参
无请求参数
参数名 | 变量 | 类型 | 必填 | 描述 |
---|---|---|---|---|
证书序列号 | serial_no | string(40) | 是 | 证书的序列号 示例值:5157F09EFDC096DE15EBE81A47057A7232F1B8E1 |
证书启用时间 | effective_time | string(32) | 是 | 启用证书的时间,时间格式为RFC3339。每个平台证书的启用时间是固定的。 示例值:2018-06-08T10:34:56+08:00 |
证书弃用时间 | expire_time | string(32) | 是 | 弃用证书的时间,时间格式为RFC3339。 更换平台证书前,会提前24小时修改老证书的弃用时间,接口返回新老两个平台证书。更换完成后,接口会返回最新的平台证书。 示例值:2018-06-08T10:34:56+08:00 |
+ 证书信息 | encrypt_certificate | object | 是 | 证书信息,详细说明见下文 |
下面详细描述证书解密的流程
1、从商户平台上获取商户的密钥,记为“key”。
2、针对“algorithm”中描述的算法(目前为AEAD_AES_256_GCM),取得对应的参数“nonce”和“associated_data”。
3、使用“key”、“nonce”和“associated_data”对数据密文“ciphertext”进行解密(需要先对ciphertext做base64解码,然后再解密),得到证书内容
注意:“AEAD_AES_256_GCM”算法的接口细节,请参考[rfc5116](https://datatracker.ietf.org/doc/html/rfc5116)。
参数名 | 变量 | 类型 | 必填 | 描述 |
---|---|---|---|---|
返回状态码 | code | string(32) | 是 | 错误码,枚举值见错误码列表 示例值:INVALID_REQUEST |
返回信息 | message | string(256) | 是 | 返回信息,如非空,为错误原因 示例值:参数格式校验错误 |
+ 详细的错误描述 | detail | object | 否 | 当code为PARAM_ERROR时返回,详细说明见下 |
{
"data": [
{
"serial_no": "5157F09EFDC096DE15EBE81A47057A7232F1B8E1",
"effective_time ": "2018-06-08T10:34:56+08:00",
"expire_time ": "2018-12-08T10:34:56+08:00",
"encrypt_certificate": {
"algorithm": "AEAD_AES_256_GCM",
"nonce": "61f9c719728a",
"associated_data": "certificate",
"ciphertext": "sRvt… "
}
},
{
"serial_no": "50062CE505775F070CAB06E697F1BBD1AD4F4D87",
"effective_time ": "2018-12-07T10:34:56+08:00",
"expire_time ": "2020-12-07T10:34:56+08:00",
"encrypt_certificate": {
"algorithm": "AEAD_AES_256_GCM",
"nonce": "35f9c719727b",
"associated_data": "certificate",
"ciphertext": "aBvt… "
}
}
]
}
错误码 | 描述 | 解决方案 |
---|---|---|
SYSTEMERROR | 系统错误 | 系统异常,请再调用发起查询 |
Customer Service Tel
Business Development
9:00-18:00
Monday-Friday GMT+8
Technical Support
WeChat Pay Global
ICP证