DEV Community: Marcelinus Ani

Atomic Money: Making a PHP/MySQL Wallet Safe Under Concurrency

Marcelinus Ani — Mon, 03 Aug 2026 03:09:47 +0000

The lost-update bug that quietly corrupts homegrown wallet balances — and the five disciplines we used across PayWithToken to make money movement correct under concurrency.

There is a bug that lives in a large share of the world's homegrown wallet systems. It doesn't throw an error. It doesn't show up in tests. It surfaces months later as a balance that is quietly, inexplicably wrong — and in a payments system, a wrong balance is either a customer who has lost money or a company that has given it away. This is the story of that bug, why the "obvious" wallet code causes it, and the handful of disciplines we used across PayWithToken to make money movement correct under concurrency.

The bug: lost updates
Here is wallet code almost everyone writes first. Credit a user's balance:

// DON'T do this
$row = $db->query("SELECT balance FROM users WHERE id = $id")->fetch();
$new = $row['balance'] + $amount;
$db->exec("UPDATE users SET balance = $new WHERE id = $id");
Read the balance, add to it in PHP, write it back. It works perfectly — until two things happen at the same time.

Picture a wallet at ₦1,000. Two credits of ₦500 arrive simultaneously — say a bank webhook and the user tapping "confirm" on their phone:

