Getting Started

Minimal Setup

Installation

composer require mollie/laravel-mollie

Publish the config file:

php artisan vendor:publish --provider="Mollie\LaravelMollie\MollieServiceProvider" --tag="mollie-config"

Configuration Add your Mollie API key to .env:
```
MOLLIE_KEY=test_XXXXXXXXXXXXXXXXXXXXXXXXXXXX
```
Set your preferred locale (e.g., nl_NL, en_US) in config/mollie.php.

First Use Case: Create a Payment

use Mollie\LaravelMollie\Facades\Mollie;

$payment = Mollie::payments()->create([
    'amount' => [
        'currency' => 'EUR',
        'value' => '10.00',
    ],
    'description' => 'Order #12345',
    'method' => 'ideal', // or 'creditcard', 'paypal', etc.
    'redirectUrl' => route('payment.success'),
]);

return redirect()->to($payment->getCheckoutUrl());

Webhook Setup Add the Mollie webhook endpoint to your routes/web.php:

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

public function boot()
{
    $this->routes(function () {
        Route::post('/mollie/webhook', [MollieWebhookController::class, 'handleWebhook'])
            ->middleware('signed'); // Optional: Add CSRF protection
    });
}

Implementation Patterns

Common Workflows

1. Payment Creation & Management

Dynamic Payments Use a service class to abstract payment logic:

class PaymentService {
    public function createOrderPayment(Order $order)
    {
        return Mollie::payments()->create([
            'amount' => [
                'currency' => $order->currency,
                'value' => $order->total,
            ],
            'description' => 'Order #' . $order->id,
            'metadata' => ['order_id' => $order->id],
            'webhookUrl' => route('mollie.webhook'),
        ]);
    }
}

Subscription Handling For recurring payments:

$subscription = Mollie::subscriptions()->create([
    'amount' => ['currency' => 'EUR', 'value' => '9.99'],
    'interval' => 'month',
    'times' => null, // Unlimited
    'metadata' => ['customer_id' => $user->id],
    'webhookUrl' => route('mollie.webhook'),
]);

2. Webhook Processing

Event-Driven Logic Handle webhooks in a dedicated controller:

class MollieWebhookController extends Controller {
    public function handleWebhook(Request $request)
    {
        $event = Mollie::webhooks()->handle($request->getContent());

        switch ($event->type) {
            case 'payment.authorized':
                $this->handleAuthorizedPayment($event->data->id);
                break;
            case 'payment.paid':
                $this->fulfillOrder($event->data->id);
                break;
            case 'payment.failed':
                $this->handleFailedPayment($event->data->id);
                break;
        }

        return response()->json(['status' => 'success']);
    }
}

Idempotency Use the idempotencyKey in API calls to avoid duplicate processing:

$payment = Mollie::payments()->create([
    'amount' => ['currency' => 'EUR', 'value' => '10.00'],
    'idempotencyKey' => 'unique-key-' . Str::uuid(),
]);

3. Mollie Connect (Socialite Integration)

Authenticate Users Add Mollie Connect to your Socialite config (config/services.php):

'mollie' => [
    'client_id' => env('MOLLIE_CONNECT_CLIENT_ID'),
    'client_secret' => env('MOLLIE_CONNECT_CLIENT_SECRET'),
    'redirect' => env('MOLLIE_CONNECT_REDIRECT_URI'),
],

Use in a controller:

public function redirectToMollieConnect()
{
    return Socialite::driver('mollie')->redirect();
}

public function handleMollieConnectCallback()
{
    $user = Socialite::driver('mollie')->user();
    // Attach user data to your app's user model
}

4. Refunds & Captures

Refund a Payment

$payment = Mollie::payments()->get('p_XXXXXXXXXXXXXXXXXXXXXXXXXXXX');
$refund = $payment->refunds()->create([
    'amount' => ['currency' => 'EUR', 'value' => '5.00'],
    'description' => 'Partial refund',
]);

Capture a Payment

$payment = Mollie::payments()->get('p_XXXXXXXXXXXXXXXXXXXXXXXXXXXX');
$payment->capture();

Integration Tips

1. Testing

Use Mollie’s test mode (test_ API keys) and test cards (e.g., 4242 4242 4242 4242).

Mock webhooks in tests:

$this->post('/mollie/webhook', $webhookPayload)
     ->assertStatus(200);

2. Logging

Enable debug logging in config/mollie.php:
```
'debug' => env('APP_ENV') === 'local',
```
Log payment events for auditing:
```
event(new PaymentProcessed($payment));
```

3. Localization

Set the locale dynamically based on user preferences:
```
Mollie::setLocale($user->locale); // e.g., 'nl_NL'
```

4. Error Handling

Catch exceptions gracefully:

try {
    $payment = Mollie::payments()->create([...]);
} catch (\Mollie\Api\Exceptions\ApiException $e) {
    Log::error('Mollie API Error: ' . $e->getMessage());
    return back()->with('error', 'Payment failed. Please try again.');
}

Gotchas and Tips

Pitfalls

1. Webhook Verification

Issue: Mollie webhooks must be verified using the id and signature headers. Fix: Use the built-in handle() method, which automatically verifies the webhook:
```
$event = Mollie::webhooks()->handle($request->getContent());
```

Manual Verification (if needed):

$isValid = Mollie::webhooks()->verify($request->getContent(), $request->header('X-Mollie-Signature'));

2. Idempotency Keys

Issue: Missing idempotencyKey can lead to duplicate payments. Fix: Always include a unique key (e.g., order ID or UUID) for critical operations.

3. Currency & Amount Formatting

Issue: Incorrect currency or decimal formatting can cause API failures. Fix: Use PHP’s number_format or bcdiv for amounts:
```
$amount = number_format($order->total, 2, '.', '');
```

4. Timeouts

Issue: Long-running webhook handlers may time out. Fix: Offload processing to a queue (e.g., Laravel Queues):
```
ProcessPayment::dispatch($event->data->id)->onQueue('mollie');
```

5. Mollie Connect Scopes

Issue: Requesting unnecessary scopes can cause permission errors. Fix: Limit scopes to only what you need (e.g., payments.read):
```
$user = Socialite::driver('mollie')->scopes(['payments.read'])->user();
```

Debugging Tips

1. Enable Debug Mode

Set 'debug' => true in config/mollie.php to log API requests/responses.

2. Inspect API Responses

Use dd() to inspect raw responses:

$payment = Mollie::payments()->create([...]);
dd($payment->toArray());

3. Test Webhooks Locally

Use tools like ngrok to expose your local webhook endpoint to Mollie’s test environment.

4. Check Rate Limits

Mollie enforces rate limits

Laravel Mollie Laravel Package