RonanCodes/mollie

Mollie

Wire Mollie into a TanStack Start + Cloudflare Workers app, or call its REST API directly. Mollie is the Dutch/EU payment provider, the default pick for a Netherlands-first product because of iDEAL coverage, with a hosted checkout so you never touch card data.

On Workers, call the REST API directly with fetch (recommended). The @mollie/api-client package switched from Axios to native fetch in v4 (so v4+ is far more edge-friendly than v3), but the README still doesn't officially list Workers, and the surface you need (create + get + refund) is tiny. Direct fetch is zero-dependency and zero runtime-compat risk.

Usage

/ro:mollie install        # env + a fetch helper module
/ro:mollie add-checkout    # create payment -> redirect to hosted checkout
/ro:mollie add-webhook     # webhook route that re-fetches status (the security boundary)
/ro:mollie add-refund      # refund a payment
/ro:mollie ops             # API-ops cheat-sheet (curl), no app wiring

Prerequisites

• A Mollie account + profile, with payment methods activated in the dashboard.
• Keys in ~/.claude/.env (megathon block): MOLLIE_API_KEY (currently test_...), MOLLIE_PROFILE_ID (pfl_...).
• The webhookUrl must be publicly reachable HTTPS, so local dev needs a tunnel or a deployed Worker (Mollie's servers call it; localhost won't work).

Auth (API-ops core)

• Base URL: https://api.mollie.com/v2
• Header: Authorization: Bearer <key> on every request.
• Key types: test_... (test mode, no real money, simulate any status) vs live_... (real). Keys are profile-scoped, so you don't send profileId on normal calls (only org/OAuth tokens need it).

| Purpose | Method + path | | --- | --- | | Create payment | POST /v2/payments | | Get payment | GET /v2/payments/{id} | | List payments | GET /v2/payments | | Cancel payment | DELETE /v2/payments/{id} (while cancelable) | | Create / list / get refund | POST / GET /v2/payments/{id}/refunds (+ /{refundId}) |

Payment ids tr_..., refund ids re_....

The flow (read this before coding)

1. Create the payment server-side with both a redirectUrl (browser returns here) and a webhookUrl (Mollie notifies here). Persist your order ↔ tr_... mapping. Status starts open.
2. Redirect the browser to _links.checkout.href from the response.
3. User pays on Mollie's hosted page; Mollie redirects the browser back to redirectUrl. Treat this as "user is back", NOT as proof of payment (they may close the tab, or iDEAL settles async).
4. Mollie POSTs your webhookUrl (form-encoded) with only id=tr_.... No status, no JSON.
5. In the webhook you MUST GET /v2/payments/{id} and read status from the API response, then update the order. This is the security boundary: because the webhook carries no status, a forged call can never mark an order paid. Make the handler idempotent (Mollie retries).

Statuses: open, pending, authorized, paid (money in), canceled, expired, failed.

Install flow

1. Env

# .dev.vars (gitignored)
MOLLIE_API_KEY=test_...
APP_URL=https://souso.app   # for building redirect/webhook URLs

wrangler secret put MOLLIE_API_KEY

2. Fetch helper, src/lib/mollie.ts

const BASE = 'https://api.mollie.com/v2'

export interface MolliePayment {
  id: string
  status: 'open' | 'pending' | 'authorized' | 'paid' | 'canceled' | 'expired' | 'failed'
  amount: { currency: string; value: string }
  _links: { checkout?: { href: string } }
}

export async function createPayment(
  apiKey: string,
  p: { amount: string; description: string; redirectUrl: string; webhookUrl: string; method?: string },
): Promise<MolliePayment> {
  const res = await fetch(`${BASE}/payments`, {
    method: 'POST',
    headers: { Authorization: `Bearer ${apiKey}`, 'Content-Type': 'application/json' },
    body: JSON.stringify({
      amount: { currency: 'EUR', value: p.amount }, // string, 2 decimals: "10.00"
      description: p.description,
      redirectUrl: p.redirectUrl,
      webhookUrl: p.webhookUrl,
      ...(p.method ? { method: p.method } : {}),
    }),
  })
  if (!res.ok) throw new Error(`Mollie create failed: ${res.status} ${await res.text()}`)
  return res.json()
}

