Quickstart

Overview

This guide covers how to establish a WebSocket connection, authenticate your POS client, and maintain a healthy connection with proper heartbeat and reconnection handling.

Authenticate

Connect with your API key via headers or query parameters

Establish Connection

Open WebSocket connection to the API endpoint

Implement Heartbeat

Send periodic ping messages to maintain connection health

Handle Messages

Process responses and push notifications

Prerequisites

Before connecting, ensure you have:

API Credentials

API key provided by Modulus Labs for your POS integration

WebSocket Client

A WebSocket client library for your programming language

Network Access

Outbound access to the WebSocket endpoint over port 443

JSON Parser

Ability to serialize and parse JSON messages

WebSocket Endpoint

Connect to the WebSocket endpoint:

wss://api.sbx.moduluslabs.io/v1/terminal-gateway/ws

This is the sandbox endpoint. Contact support@moduluslabs.io for your credentials.

Authentication

Authenticate during the WebSocket handshake with your x-api-key. Prefer the header; a ?x-api-key= query parameter also works but can leak into logs. See Authentication for headers, the query-parameter form, and the full handshake.

Establishing a Connection

const WebSocket = require('ws');

const API_KEY = process.env.MODULUS_API_KEY;
const WS_ENDPOINT = 'wss://api.sbx.moduluslabs.io/v1/terminal-gateway/ws';

function connect() {
  const ws = new WebSocket(WS_ENDPOINT, {
    headers: {
      'x-api-key': API_KEY
    }
  });

  ws.on('open', () => {
    console.log('Connected to WebSocket API');
    startHeartbeat(ws);
  });

  ws.on('message', (data) => {
    const message = JSON.parse(data.toString());
    handleMessage(message);
  });

  ws.on('close', (code, reason) => {
    console.log(`Connection closed: ${code} - ${reason}`);
    // Implement reconnection logic
    setTimeout(() => connect(), 5000);
  });

  ws.on('error', (error) => {
    console.error('WebSocket error:', error.message);
  });

  return ws;
}

function handleMessage(message) {
  switch (message.action) {
    case 'terminalsResponse':
      console.log('Terminals:', message.terminals);
      break;
    case 'paymentComplete':
      console.log('Payment complete:', message.paymentResponse);
      break;
    case 'terminalStatusUpdate':
      console.log('Terminal status:', message.status);
      break;
    case 'forceDisconnect':
      console.log('Disconnected:', message.reason);
      break;
    case 'pong':
      console.log('Heartbeat received');
      break;
    default:
      console.log('Unknown message:', message);
  }
}

const ws = connect();

import asyncio
import websockets
import json
import os

API_KEY = os.getenv('MODULUS_API_KEY')
WS_ENDPOINT = 'wss://api.sbx.moduluslabs.io/v1/terminal-gateway/ws'

async def connect():
    headers = {
        'x-api-key': API_KEY
    }

    async with websockets.connect(WS_ENDPOINT, extra_headers=headers) as ws:
        print('Connected to WebSocket API')

        # Start heartbeat task
        heartbeat_task = asyncio.create_task(heartbeat(ws))

        try:
            async for message in ws:
                data = json.loads(message)
                await handle_message(data)
        except websockets.ConnectionClosed as e:
            print(f'Connection closed: {e.code} - {e.reason}')
        finally:
            heartbeat_task.cancel()

async def handle_message(message):
    action = message.get('action')

    if action == 'terminalsResponse':
        print(f"Terminals: {message['terminals']}")
    elif action == 'paymentComplete':
        print(f"Payment complete: {message['paymentResponse']}")
    elif action == 'terminalStatusUpdate':
        print(f"Terminal status: {message['status']}")
    elif action == 'forceDisconnect':
        print(f"Disconnected: {message['reason']}")
    elif action == 'pong':
        print('Heartbeat received')
    else:
        print(f'Unknown message: {message}')

async def heartbeat(ws):
    while True:
        await asyncio.sleep(30)
        await ws.send(json.dumps({'action': 'ping'}))

async def main():
    while True:
        try:
            await connect()
        except Exception as e:
            print(f'Connection error: {e}')
        print('Reconnecting in 5 seconds...')
        await asyncio.sleep(5)

asyncio.run(main())

Quickstart Flow

Connect to WebSocket Endpoint

Establish a WebSocket connection with your API key:

wss://api.sbx.moduluslabs.io/v1/terminal-gateway/ws?x-api-key=your-api-key

Discover Available Terminals

Request a list of connected terminals:

{ "action": "getTerminals" }

Receive terminal list:

{
  "action": "terminalsResponse",
  "terminals": [
    {
      "deviceId": "TERM-001",
      "status": "online"
    }
  ]
}

Initiate Payment

Send a payment request to a terminal:

{
  "action": "payment",
  "terminalId": "TERM-001",
  "paymentRequest": {
    "transactionId": "TXN-20240115-001",
    "amount": "99.99",
    "currency": "USD",
    "paymentMethod": "CARD"
  }
}

Receive Payment Result

The terminal processes the payment and returns the result via push notification:

{
  "action": "paymentComplete",
  "terminalId": "TERM-001",
  "paymentResponse": {
    "transactionId": "TXN-20240115-001",
    "status": "SUCCESS",
    "amount": "99.99",
    "authorizationCode": "AUTH123456"
  }
}

