<?php
/**
 * BookiFlex Core
 *
 * @package    BookiFlex
 * @subpackage Core
 * @author     BookiFlex
 * @copyright  Copyright (c) 2025 BookiFlex
 * @license    GPL-2.0-or-later
 *
 * @link       https://bookiflex.com
 */


declare(strict_types=1);
namespace BookiFlex\Core\Contract\Payment;

defined( 'ABSPATH' ) || exit;

/**
 * Turns a payment into a customer-facing redirect URL for a given gateway.
 *
 * Abstracts the payment *initiation* seam so different back-ends (Payum,
 * WooCommerce, ...) can produce a redirect URL without the caller knowing how.
 * Status synchronization is intentionally NOT part of this contract: the
 * mechanisms differ too much (Payum callbacks vs WooCommerce WP hooks) and both
 * converge on the shared domain operations instead.
 */
interface PaymentProcessorInterface
{
    /**
     * Processor identifier, e.g. 'payum' or 'woocommerce'.
     */
    public function getName(): string;

    /**
     * Whether this processor handles the given gateway name.
     */
    public function supports(string $gatewayName): bool;

    /**
     * URL to redirect the customer to in order to complete (capture) the payment.
     */
    public function createCaptureUrl(PaymentInterface $payment, string $gatewayName): string;

    /**
     * URL to redirect the customer to in order to authorize the payment.
     */
    public function createAuthorizeUrl(PaymentInterface $payment, string $gatewayName): string;

    /**
     * URL to redirect the customer to in order to cancel the payment.
     */
    public function createCancelUrl(PaymentInterface $payment, string $gatewayName): string;
}