Skip to main content

Stripe Integration - Project Plan v1.0

Project: CODITECT Stripe Integration Version: 1.0.0 Status: Planning Last Updated: December 17, 2025

Executive Summary​

This project delivers the payment and billing infrastructure for CODITECT, enabling subscription management, payment processing, usage-based billing, and revenue analytics.

Key Objectives​

  1. Zero PCI Burden - Stripe handles all card data
  2. Subscription Lifecycle - Create, upgrade, downgrade, cancel
  3. Usage Metering - Track and bill AI/feature usage
  4. Self-Service - Customer billing portal
  5. Revenue Visibility - Real-time metrics

Success Criteria​

  • All subscription operations functional
  • Webhook handling reliable (99.9%+)
  • 90%+ unit test coverage
  • E2E checkout flow working
  • Customer portal integrated
  • Usage metering accurate

Phase 0: Stripe Account Setup (Prerequisites)​

0.1 Stripe Dashboard Configuration​

Duration: 1 day

  • Create Stripe account (if not exists)

  • Configure account settings

    • Business name and address
    • Support email and URL
    • Branding (logo, colors)
    • Statement descriptor

0.2 API Keys Setup​

Duration: 1 hour

  • Get API keys

    • Go to: Developers → API Keys
    • Copy Publishable key (pk_live_...)
    • Copy Secret key (sk_live_...)
    • Create restricted keys for specific services

  • Set up test mode

    • Copy test Publishable key (pk_test_...)
    • Copy test Secret key (sk_test_...)

0.3 API Endpoints Reference​

OperationEndpoint
Create CustomerPOST https://api.stripe.com/v1/customers
Create SubscriptionPOST https://api.stripe.com/v1/subscriptions
Create Checkout SessionPOST https://api.stripe.com/v1/checkout/sessions
Create Portal SessionPOST https://api.stripe.com/v1/billing_portal/sessions
Create Payment IntentPOST https://api.stripe.com/v1/payment_intents
Record UsagePOST https://api.stripe.com/v1/subscription_items/{id}/usage_records

0.4 Products and Prices Setup​

Duration: 2 hours

  • Create Products in Stripe Dashboard

    • Product: "CODITECT Starter" (prod_starter)
    • Product: "CODITECT Professional" (prod_professional)
    • Product: "CODITECT Enterprise" (prod_enterprise)

  • Create Prices for each product

    • Starter Monthly: $19/month (price_starter_monthly)
    • Starter Yearly: $190/year (price_starter_yearly)
    • Professional Monthly: $49/month
    • Professional Yearly: $490/year

  • Create Metered Prices

    • AI Requests Overage: $0.01/request
    • Storage Overage: $0.05/MB

0.5 Webhook Configuration​

Duration: 1 hour

  • Configure webhook endpoint
    • Go to: Developers → Webhooks
    • Add endpoint: https://api.coditect.ai/webhooks/stripe
    • Select events to listen:
      • customer.subscription.created
      • customer.subscription.updated
      • customer.subscription.deleted
      • invoice.paid
      • invoice.payment_failed
      • checkout.session.completed
      • customer.created
    • Copy webhook signing secret (whsec_...)

0.6 Customer Portal Configuration​

Duration: 30 minutes

  • Configure Customer Portal
    • Go to: Settings → Billing → Customer Portal
    • Enable features:
      • Update payment method
      • View invoice history
      • Cancel subscription
      • Update subscription
    • Configure products for plan switching
    • Set business profile

0.7 Environment Variables​

Duration: 30 minutes

  • Create .env file 
    STRIPE_SECRET_KEY=sk_live_...
    STRIPE_PUBLISHABLE_KEY=pk_live_...
    STRIPE_WEBHOOK_SECRET=whsec_...
    STRIPE_API_VERSION=2023-10-16
    STRIPE_PRICE_STARTER_MONTHLY=price_...
    STRIPE_PRICE_STARTER_YEARLY=price_...
    STRIPE_PRICE_PROFESSIONAL_MONTHLY=price_...
    STRIPE_PRICE_PROFESSIONAL_YEARLY=price_...
  • Add to .gitignore
  • Create .env.example

Phase 1: Foundation​

1.1 Project Setup​

Duration: 2 days

  • Create project structure
    • src/ directory
    • tests/ directory
    • config/ directory
  • Set up pyproject.toml
  • Configure pytest and coverage
  • Set up pre-commit hooks
  • Create database migrations

1.2 Stripe Client Implementation​

Duration: 2 days

  • Implement AsyncStripeClient
    • Customer operations
    • Subscription operations
    • Checkout operations
    • Portal operations
    • Usage operations
  • Implement rate limiting
  • Implement retry logic
  • Add logging and metrics

