mollie-api-php: the PHP client for Mollie payments

The method list tells you what Mollie covers

The opening paragraph of the README is a catalogue of payment methods, and it is worth reading for two reasons. The first is coverage: iDEAL, Apple Pay, Google Pay, credit card, Bancontact, SOFORT banking, SEPA bank transfer, SEPA direct debit, PayPal, Belfius Direct Net, KBC/CBC, paysafecard, ING Home'Pay, Giropay, EPS, Przelewy24, Postepay, In3, Klarna in its pay now, pay later, slice it and pay in three variants, gift cards and meal vouchers. The second is the commercial model, described as online payments without fixed monthly costs or punishing registration procedures, with the client used to receive payments directly on a website or to refund transactions. The library is the PHP half of that service, so understanding which methods your customers can use is largely a question of the Mollie account rather than of the SDK, and the README says as much, pointing to a few onboarding steps to enable payment methods in live mode.

Requirements are PHP 8.2, cURL, TLS and an account

The requirements section is short and concrete. You need a free Mollie account, and with no sign up costs, and then you are ready to use the client in test mode. The technical requirements are PHP 8.2 or newer, cURL 7.19.4 or newer, and an up-to-date OpenSSL or other SSL/TLS toolkit. There is a separate note for advanced cases, where leveraging Mollie Connect is recommended only for advanced use cases, and the OAuth2 client from the same organisation is the companion to install. That is a sensible split. The common path needs nothing but an API key, and the OAuth flow is an extra dependency you should only pull in when you are building an app that acts on behalf of other merchants. The repository also ships a UPGRADING.md at the root, which is the file to read before you move a major version forward.

Installing and setting the token

Installation is one Composer command:

composer require mollie/mollie-api-php

The client is then initialised and given a token. The setToken method is the one the README leads with, and it automatically detects whether the value is an API key, starting with test_ or live_, or an OAuth access token, starting with access_. If you would rather be explicit, setApiKey and setAccessToken are both available:

$mollie = new \Mollie\Api\MollieApiClient();
$mollie->setToken("test_dHar4XY7LxsDOtmnkVtjNVWXLSlXsM");

The convenience is real but so is the risk in it, since a token of the wrong kind fails at request time rather than at configuration time, and the auto-detection exists to support both flows in one client. The full documentation lives at docs.mollie.com, and the developer portal carries the API documentation in English.

Request objects and typed responses instead of arrays

The example shows the modern shape of the client, and the difference from an older array based SDK is visible in one line. A payment is created by sending a request object with named arguments, a description, an amount, a redirect URL and a webhook URL:

$payment = $mollie->send(new CreatePaymentRequest(
    description: 'My first API payment',
    amount: new Money(currency: 'EUR', value: '10.00'),
    redirectUrl: 'https://webshop.example.org/order/12345/',
    webhookUrl: 'https://webshop.example.org/mollie-webhook/'
));

The amount is a Money value object rather than a string with a currency field, and the response is a typed object whose status is compared against the PaymentStatus constant, in the example with PaymentStatus::Paid. The documentation set spells out the rest of the design, with guides for endpoint collections, HTTP adapters for customising communication, idempotency, requests, responses, testing, debugging and webhooks. The idempotency and HTTP adapter pages are the two that matter most in production, since the first prevents duplicate charges on retry and the second is where you plug in timeouts, logging or a custom client.

Recipes cover the flows you actually have to build

Beyond the reference guides there is a recipes directory, and the README frames it as a way to understand how to implement API features rather than as a copy of the reference. The payment recipes cover creating a payment, creating a capturable payment, handling webhooks and refunding payments. The customer recipes cover managing customers and their payments, and there are recipes for mandates and for subscriptions in the recurring payments area. The list is chosen to match the sequence of an integration rather than the shape of the API, so the order of the recipes is roughly the order you will implement things. One instruction is repeated in the README and is worth repeating here, which is to use your test API keys when testing the integration, since the recipes are written against the test environment and a live key would create real transactions.

Three version lines, one repository

The release history in the repository shows three recent tags, and their dates are the interesting part. v2.80.0 was released on 2026-10-05, while v4.0.0 and v3.15.0 were both released on 2026-09-23. That pattern says the project is maintaining several major versions at once, which is what you would expect from a library embedded in production applications that cannot all upgrade in the same sprint, and it means the version you pick is a decision rather than a formality. The tooling in the repository reflects a mature PHP project, with PHPUnit configuration for the test suite, Pint for code style, and PHPStan with a baseline file, and there is a workflow dedicated to fixing code style issues. The licence is BSD 2-Clause, the last push was on 2026-10-05, and the whole client lives under src/ with the documentation under docs/ and the recipes under docs/recipes.

Editorial conclusion

Adopt mollie-api-php if you take payments through Mollie in a PHP application, you want typed request objects and a documented webhook and idempotency story, and you are on PHP 8.2 or later. Do not adopt it as a vendor-neutral abstraction, because every call is shaped around Mollie's own API, and do not upgrade a major version without reading UPGRADING.md, since the project shipped v4.0.0 and v3.15.0 on the same day in September 2026 while v2.80.0 followed in October, so several major lines are still being maintained. Verify first that your account has the payment methods you need enabled, that you are working from test keys rather than live ones during development, and that your webhook endpoint is reachable, because a client library cannot fix a missing callback.

Frequently asked questions

Official sources

1. License: BSD-2-Clause
2. mollie/mollie-api-php on GitHub
3. Project website
4. README
5. Releases