Payum Payzen Bundle Laravel Package

Technical Evaluation

Architecture Fit

• Payum Integration: The package leverages Payum, a flexible payment abstraction layer for PHP/Symfony, making it a strong fit for decoupling payment logic from business logic. This aligns well with microservices or modular monoliths where payment processing is a distinct concern.
• Symfony Ecosystem: Designed for Symfony 3/4 (legacy but maintainable), it integrates seamlessly with Symfony’s Dependency Injection (DI), Event Dispatcher, and Routing systems. Modern Symfony (5.4+) may require minor adjustments (e.g., autowiring, config syntax).
• Gateway Abstraction: PayZen (Systempay/Scellius) is abstracted behind Payum’s gateway interface, enabling easy swapping of payment providers in the future.

Integration Feasibility

• Low-Coupling: Payum’s design ensures payment logic is isolated, reducing risk of breaking changes during upgrades.
• Symfony-Specific: Requires Symfony’s PayumBundle (payum/payum-bundle) as a dependency, adding ~10MB to the footprint. Non-Symfony PHP apps would need a custom Payum integration.
• Legacy Support: Last release in 2021 suggests limited compatibility with modern PHP (8.1+) or Symfony (6.x+). Testing required for:
  • PHP 8.x type safety (e.g., array vs. array() deprecations).
  • Symfony’s config/packages vs. legacy app/config structure.
  • Payum’s v10+ (current) vs. this bundle’s assumed v8/v9 dependency.

Technical Risk

Key Questions

1. Symfony Version: Is Symfony 3/4 a hard requirement, or can we upgrade dependencies to support 6.x?
2. Payum Version: Does the bundle work with Payum v10+? If not, what’s the effort to port?
3. Payment Workflows: Are all required PayZen features (e.g., 3D Secure, subscriptions) supported? If not, can they be added via Payum extensions?
4. Testing: Are there existing tests for edge cases (e.g., failed transactions, refunds)?
5. Alternatives: Would a custom Payum gateway (without this bundle) reduce technical debt?

Integration Approach

Stack Fit

• Symfony Apps: Ideal for Symfony 3/4 projects already using Payum. For Symfony 5/6, evaluate:
  • Symfony Flex: Use payum/payum-bundle directly and manually configure the PayZen gateway.
  • Custom Gateway: Extend Payum\Core\Bridge\Symfony\Bridge to avoid bundle dependencies.
• Non-Symfony PHP: Not recommended; Payum core would need standalone integration.
• Monolithic vs. Microservices:
  • Monolith: Bundle fits well in a "payments module."
  • Microservice: Deploy as a separate service with Payum’s HTTP API or gRPC.

Migration Path

1. Assessment Phase:
   • Audit current payment flow (e.g., direct PayZen API calls, custom logic).
   • Map to Payum’s action flow (e.g., Capture, Authorize, Notify).
2. Proof of Concept:
   • Install payum/payum-bundle and ekyna/payum-payzen in a test environment.
   • Replicate a single payment workflow (e.g., checkout → success → failure).
3. Incremental Rollout:
   • Phase 1: Replace direct PayZen calls with Payum gateways for new features.
   • Phase 2: Migrate existing transactions via a wrapper class.
   • Phase 3: Deprecate legacy payment code.

Compatibility

• PayZen API: Verify the bundle supports your PayZen contract version (e.g., Systempay v6 vs. Scellius).
• Symfony Services: Ensure compatibility with:
  • Security: CSRF protection, user authentication in payment flows.
  • Messenger: If using async payment processing.
  • Mercure: For real-time payment notifications.
• Database: No direct DB requirements, but ensure transaction IDs align with your ORM (e.g., Doctrine).

Sequencing

1. Dependency Setup:

   composer require payum/payum-bundle ekyna/payum-payzen
   

2. Configuration:
   • Define PayZen credentials in config/packages/payum.yaml (or legacy parameters.yml).
   • Example:

     payum:
       gateways:
         payzen:
           factory: payum.payzen
           username: "%env(PAYZEN_USERNAME)%"
           password: "%env(PAYZEN_PASSWORD)%"
           test: "%kernel.debug%"
     

3. Service Integration:
   • Inject Payum into controllers/services:

     use Payum\Core\Payum;
     
     public function __construct(private Payum $payum) {}
     

4. Routing:
   • Configure PayZen’s notification URLs (e.g., /payum/notifications/payzen).
5. Testing:
   • Use PayZen’s sandbox mode (test: true in config).
   • Mock Payum’s Api for unit tests.

Operational Impact

Maintenance

• Pros:
  • Payum’s abstraction reduces vendor lock-in (e.g., switching to Stripe later).
  • Community support for Payum core (though this bundle is unmaintained).
• Cons:
  • No Updates: Last release in 2021 may miss security patches (e.g., Payum CVE fixes).
  • Debugging: Limited docs mean troubleshooting may require Payum/PayZen expertise.
• Mitigation:
  • Subscribe to Payum/PayZen release notes.
  • Implement a custom fork if critical fixes are needed.

Support

• Vendor Support: PayZen provides gateway support, but bundle issues must be resolved internally.
• Community: Payum has active GitHub discussions; PayZen-specific issues may require PayZen’s help.
• Logging:
  • Enable Payum’s debug mode (%kernel.debug%: true).
  • Log raw PayZen API responses for troubleshooting:

    $gateway->executeStep(new \Payum\Core\Action\CaptureAction(), $details);
    error_log($details->getLastResponse()->getContent());
    

Scaling

• Performance:
  • Payum’s synchronous design may require async processing for high-volume apps (e.g., Symfony Messenger).
  • PayZen’s API rate limits must be monitored (e.g., 1000 requests/hour).
• Horizontal Scaling:
  • Stateless design works well with load balancers.
  • Shared session storage (e.g., Redis) needed for payment state across instances.
• Database:
  • No heavy DB operations, but ensure transaction IDs are unique and persistent.

Failure Modes

Ramp-Up

• Developer Onboarding:
  • 1 Day: Understand Payum’s action flow and PayZen’s API contract.
  • 3 Days: Implement a basic payment flow (capture + notification).
  • 1 Week: Handle edge cases (refunds, voids, async webhooks).
• Documentation Gaps:
  • Create internal runbooks for:
    • Payment lifecycle diagrams.
    • Error code mappings (PayZen → business logic).
    • Rollback procedures.
• Training:
  • Focus on Payum’s extension points (e.g., custom actions for business rules).
  • Highlight differences from direct PayZen API usage.