Sumsub Client Laravel Package

Getting Started

Minimal Setup

1. Installation

   composer require alexeevdv/sumsub-client
   

   Add the package to config/app.php under providers (if not auto-discovered):

   Alexeevdv\SumsubClient\SumsubServiceProvider::class,
   

2. Configuration Publish the config file:

   php artisan vendor:publish --provider="Alexeevdv\SumsubClient\SumsubServiceProvider" --tag=config
   

   Update .env with your API key and secret key:

   SUMSUB_API_KEY=your_api_key_here
   SUMSUB_SECRET_KEY=your_secret_key_here
   SUMSUB_API_URL=https://api.sumsub.com
   

3. First Use Case: Verify a User

   use Alexeevdv\SumsubClient\Facades\Sumsub;
   
   $user = Sumsub::verifyUser([
       'email' => 'user@example.com',
       'firstName' => 'John',
       'lastName' => 'Doe',
       'document' => [
           'type' => 'PASSPORT',
           'file' => fopen('/path/to/passport.jpg', 'r'),
       ],
   ]);
   

Implementation Patterns

Workflows

1. User Verification Flow

   • Initiate Verification:

     $verification = Sumsub::verifyUser($userData);
     $token = $verification->getToken(); // Redirect user to Sumsub for completion
     

   • Check Status:

     $status = Sumsub::getVerificationStatus($verification->getId());
     

   • Handle Callback:

     $result = Sumsub::getVerificationResult($verification->getId());
     if ($result->isSuccess()) {
         // Grant access
     }
     

2. Webhook Integration

   • Configure webhook URL in Sumsub dashboard.
   • Handle incoming events (e.g., verification.completed):

     public function handleSumsubWebhook(Request $request) {
         $event = Sumsub::parseWebhook($request->getContent());
         // Process event (e.g., update DB, send notifications)
     }
     

3. Document Uploads

   • Stream files directly:

     $file = fopen('/path/to/document.pdf', 'r');
     $upload = Sumsub::uploadDocument($file, 'user@example.com');
     

Integration Tips

• Laravel Auth Integration: Bind verification results to users:

  $user->update(['verified_at' => now()]);
  

• Queue Delayed Tasks: Use Laravel Queues to poll verification statuses asynchronously:

  VerifyUserJob::dispatch($verificationId)->delay(now()->addMinutes(5));
  

• Error Handling: Wrap API calls in try-catch:

  try {
      $result = Sumsub::getVerificationResult($id);
  } catch (\Alexeevdv\SumsubClient\Exceptions\SumsubException $e) {
      Log::error("Sumsub error: " . $e->getMessage());
      return back()->withErrors(['verification' => 'Failed']);
  }
  

Gotchas and Tips

Pitfalls

1. API Key Exposure

   • Never commit .env or hardcode keys. Use Laravel’s .env or a secure secrets manager.
   • Tip: Restrict API key permissions in Sumsub dashboard to minimize risk.

2. File Upload Limits

   • Sumsub enforces file size limits (e.g., 10MB for documents). Validate client-side before upload:

     if ($request->file('document')->getSize() > 10 * 1024 * 1024) {
         throw new \Exception('File too large');
     }
     

3. Webhook Verification

   • Always verify webhook signatures to prevent spoofing:

     $isValid = Sumsub::verifyWebhookSignature(
         $request->getContent(),
         $request->header('X-Sumsup-Signature')
     );
     

4. Rate Limiting

   • Sumsub may throttle requests. Implement exponential backoff for retries:

     use Symfony\Component\HttpClient\RetryableHttpClient;
     
     $client = new RetryableHttpClient(
         new \Symfony\Component\HttpClient\CurlHttpClient(),
         [
             'max_retries' => 3,
             'delay_factor' => 2,
         ]
     );
     

Debugging

• Enable Debug Mode: Set SUMSUB_DEBUG=true in .env to log raw API responses.
• Common Errors:
  • 401 Unauthorized: Check API keys/secrets.
  • 422 Unprocessable Entity: Validate request data (e.g., missing firstName).
  • 500 Server Error: Contact Sumsub support (may be their issue).

Extension Points

1. Custom Verification Logic Extend the client by creating a decorator:

   class CustomSumsub extends \Alexeevdv\SumsubClient\SumsubClient {
       public function customVerify($data) {
           $data['customField'] = 'value';
           return parent::verifyUser($data);
       }
   }
   

   Bind it in AppServiceProvider:

   $this->app->bind(\Alexeevdv\SumsubClient\SumsubClient::class, function ($app) {
       return new CustomSumsub($app['config']['sumsub']);
   });
   

2. Mocking for Tests Use Laravel’s HTTP mocking:

   $this->mock(\Alexeevdv\SumsubClient\SumsubClient::class)
        ->shouldReceive('verifyUser')
        ->andReturn(new \Alexeevdv\SumsubClient\Models\Verification(['id' => 123]));
   

3. Local Testing Use Sumsub’s sandbox environment (replace SUMSUB_API_URL with https://sandbox.sumsub.com).