服务商担保支付接入接口文档(无收银台版)

更新时间：2024-12-10 16:06:13

担保支付时序图(无收银台版)

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

支付流程

流程说明

提供无收银台的支付方式，支付渠道列表直接展示在订单详情页。新流程相对于原有流程的改动点如下：

1、开发者需在预下单之前获取支付渠道列表，通过小程序基础库中支付渠道列表组件提供，详见支付渠道列表组件。

2、新提供了无收银台的预下单接口，需传入勾选的支付方式，详见下面接口文档。

3、ks.pay API 改造，详见ks.pay接口文档。

1、 预下单接口(无收银台版)

请求地址

POST https://open.kuaishou.com/openapi/mp/tp/epay/create_order_with_channel

Content-Type: application/json

参数

字段名	类型	是否必填	是否参与签名	参数位置	说明
component_app_id	string	是	是	query param	服务商component_app_id
authorizer_access_token	string	是	否	query param	服务商访问authorizer_access_token，获取方式见getAuthorizerAccessToken

以下字段放置到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，需与商品对接时的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字段说明
provider	json	否(无收银台预下单必填)	是	body json	无收银台版本预下单场景，json格式，示例如下： {"provider": "ALIPAY","provider_channel_type":"NORMAL"} 注意： 1、json中字段 枚举值见 provider字段说明。 2、json中字段顺序须与示例中保持一致，否则会导致验签失败。

multi_copies_goods_info字段说明

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

provider字段说明

字段名	类型	说明
provider	string	支付方式，枚举值，目前只支持"WECHAT"、"ALIPAY"两种
provider_channel_type	string	支付方式子类型，枚举值，目前只支持"NORMAL"

响应

返回值为 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 时，说明请求错误。错误码见附录 (opens new window)。

2、 取消支付方式接口

该接口适用于开发者对接无收银台支付预下单之后，后面对该笔支付单的支付方式做修改使用。

具体场景介绍：用户第一次在下单页面选择支付方式后，由于未知情况未完成支付；后面再从待支付订单列表等场景重新支付该笔订单。因为之前的支付方式已经在预下单里标记过，但二次从待支付列表用户可能调整支付方式，此时需要把之前用户选择的支付方式取消掉，重新走收银台页面让用户选择，用户支付时会拉起收银台支付。

请求地址

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

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	错误提示信息，常见错误处理可参考附录常见问题章节
order_info	json string	拉起收银台的 orderInfo

示例如下（仅供参考）：

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

错误码

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

3、 其他接口使用说明

使用无收银台支付方式，流程中其余接口与原有流程一致。详见接口定义。