Skip to content

WebSocket

Overview

This document describes the Websocket transport protocol for communication with the payment device. The service is served on port 8000, and the endpoint is /synqpay.

Authorization

All API methods must be authenticated using an API key in the handshake headers, api-key. The API key is obtained through a pairing process. During the pairing process the key can be left out, once pairing process is complete , a new session must be created with the API key.

Hebrew / Arabic support

The Synqpay API supports UTF-8 encoding for all characters, including Hebrew and Arabic. All messages must be encoded in UTF-8.

Connection Details

  1. Single Client Limit: Only one WebSocket connection is allowed at a time. If another client tries to connect while a session is active, the connection is refused.
  2. Authorization: The client must include the api-key in the handshake headers.
  3. No Timeout: The WebSocket connection does not have a timeout configured. It remains open until explicitly closed by the client or server.

Supported Opcodes

  • PING/PONG: Keeps the connection alive.
  • TEXT: All JSON-RPC requests/responses are sent with this opcode.
  • CLOSE: The server will close the connection.

Error Handling

The WebSocket server initiates a close frame under the following conditions:

  • UnsupportedData (1003): When the server receives an unsupported opcode, such as BINARY.
  • PolicyViolation (1008): When the client is unauthorized, such as missing or invalid api-key.

These close codes follow the WebSocket standard close codes.

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.

Example Using wscat

  1. Connect to the WebSocket endpoint: 
    1
    wscat -c ws://<DEVICE-IP>:8000/synqpay -H api-key:<API-KEY>
  2. Send a request: 
    1
    {"jsonrpc": "2.0", "method": "getDeviceInfo", "id": "1"}
  3. The response will appear in JSON-RPC format.