Overview
Mollie is the leading payment service provider for Dutch and Belgian businesses, and one of the most developer-friendly payment APIs in the European market. For web applications, e-commerce platforms, SaaS products, and any digital service that needs to accept payments from Dutch and European customers, Mollie provides the payment method coverage that the European market requires — iDEAL, Bancontact, SEPA Direct Debit, credit cards, PayPal, Klarna, Apple Pay, Google Pay, and the other methods that European customers expect — through a single, well-documented API with competitive rates and no monthly fees for the standard offering.
Mollie's position in the Dutch market is particularly strong. iDEAL — the Dutch online banking payment method — accounts for the majority of Dutch online payments, and Mollie is one of the most widely used iDEAL processors. For any Dutch business with an online payment requirement, Mollie is typically the first integration to consider. The API is clean, the documentation is excellent in both Dutch and English, the test environment accurately mirrors the live environment, and the onboarding process is straightforward compared to some larger payment processors.
The Mollie Payments API follows REST conventions with simple JSON payloads. The core workflow — create a payment, redirect the customer to the payment URL, receive a webhook notification when the payment status changes, verify the payment status, process the result — is consistent across all payment methods. Mollie handles the method-specific complexity (bank redirects for iDEAL, 3DS for card payments, SEPA mandates for direct debit) behind a uniform API surface that the integration interacts with regardless of which payment method the customer chooses.
We build Mollie integrations for Dutch and European businesses across all application types — e-commerce platforms, SaaS subscription systems, marketplace payment flows, B2B invoicing systems, and any application that needs reliable, compliant payment processing for European customers.
What Mollie Payment Integration Covers
Authentication and API access. Mollie's API uses simple API key authentication without OAuth complexity.
API keys: Mollie provides two API keys per organisation — a test API key for development and testing, and a live API key for production. The API key is passed in the Authorization: Bearer {api_key} header of every request. Test API keys (prefixed test_) interact with Mollie's test environment where no real money moves. Live API keys (prefixed live_) process real payments. The environment switch from test to live requires only changing the API key — no other configuration changes.
Organisation versus profile keys: Mollie's API key can be scoped to the organisation level (access to all payment profiles) or to a specific payment profile. The profile-scoped key for integrations that should only access a specific website's payments. The organisation key for management integrations that need to access all profiles.
Mollie Connect OAuth: for platforms that process payments on behalf of other Mollie merchants — the marketplace or SaaS platform that integrates payment processing for its customers. The OAuth flow that authorises the platform to create payments on behalf of a connected merchant account. The access token and refresh token management for OAuth-based Mollie Connect integrations.
Creating payments. The core Mollie API operation — creating a payment that the customer completes through Mollie's hosted payment page.
Payment creation: the POST https://api.mollie.com/v2/payments endpoint for creating a payment. The payment object with amount (the currency and value — the value as a string with exactly two decimal places, e.g., "10.00"), description (the payment description shown to the customer), redirectUrl (the URL to redirect the customer to after payment completion), webhookUrl (the URL Mollie calls when the payment status changes), and method (the payment method, optional — omitting it allows the customer to choose from the available methods on Mollie's hosted checkout page).
Payment methods: the method parameter values for specific payment methods — ideal for iDEAL, creditcard for credit card, bancontact for Bancontact, sofort for SOFORT, eps for EPS, giropay for Giropay, paypal for PayPal, applepay for Apple Pay, klarnapaylater for Klarna Pay Later, klarnapaynow for Klarna Pay Now, klarnasliceit for Klarna Slice It, directdebit for SEPA Direct Debit, belfius for Belfius, kbc for KBC/CBC, przelewy24 for Przelewy24, twint for TWINT.
iDEAL issuer selection: for iDEAL payments, the optional issuer parameter that pre-selects the customer's bank — when provided, the customer is redirected directly to their bank's payment page rather than seeing the bank selection screen on Mollie's page. The GET https://api.mollie.com/v2/methods/ideal endpoint for retrieving the list of available iDEAL issuers with their names and logos for rendering a custom bank selection UI.
Payment redirect: the _links.checkout.href URL in the payment creation response — the Mollie-hosted checkout URL that the application redirects the customer to for payment completion. The redirect that hands control to Mollie's payment pages where the customer completes the payment through their chosen payment method.
Payment metadata: the metadata object in the payment creation request for storing arbitrary application data with the payment — the internal order ID, the customer ID, or any other data the application needs to associate with the payment. The metadata is returned in payment queries and webhook notifications, allowing the application to identify which order or transaction the payment relates to.
Payment status and verification. Retrieving payment status and verifying payment completion.
Payment retrieval: the GET https://api.mollie.com/v2/payments/{paymentId} endpoint for retrieving the current status of a payment. The payment object with the status field — open (created, awaiting customer action), pending (the payment process has started but is not complete), authorized (authorised but not yet captured, for card payments with separate capture), paid (successfully paid), failed (payment failed), canceled (canceled by the customer), expired (expired without payment).
Always verify server-side: the redirect back to the redirectUrl after payment does not confirm payment success — customers can be redirected to any URL by modifying the redirect parameter. Payment status must always be verified by querying the Mollie API using the paymentId rather than relying on URL parameters. The server-side verification that retrieves the payment object and checks its status before fulfilling an order.
Webhooks — real-time status notifications. Mollie's webhook mechanism for receiving payment status changes without polling.
Webhook configuration: the webhookUrl specified in the payment creation request — the URL that Mollie POSTs to when the payment status changes. Mollie sends a POST request with the id parameter containing the payment ID. The webhook handler that receives this notification, queries the Mollie API for the current payment status using the payment ID, and processes the result.
Webhook payload: the Mollie webhook POST contains only the payment ID — not the full payment status. The webhook handler must make a separate API call to retrieve the current payment status. This design prevents webhook forgery — only the payment ID is in the webhook, and the actual status comes from the authenticated API query.
Webhook verification: Mollie does not include a cryptographic signature in webhook requests. The verification that the webhook is legitimate comes from querying the Mollie API with the received payment ID — if the payment exists and has the expected status, the webhook is valid. The IP allowlist approach for additional security — Mollie publishes its webhook IP ranges and the application can restrict webhook processing to requests from those IPs.
Webhook retry: Mollie retries failed webhooks (non-2xx response) up to 15 times over approximately 24 hours. The webhook handler that returns a 200 response promptly after queuing the payment status update for asynchronous processing — preventing timeouts that would trigger unnecessary retries.
Idempotent webhook processing: webhooks may be delivered more than once, particularly after Mollie retries. The idempotent webhook handler that checks whether the payment has already been processed before taking action — using the payment ID as the idempotency key to prevent duplicate order fulfilment.
Refunds. Processing refunds for completed payments.
Refund creation: the POST https://api.mollie.com/v2/payments/{paymentId}/refunds endpoint for creating a refund. The refund object with amount (the amount to refund, which may be less than the original payment for partial refunds) and description (the reason for the refund, visible to the customer). Multiple partial refunds are possible for a single payment, up to the total payment amount.
Refund status: the refund status values — queued (the refund is queued), pending (the refund is being processed by the bank), processing (the refund is being processed), refunded (the refund has been transferred), failed (the refund failed). Refund processing time varies by payment method — card refunds typically take 5–7 business days, iDEAL refunds typically take 1–3 business days.
Orders API. Mollie's Orders API for e-commerce integrations that need order management alongside payment processing.
Order creation: the POST https://api.mollie.com/v2/orders endpoint for creating an order with line items — products, their quantities, their prices, and VAT rates. The order-based payment flow that Mollie uses for Klarna payment methods (which require order-level data for buy-now-pay-later functionality) and for the order management features.
Order shipping: the POST https://api.mollie.com/v2/orders/{orderId}/shipments endpoint for creating a shipment that triggers the capture of a Klarna payment — the Klarna payment flow where payment capture is delayed until shipping.
Subscriptions and recurring payments. Mollie's subscription functionality for SaaS and recurring billing.
Mandate creation: the first payment that establishes a SEPA Direct Debit or credit card mandate — the sequenceType: "first" parameter on the initial payment that collects the mandate. The mandate that authorises subsequent automatic payments.
Recurring payments: the POST https://api.mollie.com/v2/payments endpoint with sequenceType: "recurring" and the customerId for the customer with an active mandate — the server-initiated payment that charges the customer without requiring their interaction. The recurring payment that implements SaaS subscription billing, recurring invoices, and instalment plan processing.
Customer management: the POST https://api.mollie.com/v2/customers endpoint for creating Mollie customer records that aggregate mandates and payment history. The customer ID used in recurring payment requests to identify which customer's mandate to charge.
Subscription management: the POST https://api.mollie.com/v2/customers/{customerId}/subscriptions endpoint for Mollie-managed subscriptions — the subscription that Mollie automatically charges at the configured interval without requiring the application to schedule individual payment requests. The subscription webhook that notifies the application of each subscription payment.
Payment links. Shareable payment URLs for invoice payment and ad-hoc payment requests.
Payment link creation: the POST https://api.mollie.com/v2/payment-links endpoint for creating reusable payment links — the payment link with the amount, description, and expiry that generates a URL the customer visits to complete payment. The payment link for e-mail invoicing and WhatsApp payment requests that do not require the customer to be redirected from a website.
Mollie Dashboard and reporting. Programmatic access to payment data for reconciliation and reporting.
Payment listing: the GET https://api.mollie.com/v2/payments endpoint for listing payments with filtering by status and date range. The cursor-based pagination (from parameter with a payment ID) for retrieving large datasets without missing records. The payment history for financial reconciliation that matches Mollie settlements to internal order records.
Settlement data: the GET https://api.mollie.com/v2/settlements endpoint for retrieving Mollie settlement data — the periodic transfers from Mollie to the merchant's bank account. The settlement breakdown by payment for the financial reconciliation that accounting systems require.
Multi-currency and international payments. Mollie's currency support for international payment processing.
Currency configuration: Mollie supports payments in EUR, GBP, USD, and other currencies depending on the payment method. The currency field in the payment amount that specifies the payment currency. iDEAL and Bancontact are EUR-only; credit card and PayPal support multiple currencies.
Testing. Mollie's comprehensive test environment for integration development and validation.
Test environment: the test API key that accesses Mollie's test environment — a complete mirror of the live API with simulated payment flows for each payment method. The test iDEAL flow that presents a bank selection UI with a simulated bank that completes the payment without real banking interaction.
Test payment outcomes: the testmode Mollie Dashboard for viewing test payments. The test flow that simulates successful payments, failed payments, and cancellations for each payment method — enabling complete end-to-end testing of the webhook handler and the payment verification logic without real money.
Integration Patterns
E-commerce checkout. The standard e-commerce payment flow — customer adds items to cart, proceeds to checkout, the application creates a Mollie payment, the customer is redirected to Mollie's checkout page, the customer completes payment, Mollie redirects back to the application, the application verifies payment via the Mollie API, the application fulfils the order. The webhook provides the payment confirmation that the redirect cannot reliably provide.
Invoice payment. The B2B invoice payment flow — the application generates an invoice, creates a Mollie payment link or payment, emails the payment URL to the customer, the customer clicks the link and completes payment, the webhook notifies the application of payment, the application marks the invoice as paid.
SaaS subscription billing. The recurring billing flow — customer subscribes and completes the first payment with sequenceType: "first", the mandate is established, subsequent billing cycles trigger automatic payments with sequenceType: "recurring", the webhook confirms each successful recurring payment, the application updates the subscription status.
Marketplace split payments. Mollie Connect for marketplaces — the platform that creates payments on behalf of seller accounts, with automatic fee splitting between the platform and the seller.
Technologies Used
- C# / ASP.NET Core — primary Mollie integration implementation using the
Mollie.Api.NET client library - PHP / Laravel — Mollie integration for PHP-based e-commerce and web applications using the
mollie/mollie-api-phplibrary - TypeScript / Node.js — Mollie integration for Node.js applications using the
@mollie/api-clientnpm package - Python — Mollie integration for Python-based applications using the
mollie-api-pythonlibrary - Rust / Axum — high-performance Mollie webhook processing and payment status management
- REST / HTTP — Mollie API communication
- Webhooks — real-time payment status delivery
- SQL (PostgreSQL / MySQL) — payment records, order status, mandate storage, reconciliation data
- Redis — idempotency key storage, webhook deduplication, payment state caching
- Hangfire / scheduled jobs — subscription payment scheduling, settlement reconciliation
- Docker — containerised application deployment
- GitHub Actions — CI/CD pipeline for application deployment
Mollie in the Dutch E-commerce Context
For Dutch businesses, Mollie's combination of iDEAL support, SEPA Direct Debit for subscriptions, and the full range of international payment methods makes it the most practical single payment provider for the Dutch market. The Dutch consumer's strong preference for iDEAL — and the expectation that any Dutch online store will support it — makes Mollie integration a near-requirement for any Dutch consumer-facing e-commerce or digital service.
The Mollie API's simplicity relative to Stripe and the native Dutch-market orientation (Dutch-language support, Dutch banking integration, Dutch business onboarding) makes it the natural first choice for Dutch businesses rather than international alternatives that are technically capable but not optimised for the Dutch market.
Reliable Payment Processing for Dutch and European Businesses
Mollie integrations built to production standards — correct server-side payment verification that does not rely on redirect parameters, idempotent webhook handling that prevents duplicate order processing, comprehensive test coverage using Mollie's test environment, and the monitoring that surfaces payment failures and webhook delivery issues before they cause revenue impact.