---
url: >-
  https://acquirer-api-docs-v4-en.pingpongx.com/notes/zh/InPersonPayments/gmcSerialPort/index.md
description: >-
  GMC串口MIS接入方案适用于SAAS收银机厂商,通过串口与POS设备通信,实现支付、退款、查询、心跳等业务功能。该方案采用自定义串口通信协议,支持波特率115200的串口通信,使用SHA256签名保证数据安全,适合线下收银场景的快速集成。
---
## 概述

![GMC串口支付系统架构](/InPersonPayments/gmc/GMC_flow.png)

GMC串口MIS接入方案为SAAS收银机厂商提供了一种高效的支付集成方式,通过串口与POS设备直接通信,无需网络连接即可完成支付交易。

### 适用场景

- 线下零售收银系统
- SAAS收银机厂商
- POS设备集成
- 离线/半离线支付场景

### 核心功能

::: info 支持功能
- **下单支付** - 创建订单并完成支付
- **交易退款** - 对已完成的交易进行退款
- **交易查询** - 查询交易状态和详情
- **心跳检测** - 保持设备连接状态
- **重打印** - 重新打印交易小票
- **结算** - 批量结算功能
:::

## 接入前提

在开始集成之前,请确保满足以下条件:

1. **POS设备要求**
   - POS设备已集成GMC串口通信协议
   - 支持标准串口通信(RS-232/USB转串口)

2. **技术能力要求**
   - SAAS系统具备串口通信能力
   - 支持Java/Python/C++等语言的串口库
   - 具备SHA256签名实现能力，详见[签名规约](/notes/zh/onlinePayment/developer/sign/)

3. **商户资质**
   - 已获取商户在PingPong系统的 `accId` 和 `clientId`
   - 已完成商户入驻流程

:::warning 注意事项
请妥善保管商户凭证信息,避免泄露造成安全风险。
:::

## 串口通信协议

### 通信参数配置

串口通信需与POS设备约定一致的参数配置：

| 参数 | 默认值 | 说明 |
|:----|:------|:----|
| **波特率** | 115200 | 通信速率 |
| **数据位** | 8 | 数据位数 |
| **停止位** | 1 | 停止位数(1=1位,2=2位) |
| **校验位** | 0 | 校验方式(0=无,1=奇,2=偶) |

### 报文帧结构

串口通信采用自定义帧结构，格式如下：

```plaintext
[帧头(2B)] + [数据长度(2B)] + [数据报文] + [校验位(1B)] + [帧尾(2B)]
```

| 字段名称 | 长度(字节) | 取值规则 |
|:--------|:----------|:--------|
| **帧头** | 2 | 固定为 `0xAA 0x55` |
| **数据长度** | 2 | 0~65535,表示数据报文的字节数,采用大端模式存储 |
| **数据报文** | 0~65535 | 上层业务数据JSON字符串 |
| **校验位** | 1 | 数据报文所有字节的异或(XOR)结果 |
| **帧尾** | 2 | 固定为 `0x55 0xAA` |

### 报文示例

以下是退款请求的串口十六进制报文示例：

```plaintext
AA 55 01 A4 7B 22 61 63 63 49 64 22 3A 22 31 30 30 30 30 31 22 ... 33 55 AA
```

解析后的JSON数据：

```json
{
  "accId": "100001",
  "clientId": "POS_12345",
  "event": "REFUND",
  "signType": "SHA256",
  "version": "1.0",
  "requestTime": "1760754805426",
  "sign": "BAEA4D56D885D6BD449BFFA2D9F117ECEDA662C85197A19050CA0C18CC64B871",
  "bizContent": "{...}"
}
```

> [!TIP]
> 📌 `sign` 字段为请求签名，计算规则详见[签名规约](/notes/zh/onlinePayment/developer/sign/)

:::tip 帧构建提示
1. 先将JSON数据转换为UTF-8字节数组
2. 计算字节数组长度,转为2字节大端格式
3. 计算所有数据字节的异或值作为校验位
4. 按帧结构顺序拼接完整报文
:::

## 交互流程
```mermaid
%%{init: {
  'theme': 'base',
  'themeVariables': {
    'primaryColor': '#E3F2FD',
    'primaryTextColor': '#0D47A1',
    'primaryBorderColor': '#1976D2',
    'lineColor': '#1565C0',
    'secondaryColor': '#BBDEFB',
    'tertiaryColor': '#90CAF9',
    'background': '#F8FBFF',
    'mainBkg': '#E3F2FD',
    'secondBkg': '#BBDEFB',
    'tertiaryBkg': '#90CAF9',
    'actorBkg': '#2196F3',
    'actorBorder': '#1976D2',
    'actorTextColor': '#FFFFFF',
    'actorLineColor': '#1565C0',
    'signalColor': '#0D47A1',
    'signalTextColor': '#0D47A1',
    'c0': '#E8F4FD',
    'c1': '#D1E7DD',
    'c2': '#B3D9FF',
    'c3': '#81C784',
    'noteBkgColor': '#E1F5FE',
    'noteTextColor': '#01579B',
    'noteBorderColor': '#0288D1',
    'loopTextColor': '#0D47A1',
    'activationBkgColor': '#B3E5FC',
    'activationBorderColor': '#0277BD'
  }
}}%%

sequenceDiagram
    participant SAAS
    participant POS
    participant PPSERVE

    SAAS->>POS: 1. 支付/退款请求<br/>（串口通信、SHA256签名）
    
    POS->>POS: 2. 报文处理
    POS->>PPSERVE: 3. 支付/退款请求
    PPSERVE->>PPSERVE: 4. 支付/退款请求处理
    PPSERVE->>POS: 5. 支付/退款请求
    POS->>POS: 6. 交易/退款处理
    POS->>PPSERVE: 7. 支付结果

    Note over SAAS: 支付/退款结果查询
    SAAS->>POS: 8. 支付结果查询
    POS->>SAAS: 9. 支付结果返回
```

