Laravel Wallet Laravel Package

Product Decisions This Supports

• Build vs. buy on money movement. The package owns the wallet primitive — atomic balance mutation, locking, decimal handling — so the roadmap question becomes "what do we build on top of balances" (payouts, credits, refunds, gating) rather than "how do we safely decrement a number."
• API error contract design (v1.2.0 is the relevant lever). Insufficient funds can now be configured to surface as false instead of throwing UnacceptedTransactionException. That is a product-facing decision, not just a code style one: it determines whether a failed withdrawal becomes a 402/422 error response, a soft "insufficient balance" UI state, or a queue/retry path. Pick the semantics per surface — checkout flows usually want the boolean for validation-style UX; ledger-to-ledger transfers usually want the exception so nothing silently no-ops.
• Roadmap sequencing for wallet features. Because failure semantics are now configurable, you can ship low-risk read-and-validate flows (balance checks, "can they afford this?" guards) before committing to irreversible debit flows.
• Scope boundaries for v1. Decide early whether this package is your ledger of record or a convenience balance cache. That single call determines months of downstream work (reconciliation, reporting, dispute handling).
• Use cases this unlocks cheaply: promotional credits and vouchers, refund-to-wallet, prepaid top-ups, usage metering with a spend cap, gated content/entitlements backed by a balance.

When to Consider This Package

Adopt when:

• You are on Laravel/PHP and already run the framework's DB transactions, queue, and Eloquent conventions — the integration cost is low and idiomatic.
• You need multi-wallet, per-user balances with atomic debits and concurrency safety, and you do not want to hand-roll row locking.
• Your correctness bar is "balances must never go negative and must reconcile to the sum of transactions" — not "must satisfy an auditor's double-entry journal."
• You want configurable failure semantics (v1.2.0) so different call sites can opt into exception-driven or return-value-driven control flow without forking.

Look elsewhere when:

• You need true double-entry accounting, immutable append-only journals, FX/multi-currency conversion, or regulatory/tax reporting — use a dedicated ledger service or an accounting-grade system.
• You expect very high write volume or cross-service balance reads; a package inside one Laravel app becomes a coupling point fast.
• You require strong idempotency guarantees and reconciliation tooling out of the box — verify this explicitly before committing, and treat its absence as a build item, not an assumption.
• Your team is not on Laravel, or you are standardizing money handling across polyglot services.

Caveat on v1.2.0 specifically: the default behavior is unchanged (exception still thrown), so this is additive and non-breaking. But enabling the false mode silently changes the contract at every call site that previously relied on try/catch — treat flipping that flag as a reviewed, per-surface decision with tests, not a global config toggle.

How to Pitch It (Stakeholders)

To executives: This package gives us a battle-tested wallet primitive — balances, atomic debits, and concurrency safety — instead of us writing money-movement code ourselves. That is the highest-risk, lowest-differentiation code in any payments-adjacent product, and buying it moves our timeline from weeks to days while removing a class of race-condition bugs that are expensive to find in production. The latest release also lets us choose, per feature, whether "insufficient funds" is a hard error or an expected user state — which means better checkout UX without extra engineering.

To engineering: Adopt it as the balance store, not as the ledger of record. Map the transaction table into our own reconciliation job from day one, and be deliberate about exception vs. false per call site: exception for anything that must not silently no-op (transfers, payouts), boolean for validation-style guards (cart affordability, spend caps). Default behavior is unchanged in v1.2.0, so this is a safe upgrade — but any place we flip the flag needs a test asserting the new return contract.