Vendor payout ledger

<?php

namespace App\Payouts;

use Illuminate\Database\QueryException;
use Illuminate\Support\Facades\DB;
use RuntimeException;

final class VendorLedger
{
    public function __construct(private readonly int $commissionBps = 1000) {} // 10.00%

    /** Order delivered: credit the sale, debit the platform's cut. */
    public function recordSale(int $vendorId, int $grossCents, string $ref): void
    {
        $fee = intdiv($grossCents * $this->commissionBps + 5000, 10000);

        DB::transaction(function () use ($vendorId, $grossCents, $fee, $ref) {
            $this->add($vendorId, 'sale', $grossCents, $ref);
            $this->add($vendorId, 'commission', -$fee, $ref);
        });
    }

    public function balance(int $vendorId): int
    {
        return (int) DB::table('ledger_entries')->where('vendor_id', $vendorId)->sum('amount');
    }

    /** Pay out everything owed; the lock stops two payout runs from overlapping. */
    public function payout(int $vendorId, string $ref, int $minimumCents = 1000): int
    {
        return DB::transaction(function () use ($vendorId, $ref, $minimumCents) {
            DB::table('vendors')->where('id', $vendorId)->lockForUpdate()->first();
            $owed = $this->balance($vendorId);

            if ($owed < $minimumCents) {
                throw new RuntimeException('Balance is below the payout minimum.');
            }
            $this->add($vendorId, 'payout', -$owed, $ref);

            return $owed;
        });
    }

    private function add(int $vendorId, string $type, int $amount, string $ref): void
    {
        try {
            DB::table('ledger_entries')->insert([
                'vendor_id' => $vendorId, 'type' => $type, 'amount' => $amount, 'ref' => $ref,
            ]);
        } catch (QueryException $e) {
            if (! str_contains($e->getMessage(), 'nique')) {
                throw $e; // a duplicate (vendor, type, ref) is a harmless retry
            }
        }
    }
}

<?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('ledger_entries', function (Blueprint $t) {
            $t->id();
            $t->unsignedBigInteger('vendor_id')->index();
            $t->string('type', 20);          // sale, commission, refund, payout
            $t->bigInteger('amount');        // signed cents: credit +, debit -
            $t->string('ref', 60)->nullable();
            $t->timestamp('created_at')->useCurrent();
            // The same event can never be written twice (webhook retries, double clicks).
            $t->unique(['vendor_id', 'type', 'ref']);
        });
    }
};