Liontech Php Sdk Laravel Package

Technical Evaluation

Architecture fit. nokimaro/liontech-php-sdk is a framework-agnostic Composer package, not a Laravel package. It is layered cleanly: a top-level Client (with Client::builder()), a PSR-18 Transport, and domain sub-clients (orders(), payments(), refunds(), payouts(), tokens(), balances(), transfers(), plus auth(), signature(), webhookVerifier(), cardEncryptor()). Requests/responses are typed DTOs (CreateOrderRequest, Money, Currency, PaymentData, EncryptedCardData) with PHP 8.3 enums and readonly classes, so consumers get IDE support and static analysis rather than raw arrays. For a Laravel target platform, the relevant artifact is the sibling nokimaro/liontech-laravel wrapper (service provider, facade, config file), which must be evaluated separately — this package alone gives you no container bindings, no config publishing, no facade. The SDK's PSR-18 dependency injection is a genuine asset: it lets a TPM standardize on a single HTTP client (Guzzle, Symfony HTTP Client) and reuse that client across other integrations, though Laravel's own Http facade is not PSR-18-compliant and cannot be dropped in directly.

Integration feasibility. Mechanically trivial: composer require, autoload via PSR-4, constructor-injected client, no global state. The readme is unusually complete for a package of this size — sandbox endpoints, test cards with OTP, exception taxonomy, and a custom-client recipe are all documented. Two API quirks show the SDK is partially reverse-engineered against observed behavior rather than generated from the OpenAPI spec: CreateOrderRequest::$description and CreateRefundRequest::$webhookUrl were promoted to required constructor args in 1.1.0 because the API returns 400 without them despite the spec marking them optional. That is helpful in that the SDK encodes hard-won knowledge; it is also a signal that spec-to-SDK fidelity is not guaranteed.

Technical risk. The dominant risk is provenance, not code. Zero stars, zero dependents, no vendor backing (the readme explicitly says the SDK is unofficial), and a single author who also maintains the Laravel wrapper and the underlying SDK — a bus-factor of one for the entire integration surface. The provider rebrand from LionTech to FusionPayments in 1.2.0, which decommissioned the old domain, demonstrates concrete upstream churn: the SDK absorbed it gracefully only because callers may override baseUrl/secureUrl, and the old package name and Nokimaro\LionTech namespace were frozen for backward compatibility — an inconsistency the team will carry for the life of the integration. PHP 8.3 minimum is aggressive; any app still on 8.1/8.2 requires a platform upgrade before adoption, and 8.3 is also when several typed-constant and readonly refinements landed, so expect friction if the org standardizes on LTS-style PHP versions.

Key questions. (1) Is the vendor (FusionPayments) willing to endorse or support this SDK, or will support depend entirely on the maintainer's availability? (2) Who commits to the Laravel wrapper, and what Laravel/PHP version matrix does it actually support? (3) Which HTTP client will we bind, and does the platform team own that decision? (4) Does our threat model accept a third-party cardEncryptor performing RSA encryption of PAN/CVV, or must that be owned internally or delegated to hosted fields? (5) How do we defend against the next rebrand/domain decommission without touching application code?

Integration Approach

Stack fit. The SDK fits a modern PHP 8.3+ Laravel application provided you (a) install the companion nokimaro/liontech-laravel wrapper for DI/config, or (b) hand-roll a small service provider that binds a PSR-18 client, a Transport, and the Client into the container. Either way the SDK sits behind our own domain abstraction — do not let Nokimaro\LionTech\* DTOs leak into controllers and jobs. Define an internal PaymentGateway interface (create order, charge, refund, verify webhook) that the SDK adapter implements, so a future swap to a vendor-official SDK or another PSP is a container rebind, not a rewrite.

Migration path. For a greenfield integration the path is short: sandbox credentials → spike using the documented test cards (4405 6397 0401 5096 for non-3DS, 5522 0427 0506 6736 for 3DS with OTP 123456) → wrap → ship. For an existing PSP integration, treat this as a parallel run: keep the incumbent live, stand up the FusionPayments adapter behind a feature flag keyed by merchant or percentage, mirror orders to both systems, and reconcile settlement reports before cutting over. Because the SDK's createWithId() methods accept caller-supplied IDs for orders, payments, refunds, and payouts, idempotency keys can be mapped from our own internal identifiers — use this on every write to survive retries and network timeouts.

