Adyen Drop-in in the Next.js App Router: sessions flow, return page and webhooks, then a receipt checkout around it

Adyen's Drop-in is one component that shows every payment method you turned on, cards, wallets and local methods, and runs 3D Secure and redirects for you. Here it is in a Next.js App Router app with the sessions flow from @adyen/adyen-web 6: a Server Action creates the session with @adyen/api-library, Drop-in mounts in a client component, onPaymentCompleted and onPaymentFailed report the result, a return page finishes redirect payments, and a route handler checks each webhook's HMAC signature. The plain Drop-in with Adyen's own Pay button is free and shown in full. Then the same Drop-in goes inside a checkout card that turns into a stamped receipt when the payment is authorised.

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

Adyen Drop-in inside Receipt Morph Checkout, in the App Router

app/pay/checkout.tsx

"use client";
import { useEffect, useRef } from "react";
import { useRouter } from "next/navigation";
import { AdyenCheckout, Card, Dropin, GooglePay, PayPal, type ResultCode } from "@adyen/adyen-web";
import "@adyen/adyen-web/styles/adyen.css";
import "./adyen-theme.css"; // after Adyen's css, so its variables win
import { CheckoutReceiptMorph, type CardFieldsSlot, type PayResult } from "@/components/CheckoutReceiptMorph";
import { createAdyenSession } from "./actions";

type Outcome = { resultCode: ResultCode; sessionId: string; sessionResult?: string };
type Controller = { dropin: Dropin | null; settle: ((o: Outcome) => void) | null };

// Mounts Adyen's Drop-in where the receipt card would show its own number, expiry and CVC inputs.
function DropinField({ slot, ctl }: { slot: CardFieldsSlot; ctl: React.RefObject<Controller> }) {
  const node = useRef<HTMLDivElement>(null);
  const slotRef = useRef(slot);
  slotRef.current = slot;

  useEffect(() => {
    let dropin: Dropin | null = null;
    let cancelled = false;

    (async () => {
      const session = await createAdyenSession();
      if (cancelled || !node.current) return;

      // Every payment-method result lands in these two callbacks, so the Pay button can await them.
      const done = (resultCode: ResultCode, sessionResult?: string) =>
        ctl.current.settle?.({ resultCode, sessionId: session.id, sessionResult });

      const checkout = await AdyenCheckout({
        session,
        clientKey: process.env.NEXT_PUBLIC_ADYEN_CLIENT_KEY!,
        environment: "test", // "live" (or "live-us", "live-au"...) in production
        countryCode: "US",
        locale: "en-US",
        // Drop-in asks every method for its state; isValid tells the receipt card whether Pay can go.
        onChange: (state) => slotRef.current.onChange({ complete: state.isValid }),
        onPaymentCompleted: (result) => done(result.resultCode, "sessionResult" in result ? result.sessionResult : undefined),
        onPaymentFailed: (result) => done(result?.resultCode ?? "Error", result && "sessionResult" in result ? result.sessionResult : undefined),
        onError: (error) => console.error(error.name, error.message),
      });
      if (cancelled) return;

      dropin = new Dropin(checkout, {
        paymentMethodComponents: [Card, PayPal, GooglePay], // only these are bundled; @adyen/adyen-web/auto has them all
        showPayButton: false, // the receipt card's Pay button submits instead
        disableFinalAnimation: true, // the receipt plays instead of Drop-in's tick
        paymentMethodsConfiguration: {
          card: {
            hasHolderName: false, // the receipt card already asks for the name
            // The number, expiry and CVC sit in Adyen's iframes: CSS can't reach them, this can.
            styles: { base: { color: "#F4F4F6", fontSize: "16px" }, placeholder: { color: "#6B6F80" }, error: { color: "#FF5C6C" } },
            onBrand: (b) => slotRef.current.onChange({ brand: b.brand }),
            onFocus: (f) => {
              // The receipt card flips while the CVC field has focus.
              if ("focus" in f && f.fieldType === "encryptedSecurityCode") slotRef.current.onChange({ focus: f.focus ? "cvc" : null });
            },
          },
        },
      }).mount(node.current);
      ctl.current.dropin = dropin;
    })().catch((e) => console.error(e));

    return () => {
      cancelled = true;
      dropin?.unmount();
      ctl.current.dropin = null;
    };
  }, [ctl]);

  return <div ref={node} className="adyen-dark" />;
}

