Liontech Laravel Laravel Package

Technical Evaluation

Architecture fit

The package is deliberately thin: a service provider, a facade, singleton bindings for each SDK client, a publishable config file, and two security helpers (WebhookSignatureVerifier, CardEncryptor). There is no business logic, no persistence, no queue/event plumbing, and no HTTP transport of its own — it is an IoC adaptor over nokimaro/liontech-php-sdk. From a review standpoint that is favorable: the blast radius is small and auditable in an afternoon. From an architecture standpoint it also means the package solves none of the concerns a payments integration actually carries — idempotency, retry/backoff, reconciliation, ledgering, state machines, or observability hooks. Those remain ours to build regardless of whether we adopt this wrapper or call the SDK directly.

The realistic fit is a standard Laravel monolith or modular monolith with a single merchant account, where a developer wants LionTech::orders()->create(...) working in minutes. It is a poor fit for multi-tenant/marketplace architectures: the provider binds one Client from config, and the README's guidance for multiple accounts is "instantiate Nokimaro\LionTech\Client directly" — i.e. opt out of the container. In that mode the package is providing little more than auto-discovery.

Integration feasibility

Low effort, high gating. composer require plus .env keys is genuinely a sub-hour spike in sandbox. The hard constraints are:

• PHP 8.3+ and Laravel 11–13. Estates on Laravel 10 or PHP 8.1/8.2 must upgrade before this is even testable. The 13 upper bound is forward-looking and worth verifying against actual Composer resolution — over-declared compatibility can produce false confidence.
• The 1.3.0 release migrated default API URLs to fusionpayments.io. Any published config/liontech.php with baked-in literals from an earlier version needs review, and any environment pinned to the old LionTech hostnames must be re-validated.
• LIONTECH_SANDBOX / LIONTECH_BASE_URL / LIONTECH_SECURE_URL are environment-driven, so a sandbox-to-production promotion is a config change, not a code change — good, but it also means a misconfigured environment can silently transact against the wrong endpoint.

Technical risk

The score (13/100), 0 stars, and 0 dependents understate the wrapper's quality and overstate the risk inside the package — the real risk sits one layer out:

1. Supply chain / bus factor. Single maintainer (nokimaro), who also maintains the underlying SDK. Two packages in the critical payment path, one person, no commercial support contract, no vendor endorsement ("LionTech has no official Laravel package"). If the author stops, we inherit a fork obligation on both layers.
2. A shipped security defect, recently. v1.1.0 fixed CardEncryptor fetching the webhook signature key instead of the card encryption key — a silent wrong-key defect present in 1.0.0 for anyone not setting LIONTECH_CARD_ENCRYPTION_PUBLIC_KEY explicitly. That is a PCI-relevant bug that shipped to a tagged release. It was found and fixed (credit due), but it also tells us the 100% coverage / PHPStan-max claims are measured against mocked HTTP, not against gateway behaviour — they do not validate key semantics.
3. Webhook-path runtime dependency. Empty env values now resolve to null and trigger an API auto-fetch of the public key. That is correct behaviour, but it puts a network call on the webhook verification path; a failure there becomes a verification failure becomes a 403 becomes a lost payment event. We should pin keys explicitly in production.
4. PCI scope. The inclusion of RSA card encryption implies the application touches PAN before transmission. That moves us out of SAQ A territory toward SAQ A-EP/D and requires our own scoping, key-handling, and logging-suppression discipline. The package cannot help with this and its presence may encourage frontend card capture in-app.
5. Absent non-functional features. No documented idempotency keys, retry policy, rate-limit handling, HTTP client middleware injection, token-refresh concurrency semantics, or structured logging. Token refresh in a payment path under concurrent workers is a classic source of production incidents.

Key questions (to FusionPayments and to the maintainer, before commitment)

• Is FusionPayments a licensed acquirer/PSP with a published API versioning and deprecation policy, and can they supply an up-to-date PCI AOC?
• What is the webhook delivery contract — retry schedule, replay window, at-least-once guarantees, duplicate suppression, timestamp tolerance?
• Do order/payment/refund creation endpoints accept an idempotency key, and what is the conflict/duplicate response?
• Refresh-token semantics: is it rotating? What happens to in-flight requests when a refresh fails or two workers refresh simultaneously?
• Published rate limits and the full error taxonomy (retryable vs terminal)?
• Maintainer continuity: is there a commitment to respond to security reports within a stated SLA, and willingness to transfer or co-maintain if the repo is abandoned?
• Is the Laravel 13 constraint tested in CI or simply declared?

Integration Approach

Stack fit

Strong for Laravel 11/12 on PHP 8.3+ with a conventional Eloquent-backed checkout. The facade is convenient but should be treated as a containment hazard: LionTech:: calls sprinkled through controllers, jobs, and listeners create a vendor-shaped codebase that is expensive to migrate if the gateway relationship sours. The package's DI story is the more valuable feature — injecting Client or specific clients keeps test seams intact.

