adyen-sdk

Production-grade TypeScript/Node.js client for the Adyen Payments Platform.

Full coverage of all 200+ Adyen API endpoints — Checkout, Management, Balance Platform, Transfers, Capital, Legal Entity, Classic APIs — with webhooks, retry, circuit breaker, rate limiting, and telemetry.

---

Installation

npm install adyen-sdk

Node.js ≥ 18 required (uses native fetch and crypto).

---

Quick Start

import { Adyen } from "adyen-sdk";

const client = new Adyen({
  apiKey: process.env.ADYEN_API_KEY!,
  environment: "test",           // "test" | "live"
  merchantAccount: "YourMerchantECOM",
});

// Create a payment session
const result = await client.checkout.sessions.create({
  amount: { currency: "EUR", value: 1000 },
  merchantAccount: "YourMerchantECOM",
  reference: "order-1234",
  returnUrl: "https://yourapp.com/result",
});

if (result.ok) {
  // Pass result.data.id and result.data.sessionData to your frontend
  console.log(result.data.id);
} else {
  console.error(result.error.message);
}

---

Result Type

Every API call returns Promise<Result<T>> — a discriminated union with no exceptions:

type Result<T> =
  | { ok: true;  data: T }
  | { ok: false; error: AdyenError };

const result = await client.checkout.modifications.capture("PSP-REF", {
  merchantAccount: "YourMerchantECOM",
  amount: { currency: "EUR", value: 1000 },
});

if (result.ok) {
  console.log("Captured:", result.data);
} else {
  const { type, status, message, retryable } = result.error;
  if (type === "rate_limited" && retryable) scheduleRetry();
}

Error types

type	Status	retryable
auth_error	401, 403	false
not_found	404	false
validation_error	422	false
api_error	400–499	false
rate_limited	429	true
server_error	500–599	true
network_error	—	true
timeout	—	true
config_error	—	false
webhook_validation_error	—	false

---

Configuration

const client = new Adyen({
  apiKey: "AQEyhmfxK...",        // Required
  environment: "test",           // "test" | "live"
  merchantAccount: "YourMerchant",
  timeout: 30_000,               // ms
  connectTimeout: 10_000,        // ms
  maxRetries: 3,                 // on 429 / 5xx
  retryDelay: 500,               // ms, doubles each attempt
  webhookHmacKey: "44782DEF...",
  checkoutApiVersion: "72",
  managementApiVersion: "3",
  balancePlatformApiVersion: "2",
  transferApiVersion: "4",
  legalEntityApiVersion: "4",
  capitalApiVersion: "1",
});

---

APIs

Checkout

// Sessions (Drop-in / Components)
await client.checkout.sessions.create({ amount, merchantAccount, reference, returnUrl });
await client.checkout.sessions.get(sessionId, sessionResult);

// Payments
await client.checkout.payments.listMethods({ merchantAccount, amount, countryCode });
await client.checkout.payments.create({ amount, merchantAccount, reference, returnUrl, paymentMethod });
await client.checkout.payments.submitDetails({ details, paymentData });

// Modifications
await client.checkout.modifications.capture(pspRef, { merchantAccount, amount });
await client.checkout.modifications.refund(pspRef, { merchantAccount, amount });
await client.checkout.modifications.cancel(pspRef, { merchantAccount });
await client.checkout.modifications.reverse(pspRef, { merchantAccount });
await client.checkout.modifications.cancelByReference({ merchantAccount, reference });
await client.checkout.modifications.updateAmount(pspRef, { merchantAccount, amount });

// Payment Links
await client.checkout.paymentLinks.create({ amount, merchantAccount, reference });
await client.checkout.paymentLinks.get(linkId);
await client.checkout.paymentLinks.update(linkId, { status: "expired" });

// Recurring / Tokens
await client.checkout.recurring.listTokens({ merchantAccount, shopperReference });
await client.checkout.recurring.deleteToken(storedPaymentMethodId);

// Orders, Donations, Utility
await client.checkout.orders.getBalance(params);
await client.checkout.donations.create(params);
await client.checkout.utility.getApplePaySession(params);

Webhooks

import { createWebhookMiddleware, EventCode } from "adyen-sdk/webhooks";

// Express middleware
app.post("/webhooks/adyen",
  express.raw({ type: "application/json" }),
  createWebhookMiddleware({
    hmacKey: process.env.ADYEN_HMAC_KEY!,
    handler: async (eventCode, item) => {
      if (eventCode === EventCode.AUTHORISATION && item.success === "true") {
        await Orders.markPaid(item.merchantReference, item.pspReference);
      }
      if (eventCode === EventCode.CHARGEBACK) {
        await Disputes.open(item);
      }
    },
  })
);

Manual validation:

import { validateHmac, parseWebhookBody, dispatch } from "adyen-sdk/webhooks";

const payload = parseWebhookBody(rawBody);
// validateAllHmac throws AdyenError on invalid signature
validateAllHmac(payload, hmacKey);
await dispatch(payload, myHandler);

