<?php

declare(strict_types=1);

namespace App\Services\Billing\Gateway;

use App\Models\PaymentGateway;

/** Контракт платёжного драйвера. Реализации: YooKassaDriver (далее — Tinkoff и т.п.). */
interface PaymentGatewayDriver
{
    /**
     * Создать платёж в шлюзе.
     *
     * @param  string  $amountRub  DECIMAL-строка scale 2 («500.00»).
     * @param  string  $idempotenceKey  UUID — защита от двойного создания.
     * @param  string  $returnUrl  Куда вернуть клиента после оплаты.
     * @param  array<string,mixed>|null  $receipt  Состав чека 54-ФЗ или null.
     */
    public function createPayment(
        PaymentGateway $gateway,
        string $amountRub,
        string $idempotenceKey,
        string $returnUrl,
        ?array $receipt,
    ): CreatePaymentResult;

    /**
     * Сверить платёж server-to-server по его id (статус из ответа шлюза, не из webhook).
     */
    public function verifyPayment(PaymentGateway $gateway, string $gatewayPaymentId): WebhookVerifyResult;
}
