最新更新时间：2021.11.23 版本说明
商户可以调用此接口获取对账单文件的下载链接，并在有效期内请求下载链接可以下载对账单文件。
● 商户获取到的对账单数据，需先解密、再解压，才能得到原始账单文件。
适用对象：直连商户
请求URL：https://api.mch.weixin.qq.com/v3/payscore/merchant-bill
请求方式：GET
path 指该参数为路径参数
query 指该参数为URL参数
body 指该参数需在请求JSON传参
| 参数名 | 变量 | 类型[长度限制] | 必填 | 描述 |
|---|---|---|---|---|
| 账单日期 | bill_date | string[1, 10] | 是 | query格式yyyy-MM-DD，仅支持下载近三个月的账单 示例值：2021-01-01 |
| 账单压缩类型 | tar_type | string | 是 | query账单的压缩类型 GZIP：文件压缩方式为gzip，返回.gzip格式的压缩文件 示例值：GZIP |
| 加密算法 | encryption_algorithm | string | 是 | query对返回账单原文加密的算法 AEAD_AES_256_GCM：AEAD_AES_256_GCM加密算法，账单使用AEAD_AES_256_GCM加密算法进行加密 示例值：AEAD_AES_256_GCM |
| 服务ID | service_id | string[1, 32] | 是 | query支付分服务ID 示例值：2002000000000558128851361561536 |
https://api.mch.weixin.qq.com/v3/payscore/merchant-bill?bill_date=2021-01-01&tar_type=GZIP&encryption_algorithm=AEAD_AES_256_GCM&service_id=2002000000000558128851361561536
| 参数名 | 变量 | 类型[长度限制] | 必填 | 描述 |
|---|---|---|---|---|
| 下载信息总数 | download_bill_count | int | 是 | 账单的分块数量 示例值：1 |
| + 下载信息明细 | download_bill_list | array | 是 | 账单每个分块的详细信息 |
{
"download_bill_count": 1,
"download_bill_list": [
{
"bill_sequence": 1,
"download_url": "https://api.mch.weixin.qq.com/v3/payscore/bill/downloadurl?token=xxx",
"encrypt_key": "a0YK7p+9XaKzE9N4qtFfG/9za1oqKlLXXJWBkH+kX84onAs2Ol/E1fk+6S+FuBXczGDRU8I8D+6PfbwKYBGm0wANUTqHOSezzfbieIo2t51UIId7sP9SoN38W2+IcYDviIsu59KSdyiL3TY2xqZNT8UDcnMWzTNZdSv+CLsSgblB6OKGN9JONTadOFGfv1OKkTp86Li+X7S9bG62wsa572/5Rm4MmDCiKwY4bX2EynWQHBEOExD5URxT6/MX3F1D3BNYrE4fUu1F03k25xVlXnZDjksy6Rf3SCgadR+Cepc6mdfF9b2gTxNsJFMEdYXbqL0W1WQZ3UqSPQCguK6uLA==",
"hash_type": "SHA1",
"hash_value": "79bb0f45fc4c42234a918000b2668d689e2bde04",
"nonce": "5K8264ILTKCH16CQ2502SI8ZNMTM67VS"
}
]
}
商户资金账单文件采用商户指定的加密算法（目前只支持AES-256-GCM算法）进行加密，商户需要进行解密才能得到账单明文。解密流程是：
步骤1 下载账单文件，得到账单文件密文ciphertext；
步骤2 使用商户证书私钥解密从接口获取的加密密钥（变量名：encrypt_key）得到密钥明文key；
步骤3 利用步骤一、二中得到的账单密文ciphertext，密钥key和接口返回的随机字符串nonce解密账单，得到账单明文。
账单文件解密代码示例请参考[WechatPay-API-v3 证书和回调报文解密]，注意：返回的账单文件是二进制密文，不需要进行Base64解码。
下面对解密代码中使用的参数进行说明：
{
// 密文
"ciphertext": "下载得到的账单文件密文",
// 加密使用的密钥
"key": "用商户证书私钥解密加密密钥得到的明文",
// 加密使用的随机字符串
"nonce": "接口返回的随机字符串",
// 附加数据包（填空）
"associated_data": ""
} 下面对如何用商户证书私钥解密加密密钥进行说明：
商户从接口获取的加密密钥（变量名：encrypt_key）是使用商户证书公钥进行RSA加密返回的密文，商户解密后才能得到密钥原文。
解密流程如下：对encrypt_key先做Base64解码，然后对解码结果使用商户证书私钥进行RSA解密，指定填充方式为最优非对称加密填充(OAEP)。
下面我们使用命令行演示如何解密，更多的示例可以参考[WechatPay-API-v3 敏感信息加密]。
解密AES密钥得到key：
$ echo -n { encrypt_key } | openssl enc -A -base64 -d | openssl rsautl -decrypt -oaep -inkey {商户证书私钥文件}
| 状态码 | 错误码 | 描述 | 解决方案 |
|---|---|---|---|
| 400 | PARAM_ERROR | 参数错误 | 请使用正确的参数重新调用 |
| 403 | NO_AUTH | 商户暂无权限使用此功能 | 请开通商户号权限。请联系产品申请 |