Compatibility. Verify three things before committing: the wrapper's illuminate/support constraint against our Laravel version; the PHP version floor against our fleet; and whether we can supply our own baseUrl/secureUrl so we are insulated from the next domain rename (the SDK supports this today — make it config-driven, not hardcoded, and pin the sandbox/production URLs in .env). Note that PHP 8.3 enums imply consumers must also be on 8.3 if DTOs cross module boundaries.

Sequencing.

1. Provision sandbox credentials and pin baseUrl/secureUrl in configuration.
2. Spike the orders + payments + webhook flows end-to-end against sandbox using the test cards.
3. Build the internal PaymentGateway port and the SDK adapter; bind in the container.
4. Implement the webhook receiver with webhookVerifier()->verify() before touching the payload, and persist paymentId/txnId with a unique constraint for replay safety.
5. Add a token-refresh wrapper: catch TokenExpiredException, call auth()->refreshAndApply(), retry once; persist the new access/refresh tokens.
6. Layer in refunds, payouts, tokens (saved methods), and balances only when a product requirement exists — every endpoint added is surface area to keep up with upstream.
7. Write contract tests against sandbox in CI, gated on credentials, and record the API version the adapter was validated against.

Operational Impact

Maintenance. The SDK's engineering hygiene is better than its adoption numbers suggest: PSR-4/7/17/18 compliance, ~96% coverage in CI, PHPStan and ECS in the toolchain, and a changelog that documents real regressions and fixes (the SBP {}-vs-[] serialization fix in 1.1.1 is exactly the class of bug you want caught and written down). But maintenance risk is concentrated in one maintainer with no funding signal and no declared support commitment. Mitigations: pin an exact version in composer.json, vendor the source into our own repository or a private mirror, and assign an owner on our side to review upstream releases within a defined SLA — do not enable auto-updates for a payment path.

Support. No vendor SLA, no commercial support tier, GitHub Issues and Security Advisories only. If a payment path breaks in production at 02:00, escalation is to the maintainer's GitHub notifications. That is acceptable for lower-volume or internal use; it is not acceptable as a sole PSP for revenue-critical traffic without a contractual relationship with FusionPayments itself, independent of the SDK.

Scaling. The SDK is stateless — HTTP request/response only — so application-tier horizontal scaling is unaffected; the bottleneck is the provider's rate limits and our handling of RateLimitException. Token refresh is the one piece of shared state: with multiple app instances, concurrent refreshes can invalidate each other's tokens, so token persistence and refresh must be centralized (cache/DB with a lock), not held in-process. Card encryption fetches a public key from the API; cache it with a TTL and support pinning a PEM key via cardEncryptor($pemKey) to avoid a hard dependency on a live key endpoint during an incident.

Failure modes to design for.

• Token expiry mid-flight — TokenExpiredException must trigger refresh-and-retry, never surface to the user as a payment failure.
• Upstream rebrand / domain decommission — has already happened once; keep baseUrl/secureUrl configuration-driven and monitored so a DNS or 4xx spike is caught immediately.
• API schema drift — the required-field quirks mean the SDK's validation may lag upstream changes; monitor 400 rates and ValidationException::getErrors() payloads.
• Webhook forgery and replay — webhookVerifier() handles signature; idempotency on txnId/paymentId is our responsibility.
• Encryption key rotation — if encryptForPayment fails or the key endpoint is down, payment creation fails; cache the key, pin a fallback PEM, and alarm on fetch failures.
• Transport failures — TransportException on timeout is indistinguishable from "we don't know if it succeeded"; only createWithId() with our own ID plus an explicit get() reconciliation job prevents double charges.

Ramp-up. Learning curve is low — the readme covers ~90% of what a mid-level Laravel developer needs in under an hour, and the typed DTOs self-document far better than a raw cURL integration. The real ramp-up cost is domain knowledge, not SDK knowledge: PCI-DSS implications of handling card data client-side even in encrypted form, idempotency semantics for money movement, webhook-driven order fulfillment ordering (fulfill on confirmed webhook, not on the browser redirect), and refund/payout reconciliation. Budget for those; budget less for the library itself. Given zero dependents and no vendor endorsement, treat adoption as a deliberate bet on a single-maintainer dependency and document that decision explicitly in the architecture record, with an exit plan to the vendor's own API or an alternative PSP if the maintainer becomes unavailable.