# 接口定义

# 担保支付时序图

图中黄色备注是对应的开放接口。

# 支付流程

# 结算流程

# 退款流程

# 1、支付下单

# 1.1 预下单接口

# 请求地址

POST https://open.kuaishou.com/openapi/mp/developer/epay/create_order

Content-Type: application/json

# 参数

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

以下字段放置到body json中：

字段名	类型	是否必填	是否参与签名	参数位置	说明
out_order_no	string[6,32]	是	是	body json	商户系统内部订单号，只能是数字、大小写字母_-*且在同一个商户号下唯一示例值：1217752501201407033233368018
open_id	string	是	是	body json	快手用户在当前小程序的open_id，可通过login操作获取。
total_amount	number	是	是	body json	用户支付金额，单位为[分]。不允许传非整数的数值。
subject	string[1,128]	是	是	body json	商品描述。注：1汉字=2字符。
detail	string[1,1024]	是	是	body json	商品详情。注：1汉字=2字符。
type	number	是	是	body json	商品类型，不同商品类目的编号见担保支付商品类目编号
expire_time	number	是	是	body json	订单过期时间，单位秒，300s - 172800s
sign	string	是	否	body json	开发者对核心字段签名, 签名方式见附录
attach	string[0,128]	否	是	body json	开发者自定义字段，回调原样回传. 注：1汉字=2字符；勿回传敏感信息
notify_url	string[1, 256]	是	是	body json	通知URL必须为直接可访问的URL，不允许携带查询串。
goods_id	string[1, 256]	否(本地生活类必填)	是	body json	下单商品id，需与商品对接 (opens new window)时的product_id一致，长度限制256个英文字符，1个汉字=2个英文字符；
goods_detail_url	string[1, 500]	否(本地生活类必填)	是	body json	订单详情页跳转path。长度限制500个英文字符，1个汉字=2个英文字符；示例值：/page/index/anima
multi_copies_goods_info	string[1, 500]	否(单商品多份场景必填)	是	body json	单商品购买多份场景，示例值：[{"copies":2}]，内容见multi_copies_goods_info字段说明
cancel_order	number	否	是	body json	该字段表示创建订单的同时是否覆盖之前已存在的订单。取值范围: [0, 1]。 0:不覆盖 1:覆盖使用说明：如果传值为1 重复调用接口后执行逻辑为先删除已存在的订单再创建新订单，如果传值为0 重复调用接口执行逻辑为直接返回已创建订单的订单信息。如果不传该参数则和传值为0逻辑一致

# multi_copies_goods_info字段说明

字段名	类型	说明
copies	number	购买份数

# 响应

返回值为 JSON 形式，其中包括如下字段：

字段名	类型	说明
result	number	状态码 1-业务处理成功
error_msg	string	错误提示信息，常见错误处理可参考附录常见问题章节
order_info	json string	拉起收银台的 orderInfo

示例如下（仅供参考）：

{
    "result":1,
    "error_msg":"错误信息提示",
    "order_info":{
        "order_no": "121072611585202788127",
        "order_info_token": "ChJrc01wUGF5Lm9yZGVyVG9rZW4SULxOUORbNX1NAzmbs3vCE8Fo8FN8EW90EM7iReQujs85RbgDNVDPqxJoGly_jX7Zv9kwTiXsrFuSgwrR-ufuZexCYejepc-C0swHGhJtqssdzyq4aMsYYWjhyloiIOZOjlvg2cPW6VJsOmt6c4Tz2qSsZoAhTeKIZAXM13SRKAUwAQ"
    }
}

# 错误码

当 result 不为 1 时，说明请求错误。错误码见附录。

# 1.2 订单查询接口

# 请求地址

POST https://open.kuaishou.com/openapi/mp/developer/epay/query_order

Content-Type: application/json

# 参数

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

以下字段放置到body json中：

字段名	类型	是否必填	是否参与签名	参数位置	说明
out_order_no	string[6,32]	是	是	body json	商户系统内部订单号，只能是数字、大小写字母_-*且在同一个商户号下唯一示例值：1217752501201407033233368018
sign	string	是	否	body json	开发者对核心字段签名, 签名方式见附录

# 响应

返回值为 JSON 形式，其中包括如下字段：

字段名	类型	说明
result	number	状态码 1-业务处理成功
error_msg	string	错误提示信息，常见错误处理可参考附录常见问题章节
payment_info	json string	订单支付信息

示例如下（仅供参考）：