export default function AdyenCheckoutPage() {
  const router = useRouter();
  const ctl = useRef<Controller>({ dropin: null, settle: null });

  const confirm = (): Promise<PayResult> =>
    new Promise<Outcome>((resolve, reject) => {
      const dropin = ctl.current.dropin;
      if (!dropin) return reject(new Error("The payment form hasn't loaded yet."));
      ctl.current.settle = resolve;
      // Cards and wallets resolve here. Redirect methods leave the page and finish on /pay/return.
      dropin.submit();
    }).then((o) => {
      ctl.current.settle = null;
      const done = `/pay/done?sessionId=${encodeURIComponent(o.sessionId)}&sessionResult=${encodeURIComponent(o.sessionResult ?? "")}`;
      if (o.resultCode === "Authorised") {
        setTimeout(() => router.push(done), 2600); // let the receipt print first
        return { ok: true };
      }
      if (o.resultCode === "Received" || o.resultCode === "Pending") {
        router.push(done); // not paid yet: no PAID stamp, the done page explains
        return new Promise<PayResult>(() => {});
      }
      return { ok: false, message: o.resultCode === "Refused" ? "The bank refused it. Nothing was charged." : "That didn't go through. Try again." };
    });

  return <CheckoutReceiptMorph renderCardFields={(slot) => <DropinField slot={slot} ctl={ctl} />} onConfirm={confirm} />;
}

app/pay/actions.ts (Server Action: create the session)

"use server";
import { randomUUID } from "node:crypto";
import { checkout } from "@/lib/adyen";
import { ORDER } from "@/lib/order";

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

// Called when the checkout mounts. Returns only what the browser needs: the session id and sessionData.
// The amount comes from the server, never from the browser: a Server Action is a public endpoint.
export async function createAdyenSession(): Promise<{ id: string; sessionData: string }> {
  const reference = `order-${randomUUID()}`;
  const session = await checkout.PaymentsApi.sessions(
    {
      merchantAccount: process.env.ADYEN_MERCHANT_ACCOUNT!,
      amount: ORDER.amount,
      countryCode: ORDER.countryCode,
      reference,
      // Redirect methods (iDEAL, Klarna, some 3D Secure flows) come back here.
      returnUrl: `${SITE}/pay/return`,
    },
    { idempotencyKey: reference }
  );
  if (!session.sessionData) throw new Error("Adyen sent no sessionData");
  return { id: session.id, sessionData: session.sessionData };
}

lib/adyen.ts and lib/order.ts (server)

// lib/adyen.ts
import "server-only";
import { CheckoutAPI, Client, EnvironmentEnum } from "@adyen/api-library";

// The API key stays on the server. server-only fails the build if a client file imports this.
// Going live: EnvironmentEnum.LIVE plus liveEndpointUrlPrefix (your prefix from the Customer Area).
const client = new Client({ apiKey: process.env.ADYEN_API_KEY!, environment: EnvironmentEnum.TEST });

export const checkout = new CheckoutAPI(client);

// lib/order.ts
import { NW } from "@/data/northwind";

// What the receipt shows and what Adyen charges come from the same data. Adyen wants minor units.
export const ORDER = {
  amount: { currency: "USD", value: Math.round(NW.store.total * 100) },
  countryCode: "US",
};

app/pay/page.tsx

import AdyenCheckoutPage from "./checkout";

// No session on page load from the server: the client creates it when the form mounts.
export default function PayPage() {
  return <AdyenCheckoutPage />;
}

app/pay/adyen-theme.css

/* Drop-in outside its iframes reads these variables. Scoped to the wrapper, not :root. */
.adyen-dark {
  --adyen-sdk-color-background-primary: #0d0e13;
  --adyen-sdk-color-background-secondary: #15171f;
  --adyen-sdk-color-label-primary: #f4f4f6;
  --adyen-sdk-color-label-secondary: #a3a6b4;
  --adyen-sdk-color-outline-primary: #2a2e3b;
  --adyen-sdk-color-outline-primary-active: #c6ff3d;
  --adyen-sdk-border-radius-m: 14px;
}

app/pay/done/page.tsx (asks Adyen for the result)

import Link from "next/link";
import { checkout } from "@/lib/adyen";

const MESSAGES: Record<string, string> = {
  completed: "Paid. Thank you!",
  paymentPending: "Your payment is processing. We'll email you when it clears.",
  refused: "The payment was refused. Nothing was charged.",
  canceled: "The payment was cancelled.",
  expired: "The checkout timed out. Start again.",
  active: "The payment isn't finished yet.",
};

