基础支付
JSAPI支付
APP支付
Native支付
小程序支付
合单支付
付款码支付
经营能力
微信支付分(免确认预授权模式)
微信支付分(需确认模式)
微信支付分(公共API)
支付即服务
行业方案
智慧商圈
微信支付分停车服务
营销工具
代金券
商家券
委托营销
消费卡
支付有礼
小程序发券插件
H5发券
图片上传(营销专用)
现金红包
资金应用
付款
分账
风险合规
消费者投诉2.0
其他能力
清关报关
图片上传
视频上传

商户申请获取对账单API

最新更新时间:2021.09.18 版本说明


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

注意:

● 商户获取到的对账单数据,需先解密、再解压,才能得到原始账单文件。

接口说明

适用对象:直连商户

请求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

{
JAVA示例代码
}

返回参数

参数名 变量 类型[长度限制] 必填 描述
下载信息总数 download_bill_count int 账单的分块数量
示例值:1
+ 下载信息明细 download_bill_list array 账单每个分块的详细信息
参数名 变量 类型[长度限制] 必填 描述
账单文件序号 bill_sequence int 商户将多个文件按账单文件序号的顺序合并为完整的资金账单文件,起始值为1
示例值:1
哈希类型 hash_type string 账单摘要计算方式
SHA1:SHA1值,Secure Hash Algorithm 1
示例值:SHA1
哈希值 hash_value string[1, 1024] 原始账单(gzip需要解压缩)的摘要值,用于校验文件的完整性
示例值:79bb0f45fc4c42234a918000b2668d689e2bde04
下载地址 download_url string[1, 2048] 下载地址5min内有效
示例值:https://api.mch.weixin.qq.com/v3/payscore/bill/downloadurl?token=xxx
加密密钥 encrypt_key string[1, 512] 加密账单文件使用的加密密钥。密钥用商户证书的公钥进行加密,然后进行Base64编码
示例值:a0YK7p+9XaKzE9N4qtFfG/9za1oqKlLXXJWBkH+kX84onAs2Ol/E1fk+6S+FuBXczGDRU8I8D+6PfbwKYBGm0wANUTqHOSezzfbieIo2t51UIId7sP9SoN38W2+IcYDviIsu59KSdyiL3TY2xqZNT8UDcnMWzTNZdSv+CLsSgblB6OKGN9JONTadOFGfv1OKkTp86Li+X7S9bG62wsa572/5Rm4MmDCiKwY4bX2EynWQHBEOExD5URxT6/MX3F1D3BNYrE4fUu1F03k25xVlXnZDjksy6Rf3SCgadR+Cepc6mdfF9b2gTxNsJFMEdYXbqL0W1WQZ3UqSPQCguK6uLA==
随机字符串 nonce string[1, 16] 加密账单文件使用的随机字符串
示例值:5K8264ILTKCH16CQ2502SI8ZNMTM67VS

返回示例


{
  "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"
    }
  ]
}
                    

http://2323weixin.qq.com
                    

文件解密

解密流程

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

代码示例

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

下面对解密代码中使用的参数进行说明:

{
        // 密文
        "ciphertext": "下载得到的账单文件密文",
        // 加密使用的密钥
         "key": "用商户证书私钥解密加密密钥得到的明文",
        // 加密使用的随机字符串
        "nonce": "接口返回的随机字符串", 
        // 附加数据包(填空)
        "associated_data": "" 
}                

http://2323weixin.qq.com
                    

下面对如何用商户证书私钥解密加密密钥进行说明:
商户从接口获取的加密密钥(变量名: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 {商户证书私钥文件} 
                    

http://2323weixin.qq.com
                    

错误码公共错误码

状态码 错误码 描述 解决方案
400 PARAM_ERROR 参数错误 请使用正确的参数重新调用
403 NO_AUTH 商户暂无权限使用此功能 请开通商户号权限。请联系产品申请




技术咨询

文档反馈