Sumup Ecom Php Sdk Laravel Package

Technical Evaluation

Architecture Fit

• Pros:

  • Laravel Compatibility: The SDK is PHP-based and integrates seamlessly with Laravel’s dependency injection, service container, and HTTP client stack (Guzzle/cURL). Laravel’s built-in HttpClient facade can be extended to wrap the SDK’s SumUpHttpClientInterface for consistency.
  • Modular Design: The SDK follows a service-oriented architecture (e.g., Checkouts, Customers, Transactions), aligning with Laravel’s Eloquent/Service Layer patterns. Each service can be injected into Laravel controllers/repositories.
  • Authentication Abstraction: Supports OAuth flows (authorization code, client credentials, password) and token refresh, which can be encapsulated in Laravel’s Auth or Sanctum systems for reuse.
  • Custom Endpoint Support: The Custom service allows extending the SDK for undocumented APIs, useful for future-proofing integrations.
  • Error Handling: Granular exceptions (SumUpAuthenticationException, SumUpResponseException) map cleanly to Laravel’s exception handling (e.g., throw_if in controllers).

• Cons:

  • Deprecation Warning: The SDK is deprecated in favor of sumup-php. Migration to the newer SDK should be planned post-PoC.
  • PHP Version Constraint: Requires PHP ≥5.6 (Laravel 5.8+ is PHP 7.2+). May need polyfills or version pinning.
  • No Laravel-Specific Features: Lacks Laravel-specific integrations (e.g., queue jobs, events, or Scout for analytics). These would need custom wrappers.

Integration Feasibility

• High: The SDK’s simplicity and Laravel’s flexibility enable low-effort integration. Key touchpoints:

  • Service Container: Bind SDK services to Laravel’s container for dependency injection:

    $this->app->bind(\SumUp\SumUp::class, function ($app) {
        return new \SumUp\SumUp([
            'app_id' => config('services.sumup.app_id'),
            'app_secret' => config('services.sumup.app_secret'),
            // ... other config
        ]);
    });
    

  • HTTP Client: Replace the SDK’s default client with Laravel’s HttpClient for consistency:

    $client = new \SumUp\HttpClients\GuzzleHttpClient(
        new \GuzzleHttp\Client(),
        config('services.sumup.ca_bundle_path')
    );
    

  • Configuration: Store credentials in Laravel’s .env and validate via config/services.php.

• Customization: Extend the SDK’s Custom service or create Laravel-specific decorators to add features like:

  • Webhook listeners for SumUp events.
  • Queued payment processing.
  • Integration with Laravel Cashier or Stripe-like billing.

Technical Risk

• Low to Medium:

  • Authentication Complexity: OAuth flows require careful handling of tokens/refreshes. Laravel’s Auth system can mitigate this.
  • Deprecation Risk: The SDK’s deprecation may force a rewrite. Plan for a migration path to sumup-php post-PoC.
  • Error Handling: Custom exceptions must be mapped to Laravel’s error pages (e.g., render() in App\Exceptions\Handler).
  • Performance: The SDK makes synchronous API calls. For high-volume systems, consider:
    • Queueing long-running operations (e.g., refunds).
    • Caching responses (e.g., customer data) with Laravel’s cache.

• Mitigation:

  • Testing: Use Laravel’s Http tests to mock the SDK’s HTTP client.
  • Monitoring: Log SDK errors to Laravel’s log channel or a third-party tool (e.g., Sentry).
  • Documentation: Create internal docs for Laravel-specific usage (e.g., "How to handle SumUp webhooks in Laravel").

Key Questions

1. Business Requirements:
   • Are there specific SumUp features (e.g., subscriptions, payouts) not covered by the SDK that require the Custom service?
   • Will the integration support multi-merchant accounts? If so, how will Laravel manage merchant-specific configurations?
2. Performance:
   • What is the expected transaction volume? Are there plans to optimize for bulk operations (e.g., batch refunds)?
   • Should payment processing be asynchronous (e.g., queue jobs)?
3. Compliance:
   • Are there PCI/DSS requirements for storing SumUp tokens? If so, how will Laravel’s encryption (e.g., encrypt()) be used?
