文档目录 · 响应与订单约定

响应与订单约定

响应结构#

字段 类型 说明
code integer 0 为请求成功;非零为业务错误
message string 响应说明
data object / null 成功数据;错误时为 null
request_id string 请求追踪号
message_key string 错误标识,仅错误响应返回
default_message string 默认错误说明,仅错误响应返回
{
  "code": 50006,
  "message_key": "error.cashier_unavailable",
  "default_message": "cashier session unavailable",
  "message": "cashier session unavailable",
  "data": null,
  "request_id": "req_01JEXAMPLE"
}

HTTP 状态通常为 200,须以 JSON 的 code 判断请求结果。请求成功与交易成功分别判断。

收银台会话#

创建接口首次成功时返回下列 data 字段:

字段 类型 说明
checkout_mode string cashier
platform_order_no string 平台订单号
merchant_order_no string 商户订单号
amount string 交易金额
requested_amount string 原始请求金额,代收创建返回
currency string 交易币种
status string awaiting_payment_method
payment_url string 收银台地址,仅创建返回;须保存并原样交给用户
expired_at string 会话到期时间

创建会话时尚未生成正式订单。查询会话不返回 payment_url、通道或手续费;正式订单生成后,查询优先返回正式订单,此时 checkout_mode=direct 表示已进入正式订单阶段。

会话状态 说明
awaiting_payment_method 等待用户选择通道
selecting 正在确认选择或提交,请继续查询
submitted 已提交,请查询正式订单
expired 会话已过期

payment_url 中的 token 属于敏感信息,不应写入日志或分析参数。地址不得修改或跨订单复用。

重试与返回地址#

  • 创建幂等: 使用唯一且持久化的 merchant_order_no。相同订单号和业务内容重复创建时返回原会话或订单;关键字段变化返回冲突。重试须保持原业务参数,包括 return_url 和预填资料。用户编辑资料后,商户仍使用原参数重试;确认后资料锁定。
  • 结果不明: 非零 code、网络中断或超时不能单独判断交易失败。保存订单号与 request_id,使用原订单号查询,不要更换订单号重复创建。
  • 浏览器返回: 支付页面返回同一笔收银台后显示当前订单状态。代收为 paid 且存在返回地址时,页面提供“立即返回商户”按钮和 10 秒倒计时;失败、关闭、过期页面及代付页面支持手动返回。浏览器跳转不能作为交易成功依据。

通道维护#

通道处于 maintenance 时暂停接收新订单,已有正式订单继续按原规则处理。maintenance 是通道状态,不是订单或收银台会话的 status 值。

维护切换时的阶段 处理方式
新创建请求或未生成正式订单的收银台会话 不能选择维护通道;可选择其他满足授权、币种、金额、费率等条件的 active 通道。只有 payment_url 或平台订单号不代表已生成正式订单。
已生成正式订单,尚未提交支付通道 继续使用原通道,允许按原幂等和有效期规则继续提交,不重复建单或冻结资金。
已提交的正式订单 继续处理交易结果、订单查询及异步通知;维护本身不会将订单改为失败或释放冻结资金。

维护本身不阻断代收本地查单、代付查单及 sync_provider=true 的处理中订单状态同步,也不影响商户余额查询。所有请求仍须满足原有签名、权限及订单归属校验,异步通知仍需验签和去重。过期或终态订单不会因维护而重新开放提交。

/api/v1/channel/options 只返回当前可用于新单的选项,排除维护通道;币种和银行目录不是通道可交易状态。维护错误及重试建议见 错误码。

搜索文档