feat: implement comprehensive multi-provider payment processing system

- Add unified payment provider architecture with contract-based design
  - Implement 6 payment providers: Stripe, Lemon Squeezy, Polar, Oxapay, Crypto, Activation Keys
  - Create subscription management with lifecycle handling (create, cancel, pause, resume, update)
  - Add coupon system with usage tracking and trial extensions
  - Build Filament admin resources for payment providers, subscriptions, coupons, and trials
  - Implement payment orchestration service with provider registry and configuration management
  - Add comprehensive payment logging and webhook handling for all providers
  - Create customer analytics dashboard with revenue, churn, and lifetime value metrics
  - Add subscription migration service for provider switching
  - Include extensive test coverage for all payment functionality

database/factories/CouponFactory.php

@@ -0,0 +1,107 @@
+<?php
+
+namespace Database\Factories;
+
+use Illuminate\Database\Eloquent\Factories\Factory;
+
+/**
+ * @extends \Illuminate\Database\Eloquent\Factories\Factory<\App\Models\Coupon>
+ */
+class CouponFactory extends Factory
+{
+    /**
+     * Define the model's default state.
+     *
+     * @return array<string, mixed>
+     */
+    public function definition(): array
+    {
+        $type = fake()->randomElement(['percentage', 'fixed']);
+        $value = $type === 'percentage'
+            ? fake()->numberBetween(5, 50)
+            : fake()->randomFloat(2, 5, 100);
+
+        return [
+            'code' => strtoupper(fake()->lexify('??????')),
+            'name' => fake()->words(3, true),
+            'description' => fake()->sentence(),
+            'type' => $type,
+            'value' => $value,
+            'minimum_amount' => fake()->optional(0.7)->randomFloat(2, 10, 500),
+            'max_uses' => fake()->optional(0.6)->numberBetween(10, 1000),
+            'uses_count' => 0,
+            'max_uses_per_user' => fake()->optional(0.5)->numberBetween(1, 5),
+            'starts_at' => fake()->optional(0.3)->dateTimeBetween('-1 week', 'now'),
+            'expires_at' => fake()->optional(0.8)->dateTimeBetween('now', '+6 months'),
+            'is_active' => true,
+            'metadata' => fake()->optional(0.2)->randomElements([
+                'created_by_admin' => fake()->boolean(),
+                'campaign' => fake()->word(),
+                'region' => fake()->countryCode(),
+            ]),
+        ];
+    }
+
+    /**
+     * Create a percentage-based coupon
+     */
+    public function percentage(): static
+    {
+        return $this->state(fn (array $attributes) => [
+            'type' => 'percentage',
+            'value' => fake()->numberBetween(5, 50),
+        ]);
+    }
+
+    /**
+     * Create a fixed amount coupon
+     */
+    public function fixed(): static
+    {
+        return $this->state(fn (array $attributes) => [
+            'type' => 'fixed',
+            'value' => fake()->randomFloat(2, 5, 100),
+        ]);
+    }
+
+    /**
+     * Create an expired coupon
+     */
+    public function expired(): static
+    {
+        return $this->state(fn (array $attributes) => [
+            'expires_at' => fake()->dateTimeBetween('-1 month', '-1 day'),
+        ]);
+    }
+
+    /**
+     * Create an inactive coupon
+     */
+    public function inactive(): static
+    {
+        return $this->state(fn (array $attributes) => [
+            'is_active' => false,
+        ]);
+    }
+
+    /**
+     * Create a coupon with usage limits
+     */
+    public function withUsageLimit(): static
+    {
+        return $this->state(fn (array $attributes) => [
+            'max_uses' => fake()->numberBetween(10, 100),
+            'max_uses_per_user' => fake()->numberBetween(1, 3),
+        ]);
+    }
+
+    /**
+     * Create a coupon with minimum amount requirement
+     */
+    public function withMinimumAmount(): static
+    {
+        return $this->state(fn (array $attributes) => [
+            'minimum_amount' => fake()->randomFloat(2, 25, 200),
+        ]);
+    }
+}

database/factories/CouponUsageFactory.php

@@ -0,0 +1,32 @@
+<?php
+
+namespace Database\Factories;
+
+use Illuminate\Database\Eloquent\Factories\Factory;
+
+/**
+ * @extends \Illuminate\Database\Eloquent\Factories\Factory<\App\Models\CouponUsage>
+ */
+class CouponUsageFactory extends Factory
+{
+    /**
+     * Define the model's default state.
+     *
+     * @return array<string, mixed>
+     */
+    public function definition(): array
+    {
+        return [
+            'coupon_id' => Coupon::factory(),
+            'user_id' => \App\Models\User::factory(),
+            'subscription_id' => \App\Models\Subscription::factory(),
+            'discount_amount' => fake()->randomFloat(2, 5, 50),
+            'currency' => 'USD',
+            'used_at' => fake()->dateTimeBetween('-3 months', 'now'),
+            'metadata' => fake()->optional(0.2)->randomElements([
+                'ip_address' => fake()->ipv4(),
+                'user_agent' => fake()->userAgent(),
+            ]),
+        ];
+    }
+}

