Laravel Mollie Billing Laravel Package

Technical Evaluation

Architecture Fit

• Pros:

  • Batteries-included: Combines Mollie subscriptions, VAT/OSS compliance, wallet-based metered billing, coupons, and a Livewire 4 customer portal—reducing custom development effort.
  • Modular Design: Built on mollie/laravel-mollie (v4) with typed request objects, ensuring compatibility with Mollie’s ecosystem.
  • Contract-Driven: Uses a Billable contract (e.g., Organization), enabling flexible integration with existing models.
  • Feature-Rich: Supports complex billing scenarios (prorated changes, scheduled plan updates, trial flows, and refunds) out of the box.
  • Admin & Customer Portals: Pre-built Livewire 4 panels (Flux Pro required) for self-service and admin management.
  • VAT/OSS Compliance: Automated VAT validation, country reconciliation, and OSS export via mpociot/vat-calculator.
  • Wallet-Based Metering: Integrates bavix/laravel-wallet for usage tracking and overage charging.

• Cons:

  • Tight Coupling to Livewire/Flux Pro: Requires livewire/flux-pro (commercial license), which may increase costs and lock into Livewire’s ecosystem.
  • Laravel 12/13 Only: No support for older Laravel versions, limiting adoption for legacy systems.
  • Complexity: Features like VAT reconciliation, coupon engines, and wallet metering add layers of abstraction that may require deep understanding to customize.
  • Mollie Dependency: Locks into Mollie’s API, which may introduce vendor-specific constraints (e.g., pricing, compliance).

Integration Feasibility

• High for Greenfield Projects: Ideal for new Laravel 12/13 apps targeting EU markets (VAT/OSS compliance) or requiring metered billing.
• Moderate for Existing Systems:
  • Requires alignment with the Billable contract (e.g., Organization model).
  • May need refactoring to adopt wallet-based metering or Livewire 4 if not already in use.
  • Flux Pro Dependency: Commercial license adds cost; alternatives (e.g., custom Livewire panels) would require significant effort.
• Multi-Tenancy Support: Designed for tenant-aware apps (e.g., SaaS), with route prefixing and billable resolution logic.

Technical Risk

• Medium-High:
  • Migration Risk: Adopting wallet-based metering or switching from traditional subscriptions to this package’s model requires data migration (e.g., converting existing subscriptions to the new schema).
  • Customization Overhead: Overriding views, translations, or business logic (e.g., VAT rules) may require deep diving into the package’s internals.
  • Livewire/Flux Pro Dependency: If the team lacks Livewire experience, portal development or debugging could slow progress.
  • VAT/OSS Complexity: Misconfigurations in VAT handling (e.g., country mismatches) could lead to compliance issues or revenue leaks.
• Mitigation:
  • Pilot Testing: Start with a non-critical tenant or sandbox environment to validate VAT rules, wallet metering, and portal UX.
  • Documentation Review: The package includes a billing:check-config command to catch misconfigurations early.
  • Fallback Mechanisms: Features like manual admin overrides for VAT mismatches reduce risk.

Key Questions

1. Business Requirements:
   • Does the project require VAT/OSS compliance (EU market) or metered billing? If not, is the package’s complexity justified?
   • Are there existing billing systems (e.g., Stripe, custom) that would conflict with this integration?
2. Technical Constraints:
   • Can the team adopt Livewire 4 and Flux Pro, or are there budget/license constraints?
   • Is the Billable contract (e.g., Organization) already defined, or will it require model refactoring?
   • How will existing subscriptions (if any) migrate to the new wallet-based system?
3. Scaling Needs:
   • Will the package’s admin panel and customer portal meet scalability demands (e.g., high-traffic portals)?
   • Are there plans for multi-currency support beyond the configured BILLING_CURRENCY?
4. Compliance and Auditing:
   • How will VAT/OSS exports integrate with accounting systems (e.g., QuickBooks, SAP)?
   • Are there requirements for audit logs or reconciliation beyond what the package provides?
