Money arithmetic lives in one file
Why the browser never decides what a checkout costs, how the server quotes a total and checks the payment against that same total, and why partner payouts are worked out once, on the server, for every screen.
Lodge Internet · 14 November 2026 · 5 min read
You're on the plans page. Under each plan is one figure, the total. You tap Pay, Paystack's checkout opens, and it asks your card for an amount.
Somebody decided that amount. The design question is who, and the answer at Lodge is: one Python file on the server, and nobody else.
Why the browser can't be the one
Anything the browser computes, the person holding the browser can change. A JavaScript constant can be edited in developer tools. An old copy of the site can sit in a phone's cache for weeks after we've shipped a new one. A request can be replayed with a different number in it.
None of that is exotic. If the page works out the total and tells Paystack what to charge, then the page is the price list, and the page is not ours once it's on your phone.
So the rule in our engineering standards is blunt. P2: a plan's total is computed only in backend/app/services/pricing.py. No client does price arithmetic. It displays total from the API. P1, above it, says the same thing more widely: the website and the bot are clients, and they hold no prices, stock, balances or rules of their own.
The one file
pricing.py is short on purpose. It defines the site's total, and two things derived from it:
def site_checkout_total(price) -> int:
"""Total payable in whole naira for a plan at `price`."""
...
def site_checkout_charges(price) -> int:
"""Everything added on top of the plan price, so price + charges == total."""
return site_checkout_total(price) - int(price or 0)
def site_checkout_kobo(price) -> int:
"""The total in kobo, which is what Paystack is charged and verified against."""
return site_checkout_total(price) * 100The charges are defined as the total minus the price, not computed separately. So "price plus charges" always equals the total, by construction, and no screen can show a breakdown that doesn't add up.
The WhatsApp bot doesn't have a pricing function of its own. Its bot_checkout_total delegates to this file, so one plan has one price whichever door you buy through. The wallet and bank-transfer orders the website creates are priced from the same function.
Quote and verify against the same number
When the website asks for a hostel's plans, every plan comes back with its charges and total already filled in. The comment beside that line in backend/app/routers/data_codes.py says why: what the customer actually pays is decided there, rather than in the browser, because the claim path verifies against the same total.
That's the second half. After you pay, the claim doesn't take the browser's word for anything. It asks Paystack directly for the transaction by reference, then checks it with verify_paystack_payment, which refuses the claim unless:
- Paystack reports the charge as successful;
- the amount paid is at least
site_checkout_kobo(price)for this plan at this hostel; - the currency is naira.
The price itself comes from the plan record on the server, with any override applied from the hostel or its Wi-Fi controller (the router system a group of hostels shares), the same way the plans list priced it. The quote and the check can't drift apart, because they call the same function on the same input.
The webhook path has one extra wrinkle. A bot checkout and a website card payment can legitimately be priced from different records, so the webhook has to decide which total to expect. It doesn't decide from anything the payment's metadata claims about where it came from, because on the card path that metadata starts in the browser. It decides from something only the server can create: a bot or transfer checkout writes an order row carrying the total the server quoted. If such a row exists for this buyer, its amount is expected. If not, the site total is.
Money is an integer
P3 in the standards: amounts move as kobo, as integers, or as whole naira where an existing API already does. Never floats across a boundary. Money is formatted for display at the last possible moment.
You can see it at each edge. The total is an int of naira. What goes to Paystack, and what comes back from it, is an int of kobo. The money ledger stores amount_kobo as a big integer and refuses a zero posting. The wallet's balance is a sum of kobo postings. The website formats ₦ and the thousands separator when it renders, and not before.
Integers mean a total computed twice is the same total twice, and a sum of rows equals the total of the rows.
Payouts are worked out once, on the server
Hostel partners earn a share of the sales at their hostels. The figures on a split record are, as backend/app/services/splits.py puts it, the closest thing this system has to an invoice. So the same rule applies to them, only more so.
When an admin creates a split, the route in backend/app/routers/admin_splits.py takes the hostel, the dates and the chosen percentages, and recomputes every money figure itself. The comment there is explicit: the client's numbers are ignored entirely. The browser still calculates, but only to preview what a split would pay before it's created. Around that, the route refuses shares that add up to more than the whole, and refuses a split whose dates overlap an existing one, because an overlap would pay the same sales out twice.
Only sales the customer actually received count. An owed order (paid, no code yet) and a sale since refunded or charged back are excluded from what a partner is shared.
What a partner sees as their earnings comes from backend/app/services/partner_payouts.py, whose docstring opens: the one calculation every screen shows. The admin's view of payouts and the partner's own view both call it. Two screens each computing the same figure will sooner or later round differently, or cut a month at a different midnight, and then a partner and an admin are arguing about a number that both screens got "right". So there's one function, and its rules are written down:
- a share is the partner's percentage of the full price, rounded per sale, so a partner's rows always add up to their total;
- days and months are Lagos time, so a month starts at midnight in Nigeria, not midnight UTC;
- percentages are read from the partner's record on every call, not from whatever their sign-in session remembers;
- inactive hostels are included, because their sales were still made.
The trade-offs
Keeping the formula in code means changing a fee is a backend deploy, not a setting someone flips. That's slower, and deliberately so: a change to what every customer pays ships like any other code change, with its history in git. The split rates are the exception. They can be changed from settings without a deploy, and the values that shipped are the fallback when nothing is configured.
Verifying with Paystack on every claim adds a network round trip at the most anxious moment of a purchase. It's also the only check that doesn't trust the device you paid on.
Last checked against the product on 14 November 2026.