{
    "result":1,
    "error_msg":"错误提示信息",
    "payment_info":{
        "total_amount": 1200,
        "pay_status": "PROCESSING", // PROCESSING-处理中|SUCCESS-成功|FAILED-失败|TIMEOUT-超时
        "pay_time": ,
        "pay_channel": "WECHAT", // WECHAT-微信 | ALIPAY-支付宝
        "out_order_no": "1637808229728demo",
        "ks_order_no": "121112500031787702250",
        "extra_info":"{"url":"","item_type":"VIDEO","item_id":"5239375269605736845","author_id":"123"}", // VIDEO-视频|LIVE-直播|UNKNOWN-其他，url只有视频存在
        "enable_promotion": true,
        "promotion_amount": 1,
        "open_id":"5b748c61ef280130c0656638ebd4eaa6",
        "order_status": 2
    }
}

payment_info字段说明：

字段名	类型	说明
total_amount	number	预下单用户支付金额
pay_status	string	支付状态。取值： PROCESSING-处理中｜SUCCESS-成功｜FAILED-失败 TIMEOUT-超时
pay_time	number	订单支付时间，单位为毫秒时间戳。
pay_channel	string	支付渠道。取值：UNKNOWN - 未知｜WECHAT-微信｜ALIPAY-支付宝。(注：如果用户还未支付，这里返回的是UNKNOWN.）
out_order_no	string	开发者下单单号
ks_order_no	string	快手小程序平台订单号
extra_info	string	订单来源信息，历史订单为""
enable_promotion	boolean	是否参与分销，true:分销，false:非分销
promotion_amount	number	预计分销金额，单位：分
open_id	string	订单对应的用户open id
order_status	number	开发者回传的订单同步状态，状态值说明见订单同步接口 (opens new window)

extra_info说明及示例：

extra_info字段为订单信息的来源，以JSON字符串格式。开发者可通过该字段区分订单来源于直播场景或者短视频场景（其他场景返回为空）, 以及对应的视频作者和视频ID。

开发者需要解析字符串，从中获取字段具体信息，字段信息含义如下:

字段名	说明
url	视频/直播对应的链接：如为直播，返回为空；如为短视频，返回的是加密的视频ID，开发者可通过拼接http前缀，访问到具体视频。如短视频场景返回的URL为：3xqxmjkthzpckus；在该返回结果前拼接 https://www.kuaishou.com/short-video/ 生成：https://www.kuaishou.com/short-video/3xqxmjkthzpckus （可直接访问到具体视频）
item_type	VIDEO=短视频 LIVE=直播
item_id	直播id或视频id
author_id	快手ID（注意快手ID区别于快手号，但对于具体账号，均唯一 )
trade_no	用户侧支付页交易单号，具体获取方法可点击查看 (opens new window)

示例：

直播
{"url":"","item_type":"LIVE","item_id":"PMbDd4e7u9o","author_id":"2282629641"}
视频
{"url":"3xqxmjkthzpckus","item_type":"VIDEO","item_id":"5217138756521753529","author_id":"1198084488"}

# 错误码

当 result 不为 1 时，说明请求错误。错误码见附录。

# 1.3 支付回调

当订单成功支付之后，快手小程序服务端会通过 post 方式回调开发者提供的 HTTP 接口。回调的内容使用小程序 secret key 进行签名，具体回调方式和重试策略见附录。

其中，回调地址需在开发者平台-权限管理-支付-支付设置中配置：

回调内容如下：

{
    "data": {
        "channel": "WECHAT",
        "out_order_no": "1627293310922demo",
        "attach": "小程序demo得",
        "status": "SUCCESS",
        "ks_order_no": "121112500031787702250",
        "order_amount": 1,
        "trade_no":"4323300968202201201545417324",
        "extra_info":"",
        "enable_promotion": true,
        "promotion_amount": 1
    },
    "biz_type": "PAYMENT",
    "message_id": "fa578923-347b-4158-9ae8-06c54d485da3",
    "app_id": "ks682576822728417112",
    "timestamp": 1627293368719
}

其中和支付相关的主要是：

字段名	类型	说明
channel	string	支付渠道。取值：UNKNOWN - 未知｜WECHAT-微信｜ALIPAY-支付宝
out_order_no	string	商户系统内部订单号，只能是数字、大小写字母_-*且在同一个商户号下唯一示例值：1217752501201407033233368018
attach	string	预下单时携带的开发者自定义信息
status	string	订单支付状态。取值： PROCESSING-处理中｜SUCCESS-成功｜FAILED-失败
ks_order_no	string	快手小程序平台订单号
order_amount	number	订单金额
trade_no	string	用户侧支付页交易单号，具体获取方法可点击查看
extra_info	string	订单来源信息，同支付查询接口
enable_promotion	boolean	是否参与分销，true:分销，false:非分销
promotion_amount	number	预计分销金额，单位：分

