Php Api Library Laravel Package

Product Decisions This Supports

Build vs. buy (buy). Payments integration is not differentiating work. This package is Adyen's first-party, OpenAPI-generated SDK — hand-rolling HTTP calls, HMAC webhook verification, idempotency handling, and per-payment-method request schemas would cost an estimated 6–10 engineering weeks plus permanent maintenance drag, and would carry money-movement risk. Adopting the SDK converts that into a versioned Composer dependency.

Which payment capabilities are actually cheap to ship. Because services and models are generated from Adyen's OpenAPI specs and released automatically, new payment methods, endpoints, and fields arrive as version bumps rather than as integration projects. The v30.1.0 release is a clean example: a brand-new Foreign Exchange API (Adyen\Service\ForeignExchange\RatesApi::calculate()) landed as a minor bump with no migration work. This directly informs roadmap commitments: adding a local payment method (iDEAL, Klarna, PayBank, etc.), wallets, or a new region is usually a config/UI task, not an engineering epic. PMs can plan payment-method expansion at a fraction of the usual cost.

Multi-currency and pricing becomes a realistic roadmap item. The new FX API lets us calculate converted amounts and exchange rates server-side rather than hardcoding rate tables or bolting on a third-party FX feed. That unlocks presentation-currency pricing, "pay in your currency" checkout, and finance-readable FX reporting as incremental features — worth evaluating now if international expansion is on the 2–4 quarter horizon, and worth explicitly deferring if not (it is easy to over-scope FX into treasury/margin work that is not a checkout concern).

Scope sequencing for a checkout launch. The package enables a clean phasing decision:

• Phase 1 — Checkout Sessions + Adyen Drop-in/Components on the frontend; server-side just creates and configures the session. Smallest surface, lowest PCI scope.
• Phase 2 — Webhook endpoint with HMAC signature verification and idempotent order state transitions.
• Phase 3 — Tokenization/subscriptions (stored payment methods), then marketplaces (split payments, ForPlatform), payouts, or Terminal/POS depending on business model.
• Phase 4 — Management API integration to automate account/config provisioning if we operate multiple merchant accounts.
• Phase 5 (optional, newly cheap) — FX/currency presentation, and richer reconciliation using the transfer tracing data now exposed in Transfer and Transaction webhooks.

In-person payments just got a real config concern, not an engineering one. Client::setRegion() in v30.1.0 routes Terminal API cloud requests to the correct regional live endpoint, and throws on unsupported regions. For any roadmap that includes POS or in-store, that is a configuration and launch-readiness item (region coverage per market) rather than a development task — but it also means region support must be validated per market before committing to a store rollout date.

Architecture: adopt, but wrap. The library is intentionally framework-agnostic — no Laravel service provider, facade, or config publishing. That is a decision point, not a detail: we should own a thin internal adapter (interface + binding + DTOs) so controllers never touch Adyen\Client directly. This buys us testability (the SDK allows injecting a custom HttpClient\ClientInterface, so we can stub it in acceptance tests), centralized logging/observability and retry policy, and — critically — optionality if a second PSP enters the roadmap. Wrapping also contains the blast radius of model churn like this release's removal of adviceAuthorised/adviceRefused from Transfer Webhooks: only the adapter and our webhook consumers change, not the app.

Single-PSP vs. multi-PSP as a real product question. Using this SDK directly couples us to Adyen. If the roadmap contains multi-PSP routing, regional failover, or negotiating leverage with providers, budget for an abstraction layer now (or evaluate Omnipay-style gateways) rather than retrofitting later. If Adyen is a deliberate single-provider bet, skip the abstraction and take the DX hit.

Risk/upgrade policy is a PM-owned decision. Generated code churns; spec updates can change model shapes. v30.1.0 is a good illustration of the expected churn profile: additive models and new endpoints, one deprecation (Client::retrieveCloudEndpoint() → use setRegion()), and one removal of enum values we may be persisting (adviceAuthorised, adviceRefused). None of these are major-version breaks, but the removal can still break our code if we branch on those strings. We need a stated policy: pin exact versions, upgrade on a fixed cadence (e.g., quarterly, or triggered by a payment method we need), read the deprecation list every bump, and gate every upgrade behind sandbox integration tests. Also set expectations that the SDK does not handle business concerns — idempotency keys, webhook replay protection, order-state reconciliation, refund/dispute workflows, FX margin policy, and status-mapping resilience remain ours.

