---
url: >-
  https://acquirer-api-docs-v4-en.pingpongx.com/en/notes/InPersonPayments/gmcSerialPort/index.md
description: >-
  The GMC serial port MIS integration solution is suitable for SAAS cash
  register manufacturers, communicating with POS devices through serial ports to
  achieve payment, refund, query, heartbeat and other business functions. This
  solution adopts a custom serial communication protocol, supports serial
  communication with a baud rate of 115200, uses SHA256 signature to ensure data
  security, and is suitable for rapid integration in offline cash register
  scenarios.
---
## Overview

![GMC Serial Payment System Architecture](/InPersonPayments/gmc/GMC_flow.png)

The GMC serial port MIS integration solution provides an efficient payment integration method for SAAS cash register manufacturers, directly communicating with POS devices through serial ports to complete payment transactions without network connection.

### Application Scenarios

- Offline retail cash register systems
- SAAS cash register manufacturers
- POS device integration
- Offline/semi-offline payment scenarios

### Core Functions

::: info Supported Features
- **Order Payment** - Create orders and complete payments
- **Transaction Refund** - Refund completed transactions
- **Transaction Query** - Query transaction status and details
- **Heartbeat Detection** - Maintain device connection status
- **Reprint** - Reprint transaction receipts
- **Settlement** - Batch settlement function
:::

## Prerequisites

Before starting the integration, please ensure the following conditions are met:

1. **POS Device Requirements**
   - POS device has integrated GMC serial communication protocol
   - Supports standard serial communication (RS-232/USB to serial)

2. **Technical Capability Requirements**
   - SAAS system has serial communication capability
   - Supports serial libraries for Java/Python/C++ and other languages
   - Has SHA256 signature implementation capability, see [Signature Specification](/en/notes/guide/sign/)

3. **Merchant Qualifications**
   - Have obtained merchant's `accId` and `clientId` in the PingPong system
   - Have completed merchant onboarding process

:::warning Important Notes
Please properly safeguard merchant credential information to avoid security risks caused by leaks.
:::

## Serial Communication Protocol

### Communication Parameter Configuration

Serial communication requires consistent parameter configuration agreed upon with the POS device:

| Parameter | Default Value | Description |
|:----|:------|:----|
| **Baud Rate** | 115200 | Communication speed |
| **Data Bits** | 8 | Number of data bits |
| **Stop Bits** | 1 | Number of stop bits (1=1 bit, 2=2 bits) |
| **Parity** | 0 | Parity type (0=None, 1=Odd, 2=Even) |

### Message Frame Structure

Serial communication adopts a custom frame structure with the following format:

```plaintext
[Frame Header(2B)] + [Data Length(2B)] + [Data Message] + [Checksum(1B)] + [Frame Tail(2B)]
```

| Field Name | Length(Bytes) | Value Rules |
|:--------|:----------|:--------|
| **Frame Header** | 2 | Fixed as `0xAA 0x55` |
| **Data Length** | 2 | 0~65535, indicates number of bytes in data message, stored in big-endian mode |
| **Data Message** | 0~65535 | Upper layer business data JSON string |
| **Checksum** | 1 | XOR result of all bytes in data message |
| **Frame Tail** | 2 | Fixed as `0x55 0xAA` |

### Message Examples

Here is a hexadecimal serial message example for refund request:

```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
```

Parsed JSON data:

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

> [!TIP]
> 📌 The `sign` field is the request signature, calculation rules see [Signature Specification](/en/notes/guide/sign/)

:::tip Frame Construction Tips
1. First convert JSON data to UTF-8 byte array
2. Calculate byte array length, convert to 2-byte big-endian format
3. Calculate XOR value of all data bytes as checksum
4. Concatenate complete message in frame structure order
:::

## Interaction Flow
```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. Payment/Refund Request<br/>(Serial Communication, SHA256 Signature)
    
    POS->>POS: 2. Message Processing
    POS->>PPSERVE: 3. Payment/Refund Request
    PPSERVE->>PPSERVE: 4. Payment/Refund Request Processing
    PPSERVE->>POS: 5. Payment/Refund Request
    POS->>POS: 6. Transaction/Refund Processing
    POS->>PPSERVE: 7. Payment Result

    Note over SAAS: Payment/Refund Result Query
    SAAS->>POS: 8. Payment Result Query
    POS->>SAAS: 9. Payment Result Return
```

### Payment Process Steps

:::: steps

1. SAAS initiates payment request

   SAAS cash register system sends payment request to POS device via serial port, request message needs to use SHA256 signature to ensure data security ([Signature Specification](/en/notes/guide/sign/)).

   API call: [GMC Serial Payment Interface](/en/notes/api/services/InPersonPayments/gmc/pay/)

