# @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.

<!-- begin:auto-docs -->
## Documentation tree

- [adyen](./src/adyen/adyen.md) — Universal adapter that implements the `PaymentProvider` interface from `@suaveplan/payment` against Adyen's Checko…
  - [adyen](./src/adyen/adyen.md) — Universal adapter that implements the `PaymentProvider` interface from `@suaveplan/payment` against Adyen's Checko…
  - [mapping](./src/adyen/mapping.md) — Pure mapping helpers that lift Adyen Checkout API v71 response shapes into the canonical `PaymentIntent`, `PaymentMetho…
- [types](./src/types/adyen.md) — Type alias exported by `@suaveplan/payment-provider-adyen` describing the constructor argument accepted by `AdyenProvid…
  - [adyen](./src/types/adyen.md) — Type alias exported by `@suaveplan/payment-provider-adyen` describing the constructor argument accepted by `AdyenProvid…
<!-- end:auto-docs -->

## Install

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

## Quick start

```ts
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`](./src/adyen/adyen.md) — the `AdyenProvider`
  class.
- [`src/adyen/mapping.md`](./src/adyen/mapping.md) — pure mappers
  (`mapStatus`, `mapRefundStatus`, `mapPaymentMethod`, `mapPayment`).
- [`src/types/adyen.md`](./src/types/adyen.md) — `AdyenConfig` type
  alias for the slim-core `MerchantKeyConfig`.

## Related

- [`@suaveplan/payment-providers`](../payment-providers/README.md) —
  slim foundation: `httpRequest`, `composeAbortSignal`,
  `ProviderRegistry`, `PaymentProviderError`, shared config types.
- [`@suaveplan/payment`](../payment/README.md) — `PaymentEngine`,
  `WebhookVerifier`, `PaymentProvider` interface.

## License

MIT