Skip to main content

Payment for Taximeter

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
  • Pin Code: pinCode1

Request "data.body" structure

VariableTypeRequiredDescription
pairUuidUUIDYPair the uuid identifier
Example:

/*
Pin Code: pinCode1
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": "KhGmDIJZQXsNHrLM1hDB/kjPjlSpmUQVNIrRLEAptCHb+GHiqdZTnfDRWJVBJDzTyLtqDXLJYRR3433sIEm7hBvpI8vZ4WeTIxcp1BUd4GwRjutbUMCQ8vc5GTlu8aWvSoChYWeHXIu5MmWXbfkWe8AMAHLtnjuvrZfV17mTlvX+09hskf5zCcFKKXVq6qA24o4d5crbIoKEmRI0K94YSPo99N9mEdnAVdh5xNxQmzsp1JlKMnxQGIy2K1HuUmabW1JLWID/In4sADJDdRk2069oYrP1PWYUqKKoahtH7GNQqJ0Syux/IykdoXVZ2dmn"
}

Response "data.body" structure

VariableTypeRequiredDescription
pairUuidUUIDYPair the uuid identifier
ackUuidUUIDYAck the uuid identifier
pinCodeStringYIn the test code, it is pinCode2, which is used in the Ack interface and the business interface
Example:

/*
Pin Code: pinCode1
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",
"pinCode": "OvSdpyD2FoUNR5rNyte41QqZzR1Y4DVN"
}
}
*/

{
"version": 2.0,
"action": "Pair",
"data": "N7rbBZmxrGP5kh7vUaGOs1CslAJVsa53OKmEjdkx72ulWIptVPuJNCfz+GCIrt7E66S+nG5uMpNkj7XOtj2IppH/WwUQQMSBVsFc9meSy0+GjOARJ61W9CXxVu2sBMUNWGgzuxd1bhGmXD/GNTHLuuzFZJv0ANIR26tf+MyUs19a/cYxhHba8tgcIYQG/FLEHK7hI2p3hX0ETESxEDDyogVP0a8F050Jua5nIjU/BBfhfC1g0/Iu5q+oSN/caZcZyO6F/a5dF6EXPDbJY0yr8QDsH8nr8mEfaO3HS7gtozcVIylsmbXNftAzlj4Ex1768VeVHXVvfimjUzGy4HsvxiJBAQixAkKR/nQVguyCSWojmOXwDFm5jjjmoXTSvZxsrYuogke4gAlW055leR9fGiHesXoPL1zyzWSR1EeuxtAGZB1V2B9yUKjRhc5GPTWH"
}

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
  • Pin Code: pinCode2

Request "data.body" structure

VariableTypeRequiredDescription
ackUuidUUIDYThe Wonder device will use this UUID to confirm whether the pairing was successful
Example:

