README

A comprehensive Laravel package for KYC (Know Your Customer) verification management. This package provides a clean, extensible architecture for integrating multiple KYC providers with automatic infrastructure routes and provider-agnostic status mapping.

✨ Key Features

🚀 Zero-Config Infrastructure: Webhook routes automatically registered - no setup required!
🔄 Provider-Agnostic Architecture: Seamlessly switch between KYC providers (ShuftiPro, Jumio, Onfido, etc.)
🎯 Driver-Based Status Mapping: Each provider handles its own event-to-status mapping
📡 Auto-Registered Routes: Infrastructure routes work out-of-the-box
🎪 Event-Driven: Comprehensive event system for verification lifecycle
📊 Smart Status Management: Intelligent status tracking and transitions
📁 Document Management: Built-in document storage and retrieval
🔒 Secure Webhooks: Signature validation and comprehensive logging
✅ Built-in Validation: Request validation and user eligibility checks
🔍 Comprehensive Logging: Detailed logging for debugging and monitoring
🔗 Morphable Models: Works with any Eloquent model using morphable relationships

Installation

composer require asciisd/kyc-core

Configuration

Publish the configuration file:

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

Publish the migrations:

php artisan vendor:publish --tag=kyc-migrations

Run the migrations:

php artisan migrate

🚀 Automatic Infrastructure Routes

NEW! The package now automatically registers infrastructure routes - no manual setup required!

Auto-Registered Routes

When you install the package, these routes are automatically available:

// Webhook endpoints (no authentication required)
POST   /api/kyc/webhook                 // Main webhook handler
POST   /api/kyc/webhook/callback        // Alternative webhook endpoint
GET    /api/kyc/verification/complete   // Verification completion callback
GET    /api/kyc/health                  // Health check endpoint

// Backward compatibility (without /api prefix)
POST   /kyc/webhook
POST   /kyc/webhook/callback
GET    /kyc/verification/complete
GET    /kyc/health

Benefits

✅ Zero Configuration - Works immediately after installation
✅ Consistent Behavior - Same webhook handling across all applications
✅ Provider Agnostic - Works with any KYC driver
✅ Automatic Updates - Bug fixes and improvements benefit all apps
✅ Simplified Integration - Focus on business logic, not infrastructure

Health Check

Monitor your KYC system health:

curl https://yourdomain.com/api/kyc/health

{
    "success": true,
    "message": "KYC infrastructure is healthy",
    "default_driver": "shuftipro",
    "available_drivers": ["shuftipro", "jumio", "onfido"],
    "enabled_drivers": ["shuftipro"]
}

🚀 Quick Start

Minimal Setup (3 Steps!)

Install the package

composer require asciisd/kyc-core asciisd/kyc-shuftipro

Publish and run migrations

php artisan vendor:publish --tag=kyc-migrations
php artisan migrate

Add trait to your User model

use Asciisd\KycCore\Traits\HasKycVerification;

class User extends Model
{
    use HasKycVerification;
}

That's it! 🎉 Infrastructure routes are automatically registered. Just configure your KYC provider credentials and start verifying users.

Usage

Basic Usage

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

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

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

// Process webhook
$webhookResponse = Kyc::processWebhook($payload, $headers);

Model Integration

Add the trait to your User model:

use Asciisd\KycCore\Traits\HasKycVerification;

class User extends Model
{
    use HasKycVerification;

    // Your model code...
}

Now you can use KYC methods on your user:

// Check if user can start KYC
if ($user->canStartKyc()) {
    // Start verification process
}

// Check if user has completed KYC
if ($user->hasCompletedKyc()) {
    // User is verified
}

// Get current KYC status
$status = $user->getKycStatus();

Events

The package fires several events you can listen to:

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

// Listen for events
Event::listen(VerificationStarted::class, function ($event) {
    Log::info('Verification started for user: ' . $event->user->id);
});

Status Management

The package includes a comprehensive status enum:

use Asciisd\KycCore\Enums\KycStatusEnum;

// Check status properties
if ($status->isCompleted()) {
    // Handle completed verification
}

if ($status->needsAction()) {
    // User needs to take action
}

// Get human-readable label
$label = $status->label(); // "KYC Completed"
$color = $status->color(); // "green"

🏗️ Advanced Driver Architecture

The package uses a sophisticated driver-based architecture with provider-specific status mapping:

interface KycDriverInterface
{
    // Core verification methods
    public function createVerification(Model $user, KycVerificationRequest $request): KycVerificationResponse;
    public function retrieveVerification(string $reference): KycVerificationResponse;
    public function processWebhook(array $payload, array $headers = []): KycVerificationResponse;
    public function downloadDocuments(Model $user, string $reference): array;

    // Driver information
    public function getName(): string;
    public function isEnabled(): bool;
    public function getCapabilities(): array;

    // 🆕 NEW: Provider-specific status mapping
    public function mapEventToStatus(string $event): KycStatusEnum;
}

🎯 Provider-Specific Status Mapping

Each driver handles its own event-to-status mapping, making the system truly provider-agnostic:

// ShuftiPro Driver
public function mapEventToStatus(string $event): KycStatusEnum
{
    return match ($event) {
        'verification.completed' => KycStatusEnum::Completed,
        'verification.declined' => KycStatusEnum::Rejected,
        'verification.pending' => KycStatusEnum::InProgress,
        // ... ShuftiPro-specific events
    };
}

// Jumio Driver (example)
public function mapEventToStatus(string $event): KycStatusEnum
{
    return match ($event) {
        'SUCCESS' => KycStatusEnum::Completed,
        'ERROR' => KycStatusEnum::VerificationFailed,
        'INITIATED' => KycStatusEnum::InProgress,
        // ... Jumio-specific events
    };
}

Benefits

✅ Provider Independence - Each provider handles its own event mapping
✅ Easy Migration - Switch providers without changing application logic
✅ Extensible - Add new providers by implementing the interface
✅ Consistent - Standardized KYC status across all providers

Configuration

The package configuration allows you to:

Set default driver
Configure multiple drivers
Set verification settings
Define supported/restricted countries
Configure document storage

// config/kyc.php
return [
    'default_driver' => 'shuftipro',
    'drivers' => [
        'shuftipro' => [
            'enabled' => true,
            'class' => 'Asciisd\\KycShuftiPro\\Drivers\\ShuftiProDriver',
            // ...
        ],
    ],
    'settings' => [
        'require_email_verification' => true,
        'max_verification_attempts' => 3,
        // ...
    ],
];

Testing

composer test

Contributing

Please see CONTRIBUTING.md for details.

License

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

asciisd / kyc-core

Maintainers

Details

README

✨ Key Features

Installation

Configuration

🚀 Automatic Infrastructure Routes

Auto-Registered Routes

Benefits

Health Check

🚀 Quick Start

Minimal Setup (3 Steps!)

Usage

Basic Usage

Model Integration

Events

Status Management

🏗️ Advanced Driver Architecture

🎯 Provider-Specific Status Mapping

Benefits

Configuration

Testing

Contributing

License