Migration path

Adopt behind an internal boundary, not at the edges:

• Define our own PaymentGateway contract (create order, capture, refund, payout, verify webhook, encrypt card) in the domain layer, with a FusionPaymentsGateway implementation that composes the SDK. The package's service provider is then a transport detail we can swap for a direct SDK integration, or for a different PSP, without touching business code.
• Use LionTechConfig::isConfigured() as the feature flag for staged rollout and for graceful degradation when credentials are absent in CI/local, rather than letting container resolution fail.
• If we expect a second merchant account or tenant-specific credentials at any point, skip the singleton entirely and build a small client factory from day one — retrofitting that later is the expensive version.

Compatibility

Pin exact versions of both nokimaro/liontech-laravel and nokimaro/liontech-php-sdk, and treat SDK minor bumps as reviewable changes (1.1.0 changed key-fetch behaviour; 1.1.3 changed the webhook DTO surface). Verify PHP 8.3 availability across CI, staging, and production images before scheduling — that, not the Composer install, is the real lead time. Confirm the FusionPayments hostname migration is complete in every environment's .env, and decide explicitly whether keys are supplied via env (recommended for production) or auto-fetched.

Sequencing

1. Sandbox spike: auth, order creation, redirect flow, webhook receipt — validate the gateway works at all before investing in the wrapper.
2. Security review of the wrapper and SDK at pinned versions, focused on WebhookSignatureVerifier and CardEncryptor correctness and key sourcing.
3. Build the internal PaymentGateway contract + adapter; write contract tests with recorded/mocked gateway responses.
4. Integrate checkout and order lifecycle behind a feature flag.
5. Webhook receiver: signature verification with explicitly pinned public keys, idempotent event persistence (unique constraint on event ID), queue-based processing, replay-safe handlers.
6. Refunds/payouts, then reconciliation and settlement reporting.
7. Only then: observability (structured logs with PAN suppression, latency/error metrics per endpoint), alerting on webhook verification failure rate and token-refresh failures.

Operational Impact

Maintenance

Ongoing maintenance is ours, not the package's. The wrapper is small enough that we could vendor or fork it if abandoned — realistically a few hundred lines — but the SDK is the larger fork liability and the gateway API is the real dependency. Budget for: dependency-bump reviews on every release of both packages, annual re-review of the security helpers, and explicit key-rotation runbooks for the webhook signature key and the card encryption key. The package's version cadence (1.0.0 → 1.3.0 with release-please automation) suggests active but low-volume maintenance.

Support

This is the weakest dimension. There is no vendor support path for the Laravel wrapper — FusionPayments will support their HTTP API, not someone else's community package. Escalation for wrapper bugs goes to a GitHub issue on a zero-star repository. That means we must be capable of debugging the SDK ourselves, or we are one unresponsive maintainer away from a stalled payment incident. Mitigation: retain a named engineer with read-level fluency in the SDK source, and pre-write the fork procedure.

Scaling

The wrapper scales as well as the underlying SDK's HTTP client — it holds no state beyond a singleton Client. Scaling risks are behavioural, not architectural: concurrent token refresh across queue workers, thundering-herd retries against a rate-limited gateway, and webhook bursts during peak. None of these are addressed by the package; all must be handled in our adapter (single-flight refresh locking, jittered exponential backoff, queue-based webhook consumption with concurrency caps).

Failure modes

• Token refresh failure → cascading 401s across payment and payout paths; needs circuit-breaking and alerting.
• Webhook signature false negative → 403s, dropped events, silent order state divergence. Caused by clock skew, proxy header mutation, or the wrong/rotated key. Highest-severity failure and hardest to notice, because the gateway believes delivery succeeded or will retry into the same wall.
• Auto-fetch fallback unreachable → key retrieval fails during verification; same outcome as above. Pin keys in production.
• Environment/URL drift → sandbox credentials or endpoints promoted to production; low frequency, maximum severity.
• Duplicate webhook delivery → double-fulfilment or double-refund without idempotent event handling.
• Upstream abandonment → no security patches for a package in the PCI-adjacent path.

Ramp-up

Developer ramp-up is trivial — a Laravel engineer is productive in under a day, and the README is above average for a package of this size. Domain ramp-up is the real cost: webhook idempotency, reconciliation, refund/chargeback handling, and PCI scoping are payments problems, not Laravel problems, and the package's easy facade can create a false sense of completeness.

Verdict for planning purposes: technically usable and honestly small, but the decision should be made on the gateway relationship and the maintainer-continuity question, not on the wrapper. Proceed to a bounded sandbox spike behind an internal abstraction layer with pinned versions and explicit key configuration; do not commit to production until FusionPayments' PCI posture, webhook contract, and idempotency support are documented in writing, and until we have a named owner for the SDK fork contingency.