Stripe API configuration misplaced between webhook handler and payment service

In a Python-based payment processing system, the architectural separation between webhook handling and payment operations was compromised due to improper Stripe API configuration. The Stripe SDK was being used for both webhook verification and payment operations, leading to unnecessary coupling and inefficiencies.

Issue

The Stripe API key was incorrectly initialized in the webhook handler instead of the payment service. This created an architectural problem where:

• The webhook handler, responsible only for verifying incoming events, unnecessarily contained payment API credentials.
• The payment service, which required Stripe API access to create PaymentIntents, lacked proper configuration.
• Payment operations failed to execute real Stripe API calls, despite the system being configured for Stripe integration.

Culprit

The root cause was a misunderstanding of Stripe’s dual-use SDK architecture:

1. Webhook Verification: Requires only the STRIPE_WEBHOOK_SECRET for signature validation, without needing the API key.
2. Payment Operations: Requires the STRIPE_SECRET_KEY for authenticated API requests, such as creating PaymentIntents.

The original implementation placed all Stripe-related configurations in the webhook handler, while the payment service had no Stripe initialization, leading to a misaligned architecture.

Solution

1. Separate Configuration for Webhook Handler

The webhook handler was cleaned up to focus solely on signature verification:

• Removed payment-related configurations (e.g., stripe.api_key).
• Retained only the STRIPE_WEBHOOK_SECRET for validating incoming webhook events.

2. Properly Initialize Stripe in Payment Service

The payment service was updated to:

• Include the necessary Stripe initialization with the STRIPE_SECRET_KEY.
• Implement graceful degradation for environments where the Stripe key is not configured (e.g., stub mode).
• Enable real payment operations, such as creating PaymentIntents, when properly configured.

3. Environment Variable Separation

To enforce clear separation:

• Webhook Verification: Uses STRIPE_WEBHOOK_SECRET for signature validation.
• Payment Operations: Uses STRIPE_SECRET_KEY for API calls.

4. Activated Payment Operations

The refactored system now supports:

• Auto-detection of Stripe configuration status.
• Graceful fallback to stub responses if the Stripe key is missing.
• Proper error handling and metadata integration (e.g., booking IDs, customer emails).

This refactor ensures clean architectural separation:

• Webhook Domain: Focuses exclusively on verifying incoming events.
• Payment Domain: Handles all Stripe API operations with proper credentials.

The changes maintain backward compatibility while enabling real payment processing when the Stripe API is configured.