下载对账单

更新时间：2025.01.07

商户可以通过该接口下载历史交易清单。比如掉单、系统错误等导致商户侧和微信侧数据不一致，通过对账单核对后可校正支付状态。

注意：

账单完整性校验：账单完整下载后，生成SHA1签名与微信返回HTTP头的Wechatpay-Statement-Sha1值做对比校验。
对账单接口只支持下载180天以内的账单。

1. 接口说明

适用对象: 直连模式机构模式

请求URL: https://apihk.mch.weixin.qq.com/v3/global/statements

请求方式: GET

Path 指该参数为路径参数

Query 指该参数为URL参数

Body 指该参数需在请求JSON传参

2. 请求参数

参数名	变量	类型[长度限制]	必填	描述
商户号	mchid	string[1,32]	是	Query 微信支付分配的商户号注意：仅适用于直连模式示例值：1900000109
机构商户号	sp_mchid	string[1, 32]	是	Query 微信支付分配的机构商户号注意：仅适用于机构模式示例值：1900000100
子商户号	sub_mchid	string[1, 32]	否	Query 微信支付分配的子商户号，如果传入子商户号，则只返回子商户号交易的账单，如果未传入子商户号，则返回机构全部子商户交易的账单。示例值：1900000109
账单日期	date	string[1,8]	是	Query 账单日期，格式：20180103 对账单接口只支持下载180天以内的账单。示例值：20180130

请求示例

直连模式

1https://apihk.mch.weixin.qq.com/v3/global/statements?date=20180130&mchid=1900000109

机构模式

1https://apihk.mch.weixin.qq.com/v3/global/statements?date=20180130&sp_mchid=1900000109
2https://apihk.mch.weixin.qq.com/v3/global/statements?date=20180130&sp_mchid=1900000109&sub_mchid=1900000102

3. 返回参数

正常返回

成功时，数据以文本表格的方式返回，第一行为表头，后面各行为对应的字段内容，字段内容跟查询订单或退款结果一致，具体字段说明可查阅相应接口。

1）第一行为表头，目前有：交易时间,公众账号ID,商户号,子商户号,设备号,微信订单号,商户订单号,用户标识,交易类型,交易状态,付款银行,充值券币种,充值券金额,优惠券币种,优惠券金额,微信退款单号,商户退款单号,退款类型,退款状态,商品名称,商户数据包,手续费,费率,标价币种,订单金额（标价币种）,用户支付币种,用户支付金额,结算币种,应结订单金额,支付汇率,退款汇率,申请退款金额,用户退款币种,用户退款金额,退款结算币种,退款应结订单金额,充值券退款金额,优惠券退款金额。

