| name | mollie-payments |
| description | Activate this skill when a developer is working with Mollie: integrating payments, setting up Mollie Connect for a platform/marketplace, building recurring payments or subscriptions, issuing refunds or captures, investigating chargebacks or settlements, or troubleshooting a Mollie integration. This includes: accepting credit card payments, embedding Mollie Components (card fields), setting up a checkout flow, handling payment redirects, verifying webhooks, handling payment status updates, integrating Mollie in Next.js / React / Vue / vanilla JS, setting up Mollie in a backend (Node.js, PHP, Python), creating payments via the API, using the Mollie SDK, handling card tokenisation, 3D Secure, Mollie.js, mollie-api-node, PCI compliance, card form, hosted checkout, payment links, iDEAL, credit card, SEPA, Klarna, Apple Pay, Google Pay, Bancontact, building a checkout, custom checkout, payment methods, Mollie Connect, OAuth onboarding, submerchants, application fees, mandates, customers API, subscriptions, recurring charges, refunds, captures, chargebacks, settlements, reconciliation, payment stuck or pending, webhook not received, 401/403 errors.
|
Mollie Payments
Use <references/product-selection/routing-guide.md> for the full decision tree if
a request spans more than one dimension below (e.g. "recurring payments for my
marketplace clients"). The steps here cover the common single-dimension case.
Step 1 — Is this new integration work, or something else?
Ask this first, before anything else:
Are you setting up something new, fixing a problem with an existing integration,
upgrading/migrating an existing one, or building an AI agent that uses Mollie?
- Something isn't working (stuck payment, missing webhook, auth error, wrong
credentials) → go straight to
<references/troubleshooting/>. Do not generate new
integration code before ruling out a known issue.
- Upgrading an SDK version or migrating from an older API → this is the
mollie-upgrade skill, not this one.
- Building an agent that calls Mollie autonomously (via
@mollie/agent-toolkit,
or exposing Mollie as LLM tools) → this is the mollie-agent-toolkit skill.
- Refunding, capturing, or investigating existing payments/chargebacks/settlements
→
<references/operations/>.
- New integration → continue to Step 2.
Step 2 — Direct merchant or platform?
Are you building this for your own business (accepting payments directly as a
merchant), or are you building a platform or marketplace that processes payments
on behalf of other businesses?
If they are a platform or marketplace → this needs Mollie Connect, not a
standard integration. Route to <references/connect/oauth-and-onboarding.md> and
work through the Connect reference set — it covers OAuth, onboarding, application
fees, permissions/tokens, and testing/offboarding. Everything in Steps 3–5 below
still applies once Connect is set up (a platform can still need recurring payments
or hosted checkout — just executed via a client's access token).
If they are a direct merchant → continue to Step 3.
Step 3 — One-time or recurring?
Is this a single checkout, or does the customer get charged again later without
re-entering their payment details (subscription, saved card, usage billing)?
Recurring → route to <references/recurring/customers-and-mandates.md> — this
is a distinct flow (Customers API → first payment → mandate → subscription or
on-demand charge), not a variant of one-time checkout. Webhook handling still
applies (<references/payments/webhooks.md>), but skip Step 4 below.
One-time → continue to Step 4.
Step 4 — Understand their checkout preference
How much control do you want over the payment experience?
A) Mollie-hosted checkout — Mollie handles the entire payment page. Simplest to
integrate; no frontend work required. Customers are redirected to Mollie to
complete payment.
B) Build your own checkout — You embed payment method selection and
(optionally) card fields directly in your UI. More work, but full control over
design and branding.
Not sure? Hosted checkout takes ~30 minutes and handles everything for you. A
custom checkout takes longer but keeps customers on your page throughout.
Step 5 — Understand their stack
Before writing any code, ask:
What language and framework are you using?
- Backend: Node.js / PHP / Python / other?
- Frontend: React / Vue / Next.js / vanilla JS / other?
- Are you in test mode or live?
Use the answers to generate code with the correct SDK and idioms.
Step 6 — Route to the correct reference
| Checkout preference | Card handling | Reference |
|---|
| Mollie-hosted checkout | Mollie handles card UI | <references/payments/hosted-checkout.md> |
| Build your own — embed card fields | Mollie Components (Mollie.js) | <references/payments/components.md> |
| Build your own — other methods only | Methods API + Payments API | <references/payments/build-your-own-checkout.md> |
All integrations require webhook handling — always include it: <references/payments/webhooks.md>
SDK selection
Always use the official Mollie SDK for the developer's language:
| Language | Package |
|---|
| JavaScript / Node.js | @mollie/api-client |
| TypeScript | mollie-api-typescript |
| PHP | mollie/mollie-api-php (Composer) |
| Python | mollie-api-python |
Always use the v2 API. Never construct raw API calls when an SDK is available.
Never use the Orders API for a new integration — it's deprecated. Always build
against the Payments API (payments.create, etc.), including hold-then-capture
flows (captureMode: 'manual', see <references/operations/captures.md>) that the
Orders API used to handle via Shipments. If a developer's existing code already uses
the Orders API, that's a migration case — route to the mollie-upgrade skill rather
than extending the old API.
Critical rules — apply to every integration
- Never put API keys (
live_xxx / test_xxx) in frontend code. Only the profile ID (pfl_xxx) belongs in the browser.
- Always verify payment status via webhook before fulfilling an order — never trust the redirect URL alone.
- Always respond with HTTP 200 to webhook requests before doing any async work. Mollie retries on any other status.
- Always redirect customers to the checkout URL using HTTP GET (303 See Other), never POST.
- The profile ID used in
Mollie() on the frontend must belong to the same account as the API key used on the backend.
- In test mode, pass
testmode: true to Mollie() on the frontend AND use a test API key (test_xxx) on the backend. Both must match.
- When a card payment fails, create a new card token and a new payment — you cannot retry on the same payment.
- Never show a payment result to the customer until the webhook has been received and processed.
- Additionally, for any refund, capture, or cancellation: read
<references/operations/write-action-safety.md> before generating the code — these are harder to reverse than a payment creation.
