README

A Laravel package that provides ShuftiPro integration for the Asciisd KYC Core package. Features automatic webhook handling, provider-specific status mapping, and zero-config infrastructure routes.

Package Information

Package: asciisd/kyc-shuftipro
Latest Version: v1.0.0
PHP Requirements: ^8.2
Laravel Requirements: ^12.0
License: MIT

✨ Features

🚀 Zero-Config Setup: Automatic webhook routes - no manual configuration needed!
🎯 Smart Status Mapping: ShuftiPro-specific event mapping to standardized KYC statuses
🔄 Complete Integration: Full API integration with ShuftiPro services
🛣️ Journey Support: Support for both IDV journeys and direct API verification
📁 Document Management: Automatic document download and storage
🔒 Secure Webhooks: Signature validation and comprehensive logging
🖼️ Image Processing: Support for document images, selfies, and verification videos
🔍 Duplicate Detection: Built-in duplicate account detection
📊 Comprehensive Logging: Detailed logging for debugging and monitoring
⚡ Auto-Infrastructure: Webhook endpoints automatically registered by KYC Core

Installation

composer require asciisd/kyc-shuftipro

Configuration

Publish the configuration file:

php artisan vendor:publish --tag=shuftipro-config

Environment Variables

Add these variables to your .env file:

# ShuftiPro API Configuration
SHUFTIPRO_CLIENT_ID=your_client_id
SHUFTIPRO_SECRET_KEY=your_secret_key
SHUFTIPRO_BASE_URL=https://api.shuftipro.com

# ShuftiPro Webhook Configuration
SHUFTIPRO_WEBHOOK_SECRET=your_webhook_secret
SHUFTIPRO_CALLBACK_URL=https://yourdomain.com/webhooks/kyc/callback
SHUFTIPRO_REDIRECT_URL=https://yourdomain.com/kyc/complete

# ShuftiPro Journey Configuration
SHUFTIPRO_DEFAULT_JOURNEY_ID=your_journey_id

# ShuftiPro Logging
SHUFTIPRO_LOGGING_ENABLED=true
SHUFTIPRO_LOG_CHANNEL=daily

Usage

Basic Verification

use Asciisd\KycCore\Facades\Kyc;
use Asciisd\KycCore\DTOs\KycVerificationRequest;

// Create a simple verification
$response = Kyc::createSimpleVerification($user, [
    'country' => 'US',
    'language' => 'en'
]);

// Create a full verification request
$request = new KycVerificationRequest(
    email: 'user@example.com',
    country: 'US',
    language: 'en',
    journeyId: 'your_journey_id'
);

$response = Kyc::createVerification($user, $request);

Journey-based Verification

// Use a specific journey ID
$request = new KycVerificationRequest(
    email: 'user@example.com',
    journeyId: 'your_custom_journey_id',
    allowedCountries: ['US', 'CA', 'GB'],
    deniedCountries: ['IR', 'KP']
);

$response = Kyc::createVerification($user, $request);

🚀 Automatic Webhook Handling

NEW! Webhooks are now handled automatically - no manual route setup required!

Auto-Registered Webhook Routes

The KYC Core package automatically registers these routes:

POST   /api/kyc/webhook                 // ✅ Use this URL in ShuftiPro dashboard
POST   /api/kyc/webhook/callback        // ✅ Alternative webhook endpoint
GET    /api/kyc/verification/complete   // ✅ Verification completion callback

ShuftiPro Configuration

Simply configure your ShuftiPro webhook URL to:

SHUFTIPRO_CALLBACK_URL=https://yourdomain.com/api/kyc/webhook

Benefits

✅ Zero Setup - Works immediately after installation
✅ Automatic Processing - Webhooks processed with proper status mapping
✅ Secure - Built-in signature validation
✅ Logged - Comprehensive logging for debugging
✅ Consistent - Same behavior across all applications

Manual Webhook Processing (Optional)

If you need custom webhook handling:

// Optional: Custom webhook processing
$response = Kyc::processWebhook($request->all(), $request->headers->all());

if ($response->isSuccessful()) {
    // Custom logic after successful verification
}

Document Management

// Download documents for a user
$documents = Kyc::downloadDocuments($user, $reference);

// The documents are automatically stored in your configured storage disk

Configuration

API Configuration

// config/shuftipro.php
'api' => [
    'client_id' => env('SHUFTIPRO_CLIENT_ID'),
    'secret_key' => env('SHUFTIPRO_SECRET_KEY'),
    'base_url' => env('SHUFTIPRO_BASE_URL', 'https://api.shuftipro.com'),
    'timeout' => env('SHUFTIPRO_TIMEOUT', 30),
],

