预下单

1、接口说明

预下单接口需要保证同一app_id下每笔订单的out_order_no是唯一的。

同一订单(app_id，out_order_no相同)重复请求需要保持请求参数一致，否则接口会报错拦截。

2、预下单接口定义

2.1、基本信息

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

2.2、请求头

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

2.3、请求入参

如下参数在queryParam中

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

以下字段放置到body json中

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

multi_copies_goods_info字段说明

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

provider字段说明：

provider字段不传时，为有收银台模式，用户支付时，会拉起快手收银台，如果开发者想跳过收银台，可传该字段，说明如下

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

2.4请求示例

有收银台模式

curl --location --request POST 'https://open.kuaishou.com/openapi/mp/developer/epay/create_order?app_id=ks707065143182458884&access_token=ChFvYXV0aC5hY2Nlc3NUb2tlbhJQumJ4agm3wT4YzPvK7wEfSGVQiVDsnMk-2GqsV8vOKtJiUfl1NAGk4RreGEalNtnyczCzXzQTr-GJJsoKHGDdzRVlwkkOJx8s7mRo_d5_XpMaEkM6eJkoPbfUa_qSANYID35L6iIgb8uJWABERgoGQzYUR7lIgHlt5qRgcTmKYEYwIm5M9lEoDzAB' \
--header 'Content-Type: application/json' \
--data-raw '{
    "open_id": "5b748c61ef290140c0656638eaa0d69c",
    "subject": "测试demo商品",
    "sign": "5f4273e97d6c38bff8f17514e576ebfb",
    "out_order_no": "1699605608467demo1234",
    "expire_time": "3000",
    "type": "1",
    "notify_url": "https://qa-mp.corp.kuaishou.com/zeus/epay/notify",
    "total_amount": "2",
    "detail": "本子demo"
}'

无收银台模式

curl --location --request POST 'https://open.kuaishou.com/openapi/mp/developer/epay/create_order?app_id=ks707065143182458884&access_token=ChFvYXV0aC5hY2Nlc3NUb2tlbhJQumJ4agm3wT4YzPvK7wEfSGVQiVDsnMk-2GqsV8vOKtJiUfl1NAGk4RreGEalNtnyczCzXzQTr-GJJsoKHGDdzRVlwkkOJx8s7mRo_d5_XpMaEkM6eJkoPbfUa_qSANYID35L6iIgb8uJWABERgoGQzYUR7lIgHlt5qRgcTmKYEYwIm5M9lEoDzAB' \
--header 'Content-Type: application/json' \
--data-raw '{
    "open_id": "5b748c61ef290140c0656638eaa0d69c",
    "subject": "测试demo商品",
    "sign": "5f4273e97d6c38bff8f17514e576ebfb",
    "out_order_no": "1699605608467demo1234",
    "expire_time": "3000",
    "type": "1",
    "notify_url": "https://qa-mp.corp.kuaishou.com/zeus/epay/notify",
    "total_amount": "2",
    "detail": "本子demo",
    "provider": {
        "provider_channel_type": "NORMAL",
        "provider": "ALIPAY"
    }
}'

返回信息

返回值为 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 时，说明请求错误。常见错误码如下：

错误码	描述	排查建议
100200102	access denied	token失效，建议重新getAccessToken
10000631	该小程序未在小程序平台进行配置，无法创建支付订单	小程序未进件完成，先完成进件接入
10000601	{app_id}:旧订单信息未查到	cancel_order传1的场景，改单时，旧订单不存在，确认旧订单信息是否正常
10000684	订单支付完成	cancel_order传1的场景，旧订单已经支付完成了，无法修改
10000603	重复下单，且已超时关闭	预下单外部订单号已经下过单，且原订单已经超时关闭，一般请更换外部订单号下单。

3、支付结果回调

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

回调内容如下：

{
    "data": {
        "ks_order_no": "124041001358000182641",
        "channel": "WECHAT",
        "developer_promotion_amount": 0,
        "order_amount": 1,
        "attach": "小程序demo得",
        "app_id": "ks707065143182458884",
        "out_order_no": "1712743260417demo",
        "promotion_amount": 0,
        "extra_info": "{\"url\":\"\",\"provider\":\"\",\"item_type\":\"UNKNOWN\",\"item_id\":\"\",\"author_id\":\"\",\"refer_id\":\"\",\"channel_mark\":\"\",\"provider_type\":\"\",\"trade_no\":\"4333301114202404103760775150\",\"subsidy\":0,\"upa\":0,\"acf\":0,\"withhold_time\":0,\"withhold_period\":0,\"withhold_template_id\":0}",
        "enable_promotion": false,
        "trade_no": "4333301114202404103760775150",
        "status": "SUCCESS"
    },
    "biz_type": "PAYMENT",
    "message_id": "bf46b24e-a56a-4446-8cef-3dc5f23ce3c4",
    "app_id": "ks707065143182458884",
    "timestamp": 1712743274284
}

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

字段名	类型	说明
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	预计达人分销金额，单位：分
developer_promotion_amount	number	预计服务商分销金额，单位：分

开发者返回

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

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

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