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

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

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

Poll with If-None-Match; unchanged state answers 304 with no body, which keeps a two-second cadence cheap. The endpoint is throttled per credential and sized for that cadence with headroom.

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

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.