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. In addition to the standard TCP connection, the payment device also supports secure connections on port 9443. When a secure connection is established, SSL/TLS is used to encrypt the data, ensuring enhanced security for sensitive transactions and communications.

Service Ports:

  • TCP: Port 9000
  • Secure TCP (SSL/TLS): Port 9443

SSL Certificate

The server certificate is self-signed and issued by the Synqpay Root CA. Clients can either trust this certificate or disable verification to establish an SSL connection.

For more details and download links, see Synqpay Root CA Certificate.

Connection Details

  1. Single Client Limit: Only one TCP/SSL connection is allowed at a time. If a new client attempts to connect while a session is active, the device will close the previous connection and accept the new one. This behavior is designed to prevent the issue of disappearing clients.
  2. No Timeout: The TCP/SSL connection does not have a timeout configured. It remains open until explicitly closed by the client or server.

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.