Cashier Mollie Laravel Package

Getting Started

First Steps

1. Installation Replace this package with the official maintained version:

   composer require mollie/laravel-cashier-mollie
   

   Publish the config (if needed):

   php artisan vendor:publish --provider="Mollie\LaravelCashierMollie\CashierMollieServiceProvider"
   

2. Configuration Set your Mollie API key in .env:

   MOLLIE_KEY=test_XXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX
   

   Configure Cashier in config/cashier.php:

   'driver' => 'mollie',
   

3. First Use Case: Create a Subscription

   use App\Models\User;
   use Mollie\LaravelCashierMollie\Facades\Cashier;
   
   $user = User::find(1);
   $user->newSubscription('main', 'price_123')->create($request->input('payment_method'));
   

Implementation Patterns

Core Workflows

1. Subscription Management

   • Create: Use newSubscription() with a plan ID and payment method.
   • Update: subscription('main')->swap('price_456').
   • Cancel: subscription('main')->cancel() or subscription('main')->cancelNow().
   • Resume: subscription('main')->resume().

2. Webhooks Handle Mollie events via Mollie_WebhookController:

   use Mollie\LaravelCashierMollie\Webhook;
   
   public function handleWebhook(Request $request)
   {
       return (new Webhook)->handle($request);
   }
   

   Register the route in routes/web.php:

   Route::post('/mollie/webhook', [MollieWebhookController::class, 'handleWebhook']);
   

3. Invoices & Payments

   • Fetch invoice: $user->subscription('main')->invoice().
   • List payments: $user->payments().

4. Coupons & Trials

   • Apply coupon: newSubscription('main')->withCoupon('SUMMER20')->create(...).
   • Start trial: newSubscription('main')->trialDays(7)->create(...).

Integration Tips

• Plan Sync: Use mollie:prices:sync to sync Mollie prices with Laravel models.
• Middleware: Protect subscription routes with EnsureUserHasSubscription.
• Testing: Use Mollie’s test mode (test_XXXX) and mock webhooks in tests.

Gotchas and Tips

Pitfalls

1. Webhook Verification

   • Always verify webhook signatures in production:

     $webhook = new Webhook();
     if (!$webhook->verify($request)) {
         abort(403);
     }
     

   • Test webhooks locally using ngrok or Mollie’s sandbox.

2. Plan ID Mismatches

   • Ensure price_* IDs in Laravel match Mollie’s API exactly (case-sensitive).
   • Use mollie:prices:sync to avoid manual errors.

3. Stale Subscriptions

   • Mollie’s API may return stale subscriptions. Use subscription()->refresh() if needed.

4. Currency & Taxes

   • Mollie requires explicit currency (e.g., EUR). Set this in your plan config.

Debugging

• Logs: Enable Mollie debug logs in .env:

  MOLLIE_DEBUG=true
  

• API Calls: Inspect raw Mollie API responses with:

  \Mollie\LaravelCashierMollie\Facades\Mollie::getClient()->setDebugMode(true);
  

Extension Points

1. Custom Webhook Logic Extend Mollie\LaravelCashierMollie\Webhook to add custom handlers:

   public function handlePaymentSucceeded($payload)
   {
       // Custom logic (e.g., send email)
   }
   

2. Plan Validation Override validatePlan() in a service provider to enforce custom rules:

   Cashier::extend('mollie', function ($app) {
       return new class extends \Mollie\LaravelCashierMollie\Cashier {
           protected function validatePlan($plan)
           {
               // Custom validation
           }
       };
   });
   

3. Payment Method Storage Store additional payment method details in a payment_methods table:

   $user->paymentMethods()->create([
       'mollie_id' => $paymentMethod->id,
       'brand' => $paymentMethod->brand,
   ]);
   

Config Quirks

• Test Mode: Always use test_ keys in .env for development.
• Environment Variables: Prefix Mollie keys with MOLLIE_ (e.g., MOLLIE_KEY, MOLLIE_WEBHOOK_SECRET).
• Webhook Secret: Set MOLLIE_WEBHOOK_SECRET in .env for production security.

Performance

• Batch Operations: Use Mollie\LaravelCashierMollie\Facades\Mollie directly for bulk API calls to avoid Cashier overhead.
• Caching: Cache subscription data if frequently accessed:

  $subscription = Cache::remember("user_{$user->id}_subscription", now()->addHours(1), function () use ($user) {
      return $user->subscription('main');
  });