{
  "compilerOptions": {
    "target": "ES2017",
    "module": "commonjs",
    "esModuleInterop": true,
    "resolveJsonModule": true,
    "strict": true,
    "baseUrl": ".",
    "paths": {
      "@adyen/source/*": ["src/adyen/*"]
    }
  }
}

3. Set required environment variables (do not hard-code credentials):

ADYEN_API_KEY=AQExxxxxxxxxxxxx
ADYEN_MERCHANT_ACCOUNT=YourMerchantAccount
ADYEN_ENVIRONMENT=TEST   # or LIVE
ADYEN_HMAC_KEY=your_hmac_key_for_webhooks

4. Instantiate Config and Client once, then share the Client instance across your service layer.

5. If you use a proxy, HttpURLConnectionClient accepts https-proxy-agent compatible agents via Config.httpsAgent.

Public API

Client

import Client from "./src/adyen/client";
import Config, { EnvironmentEnum } from "./src/adyen/config";

const config = new Config();
config.apiKey = process.env.ADYEN_API_KEY!;
config.environment = EnvironmentEnum.TEST;
config.merchantAccount = process.env.ADYEN_MERCHANT_ACCOUNT!;

const client = new Client({ config });

Client is the single entry point for all API calls. Construct it once with a Config instance and pass it to any service constructor. It manages TLS, retries, and authentication headers.

Config / EnvironmentEnum / RegionEnum

import Config, { EnvironmentEnum, RegionEnum } from "./src/adyen/config";

const config = new Config();
config.environment = EnvironmentEnum.LIVE;
// For live US-region routing:
// config.region = RegionEnum.US;

Config holds every credential and behavioural setting (timeout, proxy, live URL prefix). EnvironmentEnum values are TEST and LIVE. RegionEnum selects the datacenter region for live traffic.

CheckoutAPI

import { CheckoutAPI } from "./src/adyen/services";
import Client from "./src/adyen/client";

const checkoutAPI = new CheckoutAPI(client);
const paymentsApi = checkoutAPI.PaymentsApi;
// paymentsApi.payments(request) — POST /payments

CheckoutAPI bundles all Checkout v71 sub-APIs as lazy getter properties. Access PaymentsApi, PaymentLinksApi, OrdersApi, etc. from a single object. Each getter creates a fresh sub-API instance backed by the shared Client.

hmacValidator

import { hmacValidator } from "./src/adyen/utils";

const isValid = hmacValidator.validateHMAC(notification, process.env.ADYEN_HMAC_KEY!);

Use hmacValidator in your webhook receiver to verify the HmacSignature field on every incoming notification. Reject any notification where validateHMAC returns false.

HttpClientException

import HttpClientException from "./src/adyen/httpClient/httpClientException";

try {
  await paymentsApi.payments(request);
} catch (e) {
  if (e instanceof HttpClientException) {
    console.error(e.statusCode, e.message);
  }
}

HttpClientException is thrown by the HTTP layer for non-2xx responses. Check statusCode to distinguish declined payments (422) from auth failures (401) and server errors (500).

Working examples

Scenario - Creating a checkout payment session

Initiate a hosted-payment-page session using the Checkout API.

import Client from "./src/adyen/client";
import Config, { EnvironmentEnum } from "./src/adyen/config";
import { CheckoutAPI } from "./src/adyen/services";
import { Types } from "./src/adyen";

const config = new Config();
config.apiKey = process.env.ADYEN_API_KEY!;
config.merchantAccount = process.env.ADYEN_MERCHANT_ACCOUNT!;
config.environment = EnvironmentEnum.TEST;

const client = new Client({ config });
const checkout = new CheckoutAPI(client);

async function createSession(): Promise<void> {
  const request: Types.Checkout.CreateCheckoutSessionRequest = {
    merchantAccount: config.merchantAccount!,
    amount: { currency: "EUR", value: 1000 },
    reference: "order-ref-001",
    returnUrl: "https://yourapp.com/checkout/result",
    countryCode: "NL",
  };

  const response = await checkout.SessionsApi.sessions(request);
  console.log("Session id:", response.id);
  console.log("Session data:", response.sessionData);
}

createSession().catch(console.error);

Scenario - Validating an incoming webhook notification

Receive a POST from Adyen and verify its HMAC signature before processing.

import express, { Request, Response } from "express";
import { hmacValidator } from "./src/adyen/utils";
import { Types } from "./src/adyen";

const app = express();
app.use(express.json());

app.post("/webhooks/adyen", (req: Request, res: Response) => {
  const notification = req.body as Types.Notification.NotificationRequest;

  for (const item of notification.notificationItems ?? []) {
    const notifItem = item.NotificationRequestItem;
    const valid = hmacValidator.validateHMAC(notifItem, process.env.ADYEN_HMAC_KEY!);

    if (!valid) {
      console.warn("Invalid HMAC, ignoring notification");
      return res.status(401).send("Invalid HMAC");
    }

    console.log("Event:", notifItem.eventCode, "PSP:", notifItem.pspReference);
  }

  res.json({ notificationResponse: "[accepted]" });
});

