基本信息

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

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

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

圖片上傳API除外。

參數(shù)兼容性

• 請求是否成功，與請求參數(shù)的順序無關
• 請求是否成功，與請求JSON中的鍵值對出現(xiàn)的順序無關
• 處理應答時，不應假設應答JSON中的鍵值對出現(xiàn)的順序
• 新的API版本可能在請求或應答中加入新的參數(shù)或者JSON的鍵值對
• 新的API版本不會去除請求和應答中已經(jīng)存在的必填參數(shù)或者JSON的鍵值對
• 當請求或應答中的JSON鍵值對的值為空（null）時，可以省略

字符集

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

日期格式

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

請求的唯一標識

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

錯誤信息

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

• 處理成功的請求，如果有應答的消息體將返回200，若沒有應答的消息體將返回204。
• 已經(jīng)被成功接受待處理的請求，將返回202。
• 請求處理失敗時，如缺少必要的入?yún)ⅰ⒅Ц稌r余額不足，將會返回4xx范圍內的錯誤碼。
• 請求處理時發(fā)生了微信支付側的服務系統(tǒng)錯誤，將返回500/501/503的狀態(tài)碼。這種情況比較少見。

錯誤碼和錯誤提示

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

• 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"
  }
}
                  

User Agent

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

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

應答的語種

微信支付API v3允許調用方聲明應答中的錯誤描述使用的自然語言語種。如果有需要，設置請求的HTTP頭Accept-Language。目前支持：

• en
• zh-CN
• zh-HK
• zh-TW

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