WebSocket Stream/openSession

Open a Session

Stream transaction lifecycle events in real time.

WS/v1/session

Open a WebSocket to drive transactions and stream their lifecycle in real time. Send JSON action messages — sale, pre_auth, card_read, complete, display, input, abort — and receive a sequence of typed events as the transaction progresses. Events are a discriminated union on the event field, so a single switch statement is enough to drive your POS UI from waiting_for_card all the way through to result. The session is designed to survive flaky networks: the terminal keeps running its transaction even if the POS disconnects, and a resume token lets the POS reconnect and pick up the event stream exactly where it left off.

Sale lifecycle

~5–15 seconds

What happens after a single POST /v1/transaction/sale. Each step is also emitted as a WebSocket event if you connect a session in parallel.

Request body

application/json

actionenumrequired

The action to initiate.

salepre_authcard_readcompletedisplayinputabort

amountinteger

Required for sale/pre_auth.

currencystring

Required for sale/pre_auth.

entryModeenum

Optional card entry mode.

CONTACTLESSCONTACTAUTO

referenceIdstring

POS-assigned reference identifier.

granularboolean

Set true to run in granular mode and receive online_authorization events.

transactionIdstring

Required for complete and abort.

responseCodestring

ISO 8583 response code (complete action).

authorizationCodestring

Issuer auth code (complete action).

NOTES

Local: ws://terminal:8443/v1/session
Cloud: wss://api.atlas-softpos.com/v1/session
Include the X-Api-Key header on the initial upgrade request, or append ?apiKey=... to the URL.
For granular mode, set "granular": true in the sale action and respond with a complete action after authorization.
Heartbeat: the terminal sends a ping frame every 15 seconds. Reply with pong within 5 seconds or the terminal will close the connection with code 1011.
Resume tokens: every event includes a sessionId and eventSeq. To reconnect, send { "action": "resume", "sessionId": "...", "lastEventSeq": N } as your first message — the terminal replays any events you missed.
Mid-transaction disconnect: the terminal keeps running the transaction. On reconnect within 60 seconds, you receive all missed events in order and the current lifecycle state. After 60 seconds the session is garbage-collected; use GET /v1/transaction/{id} to recover the final result.
Unattended / kiosk mode: include "autoAbortMs": <ms> on the sale action. If the POS stays disconnected past this deadline while the terminal is waiting_for_card, the terminal aborts and releases for the next transaction.

commerce-api/openapi.yaml · openSession