Credit first, then spend: the wallet that replaced three special cases
Every bank transfer now lands in the customer's wallet first, exactly once, and only then pays for whatever is waiting. Part-payments, overpayments and transfers with no order stopped being special cases.
Lodge Internet · 14 November 2026 · 6 min read
You open your bank app to pay for a plan by transfer to your own Lodge account number. You type the amount from memory, and it's wrong. Maybe it's short, because you misremembered the total. Maybe it's over, because you rounded up. Maybe you sent money before you'd even picked a plan, because the transfer was the easy part.
Every one of those is ordinary. And for a while, each one was its own branch in our code.
The old shape: match a transfer to an order
A bank transfer arrives with no plan attached. Paystack tells us that money landed in a customer's dedicated account (a DVA, an account number Paystack opens for one customer), how much, and the reference. That's all.
The first design, still visible in backend/app/routers/webhooks.py as the pre-wallet path, matched the transfer to the customer's waiting order by email and amount. When the amount matched, fine. When it didn't, the code needed a rule:
- short: hold the part-payment on the order and tell the customer how much more to send;
- over: fulfil the order and record the overpayment on it;
- no order at all: record an owed order and put it in front of an admin.
Each rule was reasonable. Together they were three different ways for one transfer to be handled, each with its own retry story, and "what happens when two of these overlap" was a question with no single answer.
The new rule: credit first, then spend
The docstring at the top of backend/app/services/wallet_payments.py states the replacement in two steps:
- Credit the wallet with the full amount, idempotent on the Paystack reference.
- If the customer has an order waiting for a transfer, and the wallet now covers it, pay it from the wallet and issue what it bought.
That's the whole rule. And the three special cases stop being special:
- a part-payment: the wallet simply holds it until there's enough;
- an overpayment: the rest stays in the wallet, the customer's to spend;
- no order at all: it's wallet credit, not an owed order for an admin.
Nothing has to decide what a stray transfer "meant". Money in is money in. Buying is a separate act that happens to follow it.
Step one: credit once
Crediting is credit_topup in backend/app/repos/wallet.py. It writes a balanced entry to the money ledger with an idempotency key built from the Paystack reference. A second attempt with the same reference hits the unique key, writes nothing, and returns false.
That's what lets every path call it without coordination. The webhook, the settle loop's replay and the pull reconciliation (see webhooks get lost, payments don't) can all reach the same transfer. The first one credits it. The rest find it done.
The customer is always credited the full transfer. Whatever the platform's own costs are on that transfer, they come out of the platform's side of the entry, never out of the customer's balance.
There's also no balance column. The wallet's balance is the sum of the customer's postings in the ledger, so there's nothing to drift out of step, and every naira in it traces back to the transfer that put it there. We never edit a money row has the ledger side of this.
Step two: spend, safely
After crediting, pay_open_checkouts walks the customer's waiting orders, oldest first, and pays each one the wallet now covers. When it reaches one it can't cover, it tells the customer how much more that order needs (the old part-payment message, now just a fact about the balance) and stops.
Paying one order is pay_from_wallet, and the spend inside it has three properties worth naming.
It's idempotent on the order. The spend key is the order's own id, so a retry after a crash takes nothing more. It just carries on to issuing the code.
It can't overdraw. A spend takes a per-customer lock in the database, re-reads the balance under that lock, and writes the debit in the same transaction. Two purchases in the same instant can't both spend the same naira. If the balance is short, it raises and takes nothing.
It undoes itself if the code can't be issued. If the plan sold out between the order and the payment, or the plan is gone:
except (_NoCodes, _PlanNotFound) as exc:
reason = "no_stock" if isinstance(exc, _NoCodes) else "plan_missing"
await run_in_threadpool(lambda: wallet.reverse_spend(user_id, key=key, reason=reason))
current().update("pendingPayments", pending_id, {"status": "cancelled", "cancelReason": reason, ...})reverse_spend posts the exact opposite of the spend, once. The money is back in the wallet, and the customer is told the plan sold out and their money is safe there.
And a spend that was reversed stays reversed. If anything later retries that order, the spend sees its own reversal and raises, so an order that was refunded to the wallet is never fulfilled for free on a retry.
The order also gets its own payment reference for its purchase, one per order. A retried fulfilment finds the purchase it already made instead of making another.
The website uses the same rule
backend/app/routers/wallet.py gives the website two ways to use this.
Paying from the wallet buys a plan from the balance at once. Asking twice for the same held code buys it once: before making an order, the route looks for an order of yours for that code that the wallet already paid, and returns that instead. As everywhere, the code's reservation id is matched together with the buyer, because reservation ids are reused.
Paying by transfer makes the same kind of order the bot makes. If the wallet already covers it, it's paid on the spot and the customer never transfers anything. If it partly covers it, the page asks only for the difference. Starting a new transfer order also cancels your earlier unpaid ones, so a later transfer doesn't quietly buy an old plan you'd walked away from. An order with any money on it is never touched by that.
When something breaks halfway, the route says which half. If the money was taken, the customer is told the payment went through and the code is coming, and the order stays open for the settle loop to finish. If nothing was taken, the order is cancelled so that a later retry can't buy the plan a second time.
The backstop
The webhook credits and pays in one go when a transfer lands. If the process dies between crediting and paying, or between paying and issuing the code, the settle loop's pay_waiting_orders_from_wallets picks it up. An order already paid from the wallet goes first, whatever its age, because it needs no money and mustn't wait behind one the wallet can't cover. Every step is idempotent, so finishing there is safe.
The trade-offs
A wallet holds customer money we haven't earned yet. It's a liability on our books from the moment a transfer lands until it's spent, and it has to be accounted for as one.
Automatic paying only applies to recent orders. An old order the customer abandoned isn't bought by a later top-up, because that money is theirs to spend on whatever they choose next. The cost is that someone who really did mean to finish an old order has to start it again.
What's still open
A transfer into an account we can't tie to any customer still becomes an owed order, as before. The wallet removes every case where we know whose money it is. It can't remove the case where we don't, and that one still needs a person.
Last checked against the product on 14 November 2026.