Under the hood

How money is kept straight

A bill is split four ways, one card is declined, a refund goes out the next morning and the cash drawer is a tenner short. At the end of the week someone has to explain every pound.

53 statements, each traced to code or a test.

All technical pages

Where the pounds go missing

Restaurant money goes wrong in small, ordinary ways. A card reader times out and the server taps again. A payment notice arrives twice, or never. A discount is applied after half the bill was paid. A refund is sent to a card that only paid part of it. None of these is fraud, and each one leaves the till, the bank and the accountant with three different totals.

The work then moves to the owner: an hour after close matching reader slips to tickets, a VAT return built from figures nobody fully trusts, and a dispute with a guest that turns on what was charged and when.

The answer is not a better report at the end. It is a ledger in which every payment is one row, every request can be repeated safely, and the rules that keep a bill honest are enforced where the data lives. This page describes that ledger.

In short
  • Each card-reader payment on a bill is its own ledger row, with its amount, its tip, its Stripe reference and the amount refunded from it.
  • The amount sent to the reader is worked out in the database under a lock on the bill: the total, less gift card, less part payments, less anything already on a reader. The till may ask for less, never more.
  • Each Stripe event has one row keyed by its event id, so a notice delivered twice is applied once.
  • The audit log is append-only: a database trigger rejects any update or delete.

Who holds the money

Card payments are Stripe charges created directly on the restaurant’s own connected Stripe account. No payment request carries a platform fee. An automated test fails if an application fee, a transfer or an on-behalf-of field ever appears in one. A deployment talks to one Stripe mode, and an object from the other mode is rejected.

OnlineOnline orders are paid on Stripe’s hosted checkout page, which the guest is sent to from the restaurant’s site.
At the tillAt the till, the card is tapped on a Stripe Terminal reader.
Card detailsCard numbers, expiry dates and security codes are entered on Stripe’s page or Stripe’s reader. TableSpark keeps the payment reference, the amount and the status.

One row for every payment

The till records cash, the card reader, another card machine, gift card and other tenders separately. Each card-reader payment on a bill is its own ledger row, with its amount, its tip, its Stripe reference and the amount refunded from it.

  1. The balance is decided in one placeThe amount sent to the reader is worked out in the database under a lock on the bill: the total, less gift card, less part payments, less anything already on a reader. The till may ask for less, never more.
  2. One card at a timeA bill can have one card payment in progress at a time, and a unique index in the database enforces it. A bill cannot be marked paid or cancelled while a card is on the reader.
  3. A bill cannot drop below what was takenA bill’s total cannot be taken below what has already been collected on it. A part payment larger than the remaining balance is refused.
  4. Tips stay separateA tip added on the reader is charged with the tap and kept apart from the bill’s balance.

One test settles a single bill with cash, a card on the reader, a gift card and a second card, and requires the four to reconcile exactly.

A request sent twice charges once

Networks fail in the middle of a payment. What matters is what happens when the same request arrives again.

Requests that move money carry an idempotency key: the order checkout, each order refund, each reader payment and each reader refund. A retried tap that carries the same attempt key resolves to the same payment row and the same Stripe request, so the guest is charged once.

An order submitted twice with the same reference is one order. A refund request without an idempotency key is rejected.

Payment notices, and the ones that never arrive

A card payment is confirmed by a notice from the payment processor. Notices can be forged, repeated, delayed or lost, and each case needs its own answer.

ForgedA payment notice from Stripe is accepted only with a valid signature and a recent timestamp. Anything else is refused before any work is done.
RepeatedEach Stripe event has one row keyed by its event id, so a notice delivered twice is applied once. Handling has two phases: the event is claimed under a 120-second lease, the work is applied, and only then is the event marked done.
UnansweredIf the ledger cannot answer, the reply to Stripe is an error, so Stripe sends the notice again.
LostEvery 15 minutes a reconciler asks Stripe about online checkouts that are still unpaid in TableSpark, and an order Stripe reports as paid is completed, never cancelled. Card-reader payments whose notice never arrived are re-checked four times an hour, and Stripe’s answer settles them.
Checked again dailyOnce a day a second pass checks that the refunds recorded for each order add up to the order’s refunded amount, repairs what the ledger can prove and raises an alert for the rest.

Prices the browser cannot change

Online order prices come from the menu on the server. Money values sent by the browser are ignored. The database recalculates the order and refuses a price, a line total or a total that disagrees with the menu.

An order moves only from new to confirmed, preparing, ready and completed, or to cancelled. The database refuses any other jump. Payment fields on an order change only through the payment functions, never by a direct edit.

What it costs

0% TableSpark commission on bookings and orders. Stripe’s standard card-processing fees apply to online payments.

Refunds

A refund is where a tidy ledger is usually lost, because the money has to go back the way it came.

