Sumsub Laravel Package

Getting Started

Minimal Setup

1. Installation

   composer require ax7-cmd/sumsub
   

   Publish the config file:

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

   Configure .env with your SumSub API credentials:

   SUMSUB_API_KEY=your_api_key_here
   SUMSUB_SECRET_KEY=your_secret_key_here
   

2. First Use Case: Verification Flow Initialize the client in a service or controller:

   use Ax7\Sumsub\Facades\Sumsub;
   
   $verification = Sumsub::verification()->create([
       'token' => 'user_unique_token',
       'flowId' => 'id_doc', // or 'id_video', 'id_phone', etc.
       'email' => 'user@example.com',
       'phone' => '+1234567890', // optional
       'firstName' => 'John',
       'lastName' => 'Doe',
   ]);
   

3. Key Files to Review

   • config/sumsub.php: API endpoints, default settings.
   • src/Facades/Sumsub.php: Main facade for quick access.
   • src/Exceptions/: Custom exceptions (e.g., SumsubException).

Implementation Patterns

Workflow: User Verification Pipeline

1. Initiate Verification Use the facade or service container to trigger a flow:

   $verification = Sumsub::verification()->create([
       'token' => Str::uuid()->toString(),
       'flowId' => 'id_doc',
       // ...other fields
   ]);
   

   Store the token in your DB to track status later.

2. Poll for Status Check verification status periodically (e.g., via queue job):

   $status = Sumsub::verification()->getStatus($token);
   

   Handle states like pending, completed, or failed.

3. Webhook Handling Configure a route to handle SumSub webhooks (e.g., /sumsub/webhook):

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

   Use the SumsubWebhook class to validate and parse payloads:

   use Ax7\Sumsub\SumsubWebhook;
   
   public function handle(Request $request) {
       $webhook = new SumsubWebhook($request->getContent());
       if ($webhook->isValid()) {
           $event = $webhook->getEvent();
           // Process event (e.g., update DB, send notifications)
       }
   }
   

4. Document Upload/Download For document flows, handle file attachments:

   // Upload a document (e.g., passport)
   $filePath = 'path/to/document.pdf';
   $document = Sumsub::document()->upload($filePath, $token);
   
   // Download a verified document
   $file = Sumsub::document()->download($documentId);
   

Integration Tips

• Laravel Queues: Offload status checks to a queue (e.g., VerificationsCheckJob).
• Events: Dispatch custom events (e.g., VerificationCompleted) for decoupled handling.
• Middleware: Protect routes with verified() middleware:

  public function handle($request, Closure $next) {
      if (!Sumsub::verification()->isVerified($request->user()->token)) {
          abort(403);
      }
      return $next($request);
  }
  

Gotchas and Tips

Pitfalls

1. Token Management

   • Issue: Reusing tokens for multiple flows can cause conflicts.
   • Fix: Generate unique tokens per user/flow (e.g., user_id_flow_type).

2. Webhook Validation

   • Issue: SumSub’s webhook payloads must be validated with the secretKey.
   • Fix: Always use SumsubWebhook::isValid() before processing.

3. Rate Limits

   • Issue: Exceeding API calls (e.g., rapid status checks) may trigger rate limits.
   • Fix: Implement exponential backoff in polling logic.

4. Flow Expiry

   • Issue: Verification flows expire after ~7 days (configurable via expireIn in config).
   • Fix: Notify users before expiry or auto-reinitiate flows.

Debugging

• Enable Logging Add to config/sumsub.php:

  'debug' => env('SUMSUB_DEBUG', false),
  

  Logs will appear in storage/logs/laravel.log.

• API Response Inspection Use Sumsub::getLastResponse() to debug raw API responses:

  $response = Sumsub::verification()->create([...]);
  if ($response->failed()) {
      logger()->error(Sumsub::getLastResponse());
  }
  

Extension Points

1. Custom Flows Extend the Flow class to add domain-specific logic:

   namespace App\Services;
   
   use Ax7\Sumsub\Flow;
   
   class CustomFlow extends Flow {
       public function __construct() {
           parent::__construct('custom_flow_id');
       }
   
       public function getAdditionalData() {
           return ['custom_field' => 'value'];
       }
   }
   

2. Webhook Extensions Override the SumsubWebhook class to add custom event handlers:

   namespace App\Services;
   
   use Ax7\Sumsub\SumsubWebhook;
   
   class CustomWebhook extends SumsubWebhook {
       protected function handleEvent($event) {
           if ($event['type'] === 'verification.completed') {
               // Custom logic
           }
       }
   }
   

3. Mocking for Tests Use the SumsubMock trait in tests:

   use Ax7\Sumsub\Tests\SumsubMock;
   
   class VerificationTest {
       use SumsubMock;
   
       public function test_verification_flow() {
           $this->mockSumsubResponse('verification.create', ['token' => 'test_token']);
           // Test logic
       }
   }
   

Config Quirks

• Endpoint Overrides Customize API endpoints in config/sumsub.php:

  'endpoints' => [
      'verification' => 'https://custom-api.sumsub.com/verification',
  ],
  

• Default Flow ID Set a default flow ID to avoid specifying it repeatedly:

  'default_flow_id' => 'id_doc',