Laravel Sumsub Sdk Laravel Package

Technical Evaluation

Architecture fit The laravel-sumsub-sdk package (v2.2.6) remains a lightweight, domain-specific integration layer for SumSub’s identity verification API, aligning well with Laravel’s ecosystem. The addition of a SHAREHOLDER_REGISTRY document subtype expands use cases for financial/compliance workflows (e.g., KYC for shareholder onboarding) without altering core architecture. The package’s event-driven design (e.g., webhook handling) and Laravel service provider pattern ensure minimal intrusion into existing systems.

Integration feasibility

• Low effort: The new subtype is additive—no schema changes required for existing integrations. Existing configurations (e.g., .env credentials, middleware) remain unchanged.
• Dependency risk: No breaking changes to the SDK’s core (HTTP client, response parsing). However, downstream services consuming sumsub:verified events may need to handle the new subtype in business logic (e.g., workflow routing).
• Testing scope: Validate subtype-specific error handling (e.g., SumSub\Exceptions\InvalidDocumentType) in edge cases (e.g., malformed payloads).

Technical risk

• Minimal: The change is backward-compatible and isolated to SumSub’s document validation layer. Risk lies in:
  • Event consumers: Unhandled subtypes may trigger silent failures or require manual intervention.
  • Rate limits: High-volume SHAREHOLDER_REGISTRY submissions could stress SumSub’s API if not throttled (e.g., via Laravel’s throttle middleware).
• Mitigation: Add subtype-specific logging (e.g., SumSubLogger::info('Processing SHAREHOLDER_REGISTRY')) and unit tests for event dispatching.

Key questions

1. Does our application use SumSub’s webhook events for automation (e.g., user provisioning)? If so, how will the new subtype be routed?
2. Are there existing rate-limiting mechanisms for SumSub API calls? If not, should we implement middleware to prevent throttling?
3. Does the compliance team require additional audit trails for this subtype? If yes, extend the package’s logging or add a custom trait (e.g., SumSubAuditTrait).

Integration Approach

Stack fit

• Laravel 8+/9+: Fully compatible. The package leverages Laravel’s service container and events, requiring no framework upgrades.
• PHP 8.0+: No changes; the new feature uses native PHP types (e.g., string for subtype names).
• SumSub API v2: The subtype maps directly to SumSub’s document types, so no API contract changes are needed.

Migration path

1. Zero-downtime: Deploy the updated package (composer require shureban/laravel-sumsub-sdk:^2.2.6) without code changes.
2. Feature flagging (optional): For gradual rollout, wrap subtype usage in a config flag (e.g., config('sumsub.enable_shareholder_registry')) and monitor via Sentry/New Relic.
3. Testing:
   • Unit: Mock SumSub’s API response with the new subtype to verify event dispatching.
   • Integration: Test end-to-end flows (e.g., file upload → verification → webhook).

Compatibility

• Backward: 100%. Existing code using SumSub::verify() or SumSub::check() remains unchanged.
• Forward: The package’s config/sumsub.php may need an optional allowed_document_subtypes array to explicitly whitelist/blacklist subtypes (recommend adding this proactively).

Sequencing

1. Phase 1: Update package and test locally with mock SumSub responses.
2. Phase 2: Deploy to staging and validate webhook events for the new subtype.
3. Phase 3: Monitor production for subtype-specific errors (e.g., SumSub\Exceptions\ValidationException).

Operational Impact

Maintenance

• Package updates: Monitor for future SumSub API changes (e.g., deprecated subtypes). The package’s Updater class simplifies version bumps.
• Documentation: Update internal runbooks to include SHAREHOLDER_REGISTRY in:
  • Error handling guides (e.g., "Rejected due to invalid subtype").
  • Onboarding flows for compliance teams.

Support

• Common issues:
  • Misconfigured subtypes: Add a SumSub::validateDocumentSubtype() helper to pre-check subtypes before API calls.
  • Webhook failures: Ensure the sumsub.webhook queue listener handles the new subtype (e.g., via a polymorphic event handler).
• SLA impact: None. The change is additive, but support tickets may rise for subtype-specific questions.

Scaling

• Performance: Negligible impact. The subtype adds ~50ms to document validation (SumSub’s API response time).
• Database: No schema changes, but consider adding a document_subtype column to verification logs if auditing is required.
• Cost: Potential increase in SumSub API calls if the subtype triggers additional verification steps (e.g., manual review). Track usage via SumSub’s analytics dashboard.

Failure modes

Ramp-up

• Developer onboarding: Add a 10-minute example to the team’s internal docs showing how to:

  // Handle the new subtype in a webhook listener
  public function handle(Verified $event) {
      if ($event->document->subtype === 'SHAREHOLDER_REGISTRY') {
          $this->routeToComplianceWorkflow($event->user);
      }
  }
  

• Compliance training: Highlight the subtype’s purpose (e.g., "Used for SEC-compliant shareholder KYC") and any new reporting requirements.
• Rollback plan: Downgrade the package (composer require v2.2.5) if SumSub’s API behavior changes unexpectedly (unlikely, but monitor their changelog).