A reference guide for building AI agents: every method, how to authenticate, and the permissions each one needs.
The Mollie API is how an app or AI agent works with a Mollie account: taking a payment, refunding a charge, creating a customer, or running recurring billing through mandates and subscriptions. Access is granted through a Bearer credential, an API key, an organization access token, or an OAuth grant, and OAuth carries per-area scopes that set which resources a call can read or write. When something changes, Mollie posts only the object's id to a registered address, so the receiver fetches the current state rather than trusting the message.
How an app or AI agent connects to Mollie determines what it can reach. There is a route for making calls, a route for receiving events, and a hosted server that exposes Mollie tools to agents, and each is governed by the credential behind it and the permissions that credential carries.
The REST API takes JSON request bodies, returns HAL+JSON, and pages through lists with a cursor, at https://api.mollie.com/v2. A call authenticates with a Bearer credential: a profile API key, an organization access token, or an OAuth access token. The older v1 is legacy, and the Orders API is no longer recommended for new work.
A first-party hosted Model Context Protocol server at https://mcp.mollie.com/mcp acts as a proxy for the public API, exposing Mollie tools to AI clients like Claude and Cursor. It authenticates with an organization access token passed as the MOLLIE_API_OAUTH_ORG_TOKEN environment variable, where profiles.read is required and the token's other scopes decide which tools work. It covers the Payments, Payment Links, Refunds, Captures, Customers, Mandates, Subscriptions, Methods, Settlements, Invoices, Balances, Terminals, and Webhooks APIs.
Mollie POSTs to a webhookUrl set on a payment, subscription, or payment link when its status changes. The body is form-encoded and carries only the object's id, like id=tr_..., so the receiver fetches the current state and never trusts the request itself. The endpoint must return HTTP 200, or Mollie retries up to 10 times over about 26 hours.
An API key authenticates a single profile and is sent as a Bearer token. A test key (test_...) operates on simulated data where no money moves, and a live key (live_...) processes real payments. A key carries full access for its profile, so it is not scoped per resource the way OAuth is.
An organization (advanced) access token reaches organization-level resources across profiles, sent as a Bearer token. It is shown only once, at creation, and can be limited to specific profiles or to test or live mode. The Mollie MCP server uses this token type.
OAuth lets an app call Mollie on behalf of another organization that grants consent, through Mollie Connect. The app requests a subset of scopes, like payments.read, payments.write, refunds.write, or customers.read, and the access token reaches only what those scopes allow. When no scopes are requested, the grant defaults to organizations.read alone.
The Mollie API is split into areas an agent can act on, like payments, refunds, customers, subscriptions, and settlements. Each area has its own methods, and writes in some areas move real money or change recurring billing.
Methods for creating and managing payments, the core of the Mollie API.
Methods for refunding payments, fully or in part.
Methods for working with customer records.
Methods for recurring billing on a customer.
Methods for the recurring-payment authorizations behind subscriptions.
Methods for the older Orders API, still required by some pay-later methods.
Methods for listing and configuring the payment methods a profile offers.
Methods for the payouts Mollie makes to a merchant's bank account.
Methods for reading chargebacks raised against payments.
Methods for reading account balances and their transactions.
Filter by method, access, or permission, or search any path. Select a row for version detail, rate limits, the related webhook event, and the source.
| Method | Endpoint | What it does | Access | Permission | Version | |
|---|---|---|---|---|---|---|
PaymentsMethods for creating and managing payments, the core of the Mollie API.5 | ||||||
| POST | /v2/payments | Create a payment, returning a checkout URL to send the customer to. | write | payments.write | Current | |
A core write. The webhookUrl set here is where Mollie posts status changes. Acts onpayment Permission (capability) payments.writeVersionAvailable since the API’s base version Webhook event payment.paidRate limitStandard limits apply SourceOfficial documentation ↗ | ||||||
| GET | /v2/payments/{id} | Retrieve a single payment by its id, including its current status. | read | payments.read | Current | |
Read-only. This is the call a webhook receiver makes to learn the real status. Acts onpayment Permission (capability) payments.readVersionAvailable since the API’s base version Webhook eventNone Rate limitStandard limits apply SourceOfficial documentation ↗ | ||||||
| GET | /v2/payments | List payments, newest first, paged with a cursor. | read | payments.read | Current | |
Read-only. Acts onpayment Permission (capability) payments.readVersionAvailable since the API’s base version Webhook eventNone Rate limitStandard limits apply SourceOfficial documentation ↗ | ||||||
| PATCH | /v2/payments/{id} | Update an open payment's metadata, description, or redirect and webhook URLs. | write | payments.write | Current | |
Only certain fields can change, and only while the payment is open. Acts onpayment Permission (capability) payments.writeVersionAvailable since the API’s base version Webhook eventNone Rate limitStandard limits apply SourceOfficial documentation ↗ | ||||||
| DELETE | /v2/payments/{id} | Cancel a payment that is still cancelable. | write | payments.write | Current | |
Only works while the payment's isCancelable flag is true. Acts onpayment Permission (capability) payments.writeVersionAvailable since the API’s base version Webhook event payment.canceledRate limitStandard limits apply SourceOfficial documentation ↗ | ||||||
RefundsMethods for refunding payments, fully or in part.4 | ||||||
| POST | /v2/payments/{paymentId}/refunds | Refund a payment, fully or in part, back to the customer. | write | refunds.write | Current | |
Moves real money. Only payments with a positive amountRemaining can be refunded. Acts onrefund Permission (capability) refunds.writeVersionAvailable since the API’s base version Webhook eventNone Rate limitStandard limits apply SourceOfficial documentation ↗ | ||||||
| GET | /v2/payments/{paymentId}/refunds/{id} | Retrieve a single refund on a payment. | read | refunds.read | Current | |
Read-only. Acts onrefund Permission (capability) refunds.readVersionAvailable since the API’s base version Webhook eventNone Rate limitStandard limits apply SourceOfficial documentation ↗ | ||||||
| GET | /v2/refunds | List all refunds across the organization, paged with a cursor. | read | refunds.read | Current | |
Read-only. Acts onrefund Permission (capability) refunds.readVersionAvailable since the API’s base version Webhook eventNone Rate limitStandard limits apply SourceOfficial documentation ↗ | ||||||
| DELETE | /v2/payments/{paymentId}/refunds/{id} | Cancel a refund that has not yet been processed. | write | refunds.write | Current | |
Only queued refunds can be canceled, before they are paid out. Acts onrefund Permission (capability) refunds.writeVersionAvailable since the API’s base version Webhook eventNone Rate limitStandard limits apply SourceOfficial documentation ↗ | ||||||
CustomersMethods for working with customer records.5 | ||||||
| POST | /v2/customers | Create a customer record to attach payments, mandates, and subscriptions to. | write | customers.write | Current | |
A core write for recurring billing. Acts oncustomer Permission (capability) customers.writeVersionAvailable since the API’s base version Webhook eventNone Rate limitStandard limits apply SourceOfficial documentation ↗ | ||||||
| GET | /v2/customers/{id} | Retrieve a single customer by its id. | read | customers.read | Current | |
Read-only. Acts oncustomer Permission (capability) customers.readVersionAvailable since the API’s base version Webhook eventNone Rate limitStandard limits apply SourceOfficial documentation ↗ | ||||||
| GET | /v2/customers | List customers, newest first, paged with a cursor. | read | customers.read | Current | |
Read-only. Acts oncustomer Permission (capability) customers.readVersionAvailable since the API’s base version Webhook eventNone Rate limitStandard limits apply SourceOfficial documentation ↗ | ||||||
| PATCH | /v2/customers/{id} | Update a customer's name, email, locale, or metadata. | write | customers.write | Current | |
A core write. Acts oncustomer Permission (capability) customers.writeVersionAvailable since the API’s base version Webhook eventNone Rate limitStandard limits apply SourceOfficial documentation ↗ | ||||||
| DELETE | /v2/customers/{id} | Delete a customer record permanently. | write | customers.write | Current | |
Irreversible; the customer and its stored details are removed. Acts oncustomer Permission (capability) customers.writeVersionAvailable since the API’s base version Webhook eventNone Rate limitStandard limits apply SourceOfficial documentation ↗ | ||||||
SubscriptionsMethods for recurring billing on a customer.4 | ||||||
| POST | /v2/customers/{customerId}/subscriptions | Create a recurring subscription on a customer that has a valid mandate. | write | subscriptions.write | Current | |
Requires an existing mandate; each generated charge calls the subscription's webhookUrl. Acts onsubscription Permission (capability) subscriptions.writeVersionAvailable since the API’s base version Webhook eventNone Rate limitStandard limits apply SourceOfficial documentation ↗ | ||||||
| GET | /v2/customers/{customerId}/subscriptions/{id} | Retrieve a single subscription on a customer. | read | subscriptions.read | Current | |
Read-only. Acts onsubscription Permission (capability) subscriptions.readVersionAvailable since the API’s base version Webhook eventNone Rate limitStandard limits apply SourceOfficial documentation ↗ | ||||||
| PATCH | /v2/customers/{customerId}/subscriptions/{id} | Update a subscription's amount, interval, description, or metadata. | write | subscriptions.write | Current | |
Changes future charges for an active subscription. Acts onsubscription Permission (capability) subscriptions.writeVersionAvailable since the API’s base version Webhook eventNone Rate limitStandard limits apply SourceOfficial documentation ↗ | ||||||
| DELETE | /v2/customers/{customerId}/subscriptions/{id} | Cancel an active subscription so no further charges are made. | write | subscriptions.write | Current | |
Stops recurring charges; existing payments are unaffected. Acts onsubscription Permission (capability) subscriptions.writeVersionAvailable since the API’s base version Webhook eventNone Rate limitStandard limits apply SourceOfficial documentation ↗ | ||||||
MandatesMethods for the recurring-payment authorizations behind subscriptions.3 | ||||||
| POST | /v2/customers/{customerId}/mandates | Create a mandate authorizing Mollie to charge a customer for recurring payments. | write | mandates.write | Current | |
Records consent to charge; a subscription needs a valid mandate to run. Acts onmandate Permission (capability) mandates.writeVersionAvailable since the API’s base version Webhook eventNone Rate limitStandard limits apply SourceOfficial documentation ↗ | ||||||
| GET | /v2/customers/{customerId}/mandates | List the mandates on a customer, paged with a cursor. | read | mandates.read | Current | |
Read-only. Acts onmandate Permission (capability) mandates.readVersionAvailable since the API’s base version Webhook eventNone Rate limitStandard limits apply SourceOfficial documentation ↗ | ||||||
| DELETE | /v2/customers/{customerId}/mandates/{id} | Revoke a mandate so it can no longer be used to charge the customer. | write | mandates.write | Current | |
Subscriptions relying on the mandate can no longer charge. Acts onmandate Permission (capability) mandates.writeVersionAvailable since the API’s base version Webhook eventNone Rate limitStandard limits apply SourceOfficial documentation ↗ | ||||||
Orders (legacy)Methods for the older Orders API, still required by some pay-later methods.3 | ||||||
| POST | /v2/orders | Create an order with line items, used by pay-later methods that require it. | write | orders.write | Current | |
Mollie no longer recommends the Orders API; use Payments unless a method like Klarna or Billie requires it. Acts onorder Permission (capability) orders.writeVersionAvailable since the API’s base version Webhook eventNone Rate limitStandard limits apply SourceOfficial documentation ↗ | ||||||
| GET | /v2/orders/{id} | Retrieve a single order and its lines by id. | read | orders.read | Current | |
Read-only. Acts onorder Permission (capability) orders.readVersionAvailable since the API’s base version Webhook eventNone Rate limitStandard limits apply SourceOfficial documentation ↗ | ||||||
| DELETE | /v2/orders/{id} | Cancel an order that has not been completed. | write | orders.write | Current | |
Only cancelable orders can be canceled. Acts onorder Permission (capability) orders.writeVersionAvailable since the API’s base version Webhook eventNone Rate limitStandard limits apply SourceOfficial documentation ↗ | ||||||
MethodsMethods for listing and configuring the payment methods a profile offers.3 | ||||||
| GET | /v2/methods | List the payment methods enabled for a profile, optionally for a given amount. | read | payments.read | Current | |
Read-only; used to render available methods at checkout. Acts onmethod Permission (capability) payments.readVersionAvailable since the API’s base version Webhook eventNone Rate limitStandard limits apply SourceOfficial documentation ↗ | ||||||
| GET | /v2/methods/{id} | Retrieve a single payment method by its id. | read | payments.read | Current | |
Read-only. Acts onmethod Permission (capability) payments.readVersionAvailable since the API’s base version Webhook eventNone Rate limitStandard limits apply SourceOfficial documentation ↗ | ||||||
| POST | /v2/profiles/{profileId}/methods/{id} | Enable a payment method on a profile. | write | profiles.write | Current | |
Configures which methods a profile offers; governed by the profiles scope. Acts onmethod Permission (capability) profiles.writeVersionAvailable since the API’s base version Webhook eventNone Rate limitStandard limits apply SourceOfficial documentation ↗ | ||||||
SettlementsMethods for the payouts Mollie makes to a merchant's bank account.2 | ||||||
| GET | /v2/settlements/{id} | Retrieve a single settlement, the payout Mollie made to the bank account. | read | settlements.read | Current | |
Read-only. Acts onsettlement Permission (capability) settlements.readVersionAvailable since the API’s base version Webhook eventNone Rate limitStandard limits apply SourceOfficial documentation ↗ | ||||||
| GET | /v2/settlements | List settlements, paged with a cursor. | read | settlements.read | Current | |
Read-only. Acts onsettlement Permission (capability) settlements.readVersionAvailable since the API’s base version Webhook eventNone Rate limitStandard limits apply SourceOfficial documentation ↗ | ||||||
ChargebacksMethods for reading chargebacks raised against payments.2 | ||||||
| GET | /v2/chargebacks | List all chargebacks across the organization, paged with a cursor. | read | payments.read | Current | |
Read-only; chargebacks are read through the payments scope. Acts onchargeback Permission (capability) payments.readVersionAvailable since the API’s base version Webhook eventNone Rate limitStandard limits apply SourceOfficial documentation ↗ | ||||||
| GET | /v2/payments/{paymentId}/chargebacks/{id} | Retrieve a single chargeback raised against a payment. | read | payments.read | Current | |
Read-only. Acts onchargeback Permission (capability) payments.readVersionAvailable since the API’s base version Webhook eventNone Rate limitStandard limits apply SourceOfficial documentation ↗ | ||||||
BalancesMethods for reading account balances and their transactions.3 | ||||||
| GET | /v2/balances | List the balances held in the account, paged with a cursor. | read | balances.read | Current | |
Read-only. Acts onbalance Permission (capability) balances.readVersionAvailable since the API’s base version Webhook eventNone Rate limitStandard limits apply SourceOfficial documentation ↗ | ||||||
| GET | /v2/balances/primary | Retrieve the primary balance, the one money settles into by default. | read | balances.read | Current | |
Read-only. Acts onbalance Permission (capability) balances.readVersionAvailable since the API’s base version Webhook eventNone Rate limitStandard limits apply SourceOfficial documentation ↗ | ||||||
| GET | /v2/balances/{balanceId}/transactions | List the transactions that make up a balance, paged with a cursor. | read | balances.read | Current | |
Read-only. Acts onbalance_transaction Permission (capability) balances.readVersionAvailable since the API’s base version Webhook eventNone Rate limitStandard limits apply SourceOfficial documentation ↗ | ||||||
Mollie can notify an app when something changes, like a payment being paid or a subscription generating its next charge. It sends only the object's id, so the receiver fetches the current state rather than trusting the request, and learns about activity without polling.
| Event | What it signals | Triggered by |
|---|---|---|
payment status change (paid) | A payment reached a final state such as paid. Mollie posts the payment id to the webhookUrl set on the payment, and the receiver fetches the payment to read the real status. | /v2/payments |
payment status change (canceled) | A payment was canceled. Mollie posts the payment id to the payment's webhookUrl, and the receiver fetches the payment to confirm. | /v2/payments/{id} |
Mollie limits how fast an app can call to protect the API, and pages through long lists with a cursor rather than a page number.
Mollie limits how fast the API can be called to protect it, and recommends exponential back-off when retrying so a client does not flood the API. Going over returns HTTP 429 with a Retry-After header that says how long to wait before trying again. Mollie does not publish a fixed request-per-second figure in its public reference.
A v2 list endpoint uses cursor pagination, so objects in a page do not shift when new ones are created. The limit parameter sets the page size up to a maximum of 250, from takes the id of an object to start from, and sort is asc or desc with desc (newest first) the default. The response carries a _links.next href to fetch the following page until there are no more.
A list returns at most 250 objects per page, the maximum value of limit. An Idempotency-Key is cached for one hour, after which the same key counts as a new request.
The status codes an agent should handle, and what to do about each.
| Status | Code | Meaning | What to do |
|---|---|---|---|
| 400 | Bad Request | The request could not be understood, usually a syntax problem in the body or parameters. | Read the title and detail in the response, fix the request, and resend. |
| 401 | Unauthorized | Authentication failed, for example a missing, malformed, or wrong-mode credential. | Check the Bearer credential and that it matches the mode (test or live) being used. |
| 403 | Forbidden | The credential is valid but lacks access to the requested resource, for example an OAuth token missing the needed scope. | Grant the required scope, or use a credential with access to the resource. |
| 404 | Not Found | The referenced object does not exist, or is not visible to this credential or mode. | Verify the id and that it lives in the same account and mode. |
| 422 | Unprocessable Entity | The request was well formed but could not be processed, like an invalid value. The response may include a field property naming the offending input. | Read the field and detail, correct that input, and resend. |
| 429 | Too Many Requests | The rate limit was reached. | Read the Retry-After header and back off with exponential delay before retrying. |
| 503 | Service Unavailable | The service is temporarily unavailable on Mollie's side. | Retry later with backoff; if it persists, contact Mollie support. |
Mollie runs a single current version of its API, v2, and ships dated changes through release notes rather than minting a new version string for each one.
Mollie runs a single current API version, v2, with JSON requests and HAL+JSON responses. New capability ships through dated release notes rather than a new version string, and the older v1 is legacy.
Mollie released a first-party hosted Model Context Protocol server so merchants can drive their account from AI clients in natural language. It proxies the public API and authenticates with an organization access token.
Mollie continues to extend v2, including a next-generation webhooks model in beta with new event types and flexible delivery, alongside the original per-object webhookUrl model.
Build against v2; the older v1 is legacy and the Orders API is no longer recommended for new work.
Mollie changelog ↗Bollard AI sits between a team's AI agents and Mollie. Grant each agent exactly the access it needs, read or write, resource by resource, and every call is checked and logged.