Interkassa Bundle Laravel Package

Technical Evaluation

Architecture Fit

• Symfony2 Focus: The bundle is tightly coupled to Symfony2 (now legacy) and lacks native Laravel compatibility. While Laravel shares some PHP/Symfony ecosystem components (e.g., routing, dependency injection), the bundle’s reliance on Symfony’s Kernel, EventDispatcher, and Configuration systems makes direct integration non-trivial.
• Payment Abstraction Layer: The bundle’s core functionality (payment processing, webhook handling, and redirect logic) could be abstracted into a Laravel-compatible service layer (e.g., via a facade or custom service provider). This would require rewriting Symfony-specific components (e.g., EventListener → Laravel Service Providers/Events).
• State Management: Interkassa’s redirect-based flow (success/fail URLs) aligns with Laravel’s routing but may conflict with Laravel’s session/state management if not explicitly handled (e.g., storing transaction IDs in Laravel’s session or cache).

Integration Feasibility

• High Effort, Medium Risk: Rewriting the bundle for Laravel is feasible but labor-intensive. Key challenges:
  • Dependency Injection: Symfony’s DI container → Laravel’s Service Container (e.g., bind()/singleton()).
  • Routing: Symfony’s Router → Laravel’s RouteServiceProvider (redirect logic must be adapted).
  • Configuration: YAML config → Laravel’s config/interkassa.php (with validation via config/caching).
  • Webhooks: Interkassa’s IPN (Instant Payment Notification) requires a Laravel route/controller to validate signatures (e.g., using Hash::equals() for HMAC verification).
• Alternative Approach: Use the bundle as a reference implementation and build a minimal Laravel wrapper (e.g., a InterkassaGateway service) that calls Interkassa’s API directly (via Guzzle or cURL).

Technical Risk

• Legacy Codebase: The bundle’s low stars (2) and maturity suggest potential undocumented edge cases (e.g., encoding issues, currency handling, or refund logic).
• API Changes: Interkassa’s API may evolve; the bundle’s lack of tests (implied by no PHPUnit setup) increases risk of breaking changes.
• Security: Hardcoded secret keys in config (as shown in README) are a red flag; Laravel’s .env should be used instead.
• Testing: No test suite means integration testing in Laravel would require mocking Interkassa’s responses (e.g., using Mockery or Laravel’s Http tests).

Key Questions

1. Business Criticality: Is Interkassa a core payment provider, or is a Laravel-native alternative (e.g., laravel-paypal) viable?
2. Team Expertise: Does the team have Symfony/Laravel hybrid experience to bridge the gap?
3. API Coverage: Does the bundle support all required Interkassa features (e.g., subscriptions, payouts, or recurring payments)?
4. Maintenance: Is the original maintainer responsive for Symfony2 updates, or will Laravel-specific fixes be unsupported?
5. Compliance: Does Interkassa’s API require specific Laravel middleware (e.g., CSRF protection for webhooks)?

Integration Approach

Stack Fit

• Laravel Compatibility:
  • Service Provider: Replace Symfony’s Bundle with a Laravel ServiceProvider to register Interkassa clients (e.g., InterkassaService).
  • Facade: Expose a clean interface (e.g., Interkassa::charge($amount)) via Laravel’s Facade pattern.
  • Events: Use Laravel’s Event system for payment lifecycle hooks (e.g., PaymentProcessing, PaymentFailed).
  • Middleware: Add VerifyInterkassaSignature middleware for webhook validation.
• Dependencies:
  • Guzzle HTTP Client: Replace Symfony’s HttpClient with Laravel’s Http client or Guzzle.
  • Validation: Use Laravel’s Validator for request payloads (e.g., webhook data).
  • Logging: Integrate with Laravel’s Log facade for debugging.

Migration Path

1. Phase 1: API Wrapper
   • Build a standalone Laravel package (e.g., laravel-interkassa) that:
     • Calls Interkassa’s API directly (no Symfony dependencies).
     • Supports core flows: authorization, capture, refunds, and webhooks.
   • Example structure:

     /src
       /Services/InterkassaClient.php  # Guzzle-based API calls
       /Exceptions/InterkassaException.php
       /Facades/Interkassa.php
       /Http/Middleware/VerifySignature.php
     

