Terminal
Terminal/Skill
Guides a developer through adding Mollie payments to an app, covering checkout, webhooks, subscriptions, refunds, and troubleshooting stuck payments.
By Mollie
Works with
npx skills add mollie/ai --skill mollie-paymentsUse <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.
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?
<references/troubleshooting/>. Do not generate new
integration code before ruling out a known issue.mollie-upgrade skill, not this one.@mollie/agent-toolkit,
or exposing Mollie as LLM tools) → this is the mollie-agent-toolkit skill.<references/operations/>.<references/payments/sales-invoices.md> — skip Steps 2–6 below, they don't apply.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.
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.
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.
C) Payment link — No embedded checkout at all. You share a URL with the customer (email, SMS, chat, QR code) instead of redirecting from a live session. Use this when there's no checkout page to redirect from — phone/mail orders, donations, social selling. (A formal invoice with payment terms/VAT lines is a different product — see Step 1's Sales Invoices branch.)
Not sure? Hosted checkout takes ~30 minutes and handles everything for you. A custom checkout takes longer but keeps customers on your page throughout. If there's no live session to redirect from in the first place, it's a payment link, not A or B.
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.
| 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> |
| Payment link — no embedded checkout, share a URL | Mollie handles card UI | <references/payments/payment-links.md> |
All integrations require webhook handling — always include it: <references/payments/webhooks.md>
Always use the official Mollie SDK for the developer's language:
| Language | Package |
|---|---|
| JavaScript / TypeScript / Node.js | mollie-api-typescript |
| PHP | mollie/mollie-api-php (Composer) |
| Python | mollie-api-py |
@mollie/api-client (Node) and mollie-api-python are the old/community SDKs —
don't use them for new integrations. If a developer already has one installed,
that's a migration case for the mollie-upgrade skill, not a new build.
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.
live_xxx / test_xxx) in frontend code. Only the profile ID (pfl_xxx) belongs in the browser.Mollie() on the frontend must belong to the same account as the API key used on the backend.testmode: true to Mollie() on the frontend AND use a test API key (test_xxx) on the backend. Both must match.<references/operations/write-action-safety.md> before generating the code — these are harder to reverse than a payment creation.