Mollie in React and the Next.js App Router: Mollie Components, 3-D Secure and the webhook

Mollie Components are Mollie's card fields: four iframes from Mollie.js that turn the card details into a card token, so the digits never reach your server. This page wires them into the Next.js App Router: a Server Action creates the payment with @mollie/api-client 4.6.0, the buyer finishes 3-D Secure on Mollie's page, a return page reads the status and a webhook marks the order paid. It shows the no-card-form route with Mollie's hosted checkout in full, then puts the fields inside an animated 3D card checkout.

One payment$3

By buying you agree to the Terms.

One payment, no subscription
Download right after paying
Use it in client projects
Won't run on the listed stack? We fix it or refund you

Ready forCursorv0Lovableshadcn CLI

Full product pageReact · Tailwind · TypeScript

Mollie Components inside the 3D card, in the App Router

app/pay/checkout.tsx

"use client";
import Script from "next/script";
import { useEffect, useState } from "react";
import CardCheckout, { type CardFieldsSlot } from "@/components/CardCheckout";
import type { MollieComponent, MollieFieldType, MollieInstance } from "@/lib/mollie-js";
import { createCardPayment } from "./actions";

// Mollie needs all four fields mounted before it gives you a card token, card holder included.
const FIELDS: { type: MollieFieldType; label: string; focus: "number" | "expiry" | "cvc" | null }[] = [
  { type: "cardNumber", label: "Card number", focus: "number" },
  { type: "cardHolder", label: "Cardholder name", focus: null },
  { type: "expiryDate", label: "Expiry", focus: "expiry" },
  { type: "verificationCode", label: "CVC", focus: "cvc" },
];

let mollie: MollieInstance | null = null; // one Mollie object per page load
function getMollie() {
  if (!mollie && window.Mollie) {
    mollie = window.Mollie(process.env.NEXT_PUBLIC_MOLLIE_PROFILE_ID!, {
      locale: "en_US",
      testmode: process.env.NEXT_PUBLIC_MOLLIE_TESTMODE === "true",
    });
  }
  return mollie;
}

function MollieFields({ slot, ready }: { slot: CardFieldsSlot; ready: boolean }) {
  useEffect(() => {
    const m = ready ? getMollie() : null;
    if (!m) return;
    const valid: Partial<Record<MollieFieldType, boolean>> = {};
    const mounted: MollieComponent[] = FIELDS.map(({ type, focus }) => {
      const field = m.createComponent(type, { styles: { base: { color: "#F4F4F6", fontSize: "17px" } } });
      field.mount(`#mollie-${type}`);
      field.addEventListener("change", (e) => {
        valid[type] = !!e.dirty && !e.error;
        slot.onChange({ complete: FIELDS.every((f) => valid[f.type]) });
      });
      field.addEventListener("focus", () => slot.onChange({ focus }));
      field.addEventListener("blur", () => slot.onChange({ focus: null }));
      return field;
    });
    return () => mounted.forEach((field) => field.unmount());
  }, [ready, slot]);

  return (
    <>
      {FIELDS.map((f) => (
        <div key={f.type} className="mb-[15px]">
          <span className={slot.labelClassName}>{f.label}</span>
          <div id={`mollie-${f.type}`} className={slot.fieldClassName} />
        </div>
      ))}
    </>
  );
}

// The card waits on this. Mollie has a token now, but nobody has paid: the bank's 3-D Secure step is next,
// on Mollie's page. So go there and leave the promise pending, and the button stays on Paying.
async function pay() {
  const m = getMollie();
  if (!m) throw new Error("The card form is still loading. Try again in a second.");
  const { token, error } = await m.createToken();
  if (error || !token) throw new Error(error?.message ?? "Check the card details and try again.");
  const result = await createCardPayment(token);
  if (!result.ok) throw new Error(result.message);
  window.location.assign(result.checkoutUrl);
  return new Promise<never>(() => {});
}

export default function Checkout() {
  const [ready, setReady] = useState(false);
  return (
    <>
      <Script src="https://js.mollie.com/v1/mollie.js" onReady={() => setReady(true)} />
      <CardCheckout
        amount={24} // the total your server charges, shown on the button
        currency="EUR"
        renderCardFields={(slot) => <MollieFields slot={slot} ready={ready} />}
        onConfirm={pay}
        resetAfter={null}
      />
    </>
  );
}

app/pay/actions.ts

