Skip to main content

​
Overview

Four concepts govern how the Terminal Gateway behaves, across both the HTTP and WebSocket APIs:
  • Terminal ID resolution - how a terminalId maps to a physical device
  • Single device enforcement - one active connection per API key
  • Reconnection resilience - a grace period when a terminal drops mid-payment
  • Desktop POS recovery - never losing a payment result after a disconnect
This page explains the behavior. For the exact message shapes see the WebSocket guides; for request and response fields see the API reference.

​
Terminal ID resolution

When you address a terminal, the terminalId you send is resolved in order:
  1. Device ID (recommended) - matched first against the registered deviceId. A deviceId is stable: it survives reconnection, when the underlying connectionId changes.
  2. Connection ID (legacy fallback) - if no deviceId matches, the value is treated as a raw connectionId for older integrations.
Always address terminals by deviceId. It is stable across reconnects and is what enables reconnection resilience during a payment.

​
Single device enforcement

One API key allows one active connection at a time. When a second device connects with the same key, the existing connection is displaced and the new one becomes active.

Security

Blocks simultaneous use from multiple locations.

Consistency

One source of truth for terminal state and payment flow.

Auditability

Clear, single connection to trace per key.

Resource management

No duplicate connections to exhaust resources.
The displaced WebSocket connection receives a forceDisconnect message (reasons include the key being used elsewhere, a stale-connection timeout, or an admin action). Handle it by informing the user and, if reconnectAllowed, reconnecting. The message shape and every reason are in WebSocket Notifications.
Use a separate API key per terminal or workstation. Running two clients on one key means each connection keeps displacing the other.

​
Reconnection resilience

A terminal addressed by deviceId is protected if it drops mid-payment. The transaction does not fail immediately - it moves to AwaitingReconnect and waits about 60 seconds for the terminal to return.
If the terminal comes back after the grace period with a successful result, the payment is automatically voided so a customer is never charged for a result you never saw. Your POS is told via a paymentVoided notification; surface it to staff so an “approved” terminal screen is not mistaken for a collected payment. The notification shape is in WebSocket Notifications.
There is no persistent message queue. Beyond the grace window, the transaction status query is the authoritative source of a payment’s result.

​
Desktop POS recovery

A desktop POS that disconnects after starting a payment recovers the result two ways: Query it with GET /v1/transactions/{transactionId} (HTTP) or the getTransactionStatus action (WebSocket). See the Retrieve Transaction reference for the response, and the HTTP Quickstart for a worked example.
A payment result can reach you twice - from a reconnect and again from a status query. Make your result handler idempotent: key on transactionId and apply each result once.

​
Next Steps

Authentication

HMAC request signing

API Reference

Request and response fields

HTTP Quickstart

Your first HTTP calls

WebSocket Notifications

Every event message shape