flatrender/services/identity/FlatRender.IdentitySvc/Application/Services/Interfaces/IPaymentService.cs

using FlatRender.IdentitySvc.Models.Requests;
using FlatRender.IdentitySvc.Models.Responses;

namespace FlatRender.IdentitySvc.Application.Services.Interfaces;

public interface IPaymentService
{
    Task<PagedResponse<PaymentResponse>> GetUserPaymentsAsync(Guid userId, int page, int pageSize);
    Task<PaymentResponse> GetByIdAsync(Guid paymentId, Guid userId);

    // ── ZarinPal ────────────────────────────────────────────────────────────────
    /// <summary>Calls ZarinPal request API and returns the zarinpal.com redirect URL.
    /// When the FlatRender Pay broker is configured, routes through it instead
    /// (the broker owns the single ZarinPal-verified domain pay.flatrender.ir).</summary>
    Task<string> InitiateZarinPalAsync(Guid paymentId, Guid userId);
    Task<string> HandleZarinPalCallbackAsync(string authority, string status);

    // ── FlatRender Pay broker (pay.flatrender.ir) ─────────────────────────────────
    /// <summary>Confirms a broker payment via the inquiry API and activates the plan.
    /// Called from the broker's return redirect (/v1/payments/callback/broker).</summary>
    Task<string> HandleBrokerCallbackAsync(Guid paymentId, string brokerTxnId);

    // ── SnapPay ──────────────────────────────────────────────────────────────────
    /// <summary>Calls SnapPay token API and returns the snappay.ir redirect URL.</summary>
    Task<string> InitiateSnapPayAsync(Guid paymentId, Guid userId);
    /// <summary>Handles SnapPay callback query params (paymentToken, shapSnapStatus).</summary>
    Task<string> HandleSnapPayCallbackAsync(string paymentToken, string shapStatus);

    // ── Tara ─────────────────────────────────────────────────────────────────────
    /// <summary>Calls Tara request API and returns the tara.ir redirect URL.</summary>
    Task<string> InitiateTaraAsync(Guid paymentId, Guid userId);
    /// <summary>Handles Tara callback query params (token, status).</summary>
    Task<string> HandleTaraCallbackAsync(string token, string status);

    // ── Stripe ───────────────────────────────────────────────────────────────────
    Task HandleStripeWebhookAsync(string payload, string signature);

    // ── Refunds ───────────────────────────────────────────────────────────────────
    Task<RefundResponse> IssueRefundAsync(Guid paymentId, long? amountMinor, string reason, string refundTo);
}