Opening a WebSockets connection

Obtain your API key and publish your first message.

Step 1. Get your API keys

Use the Dojo developer portal to receive your API key (apiKey). Reach out to your Partnership Development Manager (PDM) if you do not have access to the developer portal. This is required to receive and send messages to the API.

Step 2. Open a WebSocket connection to the EPOS Data API

To start integrating with the EPOS Data API, you can use our test endpoint. This endpoint allows you to simulate payments on the card machine, making it easier for you to develop and test your integration:

wss://eu.ws.dojo.tech/epos

Ensure you're using a WebSocket client that enables you to set the required headers:

Header Name	Description
Authorization	Basic authorization is used to authenticate your requests to the API using your API key as the value, for example: Basic $apiKey.
reseller-id (optional)	Identifies the reseller who sells software on behalf of the EPOS company. This value will be unique and provided by Dojo to each reseller.
software-house-id	Identifies the EPOS company whose software is generating the request. This value shouldn't be configurable as it will remain the same for all customers using particular EPOS software. This value will be provided by Dojo.

All of these values will be provided by Dojo. If you're unsure about any of them, reach out to your PDM.

tip

Despite the scheme name, do not base64-encode your API key. The literal value Basic <api_key> (with the sk_sandbox_ or sk_prod_ key inserted as-is) is what the gateway expects.

Step 3. Confirm the WebSocket connection

Ensure that you were able to successfully establish the WebSocket connection. Look out for any errors and reach out to your PDM if you require further assistance.

Step 4. Register the capabilities you implement

The connection alone is not enough — Dojo will only route a JSON-RPC method to your EPOS once you've registered that capability. Do this once, then update it whenever you add or remove a method. See Registering capabilities for the request body and a worked example, and the per-capability pages under Core concepts for the exact name value to register for each method.

Connection lifecycle

Once the WebSocket is open, Dojo multiplexes every JSON-RPC method invocation over the single connection. Keep these in mind when implementing the EPOS side:

• Long-lived connection. The connection is expected to stay open. Dispatch each incoming JSON-RPC request to a handler concurrently and reply with a matching id on the same socket; the gateway correlates requests and responses by JSON-RPC id.
• Keepalive. Send a WebSocket ping at least every 30 seconds when otherwise idle, and respond to incoming pings within a few seconds. Connections that go silent for several minutes may be closed by the gateway.
• Reconnect on close. If the connection drops, reconnect with exponential backoff (e.g. 1s, 2s, 4s, capped at ~30s) and resume serving requests. In-flight requests are not replayed across reconnects — Dojo will retry on its side as needed, so handle requests idempotently based on the JSON-RPC id if you persist any side-effects before responding.
• One connection per software-house-id deployment. Open one connection per logical EPOS instance. Multiple concurrent connections from the same software-house-id are not load-balanced; only one will receive routed requests at a time.
• HTTP/1.1 only. WebSocket upgrade is not supported over HTTP/2. If your client library defaults to HTTP/2, force HTTP/1.1 for the handshake.

Next steps

You're now ready to start building your EPOS integration!