微信支付 API
  1. API列表
微信支付 API
  • 文档说明
    • 阅读对象
    • 版本说明
  • 术语
    • 支付模式
    • 名词解释
  • 支付账户
    • 支付账户
  • 接口规则
    • 协议规则
    • 参数规定
    • 安全规范
    • 获取openid
  • JSAPI支付
    • 场景介绍
    • 案例介绍
    • 接入前准备
    • 开发指引
    • 获取微信版本号
    • JSAPI调起支付
    • 支付常见问题
  • API列表
    • 统一下单
      POST
    • 查询订单
      POST
    • 关闭订单
      POST
    • 申请退款
      POST
    • 查询退款
      POST
    • 下载交易账单
      POST
    • 下载资金账单
      POST
    • 支付结果通知
      POST
    • 交易保障
      POST
    • 退款结果通知
      POST
  • 最佳实践
    • 支付回调和查单实现指引
    • 支付验收指引
    • 网络排查指引
    • 最佳安全实践
    • 跨城冗灾方案
    • 回调通知注意事项
    • 专线商户Notify升级指引
    • 商户收银台H5大字号规范
    • 微信支付二维码规范
  • 运营规范
    • 运营规范
  • SDK与DEMO下载
    • SDK与DEMO下载
  1. API列表

下载交易账单

POST
/pay/downloadbill

应用场景#

商户可以通过该接口下载历史交易清单。比如掉单、系统错误等导致商户侧和微信侧数据不一致，通过对账单核对后可校正支付状态。
注意：
1、微信侧未成功下单的交易不会出现在对账单中。支付成功后撤销的交易会出现在对账单中，跟原支付单订单号一致；
2、微信在次日9点启动生成前一天的对账单，建议商户10点后再获取；
3、对账单中涉及金额的字段单位为“元”。
4、对账单接口只能下载三个月以内的账单。
5、对账单是以商户号维度来生成的，如一个商户号与多个appid有绑定关系，则使用其中任何一个appid都可以请求下载对账单。对账单中的appid取自交易时候提交的appid，与请求下载对账单时使用的appid无关。
6、自2018年起入驻的商户默认是开通免充值券后的结算对账单，且汇总数据为总交易单数，应结订单总金额，退款总金额，充值券退款总金额，手续费总金额，订单总金额，申请退款总金额。

交易账单格式说明#

