WebSockets - Getting Started

This section explains how to get started using Connect over a secure WebSocket connection. Once this is all set up, you'll be ready be to start working with the WebSockets API.

Messages over the WebSocket connection use JSON following the JSON-RPC2 Protocol. Every message sent across the connection has been documented below using a JSON schema which defines the structure of the message. Each JSON Schema is also provided in its raw form so it can be used to validate any messages while developing your integration.

Requirements for Interacting with Connect

Each location that uses Connect will need its own:

  • Host address
  • API token

Host

The host is unique for each customer site, or your test environment. This will be provided to you for each customer site.

Authorization

We provide each customer site with an API key to communicate with Connect. When making a WebSocket connection to the host, the API key should be provided in the URI to authorize the connection.

How To Connect

The WebSocket URI takes the form:

wss://[host-address].connect.paymentsense.cloud/[integration-type]?token=[api-key]&api-version=[connect-version]&software-house-id=[software-house-id]&installer-id=[installer-id]&final-pos-receipt-request

Where the variable portions of the URI are defined by:

  • host-address: The given Connect host address.
  • integration-type: The integration type being used. The allowed values are:
    • pac
    • pat
  • api-key: The API key to authorize the connection. The value should be configurable in your EPoS so it can be correctly set on installation.
  • connect-version: The chosen major version of Connect that will be used. The allowed values are:
    • v1
    • v0 (We are no longer accepting new integrations using this version.)
  • software-house-id: Identifies the EPoS company whose software is generating the request. This value should not be configurable as it will remain the same for all customers using particular EPoS software. The value will be provided by Paymentsense.
  • installer-id: Identifiers the installer of the EPoS. This may be the same as the software-house-id if they are also the installer. If your EPoS can be installed by resellers, they will be provided with a separate Id. The value should be configurable in your EPoS so it can be correctly set on installation.
  • final-pos-receipt-request: This is only valid for PAT integrations using v1. If passed, Connect will always ask for a final POS receipt to be printed following the transaction.

When developing or updating your integration, you should always explicitly request the connect-version you're working with. It's strongly recommended to always use the latest version of our API.

Example URI:

wss://testhost.connect.paymentsense.cloud/pat?token=00000000-0000-0000-0000-000000000000&api-version=v1&software-house-id=ABC123&installer-id=123ABC&final-pos-receipt-request

How you make this connection will depend on the language and WebSocket framework/library that you are using.

If you have been provided with a host address and API key, and would like to quickly try it yourself, there are tools that will allow you to make a WebSocket connection and send messages over it. For example the Chrome addon 'Dark Websockets'.

Pings

Connect will periodically ping the EPoS over the WebSocket connection to confirm that it is still connected. The client must respond to these pings appropriately otherwise Connect will assume the client is no longer connected and terminate the connection.

Next Steps

Once you've got started with the WebSockets connection, you're ready to start integrating with the WebSockets API.