When integrating Stripe into a multi-tenant SaaS application, one of the biggest challenges is keeping the payment logic consistent, secure, and adaptable across environments. Without proper structure, teams often duplicate code, hardcode environment variables, or risk mixing test and production configurations.

To address this, we built a dedicated _shared module,  a single source of truth for all Stripe operations. This guide explains why this approach is essential, how it prevents common pitfalls, and what benefits it brings in terms of security, maintainability, and scalability.

‍

The Problem: Scattered Stripe Logic

In many projects, each Edge Function or API route initializes its own Stripe client. This quickly leads to:

• Duplicate code: every function reimplements client setup and webhook validation.

• Configuration drift: one function may point to test keys while another points to live keys.

• Security risks: inconsistent handling of secrets increases the chance of exposing keys.

• Harder debugging: when webhooks fail, it’s unclear which piece of code is responsible.

In short, scattered Stripe logic makes the integration brittle and error-prone — especially in multi-environment setups like test vs. production.

‍

The Solution: A Centralized _shared/stripe.client.ts

By centralizing all Stripe logic in a _shared module, we ensure consistency across the entire codebase. This file handles:

1. Environment validation
   At startup, it checks that all required keys are defined (STRIPE_SECRET_KEY_PROD, STRIPE_SECRET_KEY_TEST, STRIPE_WEBHOOK_SECRET_*, etc.).
   If any are missing, the system fails fast with a clear error message instead of silently misbehaving.
   
   
   

2. Environment switching
   A single flag (STRIPE_IS_LIVE_MODE) controls whether the client runs in live or test mode. This prevents accidental use of the wrong keys.
   
   
   

3. Standard vs. Connect webhooks
   The module provides helper methods for both account-level events (subscriptions, customers, invoices) and Connect events (payouts, account updates). Each function automatically picks the correct webhook secret.
   
   
   

4. Client instantiation
   The Stripe client is always instantiated with the correct API version and keys, avoiding drift across functions.
   
   
   

‍

Code Walkthrough

Here’s a simplified view of the _shared/stripe.client.ts:

And webhook construction:

This ensures that every webhook is verified against the right secret, regardless of whether it belongs to the platform account or a connected account.

‍

Benefits of the _shared Pattern

• Consistency: all Stripe calls share the same configuration logic.

• Security: environment variables are validated once, reducing misconfiguration risks.

• Scalability: new Edge Functions simply import the shared client, avoiding boilerplate.

• Maintainability: upgrading the Stripe API version only requires changing one file.

• Auditability: webhook handling is centralized, making debugging and monitoring easier.
  
  
  

‍

Conclusion

Stripe Connect integrations are inherently complex, especially in SaaS platforms with multiple environments and connected accounts. Without structure, the risk of errors, misconfigurations, and security issues increases dramatically.

By adopting a _shared/stripe.client.ts, we transformed our integration from scattered, fragile code into a secure, maintainable, and scalable foundation. This pattern not only saves development time but also builds trust — every transaction, webhook, and payout is handled consistently, regardless of the environment.

In short: don’t scatter your Stripe logic — centralize it. Your future self (and your customers) will thank you.

‍