Liontech Php Sdk Laravel Package

Technical Evaluation

Architecture Fit

• Laravel Alignment: The SDK is explicitly designed for Laravel via nokimaro/liontech-laravel, offering a facade, service provider, and config integration. This aligns perfectly with Laravel’s dependency injection and service container patterns.
• Domain-Oriented Design: The SDK’s typed request/response objects (e.g., CreateOrderRequest, Money, Currency) reduce boilerplate and enforce data integrity, fitting Laravel’s Eloquent/value object paradigms.
• PSR Compliance: Adherence to PSR-4 (autoloading), PSR-7 (HTTP messages), PSR-17 (factories), and PSR-18 (HTTP clients) ensures seamless integration with Laravel’s ecosystem (e.g., Guzzle, Symfony HTTP components).

Integration Feasibility

• Payment Gateway Abstraction: The SDK abstracts FusionPayments’ API into Laravel-friendly methods (e.g., liontech()->orders()->create()), mirroring Laravel’s Eloquent query builder pattern.
• Webhook Handling: Built-in webhook verification (WebhookPayload::fromJson()) and typed event discrimination (WebhookEventType) simplify Laravel route/webhook controller implementation.
• Token Management: Automatic token refresh (refreshAndApply()) integrates cleanly with Laravel’s caching (e.g., Redis) and session management.

Technical Risk

• PHP 8.3 Dependency: Requires Laravel 10+ (PHP 8.3+). Legacy Laravel apps (e.g., 8/9) would need polyfills or upgrades.
• Unofficial SDK: No FusionPayments backing may introduce breaking changes (e.g., API deprecations). Monitor changelog for baseUrl/secureUrl updates (e.g., LionTech → FusionPayments rebrand).
• Card Encryption: RSA encryption requires secure key management. Laravel’s config or vault (e.g., Hashicorp Vault) should store private keys.
• Webhook Security: Signature verification must be enforced in Laravel middleware (e.g., VerifyLionTechWebhook::handle()).

Key Questions

1. Laravel Version Compatibility:
   • Is the team using Laravel 10+ (PHP 8.3+)? If not, what’s the upgrade path?
2. Key Management:
   • How will RSA encryption keys (for card data) and webhook signatures be stored/rotated?
3. Error Handling:
   • Should Laravel exceptions (e.g., HttpException) wrap SDK exceptions (e.g., ValidationException) for consistency?
4. Testing:
   • Are sandbox test cards (5522..., 4405...) sufficient for CI/CD, or need custom test data?
5. Monitoring:
   • How will SDK errors (e.g., RateLimitException) be logged/alerted (e.g., Laravel Horizon)?

Integration Approach

Stack Fit

• Laravel-Specific Package: nokimaro/liontech-laravel provides:
  • Service Provider: Registers the SDK as a singleton (liontech() facade).
  • Config File: Centralizes access_token, baseUrl, and webhook settings.
  • Middleware: Optional webhook verification middleware.
• HTTP Client: Uses Guzzle by default (Laravel’s default PSR-18 client), but supports custom clients (e.g., Symfony HTTP Client).
• Queue Jobs: Long-running operations (e.g., refunds) can be queued (e.g., LiontechRefundJob).

Migration Path

1. Installation:

   composer require nokimaro/liontech-php-sdk nokimaro/liontech-laravel
   

2. Publish Config:

   php artisan vendor:publish --provider="Nokimaro\LionTech\Laravel\LiontechServiceProvider"
   

3. Configure .env:

   LIONTECH_ACCESS_TOKEN=your_token
   LIONTECH_BASE_URL=https://api.fusionpayments.io
   LIONTECH_WEBHOOK_SECRET=your_webhook_signing_key
   

4. Facade Usage:

   use Nokimaro\LionTech\Facades\Liontech;
   
   $order = Liontech::orders()->create($request);
   

5. Webhook Route:

   Route::post('/liontech-webhook', [WebhookController::class, 'handle']);
   

Compatibility

• Laravel Ecosystem:
  • Works with Laravel Cashier (for subscription management) via custom logic.
  • Integrates with Laravel Notifications for payment success/decline emails.
• Third-Party Packages:
  • Laravel Cashier: Use SDK for refunds/payouts not covered by Cashier.
  • Spatie Fractal: Transform SDK responses into API resources.
• Database:
  • Store orderId, paymentId, and txnId in Laravel models (e.g., Order::liontechOrderId).

Sequencing

1. Phase 1: Core Integration
   • Implement CreateOrderRequest/CreatePaymentRequest for checkout flows.
   • Set up webhook verification and route handling.
2. Phase 2: Advanced Features
   • Add refund/payout logic (e.g., LiontechRefundService).
   • Implement token management (e.g., LiontechTokenRepository).
3. Phase 3: Observability
   • Log SDK errors to Laravel’s log channel.
   • Add metrics (e.g., payment success rates) via Laravel Telescope.

Operational Impact

Maintenance

• Dependencies:
  • Monitor nokimaro/liontech-php-sdk for updates (e.g., API endpoint changes).
  • Pin versions in composer.json to avoid breaking changes.
• Configuration:
  • Centralize secrets in Laravel’s .env or vault.
  • Use config/liontech.php for environment-specific settings (e.g., sandbox vs. live).
• Deprecations:
  • Watch for FusionPayments API deprecations (e.g., old baseUrl domains).

Support

• Error Handling:
  • Map SDK exceptions to Laravel’s Problem or custom exceptions:

    catch (ValidationException $e) {
        throw new \Illuminate\Validation\ValidationException($e->getErrors());
    }
    

  • Use Laravel’s App\Exceptions\Handler to format SDK errors for users.
• Debugging:
  • Enable SDK logging via config/liontech.php:

    'debug' => env('LIONTECH_DEBUG', false),
    

  • Leverage Laravel’s dd() or dump() for SDK responses.

Scaling

• Rate Limits:
  • Implement exponential backoff for RateLimitException:

    use Symfony\Component\HttpClient\RetryStrategy;
    

  • Use Laravel’s queue to batch non-critical operations (e.g., balance checks).
• Concurrency:
  • SDK is stateless; scale horizontally by distributing access_token across instances.
  • For high-volume webhooks, use Laravel’s queue workers (php artisan queue:work).

Failure Modes

Ramp-Up

• Onboarding:
  • Documentation: Create a Laravel-specific guide covering:
    • Facade usage vs. direct SDK calls.
    • Webhook setup (e.g., VerifyLiontechWebhook middleware).
    • Error handling patterns.
  • Examples: Provide:
    • Checkout flow (order → payment → webhook).
    • Refund/payout workflows.
    • Token management for saved cards.
• Training:
  • Backend Team: Focus on SDK methods, error handling, and webhook logic.
  • Frontend Team: Highlight payUrl redirection and 3DS flows.
• Testing:
  • Unit Tests: Mock SDK responses (e.g., CreateOrderRequest).
  • Integration Tests: Test webhook routes with sandbox payloads.
  • E2E Tests: Simulate checkout flows (e.g., Cypress + Laravel Dusk).