A merchant service, which accepts instruments in exchange for goods, and a cash-out service, which turns instruments back into money. They draw on one reserve, and a merchant is simply a participant who does both more often than most.
One sentence each. The merchant service lets a business hold a float of instruments, take payment at a till, give change, and settle at the end of a shift. The cash-out service lets any holder return an instrument and be paid, whether at a bank counter, through a merchant, or into their account. In both cases the instrument returns to the issuer's shelf — nothing is burned, and it can be issued again.
1 merchant account at the issuer, with the merchant role <role check: not built> 2 a float: instruments bought at denominations that suit its prices 3 a till: a device with one reader (online) or two (offline card float) 4 the till is enrolled, so its calls are attributable to the business
A merchant's float is chosen from the price points it actually charges. A shop selling $5 drinks wants $5 and $10 notes, not $1s; a grocery wants a full ladder down to the smallest note. The float is the merchant's working capital, and its size is the shop's decision.
GET /api/terminal/float what the till can give change from
POST /api/terminal/redeem customer note in, price paid, change out
the presented note retires to the issuer's shelf
change comes from the float, or into the customer purse
POST /api/purse/convert whole notes in the purse become an instrument
Each sale is one atomic step at the issuer: the presented instrument is retired, the shop is paid, and change is issued or handed over from the float. If two tills present the same note, exactly one wins and the other is told the note is spent. built
customer card → merchant card the note moves, erase-first merchant card → customer card change, out of the merchant's own slots reconnect read both cards, reconcile the record to them
No network is required between the two cards. The trade is provisional until the record catches up, and the shop's exposure is exactly the value on its merchant card. One caveat is not negotiable: a note cannot carry the issuer's signature, so an offline till is trusting the chip rather than the issuer. See the merchant page for the three ways to close that gap. designed
collected notes → redeemed for credit float → topped up from credit, or drawn on a credit line difference → the shop's margin for the shift
Without a sweep, a shop accumulates notes faster than anyone redeems them and the issuer's slot count grows with every sale. The sweep is the operation that keeps a till working tomorrow. not built
| Rail | What the holder does | What they get |
|---|---|---|
| Account | Cash out in the app or on the web | Credit at the issuer; the instrument returns to the shelf |
| Counter | Present the card to a bank or shop that accepts it | Money, or goods; the note retires and is recorded |
| Peer | Transfer to another holder | Nothing — the value moves, it is not withdrawn |
POST /api/tokens/cashout holder hands the instrument back
status → CASHOUT_REQUESTED
vault signs the redemption status → AVAILABLE, custody VAULT, held by the issuer
credit lands the holder's balance rises by the denomination
POST /api/vault/resell the same instrument, sold to somebody else
This is the rail that exists in full. Nothing is destroyed: the instrument keeps its signature and can be sold again, which is why a reserve does not shrink with each redemption. built
card + PIN possession proved inside the chip issuer record proves the instrument is unspent, in one atomic step payment money out, or a note deposited to the customer's card slot cleared the capability is retired from the card
Two checks, answering different questions: the PIN says the presenter may use this card, the record says the instrument has not already been spent. Neither alone is safe. partly built — reading and paying a presented slot works; the till application and the slot-clearing step do not.
An instrument is honoured because the issuer issued it and holds the backing, not because a card happens to hold a copy. Three records make that checkable:
A cash-out that fails any of these is refused with the reason stated. That is the service being honest rather than generous.
| Control | Why | State |
|---|---|---|
| Merchant role on the account | Otherwise any holder can call the till endpoints and pay themselves | not built |
| Per-sale and per-day caps | Bounds loss from a cloned card or an offline dispute | not built |
| Vault signer availability | A cash-out waits for a signature; a stopped signer looks like a stalled service | built, monitored by log |
| Reconciliation schedule | Cards do not travel, so daily is enough — and it must actually run | built, not scheduled |
| Customer due diligence | Cash-out is where a regulated issuer must know its holder | out of scope for the sandbox |
A merchant is a holder that redeems a lot and re-floats often. Two consequences follow, and they are the reason this page treats them together:
cards × slots. That is what the multi-card
enclosure exists to raise, and why the sweep and the float are not bookkeeping details.Sandbox deployment, USD, English. Test values, not money, and not redeemable for money. Each section marks what is built and what is designed; the difference matters more here than anywhere else in these documents.