The commonest sale was the one that would have failed
Card payments on a tab carried a reference. Ordinary counter sales carried none — and the card company requires one. The rare path worked; the frequent one would have been refused on the first press.
A card payment needs a reference: a short string that ties it to something. Without one, a payment on an acquirer's statement is a number with no story, and the first time somebody disputes a charge you have nothing to look it up by.
Our card-reader code refuses a sale that has no reference. Good rule. The till
supplied one — tab-7 — whenever the sale was against an open tab.
For an ordinary counter sale, it supplied nothing.
The shape of the mistake
Someone walks up, orders two tacos, taps a card, leaves. No tab, no table, no name. That is the majority of what a food hall counter does, and it was the one case that would have been refused — with a message about a reference, which is not something anybody behind a counter can act on.
The tab case is the unusual one. It got the attention because it was the one somebody was thinking about when they wrote it. The common case fell through a gap nobody looked at, because it did not need anything added — it just needed the thing that was already there to happen every time.
What a counter sale is called
A counter sale has no order number yet when the card is charged. The order is written down after the reader approves it, which is the whole point of letting the reader decide. So the reference cannot be an order id.
It is now the thing a person would actually use to find that payment in the
card company's own list: the venue, the counter, and when.
hp-8-front-till-tl4h8g. Short, because acquirers truncate. Our
prefix first, so ours stand out among a merchant's other traffic. A tab keeps
its own — hp-tab-7 — because a tab genuinely has a better name
available.
There is no "no reference" answer any more. A function that could return one would only move the refusal somewhere harder to find.
A caveat that still stands
None of this has taken a payment. Card processing through HelchPOS is not switched on: the reader integration is written, tested against the card company's published shapes, and has never charged a real card. Card at the till is still taken on the venue's own terminal and recorded here. What changed is that the first real attempt will fail for a real reason rather than a typo.