CloudPay.downloadBill()

支持端:云函数 2.0.2

下载对账单

说明

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

注意:

1、微信侧未成功下单的交易不会出现在对账单中。支付成功后撤销的交易会出现在对账单中,跟原支付单订单号一致;

2、微信在次日9点启动生成前一天的对账单,建议商户10点后再获取;

3、对账单中涉及金额的字段单位为“元”。

4、对账单接口只能下载三个月以内的账单。

5、对账单是以商户号纬度来生成的,如一个商户号与多个appid有绑定关系,则使用其中任何一个appid都可以请求下载对账单。对账单中的appid取自交易时候提交的appid,与请求下载对账单时使用的appid无关。

6、小微商户不单独提供对账单下载,如有需要,可在调取【下载对账单】API接口时不传sub_mch_id,获取服务商下全量特约商户(包括小微商户和非小微商户)的对账单。

此接口与微信支付原接口(文档)的不同点在于:

  • 私有安全链路,免证书管理,免签名计算
  • 商户号填入 sub_mch_id 字段,小程序/公众号 appid 填入 sub_appid 字段
  • 免填写以下字段:mch_id、appid、sign、sign_type
  • 接口入参和返回值都为 JSON 而不是 XML

参数说明

字段名变量名必填类型示例值描述
子商户号sub_mch_idString(32)1900000109微信支付分配的子商户号,如需下载指定的子商户号对账单,则此参数必传。
随机字符串nonce_strString(32)5K8264ILTKCH16CQ2502SI8ZNMTM67VS随机字符串,不长于32位。推荐随机数生成算法
签名signString(32)C380BEC2BFD727A4B6845133519F3AD6签名,详见签名生成算法
对账单日期bill_dateString(8)20140603下载对账单的日期,格式:20140603
账单类型bill_typeString(8)ALLALL,返回当日所有订单信息,默认值
SUCCESS,返回当日成功支付的订单
REFUND,返回当日退款订单
压缩账单tar_typeStringGZIP非必传参数,固定值:GZIP,返回格式为.gzip的压缩包账单。不传则默认为数据流形式。

返回值说明

失败时,返回以下字段

字段名变量名必填类型示例值描述
返回状态码returnCodeString(16)FAILFAIL
错误码描述returnMsgString(128)签名失败返回信息,如非空,为错误原因,如:签名失败 等。
错误码errorCodeString(16)20002失败错误码,详见错误码列表

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

第一行为表头,根据请求下载的对账单类型不同而不同(由bill_type决定),目前有: 当日所有订单* 交易时间,服务商的APPID,商户号,子商户号,设备号,微信订单号,商户订单号,用户标识,交易类型,交易状态,付款银行,货币种类,总金额,代金券或立减优惠金额,微信退款单号,商户退款单号,退款金额,代金券或立减优惠退款金额,退款类型,退款状态,商品名称,商户数据包,手续费,费率 当日成功支付的订单* 交易时间,服务商的APPID,商户号,子商户号,设备号,微信订单号,商户订单号,用户标识,交易类型,交易状态,付款银行,货币种类,总金额,代金券或立减优惠金额,商品名称,商户数据包,手续费,费率 当日退款的订单* 交易时间,服务商的APPID,商户号,子商户号,设备号,微信订单号,商户订单号,用户标识,交易类型,交易状态,付款银行,货币种类,总金额,代金券或立减优惠金额,退款申请时间,退款成功时间,微信退款单号,商户退款单号,退款金额,代金券或立减优惠退款金额,退款类型,退款状态,商品名称,商户数据包,手续费,费率

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

倒数第二行为订单统计标题,最后一行为统计数据

总交易单数,总交易额,总退款金额,总代金券或立减优惠退款金额,手续费总金额

举例如下:

交易时间,服务商的APPID,商户号,子商户号,设备号,微信订单号,商户订单号,用户标识,交易类型,交易状态,付款银行,货币种类,总金额,代金券或立减优惠金额,微信退款单号,商户退款单号,退款金额,代金券或立减优惠退款金额,退款类型,退款状态,商品名称,商户数据包,手续费,费率 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 结算对账单*

