@criapix/saas-assinaturas-client/src/types/Payment.ts

SDK JavaScript/TypeScript para o AssinaturasService - Sistema de gestão de assinaturas SaaS com processamento de pagamentos de faturas (cartão, PIX, débito), gerenciamento de métodos de pagamento, pagamentos recorrentes e análise de falhas de pagamento

export interface CreateOneTimePaymentRequest {
  accountId: string;
  externalReference?: string;
  description?: string;
  amount: number;
  payer?: PayerInfo;
}

export interface CreateRecurringPaymentRequest {
  accountId: string;
  externalReference?: string;
  description?: string;
  amount: number;
  recurrence: RecurrenceInfo;
  payer?: PayerInfo;
}

export interface ProcessPaymentRequest {
  token: string;
  payerEmail?: string;
  paymentMethodId?: string;
}

export interface CancelPaymentRequest {
  reason?: string;
}

export interface PaymentListQuery {
  accountId?: string;
  externalReference?: string;
  status?: PaymentStatus;
  type?: PaymentType;
  page?: number;
  pageSize?: number;
}

export interface PaymentResponse {
  id: string;
  accountId: string;
  type: PaymentType;
  status: PaymentStatus;
  amount: number;
  currency: string;
  description?: string;
  externalReference?: string;
  payer?: PayerInfo;
  recurrence?: RecurrenceInfo;
  checkoutUrl?: string;
  qrCode?: string;
  qrCodeBase64?: string;
  processedAt?: string;
  approvedAt?: string;
  cancelledAt?: string;
  cancellationReason?: string;
  // Payment failure details
  failureReason?: string;
  failureCode?: string;
  canRetry?: boolean;
  suggestedAction?: string;
  retryCount?: number;
  nextRetryDate?: string;
  createdAt: string;
  updatedAt: string;
}

export interface PayerInfo {
  email?: string;
  firstName?: string;
  lastName?: string;
  identification?: IdentificationInfo;
}

export interface IdentificationInfo {
  type?: string;
  number?: string;
}

export interface RecurrenceInfo {
  frequency: string;
  frequencyInterval: number;
  startDate?: string;
  endDate?: string;
}

export enum PaymentStatus {
  Pending = 0,
  Processing = 1,
  Approved = 2,
  Rejected = 3,
  Cancelled = 4,
  Refunded = 5,
  Failed = 6,
}

export enum PaymentType {
  OneTime = 0,
  Recurring = 1,
}

/**
 * Response from invoice payment processing or payment method update
 */
export interface ProcessInvoicePaymentResponse {
  success: boolean;
  paymentId?: string;
  invoiceId: string;
  paymentStatus: string;
  externalPaymentId?: string;
  paymentMethodId?: string;
  lastFourDigits?: string;
  cardBrand?: string;
  errorMessage?: string;
  processedAt: string;

  // Failure details
  failureReason?: string;
  failureCode?: string;
  canRetry?: boolean;
  suggestedAction?: string;
  retryCount?: number;
  nextRetryDate?: string;

  // PIX-specific fields
  qrCode?: string;
  qrCodeBase64?: string;
  pixCode?: string;
  pixExpirationDate?: string;
}

/**
 * Request to process first payment after trial with card tokenization
 * Stores payment method for future recurring payments
 * Note: Uses CustomerPaymentInfo from Subscription.ts
 *
 * The cardExpiryDate field supports multiple formats:
 * - MM/YY (e.g., "11/30") - Recommended for user input
 * - MM/YYYY (e.g., "11/2030")
 * - ISO 8601 (e.g., "2030-11-30T00:00:00Z")
 *
 * The SDK automatically normalizes the date to ISO 8601 format before sending to the API.
 */
export interface ProcessFirstPaymentRequest {
  cardToken: string;
  cardHolderName: string;
  /** Card expiry date - supports MM/YY, MM/YYYY, or ISO 8601 format */
  cardExpiryDate: string;
  customer: {
    name: string;
    email: string;
    documentNumber: string; // CPF with 11 digits
    phone?: string;
    address?: string;
    city?: string;
    state?: string;
    zipCode?: string;
  };
}

/**
 * Request to process recurring payment using stored payment method
 */
export interface ProcessRecurringPaymentRequest {
  // Empty request - invoice ID comes from URL
}

/**
 * Request to process PIX payment
 * Generates QR Code for instant payment
 * Note: Uses CustomerPaymentInfo from Subscription.ts
 */
export interface ProcessPixPaymentRequest {
  customer: {
    name: string;
    email: string;
    documentNumber: string; // CPF with 11 digits
    phone?: string;
    address?: string;
    city?: string;
    state?: string;
    zipCode?: string;
  };
}

/**
 * Request to process debit card payment
 * Immediate payment, no recurring capability
 * Note: Uses CustomerPaymentInfo from Subscription.ts
 *
 * The cardExpiryDate field supports multiple formats:
 * - MM/YY (e.g., "11/30") - Recommended for user input
 * - MM/YYYY (e.g., "11/2030")
 * - ISO 8601 (e.g., "2030-11-30T00:00:00Z")
 *
 * The SDK automatically normalizes the date to ISO 8601 format before sending to the API.
 */
export interface ProcessDebitPaymentRequest {
  cardToken: string;
  cardHolderName: string;
  /** Card expiry date - supports MM/YY, MM/YYYY, or ISO 8601 format */
  cardExpiryDate: string;
  customer: {
    name: string;
    email: string;
    documentNumber: string; // CPF with 11 digits
    phone?: string;
    address?: string;
    city?: string;
    state?: string;
    zipCode?: string;
  };
}