# 接口定义

# 担保支付时序图

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

# 支付流程

img

# 结算流程

img

# 退款流程

img

# 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 int 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 int 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
    }
}

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 预计分销金额,单位:分

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区别于快手号,但对于具体账号,均唯一 )

示例:

直播
{\"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 进行签名,具体方式见附录

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

回调内容如下:

{
    "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 用户侧支付页交易单号,具体获取方法可点击查看 (opens new window)
extra_info string 订单来源信息,同支付查询接口
enable_promotion boolean 是否参与分销,true:分销,false:非分销
promotion_amount number 预计分销金额,单位:分

# 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 body json 开发者的退款单号
reason string[1,128] body json 退款理由。1个字符=2个汉字
attach string[0,128] body json 开发者自定义字段,回调原样回传.
注:1汉字=2字符;勿回传敏感信息
notify_url string[1,256] body json 通知URL必须为直接可访问的URL,不允许携带查询串。
refund_amount string[0,128] 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_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_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":"保证金账户退款"
    },
    "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 退款账户说明

# 3、支付结算

结算用于确认一笔在途资金,将其转化为可提现资金。
结算规则:
1、订单履约完成后发起结算,结算周期为 订单到达核销状态满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 long 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 string 结算金额,单位:分
status string 结算状态。 取值: PROCESSING-处理中,SUCCESS-成功,FAILED-失败
ks_order_no string 快手小程序平台订单号。
ks_settle_no string 快手小程序平台结算单号。
enable_promotion boolean 是否参与分销,true:分销,false:非分销
promotion_amount number 预计分销金额,单位:分
Copyright ©2022, All Rights Reserved