feat: add manual payout request functionality

Add requestPayout method to InstantPayoutService for organizations to
request manual payouts with validation for amount, minimum threshold,
and pending payout checks. Also add hasPendingPayout method to
CommissionableContract interface.

Author: Just Chris

src/Contracts/CommissionableContract.php

@@ -109,4 +109,9 @@ public function requestPayout(): ?Payout;
      * Determine if a payout can be requested.
      */
     public function canRequestPayout(): bool;
+
+    /**
+     * Check if this entity has a pending payout.
+     */
+    public function hasPendingPayout(): bool;
 }

src/Services/InstantPayoutService.php

@@ -25,6 +25,100 @@ public function __construct(
         private CommissionCalculator $calculator,
     ) {}
 
+    /**
+     * Request a manual payout for an organization.
+     */
+    public function requestPayout(
+        Model&CommissionableContract $organization,
+        ?int $amount = null,
+        ?PayoutMethodEnum $method = null,
+    ): Payout {
+        $available = $organization->pendingPayoutAmount();
+        $amount ??= $available;
+
+        // Validate amount
+        if ($amount <= 0) {
+            throw PayoutFailedException::insufficientFunds(available: $available, requested: $amount);
+        }
+
+        if ($amount > $available) {
+            throw PayoutFailedException::insufficientFunds(available: $available, requested: $amount);
+        }
+
+        // Check minimum payout amount
+        /** @var int $minPayout */
+        $minPayout = config('billing.marketplace.commission.min_payout_amount', 1000);
+
+        if ($amount < $minPayout) {
+            throw PayoutFailedException::belowMinimum(amount: $amount, minimum: $minPayout);
+        }
+
+        // Check for pending payout
+        if ($organization->hasPendingPayout()) {
+            throw new PayoutFailedException('A payout is already pending for this organization');
+        }
+
+        // Validate payout details
+        $phone = $organization->getPayoutPhone();
+        $name = $organization->getPayoutName();
+
+        if ($phone === null || $phone === '') {
+            throw PayoutFailedException::missingPayoutDetails();
+        }
+
+        /** @var string $currency */
+        $currency = config('billing.marketplace.commission.currency', 'XOF');
+
+        $payoutData = new PayoutData(
+            amount: $amount,
+            currency: $currency,
+            method: $method ?? PayoutMethodEnum::MobileMoney,
+            recipientPhone: $phone,
+            recipientName: $name,
+            periodStart: new DateTimeImmutable('now'),
+            periodEnd: new DateTimeImmutable('now'),
+            metadata: [
+                'manual_request' => true,
+                'requested_at' => (new DateTimeImmutable('now'))->format('Y-m-d H:i:s'),
+            ],
+        );
+
+        // Create the payout record
+        $payout = $organization->createPayout($payoutData, [
+            'provider' => config('billing.default'),
+        ]);
+
+        // Execute via provider if it supports payouts
+        /** @var string $providerName */
+        $providerName = config('billing.default');
+        $provider = $this->billing->provider($providerName);
+
+        if ($provider instanceof PayoutProvider) {
+            try {
+                $result = $provider->createPayout($payoutData);
+
+                if (isset($result['payout_id'])) {
+                    $payout->markAsProcessing($result['payout_id']);
+                }
+
+                if (isset($result['status']) && $result['status'] === 'completed') {
+                    $payout->markAsCompleted();
+                    event(new PayoutCompleted($payout));
+                }
+            } catch (Throwable $throwable) {
+                $payout->markAsFailed($throwable->getMessage());
+                event(new PayoutFailed($payout, $throwable->getMessage()));
+
+                throw new PayoutFailedException(
+                    message: 'Payout request failed: '.$throwable->getMessage(),
+                    previous: $throwable,
+                );
+            }
+        }
+
+        return $payout->fresh() ?? $payout;
+    }
+
     /**
      * Process an instant payout for a completed transaction.
      */