账单查询能力

更新时间：2024-09-26 15:31:44

1、接口说明

快手小程序商户可以通过该接口查询担保交易历史账单，用于账单校对。

1.1、基本信息

名称	内容
HTTP URL	https://open.kuaishou.com/openapi/mp/developer/epay/query_bill
HTTP Method	POST

1.2、请求头

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

1.3、请求参数

query param

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

body json参数

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

1.4、请求示例

时间格式为：yyyyMMddHHmmss

curl --location --request POST 'https://open.kuaishou.com/openapi/mp/developer/epay/query_bill?app_id=ks707065143182458884&access_token=ChFvYXV0aC5hY2Nlc3NUb2tlbhJQAi_C0DAE6J4cLf52X1LEFEv3baSr8oclxY0Aq5dYAOMTnoIE4x3OhSx0QIQ9JOlkbghxz-GDuZ5d19i5eZlkKlPu2G-o49bxfeiDQOFixmgaErGIwMzD6sOwyjFGfC_hVS1yHyIgSL342JiJDOSZlrrxkTuxRpran8NJtt3M2uwXSEiuAIAoDzAB' \
--header 'Content-Type: application/json' \
--data-raw '{
    "start_date":"20240101000000",
    "end_date":"20240102000000",
    "bill_type":"PAY",
    "sign":"cf9a1463410a633bab31e4c372810e1e"
}'

时间格式为：yyyyMMdd

curl --location --request POST 'https://open.kuaishou.com/openapi/mp/developer/epay/query_bill?app_id=ks707065143182458884&access_token=ChFvYXV0aC5hY2Nlc3NUb2tlbhJQAi_C0DAE6J4cLf52X1LEFEv3baSr8oclxY0Aq5dYAOMTnoIE4x3OhSx0QIQ9JOlkbghxz-GDuZ5d19i5eZlkKlPu2G-o49bxfeiDQOFixmgaErGIwMzD6sOwyjFGfC_hVS1yHyIgSL342JiJDOSZlrrxkTuxRpran8NJtt3M2uwXSEiuAIAoDzAB' \
--header 'Content-Type: application/json' \
--data-raw '{
    "start_date":"20240106",
    "end_date":"20240106",
    "bill_type":"PAY",
    "sign":"cf9a1463410a633bab31e4c372810e1e"
}'

1.5、返回值

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

注：如下展示pay_order_type入参为空，或者传值为PAY_ORDER的返回结果，自动续费相关账单参考自动续费目录下的账单查询文档

1.5.1、支付账单

字段名依次为：

序号，支付时间，商户号，openId，订单号，平台订单号，订单金额(分)，支付方式，支付状态，用户支付金额(分)，平台补贴金额(分)

demo：

字段说明

字段名	描述	示例值
序号	账单行数	1
支付时间	订单支付完成时间
商户号	快手小程序平台商户号	TEST664280946812921445
openId	下单用户在当前小程序的唯一id	5b748c61ef290140c06566386ad7607c
订单号	开发者生成的订单号	1739932131demo
平台订单号	小程序平台生成的唯一单号标识	1224020110934211872378
订单金额(分)	订单金额，单位：分	10
支付方式	用户支付方式， WECHAT_SFT - 微信 ALIPAY_ZFT - 支付宝 APPLE_PAY - 苹果支付	ALIPAY_ZFT
支付状态	用户支付状态，只返回支付成功的订单	SUCCESS
用户支付金额(分)	该笔订单，用户实际支付的金额，在有补贴的场景下，一笔订单原价10，用户知己支付8，平台补贴2。 注：目前补贴场景属于试验产品，未接入小程序无需关注，因此用户支付金额=订单金额	8
平台补贴金额(分)	平台对该比订单补贴的金额，单位：分。 注：目前补贴场景属于试验产品，未接入小程序无需关注，因此用户支付金额=订单金额	2

1.5.2、退款账单

字段名依次为：

序号，退款申请时间，商户号，原单号，平台原单号，订单金额(分)，支付方式，退款单号，平台退款单号，退款金额(分)，退款状态，退款原因，退款完成时间，退款类型，退款账户

demo：

字段说明

