Laravel-mollie v4: Full support for mollie-api-php v3 and first-class webhook handling

The laravel-mollie package has been our go-to wrapper for Mollie's API in Laravel projects for years. We're releasing version 4, which brings full support for mollie-api-php v3 and introduces proper webhook handling out of the box.

Why This Matters

If you're running a Laravel application with Mollie payments, you've likely been stuck on mollie-api-php v2. Version 3 introduced typed request objects, a cleaner API surface, and support for newer Mollie features. But laravel-mollie didn't support it. Until now.

What's New in v4

mollie-api-php v3 support with typed requests. You can now use Mollie's typed request objects directly:

use Mollie\Api\Http\Requests\CreatePaymentRequest;

Mollie::send(new CreatePaymentRequest(
    description: 'Order #12345',
    amount: Money::EUR('99.99'),
    redirectUrl: route('payment.success'),
));

First-class webhook handling with event payloads. Mollie has been rolling out a new webhook system that includes full event payloads — no more fetching the resource after receiving a webhook. v4 is built for this:

• ValidatesWebhookSignatures middleware for signature validation
• HandleIncomingWebhook controller for processing requests
• WebhookDispatcher service with extensible event handling
• SetupWebhookCommand artisan command to configure webhooks via the API

The webhook route file (routes/webhook.php) is included and ready to customize. As Mollie expands their event types, your application is ready to handle them without code changes.

Improved performance. Both service providers (MollieServiceProvider and MollieSocialiteServiceProvider) are now deferred, so they only load when actually needed.

Breaking Changes

Minimum requirements:

• PHP 8.2+
• Laravel 11.x or 12.x

Removed:

• Mollie\Laravel\MollieManager class (use the Mollie facade)
• mollie() global helper (use Mollie::api() or dependency injection)
• Support for Laravel 10.x and earlier
• Support for PHP 8.1 and earlier

API changes from mollie-api-php v3:

• Endpoint access changed from methods to properties ($mollie->payments() → $mollie->payments)
• Metadata only accepts arrays (not strings or objects)

See the mollie-api-php upgrade guide for the complete list.

Upgrading

For existing projects, the migration is straightforward but requires attention to the endpoint property changes and metadata format. We're finalizing the UPGRADING.md document in the repository with step-by-step instructions.

If you're running a high-volume payment integration and want to ensure a smooth transition, reach out to us — this is exactly what we do as Mollie's Preferred Integration Partner.

Contributors

Credit to Naoray (Krishan König) for driving the v4 development, and the Mollie team for the v3 API improvements that made this possible.

---

Sandorian is Mollie's first Preferred Integration Partner. We build robust, scalable payment integrations for European SaaS and fintech companies.