### 支付流程步骤

:::: steps

1. SAAS发起支付请求

   SAAS收银系统通过串口向POS设备发送支付请求，请求报文需使用SHA256签名保证数据安全（[签名规约](/notes/zh/onlinePayment/developer/sign/)）。

   调用接口：[GMC串口支付接口](/notes/zh/api/services/InPersonPayments/gmc/pay/)

2. POS报文处理

   POS设备接收串口数据，解析报文并验证签名，提取业务参数。

3. POS转发支付请求

   POS设备将支付请求转发至PingPong服务端进行处理。

4. PingPong处理支付请求

   PingPong服务端验证商户信息、处理支付路由、执行风控检查。

5. POS执行交易

   POS设备根据PingPong服务端指令执行刷卡、插卡或扫码等交易操作。

6. POS上报支付结果

   交易完成后，POS设备将支付结果上报至PingPong服务端。

7. SAAS查询支付结果

   SAAS收银系统通过串口向POS设备查询支付结果，获取交易状态和详情。

   调用接口：[GMC串口查询接口](/notes/zh/api/services/InPersonPayments/gmc/query/)

::::

### 退款流程步骤

:::: steps

1. SAAS发起退款请求

   SAAS收银系统通过串口向POS设备发送退款请求，需提供原支付订单号和退款金额。

   调用接口：[GMC串口退款接口](/notes/zh/api/services/InPersonPayments/gmc/refund/)

2. POS报文处理

   POS设备接收串口数据，解析报文并验证签名，校验退款参数。

3. POS转发退款请求

   POS设备将退款请求转发至PingPong服务端进行处理。

4. PingPong处理退款请求

   PingPong服务端验证原订单信息、检查可退款金额、执行退款处理。

5. POS执行退款

   POS设备根据PingPong服务端指令执行退款操作。

6. POS上报退款结果

   退款完成后，POS设备将退款结果上报至PingPong服务端。

7. SAAS查询退款结果

   SAAS收银系统通过串口向POS设备查询退款结果，确认退款状态。

   调用接口：[GMC串口查询接口](/notes/zh/api/services/InPersonPayments/gmc/query/)

::::

## 相关接口

| 接口名称 | EVENT | 说明 | 链接 |
|:--------|:------|:-----|:-----|
| GMC串口心跳接口 | `HEARTBEAT` | 保持SAAS与POS设备连接状态 | [查看文档](/notes/zh/api/services/InPersonPayments/gmc/heartbeat/) |
| GMC串口支付接口 | `PAY` | 创建支付订单并完成交易 | [查看文档](/notes/zh/api/services/InPersonPayments/gmc/pay/) |
| GMC串口交易查询接口 | `PAY_QUERY` | 查询支付交易状态和详情 | [查看文档](/notes/zh/api/services/InPersonPayments/gmc/payQuery/) |
| GMC串口退款接口 | `REFUND` | 对已完成的交易发起退款 | [查看文档](/notes/zh/api/services/InPersonPayments/gmc/refund/) |
| GMC串口退款查询接口 | `REFUND_QUERY` | 查询退款交易状态和详情 | [查看文档](/notes/zh/api/services/InPersonPayments/gmc/refundQuery/) |
| GMC串口交易取消接口 | `TRANSACTION_CANCEL` | 取消进行中的交易 | [查看文档](/notes/zh/api/services/InPersonPayments/gmc/transactionCancel/) |
| GMC串口重打印接口 | `REPRINT` | 重新打印交易小票凭证 | [查看文档](/notes/zh/api/services/InPersonPayments/gmc/reprint/) |
| GMC串口结算接口 | `CALCULATE` | 触发POS设备批量结算 | [查看文档](/notes/zh/api/services/InPersonPayments/gmc/settlement/) |

### 接口使用说明

#### 心跳检测（HEARTBEAT）

- 建议每 **30秒** 发送一次心跳包
- 连续3次无响应可判定设备离线
- `bizContent` 字段可为空

#### 交易查询（PAY_QUERY）

- 用于查询支付交易状态和详情
- 支持通过 `merchantTransactionId` 或 `transactionId` 查询，二选一
- 返回交易金额、状态、时间及卡支付信息等详情

#### 退款查询（REFUND_QUERY）

- 用于查询退款交易状态和详情
- 支持通过 `merchantRefundId` 或 `transactionRefundId` 查询，二选一
- 返回退款金额、状态、时间及卡支付信息等详情

#### 交易取消（TRANSACTION_CANCEL）

- 用于取消进行中的交易
- 需要提供 `merchantTransactionId` 商户交易流水号
- 仅对特定状态下的交易有效

#### 重打印（REPRINT）

- 用于重新打印上一笔交易小票
- `bizContent` 字段可为空，默认打印最后一笔交易
- 如需指定交易，可在 `bizContent` 中传入交易ID

#### 结算（CALCULATE）

- 用于触发POS设备批量结算，通常在日终执行
- `bizContent` 字段可为空
- 结算完成后POS设备会打印结算凭证