📘 E-Commerce Backend: Payment Integration

🎯 Introduction

Welcome to this exciting tutorial on building a payment integration system for e-commerce backends! 🎉 In this guide, we’ll explore how to create a secure, type-safe payment processing system using TypeScript.

You’ll discover how proper type definitions and interfaces can make your payment system robust and reliable. Whether you’re building an online store 🛒, a subscription service 📦, or a marketplace 🏪, understanding payment integration is essential for any e-commerce application.

By the end of this tutorial, you’ll feel confident building payment systems that handle real money safely! Let’s dive in! 🏊‍♂️

📚 Understanding Payment Integration

🤔 What is Payment Integration?

Payment integration is like having a secure cashier 💰 in your digital store. Think of it as a bridge between your application and payment providers (like Stripe, PayPal, or Square) that handles money transfers safely and reliably.

In TypeScript terms, payment integration involves creating type-safe interfaces for:

✨ Payment methods (cards, wallets, bank transfers)
🚀 Transaction processing and validation
🛡️ Security and error handling

💡 Why Use TypeScript for Payment Systems?

Here’s why TypeScript is perfect for payment integration:

Type Safety 🔒: Catch payment errors at compile-time
Better Documentation 📖: Types describe payment flows clearly
Refactoring Confidence 🔧: Change payment logic without fear
IDE Support 💻: Autocomplete for payment APIs

Real-world example: Imagine processing a credit card payment. With TypeScript, you can ensure all required fields are present before sending to the payment gateway!

🔧 Basic Syntax and Usage

📝 Simple Payment Types

Let’s start with fundamental payment types:

// 💳 Credit card information
interface CreditCard {
  number: string;      // 💳 Card number (encrypted!)
  expMonth: number;    // 📅 Expiration month
  expYear: number;     // 📅 Expiration year
  cvv: string;         // 🔒 Security code
  holderName: string;  // 👤 Cardholder name
}

// 💰 Payment amount
interface PaymentAmount {
  value: number;       // 💵 Amount in cents
  currency: string;    // 🌍 Currency code (USD, EUR, etc.)
  displayValue: string; // 📊 Formatted for display
}

// 🧾 Payment request
interface PaymentRequest {
  amount: PaymentAmount;
  paymentMethod: CreditCard;
  description?: string;  // 📝 Optional description
  metadata?: Record<string, any>; // 📊 Custom data
}

💡 Explanation: Notice how we store amounts in cents to avoid floating-point issues! The metadata field lets you attach custom data to payments.

🎯 Payment Status Types

Here are common payment states:

// 🚦 Payment status
type PaymentStatus = 
  | "pending"     // ⏳ Processing
  | "succeeded"   // ✅ Completed
  | "failed"      // ❌ Failed
  | "cancelled"   // 🚫 Cancelled
  | "refunded";   // 💸 Refunded

// 📊 Payment result
interface PaymentResult {
  id: string;              // 🆔 Unique payment ID
  status: PaymentStatus;   // 🚦 Current status
  amount: PaymentAmount;   // 💰 Payment amount
  createdAt: Date;         // 📅 When created
  processedAt?: Date;      // ✅ When completed
  error?: PaymentError;    // ❌ Error details
}

// ⚠️ Payment error
interface PaymentError {
  code: string;      // 🔢 Error code
  message: string;   // 💬 User-friendly message
  type: "card_error" | "api_error" | "validation_error";
}

💡 Practical Examples

🛒 Example 1: Payment Processor Class

Let’s build a real payment processor:

// 💳 Payment gateway interface
interface PaymentGateway {
  processPayment(request: PaymentRequest): Promise<PaymentResult>;
  refundPayment(paymentId: string, amount?: number): Promise<PaymentResult>;
  getPaymentStatus(paymentId: string): Promise<PaymentResult>;
}

// 🏗️ Payment processor implementation
class PaymentProcessor implements PaymentGateway {
  private apiKey: string;
  private webhookSecret: string;
  
