Php Api Library Laravel Package

Technical Evaluation

Architecture fit

• This is a vendor SDK, not a framework integration. There is no ServiceProvider, facade, config file, or publishable migration — the entire Laravel wiring is ours to build. That is normal for Adyen (unlike Stripe/Mollie ecosystem packages) and is the single biggest driver of effort.
• The library's shape is compatible with Laravel's container: Adyen\Client is a stateful configuration object (API key, environment, merchant account, logger, timeout, and — as of v30.1.0 — Terminal API region), and Adyen\Service\* instances are constructed from it. This maps cleanly to a singleton Adyen\Client resolved from config('services.adyen.*') plus thin service wrappers.
• v30.1.0 reinforces that the client is a mutable config surface. Client::setRegion() adds another piece of client-level state that affects outbound endpoint selection, and Client::retrieveCloudEndpoint() is now deprecated. For a singleton-bound client this is manageable, but it confirms the client must be treated as configuration, not as a per-request object with request-scoped settings applied to it.
• Adyen\HttpClient\ClientInterface remains the key extension point. It lets us inject a Guzzle-backed or instrumented client instead of the bundled cURL client — this is where we get middleware, tracing, and connection reuse that Laravel's Http facade would normally provide.
• The library does not use Laravel's HTTP client, so Http::fake(), Http::retry(), and Http::macro() are unavailable. Testability must be designed in via the adapter layer, not inherited.

Integration feasibility

• Straightforward composer require; requires PHP 8.x with ext-curl and ext-json. No framework coupling, so no version conflict with Laravel 10/11/12.
• Services and models are generated from Adyen's OpenAPI specs via OpenAPI Generator + custom Mustache templates, driven from a separate adyen-sdk-automation repo. v30.1.0 is a textbook example: seven of the ten PRs are AdyenAutomationBot code-generation commits touching payments, paymentsapp, transaction webhooks, transfer webhooks, management webhooks, and a brand-new foreign exchange service. Upgrades arrive as very large, mostly mechanical diffs, and we cannot patch generated code (any local edit is lost on regeneration).
• Scope surface grew again in v30.1.0. New Adyen\Service\ForeignExchange\RatesApi::calculate(), new models (NetworkReason, TransferDataTracing, TransferEventTracingData, UKFpsTracingData, USAchTracingData, SubMerchantData), and new enum values. None of this is required for an online Checkout integration, but it does mean the package's surface is broader than the average Laravel payment integration and the changelog is not a proxy for "what changed in my code path."
• Webhook model churn is now a first-class risk. v30.1.0 removes the adviceAuthorised and adviceRefused status values from Transfer Webhooks models and adds reversalReceived to Modification, TransferData, and TransferEvent. For a payments-only integration this is inert; for anything touching transfers/payouts it is a behaviour change in generated model constants.
• Front-end is out of scope for this package: Adyen Web (Drop-in/Components) is loaded separately from CDN/npm and configured with a client key + allowed origins. Plan for two integration surfaces, not one.
• Webhook signature (HMAC) verification and idempotency handling are supported primitives but not an opinionated flow — we own the endpoint, CSRF exclusion, dedupe store, and state machine.

Technical risk

• Version line ambiguity is partly resolved, but confirm it. The repository (adyen-php-api-library) and the Composer package (adyen/php-api-library) still differ, and Adyen has shipped more than one PHP library generation. v30.1.0 confirms an active, semver-ish 30.x line with minor-version additive releases — that is the line to pin. Confirm it is the supported one and that security fixes land here.
• Generated-code churn (confirmed, not theoretical). Minor releases rename, add, and remove model fields and enum values. Domain code that imports Adyen\Model\* directly will break. Mitigate by confining all Adyen types behind our own DTOs/adapter.
• Deprecations are now live in the client API. Client::retrieveCloudEndpoint() is deprecated in v30.1.0. If Terminal API is in scope, schedule the migration to setRegion() before the next major; if Terminal API is out of scope, note it and move on. Either way, this is the pattern to expect: client-level methods get replaced across minor/major boundaries.
• Observability leakage. Adyen's built-in logging can write raw request/response bodies. Card data, shopper PII, and partial PANs must be scrubbed before anything reaches our log stack — a PCI-scope issue, not a nice-to-have.
• Thin ecosystem. ~176 stars and effectively no listed dependents means no community Laravel recipes, blog posts, or Stack Overflow coverage to lean on. Support is Adyen's account team plus their GitHub issues — vendor-maintained, not community-supported. Budget accordingly.
• Release hygiene looks healthy but is bot-driven. v30.1.0 includes a dev-dependency security bump (squizlabs/php_codesniffer 4.0.1 → 4.0.2, CVE-2026-67434). That particular CVE does not affect our runtime — it is a vendor dev dependency — but it shows Renovate is active and that dev-tooling changes ride along in release notes. Read the PR list, not just the headline features.

