预下单接口
收藏
我的收藏

提交支付订单信息。

使用限制

无

接口说明

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

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

沙盒环境使用说明详见担保支付-沙盒环境。

基本信息

基本信息
HTTP URL	正式环境：https://developer.toutiao.com/api/apps/ecpay/v1/create_order 沙盒环境：https://open-sandbox.douyin.com/api/apps/ecpay/v1/create_order
HTTP Method	POST
请求频次	app_id维度限流150QPS，thirdparty_id维度限流150QPS

请求头

名称	类型	必填	描述
Content-Type	string	是	固定值 "application/json"

请求参数

名称	类型	是否必填	最大长度	描述	示例值
app_id	string	是	64	小程序APPID	tt07e3715e98c9aac0
out_order_no	string	是	64	开发者侧的订单号。只能是数字、大小写字母_-*且在同一个app_id下唯一	7056505317450041644
total_amount	number	是	取值范围： [1,10000000000]	支付价格。单位为[分]	100，即1元
subject	string	是	128	商品描述。长度限制不超过 128 字节且不超过 42 字符	抖音商品XYZ
body	string	是	128	商品详情长度限制不超过 128 字节且不超过 42 字符	抖音商品XYZ
valid_time	number	是	取值范围： [300,172800]	订单过期时间(秒)。最小5分钟，最大2天，小于5分钟会被置为5分钟，大于2天会被置为2天	900，即15分钟
sign	string	是	344	签名，详见签名DEMO	21fc77aeeaad725d9500062a888888a2a3d
cp_extra	string	否	2048	开发者自定义字段，回调原样回传。超过最大长度会被截断	502205261403349
notify_url	string	否	256	商户自定义回调地址，必须以 https 开头，支持 443 端口。指定时，支付成功后抖音会请求该地址通知开发者	https://api.iiyyeixin.com/Notify/bytedancePay
thirdparty_id	string	条件选填服务商模式接入必传	64	第三方平台服务商 id，非服务商模式留空	tt84a4f2177777e29df
store_uid	string	条件选填多门店模式下可传	64	可用此字段指定本单使用的收款商户号（目前为灰度功能，需要联系平台运营添加白名单，白名单添加1小时后生效；未在白名单的小程序，该字段不生效）	70084531288883795888
disable_msg	number	否	-	是否屏蔽支付完成后推送用户抖音消息，1-屏蔽 0-非屏蔽，默认为0。特别注意：若接入POI, 请传1。因为POI订单体系会发消息，所以不用再接收一次担保支付推送消息，	1
msg_page	string	否	-	支付完成后推送给用户的抖音消息跳转页面，开发者需要传入在app.json中定义的链接，如果不传则跳转首页。	pages/orderDetail/orderDetail?no=DYMP8218048851499944448\u0026id=797775
expand_order_info		否	-	订单拓展信息，详见下面 expand_order_info参数说明	{"original_delivery_fee":10,"actual_delivery_fee":10}
limit_pay_way	string	否	64	屏蔽指定支付方式，屏蔽多个支付方式，请使用逗号","分割，枚举值：屏蔽微信支付：LIMIT_WX 屏蔽支付宝支付：LIMIT_ALI 特殊说明：若之前开通了白名单，平台会保留之前屏蔽逻辑；若传入该参数，会优先以传入的为准，白名单则无效	屏蔽微信支付： "LIMIT_WX"

expand_order_info 参数

名称	类型	是否必填	最大长度	描述	示例值
original_delivery_fee	number	否	取值范围： [1,10000000000]	配送费原价，单位为[分]，仅外卖小程序需要传对应信息	10
actual_delivery_fee	number	否	取值范围： [1,10000000000]	实付配送费，单位为[分]，仅外卖小程序需要传对应信息	10

请求示例

