Billing & Stripe Integration

Relevant source files

The following files were used as context for generating this wiki page:

• packages/api/src/services/stripe.ts
• packages/api/src/routes/billing.ts
• LAUNCH_PLAN.md
• BUILT.md
• scripts/launch.sh

The Billing & Stripe Integration system in SecretForge AI manages user subscriptions, payment processing, and tier-based feature access. Built on top of Cloudflare Workers and the Stripe API, it provides a secure infrastructure for transitioning users from a free tier to paid "Pro," "Team," or "Enterprise" plans.

This system handles the end-to-end lifecycle of a customer's financial relationship with the platform, including customer creation, checkout session management, subscription status synchronization via webhooks, and the provision of self-service management through the Stripe Customer Portal.

Sources: packages/api/src/services/stripe.ts:1-7, packages/api/src/routes/billing.ts:1-12, BUILT.md:104-109

System Architecture

The billing architecture consists of three primary layers: the Billing Router (API Endpoints), the Stripe Service (API Wrapper), and the Database (State Persistence).

Subscription Tiers & Plans

SecretForge AI defines four distinct tiers, each with specific feature sets and usage limits. Plans are configured for both monthly and yearly billing cycles.

Tier	Monthly Price	Yearly Price	Secret Limit	Monthly Rotations	Key Features
Free	$0	N/A	10	10	Basic encryption, email notifications
Pro	$9	$90	Unlimited	Unlimited	AI recommendations, compliance reports
Team	$49	$490	Unlimited	Unlimited	10 members, shared vaults, audit logs
Enterprise	Custom	Custom	Unlimited	Unlimited	SSO/SAML, custom support

Sources: packages/api/src/services/stripe.ts:16-107, LAUNCH_PLAN.md:108-112, BUILT.md:110-115

Implementation Detail: Plan Data Structure

Plans are stored in the STRIPE_PLANS constant, which maps tier and interval combinations to their respective Stripe Price IDs and metadata.

Sources: packages/api/src/services/stripe.ts:16-20

Core Service Components

StripeService Class

The StripeService acts as the primary interface for interacting with the Stripe REST API using the Fetch API.

• Customer Management: createCustomer and getCustomer functions manage Stripe customer objects linked to internal user IDs via metadata.
• Session Management: createCheckoutSession initiates the hosted checkout flow, while createPortalSession generates links for users to manage their billing settings.
• Subscription Operations: Functions include createSubscription, updateSubscription (for upgrades/downgrades), and cancelSubscription (supporting both immediate and period-end cancellation).
• Webhook Security: The verifyWebhook method uses crypto.subtle to perform HMAC-SHA256 signature verification on incoming Stripe events.

Sources: packages/api/src/services/stripe.ts:124-287

Billing Router Endpoints

The Hono-based router in billing.ts exposes the following API surface:

Endpoint	Method	Purpose	Auth Required
/plans	GET	Lists all available subscription plans	No
/checkout	POST	Creates a Stripe Checkout session for a chosen tier	Yes
/portal	POST	Creates a Stripe Customer Portal session	Yes
/subscription	GET	Retrieves the user's current subscription status	Yes
/cancel	POST	Cancels an active subscription	Yes
/webhook	POST	Processes asynchronous events from Stripe	No (Signature)

Sources: packages/api/src/routes/billing.ts:17-175

Data Flow: Checkout & Subscription Lifecycle

The subscription lifecycle begins with a checkout request and is maintained through asynchronous webhook notifications.

Webhook Handling logic

Webhooks are critical for maintaining data parity between Stripe and the SecretForge D1 database. The system handles four primary event types:

1. customer.subscription.created/updated: Updates the user's tier and stripe_subscription_id in the database. It uses the price ID from the event to determine the correct tier via determineTierFromPriceId.
2. customer.subscription.deleted: Downgrades the user to the free tier and clears the subscription ID.
3. invoice.payment_succeeded: Logs a payment_succeeded event in the usage_events table for audit and analytics purposes.
4. invoice.payment_failed: Logs a payment_failed event to the database.

Sources: packages/api/src/routes/billing.ts:178-265

Database Schema Integration

The billing system relies on specific fields within the users and usage_events tables to track financial state.

Field	Table	Description
stripe_customer_id	users	The unique identifier for the customer in Stripe
stripe_subscription_id	users	The active subscription ID from Stripe
tier	users	The current service level (free, pro, team, enterprise)
usage_events	Table	Logs payment history and billing status changes

Sources: packages/api/src/routes/billing.ts:44-55, packages/api/src/routes/billing.ts:238-260, packages/api/src/routes/billing.ts:281-289

The Billing & Stripe Integration provides the foundation for the project's monetization strategy. By offloading complex payment flows to Stripe while maintaining a synchronized local state in D1, the system ensures that feature flags and usage limits (defined in STRIPE_PLANS) are accurately enforced across the CLI, Web, and API components.