// EN: Interface for wallet-service client — abstracts payment gateway interaction.
// VI: Interface cho wallet-service client — trừu tượng hóa tương tác cổng thanh toán.

namespace OrderService.Infrastructure.ExternalServices;

/// <summary>
/// EN: Client interface for communicating with wallet-service for payment processing.
/// VI: Interface client để giao tiếp với wallet-service cho xử lý thanh toán.
/// </summary>
public interface IWalletServiceClient
{
    /// <summary>
    /// EN: Create a payment request via wallet-service. Returns payment URL for online gateways.
    /// VI: Tạo yêu cầu thanh toán qua wallet-service. Trả về URL thanh toán cho cổng trực tuyến.
    /// </summary>
    /// <param name="orderId">EN: Order ID / VI: Mã đơn hàng</param>
    /// <param name="amount">EN: Payment amount / VI: Số tiền thanh toán</param>
    /// <param name="gateway">EN: Payment gateway (vnpay, momo) / VI: Cổng thanh toán (vnpay, momo)</param>
    /// <param name="returnUrl">EN: URL to redirect after payment / VI: URL redirect sau thanh toán</param>
    /// <param name="ipAddress">EN: Client IP address / VI: Địa chỉ IP client</param>
    /// <param name="cancellationToken">EN: Cancellation token / VI: Token hủy</param>
    /// <returns>EN: Payment creation response with URL and transaction ID / VI: Response tạo thanh toán với URL và mã giao dịch</returns>
    Task<CreatePaymentResponse?> CreatePaymentAsync(
        Guid orderId,
        decimal amount,
        string gateway,
        string returnUrl,
        string ipAddress,
        CancellationToken cancellationToken = default);
}

/// <summary>
/// EN: Response from wallet-service payment creation.
/// VI: Response từ wallet-service khi tạo thanh toán.
/// </summary>
public record CreatePaymentResponse(
    string TransactionId,
    string PaymentUrl,
    string Status
);
