I built PayMesh, a payment gateway with a merchant dashboard, an admin console, and a hosted checkout page. The frontend is Next.js. The Laravel backend is where I learned the most. Here are the design choices that mattered, starting with the bug that scares me most in payments.
The bug that prints free money
A merchant has 10,000 in their wallet. Two withdrawal requests for 8,000 arrive at the same moment.
Both requests read the balance: 10,000. Both pass the check. Both get paid out. The wallet ends at -6,000, and 16,000 left the system when only 10,000 existed.
Nothing crashes. No error shows up. Tests that send one request at a time will never catch it. This is a race condition, and it is why payment code needs more care than normal CRUD.
The fix is a row lock. I lock the wallet row inside a database transaction (lockForUpdate() in Laravel) before reading the balance. The second request waits. When it gets its turn, it sees 2,000 and fails cleanly.
That one idea shaped the rest of the backend.
1. A ledger, not a balance column
Money never changes through a plain balance update. Every movement writes a ledger entry, and each entry stores a balance snapshot. The ledger is also the audit trail. You can always answer "why is this balance what it is?"
2. Idempotency that checks the payload
Every payment request takes an Idempotency-Key header. I store the key with a fingerprint of the request body.
- Same key, same body: return the original result.
- Same key, different body: reject the request.
This stops double charges when a client retries. It also catches clients that reuse keys by mistake.
3. Provider adapters behind a factory
Paystack and Cray both sit behind one interface. The rest of the app never talks to a provider directly. A factory picks the right adapter. Adding a new provider means writing one class, not changing the payment flow.
4. Webhooks in both directions
Inbound provider webhooks are checked with an HMAC signature before I trust them. Outbound webhooks to merchants are signed the same way, so they can verify me.
Merchants register their own webhook URLs, so I block unsafe targets such as internal addresses. This prevents SSRF.
5. API keys and access control
API keys are stored hashed, like passwords. Each key has scopes, so a key can be limited to what it needs.
Teams have roles: owner, admin, developer, and finance. A finance user should not manage API keys, and a developer should not approve withdrawals.
6. Withdrawals
Withdrawals use a verification token that the server issues. The client cannot decide for itself that a withdrawal is approved.
What I would improve next
Refunds, fraud checks, and a load test that fires many concurrent requests at one wallet to prove the lock holds.
Stack
- Backend: Laravel 13, Postgres, Sanctum, queue worker, Docker
- Frontend: Next.js, React, TypeScript, Tailwind
Demo video: https://youtu.be/8jZALDUuLeM
Source code: https://github.com/gbollybambam/mini-payment-gateway
How do you handle concurrent writes in your money code? I'd like to hear it in the comments.
Top comments (6)
Ran your test suite with one extra case: two merchants sending the same Idempotency-Key, like
order-1001. The lookup ininitialize()is scoped to merchant_id, but the column is unique on its own, so merchant B misses the lookup, hits UniqueConstraintViolationException on create and gets a 503. Two retries of the same request racing would land on that same 503 instead of the original result. A unique index on (merchant_id, idempotency_key) plus catching the violation and re-reading the row would cover both.Thanks for running the suite with that case, this is a real bug. The lookup is scoped to merchant_id but the column is unique on its own, so merchant B hits the constraint and gets a 503. Two racing retries would hit the same error instead of getting the original result.
I'm going to switch to a unique index on (merchant_id, idempotency_key) and catch the violation, then re-read the row and return the stored result. I'll add tests for both cases and credit you in the commit.
The ledger with a balance snapshot per entry is a nice touch, makes disputes so much easier to trace. Also worth noting lockForUpdate only helps when both requests hit the same database, so replicas need care.
Thanks, the snapshot has made tracing a lot easier. On replicas: the balance read and the lock both happen inside the transaction, and Laravel sends those to the primary, so the check stays consistent. It would only break if someone moved the balance check outside the transaction or read it from a cache. I'll note that in the README.
"Nothing crashes. No error shows up." is the line that stuck β that's exactly why these bugs ship, the test suite passes because it sends one request at a time. The ledger snapshot is the part I'd steal though: lockForUpdate fixes the race, but the snapshot is what lets you answer "why is this balance what it is" a month later. Curious β did you find this one from a real incident, or from thinking the code through?
Race conditions on balance checks or checkout state are usually where payment systems quietly lose money. Even with database transactions, concurrent retries or a webhook arriving mid-flight will slip through unless you pair idempotency keys with row-level locking or atomic state transitions. Once a double-spend or duplicate settlement hits production, untangling the ledger state after the fact is always worse than enforcing strict state guards upfront.