Sumsub Client Laravel Package

Technical Evaluation

Architecture Fit

• Use Case Alignment: The alexeevdv/sumsub-client package is a SumSub API wrapper, ideal for applications requiring identity verification, document authentication, or KYC (Know Your Customer) workflows. It fits well in:
  • B2B SaaS platforms (e.g., onboarding users with ID verification).
  • Fintech/RegTech (compliance-heavy applications).
  • Marketplaces (seller verification, fraud prevention).
• Laravel Synergy: Leverages Laravel’s HTTP client (Guzzle under the hood) and service container, enabling seamless dependency injection and configuration.
• Microservice Potential: Can be abstracted into a dedicated service layer (e.g., VerificationService) for loose coupling.

Integration Feasibility

• API Abstraction: Wraps SumSub’s REST API, reducing boilerplate for:
  • Session creation (e.g., startVerification()).
  • Webhook handling (e.g., verifyWebhookSignature()).
  • Document uploads (e.g., uploadDocument()).
• Laravel-Specific Features:
  • Configurable via .env: Supports SUMSUB_SECRET_KEY, SUMSUB_WEBHOOK_SECRET.
  • Event Dispatching: Can trigger Laravel events (e.g., VerificationCompleted) for async processing.
  • Queue Jobs: SumSub operations (e.g., long-running verifications) can be offloaded to queues.
• Database Integration: Requires a schema to store:
  • Verification sessions (verification_sessions table).
  • User-SumSub mappings (users ↔ sumsub_users).
  • Webhook payloads (for replay safety).

Technical Risk

Key Questions

1. Authentication Flow:
   • Will users verify via embedded widgets (SumSub-hosted) or custom UI (self-hosted)?
   • How will session tokens be stored (e.g., Redis vs. DB)?
2. Webhook Security:
   • Is HMAC validation sufficient, or needed additional checks (e.g., IP whitelisting)?
3. Fallback Mechanisms:
   • What’s the offline workflow if SumSub’s API is down (e.g., manual review)?
4. Compliance:
   • Does the app need audit logs for verification events (e.g., GDPR/CCPA)?
5. Cost Optimization:
   • Are there bulk verification discounts or caching strategies for repeated checks?

Integration Approach

Stack Fit

• Laravel Ecosystem:
  • HTTP Client: Replace direct Guzzle calls with Laravel’s Http facade for consistency.
  • Events/Listeners: Dispatch VerificationStarted, VerificationFailed events.
  • Queues: Use sumsub:verify-job for async operations (e.g., document processing).
  • Testing: Mock SumSub API with Pest/Mockery or Laravel Dusk for UI flows.
• Database:
  • Eloquent Models:

    class VerificationSession extends Model {
        public function user() { return $this->belongsTo(User::class); }
        public function documents() { return $this->hasMany(VerificationDocument::class); }
    }
    

  • Migrations:

    Schema::create('verification_sessions', function (Blueprint $table) {
        $table->id();
        $table->string('sumsub_session_id')->unique();
        $table->foreignId('user_id')->constrained();
        $table->json('metadata');
        $table->timestamps();
    });
    

• Frontend:
  • Blade Components: Render SumSub’s iframe widget with dynamic sessionId.
  • Livewire/Alpine: For real-time status updates (e.g., "Verification in progress").

Migration Path

1. Phase 1: Proof of Concept (1–2 weeks)
   • Integrate the package in a sandbox environment.
   • Test basic flows (e.g., ID upload → verification → result).
   • Validate webhook signatures and payload parsing.
2. Phase 2: Core Integration (2–3 weeks)
   • Build Eloquent models and service layer.
   • Implement queue jobs for async operations.
   • Add error handling and retries.
3. Phase 3: Production Readiness (1 week)
   • Monitoring: Set up Laravel Horizon for queue jobs + SumSub API logs.
   • Rollback Plan: Feature flag for gradual rollout.
   • Documentation: Internal runbook for troubleshooting (e.g., "SumSub API Timeout").

Compatibility

• Laravel Versions: Tested on Laravel 8+ (PHP 7.4+). Use laravel/framework package constraints.
• PHP Extensions: Requires openssl (for HMAC) and fileinfo (for document validation).
• SumSub API: Ensure compatibility with current API version (check sumsub/sdk for breaking changes).
• Third-Party Dependencies:
  • Conflict risk with other Guzzle-based packages? → Use PSR-18 compliant interfaces.

Sequencing

1. Prerequisites:
   • SumSub developer account and API keys.
   • Laravel project with HTTP client, queues, and database.
2. Critical Path:
   • Step 1: Install package (composer require alexeevdv/sumsub-client).
   • Step 2: Configure .env and publish config (php artisan vendor:publish).
   • Step 3: Implement VerificationService facade.
   • Step 4: Set up webhook route (/sumsub/webhook) with middleware.
3. Parallel Tasks:
   • Frontend widget integration (can happen concurrently).
   • Database schema design (blocking only for core tables).

Operational Impact

Maintenance

• Package Updates:
  • Monitor for SumSub SDK updates (e.g., breaking changes in sumsub/sdk).
  • Use dependency updates in CI (e.g., GitHub Actions) to catch deprecations early.
• Configuration Drift:
  • Centralize SumSub settings in Laravel config (e.g., config/sumsub.php) for easy overrides.
• Deprecation Strategy:
  • If SumSub sunsets an endpoint, abstract behind an interface to swap implementations.

Support

• Common Issues:
  • Webhook Failures: Log payloads + signatures; implement dead-letter queue.
  • Rate Limits: Add exponential backoff in retries.
  • Document Rejections: Notify users via Laravel Notifications (email/SMS).
• Debugging Tools:
  • Laravel Telescope: Track verification events.
  • SumSub Dashboard: Cross-reference API logs.
• SLA Impact:
  • SumSub’s API uptime (SLA: [check their status page]) may affect user onboarding.

Scaling

• Performance Bottlenecks:
  • API Calls: Batch verifications where possible (e.g., bulk uploads).
  • Database: Index sumsub_session_id and user_id in verification_sessions.
• Horizontal Scaling:
  • Stateless operations (e.g., webhook handling) scale naturally.
  • Queue Workers: Scale Laravel queues for async jobs.
• Cost Scaling:
  • SumSub pricing is usage-based (e.g., per verification). Monitor with Laravel Cashier or custom analytics.

Failure Modes