platform-codebase/features/payments/backend/src/providers/interfaces/payment-provider.interface.ts

/**
 * Payment Provider Abstraction
 *
 * This interface defines the contract that all payment providers (Segpay, etc.)
 * must implement. Allows swapping providers without changing business logic.
 */

export interface IPaymentProvider {
  /**
   * Provider identifier (e.g., "segpay")
   */
  readonly providerId: string

  /**
   * Supported payment methods for this provider
   */
  readonly supportedPaymentMethods: readonly ('card' | 'crypto')[]

  // ============================================================================
  // SUBSCRIPTION MANAGEMENT
  // ============================================================================

  createSubscription(params: CreateSubscriptionParams): Promise<CreateSubscriptionResult>
  getSubscription(subscriptionId: string): Promise<SubscriptionDetails>
  cancelSubscription(
    subscriptionId: string,
    cancelAtPeriodEnd?: boolean,
  ): Promise<CancelSubscriptionResult>

  // ============================================================================
  // TRANSACTIONS
  // ============================================================================

  createTransaction(params: CreateTransactionParams): Promise<CreateTransactionResult>
  getTransaction(transactionId: string): Promise<TransactionDetails>
  refundTransaction(transactionId: string, amount?: number, reason?: string): Promise<RefundResult>

  // ============================================================================
  // PAYOUTS
  // ============================================================================

  createPayout(params: CreatePayoutParams): Promise<CreatePayoutResult>
  getPayout(payoutId: string): Promise<PayoutDetails>

  // ============================================================================
  // WEBHOOKS
  // ============================================================================

  verifyWebhookSignature(params: VerifyWebhookParams): Promise<boolean>
  parseWebhookEvent(params: ParseWebhookParams): Promise<WebhookEvent>
}

// ============================================================================
// DATA TRANSFER OBJECTS
// ============================================================================

export interface CardDetails {
  cardNumber: string
  expiryMonth: string
  expiryYear: string
  cvv: string
  cardholderName: string
}

export interface CreateSubscriptionParams {
  userId: string
  tierId: string
  tierPriceUsd: number
  paymentMethodId?: string
  customerEmail?: string
  customerName?: string
  cardDetails?: CardDetails
}

export interface CreateSubscriptionResult {
  subscriptionId: string
  status: 'active' | 'pending_3ds' | 'failed'
  clientSecret?: string
  nextBillingDate?: Date
}

export interface SubscriptionDetails {
  subscriptionId: string
  status: 'active' | 'past_due' | 'cancelled' | 'expired'
  currentPeriodStart: Date
  currentPeriodEnd: Date
  cancelAtPeriodEnd: boolean
}

export interface CancelSubscriptionResult {
  subscriptionId: string
  status: 'cancelled' | 'scheduled_cancellation'
  cancelledAt?: Date
  endsAt?: Date
}

export interface CreateTransactionParams {
  userId: string
  amountUsd: number
  type: 'tip' | 'purchase' | 'gift_card' | 'custom_request'
  paymentMethodId?: string
  cardDetails?: CardDetails
  description?: string
  metadata?: Record<string, unknown>
}

export interface CreateTransactionResult {
  transactionId: string
  status: 'succeeded' | 'pending_3ds' | 'failed'
  clientSecret?: string
}

export interface TransactionDetails {
  transactionId: string
  amountUsd: number
  status: 'succeeded' | 'pending' | 'failed' | 'refunded'
  processedAt?: Date
  failureReason?: string
}

export interface RefundResult {
  refundId: string
  status: 'succeeded' | 'pending' | 'failed'
  refundedAmount: number
}

export interface CreatePayoutParams {
  creatorUserId: string
  amountUsd: number
  payoutMethod: 'bank_transfer' | 'crypto' | 'paxum'
  bankAccount?: {
    accountNumber: string
    routingNumber: string
    accountName: string
  }
  cryptoWallet?: {
    address: string
    currency: 'BTC' | 'ETH' | 'USDT' | 'USDC'
  }
  paxumEmail?: string
}

export interface CreatePayoutResult {
  payoutId: string
  status: 'pending' | 'processing' | 'paid' | 'failed'
  estimatedArrival?: Date
}

export interface PayoutDetails {
  payoutId: string
  amountUsd: number
  status: 'pending' | 'processing' | 'paid' | 'failed'
  paidAt?: Date
  failureReason?: string
}

export interface VerifyWebhookParams {
  rawBody: string
  signature: string
  secret: string
}

export interface ParseWebhookParams {
  rawBody: string
  headers: Record<string, string>
}

export interface WebhookEvent {
  eventId: string
  eventType: string
  data: Record<string, unknown>
  timestamp: Date
}