"use server";
import { PaymentMethod } from "@mollie/api-client";
import { mollieClient } from "@/lib/mollie";
import { getOpenOrder, savePaymentId } from "@/lib/orders";

const SITE = process.env.NEXT_PUBLIC_SITE_URL!; // e.g. https://shop.example.com, no trailing slash

type Result = { ok: true; checkoutUrl: string } | { ok: false; message: string };

export async function createCardPayment(cardToken: string): Promise<Result> {
  const order = await getOpenOrder(); // the amount comes from your server, never from the browser
  const returnUrl = `${SITE}/pay/return?order=${order.id}`;
  try {
    const payment = await mollieClient.payments.create({
      method: PaymentMethod.creditcard,
      cardToken, // valid for 1 hour, one payment
      amount: { currency: "EUR", value: order.total }, // a string with two decimals, e.g. "24.00"
      description: `Order ${order.id}`,
      redirectUrl: returnUrl,
      webhookUrl: `${SITE}/api/mollie/webhook`, // must be reachable from the internet, not localhost
      metadata: { orderId: order.id },
    });
    await savePaymentId(order.id, payment.id);
    // _links.checkout: the 3-D Secure step. Mollie leaves it out when the payment needs no extra step.
    return { ok: true, checkoutUrl: payment.getCheckoutUrl() ?? returnUrl };
  } catch {
    return { ok: false, message: "The payment could not be started. Nothing was charged." };
  }
}

lib/mollie-js.ts

// Mollie.js ships as a script tag (https://js.mollie.com/v1/mollie.js) with no npm types,
// so these are the parts this page uses, written from Mollie's Mollie object and Component object docs.
export type MollieFieldType = "cardHolder" | "cardNumber" | "expiryDate" | "verificationCode";

// What Mollie passes to change listeners: the field has input (dirty), was focused once (touched), and an error text.
export type MollieFieldEvent = { dirty?: boolean; touched?: boolean; error?: string };

export interface MollieComponent {
  mount(target: string | HTMLElement): void;
  unmount(): void;
  addEventListener(event: "change" | "focus" | "blur", callback: (event: MollieFieldEvent) => void): void;
}

export interface MollieInstance {
  createComponent(type: MollieFieldType, options?: { styles?: { base?: Record<string, string> } }): MollieComponent;
  createToken(): Promise<{ token?: string; error?: { message: string } }>;
}

declare global {
  interface Window {
    Mollie?: (profileId: string, options?: { locale?: string; testmode?: boolean }) => MollieInstance;
  }
}

lib/mollie.ts

import "server-only";
import createMollieClient from "@mollie/api-client";

// test_... or live_... API key from the same Mollie profile as NEXT_PUBLIC_MOLLIE_PROFILE_ID
export const mollieClient = createMollieClient({ apiKey: process.env.MOLLIE_API_KEY! });

app/pay/return/page.tsx

import { PaymentStatus } from "@mollie/api-client";
import { mollieClient } from "@/lib/mollie";
import { getPaymentId } from "@/lib/orders";

// Mollie sends the buyer back to redirectUrl without a status, so read it from Mollie.
export default async function Return({ searchParams }: { searchParams: Promise<{ order?: string }> }) {
  const { order } = await searchParams;
  const paymentId = order ? await getPaymentId(order) : null;
  if (!paymentId) return <p>We could not find that order.</p>;

  const payment = await mollieClient.payments.get(paymentId);
  if (payment.status === PaymentStatus.paid) return <p>Paid. Thank you, a receipt is on its way.</p>;
  if (payment.status === PaymentStatus.open || payment.status === PaymentStatus.pending)
    return <p>Your bank is still confirming the payment. This page will be right in a minute.</p>;
  return <p>The payment did not go through ({payment.status}). Nothing was charged. Try again.</p>;
}

app/api/mollie/webhook/route.ts

import { PaymentStatus } from "@mollie/api-client";
import { mollieClient } from "@/lib/mollie";
import { markPaid } from "@/lib/orders";

// Mollie posts only id=tr_... (form encoded). Fetch the payment to learn its status: that fetch is the check.
export async function POST(req: Request) {
  const form = await req.formData();
  const id = form.get("id");
  if (typeof id !== "string") return new Response(null, { status: 200 });

  try {
    const payment = await mollieClient.payments.get(id);
    const orderId = (payment.metadata as { orderId?: string } | null)?.orderId;
    if (orderId && payment.status === PaymentStatus.paid) await markPaid(orderId);
  } catch {
    // unknown id: still answer 200, so nobody learns which ids exist
  }
  return new Response(null, { status: 200 });
}

