DEV Community

The race condition that prints free money, and how I stopped it in my Laravel payment gateway

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:

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.

Read on DEV Community ↗ ← Back to News

Comments

No comments yet. Start the discussion.