下载平台证书API
由于证书有效期限制和交易安全原因，微信支付会不定期的更换平台证书。微信支付提供了一系列接口，帮助商户后台系统实现平滑的证书更换。
注意：
使用指引：
• 建议开发者使用中控服务器（即统一管理和分发，注意证书的保密和安全性）统一下载和管理微信支付平台证书。其他业务逻辑服务器通过该中控服务器进行报文的验签和解密。
• 在微信支付更换平台证书之前，待更换的证书会提前24小时加入商户的平台证书列表。中控服务器需要定时查询商户的平台证书列表，并及时下载新的平台证书。
• 在微信支付更换平台证书期间，商户收到的应答请求和回调通知中会同时存在不同的证书序列号，商户要能正确处理这种情况。
• 获取平台证书的接口频率限制规则: 单个商户号 1000次/s 。
• 敏感信息加密时，建议使用最新的平台证书（即：证书有效期较大的证书）进行加密。
最佳实践：
• 在中控服务器单上调用；
• 定时调用，间隔应小于12小时；
• 与本地证书序列表对比，如果发现有新增证书序列号，那就是需要新换的证书。老证书需要在被弃用前及时清理掉；
• 获取到证书后，分发到各业务接口服务器。
1. 接口说明
适用对象:直连模式机构模式
请求URL:https://apihk.mch.weixin.qq.com/v3/global/certificates
请求方式: GET
Path指该参数为路径参数
Query指该参数为URL参数
Body指该参数需在请求JSON传参
3. 返回参数
正常返回
| 参数名 |
变量 |
类型[长度限制] |
必填 |
描述 |
| 证书序列号 |
serial_no |
string[1,40] |
是 |
证书的序列号
示例值：5157F09EFDC096DE15EBE81A47057A7232F1B8E1 |
| 证书启用时间 |
effective_time |
string[1,32] |
是 |
启用证书的时间，时间格式为RFC3339。每个平台证书的启用时间是固定的。
示例值：2018-06-08T10:34:56+08:00 |
| 证书弃用时间 |
expire_time |
string[1,32] |
是 |
弃用证书的时间，时间格式为RFC3339。
更换平台证书前，会提前24小时修改老证书的弃用时间，接口返回新老两个平台证书。更换完成后，接口会返回最新的平台证书。
示例值：2018-06-08T10:34:56+08:00 |
| 证书信息 |
encrypt_certificate |
object |
是 |
证书信息，详细说明见下文 |
| 参数名 |
变量 |
类型[长度限制] |
必填 |
描述 |
| 加密证书的算法 |
algorithm |
string[1,32] |
是 |
加密证书的算法，密钥为API KEY, 需要登录商户平台设置
示例值：AEAD_AES_256_GCM |
| 加密证书的随机串 |
nonce |
string[1,12] |
是 |
加密证书的随机串
示例值：61f9c719728a |
| 加密证书的附加数据 |
associated_data |
string[1,32] |
是 |
固定值： certificate
示例值：certificate |
| 加密后的证书内容 |
ciphertext |
string[1,344] |
是 |
使用API KEY和上述参数，可以解密出平台证书的明文。证书明文为PEM格式。（注意：
更换证书时会出现PEM格式中的证书失效时间与接口返回的证书弃用时间不一致的情况）
示例值：Y1IPF0kyRe+aJ7TK6cw08r1g/agxl16o |
|
下面详细描述证书解密的流程
1、从商户平台上获取商户的密钥，记为“key”。
2、针对“algorithm”中描述的算法（目前为AEAD_AES_256_GCM），取得对应的参数“nonce”和“associated_data”。
3、使用“key”、“nonce”和“associated_data”对数据密文“ciphertext”进行解密（需要先对ciphertext做base64解码，然后再解密），得到证书内容
注意
“AEAD_AES_256_GCM”算法的接口细节，请参考
rfc5116。
异常返回
| 参数名 |
变量 |
类型[长度限制] |
必填 |
描述 |
| 返回状态码 |
code |
string[1, 32] |
是 |
错误码，枚举值见错误码列表
示例值：INVALID_REQUEST |
| 返回信息 |
message |
string[1, 256] |
是 |
返回信息，如非空，为错误原因
示例值：参数格式校验错误 |
| 详细的错误描述 |
detail |
object |
否 |
当code为PARAM_ERROR时返回，详细说明见下 |
| 参数名 |
变量 |
类型[长度限制] |
必填 |
描述 |
| 指示错误参数的位置 |
field |
string[1, 256] |
是 |
当错误参数位于请求body的JSON时，填写指向参数的JSON Pointer
当错误参数位于请求的url或者querystring时，填写参数的变量名
示例值：#/properties/payer |
| 错误参数的值 |
value |
string[1, 256] |
是 |
错误参数的值
示例值：1346177081915535577 |
| 具体错误原因 |
issue |
string[1, 256] |
是 |
具体错误原因
示例值：与ALLOF schema不符 |
| 错误参数的位置 |
location |
string[1, 256] |
否 |
body：错误参数位于请求body的JSON中
url：错误参数位于请求url中
query：错误参数位于请求的querystring中
示例值：body |
|
返回示例
{
"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… "
}
}
]
}
{
"code": "INVALID_REQUEST",
"message": "Parameter format verification error",
"detail": {
"field": "#/properties/payer",
"value": "1346177081915535577",
"issue": "与ALLOF schema不符",
"location": "body"
}
}
