Skip to main content

create_order

用一次预览返回的 preview_id 与 confirmation_token 正式下单。下单成功后返回平台订单 ID order_id、订单状态 status、应付金额 payable_price,以及(需支付时的)支付动作 payment_action。
下单链路:search_shops 得 shop_id + cart_id → get_shop_menu 选商品 → quote_cart 算价得 quote_id → select_address 得 address_id → preview_order 得 preview_id + confirmation_token → create_order 得 order_id + payment_action。preview_id 与 confirmation_token 必须来自同一次 preview_order 调用,原样回传,不可自造或混用。
本工具幂等:以 confirmation_token 为幂等键。幂等指纹比对 preview_id + confirmation_token + payment_method 三项,外加 require_phone_verify 是否为 true(不含 callback_url)。用相同 confirmation_token 重复调用时:若这几项与首次一致,返回首次的结果;若任一与首次不一致,则返回 IDEMPOTENCY_CONFLICT。同一令牌只能下一单——再次下单需重新走 preview_order 取新令牌。注意:仅改 callback_url(其余三项不变)不算冲突,会命中重放并重新开始一轮状态跟踪(回调因此可能多次送达)。

参数

require_phone_verify 说明: 传 true 后,这笔订单的所有链接——本次返回的 payment_action.action_url,以及之后 get_order_status / list_orders 给出的 detail_url——打开时都会先出现一个「确认本人」页,输入下单手机号后 4 位,输对才进入订单页。输对一次后,同一浏览器 24 小时内再打开不用重输;连错 5 次后这笔单的链接锁定 24 小时。适合链接会经过聊天转发、担心发错人的场景。是否开启在下单时确定,之后不可更改;不传或 false 时链接与以往完全一样。 callback_url 说明: 必须是绝对的 http/https URL,禁止指向回环 / 内网 / 链路本地等地址。填写后,这笔订单每次状态变化都会向该地址 POST 一条事件,直到订单结束(completed / cancelled / failed / refunded)。查状态的频率是:未支付时约 2 秒一次,已支付后约 30 秒一次。订单满 2 小时仍未结束时,会推送一条 timeout 事件后停止,调用方不会一直等下去。 回调 body:
status 枚举(共 8 值):
订单创建成功这件事不会单独推一条事件——create_order 的返回本身就是凭据。第一条事件通常是 pending_payment。
支付成败那一条额外带两个字段,格式与旧版回调完全一致,已有的接收逻辑无需改动:
用 seq 自查有没有漏收: 同一笔订单的 seq 从 1 连续递增。若你收到 1、2、4,说明第 3 条没送到,调 get_order_status 补查当前状态即可。 去重: 回调为至少一次送达,同一条可能重复到达,请按 (order_id, seq) 去重。 投递失败只重试三次(间隔 1 / 2 / 4 秒),之后不再补发,但不影响订单本身。不传 callback_url 则一条都不推,请自行调用 get_order_status 查询。

返回

金额字段 payable_price 单位为分(整数),不是元。例如 payable_price: 1500 表示 ¥15.00。
status 枚举: created(订单已创建)、pending_payment(待支付)、paid(已支付)、preparing(商家备餐中)、delivering(配送中)、completed(已完成)、cancelled(已取消)、failed(下单或履约失败)、refunded(已退款)。

错误码

完整错误码见 错误处理。

调用示例

链接需先确认本人时: