Websockets

The Tyro Connect websocket API is intended for use by integrations that require Tyro Connect to deliver the message to the individual location. If possible please consider using the webhooks integration method as it is more flexible and reliable.

To open a websocket connection you must know the Tyro Connect locationId of the location where the socket is being opened. Websockets are intended to represent a single location and will only receive the events for that single location.

The uri for opening a web socket is: wss://api.tyro.com/connect/pos/notifications/*locationId*

Make sure to indicate the data format and protocol version in the Accept header. Currently this header must be set to application/vnd.tyro.connect+json;protocol=2.0

Protocol v2.0 - Hello Message

Before the connection becomes operable you are required to send a Hello Message to Tyro Connect. Your Hello Message must contain your software version along with a list of Tyro Connect API versions supported by your software. Please see the schema below for details. If you fail to send the Hello Message within the first 30 seconds after the connection has been established, Tyro Connect will close the connection again. Please see below for how we send error messages to you.

Legacy Protocol Versions

In older versions of the Websocket protocol the hello message was not required. However, the use of protocol version 2.0 is now mandatory.

Make sure you send your JWT token as an Authorization header as well the Accept header.

Copy
Copied
url: 'wss://api.tyro.com/connect/pos/notifications/{locationId}'
method: get
headers:
  Accept: application/vnd.tyro.connect+json;protocol=2.0
  Authorization: Bearer '{{bearer}}'
type
required
string
Value: "HELLO"
posVersion
required
string
required
Array of objects
Array
name
required
string
Enum: "BOOKING" "FOOD_ORDERING" "LOYALTY" "PAYMENTS" "SALES" "LOCATION" "MENU"
version
required
string
Enum: "0.6" "1.0" "1.1"
Copy
Copied
{
  "type": "HELLO",
  "posVersion": "12.20.05",
  "supportedApis": [
    {
      "name": "FOOD_ORDERING",
      "version": "1.0"
    },
    {
      "name": "BOOKING",
      "version": "1.1"
    }
  ]
}

Message Payload

Tyro Connect will send any message events over the websocket connection. It will be a json encoded string message that contains an array of all new messages, that looks like this:

type
required
string
required
object
id
required
string
uri
required
string
resource
required
string
Copy
Copied
[
  {
    "type": "ORDER_CREATED",
    "data": {
      "resource": "order",
      "id": "abcxyz123-2c32-4a0d-a0dd-f766e965235e",
      "uri": "https://api.tyro.com/connect/orders/abcxyz123-2c32-4a0d-a0dd-f766e965235e"
    }
  }
]

Confirming message has been received

Once an event has been received, the POS needs to send a reply via the websocket to inform Tyro Connect that the event has been received:

type
required
string
Value: "MessageReceived"
id
required
string
Copy
Copied
{
  "type": "MessageReceived",
  "id": "event-1234"
}

When new connection is established

When a new connection is established, Tyro Connect will send messages about all the orders that have not been marked as MessageReceived by the POS at the time of the connection. This will make sure that you don't lose an order even if the websocket connection is broken or closed.

Keeping the Connection Open

To ensure that the connection is still alive and to improve the performance of orders delivery to the POS location, please send a PING message every 20s and verify the PONG response.

If we do not receive a PING message for 45 seconds the server will close the websocket.

Tyro Connect follows the RFC standard protocol when it comes to websocket implementation: https://tools.ietf.org/html/rfc6455#section-5.5.2

Duplicated messages

Duplicate, Unknown or Out of Order Events

Please ensure your implementation ignores the following occurrences:

  • Duplicate Events: Please make sure that your system can handle duplicate events i.e a message with an identical type and id. If you receive an message about an event you have already received please ignore it. This should be an uncommon occurrence but can occur if Tyro Connect encounters an error and we are not sure we delivered the message to you.
  • Out of Order Events: Rare network issues could potentially result in out-of-order events. If you receive a message about an event that appears to be outdated, please ignore it as this is most likely an out-of-order event.
  • Unknown Events: It is also possible that Tyro Connect publishes events with a type that you do not support. When this happens please ensure that your implementation ignores the event.

Error Handling

When Tyro Connect detects a problem with the connection (for example a non-conformant or missing Hello Message) it will send an object to you containing an error property which specifies the error. Right after sending this mesage, Tyro Connect will close the connection.

Copyright © Tyro Payments 2019-2024. All right reserved.