Webhook Configuration

'webhook' => [
    'secret_key' => env('SHUFTIPRO_WEBHOOK_SECRET'),
    'callback_url' => env('SHUFTIPRO_CALLBACK_URL'),
    'redirect_url' => env('SHUFTIPRO_REDIRECT_URL'),
    'signature_validation' => env('SHUFTIPRO_WEBHOOK_SIGNATURE_VALIDATION', true),
],

Document Configuration

'documents' => [
    'auto_download' => env('SHUFTIPRO_AUTO_DOWNLOAD_DOCUMENTS', true),
    'storage_disk' => env('SHUFTIPRO_DOCUMENT_STORAGE_DISK', 's3'),
    'storage_path' => env('SHUFTIPRO_DOCUMENT_STORAGE_PATH', 'shuftipro/documents'),
    'allowed_types' => ['jpg', 'jpeg', 'png', 'pdf', 'mp4'],
    'max_file_size' => env('SHUFTIPRO_MAX_FILE_SIZE', 10485760), // 10MB
],

Supported Features

Document Types

Identity documents (passport, driver's license, national ID)
Address verification documents
Selfie verification
Video verification
Verification reports

Verification Methods

IDV Journey verification
Direct API verification
Custom journey configurations
Country-specific verification rules

Security Features

Webhook signature validation
Secure document storage
Duplicate account detection
Comprehensive audit logging

Events

The package fires standard KYC events that you can listen to:

use Asciisd\KycCore\Events\VerificationStarted;
use Asciisd\KycCore\Events\VerificationCompleted;
use Asciisd\KycCore\Events\VerificationFailed;

Event::listen(VerificationCompleted::class, function ($event) {
    // Handle successful verification
    Log::info('ShuftiPro verification completed for user: ' . $event->user->id);
});

Error Handling

The package includes comprehensive error handling:

use Asciisd\KycShuftiPro\Exceptions\ShuftiProException;

try {
    $response = Kyc::createVerification($user, $request);
} catch (ShuftiProException $e) {
    // Handle ShuftiPro-specific errors
    Log::error('ShuftiPro error: ' . $e->getMessage());
}

Testing

composer test

🎯 ShuftiPro Status Mapping

The driver automatically maps ShuftiPro events to standardized KYC statuses:

// ShuftiPro Event → KYC Status
'request.pending'           → RequestPending
'verification.pending'      → InProgress
'verification.in_progress'  → InProgress
'verification.review_pending' → ReviewPending
'verification.completed'    → Completed
'verification.approved'     → Completed
'verification.accepted'     → VerificationCompleted
'verification.failed'       → VerificationFailed
'verification.declined'     → Rejected
'verification.cancelled'    → VerificationCancelled
'request.timeout'          → RequestTimeout

Benefits

✅ Automatic Mapping - No manual status handling required
✅ Standardized - Consistent status across all KYC providers
✅ Provider-Specific - Handles ShuftiPro's unique event names
✅ Extensible - Easy to add new event mappings

API Reference

ShuftiProDriver Methods

createVerification(Model $user, KycVerificationRequest $request): KycVerificationResponse
createSimpleVerification(Model $user, array $options = []): KycVerificationResponse
retrieveVerification(string $reference): KycVerificationResponse
processWebhook(array $payload, array $headers = []): KycVerificationResponse
downloadDocuments(Model $user, string $reference): array
validateWebhookSignature(array $payload, array $headers): bool

Response Data

The package returns comprehensive verification data including:

Verification status and results
Extracted document data
Document image URLs
Verification video URLs
Duplicate detection results
Decline reasons (if applicable)

Contributing

Please see CONTRIBUTING.md for details.

License

The MIT License (MIT). Please see License File for more information.

asciisd / kyc-shuftipro

Maintainers

Details

README

Package Information

✨ Features

Installation

Configuration

Environment Variables

Usage

Basic Verification

Journey-based Verification

🚀 Automatic Webhook Handling

Auto-Registered Webhook Routes

ShuftiPro Configuration

Benefits

Manual Webhook Processing (Optional)

Document Management

Configuration

API Configuration

Webhook Configuration

Document Configuration

Supported Features

Document Types

Verification Methods

Security Features

Events

Error Handling

Testing

🎯 ShuftiPro Status Mapping

Benefits

API Reference

ShuftiProDriver Methods

Response Data

Contributing

License