database/factories/PaymentProviderFactory.php

@@ -0,0 +1,23 @@
+<?php
+
+namespace Database\Factories;
+
+use Illuminate\Database\Eloquent\Factories\Factory;
+
+/**
+ * @extends \Illuminate\Database\Eloquent\Factories\Factory<\App\Models\PaymentProvider>
+ */
+class PaymentProviderFactory extends Factory
+{
+    /**
+     * Define the model's default state.
+     *
+     * @return array<string, mixed>
+     */
+    public function definition(): array
+    {
+        return [
+            //
+        ];
+    }
+}

database/factories/SubscriptionChangeFactory.php

@@ -0,0 +1,53 @@
+<?php
+
+namespace Database\Factories;
+
+use Illuminate\Database\Eloquent\Factories\Factory;
+
+/**
+ * @extends \Illuminate\Database\Eloquent\Factories\Factory<\App\Models\SubscriptionChange>
+ */
+class SubscriptionChangeFactory extends Factory
+{
+    /**
+     * Define the model's default state.
+     *
+     * @return array<string, mixed>
+     */
+    public function definition(): array
+    {
+        $changeType = fake()->randomElement([
+            'plan_change', 'cancellation', 'pause', 'resume', 'migration', 'provider_change',
+        ]);
+
+        return [
+            'subscription_id' => \App\Models\Subscription::factory(),
+            'user_id' => \App\Models\User::factory(),
+            'change_type' => $changeType,
+            'change_description' => fake()->sentence(),
+            'old_values' => fake()->optional(0.7)->randomElement([
+                ['plan_id' => fake()->numberBetween(1, 5), 'price' => fake()->randomFloat(2, 10, 100)],
+                ['status' => 'active', 'provider' => 'stripe'],
+            ]),
+            'new_values' => fake()->optional(0.7)->randomElement([
+                ['plan_id' => fake()->numberBetween(1, 5), 'price' => fake()->randomFloat(2, 10, 100)],
+                ['status' => 'cancelled', 'provider' => 'lemon_squeezy'],
+            ]),
+            'reason' => fake()->optional(0.6)->randomElement([
+                'Customer request',
+                'Payment failure',
+                'Plan upgrade',
+                'Service downgrade',
+                'Technical migration',
+            ]),
+            'effective_at' => fake()->dateTimeBetween('-1 month', 'now'),
+            'processed_at' => fake()->optional(0.8)->dateTimeBetween('-1 month', 'now'),
+            'is_processed' => fake()->boolean(80),
+            'metadata' => fake()->optional(0.2)->randomElements([
+                'processed_by' => fake()->name(),
+                'system_generated' => fake()->boolean(),
+                'batch_id' => fake()->uuid(),
+            ]),
+        ];
+    }
+}

database/factories/TrialExtensionFactory.php

@@ -0,0 +1,45 @@
+<?php
+
+namespace Database\Factories;
+
+use Illuminate\Database\Eloquent\Factories\Factory;
+
+/**
+ * @extends \Illuminate\Database\Eloquent\Factories\Factory<\App\Models\TrialExtension>
+ */
+class TrialExtensionFactory extends Factory
+{
+    /**
+     * Define the model's default state.
+     *
+     * @return array<string, mixed>
+     */
+    public function definition(): array
+    {
+        $originalEnd = fake()->dateTimeBetween('now', '+14 days');
+        $extensionDays = fake()->numberBetween(1, 30);
+        $newEnd = (new \DateTime($originalEnd->format('Y-m-d')))->modify("+{$extensionDays} days");
+
+        return [
+            'subscription_id' => \App\Models\Subscription::factory(),
+            'user_id' => \App\Models\User::factory(),
+            'extension_days' => $extensionDays,
+            'reason' => fake()->optional(0.7)->randomElement([
+                'Customer request',
+                'Technical issues',
+                'Service outage compensation',
+                'Goodwill gesture',
+                'Payment processing delay',
+            ]),
+            'extension_type' => fake()->randomElement(['manual', 'automatic', 'compensation']),
+            'original_trial_ends_at' => $originalEnd,
+            'new_trial_ends_at' => $newEnd,
+            'granted_at' => fake()->dateTimeBetween('-1 week', 'now'),
+            'granted_by_admin_id' => \App\Models\User::factory(),
+            'metadata' => fake()->optional(0.2)->randomElements([
+                'notes' => fake()->sentence(),
+                'approval_ticket' => fake()->numerify('TCK-#####'),
+            ]),
+        ];
+    }
+}

