Payment Laravel Package

Product Decisions This Supports

What it is, in product terms: Vanilo's payment module is the provider-agnostic layer of a Laravel commerce stack — it owns the payment record (a payment tied to an order/payable), the payment method (admin-configurable, per-channel), the status lifecycle (created → pending → authorized/paid → refunded/failed/cancelled), and a gateway contract that provider integrations implement. In other words: it is the seam between "our order" and "their money."

Decisions it directly informs:

• Build vs. buy the payment layer. It is a ready-made abstraction with an MIT license and no per-transaction fee. The decision it supports is whether to own a provider-agnostic payment domain model (this) versus renting that layer (Stripe Checkout, Paddle, Lemon Squeezy) or going single-provider deep (Laravel Cashier). Choosing this package is choosing control over checkout UX and provider optionality in exchange for owning integration and upgrade work.
• Gateway optionality as a roadmap hedge. Because adding a provider is a driver-level change rather than an order-flow rewrite, this package turns "which PSP do we launch with?" from a one-way door into a reversible decision — high value when you are negotiating rates, entering a region where your current PSP is weak, or hedging against a provider's pricing change.
• Market and channel expansion sequencing. Vanilo's channel concept plus per-method configuration means "can we enable iDEAL for NL and cards for US without forking the codebase?" becomes a scoping question, not an architecture question. Directly informs whether a new region is a 2-week or 2-quarter initiative.
• Finance/ops feature scope: refunds, partial refunds, voids, reconciliation. Persisted payment records with status transitions are the prerequisite for any admin refund workflow, finance export, or dispute handling. If refunds are on the roadmap, this is a build-vs-buy line item you can close cheaply.
• Adopting the Vanilo suite vs. assembling best-of-breed. This module is one node in a suite (cart, checkout, order, product, tax, shipment, admin). Adopting it is rarely a standalone decision — it is a signal that you are evaluating a coherent framework over a stitched-together stack, which trades flexibility for lower integration cost and a single upgrade cadence.
• Explicit scope exclusions. It does not do subscription billing, proration, dunning, invoicing, or tax calculation. Naming that boundary is what keeps a "we'll just use a payments module" plan from quietly becoming a billing-platform project.

When to Consider This Package

Consider it when:

• You are on Laravel and building a commerce domain (physical or digital goods) where orders need a durable payment record, not just a redirect.
• You are already using, or seriously evaluating, the Vanilo suite (vanilo/order, vanilo/checkout, vanilo/cart). The payment module expects to bind to a payable/order entity; used in isolation it becomes a glue-writing exercise and much of its value evaporates.
• You need provider-agnostic abstraction with persistence: multiple gateways live at once, admin-editable payment methods, refunds, and an auditable status history.
• You want forkable, MIT-licensed code with no revenue share, and you have — or can hire — someone comfortable reading framework source and tracking upgrades.
• You are small enough that one coherent framework beats five best-of-breed packages, and disciplined enough to keep the payment seam thin.

Look elsewhere when:

• Recurring revenue is core. Subscriptions, proration, dunning, SCA/3DS handling, and invoice generation are Laravel Cashier's job and this module's explicit non-goal.
• You have one provider and simple one-time charges. A provider SDK or hosted checkout gets you to market faster with a materially smaller PCI surface.
• You need enterprise commerce breadth — B2B price lists, complex promotions, multi-warehouse fulfillment, hard SLAs, commercial support contracts. Sylius, Spryker, commercetools, or Shopify are the honest comparisons there, not a 6-star module.
• You are not on Laravel, or you cannot absorb churn across Laravel major versions and the underlying Concord module system.
• You need a turnkey admin experience. Vanilo's admin is a separate package with its own stack assumptions; validate the fit before committing.

Adoption diligence — do these before committing. The standalone repository metrics (6 stars, 0 dependents) are not the health signal; the real signal is the umbrella project. Check instead: (1) the vanilo/framework release cadence and Laravel version matrix; (2) test coverage and CI status on this module; (3) whether the provider drivers you need — Stripe, PayPal, etc. — are separate packages that are actually maintained, since the abstraction is only worth what its drivers are; (4) whether refunds and partial refunds are first-class in the current version rather than aspirational. Run all four as a timeboxed spike, not a research project.

How to Pitch It (Stakeholders)

For executives — the one-paragraph version: This is an open-source (MIT, zero license cost) payments module from a Laravel e-commerce framework. Its job is to make our payment provider a configurable integration instead of a load-bearing architectural choice — so switching PSPs, adding a regional method, or enabling refunds is work measured in days rather than a checkout rebuild. The trade-off is honest: it is a small project, so we are taking on dependency risk and some maintenance ownership in exchange for provider flexibility and speed to a second gateway. Recommendation: adopt as a bounded pilot behind one storefront with a 4–6 week go/no-go gate; because the provider seam is thin, the exit cost stays low and we retain the option to fall back to hosted checkout.

For engineering — what you are actually signing up for: You get Eloquent-backed payment and payment-method models, a gateway contract and registry so each provider is a driver rather than a branch in the checkout controller, a status lifecycle with events to hook order state and notifications onto, and a refund path. That is real leverage: the second gateway is incremental, not a rewrite. The costs are equally real — you own the integration and the upgrade path, using it outside the Vanilo suite means writing the payable/order glue yourself, and the provider drivers live in sibling packages whose maintenance you must verify before you depend on them. The ask: one spike that integrates our current provider plus a second sandbox provider end-to-end, including a refund. If the abstraction holds across two providers with no order-flow changes, the architecture argument is settled on evidence; if it doesn't, we learned that cheaply.