ANTOOZA-BACKEND/Application/Abstractions/Payment/ITossPaymentService.cs

namespace Application.Abstractions.Payment;

/// <summary>
/// 토스페이먼츠 PG 결제 서비스 (V2 — api.tosspayments.com)
/// - Config DB(External.TossPayMode)에서 테스트/라이브 자동 분기
/// - Basic Auth 헤더 생성 (secretKey + ":" → Base64, BOM 없이)
/// - 승인/취소/조회 API 호출. POST 에는 Idempotency-Key(UUID v4) 부여.
/// - 통신 불명 예외(HttpRequestException/TaskCanceledException)는 삼키지 않고 전파 —
///   호출측이 NeedsReconciliation 분기(승인 통신 실패 = 결제 실패 단정 금지). (Phase 1.5)
/// </summary>
public interface ITossPaymentService
{
    /// <summary>프론트엔드에 전달할 ClientKey</summary>
    Task<TossClientConfig> GetClientConfigAsync(CancellationToken ct);

    /// <summary>결제 승인 (successUrl 콜백 후 서버에서 호출) — POST /v1/payments/confirm</summary>
    Task<TossPaymentResult> ConfirmAsync(string paymentKey, string orderID, int amount, CancellationToken ct);

    /// <summary>결제 취소 — POST /v1/payments/{paymentKey}/cancel (cancelAmount null = 전액 취소)</summary>
    Task<TossPaymentResult> CancelAsync(string paymentKey, string cancelReason, int? cancelAmount, CancellationToken ct);

    /// <summary>결제 조회 — GET /v1/payments/{paymentKey} (웹훅/대사 재확인용)</summary>
    Task<TossPaymentResult> GetPaymentAsync(string paymentKey, CancellationToken ct);
}