Laravel Mollie Billing Laravel Package

Getting Started

Minimal Steps

1. Installation:

   composer require graystackit/laravel-mollie-billing
   php artisan vendor:publish --tag=mollie-billing-config
   php artisan vendor:publish --tag=mollie-billing-migrations
   php artisan vendor:publish --tag=mollie-billing-views
   php artisan migrate
   

2. Configure .env:

   BILLING_MOLLIE_KEY=test_xxxxxxxxxxxxxxxxxxxxxxxxxxxx
   BILLING_BILLABLE_MODEL=App\Models\Organization
   BILLING_BILLABLE_KEY_TYPE=uuid
   BILLING_USER_KEY_TYPE=int
   BILLING_CURRENCY=EUR
   

3. Set Up Routes (in routes/web.php):

   Route::middleware(['web', 'auth', 'tenant'])->group(function () {
       MollieBilling::routes(); // Customer portal
   });
   
   Route::middleware(['web', 'auth'])->group(function () {
       MollieBilling::checkoutRoutes(); // Checkout flow
   });
   

4. Implement Billable Contract:

   use GraystackIT\MollieBilling\Concerns\HasBilling;
   use GraystackIT\MollieBilling\Contracts\Billable;
   
   class Organization extends Model implements Billable
   {
       use HasBilling;
   
       public function getUsedBillingSeats(): int
       {
           return $this->users()->count();
       }
   }
   

5. Resolve Billable in AppServiceProvider:

   MollieBilling::resolveBillableUsing(fn () => auth()->user()?->currentOrganization);
   MollieBilling::authUsing(fn () => auth()->check());
   

6. Validate Config:

   php artisan billing:check-config
   

First Use Case

Trigger the checkout flow for a user:

use GraystackIT\MollieBilling\Facades\MollieBilling;

$organization = new Organization();
MollieBilling::checkout($organization, 'basic-plan');

Implementation Patterns

Core Workflows

1. Subscription Management:

   • Create a subscription:

     $subscription = MollieBilling::createSubscription($billable, 'premium-plan');
     

   • Cancel a subscription:

     $subscription->cancel();
     

   • Update a subscription (e.g., change plan or add addons):

     $subscription->updatePlan('pro-plan', ['addon1', 'addon2']);
     

2. Wallet-Based Metered Billing:

   • Charge for usage:

     $wallet = $billable->wallet();
     $wallet->charge('api_calls', 100, ['price' => 0.01]);
     

   • Handle overages:

     $wallet->handleOverages(); // Automatically charges overages
     

3. Coupon Application:

   • Apply a coupon during checkout:

     MollieBilling::checkout($billable, 'basic-plan', coupon: 'SUMMER20');
     

4. Plan Changes:

   • Schedule a plan change (e.g., downgrade at end of period):

     $subscription->schedulePlanChange('basic-plan', now()->addMonth());
     

5. Refunds and Credits:

   • Issue a refund:

     $subscription->refund(100.00, 'Customer requested refund');
     

   • Apply credits:

     $billable->applyCredits(50.00, 'Trial extension');
     

Integration Tips

• Feature Gating: Use the @planFeature Blade directive to restrict access:

  @planFeature('analytics')
      <div>Analytics Dashboard</div>
  @endplanFeature
  

• Checkout Flow: Customize the checkout steps by overriding Livewire components in resources/views/vendor/mollie-billing/.

• Admin Panel: Extend the admin panel by publishing and overriding views:

  php artisan vendor:publish --tag=mollie-billing-views
  

• Webhooks: Handle Mollie webhooks by extending the MollieBillingServiceProvider:

  MollieBilling::extendWebhookHandling(function ($event, $payload) {
      // Custom logic for specific events
  });
  

• Localization: Override translations:

  php artisan vendor:publish --tag=billing-lang
  

• URL Generation: Generate signed promotion links:

  $url = MollieBilling::promotionUrl($billable, 'basic-plan', 'SUMMER20');
  

Gotchas and Tips

Pitfalls

1. Key Type Configuration:

   • billable_key_type and user_key_type must be set before running migrations. Changing them later requires manual column alterations.

2. Tenant Resolution:

   • Ensure PropagateRouteDefaults middleware is applied to tenant-scoped routes to propagate route parameters (e.g., organization:slug) into generated URLs.

3. Checkout Flow:

   • The checkout route is mounted outside tenant-scoped routes. If resolveBillableUsing returns null, the package falls back to query parameters (e.g., ?organization=acme-corp).

4. Wallet Integration:

   • The package rewrites wallets.holder_id and related columns to match billable_key_type. Ensure your migrations align with this.

5. Coupon Validation:

   • Coupons are validated against the current plan and addons. Invalid combinations (e.g., a Recurring coupon on a SinglePayment plan) will throw errors.

6. VAT/OSS Compliance:

   • Country mismatches (user-declared vs. payment-derived vs. IP-derived) trigger automatic cancellation at period-end. B2B customers with VIES-validated VAT numbers bypass this check.

7. Livewire Dependencies:

   • The package requires livewire/flux-pro (commercial license). Ensure it’s installed separately:

     composer require livewire/flux-pro
     

8. Tailwind CSS:

   • Add the package’s Blade views to your Tailwind content config to avoid purging utility classes:

     // vite.config.js
     content: [
         './resources/views/**/*.blade.php',
         './vendor/graystackit/laravel-mollie-billing/resources/views/**/*.blade.php',
     ],
     

Debugging

1. Config Validation: Use php artisan billing:check-config to catch syntax errors or misconfigurations early.

2. Webhook Debugging: Enable Mollie webhook logging in config/mollie-billing.php:

   'webhook_logging' => true,
   

3. Subscription States: Check subscription statuses via the admin panel or directly:

   $subscription->status; // 'active', 'cancelled', 'past_due', etc.
   

4. Wallet Transactions: Audit wallet transactions:

   $wallet->transactions()->latest()->get();
   

Extension Points

1. Custom Billable Creation: Override createBillableUsing to customize billable creation logic (e.g., attach users or set default values).

2. Checkout Hooks: Use beforeCheckoutUsing and afterCheckoutUsing to run logic before/after checkout (e.g., user creation or cleanup).

3. Orphaned Billable Cleanup: Register a closure for cleanupOrphanedBillablesUsing to handle cascading deletes for abandoned checkouts.

4. Webhook Handling: Extend webhook logic via extendWebhookHandling for custom event processing.

5. URL Parameter Resolution: Override urlParametersUsing or urlRouteParameters() for custom URL generation logic in non-request contexts.

6. Feature Keys: Extend feature keys in config/mollie-billing-plans.php to add new plan features.

7. Localization: Override translations in resources/lang/vendor/billing/ to customize messages.

8. Views: Publish and override Livewire/Blade views for full customization of the portal, checkout, or admin panel.