Overview#
Simplified cashier experience for in-person payments. Automating payment input and streamlining cashier workflows with seamless terminal connectivity — no manual entry required.The terminal model interfaces through an asynchronous serial communications port with the following port parameters:| Parameter | Remarks |
|---|
| Connection | USB, WIFI, RS232 with Cradle |
| Data Rate | 9600 bps (for RS232, USB) |
| Transmission | Asynchronous, 8 data bits, no parity, 1 stop bit (N,8,1) |
| Characters | ASCII character set (for character fields) |
Message Flow
Message flow between POS and payment terminal that includes exception handling to be handled by both POS and payment terminal devices.Message Protocol
POS requests the terminal to perform a particular task with following standard messages interface protocol.Message Flow#
Following are the message flow between POS and payment terminal that includes exception handling to be handled by both POS and payment terminal devices.Normal Flow (Happy Flow)#
Under normal scenario, when the external device (POS / Kiosk) sends a request command to payment terminal; it waits for the acknowledgement from the terminal. Upon received the command, the terminal should validate the validity of the message by checking its’ command data length and Long Range Checksum (LRC). If the data length and the message LRC are correct, the terminal responses to the external device with an acknowledgement (ACK).With the external device received acknowledgement from the terminal, it waits for the message response from the terminal. At the terminal side, it processes the request message and then sends the response message to the external device. Depending on the nature of the request message, the terminal may need to send online message to acquirer host for approval which takes time for processing or authorization the payment.When the external device had received the message response from the terminal, it validates the validity of the response message by checking the message LRC. If the LRC is correct, it acknowledges to terminal to confirm that the response message had been received successfully.NACK received by POS or Kiosk#
When the terminal validates that the request message (command) received is corrupted such as it fails the LRC checking, the terminal will send a negative acknowledgement (NACK) to the external device to request for message re-send. The external device, upon received the negative acknowledgement should re-send the request command again to terminal immediately up to 2 re-sends. If a NACK is received after the External device has made the final re-send, the transaction is considered unsuccessful and the external device should check for any error in the communication setup, fix the error and then re-issue another request message again.Timeout or No Response received by POS or Kiosk#
When the request message (command) is sent to terminal, but no acknowledgement is received by the external device from the terminal within a wait period, the external device should re-send the request command again to terminal. With each re-send, the external device waits for acknowledgement for 2s. The external device only re-sends the command twice. After it re-send the command message for second time and waits for 2s, if no acknowledgement is received from terminal, the transaction is considered unsuccessful and the external device should check for any error in the communication setup, fix the error and then re-issue another request message again.NACK received by Terminal#
When the external device validates that the response message from the terminal is corrupted such that it fails the LRC check, the external device should send a negative acknowledgement (NACK) to the terminal to request the terminal to re-send the response message. The terminal, upon received the negative acknowledgement should re-send the response message to external device immediately. The terminal will only re-send the response message twice in response to the NACK received. If the 2nd resend message received by the external device still is corrupted, the transaction is considered unsuccessful and the external device should check for any error in the communication setup, fix the error and then re-issue another request message again (e.g. a void to reverse the transaction).No response or Timeout received by Terminal after send response message#
When the terminal sends response message to the external device and is expecting acknowledgement from the external device, but no acknowledgement is received within 2 seconds; the terminal should re-send the response message again to the external device, and waits for the acknowledgement. The terminal only re-sends the response message twice. After the terminal makes the final re-sends and has waited for 2s, if no acknowledgement is received from external device, the transaction is considered unsuccessful and the external device should check for any error in the communication setup.Message Protocol#
The external module initiates the message exchange to payment terminal. The device (POS) requests the terminal to perform a particular task with following standard messages interface protocol.The following control characters are used to control the communication protocol.| Name | Attribute | Length (Byte) | Description | Sample Value |
|---|
| STX | HEX | 1 | Start of text | Fixed 0x02 |
| Len (LLLL) | BCD | 2 | The number of bytes of the Message Data. | 0042 |
| ETX | HEX | 1 | End of text | 0x03 |
| LRC | HEX | 1 | Long Range Checksum | 0x04 |
| ACK | HEX | 1 | Acknowledgment | 0x06 |
| NAK | HEX | 1 | Negative Acknowledgment | 0x15 |
Long Range Checksum (LRC) appended at the end of the message following the ETX control character. The LRC is an exclusive OR of all data bytes contained in between STX and ETX. The LRC operation includes the ETX control character, but not the STX. The Start value for computing the LRC is hexadecimal 0x00.
Message Data#
Request and response of Message Data Structure will be explained in detail in this section.Request Message Data Structure#
| Name | Attribute | Length (Byte) | Description | Sample Value |
|---|
| ECN | ASC | 12 | ECR Control Number.
A unique numbering sequence that the ECR define for each Function request. | e.g. 000000000001
(0x30 0x30 0x30 0x30 0x30 0x30 0x30 0x30 0x30 0x30 0x30 0x31). |
| Function Code | ASC | 2 | Please refer to individual Function for the value. | e.g. C1
(0x43 0x31) |
| Version Code | ASC | 2 | Fixed value as of current version. | Default value is “01”
(0x30 0x31) |
| More Indicator | ASC | 1 | '0': last message.
'1': there is another message coming. | e.g.(0x30) OR (0x31) |
| Separator | HEX | 1 | To separate each section. | Value is “;”
(0x1C) |
| Field Code | ASC | 2 | Please refer to the individual function code (transaction) for list of field code for each transaction request and response. | |
| Len (LLLL) | BCD | 2 | The number of bytes of the 'Data' that follows. | |
| Data | ASC | Variable | Variable length and different format. Please refer to the individual function code for data format or structure. | |
If the transaction request with the same ECN and Function Code with previous request that already approved, terminal will just return the approved transaction instead of performing the new transaction.
However if the previous request was failed, terminal will perform the new transaction.
Response Message Data Structure#
| Name | Attribute | Length (Byte) | Description | Sample Value |
|---|
| ECN | ASC | 12 | ECR Control Number echo from request message. | |
| Function Code | ASC | 2 | Please refer to individual Function for the value. | e.g. C1
(0x43 0x31) |
| Response Code | ASC | 2 | Please refer to individual Function for response code. | e.g. 00
(0x30 0x30) |
| More Indicator | ASC | 1 | '0': last message.
'1': there is another message coming. | e.g.(0x30) OR (0x31) |
| Separator | HEX | 1 | To separate each section. | Value is “;”
(0x1C) |
| Field Code | ASC | 2 | Please refer to the individual transaction function codes for list of field code for each transaction request and response. | |
| Len (LLLL) | BCD | 2 | The number of bytes of the 'Data' that follows. | |
| Data | ASC | Variable | Variable length and different format. Please refer to the individual transaction function codes for data format or structure. | |
The list of fields in Field Data doesn't comes in sequence or based on list provided, therefore POS / Kiosk have to processed based on Field code instead expecting the data comes in sequence order or according to the document list.