2. POS message processing

   POS device receives serial data, parses message and verifies signature, extracts business parameters.

3. POS forwards payment request

   POS device forwards payment request to PingPong server for processing.

4. PingPong processes payment request

   PingPong server validates merchant information, processes payment routing, executes risk control checks.

5. POS executes transaction

   POS device performs swipe, insert or scan transactions according to PingPong server instructions.

6. POS reports payment result

   After transaction completion, POS device reports payment result to PingPong server.

7. SAAS queries payment result

   SAAS cash register system queries payment result from POS device via serial port to obtain transaction status and details.

   API call: [GMC Serial Query Interface](/en/notes/api/services/InPersonPayments/gmc/query/)

::::

### Refund Process Steps

:::: steps

1. SAAS initiates refund request

   SAAS cash register system sends refund request to POS device via serial port, needs to provide original payment order number and refund amount.

   API call: [GMC Serial Refund Interface](/en/notes/api/services/InPersonPayments/gmc/refund/)

2. POS message processing

   POS device receives serial data, parses message and verifies signature, validates refund parameters.

3. POS forwards refund request

   POS device forwards refund request to PingPong server for processing.

4. PingPong processes refund request

   PingPong server validates original order information, checks refundable amount, executes refund processing.

5. POS executes refund

   POS device performs refund operation according to PingPong server instructions.

6. POS reports refund result

   After refund completion, POS device reports refund result to PingPong server.

7. SAAS queries refund result

   SAAS cash register system queries refund result from POS device via serial port to confirm refund status.

   API call: [GMC Serial Query Interface](/en/notes/api/services/InPersonPayments/gmc/query/)

::::

## Related Interfaces

| Interface Name | EVENT | Description | Link |
|:--------|:------|:-----|:-----|
| GMC Serial Heartbeat Interface | `HEARTBEAT` | Maintain SAAS and POS device connection status | [View Documentation](/en/notes/api/services/InPersonPayments/gmc/heartbeat/) |
| GMC Serial Payment Interface | `PAY` | Create payment order and complete transaction | [View Documentation](/en/notes/api/services/InPersonPayments/gmc/pay/) |
| GMC Serial Pay Query Interface | `PAY_QUERY` | Query payment transaction status and details | [View Documentation](/en/notes/api/services/InPersonPayments/gmc/payQuery/) |
| GMC Serial Refund Interface | `REFUND` | Initiate refund for completed transactions | [View Documentation](/en/notes/api/services/InPersonPayments/gmc/refund/) |
| GMC Serial Refund Query Interface | `REFUND_QUERY` | Query refund transaction status and details | [View Documentation](/en/notes/api/services/InPersonPayments/gmc/refundQuery/) |
| GMC Serial Transaction Cancel Interface | `TRANSACTION_CANCEL` | Cancel transactions in progress | [View Documentation](/en/notes/api/services/InPersonPayments/gmc/transactionCancel/) |
| GMC Serial Reprint Interface | `REPRINT` | Reprint transaction receipt vouchers | [View Documentation](/en/notes/api/services/InPersonPayments/gmc/reprint/) |
| GMC Serial Settlement Interface | `CALCULATE` | Trigger POS device batch settlement | [View Documentation](/en/notes/api/services/InPersonPayments/gmc/settlement/) |

### Interface Usage Instructions

#### Heartbeat Detection (HEARTBEAT)

- Recommend sending heartbeat packet every **30 seconds**
- Continuous 3 no-response can determine device offline
- `bizContent` field can be empty

#### Pay Query (PAY_QUERY)

- Used to query payment transaction status and details
- Supports querying by `merchantTransactionId` or `transactionId`, choose one of the two
- Returns transaction amount, status, time and card payment information details

#### Refund Query (REFUND_QUERY)

- Used to query refund transaction status and details
- Supports querying by `merchantRefundId` or `transactionRefundId`, choose one of the two
- Returns refund amount, status, time and card payment information details

#### Transaction Cancel (TRANSACTION_CANCEL)

- Used to cancel transactions in progress
- Requires `merchantTransactionId` merchant transaction ID
- Only effective for transactions in specific states

#### Reprint (REPRINT)

- Used to reprint previous transaction receipt
- `bizContent` field can be empty, defaults to print last transaction
- If specifying transaction, pass transaction ID in `bizContent`

#### Settlement (CALCULATE)

- Used to trigger POS device batch settlement, usually executed at end of day
- `bizContent` field can be empty
- After settlement completion, POS device will print settlement voucher