下载平台证书

更新时间：2025.01.07

由于证书有效期限制和交易安全原因，微信支付会不定期的更换平台证书。微信支付提供了一系列接口，帮助商户后台系统实现平滑的证书更换。

注意：

使用指引：

建议开发者使用中控服务器（即统一管理和分发，注意证书的保密和安全性）统一下载和管理微信支付平台证书。其他业务逻辑服务器通过该中控服务器进行报文的验签和解密。

在微信支付更换平台证书之前，待更换的证书会提前24小时加入商户的平台证书列表。中控服务器需要定时查询商户的平台证书列表，并及时下载新的平台证书。

在微信支付更换平台证书期间，商户收到的应答请求和回调通知中会同时存在不同的证书序列号，商户要能正确处理这种情况。

获取平台证书的接口频率限制规则: 单个商户号 1000次/s 。

敏感信息加密时，建议使用最新的平台证书（即：证书有效期较大的证书）进行加密。

最佳实践：

在中控服务器单上调用；

定时调用，间隔应小于12小时；

与本地证书序列表对比，如果发现有新增证书序列号，那就是需要新换的证书。老证书需要在被弃用前及时清理掉；

获取到证书后，分发到各业务接口服务器。

1. 接口说明

适用对象: 直连模式机构模式

请求URL:https://apihk.mch.weixin.qq.com/v3/global/certificates

请求方式: GET

Path 指该参数为路径参数

Query 指该参数为URL参数

Body 指该参数需在请求JSON传参

2. 请求参数

无请求参数

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

是

证书信息，详细说明见下文

证书信息

下面详细描述证书解密的流程

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时返回，详细说明见下

详细的错误描述

返回示例

正常示例

1{
2	"data": [{
3			"serial_no": "5157F09EFDC096DE15EBE81A47057A7232F1B8E1",
4			"effective_time ": "2018-06-08T10:34:56+08:00",
5			"expire_time ": "2018-12-08T10:34:56+08:00",
6			"encrypt_certificate": {
7				"algorithm": "AEAD_AES_256_GCM",
8				"nonce": "61f9c719728a",
9				"associated_data": "certificate",
10				"ciphertext": "sRvt… "
11			}
12		},
13		{
14			"serial_no": "50062CE505775F070CAB06E697F1BBD1AD4F4D87",
15			"effective_time ": "2018-12-07T10:34:56+08:00",
16			"expire_time ": "2020-12-07T10:34:56+08:00",
17			"encrypt_certificate": {
18				"algorithm": "AEAD_AES_256_GCM",
19				"nonce": "35f9c719727b",
20				"associated_data": "certificate",
21				"ciphertext": "aBvt… "
22			}
23		}
24	]
25}

异常示例

1{
2	"code": "INVALID_REQUEST",
3	"message": "Parameter format verification error",
4	"detail": {
5		"field": "#/properties/payer",
6		"value": "1346177081915535577",
7		"issue": "与ALLOF schema不符",
8		"location": "body"
9	}
10}

4. 错误码

错误码	描述	解决方案
SYSTEM_ERROR	系统错误	系统异常，请再调用发起查询