// Ask Adyen for the result. The query string alone proves nothing. Fulfil from the webhook, not here.
export default async function Done({ searchParams }: { searchParams: Promise<{ sessionId?: string; sessionResult?: string }> }) {
  const { sessionId, sessionResult } = await searchParams;
  if (!sessionId || !sessionResult) return <p className="p-8">No payment found.</p>;

  const result = await checkout.PaymentsApi.getResultOfPaymentSession(sessionId, sessionResult);
  const status = result.status ?? "active";
  return (
    <main className="mx-auto max-w-md p-8">
      <h1 className="text-2xl font-semibold">{MESSAGES[status] ?? "Something went wrong."}</h1>
      {status !== "completed" && status !== "paymentPending" && (
        <Link href="/pay" className="mt-6 inline-block underline">Back to checkout</Link>
      )}
    </main>
  );
}

lib/orders.ts

import "server-only";

// Your database call. Adyen can send the same notification more than once: make this idempotent on pspReference.
export async function fulfillOrder(merchantReference: string, pspReference: string) {
  console.log("fulfil", merchantReference, pspReference);
}

Good to know

Drop-in is Adyen's own UI. It draws the payment method list, the card form, the wallet buttons and the 3D Secure challenge. Receipt Morph Checkout wraps it: the order summary, the live card beside the form, the name field, its own Pay button and the receipt animation are ours. We don't restyle Adyen's card fields beyond what Adyen's styles option and CSS variables allow.
showPayButton: false hides Drop-in's button, and the receipt card's Pay button calls dropin.submit() instead. The result still arrives in onPaymentCompleted or onPaymentFailed, so confirm wraps both in one promise and the card's arc spins until Adyen answers.
The receipt only prints for resultCode Authorised. Received and Pending (some bank and voucher methods) go straight to the done page without a PAID stamp, and Refused drops the card back with a message. Methods that redirect (many local bank methods, and 3D Secure when the bank uses a redirect) leave the page: their receipt never plays, and the buyer finishes on /pay/return.
The live card follows the card method only. onBrand puts the brand on the card and CVC focus flips it. When the buyer picks PayPal or Google Pay in Drop-in, the card stays blank. If you only want cards, add allowedPaymentMethods: ["scheme"] to the session request.
The receipt shows a last4 only if onConfirm returns one, and the sessions flow doesn't give the browser the card's last4, so this setup leaves it empty. The amount the receipt prints and the amount Adyen charges both come from data/northwind.ts through lib/order.ts, so they can't drift apart. Edit that file, not the browser.
React's dev mode mounts effects twice. The cleanup unmounts the first Drop-in, but createAdyenSession still runs twice in development. That only makes an extra session in your test account; production mounts once.

The free route: Drop-in with Adyen's own Pay button

If you don't need a designed checkout, this is the whole client side. It uses the same createAdyenSession Server Action and done page as above, and Drop-in keeps its own Pay button and its own success tick.
Adyen Web 6 is split per payment method: Drop-in only shows a method if you pass its class in paymentMethodComponents and the method is turned on for your merchant account. Importing from @adyen/adyen-web/auto instead registers every method, at the cost of a bigger bundle. The stylesheet comes from @adyen/adyen-web/styles/adyen.css, which Next.js lets a client component import straight from node_modules.

app/plain/drop-in.tsx (no paid piece)

"use client";
import { useEffect, useRef } from "react";
import { useRouter } from "next/navigation";
import { AdyenCheckout, Card, Dropin, GooglePay, PayPal } from "@adyen/adyen-web";
import "@adyen/adyen-web/styles/adyen.css";
import { createAdyenSession } from "../pay/actions";

// The free route: Adyen's whole Drop-in with its own Pay button. No paid piece.
export default function PlainDropin() {
  const node = useRef<HTMLDivElement>(null);
  const router = useRouter();

  useEffect(() => {
    let dropin: Dropin | null = null;
    let cancelled = false;

    (async () => {
      const session = await createAdyenSession();
      if (cancelled || !node.current) return;
      const toDone = (sessionResult?: string) =>
        router.push(`/pay/done?sessionId=${encodeURIComponent(session.id)}&sessionResult=${encodeURIComponent(sessionResult ?? "")}`);

      const checkout = await AdyenCheckout({
        session,
        clientKey: process.env.NEXT_PUBLIC_ADYEN_CLIENT_KEY!,
        environment: "test",
        countryCode: "US",
        onPaymentCompleted: (result) => toDone("sessionResult" in result ? result.sessionResult : undefined),
        onPaymentFailed: (result) => toDone(result && "sessionResult" in result ? result.sessionResult : undefined),
        onError: (error) => console.error(error.name, error.message),
      });
      if (cancelled) return;
      dropin = new Dropin(checkout, { paymentMethodComponents: [Card, PayPal, GooglePay] }).mount(node.current);
    })().catch((e) => console.error(e));

    return () => {
      cancelled = true; // React's dev double mount: the first run stops here
      dropin?.unmount();
    };
  }, [router]);

  return <div ref={node} className="mx-auto max-w-md p-6" />;
}

