微信支付-融合钱包开发者文档

返回上一层融合钱包 / 小程序支付 / 下载平台证书API

下载平台证书

最新更新时间：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

是

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

参数名	变量	类型	必填	描述
加密证书的算法	algorithm	string(32)	是	加密证书的算法，密钥为API KEY, 需要登录商户平台设置示例值：AEAD_AES_256_GCM
加密证书的随机串	nonce	string(12)	是	加密证书的随机串示例值：61f9c719728a
加密证书的附加数据	associated_data	string(32)	是	固定值： certificate 示例值：certificate
加密后的证书内容	ciphertext	string(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](https://datatracker.ietf.org/doc/html/rfc5116)。

异常返回

参数名

变量

类型

必填

描述

返回状态码

code

string(32)

是

错误码，枚举值见错误码列表
示例值：INVALID_REQUEST

返回信息

message

string(256)

是

返回信息，如非空，为错误原因
示例值：参数格式校验错误

+ 详细的错误描述

detail

object

否

当code为PARAM_ERROR时返回，详细说明见下

参数名	变量	类型	必填	描述
指示错误参数的位置	field	string(256)	是	当错误参数位于请求body的JSON时，填写指向参数的JSON Pointer；当错误参数位于请求的url或者querystring时，填写参数的变量名示例值：#/properties/payer
错误参数的值	value	string(256)	是	错误参数的值示例值：1346177081915535577
具体错误原因	issue	string(256)	是	具体错误原因示例值：与ALLOF schema不符
错误参数的位置	location	string(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":"参数格式校验错误",
"detail":{
    "field":"#/properties/payer",
    "value":"1346177081915535577",
    "issue":"与ALLOF schema不符",
    "location":"body"
   }
}

错误码

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

WeChat Pay

Feedback

Feedback

Submitted successfully

Feedback

Network exception, please try again later

小程序支付

下载平台证书

注意：

接口说明

请求参数

返回参数

正常返回

异常返回

返回示例：

错误码

版本说明