How to Integrate Adyen with V0

Open V0 and describe the checkout experience you want to build. Adyen's Drop-in will occupy a specific container div in your layout — the rest of the page (order summary, product details, trust badges, progress indicators) is entirely up to you and is what V0 excels at generating. Think about your checkout flow: do you want a single-page checkout where everything is visible at once, or a multi-step flow (cart → shipping → payment → confirmation)? Single-page is simpler to build and converts well for low-complexity purchases. For the payment step, all you need is a container element — a div with a specific ID — where the Adyen SDK will inject its own HTML. Ask V0 to generate a realistic-looking checkout page with hardcoded placeholder data so you can see how the full page looks. Include an order summary with item names, quantities, and prices, plus a right column or bottom section reserved for the payment form. Also ask V0 to generate the post-payment confirmation page that users land on after a successful payment — this page reads the payment result from URL query parameters that Adyen appends on redirect. Use V0's Design Mode to polish typography, colors, and spacing so the page matches your brand before adding any payment logic.

Install two packages: @adyen/adyen-web for the browser-side Drop-in UI, and @adyen/api-library for making server-side calls to the Adyen API from your Next.js API routes. The @adyen/adyen-web package is a client-side library — it gets imported in your React component and mounts the payment form UI into the container div. It communicates directly with Adyen's checkout shopper endpoints (checkoutshopper-live.adyen.com or checkoutshopper-test.adyen.com) from the browser, so you do not need to proxy every payment interaction through your API. The @adyen/api-library package is used exclusively in your Next.js API routes for server-side operations: creating sessions, refunding payments, retrieving payment details, and managing stored payment methods. This separation is important for security — your Adyen API key only ever appears in server-side code. Add both to your package.json and import @adyen/adyen-web CSS in your global stylesheet or layout. The Adyen Web SDK also requires importing its CSS file (node_modules/@adyen/adyen-web/dist/adyen.css) to render correctly — without it the form will be unstyled.

1// lib/adyen.ts
2import { Client, Config, CheckoutAPI } from '@adyen/api-library';
3
4const config = new Config();
5config.apiKey = process.env.ADYEN_API_KEY ?? '';
6config.environment = (process.env.ADYEN_ENVIRONMENT as 'TEST' | 'LIVE') ?? 'TEST';
7
8const client = new Client({ config });
9
10export const checkout = new CheckoutAPI(client);
11export const MERCHANT_ACCOUNT = process.env.ADYEN_MERCHANT_ACCOUNT ?? '';

Build the Next.js API route at app/api/adyen/session/route.ts that your checkout page calls to create a payment session. This is the only Adyen API call that goes through your server — once the session is created, the browser talks to Adyen directly. The session endpoint requires your merchant account, the payment amount (in the smallest currency unit — cents for USD/EUR, pence for GBP), the currency code, a return URL where Adyen redirects after payment (for 3D Secure redirects), and a reference string (your order ID). Optionally include the shopper's email and name for fraud scoring. The session response contains a sessionId and sessionData — both are required by the browser-side SDK. The return URL should point to your confirmation page (e.g., https://your-app.vercel.app/checkout/confirmation) because some payment methods like bank transfers and 3DS2 redirect users away from your site and back. In test mode, use an amount like 1000 (meaning $10.00) and the 'TEST' environment. Adyen's test environment is completely separate from live — test API keys only work against test URLs and do not process real charges. The route should also accept the cart details from the request body so you can pass the real order total dynamically.

1// app/api/adyen/session/route.ts
2import { NextRequest, NextResponse } from 'next/server';
3import { checkout, MERCHANT_ACCOUNT } from '@/lib/adyen';
4import type { CreateCheckoutSessionRequest } from '@adyen/api-library/lib/src/typings/checkout/createCheckoutSessionRequest';
5
6export async function POST(req: NextRequest) {
7  try {
8    const { amount, currency, reference, returnUrl } = await req.json();
9
10    if (!amount || !currency || !reference || !returnUrl) {
11      return NextResponse.json(
12        { error: 'amount, currency, reference, and returnUrl are required' },
13        { status: 400 }
14      );
15    }
16
17    const request: CreateCheckoutSessionRequest = {
18      merchantAccount: MERCHANT_ACCOUNT,
19      amount: { value: amount, currency },
20      reference,
21      returnUrl,
22      channel: 'Web',
23      shopperInteraction: 'Ecommerce',
24    };
25
26    const response = await checkout.PaymentsApi.sessions(request);
27
28    return NextResponse.json({
29      sessionId: response.id,
30      sessionData: response.sessionData,
31    });
32  } catch (error) {
33    console.error('Adyen session error:', error);
34    return NextResponse.json(
35      { error: 'Failed to create payment session' },
36      { status: 500 }
37    );
38  }
39}

