Most payments APIs assume a browser or a server. Square's original trick was a plastic reader on a phone jack, then a parade of hardware, plus APIs that developers call from POS apps. The charge still has to clear a card network. That means firmware, BLE or Lightning or USB, a merchant's terrible Wi-Fi, and a cloud that must not double-charge because the reader timed out. Hardware and API teams that do not share a transaction identity will learn about that coupling from chargebacks.
The reader is an untrusted, intermittent computer
A Square reader captures PAN data in a PCI-shaped boundary, encrypts it, and hands a payload to the POS app, which should never see raw card numbers. That payload is not a completed payment. It is an intent that the cloud and the acquiring stack must authorize. Offline mode — store-and-forward when the cafe has no uplink — is a product feature that is also a risk feature. You have taken on deferred authorization. Declines that happen later are a merchant-education problem and a ledger problem.
Firmware versions fragment the fleet. A protocol change between reader and app must be backward compatible or you brick a farmer's market on Saturday. Square's developer docs for Readers and Terminal APIs exist because third-party POS software is now in that handshake. The hardware is a platform.
APIs that look like REST still start at the counter
Square's Payments API, Orders API, and idempotency keys are how a tap becomes a server-side object a merchant can refund. The POS may retry. The reader may fire two callbacks. The app may crash after the card is approved at the network but before local UI updates. The cloud object is the source of truth; the device UI is a cache. Receipt printers and kitchen displays are more caches.
Inventory and catalog sync sit next to payments because a coffee shop thinks in items, not in payment intents. That is a distributed systems problem wearing a menu: eventual consistency between devices on the same account, with conflict rules when two registers sell the last muffin.
Failure modes at the hardware/API seam
The concrete failure is a client that treats a reader timeout as a failure and starts a new payment without the same idempotency key. The cardholder sees two holds. Mid-size steal: one client-generated idempotency key for the whole tap-to-completion lifecycle, stored on device before the reader is invoked, surviving app restart.
Operational gotcha: offline queues that never drain, then dump a day's charges into the network at once and trip velocity fraud rules — including Square's own. Pace the replay. Another is clock skew on the device so "offline authorized at 2 a.m." looks fraudulent. Use server time as soon as you reconnect. Firmware that allows a debug interface in production readers is a PCI incident. Signed firmware and a rollback plan matter as much as API versioning. If you build hardware+API, run a lab that includes packet loss to the cloud, BLE flakiness, and a killed app mid-tap. Contract tests between firmware and API schemas belong in CI. Do not let the POS invent a second payment identifier that support cannot search. The dashboard should find the charge by the same id the receipt shows.
What you can borrow
- Create the idempotency key before talking to the reader, and persist it across process death.
- Treat device UI as a cache of cloud payment state, especially after offline mode.
- Version firmware like an API, with signed updates and a Saturday-safe rollback.
- Replay queued authorizations with pacing and server-side clocks so risk systems see reality.