Libwebtopay Laravel Package

Technical Evaluation

Architecture fit

webtopay/libwebtopay is a thin, framework-agnostic SDK for Paysera's Checkout (payment gateway) API. It is not a Laravel package: there is no service provider, no facade, no publishable config, and no package discovery. The README shows a global-namespace class consumed as use WebToPay; — i.e. static-facade calls from arbitrary application code, with three supported installation shapes (merged WebToPay.php, src/includes.php, Composer).

For a Laravel codebase this is a driver, not a component. The correct architecture is:

• An internal App\Payments\Paysera adapter implementing a first-party contract (CheckoutGateway::initiate(), ::verifyCallback(), ::refund() if supported), bound in a service provider.
• Zero direct WebToPay:: calls in controllers, jobs, or domain services — otherwise the static API becomes untestable and unswappable.
• Configuration in config/payments.php fed from .env/secret manager: project ID, sign password, Paysera public key, merchant private key, callback URL, environment (test vs. live).

Integration feasibility

High. Composer install, a config block, two routes (initiate + callback), one queued job. Realistic estimate: 2–4 engineer-days for an MVP redirect flow, another 3–5 days for idempotency, reconciliation, admin tooling, and tests. The library's value is narrow but real: request signing, SS1/SS2 callback parameter validation, and encoding/format edge cases you would otherwise get wrong.

Technical risk

• Callback authenticity (highest). SS2 (RSA) validation must be mandatory; SS1/MD5 must be explicitly disabled or rejected. Every callback must be re-validated against the internal order record — amount in minor units, currency, and order reference — not trusted as authoritative because the signature passed.
• Idempotency and replay. Gateways retry callbacks. Without a unique constraint on the payment reference and a monotonic state machine (pending → paid → refunded, no regressions), duplicate deliveries cause double fulfillment or double credit.
• Version/namespace coupling. ^3.0 is documented as PHP 7.4-era (strict types, type hints) with an unchanged interface from ^2.0. PHP 8.2/8.3 compatibility is unverified from the README; a CI matrix is required before committing. The global class name also rules out clean mocking without an adapter.
• Licensing. LGPL-3.0 permits dynamic linking from proprietary code, which Composer consumption satisfies. Copying the merged WebToPay.php into application source, or patching it in-tree, changes that analysis. Route to legal before build, not after.
• Maintenance signals. 11 stars and 0 dependents indicate near-zero third-party adoption — but the publisher is Paysera itself, which is the best possible bus factor for a PSP SDK. Absence of a visible test suite is the more relevant gap: your own callback-validation fixtures become the real safety net.
• Data quality flag. The listed last-release date (2026-07-17) is anomalous and should be cross-checked against Packagist and GitHub tags before pinning a version.
• Scope ambiguity. The README covers payment collection and security-parameter validation only. Refunds, transaction reporting, and reconciliation endpoints may live outside this library.

Key questions

1. Does the library cover refunds, payouts, and transaction statements, or only initiation and callback validation?
2. What is the supported PHP range for ^3.0, and is there an 8.x-tested release?
3. Which flow do we need — macro (hosted redirect) or micro (embedded), and does the library support both cleanly?
4. Do we need multiple Paysera projects (per brand/entity) and separate test/live credentials in one deployment?
5. What are the key rotation procedures and who owns them?
6. Is Paysera our sole PSP or one of several — does the adapter need a multi-gateway contract from day one?
7. Has legal signed off on LGPL-3.0 usage in our distribution model (SaaS vs. shipped binary)?

Integration Approach

Stack fit

Laravel 10–12 on PHP 8.1+. Because the library is not PSR-4 namespaced, wrap it: a single PayseraGateway class that composes the static API, injected via constructor into a PaymentService. Bind in AppServiceProvider (or a dedicated PaymentServiceProvider) as a singleton. Keep all WebToPay:: references inside that one file so the blast radius of an API change is one class.

Config surface:

PAYSERA_PROJECT_ID=
PAYSERA_SIGN_PASSWORD=
PAYSERA_PUBLIC_KEY_PATH=      # Paysera's key, for callback verification
PAYSERA_PRIVATE_KEY_PATH=     # merchant key, for request signing
PAYSERA_CALLBACK_URL=
PAYSERA_ENV=test|live

