Omnipay3 Yandexkassa Laravel Package

Technical Evaluation

Architecture Fit

• Modularity: The package extends Omnipay 3.x, a widely adopted payment abstraction layer, making it a clean fit for Laravel applications requiring Yandex.Kassa (Checkout) integration. It adheres to Omnipay’s driver-based architecture, ensuring compatibility with existing payment workflows.
• Laravel 5.6 Compatibility: Targets an older Laravel version (5.6), which may introduce deprecation risks if upgrading to newer Laravel versions (e.g., 8.x/9.x/10.x). The package’s lack of maintenance (no stars/dependents) suggests potential long-term viability concerns.
• Use Case Alignment: Ideal for e-commerce, SaaS, or any application requiring Yandex.Kassa Checkout (Russia-focused) with Omnipay’s multi-gateway support. Poor fit for non-Russian markets or if Omnipay’s abstraction is unnecessary.

Integration Feasibility

• Omnipay Integration: Leverages Omnipay’s PSR-compliant design, simplifying integration with Laravel’s service container and dependency injection. Minimal boilerplate required for basic payment flows (authorize, capture, refund).
• Yandex.Kassa API Wrappers: Abstracts Yandex’s Checkout API (vs. older Yandex.Money), reducing direct API handling. However, Yandex’s API changes (e.g., new endpoints, auth schemes) may require package updates.
• Laravel-Specific Features:
  • Service Provider: Likely requires manual registration (no Laravel 5.6+ auto-discovery).
  • Queue Jobs: Omnipay’s async operations (e.g., webhooks) may need Laravel Queues for reliability.
  • Middleware: Potential need for payment validation middleware (e.g., checking Yandex’s IPN signatures).

Technical Risk

• Maintenance Risk: No stars/dependents + last commit likely years old (2017–2019 era). Risk of:
  • Breaking changes with newer Omnipay/Yandex.Kassa versions.
  • Security vulnerabilities (e.g., outdated dependencies like guzzlehttp/guzzle: ~5.0).
• Dependency Conflicts:
  • Omnipay 3.x may conflict with newer Laravel packages (e.g., laravel-money).
  • PHP 7.4+ may introduce BC breaks (e.g., json_encode type changes).
• Testing Gaps:
  • No visible test suite → manual QA required for edge cases (e.g., failed payments, refunds).
  • Webhook handling may need custom validation (Yandex’s IPN signatures).

Key Questions

1. Why Laravel 5.6?

   • Is this a legacy system, or is there a plan to upgrade? If upgrading, will this package work with Laravel 8+/9+/10+?
   • Are there modern alternatives (e.g., yandex-checkout-sdk)?

2. Omnipay Overhead

   • Does the team need Omnipay’s abstraction, or would a direct Yandex.Kassa SDK (if available) reduce complexity?

3. Webhook Reliability

   • How will Yandex.Kassa’s IPN/webhook notifications be handled? Will Laravel’s queue system or horizon be used?

4. Error Handling

   • Are there plans for retry logic (e.g., transient Yandex API failures) or dead-letter queues?

5. Compliance

   • Does Yandex.Kassa require specific PCI-DSS or KYC flows? How will these be implemented?

Integration Approach

Stack Fit

• Laravel 5.6: Directly compatible, but requires:
  • Manual service provider registration (no auto-discovery).
  • Potential composer.json dependency overrides for Omnipay/Yandex.Kassa.
• Modern Laravel (8+/9+/10+):
  • High risk without forks/updates. May need:
    • Custom package fork to support newer PHP/Laravel.
    • Replacement with a maintained SDK (e.g., yandex-checkout-sdk).
• PHP Version:
  • Original package likely targets PHP 7.0–7.2. PHP 8.x may require type-declaration fixes or compatibility layers.

Migration Path

1. Assessment Phase:
   • Audit current payment flows (e.g., Stripe, PayPal) to ensure Omnipay’s abstraction is beneficial.
   • Test Yandex.Kassa’s sandbox mode for edge cases (e.g., 3D Secure, partial refunds).
2. Integration Steps:
   • Step 1: Add package via Composer:

     composer require andchir/omnipay3-yandexkassa
     

   • Step 2: Register service provider in config/app.php:

     Andchir\Omnipay3Yandexkassa\YandexkassaServiceProvider::class,
     

   • Step 3: Configure Omnipay in config/services.php:

     'yandexkassa' => [
         'shopId' => env('YANDEX_KASSA_SHOP_ID'),
         'secretKey' => env('YANDEX_KASSA_SECRET_KEY'),
     ],
     

   • Step 4: Implement payment gateway in a service class:

     use Omnipay\Omnipay;
     
     $gateway = Omnipay::create('Yandexkassa');
     $gateway->setShopId(env('YANDEX_KASSA_SHOP_ID'))->setSecretKey(env('YANDEX_KASSA_SECRET_KEY'));
     

   • Step 5: Handle responses (success/failure) and webhooks (IPN).
3. Testing:
   • Use Yandex.Kassa’s sandbox for all test cases.
   • Mock Omnipay responses for unit testing.

Compatibility

• Omnipay 3.x: Compatible with Laravel’s HTTP clients (Guzzle) and event system.
• Yandex.Kassa API: Assumes Checkout API (not legacy Yandex.Money). Verify no breaking changes since package’s last update.
• Laravel Ecosystem:
  • Cashier/Voyager: May need custom adapters if using these packages.
  • Queues: Critical for async operations (e.g., webhook processing).

Sequencing

1. Phase 1: Proof of Concept (PoC)
   • Implement a single payment flow (e.g., "Purchase" button).
   • Test sandbox transactions and webhooks.
2. Phase 2: Full Integration
   • Extend to refunds, subscriptions (if applicable), and error handling.
   • Add monitoring (e.g., Laravel Horizon for webhook queues).
3. Phase 3: Go-Live
   • Enable in staging with real Yandex.Kassa credentials (low-volume).
   • Roll out to production with feature flags for gradual adoption.

Operational Impact

Maintenance

• Short-Term:
  • Low effort for basic use cases (authorize/capture).
  • High effort for advanced features (e.g., subscriptions, custom fields).
• Long-Term:
  • Critical risk: Package abandonment may require forking or rewriting.
  • Dependency updates: Omnipay/Yandex.Kassa API changes will need manual patches.
• Documentation:
  • Nonexistent for this package → internal docs required for onboarding.

Support

• Vendor Lock-In: No official support from Yandex or Omnipay team.
• Community: Zero dependents → no public troubleshooting resources.
• Workarounds:
  • Yandex.Kassa’s official docs may help, but Omnipay-specific issues are unsupported.
  • Stack Overflow/GitHub issues may have outdated answers.

Scaling

• Performance:
  • Omnipay adds minor overhead (~10–20ms per request for abstraction).
  • Yandex.Kassa API limits (e.g., 1000 requests/minute) must be monitored.
• Concurrency:
  • Webhook handling must scale with Laravel’s queue workers.
  • Rate limiting: Implement exponential backoff for retries.
• Cost:
  • Yandex.Kassa fees (~2.9% + 30 RUB) are separate from dev costs.
  • Maintenance cost may rise if forking is needed.

Failure Modes

| Failure Scenario | Impact | **Mit