95 lines
4.2 KiB
Markdown
95 lines
4.2 KiB
Markdown
# @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
|
|
|