API升級指引

1. 背景說明

為了帶給商戶簡單、一致且易用的開發(fā)體驗，微信支付目前推出了可供全球機構/商戶使用的API V3，該版本API的具體規(guī)則請參考“APIv3接口規(guī)則”。

對于新入駐的微信支付機構/商戶，請參考API v3 Global文檔中心各產(chǎn)品的接入前準備，開發(fā)指引來完成對接。

非香港地區(qū)的已接入機構/商戶，默認使用的API版本為API v2，后續(xù)可根據(jù)自身情況選擇是否要對已接入API進行升級，若選擇保持使用v2，可通過API v2文檔中心查看相關文檔。如選擇升級，請參考以下升級及注意事項說明完成API升級。

說明

API升級并非強制行為，機構可根據(jù)自身的實際需求及情況選擇是否升級，原API v2仍可繼續(xù)使用。

注意

對于香港地區(qū)已接入API v3 HK的機構和商戶，后續(xù)的產(chǎn)品接入請參考API v3 Global的相關文檔，原API v3 HK可繼續(xù)使用，但對應文檔會逐步下架。

說明

API v3 HK與API v3 Global僅各API的請求地址存在差異，其他均保持一致，詳情請參考API v3 Global文檔中心。

2. 接口版本對比

與當前使用的XML+MD5的API v2接口相比，新的API v3 Global的產(chǎn)品接入流程及產(chǎn)品業(yè)務流程并沒有發(fā)生變化，主要的區(qū)別點在于API的協(xié)議差異，以下為具體差異對比：

3. 參數(shù)說明

appid：已入駐且已對接API v2的機構/商戶，若需要升級到API V3，可繼續(xù)使用已有的公眾號appid，不需要做額外的更換或升級。

mch_id：與appid情況一致，可繼續(xù)使用已有的Mch_id，不需要重新申請或升級。

sub_mch_id：子商戶號同樣不需要重新申請或升級，可直接使用。

sub_appid：子商戶appid也不需要重新申請或升級，可直接使用。

API key：該參數(shù)在API V3中不會使用，已設置的api key可以在商戶升級API灰度過程中保留。

API key v3：API V3新增開發(fā)參數(shù)，主要用于敏感信息的加密和解密，具體用途及用法請參考“加密解密”，設置方式請參考“API V3 key設置指引”。

證書：API V3的調(diào)用，需要使用CA簽發(fā)的證書，請先登錄商戶平臺，進入account settings→API security目錄，查看API certificate項，若界面如下圖所示，則代表該商戶號對應證書已經(jīng)升級到CA證書，可直接對接API V3。 若界面如下圖所示，則代表當前商戶號使用證書為自簽證書，若想要調(diào)用API V3，則必須先對證書進行升級，點擊界面中的Upgrade，然后參考“API證書下載”進行升級。

注意

證書升級后，并不影響當前API v2的使用，API v2接口的調(diào)用也可以使用升級后的CA證書。

證書升級后，新老證書有14天的共同有效期，14天后，老證書將過期失效，所以請及時將新證書部署到系統(tǒng)內(nèi)。

4. 權限申請

API V3不需要額外的權限申請，僅需完成API V3 key的設置及證書升級后即可開始API V3的對接開發(fā)。

5. 其他注意事項

未來微信支付新增的能力都將使用API V3協(xié)議，建議機構/商戶優(yōu)先選擇API V3進行業(yè)務對接。