Monitor Mollie API Schema Changes for Your Integration

Published: May 2026 • 8 min read

Mollie is one of the leading payment service providers in Europe, powering payments for thousands of businesses. If your application integrates with Mollie's API, staying informed about API changes is essential to keep your payment flow running. This guide covers Mollie's API structure, common integration pitfalls, and how to automatically detect changes to Mollie's API schema.

Mollie's API Structure

Mollie provides a RESTful API for managing payments, refunds, customers, subscriptions, and more. Key resources include:

• Payments — Create, retrieve, list, and cancel payments
• Refunds — Process full or partial refunds
• Customers — Manage customer records for recurring payments
• Subscriptions — Set up and manage recurring billing
• Methods — List available payment methods (iDEAL, Bancontact, credit cards, etc.)
• Settlements — Track payouts and settlement details
• Webhooks — Receive real-time payment status updates

Mollie's API is well-documented and follows REST conventions. They publish an OpenAPI-compatible specification that describes all endpoints, parameters, and response schemas.

How Mollie Handles API Changes

Mollie's approach to API evolution has some important characteristics:

Versioning by Endpoint

Mollie doesn't use global API version numbers like /v1/ or /v2/. Instead, they evolve endpoints individually. When a breaking change is needed, they may introduce a new version of a specific endpoint while keeping others unchanged.

API Version Header

You can pin your integration to a specific API version by sending the API-Version header. This ensures your requests and responses use a consistent format, even as Mollie releases new versions. If you don't specify a version, your account's default version is used.

Additive Changes

Mollie frequently adds new fields to responses — new payment method options, additional metadata fields, new status values. These are generally non-breaking, but they can cause issues if your integration uses strict parsing or exhaustive type checking.

Common Integration Issues

1. New Payment Method Types

Mollie regularly adds support for new payment methods. If your integration has a hardcoded list of payment methods, new additions may not display correctly. Always handle unknown payment methods gracefully.

2. Status Field Changes

Payment statuses evolve over time. New statuses may be added, or the conditions for existing statuses may change. If your integration uses a switch statement on payment status, ensure it handles unknown values.

3. Webhook Payload Evolution

Webhook payloads change as the API evolves. If your webhook handler parses specific fields, changes to the payload structure can cause processing failures. Always validate webhook payloads against the current schema.

4. Amount and Currency Handling

Minor changes to how amounts are represented (string vs. integer, decimal places) can cause calculation errors. Mollie uses string amounts with explicit currency codes, but changes to this format would be breaking.

5. Pagination Changes

List endpoints may change their pagination format. If your integration fetches large datasets, changes to pagination parameters or response structure can cause data loss or infinite loops.

Monitoring Mollie's API Changes

Staying ahead of Mollie's API changes requires systematic monitoring. Here's how to approach it:

Manual Monitoring

Mollie publishes a changelog and sends notifications about significant changes. You can also:

• Subscribe to Mollie's developer newsletter
• Watch their documentation for updates
• Review the API changelog before deploying integration changes

The limitation: changelogs are human-readable but not machine-parseable. They describe what changed at a high level, but don't give you exact field-level diffs.

Automated Monitoring with SchemaWatch

SchemaWatch monitors Mollie's OpenAPI specification automatically. It detects changes at the schema level — exactly which endpoints, parameters, and response fields were added, modified, or removed.

SchemaWatch gives you:

• Continuous monitoring — Mollie's spec is checked on a schedule, not just when you remember to look
• Field-level diffs — See exactly which fields changed, not just a high-level summary
• Breaking change classification — Changes are automatically categorized as breaking or non-breaking
• Version history — Full timeline of all detected changes
• Alerts — Get notified immediately when changes are detected

This is especially valuable for Mollie because their changes are endpoint-specific rather than global. SchemaWatch tracks changes at the individual endpoint level, so you know exactly which part of your integration needs attention.

Best Practices for Mollie Integration Maintenance

1. Pin your API version — Always specify the API-Version header in your requests. This prevents unexpected behavior changes.
2. Use loose parsing — Don't reject responses with unknown fields. Use a tolerant parser that ignores unexpected data.
3. Handle unknown enum values — For payment methods, statuses, and other enum fields, always have a fallback for values you don't recognize.
4. Test with sandbox first — Mollie's test environment reflects the latest API version. Test your changes there before upgrading production.
5. Monitor webhook reliability — Track webhook delivery success rates. A sudden increase in failures may indicate a schema change.
6. Keep your SDK updated — If you use Mollie's official SDK, updates often include support for new API features and compatibility fixes.
7. Review changes before upgrading — When you're ready to move to a new API version, review the exact schema diff, not just the changelog.

Responding to Detected Changes

When SchemaWatch detects a change in Mollie's API spec:

1. Review the diff — Check which endpoints and fields are affected
2. Assess impact — Does the change affect features your integration uses?
3. Check your pinned version — If you're pinned, the change only affects you when you upgrade
4. Update your code — Make your integration compatible with the new schema
5. Test in sandbox — Verify your changes work in Mollie's test environment
6. Deploy and monitor — After deploying, watch your error rates and payment success rates

Conclusion

Mollie's API is stable and well-designed, but like any actively developed API, it evolves over time. Automated monitoring of Mollie's OpenAPI spec gives you early warning of changes, so you can update your integration proactively instead of reacting to production failures.