响应与订单约定
响应结构#
| 字段 | 类型 | 说明 |
|---|---|---|
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 只返回当前可用于新单的选项,排除维护通道;币种和银行目录不是通道可交易状态。维护错误及重试建议见 错误码。