Mollie API Integration | iDEAL, Direct Debit & Beyond

Mollie is a Dutch payment service provider known for a developer-friendly REST API and transparent pricing. The platform supports the payment methods most popular in the Netherlands and across Europe: iDEAL, credit card, Bancontact, SEPA Direct Debit, Klarna, PayPal and more. Thanks to a clean API structure and thorough documentation, Mollie has become a go-to choice for startups, scale-ups and established businesses in the Benelux region.

The Mollie API follows a webhook-first principle. After a payment is created, your application receives status updates via webhooks instead of polling for changes. This keeps the integration efficient and reliable, provided the webhook handling is implemented correctly.

Mollie offers two API variants: the Payments API for standalone payments and the Orders API that links payments to order lines with support for partial shipments and line-level refunds. The choice between them depends on your business logic. E-commerce platforms typically benefit from the Orders API, while a SaaS product is often better served by the Payments API.

At MG Software we build Mollie integrations that fit seamlessly into your domain model. Payment statuses, refunds and mandates become part of your own application logic so your team does not depend on the Mollie Dashboard for daily operations.

Mollie offers ready-made plugins for popular platforms, but once you run custom software or need to connect multiple systems, a plugin falls short. A direct API integration gives you full control over the checkout experience, webhook processing and reconciliation with your accounting system.

Without integration a familiar pattern emerges: staff check the Mollie Dashboard, copy payment statuses into internal systems and process refunds by hand. At ten transactions per day that is manageable. At a hundred it becomes a source of errors and delays. Automation removes this burden and makes your payment flow scalable.

For businesses with recurring payments, Mollie provides mandates for SEPA Direct Debit and credit card. An integration that manages these mandates enables automatic subscription renewals without requiring customers to pay manually each time. The mandate status flow (pending, valid, revoked) is handled inside your application so your team always knows which customers are active.

Reconciliation plays an equally important role. When Mollie payments are automatically matched to open invoices in your administration, your finance team saves hours of manual detective work. We build this connection so discrepancies surface immediately rather than at month-end close.

When setting up a Mollie integration we start by choosing the right API variant. The Payments API suits scenarios where a payment stands alone, such as donations, one-off invoices or SaaS subscriptions. The Orders API is designed for e-commerce and ties payment status to individual order lines, enabling partial shipments and line-level refunds. We choose based on your business logic, not on implementation speed.

Webhooks sit at the heart of every Mollie integration. When a payment status changes (from open to paid, expired or failed), Mollie sends a POST request to your webhook URL. Our implementation then fetches the current status via the API to prevent a forged or delayed webhook from triggering incorrect actions. This fetch-after-notify pattern is a best practice recommended by Mollie itself.

For recurring payments we work with Mollie Mandates. A customer authorises the first payment through iDEAL or credit card, after which Mollie creates a mandate for future debits. We manage the mandate status inside your application and build retry logic for failed debits including customer notifications.

Idempotency and error handling are central to our architecture. We store the Mollie payment ID in your domain model and use unique references to prevent duplicate charges. Failed webhooks enter a retry queue with exponentially increasing intervals.

To make the transition to production smooth, we always develop against the Mollie test environment first. Test payments are simulated for every payment method so edge cases such as expired payments and declined debits are tested under controlled conditions.

Mollie holds PCI DSS Level 1 certification. Because payments flow through Mollie-hosted payment pages or redirects, your servers never handle raw card data. This keeps your PCI scope minimal and reduces the compliance burden on your organisation.

Webhook security at Mollie works differently from some other providers. Mollie sends only a payment ID via the webhook, not the full payment data. Your application then fetches the current status via the API using your secret key. This prevents an attacker from misleading your system with a forged webhook payload.

We also recommend securing webhook endpoints with IP whitelisting where your infrastructure supports it. Mollie publishes the IP ranges used for webhook delivery. Combined with HTTPS-only endpoints and structured logging, this provides a strong security layer without complex cryptographic verification on your side.

Webhook delivery order is a common point of attention. Mollie does not guarantee that webhooks arrive in chronological sequence. A webhook for a payment that has expired can arrive after the webhook for the same payment that was completed. Our implementation therefore always bases decisions on the fetched API status, never on webhook arrival order.

Recurring payments bring their own challenges. SEPA Direct Debit mandates can be revoked by the customer or their bank, and the timeline for SEPA payments differs from instant methods. A debit is only final after several business days, which affects when you grant access or ship products.

The gap between test and production environments is a third point that deserves attention. Test API keys simulate payment flows but not all edge cases produced by real banks. We document which scenarios can only be validated in production and plan a controlled initial live run.

Mollie regularly updates its API and adds new payment methods. We track the changelog and plan adjustments when relevant changes affect your integration. API version pinning prevents unexpected breaking changes.

For daily operations we monitor webhook failure rates and processing times. When Mollie announces planned maintenance windows, we prepare fallback procedures so your customers are never left without a payment option. Periodic reconciliation checks confirm that your administration and Mollie settlements remain in sync.

A Mollie integration with a single payment flow and webhooks typically takes a few weeks. The project grows when the Orders API, recurring payments or reconciliation with your accounting system enter the scope.

At MG Software we work with transparent sprint budgets. A scoping workshop upfront determines which payment flows take priority and which can follow later. This keeps you in control of costs without compromising on quality.

Mollie itself charges transaction fees per payment method, separate from our development costs. We can advise on which payment methods yield the best return for your customer segment and how to avoid unnecessary costs on methods that see little use.