5. Vendor Lock-In:
   • Is Mollie’s API pricing/model stable enough for long-term use, or are there contingency plans for switching payment providers?

Integration Approach

Stack Fit

• Ideal Stack:
  • Backend: Laravel 12/13 with PHP 8.3+.
  • Frontend: Livewire 4 (for portals) + Tailwind CSS (for styling).
  • Payments: Mollie API (v4 SDK).
  • Database: Supports UUID/ULID keys (for billable_key_type).
  • Queue: For async operations (e.g., webhook processing, cleanup jobs).
• Compatibility:
  • Pros:
    • Seamless with Laravel’s ecosystem (e.g., Eloquent, Blade, Queues).
    • Mollie’s SDK is battle-tested for Laravel.
    • Wallet-based metering (bavix/laravel-wallet) integrates cleanly.
  • Cons:
    • Livewire Dependency: If the app uses Inertia.js, Vue, or React, the Livewire portals may require wrappers or rebuilds.
    • Tailwind CSS: Views rely on Tailwind utilities; custom CSS frameworks may need adjustments.
    • Flux Pro: Commercial license adds cost; alternatives would require rebuilding portal UX.

Migration Path

1. Assessment Phase:
   • Audit existing billing logic (e.g., Stripe, custom subscriptions) to identify gaps/overlaps.
   • Validate Billable model compatibility (e.g., Organization vs. User).
   • Test VAT/OSS requirements with a subset of EU customers.
2. Pilot Integration:
   • Set up a sandbox environment with Mollie test keys.
   • Implement the Billable contract and publish config/migrations.
   • Test the checkout flow, wallet metering, and VAT reconciliation.
3. Parallel Run (Optional):
   • For existing subscriptions, build a dual-writing system (e.g., sync old subscriptions to new wallet-based model).
   • Use feature flags to toggle between old/new billing paths.
4. Full Cutover:
   • Migrate historical data (e.g., subscriptions, refunds) to the new schema.
   • Deprecate old billing logic and redirect traffic to the new portal.
   • Monitor Mollie webhooks and VAT reconciliation for errors.

Compatibility

• Laravel:
  • Works with Laravel 12/13; no support for older versions.
  • Requires PHP 8.3+ (for typed properties, enums, etc.).
• Mollie:
  • Built on Mollie’s Laravel SDK v4; ensure API version alignment.
  • Supports Mollie’s subscriptions, mandates, and webhooks.
• Database:
  • Supports uuid, ulid, or int for billable_key_type and user_key_type.
  • Migrations handle schema changes (e.g., converting wallets.holder_id to UUID).
• Frontend:
  • Livewire 4: Mandatory for portals; Flux Pro required for checkout/admin panels.
  • Tailwind CSS: Views use Tailwind utilities; ensure your build pipeline includes the package’s Blade files as content sources.

Sequencing

1. Prerequisites:
   • Install dependencies: composer require graystackit/laravel-mollie-billing livewire/flux-pro.
   • Configure .env and config/mollie-billing.php (including billable_model and key types).
   • Run migrations: php artisan migrate.
2. Core Setup:
   • Implement the Billable contract on your model (e.g., Organization).
   • Define plans in config/mollie-billing-plans.php.
   • Register callbacks (e.g., createBillableUsing, resolveBillableUsing) in AppServiceProvider.
3. Routing:
   • Mount routes in routes/web.php with appropriate middleware (e.g., auth, tenant).
   • Configure URL parameter resolution for non-request contexts (e.g., queues).
4. Frontend:
   • Ensure Vite/Tailwind includes the package’s Blade files as content sources.
   • Publish views/translations if customizing: php artisan vendor:publish --tag=mollie-billing-views.
5. Testing:
   • Validate config: php artisan billing:check-config.
   • Test checkout flow, VAT reconciliation, and wallet metering.
6. Deployment:
   • Roll out in phases (e.g., new signups first, then existing customers).
   • Monitor Mollie webhooks and error logs for issues.

Operational Impact

Maintenance

• **Pro