lib/orders.ts

import "server-only";

// Stand-ins for your database. Keep the Mollie payment id next to your order.
type Order = { id: string; total: string; paymentId?: string; paid?: boolean };
const orders = new Map<string, Order>();

export async function getOpenOrder(): Promise<Order> {
  const order = { id: crypto.randomUUID(), total: "24.00" }; // read the cart and its total here
  orders.set(order.id, order);
  return order;
}

export async function savePaymentId(orderId: string, paymentId: string) {
  const order = orders.get(orderId);
  if (order) order.paymentId = paymentId;
}

export async function getPaymentId(orderId: string) {
  return orders.get(orderId)?.paymentId ?? null;
}

export async function markPaid(orderId: string) {
  const order = orders.get(orderId);
  if (order && !order.paid) order.paid = true; // ship once, even if the webhook comes twice
}

Good to know

pay() never resolves after createToken. A card token is not a payment: Mollie creates the payment on your server, and the bank's 3-D Secure step happens on Mollie's page. So the browser goes to payment.getCheckoutUrl() and the promise stays pending, the button keeps saying Paying, and the paid moment belongs on the return page, not on the card.
Mollie needs all four fields mounted before createToken answers, card holder included: Mollie.js returns "Not all required components are mounted yet. Card holder, card number, expiry date, and verification code are required." otherwise. That is why the slot renders Mollie's cardHolder iframe and the two edits below hide the piece's own name input.
What the 3D card shows: the digits stay in Mollie's iframes, so the card face stays blank and shows no brand. Mollie.js reports focus, blur and change for each field, so the card flips when the CVC field gets focus, and Pay unlocks when every field reports dirty with no error.
The amount comes from your server. createCardPayment reads the order and sends Mollie a string with two decimals ("24.00"), never a number from the browser. amount on the card is only what the button shows, so keep it in step.
If createCardPayment fails, pay() throws, the card goes back to idle and shows the message, and nothing was charged because no payment exists. A token is good for one payment and one hour, so the next press makes a new one.
We mounted all four Mollie fields in a local next start build (four iframes from js.mollie.com, no console errors) with a placeholder profile id. We didn't take a token or create a payment against a Mollie account.

The free route: Mollie's hosted checkout from a Server Action

If you don't need a card form on your own page, this is the whole job and it costs nothing beyond Mollie's fees. Leave out method and cardToken, and Mollie's hosted checkout shows every method switched on for your profile: cards, iDEAL, Bancontact and the rest. The same lib/mollie.ts, return page and webhook work with it.
redirect() works by throwing, so it sits outside any try/catch. getCheckoutUrl() returns the _links.checkout URL, which a payment without a method always has, so the non-null assertion is safe here.

app/buy/page.tsx (no paid piece, no client code)

import { redirect } from "next/navigation";
import { mollieClient } from "@/lib/mollie";
import { getOpenOrder, savePaymentId } from "@/lib/orders";

const SITE = process.env.NEXT_PUBLIC_SITE_URL!;

// No card form on your page: Mollie's hosted checkout shows every method on your profile (cards, iDEAL, Bancontact...).
async function checkout() {
  "use server";
  const order = await getOpenOrder();
  const payment = await mollieClient.payments.create({
    amount: { currency: "EUR", value: order.total },
    description: `Order ${order.id}`,
    redirectUrl: `${SITE}/pay/return?order=${order.id}`,
    webhookUrl: `${SITE}/api/mollie/webhook`,
    metadata: { orderId: order.id },
  });
  await savePaymentId(order.id, payment.id);
  redirect(payment.getCheckoutUrl()!); // outside any try/catch: redirect() works by throwing
}

export default function Buy() {
  return (
    <form action={checkout}>
      <button type="submit">Pay with Mollie</button>
    </form>
  );
}

Two edits to the card for Mollie's name field

Stripe and Adyen let you leave the name to your own input. Mollie doesn't: createToken refuses to run until a cardHolder component is mounted. So the slot renders Mollie's four fields, and in your copy of CardCheckout.tsx the built-in name input steps aside in hosted mode. Without these edits the buyer sees two name fields, and Pay waits on the one Mollie ignores.
What you give up: the name no longer appears on the 3D card face, because it is typed inside Mollie's iframe too. The tilt, the flip on the CVC field and the paid animation are unchanged.

