Payum Payzen Laravel Package

Technical Evaluation

Architecture Fit

• Payment Abstraction: The package integrates seamlessly with Payum, a generic payment abstraction library for PHP, making it ideal for Laravel applications requiring multi-gateway support (e.g., PayZen, Systempay, Scellius). It adheres to Payum’s gateway pattern, allowing for modular payment handling without tight coupling to a single provider.
• Laravel Compatibility: Since Payum has Laravel bridges (e.g., payum/laravel), this package can be integrated into Laravel’s service container and event system (e.g., payments.sent, payments.captured).
• Domain-Specific Fit: PayZen is a European-focused payment processor (common in France/Benelux), making this package relevant for region-specific e-commerce or B2B SaaS targeting these markets.

Integration Feasibility

• Low-Coupling Design: The package follows Payum’s gateway interface, ensuring minimal boilerplate for basic use cases (e.g., one-time payments, subscriptions).
• Configuration-Driven: Supports runtime configuration (e.g., site_id, certificate, hash_mode), enabling multi-environment setups (dev/staging/prod) via Laravel’s .env.
• Webhook/Callback Handling: Payum’s notification system can be leveraged for asynchronous payment confirmations, though the package itself does not include built-in webhook logic (this would require custom Payum actions or middleware).

Technical Risk

• Deprecated Payum Version: The last release (2021-03-26) suggests potential compatibility issues with newer Payum/Laravel versions. Risk: May require backporting fixes or forking if Payum’s API evolves.
• Limited Documentation: No official Laravel-specific guides or example implementations, increasing ramp-up time for non-Payum experts.
• No Active Maintenance: No recent commits/pull requests (since 2021) raises concerns about security patches (e.g., PHP 8.2+, Laravel 10+) or deprecated dependencies.
• Hash Mode Deprecation: SHA1 is obsolete (only SHA256 is recommended), but the package allows configuration—audit required to ensure compliance with PCI DSS.

Key Questions

1. Payum Version Compatibility:

   • Which Payum version is this package tested against? Does it support Payum 2.x (latest)?
   • Are there breaking changes in newer Payum releases that would require modifications?

2. Laravel-Specific Integration:

   • How would you bind the gateway to Laravel’s service container (e.g., AppServiceProvider)?
   • Does the package support Laravel’s queue system for async payment processing?

3. Webhook/Callback Handling:

   • How would you validate and route PayZen callbacks (e.g., NOTIFICATION endpoints) in Laravel?
   • Would you need to extend Payum’s Notification system or use Laravel middleware?

4. Testing & Security:

   • Are there unit/integration test examples for the package?
   • How would you mock PayZen API responses in tests (e.g., using Payum’s MockGateway)?
   • Does the package handle retry logic for failed API calls (e.g., network issues)?

5. Multi-Gateway Strategy:

   • If the app supports multiple payment methods, how would you dynamically switch between PayZen and other Payum gateways?
   • Would you use Payum’s Payment class or a custom Laravel service facade?

6. Long-Term Viability:

   • Given the lack of maintenance, would you fork the repo to add Laravel-specific features (e.g., queue jobs, event listeners)?
   • Are there alternatives (e.g., official PayZen SDK, Stripe Connect for European markets)?

Integration Approach

Stack Fit

• Payum + Laravel: The package is natively compatible with Payum’s Laravel bridge (payum/laravel), enabling:
  • Dependency injection via Laravel’s IoC container.
  • Event dispatching (e.g., payments.sent, payments.captured) for analytics/logging.
  • Queueable payment processing (if using payum/doctrine-extensions or custom jobs).
• PHP 8.1+: The package likely supports modern PHP, but audit required for strict_types and return_type declarations.
• Database: Payum can store payment states in Eloquent models or Doctrine entities, but this package does not enforce a schema—custom migration may be needed.

Migration Path

1. Install Dependencies:

   composer require ekyna/payum-payzen payum/payum payum/laravel
   

2. Configure Payum:
   • Bind the gateway in AppServiceProvider:

     $this->app->bind('payum.gateway.payzen', function ($app) {
         $factory = new PayzenGatewayFactory();
         return $factory->create([
             'site_id' => env('PAYZEN_SITE_ID'),
             'certificate' => env('PAYZEN_CERTIFICATE'),
             'hash_mode' => \Ekyna\Component\Payum\Payzen\Api\Api::HASH_MODE_SHA256,
             'directory' => storage_path('app/payzen-cache'),
             'ctx_mode' => \Ekyna\Component\Payum\Payzen\Api\Api::MODE_PRODUCTION,
         ]);
     });
     

3. Extend Payum Actions (if needed):
   • Create custom actions for Laravel-specific logic (e.g., ConvertPaymentAction to map Payum Payment to a Laravel Order model).
4. Set Up Callbacks:
   • Use Laravel middleware or a dedicated route (e.g., /payzen/callback) to handle PayZen notifications.
   • Validate signatures using PayZen’s hash parameter (custom logic required).

Compatibility

• Payum 2.x: Verify compatibility with the latest Payum version (may require composer overrides or patches).
• Laravel 9/10: Test for PHP 8.1+ compatibility (e.g., named arguments, union types).
• PayZen API Changes: PayZen may have updated their API since 2021—audit the Api class for deprecated endpoints.

Sequencing

1. Phase 1: Basic Integration
   • Implement synchronous payments (e.g., checkout flow).
   • Test with PayZen’s sandbox (MODE_TEST).
2. Phase 2: Async Processing
   • Add queue jobs for payment status updates.
   • Implement webhook validation (e.g., HMAC verification).
3. Phase 3: Advanced Features
   • Add subscription management (if needed).
   • Integrate with Laravel Cashier or a custom billing system.
4. Phase 4: Monitoring
   • Log payment events to Laravel Horizon or a third-party tool.
   • Set up alerts for failed transactions.

Operational Impact

Maintenance

• Dependency Updates:
  • Monitor Payum’s changelog for breaking changes.
  • Consider forking the repo to backport fixes or add Laravel-specific features.
• Configuration Management:
  • Store sensitive keys (site_id, certificate) in Laravel Vault or .env.
  • Use environment-specific configs (e.g., config/payum.php).
• Deprecation Handling:
  • SHA1 support may be removed in future PHP versions—plan to enforce SHA256 only.

Support

• Troubleshooting:
  • Payum’s debug mode ($gateway->setDebug(true)) helps log API calls.
  • PayZen’s sandbox allows testing without real transactions.
• Community Resources:
  • Limited to GitHub issues (4 stars, low activity)—expect self-service debugging.
  • PayZen’s official docs may provide additional context.
• Vendor Lock-In:
  • Payum’s abstraction reduces lock-in, but custom actions may need updates if PayZen’s API changes.

Scaling

• Performance:
  • PayZen API calls are synchronous by default—consider queueing for high-volume apps.
  • Cache API responses (e.g., directory config) to reduce latency.
• Concurrency:
  • Payum is thread-safe, but file-based caching (directory) may need locking in multi-server setups.
• Load Testing:
  • Simulate high-frequency payments to validate PayZen’s rate limits.

Failure Modes