FastPay SDK Architecture

Overview

The FastPay SDK is built using the Factory Pattern to provide a flexible, extensible payment processing system that supports multiple payment providers.

Architecture Diagram

┌─────────────────────────────────────────────────┐
│                   Client Code                    │
│              (new FastPay(...))                  │
└─────────────────┬───────────────────────────────┘
                  │
                  ▼
┌─────────────────────────────────────────────────┐
│              src/index.ts                        │
│          (FastPay Class)                         │
│   - constructor(config)                          │
│   - initialize()                                 │
│   - pay()                                        │
│   - static getSupportedProviders()               │
└─────────────────┬───────────────────────────────┘
                  │
                  ▼
┌─────────────────────────────────────────────────┐
│     factory/PaymentProviderFactory.ts            │
│         (Factory Pattern)                        │
│   - createProvider()                             │
│   - getSupportedProviders()                      │
└─────────────────┬───────────────────────────────┘
                  │
        ┌─────────┴─────────┐
        │                   │
        ▼                   ▼
┌───────────────┐   ┌───────────────┐
│ StripeProvider│   │ PayPalProvider│
│   (Concrete)  │   │   (Stub)      │
└───────┬───────┘   └───────┬───────┘
        │                   │
        └─────────┬─────────┘
                  │
                  ▼
    ┌─────────────────────────┐
    │  BasePaymentProvider    │
    │   (Abstract Class)      │
    │ - initialize()          │
    │ - processPayment()      │
    └─────────────────────────┘
                  │
                  ▼
    ┌─────────────────────────┐
    │   IPaymentProvider      │
    │     (Interface)         │
    └─────────────────────────┘

Directory Structure

src/
├── index.ts                    # Main entry point
├── types/
│   └── index.ts               # Type definitions and interfaces
├── providers/
│   ├── index.ts               # Provider exports
│   ├── BaseProvider.ts        # Abstract base class
│   ├── StripeProvider.ts      # Stripe implementation
│   └── PayPalProvider.ts      # PayPal stub
├── factory/
│   └── PaymentProviderFactory.ts  # Factory pattern implementation
└── utils/
    └── errors.ts              # Custom error classes

Key Components

1. Types (src/types/index.ts)

Defines all interfaces and types:

• PaymentProvider: Enum for supported providers
• PaymentConfig: Configuration interface
• PaymentResult: Result interface
• IPaymentProvider: Provider interface contract

2. Base Provider (src/providers/BaseProvider.ts)

Abstract base class that:

• Implements common validation logic
• Enforces the provider contract
• Provides extension points for concrete providers

3. Concrete Providers

StripeProvider (src/providers/StripeProvider.ts)

• Implements Stripe payment processing
• Uses @stripe/stripe-js library
• Handles initialization and checkout redirection

PayPalProvider (src/providers/PayPalProvider.ts)

• Stub for future PayPal integration
• Throws "not implemented" errors

4. Factory (src/factory/PaymentProviderFactory.ts)

Implements the Factory Pattern:

• Maps provider enum to provider classes
• Creates provider instances dynamically
• Validates provider support
• Provides list of supported providers

5. Error Utilities (src/utils/errors.ts)

Custom error classes:

• PaymentError: Base payment error
• InitializationError: Provider initialization failures
• ValidationError: Input validation failures
• ProcessingError: Payment processing failures

Design Patterns

Factory Pattern

The SDK uses the Factory Pattern to:

• Encapsulate object creation: Clients don't need to know about concrete provider classes
• Support extensibility: New providers can be added without changing client code
• Centralize provider management: Single place to register and manage providers

Strategy Pattern

The provider system implements the Strategy Pattern:

• Common interface: All providers implement IPaymentProvider
• Interchangeable implementations: Providers can be swapped at runtime
• Isolated behavior: Each provider encapsulates its own payment logic

Benefits

1. Separation of Concerns

   • Each provider handles its own logic
   • Factory manages provider creation
   • Main entry point handles orchestration

2. Extensibility

   • Add new providers by creating a new class
   • Register in factory's provider map
   • No changes to existing code

3. Type Safety

   • Strong TypeScript typing throughout
   • Interface contracts enforce consistency
   • Compile-time error checking

4. Testability

   • Each component can be tested independently
   • Easy to mock providers for testing
   • Clear boundaries between layers

5. Error Handling

   • Custom error types for different scenarios
   • Consistent error structure across providers
   • Graceful degradation

Usage Example

import FastPay, { PaymentProvider } from 'fastpay-sdk';

// Check supported providers
const providers = FastPay.getSupportedProviders();
console.log('Supported:', providers);

// Create FastPay instance
const payment = new FastPay({
  provider: PaymentProvider.STRIPE,
  publicKey: 'pk_test_...',
  sessionId: 'cs_test_...'
});

// Process payment (auto-initializes if not already initialized)
const result = await payment.pay();

if (result.success) {
  console.log('Payment initiated');
} else {
  console.error('Error:', result.error);
}

// Or manually initialize first
const payment2 = new FastPay({
  provider: PaymentProvider.STRIPE,
  publicKey: 'pk_test_...',
  sessionId: 'cs_test_...'
});

await payment2.initialize();
const result2 = await payment2.pay();

Adding a New Provider

To add a new payment provider:

1. Create provider class in src/providers/NewProvider.ts:

export class NewProvider extends BasePaymentProvider {
  async initialize(): Promise<void> {
    // Initialize provider SDK
  }

  async processPayment(sessionId: string): Promise<PaymentResult> {
    // Process payment
  }
}

2. Add to enum in src/types/index.ts:

export enum PaymentProvider {
  STRIPE = "stripe",
  PAYPAL = "paypal",
  NEW_PROVIDER = "new_provider", // Add this
}

3. Register in factory in src/factory/PaymentProviderFactory.ts:

private static providers = new Map([
  [PaymentProvider.STRIPE, StripeProvider],
  [PaymentProvider.PAYPAL, PayPalProvider],
  [PaymentProvider.NEW_PROVIDER, NewProvider], // Add this
]);

4. Export from providers in src/providers/index.ts:

export { NewProvider } from "./NewProvider";

Done! The new provider is now integrated and available.