Heartbeat / Keep-Alive

Send a periodic ping action (about every 30s) and expect a pong to keep the connection alive and detect stale sockets. The settings table and the full Node.js/Python heartbeat implementation are in Actions.

Testing Your Connection

Connect to the WebSocket endpoint

Verify successful connection by checking for the open event

Send getTerminals action

Verify you receive a terminalsResponse with available terminals

Test heartbeat

Send a ping and verify you receive a pong response

Test reconnection

Simulate a connection drop and verify automatic reconnection works

Quick Connection Test

const WebSocket = require('ws');

async function testConnection() {
  const ws = new WebSocket('wss://api.sbx.moduluslabs.io/v1/terminal-gateway/ws', {
    headers: { 'x-api-key': process.env.MODULUS_API_KEY }
  });

  ws.on('open', () => {
    console.log('1. Connection established');

    // Test getTerminals
    ws.send(JSON.stringify({ action: 'getTerminals' }));

    // Test ping
    setTimeout(() => {
      ws.send(JSON.stringify({ action: 'ping' }));
    }, 1000);
  });

  ws.on('message', (data) => {
    const message = JSON.parse(data.toString());

    if (message.action === 'terminalsResponse') {
      console.log('2. Terminals received:', message.terminals.length);
    }

    if (message.action === 'pong') {
      console.log('3. Heartbeat working');
      console.log('All tests passed!');
      ws.close();
    }
  });

  ws.on('error', (err) => {
    console.error('Test failed:', err.message);
  });
}

testConnection();

import asyncio
import websockets
import json
import os

async def test_connection():
    headers = {'x-api-key': os.getenv('MODULUS_API_KEY')}

    async with websockets.connect(
        'wss://api.sbx.moduluslabs.io/v1/terminal-gateway/ws',
        extra_headers=headers
    ) as ws:
        print('1. Connection established')

        # Test getTerminals
        await ws.send(json.dumps({'action': 'getTerminals'}))
        response = json.loads(await ws.recv())

        if response.get('action') == 'terminalsResponse':
            print(f"2. Terminals received: {len(response['terminals'])}")

        # Test ping
        await ws.send(json.dumps({'action': 'ping'}))
        response = json.loads(await ws.recv())

        if response.get('action') == 'pong':
            print('3. Heartbeat working')
            print('All tests passed!')

asyncio.run(test_connection())

Troubleshooting

Connection Rejected

Possible causes:

Invalid or missing API key
API key not authorized for WebSocket access
Network firewall blocking WebSocket connections

Solutions:

Verify your API key is correct
Contact support@moduluslabs.io to verify API key permissions
Check that outbound WebSocket connections are allowed on port 443

Connection Drops Frequently

Possible causes:

Heartbeat not implemented
Network instability
Firewall or proxy terminating idle connections

Solutions:

Implement heartbeat with 30-second ping interval
Check network connectivity
Configure proxy/firewall to allow persistent WebSocket connections

forceDisconnect Messages

Possible causes:

Multiple POS instances using the same API key
Previous connection not properly closed

Solutions:

Ensure only one POS instance uses each API key
Request additional API keys for multiple terminals
Implement proper connection cleanup on application exit

Messages Not Received

Possible causes:

Message handler not processing all action types
JSON parsing errors
Connection silently dropped

Solutions:

Log all incoming messages for debugging
Add try/catch around JSON parsing
Implement heartbeat to detect stale connections

Security Best Practices

Protect API Keys

Store API keys in environment variables, not in source code. Never expose keys in client-side JavaScript.

Use Headers

Prefer header-based authentication over query parameters to avoid keys appearing in logs.

Validate Messages

Always validate incoming message structure before processing to prevent errors from malformed data.

Secure Reconnection

When reconnecting, ensure you’re connecting to the legitimate endpoint. Validate SSL certificates.

Next Steps

Actions Reference

Learn how to send commands to terminals

Push Notifications

Handle real-time terminal and payment updates

Core Concepts

Device enforcement and reconnection resilience

API Reference

Complete schema reference for all data types

Get Started

QR API

Webhooks API

Onboarding API

Terminal Gateway API

Transaction Reporting API

Ecom API

Shared Resources

Overview

Prerequisites

API Credentials

WebSocket Client

Network Access

JSON Parser

WebSocket Endpoint

Authentication

Establishing a Connection

Quickstart Flow

Heartbeat / Keep-Alive

Testing Your Connection

Quick Connection Test

Troubleshooting

Security Best Practices

Protect API Keys

Use Headers

Validate Messages

Secure Reconnection

Next Steps

Actions Reference

Push Notifications

Core Concepts

API Reference

​Overview

​Prerequisites

API Credentials

WebSocket Client

Network Access

JSON Parser

​WebSocket Endpoint

​Authentication

​Establishing a Connection

​Quickstart Flow

​Heartbeat / Keep-Alive

​Testing Your Connection

​Quick Connection Test

​Troubleshooting

​Security Best Practices

Protect API Keys

Use Headers

Validate Messages

Secure Reconnection

​Next Steps

Actions Reference

Push Notifications

Core Concepts

API Reference

Overview

Prerequisites

WebSocket Endpoint

Authentication

Establishing a Connection

Quickstart Flow

Heartbeat / Keep-Alive

Testing Your Connection

Quick Connection Test

Troubleshooting

Security Best Practices

Next Steps