Laravel Wallet Laravel Package

Product Decisions This Supports

• Build vs. buy for money movement inside the product. A virtual wallet is a ledger problem, not a UI problem: atomic debits/credits, concurrency locks, refunds, transfers, and an auditable transaction history. This package ships that layer for Laravel, so the roadmap decision becomes "buy the ledger, build the product surface" instead of spending a quarter of engineering on double-entry bookkeeping edge cases.
• Monetization and retention features that all need the same primitive. In-app credits, prepaid balances, loyalty points, cashback, referral bonuses, promotional credits, gift/store credit, and tipping are all the same deposit/withdraw/transfer model. One adoption unlocks several roadmap items without re-architecting each one.
• Purchase and refund flows. The Customer/ProductInterface model (plus ProductLimitedInterface for one-time or inventory-constrained purchases, and PurchaseQueryHandlerInterface to check "already bought?") directly supports digital goods, one-time unlocks, and entitlement checks — and refund() makes the reversal path a first-class operation rather than a custom job.
• Credit terms and postpaid behavior. forceWithdraw() allows a negative balance, which maps to "bill me later," tax/fee collection, or overdraft-style products. That's a product policy decision this package lets you test quickly instead of blocking on infrastructure.
• Multi-wallet as a packaging decision. Per-purpose or per-currency wallets (slug-based, plus the uuid extension) let you offer "bonus credits that expire" vs. "real balance," or separate currencies, without a second system. The swap extension covers simple exchange-rate scenarios.
• Pricing and display decisions. Balances are stored as integer minor units with brick/math behind the scenes, and balanceFloat/depositFloat handle presentation. This lets you commit to a currency precision policy (including zero-decimal currencies) without float-rounding bugs reaching customers.
• Ops and finance decisions. Confirmed vs. pending states, transfer records, and per-transaction meta (description, product title) give support and finance a reconciliation trail. It also makes "can we answer a customer dispute in under 5 minutes?" a yes.
• Scope boundary decision: ledger, not payments. This does not move real money — no card acquiring, bank rails, KYC/AML, or payouts. Pair it with a PSP; treat it as the internal accounting record. Getting that boundary explicit early prevents scope creep and compliance surprises.
• Roadmap sequencing. Because releases are active and 12.x is supported through Sep 2028 on Laravel 13 / PHP 8.3–8.5, you can slot wallet-dependent features into a multi-year plan without a forced migration cliff.

When to Consider This Package

Adopt when:

• You are on Laravel 11/12/13 with PHP 8.3+, and the wallet lives inside the existing monolith.
• You need an internal balance/ledger — credits, points, store credit, prepaid usage — not regulated custody of customer funds.
• Concurrency correctness matters and you'd rather not own it: simultaneous debits, idempotency concerns, lock and cache drivers configurable via WALLET_* env vars.
• You need refunds, transfers, and "pay with balance" alongside manual adjustments by support.
• The team is small enough that a well-documented, MIT-licensed package with coverage and mutation-testing badges is a better bet than a bespoke ledger.
• You can accept a backend-only library: no admin UI, no reporting dashboards, no customer-facing statements out of the box.

Look elsewhere or build deliberately when:

• The stack isn't Laravel, or the wallet should be a separate service shared across products — this is a Laravel trait/interface package, and that coupling is the point.
• You are in a regulated e-money, remittance, or custodial context. Licensing and audit obligations point to a purpose-built ledger (or a vendor with contractual assurance), not a community package.
• You need high-throughput writes (sustained thousands of TPS), multi-region consistency, or streaming reconciliation. Every transaction is a database write path; plan an outbox/queue strategy or a dedicated ledger.
• You need real FX, multi-currency conversion at scale, or settlement. The swap extension sets rates; it is not a treasury system.
• You require a support contract or SLA. This is MIT with community support (Telegram, Open Collective) and a small maintainer group — the release history shows mostly one primary maintainer plus dependabot and drive-by contributions.
• Ecosystem validation matters to your risk review: the dependents signal here is effectively zero, so third-party production evidence is thin. Treat that as a "run a spike" flag, not a disqualifier.
• Your schema is already large and index-sensitive: the 12.1.0 release removed four redundant indexes with meaningful gains (index size −52% MySQL / −41% Postgres; 50k-row insert −63% / −32% on their benchmark). Useful, but it means planning migrations and, for highload tables, online schema changes and manual migrations table bookkeeping.

Diligence checklist before committing: pin to a major version and read its upgrade guide; verify the lock/cache driver configuration against your infrastructure; decide the currency-precision policy up front; confirm your PSP integration writes wallet entries only after settlement; and wrap the package behind a thin domain interface so a future migration isn't a rewrite.

How to Pitch It (Stakeholders)

For executives (one paragraph): We need balances, credits, refunds, and "pay with balance" for several roadmap items. Building that correctly means ledger design, concurrency safety, and an audit trail — roughly a quarter of engineering plus ongoing accounting risk. bavix/laravel-wallet is an MIT-licensed Laravel package that already provides this: about 1,300 GitHub stars, active releases, published documentation, a public benchmark, and a stated support window through September 2028 on current Laravel and PHP versions. It handles the correctness-critical part — atomic transactions, locking, refunds, transfers, and integer-based money math — so our engineers build the product experience instead of re-deriving accounting edge cases. The trade-offs are honest: it is backend-only (no admin UI), it is maintained by a small team with community support rather than a vendor SLA, it does not move real money (we still need our payment provider), and its third-party adoption signal is thin enough that we should validate it in a bounded pilot before betting a revenue-critical flow on it.

For engineering (the short version): Drop-in HasWallet/CanPay traits and Wallet/Customer/ProductInterface contracts, migrations included, configurable lock and cache drivers, brick/math under the hood, PHPStan-friendly typed APIs, and extensions for UUID keys, exchange rates, and balance warm-up. Refunds, safePay, purchase-query checks, and multi-wallet are first-class. Known costs: schema/index footprint (recent releases trimmed redundant indexes — plan the migration, and use online schema change tooling on large tables), a disciplined major-version upgrade path, and single-service coupling. Proposal: two-week spike behind a domain interface, covering deposit/withdraw/transfer/refund plus a concurrency test, then a decision.