开发者返回

开发者在接收到回调消息，并正确处理后，需要返回以下内容格式，以通知小程序平台不再持续回调：

{
  "result" : 1,   //必填。 1-成功，其他-失败。失败小程序平台会尝试重推此消息
  "message_id" : "ChFvYXV0aC5hY2Nlc3NUb2tlbhJQvpR51x8In46B1sDB" //当前消息的message_id
}

如果开发者没有返回或者返回的result不等于1，则小程序平台会尝试重复推送此消息，开发者务必做好消息的幂等处理！

# 2、支付退款

# 2.1 请求退款接口

当交易发生之后一段时间内，由于买家或者卖家的原因需要退款时，卖家可以通过退款接口将支付款退还给买家，将在收到退款请求并且验证成功之后，按照退款规则将支付款按原路退到买家帐号上。注意：

在途资金中的所有货款均是与订单关联的，只有当该订单在途资金中剩余金额超过退款金额时，才可以进行在途资金的退款。
当可提现金额也不足退款金额时，会退款失败，为了避免出现订单无法退款的情况出现，请根据业务情况自行保留一部分可提现金额在系统中。
退款的资金判断流程如下：

# 请求地址

POST https://open.kuaishou.com/openapi/mp/developer/epay/apply_refund

Content-Type: application/json

接口频次: 30QPS(小程序app_id维度)

# 参数

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

以下字段放置到body json中：

字段名	类型	是否必填	是否参与签名	参数位置	说明
out_order_no	string	是	是	body json	开发者需要发起退款的支付订单号，商户系统内部订单号，只能是数字、大小写字母_-*且在同一个商户号下唯一示例值：1217752501201407033233368018
out_refund_no	string[6,32]	是	是	body json	开发者的退款单号
reason	string[1,80]	是	是	body json	退款理由。1个汉字=2个字符
attach	string[0,80]	否	是	body json	开发者自定义字段，回调原样回传. 注：1汉字=2字符；勿回传敏感信息
notify_url	string[1,256]	是	是	body json	通知URL必须为直接可访问的URL，不允许携带查询串。
refund_amount	number	否	是	body json	用户退款金额，单位为分。不允许传非整数的数值
sign	string	是	否	body json	开发者对核心字段签名, 防止传输过程中出现意外，签名方式见附录
multi_copies_goods_info	string[1, 500]	否(单商品多份场景必填)	是	body json	单商品购买多份场景，示例值：[{"copies":2}]，内容见multi_copies_goods_info字段说明

# multi_copies_goods_info字段说明

字段名	类型	说明
copies	number	退款份数

# 响应

返回值为 JSON 形式，其中包括如下字段：

字段名	类型	说明
result	number	状态码 1-业务处理成功
error_msg	string	错误提示信息，常见错误处理可参考附录常见问题章节
refund_no	string	快手小程序平台的退款单号

示例如下（仅供参考）：

{
    "result":1,
    "error_msg":"错误信息提示",
    "refund_no": "221072611585202788127"
}

# 错误码

当 result 不为 1 时，说明请求错误。错误码见附录。

# 2.2 退款查询接口

# 请求地址

POST https://open.kuaishou.com/openapi/mp/developer/epay/query_refund

Content-Type: application/json

接口频次: 30QPS(小程序app_id维度)

# 参数

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

以下字段放置到body json中：

字段名	类型	是否必填	是否参与签名	参数位置	说明
out_refund_no	string[6,32]	是	是	body json	开发者的退款单号
sign	string	是	否	body json	开发者对核心字段签名, 签名方式见附录

# 响应

返回值为 JSON 形式，其中包括如下字段：

字段名	类型	说明
result	number	状态码 1-业务处理成功。其他不成功，详细见错误码
error_msg	string	错误提示信息，常见错误处理可参考附录常见问题章节
refund_info	json string	退款信息

示例如下（仅供参考）：

{
    "result":1,
    "error_msg":"success",
    "refund_info":{
        "ks_order_no":"122081801105480677436",
        "refund_status":"REFUND_SUCCESS",
        "refund_no":"1660811124083refund",
        "ks_refund_type":"保证金账户退款",
        "refund_amount":1,
        "ks_refund_fail_reason":"账户异常",
        "apply_refund_reason":"用户申请退款",
        "ks_refund_no":"222081811172813537436"
    }
}

refund_info字段说明：

