zemailnator/app/Contracts/Payments/PaymentProviderContract.php

<?php

namespace App\Contracts\Payments;

use App\Models\Plan;
use App\Models\Subscription;
use App\Models\User;
use Illuminate\Http\Request;

interface PaymentProviderContract
{
    /**
     * Get the provider name/identifier
     */
    public function getName(): string;

    /**
     * Check if provider is properly configured and active
     */
    public function isActive(): bool;

    /**
     * Create a new subscription for a user
     */
    public function createSubscription(User $user, Plan $plan, array $options = []): array;

    /**
     * Cancel an existing subscription
     */
    public function cancelSubscription(Subscription $subscription, string $reason = ''): bool;

    /**
     * Update an existing subscription (e.g., change plan)
     */
    public function updateSubscription(Subscription $subscription, Plan $newPlan): array;

    /**
     * Pause a subscription
     */
    public function pauseSubscription(Subscription $subscription): bool;

    /**
     * Resume a paused subscription
     */
    public function resumeSubscription(Subscription $subscription): bool;

    /**
     * Get subscription details from provider
     */
    public function getSubscriptionDetails(string $providerSubscriptionId): array;

    /**
     * Create a checkout session for one-time payment
     */
    public function createCheckoutSession(User $user, Plan $plan, array $options = []): array;

    /**
     * Create a customer portal session
     */
    public function createCustomerPortalSession(User $user): array;

    /**
     * Process webhook events from provider
     */
    public function processWebhook(Request $request): array;

    /**
     * Validate webhook signature
     */
    public function validateWebhook(Request $request): bool;

    /**
     * Get provider-specific configuration
     */
    public function getConfiguration(): array;

    /**
     * Sync subscription status from provider
     */
    public function syncSubscriptionStatus(Subscription $subscription): array;

    /**
     * Get payment method details
     */
    public function getPaymentMethodDetails(string $paymentMethodId): array;

    /**
     * Handle refund
     */
    public function processRefund(string $paymentIntentId, float $amount, string $reason = ''): array;

    /**
     * Get transaction history
     */
    public function getTransactionHistory(User $user, array $filters = []): array;

    /**
     * Calculate fees for a transaction
     */
    public function calculateFees(float $amount): array;

    /**
     * Get supported currencies
     */
    public function getSupportedCurrencies(): array;

    /**
     * Check if provider supports recurring subscriptions
     */
    public function supportsRecurring(): bool;

    /**
     * Check if provider supports one-time payments
     */
    public function supportsOneTime(): bool;

    /**
     * Get provider-specific metadata for subscription
     */
    public function getSubscriptionMetadata(Subscription $subscription): array;

    /**
     * Update provider-specific metadata
     */
    public function updateSubscriptionMetadata(Subscription $subscription, array $metadata): bool;

    /**
     * Handle subscription trial
     */
    public function startTrial(Subscription $subscription, int $trialDays): bool;

    /**
     * Apply coupon/discount
     */
    public function applyCoupon(Subscription $subscription, string $couponCode): array;

    /**
     * Remove applied coupon
     */
    public function removeCoupon(Subscription $subscription): bool;

    /**
     * Get upcoming invoice details
     */
    public function getUpcomingInvoice(Subscription $subscription): array;

    /**
     * Handle failed payment retry
     */
    public function retryFailedPayment(Subscription $subscription): array;

    /**
     * Check if subscription can be modified
     */
    public function canModifySubscription(Subscription $subscription): bool;

    /**
     * Get subscription cancellation terms
     */
    public function getCancellationTerms(Subscription $subscription): array;

    /**
     * Export subscription data for migration
     */
    public function exportSubscriptionData(Subscription $subscription): array;

    /**
     * Import subscription data from another provider
     */
    public function importSubscriptionData(User $user, array $subscriptionData): array;
}