Key questions

1. Which Adyen products are in scope — online Checkout only, or also Management API, Marketplaces/split payments, terminals, transfers/payouts, or the new Foreign Exchange API? v30.1.0 added a whole new service surface; scope directly determines how much of this release actually lands in our dependency-upgrade regression.
2. What PCI scope are we targeting (SAQ A vs A-EP)? That determines whether we can use Drop-in/Components with a client key only, or need host-based redirect.
3. Which team owns the Adyen adapter long-term, and what is the accepted upgrade cadence? Observed cadence is frequent minor releases with large generated diffs — quarterly windows with exact pins is the realistic policy.
4. Do we need multi-merchant or multi-region routing (different merchant accounts per brand/currency)? If Terminal API cloud is in play, region is now client-level state via setRegion() and interacts with that answer.
5. Is there an existing PSP being replaced? If so, is dual-running and reconciliation reporting required during cutover?
6. What is the non-functional bar — peak TPS, p95 latency budget for authorization calls, and required uptime for the webhook receiver?

Integration Approach

Stack fit

• Bind a singleton Adyen\Client in a dedicated AdyenServiceProvider, sourced from config/adyen.php (.env-backed: API key, environment, merchant account, HMAC key, client key, timeout, logging toggle, and — if Terminal API is in scope — region).
• Introduce a PaymentGateway interface with an AdyenGateway implementation. All application code depends on the interface and our own request/response DTOs; the Adyen SDK appears in exactly one namespace. This is the main hedge against generated-code churn (v30.1.0 alone touched six generated service families) and against a future provider change.
• Implement a custom HttpClient\ClientInterface wrapping Guzzle to get: shared connection pool, structured logging with payload redaction, tracing headers, and test doubles.
• Do not inject Adyen\Client into queued jobs by serializing it — re-resolve from the container inside handle().
• Do not expose setRegion() (or any other client setter) to application code. Resolve region from config at boot and fail fast on an unsupported value rather than letting AdyenException surface mid-request.

Migration path

• If replacing a prior PSP: build the adapter first, then migrate endpoint-by-endpoint (authorize → capture → refund → webhook) rather than a big-bang swap.
• If migrating from an older Adyen PHP library generation: expect module-string services (checkout->payments()) to map to typed generated services, and config setters to map to our config file. Amounts are minor units everywhere — centralize that conversion in one value object before migration, not during.
• Upgrading within 30.x: v30.1.0 is additive for online Checkout. The upgrade itself is a composer bump plus a full payment-path regression; the real work is verifying no generated type you import changed shape. Contract tests around the adapter are what make this a half-day task instead of a sprint.
• Feature-flag the new gateway and roll out by percentage of traffic on low-value transactions first, with a hard cap on transaction value during the canary window.

Compatibility

• Octane / long-lived workers: Adyen\Client carries mutable state, and v30.1.0 added more (region). Ensure per-request state (idempotency key, merchant account override, logger context) is set per call, not on the shared singleton, and flush anything request-scoped in a middleware. setRegion() in particular should be set once at boot, never per request.
• Horizon / queues: never retry an authorize or capture without an idempotency key. Enforce this in the adapter so callers cannot forget.
• Containers: slim PHP images frequently lack a current CA bundle — a common, confusing TLS failure in production. Bake it in and assert it in a health check.
• Tests: the Adyen test environment with documented test cards is the only realistic verification path; there is no local simulator. Keep a small, slow, credential-gated integration suite plus fast unit tests against a faked ClientInterface.
• Version pinning: pin the exact patch (30.1.0) in composer.json with a documented bump procedure. Given the generated-code volume, ^30.1 is too loose.

Sequencing

