下載平臺證書API
由于證書有效期限制和交易安全原因，微信支付會不定期的更換平臺證書。微信支付提供了一系列接口，幫助商戶后臺系統(tǒng)實現(xiàn)平滑的證書更換。
注意：
使用指引：
? 建議開發(fā)者使用中控服務(wù)器（即統(tǒng)一管理和分發(fā)，注意證書的保密和安全性）統(tǒng)一下載和管理微信支付平臺證書。其他業(yè)務(wù)邏輯服務(wù)器通過該中控服務(wù)器進行報文的驗簽和解密。
? 在微信支付更換平臺證書之前，待更換的證書會提前24小時加入商戶的平臺證書列表。中控服務(wù)器需要定時查詢商戶的平臺證書列表，并及時下載新的平臺證書。
? 在微信支付更換平臺證書期間，商戶收到的應(yīng)答請求和回調(diào)通知中會同時存在不同的證書序列號，商戶要能正確處理這種情況。
? 獲取平臺證書的接口頻率限制規(guī)則: 單個商戶號 1000次/s 。
? 敏感信息加密時，建議使用最新的平臺證書（即：證書有效期較大的證書）進行加密。
最佳實踐：
? 在中控服務(wù)器單上調(diào)用；
? 定時調(diào)用，間隔應(yīng)小于12小時；
? 與本地證書序列表對比，如果發(fā)現(xiàn)有新增證書序列號，那就是需要新?lián)Q的證書。老證書需要在被棄用前及時清理掉；
? 獲取到證書后，分發(fā)到各業(yè)務(wù)接口服務(wù)器。
1. 接口說明
適用對象:直連模式機構(gòu)模式
請求URL:https://apihk.mch.weixin.qq.com/v3/global/certificates
請求方式: GET
Path指該參數(shù)為路徑參數(shù)
Query指該參數(shù)為URL參數(shù)
Body指該參數(shù)需在請求JSON傳參
3. 返回參數(shù)
正常返回
| 參數(shù)名 |
變量 |
類型[長度限制] |
必填 |
描述 |
| 證書序列號 |
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 |
是 |
證書信息，詳細說明見下文 |
| 參數(shù)名 |
變量 |
類型[長度限制] |
必填 |
描述 |
| 加密證書的算法 |
algorithm |
string[1,32] |
是 |
加密證書的算法，密鑰為API KEY, 需要登錄商戶平臺設(shè)置
示例值：AEAD_AES_256_GCM |
| 加密證書的隨機串 |
nonce |
string[1,12] |
是 |
加密證書的隨機串
示例值：61f9c719728a |
| 加密證書的附加數(shù)據(jù) |
associated_data |
string[1,32] |
是 |
固定值：?certificate
示例值：certificate |
| 加密后的證書內(nèi)容 |
ciphertext |
string[1,344] |
是 |
使用API?KEY和上述參數(shù)，可以解密出平臺證書的明文。證書明文為PEM格式。（注意：
更換證書時會出現(xiàn)PEM格式中的證書失效時間與接口返回的證書棄用時間不一致的情況）
示例值：Y1IPF0kyRe+aJ7TK6cw08r1g/agxl16o |
|
下面詳細描述證書解密的流程
1、從商戶平臺上獲取商戶的密鑰，記為“key”。
2、針對“algorithm”中描述的算法（目前為AEAD_AES_256_GCM），取得對應(yīng)的參數(shù)“nonce”和“associated_data”。
3、使用“key”、“nonce”和“associated_data”對數(shù)據(jù)密文“ciphertext”進行解密（需要先對ciphertext做base64解碼，然后再解密），得到證書內(nèi)容
注意
“AEAD_AES_256_GCM”算法的接口細節(jié)，請參考
rfc5116。
異常返回
| 參數(shù)名 |
變量 |
類型[長度限制] |
必填 |
描述 |
| 返回狀態(tài)碼 |
code |
string[1, 32] |
是 |
錯誤碼，枚舉值見錯誤碼列表
示例值：INVALID_REQUEST |
| 返回信息 |
message |
string[1, 256] |
是 |
返回信息，如非空，為錯誤原因
示例值：參數(shù)格式校驗錯誤 |
| 詳細的錯誤描述 |
detail |
object |
否 |
當code為PARAM_ERROR時返回，詳細說明見下 |
| 參數(shù)名 |
變量 |
類型[長度限制] |
必填 |
描述 |
| 指示錯誤參數(shù)的位置 |
field |
string[1, 256] |
是 |
當錯誤參數(shù)位于請求body的JSON時，填寫指向參數(shù)的JSON Pointer
當錯誤參數(shù)位于請求的url或者querystring時，填寫參數(shù)的變量名
示例值：#/properties/payer |
| 錯誤參數(shù)的值 |
value |
string[1, 256] |
是 |
錯誤參數(shù)的值
示例值：1346177081915535577 |
| 具體錯誤原因 |
issue |
string[1, 256] |
是 |
具體錯誤原因
示例值：與ALLOF schema不符 |
| 錯誤參數(shù)的位置 |
location |
string[1, 256] |
否 |
body：錯誤參數(shù)位于請求body的JSON中
url：錯誤參數(shù)位于請求url中
query：錯誤參數(shù)位于請求的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 |
系統(tǒng)錯誤 |
系統(tǒng)異常，請再調(diào)用發(fā)起查詢 |