Card readerRefunding a bill paid on the reader creates a Stripe refund against that same payment. The refund is reserved in the ledger before Stripe is called and is limited to what that payment took.
Mixed tendersOn a bill paid with more than one tender, staff choose where a refund goes, with each tender capped at what it took. When the choice is open, the till asks instead of guessing.
CashCash refunds and refunds made on another card machine are recorded against their tender in the same ledger.
Online ordersAn online card order is refunded through Stripe in full, by amount or by item, never above what remains unrefunded. When the order was paid partly from a gift balance, the card is refunded first and the gift balance is restored.
Gift cards at the tillWhen a till bill was paid partly with a gift card, refunding it returns that part to the card’s balance, in one transaction with the refund record.
Booking depositsWhen a guest cancels a booking that carries a deposit, the refund is a stored job with its own idempotency key, so it is sent once. When staff cancel a booking with a paid deposit, the deposit is settled in the same transaction, under the terms the guest accepted when they paid.
DisputesA card dispute opened by a guest’s bank is recorded against the order with its amount, reason and evidence deadline, and raises an alert to the owner.

The end-of-day report

The end-of-day report lists takings by tender, refunds by tender, VAT by rate, voided lines, open bills, sales by channel and by hour, and the cash drawer: float, cash sales, cash refunds, cash paid in and out, and the amount expected in the drawer.

Closing the day stores that report as a snapshot, together with the cash you counted and the difference from the expected amount. A business day is closed once. A second close is refused. Team members can read past closes, and the database gives them no function that edits or reopens one.

The TableSpark End of day screen showing takings by tender, sales, VAT on items sold and the cash drawer with float, cash taken and the amount expected
End of day for one business day: takings by tender, VAT on items sold and the cash drawer.

End of day has a tips record: a written policy kept by version, the day’s card and cash tips, and a split by rota hours or in equal shares that adds up to the pool exactly.

VAT by rate

Menu prices include VAT. The VAT in each line is worked out from the gross price at that line’s rate and rounded to the penny. The rate is resolved for each line from the dish, the restaurant’s default and the channel, so a takeaway line and an eat-in line can carry different rates, and the rate is stored on the line.

Printed receipts carry a VAT summary with a row for each rate: net, rate, VAT and gross.

The audit log

When a void or a discount is questioned a month later, the answer has to be a record nobody could have tidied up.

The audit log is append-only: a database trigger rejects any update or delete. Entries are written by the database itself when a line is voided or reduced, a discount or service charge changes, a bill is reopened, an order is cancelled, a refund is made, a menu price changes or the day is closed.

Each entry records who acted, what they did, the amount, the reason given and the time. End of day shows the day’s exceptions from that log beside the takings.

Gift cards

Gift-card value is an append-only ledger of issues, holds, commits, releases and refunds. Redeeming locks the card and refuses to spend more than the balance less any live holds.

How this is tested

Hand-written examples only cover the cases someone thought of. The ledger is also attacked with cases nobody chose.

  • A property test runs random sequences of payments, reader taps, gift cards, discounts and refunds against the real database functions, and checks after every step that a bill is never over-collected.
  • One test settles a single bill with cash, a card on the reader, a gift card and a second card, and requires the four to reconcile exactly.
  • No payment request carries a platform fee. An automated test fails if an application fee, a transfer or an on-behalf-of field ever appears in one.

Questions owners ask

Can a card be charged twice if the reader times out?

A retried tap that carries the same attempt key resolves to the same payment row and the same Stripe request, so the guest is charged once. A bill can have one card payment in progress at a time, and a unique index in the database enforces it.

What happens if a payment notice is lost?

Every 15 minutes a reconciler asks Stripe about online checkouts that are still unpaid in TableSpark, and an order Stripe reports as paid is completed, never cancelled. Card-reader payments whose notice never arrived are re-checked four times an hour, and Stripe’s answer settles them.

Can the audit log be edited?

The audit log is append-only: a database trigger rejects any update or delete. Each entry records who acted, what they did, the amount, the reason given and the time.

How this page is kept true

This page makes 53 statements about how TableSpark behaves. Each one is recorded with the place in the code, the database or the test suite that enforces it, and an automated check fails when a statement loses its evidence. The suites named below exercise the behaviour described here.

Automated suites behind this page

  • audit-log-db
  • end-of-day-db
  • gift-card-redemption-db
  • ledger-property-db
  • part-payments-db
  • payments
  • pos-order-reconcile
  • pos-order-state
  • pos-stripe-webhook
  • priority-zero-public-copy
  • terminal-ledger-db
  • tips-db
  • vat-rates

See it on your own restaurant

Build your site free and publish when you are ready. Plans start at £19 a month, excluding VAT.

Start building free