Skip to content
Sitora Docs

Customer displays

A customer display shows the guest what is happening at the till. It reads one endpoint and renders what it gets:

GET /api/payments/v1/devices/display/
If-None-Match: "<last etag>"
{
  "state": "qr",
  "order_display_number": 118,
  "amount": "100000.00",
  "currency": "UZS",
  "qr_payload": "https://checkout.example/…",
  "intent_status": "presented",
  "server_time": "2026-08-09T12:00:11Z"
}

States

Section titled “States”
state Show
idle Your branding, the time, whatever the venue wants
total The order number and the amount to pay
qr The amount plus qr_payload rendered as a scannable code
paid A brief confirmation of the amount just paid

paid is shown for a short window after settlement and then returns to idle on its own. Do not latch it.

qr_payload is only for devices that may render it

Section titled “qr_payload is only for devices that may render it”

The payload is included only when the device declares qr_dynamic_present. A display registered without that capability receives an empty string on every read — the capability is enforced server-side, not by asking you to behave. Render exactly what you are given, unchanged.

The payload is a provider’s own checkout reference. It contains no secret, and it is not yours to rewrite, shorten, or wrap in a redirect.

Polling

Section titled “Polling”

Poll with If-None-Match; unchanged state answers 304 with no body, which keeps a tight cadence cheap.

How tight is Sitora’s call, not yours. Every response carries X-Sitora-Poll-After and Retry-After, both holding the same number of seconds to wait before the next read — two, today. Obey it and do not hard-code it: the number can be raised fleet-wide without any release of yours. Retry-After on a 200 or a 304 is pacing, not an error. The endpoint is also throttled per credential, but that is enforcement of last resort — a display that obeys the header never meets it.

Realtime push is deliberately not offered. Polling is the contract.

When the platform is frozen

Section titled “When the platform is frozen”

Displays exist to present provider-driven collection, so their plane freezes with it: under a platform freeze a display credential is refused with platform_frozen. Show a neutral idle screen and keep polling — the freeze lifts without any action from you.

Meanwhile the till keeps working. Cash and attested-terminal collection survive every freeze by design, so a dark display never stops a restaurant from taking money.