Balance Platform webhooks sign the full body:

import { validateBalancePlatformHmac } from "adyen-sdk/webhooks";

const isValid = validateBalancePlatformHmac(rawBody, receivedHmac, hmacKey);

Management

// Companies & Merchants
await client.management.companies.list({}, client.config);
await client.management.merchants.create({ legalEntityId }, client.config);
await client.management.merchants.activate(merchantId, client.config);

// Webhooks
await client.management.webhooks.createMerchant(merchantId, webhookParams, client.config);
await client.management.webhooks.generateMerchantHmac(merchantId, webhookId, client.config);
await client.management.webhooks.testMerchant(merchantId, webhookId, params, client.config);

// Payout Settings
await client.management.payoutSettings.add(merchantId, params, client.config);
await client.management.payoutSettings.list(merchantId, client.config);

// Terminal Settings (20 variants: company/merchant/store/terminal × settings/logo)
await client.management.terminalSettings.getMerchantSettings(merchantId, client.config);
await client.management.terminalSettings.updateTerminalLogo(terminalId, params, client.config);
await client.management.terminalSettings.getStoreLogoById(storeId, client.config);

// Terminal Orders
const orders = client.management.terminalOrdersCompany(companyId);
await orders.list({}, );

Balance Platform

// Onboarding flow
await client.balancePlatform.createAccountHolder({ legalEntityId }, client.config);
await client.balancePlatform.createBalanceAccount({ accountHolderId }, client.config);
await client.balancePlatform.createPaymentInstrument({ balanceAccountId, type: "card" }, client.config);

// Sweeps
await client.balancePlatform.createSweep(accountId, { schedule, counterparty }, client.config);

// Card PIN
await client.balancePlatform.getPublicKey(client.config);
await client.balancePlatform.changePin({ encryptedPin, token }, client.config);

// SCA Devices
await client.balancePlatform.beginScaDeviceRegistration(params, client.config);
await client.balancePlatform.finishScaDeviceRegistration(deviceId, params, client.config);

// Transaction Rules
await client.balancePlatform.createTransactionRule({ entityKey, type: "velocity" }, client.config);

// Balance Webhook Settings
await client.balancePlatform.createBalanceWebhookSetting(accountId, params, client.config);

// Transfer Limits
await client.balancePlatform.createPlatformLimit(platformId, params, client.config);
await client.balancePlatform.approveBalanceAccountLimits(accountId, params, client.config);

Transfers & Capital

// Transfers
await client.transfers.create({ amount, category: "internal", balanceAccountId, counterparty }, client.config);
await client.transfers.list({ balanceAccountId }, client.config);
await client.transfers.listTransactions({ balanceAccountId, createdSince }, client.config);

// Capital
await client.capital.listDynamicOffers(client.config);
await client.capital.requestGrant({ grantOfferId }, client.config);

// Raise Disputes (cardholders)
await client.raiseDisputes.raise({ transactionId, reason }, client.config);
await client.raiseDisputes.addAttachment(disputeId, { content, contentType }, client.config);

Legal Entity (KYC)

await client.legalEntity.create({ type: "individual", individual: { name, email } }, client.config);
await client.legalEntity.uploadDocument({ type: "PASSPORT", content }, client.config);
await client.legalEntity.acceptToS(id, tosDocId, { acceptedBy, ip }, client.config);
await client.legalEntity.getOnboardingLink(id, { returnUrl }, client.config);

Classic APIs

await client.classicPayments.authorise({ amount, merchantAccount, paymentMethod }, client.config);
await client.classicPayments.capture({ merchantAccount, originalReference, modificationAmount }, client.config);
await client.classicAccount.createAccountHolder(params, client.config);
await client.classicFund.payoutAccountHolder(params, client.config);

Functional style (no class instance needed)

import { sessions, modifications } from "adyen-sdk";
import { buildConfig } from "adyen-sdk";

const config = buildConfig({ apiKey: "...", environment: "test" });

const result = await sessions.create({ ... }, config);
await modifications.refund(pspRef, { merchantAccount, amount }, config);

---

Telemetry

const unsub = client.onTelemetry((event) => {
  if (event.type === "request.stop") {
    metrics.histogram("adyen.request.duration_ms", event.durationMs ?? 0, {
      method: event.method,
      status: String(event.httpStatus ?? 0),
    });
  }
});

// Later: unsub() to detach

Events

Event	Fields
request.start	method, url, body (PCI-field redacted)
request.stop	method, url, durationMs, httpStatus, ok

---

Reliability

• Retry — exponential backoff on 429 / 5xx (maxRetries, retryDelay)
• Circuit breaker — opens after 5 consecutive failures; half-opens after 30s
• Rate limiter — token bucket, 100 req/s sustained, burst 200
• Idempotency — auto-generated Idempotency-Key on every POST

---

ESM + CJS

Dual-published. Works in ESM and CommonJS:

// ESM
import { Adyen } from "adyen-sdk";

// CJS
const { Adyen } = require("adyen-sdk");

---

License

MIT