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

> The Mollie PHP client is a vendor SDK with a long list of payment methods, request objects instead of positional arguments, and a documentation set that covers webhooks, idempotency and testing. It is BSD licensed, requires PHP 8.2, and is currently shipping three version lines in parallel.

**mollie/mollie-api-php** — Mollie API client for PHP

- Repository: https://github.com/mollie/mollie-api-php
- Website: http://www.mollie.com
- Stars: 605 · Forks: 199
- Language: PHP
- License: BSD-2-Clause
- Published: 2026-10-22 · Updated: 2026-10-22 · Language: en
- Canonical page: https://hysenlabs.com/projects/mollie-mollie-api-php

## 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:

```bash
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:

```php
$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:

```php
$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.

## 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.

## FAQ

### What are the requirements for the Mollie PHP client?

You need PHP 8.2 or newer, cURL 7.19.4 or newer and an up-to-date OpenSSL or other SSL/TLS toolkit, plus a free Mollie account. Using Mollie Connect for advanced cases additionally needs the separate OAuth2 client from Mollie.

### How do I install the Mollie API client for PHP?

Through Composer, with composer require mollie/mollie-api-php. You then create a MollieApiClient and give it a token with setToken, which detects whether the value is an API key starting with test_ or live_ or an OAuth access token starting with access_, or you can call setApiKey or setAccessToken explicitly.

### How do I create a payment with the Mollie PHP client?

You send a CreatePaymentRequest with a description, a Money value object for the amount, a redirectUrl and a webhookUrl, then compare the returned payment status against the PaymentStatus constants such as PaymentStatus::Paid.

### What are the different version lines of mollie-api-php?

Recent releases include v2.80.0 on 2026-10-05, v3.15.0 on 2026-09-23 and v4.0.0 on 2026-09-23, so several major versions are maintained in parallel. The repository includes an UPGRADING.md file to read before moving between them.

### Which payment methods can I use with the Mollie API client?

The README lists iDEAL, Apple Pay, Google Pay, credit card, Bancontact, SOFORT, SEPA bank transfer and direct debit, PayPal, Belfius Direct Net, KBC/CBC, paysafecard, ING Home'Pay, Giropay, EPS, Przelewy24, Postepay, In3, Klarna in several variants, gift cards and vouchers. Payment methods have to be enabled on the account for live mode.

## Sources

- [License: BSD-2-Clause](https://github.com/mollie/mollie-api-php/blob/main/LICENSE)
- [mollie/mollie-api-php on GitHub](https://github.com/mollie/mollie-api-php)
- [Project website](http://www.mollie.com)
- [README](https://github.com/mollie/mollie-api-php/blob/main/README.md)
- [Releases](https://github.com/mollie/mollie-api-php/releases)

---

Hysen Labs editorial analysis, written from the project's own repository and release notes. Cite the canonical page: https://hysenlabs.com/projects/mollie-mollie-api-php