本接口適用于下載單個子商戶和二級商戶資金賬單。
注意
- 該接口響應(yīng)的信息請求頭中不包含微信接口響應(yīng)的簽名值,因此需要跳過驗簽的流程。
- 賬單文件的下載地址的有效時間為5min。
- 建議商戶比對實際下載賬單文件的哈希值和從接口獲取到的哈希值是否一致,以確認(rèn)下載賬單數(shù)據(jù)的完整性。
- 微信將在次日9點開始生成前一天的對賬單,建議商戶在10點后獲取。
# 接口說明
支持商戶: 【普通服務(wù)商】 【電商平臺】
請求方式: 【GET】
請求URL: 調(diào)用申請賬單接口,返回參數(shù)“download_url”對應(yīng)的URL
# 請求步驟說明
下載加密賬單步驟分為:
- 下載賬單
- 解密賬單
# 步驟1:下載賬單
- 使用申請賬單接口獲取download_url,參考下方申請賬單返回參數(shù)示例。
- 使用微信支付APIv3標(biāo)準(zhǔn)對download_url進(jìn)行簽名,并發(fā)起請求即可下載賬單文件的數(shù)據(jù)流,參考右側(cè)請求示例。
提示
在下載賬單時,當(dāng)子商戶資金賬單文件太大(未壓縮情況下約大于16GB)時,微信支付會對賬單文件進(jìn)行分割,此時接口會返回多個下載地址。商戶分別根據(jù)下載地址下載賬單文件并解密。解密后,將多個文件按賬單文件序號(變量名:bill_sequence)的順序合并為完整的資金賬單文件。
商戶需要注意,當(dāng)返回多個下載地址時,商戶依然需要在下載地址有效時間內(nèi)發(fā)起下載請求。因此建議商戶獲取到下載地址后,并發(fā)請求下載。
申請賬單返回參數(shù)示例
1{2 "download_bill_count": 1,3 "download_bill_list": [4 {5 "bill_sequence": 1,6 "download_url": "https://api.mch.weixin.qq.com/v3/bill/downloadurl?token=xxx",7 "encrypt_key": "a0YK7p+9XaKzE9N4qtFfG/9za1oqKlLXXJWBkH+kX84onAs2Ol/E1fk+6S+FuBXczGDRU8I8D+6PfbwKYBGm0wANUTqHOSezzfbieIo2t51UIId7sP9SoN38W2+IcYDviIsu59KSdyiL3TY2xqZNT8UDcnMWzTNZdSv+CLsSgblB6OKGN9JONTadOFGfv1OKkTp86Li+X7S9bG62wsa572/5Rm4MmDCiKwY4bX2EynWQHBEOExD5URxT6/MX3F1D3BNYrE4fUu1F03k25xVlXnZDjksy6Rf3SCgadR+Cepc6mdfF9b2gTxNsJFMEdYXbqL0W1WQZ3UqSPQCguK6uLA==",8 "hash_type": "SHA1",9 "hash_value": "79bb0f45fc4c42234a918000b2668d689e2bde04",10 "nonce": "a8607ef79034c49c"11 }12 ]13}
請求示例
1$ curl https://api.mch.weixin.qq.com/v3/billdownload/file?token=xxx -H '2Authorization: WECHATPAY2-SHA256-RSA2048 mchid="1900009191",3nonce_str="593BEC0C930BF1AFEB40B4A08C8FB242",4signature="uOVRnA4qG/MNnYzdQxJanN+zU+lTgIcnU9BxGw5dKjK+VdEUz2FeIoC+D5sB/LN+nGzX3hfZg6r55wT1pl2ZobmIc6p0ldN7J6yDgUzbX8Uk3sD4a4eZVPTBvqNDoUqcYMlZ9uuDdCvNv4TM3c1WzsXUrExwVkI61XO5jCNbgDJ25nkT/c1gIFvqoogl7MdSFGc4W4xZsqCItnqbypR3RuGIlR9h9vlRsy7zJR9PBI83X8al7LDIfR1ukt1P7tMnmogZ0cuDY8cZsd8ZlCgLadmvej58SLsIkVxFJ8XyUgx9FmutKSYTmYtWBZ0+tNvfGmbXU7cob8H/84nLBiCwIUFluw==",timestamp="1554208460",serial_no="1DDE55AD98ED71D6EDD4A4A16996DE7B47773A8C"'
# 步驟2:解密賬單
# 解密流程
子商戶資金賬單文件采用商戶指定的加密算法(支持AES-256-GCM算法和SM4-GCM算法)進(jìn)行加密,商戶需要進(jìn)行解密才能得到賬單明文。解密流程是:
- 通過步驟1:下載賬單可以得到賬單文件密文ciphertext;
- 使用商戶證書私鑰解密從接口獲取的加密密鑰(變量名:encrypt_key)得到密鑰明文key,詳細(xì)可參考:encrypt_key密鑰解密
- 利用前面得到的賬單密文ciphertext,密鑰key和接口返回的隨機(jī)字符串nonce解密賬單,得到賬單明文。
提示
GCM即可以進(jìn)行加密,又可以對信息的完整性進(jìn)行校驗,因此基于GCM加密的賬單,解密成功則表示賬單完整性校驗通過。
基于AES-256-GCM算法加密的賬單文件解密代碼示例
賬單文件解密代碼示例請參考WechatPay-API-v3 證書和回調(diào)報文解密,注意:返回的賬單文件是二進(jìn)制密文,需以字節(jié)數(shù)組形式處理,不需要進(jìn)行Base64解碼。
下面對解密代碼中使用的參數(shù)進(jìn)行說明:
1{2 // 密文3 "ciphertext": "下載得到的賬單文件密文",4 // 加密使用的密鑰5 "key": "用商戶證書私鑰解密加密密鑰得到的明文",6 // 加密使用的隨機(jī)字符串7 "nonce": "接口返回的隨機(jī)字符串", 8 // 附加數(shù)據(jù)包(填空)9 "associated_data": "" 10 }
基于SM4算法加密的賬單文件解密代碼示例
1with open(r"./ciphertext", 'rb') as f:2 ciphertext_tag_bytes = f.read()3ciphertext_tag_hex = binascii.b2a_hex(ciphertext_tag_bytes)45# 賬單密文最后16字節(jié)是消息驗證碼6ciphertext_bytes = binascii.unhexlify(ciphertext_tag_hex[:-32])7tag_bytes = binascii.unhexlify(ciphertext_tag_hex[-32:])8key="cbf063b0b33781c3"9key_bytes = str.encode(key)10iv="09ba90b74310"11iv_bytes = str.encode(iv)12aad = ''1314# 賬單明文15decrypt_plain = SM4_GCM_Decrypt_NoPadding_NIST_SP800_38D(ciphertext_bytes, key_bytes, iv_bytes, aad, tag_bytes)
# encrypt_key密鑰解密
# RSA-2048加解密
如果HTTP頭的Authorization的認(rèn)證類型采用WECHATPAY2-SHA256-RSA2048, 則從接口獲取的加密密鑰(變量名:encrypt_key)是使用商戶證書公鑰進(jìn)行RSA加密返回的密文,商戶需解密后才能得到密鑰原文。
解密流程:對encrypt_key先做Base64解碼,然后對解碼結(jié)果使用商戶證書私鑰進(jìn)行RSA解密,指定填充方式為最優(yōu)非對稱加密填充(OAEP)。
請參考右側(cè)我們使用命令行演示如何解密,更多的示例可以參考WechatPay-API-v3 敏感信息加密, 解密AES密鑰得到key。
RSA-2048加解密示例
1# 解密AES密鑰得到key:2$ echo -n { encrypt_key } | openssl enc -A -base64 -d | openssl rsautl -decrypt -oaep -inkey {商戶證書私鑰文件}
# SM2加解密
如果HTTP頭的Authorization的認(rèn)證類型采用WECHATPAY2-SM2-WITH-SM3, 則從接口獲取的加密密鑰(變量名:encrypt_key)是使用SM2橢圓曲線公鑰密碼算法加密返回的密文,商戶需解密后才能得到密鑰原文。
解密流程:對encrypt_key先做Base64解碼,然后對解碼結(jié)果使用商戶證書私鑰進(jìn)行SM2解密,密文格式是C1C3C2_ASN1。
SM2加解密示例
1# 解密AES密鑰得到key2SM2Init()3cipher = 'MIGKAiEA4FdfXZIG9oaS4v0CrCcFWAhQR0mR04cwZwFqP6lWwfACIQCGIdcc9PD9ZXmjvpyhbY0/lcww+UCp3+LP1yelYWpdbQQg5D4m4+JIyCyUwhwGuxMGPZR+bNmc2AVhlPQWj99WfT8EIOiAP7dYMFbc3HUHTt8F0RpGQns6zWhc3snUeMdkAWXF'4priv = "2f9f54d3a8793c50af8c61d10f88856cfcad6297f33b910b7f1093846083e835"5SM2CipherMode_C1C3C2_ASN1 = 06decrypt_plain = SM2DecryptWithMode(base64.b64decode(cipher), priv, SM2CipherMode_C1C3C2_ASN1)7# 預(yù)期返回 SM2 Decrypt binary data, Plain is -------c6fafbae361863c146f0a1c27ff9c1a28print("SM2 Decrypt binary data, Plain is -------"+decrypt_plain.decode('utf-8'))
# 返回信息
# 文件格式說明
賬單文件包括明細(xì)數(shù)據(jù)和匯總數(shù)據(jù)兩部分,每一部分都包含一行表頭和若干行具體數(shù)據(jù)。
明細(xì)數(shù)據(jù)每一行對應(yīng)一筆資金操作,同時每一個數(shù)據(jù)前加入了字符,以避免數(shù)據(jù)被Excel按科學(xué)計數(shù)法處理。如需匯總金額等數(shù)據(jù),可以批量替換掉該字符。
# 示例文件
單個子商戶資金賬單: 解密后的資金賬單示例 (opens new window)
電商平臺二級商戶資金賬單: 解密后的賬單示例 (opens new window)
# 錯誤碼
# 公共錯誤碼
狀態(tài)碼 | 錯誤碼 | 描述 | 解決方案 |
---|---|---|---|
400 | PARAM_ERROR | 參數(shù)錯誤 | 請根據(jù)錯誤提示正確傳入?yún)?shù) |
400 | INVALID_REQUEST | HTTP 請求不符合微信支付 APIv3 接口規(guī)則 | 請參閱 接口規(guī)則 |
401 | SIGN_ERROR | 驗證不通過 | 請參閱 簽名常見問題 |
500 | SYSTEM_ERROR | 系統(tǒng)異常,請稍后重試 | 請稍后重試 |
# 業(yè)務(wù)錯誤碼
狀態(tài)碼 | 錯誤碼 | 描述 | 解決方案 |
---|---|---|---|
400 | INVALID_REQUEST | 參數(shù)錯誤 | 請按第一步申請賬單的API指引,重新獲取賬單地址后再請求 |
403 | NO_AUTH | 權(quán)限異常 | 請檢查本次請求的商戶是否與第一步申請賬單API的請求商戶一致 |