database/migrations/2025_11_18_110315_create_payment_events_table.php

@@ -0,0 +1,47 @@
+<?php
+
+use Illuminate\Database\Migrations\Migration;
+use Illuminate\Database\Schema\Blueprint;
+use Illuminate\Support\Facades\Schema;
+
+return new class extends Migration
+{
+    /**
+     * Run the migrations.
+     */
+    public function up(): void
+    {
+        Schema::create('payment_events', function (Blueprint $table) {
+            $table->id();
+            $table->string('event_type', 100);
+            $table->string('level', 20)->default('info');
+            $table->json('data');
+            $table->nullableMorphs('user');
+            $table->string('request_id')->nullable();
+            $table->string('ip_address', 45)->nullable();
+            $table->text('user_agent')->nullable();
+            $table->timestamp('expires_at')->nullable();
+            $table->timestamps();
+
+            // Indexes for performance
+            $table->index(['event_type', 'created_at']);
+            $table->index(['user_type', 'user_id', 'created_at']);
+            $table->index(['level', 'created_at']);
+            $table->index('expires_at');
+            $table->index('request_id');
+
+            // Full-text index for searching data (if supported)
+            if (config('database.default') === 'mysql') {
+                $table->fullText('data');
+            }
+        });
+    }
+
+    /**
+     * Reverse the migrations.
+     */
+    public function down(): void
+    {
+        Schema::dropIfExists('payment_events');
+    }
+};

database/migrations/2025_11_18_110548_create_payment_providers_table.php

@@ -0,0 +1,45 @@
+<?php
+
+use Illuminate\Database\Migrations\Migration;
+use Illuminate\Database\Schema\Blueprint;
+use Illuminate\Support\Facades\Schema;
+
+return new class extends Migration
+{
+    /**
+     * Run the migrations.
+     */
+    public function up(): void
+    {
+        Schema::create('payment_providers', function (Blueprint $table) {
+            $table->id();
+            $table->string('name', 50)->unique();
+            $table->string('display_name');
+            $table->text('description')->nullable();
+            $table->boolean('is_active')->default(true);
+            $table->json('configuration');
+            $table->boolean('supports_recurring')->default(false);
+            $table->boolean('supports_one_time')->default(true);
+            $table->json('supported_currencies')->default('[]');
+            $table->string('webhook_url')->nullable();
+            $table->string('webhook_secret')->nullable();
+            $table->json('fee_structure')->nullable();
+            $table->integer('priority')->default(0);
+            $table->boolean('is_fallback')->default(false);
+            $table->timestamps();
+
+            // Indexes
+            $table->index('is_active');
+            $table->index('priority');
+            $table->index('is_fallback');
+        });
+    }
+
+    /**
+     * Reverse the migrations.
+     */
+    public function down(): void
+    {
+        Schema::dropIfExists('payment_providers');
+    }
+};

database/migrations/2025_11_18_110634_add_unified_payment_fields_to_subscriptions_table.php