export async function getPayment(apiKey: string, id: string): Promise<MolliePayment> {
  const res = await fetch(`${BASE}/payments/${id}`, {
    headers: { Authorization: `Bearer ${apiKey}` },
  })
  if (!res.ok) throw new Error(`Mollie get failed: ${res.status}`)
  return res.json()
}

add-checkout

// src/routes/api/checkout.ts
export const Route = createFileRoute('/api/checkout')({
  server: { handlers: { POST: async ({ request }) => {
    const { env } = await import('cloudflare:workers')
    const { createPayment } = await import('../../lib/mollie')
    const { orderId, total } = await request.json()
    const payment = await createPayment(env.MOLLIE_API_KEY, {
      amount: Number(total).toFixed(2),               // "10.00"
      description: `Souso order #${orderId}`,
      redirectUrl: `${env.APP_URL}/order/${orderId}/return`,
      webhookUrl: `${env.APP_URL}/api/mollie/webhook`,
      // method: 'ideal',                              // optional: skip the picker
    })
    // store orderId -> payment.id, then send the checkout url to the client
    return Response.json({ checkoutUrl: payment._links.checkout?.href })
  }}},
})

add-webhook (the security boundary)

// src/routes/api/mollie/webhook.ts
export const Route = createFileRoute('/api/mollie/webhook')({
  server: { handlers: { POST: async ({ request }) => {
    const { env } = await import('cloudflare:workers')
    const { getPayment } = await import('../../../lib/mollie')
    const form = await request.formData()
    const id = String(form.get('id') ?? '')
    if (!id) return new Response('missing id', { status: 400 })
    const payment = await getPayment(env.MOLLIE_API_KEY, id) // source of truth
    await updateOrderStatus(id, payment.status)              // idempotent
    return new Response('ok', { status: 200 })               // 200 fast; Mollie retries on failure
  }}},
})

add-refund

curl -X POST "https://api.mollie.com/v2/payments/tr_xxx/refunds" \
  -H "Authorization: Bearer $MOLLIE_API_KEY" -H "Content-Type: application/json" \
  -d '{"amount":{"currency":"EUR","value":"10.00"},"description":"Refund order #123"}'

NL payment methods

• iDEAL (ideal) — dominant NL bank redirect, essential. Pass method:"ideal" (optionally an issuer) to skip the picker.
• creditcard — Visa/Mastercard, international.
• bancontact — the BE equivalent of iDEAL.
• Omit method to show Mollie's hosted picker (lists every method enabled on the profile). Activate methods in the dashboard before they appear live.

Gotchas

1. amount.value is a string with exactly 2 decimals ("10.00"), not a number. 10, 10.0, "10" are rejected. Use total.toFixed(2).
2. Test and live are separate worlds. test_ only makes test payments (force statuses in the test UI); live_ needs an approved account + activated methods. Don't mix.
3. webhookUrl must be public HTTPS. Tunnel (cloudflared/ngrok) or deployed Worker for local dev.
4. Never trust the redirect or the webhook body for status. Status comes only from GET /v2/payments/{id}. Webhook is idempotent (Mollie retries, may fire multiple times).
5. SDK on Workers: v4+ is fetch-based and likelier to work (add compatibility_flags=["nodejs_compat"] and test), but direct fetch is the safe default.

Souso use cases

• Premium/subscription checkout, or paying for a filled basket if you ever sell beyond the AH/Jumbo hand-off. Note Souso's hard rule is no autonomous purchasing of groceries; Mollie is for Souso's own product revenue, not the supermarket basket.

Env var summary

MOLLIE_API_KEY=test_...    # server only; live_... in prod
MOLLIE_PROFILE_ID=pfl_...  # informational; not sent on profile-scoped key calls
APP_URL=https://...        # to build redirect + webhook URLs

Safety

Server-side only; the key is full payment access. The webhook re-fetch is mandatory and is what makes the flow forgery-proof, never derive paid-status from the request. Keep the live key out of the repo (Wrangler secret).

See also

• Docs: https://docs.mollie.com (create-payment, webhooks, authentication)
• SDK: @mollie/api-client (v4+ fetch-based). Sibling payments skill: /ro:stripe