1. 交易账单介绍#
微信支付每天提供前一天的交易账单文件，用于商户核对订单、退款、营销、手续费等信息。账单内的数据包括：
（1）当天支付成功的订单，下单成功但用户未支付的订单不会出账。
（2）当天发起退款成功的退款单，退款发起成功就会出账，出账后退款状态不会更新。如果需要获取最新退款状态，请使用查询退款API查询。
微信支付提供了3份不同类型的账单文件：
• ALL，包含了当天支付成功的订单和发起成功的退款单
• SUCCESS，仅包含支付成功的订单
• REFUND，仅包含发起成功的退款单
2. 交易账单的文件格式#
交易账单文件内包含：明细数据表头、明细数据内容、汇总数据表头、汇总数据四个部分，每个字段使用英文逗号 , 间隔，明细数据内容每个字段前会增加1个字符 ` 用于避免获取的内容被excel展示为科学计数法的格式、丢失数据细节。3份不同类型的账单文件字段内容略有差异。
2.1. ALL类型账单文件具体字段
字段名描述示例值
明细数据
交易时间指该笔交易的支付成功时间或发起退款成功时间（注：不是退款成功时间），格式为yyyy-MM-dd HH:MM:SS2015-01-01 10:00:00
公众账号ID发起该笔交易时使用的appid，appid是由微信给公众号或app等分配的唯一标识wxab8acb865bb11234
商户号发起该笔交易下单的微信支付商户号，8~10位数字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）则展示050401010122021000000038202001
商户退款单号商户发起退款时填入的商户退款单号，如果该行数据为订单（交易状态SUCCESS）则展示0refundno001
退款金额该笔退款单参与计费的应结算金额（申请退款金额-免充值券退款金额），如果该行数据为订单则展示为0.00，非负数、单位元，保留到小数点后2位6.66
充值券退款金额退款金额中包含的充值券退款金额，如果该行数据为订单或没有充值券退款则展示为0.00，非负数、单位元，保留到小数点后2位0.66
退款类型ORIGINAL—原路退款 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
2.2. SUCCESS和REFUND账单
SUCCESS和REFUND账单的字段和ALL账单内略有不同
SUCCESS账单字段：交易时间,公众账号ID,商户号,设备号,微信订单号,商户订单号,用户标识,交易类型,交易状态,付款银行,货币种类,应结订单金额,代金券金额,商品名称,商户数据包,手续费,费率,订单金额,费率备注
REFUND账单字段：交易时间,公众账号ID,商户号,设备号,微信订单号,商户订单号,用户标识,交易类型,交易状态,付款银行,货币种类,应结订单金额,代金券金额,退款申请时间,退款成功时间,微信退款单号,商户退款单号,退款金额,充值券退款金额,退款类型,退款状态,商品名称,商户数据包,手续费,费率,订单金额,申请退款金额,费率备注
2.3. 特殊字符转义
账单处理过程会对商品名称、商户数据包、设备号等商户自定义字段进行特殊字符转义，具体规则包括：
'转换成为'
"转换成为"
转换成为\
,转换成为\ （+空格）
\r转换成为\r
\t转换成为\t
2.4. 补充说明
少部分商户目前的账单格式停留在历史早期版本，具体表现为：没有应结算订单金额字段、对应的是总金额字段，没有代金券金额字段、对应的是企业红包金额字段。如需调整为最新格式的账单，可以通过在产品中心中开通免充值优惠券功能，次日开始的账单格式即会完成变更。
3. 账单样例#
《ALL.xlsx》、《REFUND.xlsx》、《SUCCESS.xlsx》

错误码#

错误码名称描述原因解决方案
100SYSTEMERROR下载失败系统超时请尝试再次查询。
100Network Traffic Limit网络流量限制当前系统请求繁忙请尝试再次查询
20003SYSTEMERROR下载失败系统超时请尝试再次查询。
20001sign 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格式请重新检查请求参数格式是否为xml
missing parameter缺少参数有必传的参数未上传请重新检查是否所有必传参数都上传了，且不为空
invalid appidappid错误请求参数appid有误请重新检查参数appid是否正确
invalid parameter参数错误有未知的请求参数请重新检查是否所有参数都与文档相符
20002No Bill Exist账单不存在当前商户号没有已成交的订单，不生成对账单请检查当前商户号在指定日期内是否有成功的交易。
Bill Creating账单未生成当前商户号没有已成交的订单或对账单尚未生成请先检查当前商户号在指定日期内是否有成功的交易，如指定日期有交易则表示账单正在生成中，请在上午10点以后再下载。
20007当前商户号账单API权限已经关闭当前商户号账单API权限已经关闭当前商户号账单API权限已经关闭当前商户号账单API权限已经关闭，请联系微信支付解决
20008Frequency Limited请求频率超过限制当前IP或商户号的请求过于频繁，超过了频率限制请放慢请求速度，稍后再次查询
20100system error下载失败系统超时请尝试再次查询。
请求示例请求示例
Shell
JavaScript
Java
Swift
curl --location --request POST '/pay/downloadbill' \
--header 'Content-Type: application/xml' \
--data-raw '<xml>
   <appid>wx2421b1c4370ec43b</appid>
   <bill_date>20141110</bill_date>
   <bill_type>ALL</bill_type>
   <mch_id>10000100</mch_id>
   <nonce_str>21df7dc9cd8616b56919f20d9f679233</nonce_str>
   <sign>332F17B766FC787203EBE9D6E40457A1</sign>
</xml>'
响应示例响应示例
{
  "return_code": "string",
  "return_msg": "string",
  "error_code": "string"
}

请求参数

Body 参数application/xml
appid
string 
公众账号ID
必需
微信分配的公众账号ID
bill_date
string 
对账单日期
必需
下载对账单的日期，格式：20140603
bill_type
string 
账单类型
必需
ALL（默认值），返回当日所有订单信息（不含充值退款订单） SUCCESS，返回当日成功支付的订单（不含充值退款订单） REFUND，返回当日退款订单（不含充值退款订单） RECHARGE_REFUND，返回当日充值退款订单
mch_id
string 
商户号
必需
微信支付分配的商户号
nonce_str
string 
随机字符串
必需
随机字符串，不长于32位。推荐随机数生成算法
sign
string 
签名
必需
签名，详见签名生成算法
sign_type
string 
签名类型
可选
签名类型，目前支持HMAC-SHA256和MD5，默认为MD5
tar_type
string 
压缩账单
可选
非必传参数，固定值：GZIP，返回格式为.gzip的压缩包账单。不传则默认为数据流形式。
示例

返回响应

🟢200成功
application/json
Body
return_code
string 
返回状态码
必需
FAIL
return_msg
string 
错误码描述
可选
返回信息，如非空，为错误原因 如：签名失败 等。
error_code
string 
错误码
可选
失败错误码，详见错误码列表
上一页
查询退款
下一页
下载资金账单
Built with