字段名	描述	示例值
序号	账单行数	1
退款申请时间	退款申请发起的时间	2024-04-01 10:01:11
商户号	快手小程序平台商户号	TEST664280946812921445
原单号	当前退款单的支付单原单号，是开发者侧生成的单号	1312312312demo
平台原单号	当前退款单的支付单原平台单号，平台生成	1224020110934211872378
订单金额(分)	该退款单对应的支付单，订单金额	10
支付方式	用户支付方式， WECHAT_SFT - 微信 ALIPAY_ZFT - 支付宝 APPLE_PAY - 苹果支付	WECHAT_SFT
退款单号	开发者侧生成的退款单号	refundNoXXXX
平台退款单号	小程序平台生成的退款单号	2324020110934211872378
退款金额(分)	退给用户金额	10
退款状态	退款结果，目前只展示退款成功状态，枚举值为：SUCCESS	10
退款原因	退款原因的说明	协商一致退款
退款完成时间	退款到账时间	2024-04-01 10:01:21
退款类型	枚举值如下 结算前退款 结算后退款 保证金账户退款	结算前退款
退款账户	枚举值如下 待结算账户 可提现账户 保证金账户 和退款类型字段一一对应	待结算账户

1.5.3、结算账单

字段名依次为：

序号，分账时间，商户号，原单号，平台原单号，订单金额(分)，用户支付金额(分)，平台补贴金额(分)，结算金额(分)，支付方式，分账单号，平台分账单号，分账状态，分账方及分账金额

demo：

字段解释

字段名	描述	示例值
序号	账单行数	1
分账时间	分账	2024-04-01 10:01:11
商户号	快手小程序平台商户号	TEST664280946812921445
原单号	当前退款单的支付单原单号，是开发者侧生成的单号	1312312312demo
平台原单号	当前退款单的支付单原平台单号，平台生成	1224020110934211872378
订单金额(分)	该结算单对应的支付单，订单金额	10
用户支付金额(分)	用户除去平台补贴后实际支付金额	8
平台补贴金额(分)	平台对该比订单的补贴金额	2
结算金额(分)	当前结算单发起分账金额	10
分账单号	开发者发起结算分账时传入单号	settle_xxxx
平台分账单号	小程序平台对该比结算单生成的唯一平台单号	3224020110934211872378
分账状态	结算分账结果，目前只展示分账成功的结算单，枚举值为SUCCESS	SUCCESS
分账方及分账金额	分账方参数说明： COMMISSION_RATE：平台服务费比例类型      1. feePermille：平台服务费率（千分比）      2. feeAmount：平台服务费金额，cents：金额（分），currency：币种（CNY人民币）      3. orderAmount：当次结算总金额，cents：金额（分），currency：币种（CNY人民币） PROMOTION：达人分佣金额      1. feePermille：达人分佣比例（万分比，若商品对接时仅设置固定佣金，此项返回0。佣金以feeAmount为准）      2. feeAmount：达人分佣金额，cents：金额（分），currency：币种（CNY人民币）      3. orderAmount：当次结算总金额，cents：金额（分），currency：币种（CNY人民币） DEVELOPER_PROMOTION：服务商分佣金额      1. feePermille：服务商分佣比例（万分比）      2. feeAmount：服务商分佣金额，cents：金额（分），currency：币种（CNY人民币）      3. orderAmount：当次结算总金额，cents：金额（分），currency：币种（CNY人民币）	[ { "feeType": "COMMISSION_RATE", "feePermille": 6, "feeAmount": { "cents": 7, "currency": "CNY" }, "orderAmount": { "cents": 1200, "currency": "CNY" } }, { "feeType": "PROMOTION", "feePermille": 0, "feeAmount": { "cents": 200, "currency": "CNY" }, "orderAmount": { "cents": 1200, "currency": "CNY" } }, { "feeType": "DEVELOPER_PROMOTION", "feePermille": 100, "feeAmount": { "cents": 12, "currency": "CNY" }, "orderAmount": { "cents": 1200, "currency": "CNY" } } ]

2、 账单样例

支付账单 Demo (opens new window)

退款账单 Demo (opens new window)

结算账单 Demo (opens new window)