/*
Pin Code: pinCode2 (OvSdpyD2FoUNR5rNyte41QqZzR1Y4DVN)
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": "1Rlzdz9YVYhK9cI0tqodWqay2D8t0vs3slnvVn0lW5G2EqFcfQtC/4j7oQ+X/MOvADkbVGVDREB54LxJWK5UtzNVx1+z5R/ydgYryjcUuI4p724nsggY0lIbIBE+6yCDZQE6iXYZYAVAUkdyukNB18WbmqEK0+V+uPt/NWc4H0t5drhK+nz8uu62h4PT/Fxma5/ZcnBbRqjSMe1nUJmlqY0vKmJhhZ17N9M85rgh/JUsMebNMmERR6XDbnuls4bKY4hffSVzNbWHjBWjdfX60KU2r7SBE8HiEKS41FcVDhl2dmVcNybz/+RTSxMsnEvA"
}

Response "data.body" structure

VariableTypeRequiredDescription
deviceStatusStringYPayment 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.
networkStatusStringYThe current network connection status of the payment device: Connected / Disconnected
softwareVersionStringYThe software version of the payment device
businessIDStringYThe response ID in the response Header is derived from the request ID in the request header.
Example:

/*
Pin Code: pinCode2 (OvSdpyD2FoUNR5rNyte41QqZzR1Y4DVN)
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": "thygIk5FDezl1xaeyOFkwduPBRl8PS65YQ5+aa1bLCT6gjIVGbjGsQlvkOl+24To6ztvk3CtJ5Jgeimy93RuW3cGYflth+Eb8A2031pbUa8918aJ08lHhVmbeajnWoaN9iWmExBuqkN4EA76SB6ELELwJQR3z0xlfREuhDyhlhIeBTs5dy+UptkKzIpHzcMB6aPL37qF+TIAW6M4B7hLniTM5RfCmFwQjDRNrj78pwA8teLrvPrGSXceQnbMxlk2BXl1BhVnhTSxVh8iP/KtLi9MxO4YvSfBsrfOkwrFLNIh3SardG0V2QVgGwdfKxmCSIf4GxuDF3bJz8XM8CowAogC0dY5zea4Ms2ifblCI13dD/uMJF3qrS36Xuj+LN7lO3UYWYtNzBy0vYo45PrZ/5Zh4WOeZ5sZk43Ycotj+fk="
}

3.3 Device Info

  • Action: DeviceInfo
  • Pin Code: pinCode2

Request "data.body" structure

This request has no body

Example:

/*
Pin Code: pinCode2 (OvSdpyD2FoUNR5rNyte41QqZzR1Y4DVN)
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": "fZL3Z4ZlYRz5dt5ls0orrG5Pw1vdHxK+35tOc1aDIyInrHErmJRfeohzuviFFb7FuaxMZYPKU2GEMVIq8BvS3ua2xAj1CWHnduaO0YGTHfcuYTOTZxy3CZHvMtphPux+LZ2n3QlkhRPXeMwDlcOeaq1lKLerkcQf1SDSK14MvrTVg/NuB3BArPVmZsX9zBZ1pDrc7ixr4O/yNLD6RR/9JOKt3XWYqAJyztN06hYfSSI="
}

Response "data.body" structure

VariableTypeRequiredDescription
deviceStatusStringYPayment 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.
networkStatusStringYThe current network connection status of the payment device: Connected / Disconnected
softwareVersionStringYThe software version of the payment device
businessIDStringYThe response ID in the response Header is derived from the request ID in the request header.
Example:

/*
Pin Code: pinCode2 (OvSdpyD2FoUNR5rNyte41QqZzR1Y4DVN)
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": "+AGm65vmYsIBpb0oOlvyCkcJ/BurpmzLL7LusZW2mlfmEE3bYAD8hbwbrOshjozgFtkL+oMSrSfvs8rxHxdr5RU9WVCBgfognPaJj+9XnNJ43vnY7cjr5LvN5OZg8HNEiRYRQipGkjlPqiqWpyYCHs1nSIFoR/KSUvIokFKDY5USySXSBs5cp+vdbO6THLjWPYrgywQ8aBfNdaUUEMZEVURRhoQYY0frhko6I2i6iatD7b4BiO2W+J8ycDClo+3QBRmRUPjZA6w5CobbWXckYZO2GxWDg1X3i8IJqx2qioVew9mzYeJ74a4/6EIiUy/ebqGOqHeVTGEuCa0jogZkVixbYBoBbb3yhdLyPa0s8aPGatYmO5XzUTpsXXoDwmXf00yJdgE5Q7vNmxwv94jSp4SAVxB8gR9yvO3iLXqG+3I="
}

3.4 SyncTravelData

  • Action: SyncTravelData
  • Pin Code: pinCode2

Request "data.body" structure

VariableTypeRequiredDescription
sequenceIntYThe communication serial number needs to be increased by 1 for each request
customerOrderIDStringYThe order ID of the travel transaction
plateNumberStringYThe vehicle plate number
waitingTimeIntYThe waiting time of the travel transaction in seconds
totalMileageFloatYThe total mileage of the travel transaction in kilometers
validMileageFloatYThe valid mileage of the travel transaction in kilometers
startedAtLongYThe timestamp(milliseconds) when the taxi travel began
feeFloatYThe fee of the travel transaction in cents
additionalFeeFloatYThe additional fee of the travel transaction in cents
amountFloatYThe amount of the travel transaction in cents
unpaidAmountFloatYThe current unpaid transaction amount
currencyStringYThe currency of the travel transaction, Example: HKD / USD / RMB

Response "data.body" structure

This request has no body

3.5 Sale

  • Action: Sale
  • Pin Code: pinCode2

Request "data.body" structure

VariableTypeRequiredDescription
sequenceIntYThe communication serial number needs to be increased by 1 for each request
customerOrderIDStringYThe order ID of the travel transaction
plateNumberStringYThe vehicle plate number
waitingTimeIntYThe waiting time of the travel transaction in seconds
totalMileageFloatYThe total mileage of the travel transaction in kilometers
validMileageFloatYThe valid mileage of the travel transaction in kilometers
startedAtLongYThe timestamp(milliseconds) when the taxi travel began
pausedAtLongYThe timestamp(milliseconds) when the taxi travel paused
feeFloatYThe fee of the travel transaction in cents
additionalFeeFloatYThe additional fee of the travel transaction in cents
amountFloatYThe amount of the travel transaction in cents
unpaidAmountFloatYThe current unpaid transaction amount
currencyStringYThe currency of the travel transaction, Example: HKD / USD / RMB
countdownIntYAfter the countdown ends (seconds), it will jump to the home page. If you don't send it, it won't jump automatically. You need to send the action: End

Response "data.body" structure

VariableTypeRequiredDescription
statusStringYResponse status: Success / Failed / Pending
errorCodeStringY
errorMessageStringY
customerOrderIDStringNThe order ID of the customer's transaction
currencyStringNExample: HKD / USD / RMB
amountStringNSale amount
paymentMethodStringNPayment method
paymentEntryTypeStringNPayment entries, Example: contactless
rrnStringNReceiver Reference Number
brnStringNBindo Reference Number
transactionTypeStringNTransaction type: Sale / PreAuth / Void / Refund
transactionTimeDatetimeNTransaction Time
creditCardObjectN
creditCard.panPrefix6DigitsStringYFirst 6 digits of the credit card number
creditCard.panLast4DigitsStringYLast 4 digits of the credit card number
creditCard.consumerIdentifyStringYConsumer identify, e.g. Card Number, Open ID, etc.
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": {
"status": "Pending",
"errorCode": "",
"errorMessage": ""
}
}
*/