  constructor(apiKey: string, webhookSecret: string) {
    this.apiKey = apiKey;
    this.webhookSecret = webhookSecret;
    console.log("💳 Payment processor initialized!");
  }
  
  // 💰 Process a payment
  async processPayment(request: PaymentRequest): Promise<PaymentResult> {
    console.log(`💳 Processing payment of ${request.amount.displayValue}...`);
    
    // 🔍 Validate payment request
    this.validatePaymentRequest(request);
    
    // 🚀 Simulate API call to payment gateway
    const result = await this.simulatePaymentProcessing(request);
    
    if (result.status === "succeeded") {
      console.log("✅ Payment successful!");
    } else {
      console.log(`❌ Payment failed: ${result.error?.message}`);
    }
    
    return result;
  }
  
  // 🔍 Validate payment request
  private validatePaymentRequest(request: PaymentRequest): void {
    const { amount, paymentMethod } = request;
    
    // 💰 Check amount
    if (amount.value <= 0) {
      throw new Error("❌ Payment amount must be positive!");
    }
    
    // 💳 Validate card number (basic check)
    if (!this.isValidCardNumber(paymentMethod.number)) {
      throw new Error("❌ Invalid card number!");
    }
    
    // 📅 Check expiration
    const currentDate = new Date();
    const expDate = new Date(paymentMethod.expYear, paymentMethod.expMonth - 1);
    if (expDate < currentDate) {
      throw new Error("❌ Card has expired!");
    }
  }
  
  // 💳 Basic card validation (Luhn algorithm)
  private isValidCardNumber(cardNumber: string): boolean {
    const digits = cardNumber.replace(/\s/g, '');
    return digits.length >= 13 && digits.length <= 19;
  }
  
  // 🎮 Simulate payment processing
  private async simulatePaymentProcessing(
    request: PaymentRequest
  ): Promise<PaymentResult> {
    // 🎲 Simulate random success/failure
    const isSuccessful = Math.random() > 0.1;
    
    return new Promise((resolve) => {
      setTimeout(() => {
        resolve({
          id: `pay_${Date.now()}`,
          status: isSuccessful ? "succeeded" : "failed",
          amount: request.amount,
          createdAt: new Date(),
          processedAt: isSuccessful ? new Date() : undefined,
          error: isSuccessful ? undefined : {
            code: "card_declined",
            message: "Your card was declined 💳❌",
            type: "card_error"
          }
        });
      }, 1500); // Simulate network delay
    });
  }
  
  // 💸 Refund a payment
  async refundPayment(
    paymentId: string, 
    amount?: number
  ): Promise<PaymentResult> {
    console.log(`💸 Processing refund for payment ${paymentId}...`);
    
    return {
      id: `ref_${Date.now()}`,
      status: "refunded",
      amount: {
        value: amount || 0,
        currency: "USD",
        displayValue: `$${(amount || 0) / 100}`
      },
      createdAt: new Date(),
      processedAt: new Date()
    };
  }
  
  // 📊 Get payment status
  async getPaymentStatus(paymentId: string): Promise<PaymentResult> {
    console.log(`🔍 Checking status for payment ${paymentId}...`);
    
    return {
      id: paymentId,
      status: "succeeded",
      amount: {
        value: 5000,
        currency: "USD",
        displayValue: "$50.00"
      },
      createdAt: new Date()
    };
  }
}

// 🎮 Let's use it!
const processor = new PaymentProcessor("sk_test_123", "whsec_456");

const payment: PaymentRequest = {
  amount: {
    value: 2999, // $29.99
    currency: "USD",
    displayValue: "$29.99"
  },
  paymentMethod: {
    number: "4242 4242 4242 4242",
    expMonth: 12,
    expYear: 2025,
    cvv: "123",
    holderName: "John Doe"
  },
  description: "TypeScript Course 📘"
};

