> For AI agents: the complete documentation index is available at /zh/llms.txt, the full documentation bundle is available at /zh/llms-full.txt. # 订单推送 将商户系统中的订单推送至专用支付终端(例如支持的P3、MT919设备等),支持扫码、银行卡支付 ## 接口信息 - **接口地址:** POST `https://api.aimt-horizon.com/appPush/tradePush` - **签名凭证:** 使用 terminal_sn + terminal_key ## 请求参数 | 参数 | 类型 | 是否必填 | 说明 | | ------------------- | ----------- | ---- | -------------------------------------------------------------------------- | | `terminal_sn` | String(32) | 是 | 绑定来源系统的终端序列号 | | `out_trade_no` | String(32) | 是 | 同一商户内唯一,最多 32 字节,仅英文字母和数字;后续 client_sn 填同一值。 | | `total_amount` | String(10) | 是 | 正整数分,最多 10 位;例如 SGD 1.00 = "100"。渠道限额另行生效。 | | `trade_time` | String(13) | 是 | 发起推送时的 13 位 Unix 毫秒时间戳;每次调用生成当前值,不复制示例历史时间。 | | `target_device_id` | String(20) | 是 | 目标支付设备 ID,例如终端背面的 TUSN 编号 | | `notify_url` | String(128) | 是 | 支付结果通知地址,使用可公网访问的 HTTPS;通知重试见异步回调,不能用于推单重试。 | | `cancel_notify_url` | String(128) | 否 | 取消通知地址;具体触发路径依设备与路由而异,需联调验证;不能代替支付查单。 | | `pay_type` | String(32) | 否 | 常用值:1=银行卡、2=扫码、6=C 扫 B(顾客扫描商户收款码);多个值用半角逗号分隔,例如 1,2,6。其他枚举不代表新加坡已开通,见能力边界。 | | `remark` | String(16) | 否 | 订单备注,例如桌号、参考信息 | ## 调用示例 ```bash curl --request POST 'https://api.aimt-horizon.com/appPush/tradePush' \ --header 'Authorization: 2101107140290972547 ' \ --header 'Authorization-Type: sha256' \ --header 'Content-Type: application/json' \ --data '{ "terminal_sn": "2101107140290972547", "out_trade_no": "SG20261022001", "total_amount": "100", "trade_time": "1792627200000", "target_device_id": "TUSN12345678", "notify_url": "https://your-system.com/api/payment/callback", "pay_type": "1,2,6", "remark": "Table 12" }' ``` ## 业务流程 ```mermaid flowchart TD accTitle: 订单推送支付流程 accDescr: 收银员创建订单并推送到支付设备。顾客付款后,商户验签通知并确认结果,结合查询恢复未知结果。 A["收银员在商户系统创建订单"] --> B["POST /appPush/tradePush"] B --> C["终端显示订单并提示付款"] C --> D["顾客扫码或刷卡付款"] D --> E["结果回调至 notify_url"] E --> F["验签并核对订单、金额和流水状态"] F --> G["持久化事件并幂等更新订单"] B -. "确认结果或恢复未知状态" .-> Q["POST /upay/v2/query"] Q --> F ``` `PUSH_SUCCESS` 仅表示受理,不能证明设备已显示订单或支付成功。更新本地订单前,按[响应与状态规则](/zh/guide/business.md#response-states)确认结果。 :::warning 关键规则 - out_trade_no 对应查询/服务端退款的 client_sn,同一商户内唯一;PUSH_SUCCESS 响应通常不返回 sn。 - target_device_id 必须预先登记(扫描终端上的 TUSN 条码)。 - PUSH_SUCCESS 后等待付款并查单;超时先查原订单,不能按通知的 1/5/30/600 秒间隔自动重推。 - 必须结合查询接口主动确认状态,不要仅依赖回调。 ::: ## 受理响应 ```json { "result_code": "200", "biz_response": { "result_code": "PUSH_SUCCESS" } } ``` 错误字段可能为 null 或省略。此响应通常没有 `sn`,也不承诺设备已显示订单或顾客已付款;保留原 `out_trade_no`,后续用它查单。常见拒绝与未知结果见[错误码](/zh/guide/testing.md#errors)。