<?php

declare(strict_types=1);

namespace apexl\Io\modules\payment\Contract;

/**
 * Gateway provides a hosted self-service billing portal (Stripe Billing
 * Portal, PayPal customer-management URL). Consumer creates a short-lived
 * session URL + redirects the customer; gateway handles plan changes /
 * payment-method updates / invoice download UI.
 *
 * Saves us building the whole subscription-management UI for any gateway
 * that ships one — typically just for Stripe in V1.
 */
interface BillingPortalInterface
{
    /**
     * Create a single-use hosted billing portal session URL.
     */
    public function createBillingPortalSession(
        string $gatewayCustomerRef,
        string $returnUrl,
    ): string;
}
