> ## Documentation Index
> Fetch the complete documentation index at: https://docs.moduluslabs.io/llms.txt
> Use this file to discover all available pages before exploring further.

# Terminal Gateway

> Real-time communication between your POS system and payment terminals via HTTP or WebSocket

## Overview

The Terminal Gateway enables communication between your POS (Point of Sale) system and payment terminals. Choose between two protocols based on your integration needs:

* **HTTP API** - Synchronous request/response pattern with long-polling for payments
* **WebSocket API** - Real-time bidirectional communication with push notifications

<Note>
  **Version 1.0** - This documentation covers the current Terminal Gateway API. Contact [support@moduluslabs.io](mailto:support@moduluslabs.io) to obtain your endpoint URL and credentials.
</Note>

## Protocol Comparison

| Feature                | HTTP API                        | WebSocket API                                   |
| ---------------------- | ------------------------------- | ----------------------------------------------- |
| **Communication**      | Request/response (synchronous)  | Bidirectional (asynchronous)                    |
| **Connection**         | Stateless, per-request          | Persistent connection                           |
| **Payment flow**       | Long-polling (up to 90 seconds) | Push notification on completion                 |
| **Terminal discovery** | Poll `GET /terminals`           | Real-time `terminalStatusUpdate` events         |
| **Best for**           | Simple integrations, serverless | Real-time dashboards, multi-terminal management |
| **Authentication**     | HMAC-SHA256 per request         | API key at connection time                      |
| **Complexity**         | Lower                           | Higher                                          |

## Choosing a Protocol

<CardGroup cols={2}>
  <Card title="HTTP API" icon="server" href="./http/quickstart">
    **Choose HTTP if you need:**

    * Simple request/response pattern
    * Serverless or stateless architecture
    * Minimal client-side complexity
    * Occasional terminal interactions
  </Card>

  <Card title="WebSocket API" icon="bolt" href="./websocket/quickstart">
    **Choose WebSocket if you need:**

    * Real-time terminal status updates
    * Instant payment notifications
    * Multi-terminal management
    * Persistent connection with push events
  </Card>
</CardGroup>

## API Endpoints

<Tabs>
  <Tab title="HTTP API">
    ```text theme={null}
    https://{your-api-endpoint}/v1
    ```

    | Endpoint                                   | Description              |
    | ------------------------------------------ | ------------------------ |
    | `GET /v1/terminals`                        | List available terminals |
    | `POST /v1/terminals/{terminalId}/payments` | Initiate a payment       |
    | `GET /v1/transactions/{transactionId}`     | Check transaction status |
  </Tab>

  <Tab title="WebSocket API">
    ```text theme={null}
    wss://{your-api-endpoint}/v1
    ```

    Connect with your API key via headers or query parameters.
  </Tab>
</Tabs>

## Quickstart

<Steps>
  <Step title="Obtain API credentials">
    Contact [support@moduluslabs.io](mailto:support@moduluslabs.io) to request API credentials. You'll receive an API key and API secret pair.
  </Step>

  <Step title="Choose your protocol">
    Select HTTP for simple integrations or WebSocket for real-time features. See the [protocol comparison](#protocol-comparison) above.
  </Step>

  <Step title="Follow the quick start guide">
    <CardGroup cols={2}>
      <Card title="HTTP Quickstart" icon="rocket" href="./http/quickstart">
        Get started with HTTP API
      </Card>

      <Card title="WebSocket Quickstart" icon="rocket" href="./websocket/quickstart">
        Get started with WebSocket API
      </Card>
    </CardGroup>
  </Step>
</Steps>

## Core Concepts

Both protocols share these core concepts:

<CardGroup cols={2}>
  <Card title="Single Device Enforcement" icon="shield" href="./concepts#single-device-enforcement">
    One active connection per API key for security
  </Card>

  <Card title="Reconnection Resilience" icon="rotate" href="./concepts#terminal-reconnection-resilience">
    60-second grace period for terminal reconnections during payments
  </Card>

  <Card title="Authentication" icon="key" href="./authentication">
    API key provisioning and authentication methods
  </Card>

  <Card title="Data Types" icon="brackets-curly" href="./reference">
    Shared schemas for payments, terminals, and errors
  </Card>
</CardGroup>

## Documentation Structure

<CardGroup cols={2}>
  <Card title="HTTP API" icon="server">
    * [Quickstart](./http/quickstart) - Get started with HTTP
    * [Endpoints](./http/endpoints) - Complete endpoint reference
  </Card>

  <Card title="WebSocket API" icon="bolt">
    * [Quickstart](./websocket/quickstart) - Connection and setup
    * [Actions](./websocket/actions) - Commands you can send
    * [Notifications](./websocket/notifications) - Events you receive
  </Card>
</CardGroup>

## Support

For technical support or questions about the Terminal Gateway:

* **Email:** [support@moduluslabs.io](mailto:support@moduluslabs.io)
* **Documentation:** Browse the pages in this section for detailed implementation guides