<?php
namespace App\Http\Controllers;
use App\Models\Wallet;
use App\Services\WalletService;
use App\Exceptions\InsufficientFundsException;
use Illuminate\Http\Request;
class WalletController extends Controller
{
public function __construct(private WalletService $wallets)
{
}
public function debit(Request $request, Wallet $wallet)
{
$data = $request->validate([
'amount' => ['required', 'integer', 'min:1'],
'idempotency_key' => ['required', 'string', 'uuid'],
'reason' => ['nullable', 'string', 'max:255'],
]);
try {
$transaction = $this->wallets->debit(
$wallet->id,
$data['amount'],
$data['idempotency_key'],
$data['reason'] ?? 'debit'
);
} catch (InsufficientFundsException $e) {
return response()->json(['error' => $e->getMessage()], 422);
}
return response()->json([
'transaction_id' => $transaction->id,
'balance' => $transaction->wallet->balance,
], 201);
}
}
<?php
namespace App\Services;
use App\Models\Wallet;
use App\Models\WalletTransaction;
use Illuminate\Support\Facades\DB;
class WalletService
{
public function debit(int $walletId, int $amount, string $idempotencyKey, string $reason): WalletTransaction
{
return DB::transaction(function () use ($walletId, $amount, $idempotencyKey, $reason) {
$existing = WalletTransaction::where('idempotency_key', $idempotencyKey)->first();
if ($existing !== null) {
return $existing->load('wallet');
}
// Row-level write lock; blocks concurrent debits on this wallet.
$wallet = Wallet::whereKey($walletId)->lockForUpdate()->firstOrFail();
$transaction = $wallet->debit($amount, $idempotencyKey, $reason);
return $transaction->load('wallet');
});
}
}
<?php
namespace App\Models;
use App\Exceptions\InsufficientFundsException;
use Illuminate\Database\Eloquent\Model;
class Wallet extends Model
{
protected $fillable = ['user_id', 'currency', 'balance'];
protected $casts = ['balance' => 'integer'];
public function transactions()
{
return $this->hasMany(WalletTransaction::class);
}
public function debit(int $amount, string $idempotencyKey, string $reason): WalletTransaction
{
if ($amount > $this->balance) {
throw new InsufficientFundsException(
"Wallet {$this->id} has {$this->balance}, cannot debit {$amount}."
);
}
$this->decrement('balance', $amount);
return $this->transactions()->create([
'idempotency_key' => $idempotencyKey,
'type' => 'debit',
'amount' => $amount,
'reason' => $reason,
'balance_after' => $this->balance,
]);
}
}
<?php
use Illuminate\Database\Migrations\Migration;
use Illuminate\Database\Schema\Blueprint;
use Illuminate\Support\Facades\Schema;
return new class extends Migration
{
public function up(): void
{
Schema::create('wallet_transactions', function (Blueprint $table) {
$table->id();
$table->foreignId('wallet_id')->constrained()->cascadeOnDelete();
$table->uuid('idempotency_key')->unique();
$table->string('type');
$table->unsignedBigInteger('amount');
$table->string('reason')->default('debit');
$table->unsignedBigInteger('balance_after');
$table->timestamps();
$table->index(['wallet_id', 'created_at']);
});
}
public function down(): void
{
Schema::dropIfExists('wallet_transactions');
}
};
Debiting a wallet balance is a classic race-condition trap: two concurrent requests both read a balance of 100, both decide a 60 charge is affordable, and both write back 40 — the account goes negative or double-spends. The fix is to serialize the read-modify-write against a single row using database-level pessimistic locking, and this snippet shows the full path from HTTP request through service to model.
In the WalletController tab, the controller stays thin: it validates the incoming amount and idempotency key, resolves the wallet by route binding, then delegates to WalletService::debit. It never touches the balance directly, which keeps the locking logic in one place and out of the request layer.
The WalletService tab holds the core pattern. DB::transaction wraps the whole operation so any thrown exception rolls back cleanly. Inside, Wallet::whereKey($id)->lockForUpdate()->firstOrFail() issues a SELECT ... FOR UPDATE, taking a row-level write lock that blocks other transactions from reading that same row FOR UPDATE until this transaction commits. Crucially, the balance is re-read after acquiring the lock, so the affordability check in $wallet->debit($amount, ...) operates on fresh, isolated data rather than a stale value. An idempotency guard checks the wallet_transactions ledger first: if a row with the same idempotency_key already exists, the prior result is returned instead of debiting twice, which matters because clients retry.
The Wallet model tab encapsulates the invariant. debit throws InsufficientFundsException when amount exceeds balance, decrements the column, and records a ledger row in the same transaction so the balance and its audit trail can never drift apart.
The trade-off is throughput: lockForUpdate holds the lock for the transaction's duration, so heavy contention on one wallet serializes those requests. Keeping the transaction short — no external HTTP calls inside it — mitigates this. Alternatives like optimistic locking with a version column or an atomic UPDATE ... WHERE balance >= ? avoid held locks but complicate multi-step writes. Pessimistic locking is the clearest choice when several related rows must change atomically under a read-check-write flow.
Related snips
package dbutil
import (
"context"
"github.com/jackc/pgconn"Retry Postgres serialization failures with bounded attempts
class SignupForm
include ActiveModel::Model
include ActiveModel::Attributes
attribute :account_name, :string
attribute :email, :stringShallow Controller, Deep Params: Form Object Pattern
use crossbeam::channel::unbounded;
use std::thread;
fn main() {
let (tx, rx) = unbounded();Crossbeam for advanced concurrent data structures
// Creating a Promise
const myPromise = new Promise((resolve, reject) => {
const success = true;
setTimeout(() => {
if (success) {Promises and async/await patterns for asynchronous JavaScript
use std::sync::mpsc;
use std::thread;
fn main() {
let (tx, rx) = mpsc::channel();Channels (mpsc) for message passing between threads
export type Settled<R> =
| { status: 'fulfilled'; value: R }
| { status: 'rejected'; reason: unknown };
export interface ConcurrencyOptions {
limit: number;Simple concurrency limiter for batch operations
Share this code
Here's the card — post it anywhere.
