{
  "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.

完全なインストールガイドと統合プロンプトは購入後に解放されます。

eCommerce, Marketplace & POS Systems

無料