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
Version 1.0 - This documentation covers the current Terminal Gateway API. Contact support@moduluslabs.io to obtain your endpoint URL and credentials.
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
HTTP API
Choose HTTP if you need:
- Simple request/response pattern
- Serverless or stateless architecture
- Minimal client-side complexity
- Occasional terminal interactions
WebSocket API
Choose WebSocket if you need:
- Real-time terminal status updates
- Instant payment notifications
- Multi-terminal management
- Persistent connection with push events
API Endpoints
- HTTP API
- WebSocket API
| Endpoint | Description |
|---|---|
GET /v1/terminals | List available terminals |
POST /v1/terminals/{terminalId}/payments | Initiate a payment |
GET /v1/transactions/{transactionId} | Check transaction status |
Quick Start
Obtain API credentials
Contact support@moduluslabs.io to request API credentials. You will receive an API key and API secret pair.
Choose your protocol
Select HTTP for simple integrations or WebSocket for real-time features. See the protocol comparison above.
Core Concepts
Both protocols share these core concepts:Single Device Enforcement
One active connection per API key for security
Reconnection Resilience
60-second grace period for terminal reconnections during payments
Authentication
API key provisioning and authentication methods
Data Types
Shared schemas for payments, terminals, and errors
Documentation Structure
HTTP API
- Quick Start - Get started with HTTP
- Endpoints - Complete endpoint reference
WebSocket API
- Quick Start - Connection and setup
- Actions - Commands you can send
- Notifications - Events you receive
Support
For technical support or questions about the Terminal Gateway:- Email: support@moduluslabs.io
- Documentation: Browse the pages in this section for detailed implementation guides