{
"version": "2.0",
"action": "Sale",
"data": "CcDYsa/fPAjhaaTi5e0SQHJ5AGeWrfhu+D70RJwU9vizGFB38D9j65iEUbBQqs7qbjOQ9AGaBkhNhBWNYUXtdDT5FT9R/2aSLodTgpTPbsWNGhkihyaaVQ+9kN/RjL/frPrvKV1VQsRDEG783RKRLY5Uz0RsSGLXbqkW0drzKxnAvAs13KlcqrfTe0rHNnZ+fKzuW7imxytn1nXKUtGciIXCE+NzXvRSmYbk0WPM+hTCM2WbC+Vul8vD3++vp4v7u4z3d+A7LRcE30W3q6TZKciZ9pnau1A4eVjxAY5EJ93uMWNnny5/yDOE2s1gKHS1"
}

Example 2:

When the status is Failed


/*
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": {
"status": "Failed",
"errorCode": "5xxxx",
"errorMessage": "The equipment is being traded"
}
}
*/

{
"version": "2.0",
"action": "Sale",
"data": "aDmtvHICThbeeWzsusOZbKWWwJOI1PZC5mUHufTvsVr8vO8UyqBw99XfujjCJNq6ibse10OsBLbGc488Ty7qZW/aO8cJi/KQgqVhPU84pQ1wmfbbbZODvlV0PmD9JU6dqjU2BvChhNfFVXKYF6AGXjMh6/NFQlY4G59w0kI1vgNYyRHohoyqHBX9qm4+MUlb0f010DtTPZKMzfRL//KBilJjctok9CWz9CjRim39D969UoS4WLm7x1eXAC/DMPaw2KM/MlUp05BFzcArZlgf1bCtxhvL1TVcwhVQSLHtxYk5Mrc8rIeLMZ0I8Yw5JsbXATMgSmcz+KzaHSwlg7TtB+8rpA1VLelBf0PZmPXwOKU="
}

Example 3:

When the status is Success


/*
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": {
"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",
"consumerIdentify": "xxxxxxx"
}
}
}
*/

{
"version": "2.0",
"action": "Sale",
"data": "FhziRMtQCRA3hORV/aOvKL7I8EZFbQLGumGab6TgLKw4U1fNLTP0JdU2hS1VoDCvIVSi9f9wC4gdj7kjXkbXJ9Did6YTAYmI/9YYTWrF1inowCYvgRalVHflFiKuHH0Oog8ex3HHWrz4hFMJ+/9aYRgHiFN2sl6dwgI6gkT9ea6bnpPENsPgyy9UBLtk/baD5duu/EgLfcN/1gp6v6O4g4tD1YVSeNdan6Xe7fbGzLhq4XkKBbMaAJ/95TEWXkpXLUu0CrqevPX+YkG5rsi1vimizJOKzEQeLhKKzT4j4uBMqjVJK/SXGTzu/AloNIFbPcFxLxBOUyHxqFHwFCcU+sZmIb/lQP3x8rbHacM0bL0LMeCSXZhWLPwxjqh2qhbrpKYtNqipkbB3cyCpQquw69h1SH/EqIBFFabTVHUPyj6ky0yUsVeTsnj1CgcL5ILdvaJhyFcAPlBkqtVy7DxR8a8ksAQsXanR7Li8JeHlGIGQ2SiewkxZckdE9kDaf2iHiq+7H68ZKzuklJ+GE4Jtug30rCFnefs83RNhAL6LoY9KzgMAQ02MyzW5kJZKAKBmK2TaG5EgbO/L7GAPhoK8wgr0j2qfD/0uMyXJGapBzPoDy1Jjg3GE1sbiv/n+bfz362LfcVaErRm6pybvrWLTHZkOO4rRdP5e4v3fgP1hHmwr2nIG1RoOvaR7VnQ+VyuqpLGrkxPuo1pezZGftdqDcR2OzrEIexVy3OvTNKVnBdksGXI/HZe8MviaOYzsx8MEuMDQfU6tPYIGCfTwHIr598tga9eXN98PoB2JdZ+hynUcc0VKvaumF6tCQxGCXmdk"
}