2. Phase 2: Bundle Adaptation
   • Fork the Symfony bundle and rewrite:
     • DependencyInjection/Configuration.php → Laravel config/interkassa.php.
     • EventListener → Laravel Event listeners.
     • Symfony routes → Laravel Route::post('/interkassa/webhook', ...).
3. Phase 3: Hybrid Integration
   • Use the Symfony bundle only for legacy Symfony2 services and expose its functionality via Laravel’s Process facade (e.g., for CLI-based payments).

Compatibility

• Symfony → Laravel Mappings:

  Symfony Component	Laravel Equivalent	Notes
  EventDispatcher	Laravel Event system	Use event(new PaymentProcessed()).
  Configuration	Laravel config() + validation	Use config/caching for YAML parsing.
  Router	Laravel RouteServiceProvider	Manual route definitions required.
  HttpClient	Guzzle or Laravel Http	Inject client into service.
  Twig templates	Laravel Blade	Replace if UI is needed.

• Webhook Handling:
  • Interkassa’s IPN must be mapped to a Laravel route (e.g., /interkassa/webhook).
  • Validate signatures using Interkassa’s secret_key (e.g., hash_hmac('sha256', $payload, $secret)).
  • Store transaction data in Laravel’s database (e.g., payments table) for reconciliation.

Sequencing

1. Pre-Integration:
   • Audit Interkassa’s API docs for Laravel-specific requirements (e.g., UTF-8 encoding, timeouts).
   • Set up a Laravel test environment with Interkassa’s sandbox mode.
2. Core Implementation:
   • Implement InterkassaClient for API calls.
   • Create InterkassaService to handle business logic (e.g., createPayment(), verifyWebhook()).
3. UI/UX:
   • Add Blade components for payment buttons/forms (if replacing Symfony templates).
   • Configure success/fail redirects (e.g., return redirect()->route('payment.success')).
4. Testing:
   • Unit tests for InterkassaClient (mock Guzzle).
   • Integration tests for webhook validation.
   • End-to-end tests with Interkassa’s sandbox.
5. Deployment:
   • Roll out in staging with monitoring for failed transactions.
   • Gradually migrate from legacy Symfony services (if applicable).

Operational Impact

Maintenance

• Long-Term Support:
  • Pros: Laravel’s active ecosystem (e.g., updates to Guzzle, HTTP client) reduces dependency rot.
  • Cons: Original Symfony bundle may stagnate; Laravel-specific fixes require in-house maintenance.
• Dependency Updates:
  • Monitor Interkassa’s API deprecations (e.g., SHA-1 → SHA-256 for signatures).
  • Update Laravel’s config/caching if schema changes (e.g., new config keys).
• Documentation:
  • Create Laravel-specific docs (e.g., "Setting Up Webhooks in Laravel") to replace Symfony’s README.

Support

• Debugging:
  • Use Laravel’s Log facade for Interkassa-related errors (e.g., failed API calls).
  • Implement a InterkassaDebugger trait to log raw requests/responses in development.
• Common Issues:
  • Webhook Failures: Ensure Laravel’s APP_URL matches Interkassa’s callback URLs.
  • Currency Mismatches: Validate that Interkassa’s amount and currency fields align with Laravel’s Money package (if used).
  • Timeouts: Interkassa’s API may throttle requests; implement retries with Laravel’s retry() helper.
• Vendor Lock-in:
  • Abstract Interkassa-specific logic behind interfaces (e.g., PaymentGateway) to switch providers later.

Scaling

• Performance:
  • API Calls: Use Laravel’s queue:work to process Interkassa webhooks asynchronously (e.g., dispatch(new ProcessWebhook($payload))).
  • Database: Index payments table on transaction_id for fast lookups.
• Concurrency:
  • Webhook handling must be idempotent (e.g., store processed transaction IDs in `seen_webhooks