下載對(duì)賬單API
商戶可以通過(guò)該接口下載歷史交易清單。比如掉單、系統(tǒng)錯(cuò)誤等導(dǎo)致商戶側(cè)和微信側(cè)數(shù)據(jù)不一致,通過(guò)對(duì)賬單核對(duì)后可校正支付狀態(tài)。
注意:
? 賬單完整性校驗(yàn):賬單完整下載后,生成SHA1簽名與微信返回HTTP頭的Wechatpay-Statement-Sha1值做對(duì)比校驗(yàn)。
? 對(duì)賬單接口只支持下載180天以內(nèi)的賬單。
1. 接口說(shuō)明
適用對(duì)象:直連模式機(jī)構(gòu)模式
請(qǐng)求URL:https://apihk.mch.weixin.qq.com/v3/global/statements
請(qǐng)求方式: GET
Path指該參數(shù)為路徑參數(shù)
Query指該參數(shù)為URL參數(shù)
Body指該參數(shù)需在請(qǐng)求JSON傳參
3. 返回參數(shù)
正常返回
成功時(shí),數(shù)據(jù)以文本表格的方式返回,第一行為表頭,后面各行為對(duì)應(yīng)的字段內(nèi)容,字段內(nèi)容跟查詢訂單或退款結(jié)果一致,具體字段說(shuō)明可查閱相應(yīng)接口。
1)第一行為表頭,目前有:交易時(shí)間,公眾賬號(hào)ID,商戶號(hào),子商戶號(hào),設(shè)備號(hào),微信訂單號(hào),商戶訂單號(hào),用戶標(biāo)識(shí),交易類型,交易狀態(tài),付款銀行,充值券幣種,充值券金額,優(yōu)惠券幣種,優(yōu)惠券金額,微信退款單號(hào),商戶退款單號(hào),退款類型,退款狀態(tài),商品名稱,商戶數(shù)據(jù)包,手續(xù)費(fèi),費(fèi)率,標(biāo)價(jià)幣種,訂單金額(標(biāo)價(jià)幣種),用戶支付幣種,用戶支付金額,結(jié)算幣種,應(yīng)結(jié)訂單金額,支付匯率,退款匯率,申請(qǐng)退款金額,用戶退款幣種,用戶退款金額,退款結(jié)算幣種,退款應(yīng)結(jié)訂單金額,充值券退款金額,優(yōu)惠券退款金額。
2)從第二行起,為數(shù)據(jù)記錄,各參數(shù)以逗號(hào)分隔,參數(shù)前增加`符號(hào),為標(biāo)準(zhǔn)鍵盤1左邊鍵的字符,字段順序與表頭一致。
異常返回
參數(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í),填寫指向參數(shù)的JSON Pointer
當(dāng)錯(cuò)誤參數(shù)位于請(qǐng)求的url或者querystring時(shí),填寫參數(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 |
|
返回示例
{
"code": "INVALID_REQUEST",
"message": "Parameter format verification error",
"detail": {
"field": "#/properties/payer",
"value": "1346177081915535577",
"issue": "與ALLOF schema不符",
"location": "body"
}
}
{
"code": "INVALID_REQUEST",
"message": "Parameter format verification error",
"detail": {
"field": "#/properties/payer",
"value": "1346177081915535577",
"issue": "與ALLOF schema不符",
"location": "body"
}
}
4. 應(yīng)答簽名校驗(yàn)說(shuō)明
4.1. 構(gòu)造簽名串
首先從應(yīng)答中獲取HTTP頭Wechatpay-Nonce中的應(yīng)答隨機(jī)串,Wechatpay-Timestamp中的應(yīng)答時(shí)間戳,Wechatpay-Statement-Sha1中取得賬單SHA1值。
請(qǐng)按照以下規(guī)則構(gòu)造應(yīng)答的簽名串。\n為換行符(ASCII編碼值為0x0A)。
應(yīng)答時(shí)間戳\n
應(yīng)答隨機(jī)串\n
賬單SHA1\n
\n
則簽名串為:
1507709906
5K8264ILTKch16CQ2502SI8ZNMTM67VS
{"sha1" : "12345678999"}
注意
標(biāo)紅的sha1值特殊處理為json格式進(jìn)行簽名;簽名串最后一行為空,即多一個(gè)換行符
4.2. 獲取應(yīng)答簽名
微信支付應(yīng)答簽名通過(guò)HTTP頭Wechat-Signature傳遞。(注意,示例因?yàn)榕虐婵赡艽嬖趽Q行,實(shí)際數(shù)據(jù)應(yīng)在一行)
Wechatpay-Signature: WcO+t3D8Kg71dTlKwN7r9PzUOXeaBJwp8/FOuSxcuSkXsoVYxBpsAidprySCjHCjmaglNcjoKJQLJ28/Asl93joTW39FX6i07lXhnbPknezAl
wmvPdnQuI01HZsZF9V1i6ggZjBiAd5lG8bZtTxZOJ87ub2i9GuJ3Nr/NUc9VeY=,對(duì)Wechatpay-Signature的字段值使用Base64進(jìn)行解碼,得到應(yīng)答簽名。
4.3. 驗(yàn)證簽名
很多編程語(yǔ)言的簽名驗(yàn)證函數(shù)支持對(duì)“簽名數(shù)據(jù)”進(jìn)行簽名驗(yàn)證。建議商戶調(diào)用該類函數(shù),使用微信支付平臺(tái)公鑰對(duì)“簽名串”進(jìn)行SHA256 with RSA簽名驗(yàn)證。
如果商戶使用的編程語(yǔ)言或者庫(kù)只支持對(duì)“摘要數(shù)據(jù)”進(jìn)行簽名驗(yàn)證,請(qǐng)按照以下步驟驗(yàn)證簽名:
1.使用SHA256計(jì)算簽名串的摘要,得到摘要信息
2.使用微信支付平臺(tái)公鑰對(duì)摘要信息進(jìn)行RSA簽名驗(yàn)證(簽名類型為SHA256)。請(qǐng)參考OpenSSL的RSA_verify()
注意
微信支付證書序列號(hào)位于HTTP頭`Wechatpay-Serial`,驗(yàn)證簽名前請(qǐng)先檢查序列號(hào)是否跟商戶所持有的微信支付證書序列號(hào)一致。更新證書的說(shuō)明,請(qǐng)參考《獲取微信支付平臺(tái)證書》。
4.4. 驗(yàn)證賬單完整性
賬單完整下載后,生成SHA1簽名與微信Wechatpay-Statement-Sha1值做賬單完整性的校驗(yàn)。