Most Cloud API failures surface as a 404 — either the terminal cannot be reached from the cloud, or the request is addressed wrongly. Work through the three groups below.
404 — the terminal is not reachable
The terminal is not connected to the cloud, so the platform cannot route to it. Confirm with GET /terminals; if it is not listed (or shows connected: false), it is offline. Common causes and fixes:
| Root cause | How to check | Fix |
|---|---|---|
| Master App (launcher) did not start | Terminal missing from GET /terminals; check NTMS shows it active/provisioned | Ask the client to launch the Master App manually |
| Master App version too low or buggy | 1.0.7.1 has no WebSocket support; 4.3.0 is known-buggy | Update the Master App (for example 4.4.0 instead of 4.3.0) and trigger a terminal update |
| Cloud API / WebSocket not configured | Check the Cloud configuration in Spring is set as integrated | Enable the Cloud API on the device, applying WebSocket config at group level if needed |
| Terminal in power-saving mode | Screen shows the default saving-mode bubbles | Disable saving mode on the terminal |
| Wrong store code | Confirm the store code is the one assigned to the terminal | Use the correct store code |
404 — the request is addressed wrongly
| Root cause | How to check | Fix |
|---|---|---|
| Terminal ID case | The manufacturer prefix is case-sensitive: pax:… fails, PAX:… works | Send the prefix in UPPERCASE, e.g. PAX:2290337902 |
| Currency mismatch | Compare request currency (e.g. 978 EUR) with the terminal's configured currency (e.g. 752 SEK) | Send the currency configured on the terminal |
Wrong environment
Using a production terminal against the staging URL (or vice versa) also fails. Confirm the base URL:
- Production —
https://eci.market-pay.com - Pre-production —
https://eci-stg.market-pay.com
ecrTransactionId rejected
If a request is rejected on the ecrTransactionId, it exceeds the 35-character limit. Shorten it — a raw 36-character UUID will not fit.
Immediate 500 with a stale connection
An immediate 500, combined with the terminal still showing in GET /terminals with an unchanging wsCreatedTime, usually means a stale / half-open cloud connection rather than a busy terminal. Force the connection to re-establish (block/unblock in the Hub, or reboot the terminal) — and always check GET /last-transaction first for financial safety.