wss://<account-name>.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]
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 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 address is made up of a unique account name plus ".connect.paymentsense.cloud". For your test environment, use ".test.connect.paymentsense.cloud". This address will be provided to you for each customer site.
Error:
This value should be configurable in your EPoS since we provide each customer site with their own host.
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.
Error:
This value should be configurable in your EPoS so each customer site can have their own key and each till can be identified.
How To Connect
The WebSocket URI takes the form:
Where the variable portions of the URI are defined by:
- account-name: The given Connect account name.
- 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(Ingenico Only): 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.
Error:
By default, the documentation always describes the latest API version.
Error:
If no version is explicitly requested, Connect will default to the oldest available version: v0.
Example URI:
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 familiarising yourself with the PAC Transaction Flow and the PAT Transaction Flow.