skills/plugins/document-navigator/docs/money/payment/payment-provider-adyen

@suaveplan/payment-provider-adyen - Universal Adyen Checkout API v71 adapter for @suaveplan/payment. Implements the PaymentProvider interface via the slim @suaveplan/payment-providers core (httpRequest + composeAbortSignal + MerchantKeyConfig + PaymentProviderError), forwarding X-API-Key auth on every call and injecting the configured merchantAccount into capture / cancel / refund request bodies. Generates default payment references via an injectable RandomIdFn so the package stays universal and deterministic under test.

Universal Adyen Checkout API v71 adapter for @suaveplan/payment. Implements the PaymentProvider interface via the slim @suaveplan/payment-providers core (httpRequest, composeAbortSignal, MerchantKeyConfig, PaymentProviderError), forwarding X-API-Key auth on every call and injecting the configured merchantAccount into capture / cancel / refund request bodies. Generates default payment references via an injectable RandomIdFn so the package stays universal and deterministic under test.

Documentation tree

• adyen — Universal adapter that implements the PaymentProvider interface from @suaveplan/payment against Adyen's Checko…
  • adyen — Universal adapter that implements the PaymentProvider interface from @suaveplan/payment against Adyen's Checko…
  • mapping — Pure mapping helpers that lift Adyen Checkout API v71 response shapes into the canonical PaymentIntent, `PaymentMetho…
• types — Type alias exported by @suaveplan/payment-provider-adyen describing the constructor argument accepted by `AdyenProvid…
  • adyen — Type alias exported by @suaveplan/payment-provider-adyen describing the constructor argument accepted by `AdyenProvid…

Install

bun add @suaveplan/payment-provider-adyen @suaveplan/payment @suaveplan/payment-providers

Quick start

import { AdyenProvider } from "@suaveplan/payment-provider-adyen";
import { ProviderRegistry } from "@suaveplan/payment-providers";
import { PaymentEngine } from "@suaveplan/payment";

const adyen = new AdyenProvider({
    apiKey: process.env.ADYEN_API_KEY ?? "",
    merchantAccount: "AcmeMerchantECOM",
});

const registry = new ProviderRegistry();
registry.register(adyen);

const engine = new PaymentEngine({ provider: registry.get("adyen") });

const intent = await engine.createIntent({
    amount: { amount: 5_000n, currency: "USD" },
    captureMethod: "automatic",
});

Features

• Full PaymentProvider surface — createIntent / confirmIntent / captureIntent / cancelIntent / refund / getIntent.
• X-API-Key authentication with Idempotency-Key forwarding on createIntent and refund.
• merchantAccount context injected into every modification body (/captures, /cancels, /refunds).
• Injectable RandomIdFn for default reference generation — with globalThis.crypto.randomUUID() fallback at call time.
• Adyen status mapping for all 10 documented v71 result codes plus failed fallback.
• Typed errors only — every failure surfaces as PaymentProviderError (HTTP / timeout / parse) from the slim core.
• Universal tier — zero node: / bun: / fs / path / stream / net / http / crypto imports; runs on Node, Bun, browsers, and Web Workers.
• Tree-shakeable — sideEffects: false + per-feature subpath exports.
• 100% test coverage (Istanbul) + 100% docs coverage.

Modules

• src/adyen/adyen.md — the AdyenProvider class.
• src/adyen/mapping.md — pure mappers (mapStatus, mapRefundStatus, mapPaymentMethod, mapPayment).
• src/types/adyen.md — AdyenConfig type alias for the slim-core MerchantKeyConfig.

Related

• @suaveplan/payment-providers — slim foundation: httpRequest, composeAbortSignal, ProviderRegistry, PaymentProviderError, shared config types.
• @suaveplan/payment — PaymentEngine, WebhookVerifier, PaymentProvider interface.

License

MIT