Buyer/user-facing trust. First-party SDK plus MIT license plus active automated releases means we can tell security and finance that payment traffic flows through vendor-maintained, vendor-supported code paths rather than bespoke glue. The v30.1.0 dependency patch for a dev-tooling CVE also confirms the maintainers respond to security advisories — worth citing as evidence of a maintained supply chain (noting it affected a dev dependency only, not the shipped runtime).

When to Consider This Package

Adopt when:

• Adyen is the payment provider (or has been selected pending integration) — there is no meaningful alternative; this is the official path.
• Stack is PHP/Laravel, Composer-managed, with a PHP version that satisfies the package's constraints — verify at evaluation time, don't assume.
• Requirements include typed request/response models, broad payment-method coverage, marketplaces, subscriptions, POS, or multi-currency FX conversion.
• The team is willing to own a thin Laravel integration wrapper rather than expect batteries-included DX.
• You need to move fast on a checkout MVP and want the smallest defensible integration surface (Sessions + Components).

Look elsewhere or pause when:

• Adyen is not the provider. For multi-PSP or provider-agnostic needs, look at gateway abstraction layers instead; for Stripe/Paddle, use their SDKs (and Laravel Cashier if billing/subscription ergonomics matter more than provider choice).
• You want framework-native DX out of the box — service provider, publishable config, facades, queued webhook jobs, artisan scaffolding. This package provides none of that; you build it.
• You want an opinionated subscription/billing layer (proration, dunning, invoices, trial logic). This is a raw API client; all billing semantics — and all FX/margin semantics — are yours.
• The integration is trivially small and you're tempted to skip the SDK — resist; webhook verification and idempotency alone justify it.
• You require a large, self-supporting OSS community for hiring/onboarding confidence. Stars (~176) and observed dependents are modest; support comes from the vendor relationship, not the community. That's fine for a first-party SDK, but don't plan around community plugins.

Due diligence checklist before committing: confirm current PHP version support, review the changelog/breaking-change history (v30.1.0 shows the pattern: additive by default, deprecations announced ahead of removal, occasional enum-value removals — treat the deprecation list as required reading each upgrade), validate the Laravel wrapper estimate (1 sprint), audit whether we persist any webhook enum values that Adyen retires, confirm in-scope Terminal regions if POS is on the roadmap, and confirm Adyen account/test credentials are available for sandbox testing in CI.

How to Pitch It (Stakeholders)

To executives: We are integrating Adyen. This is Adyen's own official PHP library, MIT-licensed, actively maintained with automated releases — so we are buying a maintained component, not building payment plumbing. It reduces time-to-market for checkout from roughly two months of engineering to a couple of sprints, keeps us out of PCI scope by design (hosted components + server-side session creation), and makes expanding into new payment methods and regions a small, incremental effort instead of a new project. The latest minor release is evidence of that model working: a new currency-conversion (FX) capability and regional in-person terminal routing arrived as free upgrades with no rework on our side. Cost is a Composer dependency plus one sprint of internal wrapper work we'd need with any provider.

To engineering: It's an OpenAPI-generated client with typed service and model classes, a pluggable HTTP client interface (so we can inject our own transport, logging, and retries, and stub it in tests), and full unit-test coverage upstream. It is deliberately framework-agnostic — no Laravel service provider — so we will wrap it in an internal adapter interface, bind it in the container, and keep Adyen\Client out of controllers. Pin versions, upgrade on a set cadence, read the deprecation list on every bump (v30.1.0 deprecates Client::retrieveCloudEndpoint() in favor of setRegion(), and removes the adviceAuthorised/adviceRefused transfer status values), and run sandbox integration tests on every upgrade. We still own idempotency, webhook HMAC verification, order-state reconciliation, FX pricing policy, and refund/dispute handling — treat those as acceptance criteria, not SDK features.

To risk/compliance: First-party, MIT-licensed, vendor-supported, with no warranty — the same posture as any commercial SDK. Payment data stays within Adyen's hosted surfaces; our servers handle session creation and signed webhooks. The maintainers actively patch security issues (v30.1.0 includes a CVE fix in a development-only dependency, no runtime impact) and publish removal timelines via deprecation notices rather than silent breaks. Adyen's support channel is our escalation path, not a community forum.