字段名	类型	说明
ks_order_no	string	快手小程序平台订单号
refund_status	string	退款状态。 REFUND_PROCESSING-处理中，REFUND_SUCCESS-成功，REFUND_FAILED-失败
refund_no	string	小程序平台的退款单号
ks_refund_type	string	退款账户说明
refund_amount	number	此次退款金额。单位为分
ks_refund_fail_reason	string	退款失败原因
apply_refund_reason	string	订单发起退款的原因
ks_refund_no	string	快手小程序平台退款单号

# 错误码

当 result 不为 1 时，说明请求错误。错误码见附录。

# 2.3 退款回调

当订单退款成功之后，快手小程序服务端会通过 post 方式回调开发者提供的 HTTP 接口。回调的内容使用小程序 secret key 进行签名，具体回调方式和重试策略见附录。

回调内容如下：

{
    "data": {
        "out_refund_no": "0007",
        "refund_amount": 1234,
        "attach": "this is some attach",
        "status": "SUCCESS",
        "ks_order_no": "121111200785144945641",
        "ks_refund_no": "221111211991390142641",
        "ks_refund_type":"保证金账户退款",
        "ks_refund_fail_reason":"账户异常",
        "apply_refund_reason":"用户申请退款"
    },
    "message_id": "61901a3a-2b1f-40b6-af14-de34660d7541",
    "biz_type": "REFUND",
    "app_id": "ks656399649443988986",
    "timestamp": 1625728322061
}

其中和退款相关的主要是：

字段名	类型	说明
refund_amount	number	退款金额
out_refund_no	string	开发者的退款单号。
attach	string	预下单时携带的开发者自定义信息
status	string	退款状态。取值： PROCESSING-处理中，SUCCESS-成功，FAILED-失败
ks_order_no	string	快手小程序平台订单号。
ks_refund_no	string	快手小程序平台退款单号。
ks_refund_type	string	退款账户说明
ks_refund_fail_reason	string	退款失败原因
apply_refund_reason	string	订单发起退款的原因

开发者返回

开发者在接收到回调消息，并正确处理后，需要返回以下内容格式，以通知小程序平台不再持续回调：

{
  "result" : 1,   //必填。 1-成功，其他-失败。失败小程序平台会尝试重推此消息
  "message_id" : "ChFvYXV0aC5hY2Nlc3NUb2tlbhJQvpR51x8In46B1sDB" //当前消息的message_id
}

如果开发者没有返回或者返回的result不等于1，则小程序平台会尝试重复推送此消息，开发者务必做好消息的幂等处理！

# 3、支付结算

结算用于确认一笔在途资金，将其转化为可提现资金。

结算规则:

1、订单履约完成后发起结算，结算周期为订单到达核销状态（订单状态为11或15）满3天后可发起结算。核销状态通过订单同步接口 (opens new window)进行同步。
2、需要主动调用结算接口后，才能进行后续资金的提现。
3、结算时，小程序平台会收取整笔交易的平台服务费。若结算后发生退款，则平台服务费不作退还。

# 3.1 请求结算接口

结算功能用于在交易满足结算规则后，可以根据需求分配货款，将资金从冻结户转移至可提现账户。为了保证业务正确处理, 请按担保交易设置页面的分账周期处理分账. 订单在支付后 360 天后如果仍然未进行分账，则当笔交易无法进行资金结算；超期未结算的订单，微信平台将自动结算给商户，支付宝会将资金停留在支付平台，无法结算。在结算环节中，小程序平台会参与对整笔交易的平台服务费进行扣除，详情可以参考附录。平台服务费默认由卖家承担，对于一些特殊场景，允许由接入方指定的分账方承担。

# 请求地址

POST https://open.kuaishou.com/openapi/mp/developer/epay/settle

Content-Type: application/json

接口频次: 30QPS(小程序app_id维度)

# 参数

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

以下字段放置到body json中：

字段名	类型	是否必填	是否参与签名	参数位置	说明
out_order_no	string[6,32]	是	是	body json	开发者需要发起结算的支付订单号，商户系统内部订单号，只能是数字、大小写字母_-*且在同一个商户号下唯一示例值：1217752501201407033233368018
out_settle_no	string[6,32]	是	是	body json	开发者的结算单号，小程序唯一。
reason	string[1,128]	是	是	body json	结算描述，长度限制 128 个字符。1个字符=2个汉字
attach	string[0, 128]	否	是	body json	开发者自定义字段，回调原样回传. 注：1汉字=2字符；勿回传敏感信息
notify_url	string[1,256]	是	是	body json	通知URL必须为直接可访问的URL，不允许携带查询串。
sign	string	是	否	body json	开发者对核心字段签名, 防止传输过程中出现意外，签名方式见附录
settle_amount	number	否	是	body json	当次结算金额，需传大于0的金额，单位为【分】；不传默认全额结算
multi_copies_goods_info	string[1, 500]	否(单商品多份场景必填)	是	body json	单商品购买多份场景，示例值：[{"copies":2}]，内容见multi_copies_goods_info字段说明