Keys belong in a secret manager mounted to a path, never in the repo or .env committed to source control.

Migration path

• Greenfield: build behind the contract immediately; no direct SDK usage ever enters controllers.
• Brownfield: strangle existing raw WebToPay:: call sites in three steps — (a) extract each call site into the adapter with identical behavior and no refactor, (b) capture recorded callback payloads and write validation tests against the adapter, (c) swap call sites one route at a time behind a feature flag. Pin the current major version for the duration; do not combine a version bump with the extraction.

Compatibility

• Pin a caret major (^3.0) and commit composer.lock; set config.platform.php to the production runtime so CI and deploys agree.
• Add a CI matrix over PHP 8.1/8.2/8.3 running the callback-validation fixtures. Expect deprecation notices from 7.4-era style; treat warnings as non-blocking but tracked.
• Do not use class_alias to fake a namespace — it breaks static analysis and container resolution.
• Callback route must be withoutMiddleware(VerifyCsrfToken::class), outside auth/verified, and rate-limited by IP with a generous ceiling. Log the full payload (redacting keys) for forensic replay.

Sequencing

1. Legal/LGPL review; obtain test-environment credentials and merchant portal access.
2. Spike: complete one sandbox payment end-to-end; capture real callback payloads for both success and failure.
3. Define the CheckoutGateway contract and adapter; write fixtures from step 2 and unit-test signature verification both ways.
4. Callback handler: verify signature → cross-check amount/currency/reference against the order → persist transition transactionally → enqueue fulfillment job → return HTTP 200 within ~200ms.
5. Fulfillment job (idempotent), reconciliation cron against Paysera's statement, admin view of raw payloads and state history.
6. Feature-flagged rollout 1% → 25% → 100%, with a manual "mark paid" runbook available throughout.

Operational Impact

Maintenance

The library itself should change rarely — it is a stable, first-party protocol wrapper. Ongoing cost is the adapter and the payment domain: budget ~0.5 engineer-day per month for dependency updates, PHP deprecation fixes, and Paysera API notices. The real liability is that a 7.4-era package will accumulate PHP 8.x friction faster than a modern one; schedule a quarterly compatibility check rather than reacting to a failed deploy.

Support

Vendor support flows through Paysera's merchant channel and developer documentation, which is adequate for a first-party PSP. Internally you need a written runbook covering the three recurring incidents: order stuck pending (callback lost), signature mismatch (key rotation or config drift), and duplicate fulfillment (idempotency breach). Support staff need merchant-portal access to look up transactions manually — without it, every discrepancy becomes an engineering escalation.

Scaling

Effectively negligible. The library is stateless and CPU-light; RSA verification per callback is sub-millisecond. Callback volume is bounded by payment volume, which is orders of magnitude below application traffic. The only scaling concerns are the callback endpoint's response time (keep work off the request thread, defer to queues) and DB row contention on hot order records under retry storms — solved with row-level locking or an append-only payment-events table with a unique constraint on the gateway reference.

Failure modes

• Callback never arrives → order stuck pending; mitigation is a scheduled poll/reconciliation job against Paysera's records, plus alerting on orders pending beyond N minutes.
• Duplicate callback → double fulfillment if the transition isn't idempotent; mitigate with a unique index on gateway reference and conditional state updates.
• Signature verification failing en masse → usually key rotation or an environment mismatch after deploy; alert on reject rate as a first-class metric, not just an error log.
• Amount/currency tampering → only exploitable if the callback payload is trusted over the internal order record; assert both.
• PSP outage → degraded checkout with no fallback; decide early whether a second gateway is required for business continuity, which changes the contract design.
• Orphan orders → abandoned redirect initiations accumulate; add TTL cleanup and a "cancelled" terminal state.
• Major version bump → the static global interface is the breaking surface; the adapter contains it, but pin explicitly and test upgrades in staging against the fixture suite.

Ramp-up

One backend engineer reaches productivity in 2–3 days; the library is small and the README is sufficient to get a sandbox payment working. The expensive knowledge is domain, not package: payment state machines, signature validation discipline, minor-unit arithmetic, reconciliation, and refund/chargeback handling. Document the payment lifecycle and the SS2 validation checklist before go-live, and run a tabletop exercise on refund and chargeback scenarios — none of which the library documentation will teach you.