What Drop-in renders, and what Receipt Morph Checkout wraps

Receipt Morph Checkout has a renderCardFields slot for a provider's hosted fields. Here the slot holds the whole Drop-in, mounted into a div, in the place where the piece's own number, expiry and CVC inputs would be. Card digits stay in Adyen's iframes; the component never sees them.
Adyen's onChange gives each method's isValid, which tells the piece when Pay can go. The card method's onBrand and onFocus drive the live card. disableFinalAnimation: true turns off Drop-in's own tick so the receipt is the only success moment.
What the piece doesn't do: it doesn't change which methods Adyen shows or how they look inside Adyen's iframes, it doesn't run without Adyen's script, and it doesn't fulfil orders. That stays in the webhook below. It also isn't a shadcn component; you copy its files from the zip.

Coming back from a redirect: redirectResult and sessionResult

Some methods leave your site. When they finish, Adyen sends the buyer to the returnUrl from the session request with sessionId and redirectResult added to the query string. The return page passes redirectResult back into the same session with checkout.submitDetails, and Adyen answers through onPaymentCompleted or onPaymentFailed, exactly like an on-page payment.
Both paths end on /pay/done with the sessionId and the sessionResult from the callback. That page calls PaymentsApi.getResultOfPaymentSession(sessionId, sessionResult) on the server, so the status it shows (completed, paymentPending, refused, canceled, expired) comes from Adyen, not from the URL.
A redirectResult works once, so the return page guards against React running the effect twice. Keep personal data out of returnUrl: Adyen's API reference says it must not include it.

app/pay/return/page.tsx

import { redirect } from "next/navigation";
import FinishRedirect from "./finish-redirect";

// Redirect methods come back to returnUrl with ?sessionId=...&redirectResult=...
export default async function ReturnPage({
  searchParams,
}: {
  searchParams: Promise<{ sessionId?: string; redirectResult?: string }>;
}) {
  const { sessionId, redirectResult } = await searchParams;
  if (!sessionId || !redirectResult) redirect("/pay");
  return <FinishRedirect sessionId={sessionId} redirectResult={redirectResult} />;
}

app/pay/return/finish-redirect.tsx

"use client";
import { useEffect, useRef } from "react";
import { useRouter } from "next/navigation";
import { AdyenCheckout } from "@adyen/adyen-web";

// Hands redirectResult back to the same session. Adyen answers through onPaymentCompleted / onPaymentFailed.
export default function FinishRedirect({ sessionId, redirectResult }: { sessionId: string; redirectResult: string }) {
  const router = useRouter();
  const sent = useRef(false);

  useEffect(() => {
    if (sent.current) return; // React dev mode runs effects twice; a redirectResult works once
    sent.current = true;
    const toDone = (sessionResult?: string) =>
      router.replace(`/pay/done?sessionId=${encodeURIComponent(sessionId)}&sessionResult=${encodeURIComponent(sessionResult ?? "")}`);

    AdyenCheckout({
      session: { id: sessionId }, // no sessionData needed on the way back
      clientKey: process.env.NEXT_PUBLIC_ADYEN_CLIENT_KEY!,
      environment: "test",
      countryCode: "US",
      onPaymentCompleted: (r) => toDone("sessionResult" in r ? r.sessionResult : undefined),
      onPaymentFailed: (r) => toDone(r && "sessionResult" in r ? r.sessionResult : undefined),
      onError: () => router.replace("/pay?error=1"),
    }).then((checkout) => checkout.submitDetails({ details: { redirectResult } }));
  }, [router, sessionId, redirectResult]);

  return <main className="grid min-h-dvh place-items-center text-neutral-400">Finishing your payment...</main>;
}

Adyen webhooks in a route handler: check the HMAC signature