// Process the payment
processor.processPayment(payment).then(result => {
  console.log("Payment result:", result);
});

🎯 Try it yourself: Add support for different payment methods like PayPal or Apple Pay!

🎮 Example 2: Subscription Management

Let’s handle recurring payments:

// 📅 Subscription plan
interface SubscriptionPlan {
  id: string;
  name: string;
  price: PaymentAmount;
  interval: "monthly" | "yearly";
  features: string[];
  emoji: string; // Every plan needs an emoji!
}

// 👤 Subscription status
interface Subscription {
  id: string;
  customerId: string;
  planId: string;
  status: "active" | "cancelled" | "past_due" | "trialing";
  currentPeriodEnd: Date;
  cancelAtPeriodEnd: boolean;
}

// 🏗️ Subscription manager
class SubscriptionManager {
  private plans: Map<string, SubscriptionPlan> = new Map();
  private subscriptions: Map<string, Subscription> = new Map();
  private paymentProcessor: PaymentProcessor;
  
  constructor(paymentProcessor: PaymentProcessor) {
    this.paymentProcessor = paymentProcessor;
    this.initializePlans();
  }
  
  // 🎯 Initialize subscription plans
  private initializePlans(): void {
    const plans: SubscriptionPlan[] = [
      {
        id: "basic",
        name: "Basic Plan",
        price: { value: 999, currency: "USD", displayValue: "$9.99" },
        interval: "monthly",
        features: ["✅ 10 products", "✅ Basic support", "✅ 1 user"],
        emoji: "🌟"
      },
      {
        id: "pro",
        name: "Pro Plan",
        price: { value: 2999, currency: "USD", displayValue: "$29.99" },
        interval: "monthly",
        features: ["✅ Unlimited products", "✅ Priority support", "✅ 5 users", "✅ Analytics"],
        emoji: "🚀"
      },
      {
        id: "enterprise",
        name: "Enterprise Plan",
        price: { value: 9999, currency: "USD", displayValue: "$99.99" },
        interval: "monthly",
        features: ["✅ Everything in Pro", "✅ Dedicated support", "✅ Unlimited users", "✅ Custom features"],
        emoji: "🏆"
      }
    ];
    
    plans.forEach(plan => {
      this.plans.set(plan.id, plan);
      console.log(`${plan.emoji} Added plan: ${plan.name}`);
    });
  }
  
  // 🛒 Subscribe to a plan
  async subscribe(
    customerId: string,
    planId: string,
    paymentMethod: CreditCard
  ): Promise<Subscription> {
    const plan = this.plans.get(planId);
    if (!plan) {
      throw new Error(`❌ Plan ${planId} not found!`);
    }
    
    console.log(`🎯 Subscribing customer ${customerId} to ${plan.name}...`);
    
    // 💳 Process initial payment
    const paymentResult = await this.paymentProcessor.processPayment({
      amount: plan.price,
      paymentMethod,
      description: `Subscription to ${plan.name}`,
      metadata: { customerId, planId }
    });
    
    if (paymentResult.status !== "succeeded") {
      throw new Error(`❌ Payment failed: ${paymentResult.error?.message}`);
    }
    
    // ✅ Create subscription
    const subscription: Subscription = {
      id: `sub_${Date.now()}`,
      customerId,
      planId,
      status: "active",
      currentPeriodEnd: this.calculatePeriodEnd(plan.interval),
      cancelAtPeriodEnd: false
    };
    
    this.subscriptions.set(subscription.id, subscription);
    console.log(`✅ Subscription created! Welcome to ${plan.name} ${plan.emoji}`);
    
    return subscription;
  }
  
  // 📅 Calculate period end date
  private calculatePeriodEnd(interval: "monthly" | "yearly"): Date {
    const date = new Date();
    if (interval === "monthly") {
      date.setMonth(date.getMonth() + 1);
    } else {
      date.setFullYear(date.getFullYear() + 1);
    }
    return date;
  }
  
