namespace WalletService.Domain.AggregatesModel.PaymentAggregate;

/// <summary>
/// EN: Abstraction for payment gateway integrations.
/// VI: Abstraction cho tich hop cong thanh toan.
/// </summary>
/// <remarks>
/// EN: Each payment gateway (VNPay, MoMo, ZaloPay, etc.) implements this interface.
/// VI: Moi cong thanh toan (VNPay, MoMo, ZaloPay, v.v.) implement interface nay.
/// </remarks>
public interface IPaymentGateway
{
    /// <summary>
    /// EN: The name of this payment gateway.
    /// VI: Ten cua cong thanh toan nay.
    /// </summary>
    string GatewayName { get; }

    /// <summary>
    /// EN: Create a payment request and get the payment URL.
    /// VI: Tao yeu cau thanh toan va lay URL thanh toan.
    /// </summary>
    /// <param name="request">EN: Payment request details / VI: Chi tiet yeu cau thanh toan</param>
    /// <param name="cancellationToken">EN: Cancellation token / VI: Token huy</param>
    /// <returns>EN: Payment result with payment URL / VI: Ket qua thanh toan voi URL thanh toan</returns>
    Task<PaymentResult> CreatePaymentAsync(PaymentRequest request, CancellationToken cancellationToken);

    /// <summary>
    /// EN: Query the status of an existing payment transaction.
    /// VI: Truy van trang thai cua giao dich thanh toan hien co.
    /// </summary>
    /// <param name="transactionId">EN: Transaction identifier / VI: Ma giao dich</param>
    /// <param name="cancellationToken">EN: Cancellation token / VI: Token huy</param>
    /// <returns>EN: Payment result with current status / VI: Ket qua thanh toan voi trang thai hien tai</returns>
    Task<PaymentResult> QueryPaymentAsync(string transactionId, CancellationToken cancellationToken);

    /// <summary>
    /// EN: Request a refund for a completed payment.
    /// VI: Yeu cau hoan tien cho giao dich da hoan thanh.
    /// </summary>
    /// <param name="transactionId">EN: Transaction identifier / VI: Ma giao dich</param>
    /// <param name="amount">EN: Amount to refund / VI: So tien hoan</param>
    /// <param name="cancellationToken">EN: Cancellation token / VI: Token huy</param>
    /// <returns>EN: Payment result with refund status / VI: Ket qua thanh toan voi trang thai hoan tien</returns>
    Task<PaymentResult> RefundAsync(string transactionId, decimal amount, CancellationToken cancellationToken);

    /// <summary>
    /// EN: Validate a callback/IPN from the payment gateway.
    /// VI: Xac thuc callback/IPN tu cong thanh toan.
    /// </summary>
    /// <param name="parameters">EN: Callback parameters / VI: Cac tham so callback</param>
    /// <param name="secureHash">EN: Secure hash from the gateway / VI: Hash bao mat tu cong thanh toan</param>
    /// <returns>EN: True if the callback is valid / VI: True neu callback hop le</returns>
    bool ValidateCallback(IDictionary<string, string> parameters, string secureHash);
}