The done page is for the buyer. Record the order from the AUTHORISATION webhook, because the buyer can close the tab before any page loads. Adyen sends a batch of notification items, each with its own hmacSignature in additionalData, and hmacValidator.validateHMAC(item, key) checks it with the HMAC key you generate for the webhook in your Customer Area.
success arrives as the string "true" or "false", not a boolean. Answer quickly with a 2xx so Adyen doesn't retry, and make fulfilment idempotent on pspReference because the same notification can come twice.
We ran this route locally: a notification signed with a test key answered 202 [accepted] and called fulfillOrder, and the same body with the amount changed answered 401.

app/api/adyen/webhook/route.ts

import { hmacValidator, type Types } from "@adyen/api-library";
import { fulfillOrder } from "@/lib/orders";

const validator = new hmacValidator();

// Adyen posts a batch of notification items. Check each item's HMAC signature before you trust it.
export async function POST(req: Request) {
  const body = (await req.json()) as Types.notification.Notification;

  for (const { NotificationRequestItem: item } of body.notificationItems ?? []) {
    if (!validator.validateHMAC(item, process.env.ADYEN_HMAC_KEY!)) {
      return new Response("invalid HMAC signature", { status: 401 });
    }
    // success arrives as the string "true" or "false".
    if (item.eventCode === "AUTHORISATION" && item.success === "true") {
      await fulfillOrder(item.merchantReference, item.pspReference);
    }
  }
  // Acknowledge quickly; Adyen retries webhooks it doesn't see accepted.
  return new Response("[accepted]", { status: 202 });
}

Styling Adyen Drop-in

Two layers. Everything outside the iframes (the method list, labels, borders, buttons) reads --adyen-sdk-* CSS variables, which adyen-theme.css above sets on the Drop-in's wrapper instead of :root so the rest of your app is untouched. The card number, expiry and CVC sit in Adyen's iframes, where CSS can't reach; the card method's styles option (base, placeholder, error) sets their text.
Import your overrides after Adyen's stylesheet so they win. We type-checked and built this but didn't look at it against a live Adyen test account.

Adyen Drop-in not working? Check these

Nothing renders and the console shows a client key error. The client key only works on origins you add to its allowed origins in the Customer Area, and a test key needs environment: "test".
A payment method you enabled doesn't show. In Adyen Web 6 it also has to be in paymentMethodComponents (or use the auto import), and it has to be available for the session's country and currency.
The session fails later. Sessions expire 1 hour after creation unless you set expiresAt, and never later than 24 hours. Create a fresh one when the checkout mounts, as this page does.
The webhook always answers 401. Use the HMAC key of that exact webhook, and pass the NotificationRequestItem as Adyen sent it, without changing values.

Adyen Custom Card component in React

Scope the receipt checkout's CSS before it goes into a shadcn app

checkout-receipt-morph.css ships as a full-page stylesheet: it sets variables on :root, styles html and body, and resets every button, input, h1 and h2. In a shadcn or other Tailwind UI kit app that reaches past the checkout.
The receipt checkout guide has the measured fix: wrap the file in @scope (.qd-rcpt), swap :root and html,body for :scope, add one preflight rule and a qd-rcpt div around the component. The Adyen wiring above stays the same. Adyen's own stylesheet is separate and isn't affected.

Checkout animation for React + Tailwind (card to receipt)

Install

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

Props

renderCardFields: slot for Adyen Drop-in; card digits never reach the component
onConfirm: dropin.submit(), wait for onPaymentCompleted or onPaymentFailed, return ok or a message
order: the order the receipt prints (items, total); the same data sets the session amount
onComplete: gets the receipt: orderId, total, last4 (empty here), paidAt

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

Drop-in or Custom Card for Adyen in React?

Drop-in if you want every enabled method (wallets, local methods) with the least code. It renders Adyen's own UI. Custom Card if you only take cards and want your own field layout; the Custom Card guide puts those fields in a 3D card.

Sessions flow or advanced flow?

The sessions flow is one server call (/sessions) and Adyen Web handles the rest, which is what this page uses. The advanced flow calls /paymentMethods, /payments and /payments/details yourself through onSubmit and onAdditionalDetails, for when you need to change the payment on each step.

Can I hide Drop-in's Pay button and use my own?

Yes. Set showPayButton: false and call dropin.submit() from your button. The result still comes back in onPaymentCompleted or onPaymentFailed.

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, @adyen/adyen-web 6.47.0 and @adyen/api-library 32.2.0. We ran the webhook route locally with a signed test notification. We didn't run a payment against an Adyen 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.