1.3 Database Models​

Duration: 2 days

  • Create SQLAlchemy models
    • StripeCustomer model
    • Subscription model
    • Invoice model
    • PaymentMethod model
    • UsageRecord model
    • WebhookEvent model
  • Create database migrations
  • Set up indexes

Phase 2: Core Billing Features​

2.1 Customer Management​

Duration: 2 days

  • Implement CustomerManager
    • Create customer
    • Update customer
    • Delete customer
    • Sync with CODITECT users
  • API endpoints
    • GET /api/v1/billing/customer
    • PATCH /api/v1/billing/customer

2.2 Subscription Management​

Duration: 3 days

  • Implement SubscriptionManager
    • Create subscription
    • Upgrade subscription
    • Downgrade subscription
    • Cancel subscription
    • Resume subscription
    • Trial handling
  • API endpoints
    • GET /api/v1/billing/subscription
    • POST /api/v1/billing/subscription
    • PATCH /api/v1/billing/subscription
    • DELETE /api/v1/billing/subscription

2.3 Checkout Integration​

Duration: 2 days

  • Implement checkout session creation
  • API endpoints
    • POST /api/v1/billing/checkout
  • Frontend integration
    • Redirect to Stripe Checkout
    • Handle success/cancel URLs

2.4 Customer Portal​

Duration: 1 day

  • Implement portal session creation
  • API endpoints
    • POST /api/v1/billing/portal
  • Frontend integration

Phase 3: Webhook Handling​

3.1 Webhook Endpoint​

Duration: 2 days

  • Implement webhook handler
    • Signature verification
    • Idempotency checking
    • Event routing
  • Endpoint: POST /webhooks/stripe

3.2 Event Handlers​

Duration: 3 days

  • Subscription events
    • customer.subscription.created
    • customer.subscription.updated
    • customer.subscription.deleted
  • Invoice events
    • invoice.paid
    • invoice.payment_failed
  • Checkout events
    • checkout.session.completed
  • Customer events
    • customer.created
    • customer.updated

Phase 4: Usage Metering​

4.1 Usage Recording​

Duration: 2 days

  • Implement UsageMeter
    • Record usage
    • Get usage summary
    • Check limits
  • Usage caching in Redis

4.2 Usage Middleware​

Duration: 1 day

  • Track AI request usage
  • Track storage usage
  • Limit enforcement

4.3 Overage Billing​

Duration: 1 day

  • Configure metered billing in Stripe
  • Report usage at period end
  • Overage notifications

Phase 5: Feature Gating​

5.1 Feature Gate Implementation​

Duration: 2 days

  • Implement FeatureGate
    • Check feature access
    • Check usage limits
  • Plan definitions in YAML
  • Real-time enforcement

5.2 Provisioning System​

Duration: 2 days

  • Implement FeatureProvisioner
    • Provision on subscription
    • Deprovision on cancellation
    • Handle plan changes
  • Integrate with webhook handlers

Phase 6: Testing​

6.1 Unit Tests​

Duration: 3 days Target Coverage: 90%+

6.1.1 Client Tests​

  • test_stripe_client.py
    • Test customer creation
    • Test subscription creation
    • Test checkout session
    • Test portal session
    • Test usage recording
    • Test error handling
    • Test retry logic

6.1.2 Manager Tests​

  • test_customer_manager.py

    • Test create customer
    • Test update customer
    • Test sync with user
    • Test duplicate handling

  • test_subscription_manager.py

    • Test create subscription
    • Test upgrade (proration)
    • Test downgrade
    • Test cancel at period end
    • Test cancel immediately
    • Test resume
    • Test trial handling

  • test_usage_meter.py

    • Test record usage
    • Test get summary
    • Test check limits
    • Test overage calculation

6.1.3 Webhook Tests​

  • test_webhook_handler.py

    • Test signature verification
    • Test invalid signature
    • Test idempotency
    • Test event routing
    • Test unknown event type

  • test_event_handlers.py

    • Test subscription created
    • Test subscription updated
    • Test subscription deleted
    • Test invoice paid
    • Test payment failed
    • Test checkout completed

6.1.4 Feature Gate Tests​

  • test_feature_gate.py
    • Test feature access by plan
    • Test usage limits
    • Test unlimited features
    • Test free tier

6.2 Integration Tests​

Duration: 3 days

6.2.1 Stripe API Integration​

  • test_stripe_integration.py
    • Test real customer creation (test mode)
    • Test real subscription (test mode)
    • Test checkout flow (test mode)
    • Test portal flow (test mode)
    • Test usage reporting (test mode)

6.2.2 Database Integration​

  • test_database_integration.py
    • Test customer persistence
    • Test subscription persistence
    • Test invoice persistence
    • Test usage record persistence
    • Test webhook event logging

