基本規(guī)則

1. 基本信息

所有的API請求必須使用HTTPS。

注意

請求時不應(yīng)忽略服務(wù)器證書驗證的錯誤，避免被惡意劫持

2. 數(shù)據(jù)格式

所有的API請求必須使用HTTPS。

注意

微信支付API V3使用 JSON 作為消息體的數(shù)據(jù)交換格式。請求須設(shè)置HTTP頭部：

Content-Type: application/json
Accept: application/json

圖片上傳API除外。

注意

API應(yīng)答中的數(shù)據(jù)有可能包含商戶傳入的數(shù)據(jù)，即可能是未經(jīng)檢查的用戶輸入內(nèi)容。為了避免XSS（Cross-site scripting）攻擊，請調(diào)用方在使用應(yīng)答數(shù)據(jù)前根據(jù)場景做適當?shù)霓D(zhuǎn)義或者過濾。

3. 參數(shù)兼容性

? 請求是否成功，與請求參數(shù)的順序無關(guān)

? 請求是否成功，與請求JSON中的鍵值對出現(xiàn)的順序無關(guān)

? 處理應(yīng)答時，不應(yīng)假設(shè)應(yīng)答JSON中的鍵值對出現(xiàn)的順序

? 新的API版本可能在請求或應(yīng)答中加入新的參數(shù)或者JSON的鍵值對

? 新的API版本不會去除請求和應(yīng)答中已經(jīng)存在的必填參數(shù)或者JSON的鍵值對

? 當請求或應(yīng)答中的JSON鍵值對的值為空（null）時，可以省略

4. 字符集

微信支付API V3僅支持UTF-8字符編碼的一個子集：使用一至三個字節(jié)編碼的字符。也就是說，不支持Unicode輔助平面中的四至六字節(jié)編碼的字符。

5. 日期格式

所有的日期對象，使用 ISO 8601 所定義的格式。示例：

yyyy-MM-DDTHH:mm:ss.SSSZ
yyyy-MM-DDTHH:mm:ssZ
yyyy-MM-DDTHH:mm:ss.SSS+08:00
yyyy-MM-DDTHH:mm:ss+08:00

6. 請求的唯一標識

微信支付給每個接收到的請求分配了一個唯一標識。請求的唯一標識包含在應(yīng)答的HTTP頭Request-ID中。當需要微信支付幫助時，請?zhí)峁┱埱蟮奈ㄒ粯俗R，以便我們更快的定位到具體的請求。

7. 錯誤信息

微信支付API V3使用HTTP狀態(tài)碼來表示請求處理的結(jié)果。

? 處理成功的請求，如果有應(yīng)答的消息體將返回200，若沒有應(yīng)答的消息體將返回204。

? 已經(jīng)被成功接受待處理的請求，將返回202。

? 請求處理失敗時，如缺少必要的入?yún)ⅰ⒅Ц稌r余額不足，將會返回4xx范圍內(nèi)的錯誤碼。

? 請求處理時發(fā)生了微信支付側(cè)的服務(wù)系統(tǒng)錯誤，將返回500/501/503的狀態(tài)碼。這種情況比較少見。

8. 錯誤碼和錯誤提示

當請求處理失敗時，除了HTTP狀態(tài)碼表示錯誤之外，API將在消息體返回錯誤相應(yīng)說明具體的錯誤原因。

? code：詳細錯誤碼

? message：錯誤描述，使用易理解的文字表示錯誤的原因。

? field: 指示錯誤參數(shù)的位置。當錯誤參數(shù)位于請求body的JSON時，填寫指向參數(shù)的JSON Pointer 。當錯誤參數(shù)位于請求的url或者querystring時，填寫參數(shù)的變量名。

? value:錯誤的值

? issue:具體錯誤原因

{
  "code": "PARAM_ERROR",
  "message": "參數(shù)錯誤",
  "detail": {
    "field": "/amount/currency",
    "value": "XYZ",
    "issue": "Currency code is invalid",
    "location" :"body"
  }
}

9. User Agent

HTTP協(xié)議要求發(fā)起請求的客戶端在每一次請求中都使用HTTP頭 User-Agent來標識自己。微信支付建議調(diào)用方選用以下兩種方式的一種：

1.使用HTTP客戶端默認的 User-Agent。

2.遵循HTTP協(xié)議，使用自身系統(tǒng)和應(yīng)用的名稱和版本等信息，組成自己獨有的User-Agent。

微信支付API V3很可能會拒絕處理無User-Agent 的請求。

10. 應(yīng)答的語種

微信支付API V3允許調(diào)用方聲明應(yīng)答中的錯誤描述使用的自然語言語種。如果有需要，設(shè)置請求的HTTP頭Accept-Language。目前支持：

? en

? zh-CN

? zh-HK

? zh-TW

當不設(shè)置或者值不支持時，將使用簡體中文（zh-CN）。