app.listen(3000);

Scenario - Fetching balance account details (Balance Platform)

Query account holder information via the Balance Platform API.

import Client from "./src/adyen/client";
import Config, { EnvironmentEnum } from "./src/adyen/config";
import { BalancePlatformAPI } from "./src/adyen/services";

const config = new Config();
config.apiKey = process.env.ADYEN_API_KEY!;
config.environment = EnvironmentEnum.TEST;

const client = new Client({ config });
const balancePlatform = new BalancePlatformAPI(client);

async function getAccountHolder(id: string): Promise<void> {
  const response = await balancePlatform.AccountHoldersApi.getAccountHolder(id);
  console.log("Account holder:", response.id, response.status);
}

getAccountHolder("AH3227C223222B5CMD2SXFKGT").catch(console.error);

File walkthrough

• client.ts — Constructs HTTP requests using Config; passed into every service and sub-API.
• config.ts — Holds apiKey, environment, merchantAccount, timeout, proxy, and live URL prefix.
• index.ts — Single barrel file; import everything from here in application code.
• service.ts — Base class storing a Client reference; all API classes extend this.
• webhooks.ts — Re-exports banking and management webhook handler classes.
• constants/apiConstants.ts — Base URLs and path segments for each Adyen API.
• constants/libraryConstants.ts — Library version string injected into User-Agent.
• constants/nexoConstants.ts — Terminal API (Nexo) protocol constants.
• helpers/checkServerIdentity.ts — Custom TLS certificate pinning helper.
• helpers/getJsonResponse.ts — Parses HTTP response body to typed object.
• helpers/setApplicationInfo.ts — Injects library metadata into every request payload.
• httpClient/clientInterface.ts — Interface contract for HTTP client implementations.
• httpClient/httpClientException.ts — Typed exception carrying HTTP status code and body.
• httpClient/httpURLConnectionClient.ts — Default Node.js HTTP client using https + proxy agent.
• notification/bankingWebhookHandler.ts — Parses and validates banking webhook payloads.
• notification/managementWebhookHandler.ts — Parses management webhook events.
• notification/notificationRequest.ts — Type definitions for standard notification requests.
• security/nexoCrypto.ts — Encrypts/decrypts Terminal API (Nexo) messages.
• security/nexoDerivedKeyGenerator.ts — Derives session keys for Nexo encryption.
• security/exception/invalidSecurityKeyException.ts — Thrown on malformed Nexo key material.
• services/ — One subdirectory per Adyen API; each exports a top-level API class.
• typings/ — All generated request/response TypeScript interfaces, re-exported as Types.
• utils/ — hmacValidator for HMAC-SHA256 notification signature verification.

Common pitfalls and fixes

• Wrong EnvironmentEnum for production: Using TEST in production silently routes to the sandbox — set config.environment = EnvironmentEnum.LIVE and supply config.liveEndpointUrlPrefix.
• Missing merchantAccount on config: Several APIs require it on Config, not only in the request body; set config.merchantAccount at startup.
• ESM / CJS interop errors: The library emits CommonJS; if your project uses "type": "module", add "esModuleInterop": true and "allowSyntheticDefaultImports": true in tsconfig.json.
• HMAC validation always failing: The HMAC key in the Customer Area is hex-encoded; pass the raw hex string directly to validateHMAC — do not Base64-decode it first.
• Proxy not applied: https-proxy-agent must be installed and config.httpsAgent set explicitly; the library does not read HTTPS_PROXY env vars automatically.
• TypeScript strict null errors on Config fields: Many Config properties are optional strings; guard with ! or null-check before passing to APIs that require them.

Vibe-coding prompt template

I have dropped the Adyen Node.js API Library source into `src/adyen/` in my project.
The library is documented in `USAGE.md` at the project root.
The upstream package is `@adyen/api-library@30.1.0`.

Please help me integrate this library step-by-step:

1. Read `USAGE.md` and `src/adyen/index.ts` to understand available exports.
2. Create a shared `client.ts` in `src/` that instantiates `Config` and `Client`
   using environment variables (ADYEN_API_KEY, ADYEN_MERCHANT_ACCOUNT, ADYEN_ENVIRONMENT).
3. Create a `src/routes/checkout.ts` Express router that:
   - POST /session — calls CheckoutAPI.SessionsApi.sessions() and returns the session id and data
   - POST /webhook — validates HMAC with hmacValidator, logs the event code, returns [accepted]
4. Add proper TypeScript types from `src/adyen/typings/` for all request and response objects.
5. Wrap all Adyen calls in try/catch, handling HttpClientException with the statusCode.
6. Show me the final file structure and any required tsconfig changes.

License and credit

The source is released under the MIT License — see source/LICENSE or the upstream repository for the full text. Upstream package: @adyen/api-library by Adyen B.V., source at github.com/Adyen/adyen-node-api-library.

This product’s unique contribution is clean room implementation of valuable code block into AVCP compatible standard.

The full install guide and integration prompts unlock after purchase.

Checkout.com Official Node.js Payment SDK

eCommerce, Marketplace & POS Systems

Free