Stripe Laravel Package

Technical Evaluation

Architecture Fit

• Pros:

  • Payum’s Gateway Pattern: Aligns with Laravel’s service-oriented architecture, enabling decoupled payment logic and multi-gateway support (e.g., future PayPal/Adyen integration).
  • Stripe Abstraction: Encapsulates Stripe’s complexity (tokens, webhooks, idempotency) behind Payum’s action-based workflows (e.g., capture, authorize), reducing business logic pollution.
  • Event-Driven Extensibility: Payum’s event system integrates with Laravel’s event bus, allowing custom logic (e.g., fraud checks, analytics) without modifying core payment flows.
  • PCI Compliance: Offloads tokenization and sensitive data handling to Stripe/Payum, simplifying audits and scope reduction.
  • Laravel Synergy: Leverages Laravel’s service container, routing, and queue systems (e.g., for async webhook processing).

• Cons:

  • Legacy Codebase: Last updated in 2016, risking incompatibility with:
    • PHP 8.x (e.g., named arguments, JIT, strict types).
    • Stripe API v2/v3 (deprecated v1 endpoints, PaymentIntents, 3D Secure 2.0).
    • Modern Laravel (e.g., dependency injection, route model binding).
  • Documentation Gaps: Scattered and Payum-centric; lacks Stripe-specific examples (e.g., subscription proration, invoicing).
  • Symfony Dependencies: May pull in unnecessary Symfony components (e.g., HttpFoundation) if not configured carefully.
  • No Active Maintenance: Absence of recent updates or dependents signals abandonware risk; requires internal validation.

Integration Feasibility

• Laravel Compatibility:
  • Payum Bridge: payum/payum-bridge (v1.0+) provides Laravel integration but may need updates for PHP 8.x/Stripe v2.
  • Service Container: Payum’s GatewayFactory and Storage can be bound to Laravel’s container, but type hints may require adjustments.
  • Routing/Webhooks: Supports Laravel’s routing system for Stripe webhooks, but signature verification (Stripe v2 uses t parameter) may need custom handling.
  • Queue Integration: Payum’s async actions (e.g., webhook retries) can integrate with Laravel’s queues, but Horizon compatibility should be tested.
• Stripe API Risks:
  • Critical: Uses Stripe API v1 (Stripe_Charge), which is deprecated. Migration to PaymentIntents (v2) requires rewriting core logic.
  • Webhooks: Payum’s event system may not fully align with Stripe v2’s webhook payload structure (e.g., payment_intent.succeeded vs. charge.succeeded).
  • Idempotency: Payum’s built-in idempotency may conflict with Stripe’s client-side idempotency keys (v2).

Technical Risk

Key Questions

1. Stripe API Strategy:
   • Should we fork the package to support Stripe v2, or hybridize (Payum for workflows + Stripe SDK for v2 features)?
2. Webhook Reliability:
   • How will we handle Stripe v2 webhook retries? Does Payum’s event system support exponential backoff?
3. Laravel-Specific Challenges:
   • Are there known issues with Laravel’s queue system (e.g., payum/payum-bridge compatibility with Horizon)?
4. Testing Coverage:
   • What tools exist for mocking Stripe responses in Payum? Can we integrate with Laravel’s mocks or pestphp?
5. Fallback Plan:
   • If Payum proves unmaintainable, what’s the migration path to spatie/laravel-stripe or direct Stripe SDK usage?
6. Performance Impact:
   • Does Payum introduce latency for high-volume transactions? How does its storage layer (e.g., database) scale?

Integration Approach

Stack Fit

• Laravel Integration:
  • Service Provider: Register Payum’s GatewayFactory and Storage (e.g., database or array) in Laravel’s container:

    $this->app->bind('payum.gateway', function ($app) {
        return Payum::createGateway([
            'factory_name' => 'stripe',
            'config' => [
                'api_key' => config('services.stripe.key'),
            ],
        ]);
    });
    

  • Routing: Bind Stripe webhooks to a controller:

    Route::post('/stripe/webhook', [StripeWebhookController::class, 'handle'])
        ->middleware('stripe.signature');
    

  • Events: Listen to Payum actions via Laravel’s event system:

    event(new PayumActionEvent($gateway, 'post.capture', $details));
    

  • Queue Jobs: Offload async Payum actions (e.g., webhook retries) to Laravel queues:

    dispatch(new ProcessPayumAction($gateway, $action, $details));
    

• Hybrid Stripe SDK:
  • Use Stripe’s PHP SDK for v2 features (e.g., PaymentIntents) while keeping Payum for workflows:

    // Stripe SDK for v2
    $intent = \Stripe\PaymentIntent::create([...]);
    
    // Payum for idempotency/storage
    $gateway->execute($intent->id);
    

  • Webhook Handling: Implement a custom middleware to route Stripe v2 events to Payum’s event system.

Migration Path

1. Assessment:
   • Map existing Stripe API calls to Payum’s actions (e.g., capture → Stripe_Charge).
   • Identify Stripe v1 dependencies (e.g., Stripe_Charge) and plan for v2 migration.
2. Proof of Concept:
   • Implement a single payment flow (e.g., one-time charge) using Payum + Stripe SDK hybrid.
   • Test webhooks with Stripe’s test mode and validate event mapping.
3. Incremental Rollout:
   • Phase 1: Replace direct Stripe v1 calls with Payum for existing flows (low risk).
   • Phase 2: Migrate new features to Stripe v2 (e.g., PaymentIntents) while keeping Payum for workflows.
   • Phase 3: Deprecate Stripe v1 entirely; update Payum or fork for v2 support.
4. Fallback:
   • If Payum proves unmaintainable, extract payment logic into a service layer and switch to spatie/laravel-stripe or direct SDK usage.

Compatibility

• PHP 8.x:
  • Patch Payum’s type hints (e.g., return_type declarations) or use payum/payum-bridge updates.
  • Test with Laravel’s strict mode and JIT.
• Stripe v2:
  • Hybrid approach: Use Payum for workflows + Stripe SDK for v2 features.
  • Custom webhook handler to bridge Stripe v2 payloads to Payum events.
• Laravel Features:
  • Dependency Injection: Bind Payum services to Laravel’s container.
  • Routing: Use Laravel’s route model binding for webhook validation.
  • Queues: Offload async Payum actions to Laravel queues (test Horizon compatibility).

Sequencing

1. Core Integration:
   • Set up Payum’s GatewayFactory and Storage in Laravel.
   • Implement one-time charge flow (