下载请客账单

更新时间：2026.01.16

应用场景

本接口适用于下载社交活动请客账单。

注意

该接口响应的信息请求头中不包含微信接口响应的签名值，因此需要跳过验签的流程。
账单文件的下载地址的有效时间为5min。
建议商户比对实际下载账单文件的哈希值和从接口获取到的哈希值是否一致，以确认下载账单数据的完整性。
微信将在次日9点开始生成前一天的对账单，建议商户在10点后获取。

接口说明

支持商户：【品牌商户】

请求方式：【GET】

请求URL：调用申请请客账单接口，返回参数“download_url”对应的URL

请求步骤说明

步骤1：下载账单

1、使用申请请客账单接口获取download_url，参考下方申请账单返回参数示例。

申请请客账单返回参数示例

1{
2  "hash_type" : "SHA1",
3  "hash_value" : "79bb0f45fc4c42234a918000b2668d689e2bde04",
4  "download_url" : "https://api.mch.weixin.qq.com/v3/bill/downloadurl?token=xxx",
5  "encrypt_key" : "a0YK7p+9XaKzE9N4qtFfG/9za1oqKlLXXJWBkH+kX84onAs2Ol/E1fk+6S+FuBXczGDRU8I8D+6PfbwKYBGm0wANUTqHOSezzfbieIo2t51UIId7sP9SoN38W2+IcYDviIsu59KSdyiL3TY2xqZNT8UDcnMWzTNZdSv+CLsSgblB6OKGN9JONTadOFGfv1OKkTp86Li+X7S9bG62wsa572/5Rm4MmDCiKwY4bX2EynWQHBEOExD5URxT6/MX3F1D3BNYrE4fUu1F03k25xVlXnZDjksy6Rf3SCgadR+Cepc6mdfF9b2gTxNsJFMEdYXbqL0W1WQZ3UqSPQCguK6uLA==",
6  "nonce" : "a8607ef79034c49c"
7}

2、使用品牌API标准对download_url进行签名，并发起请求即可下载账单文件的数据流，参考下方请求示例。

请求示例

1$ curl https://api.mch.weixin.qq.com/v3/billdownload/file?token=xxx -H '
2Authorization: WECHATPAY-BRAND-SHA256-RSA2048 brand_id="100XX",
3nonce_str="593BEC0C930BF1AFEB40B4A08C8FB242",
4signature="AGqDkww6H1Yva2ftvZfUIVRDgLHA15iwfl5kta7T0pyUgp1giG/MFQhsUnfz
5RxNYOU9gdJfw3kZJyqAlmGsKjfldHRpXgMbnlTimMRWwJgOcC56fh8Bf3ecCLd60yio+GD+
6WfB8KwooCaHcst8G0VgIKmUS6qJ3TcmbR9/6XcfaZamxnEeIoAJ6CkD7oDx84MT2Je9QvQ0
7LXC+ONguf1z/Wydl1GE6YXJYivRxnl4jFGThsp4i4IagjfsZzihNppia5vQcyINnkJUo4YV
8aIa77pgMWVuVMSP0iCJAwU4jqRgRUeCLxL9eeGENyiwfDBB6EFmybwPlsJORsn3iitGtg==",
9timestamp="1554208460",
10serial_no="3493DE0D9BB4EB98A8C65EAA7E8EE887EC24B71A"'

步骤2：解密账单

请客账单文件采用SM4-GCM算法进行加密，商户需要进行解密才能得到账单明文。解密流程如下：

1、通过步骤1：下载账单可以得到账单文件密文ciphertext；

2、使用品牌证书私钥解密从接口获取的加密密钥（变量名：encrypt_key）得到密钥明文key，encrypt_key密钥解密方式如下：

RSA-2048加解密

如果HTTP头的Authorization的认证类型采用WECHATPAY-BRAND-SHA256-RSA2048, 则从接口获取的加密密钥（变量名：encrypt_key）是使用品牌证书公钥进行RSA加密返回的密文，商户需解密后才能得到密钥原文。

