Skip to content

TCP

Overview

This document describes the TCP transport protocol for communication with the payment device. The device listens on port 9000 and uses the link layer protocol for message framing. JSON-RPC requests, responses, and control messages are transported over this channel.

Message Types

The TCP transport supports the following message types:

MessageType Value (Hex) Requires API Key? Description
Request 0x01 Yes JSON-RPC request with authentication.
Response 0x02 No JSON-RPC response from the device.
Event 0x03 No JSON-RPC notification.
KeepAlive 0x04 No Periodic keep-alive signal.
ACK 0x05 No Acknowledgment of a KeepAlive.
Error 0x06 No Indicates a link-layer error.

For details about message frame structures and payloads, refer to the Link Layer Protocol Documentation.

Authentication

All API methods must be authenticated. Each request (MessageType 0x01) must include a 4-byte API key in the message body (refer to the Link Layer Protocol for details). The API key is obtained through a pairing process.

  • If the API key is invalid or missing, the device responds with an Error frame with code 0x05 (NOT_AUTHENTICATED).
  • For the methods that process the pairing (pair and authenticate) the API Key must be filled with zeros).

Communication Workflow

  1. Establish Connection:
  2. Connect to the payment device on port 9000 over TCP.
  3. Send Requests:
  4. Construct a valid Request frame (refer to the link layer for structure) and send it to the device. Ensure the API key is included.
  5. Receive Responses:
  6. Parse incoming Response, Event, or Error frames using the link-layer structure.
  7. KeepAlive:
  8. Send periodic KeepAlive messages (MessageType 0x04) to maintain the connection.
  9. Expect an ACK (MessageType 0x05) in response.

Error Handling

When an error occurs, the device responds with an Error frame (MessageType 0x06). The 1-byte error code in the body indicates the type of issue. For error codes and their meanings, (refer to the Link Layer Protocol Documentation).

Cached Responses

When enabled in the device settings screen, responses that fail to deliver (e.g., due to client disconnection) are cached. These responses are retried upon the next connection from the same client is established.