收银台接口参考

供 web/cashier 使用。商户通常创建 QR_CASHIER 订单后分发链接，无需重写收银台。先阅读 完整流程。

认证与响应

全部 POST，接受 JSON / 表单，以订单链接中的 token 认证，不要求 mchNo/appId/sign。token 与订单及应用密钥绑定，不自行构造，不写入公开日志。

普通成功为 {code:0,msg:"SUCCESS",data:...}，失败为 code=1 加错误 msg；不提供商户接口响应签名。金额单位为分。

confirm、pay 使用双层响应，必须同时检查外层 code 和内层 data.code。

获取订单与恢复展示

POST /api/cashier/payOrderInfo

请求：{"token":"ORDER_TOKEN"}。

data 字段	类型	说明
mchName	string	接口保留名称，当前 UI 不展示
amount	integer	金额，分
payOrderId、mchOrderNo	string	平台、商户单号
state	integer	支付状态
errCode、errMsg	string / null	渠道错误
returnUrl	string	带签名业务参数的同步跳转地址，可为空
expiredTime	string	数据库日期时间字符串，不是毫秒时间戳
expired	boolean	是否过期
selectedWayCode	string / null	待选择时为 null，锁定后为实际方式
presentation	object / null	持久化展示快照，尚未创建为 null

presentation 含 wayCode、ifCode、presentationState、payDataType、payData、expiresAt；按需含 form（action、fields）及 launchUrl。expiresAt 是日期时间字符串。

presentationState	处理
preparing	已占位，渠道调用/保存可能进行中，查询原单
ready	恢复已有展示
unknown	展示或结果未知，不重复创建支付
expired	过期，停止展示与唤起
complete	订单终态，停止展示与唤起

过期或终态会清空 payData 并移除 form/launchUrl。准备超过 120 秒未完成时按 unknown 展示，不代表渠道确认失败。

获取候选项

POST /api/cashier/options

请求：{"token":"ORDER_TOKEN"}。data 是数组；非状态 0、非聚合待选订单或已过期时返回空数组。

{
  "code": 0,
  "msg": "SUCCESS",
  "data": [{
    "label": "支付宝扫码",
    "wallet": "alipay",
    "interaction": "qr",
    "oauth": false,
    "wayCode": "ALI_QR",
    "ifCode": "globetap",
    "channelName": "渠道名称",
    "optionId": "服务器返回的选项标识",
    "available": true,
    "reason": ""
  }]
}

wallet 为 alipay / wechat；interaction 为 qr / redirect / bridge。available=false 时展示 reason 并禁用确认，不能仅凭 wayCode 判断可用。ifCode/channelName 是接口描述，当前收银台 UI 不展示渠道标识。

确认支付项

POST /api/cashier/confirm

字段	必填	说明
token	是	订单 token
optionId	是	options 返回的原始 ID

环境取自 User-Agent。服务器验证候选能力，首次确认后锁定方式与渠道。

{
  "code": 0,
  "msg": "SUCCESS",
  "data": {
    "code": 0,
    "msg": "SUCCESS",
    "data": {
      "payOrderId": "P_DEMO",
      "mchOrderNo": "ORDER_DEMO",
      "orderState": 1,
      "payDataType": "codeUrl",
      "payData": "渠道二维码原始内容",
      "errCode": null,
      "errMsg": null
    }
  }
}

结果兼容统一下单字段，可附加 launchUrl。业务失败或未知时，可能外层成功、内层失败：

{
  "code": 0,
  "msg": "SUCCESS",
  "data": { "code": 1, "msg": "支付正在确认，请刷新订单状态，勿重复下单", "data": null }
}

重复确认已绑定项可恢复结果，切换其他项被拒绝。不以自动重试触发新资金创建请求。

OAuth 与用户身份

授权地址

POST /api/cashier/redirectUrl：必填 token、wayCode，data 为 OAuth URL。仅适用于实际支持授权的通道；当前 JSAPI 为 ALI_JSAPI / WX_JSAPI。

换取用户标识

POST /api/cashier/channelUserId：必填 token、wayCode；微信另传 code、state；支付宝传 auth_code（兼容 authCode）。data 为用户标识字符串。

服务器按 token 与 wayCode 绑定 Redis 身份，当前有效期 300 秒。不能使用其他订单/应用的 openid 或 buyerUserId。

兼容旧版 JSAPI 支付

POST /api/cashier/pay：必填 token、wayCode；channelUserId 字段兼容保留，OAuth 方式读取服务器绑定身份，不信任浏览器传入值。

与 confirm 相同双层响应，结果保留历史兼容 alipayTradeNo。新选择页使用 options / confirm；旧流程由收银台内部协调，不同时调用两套流程。

取消待支付订单

POST /api/cashier/cancelPay：必填 token，仅取消状态 0 且未请求渠道支付的订单。成功：

{ "code": 0, "msg": "SUCCESS", "data": true }

不执行上游支付中订单的本地强制关闭。