# multi_copies_goods_info字段说明

字段名	类型	说明
copies	number	结算份数

# 响应

返回值为 JSON 形式，其中包括如下字段：

字段名	类型	说明
result	number	状态码 1-业务处理成功。其他不成功，详细见错误码
error_msg	string	错误提示信息，常见错误处理可参考附录常见问题章节
settle_no	string	快手小程序平台的结算单号

示例如下（仅供参考）：

{
    "result":1,
    "error_msg":"错误信息提示",
    "settle_no": "221072611585202788127"
}

# 错误码

当 result 不为 1 时，说明请求错误。错误码见附录。

# 3.2 结算查询接口

# 请求地址

POST https://open.kuaishou.com/openapi/mp/developer/epay/query_settle

Content-Type: application/json

接口频次: 30QPS(小程序app_id维度)

# 参数

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

以下字段放置到body json中：

字段名	类型	是否必填	是否参与签名	参数位置	说明
out_settle_no	string[6,32]	是	是	body json	开发者的结算单号
sign	string	是	否	body json	开发者对核心字段签名, 签名方式见附录

# 响应

返回值为 JSON 形式，其中包括如下字段：

字段名	类型	说明
result	number	状态码 1-业务处理成功。其他不成功，详细见错误码
error_msg	string	错误提示信息，常见错误处理可参考附录常见问题章节
settle_info	json string	结算信息

示例如下（仅供参考）：

{
    "result":1,
    "error_msg":"错误提示信息",
    "settle_info":{
        "settle_no":"234325456565",
        "total_amount":3234, // 支付订单总金额
        "settle_amount":234, // 结算后给商家的金额
        "settle_status": "SETTLE_PROCESSING",
        "ks_order_no": "121120711774457276553",
        "ks_settle_no": "321120700415719078553"
    }
}

settle_info字段说明：

字段名	类型	说明
settle_no	string	开发者的结算单号
total_amount	number	支付订单的总金额，单位为分
settle_amount	number	结算后给商户的金额，单位为分
settle_status	string	SETTLE_PROCESSING-处理中，SETTLE_SUCCESS-成功，SETTLE_FAILED-失败
ks_order_no	string	快手小程序平台订单号
ks_settle_no	string	快手小程序平台结算单号

# 错误码

当 result 不为 1 时，说明请求错误。错误码见附录。

# 3.3 结算回调

当订单结算成功之后，快手小程序服务端会通过 post 方式回调开发者提供的 HTTP 接口。回调的内容使用小程序 secret key 进行签名，具体回调方式和重试策略见附录。

回调内容如下：

{
    "data": {
        "out_settle_no": "300005",
        "attach": "第四笔订单结算",
        "settle_amount": 100,
        "status": "SUCCESS",
        "ks_order_no": "121120711774457276553",
        "ks_settle_no": "321120700415719078553",
        "enable_promotion": true,
        "promotion_amount": 1
    },
    "biz_type": "SETTLE",
    "message_id": "9ddc1134-f8b4-4f4c-a991-772ffe841449",
    "app_id": "ks682576822728817112",
    "timestamp": 1627295473323
}

其中和结算相关的主要是：

字段名	类型	说明
out_settle_no	string	外部结算单号，即开发者结算请求的单号。
attach	string	预下单时携带的开发者自定义信息
settle_amount	number	结算后给商户的金额，单位：分
status	string	结算状态。取值： PROCESSING-处理中，SUCCESS-成功，FAILED-失败
ks_order_no	string	快手小程序平台订单号。
ks_settle_no	string	快手小程序平台结算单号。
enable_promotion	boolean	是否参与分销，true:分销，false:非分销
promotion_amount	number	预计分销金额，单位：分

开发者返回

开发者在接收到回调消息，并正确处理后，需要返回以下内容格式，以通知小程序平台不再持续回调：

{
  "result" : 1,   //必填。 1-成功，其他-失败。失败小程序平台会尝试重推此消息
  "message_id" : "ChFvYXV0aC5hY2Nlc3NUb2tlbhJQvpR51x8In46B1sDB" //当前消息的message_id
}

如果开发者没有返回或者返回的result不等于1，则小程序平台会尝试重复推送此消息，开发者务必做好消息的幂等处理！