下载账单
更新时间：2024.01.17本接口适用于下载交易账单和资金账单。
注意
- 该接口响应的信息请求头中不包含微信接口响应的签名值，因此需要跳过验签的流程。
- 账单文件的下载地址的有效时间为5min。
- 建议商户比对实际下载账单文件的哈希值和从接口获取到的哈希值是否一致，以确认下载账单数据的完整性。
- 微信将在次日9点开始生成前一天的对账单，建议商户在10点后获取。
# 接口说明
支持商户： 【普通服务商】 【普通商户】
请求方式： 【GET】
请求URL： 调用申请账单接口，返回参数“download_url”对应的URL
# 请求步骤说明
- 使用申请账单接口获取download_url，参考下方申请账单返回参数示例。
- 使用微信支付APIv3标准对download_url进行签名，并发起请求即可下载账单文件的数据流，参考右侧请求示例。
# 申请账单返回参数示例
1{2 "hash_type": "SHA1",3 "hash_value": "79bb0f45fc4c42234a918000b2668d689e2bde04",4 "download_url": " https://api.mch.weixin.qq.com/v3/billdownload/file?token=xxx"5}请求示例
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"'# 返回信息
# 1. 交易账单
# 1.1. 交易账单介绍
微信支付每天提供前一天的交易账单文件，用于商户核对订单、退款、营销、手续费等信息。账单内的数据包括：
（1）当天支付成功的订单，下单成功但用户未支付的订单不会出账。
（2）当天发起退款成功的退款单，退款发起成功就会出账，出账后退款状态不会更新。如果需要获取最新退款状态，请使用查询单笔退款API查询。
微信支付提供了3份不同类型的账单文件：
- ALL，包含了当天支付成功的订单和发起成功的退款单
- SUCCESS，仅包含支付成功的订单
- REFUND，仅包含发起成功的退款单
# 1.2. 交易账单文件格式
交易账单文件内包含：明细数据表头、明细数据内容、汇总数据表头、汇总数据四个部分，每个字段使用英文逗号 , 间隔，明细数据内容每个字段前会增加1个字符 ` 用于避免获取的内容被excel展示为科学计数法的格式、丢失数据细节。3份不同类型的账单文件字段内容略有差异。
# 1.2.1. ALL类型账单文件具体字段
| 字段名 | 描述 | 示例值 |
|---|---|---|
| 明细数据 | ||
| 交易时间 | 指该笔交易的支付成功时间或发起退款成功时间（注：不是退款成功时间），格式为yyyy-MM-dd HH:MM:SS | 2015-01-01 10:00:00 |
| 公众账号ID | 发起该笔交易时使用的AppID，AppID是由微信给公众号或App等分配的唯一标识 | wxab8acb865bb11234 |
| 商户号 | 发起该笔交易下单的微信支付商户号，8~10位数字 | 1234567890 |
| 特约商户号 | 如果是普通受理模式下的交易，展示特约商户的商户号，8~10位数字 如果是普通直连模式交易，则展示成数字0 | 1234567890 |
| 设备号 | 对应在下单时传入的device_info字段，没填写则留空 | casher001 |
| 微信订单号 | 微信支付为该笔订单（或该笔退款对应的订单）分配的订单号 | 4200000008201712143733500001 |
| 商户订单号 | 商户传入的该笔订单（或该笔退款对应的订单）的商户订单号，对应下单接口里的out_trade_no字段 | outtradeno001 |
| 用户标识 | 微信为支付用户在公众账号ID(AppID)下分配的唯一标识(OpenID) | testxt08c-XB5-QD208X1Aid0Cbs |
| 交易类型 | 该笔订单（或该笔退款单对应的订单）的类型，使用英文缩写展示，包括但不限于（后续可能新增）： MICROPAY：付款码支付 JSAPI：JSAPI支付、小程序支付NATIVE：NATIVE支付APP：App支付 FACE：刷脸支付 | NATIVE |
| 交易状态 | 标识该笔明细数据的类型：SUCCESS：支付成功，说明该行数据为一笔支付成功的订单REFUND：转入退款，说明该行数据为一笔发起退款成功的退款单REVOKED：已撤销，说明该行数据为一笔在用户支付成功后发起撤销的退款单 | SUCCESS |
| 付款银行 | 用户支付时使用的付款方式，包括但不限于（后续可能新增）：XXX_CREDIT：用户使用了XXX银行的一张信用卡付款XXX_DEBIT：用户使用了XXX银行的一张储蓄卡付款OTHERS：用户使用了零钱/零钱通等其他付款方式 | CMB_CREDIT |
| 货币种类 | 货币类型，符合ISO 4217标准的三位字母代码 | CNY |
| 应结订单金额 | 该笔订单参与计费的应结算金额（=订单金额-用户使用的免充值券金额），如果该行数据为退款或撤销则展示0.00，单位元，保留到小数点后2位 | 8.88 |
| 代金券金额 | 该笔订单中使用的微信支付代金券金额（包括充值券和免充值券），如果未使用代金券、或该行数据为退款或撤销则展示0.00，单位元，保留到小数点后2位 | 0.88 |
| 微信退款单号 | 微信支付为该笔退款分配的退款单号，如果该行数据为订单（交易状态SUCCESS）则展示0 | 50401010122021000000038202001 |
| 商户退款单号 | 商户发起退款时填入的商户退款单号，如果该行数据为订单（交易状态SUCCESS）则展示0 | refundno001 |
| 退款金额 | 该笔退款单参与计费的应结算金额（申请退款金额-免充值券退款金额），如果该行数据为订单则展示为0.00，非负数、单位元，保留到小数点后2位 | 6.66 |
| 充值券退款金额 | 退款金额中包含的充值券退款金额，如果该行数据为订单或没有充值券退款则展示为0.00，非负数、单位元，保留到小数点后2位 | 0.66 |
| 退款类型 | ORIGINAL：原路退款BALANCE：转退到用户的微信支付零钱PLATFORM-ORIGINAL：平台退款，原路退款PLATFORM-BALANCE：平台退款，转退到用户的微信支付零钱如果该行数据为订单（交易状态 SUCCESS）则留空 | ORIGINAL |
| 退款状态 | 生成账单文件时该笔退款的状态、出账后不会更新，如果该行数据为订单（交易状态SUCCESS），则留空SUCCESS：退款成功PROCESSING：退款处理中FAIL：退款失败CHANGE：退款异常 | SUCCESS |
| 商品名称 | 商户传入的该笔订单（或该笔退款对应的订单）的商品名称，对应下单接口里的body字段 | 零食 |
| 商户数据包 | 商户传入的该笔订单（或该笔退款对应的订单）的商户数据包，对应下单接口里的attach字段，不传时留空 | 交易收款 |
| 手续费 | 该笔订单/退款对应的手续费金额，订单对应正数、退款对应负数，单位元，保留小数点后2位 | 0.01 |
| 费率 | 该笔交易计费所使用的费率，百分数 | 0.60% |
| 订单金额 | 该笔订单的金额，包括用户支付金额、充值券金额、免充值券金额，如果该行数据为退款或撤销则填0.00，单位元，保留到小数点后2位 | 9.76 |
| 申请退款金额 | 商户发起退款的金额，包括退给用户的金额、充值券退款金额、免充值券退款金额，如果该行数据订单则填0.00，单位元，保留到小数点后2位 | 6.66 |
| 费率备注 | 对计费费率的补充说明，如入驻结算规则ID、优惠费率活动ID等，可为空 | 726 |
| 汇总数据 | ||
| 总交易单数 | 该份账单内明细数据的笔数 | 200 |
| 应结订单总金额 | 账单内所有应结订单金额字段之和，保留小数点后2位 | 888.00 |
| 退款总金额 | 账单内所有退款金额字段之和，保留小数点后2位 | 666.00 |
| 充值券退款总金额 | 账单内所有充值券退款金额字段之和，保留小数点后2位 | 6.60 |
| 手续费总金额 | 账单内所有交易手续费字段之和，保留小数点后2位 | 10.00 |
| 订单总金额 | 账单内所有交易订单金额字段之和，保留小数点后2位 | 976.00 |
| 申请退款总金额 | 账单内所有申请退款金额字段之和，保留小数点后2位 | 666.00 |
# 1.2.2. SUCCESS和REFUND账单
SUCCESS和REFUND账单的字段和ALL账单内略有不同：
SUCCESS账单字段：交易时间,公众账号ID,商户号,特约商户号,设备号,微信订单号,商户订单号,用户标识,交易类型,交易状态,付款银行,货币种类,应结订单金额,代金券金额,商品名称,商户数据包,手续费,费率,订单金额,费率备注
REFUND账单字段：交易时间,公众账号ID,商户号,特约商户号,设备号,微信订单号,商户订单号,用户标识,交易类型,交易状态,付款银行,货币种类,应结订单金额,代金券金额,退款申请时间,退款成功时间,微信退款单号,商户退款单号,退款金额,充值券退款金额,退款类型,退款状态,商品名称,商户数据包,手续费,费率,订单金额,申请退款金额,费率备注
# 1.2.3. 特殊字符转义
账单处理过程会对商品名称、商户数据包、设备号等商户自定义字段进行特殊字符转义，具体规则包括：
| 原始特殊字符 Unicode | 含义 | 订单转义 Unicode | 含义 | 退款单转义 Unicode | 含义 |
|---|---|---|---|---|---|
\u005c | \ | \u005c\u005c | \\ | \u005c\u005c | \\ |
\u0027 | ' | \u005c\u0027 | \' | \u0027 | ' |
\u0022 | " | \u005c\u0022 | \" | \u005c\u0022 | \" |
\u0060 | ` | \u005c\u0060 | \` | \u005c\u0031\u0034\u0030 | \140 |
\u002c | , | \u005c\u0020 | \空格 | \u005c\u0020 | \空格 |
\u000a | 换行符(LF) | \u005c\u006e | \n | \u005c\u006e | \n |
\u000d | 回车符(CR) | \u005c\u0072 | \r | \u005c\u0072 | \r |
\u0009 | 制表符(HT) | \u005c\u0074 | \t | \u005c\u0074 | \t |
\ue000 | 不可见字符(\xee\x80\x80) | \u005c\u0020 | \空格 | \u005c\u0020 | \空格 |
\u001a | 控制字符SUB(\032) | \u005c\u001a | \控制字符SUB | \u005c\u001a | \控制字符SUB |
# 1.2.4. 补充说明
少部分商户目前的账单格式停留在历史早期版本，具体表现为：没有应结算订单金额字段、对应的是总金额字段，没有代金券金额字段、对应的是企业红包金额字段。如需调整为最新格式的账单，可以通过在产品中心中开通免充值优惠券功能，次日开始的账单格式即会完成变更。
# 1.3. 账单样例
# 2. 资金账单
# 2.1. 账单样例
# 错误码
# 公共错误码
| 状态码 | 错误码 | 描述 | 解决方案 |
|---|---|---|---|
| 400 | PARAM_ERROR | 参数错误 | 请根据错误提示正确传入参数 |
| 400 | INVALID_REQUEST | HTTP 请求不符合微信支付 APIv3 接口规则 | 请参阅 接口规则 |
| 401 | SIGN_ERROR | 验证不通过 | 请参阅 签名常见问题 |
| 500 | SYSTEM_ERROR | 系统异常，请稍后重试 | 请稍后重试 |
# 业务错误码
| 状态码 | 错误码 | 描述 | 解决方案 |
|---|---|---|---|
| 400 | INVALID_REQUEST | 参数错误 | 请按第一步申请账单的API指引，重新获取账单地址后再请求 |
| 403 | NO_AUTH | 权限异常 | 请检查本次请求的商户是否与第一步申请账单API的请求商户一致 |
文档是否有帮助
商户文档
