A Local API session is the period between a Login and the following Logout. Nothing meaningful happens outside one: operations sent without a session fail with NotAllowed. This guide covers opening, verifying, maintaining, and closing sessions.
Opening a session — Login
Send a Login request when your POS application starts or reconnects — not before every payment. The request carries your software identity (SaleSoftware: name, provider, version); keep it accurate, it appears in support logs.
A successful LoginResponse includes POISystemData describing the terminal: software versions, status, and the POISerialNumber.
Verify the serial number — hardware swap detection
On first login, persist the POISerialNumber. On every subsequent login, compare it. A changed serial number means the physical terminal was replaced — your POS should surface this to the merchant (and, depending on your policies, require re-validation) rather than silently continue. Terminal swaps are routine in stores; undetected swaps are how transactions end up on the wrong device.
During the session
- A Diagnosis request verifies the terminal is reachable and healthy, and reports pending offline transactions. Use it as your connection test and before daily opening.
- Busy state: if the terminal is already processing, new requests return
ErrorCondition: Busy. Wait and retry — do not queue a second payment. - One operation at a time: the terminal processes a single service request at once. Start a second operation while one is running and it is rejected (on HTTP this surfaces as
403 Forbidden— see Transport bindings).
Session expiry and re-login
If the terminal restarts, upgrades its firmware, or the session times out, subsequent requests return ErrorCondition: LoggedOut. The recovery is always the same: re-Login, verify the serial number, then resume. Build this into your client as an automatic path — it is normal operation, not an error.
Tip
After a firmware upgrade the terminal may take some time to return to service. Diagnosis is the polite way to wait: poll it until GlobalStatus is OK, then re-Login.
Closing a session — Logout
Send a Logout request when the POS shuts down. Logging out releases the session cleanly; the next Login starts fresh.
Related
- How the message model works — the message rules that apply inside a session.
- Troubleshooting: NotAllowed / LoggedOut errors — diagnosis when session state and reality disagree.
- Troubleshooting: hardware swap detected on login — the operational procedure.