Login expired. Please log in again.

Feedback

0/300

Feedback

Submitted successfully

ok

Feedback

Network exception, please try again later

ok

下载平台证书API

最新更新时间:2023.04.21 版本说明

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

注意:

使用指引:

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

• 在微信支付更换平台证书之前,待更换的证书会提前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 证书信息,详细说明见下文
参数名 变量 类型[长度限制] 必填 描述
加密证书的算法 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"
	}
}

4. 错误码

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


About  WeChat  Pay

Powered By Tencent & Tenpay Copyright©

2005-2024 Tenpay All Rights Reserved.

Contact Us
Wechat Pay Global

WeChat Pay Global

置顶