NewYour coding agent can read the release notes before it upgrades.Set up the MCP server →
Packagist · #868 most downloaded on Packagist
Mollie API client library for PHP. Mollie is a European Payment Service provider and offers international payment methods such as Mastercard, VISA, American Express and PayPal, and local payment methods such as iDEAL, Bancontact, SOFORT Banking, SEPA direct debit, Belfius Direct Net, KBC Payment Button and various gift cards such as Podiumcadeaukaart and fashioncheque.
Last release 2 days ago
05 Oct 2026
Ships fairly regularly
a new release about every 3 weeks
Some releases are documented
notes for 27 of the last 60 stable releases
Nothing withdrawn
no release was ever pulled
13 years old
244 releases · first in 2013
The first stable v4 release modernizes Mollie API PHP for PHP 8.2 and newer . It includes the changes from all three v4 betas and the v3 API additions
The first stable v4 release modernizes Mollie API PHP for PHP 8.2 and newer. It includes the changes from all three v4 betas and the v3 API additions through v3.14.0. If you are upgrading an application from v3, read the v3 to v4 upgrade guide before changing the dependency.
Mollie\Api\Types are string-backed enums: for example, PaymentStatus::PAID becomes PaymentStatus::Paid. Resource status and method fields use enum cases while preserving unknown API values as strings. The GetAllConstants trait is gone; use cases() or the retained all() methods on the three enums documented in the upgrade guide.stdClass can now hold typed value objects such as Money. Familiar property reads such as $payment->amount->value still work. Rebuild a readonly value object when you need to change it. Check positional constructor calls after property promotion; named arguments retain their names. A typed property with no default stays uninitialized when a response omits that field; guard reads from partial responses.onResponse() always receives the raw Response; use onResolved() for middleware that needs a hydrated resource or collection. Subclasses that changed the protected static $endpoints map should override the ENDPOINTS constant. Custom retry strategies should follow the updated exception contract. Typed method arguments follow the strict_types setting of the calling file.MollieApiClient::send() infers the concrete resource from its request class in static analysis. ResourceHydratableRequest::hydrateInto() and wrapInto() also preserve inference when retargeting or wrapping a response.Money::of('EUR')->minorUnits(1099) and Money::of('EUR')->fromString('10.99') account for currency exponents. Money supports macros for custom factories.ExponentialRetryStrategy supports jitter and HTTP 429 Retry-After, and Response::rateLimit() reads rate limit headers. ValidationException exposes field errors; TooManyRequestsException exposes the retry delay. Exception messages no longer include API tokens or request bodies.MockResponse has typed factories for payments, customers, subscriptions, mandates, refunds, and other common resources.applicationFee, response origins, and webhook snapshots are present in v4. PaymentMethod::Wero carries the v3.14.0 payment method addition into the enum.->value, or use Utility::equals().PaymentMethodStatus and TerminalPairingCodeStatus are enums. A method that was never requested has Method::$status === null; there is no PaymentMethodStatus::NOT_REQUESTED case.Organization, Capability, Balance, Terminal, SalesInvoice, and other resources. Payment::$statusReason is now a readonly PaymentStatusReason value object.0, "0", and 0.0 values. Idempotency keys are cleared when a request is assembled, including failure paths, and test mode is resolved consistently for each request.The changelog has the detailed beta changes. Compare v3.14.0 with v4.0.0 for the full major upgrade, or beta.3 with v4.0.0 for the final changes. The full test suite passed in CI on PHP 8.2, 8.3, and 8.4; PHPStan also passed.
One column per quarter.
The first stable v4 release requires PHP 8.2 or newer. See UPGRADING.md for the v3 migration guide and the beta entries below for detailed changes.
PaymentMethod::Wero brings the v3.14.0 payment method addition to v4. The enum remains SDK vocabulary, not an allow-list; unknown methods still arrive as strings.MollieApiClient::send() return types.Money::of() builders, exponential retries with Retry-After handling, improved validation errors, and typed fake responses.0, "0", and 0.0; the latest v3 fix is already present in v4. See the beta.2 notes for related request factory behavior.Balance no longer fails on a conformant response: $incomingAmount and $outgoingAmount (both deprecated because they are not part of the Balance respon…
PaymentStatusReason value object (code, message); Payment::$statusReason is now ?PaymentStatusReason instead of an untyped stdClass. ->code/->message reads and json_encode() keep working; update instanceof stdClass checks, any mutation (the object is readonly), and array-only consumers by calling toArray().PaymentMethod cases Billink, Bizum, Mobilepay, Vipps, and Voucher. Existing cases are unchanged; the enum documents known SDK vocabulary, not an allow-list.CapabilityStatus::Unrequested and Capability::isUnrequested().Balance::$pendingAmount (?Money), the amount field the Balance API returns.ResourceHydratableRequest::hydrateInto() and ::wrapInto(). Both carry @phpstan-self-out and @psalm-this-out annotations that PHPStan honors so send() infers the re-targeted class or wrapper. setHydratableResource() is unchanged but cannot narrow the type.PaymentMethodStatus and TerminalPairingCodeStatus are string-backed enums. Their SCREAMING_SNAKE constants are gone, the same migration the other value sets took in beta.1. PaymentMethodStatus::NOT_REQUESTED has no case: Method::$status is null for a method that was never requested. TerminalPairingCode::$status is typed TerminalPairingCodeStatus|string.Method::$status no longer has a null default. The API marks the field required (nullable), so an omitted field now stays uninitialized instead of reading as "not requested"; an explicit null still means the method was never requested.Enum|string|null properties resolved as mixed and kept the raw API string. Affected: Payment::$method, Payment::$sequenceType, Refund::$status, Mandate::$status, Settlement::$status, Profile::$status, CurrentProfile::$status, Invoice::$status, Subscription::$status, and, after its enum migration, Method::$status. Code written against beta.2 that compares these to raw strings must compare with the case or ->value, or use Utility::equals(), which accepts the case or raw value on either side. MandateCollection::whereStatus() accepts a MandateStatus case or raw string. Unknown values still arrive as strings; null is unchanged. Profile::$categoryCode (int|string|null) keeps the delivered scalar type.Organization::$address, $registrationNumber, and $vatNumber are nullable with a null default, matching the API contract. Beta.2 threw TypeError on null and Error on an omitted field. Organization::$locale stays a required, non-null string.Capability::$statusReason accepts null; Capability::$organizationId is nullable with a null default because the field is not part of the Capability response.Balance no longer fails on a conformant response: $incomingAmount and $outgoingAmount (both deprecated because they are not part of the Balance response), $transferFrequency, and $transferThreshold are nullable with a null default.TypeError on null or Error when omitted: Terminal::$brand, $model, $serialNumber (?string); Terminal::$timezone, $locale (?string = null); Capture::$amount (?Money); PaymentLink::$profileId (?string); Webhook::$profileId (?string); Partner::$partnerType (?string); Partner::$partnerContractUpdateAvailable (?bool = null); BalanceTransaction::$deductions (?Money = null); BalanceTransaction::$mode (?string = null); Route::$releaseDate (?string = null); ConnectBalanceTransfer::$category (?string = null); SalesInvoice::$paymentTerm, $currency, $webhookUrl (?string = null); and SalesInvoice::$lines (?array = null). Other SalesInvoice fields are unchanged pending further contract review.strict_types behavior.src/Types/ is a backed enum except the query helpers and Types\Method.tests/ asserts the inferred send() types on every analysis run.RateLimit value object and Response::rateLimit() accessor for RateLimit and RateLimit-Policy response headers.
RateLimit value object and Response::rateLimit() accessor for RateLimit and RateLimit-Policy response headers.middleware()->onResolved(), a post-hydration middleware phase for transforms that need the hydrated resource or collection rather than the raw response.Mollie\Api\Utils\Utility::isTrue(), the shared boolean coercion used for API-facing scalar values such as testmode arriving from a query string or payload.ExponentialRetryStrategy skips 429 retries when Retry-After exceeds maxDelayMs and adds bounded, additive jitter when honoring the header.ExponentialRetryStrategy applies the maxDelayMs cap before exponential full jitter, avoiding a probability spike at the cap.onResponse() callbacks now always receive the raw Response, regardless of priority. Move transforms that expect a hydrated resource or collection to onResolved(). See UPGRADING.md section 3.7.$endpoints property must override the protected ENDPOINTS constant instead. See UPGRADING.md section 3.6.0, "0" and 0.0 are no longer dropped.ResourceRegistry keeps its class and type indexes consistent, and paginated query factories build their query from one authoritative input map.Mollie\Api\Http\Middleware\ResetIdempotencyKey. It cleared the connector key from the response phase, which never runs when a request throws. Clearing now happens during request assembly, so no replacement is needed. setIdempotencyKey() and resetIdempotencyKey() are unchanged.composer format to apply and composer check:format to verify. The rule set is unchanged, so no reformatting is required on in-flight branches.bin/release publishes only from an already-merged remote state and honors the operator's tag signing configuration.published, so pre-releases are no longer skipped.This is a pre-release for early adopters; expect breaking changes until 4.0.0 stable. Full details in the changelog and the upgrade guide .
First beta of v4.0.0 — the PHP 8.2+ modernization (#901).
Highlights:
src/Types/ constants are now string-backed enums (PaymentStatus::Paid)Money, Address, OrderLine, …)MollieApiClient::send() — your IDE infers the resource from the request classMoney::of() fluent builder, typed MockResponse factoriesExponentialRetryStrategy with jitter and HTTP 429 / Retry-After supportThis is a pre-release for early adopters; expect breaking changes until 4.0.0 stable. Full details in the changelog and the upgrade guide.
Install:
composer require mollie/mollie-api-php:^4.0@beta
Feedback welcome on #901.
PHP 8.2+ modernization. See UPGRADING.md for the full guide.
src/Types/ are now enum ... : string with PascalCase cases (PaymentStatus::Paid). PaymentMethodStatus and TerminalPairingCodeStatus followed after v4.0.0-beta.2; query helpers and Types\Method stay classes. Resource $status-style properties are typed EnumName|string. The Mollie\Api\Traits\GetAllConstants trait is removed with this migration — call cases() on the enum instead; BusinessCategory, ConnectBalanceTransferCategory, and SubscriptionStatus keep a static all() returning the raw values.\stdClass are now concrete value objects. Property names are unchanged — $payment->amount->value and ->currency still work.readonly class. Money, Address, OrderLine etc. cannot be subclassed by non-readonly children. Prefer the new Macroable extension point.strict_types in your files, not the SDK's; see UPGRADING.md section 3.3.Macroable on Money — undefined methods now throw BadMethodCallException instead of PHP's default fatal error.require-dev (consumer impact only if running SDK tests).@template return type on MollieApiClient::send() — return type inferred from the request class. Resolves #875.Money::of(string $currency) fluent builder with minorUnits(int $amount) and fromString(string $value). Resolves #876.ExponentialRetryStrategy with optional jitter and HTTP 429 (Retry-After) support.MockResponse factories: payment(...), customer(...), subscription(...), mandate(...), refund(...), chargeback(...), method(...), paymentLink(...), invoice(...), capture(...).Macroable trait for Money (and other value objects) for custom factories without subclassing.ValidationException exposes per-field errors; TooManyRequestsException exposes retryAfterSeconds; Response exposes header access.ProfileCreated, ProfileVerified, ProfileBlocked, ProfileDeleted) for constants-to-class parity.ResourceHydrator rewritten reflection-based so it can populate the new typed resource properties (value objects, enums, nested collections). Origin routing (HTTP vs. webhook snapshot) behaves exactly as in v3.13.--parallel built in).Mollie\Api\Traits\GetAllConstants trait — superseded by the enum migration. Use the enum's native cases(); BusinessCategory, ConnectBalanceTransferCategory, and SubscriptionStatus keep a static all() returning the raw string values.docs/webhooks.md previously stated that $event->entity() returns null for simple payloads. It actually throws. Updated to correctly describe reading the nullable $event->entity property or fetching the resource via $event->entityId.v3.15.0 brings rate-limit visibility and opt-in HTTP 429 retries to the PHP 7.4-compatible v3 line. Existing clients keep their current retry behavior
v3.15.0 brings rate-limit visibility and opt-in HTTP 429 retries to the PHP 7.4-compatible v3 line. Existing clients keep their current retry behavior unless they select the new strategy.
Response::header() and headers() expose response headers. Response::rateLimit() parses Mollie's RateLimit and RateLimit-Policy headers into a RateLimit object with the policy, remaining requests, restore time, burst, quota, and window. Missing or malformed rate-limit headers return null.TooManyRequestsException::getRetryAfterSeconds() exposes Retry-After as a delay in seconds, accepting both integer seconds and HTTP-date values.ExponentialRetryStrategy can retry temporary network failures and HTTP 429 responses. It supports exponential backoff, optional jitter, and a maximum delay budget. A 429 whose Retry-After exceeds that budget is thrown rather than delayed.ConditionalRetryStrategyContract lets custom strategies decide which exceptions to retry and use the triggering exception when calculating a delay.LinearRetryStrategy remains the default and continues to retry temporary network failures as before. The original RetryStrategyContract is unchanged, so existing custom strategies require no migration. The new behavior is opt-in:
use Mollie\Api\Http\ExponentialRetryStrategy;
$client->setRetryStrategy(new ExponentialRetryStrategy());See the retry guide for configuration and custom strategy examples, or compare v3.14.0 with v3.15.0 for all changes.
Add wero as supported payment method by @robindirksen1 in #924
Full Changelog: v3.13.0...v3.14.0
Full Changelog: https://github.com/mollie/mollie-api-php/compare/v3.13.0...v3.14.0
Update signature-verification.md by @fjbender in #902
Full Changelog: v3.13.1...v3.13.2
Full Changelog: https://github.com/mollie/mollie-api-php/compare/v3.13.1...v3.13.2
fix: support applicationFee on payment link creation by @Naoray in #895
Full Changelog: v3.13.0...v3.13.1
feat: add terminal pairing code endpoints by @gabrielciobanu-mollie in #894
Full Changelog: v3.12.0...v3.13.0
fix: add scopes query parameter to list customer mandates by @Naoray in #887
refactor(webhooks): decouple hydrated resources from the HTTP domain by @Naoray in #880
Full Changelog: v3.10.0...v3.11.0
Mollie\Api\Contracts\ResourceOrigin marker interface describing where
a hydrated resource came from. Http\Response now implements it.BaseResource::getOrigin() / setOrigin() accessors on every hydrated
resource and collection. HTTP-hydrated resources set origin to the
Response automatically; no migration needed for existing user code.Mollie\Api\Webhooks\WebhookSnapshotOrigin exposes the event id,
signature, and received-at timestamp of the webhook that produced a
hydrated resource. Accessible via $resource->getOrigin().Mollie\Api\Webhooks\SnapshotHydrator feeds a webhook snapshot through
the main ResourceHydrator after a one-line json_decode(json_encode())
normalization so nested values arrive as stdClass (matching the HTTP
path byte-for-byte).BaseEvent::asResource(Connector) hydrates the embedded entity into a
fully-typed SDK resource and automatically threads the rich origin
(event id, signature, received-at).WebhookEventMapper::processPayload() gains an optional ?string $signature parameter that is threaded through to the resulting event
and carried onto hydrated resources via WebhookSnapshotOrigin.ResourceCollection::withOrigin() factory as the origin-aware sibling
of withResponse().IsResponseAware::getResponse() return type narrowed
from Response to ?Response. HTTP-hydrated resources continue to
return a non-null Response, matching pre-refactor behavior.
Webhook-hydrated resources return null. User code that chains
$resource->getResponse()->successful() or similar without a null
check will NPE on webhook-origin resources — audit your webhook
handlers before upgrading. HTTP-only consumers see no change.HasResponse::getPendingRequest() return type
narrowed from PendingRequest to ?PendingRequest. Same rationale.WebhookEntity::asResource() gains an optional
?WebhookSnapshotOrigin second parameter. Callers using the
single-arg form ($event->entity()->asResource($mollie)) continue to
work and receive a fallback origin with null signature. Mapper-driven
flow ($event->asResource($mollie)) passes the rich origin
automatically.$payment->refunds(), $subscription->payments(), etc.) still
require an authenticator — they fire real HTTP requests.Payment::refunds/captures/chargebacks,
Profile::chargebacks/methods/payments/refunds, Subscription::payments)
now fall back to their endpoint collection when the embedded webhook
snapshot does not carry the corresponding _links.{name}.href.
Previously these methods returned an empty collection in that case,
which was a silent behavioural difference between HTTP-origin and
webhook-origin resources. With this change the SDK routes through
the connector using the resource's id (same pattern
PaymentLink::payments() already used), so you get a live child
collection on both origins. Relative _links.{name}.href values in
webhook payloads are resolved against the client's base URL via
Url::join, no special handling required on the caller's side.WebhookEventMapper::createWebhookEntityFromPayload() switched from
array_pop($_embedded) to key-agnostic iteration that picks the first
candidate carrying id and resource fields. Mollie keys the
embedded entity under _embedded.entity; the new iteration resolves
that correctly and is resilient to any future schema tweak (additional
_embedded sub-blocks, renamed key) without silently breaking webhook
handling.WebhookEntity::buildSyntheticResponse() and its dependencies on
PendingRequest, DynamicGetRequest, Nyholm\Psr7\Request, and
Nyholm\Psr7\Response. Webhook hydration goes through
SnapshotHydrator.protected Response $response property on the HasResponse trait.
Storage is now ?ResourceOrigin $origin; the getResponse() accessor
narrows back to ?Response for callers. Third-party subclasses that
read $this->response directly must migrate to $this->getResponse()
or $this->getOrigin().docs/webhooks.md previously stated that $event->entity() returns
null for simple payloads. It actually throws. Updated to correctly
describe reading the nullable $event->entity property or fetching
the resource via $event->entityId.Fix PHP 8+ deprecation warning in CreatePaymentRefundRequest by @Naoray in #872
googlepay type to wallet constants by @NormanAlbert91 in #869Full Changelog: v3.9.0...v3.10.0
Fix: Don't call deprecated setAccessible() by @derrabus in #852
setAccessible() by @derrabus in #852Capability::$requirements structure by @derrabus in #853Full Changelog: v3.8.0...v3.9.0
Fixed: cURL deprecation notice for PHP 8.5 and higher by @RobinvanderVliet in #847
Full Changelog: v3.7.0...v3.8.0
Full Changelog: https://github.com/mollie/mollie-api-php/compare/v3.7.0...v3.8.0
Add SWISH payment method by @samdejongobc in #844
Full Changelog: v3.6.0...v3.7.0
Full Changelog: https://github.com/mollie/mollie-api-php/compare/v3.6.0...v3.7.0
Feat/add balance transfer webhook events by @sandervanhooft in #842
Full Changelog: v3.5.0...v3.6.0
Full Changelog: https://github.com/mollie/mollie-api-php/compare/v3.5.0...v3.6.0
Feat/add retry logic by @Naoray in https://github.com/mollie/mollie-api-php/pull/826
MockEvent to easily test event handlingStr utility classclassBasename to UtilityWebhookEntity to serve as Container for Resource data received through webhooks (-> can be transformed into BaseResource)WebhookEventMapperFull Changelog: https://github.com/mollie/mollie-api-php/compare/v3.4.0...v3.5.0
Feat/add new payment route endpoints by @Naoray in https://github.com/mollie/mollie-api-php/pull/825
Full Changelog: https://github.com/mollie/mollie-api-php/compare/v3.3.3...v3.4.0
Nothing published for this version
Nothing published for this version
fix: signature validator handling null signatures by @Naoray in https://github.com/mollie/mollie-api-php/pull/822
Full Changelog: https://github.com/mollie/mollie-api-php/compare/v3.3.0...v3.3.1
Nothing published for this version
Feat/add create webhook endpoint by @Naoray in https://github.com/mollie/mollie-api-php/pull/812
Full Changelog: https://github.com/mollie/mollie-api-php/compare/v3.1.5...v3.2.0
Fix: allow array of payment methods when creating a payment by @jockri in https://github.com/mollie/mollie-api-php/pull/811
Full Changelog: https://github.com/mollie/mollie-api-php/compare/v3.1.4...v3.1.5
Nothing published for this version
Full Changelog: https://github.com/mollie/mollie-api-php/compare/v3.1.3...v3.1.3
Full Changelog: https://github.com/mollie/mollie-api-php/compare/v3.1.3...v3.1.3
Full Changelog: https://github.com/mollie/mollie-api-php/compare/v3.1.1...v3.1.2
Full Changelog: https://github.com/mollie/mollie-api-php/compare/v3.1.1...v3.1.2
Nothing published for this version
Main by @Naoray in https://github.com/mollie/mollie-api-php/pull/804
Full Changelog: https://github.com/mollie/mollie-api-php/compare/v3.0.6...v3.1.0
Amend capturable recipe by @fjbender in https://github.com/mollie/mollie-api-php/pull/796
Full Changelog: https://github.com/mollie/mollie-api-php/compare/v3.0.5...v3.0.6
Fix/791 data types may mess up property order by @Naoray in https://github.com/mollie/mollie-api-php/pull/794
Full Changelog: https://github.com/mollie/mollie-api-php/compare/v3.0.4...v3.0.5
Chore/allow psr message v1 by @Naoray in https://github.com/mollie/mollie-api-php/pull/793
Full Changelog: https://github.com/mollie/mollie-api-php/compare/v3.0.3...v3.0.4
Fixed docs links by @sandervanhooft in https://github.com/mollie/mollie-api-php/pull/787
MockResponse serializable$metadata handling to upgrade guideFull Changelog: https://github.com/mollie/mollie-api-php/compare/v3.0.2...v3.0.3
handle nullable 422 exception field by @sandervanhooft in https://github.com/mollie/mollie-api-php/pull/786
Full Changelog: https://github.com/mollie/mollie-api-php/compare/v3.0.1...v3.0.2
Nothing published for this version
Nothing published for this version
Nothing published for this version
Nothing published for this version
Nothing published for this version
Nothing published for this version
Nothing published for this version
Nothing published for this version
Nothing published for this version
Nothing published for this version
Nothing published for this version
Nothing published for this version
Nothing published for this version
This release aligns the v2 Checkout Sessions integration with the current API specification.
This release aligns the v2 Checkout Sessions integration with the current API specification.
clientAccessToken, customer and payment details, profile ID, and lifecycle timestamps.STATUS_OPEN, STATUS_EXPIRED, isOpen(), and isExpired() while retaining legacy fields and helpers for compatibility.requiredCustomerDetails option remains in private beta.See #939 and the full comparison.
Nothing published for this version
Nothing published for this version
Nothing published for this version
Nothing published for this version
Nothing published for this version
Nothing published for this version
Nothing published for this version
Nothing published for this version
Nothing published for this version
Nothing published for this version
Nothing published for this version
Nothing published for this version
Your coding agent can read these notes before it upgrades. Set up the MCP server →