  // 🚫 Cancel subscription
  cancelSubscription(subscriptionId: string, immediate: boolean = false): void {
    const subscription = this.subscriptions.get(subscriptionId);
    if (!subscription) {
      throw new Error(`❌ Subscription ${subscriptionId} not found!`);
    }
    
    if (immediate) {
      subscription.status = "cancelled";
      console.log("🚫 Subscription cancelled immediately!");
    } else {
      subscription.cancelAtPeriodEnd = true;
      console.log("📅 Subscription will cancel at period end");
    }
  }
  
  // 📊 Get subscription details
  getSubscriptionDetails(subscriptionId: string): {
    subscription: Subscription;
    plan: SubscriptionPlan;
  } | null {
    const subscription = this.subscriptions.get(subscriptionId);
    if (!subscription) return null;
    
    const plan = this.plans.get(subscription.planId);
    if (!plan) return null;
    
    return { subscription, plan };
  }
}

// 🎮 Test subscription system
const subManager = new SubscriptionManager(processor);

// Subscribe to Pro plan
subManager.subscribe("customer_123", "pro", {
  number: "4242 4242 4242 4242",
  expMonth: 12,
  expYear: 2025,
  cvv: "123",
  holderName: "Jane Smith"
}).then(subscription => {
  console.log("🎉 Subscription active:", subscription);
});

🚀 Advanced Concepts

🧙‍♂️ Webhook Handling

When you’re ready to level up, implement webhook handling:

// 🎯 Webhook event types
type WebhookEventType = 
  | "payment.succeeded"
  | "payment.failed"
  | "subscription.created"
  | "subscription.cancelled"
  | "refund.processed";

// 📦 Webhook payload
interface WebhookPayload<T = any> {
  id: string;
  type: WebhookEventType;
  data: T;
  timestamp: Date;
  signature: string;
}

// 🪄 Webhook handler
class WebhookHandler {
  private handlers: Map<WebhookEventType, Function[]> = new Map();
  
  // 📝 Register event handler
  on(event: WebhookEventType, handler: Function): void {
    const handlers = this.handlers.get(event) || [];
    handlers.push(handler);
    this.handlers.set(event, handlers);
    console.log(`🎯 Registered handler for ${event}`);
  }
  
  // 🚀 Process webhook
  async processWebhook(payload: WebhookPayload): Promise<void> {
    console.log(`📦 Processing webhook: ${payload.type}`);
    
    // 🔒 Verify signature (simplified)
    if (!this.verifySignature(payload)) {
      throw new Error("❌ Invalid webhook signature!");
    }
    
    // 🎯 Execute handlers
    const handlers = this.handlers.get(payload.type) || [];
    for (const handler of handlers) {
      await handler(payload.data);
    }
    
    console.log(`✅ Webhook processed: ${payload.type}`);
  }
  
  // 🔒 Verify webhook signature
  private verifySignature(payload: WebhookPayload): boolean {
    // In real implementation, verify HMAC signature
    return true;
  }
}

🏗️ Payment Method Tokenization

For production systems, implement tokenization:

// 🔐 Tokenized payment method
interface PaymentToken {
  token: string;        // 🔑 Secure token
  last4: string;        // 💳 Last 4 digits
  brand: string;        // 🏷️ Card brand
  expiryMonth: number;  // 📅 Expiry month
  expiryYear: number;   // 📅 Expiry year
}

// 🛡️ Tokenization service
class TokenizationService {
  // 🔐 Tokenize card details
  async tokenizeCard(card: CreditCard): Promise<PaymentToken> {
    // In real implementation, this would call a secure tokenization API
    return {
      token: `tok_${Date.now()}`,
      last4: card.number.slice(-4),
      brand: this.detectCardBrand(card.number),
      expiryMonth: card.expMonth,
      expiryYear: card.expYear
    };
  }
  