json复制
{
  "app_id": "tt07e3715e98c9aac0",
  "out_order_no": "out_order_no_1",
  "total_amount": 12800,
  "subject": "测试商品",
  "body": "测试商品", 
  "valid_time": 180,
  "sign": "d716027b7b5a91a3319a061d818cc9cc",
  "cp_extra": "一些附加信息",
  "notify_url": "https://api.iiyyeixin.com/Notify/bytedancePay"
}

响应参数

公共响应参数

名称	类型	是否必填	最大长度	描述	示例值
err_no	number	是	-	返回码，详见错误码	40004
err_tips	string	是	-	返回码描述，详见错误描述	Business Failed
data	object	否	-	结构体描述如下	见下方「响应示例」

业务响应参数

名称	类型	是否必填	最大长度	描述	示例值
order_id	string	是	128	抖音侧唯一订单号	N6819903302604491021
order_token	string	是	-	签名后的订单信息	CgwIARDiDRibDiABKAESTgpMbBhsCG7V1MPGAvpICgUSyGcuNOVb/

响应示例

正常响应示例

json复制
{
  "err_no": 0,
  "err_tips": "",
  "data": {
    "order_id": "N6819903302604491021",
    "order_token": "CgwIARDiDRibDiABKAESTgpMbBhsCG7V1MPGAvpICgUSyGcuNOVb/BnCOi9EXgAxIxDqLTwCA6Hd3tNrCde28o0qjmAJQsmLrD18ifr5QktalszSSmTpHCqEm3h55xoA"
  }
}

异常响应示例

json复制
{
  "err_no": 5004,
  "err_tips": "小程序违规，相关接口已被封禁，请咨询相关同学后进行整改" 
}

错误码

公共错误码

错误码 err_no	描述 err_tips	排查建议
0	预下单成功	-
1000	系统异常	当前请求可能成功也可能失败。 1、请使用相同的参数再次重试调用，需要保证订单号、金额、id等参数信息不能变更。 2、或者通过支付查询接口查询支付结果
1001	业务繁忙，请稍后重试	系统限流，稍后原单号重试
2000	支付记录不存在	检查请求中的支付单号、商户支付单号是否正确，确认后重新发起
2003	无有效回调配置	请检查参数，原单号重试
2008	验签异常	请检查参数，详见签名DEMO
2020	非法app_id	请检查参数中的app_id是否有效
2021	订单号为空	检查请求参数，修改后重试
2022	订单金额必须大于0	检查请求参数，修改后原单号重试
2023	商品描述为空	检查请求参数，修改后原单号重试
2025	商品详情为空	检查请求参数，修改后原单号重试
2028	非法自定义回调地址	检查请求参数，修改后原单号重试
2038	小程序违规，小程序被封禁，请咨询相关同学后进行整改	联系小程序平台处理
2042	小程序appid无效，请检查app_id字段	检查app_id字段信息是否有误
2047	服务商id无效，请检查thirdparty_id字段	检查thirdparty_id字段信息是否有误
2048	未查询到服务商与小程序的授权关系	检查服务商与小程序的授权关系
3000	业务异常，请检查订单状态	联系小程序平台处理
3114	会员未开户	联系小程序平台处理
3173	商户无可用支付方式	联系小程序平台处理
5001	订单已支付	确认该笔交易信息是否为当前买家的，如果是则认为交易付款成功，如果不是则更换订单号后，重新发起请求
5002	订单已超时，请重新下单	请更换订单号后，重新发起请求
5004	小程序违规，支付接口已被封禁，请咨询相关同学后进行整改	请先参考小程序交易能力接入规范看对应小程序交易类目是否开放，如果交易类目已开放，联系小程序平台处理
5005	交易信息被篡改	请确认当前out_order_no对应的订单是否已存在，如果是则因为本次请求参数与已存交易不一致，如果不是请更换out_order_no后，重新发起请求
5007	无可用支付方式	请检查是否开通支付方式/传入屏蔽指定支付方式参数
5008	请求已被拦截，请使用交易系统下单	请参考交易系统介绍接入交易系统