components/CardCheckout.tsx (two edits)

// components/CardCheckout.tsx, two edits in your copy. Mollie's cardHolder field replaces the built-in name input.

// 1. Pay no longer waits on the built-in name input in hosted mode:
const valid = hostedMode ? hosted.complete : okNum && okExp && okCvc && okName;

// 2. Wrap the built-in "Cardholder name" block so it only shows without renderCardFields:
{!hostedMode && (
  <div className="mb-[15px]">
    <label htmlFor="qcc-name" className={label}>
      Cardholder name
    </label>
    {/* ...the input stays as it is... */}
  </div>
)}

Mollie webhooks in Next.js: what arrives and what to check

Mollie's webhook carries no status and no signature for payments: it posts one form field, id=tr_..., and expects you to fetch the payment. That fetch with your API key is the check, so the route reads req.formData(), calls payments.get and ships only on status paid. Mollie's docs recommend answering 200 even for an id you don't know, so the route does.
Mollie times a call out after 15 seconds and retries a failed one 10 times over about a day, so keep the handler quick and make markPaid safe to run twice. The webhook URL has to be reachable from Mollie: Mollie doesn't accept localhost, so use a tunnel such as ngrok while you develop.

Mollie Components not working? Check these

createToken returns "Not all required components are mounted yet". All four fields have to be mounted: cardHolder, cardNumber, expiryDate and verificationCode. The single card component is the other option; it draws all four in one box with Mollie's own labels.
The profile id is not the API key. The browser gets the pfl_... profile id; the test_ or live_ key stays on the server in MOLLIE_API_KEY. Both must belong to the same profile, and testmode in the browser has to match a test_ key.
TypeScript rejects method: "creditcard". In @mollie/api-client 4.6.0 method is the PaymentMethod enum, so import it and write PaymentMethod.creditcard. Amounts are strings with two decimals: value: 24 fails to type-check, value: "24.00" is right.
The fields mount twice or vanish. Mount once per field and unmount in the effect cleanup, as MollieFields does. Mollie warns in the console when a mounted field leaves the DOM without unmount().
Test cards and failures: initialise Mollie with testmode: true and a test_ key. Mollie's testing docs trigger declines with magic amounts, and a failed payment carries details.failureReason and a translated details.failureMessage you can show.

Adyen Custom Card fields in the same 3D card

Install

Copy from the zipPut react/src/components into src/, then npm i framer-motion @mollie/api-client server-only.
Or ask your AIPaste PROMPT.md into Cursor, Lovable or v0.

Props

renderCardFields: Mollie's four fields inside the design
onConfirm: createToken, create the payment on the server, go to Mollie's checkout URL; throw to show the error
amount / currency: what the card shows (your server sets what Mollie charges)
resetAfter: null: the page leaves for 3-D Secure

How qodesign compares

qodesign vs 21st.dev21st.dev is best for: browsing a huge marketplace and copying many components a month.
qodesign vs Skiper UISkiper UI is best for: unusual interaction details for landing pages: image reveals, cursor trails, tooltips, drag-and-scroll galleries.

All comparisons, with prices read on each library's own site.

From the blog: Stripe Elements With a Custom Card Design in React and Next.js

Questions

Does Mollie have a React package?

Not for the card fields. Mollie.js is a script tag (https://js.mollie.com/v1/mollie.js) with no npm types, so this page loads it with next/script and types the parts it uses. The server side is the official @mollie/api-client package.

Do I need Mollie Components to take payments in Next.js?

No. Create a payment without method and cardToken and send the buyer to getCheckoutUrl(): Mollie's hosted checkout handles cards, iDEAL and the rest. Components are for a card form on your own page.

Why does the card show no brand?

Mollie.js doesn't report the card brand to your page, only focus, blur and change with dirty, touched and error. The card still flips for the CVC and unlocks Pay when every field is valid.

Does this work with Next.js 15 and React 19?

Every snippet here type-checks and builds with Next.js 15.5.28, React 19.1.1, TypeScript 5.9.3 and @mollie/api-client 4.6.0. We didn't run a payment against a Mollie account.

Can Cursor or v0 add it for me?

Yes. Each download has a PROMPT.md. Paste it into Cursor, Lovable, v0 or Claude Code and it fits the piece into your app.

Can I use it in client work?

Yes, in personal and client projects. You can't resell the code itself as a kit.