ECR via RS232 (Transit)
1. Communication Interaction Protocol Data Format
When communicating via serial ports, communication must be adhere to protocol data format defined below. Failure to do so will result in the device being unable to recognize the data
| Start symbol (1Byte) | CMD (2Bytes) | Data Size (2Bytes) | Type (1Byte) | Header CRC (4Bytes) | Data (n Bytes) | Data CRC (4Bytes) |
|---|---|---|---|---|---|---|
| 0x55 | 0xXXXX | 0xXXXX | 0x02 | 0xXXXXXXXX | 0xXXXXXXXX |
- Start symbol:
Fixed value: 0x55. It occupies one byte. The end bit of an entire instruction is determined by the start byte, along with the data structure and length. - CMD:
Occupies two bytes. The command code is defined in the protocol document. - Data Size:
Occupies two bytes. It represents the length of the data field. - Type:
Fixed value: 0x02. It occupies one byte and specifies the type of the current protocol. - Header CRC:
Occupies four bytes. The Header CRC is calculated based on the start symbol, CMD, Data Size, and Type. - Data:
The data field, which occupies n bytes. The content of the data field is defined in the protocol document. - Data CRC:
Occupies four bytes. The Data CRC is calculated from the data field.
2 Data and Flow
2.1 Generate Serial Port Data
The CMD command for functional interface communication is consistently set to 0x0006 and remains static.
// 1. Obtain the JSON data object
const deviceInfoRequestBodyJson = {
"version": "2.0",
"action": "DeviceInfo",
"data": "TviXv23Ee/P/LsVJ3LuhUNlqYtFcQLF3wKeMiPn2p50Z9aaquqJ/LCo5hHEMhvLsOGjzB/nsOvqe2Ebm78X4chufwVH5uhH1pvokt3mkFqZUEnaUKrYvfUYF8kc72VTAdXjG9np2MkRU2yESBVfg2pJQ4RhmgtT8+W72bnPyN/Z6gpV63Ynk4GRqjJ2mgrLP"
};
// Convert JSON data to String
const deviceInfoRequestBodyString = '{"version":"2.0","action":"DeviceInfo","data":"TviXv23Ee/P/LsVJ3LuhUNlqYtFcQLF3wKeMiPn2p50Z9aaquqJ/LCo5hHEMhvLsOGjzB/nsOvqe2Ebm78X4chufwVH5uhH1pvokt3mkFqZUEnaUKrYvfUYF8kc72VTAdXjG9np2MkRU2yESBVfg2pJQ4RhmgtT8+W72bnPyN/Z6gpV63Ynk4GRqjJ2mgrLP"}';
// 2. Convert String data to Hex
const deviceInfoRequestBodyHex = "7B 22 76 65 72 73 69 6F 6E 22 3A 22 32 2E 30 22 2C 22 61 63 74 69 6F 6E 22 3A 22 44 65 76 69 63 65 49 6E 66 6F 22 2C 22 64 61 74 61 22 3A 22 54 76 69 58 76 32 33 45 65 2F 50 2F 4C 73 56 4A 33 4C 75 68 55 4E 6C 71 59 74 46 63 51 4C 46 33 77 4B 65 4D 69 50 6E 32 70 35 30 5A 39 61 61 71 75 71 4A 2F 4C 43 6F 35 68 48 45 4D 68 76 4C 73 4F 47 6A 7A 42 2F 6E 73 4F 76 71 65 32 45 62 6D 37 38 58 34 63 68 75 66 77 56 48 35 75 68 48 31 70 76 6F 6B 74 33 6D 6B 46 71 5A 55 45 6E 61 55 4B 72 59 76 66 55 59 46 38 6B 63 37 32 56 54 41 64 58 6A 47 39 6E 70 32 4D 6B 52 55 32 79 45 53 42 56 66 67 32 70 4A 51 34 52 68 6D 67 74 54 38 2B 57 37 32 62 6E 50 79 4E 2F 5A 36 67 70 56 36 33 59 6E 6B 34 47 52 71 6A 4A 32 6D 67 72 4C 50 22 7D";
// 3. Header Section
const headerHex = "55 00 06 00 F1 02"
// 4. CRC of the Header
const headerCRC = "2B 43 D6 EB";
// 5. CRC of the data
const dataCRC = "B7 80 AC B6";
// 6. The entire data finally transmitted through the serial port
const data = "55 00 06 00 F1 02 2B 43 D6 EB 7B 22 76 65 72 73 69 6F 6E 22 3A 22 32 2E 30 22 2C 22 61 63 74 69 6F 6E 22 3A 22 44 65 76 69 63 65 49 6E 66 6F 22 2C 22 64 61 74 61 22 3A 22 54 76 69 58 76 32 33 45 65 2F 50 2F 4C 73 56 4A 33 4C 75 68 55 4E 6C 71 59 74 46 63 51 4C 46 33 77 4B 65 4D 69 50 6E 32 70 35 30 5A 39 61 61 71 75 71 4A 2F 4C 43 6F 35 68 48 45 4D 68 76 4C 73 4F 47 6A 7A 42 2F 6E 73 4F 76 71 65 32 45 62 6D 37 38 58 34 63 68 75 66 77 56 48 35 75 68 48 31 70 76 6F 6B 74 33 6D 6B 46 71 5A 55 45 6E 61 55 4B 72 59 76 66 55 59 46 38 6B 63 37 32 56 54 41 64 58 6A 47 39 6E 70 32 4D 6B 52 55 32 79 45 53 42 56 66 67 32 70 4A 51 34 52 68 6D 67 74 54 38 2B 57 37 32 62 6E 50 79 4E 2F 5A 36 67 70 56 36 33 59 6E 6B 34 47 52 71 6A 4A 32 6D 67 72 4C 50 22 7D B7 80 AC B6";
2.2 Scan and Sale flow
- When the third-party terminal is ready, send the Scan interface to the wonder terminal.
- Wait for passengers to swipe their cards;
- After a passenger swipes their card, the wonder terminal will respond with a Scan interface to a third-party terminal.
- The third-party terminal confirms the information and initiates a Sale again for order collection.
a. Scan and sale for transit
b. Sale directly for transit
3. Interface Protocol
3.1 Pair
Please refer to ECR Interface Protocol - 3.1 Pair
3.2 Ack
Please refer to ECR Interface Protocol - 3.2 Ack
3.3 Device Info
Please refer to ECR Interface Protocol - 3.3 Device Info
3.4 Scan
- Action: Scan
- Pin Code: pinCode2
Request "data.body" structure
| Variable | Type | Required | Description |
|---|---|---|---|
| referenceID | String | Y | Reference ID: Every time a transaction request is initiated, it is crucial to ensure the uniqueness of this ID. Failure to do so will render any subsequent operations on the transaction invalid. |
| customerOrderID | String | N | The order ID of the customer's transaction |
| paymentMethod | enum | N | Payment methods: -credit_card, -fps, -octopus. -consumer_presented_qr_code, -all, If the payment method is transmitted, it will directly redirect to the target page |
| restrictedPaymentMethods | Array | N | Payment Methods |
| currency | String | Y | Example: HKD / USD / RMB |
| amount | String | Y | Sale amount |
| timeout | Number | N | The timeout in seconds. The default is 0, indicating that it will never time out |
Example:
/*
Pin Code: pinCode2 (OvSdpyD2FoUNR5rNyte41QqZzR1Y4DVN)
Encrypt the original data:
{
"header": {
"requestID": "5debf769-49d7-4c9b-b6f4-8a9d90e1a874",
"clientDeviceSN": "126498561093",
"timestamp": "2025-11-12T10:11:04+00:00"
},
"body": {
"referenceID": "f8b13b22-16ca-4a87-95a4-df4bebf09ee1",
"customerOrderID": "e246c1cc-02f6-4ac5-b7fb-066cb2b2f5b1",
"currency": "HKD",
"amount": "10.20",
"timeout": 0
}
}
*/
{
"version": "2.0",
"action": "Scan",
"data": "AQKChJaHhNJU8cR7Yql6BdQqz2nt4CfnLMwLHdqotTH/Phn/JlDnF8cQhJwQOly/GvyB5DiULj7IwqRqkINVkqjSM75g8plKBkbvEzjI+3pEc4kyRK3+LoKnCgjq6JyJDCdHxeUFqk/zJLe0HuvycHNOR0NreBJNYcMtRGfax4Z2PQcP8X2VdPdNCW0vN9E+LIldAUq+tjZ2NfFgscK9KPpPKkYj8UYn0HxYCCiqbpgAImx9SHbFv7QuSVFp/MEeDG/hN6MtGFgtG7ON5o/zQVtWCnekK1MYQxmBwFnh9iHkl1XyVgbjjKAdhMRkjmgrKwd2A0hl+TuqBaA/cyhuA4V1sjoBiKC0TA48VWSdtUQBqitXLQ07gbBzd1Drlan0yPwCraXtdduHBPzTlBEEhg=="
}
Response "data.body" structure
| Variable | Type | Required | Description |
|---|---|---|---|
| status | String | Y | Response status: Success / Failed |
| errorCode | String | N | |
| errorMessage | String | N | |
| customerOrderID | String | N | The order ID of the customer's transaction |
| currency | String | Y | Example: HKD / USD / RMB |
| amount | String | Y | Sale amount |
| consumer_identify_hash | String | Y | |
| acquirer_type | String | Y | Acquirer type |
| en_payment_data | String | Y | |
| balance | String | N | Balance amount |
| balance_currency | String | N | Balance currency |
3.5 Sale
- Action: Sale
- Pin Code: pinCode2
Request "data.body" structure
| Variable | Type | Required | Description |
|---|---|---|---|
| referenceID | String | Y | Reference ID, It should be consistent with the referenceID in the Scan interface |
| currency | String | Y | Example: HKD / USD / RMB |
| amount | String | Y | Sale amount |
| timeout | Number | N | The timeout in seconds. The default is 0, indicating that it will never time out |
Example:
/*
Pin Code: pinCode2 (OvSdpyD2FoUNR5rNyte41QqZzR1Y4DVN)
Encrypt the original data:
{
"header": {
"requestID": "5debf769-49d7-4c9b-b6f4-8a9d90e1a874",
"clientDeviceSN": "126498561093",
"timestamp": "2025-11-12T10:11:04+00:00"
},
"body": {
"referenceID": "f8b13b22-16ca-4a87-95a4-df4bebf09ee1",
"currency": "HKD",
"amount": "10.20",
"timeout": 0
}
}
*/
{
"version": "2.0",
"action": "Sale",
"data": "AQKChJaHhNJU8cR7Yql6BdQqz2nt4CfnLMwLHdqotTH/Phn/JlDnF8cQhJwQOly/GvyB5DiULj7IwqRqkINVkqjSM75g8plKBkbvEzjI+3pEc4kyRK3+LoKnCgjq6JyJDCdHxeUFqk/zJLe0HuvycHNOR0NreBJNYcMtRGfax4Z2PQcP8X2VdPdNCW0vN9E+LIldAUq+tjZ2NfFgscK9KPpPKkYj8UYn0HxYCCiqbpgAImx9SHbFv7QuSVFp/MEe5JveqDo4DqN+gR4n3iHx32R0g5KHKYagjDLMhwaPsrtaXjFUj+P8VE8BPA6aevTA0zREPsU3P/cLqutFSd2eFw=="
}
Response "data.body" structure
| Variable | Type | Required | Description |
|---|---|---|---|
| status | String | Y | Response status: Success / Failed |
| errorCode | String | N | |
| errorMessage | String | N | |
| currency | String | Y | Example: HKD / USD / RMB |
| amount | String | Y | Sale amount |
| balance | String | N | Balance amount |
| balance_currency | String | N | Balance currency |
3.6 Sale Directly
- Action: SaleDirectly
- Pin Code: pinCode2
Request "data.body" structure
| Variable | Type | Required | Description |
|---|---|---|---|
| referenceID | String | Y | Reference ID: Every time a transaction request is initiated, it is crucial to ensure the uniqueness of this ID. Failure to do so will render any subsequent operations on the transaction invalid. |
| qrCode | String | Y | The QR code string |
| currency | String | Y | Example: HKD / USD / RMB |
| amount | String | Y | Sale amount |
| timeout | Number | N | The timeout in seconds. The default is 0, indicating that it will never time out |
Example:
/*
Pin Code: pinCode2 (OvSdpyD2FoUNR5rNyte41QqZzR1Y4DVN)
Encrypt the original data:
{
"header": {
"requestID": "5debf769-49d7-4c9b-b6f4-8a9d90e1a874",
"clientDeviceSN": "126498561093",
"timestamp": "2025-11-12T10:11:04+00:00"
},
"body": {
"referenceID": "f8b13b22-16ca-4a87-95a4-df4bebf09ee1",
"qrCode": "22349671249672146346",
"currency": "HKD",
"amount": "10.20",
"timeout": 120
}
}
*/
{
"version": "2.0",
"action": "SaleDirectly",
"data": "AQKChJaHhNJU8cR7Yql6BdQqz2nt4CfnLMwLHdqotTH/Phn/JlDnF8cQhJwQOly/GvyB5DiULj7IwqRqkINVkqjSM75g8plKBkbvEzjI+3pEc4kyRK3+LoKnCgjq6JyJDCdHxeUFqk/zJLe0HuvycHNOR0NreBJNYcMtRGfax4Z2PQcP8X2VdPdNCW0vN9E+LIldAUq+tjZ2NfFgscK9KPpPKkYj8UYn0HxYCCiqbpgAImx9SHbFv7QuSVFp/MEe0LRDKSaYswb1AC7dLamtOSBq4gW2HS0s7j+6WpyEw6V8UqzaOYk7VCkS5niYUoDa0my3u3OB2AiY+grtsSlsPkw1D9tdOSBXhbLV85YNbi+KgsHuOMatVJrSOcszfGcy"
}
Response "data.body" structure
| Variable | Type | Required | Description |
|---|---|---|---|
| status | String | Y | Response status: Success / Failed |
| errorCode | String | N | |
| errorMessage | String | N | |
| currency | String | Y | Example: HKD / USD / RMB |
| amount | String | Y | Sale amount |
| consumer_identify_hash | String | Y | |
| acquirer_type | String | Y | Acquirer type |
3.7 Inquiry Unupload
- Action: InquiryUnupload
- Pin Code: pinCode2
Request "data.body" structure
| Variable | Type | Required | Description |
|---|---|---|---|
Example:
/*
Pin Code: pinCode2 (OvSdpyD2FoUNR5rNyte41QqZzR1Y4DVN)
Encrypt the original data:
{
"header": {
"requestID": "5debf769-49d7-4c9b-b6f4-8a9d90e1a874",
"clientDeviceSN": "126498561093",
"timestamp": "2025-11-12T10:11:04+00:00"
},
"body": {}
}
*/
{
"version": "2.0",
"action": "InquiryUnupload",
"data": "AQKChJaHhNJU8cR7Yql6BdQqz2nt4CfnLMwLHdqotTH/Phn/JlDnF8cQhJwQOly/GvyB5DiULj7IwqRqkINVkqjSM75g8plKBkbvEzjI+3pEc4kyRK3+LoKnCgjq6JyJDCdHxeUFqk/zJLe0HuvycHNOR0NreBJNYcMtRGfax4aTaoajhDtH2JEMcHQhzG/Qyt6YroHyqU0Aee3riHZ42A=="
}
Response "data.body" structure
| Variable | Type | Required | Description |
|---|---|---|---|
| count | Number | Y | The count of unuploaded transactions |
| datetime | String | N | The earliest time when the sale was not uploaded to the server, it is recommended to issue a warning after 4 hours |
Example 1:
When the status is Pending
/*
Pin Code: pinCode2 (OvSdpyD2FoUNR5rNyte41QqZzR1Y4DVN)
Encrypt the original data:
{
"header": {
"responseID": "5debf769-49d7-4c9b-b6f4-8a9d90e1a874",
"serverDeviceSN": "NEXGO-N96-1170270945",
"timestamp": "2025-11-12T10:12:04+00:00"
},
"body": {
"count": 10,
"datetime": "2025-11-11T10:12:04+00:00"
}
}
*/
{
"version": "2.0",
"action": "InquiryUnupload",
"data": "PB+rSP8K81XXavrKxJPcl92xo6mcM41z9ktD03djtpq5XMpTcQsEerDGyEPT6SBJ+mA8TsYwGGvrL7j5TGR06WX6mFyIK3t50Yo2Yvj0bAiTmSWdQDJ7KLJjrEPnDj85FnBdK1HuKrrxATLG8O6KhpxAvy4ULHzqpOTM/8WAcyxZ9FYwwJiqHiJSZi8nN/oWf4DU5DhGblyWh6X+hQSalaUPAiF5ODWTKD/oxdHX5C7Cw342lehTBtpJh0Dy/msG/F0Hfz6fVsA7+ouZPxc/0w=="
}