Liontech Php Sdk Laravel Package

Getting Started

Minimal Setup

1. Install the SDK:

   composer require nokimaro/liontech-php-sdk
   

   For Laravel, use the dedicated wrapper:

   composer require nokimaro/liontech-laravel
   

2. Initialize the Client (Laravel example):

   use Nokimaro\LionTech\Laravel\Facades\LionTech;
   
   $liontech = LionTech::client(); // Uses config/liontech.php
   

   Or manually:

   use Nokimaro\LionTech\Client;
   
   $liontech = new Client(
       accessToken: config('liontech.access_token'),
       baseUrl: config('liontech.base_url')
   );
   

3. First Use Case: Create an Order

   $order = $liontech->orders()->create(new CreateOrderRequest(
       amount: new Money('100.00', Currency::USD),
       customer: new CustomerData(
           email: 'user@example.com',
           fullName: 'John Doe',
           ip: request()->ip(),
       ),
       successUrl: route('payment.success'),
       declineUrl: route('payment.decline'),
       description: 'Order #123'
   ));
   

   Redirect users to $order->payUrl.

Implementation Patterns

Core Workflows

1. Payment Flow

   • Step 1: Create an order (store orderId in DB).
   • Step 2: Process payment with payments()->create().
   • Step 3: Handle 3DS redirects via requiresRedirect().
   • Step 4: Confirm payment via webhook or payments()->confirm().

   // Example: Process payment with saved token
   $payment = $liontech->payments()->create(new CreatePaymentRequest(
       amount: new Money('50.00', Currency::USD),
       paymentData: PaymentData::token('tok_123'),
       orderId: 'ord_456',
   ));
   

2. Webhook Handling

   • Use middleware to verify signatures:

     public function handle(Request $request, Closure $next) {
         $liontech = LionTech::client();
         $verifier = $liontech->webhookVerifier();
         if (!$verifier->verify($request->header(), $request->getContent())) {
             abort(401);
         }
         return $next($request);
     }
     

   • Parse payloads with typed DTOs:

     $webhook = WebhookPayload::fromJson($request->getContent());
     if ($webhook->payment->isSuccessful()) {
         // Fulfill order
     }
     

3. Token Management

   • Store tokens in your DB with expiresAt.
   • Refresh tokens automatically:

     try {
         $liontech->payments()->create(...);
     } catch (TokenExpiredException $e) {
         $liontech->auth()->refreshAndApply(new RefreshTokenRequest(
             refreshToken: $storedRefreshToken
         ));
         retry();
     }
     

Integration Tips

• Laravel Service Provider: Use liontech-laravel to bind the client to the container.
• Queues: Offload webhook processing to queues for async handling.
• Logging: Log payment IDs and amounts for reconciliation:

  \Log::info('Payment created', [
      'payment_id' => $payment->paymentId,
      'amount' => $payment->amount->value,
      'currency' => $payment->amount->currency->value,
  ]);
  

• Testing: Use sandbox test cards (e.g., 5522 0427 0506 6736 for 3DS flows).

Gotchas and Tips

Pitfalls

1. Token Expiry

   • Always handle TokenExpiredException and refresh tokens. Use the refreshAndApply() method to update the client’s token automatically.
   • Store refreshToken securely (e.g., encrypted in DB).

2. Webhook Verification

   • Gotcha: Forgetting to verify signatures can expose your endpoint to spoofing.
   • Fix: Use the webhookVerifier() in middleware or controllers.
   • Tip: Cache the public key to avoid repeated fetches:

     $verifier = $liontech->webhookVerifier()->withCachedKey();
     

3. Required Fields

   • CreateOrderRequest::$description and CreateRefundRequest::$webhookUrl are required (API returns 400 if omitted).
   • Tip: Validate requests early:

     $request = new CreateOrderRequest(
         amount: new Money('100.00', Currency::USD),
         customer: new CustomerData(...),
         description: 'Order #123', // <-- Required!
         // ...
     );
     

4. 3DS Redirects

   • Gotcha: Forgetting to check requiresRedirect() before redirecting users.
   • Fix: Always verify:

     if ($payment->requiresRedirect()) {
         return redirect()->away($payment->getRedirectUrl());
     }
     

5. Card Encryption

   • Gotcha: Using plain card data (PCI compliance violation).
   • Fix: Always encrypt with cardEncryptor():

     $encrypted = $liontech->cardEncryptor()->encryptForPayment([
         'pan' => '4111111111111111',
         'exp_month' => 12,
         'exp_year' => 2030,
     ]);
     

6. Error Handling

   • Gotcha: Catching generic Exception and losing context.
   • Fix: Use typed exceptions:

     try {
         $liontech->payments()->create($request);
     } catch (ValidationException $e) {
         // Log $e->getErrors()
     } catch (RateLimitException $e) {
         retryAfter($e->getRetryAfter());
     }
     

Debugging Tips

• Enable Debug Mode: Set LIONTECH_DEBUG=true in .env to log raw API responses.
• Check Headers: Use dd($liontech->getLastRequest()->getHeaders()) to inspect requests.
• Test Cards: Use sandbox test cards to reproduce issues (e.g., 4405 6397 0401 5096 for non-3DS payments).

Extension Points

1. Custom HTTP Client

   • Replace Guzzle with Symfony’s HttpClient or another PSR-18 client:

     $liontech = new Client(
         accessToken: '...',
         httpClient: new Transport(
             client: new Symfony\Contracts\HttpClient\HttpClient(),
         ),
     );
     

2. Webhook Payload Parsing

   • Extend WebhookPayload to add custom logic:

     $webhook = WebhookPayload::fromJson($payload);
     if ($webhook->eventType === WebhookEventType::PAYMENT_CONFIRMED) {
         // Custom logic
     }
     

3. Retry Logic

   • Implement exponential backoff for RateLimitException:

     use Symfony\Component\ErrorHandler\RetryableErrorInterface;
     
     if ($e instanceof RateLimitException) {
         throw new RetryableErrorInterface($e->getMessage(), $e->getRetryAfter());
     }
     

4. Mocking for Tests

   • Use Mockery or PHPUnit to mock the client:

     $mockClient = Mockery::mock(Client::class);
     $mockClient->shouldReceive('payments()->create')
         ->andReturn(new PaymentResponse(...));
     

Config Quirks

• Base URL: The SDK defaults to fusionpayments.io, but you can override it:

  $liontech = new Client(
      accessToken: '...',
      baseUrl: 'https://api.liontechnology.ai', // Legacy support
  );
  

• Sandbox Mode: Use the builder for clarity:

  $liontech = Client::builder()
      ->accessToken('sandbox_token')
      ->sandbox() // Auto-configures sandbox URLs
      ->build();
  

• Environment Variables: The Laravel wrapper reads from config/liontech.php by default. Override with:

  config(['liontech.access_token' => env('LIONTECH_ACCESS_TOKEN')]);