# 预下单
更新时间：2024-09-10 22:14:19
# 1、接口说明
- 预下单接口需要保证同一app_id下每笔订单的out_order_no是唯一的。
- 同一订单(app_id，out_order_no相同)重复请求需要保持请求参数一致，否则接口会报错拦截。
- 支付回调地址会优先使用开发者在 预下单接口 传入的 notify_url，如果预下单接口没有传入，会填充开发者在开发者平台设置的 支付回调，该支付回调地址设置与查看步骤如下【小程序开发者平台 (opens new window) -> 交易管理 -> 支付管理 -> 支付设置 -> 默认回调地址】
# 2、预下单接口定义
# 2.1、基本信息
| 名称 | 内容 |
| HTTP URL | 有收银台模式：https://open.kuaishou.com/openapi/mp/developer/epay/create_order 无收银台模式：https://open.kuaishou.com/openapi/mp/developer/epay/create_order_with_channel |
| 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,256] | 否 | 是 | 开发者自定义字段，回调原样回传. 注：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格式，示例如下： 注意： 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_with_channel?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:业务处理成功 非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，则小程序平台会尝试重复推送此消息，开发者务必做好消息的幂等处理！
上一篇：《自动结算接入说明》
下一篇：《无收银台模式预下单取消支付渠道》
仍有疑问? 前往社区提问