Now wire the checkout page component to fetch a session from your API route and mount the Adyen Drop-in. The Drop-in must be initialized client-side — import AdyenCheckout from @adyen/adyen-web inside a useEffect hook (not at the top level) to avoid SSR issues, since the Adyen SDK accesses browser APIs like window and document. Alternatively, use Next.js's dynamic import with { ssr: false } to lazy-load the Adyen module. The initialization flow is: (1) fetch the session from /api/adyen/session on component mount, (2) initialize AdyenCheckout with the session data, client key, and environment, (3) create a Drop-in instance from the checkout object, (4) mount the Drop-in into the container div using its ID or a ref. The Drop-in accepts onPaymentCompleted and onError callback functions. The onPaymentCompleted callback fires when the payment is authorized — it receives a result object with a resultCode like 'Authorised', 'Refused', or 'Pending'. On 'Authorised', redirect the user to your confirmation page. The client key (NEXT_PUBLIC_ADYEN_CLIENT_KEY) is different from your API key — it is a public credential used by the browser SDK to identify your merchant account on Adyen's CDN, and it is safe to expose as a NEXT_PUBLIC_ variable.

1'use client';
2
3import { useEffect, useState, useRef } from 'react';
4import { useRouter } from 'next/navigation';
5
6const ADYEN_ENV = process.env.NEXT_PUBLIC_ADYEN_ENVIRONMENT ?? 'test';
7const ADYEN_CLIENT_KEY = process.env.NEXT_PUBLIC_ADYEN_CLIENT_KEY ?? '';
8
9export default function CheckoutPage() {
10  const router = useRouter();
11  const dropinRef = useRef<HTMLDivElement>(null);
12  const [sessionLoading, setSessionLoading] = useState(true);
13  const [error, setError] = useState<string | null>(null);
14
15  useEffect(() => {
16    let dropin: { unmount: () => void } | null = null;
17
18    async function initAdyen() {
19      try {
20        // 1. Create session
21        const res = await fetch('/api/adyen/session', {
22          method: 'POST',
23          headers: { 'Content-Type': 'application/json' },
24          body: JSON.stringify({
25            amount: 1000,
26            currency: 'USD',
27            reference: crypto.randomUUID(),
28            returnUrl: `${window.location.origin}/checkout/confirmation`,
29          }),
30        });
31        const { sessionId, sessionData } = await res.json();
32        setSessionLoading(false);
33
34        // 2. Init Adyen Checkout
35        const { default: AdyenCheckout } = await import('@adyen/adyen-web');
36        const checkout = await AdyenCheckout({
37          environment: ADYEN_ENV,
38          clientKey: ADYEN_CLIENT_KEY,
39          session: { id: sessionId, sessionData },
40          onPaymentCompleted(result: { resultCode: string }) {
41            router.push(`/checkout/confirmation?resultCode=${result.resultCode}`);
42          },
43          onError(error: Error) {
44            console.error('Adyen error:', error);
45            setError('Payment failed. Please try again.');
46          },
47        });
48
49        // 3. Mount Drop-in
50        if (dropinRef.current) {
51          dropin = checkout.create('dropin').mount(dropinRef.current);
52        }
53      } catch (err) {
54        setError('Failed to load payment form. Please refresh the page.');
55        setSessionLoading(false);
56      }
57    }
58
59    initAdyen();
60    return () => dropin?.unmount();
61  }, [router]);
62
63  return (
64    <div className="max-w-2xl mx-auto p-6">
65      <h1 className="text-2xl font-bold mb-6">Checkout</h1>
66      {error && <p className="text-red-600 mb-4">{error}</p>}
67      {sessionLoading && <div className="h-48 bg-gray-100 rounded-lg animate-pulse" />}
68      <div ref={dropinRef} id="adyen-dropin-container" />
69    </div>
70  );
71}

Configure all Adyen environment variables in your Vercel project before deploying. Open Vercel → your project → Settings → Environment Variables and add the following variables. ADYEN_API_KEY is your secret key from Customer Area → Developers → API credentials — this must never have the NEXT_PUBLIC_ prefix, as it is a server-side secret. ADYEN_MERCHANT_ACCOUNT is your merchant account name (found in the top-left of your Customer Area dashboard). ADYEN_ENVIRONMENT is the string 'TEST' for test mode or 'LIVE' for production — the @adyen/api-library uses this to route requests to the correct API endpoint. NEXT_PUBLIC_ADYEN_CLIENT_KEY is your client key from API credentials — it uses the NEXT_PUBLIC_ prefix because the browser SDK needs it to communicate with Adyen's CDN. NEXT_PUBLIC_ADYEN_ENVIRONMENT is the lowercase version ('test' or 'live') used by the browser SDK, which has different casing requirements from the server-side library. When you are ready to go live, change both environment variables from TEST/test to LIVE/live and obtain a live API key — live API keys are only issued after your Adyen account team reviews and activates your account. For enterprise payment flows involving marketplace splits, recurring billing, or advanced fraud rules, RapidDev's team can help configure the full Adyen integration including webhook handling and payment result processing.

1# .env.local (development — never commit this file)
2# Server-side only (no NEXT_PUBLIC_ prefix)
3ADYEN_API_KEY=AQE...your-test-api-key
4ADYEN_MERCHANT_ACCOUNT=YourMerchantAccountName
5ADYEN_ENVIRONMENT=TEST
6
7# Client-side (NEXT_PUBLIC_ prefix required)
8NEXT_PUBLIC_ADYEN_CLIENT_KEY=test_...your-client-key
9NEXT_PUBLIC_ADYEN_ENVIRONMENT=test