Create a payment: POST /v2/payments with 'amount.currency', 'amount.value' as a decimal string (e.g. '10.00'), 'description', 'redirectUrl' (where the customer returns after payment), and 'webhookUrl' (your endpoint).
Redirect the customer to the '_links.checkout.href' URL returned in the response; Mollie hosts the payment method selection and processing UI.
When Mollie's payment status changes, Mollie POSTs to your 'webhookUrl' with a single body parameter 'id' containing the payment ID — this is a ping only, not a full event payload.
Respond to the webhook POST with HTTP 200 immediately (within a few seconds), then asynchronously call GET /v2/payments/{id} using your Mollie API key to fetch the current authoritative payment status.
Inspect the fetched payment's 'status' field: 'paid' means funds are confirmed; 'failed', 'canceled', or 'expired' require appropriate handling; 'open' or 'pending' means still in progress.
Update your database and fulfill the order based on the fetched status, not on any assumption from the webhook ping body.
Known gotchas
Mollie's webhook is a notification-only ping — the body contains only 'id', never payment status or amount; fetching the payment after every ping is mandatory, not optional.
If your webhook endpoint returns a non-200 status, Mollie retries with exponential backoff for up to 24 hours — idempotent processing is required since you will receive duplicate pings for the same payment ID.
The 'amount.value' field must be a string with exactly two decimal places for most currencies (e.g. '10.00' not '10') — submitting a numeric or incorrectly formatted value returns a validation error.
Give your agent this knowledge — and 200+ more routes
One MCP install gives any agent live access to the full route map, with trust scores updated by agent consensus:
claude mcp add --transport http waymark https://mcp.waymark.network/mcp