Yookassa Sdk Php Laravel Package

Technical Evaluation

Architecture fit. The package is a thin, framework-agnostic client for the YooKassa (Yandex.Checkout successor) REST API: it wraps HTTP calls for payment creation, confirmation, capture, refunds, and receipt (54-ФЗ) payloads behind PHP value objects. It has no Laravel service provider, facade, config publishing, or event integration, so it slots in as a library behind your own domain layer rather than as a Laravel-native integration. That is a workable architecture — arguably preferable to a magic facade — but it means the TPM owns the adapter, webhook controller, and persistence of payment state, because the SDK provides none of them.

Integration feasibility. Mechanically straightforward: Composer install, a config entry for shopId and the secret key, and a small YooKassaGateway service that maps our Order/Payment models to SDK request objects and maps SDK responses back to our enum of statuses. The real work is around the SDK, not in it: webhook endpoint with IP allow-listing plus re-fetch-and-verify of each payment, idempotency-key storage keyed to our order and attempt, receipt line-item construction for fiscalisation, and reconciliation of pending → waiting_for_capture → succeeded/canceled transitions into our own state machine.

Technical risk. This is the dominant concern. The repository is archived and the last release was 2022-03-22, with a low composite score (~2.06) and modest adoption (75 stars). Concretely:

• No upstream maintenance. No fixes for API changes, PHP minor-version deprecations, or dependency CVEs. Under a 2026 Laravel runtime (PHP 8.2–8.4) the SDK's Guzzle/PSR-7 pins and any implicit-nullable or dynamic-property usage are plausible breakage points and must be verified before committing.
• Bus-factor and provenance. The repo URL is not resolvable from the package metadata as supplied; we should confirm the canonical source, that the archive is read-only (not deleted), and that Packagist distribution still works. MIT licensing does permit an internal fork.
• Security surface. Payment credentials and fiscal data flow through this code. An unmaintained dependency in the payment path is a standing audit finding; expect to document a compensating control.
• API drift. YooKassa evolves (payment methods, SBP, receipt formats). A frozen client will not expose new fields; we would be forced into raw HTTP calls alongside the SDK, which erodes the reason to use it.

Key questions for the evaluation gate.

1. Is the archived status a hard blocker for our security/procurement review, or can we adopt with a named internal owner and a fork policy?
2. Does it install and pass a smoke test (create/confirm/refund against sandbox) on our target PHP and Laravel versions?
3. What is our exit cost — can the gateway adapter be swapped for direct HTTP or an alternative SDK within one sprint?
4. Who owns receipt/54-ФЗ correctness, and does the frozen SDK's receipt model cover our tax regimes and line-item structures?
5. Do we need features added after 2022 (new payment methods, SBP flows) at launch or only later?

Recommendation: conditionally viable for a single, well-bounded integration — adopt only behind an internal adapter interface, pin the version in composer.json, and pre-approve a fork. If the security review forbids archived dependencies in the payment path, write a ~300-line direct HTTP client instead; the API is JSON-over-HTTPS with basic auth and an idempotency header, and the SDK's marginal value over Http::withBasicAuth() is modest.

Integration Approach

Stack fit. Laravel 10/11 with PHP 8.2+, Composer 2. The SDK is a plain library, so fit is "compatible in principle, unverified in practice." Confirm at spike time: PSR-7/PSR-18 and Guzzle constraints resolve against the rest of the lockfile, and no transitive dependency is pinned to an abandoned branch. If resolution conflicts with an existing Guzzle major, that alone may kill the option.

Migration path. No data migration; this is greenfield payment capability. The migration is organisational: define the seam first.

1. App\Contracts\PaymentGateway interface (createPayment, capture, refund, getPayment) — our vocabulary, not YooKassa's.
2. YooKassaGateway implementing it via the SDK; FakeGateway for tests and local dev.
3. Bind in a service provider; credentials in config/services.php from env, never committed.
4. Only this adapter may use SDK namespaces — enforce with a PHPStan/architecture rule or a lint check so the rest of the codebase is SDK-agnostic.

Compatibility. Two axes. Runtime: verify on the exact PHP/Laravel matrix we deploy, not the matrix we plan to. API: verify against the live YooKassa sandbox, not just the SDK's unit tests — archived SDKs commonly pass their own tests while failing on the provider's current response shapes. Check timeout/retry behaviour, TLS verification defaults, and whether errors surface as typed exceptions or raw Guzzle exceptions we must translate.

Sequencing. (1) Sandbox spike, timeboxed to 2–3 days, with a written go/no-go. (2) Adapter + fakes + contract tests. (3) Webhook endpoint with IP allow-list, idempotent handling, and mandatory re-fetch of payment state before mutating our order — never trust webhook body status alone. (4) Refunds and receipts. (5) Reconciliation job and observability. (6) Only then, production keys. If the spike fails, the fallback (direct HTTP client) starts at step 2 with no rework of steps 3–6, which is the point of the interface.

Operational Impact

Maintenance. Effectively ours from day one. Budget a named owner and a recurring review: dependency audit on each Laravel/PHP upgrade, sandbox smoke test per release, and a documented fork procedure. Track the fork in our own registry so composer update cannot silently pull an unexpected version. Realistically 1–2 days per quarter steady state, spiking hard whenever we upgrade PHP.

Support. No upstream support channel worth relying on — no maintainer to file issues with, no security advisory stream. Vendor support comes from YooKassa's own API documentation and merchant support, which remains current; the SDK is not the supported artifact. Escalation path for a production payment incident is our on-call plus YooKassa merchant support, with a documented manual fallback (create payment or refund via the merchant dashboard) so finance is never blocked by a code defect.

Scaling. The SDK is stateless and synchronous — no scaling concern of its own. Our constraints are API rate limits, webhook throughput, and HTTP timeouts inside request cycles. Rule: never call the gateway inline in a user-facing request path for anything non-interactive; queue refunds, captures, and receipt retries. Use per-order idempotency keys so retries are safe, and a bounded retry policy with backoff. Webhook handlers must be idempotent and cheap, returning 200 fast and processing on a queue.

Failure modes. Enumerate and instrument them: provider outage or elevated latency (circuit-break, surface a clear user message, do not auto-retry create-payment blindly); timeout with an unknown outcome (the dangerous case — always reconcile by idempotency key before retrying, or you risk double charges); webhook loss or duplication (scheduled reconciliation job against the API as source of truth); status drift between our order and provider state; receipt/fiscalisation errors failing silently and creating a compliance gap; and abrupt total failure if the frozen SDK's dependencies are yanked, which the fork-plus-pinned-lockfile policy mitigates. Alert on: payment success-rate drop, webhook lag, reconciliation mismatches, and any uncaught SDK exception class.

Ramp-up. Low for a mid-level Laravel engineer — the SDK's surface is small and the YooKassa docs are good — but the payments domain is the learning curve: state machine, idempotency, reconciliation, fiscalisation. Assume ~1 week for a competent engineer to be productive with the adapter, and 100% of that time should be paired with someone who has shipped payments before. Allocate explicit review time from security/finance before production keys, and write the runbook (manual refund path, key rotation, incident contacts) as a deliverable of the integration, not an afterthought.

Bottom line for planning: treat this as "build a payment integration, with an archived SDK as one replaceable component." If the sandbox spike passes and security accepts a fork-ready stance, proceed — the isolation layer keeps exit cost to days. If either gate fails, the direct-HTTP fallback is small, well-understood, and removes the archive risk entirely; that is the safer default for a payment path.