账单查询能力

更新时间：2024-09-26 19:09:53

1.  接口说明

接入担保交易-自动续费能力的商户，可以通过该接口查询历史账单，用于账单校对。

接入担保交易-单次支付能力的商户，请通过单次支付-账单查询 (opens new window)接口进行查询。

2. 基本信息

名称	内容
HTTP URL	https://open.kuaishou.com/openapi/mp/developer/epay/query_bill
HTTP Method	POST
Scope	需要具有小程序担保支付权限(scope.ks.epay)

3. 请求头

名称	字段类型	内容
Content-Type	String	固定值: "application/json"

4. 请求签名

请求需要签名，详见：附录 (opens new window)

5. 请求参数

以下字段放在 query param 处：

字段名	类型	是否必填	是否参与签名	说明
app_id	string	是	是	小程序 AppId
access_token	string	是	否	拥有小程序支付权限的access token，获取方式见getAccessToken

以下字段放在 body json 处：

属性	数据类型	必填	说明
start_date	string	是	开始日期，格式：yyyyMMddHHmmss，示例：20220801180000。
end_date	string	是	结束日期，格式：yyyyMMddHHmmss，示例：20220801190000。 查询范围精确到秒级，开始时间和结束时间范围左闭右开。 建议每次查询时间范围不超过1天，订单量比较大的场景可以缩短到10-30分钟，可以for循环调用。
bill_type	string	是	账单类型， 支付账单：PAY 退款账单：REFUND 分账账单：SETTLE
pay_order_type	string	否	支付类型：签约/代扣单 普通支付单：PAY_ORDER 签约/代扣单：WITHHOLD_ORDER 不传默认为 PAY_ORDER
sign	string	是	对上面的参数进行签名

6. 响应结果

请求成功后，数据以csv文件的压缩文件（zip）的字节数组（byte[]）形式返回，第一行为各列的字段名字，不同的订单类型字段有所不同，第二行起为对应的数据记录行。

6.1. 支付账单

字段名依次为：

序号，商户号，扣款时间，快手小程序平台签约号，周期代扣产品名称，签约模板类型，支付用户openid，支付方式，开发者订单号，平台订单号，快手小程序平台代扣记录号，支付金额（分），代扣周期，扣款状态

Demo：

各字段含义：

字段名	描述	示例值
序号	账单行数	1
商户号	快手小程序平台商户号	TEST664280946812921445
扣款时间	代扣单平台扣款时间，格式：yyyy-MM-dd HH:mm:ss	2024-01-12 14:25:37
平台签约号	快手小程序平台分配的签约单号	524010201547195973250
周期代扣产品名称	开发者传入的签约产品名称	ks_vip_card_month
签约模板类型	开发者传入的签约模版 WEEK - 周 MONTH - 月 QUARTER - 季 YEAR - 年 FIX30 - 固定30天 FIX31 - 固定31天	MONTH
支付用户openid	签约用户在当前小程序的唯一id	5b748c61ef290140c06566386ad7607c
支付方式	用户支付方式 WECHAT_SFT - 微信 ALIPAY_ZFT - 支付宝	ALIPAY_ZFT
开发者订单号	开发者传入的订单号(代扣单不存在)	-
平台订单号	平台生成订单号(代扣单不存在)	-
平台代扣记录号	快手小程序平台生成代扣单号	624010201147476465250
支付金额	代扣金额，单位分	100
代扣周期	平台当前代扣周期，默认从1开始累加 当代扣周期为0时，代表首次签约并支付产生的支付单	1
扣款状态	平台代扣结果 SUCCESS - 成功 FAIL - 失败	SUCCESS

6.2. 退款账单

字段名依次为：

序号，商户号，退款申请时间，开发者原单号，平台原单号，快手小程序平台代扣订单号，开发者退款单号，平台退款单号，退款订单类型，订单金额(分)，支付方式，退款金额(分)，退款状态，退款原因，退款完成时间，退款类型，退款账户

Demo：

各字段含义：

字段名	描述	示例值
序号	账单行数	1
商户号	快手小程序平台商户号	TEST664280946812921445
退款申请时间	开发者申请退款时间 格式：yyyy-MM-dd HH:mm:ss	2024-01-12 14:25:37
开发者原单号	开发者支付时传递的外部单号，代扣单无此值	-
平台原单号	快手小程序平台生成的订单号	624010310956666484152
平台代扣订单号	快手小程序平台生成代扣单号	624010201147476465250
开发者退款单号	开发者申请退款时传入的退款单号	624010359200001
平台退款单号	快手小程序平台分配的退款单号	224010300617464172592
退款订单类型	平台退款单类型 PAY_CONTRACT_ORDER - 首次支付并签约订单 WITHHOLD_ORDER - 代扣单	WITHHOLD_ORDER
订单金额	用户支付/平台代扣金额，单位分	100
支付方式	用户支付方式 WECHAT_SFT - 微信 ALIPAY_ZFT - 支付宝	ALIPAY_ZFT
退款金额	用户申请退款金额，单位分	100
退款状态	用户申请退款状态，只有 SUCCESS 一种状态	SUCCESS
退款原因	用户申请退款的原因	代扣单申请退款
退款完成时间	平台受理退款完成时间 格式：yyyy-MM-dd HH:mm:ss	2024-01-12 14:26:37
退款类型	枚举值如下 结算前退款 结算后退款 保证金账户退款	结算前退款
退款账户	枚举值如下 待结算账户 可提现账户 保证金账户 和退款类型字段一一对应	待结算账户

6.3. 结算账单

字段名依次为：

序号，商户号，结算时间，开发者原单号，平台原单号，结算单号，平台结算单号，用户支付金额(分)，支付方式，分账状态，商家分账金额(分)，平台服务费(分)，达人分佣金额(分)

Demo：

各字段含义：

字段名	描述	示例值
序号	账单行数	1
商户号	快手小程序平台商户号	TEST664280946812921445
分账时间	平台完成分账的时间 格式：yyyy-MM-dd HH:mm:ss	2024-01-12 14:25:37
原单号	开发者支付时传递的外部单号 签约支付单此字段有值 代扣单无此值	1703578340452contractDemo
平台原单号	快手小程序平台生成的订单号	624010310956666484152
分账单号	开发者传入的分账单号 对于代扣单，此单号为平台生成	624010201147476465250
平台分账单号	快手小程序平台分配的结算单号	324010310953828678592
用户支付金额	用户支付/平台代扣金额，单位分	100
支付方式	用户支付方式 WECHAT_SFT - 微信 ALIPAY_ZFT - 支付宝	WECHAT_SFT
分账状态	平台结算状态，只有 SUCCESS 一种状态	SUCCESS
商家分账金额	商家实际分账金额，单位分	80
平台服务费	平台分账金额，单位分	20
达人分佣金额	达人分账金额，单位分	0

7. 错误码

错误码	描述	排查建议
10000011	token 过期	调用 getAccessToken 重新生成 token
10000200	参数错误	对照错误提示和接口字段定义，检查对应的参数
10000302	请求频率太快，被限速。	请降低访问频率
10000500	系统故障	请联系相关开发人员进行排查
10000501	稍后重试	请等待1-2秒，再重试
10000606	接口参数签名错误	对照接口字段，检查签名字段是否正确
10000607	不合理的订单金额	请检查传入的订单金额是否合理
10000632	平台内部错误	请联系相关开发人员进行排查

8. 账单样例

支付账单 Demo (opens new window)

代扣账单 Demo (opens new window)

退款账单 Demo (opens new window)

结算账单 Demo (opens new window)