BWEZE holds its customers’ money. A workspace tops up its wallet with mobile money, and every GiB-hour, SMS segment and domain is paid out of it. Any bug in that path is a bug in someone’s balance, so we made a rule before writing the first line of billing code: the ledger’s guarantees live in Postgres constraints, not in application code.
Application code has many authors and many paths in: the API, background jobs, webhooks from payment rails, one-off scripts. A rule that lives in a function holds only on the paths that call it. A rule in the database holds on every path, including the one someone writes next year at two in the morning.
Double entry, checked at commit
Every movement of money is a transaction made of entries, and each entry is a debit or a credit on an account: a workspace’s wallet, BWEZE’s revenue, cash. An amount is always positive; its side lives in a direction column. The rule of double entry is that a transaction’s debits equal its credits, and Postgres checks it:
CREATE CONSTRAINT TRIGGER ledger_entry_balanced
AFTER INSERT ON ledger_entry
DEFERRABLE INITIALLY DEFERRED
FOR EACH ROW EXECUTE FUNCTION ledger_balanced();
The trigger is deferred, so it runs once at COMMIT, after all of a transaction’s entries are in, instead of failing on the first row. It sums the entries per currency, not across them, so a transaction cannot balance francs against dollars. A second trigger refuses an entry whose currency differs from its account’s.
Append-only, even against TRUNCATE
Posted entries are never changed. A trigger raises an error on any UPDATE or DELETE of ledger_entry, and because row triggers do not fire on TRUNCATE, a statement trigger covers that too. A refund is a new transaction that points back at the one it reverses, so the history of a wallet is always the full history.
The wallet balance is never stored. It is a view that sums a wallet’s entries, so there is no second number that can drift from the first.
Idempotency in a unique index
Payment webhooks arrive twice. Clients retry. Agents retry more. Each transaction can carry an idempotency key, and (organization_id, idempotency_key) is unique, so a replayed top-up cannot post twice: the second insert fails and the caller gets the first result. Metered usage works the same way: a usage event carries a dedupe key, unique per workspace and meter, so the same minute of memory is counted once. The SMS API exposes this directly: a send with a key that was already used returns the original result and never sends again.
Holding money for an SMS before it moves
Sending SMS has a race. Two sends check the balance at the same moment, both see enough, and both go out. We close it with a reservation: before a send, a short-lived hold for its cost is written, and the balance check subtracts every live hold. A reservation is not money moving, and nothing is written to the ledger until the carrier accepts the message, so a failed submit never bills. Holds expire after two minutes, so a crash in the middle of a send leaves a hold that blocks a little too much for at most that long and then clears. It fails closed: in doubt, BWEZE refuses a send instead of sending on credit.
The free allowance can only be claimed once
The free monthly allowance unlocks when a workspace owner verifies a Rwandan mobile number, and a number unlocks it for one workspace, for good. That rule lives in Postgres too. A check constraint accepts only Rwandan mobile numbers, the number is the primary key of the claims table, and a trigger refuses to delete a claim. Deleting the workspace or the account leaves the number used.
What it costs us
Constraints make some things harder. A mistaken charge cannot be edited away; it has to be reversed with a new transaction, which is the point, but it is more work. Migrations that touch the ledger need care, because the triggers apply to the migration too. And tests have to run against a real Postgres, not a mock, because the rules are in the database.
We think that is the right trade for money. The shape of the schema (typed transactions, paired reversals, entitlements that do not care which payment rail paid for them) borrows from Polar’s Apache-2.0 billing models, and we are grateful it was open.