Firebase TypeScript Stripe API

A complete, production-ready Stripe API integration for Firebase projects that eliminates CORS issues and provides full type safety.

🎯 Features

• ✅ 100% Stripe API Coverage - All 87 Stripe API endpoints implemented
• ✅ CORS-Free - Firebase Cloud Function proxy eliminates all CORS issues
• ✅ Fully Type-Safe - 1100+ TypeScript definitions with zero any types
• ✅ Environment Switching - Runtime switching between test/live without redeployment
• ✅ AI-Friendly - Consistent structure prevents AI coding errors
• ✅ Production-Ready - Used in production with comprehensive error handling

📦 What's Included

Frontend (src/)

• services/stripe/ - 87 folders with 290+ service files covering all Stripe operations
• types/stripe/ - 77 modular type files with complete Stripe API type definitions
• components/stripe/ - Reusable Stripe UI components
• config/environment.ts - Environment configuration for test/live switching
• utils/firebase/config.ts - Firebase initialization and configuration
• services/errorHandler.ts - Centralized error handling for Stripe operations

Backend (functions/src/)

• stripe-proxy.ts - Complete Stripe API proxy with all endpoints
• cors-helper.ts - CORS configuration and handling utilities
• environment.ts - Runtime environment switching (test/live)
• services/errorHandler.ts - Error handling for Cloud Functions

🚀 Quick Start

1. Copy Files to Your Project

# Copy frontend files
cp -r src/services/stripe YOUR_PROJECT/src/services/
cp -r src/types/stripe YOUR_PROJECT/src/types/
cp -r src/components/stripe YOUR_PROJECT/src/components/
cp src/config/environment.ts YOUR_PROJECT/src/config/
cp src/utils/firebase/config.ts YOUR_PROJECT/src/utils/firebase/
cp src/services/errorHandler.ts YOUR_PROJECT/src/services/

# Copy backend files
cp functions/src/stripe-proxy.ts YOUR_PROJECT/functions/src/
cp functions/src/cors-helper.ts YOUR_PROJECT/functions/src/
cp functions/src/environment.ts YOUR_PROJECT/functions/src/
cp functions/src/services/errorHandler.ts YOUR_PROJECT/functions/src/services/

2. Configure Firebase Secrets

# Set up Stripe test credentials
firebase functions:secrets:set STRIPE_TEST_SECRET_KEY
firebase functions:secrets:set STRIPE_TEST_PUBLISHABLE_KEY
firebase functions:secrets:set STRIPE_TEST_ACCOUNT_ID

# Set up Stripe live credentials
firebase functions:secrets:set STRIPE_LIVE_SECRET_KEY
firebase functions:secrets:set STRIPE_LIVE_PUBLISHABLE_KEY
firebase functions:secrets:set STRIPE_LIVE_ACCOUNT_ID

3. Create Firestore Configuration Document

Create /config/stripe document in Firestore:

{
  "environment": "test",
  "testPublishableKey": "pk_test_...",
  "livePublishableKey": "pk_live_..."
}

4. Deploy Functions

firebase deploy --only functions:stripeProxy

5. Use in Your Code

import { customersCreateService } from 'src/services/stripe';

// Create a customer
const result = await customersCreateService.create({
  email: 'customer@example.com',
  name: 'John Doe',
  phone: '+1234567890'
});

if (result.success) {
  console.log('Customer created:', result.customer?.id);
}

📚 API Coverage

Core Payment APIs

• Customers, PaymentIntents, PaymentMethods, Charges, Refunds
• Checkout Sessions, Payment Links
• Subscriptions, Invoices, Invoice Items

Connect APIs

• Accounts, Account Links, Account Sessions
• Transfers, Payouts, Application Fees
• External Accounts, Persons, Capabilities

Specialized APIs

• Terminal, Identity, Issuing, Treasury
• Climate, Crypto, Entitlements, Financial Connections
• Tax, Radar, Sigma, Reporting, Reviews
• OAuth, Webhooks, Test Helpers

V2 (Next Generation) APIs

• Events, Event Destinations
• Core Accounts, Account Links
• Billing Meters, Meter Events, Licensed Items

🔧 Architecture

CORS Solution

The stripeProxy Cloud Function acts as a proxy between your frontend and Stripe API:

Frontend → Firebase Function → Stripe API
         (CORS-free)        (authenticated)

Environment Switching

Switch between test and live environments without redeployment:

1. Update Firestore /config/stripe document: { environment: "live" }
2. Changes take effect immediately
3. No function redeployment needed

Type Safety

All services use centralized types from src/types/stripe/:

// Type-safe parameters
const params: CustomerCreateParams = {
  email: 'test@example.com',  // ✅ Type-checked
  name: 'John Doe',           // ✅ Type-checked
  invalidField: 'value'       // ❌ TypeScript error
};

📖 Documentation

• All types match Stripe API documentation exactly (snake_case)
• JSDoc comments include Stripe API reference links
• Consistent error handling across all services
• Predictable file structure (alphabetically organized)

🛠️ Error Handling

All services use ErrorHandler for consistent error management:

import { ErrorHandler, ErrorContext } from 'src/services/errorHandler';

try {
  const result = await stripe.customers.create(params);
} catch (error) {
  const context: ErrorContext = { 
    operation: 'createCustomer',
    customerEmail: params.email 
  };
  const errorResult = ErrorHandler.handleStripeError(error, context);
  return { success: false, error: errorResult.userMessage };
}

📝 Requirements

• Firebase Project with Functions enabled
• Node.js 20+
• TypeScript 5.0+
• Firebase Admin SDK
• Stripe Node SDK

🤝 Contributing

This is a production-tested implementation. Feel free to use in your own projects!

📄 License

MIT License - Use freely in your projects

🙏 Credits

Created by Eric Wiedemann to solve Stripe CORS issues in Firebase projects.

Twizbee - Building better developer tools and solutions.

---

Need help? Check the Stripe API documentation: https://docs.stripe.com/api