Kiosk-X: manufacturer, machine, fleet and release handover

Open the illustrated installation atlas and cabinet checklist.

Instructional illustration; screens and device details vary. Follow the exact steps and approved release record below.

Use this as the handover record for each cabinet and each release wave. A working website, passing software tests, an uploaded signature and a successful physical sale are separate pieces of evidence. Record all four where applicable.

Start in the right place

The public website is https://kiosk-x.ai. The operator console is https://operator.kiosk-x.ai. The device gateway, Partner API, downloads and hosted guides are on https://api.kiosk-x.ai. The operator app belongs on the operator's phone; the ZHZN vending APK belongs on the vending machine. A Reyeah vending APK is a different hardware-family artifact. Do not identify any of these by its filename alone.

One record per physical machine

Before production, assign a serial and record the cabinet model, head-unit model, Android version, supported CPU ABI, VMC model/firmware, actual shelf/coil geometry, drop sensor configuration, serial-port wiring, MDB reader model and accessories. Photograph the rating labels and physical coil labels. Record the APK package, versionName, versionCode, SHA-256 and signing certificate, plus backend and operator release identifiers. Never place a device key, password or invite token in this handover record.

Keep identity separate from the equipment's current owner: cabinet serial, Android device ID, per-device cloud credential, Nayax Device Number and operator account are different identifiers. Preserve leading zeros in a reader's Device Number. A replacement head unit needs a controlled re-enrolment; copying another cabinet's storage is not a replacement procedure.

End-to-end acceptance sequence

The cloud onboarding checks currently cover ownership, online contact, payment configuration, usable stocked inventory and the dispensing guard. paymentsReady accepts a bound non-provisional card reader or live Stripe configuration with a webhook secret and a supported operator currency; test keys do not qualify for QR-only go-live. This is a configuration check, not a processor health probe, country-availability check, merchant onboarding check or physical acceptance certificate. Older backends may return only nayaxBound; update the backend before relying on QR-only readiness. Operators cannot force incomplete setup live. Full-admin override is restricted to a non-production sandbox.

Daily operation of one machine

1. Open Machines and select the exact serial, not only the venue nickname. Check freshness of the last contact, board/reader state, stock and unresolved orders. A machine can be online while unable to dispense or take payment.
2. Check physically available inventory against the planogram before replenishing. Remove damaged/expired products according to the operator's procedure. Enter the quantity actually present. Clear a fault only after its cause is corrected.
3. For a changed product, confirm dimensions, coil fit, price, currency and age policy. Test the changed slot before reopening sales. Count later shelves too; a successful first shelf does not prove row/column mapping everywhere.
4. Reconcile paid-without-delivery, partial delivery, pending captures/refunds and offline-originated orders. A request for a refund is not a completed refund. Keep the processor transaction reference and resolve the shopper's case once.
5. Schedule maintenance and software changes when no shopper transaction is active. Check the tray and pending payment first; do not use a reboot to clear an uncertain payment. After repair, recheck readiness and the affected sale path before returning to service.
6. Close the service menu, remove service media, lock the door, test the Home screen and confirm the public support label is legible.

Operating a fleet

Assign an accountable fleet manager and a local responder for every location. Keep a daily exception queue ordered by customer impact: paid/no delivery or uncertain payment, unsafe/damaged cabinet, offline board, unavailable payment, low stock, and release follow-up. Include serial, location, last known contact, owner, assigned responder, time detected, next action and resolution evidence. Do not close a case because its last telemetry row is green.

For each restock run, select only machines accessible to the signed-in operator, use the latest inventory, calculate pick quantities and recheck at the cabinet. Offline readings may lag physical sales. If any page or inventory request fails, the fleet count and pick list are incomplete; reload or split the run. The web fleet loader reports its supported limit rather than silently discarding machines.

Team invitations are pending until accepted by the named account. Copy and share the generated invitation link through the operator's approved channel; the current backend returns delivery: manual and does not send invitation email. The recipient opens the link, signs in with the invited email and explicitly accepts. Expired or wrong-account invitations require correction; ownership cannot be reassigned with the member role controls. Crew membership currently does not grant another owner's machine API scope. Verify the assigned person's actual machine access before dispatching them; use the platform's supported tenant/access workflow for delegated fleet access.

Invitation creation, acceptance and crew edits report a save failure instead of publishing an unpersisted change. Acceptance reads the current invitation and crew from the shared store when fleet sync is active; a stale replica cannot use an already-consumed token or a removed inviter's old role. Keep invitation links private and never add them to machine handover records.

Coordinate crew changes through one administrator at a time. Crew snapshots are not protected by a cross-replica transaction or compare-and-swap update, so simultaneous changes can overwrite each other. Invitation consumption and membership are separate durable writes. If acceptance fails after the link has been consumed, check the actual member list and issue a new invitation when needed; retrying the consumed link does not restore removed access. When the shared record cannot be read, the operation fails closed with an unavailable response instead of trusting a stale local grant. Refresh and resolve the save/read error before dispatching the person to a machine.

For relocation, record the destination and venue timezone, reconcile outstanding orders and count stock before the move. Repeat network, board, payment, product and support-label checks at the new location. For resale/RMA, preserve historical orders with their original owner, reconcile captures/refunds, revoke or rotate the cabinet credential through the supported workflow and document reader ownership separately. A serial claim does not transfer the Nayax merchant actor. Do not delete app storage until pending reports and replacement credentials are accounted for.

