下载交易账单
更新时间:2024.11.14商户可以通过该接口下载历史交易清单。比如掉单、系统错误等导致商户侧和微信侧数据不一致,通过对账单核对后可校正支付状态。
|
接口说明
适用对象:直连商户
请求URL: https://api.mch.weixin.qq.com/pay/downloadbill
请求方式: POST
数据格式: XML
是否需要证书: 否
请求参数
参数名 | 变量 | 类型[长度限制] | 必填 | 描述 |
---|---|---|---|---|
应用ID | appid | string[1,32] | 是 | 直连商户申请的公众号或移动应用appid。 |
商户号 | mch_id | string[1,32] | 是 | 微信支付分配的商户号 |
随机字符串 | nonce_str | string[1,32] | 是 | 随机字符串,不长于32位。推荐随机数生成算法 |
签名 | sign | string[1,32] | 是 | 签名,详见签名生成算法 |
对账单日期 | bill_date | string[1,8] | 是 | 下载对账单的日期,格式:20140603 |
账单类型 | bill_type | string[1,16] | 否 | 账单类型,枚举值: |
压缩账单 | tar_type | string[1,4] | 否 | 非必传参数,固定值:GZIP,返回格式为.gzip的压缩包账单。不传则默认为数据流形式。 |
请求示例:
XML
返回参数
失败时,返回以下字段
参数名 | 变量 | 类型[长度限制] | 必填 | 描述 |
---|---|---|---|---|
返回状态码 | return_code | string[1,16] | 是 | SUCCESS/FAIL |
返回信息 | return_msg | string[1,128] | 否 | 返回信息,如非空,为错误原因 |
错误代码 | err_code | string[1,16] | 否 | 失败错误码,详见错误码列表 |
成功时,数据以文本表格的方式返回,第一行为表头,后面各行为对应的字段内容,字段内容跟查询订单或退款结果一致,具体字段说明可查阅相应接口。
第一行为表头,根据请求下载的对账单类型不同而不同(由bill_type决定), 目前有:
当日所有订单
交易时间,公众账号ID,商户号,子商户号,设备号,微信订单号,商户订单号,用户标识,交易类型,交易状态,付款银行,货币种类,总金额,代金券或立减优惠金额,微信退款单号,商户退款单号,退款金额, 代金券或立减优惠退款金额,退款类型,退款状态,商品名称,商户数据包,手续费,费率
当日成功支付的订单
交易时间,公众账号ID,商户号,子商户号,设备号,微信订单号,商户订单号,用户标识,交易类型,交易状态,付款银行,货币种类,总金额, 代金券或立减优惠金额,商品名称,商户数据包,手续费,费率
当日退款的订单
交易时间,公众账号ID,商户号,子商户号,设备号,微信订单号,商户订单号,用户标识,交易类型,交易状态,付款银行,货币种类,总金额, 代金券或立减优惠金额,退款申请时间,退款成功时间,微信退款单号,商户退款单号,退款金额, 代金券或立减优惠退款金额,退款类型,退款状态,商品名称,商户数据包,手续费,费率
从第二行起,为数据记录,各参数以逗号分隔,参数前增加`符号,为标准键盘1左边键的字符,字段顺序与表头一致。
倒数第二行为订单统计标题,最后一行为统计数据
总交易单数,总交易额,总退款金额,总代金券或立减优惠退款金额,手续费总金额
举例如下:
交易时间,公众账号ID,商户号,子商户号,设备号,微信订单号,商户订单号,用户标识,交易类型,交易状态,付款银行,货币种类,总金额,代金券或立减优惠金额,微信退款单号,商户退款单号,退款金额,代金券或立减优惠退款金额,退款类型,退款状态,商品名称,商户数据包,手续费,费率
`2014-11-10 16:33:45,`wx2421b1c4370ec43b,`10000100,`0,`1000,`1001690740201411100005734289,`1415640626,
`085e9858e3ba5186aafcbaed1,`MICROPAY,`SUCCESS,`OTHERS,`CNY,`0.01,`0.0,`0,`0,`0,`0,`,`,`被扫支付测试,`订单额外描述,`0,`0.60%
2014-11-10 16:46:14,`wx2421b1c4370ec43b,`10000100,`0,`1000,`1002780740201411100005729794,`1415635270,
`085e9858e90ca40c0b5aee463,`MICROPAY,`SUCCESS,`OTHERS,`CNY,`0.01,`0.0,`0,`0,`0,`0,`,`,`被扫支付测试,`订单额外描述,`0,`0.60%
总交易单数,总交易额,总退款金额,总代金券或立减优惠退款金额,手续费总金额
`2,`0.02,`0.0,`0.0,`0
结算对账单
普通结算对账单 | ||
字段名称 | 示例值 | 字段说明 |
---|---|---|
交易时间 | 2015-01-01 10:00:00 | 指该笔交易的支付成功时间或发起退款成功时间(注:不是退款成功时间),格式为YYYY-MM-DD HH:MM:SS,如2015-01-01 10:00:00 |
公众账号ID | wxab8acb865bb11234 | 发起该笔交易时使用的appid,appid是由微信平台给公众号或app分配的唯一标识、用于区分交易场景 |
商户号 | 1234567890 | 发起该笔交易的微信支付商户号,8~10位数字 |
子商户号 | 0 | 如果是普通受理模式下的交易,展示特约商户的商户号,8~10位数字 |
设备号 | 8888 | 该笔交易下单时在device_info字段中传入的信息,没填写则留空 |
微信订单号 | 4200000008201712143733500001 | 微信支付为该笔订单(或该笔退款对应的订单)分配的订单号 |
商户订单号 | test1 | 商户传入的该笔订单(或该笔退款对应的订单)的商户订单号,对应下单接口里的out_trade_no字段 |
用户标识 | testxt08c-XB5-QD208X1Aid0Cbs | 微信平台为支付用户在公众账号(appid)下分配的唯一标识(openid) |
交易类型 | NATIVE | 该笔订单(或该笔退款单对应的订单)的交易类型,使用英文缩写展示,取值和含义: 值: |
交易状态 | SUCCESS | SUCCESS—支付成功,说明该行数据为一笔支付成功的订单 |
付款银行 | OTHERS | 银行类型,采用字符串类型的银行标识,如CMC_CREDIT,完整说明见参数规定文档 |
货币种类 | CNY | 货币类型,符合ISO 4217标准的三位字母代码,如CNY |
总金额 | 0.01 | 该笔订单的应结算金额(=订单金额-用户使用的免充值券金额),如果该行数据为退款或撤销则展示0.00,单位元,保留到小数点后2位 |
代金券或立减优惠金额 | 0.00 | 该笔订单中使用的微信支付代金券金额(包括充值券和免充值券),如果未使用代金券、或该行数据为退款或撤销则展示0.00,单位元,保留到小数点后2位 |
微信退款单号 | 0 | 微信支付为该笔退款分配的退款单号,如果该行数据为订单则展示0 |
商户退款单号 | 0 | 商户发起退款时填入的商户退款单号,如果该行数据为订单则展示0 |
退款金额 | 0.00 | 该笔退款或撤销单的应结算金额(申请退款金额-免充值券退款金额),如果该行数据为订单则展示为0.00,非负数、单位元,保留到小数点后2位 |
代金券或立减优惠退款金额 | 0.00 | 退款金额中包含的充值券退款金额,如果该行数据为订单或没有充值券退款则展示为0.00,非负数、单位元,保留到小数点后2位 |
退款类型 | ORIGINAL | ORIGINAL—原路退款 |
退款状态 | SUCCESS | 生成账单文件时该笔退款的状态、后续不会更新,如果该行数据为订单,则留空 |
商品名称 | 中文[body] | 商户传入的该笔订单(或该笔退款对应的订单)的商品名称,对应下单接口里的body字段 |
商户数据包 | 测试中文[attach] | 商户传入的该笔订单(或该笔退款对应的订单)的商户数据包,对应下单接口里的attach字段,不传时留空 |
手续费 | 0.00000 | 该笔订单/退款对应的手续费金额,订单对应正数、退款对应负数,单位元,保留小数点后2位 |
费率 | 0.00% | 该笔交易计费所使用的费率,百分数,如0.60% |
开通免充值券后的结算对账单 | ||
字段名称 | 示例值 | 字段说明 |
---|---|---|
交易时间 | 2015-01-01 10:00:00 | 指该笔交易的支付成功时间或发起退款成功时间(注:不是退款成功时间),格式为YYYY-MM-DD HH:MM:SS,如2015-01-01 10:00:00 |
公众账号ID | wxab8acb865bb11234 | 发起该笔交易时使用的appid,appid是由微信平台给公众号或app分配的唯一标识、用于区分交易场景 |
商户号 | 1234567890 | 发起该笔交易的微信支付商户号,8~10位数字 |
特约商户号 | 0 | 如果是普通受理模式下的交易,展示特约商户的商户号,8~10位数字 |
设备号 | 8888 | 该笔交易下单时在device_info字段中传入的信息,没填写则留空 |
微信订单号 | 4200000008201712143733500001 | 微信支付为该笔订单(或该笔退款对应的订单)分配的订单号 |
商户订单号 | test1 | 商户传入的该笔订单(或该笔退款对应的订单)的商户订单号,对应下单接口里的out_trade_no字段 |
用户标识 | testxt08c-XB5-QD208X1Aid0Cbs | 微信平台为支付用户在公众账号(appid)下分配的唯一标识(openid) |
交易类型 | NATIVE | 该笔订单(或该笔退款单对应的订单)的交易类型,使用英文缩写展示,取值和含义: 值: |
交易状态 | SUCCESS | SUCCESS—支付成功,说明该行数据为一笔支付成功的订单 |
付款银行 | OTHERS | 银行类型,采用字符串类型的银行标识,如CMC_CREDIT,完整说明见参数规定文档 |
货币种类 | CNY | 货币类型,符合ISO 4217标准的三位字母代码,如CNY |
应结订单金额 | 0.01 | 该笔订单的应结算金额(=订单金额-用户使用的免充值券金额),如果该行数据为退款或撤销则展示0.00,单位元,保留到小数点后2位 |
代金券 | 0.00 | 该笔订单中使用的微信支付代金券金额(包括充值券和免充值券),如果未使用代金券、或该行数据为退款或撤销则展示0.00,单位元,保留到小数点后2位 |
微信退款单号 | 0 | 微信支付为该笔退款分配的退款单号,如果该行数据为订单则展示0 |
商户退款单号 | 0 | 商户发起退款时填入的商户退款单号,如果该行数据为订单则展示0 |
退款金额 | 0.00 | 该笔退款或撤销单的应结算金额(申请退款金额-免充值券退款金额),如果该行数据为订单则展示为0.00,非负数、单位元,保留到小数点后2位 |
充值券退款金额 | 0.00 | 退款金额中包含的充值券退款金额,如果该行数据为订单或没有充值券退款则展示为0.00,非负数、单位元,保留到小数点后2位 |
退款类型 | ORIGINAL | ORIGINAL—原路退款 |
退款状态 | SUCCESS | 生成账单文件时该笔退款的状态、后续不会更新,如果该行数据为订单,则留空 |
商品名称 | 中文[body] | 商户传入的该笔订单(或该笔退款对应的订单)的商品名称,对应下单接口里的body字段 |
商户数据包 | 测试中文[attach] | 商户传入的该笔订单(或该笔退款对应的订单)的商户数据包,对应下单接口里的attach字段,不传时留空 |
手续费 | 0.00000 | 该笔订单/退款对应的手续费金额,订单对应正数、退款对应负数,单位元,保留小数点后2位 |
费率 | 0.00% | 该笔交易计费所使用的费率,百分数,如0.60% |
订单金额 | 0.01 | 该笔订单的金额,包括用户支付金额、充值券金额、免充值券金额,如果该行数据为退款或撤销则填0.00,单位元,保留到小数点后2位 |
申请退款金额 | 0.00 | 商户发起退款的金额,包括退给用户的金额、充值券退款金额、免充值券退款金额,如果该行数据订单则填0.00,单位元,保留到小数点后2位 |
费率备注 | - | 如果有特殊费率规则时则加以说明,默认留空 |
错误码
错误码 | 名称 | 描述 | 解决方案 |
---|---|---|---|
100 | SYSTEMERROR | 下载失败 | 请尝试再次查询。 |
20003 | SYSTEMERROR | 下载失败 | 请尝试再次查询。 |
20001 | sign error | 签名错误 | 签名错误,请重新检查参数和签名密钥是否正确 |
nonce_str too long | 参数nonce_str错误 | 参数nonce_str长度超长 | |
invalid tar_type, Only GZIP supported | 参数tar_type错误 | 请重新检查参数invalid tar_typ是否正确 | |
invalid bill_type | 参数bill_type错误 | 请重新检查参数bill_type是否正确 | |
invalid bill_date | 参数bill_date错误 | 请重新检查参数bill_date是否符合要求 | |
require POST method | 请求方式错误 | 请求检查参数请求方式是否为post | |
empty post data | 请求报文错误 | 请重新检查请求报文是否正确 | |
data format error | 参数格式错误 | 请重新检查请求参数格式是否为xml | |
missing parameter | 缺少参数 | 请重新检查是否所有必传参数都上传了,且不为空 | |
invalid appid | appid错误 | 请重新检查参数appid是否正确 | |
invalid parameter | 参数错误 | 请重新检查是否所有参数都与文档相符 | |
20002 | NO Bill Exist | 账单不存在 | 请检查当前商户号在指定日期内是否有成功的交易。 |
Bill Creating | 账单未生成 | 请先检查当前商户号在指定日期内是否有成功的交易,如指定日期有交易则表示账单正在生成中,请在上午10点以后再下载。 | |
20007 | 当前商户号账单API权限已经关闭 | 当前商户号账单API权限已经关闭 | 当前商户号账单API权限已经关闭,请联系微信支付解决 |
20100 | system error | 下载失败 | 请尝试再次查询。 |