解密流程：对encrypt_key先做Base64解码，然后对解码结果使用商户证书私钥进行RSA解密，指定填充方式为最优非对称加密填充(OAEP)。

可以参考如何使用品牌API证书解密敏感字段进行解密得到key。

3、利用前面得到的账单密文ciphertext，密钥key和接口返回的随机字符串nonce解密账单，得到账单明文，解密账单文件密文如下：

提示

GCM即可以进行加密，又可以对信息的完整性进行校验，因此基于GCM加密的账单，解密成功则表示账单完整性校验通过。

基于SM4算法加密的账单文件解密代码示例

1with open(r"./ciphertext", 'rb') as f:
2    ciphertext_tag_bytes = f.read()
3ciphertext_tag_hex  = binascii.b2a_hex(ciphertext_tag_bytes)
4# 账单密文最后16字节是消息验证码
5ciphertext_bytes = binascii.unhexlify(ciphertext_tag_hex[:-32])
6tag_bytes = binascii.unhexlify(ciphertext_tag_hex[-32:])
7key="cbf063b0b33781c3"
8key_bytes = str.encode(key)
9iv="09ba90b74310"
10iv_bytes = str.encode(iv)
11aad = ''
12# 账单明文
13decrypt_plain = SM4_GCM_Decrypt_NoPadding_NIST_SP800_38D(ciphertext_bytes, key_bytes, iv_bytes, aad, tag_bytes)

返回信息

文件格式说明

账单文件包含一行表头和若干行明细数据。

明细数据每个字段使用英文逗号 , 间隔，明细数据内容每个字段前会增加1个字符 ` 用于避免获取的内容被excel展示为科学计数法的格式、丢失数据细节。

具体字段

字段名	描述	示例值
日期	数据分区日期（yyyyMMdd格式）	20260106
活动ID	请客的活动ID	b5ef10677246411fbd5b4809d9de55f3
活动名称	base64编码的活动名称	5paw5bm06K+35pyL5Y+L5Zad5LiA5p2v4piV77iP
品牌ID	品牌ID	100000006006
品牌名称	品牌名称（base64编码）	aW1hZ2XniLHpqazlk6XlkpbllaE=
券ID	创建的礼品券ID	5fe0cb2d46544f77a80edcce1877e0ca
券面值	商品券的购买面值（单位：分）	1000
券批次ID	商品券的券批次ID	701211100891764673358217829128
券CODE	商品券券CODE	1232127284000055448138
券状态	商品券状态 TO_BE_USED，待使用 USED，已核销 EXPIRED，已过期	USED
券状态时间	商品券状态变更时间，遵循rfc3339标准格式	2026-01-06T11:40:30+08:00
资金状态	商品券资金状态 DEFAULT，默认 SETTLED，已结算 REFUNDED，已退款	SETTLED
资金状态时间	商品券资金状态变更时间，遵循rfc3339标准格式	2026-01-06T11:41:36+08:00
券领取时间	用户领取时间，遵循rfc3339标准格式	2026-01-06T11:21:47+08:00
结算资金单号	对应微信支付商户平台的「资金账单」中的单号	420000123456789012345678901234567890
结算收款商户号	商户实际接收商户号	1234567890
平台手续费	微信支付扣除的平台手续费（单位：分）	20
结算金额	实际产生的结算金额（单位：分）	2020
结算时间	结算成功时间，遵循rfc3339标准格式	2025-12-29T08:25:00+08:00

错误码

以下是本接口返回的错误码列表。详细错误码规则，请参考微信支付接口规则-错误码和错误提示

状态码	错误码	描述	解决方案
400	PARAM_ERROR	参数错误	请根据错误提示正确传入参数
400	INVALID_REQUEST	HTTP 请求不符合微信支付 APIv3 接口规则	请参阅基本规则
401	SIGN_ERROR	验证不通过	请参阅为什么请求返回401 Unauthorized？
500	SYSTEM_ERROR	系统异常，请稍后重试	请稍后重试

文档是否有帮助

LLM请查看llms.txt

开发者社区微信开放平台微信公众平台腾讯客服