Building on it
Sales, returns, shifts
Two front doors, one engine. A terminal uses /v1/terminal/* with its session token (merchant, branch and terminal are
fixed by the token). The Operator backend or back office uses /v1/merchants/{merchantId}/*, naming the branch and (optionally)
the terminal by tid. Same handlers, same rules. Money is whole kobo; prices are VAT-inclusive (a line's tax is the VAT
already inside its net amount, net × 7.5 / 107.5, rounded half away from zero).
Recording a sale — POST /v1/terminal/sales · POST /v1/merchants/{id}/sales#
{ "saleId": "<uuid>", "occurredAt": "2026-11-16T10:02:11+01:00", "shiftId"?, "receiptNo"?, "cashierRef"?,
"lines": [{ "variantId", "quantity", "unitPriceKobo", "discountKobo"? }],
"tenders": [{ "type": "Cash|Card|Transfer|Other", "amountKobo", "rrn"?, "stan"?, "tid"?, "maskedPan"?, "authCode"?, "reference"? }],
"expectedTotalKobo"?, "note"? }Optional header Idempotency-Key. Response { receipt, replayed, warnings }; the receipt is print-ready (the business's name leads;
ours never appears).
- The charged price wins. The terminal may have sold from a stale cache; we record what the customer paid and add a
price_differs:SKUwarning rather than refuse. - Tenders.
cash + non-cashmust cover the total. Only cash may exceed it (that is change); a card or transfer may not. - Idempotent by
saleId. Replay →200with the original receipt and no second stock move or receipt number. Same id, different contents →409 idempotency_conflict. A reusedIdempotency-Keyfor a different sale →409. Ten identical requests at once create one sale (the sale row is written first, so a duplicate fails before stock moves). - A paid sale is never refused for lack of stock. Stock may go negative; the shortfall is a
warnings: ["oversold:SKU:n"]entry and an oversell alert a manager acknowledges (GET/POST …/oversells). Untracked items (services) never move stock. - Receipt numbers. If the device printed one offline, send it and we keep it verbatim. Otherwise we assign
{TID}-{000001…}, gapless (counter in the same transaction; a rolled-back sale gives its number back). - Time. Send
occurredAt(any offset;+01:00is fine — stored as UTC). A device clock >5 min ahead is flaggedfuture_clockand reported at our receive time; older than 7 days is flaggedvery_old. Both are still accepted. - Cost of goods is snapshotted per line from the ledger (the average cost the stock left at).
What gets refused, and how#
| status | meaning | retry? |
|---|---|---|
400 |
malformed request (bad shape, zero quantity, anything that looks like a card number) — nothing is stored | fix the device |
409 |
idempotency_conflict / idempotency_key_reused |
no: that id means something else |
422 |
a business fact retrying cannot change: tender_mismatch, overpaid_non_cash, total_mismatch, discount_exceeds_price, unknown_variant, unknown_shift, terminal_branch_mismatch… |
no — and the submission is kept on the dead-letter list (GET …/rejections) for a manager to see and resolve |
5xx |
ours | yes, with the same ids |
Card data: never send a card number. maskedPan may show at most the first six and last four digits; free-text fields
are scanned (Luhn) and refused. A refused number is never persisted — not even in the dead-letter payload.
Returns — POST …/sales/{saleId}/returns#
{ returnId, occurredAt, reason?, lines:[{ saleLineId, quantity, restock? }], refunds:[{ type, amountKobo, rrn?, reference? }] }
The refund is computed here, not trusted: each line refunds its share of what was actually paid (discount and VAT in
proportion) as a cumulative figure, so three partial returns of an awkward amount sum to exactly the line (299 kobo → 100 + 99 + 100).
Refunds must be paid out in full, and card/transfer money can only go back as far as it came in (net of earlier refunds); cash is
always allowed. restock (default true) puts stock back at the cost it left with, so the average does not move; restock:false
is a write-off. Idempotent by returnId; concurrent returns of the same line cannot over-return (the sale's xmin serialises them).
Shifts — POST /v1/terminal/shifts · …/{id}/close#
One open shift per terminal, enforced by a partial unique index. Open/close are idempotent by shiftId.
Expected cash = opening float + cash taken − change given − cash refunds; closing records counted − expected as the variance.
A sale joins the shift open at its occurredAt (or the one it names), even if it syncs after that shift closed; sales outside any
shift are simply unattributed. Cash that arrives after close is reported as lateCashKobo, never folded into the closed figures.
A manager can close a lost terminal's shift: POST …/shifts/{id}/close.
Z report — GET …/reports/z · GET /v1/terminal/shifts/{id}/report#
For a shiftId, or a window (date=YYYY-MM-DD in Nigerian time, or from/to, ≤31 days; default today), optionally narrowed to
branchId/terminalId. Gross, discounts, net, VAT, returns, net after returns, per-tender sales/refunds/net (cash net of change),
the drawer reconciliation, the shifts involved, open oversell alerts and flagged sales.
Not here yet#
Matching card/transfer tenders to the acquirer's transactions (Phase 5 uses the stored rrn/stan/tid); sale-level (basket)
discounts; voiding an unpaid sale; cash pay-ins/pay-outs mid-shift; the sale.created webhook (Phase 7 outbox).