Mollie Laravel Package

Getting Started

Install the package via Composer:

composer require vanilo/mollie

The service provider is auto-discovered. Publish the config (tag is usually vanilo-mollie or falls under vanilo-config; check php artisan vendor:publish --list) and set your Mollie key:

MOLLIE_API_KEY=test_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxx

Register the gateway with Vanilo Payments — typically in config/vanilo.php:

'payment' => [
    'gateways' => [
        'mollie' => [
            'api_key' => env('MOLLIE_API_KEY'),
        ],
    ],
],

First use case: accept iDEAL / Bancontact / SEPA / cards on a European storefront. Once registered, resolve the gateway through Vanilo and create a payment from a PaymentRequest:

use Vanilo\Payment\PaymentGateways;

$gateway  = PaymentGateways::make('mollie');
$response = $gateway->createPayment($paymentRequest);

if ($response->hasRedirect()) {
    return redirect($response->getRedirectUrl());
}

For anything non-trivial, read the gateway class in src/ first — it's small, and its createPayment() / status-mapping code is the source of truth for which Vanilo contracts and config keys it actually honors.

Implementation Patterns

Checkout redirect flow. Build a PaymentRequest from your Order/Payment model (amount, currency, method, redirectUrl, webhookUrl, metadata), call createPayment(), then redirect. The Mollie payment ID (tr_...) comes back as the transaction ID — persist it via Vanilo's Payment model so webhooks can later find the row.

Webhook → status sync. Mollie's webhook posts only id=tr_.... Your controller must fetch the payment from Mollie and map its status to Vanilo's:

public function webhook(Request $request)
{
    $payment = $request->input('id');
    $gateway = PaymentGateways::make('mollie');
    $gateway->getPaymentStatus($payment); // or retrievePayment + sync
    return response('OK', 200);
}

Vanilo's payment-status machinery then fires its own events (PaymentPaid, etc.) — hook order fulfillment there, not in the controller.

Choose methods explicitly. For iDEAL/Bancontact, pass the method on the PaymentRequest (ideal, bancontact, creditcard, paypal, klarna). For a "let Mollie decide" host, omit it and Mollie's hosted checkout picks.

Refunds. Use Vanilo's refund abstraction and let the gateway call Mollie's refunds API; partial refunds are supported by Mollie but verify the package forwards the amount — older wrappers sometimes refund in full only.

Testing. Keep MOLLIE_API_KEY=test_... in local/staging. Mollie's test checkout lets you force statuses, so you can drive the webhook → PaymentPaid → fulfillment path without real money.

Gotchas and Tips

• Test vs live keys. test_... and live_... are fully separate environments; a test payment is invisible in live and vice versa. Never let MOLLIE_API_KEY fall back to a stale value in production.
• Webhooks need a public URL. localhost will silently fail. Use a tunnel (ngrok/expose) during development and confirm the URL is reachable without auth.
• No webhook signature. Mollie does not sign payloads. Never trust the posted id alone — always fetch the payment from the API and re-check amount/currency/status before marking paid. This is the single most common integration bug.
• Amounts are in minor units. Vanilo normalizes this, but watch rounding for currencies without 2 decimals.
• Method/currency limits. iDEAL is EUR-only; some methods have min/max amounts. A rejected request usually surfaces as a Mollie API error, not a Vanilo exception — log the raw response.
• Status mapping is opinionated. open/pending/authorized/expired/failed/canceled/paid/refunded/charged_back must all map sensibly; charged_back (disputes) often needs custom handling because the package won't auto-reverse fulfillment.
• Idempotency. Pass an idempotencyKey (e.g. order-{id}) when creating payments to survive double-submits.
• Version pinning. This package is young (2 stars, 0 dependents) and its constraints track specific vanilo/payment releases — pin both and read the changelog before upgrading. Expect to read source over docs.
• Extension points. Subclass the gateway and override createPayment() / status mapping for locale, metadata, or custom method filtering; bind your subclass under the same config alias rather than editing vendor code.