Release qualification by market and hardware

Do not treat “global” as one machine configuration. Create an acceptance row for every supported combination of market, language, currency, Android/head unit, board protocol, reader/profile and accessory set. A region with no completed row is unqualified for this release, even if another region passed.

New orders snapshot currency so an account currency change cannot reinterpret a past sale. Orders created before currency metadata existed retain the USD legacy interpretation. Provider precision can differ from ISO currency precision; unsupported or nonrepresentable Stripe amounts are refused before payment rather than rounded into a different charge. This does not certify every currency or processor account worldwide. See the gateway currency tests and release evidence.

Sales summaries and refund queues keep different currencies in separate groups. Unavailable or a dash does not mean zero. Read the currency on each period, order and exported CSV row; the account's current currency does not relabel an older sale. CSV amounts retain the sale currency's decimal precision. Machine detail and recent-history views name their limited scope; use the full server summary for fleet totals. Tax and cost accounting is currently validated only for USD; non-USD order summaries leave those figures unavailable. Complete the destination's accounting/reconciliation acceptance before approving that market.

If a refund response is interrupted, its outcome is unconfirmed. Refresh the original order and check the processor reference before retrying; a network error does not establish that no money moved.

The hosted QR checkout keeps the same request reference while an order-opening response is missing, including after a screen reload. Retrying that request returns its saved outcome; it must not create another charge. A changed cart is blocked while the first request remains unresolved. If the screen says the payment request is still being confirmed, check the original order and processor records with support. Do not clear browser/app storage or create a fresh request to bypass the hold. An interrupted request has no automatic expiry or takeover; support must reconcile it before another payment. Legacy integrations that send no request reference do not gain this retry protection merely by sending the same cart twice.

If a processor's captured amount or currency differs from the agreed receipt, the accounting pages show Reconciliation required and withhold affected totals. Review each capture and refund in its actual currency, retain the agreed receipt, and resolve the discrepancy before using the P&L, balance sheet or trend for a financial decision. An unavailable total is not a zero balance.

The local card route accepts one product line and one unit per purchase. The hosted card endpoint and cabinet enforce this limit before starting the reader. Do not use a multi-unit card request to approximate a basket: partial unit delivery cannot be represented safely by that cashless session. Resolve each payment and dispense before starting another purchase.

The current Nayax Spark integration accepts USD only because terminal currency negotiation has not been verified for other denominations. A bound reader does not establish Spark support for a non-USD operator. Verify any separate local MDB route against that reader's actual currency and decimal scale; do not infer its support from a Spark or software-only test.

With capture-after-delivery enabled (SCANPAY_MANUAL_CAPTURE), Scan & Pay accepts one product line and one unit per checkout; multiple product lines or a quantity above one are refused before authorization. Existing multi-product or multi-unit sessions that share one processor hold must be reconciled together at the processor; per-line capture or cancellation is blocked and remains an operator review item. Do not promise multi-product manual settlement, or ask the shopper to repay a cart whose earlier authorization is unresolved.

Release sequence and rollback

1. Reconcile the candidate against the source revisions currently deployed. This workspace can be older than the public download. Carry forward fixes and published guides from the deployed branch; do not deploy an older checkout as a replacement for a newer production build.
2. Build a release with the approved signing key and a versionCode above every supported installed target. Inspect the actual package, ABI, minimum SDK, version and certificate. A debug APK and a bundled sample APK are bench artifacts, even when unit tests pass.
3. Publish the exact bytes to an immutable version-and-digest URL. Fetch the published bytes and compare SHA-256. The download button, APK manifest, release description and OTA descriptor must name those same bytes.
4. Deploy compatible backend routes and publish matching guides before offering an APK that requires them. Verify the operator web build and the actual distributed operator APK separately: Flutter tests do not validate a Kotlin/Compose artifact built from another source directory.
5. Start with a named, staffed bench/canary cohort covering each hardware and market profile. Verify reboot, device-key contact, native factory report, one sale per enabled route, failures, outage recovery and order reconciliation.
6. Check adoption and return-to-service evidence before widening. Compare before and after: contacts, usable stock, sales, failed/uncertain vends, captures, pending reports and refunds. Stop a wave for a new unexplained payment, dispensing, credential or startup fault.
7. Expand in documented cohorts and maintain a per-machine outcome: pending, offered, downloaded, installed, returned online, sale verified or blocked with an owner and next action. Do not convert missing evidence into success.
8. For rollback, prefer a corrected forward release with a higher versionCode. Android may refuse a downgrade or a different signing certificate. Any attended reinstall must preserve/recover device identity and pending reports; do not prescribe a blanket uninstall as a remote rollback.

Failure and recovery acceptance matrix

Handover signatures

For each machine record the manufacturer QA signer, receiving inspector, installer, operator owner and release approver with timestamp, serial and the evidence references above. Mark each result pass, fail, not fitted or not tested, with a reason. “Not tested” remains unfinished. Record the release wave and every outstanding item with its owner. No final signature should hide an unresolved payment, dispensing, identity or installation failure.