  // 🏷️ Detect card brand
  private detectCardBrand(cardNumber: string): string {
    const firstDigit = cardNumber[0];
    if (firstDigit === "4") return "Visa 💳";
    if (firstDigit === "5") return "Mastercard 💳";
    if (firstDigit === "3") return "Amex 💳";
    return "Unknown 💳";
  }
}

⚠️ Common Pitfalls and Solutions

😱 Pitfall 1: Storing Sensitive Data

// ❌ Wrong way - NEVER store sensitive data!
interface UnsafePayment {
  cardNumber: string;      // 💥 Security breach!
  cvv: string;             // 💥 PCI violation!
  customerPassword: string; // 💥 Never store passwords!
}

// ✅ Correct way - use tokens and encryption!
interface SafePayment {
  paymentToken: string;     // 🔐 Secure token
  last4Digits: string;      // 👁️ Safe for display
  customerId: string;       // 🆔 Reference only
}

🤯 Pitfall 2: Floating Point for Money

// ❌ Dangerous - floating point precision issues!
function calculateTotal(price: number, tax: number): number {
  return price + (price * tax); // 💥 0.1 + 0.2 !== 0.3
}

// ✅ Safe - use integers (cents)!
function calculateTotal(priceInCents: number, taxRate: number): number {
  const taxInCents = Math.round(priceInCents * taxRate);
  return priceInCents + taxInCents; // ✅ Precise calculation!
}

🛠️ Best Practices

🎯 Always Use HTTPS: Never process payments over unsecured connections
📝 Log Everything: Keep detailed audit trails (without sensitive data!)
🛡️ Implement Idempotency: Prevent duplicate charges with idempotency keys
🎨 Use Strong Types: Define interfaces for all payment entities
✨ Handle Errors Gracefully: Provide clear, actionable error messages

🧪 Hands-On Exercise

🎯 Challenge: Build a Payment Gateway Adapter

Create a flexible payment gateway adapter system:

📋 Requirements:

✅ Support multiple payment providers (Stripe, PayPal, Square)
🏷️ Unified interface for all providers
👤 Customer payment method management
📅 Automatic retry for failed payments
🎨 Each provider needs its own emoji!

🚀 Bonus Points:

Add fraud detection
Implement 3D Secure authentication
Create a payment dashboard

💡 Solution

🔍 Click to see solution

// 🎯 Unified payment provider interface
interface PaymentProvider {
  name: string;
  emoji: string;
  processPayment(request: PaymentRequest): Promise<PaymentResult>;
  refund(paymentId: string, amount?: number): Promise<PaymentResult>;
  supportedCurrencies: string[];
}

// 💳 Stripe provider implementation
class StripeProvider implements PaymentProvider {
  name = "Stripe";
  emoji = "🦓";
  supportedCurrencies = ["USD", "EUR", "GBP"];
  
  async processPayment(request: PaymentRequest): Promise<PaymentResult> {
    console.log(`${this.emoji} Processing with Stripe...`);
    // Stripe-specific implementation
    return {
      id: `stripe_${Date.now()}`,
      status: "succeeded",
      amount: request.amount,
      createdAt: new Date()
    };
  }
  
  async refund(paymentId: string, amount?: number): Promise<PaymentResult> {
    console.log(`${this.emoji} Refunding via Stripe...`);
    return {
      id: `stripe_ref_${Date.now()}`,
      status: "refunded",
      amount: { value: amount || 0, currency: "USD", displayValue: "$0.00" },
      createdAt: new Date()
    };
  }
}

// 💰 PayPal provider implementation
class PayPalProvider implements PaymentProvider {
  name = "PayPal";
  emoji = "🅿️";
  supportedCurrencies = ["USD", "EUR", "GBP", "CAD"];
  
  async processPayment(request: PaymentRequest): Promise<PaymentResult> {
    console.log(`${this.emoji} Processing with PayPal...`);
    return {
      id: `paypal_${Date.now()}`,
      status: "succeeded",
      amount: request.amount,
      createdAt: new Date()
    };
  }
  
