README

Mollie payment gateway integration for Maho Commerce.

Accept payments through Mollie, one of Europe's leading payment service providers — offering 40+ payment methods across the Payments API and the Orders API (for Klarna and other Buy Now Pay Later methods).

Status: Beta — unverified against a live Mollie sandbox. Core payment flow (create → redirect → webhook → return → cron) is implemented against the Mollie Payments API, plus online refunds, admin-configurable order statuses, and a payment-fee surcharge that shows in checkout. 16 method blocks are configurable in admin — of those, 10 should work end-to-end via redirect (the generic Mollie selector plus iDEAL, Bancontact, Credit Card, PayPal, Apple Pay, Bank Transfer, SEPA Direct Debit, Gift Card, Google Pay, Trustly). The remaining 6 are flagged "(not implemented yet)" in their admin labels: Klarna Pay later / Pay now / Slice it, iDEAL in3, and Riverty all require the Orders API (not yet wired) to send orderLines; Apple Pay's express-checkout button (cart/PDP) is also not implemented, though Apple Pay via redirect works. Translations ship for Dutch, German, French, Italian, and Spanish.

Known gaps you'll hit in real testing:

• The payment fee is added to the cart grand total but not propagated to the invoice or credit memo (DB columns exist; nothing populates them). The fee is also not rendered on order/invoice/creditmemo views — the module ships zero layout XML or phtml templates.
• Refund amounts passed by Maho's creditmemo flow are forwarded to Mollie verbatim — there is no special handling to exclude the payment fee from a partial refund.
• The webhook re-fetches the payment from Mollie's API for verification, but there is no DB-level lock around the capture path; concurrent webhook redeliveries could race.

Requirements

• PHP >= 8.3
• Maho Commerce
• A Mollie merchant account

Installation

composer require mahocommerce/module-mollie

Clear the cache after installation:

./maho cache:flush

Configuration

Navigate to System > Configuration > Payment Methods in the Maho admin panel.

General Settings (Mollie - General Settings)

Find your API keys in the Mollie dashboard under Developers.

Order statuses (Mollie - Order Statuses)

Configurable codes applied when Mollie reports pending / paid, with optional per-method overrides on each method group.

Payment fee (Mollie - Payment Fee)

Optional surcharge added to the order grand total when the customer picks a fee-enabled Mollie method. Supports fixed, percent, or combined fees, with per-method opt-in.

Method-specific groups

Each of the 16 bundled methods has its own admin group with the usual active / title / country / sort-order controls plus optional status and fee overrides. Method blocks whose label ends with "(not implemented yet)" can be saved/configured but will not produce a working checkout — the module either lacks the Orders API plumbing they need (Klarna ×3, iDEAL in3, Riverty) or is missing a non-redirect flow (Apple Pay express button — note that Apple Pay via redirect does work).

Roadmap

API layer

• Payments API integration (create, webhook, return, cron reconciliation, refunds)
• Orders API integration (Klarna line items, in3, Billie, Alma, Riverty, Voucher categorisation)
• Apple Pay express checkout (domain association + JS button)

Payment methods

Working end-to-end via redirect (Mollie hosts the actual UI):

• Generic Mollie gateway (Mollie's full method picker)
• iDEAL
• Bancontact
• Credit card (redirect; Mollie Components / hosted fields not yet)
• PayPal
• Apple Pay (redirect only — express button on cart/PDP not yet)
• Bank Transfer
• SEPA Direct Debit
• Gift Card
• Google Pay
• Trustly

Configurable in admin but not functional without further work (labels end with "(not implemented yet)"):

• Klarna Pay Later — needs Orders API (orderLines)
• Klarna Pay Now — needs Orders API
• Klarna Slice It — needs Orders API
• iDEAL in3 — needs Orders API
• Riverty — needs Orders API

Not bundled at all (Mollie supports them; this module has no method block, model, or config):

• TWINT (Switzerland)
• BLIK (Poland)
• Przelewy24 (Poland)
• EPS (Austria)
• KBC / CBC (Belgium)
• Belfius (Belgium)
• Bizum (Spain)
• MyBank (Italy)
• Satispay (Italy)
• Multibanco (Portugal)
• Voucher (meal-voucher schemes — Edenred, Sodexo, etc.)
• Alma, Billie, Pay by Bank, POS, and other long-tail methods
• SOFORT Banking (deprecated by Mollie — listed for completeness)

Features

• Online refunds from admin via Mollie API (full + partial — but partial refunds forward Maho's amount verbatim, no fee-aware logic)
• Webhook-driven payment status reconciliation (all mollie_* method codes, not just the generic gateway)
• Cron-based safety net for missed webhooks (5-minute interval, 24-hour lookback)
• Admin-configurable pending / processing order statuses (global + per-method override)
• Payment-fee surcharge in checkout (fixed / percent / combined, per-method opt-in)
• External-refund and chargeback reconciliation (creditmemo from Mollie dashboard refunds; chargeback order comments only)
• Multi-store API key scoping
• Admin "Test API Key" button (one-click connectivity check)
• Debug logging toggle (gates info-level entries in var/log/mollie.log)
• Translations for Dutch, German, French, Italian, and Spanish
• Payment fee carried into invoice and credit memo records (DB columns exist, no code populates them)
• Payment fee rendered on order / invoice / credit memo / "My Orders" / order email / PDF (no layout XML or templates ship)
• Tax on the payment fee (fee_tax_class is stored but no tax collector applies it)
• DB-level idempotency lock on the capture path (today only an in-memory hasInvoices() check)
• Multi-currency support (code paths present but not verified end-to-end)
• Second-chance payment email
• Vault / stored cards
• Mollie Components (hosted card fields)
• Payment-link generation from admin
• Shipment push to Mollie (Orders API)

Acknowledgements

Architecture and feature set informed by the official mollie/magento2 module by Magmodules (OSL-3.0). This module is an independent Maho implementation; no code is copied, but the integration shape and feature surface follow the upstream as a reference.

License

This module is licensed under the Open Software License v3.0.

Links

• Maho Commerce
• Mollie
• Mollie API documentation
• Mollie Magento 2 module (reference for business logic)