1. Provider + config + adapter skeleton + redacting HTTP client (1–2 days).
2. Authorization flow in test environment (Drop-in/Components front-end, return URLs, 3DS challenge handling).
3. Webhook receiver: route + CSRF exclusion, HMAC verification, durable dedupe on event/pspReference, async processing, idempotent state machine.
4. Capture, partial capture, refunds, and cancellation.
5. Reconciliation job and reporting surface.
6. Management API, Terminal API (setRegion() + deprecated retrieveCloudEndpoint() migration), transfers, or Foreign Exchange only if in scope.
7. Cutover with feature flag, then decommission prior path.

Operational Impact

Maintenance

• Low hand-written surface, but recurring upgrade work: generated-code releases arrive as large diffs (v30.1.0: six generated service/model families) and require a full regression on payment paths. Plan one scheduled upgrade window per quarter and pin exact versions between windows.
• Our adapter, webhook state machine, and reconciliation job are the parts that actually need care; the SDK itself needs only version bumps plus contract tests.
• Track the adyen-sdk-automation repository and the changelog to get early warning on template changes — that's where behaviour shifts originate. Filter the changelog by the product surface you actually use; most of any given release is irrelevant to a Checkout-only integration.
• Keep a deprecation watchlist. retrieveCloudEndpoint() is the first entry; expect more client-level method replacements over time.

Support

• Vendor support covers the payment platform and account configuration, not PHP integration questions. Escalate model/service quirks through the GitHub repo and the account manager; expect slow turnaround on library-level issues.
• With ~176 stars there is no meaningful community safety net. Assume self-serve: write an internal runbook (test cards, environment keys, common error codes, webhook replay procedure) in the first sprint.
• Document the upgrade playbook once and reuse it — this is where a TPM's leverage is highest on a low-community package. The v30.1.0 notes are a good template: separate "does this touch my surface" from "does this touch anything at all."

Scaling

• The SDK is stateless per call, so the web tier scales normally. The bundled cURL client does not pool connections; at meaningful volume, swap in a Guzzle client with keep-alive to reduce TLS handshake overhead.
• Respect Adyen-side rate limits with bounded retries plus jitter behind a circuit breaker, never inside the user-facing request path.
• The webhook endpoint is the real scaling hazard: acknowledge fast, enqueue, process asynchronously. A slow synchronous handler turns a traffic spike into a payment-state divergence.

Failure modes

• Timeout after authorization. The request fails but the payment succeeded. Never map a transport error to "declined" — reconcile via webhook and /payments/details, and show the user a pending state.
• Duplicate / out-of-order webhooks. Requires durable dedupe plus terminal-state guards in the state machine; refunds and captures can legitimately arrive before the authorization notification is processed.
• Enum and model drift after an upgrade. A generated status value disappears (e.g. adviceAuthorised/adviceRefused in v30.1.0) and a switch/match in domain code silently falls through. Guard with typed handles and explicit default branches, and never reference Adyen\Model\* constants outside the adapter.
• HMAC mismatch. Return 401, alert, and never process. Silent acceptance is a forgery path.
• Idempotency key reuse. Reusing a key across different payloads returns the original response — a subtle source of "wrong amount charged" incidents. Generate keys per attempt, persist them, and reuse only on deliberate retry.
• Environment/credential drift. Live key against test merchant account, missing allowed origin on the client key, or an unsupported Terminal region throwing AdyenException at the wrong time. Assert config on boot.
• Amount and currency errors. Minor-unit math and zero-decimal currencies; centralize in one tested value object. FX-aware flows (new in v30.1.0) widen this surface if in scope.
• Log leakage. Redaction failure exposes shopper PII and card fragments. Treat as a release-blocking checklist item.

Ramp-up

• A Laravel developer familiar with payment flows: roughly 1–2 days to a working test-environment authorization and webhook.
• Production-hardened: about one sprint for the adapter, state machine, reconciliation, observability, and runbooks. Add a sprint if Marketplaces/split payments, Terminal API, or multi-merchant routing is in scope.
• Because there is no first-party Laravel documentation, budget explicitly for internal docs and 1–2 ADRs (adapter boundary, webhook idempotency model, upgrade/pinning policy) — otherwise the next engineer re-derives the design from generated source.
• Recommended posture: adopt, but only behind an internal adapter with contract tests and an exact pinned version. v30.1.0 does not change that verdict — it is an additive minor on an actively maintained line, with one deprecation to track and no breaking changes to the Checkout path. The library remains a reasonable, vendor-maintained transport layer; it is not an integration, and treating it as one is the primary delivery risk.