武汉高盛伟业科技股份有限公司
Wuhan Gao Sheng Wei Ye Technology Co., Ltd
第三方串口支付对接接口文档 完整版 v1.3
Third-party serial payment interface documentation (Complete) v1.3
All rights reserved. All reproduction prohibited
| 版本号 Version | 修改标识 Modify Logo | 修改原因/内容 Modification reason/content | 修改人 Modified by | 审核人 Reviewer | 审批人 Approver | 修改时间 Modification time |
|---|---|---|---|---|---|---|
| V1.0 | 新建/Create | 创建原始文档 Create original file | 王显泽 | 王显泽 | 2024-12-11 | |
| V1.1 | 修改/Revise | 添加示例 Add example | 王显泽 | 王显泽 | 2025-01-09 | |
| V1.2 | 补全/Complete | 补齐物理层、校验算法、字节序、金额表达、完整十六进制示例、时序与错误处理等对接说明 | 2026-08-26 | |||
| V1.3 | 扩展/Extend | 新增取消支付命令 0x22，并完善时序、错误处理与检查清单 |
2026-09-10 |
0x200x210x080x240x22本通信接口使用主从模式。Android 上位机发起请求，支付设备（下位机）被动应答。
This interface uses master-slave mode. The Android host initiates requests; the payment device responds passively.
| 角色 / Role | 说明 / Description |
|---|---|
| 上位机 / Host | Android 侧业务逻辑：读状态、下单、轮询支付结果、通知制作结果 |
| 下位机 / Device | 支付设备：应答命令、执行扣款、在超时未收到制作通知时可退款等 |
| 参数 / Parameter | 值 / Value |
|---|---|
| 串口类型 / Serial type | 标准 RS-232 |
| 波特率 / Baud rate | 9600 |
| 数据位 / Data bits | 8 |
| 校验位 / Parity | 无 / None |
| 停止位 / Stop bits | 1（8N1） |
| 流控 / Flow control | 无 / None |
即：9600 8N1。
| FLAG | LEN | COMND | DATA | SUM |
|---|
| 字段 | 长度 | 说明 |
|---|---|---|
| FLAG | 2 字节 | 帧头：0xAA, 0x55 |
| LEN | 1 字节 | 从 COMND 到 SUM（含） 的字节数 |
| COMND | 1 字节 | 命令字节 |
| DATA | 0～N 字节 | 数据区，不定长 |
| SUM | 1 字节 | 校验和 |
| FLAG1 | LEN | RESP | DATA | SUM |
|---|
| 字段 | 长度 | 说明 |
|---|---|---|
| FLAG1 | 2 字节 | 帧头：0xA5, 0x5A |
| LEN | 1 字节 | 从 RESP 到 SUM（含） 的字节数 |
| RESP | 1 字节 | 接收正确时等于对应命令字节；错误时为 0xFF |
| DATA | 0～N 字节 | 数据区，不定长 |
| SUM | 1 字节 | 校验和 |
计算规则：SUM = FLAG + LEN + COMND + DATA（应答侧对应 FLAG1 + LEN + RESP + DATA）。
注意事项：
SUM = total & 0xFF（模 256）；逐步计算示例（读状态请求）：
字节：AA 55 02 20
累加：0xAA + 0x55 + 0x02 + 0x20 = 0x121
SUM = 0x121 & 0xFF = 0x21
完整帧：AA 55 02 20 21
金额、流水号等 2 字节无符号整数采用大端序（高字节在前）。
示例：金额数值 1250（十进制）→ 0x04E2 → 线上字节 04 E2。
读状态 / Read status
上位机发送 0x20；下位机返回就绪 DATA1=0x00 或支付禁用 0x01。
Host sends 0x20; device replies ready (0x00) or payment prohibited (0x01).
禁用则结束 / End if prohibited
若支付禁用，上位机不创建订单，流程结束。
If prohibited, host must not create an order; flow ends.
创建订单 / Create order
就绪后上位机发送 0x21；下位机返回成功 0x00 或异常 0xFF（异常则结束并需重新下单）。
When ready, host sends 0x21; device returns OK (0x00) or error (0xFF). On error, end and place a new order.
轮询支付 / Poll payment
创建成功后每 200 ms 发送 0x08，总超时 5 分钟。0x00 扣款成功并进入制作；0xFF 失败结束；其它值视为支付中继续轮询；超时结束并重新下单。
After create OK, poll 0x08 every 200 ms within 5 minutes. 0x00 = paid then produce; 0xFF = fail and end; other = pending keep polling; timeout ends and requires a new order.
取消支付（可选） / Cancel payment (optional)
在创建订单成功之后、查询支付尚未返回 0x00 之前，上位机可发送 0x22 取消当前进行中订单。应答 0x00：取消成功，停止轮询并结束本单；应答 0xFF：取消失败（无进行中订单 / 已扣款成功 / 设备异常）。支付成功后不可用本命令取消。
After create OK and before payment query returns 0x00, host may send 0x22 to cancel the current pending order. 0x00 = cancel OK, stop polling and end this order; 0xFF = cancel failed (no pending order / already paid / device error). Do not use this command after payment success.
制作通知 / Production result
支付成功后上位机开始制作，完成后发送 0x24（成功 0x00 / 失败 0x01）；下位机应答。若支付成功后 5 分钟仍未收到制作通知，下位机可退款。
After payment success, host produces then sends 0x24 (0x00 success / 0x01 failure); device acknowledges. If no result within 5 minutes after payment, device may refund.
时序图（成功主路径）如下 / Sequence diagram (happy path) below:
取消支付路径如下 / Cancel payment path below:
超时约定：
| 阶段 | 超时 | 处理 |
|---|---|---|
| 创建订单后等待支付成功 | 5 分钟 | 支付设备结束流程；需重新下单 |
| 支付成功后等待制作结果通知 | 5 分钟 | 下位机可执行退款等操作 |
轮询约定：
DATA = 0x00：扣款成功，进入制作；DATA = 0xFF：扣款异常/失败，结束本单；0x22 取消当前进行中订单；取消成功后应停止轮询。命令字一览：
0x20读状态，0x21创建订单，0x08查询支付状态，0x22取消支付，0x24制作结果通知。
0x20）| FLAG | LEN | COMND | SUM |
|---|---|---|---|
| AA 55 | 0x02 | 0x20 | SUM |
0x02：COMND(1) + SUM(1)| FLAG1 | LEN | RESP | DATA1 … DATA7 | SUM |
|---|---|---|---|---|
| A5 5A | 0x09 | 0x20 | 7 字节 | SUM |
0x09：RESP(1) + DATA1…DATA7(7) + SUM(1)| 字段 | 说明 |
|---|---|
| DATA1 | 设备状态：0x00 在线/就绪；0x01 支付禁用 |
| DATA2～DATA7 | 保留，填 0x00 |
请求：
AA 55 02 20 21
应答（设备就绪）：
A5 5A 09 20 00 00 00 00 00 00 00 28
计算：A5+5A+09+20+00×7 = 0x128 → SUM=0x28。
0x21）| FLAG | LEN | COMND | DATA | DATA1 | DATA2 | SUM |
|---|---|---|---|---|---|---|
| AA 55 | 0x07 | 0x21 | 1B 单位 | 2B 金额 | 2B 流水号 | SUM |
0x07：COMND(1) + DATA(1) + DATA1(2) + DATA2(2) + SUM(1)DATA — 金额最小单位（仅此字段 + DATA1 表达金额；流水号不参与金额）：
| DATA | 单位 | 1 个单位折合人民币 | DATA1 可表达最大金额 |
|---|---|---|---|
| 0x01 | 分 | 0.01 元 | 655.35 元 |
| 0x02 | 角 | 0.1 元 | 6553.5 元 |
| 0x03 | 元 | 1 元 | 65535 元 |
| 0x04 | 百 | 100 元 | 6,553,500 元 |
| 0x05 | 千 | 1000 元 | 65,535,000 元 |
| 0x06 | 万 | 10000 元 | 655,350,000 元 |
金额公式：
实际支付金额（元）= DATA1（无符号整数 0～65535）× 单位面值
推荐： 常规售货/点餐优先使用 DATA = 0x01（分），保证分位精度。超过 655.35 元时需换更大单位，但会损失更小面额精度。
| 字段 | 长度 | 说明 |
|---|---|---|
| DATA1 | 2 字节，大端 | 金额数值（在所选单位下） |
| DATA2 | 2 字节，大端 | 支付流水号 / 订单标识，范围 0～65535，不参与金额计算；溢出复用策略由业务自行约定 |
| FLAG1 | LEN | RESP | DATA | SUM |
|---|---|---|---|---|
| A5 5A | 0x03 | 0x21 | 状态 | SUM |
| DATA | 含义 |
|---|---|
| 0x00 | 操作成功 |
| 0xFF | 设备异常 |
场景：支付 12.50 元，单位用分 → DATA1 = 1250 = 0x04E2；流水号 = 1 = 0x0001。
请求：
AA 55 07 21 01 04 E2 00 01 0F
计算：AA+55+07+21+01+04+E2+00+01 = 0x20F → SUM=0x0F。
应答（成功）：
A5 5A 03 21 00 23
计算：A5+5A+03+21+00 = 0x123 → SUM=0x23。
0x08）上位机下发创建订单成功后，每 200 ms 轮询本命令。支付侧总超时 5 分钟；超时需重新下单。
| FLAG | LEN | COMND | SUM |
|---|---|---|---|
| AA 55 | 0x02 | 0x08 | SUM |
| FLAG1 | LEN | RESP | DATA | SUM |
|---|---|---|---|---|
| A5 5A | 0x03 | 0x08 | 状态 | SUM |
| DATA | 含义 | 上位机处理 |
|---|---|---|
| 0x00 | 正常扣款 / 支付成功 | 停止轮询，开始制作，随后发 0x24 |
| 0xFF | 扣款异常 / 支付失败 | 停止轮询，结束本单 |
| 其它值 | 视为支付中 | 继续 200 ms 轮询，直至超时 |
请求：
AA 55 02 08 09
计算：AA+55+02+08 = 0x109 → SUM=0x09。
应答（扣款成功）：
A5 5A 03 08 00 0A
计算：A5+5A+03+08+00 = 0x10A → SUM=0x0A。
应答（扣款异常）：
A5 5A 03 08 FF 09
计算：A5+5A+03+08+FF = 0x209 → SUM=0x09。
0x24）上位机收到支付成功后开始制作；下位机等待制作完成通知。
超时 3 分钟仍未收到通知时，下位机可执行退款等操作。
| FLAG | LEN | COMND | DATA | SUM |
|---|---|---|---|---|
| AA 55 | 0x03 | 0x24 | 结果 | SUM |
| DATA | 含义 |
|---|---|
| 0x00 | 制作成功 |
| 0x01 | 制作失败 |
| FLAG1 | LEN | RESP | DATA | SUM |
|---|---|---|---|---|
| A5 5A | 0x03 | 0x24 | 状态 | SUM |
| DATA | 含义 |
|---|---|
| 0x00 | 返回正常 |
| 0xFF | 返回异常 |
请求（制作成功）：
AA 55 03 24 00 26
计算：AA+55+03+24+00 = 0x126 → SUM=0x26。
请求（制作失败）：
AA 55 03 24 01 27
计算：AA+55+03+24+01 = 0x127 → SUM=0x27。
应答（正常）：
A5 5A 03 24 00 26
计算：A5+5A+03+24+00 = 0x126 → SUM=0x26。
0x22）扩展约定： 原文未定义本命令；用于取消当前进行中、尚未扣款成功的订单（设备侧单活跃订单模型）。
允许时机： 仅在「创建订单成功之后、查询支付尚未返回 0x00 之前」。支付成功后不可用本命令取消（退款走设备侧超时等既有逻辑）。
兜底处理： 上位机停止 0x08 轮询，当两帧超时时间未收到轮询指令，下位机自行取消支付退出，本单结束；需支付时重新 0x21 下单。
| FLAG | LEN | COMND | SUM |
|---|---|---|---|
| AA 55 | 0x02 | 0x22 | SUM |
0x02：COMND(1) + SUM(1)0x08 相同结构）| FLAG1 | LEN | RESP | DATA | SUM |
|---|---|---|---|---|
| A5 5A | 0x03 | 0x22 | 状态 | SUM |
| DATA | 含义 |
|---|---|
| 0x00 | 取消成功 |
| 0xFF | 取消失败（无进行中订单 / 已扣款成功不可取消 / 设备异常） |
请求：
AA 55 02 22 23
计算：AA+55+02+22 = 0x123 → SUM=0x23。
应答（取消成功）：
A5 5A 03 22 00 24
计算：A5+5A+03+22+00 = 0x124 → SUM=0x24。
应答（取消失败）：
A5 5A 03 22 FF 23
计算：A5+5A+03+22+FF = 0x223 → SUM=0x23。
| 情况 | 判定 | 建议处理 |
|---|---|---|
应答 RESP = 0xFF |
帧被识别但命令处理错误 | 检查命令字、LEN、DATA；必要时重发或中止 |
| 校验和错误 | 本地计算 SUM 与帧内 SUM 不符 | 丢弃该帧；可有限次重发请求 |
| 无应答 / 超时无帧 | 链路或设备无响应 | 检查串口参数与接线；重试；仍失败则告警 |
创建订单应答 0xFF |
设备异常 | 勿进入支付轮询；提示用户 |
支付查询 0xFF |
扣款失败 | 结束本单；需重新 0x21 下单 |
取消支付应答 0x00 |
取消成功 | 停止 0x08 轮询；本单结束；再支付需重新下单 |
取消支付应答 0xFF |
取消失败 | 无进行中订单、已扣款成功或设备异常；已支付则勿再取消，按制作/退款流程处理 |
已支付后误发 0x22 |
取消失败或不应取消 | 支付成功后不得用取消代替退款；应走 0x24 或设备侧超时退款 |
| 支付等待超过 5 分钟 | 支付流程超时 | 结束本单；重新下单 |
| 制作通知超过 5 分钟未发 | 下位机侧超时 | 下位机可退款；上位机应保证及时发 0x24 |
设备状态 0x01 |
支付禁用 | 禁止创建订单 |
建议重试： 单次请求无有效应答时，可间隔短延时重发 2～3 次；业务状态机仍以支付/制作 5 分钟总超时为准。
AA 55，应答帧头 A5 5A0x01（分）表达金额0x20 确认设备就绪（DATA1=0x00）0x08，仅 0x00 进入制作0x22；成功则停止轮询并结束本单0x22；尽快下发 0x24，避免下位机 5 分钟后退款| 步骤 | 方向 | 帧（十六进制） |
|---|---|---|
| 1 读状态 | Host → Dev | AA 55 02 20 21 |
| 1 应答就绪 | Dev → Host | A5 5A 09 20 00 00 00 00 00 00 00 28 |
| 2 创建订单 | Host → Dev | AA 55 07 21 01 04 E2 00 01 0F |
| 2 应答成功 | Dev → Host | A5 5A 03 21 00 23 |
| 3 查询支付 | Host → Dev | AA 55 02 08 09 |
| 3 应答成功 | Dev → Host | A5 5A 03 08 00 0A |
| 4 制作成功 | Host → Dev | AA 55 03 24 00 26 |
| 4 应答正常 | Dev → Host | A5 5A 03 24 00 26 |
| 步骤 | 方向 | 帧（十六进制） |
|---|---|---|
| 创建订单成功后轮询中 | — | （略，同主路径步骤 2～3 请求侧） |
| 取消支付 | Host → Dev | AA 55 02 22 23 |
| 应答取消成功 | Dev → Host | A5 5A 03 22 00 24 |
文档结束 / End of document