@@ -0,0 +1,76 @@
+<?php
+
+use Illuminate\Database\Migrations\Migration;
+use Illuminate\Database\Schema\Blueprint;
+use Illuminate\Support\Facades\Schema;
+
+return new class extends Migration
+{
+    /**
+     * Run the migrations.
+     */
+    public function up(): void
+    {
+        Schema::table('subscriptions', function (Blueprint $table) {
+            // Provider tracking
+            $table->string('provider', 50)->default('stripe')->after('user_id');
+            $table->string('provider_subscription_id')->nullable()->after('stripe_id');
+
+            // Unified status tracking
+            $table->string('unified_status', 50)->default('active')->after('stripe_status');
+            $table->timestamp('cancelled_at')->nullable()->after('trial_ends_at');
+            $table->string('cancellation_reason')->nullable()->after('cancelled_at');
+            $table->timestamp('paused_at')->nullable()->after('cancellation_reason');
+            $table->timestamp('resumed_at')->nullable()->after('paused_at');
+
+            // Migration tracking
+            $table->string('migration_batch_id')->nullable()->after('resumed_at');
+            $table->boolean('is_migrated')->default(false)->after('migration_batch_id');
+            $table->json('legacy_data')->nullable()->after('is_migrated');
+
+            // Sync and audit
+            $table->timestamp('synced_at')->nullable()->after('legacy_data');
+            $table->json('provider_data')->nullable()->after('synced_at');
+            $table->timestamp('last_provider_sync')->nullable()->after('provider_data');
+
+            // Indexes
+            $table->index('provider');
+            $table->index('provider_subscription_id');
+            $table->index('unified_status');
+            $table->index('is_migrated');
+            $table->index('migration_batch_id');
+            $table->index('synced_at');
+        });
+    }
+
+    /**
+     * Reverse the migrations.
+     */
+    public function down(): void
+    {
+        Schema::table('subscriptions', function (Blueprint $table) {
+            $table->dropIndex(['provider']);
+            $table->dropIndex(['provider_subscription_id']);
+            $table->dropIndex(['unified_status']);
+            $table->dropIndex(['is_migrated']);
+            $table->dropIndex(['migration_batch_id']);
+            $table->dropIndex(['synced_at']);
+
+            $table->dropColumn([
+                'provider',
+                'provider_subscription_id',
+                'unified_status',
+                'cancelled_at',
+                'cancellation_reason',
+                'paused_at',
+                'resumed_at',
+                'migration_batch_id',
+                'is_migrated',
+                'legacy_data',
+                'synced_at',
+                'provider_data',
+                'last_provider_sync',
+            ]);
+        });
+    }
+};

database/migrations/2025_11_18_120425_add_plan_id_to_subscriptions_table.php

@@ -0,0 +1,31 @@
+<?php
+
+use Illuminate\Database\Migrations\Migration;
+use Illuminate\Database\Schema\Blueprint;
+use Illuminate\Support\Facades\Schema;
+
+return new class extends Migration
+{
+    /**
+     * Run the migrations.
+     */
+    public function up(): void
+    {
+        Schema::table('subscriptions', function (Blueprint $table) {
+            $table->foreignId('plan_id')->nullable()->after('user_id')->constrained()->nullOnDelete();
+            $table->string('status', 50)->default('active')->after('unified_status');
+            $table->timestamp('starts_at')->nullable()->after('ends_at');
+        });
+    }
+
+    /**
+     * Reverse the migrations.
+     */
+    public function down(): void
+    {
+        Schema::table('subscriptions', function (Blueprint $table) {
+            $table->dropForeign(['plan_id']);
+            $table->dropColumn(['plan_id', 'status', 'starts_at']);
+        });
+    }
+};

database/migrations/2025_11_19_090057_create_coupons_table.php

@@ -0,0 +1,43 @@
+<?php
+
+use Illuminate\Database\Migrations\Migration;
+use Illuminate\Database\Schema\Blueprint;
+use Illuminate\Support\Facades\Schema;
+
+return new class extends Migration
+{
+    /**
+     * Run the migrations.
+     */
+    public function up(): void
+    {
+        Schema::create('coupons', function (Blueprint $table) {
+            $table->id();
+            $table->string('code')->unique();
+            $table->string('name');
+            $table->text('description')->nullable();
+            $table->enum('type', ['percentage', 'fixed']);
+            $table->decimal('value', 10, 2);
+            $table->decimal('minimum_amount', 10, 2)->nullable();
+            $table->integer('max_uses')->nullable();
+            $table->integer('uses_count')->default(0);
+            $table->integer('max_uses_per_user')->nullable();
+            $table->timestamp('starts_at')->nullable();
+            $table->timestamp('expires_at')->nullable();
+            $table->boolean('is_active')->default(true);
+            $table->json('metadata')->nullable();
+            $table->timestamps();
+
+            $table->index(['code', 'is_active']);
+            $table->index(['expires_at', 'is_active']);
+        });
+    }
+
+    /**
+     * Reverse the migrations.
+     */
+    public function down(): void
+    {
+        Schema::dropIfExists('coupons');
+    }
+};

database/migrations/2025_11_19_090110_create_coupon_usages_table.php

@@ -0,0 +1,37 @@
+<?php
+
+use Illuminate\Database\Migrations\Migration;
+use Illuminate\Database\Schema\Blueprint;
+use Illuminate\Support\Facades\Schema;
+
+return new class extends Migration
+{
+    /**
+     * Run the migrations.
+     */
+    public function up(): void
+    {
+        Schema::create('coupon_usages', function (Blueprint $table) {
+            $table->id();
+            $table->foreignId('coupon_id')->constrained()->onDelete('cascade');
+            $table->foreignId('user_id')->constrained()->onDelete('cascade');
+            $table->foreignId('subscription_id')->nullable()->constrained()->onDelete('cascade');
+            $table->decimal('discount_amount', 10, 2);
+            $table->string('currency', 3)->default('USD');
+            $table->timestamp('used_at');
+            $table->json('metadata')->nullable();
+            $table->timestamps();
+
+            $table->index(['coupon_id', 'user_id']);
+            $table->index(['user_id', 'used_at']);
+        });
+    }
+
+    /**
+     * Reverse the migrations.
+     */
+    public function down(): void
+    {
+        Schema::dropIfExists('coupon_usages');
+    }
+};

