最新更新時(shí)間:2020.1.08 版本說明
由于證書有效期限制和交易安全原因,微信支付會(huì)不定期的更換平臺(tái)證書。微信支付提供了一系列接口,幫助商戶后臺(tái)系統(tǒng)實(shí)現(xiàn)平滑的證書更換。
使用指引:
● 建議開發(fā)者使用中控服務(wù)器(即統(tǒng)一管理和分發(fā),注意證書的保密和安全性)統(tǒng)一下載和管理微信支付平臺(tái)證書。其他業(yè)務(wù)邏輯服務(wù)器通過該中控服務(wù)器進(jìn)行報(bào)文的驗(yàn)簽和解密。
● 在微信支付更換平臺(tái)證書之前,待更換的證書會(huì)提前24小時(shí)加入商戶的平臺(tái)證書列表。中控服務(wù)器需要定時(shí)查詢商戶的平臺(tái)證書列表,并及時(shí)下載新的平臺(tái)證書。
● 在微信支付更換平臺(tái)證書期間,商戶收到的應(yīng)答請(qǐng)求和回調(diào)通知中會(huì)同時(shí)存在不同的證書序列號(hào),商戶要能正確處理這種情況。
● 獲取平臺(tái)證書的接口頻率限制規(guī)則:?單個(gè)商戶號(hào)?1000次/s?。
● 敏感信息加密時(shí),建議使用最新的平臺(tái)證書(即:證書有效期較大的證書)進(jìn)行加密。
最佳實(shí)踐:
● 在中控服務(wù)器單上調(diào)用;
● 定時(shí)調(diào)用,間隔應(yīng)小于12小時(shí);
● 與本地證書序列表對(duì)比,如果發(fā)現(xiàn)有新增證書序列號(hào),那就是需要新?lián)Q的證書。老證書需要在被棄用前及時(shí)清理掉;
● 獲取到證書后,分發(fā)到各業(yè)務(wù)接口服務(wù)器。
適用對(duì)象:直連模式機(jī)構(gòu)模式
請(qǐng)求URL: https://api.mch.weixin.qq.com/hk/v3/certificates
請(qǐng)求方式: GET
接口規(guī)則: https://wechatpay-api.gitbook.io/wechatpay-api-v3/wei-xin-zhi-fu-api-v3-jie-kou-gui-fan
path 指該參數(shù)為路徑參數(shù)
query 指該參數(shù)為URL參數(shù)
body 指該參數(shù)需在請(qǐng)求JSON傳參
無請(qǐng)求參數(shù)
參數(shù)名 | 變量 | 類型 | 必填 | 描述 |
---|---|---|---|---|
證書序列號(hào) | serial_no | string(40) | 是 | 證書的序列號(hào) 示例值:5157F09EFDC096DE15EBE81A47057A7232F1B8E1 |
證書啟用時(shí)間 | effective_time | string(32) | 是 | 啟用證書的時(shí)間,時(shí)間格式為RFC3339。每個(gè)平臺(tái)證書的啟用時(shí)間是固定的。 示例值:2018-06-08T10:34:56+08:00 |
證書棄用時(shí)間 | expire_time | string(32) | 是 | 棄用證書的時(shí)間,時(shí)間格式為RFC3339。 更換平臺(tái)證書前,會(huì)提前24小時(shí)修改老證書的棄用時(shí)間,接口返回新老兩個(gè)平臺(tái)證書。更換完成后,接口會(huì)返回最新的平臺(tái)證書。 示例值:2018-06-08T10:34:56+08:00 |
+ 證書信息 | encrypt_certificate | object | 是 | 證書信息,詳細(xì)說明見下文 |
下面詳細(xì)描述證書解密的流程
1、從商戶平臺(tái)上獲取商戶的密鑰,記為“key”。
2、針對(duì)“algorithm”中描述的算法(目前為AEAD_AES_256_GCM),取得對(duì)應(yīng)的參數(shù)“nonce”和“associated_data”。
3、使用“key”、“nonce”和“associated_data”對(duì)數(shù)據(jù)密文“ciphertext”進(jìn)行解密(需要先對(duì)ciphertext做base64解碼,然后再解密),得到證書內(nèi)容
注意:“AEAD_AES_256_GCM”算法的接口細(xì)節(jié),請(qǐng)參考[rfc5116](https://datatracker.ietf.org/doc/html/rfc5116)。
參數(shù)名 | 變量 | 類型 | 必填 | 描述 |
---|---|---|---|---|
返回狀態(tài)碼 | code | string(32) | 是 | 錯(cuò)誤碼,枚舉值見錯(cuò)誤碼列表 示例值:INVALID_REQUEST |
返回信息 | message | string(256) | 是 | 返回信息,如非空,為錯(cuò)誤原因 示例值:參數(shù)格式校驗(yàn)錯(cuò)誤 |
+ 詳細(xì)的錯(cuò)誤描述 | detail | object | 否 | 當(dāng)code為PARAM_ERROR時(shí)返回,詳細(xì)說明見下 |
{
"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… "
}
}
]
}
錯(cuò)誤碼 | 描述 | 解決方案 |
---|---|---|
SYSTEMERROR | 系統(tǒng)錯(cuò)誤 | 系統(tǒng)異常,請(qǐng)?jiān)僬{(diào)用發(fā)起查詢 |
Customer Service Tel
Business Development
9:00-18:00
Monday-Friday GMT+8
Technical Support
WeChat Pay Global
ICP證