基本信息

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

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

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

圖片上傳API除外。

參數(shù)兼容性

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

字符集

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

日期格式

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

請求的唯一標(biāo)識

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

錯(cuò)誤信息

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

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

錯(cuò)誤碼和錯(cuò)誤提示

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

• code：詳細(xì)錯(cuò)誤碼
• message：錯(cuò)誤描述，使用易理解的文字表示錯(cuò)誤的原因。
• field: 指示錯(cuò)誤參數(shù)的位置。當(dāng)錯(cuò)誤參數(shù)位于請求body的JSON時(shí)，填寫指向參數(shù)的JSON Pointer 。當(dāng)錯(cuò)誤參數(shù)位于請求的url或者querystring時(shí)，填寫參數(shù)的變量名。
• value:錯(cuò)誤的值
• issue:具體錯(cuò)誤原因

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

User Agent

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

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

應(yīng)答的語種

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

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

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