2）从第二行起，为数据记录，各参数以逗号分隔，参数前增加`符号，为标准键盘1左边键的字符，字段顺序与表头一致。

Field Name	字段类型	字段释义	Payment Example	Refund Example
Transaction Time	varchar(255)	指该笔交易的支付成功时间或发起退款成功时间（注：不是退款成功时间），格式为yyyy-MM-dd HH:MM:SS	`2024-03-11 10:00:00	`2024-03-11 10:00:00
Official Account ID(appid)	varchar(255)	发起该笔交易时使用的appid，appid是由微信给公众号或app等分配的唯一标识	`wx87b0b4160031234	`wx87b0b4160031234
Vendor ID(mchid)	varchar(255)	发起该笔交易下单的微信支付商户号	`123450000	`123450000
Sub vendor ID(sub_mchid)	varchar(255)	发起该笔交易下单的子商户号	`600000001	`600000001
Device ID(device_id)	varchar(255)	对应在下单时传入的device_info字段，没填写则留空	`013467007045764	`013467007045764
Wechat Order Number(transaction_id)	varchar(255)	微信支付为该笔订单（或该笔退款对应的订单）分配的订单号	`4200002158202403119854123456	`4200002158202403119854123456
Vendor Order Number(out_trade_no)	varchar(255)	商户传入的该笔订单（或该笔退款对应的订单）的商户订单号，对应下单接口里的out_trade_no字段	`20240311105346P3791	`20240311105346P3791
User Tag(openid)	varchar(255)	微信为支付用户在公众账号ID(appid)下分配的唯一标识(openid)	`oZPPassSdACFwnRNEVQVAkvj_5NU	`oZPPassSdACFwnRNEVQVAkvj_5NU
Transaction Type(trade_type)	varchar(50)	该笔订单（或该笔退款单对应的订单）的类型，使用英文缩写展示，包括但不限于（后续可能新增）： MICROPAY，付款码支付 JSAPI，JSAPI支付、小程序支付 NATIVE，Native支付 APP，APP支付 FACE，刷脸支付	`NATIVE	`NATIVE
Transaction Status(trade_state)	varchar(50)	标识该笔明细数据的类型： SUCCESS，支付成功，说明该行数据为一笔支付成功的订单 REFUND，转入退款，说明该行数据为一笔发起退款成功的退款单	`SUCCESS	`REFUND
Payment Bank(bank_type)	varchar(50)	用户支付时使用的付款方式，包括但不限于（后续可能新增）： XXX_CREDIT，用户使用了XXX银行的一张信用卡付款 XXX_DEBIT，用户使用了XXX银行的一张储蓄卡付款 WPHK，用户使用了香港钱包付款 OTHERS，用户使用了中国钱包零钱/零钱通等其他付款方式	`CMB_CREDIT	`CMB_CREDIT
Top-up Voucher Currency Type	varchar(50)	充值券币种（是商户出资的券）券币种为标价币种	`	`
Top-up Voucher Amount	varchar(255) 浮点型字符串，保留2位小数	充值券金额	`0.00	`0.00
Coupon Currency Type	varchar(50)	无关字段	`	`
Coupon Amount	varchar(255) 浮点型字符串，保留2位小数	无关字段	`0.00	`0.00
Wechat Refund Number(refund_id)	varchar(255)	微信支付为该笔退款分配的退款单号，如果该行数据为支付（交易状态SUCCESS）则展示0	`	`50202407752024031135708554321
Vendor Refund Number(out_refund_no)	varchar(255)	商户发起退款时填入的商户退款单号，如果该行数据为支付（交易状态SUCCESS）则展示0	`	`20240311459568556791724321
Refund Channel	varchar(50)	ORIGINAL—原路退款 BALANCE--退回微信零钱如果该行数据为支付（交易状态SUCCESS）则留空	`	`ORIGINAL
Refund Status	varchar(50)	生成账单文件时该笔退款的状态、出账后不会更新，如果该行数据为支付（交易状态SUCCESS），则留空 SUCCESS，退款成功 PROCESSING，退款处理中	`	`SUCCESS
Product Name(description)	varchar(255)	商户传入的该笔支付（或该笔退款对应的订单）的商品名称，对应下单接口里的body字段	`E8D253EF9036	`E8D253EF9036
Merchant's Data Package(attach)	varchar(255)	商户传入的该笔支付（或该笔退款对应的订单）的商户数据包，对应下单接口里的attach字段，不传时留空	`3EF9E1D25036	`3EF9E1D25036
Fee	varchar(255) 浮点型字符串，保留5位小数	该笔支付/退款对应的手续费金额（结算币种），支付对应正数、退款对应负数，单位元，保留小数点后2位。手续费金额计算规则：单笔交易金额乘以费率后，按照该币种支持的最小单位四舍五入如交易金额为 100 日元，费率为千分之5，则手续费金额计算后为 0.5 日元，由于日元最小单位为元，四舍五入后手续费金额为 1 日元。如交易金额为 1 美元，费率为千分之 5，则手续费金额计算后为 0.005 美元，由于美元最小单位为分，四舍五入后手续费金额为 0.01 美元。	`0.33000	`-0.08000
Rate	varchar(10)	该笔交易计费所使用的费率，百分数	`0.50%	`0.50%
Transaction Currency Type	varchar(50)	订单货币类型，符合ISO 4217标准的三位字母代码	`HKD	`HKD
Transaction Amount(total)	varchar(255) 浮点型字符串，保留2位小数	支付金额（参与计费的金额，标价币种）如果该行数据为退款则展示0.00 单位元，保留到小数点后2位	`65.66	`0.00
Payer Currency Type(payer_currency)	varchar(50)	用户支付币种	`CNY	`CNY
Payer Payment Amount(payer_total)	varchar(255) 浮点型字符串，保留2位小数	用户支付金额	`60.45	`0.00
Settlement Currency Type	varchar(50)	结算币种	`HKD	`HKD
Settlement Currency Amount	varchar(255) 浮点型字符串，保留2位小数	结算币种金额	`65.66	`0.00
Transaction Exchange Rate	varchar(255) 整型字符串	汇率	`92067840	`92067840
Refund Exchange Rate	varchar(255) 整型字符串	退款汇率	`0	`0
Refund Amount	varchar(255) 浮点型字符串，保留2位小数	标价币种退款金额	`0	`16.00
Payer Refund Currency Type	varchar(50)	用户退款币种	`	`CNY
Payer Refund Amount	varchar(255) 浮点型字符串，保留2位小数	用户退款金额	`0	`14.73
Refund Settlement Currency Type	varchar(50)	退款结算币种	`	`HKD
Refund Amount for merchant in settlement currency	varchar(255) 浮点型字符串，保留2位小数	结算币种退款金额	`0	`16.00
Refund Amount of Top-up Voucher	varchar(255) 浮点型字符串，保留2位小数	退款退券金额	`0	`0.00
Refund Amount of Coupon	varchar(255) 浮点型字符串，保留2位小数	无关字段	`0	`0.00

若商户扩展了分账、垫资退款字段，还会追加以下3个字段：

Fund type	varchar(50)	是否分账订单，包括：	`NonSplittingOrder	`NonSplittingOrder
		SplittingOrder分账订单
		NonSplittingOrder非分账订单
Fee RMB	varchar(255) 浮点型字符串，保留5位小数	该笔支付/退款对应的手续费金额（人民币），支付对应正数、退款对应负数，单位元，保留小数点后2位	`2.50000	`2.50000
Refund account	varchar(50)	退款出资账户，包括：	`	`UnsettledFund
		UnsettledFund未结算余额
		RechargeFund充值余额

异常返回

参数名

变量

类型[长度限制]

必填

描述

返回状态码

code

string[1, 32]

是

错误码，枚举值见错误码列表
示例值：INVALID_REQUEST

返回信息

message

string[1, 256]

是

返回信息，如非空，为错误原因
示例值：参数格式校验错误

详细的错误描述

detail

object

否

当code为PARAM_ERROR时返回，详细说明见下

详细的错误描述

返回示例

异常示例

1{
2	"code": "INVALID_REQUEST",
3	"message": "Parameter format verification error",
4	"detail": {
5		"field": "#/properties/payer",
6		"value": "1346177081915535577",
7		"issue": "与ALLOF schema不符",
8		"location": "body"
9	}
10}

4. 应答签名校验说明

4.1. 构造签名串

首先从应答中获取HTTP头Wechatpay-Nonce中的应答随机串，Wechatpay-Timestamp中的应答时间戳，Wechatpay-Statement-Sha1中取得账单SHA1值。

请按照以下规则构造应答的签名串。\n为换行符（ASCII编码值为0x0A）。

1    应答时间戳\n
2    应答随机串\n
3    账单SHA1\n
4    \n

则签名串为：

1    1507709906
2    5K8264ILTKch16CQ2502SI8ZNMTM67VS
3    {"sha1" : "12345678999"}

注意

标红的sha1值特殊处理为json格式进行签名；签名串最后一行为空，即多一个换行符

4.2. 获取应答签名

微信支付应答签名通过HTTP头Wechat-Signature传递。（注意，示例因为排版可能存在换行，实际数据应在一行） Wechatpay-Signature: WcO+t3D8Kg71dTlKwN7r9PzUOXeaBJwp8/FOuSxcuSkXsoVYxBpsAidprySCjHCjmaglNcjoKJQLJ28/Asl93joTW39FX6i07lXhnbPknezAl wmvPdnQuI01HZsZF9V1i6ggZjBiAd5lG8bZtTxZOJ87ub2i9GuJ3Nr/NUc9VeY=，对Wechatpay-Signature的字段值使用Base64进行解码，得到应答签名。

4.3. 验证签名

很多编程语言的签名验证函数支持对“签名数据”进行签名验证。建议商户调用该类函数，使用微信支付平台公钥对“签名串”进行SHA256 with RSA签名验证。

如果商户使用的编程语言或者库只支持对“摘要数据”进行签名验证，请按照以下步骤验证签名：

1.使用SHA256计算签名串的摘要，得到摘要信息

2.使用微信支付平台公钥对摘要信息进行RSA签名验证（签名类型为SHA256）。请参考OpenSSL的RSA_verify()

注意

微信支付证书序列号位于HTTP头`Wechatpay-Serial`，验证签名前请先检查序列号是否跟商户所持有的微信支付证书序列号一致。更新证书的说明，请参考《获取微信支付平台证书》。

4.4. 验证账单完整性

账单完整下载后，生成SHA1签名与微信Wechatpay-Statement-Sha1值做账单完整性的校验。

5. 错误码

错误码	描述	解决方案
SYSTEM_ERROR	微信支付内部错误	请稍后重试
PARAM_ERROR	参数错误	请对照文档的请求参数说明检查参数
NO_STATEMENT_EXIST	账单不存在	请检查当前商户号的微信账户在指定日期内是否有资金变动。
BILL_CREATING	账单生成中	请先检查当前商户号在指定日期内是否有成功的交易，如指定日期有交易则表示账单正在生成中，请在上午10点以后再下载。