  async refund(paymentId: string, amount?: number): Promise<PaymentResult> {
    console.log(`${this.emoji} Refunding via PayPal...`);
    return {
      id: `paypal_ref_${Date.now()}`,
      status: "refunded",
      amount: { value: amount || 0, currency: "USD", displayValue: "$0.00" },
      createdAt: new Date()
    };
  }
}

// 🎯 Payment gateway adapter
class PaymentGatewayAdapter {
  private providers: Map<string, PaymentProvider> = new Map();
  private retryAttempts = 3;
  
  // ➕ Register provider
  registerProvider(provider: PaymentProvider): void {
    this.providers.set(provider.name, provider);
    console.log(`✅ Registered ${provider.emoji} ${provider.name}`);
  }
  
  // 💳 Process payment with retry
  async processPayment(
    providerName: string,
    request: PaymentRequest,
    retries: number = this.retryAttempts
  ): Promise<PaymentResult> {
    const provider = this.providers.get(providerName);
    if (!provider) {
      throw new Error(`❌ Provider ${providerName} not found!`);
    }
    
    let lastError: Error | undefined;
    
    for (let attempt = 1; attempt <= retries; attempt++) {
      try {
        console.log(`🔄 Attempt ${attempt}/${retries}...`);
        const result = await provider.processPayment(request);
        
        if (result.status === "succeeded") {
          return result;
        }
        
        lastError = new Error(result.error?.message || "Payment failed");
      } catch (error) {
        lastError = error as Error;
        console.log(`⚠️ Attempt ${attempt} failed: ${lastError.message}`);
        
        if (attempt < retries) {
          await this.delay(1000 * attempt); // Exponential backoff
        }
      }
    }
    
    throw lastError || new Error("Payment failed after all retries");
  }
  
  // ⏱️ Delay helper
  private delay(ms: number): Promise<void> {
    return new Promise(resolve => setTimeout(resolve, ms));
  }
  
  // 📊 Get provider stats
  getProviderInfo(): void {
    console.log("📊 Available Payment Providers:");
    this.providers.forEach(provider => {
      console.log(`  ${provider.emoji} ${provider.name}`);
      console.log(`    Currencies: ${provider.supportedCurrencies.join(", ")}`);
    });
  }
}

// 🎮 Test the adapter system
const gateway = new PaymentGatewayAdapter();
gateway.registerProvider(new StripeProvider());
gateway.registerProvider(new PayPalProvider());

// Process a payment
gateway.processPayment("Stripe", {
  amount: { value: 4999, currency: "USD", displayValue: "$49.99" },
  paymentMethod: {
    number: "4242 4242 4242 4242",
    expMonth: 12,
    expYear: 2025,
    cvv: "123",
    holderName: "Test User"
  }
}).then(result => {
  console.log("✅ Payment processed:", result);
});

🎓 Key Takeaways

You’ve learned so much! Here’s what you can now do:

✅ Create payment systems with proper type safety 💪
✅ Handle sensitive data securely and responsibly 🛡️
✅ Implement subscriptions and recurring payments 🎯
✅ Build provider adapters for flexibility 🐛
✅ Process webhooks and async events safely! 🚀

Remember: When handling payments, security and reliability are paramount! Always follow PCI compliance guidelines. 🤝

🤝 Next Steps

Congratulations! 🎉 You’ve mastered payment integration basics!

Here’s what to do next:

💻 Build a complete checkout flow
🏗️ Integrate a real payment provider SDK
📚 Learn about PCI compliance and security
🌟 Explore advanced features like SCA and 3DS!

Remember: Every successful e-commerce platform started with someone learning payment integration. Keep building, keep learning, and most importantly, keep your customers’ data safe! 🚀

Happy coding! 🎉🚀✨

Prerequisites

What you'll learn