普通结算对账单

字段名称示例值字段说明
交易时间2017-12-14 15:49:06指该笔交易的支付成功时间或发起退款成功时间(注:不是退款成功时间),格式为YYYY-MM-DD HH:MM:SS,如2015-01-01 10:00:00
公众账号IDwxab8acb865bb11234发起该笔交易时使用的appid,appid是由微信平台给公众号或app分配的唯一标识、用于区分交易场景
商户号1234567890发起该笔交易的微信支付商户号,8~10位数字
子商户号0如果是普通受理模式下的交易,展示特约商户的商户号,8~10位数字
如果是直连模式交易,则展示成数字0
设备号8888该笔交易下单时在device_info字段中传入的信息,没填写则留空
微信订单号4200000008201712143733500001微信支付为该笔订单(或该笔退款对应的订单)分配的订单号
商户订单号test1商户传入的该笔订单(或该笔退款对应的订单)的商户订单号,对应下单接口里的out_trade_no字段
用户标识testxt08c-XB5-QD208X1Aid0Cbs微信平台为支付用户在公众账号(appid)下分配的唯一标识(openid)
交易类型NATIVE该笔订单(或该笔退款单对应的订单)的交易类型,使用英文缩写展示,取值和含义: 值:
JSAPI-JSAPI支付(或小程序支付)
NATIVE-Native支付
APP-app支付
MWEB-H5支付
MICROPAY-付款码支付
PAP-委托代扣
交易状态SUCCESSSUCCESS—支付成功,说明该行数据为一笔支付成功的订单
REFUND—转入退款,说明该行数据为一笔发起退款成功的退款单
REVOKED—已撤销,说明该行数据为一笔成功撤销的撤销单
付款银行OTHERS银行类型,采用字符串类型的银行标识,如CMC_CREDIT,完整说明见https://pay.weixin.qq.com/wiki/doc/api/jsapi.php?chapter=4_2
货币种类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—原路退款
BALANCE—转退到用户的微信支付零钱
如果该行数据为订单,则留空
退款状态生成账单文件时该笔退款的状态、后续不会更新,如果该行数据为订单,则留空
SUCCES—退款成功
FAIL—退款失败M
PROCESSING—退款处理中
商品名称中文[body]商户传入的该笔订单(或该笔退款对应的订单)的商品名称,对应下单接口里的body字段
商户数据包测试中文[attach]商户传入的该笔订单(或该笔退款对应的订单)的商户数据包,对应下单接口里的attach字段,不传时留空
手续费0.00000该笔订单/退款对应的手续费金额,订单对应正数、退款对应负数,单位元,保留小数点后2位
费率0.00%该笔交易计费所使用的费率,百分数,如0.60%

开通免充值券后的结算对账单