4. Future-Proofing:
   • Is there a timeline to migrate to sumup-php? What are the breaking changes?
   • Should the integration abstract the SDK entirely (e.g., via a facade) to simplify future swaps?
5. Monitoring:
   • How will payment failures/retries be logged and alerted? (e.g., Laravel Horizon for queues, or SumUp’s webhooks + Laravel Echo).

Integration Approach

Stack Fit

• Laravel Core:
  • Service Container: Inject SDK services into controllers/repositories.
  • Configuration: Use Laravel’s .env and config/ for SDK credentials.
  • Routing: Map SumUp webhooks to Laravel routes (e.g., Route::post('/sumup/webhook', [SumupWebhookController::class, 'handle'])).
  • Middleware: Add auth middleware to protect SumUp-related routes.
• Laravel Ecosystem:
  • Queues: Use Laravel Queues for async operations (e.g., SumupPaymentJob).
  • Events: Dispatch Laravel events for SumUp actions (e.g., SumupPaymentSucceeded).
  • Notifications: Send payment confirmations via Laravel Notifications.
  • Scout/Algolia: Index customer/payment data for search.
• Testing:
  • Mocking: Use Laravel’s Mockery to test SDK interactions.
  • Factories: Create SumupPaymentFactory for seeding test data.

Migration Path

1. Phase 1: Proof of Concept (PoC)
   • Integrate the SDK into a Laravel module (e.g., app/Modules/Sumup).
   • Implement core flows: checkout, refunds, customer management.
   • Use Laravel’s Http tests to mock the SDK.
2. Phase 2: Production Readiness
   • Add error handling (e.g., retry logic for failed payments).
   • Implement webhook listeners for real-time updates.
   • Set up monitoring (e.g., Laravel Telescope for SDK logs).
3. Phase 3: Optimization
   • Replace synchronous calls with queues for long-running operations.
   • Cache frequent API calls (e.g., merchant details) using Laravel Cache.
4. Phase 4: Deprecation Migration
   • Parallel run with sumup-php SDK.
   • Gradually replace sumup-ecom-php-sdk with the new SDK in Laravel’s codebase.
   • Update tests and documentation.

Compatibility

• Laravel Versions: Tested with Laravel 5.8+ (PHP 7.2+). For older versions, pin PHP dependencies or use polyfills.
• PHP Extensions: Requires curl or guzzlehttp/guzzle (Laravel’s HttpClient uses Guzzle by default).
• Database: No direct DB requirements, but consider:
  • Storing payment metadata in Laravel’s payments table.
  • Using Laravel’s migrations to track SumUp webhook events.
• Third-Party Packages:
  • Laravel Cashier: If using subscriptions, explore Cashier’s SumUp integration (if available).
  • Spatie Fractal: For API resource transformation of SumUp responses.

Sequencing

1. Setup:
   • Install SDK: composer require sumup/sumup-ecom-php-sdk.
   • Configure Laravel’s config/services.php:

     'sumup' => [
         'app_id' => env('SUMUP_APP_ID'),
         'app_secret' => env('SUMUP_APP_SECRET'),
         'ca_bundle_path' => storage_path('certs/company-ca.pem'),
         'scopes' => ['payments', 'transactions.history'],
     ],
     

2. Core Integration:
   • Create a SumupService facade/class to wrap SDK functionality:

     class SumupService {
         public function __construct(private \SumUp\SumUp $sumup) {}
     
         public function createCheckout(float $amount, string $currency, string $reference) {
             return $this->sumup->getCheckoutService()->create($amount, $currency, $reference, config('services.sumup.merchant_code'));
         }
     }
     

   • Bind the facade to the container in AppServiceProvider.
3. Webhooks:
   • Set up a SumupWebhookController to handle SumUp’s POST requests.
   • Validate webhook signatures (SumUp provides a signature header).
4. Testing:
   • Write feature tests for checkout/refund flows.
   • Mock the SDK’s HTTP client to avoid real API calls.
5. Deployment:
   • Add SDK to `composer.json