Laravel Wallet Laravel Package

Product Decisions This Supports

• Defines the failure contract for insufficient funds. Whether a payment attempt fails loudly (UnacceptedTransactionException) or returns a soft false is a product decision, not purely an implementation detail: it determines what the user sees at checkout, whether the flow retries, and whether the failure is surfaced in analytics. This release lets that decision be made per-surface (e.g. strict enforcement in withdrawals, soft-fail in low-stakes flows like promo credits or metered usage), rather than being locked to one global behavior.
• Shapes flow-level UX for balance-dependent journeys. Relevant to checkout, subscription renewal, gifting/top-ups, refunds, payouts, and any metered-billing surface. Product can decide, per journey, whether an empty wallet produces a blocking error, a graceful "add funds" prompt, or a silent skip.
• Reduces integration cost for teams that treat balance as a pre-check rather than an exception path. Removing mandatory try/catch boilerplate lowers the effort to build secondary flows (dashboards, internal tooling, batch jobs) that just need to know "can this proceed? yes/no."
• Roadmap signal: the package is maturing in configurability rather than adding ledger primitives. Treat it as stabilizing, and prioritize adopting it if the alternative is a homegrown balance column with ad-hoc checks.
• Build vs. buy: this reinforces "buy/adopt" for wallet mechanics. Do not hand-roll a balance ledger to get one configurable failure mode.

When to Consider This Package

• Consider adopting when: you need a transactional wallet/ledger with balance enforcement, and your product has more than one balance-dependent flow with different tolerance for failure. The new opt-in false behavior is exactly what lets one package serve both a hard-gated payout flow and a forgiving consumption flow.
• Consider only after verification when: you need multi-currency, double-entry accounting, reconciliation/statement exports, regulatory audit trails, or high write throughput. Insufficient-funds handling is a small slice of those problems.
• Look elsewhere when: you require strict, non-suppressible enforcement everywhere (e.g. regulated stored-value or financial disbursement) — a mode that can return false instead of raising is a liability if it can be enabled accidentally or inherited by new call sites.
• Adoption criteria to confirm before committing:
  • Confirm this behavior is opt-in and default-off; if the default ever flips, that is a breaking semantic change for every existing try/catch.
  • Confirm the failure is still recorded (attempted transaction, reason, actor) when false is returned — otherwise you lose auditability and debugging signal.
  • Confirm false is distinguishable from other falsy outcomes (e.g. zero-amount transactions) so callers don't misread success as failure.
  • Require a documented, lintable convention for which flows use which mode; inconsistency across a codebase is the real risk here, not the feature itself.

How to Pitch It (Stakeholders)

Executive summary: This release makes insufficient-balance handling a configurable product decision instead of a hard-coded error path. Teams can now choose, per flow, whether an empty wallet raises an exception or returns a simple false — so forgiving journeys (promo credits, metered usage, internal tooling) stop surfacing hard errors to users, while high-stakes flows (payouts, withdrawals) keep strict enforcement. It is a small, additive change with no new infrastructure and no migration.

For engineering: additive and backwards compatible — existing exception-based call sites are unaffected, and the false return is opt-in. Benefit is reduced try/catch boilerplate at call sites that only need a boolean gate. Two requirements before rollout: (1) guarantee the suppressed path still writes an audit record with a failure reason, and (2) standardize per-flow usage so we don't end up with two error conventions in the same domain.

Product recommendation: adopt as part of the wallet integration, but gate it behind an explicit, documented choice per flow — not a global setting. Revisit if a future release changes the default, since that would alter the failure contract for all existing consumers.