申请获取对账单

更新时间：2025.01.02

商户可以调用此接口获取对账单文件的下载链接，并在有效期内请求下载链接可以下载对账单文件。

文件解密

解密流程

子商户资金账单文件采用商户指定的加密算法（目前只支持AES-256-GCM算法）进行加密，商户需要进行解密才能得到账单明文。解密流程是：
步骤一：下载账单文件，得到账单文件密文ciphertext；
步骤二：使用商户证书私钥解密从接口获取的加密密钥（变量名：encrypt_key）得到密钥明文key；
步骤三：利用步骤一、二中得到的账单密文ciphertext，密钥key和接口返回的随机字符串nonce解密账单，得到账单明文。

代码示例

账单文件解密代码示例请参考WechatPay-API-v3 证书和回调报文解密，注意，返回的账单文件是二进制密文，不需要进行Base64解码。

接口说明

支持商户：【普通商户】

请求方式：【GET】/v3/payscore/merchant-bill

请求域名：【主域名】https://api.mch.weixin.qq.com 使用该域名将访问就近的接入点

　　　　　【备域名】https://api2.mch.weixin.qq.com 使用该域名将访问异地的接入点，指引点击查看

请求参数

Header HTTP头参数

Authorization 　必填　string

请参考签名认证生成认证信息

Accept 　必填　string

请设置为application/json

query 查询参数

bill_date 　必填 string(10)

【账单日期】格式YYYYMMDDHH，仅支持下载近三个月的账单

service_id 　必填 string(32)

【服务ID】支付分服务ID

tar_type 　必填 string

【账单压缩类型】账单的压缩类型

可选取值

GZIP: 返回.gzip格式的压缩文件

encryption_algorithm 　必填 string

【加密算法】对返回账单原文加密的算法

可选取值

AEAD_AES_256_GCM: 账单使用AEAD_AES_256_GCM加密算法进行加密

请求示例

GET

1curl -X GET \
2  https://api.mch.weixin.qq.com/v3/payscore/merchant-bill?bill_date=2021010122&service_id=2002000000000558128851361561536&tar_type=GZIP&encryption_algorithm=AEAD_AES_256_GCM \
3  -H "Authorization: WECHATPAY2-SHA256-RSA2048 mchid=\"1900000001\",..." \
4  -H "Accept: application/json" 
5

应答参数

200 OK

download_bill_count 　必填 integer

【下载信息总数】账单的分块数量

download_bill_list 　选填 array[object]

【下载信息明细】账单每个分块的详细信息

属性

bill_sequence 　必填 integer

【账单文件序号】商户将多个文件按账单文件序号的顺序合并为完整的资金账单文件，起始值为1

hash_type 　必填 string

【哈希类型】账单摘要计算方式

可选取值

SHA1: Secure Hash Algorithm 1

hash_value 　必填 string(1024)

【哈希值】原始账单（gzip需要解压缩）的摘要值，用于校验文件的完整性

download_url 　必填 string(2048)

【下载地址】下载地址5min内有效

encrypt_key 　必填 string(512)

【加密密钥】加密账单文件使用的加密密钥。密钥用商户证书的公钥进行加密，然后进行Base64编码

nonce 　必填 string(16)

【随机字符串】加密账单文件使用的随机字符串

应答示例

200 OK

1{
2  "download_bill_count" : 1,
3  "download_bill_list" : [
4    {
5      "bill_sequence" : 1,
6      "hash_type" : "SHA1",
7      "hash_value" : "79bb0f45fc4c42234a918000b2668d689e2bde04",
8      "download_url" : "https://api.mch.weixin.qq.com/v3/payscore/bill/downloadurl?token=xxx",
9      "encrypt_key" : "a0YK7p+9XaKzE9N4qtFfG/9za1oqKlLXXJWBkH+kX84onAs2Ol/E1fk+6S+FuBXczGDRU8I8D+6PfbwKYBGm0wANUTqHOSezzfbieIo2t51UIId7sP9SoN38W2+IcYDviIsu59KSdyiL3TY2xqZNT8UDcnMWzTNZdSv+CLsSgblB6OKGN9JONTadOFGfv1OKkTp86Li+X7S9bG62wsa572/5Rm4MmDCiKwY4bX2EynWQHBEOExD5URxT6/MX3F1D3BNYrE4fUu1F03k25xVlXnZDjksy6Rf3SCgadR+Cepc6mdfF9b2gTxNsJFMEdYXbqL0W1WQZ3UqSPQCguK6uLA==",
10      "nonce" : "5K8264ILTKCH"
11    }
12  ]
13}
14

错误码

公共错误码

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

业务错误码

状态码	错误码	描述	解决方案
403	NO_AUTH	商户暂无权限使用此功能	请开通商户号权限。请联系产品申请

文档是否有帮助

更多支持

开发文档(服务商)开发文档(V2版)开发者社区微信开放平台微信公众平台腾讯客服