Liontech Laravel Laravel Package

## Getting Started

### Minimal Setup
1. **Installation**:
   ```bash
   composer require nokimaro/liontech-laravel

The package auto-discovers via Laravel's package discovery (no manual ServiceProvider registration needed).

2. Publish Config:

   php artisan vendor:publish --provider="Nokimaro\LiontechLaravel\LiontechServiceProvider" --tag="config"
   

   This generates config/liontech.php. Update with your LionTech (now FusionPayments.io) API credentials:

   return [
       'api_key' => env('LIONTECH_API_KEY'),
       'secret_key' => env('LIONTECH_SECRET_KEY'),
       'environment' => env('LIONTECH_ENV', 'sandbox'), // 'live' or 'sandbox'
       'webhook_secret' => env('LIONTECH_WEBHOOK_SECRET'),
       'api_url' => env('LIONTECH_API_URL', 'https://api.fusionpayments.io'), // Default now points to fusionpayments.io
   ];
   

3. First Use Case: Charge a card via the facade (API URLs now default to fusionpayments.io):

   use Nokimaro\LiontechLaravel\Facades\LionTech;
   
   $charge = LionTech::charges()->create([
       'amount' => 1000, // cents
       'currency' => 'USD',
       'description' => 'Premium Subscription',
       'card' => [
           'number' => '4242424242424242',
           'exp_month' => 12,
           'exp_year' => 2030,
           'cvc' => '123',
       ],
   ]);
   

Implementation Patterns

Core Workflows

1. Dependency Injection (Recommended)

Inject the LionTech facade or service directly into controllers/services:

use Nokimaro\LiontechLaravel\Facades\LionTech;

class SubscriptionController extends Controller
{
    public function __construct(private LionTech $liontech) {}

    public function create()
    {
        $subscription = $this->liontech->subscriptions()->create([
            'plan_id' => 'monthly_premium',
            'customer_id' => auth()->id(),
        ]);
    }
}

2. Webhook Handling

Validate and process incoming webhooks in a middleware or route:

use Nokimaro\LiontechLaravel\Facades\LionTech;

Route::post('/liontech-webhook', function (Request $request) {
    $event = LionTech::webhooks()->verifyAndParse($request->getContent(), $request->header('Liontech-Signature'));

    // Handle event (e.g., charge.succeeded, subscription.updated)
    match ($event['type']) {
        'charge.succeeded' => $this->handleChargeSucceeded($event['data']),
        default => null,
    };
});

3. Card Encryption (PCI Compliance)

Use the SDK’s RSA encryption to securely transmit card data:

$publicKey = LionTech::config()->get('public_key'); // Publish this to frontend
$encryptedCard = LionTech::cards()->encrypt([
    'number' => '4111111111111111',
    'exp_month' => 12,
    'exp_year' => 2025,
    'cvc' => '123',
], $publicKey);

// Send $encryptedCard to your frontend for tokenization.

4. Configuration Management

Dynamically switch environments (e.g., for testing) or override API URLs:

// Override config temporarily (e.g., in tests)
config(['liontech.environment' => 'sandbox']);
config(['liontech.api_url' => 'https://sandbox.fusionpayments.io']);

Integration Tips

Laravel Cashier Integration

Extend Laravel’s built-in Cashier for LionTech-specific logic:

use Nokimaro\LiontechLaravel\Facades\LionTech;

class LiontechServiceProvider extends ServiceProvider
{
    public function boot()
    {
        Cashier::extend('liontech', function ($app, $name, $config) {
            return new class {
                public function createSubscription($user, $plan)
                {
                    return LionTech::subscriptions()->create([
                        'customer_id' => $user->liontech_customer_id,
                        'plan_id' => $plan->external_id,
                    ]);
                }
            };
        });
    }
}

Testing

Use the LionTech facade’s mocking capabilities:

$this->mock(LionTech::class)->shouldReceive('charges()->create')
    ->once()
    ->andReturn((new Charge())->setId('test_123'));

Logging

Enable SDK logging via Laravel’s config:

'logging' => [
    'enabled' => env('LIONTECH_LOGGING', false),
    'channel' => 'single',
],

Gotchas and Tips

Pitfalls

1. Webhook Signature Mismatches

   • Issue: Webhook verification fails due to incorrect Liontech-Signature header or webhook_secret.
   • Fix: Ensure the secret matches config('liontech.webhook_secret') and the request payload is unmodified.
   • Debug: Log the raw request headers/signature for comparison:

     \Log::debug('Webhook Signature', [
         'received' => $request->header('Liontech-Signature'),
         'expected' => LionTech::webhooks()->generateSignature($request->getContent()),
     ]);
     

2. Environment Mismatches

   • Issue: API calls fail silently in live mode due to sandbox credentials or incorrect API URL.
   • Fix: Double-check config('liontech.environment') and config('liontech.api_url'):

     LIONTECH_ENV=live
     LIONTECH_API_URL=https://api.fusionpayments.io
     

3. Card Encryption Key Rotation

   • Issue: Encrypted cards fail after LionTech updates their public key.
   • Fix: Publish the latest public_key to your frontend and update your liontech.php config:

     'public_key' => env('LIONTECH_PUBLIC_KEY'),
     

4. Idempotency Keys

   • Issue: Duplicate charges due to missing idempotency keys in retries.
   • Fix: Always include idempotency_key in charge creation:

     $charge = LionTech::charges()->create([
         'amount' => 1000,
         'idempotency_key' => 'unique_key_' . uniqid(),
         // ... other params
     ]);
     

Debugging Tips

1. Enable SDK Debug Mode Add to liontech.php:

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

   This logs raw API requests/responses to storage/logs/liontech.log.

2. Validate API Responses Use Laravel’s dd() to inspect raw responses:

   $response = LionTech::charges()->retrieve('charge_123');
   dd($response->json());
   

3. Common HTTP Errors

   • 401 Unauthorized: Invalid api_key or secret_key.
   • 402 Payment Required: Insufficient funds or declined card.
   • 422 Unprocessable Entity: Invalid request parameters (check the errors field in the response).
   • 404 Not Found: Incorrect api_url (e.g., pointing to old liontech.com domain).

Extension Points

1. Custom API Clients Bind a custom client to the container in a service provider:

   $this->app->singleton('liontech.custom', function ($app) {
       return LionTech::client()->withOptions([
           'timeout' => 30,
           'connect_timeout' => 5,
           'base_uri' => 'https://api.fusionpayments.io', // Explicitly set if needed
       ]);
   });
   

2. Event Listeners Subscribe to LionTech events via Laravel’s event system:

   LionTech::events()->listen('charge.succeeded', function ($event) {
       // Trigger a notification or update a database
   });
   

3. Middleware for API Calls Add middleware to log or transform requests/responses:

   LionTech::middleware(function ($request, $next) {
       \Log::info('LionTech Request', $request->all());
       return $next($request);
   });
   

4. Testing Helpers Extend the package’s test