ECR via RS232 (Retail)
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. 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";
3. Interface Protocol
3.1 Pair
After the customer device acquires the 6-digit pairing code, it uses the "Pair" protocol for pairing. After the Wonder terminal receives a pairing request, it will return a UUID identifier, which will be used by the "Ack" protocol.
Action: Pair
Request "data.body" structure
| Variable | Type | Required | Description |
|---|---|---|---|
| pairUuid | UUID | Y | Pair the uuid identifier |
Example:
/*
Encrypt the original data:
{
"header": {
"requestID": "9c07d8d7-2a43-4a29-9c6d-6b8d8f7d44e5",
"clientDeviceSN": "126498561093",
"timestamp": "2025-11-12T10:11:04+00:00"
},
"body": {
"pairUuid": "3f37e6c0-bf6e-4c00-b1fa-b2bd5e1d6a3b"
}
}
*/
{
"version": "2.0",
"action": "Pair",
"data": "WJq3v/ZX/aMMR45WFqfs9BZ2J93EtSTYQh4JOD17ldQkzXi6ohsjxCdl4mpvAOqhFyWPVuEadUubmRzfACUAQpqledyJhOdtQTMlr4KnZXBJw6g3TOFTeKe1I/DqMiEEG0X9BEelUNS+0+FpaoWN1mVkuKEpt8XMGrHyA+M4XbaMwjQ3fMeoR77FULPvM9MCkw6B3QTGONMml51X8pqXsBYTrcpS5SLFVvdL5e+1CcIuVvliyrV3MDd+cwlSjHNIoaLwDEgu9wDNjGTYe1L8Ww=="
}
Response "data.body" structure
| Variable | Type | Required | Description |
|---|---|---|---|
| pairUuid | UUID | Y | Pair the uuid identifier |
| ackUuid | UUID | Y | Ack the uuid identifier |
Example:
/*
Encrypt the original data:
{
"header": {
"responseID": "9c07d8d7-2a43-4a29-9c6d-6b8d8f7d44e5",
"serverDeviceSN": "NEXGO-N96-1170270945",
"timestamp": "2025-11-12T10:12:04+00:00"
},
"body": {
"pairUuid": "3f37e6c0-bf6e-4c00-b1fa-b2bd5e1d6a3b",
"ackUuid": "4d366618-49cf-4f93-bd23-25388a573b0c"
}
}
*/
{
"version": 2.0,
"action": "Pair",
"data": "G6RaFsGPTiVzAYsUTu/gY1Igjv+4THb1tZ7vwXWP9f1CYRRrNKKuz4Op7ai9xCqKCdBymnO/YAQTB9egq10DIp/mxQ4pG1dGyL+Erkd91G4xYJd9S7iXNqnCwEn2wOhMIn3sP0H6vgTzoGX9ZOi59pLhuGqYTbHBPvDIkavEIweWWVQjEUdQn7HG0ymqxq4O36giOlh5NldSPwH5LjbnOamEm+Y41jIW/dRexnd7hhKkF/TrZg2lDYKOry9NflNzoMPHiB2/7YgVVmgVfBysW9dqqNRiJXxYLOD6UGoJlQqsICeiidKm6SYL4dkKHYniFEnZ0a5KGdxZs7viSahmiA=="
}
3.2 Ack
After the client terminal initiates the pairing, it will receive an "ackUuid" identifier. This protocol needs to carry the "ackUuid" identifier to confirm that the pairing has been successful.
Action: Ack
Request "data.body" structure
| Variable | Type | Required | Description |
|---|---|---|---|
| ackUuid | UUID | Y | The Wonder device will use this UUID to confirm whether the pairing was successful |
Example:
/*
Encrypt the original data:
{
"header": {
"requestID": "73a95cfe-b0f1-42b3-82d1-5a640f61e359",
"clientDeviceSN": "126498561093",
"timestamp": "2025-11-12T10:11:04+00:00"
},
"body": {
"ackUuid": "4d366618-49cf-4f93-bd23-25388a573b0c"
}
}
*/
{
"version": "2.0",
"action": "Ack",
"data": "WJq3v/ZX/aMMR45WFqfs9P9yP8iBOv/+QIHiUObOM9A2N/r4Erh3+K6la2u/I/9AqkSwid8LlMtWMJzhA1nPETvrU2MjYqJbiIZvJAYofdE1ImF4sJnJWojCxCIghSCy/3F0gkheUyv13y0w7ZpUnY2KjqsaxdZ5Rofnw44PBZFberO+UQ96d/x4s6IyAgqb8x2Gxfr4ypg5Jhb1U643mMJantOuY0qg73h7JdmoJLxp0OhowhVe8/hpcX+MwKFcnEMkrcWoE5vZhM7O0Utypw=="
}
Response "data.body" structure
| Variable | Type | Required | Description |
|---|---|---|---|
| deviceStatus | String | Y | Payment device transaction status: Free / Busy Free: The current device is idle and available for new transactions; Busy: The current device is occupied with an ongoing transaction and is not available for other transactions at the moment. |
| networkStatus | String | Y | The current network connection status of the payment device: Connected / Disconnected |
| softwareVersion | String | Y | The software version of the payment device |
| businessID | String | Y | The response ID in the response Header is derived from the request ID in the request header. |
Example:
/*
Encrypt the original data:
{
"header": {
"responseID": "73a95cfe-b0f1-42b3-82d1-5a640f61e359",
"serverDeviceSN": "NEXGO-N96-1170270945",
"timestamp": "2025-11-12T10:12:04+00:00"
},
"body": {
"deviceStatus": "Free",
"networkStatus": "Connected",
"softwareVersion": "1.0.0(188)",
"businessID": "ff467f02-5b69-45f3-81aa-bffcca55fe8f"
}
}
*/
{
"version": 2.0,
"action": "Ack",
"data": "G6RaFsGPTiVzAYsUTu/gYy/OriQOOARMWzAfv9FZ3+u7+iwmMj/cxrnRahw2KCO8/q6XLMAK2jV2pK17hmx3vNCwrO7dcoqx8faj+UipeweNnfY9HYZH06Bd5yuu/BYAEOBXkeoJLbfAAgj0KDOHvwEHRryK0zqW6jSQh6nOsqQIr2BhiwxLDR3IZFYVZk4T57Qkzqa/U3xsADyrw0Ou4JXlrWdshE5IAtxrCHnZzj7t3jlmlNRF2DoHbaRCqnYnI/BMNRWUJOnRbAvQqxNWbpZznywFNWR/uazYyU95lNhXJMRWol/9r0dJUa5xf/iQEybihz4cO8tJkalp7oU2w6I3mrnaCHx3qySC/pnC4+rg4AUw065uSxHee/aEJFNE"
}
3.3 Device Info
Action: DeviceInfo
Request "data.body" structure
This request has no body
Example:
/*
Encrypt the original data:
{
"header": {
"requestID": "2c7f32e1-b9e4-4b34-96cc-15c51289f69b",
"clientDeviceSN": "126498561093",
"timestamp": "2025-11-12T10:11:04+00:00"
}
}
*/
{
"version": "2.0",
"action": "DeviceInfo",
"data": "WJq3v/ZX/aMMR45WFqfs9EUXMXYXYYzSxo7SkNX80Y2hL4HhG471eXFw81ikn0cFWH05k1cMA4OcJtxDhh3OCKLA85WwmAHWp3uVBKq0nqTVS+xcPlDIQg8W8taTrfku6d8KWi4HinX80/Yksx5meN1klIjlStY4I8GBA/ElO3t/MprwU33jG68xDXixNalB"
}
Response "data.body" structure
| Variable | Type | Required | Description |
|---|---|---|---|
| deviceStatus | String | Y | Payment device transaction status: Free / Busy Free: The current device is idle and available for new transactions; Busy: The current device is occupied with an ongoing transaction and is not available for other transactions at the moment. |
| networkStatus | String | Y | The current network connection status of the payment device: Connected / Disconnected |
| softwareVersion | String | Y | The software version of the payment device |
| businessID | String | Y | The response ID in the response Header is derived from the request ID in the request header. |
Example:
/*
Encrypt the original data:
{
"header": {
"responseID": "2c7f32e1-b9e4-4b34-96cc-15c51289f69b",
"serverDeviceSN": "NEXGO-N96-1170270945",
"timestamp": "2025-11-12T10:12:04+00:00"
},
"body": {
"deviceStatus": "Free",
"networkStatus": "Connected",
"softwareVersion": "1.0.0(188)",
"businessID": "ff467f02-5b69-45f3-81aa-bffcca55fe8f"
}
}
*/
{
"version": "2.0",
"action": "DeviceInfo",
"data": "G6RaFsGPTiVzAYsUTu/gY/wIUdGoYnFoWxIXOwjoBx5bJelgkrMqYDKxicyD0ApBnxqcvr8+kcqCyI2a5oeFm4duqrKwjQdFVW29ggdvuzyMUoqmxJyM3KAkyXTWV1dSbMrDJknalfufODYpuFgV0BfxBdPVvh2EfxlegKza9DtskKZOO/uSLh9GGoMGMHZIC4HBFv6iFSE0Rp4AmhZx012RmkDHfy7lvdvbMaXe690Lytal4srXom0MQ3tpAcJ7FieiFqlS79GopPlAX2o3ZlLKOBsZwhylMvE0SgPbzu5VZXklWqTVBYotFy+GAlzA2LC9Z6MT68hdHI4RkWtlO1HPEnPuUg/VHNxoI0l1y6PWEQaOEb+E+INJmnN/sa4g"
}
3.4 Sale
Action: Sale
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 |
| currency | String | Y | Example: HKD / USD / RMB |
| amount | String | Y | Sale amount |
Example:
/*
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"
}
}
*/
{
"version": "2.0",
"action": "Sale",
"data": "WJq3v/ZX/aMMR45WFqfs9Pf6x7dtrIlEwp8hFIRh5wM2LMFIbUxxGepCCp67NrcI212O5Sk1EMIFmQOI/+/l1X0Bm2tCLXV4VlqvexdPTqViAVWFwnuQMnifC9TXXcxgA0R3WTp3Vgi4yBqsBwDFJMpqdPW/pVBtiRQHwqLzhW6KS/UaNjUbjh20MVI83xJjorUrF1xtdyMerTOrWyd0cysiDWzIMc8kIsdb0Cmj8GBMM7C/S1UVgkY8P4ybJj62cIaxUTF1si7bB5QLjSZ200irnGSMEtGhHpbPLKO1NElG4criVkekYnE4tGT91fbBsJ6CafW7jlrnKfTKVhahoooscXjwsMpZTAYrA2EVHJEE/Ov6RuVNcBTzfUXjx9GgHxJpbI0J5hgqoDXR9QpT7g=="
}
Response "data.body" structure
| Variable | Type | Required | Description |
|---|---|---|---|
| status | String | Y | Response status: Success / Failed / Pending |
| errorCode | String | Y | |
| errorMessage | String | Y | |
| customerOrderID | String | N | The order ID of the customer's transaction |
| currency | String | N | Example: HKD / USD / RMB |
| amount | String | N | Sale amount |
| paymentMethod | String | N | Payment method |
| paymentEntryType | String | N | Payment entry type, Example: contactless |
| rrn | String | N | Receiver Reference Number |
| brn | String | N | Bindo Reference Number |
| transactionStatus | String | N | Transaction Status: Success / Failed / Pending / Voided |
| transactionTime | Datetime | N | Transaction Time |
| creditCard | Object | N | |
| creditCard.panPrefix6Digits | String | Y | First 6 digits of the credit card number |
| creditCard.panLast4Digits | String | Y | Last 4 digits of the credit card number |
| creditCard.panHash | String | Y | SHA512 |
| creditCard.panToken | String | Y |
Example 1:
When the status is Pending
/*
Encrypt the original data:
{
"header": {
"responseID": "5debf769-49d7-4c9b-b6f4-8a9d90e1a874",
"serverDeviceSN": "NEXGO-N96-1170270945",
"timestamp": "2025-11-12T10:12:04+00:00"
},
"body": {
"status": "Pending",
"errorCode": "",
"errorMessage": ""
}
}
*/
{
"version": "2.0",
"action": "Sale",
"data": "G6RaFsGPTiVzAYsUTu/gYxFoWAK/iASzF9SHjxbqRD0MMn2iTlk2EFxkPtQGqwngvLUivaenLxsUaFlYTI675dIeqAiXwTPEbr0wLFLj087eYP8lQnXuPcXd2amDzp27Km6rLhJsn9xP43ZdMLPbaiFpHgoSRzt09G5voOBxpMeeQ9L/03i4BqRMKa9D6qG6/RgZJJJP2epBbjhdmtRdD17Q+kWSgKvEEOCHB+kAXYoDL3eXK5VfjKDY1udlAGJohH8JdyllwIULEi+QyIK1Kw=="
}
Example 2:
When the status is Failed
/*
Encrypt the original data:
{
"header": {
"responseID": "5debf769-49d7-4c9b-b6f4-8a9d90e1a874",
"serverDeviceSN": "NEXGO-N96-1170270945",
"timestamp": "2025-11-12T10:12:04+00:00"
},
"body": {
"status": "Failed",
"errorCode": "5xxxx",
"errorMessage": "The equipment is being traded"
}
}
*/
{
"version": "2.0",
"action": "Sale",
"data": "G6RaFsGPTiVzAYsUTu/gYxFoWAK/iASzF9SHjxbqRD0MMn2iTlk2EFxkPtQGqwngvLUivaenLxsUaFlYTI675dIeqAiXwTPEbr0wLFLj087eYP8lQnXuPcXd2amDzp27Km6rLhJsn9xP43ZdMLPbaiFpHgoSRzt09G5voOBxpMeeQ9L/03i4BqRMKa9D6qG6/RgZJJJP2epBbjhdmtRdD1c3o/Y+4kNACYdO6mEG3Lac/Hg8IRTCMToHPj1o3DdXtA3o3CYsD3tJ2yaNAYZ+gV/PKAZgF40xHQhKUJi/FZyHjKvDwd0CEAWOqXMFIRZB"
}
Example 3:
When the status is Success
/*
Encrypt the original data:
{
"header": {
"responseID": "5debf769-49d7-4c9b-b6f4-8a9d90e1a874",
"serverDeviceSN": "NEXGO-N96-1170270945",
"timestamp": "2025-11-12T10:12:04+00:00"
},
"body": {
"status": "Success",
"errorCode": "",
"errorMessage": "",
"customerOrderID": "e246c1cc-02f6-4ac5-b7fb-066cb2b2f5b1",
"currency": "HKD",
"amount": "10.20",
"paymentMethod": "visa",
"paymentEntryType": "contactless",
"rrn": "3263492852830699521",
"brn": "3263492852495159296",
"transactionStatus": "Success",
"transactionTime": "2023-06-30T09:08:52+00:00",
"creditCard": {
"panPrefix6Digits": "555555",
"panLast4Digits": "1234",
"panHash": "xxxxxxx",
"panToken": ""
}
}
}
*/
{
"version": "2.0",
"action": "Sale",
"data": "G6RaFsGPTiVzAYsUTu/gYxFoWAK/iASzF9SHjxbqRD0MMn2iTlk2EFxkPtQGqwngvLUivaenLxsUaFlYTI675dIeqAiXwTPEbr0wLFLj087eYP8lQnXuPcXd2amDzp27Km6rLhJsn9xP43ZdMLPbaiFpHgoSRzt09G5voOBxpMeeQ9L/03i4BqRMKa9D6qG6/RgZJJJP2epBbjhdmtRdD55kdo+uYoEHqQUkCE82SpewPj0to+rL4ZjLQ33P8x/CaF/0DAA0SHUW2rXoRss+5yfOc/DhByUeCG33O3MmoRdwIRrsHU91R3LTE5SAnO6dMDglCqIT1WfOQNboikIeYF/C7lhiA9IOJjHO4ObHBo1+XT2WS4Zi53/dYrAnKcTa3d+EHW/B8u4IfzdEojAazehwO8ghEZsINwjVdlYZ0zwMMklC4OCarj71b7uTS4vzWZFqunEI4Nj4dI0ocB0wDLZcQs+GtIoqXLVE+vFEFRCd04EeGwcdNiks0fRMqCtrpntv9K7wJfHNH2AeVxqAE1ub8mHj23bWFQB08W7pNc/f8KudM4XMRtYgEg2RiOORw6F4B2GjG60N2Ei5ZlU5cme8CE9S/xoMawWWHw3vdOJL/pCpcg2ESSYDYcrKeaCggBRpYYY3UmG+2hnJzZyWaRuBx2o4Qtu0GFJCU5mnCzTHv+P8ErMAZ4e9Jv/1w3aqTpTQg6jSkNrkzuN89GOSWO+xzVfrW0aFUy7hhMi2k9SyvFRv4NNDA52t8aroDKnozljjW1ELWvByqLsP1FAp/g=="
}
3.5 Abort
Action: Abort
Request "data.body" structure
This request has no body
Example:
/*
Encrypt the original data:
{
"header": {
"requestID": "c5bf3cbe-a146-4f8c-bb8e-209c1e7b8437",
"clientDeviceSN": "126498561093",
"timestamp": "2025-11-12T10:11:04+00:00"
}
}
*/
{
"version": 2.0,
"action": "Abort",
"data": "WJq3v/ZX/aMMR45WFqfs9NfmNINDhS6jMfjiae1x0uuLyfhJ5aQziTk3o4u/gJcw2J+Nzsme4+TivtS//xsb8lN+GbgYDj38GnnQcuI1OuyVAwHS5eq/n7EBNDnz69b2reqf9bprzNq6L5Nnuu/xYV0hi552oKI4lOh4T5fLtDv+ul7gHdbJ8BsOEbQP82zE"
}
Response "data.body" structure
| Variable | Type | Required | Description |
|---|---|---|---|
| status | String | Y | Response status: Success / Failed / Pending |
| errorCode | String | Y | |
| errorMessage | String | Y |
Example:
/*
Encrypt the original data:
{
"header": {
"responseID": "c5bf3cbe-a146-4f8c-bb8e-209c1e7b8437",
"serverDeviceSN": "NEXGO-N96-1170270945",
"timestamp": "2025-11-12T10:12:04+00:00"
},
"body": {
"status": "Success",
"errorCode": "",
"errorMessage": ""
}
}
*/
{
"version": 2.0,
"action": "Abort",
"data": "G6RaFsGPTiVzAYsUTu/gYwWEaHKVOBFIR6cifm5aC/lOPZYHWq8mADm+tCmHlySZnc21ZR7sXvjMJtojcdCnMm1OM9r4gexIaa5zzfv7slCEQERE44uLV07ZvG1rn8QJ/OG5nY2KIlINAz36Y+pSVFXnh35plvhbX1pGANwv0jV2cUpoe9jZpVInYkt3NebKjIPHEMrlM+/weHgd/5BFmWZ6YJ18h5xEzacK1YQH/Z4QHMb0KKR6h8vDg87yc51dMhrbAgz+YOJgKl90JPgGXg=="
}
3.6 Void
Action: Void
Request "data.body" structure
| Variable | Type | Required | Description |
|---|---|---|---|
| orgReferenceID | String | Y | The reference ID that was carried during the transaction made at that time. |
Example:
/*
Encrypt the original data:
{
"header": {
"requestID": "8e2c77fb-ff49-4c49-82f5-ae741cb7d3d9",
"clientDeviceSN": "126498561093",
"timestamp": "2025-11-12T10:11:04+00:00"
},
"body": {
"orgReferenceID": "f8b13b22-16ca-4a87-95a4-df4bebf09ee1"
}
}
*/
{
"version": 2.0,
"action": "Void",
"data": "WJq3v/ZX/aMMR45WFqfs9Md7p/WA11XarluvtqfrO40ET05RPITLV2SXN85mPeMAYDa6g1fpCkQ9aVLejgbHJ93EmugB/POc28afZn1J2SD5FqTOlfKxBFeeL29NNXUeecEu4bvjXjgVScrJVCz+JecdQhXBy9iKj95BT/Vl/7R1xhKT1wAe7/sps4D+xgeTkP6YTIEqVAU5wkd7CS8EG8TYfJsmgwZW1P8yXwda6492lWvlMUIf3LXDGItMGbx+LYcuUcdZkGFRGDIFnoLyCA=="
}
Response "data.body" structure
| Variable | Type | Required | Description |
|---|---|---|---|
| status | String | Y | Response status: Success / Failed / Pending |
| errorCode | String | Y | |
| errorMessage | String | Y |
Example:
/*
Encrypt the original data:
{
"header": {
"responseID": "8e2c77fb-ff49-4c49-82f5-ae741cb7d3d9",
"serverDeviceSN": "NEXGO-N96-1170270945",
"timestamp": "2025-11-12T10:12:04+00:00"
},
"body": {
"status": "Success",
"errorCode": "",
"errorMessage": ""
}
}
*/
{
"version": 2.0,
"action": "Void",
"data": "G6RaFsGPTiVzAYsUTu/gY0kKWwxCZzx9XNP8TZz61iQ5xwi/UXLUU0NsfRm5kwstCH+RyvZo8WQAJ5J1HfNq2zKCeKqvwAn79DEFr0NuH+IECMmsWW9UeUMSlLo3SkNZqRwstqTOkwE0r7fDfD6+KjPlNxW6impHrf54iAWdGFWOYEkmXhb79lG6zPmtsfzW2JBYcnZUxmH/DERUyD6rCke2fH7Q7P6c7Uug+Fl9RuxjxpQnBjBoPReIvkonzyMPzDkqs0cEnZuZu+PQT2d+sA=="
}
3.7 Refund
Action: Refund
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. |
| orgReferenceID | String | Y | The reference ID that was carried during the transaction made at that time. |
| currency | String | Y | Example: HKD / USD / RMB |
| amount | String | Y | preAuth amount |
Example:
/*
Encrypt the original data:
{
"header": {
"requestID": "0f7d24de-76fc-46f8-861b-2d0d31a2dd9e",
"clientDeviceSN": "126498561093",
"timestamp": "2025-11-12T10:11:04+00:00"
},
"body": {
"referenceID": "97cc8c76-65e0-4bd2-9e16-9b9e09f65c42",
"orgReferenceID": "4b02c099-4dc9-4b30-bd2c-27bf3223df6b",
"currency": "HKD",
"amount": "10.20"
}
}
*/
{
"version": 2.0,
"action": "Refund",
"data": "WJq3v/ZX/aMMR45WFqfs9GzNHvhJRs83Ew46fDlVcvpHw1zUFJYPQ9XhptGTILDTRdnX2gFVBpO/eaq+htMhS2565R9J9zgryR1ZBCxWXmA5DdEjoOdyZpQOgfVozTxeRXGvYeOdI+Cv+xeOks/Izfgs83KTHwCI33HLuYZEXYGbqRZiZZ8SqplhqKKKe6ZmN/qqc5mofqUaDrmKNzSF1nrvjF24bBJKpEJdmXB6dsom1jAE6oPB1VUmHIHyt0OG68+oQbFDjfF+kZW6pTgdWOmhVZ7tzx74dcxRsKKLuTKNM/DkeB2KnSA9IK6ZiytqJ35IrWsgMxK/9/4PbwyHmwrJif5YhfCtdD4FpgmhmMIQhnMKQM0wLERJZnyXSVNV"
}
Response "data.body" structure
| Variable | Type | Required | Description |
|---|---|---|---|
| status | String | Y | Response status: Success / Failed / Pending |
| errorCode | String | Y | |
| errorMessage | String | Y |
Example:
/*
Encrypt the original data:
{
"header": {
"responseID": "0f7d24de-76fc-46f8-861b-2d0d31a2dd9e",
"serverDeviceSN": "NEXGO-N96-1170270945",
"timestamp": "2025-11-12T10:12:04+00:00"
},
"body": {
"status": "Success",
"errorCode": "",
"errorMessage": ""
}
}
*/
{
"version": 2.0,
"action": "Refund",
"data": "G6RaFsGPTiVzAYsUTu/gY9HNXCyk05Sa1B0RQLuXZ8ElUp/OsCdaQq70JroARxmq5PtZqtls46kxQKI/cL3McoQ8QD0fkAaFNXEjgkOtKP1h5lDIRcFkxft8HYwC38WjqAunykK8hrIHhdxA7naqcUshYaOoKUFO6zOxrkHBW6YoKdOSLZgqPY7KHNT9EOOyfPaScSWzfR5G84bZ9CfSoe4kBsWnbqvyIbB09qk7LhlGMosoTmZ4DEThkexDC/1DR8atATgMc0D8OeKNp0RrYQ=="
}
3.8 Query Transaction Status
Action: TransactionStatus
Request "data.body" structure
| Variable | Type | Required | Description |
|---|---|---|---|
| targetReferenceID | String | Y | The reference ID that was carried during the transaction made at that time. |
Example:
/*
Encrypt the original data:
{
"header": {
"action": "TransactionStatus",
"requestID": "18fd2b62-6f65-40f2-8b94-88ef32f07a3f",
"clientDeviceSN": "126498561093",
"timestamp": "2025-11-12T10:11:04+00:00"
},
"body": {
"targetReferenceID": "f8b13b22-16ca-4a87-95a4-df4bebf09ee1"
}
}
*/
{
"version": 2.0,
"action": "TransactionStatus",
"data": "c0newW5J8LHyihFFZyXity9fW0sMGLKeANTZJpeGvEhkANMem9OjBRCZ48mSU491oYsB1HUvJx2fLaHRlvCtyiIkHknwitHW7Xb/hgCqQaPn/a+BLCnMJ8Xo5QUsNZ5jFOjwHOSACqsXlvR0EqlWOeVMnhplmWRewit5ePvvJWRUoz8BcXD5O8ulhQ7wYWMtVAryS8uOFgGlXClEW25WJnjiw0T6uqRUqUWZ/J6LEdzSFzpg3hBdh9KC7DWTu7g26mzyaEq7KASIs96LBelehGZnFJG0VxUwPbVP9+LEvcZgUPMEzEFiiGBzlzJ99IMr"
}
Response "data.body" structure
| Variable | Type | Required | Description |
|---|---|---|---|
| status | String | Y | Response status: Success / Failed / Pending |
| errorCode | String | Y | |
| errorMessage | String | Y | |
| ... | Any | Y | It is consistent with the returned information of the current query transaction type |
Example:
/*
Encrypt the original data:
{
"header": {
"responseID": "18fd2b62-6f65-40f2-8b94-88ef32f07a3f",
"serverDeviceSN": "NEXGO-N96-1170270945",
"timestamp": "2025-11-12T10:12:04+00:00"
},
"body": {
"status": "Success",
"errorCode": "",
"errorMessage": "",
"customerOrderID": "e246c1cc-02f6-4ac5-b7fb-066cb2b2f5b1",
"currency": "HKD",
"amount": "10.20",
"paymentMethod": "visa",
"paymentEntryType": "contactless",
"rrn": "3263492852830699521",
"brn": "3263492852495159296",
"transactionStatus": "Success",
"transactionTime": "2023-06-30T09:08:52+00:00",
"creditCard": {
"panPrefix6Digits": "555555",
"panLast4Digits": "1234",
"panHash": "xxxxxxx",
"panToken": ""
}
}
}
*/
{
"version": 2.0,
"action": "TransactionStatus",
"data": "G6RaFsGPTiVzAYsUTu/gY9vEIGAj+H+QS8BwEc7oeGrzV3q8VQl6BEkdruH+DJIWiVbSaqdLcYl4rvUlDuTkWb2je1ainccR2dO+cKfJhJTr99Q4/y2DFrni/QiFNzzszUP/LfFbJecLNsOSEAT9xTND1FApr3V/mZV8KAJtcFvIesHtFxFyElJ9knGXZ0f5aGAJ08LiZP23CtQQBTusFSk2QPJ3eEkYBukuUdHj7GCQ9N85v0Og0PeCR3dWhIDIjWF+uSel+EdLGaKDMVoxY0taNQfedt32VkbRCs8yznlcX3nDgO5gI6SAR78ohnXj8TQT4lzdHz185urs2hV43e7exFkaS9q61fejxD7Zfzp06lBiovYO4ElIsOrUt99xudP9zXJmniEBfj++kDUQLMIeyiwQbEqn5QU1sWCzFMVS6w+PBMADHIwMbosXRRgz0ZwUcVHlWUrTnyBMhEKPEZ/zGYpqujeROw0wh3WnMBbTGy8CEAtOFpxl05djkx38yQWPPm7ODF8Sy02OgjBHNuY+2C85O1ObNsCncBOPIFiDE/sv6fjm0MY95mve+CJ8NimBDhf16gPEngso6Y52l2Z6A5NRaoktoBn1xeFHmc4cSOVFnT91jCtzWhDWhJMnuJBJ2R5Zn2Jr/aFhijMgyzDLX/thzTk5H7EQvr4C+3OeZUoM1Eavka/NrGhJLQ1cTSlUmjlJkKO0S1jlUmq0TwSaIKzRwMdBPNMLqlu7v5kUN6fkUTDsbHf6Y+sbeFSRbn1ArXirjbcvv5FPMhMEng=="
}