6.2.3 Webhook Integration​

  • test_webhook_integration.py
    • Test full event processing
    • Test database updates
    • Test feature provisioning
    • Test email notifications

6.3 End-to-End Tests​

Duration: 3 days

6.3.1 Checkout Flow E2E​

  • test_checkout_e2e.py
    • User signs up → Redirected to checkout
    • User completes payment (test card)
    • Webhook received and processed
    • Subscription active in database
    • Features provisioned
    • User can access paid features

6.3.2 Subscription Lifecycle E2E​

  • test_subscription_lifecycle_e2e.py
    • Create subscription
    • Verify trial period
    • Upgrade plan
    • Verify proration
    • Cancel at period end
    • Verify access until period end
    • Verify downgrade to free

6.3.3 Usage Metering E2E​

  • test_usage_metering_e2e.py
    • User makes AI requests
    • Usage recorded accurately
    • Limit enforcement works
    • Overage billing at period end

6.3.4 Customer Portal E2E​

  • test_portal_e2e.py
    • User accesses portal
    • Updates payment method
    • Views invoices
    • Changes subscription
    • Cancels subscription

6.3.5 Payment Failure E2E​

  • test_payment_failure_e2e.py
    • Simulate failed payment (test card)
    • Webhook processed
    • User notified
    • Grace period handling
    • Retry behavior

6.4 Test Infrastructure​

Stripe CLI for Local Testing​

# Install Stripe CLI
brew install stripe/stripe-cli/stripe

# Login
stripe login

# Forward webhooks to local
stripe listen --forward-to localhost:8000/webhooks/stripe

# Trigger test events
stripe trigger customer.subscription.created
stripe trigger invoice.paid
stripe trigger invoice.payment_failed

Test Card Numbers​

ScenarioCard Number
Success4242424242424242
Decline4000000000000002
Insufficient funds4000000000009995
Requires 3D Secure4000002760003184
Expired4000000000000069

Phase 7: Documentation​

7.1 Technical Documentation​

Duration: 2 days

  • Complete SDD
  • Complete TDD
  • Complete ADRs
  • API reference (OpenAPI)
  • Integration guide

7.2 User Documentation​

Duration: 1 day

  • Billing FAQ
  • Subscription guide
  • Payment troubleshooting
  • Portal user guide

Phase 8: Deployment​

8.1 Environment Configuration​

Duration: 1 day

  • Production Stripe keys
  • Webhook endpoint verified
  • Secrets in Secret Manager

8.2 Monitoring​

Duration: 1 day

  • Webhook success rate
  • Payment success rate
  • Error alerting
  • Revenue dashboards

8.3 Go-Live Checklist​

Duration: 1 day

  • All tests passing
  • Webhook endpoint responsive
  • Portal configured
  • Test transactions in production
  • Rollback plan ready

Test Plan Summary​

Test Categories​

CategoryTestsCoverage TargetDuration
Unit Tests50+90%+3 days
Integration Tests15+80%+3 days
E2E Tests10+Critical paths3 days
Total75+85%+9 days

Test Execution​

# Run all tests
pytest tests/ -v --cov=src --cov-report=html

# Run unit tests only
pytest tests/unit/ -v

# Run integration tests (requires Stripe test mode)
pytest tests/integration/ -v --stripe-mode=test

# Run E2E tests (requires Stripe CLI)
pytest tests/e2e/ -v --stripe-cli

# Generate coverage report
pytest tests/ --cov=src --cov-report=html
open htmlcov/index.html

CI/CD Integration​

# .github/workflows/test.yml
test-stripe:
  runs-on: ubuntu-latest
  steps:
    - uses: actions/checkout@v3
    - uses: stripe/stripe-cli-action@v1
    - run: |
        stripe listen --forward-to localhost:8000/webhooks/stripe &
        pytest tests/ -v --cov=src

Success Metrics​

MetricTarget
Unit test coverage90%+
Integration test pass rate100%
E2E test pass rate100%
Webhook success rate99.9%+
Payment success rate95%+
Customer portal uptime99.9%+

Timeline​

PhaseDurationDependencies
Phase 0: Setup1 dayStripe account
Phase 1: Foundation6 daysPhase 0
Phase 2: Core Billing8 daysPhase 1
Phase 3: Webhooks5 daysPhase 1
Phase 4: Usage4 daysPhase 2
Phase 5: Feature Gating4 daysPhase 2, 3
Phase 6: Testing9 daysPhase 2-5
Phase 7: Documentation3 daysPhase 2-5
Phase 8: Deployment3 daysPhase 6, 7
Total~7 weeks

Document Control:

  • Created: December 17, 2025
  • Owner: CODITECT Engineering Team