Pass

ALWAYS answers the same way, whether or not the contact matches anybody. A response that differed would turn this endpoint into a directory of who holds a ticket to tonight's event, which is exactly the kind of thing an event's guest list must not leak (OWASP: no user enumeration on an unauthenticated surface).

THE MISSING STEP between "the box is registered" and "the desk can issue one". Stock is registered by a platform operator, whose session carries NO tenant, so the row lands with tenant_id = NULL — the pool. Issuing reads BandService::find, which is scoped where tenant_id = $ctx->tenantId, so a desk holding an organizer's session can never see a pooled tag: it answers unknown_band and the steward is told the wristband is not registered, which is exactly what a genuinely unregistered one says.

Found live on 2026-08-25: three sample tags Eric had added sat in the pool, and the only mover was /v3/portal/band/{serial}/school — a surface an event console cannot reach. The tags had to be moved by hand with an admin token.

PLATFORM ONLY, on the same fence as {@see index}: the pool is Terra's inventory, and a venue that could pull from it could hand itself credentials nobody paid for. That is the whole reason the whitelist exists.

Read from the query rather than resolved from the device row, because a handset is moved between stations during a night — the till's own picker already knows where the steward is standing, and pay resolves the settlement zone from the device independently. Omitted, the whole tenant's catalogue comes back, which is what every caller got before and what a single-bar venue still wants.

Rides the surface-neutral {@see WebDeviceService} (the same read the school console uses) and re-projects at THIS surface: pass has no schools, so the row carries the device, its zone and its derived presence — vocabulary at the surface, one query underneath.

Beside the shifts and not inside them on purpose: a desk top-up is not attributable to a till. Nobody's drawer is short because of it, and folding it into a steward's ledgered figure would make a shift answer for money it never handled.

404 when there is none. That is the handset's cue to show "open a shift" rather than a zeroed till, and the two are different states — a till showing Sh 0.00 with no shift open takes money nothing will account for.

What a desk reads when somebody is refused at a rope. The ticket row only ever shows the LATEST holder, so "who had this before, and when did it move" cannot be answered from it.

CURSOR-PAGED like every other list here, and not because a chain of custody is long — most are one move. It is paged because the contract has two answer shapes, data and dataList, and this is a list: declaring it as anything else put an untyped bag on the wire, which is what every SDK generated for it until now (Record<string, unknown>). A caller that never sends a cursor still gets the whole history in one read.

A desk doing what a guest could not: claiming an open seat for somebody standing in front of them with no smartphone, recording a resale, or fixing a name. The self-service channels reach the same {@see TicketService::changeHolder}, so the history reads identically whichever door the change came through — only channel differs, which is exactly the fact a dispute wants.

actor_user_id is stamped from the token and never from the body: "on whose authority" is not something a caller gets to assert.

create mints the root and nothing else, and until now the only zone write in the codebase was on the legacy WaaS surface — so an organiser could build an event in their own console and then had nowhere to put a gate or a bar.

Profile, wallet and the first page of tickets together: a fan opens this on mobile data outside a venue, and the same one-request doctrine the steward bootstrap follows applies with more force to somebody on a phone in a queue.

The most time-critical thing anybody does in this product: a lost band is somebody else holding your money, at a bar, now. Waiting in a queue at the Pass desk to have a staff member do this is the difference between losing nothing and losing the balance. BandService::transition busts the tap cache synchronously, so the next tap on that serial is refused rather than refused-eventually.

No serial in the body. The band is resolved from the principal, so a fan can freeze exactly one wristband — their own — and a mistyped or guessed serial cannot freeze a stranger's night out. Unfreezing is deliberately NOT here: lost -> active is a staff decision made by somebody looking at the person and the band together.

The one screen a fan opens when they think they were overcharged, so it reads the LEDGER rather than any per-event summary: the entries are what a dispute is settled against, and a second aggregate that disagreed with them would be worse than none.

The SAME PaymentIntentService::collect the parent app tops up a student through: an STK push, idempotent on the intent id so a retry on a venue's wifi cannot fire a second one. Nothing about money is reimplemented here; what this method adds is that the wallet is resolved from the PRINCIPAL rather than named in the body.

That is why preloading needs the wallet to exist at ticket-import time (SpendWallets): this endpoint funds a wallet, it does not conjure one. It will open theirs on first use as a backstop, for the fan whose ticket landed before that change.

The other half of "does leftover money follow the fan": it follows them, and when they want it in cash it goes to their M-Pesa. Owner's decisions, 2026-08-09 — the destination is the number ON THE ACCOUNT and cannot be named by the caller, a withdrawal may be made at any time rather than only after doors close, and the B2C send cost comes off the fan's amount rather than the organiser's pocket.

Almost none of this is new machinery. PaymentIntentService::payout() already holds the money BEFORE the provider is asked to send it, already puts the intent under a durable settlement watcher, and already reverses the hold when a send fails or times out. What is new is a fan-shaped door onto it, with a fee.

The console has offered this since #287 and terra answered 405: the button called a route that was never shipped, so an organiser setting up a stall an hour before doors was sent to another product's admin to mint the wallet.

A vendor IS a merchant wallet with a nameplate, so this creates both — there is no vendor row to create first and fund later, which is the same reason the list reports taken_minor as the wallet's balance rather than a figure kept beside it.