API integration for Mollie
We build your Mollie connector
We wire the Mollie API into your checkout to the Mollie API to take Cartes Bancaires payments, manage mandates and subscriptions, and reconcile payouts.
- Senior product team
- payment integrations in production
- from scoping to monitoring
What does the Mollie API do and why integrate it as a payment solution?
Mollie is a European PSP that bundles the main payment methods into a single integration: bank card, instant transfer, SEPA direct debit, PayPal, and local methods like Bancontact or iDEAL. Its API lets your application create a payment link, manage subscriptions and mandates, and track settlements and refunds. You integrate it to offer each client their preferred payment method without multiple contracts, and to have payment events automatically trigger actions in your software.
What our clients build on the Mollie API
French checkout with Cartes Bancaires
The Methods API picks Cartes Bancaires (CB), Visa, Mastercard, PayPal by country. Missing the CB logo shows up directly in conversion.
Subscription with a mandate on first payment
sequenceType first, then recurring with no browser session. Chasing starts before Mollie's 5th attempt, not after cancellation.
Payment link for a deposit
A Payment Link sent by email, file closed on payment-link.paid. No checkout to build for a one-off invoice.
Reconciliation by bank payout
Settlements explains the gap between collections and the transfer received. Balances gives the running view. Two questions, two APIs.
What it changes in your checkout
Engineering in service of a measurable outcome: card payment at the right moment, living mandates, readable reconciliation.
The right logo at the right time
Cartes Bancaires is a first-class method at Mollie. The French checkout no longer shows only Visa and Mastercard.
You know if the customer can be charged
A mandate has a status. We check it before billing, instead of discovering a missing mandate through a failure.
Failed payment has a sequence
Mollie retries up to 5 times, then cancels. We warn before the 5th, and we handle mandate revocation if the subscription pins mandateId.
The transfer received is explained
Settlements breaks down fees and collections in the payout. Your accountant stops rebuilding the gap from an export.
How we ship your Mollie connector
Scoping
Methods, recurring, classic and next-gen, Connect or not. We settle the two webhook systems before writing a line.
Development
Typed connector, amounts as strings, handler under 15 seconds, a single webhook URL (cap of 3 subscriptions).
Acceptance testing
Payment, 3DS, failed subscription, 301 redirect on the webhook URL, secret rotation with two headers.
Monitoring
Alert on blocked, a payment log, a health dashboard. A blocked webhook cuts everything until manual reactivation.
What the Mollie API allows
- Payments and methods
- Payments API plus Methods API. Cartes Bancaires, international cards, PayPal, iDEAL, Bancontact, Direct Debit, depending on profile and country.
- Customers, mandates, recurring
- First payment sequenceType first, later recurring with mandateId. iDEAL and Bancontact create a directdebit mandate, to be enabled on the profile.
- Subscriptions
- Amount, interval, occurrences. If the day does not exist in the month, Mollie collects on the last day. No subscription-state webhook: we match on subscriptionId.
- Balances and settlements
- Balances for the running view, Settlements for the transfer received. Two books, named explicitly by Mollie.
The vocabulary of the Mollie API
- sequenceType
- first creates the mandate, recurring collects with no browser. iDEAL, Bancontact, eps, kbc, belfius and paybybank yield a directdebit mandate.
- X-Mollie-Signature
- HMAC-SHA256 of the unaltered POST body, prefixed sha256=, on the next generation. For 24 hours after rotation, two headers coexist.
- Amount as string
- {"currency": "EUR", "value": "24.95"}. A TypeScript client typed as number produces validation errors or silent rounding.
- blocked
- After repeated failures over 24 hours, the next-gen webhook stops. Manual reactivation. Without an alert, you discover it through an unhappy customer.
- Pinned mandateId
- If the subscription carries a mandateId, cancelling it also revokes the mandate. That is a major business event, not an API detail.
- RateLimit-Policy
- Present on every response. Reads and writes in separate buckets. All keys for a merchant share the same bucket: an export can starve checkout.
The real constraints of the Mollie API
Two webhook systems to run
Mollie recommends classic webhooks for payments (next-gen payment.* is beta on request) and the next generation for the rest. An integration that only wires next-gen will miss payments.
Fifteen seconds, not sixteen
A 200 returned after 16 seconds is counted as failure, and the work already ran. 10 attempts over 26 hours, no manual retrigger: you go through support.
3 subscriptions, then blocked
Up to 3 active subscriptions per organisation in live mode. One URL, internal dispatch. After 24 hours of failures, blocked cuts everything until manual reactivation.
Subscription failure cancels
Up to 5 attempts, one per day, then cancellation. AC01, AC04, AC06, MD07 cancel immediately. A pinned mandateId also revokes the mandate. We warn before the 5th.
Classic webhooks or next generation?
Two systems coexist. Mollie recommends running both, for precise reasons.
| Criterion | ClassicPayments | Next generationNon-payment |
|---|---|---|
| Payload | id=tr_... as form body | JSON, simple or embedded |
| Signature | None: API re-read | X-Mollie-Signature HMAC |
| Payment events | The recommended path today | payment.* in beta on request |
| Invoices, payouts, balances | Out of scope | The recommended path |
| Subscription cap | One webhook per payment (single use) | 3 active subscriptions per organisation |
| Long outage | 10 attempts over 26 hours | blocked after 24 hours, manual reactivation |
| The right case | Payment status updates | Event-driven accounting, non-payment |
We wire both. An architecture that picks only one misses either payments or the durable accounting events.
What we measure on a Mollie integration
The other payment APIs
If Mollie is not the right fit for your model, these options are worth discussing during scoping.
MollieWe build your Mollie connectorThis page
StripeThe most complete Connect and Billing, when the platform and proration are the core of the product.
PayPalAn account the buyer already has, often alongside card payments.
SumUpIn-person collection, when the sale closes on a terminal.
GoCardlessWe build your GoCardless connectorWe combine Mollie with
The stack that surrounds Mollie on our projects.
Mollie integration: your questions
Three steps. First an API key (test and live pair) and the Methods API to show Cartes Bancaires at the right moment. Then POST /v2/payments with amounts as strings, and for recurring a customer plus a first payment with sequenceType first. Finally the classic webhook: read the id, enqueue, return 200 in under 15 seconds, re-read GET /v2/payments/{id}. The next generation is wired as well for non-payment events. The sensitive part is not the call, it is the cap of 3 subscriptions, the blocked state, and the fact that a 200 that is too slow counts as failure even though the work already ran.
It depends on the methods and on recurring. A card-only checkout is shorter than a subscription with mandates, chasing before 5 attempts, Settlements and Mollie Connect. A first useful flow ships in two to three weeks. A full chain is closer to six to eight weeks. We do not quote vendor pricing: the public grids we checked target other countries. We scope the perimeter and give a firm estimate before we start.
Classic sends id=tr_... as form body, with no signature: protection is an authenticated API re-read. Mollie still recommends it for payment updates. Next generation subscribes to durable types, signs with X-Mollie-Signature, and covers invoices, payouts, transfers. payment.* events there are beta on request. You need both. A single URL on the next-gen side, because of the cap of 3 subscriptions. A 301 or 302 on the URL turns the POST into a GET and drops the body: use 307 or 308, or better no redirect at all.
Mollie retries up to 5 times, once a day, then cancels the subscription. Some SEPA codes cancel immediately (AC01 invalid IBAN, AC04 closed account, AC06 blocked, MD07 deceased). Others after 3 occurrences (MD01, MD06, MS02, MS03, SL01). If the subscription pins a mandateId, cancellation also revokes the mandate. There is no subscription-state webhook: payments arrive with an unknown id, matched on subscriptionId. We warn the user before the 5th attempt, and we treat mandate revocation as a business event, not a detail.
Yes. We push collections with the order reference, and we hang reconciliation on the two APIs meant for it: Balances for the running view, Settlements for the bank transfer. A periodic check flags the gap, with no silent fix. payout.completed on the next-gen side can close the batch. Fees, refunds and chargebacks have to land on the right lines, or the accountant spends the close rebuilding an export. An entry is not repaired behind the accountant's back.
A Mollie integration project?
Let's talk. 30 minutes to scope card payments, mandates and webhooks, check what the API actually allows and tell you honestly what is feasible.
Discuss my Mollie project