Request A reads balance = 1000.
Request B reads balance = 1000 (A hasn't written yet).
A computes 1500, writes 1500.
B computes 1500, writes 1500.
Two credits landed; the balance rose by ₦500. ₦500 vanished. This is a lost update, and it is a race condition, which means it is invisible until you have real concurrent traffic — exactly when you can least afford it. The debit version of the same bug lets a balance go negative or double-spends a token.

Fix #1: let the database do the arithmetic
The read-modify-write happened in PHP, across three round trips, with a gap where another request could interleave. The fix is to make the update a single atomic statement and let the database's row lock serialise it:

// DO this — one atomic statement
$db->prepare("UPDATE users SET balance = balance + :amt WHERE id = :id")
->execute([':amt' => $amount, ':id' => $id]);
Now the addition happens inside the database, under the row lock it already takes for an UPDATE. Concurrent credits queue behind each other and both land. There is no window to interleave because there is no gap between read and write — they are the same operation. In PayWithToken we converted every wallet credit and debit site — 21 of them — to this pattern. Consistency matters more than cleverness: one read-modify-write left in the codebase is enough to corrupt a balance.

Fix #2: store money as DECIMAL, never FLOAT
The second silent corruption is the column type. Floating-point numbers cannot represent most decimal fractions exactly:

0.1 + 0.2 → 0.30000000000000004
Store balances as FLOAT/DOUBLE and those tiny errors accumulate across millions of operations until statements no longer reconcile to the penny. Money must be exact, so money columns are DECIMAL:

ALTER TABLE users MODIFY balance DECIMAL(18,2) NOT NULL DEFAULT 0.00;
DECIMAL(18,2) stores an exact base-10 number with two fractional digits and headroom for very large totals. Combined with atomic updates, arithmetic is now both race-free and exact.

Fix #3: guard the debit
A credit can always succeed; a debit must not overdraw. The guard belongs in the same atomic statement, not in a separate SELECT:

$stmt = $db->prepare(
"UPDATE users SET balance = balance - :amt
WHERE id = :id AND balance >= :amt");
$stmt->execute([':amt' => $amount, ':id' => $id]);

if ($stmt->rowCount() === 0) {
// No row updated → insufficient funds (or wrong id). The debit did NOT happen.
throw new InsufficientFunds();
}
The WHERE balance >= :amt makes the check and the deduction one indivisible act. You then trust rowCount(): if zero rows changed, the money did not move. A separate "check balance, then debit" would reopen exactly the race we just closed.

Fix #4: credit at confirm time, keyed to a specific payment
Atomicity stops corruption. It does not stop duplication. In a real payments system the same credit can be triggered from several places — a bank webhook, a scheduled reconciliation job, a user pressing "confirm." If each one credits the wallet, the user is paid three times for one deposit.

The naive guard — "have we credited this user today?" — is wrong, because a user can legitimately deposit twice in a day. The credit must be tied to the specific payment artifact: a bank reference, a transaction id. Record that a given reference has been settled, and make claiming it a one-time, atomic act:

// Idempotent: only the FIRST caller for this bank reference wins
$claimed = $db->prepare(
"INSERT IGNORE INTO settled_refs (bank_ref) VALUES (:ref)");
$claimed->execute([':ref' => $ref]);

if ($claimed->rowCount() === 1) {
// We are the first — safe to credit exactly once
creditWallet($userId, $amount);
}
// rowCount() === 0 → already settled → do nothing
A UNIQUE constraint on bank_ref plus INSERT IGNORE turns "have we already handled this payment?" into a single race-free question. Webhook, cron and manual reconciliation can now all run — even simultaneously — and the wallet is credited exactly once. We applied the same "execute-once claim" to dispute resolutions, so a refund can never be paid twice.

Fix #5: make the whole movement transactional
When money moves between two places — debit one wallet, credit another, write a ledger row — those writes must all commit or all roll back. A crash between the debit and the credit must not leave money destroyed:

$db->beginTransaction();
try {
debit($sender, $amount); // atomic, guarded
credit($receiver, $amount); // atomic
writeLedger($sender, $receiver, $amount);
$db->commit();
} catch (Throwable $e) {
$db->rollBack(); // nothing moved
throw $e;
}
The disciplines, distilled
None of this is exotic. It is five disciplines applied without exception:

Never read-modify-write a balance in application code. Let the database add and subtract in one statement.
Store money as DECIMAL, never floating point.
Guard debits in the WHERE clause and trust the affected-row count.
Make credits idempotent by keying them to a specific payment reference, claimed exactly once.
Wrap multi-step movements in a transaction so they are all-or-nothing.
The reason to be absolute about it is that concurrency bugs don't fail loudly. They fail as a slow leak of trust — a balance that's a little off, a reconciliation that won't tie out, a customer who swears they were charged twice. In payments, "usually correct" is another way of saying "wrong." Money-grade software earns its name by being correct every time two things happen at once — and that is a property you design in deliberately, one atomic statement at a time.

Reprint-Safe Payment Tokens: Keyed HMAC-SHA256 with a Luhn Check Digit

Marcelinus Ani — Mon, 03 Aug 2026 02:59:17 +0000

When you build a payment rail around a token — a short, redeemable claim on value that a person can receive by SMS, read over the phone, or type into a USSD menu — the token is the money. Get its design wrong and you have either a fraud surface or an operations nightmare. This is the story of how we redesigned PayWithToken's token so it is unpredictable, leaks nothing about the sender, survives a reprint, and can be validated on a feature phone with no network — and the small number of ideas that made all of that fit into 18 digits.

The trap: "obvious" tokens
The first version of almost every token scheme looks reasonable and is quietly dangerous. A common pattern is to compose the token from things you already have — a phone number and a timestamp, maybe a sequence counter:

token = last9(phone) + HHMMSS + seq
It is easy to generate, easy to look up, and completely broken:

It is predictable. If I know (or guess) your phone number and roughly when a token was issued, I can enumerate a very small space of candidates. Bearer instruments must not be guessable.
It leaks PII. The token now contains a phone number. Anyone who sees a token — printed on a receipt, forwarded in a chat — learns something about the parties.
It collides. Two tokens minted in the same second for the same user need ugly tie-breakers.
It can't be checked offline. A mistyped digit sails straight through to a failed redemption at the counter.
We wanted the opposite of all four properties.

The requirements
Before touching code, we wrote down what a token had to be:

Numeric and short. It has to be entered on a phone keypad and read aloud, so: digits only, 18 of them.
Unpredictable. Knowing any number of past tokens must not help you forge the next one.
PII-free. The token must reveal nothing about the sender, recipient, amount, or time.
Offline-verifiable for typos. A cashier or USSD flow should catch an obvious mistype without a round trip.
Reprint-safe. If a customer loses the SMS, we must be able to re-issue the exact same token — without ever having stored the token itself.
Hash-only at rest. The database must never hold a plaintext token. If the table leaks, the tokens are useless.
Requirements 5 and 6 look contradictory — reproduce the token, but don't store it — and resolving that tension is the interesting part.

The design
The token is the output of a keyed hash, mapped to digits, with a Luhn check digit on the end.

Deterministic inputs, secret key We never hash the token; we hash the facts that define it. Those are things we already persist for the transaction anyway — a monotonic issue reference, the wallet/transaction id, a per-token counter — assembled in a fixed, canonical order:

message = canonical(issue_ref, txn_id, counter) # deterministic, no secrets
mac = HMAC_SHA256(server_key, message) # 32 bytes, unpredictable
server_key is a high-entropy secret that lives outside the web root, in environment configuration / a secrets manager, and is rotated on a schedule. The unpredictability of the token comes entirely from this key: without it, HMAC output is computationally infeasible to reproduce or reverse.

Bytes to digits We turn the 32-byte MAC into a big integer and take it modulo 10^17 to get 17 digits, then compute a Luhn check digit to make 18:

n17 = int_from_bytes(mac) % 10**17 # 17 digits
check = luhn_check_digit(n17) # 1 digit
token = zero_pad(n17, 17) + str(check) # 18 digits

Luhn — integrity, not security
The final digit is the same checksum the card industry uses. It is not a security control — it stops honest typos, not attackers. One transposed or wrong digit fails the Luhn test instantly, on-device, with no network. That single digit removes a whole class of "valid-looking but wrong" tokens from ever reaching the backend.
Reprint-safety without storing the token
Here is the resolution to the apparent contradiction. Because generation is a pure function of stored inputs and the key, we can always recompute the exact token on demand:

reissue(issue_ref, txn_id, counter) -> same 18 digits, every time
So to reprint or resend, we don't fetch a stored token — we regenerate it from the transaction record. Meanwhile, what we store for validation is only the token's hash:

store: token_hash = SHA256(token) # never the token itself
verify: SHA256(entered_token) == token_hash ? # constant-time compare
A database dump therefore contains no spendable value. Redemption is a hash comparison; reprint is a recomputation; the plaintext exists only in transit to the recipient.

The partner-format contract
There is one more real-world wrinkle. We also issue an 11-digit token variant for white-label partners whose systems were built expecting exactly 11 digits. When we rolled out the keyed scheme, we could not change that length without breaking every partner integration — the token's shape was effectively an API contract.

The design handles this by construction: the only length-dependent step is the modulus. Take the MAC modulo 10^10, append the Luhn digit, and you have a secure 11-digit token with identical properties. Same engine, same guarantees, different envelope — and no partner had to change a line of code.

n10 = int_from_bytes(mac) % 10**10
token = zero_pad(n10, 10) + luhn_check_digit(n10) # 11 digits, still keyed + checked
What the token does not do (and how we cover it)
A well-designed token value is necessary but not sufficient. Because a token is a bearer instrument, the surrounding system still has to:

Make redemption one-time and atomic, so a token can't be spent twice under a race.
Support suspension and expiry, so a compromised or disputed token can be killed instantly, everywhere.
Rate-limit validation, so nobody can brute-force the (already vast) space by hammering the redeem endpoint.
Protect and rotate the key, because the key is the whole security model.
Get those right around a keyed, checksummed, hash-stored token and you have something you can safely send by SMS to a stranger.

Takeaways
Never compose a token from user data. Predictability and PII leakage are baked in from the first line.
Let a keyed hash supply the entropy; the secret key is the security boundary, not the format.
Store the hash, regenerate from inputs. That single decision gives you reprint-safety and a database that holds no spendable value.
Add a Luhn digit for humans, not attackers — it pays for itself the first time someone reads a token aloud.
Treat length as a contract. A modulus is all that separates an 18-digit consumer token from an 11-digit partner token with the same guarantees.
Designing money to travel as eighteen typed digits forces a satisfying discipline: every property you want has to be earned explicitly. The result is a token that is unpredictable, private, human-checkable, reproducible, and worthless at rest — which is exactly what you want the thing that is the money to be.