Weave Code
Laravel Mollie Billing Laravel Package
graystackit/laravel-mollie-billing
Batteries-included Mollie billing for Laravel with VAT/OSS compliance, VIES validation, wallet-based metered billing, coupons, trials, scheduled plan changes, webhooks/mandates, an admin panel, and a Livewire 4 customer portal for any Billable model.
graystackit/laravel-mollie-billing is a batteries-included billing layer for Laravel that wraps Mollie’s official SDK and adds a complete subscription stack around a Billable model (often an Organization, not a User). It focuses on production-ready compliance and self-service billing flows.
Includes VAT/OSS tooling, metered billing via wallets, and ready-made UI for admins and customers.
- Mollie subscriptions, mandates & webhooks (SDK v4, typed requests)
- VAT/OSS compliance: VAT calc, VIES validation, OSS export
- Country-mismatch reconciliation with auto cancel-at-period-end + self-correction flow
- Wallet-based metered billing, coupons, trials, and scheduled plan changes
- Built-in admin panel and Livewire 4 customer portal
Frequently asked questions about Laravel Mollie Billing
- What Laravel versions does this package support, and do I need PHP 8.3+?
- This package requires **Laravel 12 or 13** and **PHP 8.3+** due to Livewire 4 and Mollie SDK v4 dependencies. If your project uses an older stack, you’ll need to upgrade dependencies, which may introduce compatibility risks. Always test thoroughly after upgrading.
- How does the VAT/OSS compliance system handle country mismatches (e.g., user declares France but pays from the US)?
- The package uses **three-way reconciliation**: user-declared country, payment-derived country, and IP-derived country. If they mismatch, subscriptions auto-cancel at period-end, trigger a refund/reissue at the correct VAT rate, and notify the user via email. B2B customers with VIES-validated VAT numbers bypass this check entirely (reverse-charge scenario).
- Can I use this for one-off payments, or is it strictly for subscriptions?
- While the package is optimized for **subscriptions**, you can still use Mollie’s underlying SDK for one-off payments via the `mollie/laravel-mollie` integration. However, features like VAT/OSS compliance, wallets, and the customer portal are subscription-focused. For simple payments, consider `mollie/laravel-mollie` alone.
- Does the Livewire 4 customer portal require Flux Pro, and is there a free alternative?
- Yes, the **admin panel and customer portal** require **Flux Pro** (a commercial Livewire component library). There’s no free alternative provided, so factor in licensing costs (~$100/year) and team onboarding time for Livewire if your project doesn’t already use it.
- How do I integrate this with an existing `Organization` or `User` model as the `Billable`?
- Implement the `Billable` contract on your model (e.g., `Organization`) by defining `getMollieCustomerId()`, `getBillingCountry()`, and `getVatNumber()`. The package handles polymorphic relations via UUID/ULID, so ensure your primary keys match. Run the migrations to add Mollie, wallet, and VAT tables.
- What happens if Mollie webhooks fail or time out? Can I customize retry logic?
- The package includes **webhook handling** for subscriptions, mandates, and payments, but custom logic (e.g., syncing with your database) may still be needed. Failed webhooks can be retried via Mollie’s dashboard or by extending the `MollieWebhookHandler` class. For critical events, consider adding a **dead-letter queue** to log and alert on failures.
- Are there alternatives for metered billing without using `bavix/laravel-wallet`?
- The package **requires** `bavix/laravel-wallet` for wallet-based metered billing (e.g., pay-as-you-go usage). If you need a lighter solution, you could build custom usage tracking with a `usage_logs` table and calculate charges manually, but you’d lose the built-in reconciliation and overage handling.
- How do I handle custom VAT rules (e.g., zero-rated items, regional exemptions)?
- The package uses `mpociot/vat-calculator` for base VAT logic, but you can **override rates per product or subscription** via the `VatRate` model or by extending the `VatService`. For complex scenarios (e.g., EU OSS vs. non-EU VAT), document edge cases and use the **admin override** feature to manually adjust rates when needed.
- Can I use this for B2B customers with reverse-charge VAT (e.g., EU OSS)?
- Yes, the package supports **reverse-charge scenarios** for B2B customers. If a `Billable` has a **VIES-validated VAT number**, the system skips country-mismatch checks and applies reverse-charge rules automatically. Ensure your `Organization` model includes `getVatNumber()` and `isB2B()` methods.
- What’s the best way to test this in a staging environment before production?
- Use Mollie’s **test mode** with sandbox API keys and mock webhooks via `mollie/laravel-mollie`'s testing helpers. Test VAT scenarios with fake VIES numbers (e.g., `DE123456789` for Germany) and simulate country mismatches. For wallets, use the `bavix/laravel-wallet` testing tools to verify metered billing logic without real charges.
Weaver
How can I help you explore Laravel packages today?