3.6 End

  • Action: End
  • Pin Code: pinCode2

Request "data.body" structure

This request has no body

Response "data.body" structure

VariableTypeRequiredDescription
statusStringYResponse status: Success / Failed / Pending
errorCodeStringY
errorMessageStringY

3.7 Query Transaction Status

  • Action: TransactionStatus
  • Pin Code: pinCode2

Request "data.body" structure

VariableTypeRequiredDescription
targetReferenceIDStringYThe reference ID that was carried during the transaction made at that time.
Example:

/*
Pin Code: pinCode2 (OvSdpyD2FoUNR5rNyte41QqZzR1Y4DVN)
Encrypt the original data:
{
"header": {
"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": "g1dOdau+ZkncE2e9w4a+hNBM155OiQEjrb5OM8HhtgByL1QO133bR+SZGUwOyUVHgUNzXBWQMuwuBHKFZY4YFaBu9DBZO7kwqvqS6tykd4D6OGgCSCazoa8j7JnynEPOX5ddBX/UA20jYBZswOAGUSkzu+W8uPLxj78/kS+QxeM+x69l5gr26dYYFL6hifsuYFPDUEAEXdwb0wd4jT/wadaxntunizLqhZBLgpF/JreyT5VuUXu5fEVtJQ8g6ahbYLcaGUic1wOOE83JppispRwO5yy/ZlJUMNN5Utb6yGLs7lnhby+V6bxtLwQWV+A1"
}

Response "data.body" structure

VariableTypeRequiredDescription
statusStringYResponse status: Success / Failed / Pending
errorCodeStringY
errorMessageStringY
...AnyYIt is consistent with the returned information of the current query transaction type
Example:

/*
Pin Code: pinCode2 (OvSdpyD2FoUNR5rNyte41QqZzR1Y4DVN)
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",
"consumerIdentify": "xxxxxxx"
}
}
}
*/

{
"version": 2.0,
"action": "E+tHz6mfJFRWUZZLQh+m/YM3qZkVODr34GRkJ2QvDp/cNEMVUKzyK2nEy8GacOxB//x5wq9+iSjmbFsPln6OUN12cqB1uP57KTvTfbaCk0G+4/blA3ltZ+zCjnwMW3BWrL2/dUrHMllKvL/hm3OH+mWMCn2VNn4dEdTsfJztq/YCLnQktQGZmyV72wRuIWJ0OLwS2i9K0NeMw3uBzKOUaOsK0vtMEwdyyuuxT8zBit+Y9KMlC2gopLjUii+pgphecYLFFszVup4F6Y5VAzzE/RMSjUeHm5y68dDQSUPUOgSo13F31PJk/noY0C9QAGo8Y7iLx/zYdjkIM4ghFtvWrRd/jrJeUXZj6jNAthb7CowA+8hscgl5DzPKdLJWnLQrJJxAfUwhvQfayuS2UqMdnmxdrHIaAbp92LqELlOPVeSglqpmWIilOplDLvDmBvVkNuV7FqmEIeye01eoDzRWisZgfPW7jgWAp1on1B6KXR3EB87Jj8s5pD8Bhi4jlC6aM95jbSN19U+DoxLocAyzrCUg1ZZhHHFUch9Gr91xMr1f4GNG5RFKrB81bYy3tgDVvJrY5FIu6FVpbuOU2LFtv41+aJdFRwkExgXT+ljNfvOutt2ZCoS72vhNNbLERBSL+iLy/ieiG1FWqv9a5W5T5r/50fmB38BGD9cD/ejwmKzW+bDwDIoFoHXfcrNl8UjJT3DyAH9VyvZzzqv6tDDQDgnDRKJMFVZ0CtmWh3Vxzt//LhReIeTOpNgeix9ntN9WaS4vvxieBSkcsM6D3I1GSilL2uHLqkBfwDGDDO1HdrM8QosKDOKWTtsDEhIyt8fMw1Ohc8zEcNW572pAffjo9A=="
}