Sumsub Laravel Package

Technical Evaluation

Architecture Fit

• Purpose Alignment: The ax7-cmd/sumsub package is a PHP/Laravel wrapper for the SumSub API, a service for identity verification, fraud prevention, and e-signatures. It fits well in architectures requiring KYC (Know Your Customer), AML (Anti-Money Laundering), or document verification (e.g., fintech, SaaS with regulated users, or compliance-heavy applications).
• Laravel Compatibility: Leverages Laravel’s service container, HTTP client, and configuration system, making it a low-friction integration for Laravel-based apps. The package abstracts SumSub’s REST API, reducing boilerplate for OAuth, webhooks, and verification flows.
• Modularity: The package appears to support core SumSub features (verification flows, document uploads, webhook handling), but lacks explicit documentation on advanced use cases (e.g., custom workflows, bulk operations). Assess whether the package’s scope aligns with your minimum viable compliance requirements.

Integration Feasibility

• API Abstraction: The package wraps SumSub’s REST API, handling:
  • OAuth 2.0 authentication (client credentials/authorization code).
  • Verification flow management (e.g., createVerification, getVerification).
  • Webhook validation and event handling (critical for real-time compliance updates).
• Laravel-Specific Features:
  • Service Provider: Registers the SumSub client as a singleton, enabling dependency injection.
  • Configuration: Uses Laravel’s config/sumsub.php for API keys/secrets, aligning with Laravel’s conventions.
  • HTTP Client: Likely leverages Laravel’s Http facade or Guzzle under the hood (verify in code).
• Gaps:
  • Webhooks: Requires manual setup of a Laravel route/handler for SumSub’s webhook URLs. The package may not include a pre-built webhook listener (risk: missed events or duplicate handling).
  • Error Handling: Limited visibility into how SumSub API errors (e.g., rate limits, invalid requests) are surfaced to Laravel’s exception handler.
  • Testing: No visible test suite or PHPDoc examples; integration testing will be critical.

Technical Risk

Key Questions

1. Feature Coverage:
   • Does the package support all required SumSub endpoints (e.g., verifications, documents, webhooks)? If not, can gaps be filled with direct API calls?
   • Are there plans to extend the package (e.g., for SumSub’s newer features like "Video Verification")?
2. Webhook Handling:
   • How are webhook events validated (e.g., HMAC, IP whitelisting)? Is there a built-in listener?
   • What’s the retry strategy for failed webhook deliveries?
3. Error Resilience:
   • How are SumSub API errors (e.g., 429 Too Many Requests) translated into Laravel exceptions?
   • Is there support for offline queueing of verification requests?
4. Performance:
   • Does the package support async verification flows (e.g., Laravel Queues)?
   • What’s the overhead of using the wrapper vs. direct API calls?
5. Maintenance:
   • Who maintains the package? Is there a roadmap or issue tracker?
   • How will breaking changes (e.g., SumSub API updates) be handled?

Integration Approach

Stack Fit

• Laravel Ecosystem:
  • Service Container: The package integrates seamlessly with Laravel’s DI system. Bind the SumSub client in a service provider:

    $this->app->singleton(SumSubClient::class, function ($app) {
        return new SumSubClient($app['config']['sumsub.api_key']);
    });
    

  • Configuration: Store SumSub credentials in .env and config/sumsub.php:

    SUMSUB_API_KEY=your_key
    SUMSUB_WEBHOOK_SECRET=your_secret
    

  • HTTP Client: Prefer Laravel’s Http facade for consistency (if the package uses Guzzle, wrap it in a facade).
• Database:
  • Store verification IDs, user mappings, and webhook payloads in a verifications table. Example schema:

    CREATE TABLE verifications (
        id BIGINT AUTO_INCREMENT PRIMARY KEY,
        user_id BIGINT UNSIGNED, -- FK to users table
        sumsub_id VARCHAR(255), -- SumSub's verification ID
        status ENUM('pending', 'completed', 'failed'),
        metadata JSON,
        created_at TIMESTAMP
    );
    

• Queue System:
  • Use Laravel Queues to offload long-running verification processes (e.g., document review). Example job:

    class SumSubVerificationJob implements ShouldQueue {
        public function handle() {
            $verification = app(SumSubClient::class)->createVerification($user);
            // Store $verification->id in DB
        }
    }
    

Migration Path

1. Phase 1: Core Integration
   • Replace manual API calls with the package’s methods (e.g., createVerification, getVerification).
   • Implement a webhook endpoint (e.g., /sumsub/webhook) with HMAC validation.
   • Test with sandbox credentials (SumSub provides a test environment).
2. Phase 2: Error Handling & Observability
   • Log SumSub API responses/errors to a monitoring tool (e.g., Sentry, Laravel Log).
   • Add retries for transient failures (e.g., 500 errors).
3. Phase 3: Advanced Features
   • Integrate with Laravel Notifications for user status updates (e.g., "Verification pending").
   • Add a CLI command to trigger verifications or check statuses:

     Artisan::command('sumsub:verify {user}', function ($userId) {
         $verification = app(SumSubClient::class)->createVerification($userId);
         info("Initiated verification: {$verification->id}");
     });
     

Compatibility

• Laravel Versions: Verify compatibility with your Laravel version (e.g., 9.x, 10.x). If unsupported, fork and update dependencies (e.g., guzzlehttp/guzzle).
• PHP Versions: Ensure PHP 8.1+ compatibility (SumSub API may require it).
• SumSub API Changes: Monitor SumSub’s API changelog for breaking changes. Plan to:
  • Update the package or fork it if maintenance stalls.
  • Use feature flags for deprecated endpoints.

Sequencing

1. Prerequisites:
   • Set up a SumSub account and obtain API keys.
   • Configure a Laravel project with PHP 8.1+, Laravel 9+, and Composer.
2. Installation:

   composer require ax7-cmd/sumsub
   

3. Configuration:
   • Publish the package’s config:

     php artisan vendor:publish --provider="Ax7\Sumsub\SumsubServiceProvider"
     

   • Update .env with SumSub credentials.
4. Webhook Setup:
   • Add a route:

     Route::post('/sumsub/webhook', [SumsubWebhookController::class, 'handle']);
     

   • Implement HMAC validation (SumSub docs provide the secret).
5. Testing:
   • Test in SumSub’s sandbox environment.
   • Validate webhook payloads with tools like ngrok for local testing.

Operational Impact

Maintenance

• Package Updates:
  • Monitor for updates via Packagist or GitHub releases. Minor updates (e.g., bug fixes) can be applied via Composer.
  • Major updates may require testing due to SumSub API changes.
• Dependency Management:
  • Audit composer.json for bloated dependencies (e.g., unused libraries).
  • Consider pinning versions of ax7-cmd/sumsub and its dependencies to avoid surprises.
• Documentation:
  • Lack of PHPDoc or examples means you’ll need to:
    • Document internal usage (e.g., "How to trigger a verification").
    • Create runbooks for common issues (e.g., "Webhook failed: retry logic").

Support

• Vendor Lock-in:
  • The package abstracts SumSub’s API, but custom logic (e.g.,