database/migrations/2025_11_19_090138_create_trial_extensions_table.php

@@ -0,0 +1,40 @@
+<?php
+
+use Illuminate\Database\Migrations\Migration;
+use Illuminate\Database\Schema\Blueprint;
+use Illuminate\Support\Facades\Schema;
+
+return new class extends Migration
+{
+    /**
+     * Run the migrations.
+     */
+    public function up(): void
+    {
+        Schema::create('trial_extensions', function (Blueprint $table) {
+            $table->id();
+            $table->foreignId('subscription_id')->constrained()->onDelete('cascade');
+            $table->foreignId('user_id')->constrained()->onDelete('cascade');
+            $table->integer('extension_days');
+            $table->string('reason')->nullable();
+            $table->enum('extension_type', ['manual', 'automatic', 'compensation']);
+            $table->timestamp('original_trial_ends_at');
+            $table->timestamp('new_trial_ends_at');
+            $table->timestamp('granted_at');
+            $table->foreignId('granted_by_admin_id')->nullable()->constrained('users')->onDelete('set null');
+            $table->json('metadata')->nullable();
+            $table->timestamps();
+
+            $table->index(['subscription_id', 'extension_type']);
+            $table->index(['user_id', 'granted_at']);
+        });
+    }
+
+    /**
+     * Reverse the migrations.
+     */
+    public function down(): void
+    {
+        Schema::dropIfExists('trial_extensions');
+    }
+};

database/migrations/2025_11_19_090154_create_subscription_changes_table.php

@@ -0,0 +1,42 @@
+<?php
+
+use Illuminate\Database\Migrations\Migration;
+use Illuminate\Database\Schema\Blueprint;
+use Illuminate\Support\Facades\Schema;
+
+return new class extends Migration
+{
+    /**
+     * Run the migrations.
+     */
+    public function up(): void
+    {
+        Schema::create('subscription_changes', function (Blueprint $table) {
+            $table->id();
+            $table->foreignId('subscription_id')->constrained()->onDelete('cascade');
+            $table->foreignId('user_id')->constrained()->onDelete('cascade');
+            $table->enum('change_type', ['plan_change', 'cancellation', 'pause', 'resume', 'migration', 'provider_change']);
+            $table->string('change_description');
+            $table->json('old_values')->nullable();
+            $table->json('new_values')->nullable();
+            $table->string('reason')->nullable();
+            $table->timestamp('effective_at');
+            $table->timestamp('processed_at')->nullable();
+            $table->boolean('is_processed')->default(false);
+            $table->json('metadata')->nullable();
+            $table->timestamps();
+
+            $table->index(['subscription_id', 'change_type']);
+            $table->index(['user_id', 'effective_at']);
+            $table->index(['is_processed', 'processed_at']);
+        });
+    }
+
+    /**
+     * Reverse the migrations.
+     */
+    public function down(): void
+    {
+        Schema::dropIfExists('subscription_changes');
+    }
+};

database/migrations/2025_11_19_125140_make_stripe_fields_nullable_in_subscriptions_table.php

@@ -0,0 +1,34 @@
+<?php
+
+use Illuminate\Database\Migrations\Migration;
+use Illuminate\Database\Schema\Blueprint;
+use Illuminate\Support\Facades\Schema;
+
+return new class extends Migration
+{
+    /**
+     * Run the migrations.
+     */
+    public function up(): void
+    {
+        Schema::table('subscriptions', function (Blueprint $table) {
+            // Make Stripe-specific fields nullable for unified payment system
+            $table->string('stripe_id')->nullable()->change();
+            $table->string('stripe_status')->nullable()->change();
+            $table->string('stripe_price')->nullable()->change();
+        });
+    }
+
+    /**
+     * Reverse the migrations.
+     */
+    public function down(): void
+    {
+        Schema::table('subscriptions', function (Blueprint $table) {
+            // Revert Stripe fields back to NOT NULL
+            $table->string('stripe_id')->nullable(false)->change();
+            $table->string('stripe_status')->nullable(false)->change();
+            $table->string('stripe_price')->nullable(false)->change();
+        });
+    }
+};