WebSocket Interface

Available in API versions	`v2`, `v3`

This section describes the protocol for communication between the POS and Qerko over WebSocket. It is an alternative to the REST API. You can still use REST endpoints for POS-initiated requests, such as cancelling a payment.

WebSockets are used according to the RFC-6455 specification. The connection runs over WebSocket-over-TLS for security; the handshake happens through HTTPS.

All data is transferred in JSON format.

🚫

Each restaurant can have only one dedicated connection to Qerko. Differences in API keys are irrelevant if both API keys belong to the same restaurant.

Ping-pong

Maintaining a stable connection to Qerko is critical for a reliable POS integration.

To ensure a stable WebSocket connection, the POS must actively monitor connectivity using one of the following approaches. While the WebSocket spec doesn’t mandate sending pings, it does require responding to them. Verify that your integration actively sends pings (or equivalent) so that a dropped connection is detected and handled promptly.

Tip: In some situations, the close event is not emitted (for example, when the WAN cable is disconnected). Ensure your implementation handles that scenario; that’s what the ping-pong mechanism is for.

Qerko supports three strategies for detecting dead connections:

WebSocket ping-pong

What: Send a WebSocket-level ping frame.
Response: Qerko sends back a pong frame.
Timeout: If no pong is received within 5 seconds, treat the connection as dead and reconnect.
Note: Check your WebSocket library docs for how to send ping frames (some libraries call this heartbeat or keepAlive).

Method `noop`

What: If you can’t send a ping, call the method noop.
How: Send a MethodCallRequest with method noop - include a uuid otherwise you won’t receive a response.
Response: Wait for the corresponding response.
Timeout: If no response arrives within 5 seconds, consider the connection dead and reconnect.

Watching activity

What: Qerko sends its own pings whenever there has been no communication in the last 45 seconds to detect dead connections.
How to monitor:
- Periodically check that your POS has received either a message or a ping from Qerko within the last 60 seconds.
- If nothing is received in the last 60 seconds, consider the connection dead and reconnect.
Requirement: Your WebSocket library must support detecting incoming pings.

WebSocket wss://…/api/v2/pos/ws

Using this endpoint, the POS opens a WebSocket connection to Qerko. The connection is bidirectional, enabling both sides to send messages and call methods. The duplex WebSocket connection replaces long-polling; do not use both approaches at the same time.

Response HTTP statuses

During the connection handshake you can receive these HTTP status codes:

status: 503 Service Unavailable - The server is about to be restarted. Try again in 2 minutes. Responses can contain various headers and should be ignored.

WebSocket close codes

The WebSocket connection can be terminated with the following close codes. Do not confuse them with HTTP status codes; see CloseEvent.

status: 1001 Going Away - Our server needs to restart the connection. Reconnect immediately. This can occur, for example, when we release an upgrade without downtime.
status: 4503 Service Unavailable - The server is preparing to restart this specific WebSocket connection. Wait 2 minutes before reconnecting. Any payload can be ignored.
status: 4401 Unauthorized - Invalid API key or POS ID. This can happen when the API key is deleted while the connection is active.
status: 4409 Conflict - The server ended the connection because another concurrent connection was opened for the same restaurant. The response is empty.

Messages

Messages are JSON data structures sent through the WebSocket. They are identified by the type property.

Authorization request message

The POS sends this message to Qerko to authenticate itself. Websockets don’t support additional HTTP headers, so we need to authenticate the POS using something else.

Right after opening, Qerko awaits an authorization message. If it receives anything else the WebSocket will be closed. If no authorization message is received within 5 seconds of opening the connection, it is also closed.

Send this message right after opening the websocket. It will authenticate the connection.

Property	Type	Required?	Description
`type`	string	Yes	Present in all messages. It defines the purpose of the message. Value: `auth-request`.
`posId`	string	Yes	POS ID assigned to your POS. See Production environment.
`apiKey`	string	Yes	The API key without any prefix. Example: `abcd-efgh-ijkl-mnop-qrst`.
`locale`	string	No	Locale for error localization in ISO 639-1 format. Default: `en`.

Authorization response message

This message is sent as a response to the authorization message.

Property	Type	Required?	Description
`type`	string	Yes	Present in all messages. It defines the purpose of the message. Value: `auth-response`.
`authorized`	boolean	Yes	`true` - You are authorized and can send and receive other messages. `false` - You are not authorized. Qerko closes the socket after this message.
`error`	Error \| null	Yes	If not authorized, this contains the reason. If authorized, the value is `null`. Example: `{ message: "Invalid Pos-Id", code: "POS_UNKNOWN" }`.

Method call request message

This message can go both ways: from Qerko to the POS and vice versa. After receiving this message, the receiver executes the corresponding method and sends a method call response message with the result.

Property	Type	Required?	Description
`type`	string	Yes	Present in all messages. It defines the purpose of the message. Value: `method-call-request`.
`uuid`	string \| null	Yes	Identifier of the call. If `null`, the receiver doesn’t have to send a response. Example: `1d0de3e1-5d4c-11e9-bc19-064f106d678c`.
`method`	string	Yes	One of the method names. Example: `paymentStart`.
`args`	Array<object>	Yes	Arguments for the method. The array matches the method signature. Example: `[{ id: "1", total: "255", ... }]`.

Method call response message

This message can go both ways. It means from POS to Qerko and vice versa.

This message is sent when there is a result of a method call from a previous method call request. A response is mandatory when a call request contains a non-null UUID.

Property	Type	Required?	Description
`type`	string	Yes	Present in all messages. It defines the purpose of the message. Value: `method-call-response`.
`uuid`	string	Yes	Identifier of the call. You received this value in the previous method call request. Example: `1d0de3e1-5d4c-11e9-bc19-064f106d678c`.
`result`	any	No	Whatever the method returns, including `null`. Default: `null`. Example: `{ "foo": "bar" }`.
`error`	Error \| null	No	Error that occurred, or `null` if there was none. Default: `null`.
`calledMethod`	string \| null	No	Method that produced this response. Qerko sends this every time to simplify stateless clients. Default: `null`.

Need help? Contact techsupport@qerko.com for assistance.

REST-API Interface Webhook interface