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