字段名称示例值字段说明
交易时间2017-12-14 15:49:06指该笔交易的支付成功时间或发起退款成功时间(注:不是退款成功时间),格式为YYYY-MM-DD HH:MM:SS,如2015-01-01 10:00:00
公众账号IDwxab8acb865bb11234发起该笔交易时使用的appid,appid是由微信平台给公众号或app分配的唯一标识、用于区分交易场景
商户号1234567890发起该笔交易的微信支付商户号,8~10位数字
特约商户号0如果是普通受理模式下的交易,展示特约商户的商户号,8~10位数字
如果是直连模式交易,则展示成数字0
设备号8888该笔交易下单时在device_info字段中传入的信息,没填写则留空
微信订单号4200000008201712143733500001微信支付为该笔订单(或该笔退款对应的订单)分配的订单号
商户订单号test1商户传入的该笔订单(或该笔退款对应的订单)的商户订单号,对应下单接口里的out_trade_no字段
用户标识testxt08c-XB5-QD208X1Aid0Cbs微信平台为支付用户在公众账号(appid)下分配的唯一标识(openid)
交易类型NATIVE该笔订单(或该笔退款单对应的订单)的交易类型,使用英文缩写展示,取值和含义: 值:
JSAPI-JSAPI支付(或小程序支付)
NATIVE-Native支付
APP-app支付
MWEB-H5支付
MICROPAY-付款码支付
PAP-委托代扣
交易状态SUCCESSSUCCESS—支付成功,说明该行数据为一笔支付成功的订单
REFUND—转入退款,说明该行数据为一笔发起退款成功的退款单
REVOKED—已撤销,说明该行数据为一笔成功撤销的撤销单
付款银行OTHERS银行类型,采用字符串类型的银行标识,如CMC_CREDIT,完整说明见https://pay.weixin.qq.com/wiki/doc/api/jsapi.php?chapter=4_2
货币种类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—原路退款
BALANCE—转退到用户的微信支付零钱
如果该行数据为订单,则留空
退款状态生成账单文件时该笔退款的状态、后续不会更新,如果该行数据为订单,则留空
SUCCES—退款成功
FAIL—退款失败M
PROCESSING—退款处理中
商品名称中文[body]商户传入的该笔订单(或该笔退款对应的订单)的商品名称,对应下单接口里的body字段
商户数据包测试中文[attach]商户传入的该笔订单(或该笔退款对应的订单)的商户数据包,对应下单接口里的attach字段,不传时留空
手续费0.00000该笔订单/退款对应的手续费金额,订单对应正数、退款对应负数,单位元,保留小数点后2位
费率0.00%该笔交易计费所使用的费率,百分数,如0.60%
订单金额0.01该笔订单的金额,包括用户支付金额、充值券金额、免充值券金额,如果该行数据为退款或撤销则填0.00,单位元,保留到小数点后2位
申请退款金额0.00商户发起退款的金额,包括退给用户的金额、充值券退款金额、免充值券退款金额,如果该行数据订单则填0.00,单位元,保留到小数点后2位
费率备注如果有特殊费率规则时则加以说明,默认留空

错误码

错误码名称描述原因解决方案
20003SYSTEMERROR下载失败系统超时请尝试再次查询。
20001sign error签名错误请求参数未按要求进行填写签名错误,请重新检查参数和签名密钥是否正确
20001nonce_str too long参数nonce_str错误请求参数未按要求填写参数nonce_str长度超长
20001invalid tar_type, Only GZIP supported参数tar_type错误请求参数未按指引进行填写请重新检查参数invalid tar_typ是否正确
20001invalid bill_type参数bill_type错误请求参数未按指引进行填写请重新检查参数bill_type是否正确
20001invalid bill_date参数bill_date错误请求参数未按指引进行填写请重新检查参数bill_date是否符合要求
20001require POST method请求方式错误请求方式不符合要求请求检查参数请求方式是否为post
20001empty post data请求报文错误请求报文为空请重新检查请求报文是否正确
20001data format error参数格式错误请求参数要求为xml格式请重新检查请求参数格式是否为xml
20001missing parameter缺少参数有必传的参数未上传请重新检查是否所有必传参数都上传了,且不为空
20001invalid appidappid错误请求参数appid有误请重新检查参数appid是否正确
20001invalid parameter参数错误有未知的请求参数请重新检查是否所有参数都与文档相符
20001sub_mch not allow特约商户号权限错误无该特约商户账单的下载权限请检查特约商户号是否正确。若是小微商户,可不传sub_mch_id以获取服务商下全量特约商户的账单
20002NO Bill Exist账单不存在当前商户号没有已成交的订单,不生成对账单请检查当前商户号在指定日期内是否有成功的交易。
20002Bill Creating账单未生成当前商户号没有已成交的订单或对账单尚未生成请先检查当前商户号在指定日期内是否有成功的交易,如指定日期有交易则表示账单正在生成中,请在上午10点以后再下载。
20007当前商户号账单API权限已经关闭当前商户号账单API权限已经关闭当前商户号账单API权限已经关闭当前商户号账单API权限已经关闭,请联系微信支付解决
20100system error下载失败系统超时请尝试再次查询。