Skip to content

Stripe Payments

Top G & AI Velocity Feature

Stripe payments are available in Top G and AI Velocity tiers only.
See tier comparison

Complete Stripe integration with subscriptions, one-time purchases, webhook handling, and customer portal.

Quick Start

Bash
 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
# 1. Add Stripe keys to local.env
STRIPE_SECRET_KEY=sk_test_your_key
STRIPE_PUBLISHABLE_KEY=pk_test_your_key
STRIPE_WEBHOOK_SECRET=whsec_your_secret

# 2. Initialize Stripe products
task payments:setup

# 3. Test payment flow
# Visit: http://localhost:5173/pricing
# Use test card: 4242 4242 4242 4242

What's Included

Subscription Payments

  • Monthly/annual billing
  • Multiple subscription tiers
  • Trial periods
  • Auto-renewal
  • Plan upgrades/downgrades
  • Proration handling

One-time Purchases

  • Product purchases
  • Lifetime access options
  • Success/cancel handling

Webhook Processing

  • Secure signature verification
  • Event handling (checkout, subscription updates)
  • Automatic user plan updates
  • Payment confirmation emails

Customer Portal

  • Self-service billing management
  • Update payment methods
  • View invoices
  • Cancel subscriptions

Setup Guide

1. Create Stripe Account

  1. Go to stripe.com
  2. Create account
  3. Get API keys from dashboard

2. Configure Environment

Add to local.env:

Text Only
1
2
3
STRIPE_SECRET_KEY=sk_test_...
STRIPE_PUBLISHABLE_KEY=pk_test_...
STRIPE_WEBHOOK_SECRET=whsec_...

3. Create Products

Bash
1
2
3
4
5
# Auto-create products/prices
task payments:setup

# Or manually create in Stripe Dashboard
# Then add price IDs to local.env

4. Test Webhooks Locally

Bash
1
2
3
4
5
6
7
8
9
# Terminal 1: Start backend
task run-backend

# Terminal 2: Stripe CLI webhook forwarding
stripe listen --forward-to localhost:8020/api/payments/webhook

# Terminal 3: Test events
stripe trigger checkout.session.completed
stripe trigger customer.subscription.updated

Architecture

Backend Components

Payment Manager (app/services/payment_manager.py):

  • Creates checkout sessions
  • Manages subscriptions
  • Handles customer portal

Webhook Handler (app/services/webhook_handler.py):

  • Verifies webhook signatures
  • Processes payment events
  • Updates user plans

Payment Controller (app/controllers/payments.py):

  • API endpoints
  • Request/response handling

Frontend Components

Payment Hooks (frontend/src/hooks/api/usePayments.ts):

  • useCreateCheckout() - Create checkout session
  • useCustomerPortal() - Open billing portal
  • useCancelSubscription() - Cancel subscription

Pages:

  • /pricing - Pricing page with checkout
  • /billing - Subscription management
  • /payment/success - Success handler
  • /payment/cancel - Cancel handler

Usage Examples

Create Checkout Session

TypeScript
 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
// Frontend
import { useCheckoutWithProduct } from '@/hooks/api/usePayments';

const Component = () => {
  const { checkoutWithProduct } = useCheckoutWithProduct();

  const handleSubscribe = () => {
    checkoutWithProduct('premium'); // Redirects to Stripe
  };

  return <Button onClick={handleSubscribe}>Subscribe</Button>;
};

Open Customer Portal

TypeScript
 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
import { useCustomerPortal } from '@/hooks/api/usePayments';

const BillingPage = () => {
  const portal = useCustomerPortal();

  return (
    <Button onClick={() => portal.mutate()}>
      Manage Billing
    </Button>
  );
};

Webhook Events

Handled automatically:

  • checkout.session.completed - Payment successful
  • customer.subscription.created - New subscription
  • customer.subscription.updated - Subscription changed
  • customer.subscription.deleted - Subscription cancelled
  • invoice.payment_succeeded - Invoice paid
  • invoice.payment_failed - Payment failed

Testing

Test Cards

  • Success: 4242 4242 4242 4242
  • Decline: 4000 0000 0000 0002
  • 3D Secure: 4000 0027 6000 3184

Full test card list

Testing Workflow

  1. Start local webhook listener
  2. Trigger test purchase in UI
  3. Verify webhook received
  4. Check user plan updated
  5. Confirm email sent (if configured)

Common Issues

Problem: Webhook signature verification fails
Solution: Use correct webhook secret from Stripe CLI or Dashboard

Problem: Redirect after payment fails
Solution: Check success_url and cancel_url in config

Problem: User plan not updating after payment
Solution: Verify webhook handler calls update_user_plan()

Production Checklist

  • Replace test keys with live keys
  • Configure production webhook endpoint
  • Add webhook endpoint to Stripe Dashboard
  • Test with real card (refund immediately)
  • Verify email notifications work
  • Test customer portal
  • Monitor webhook logs

Files Reference

  • app/services/payment_manager.py - Payment logic
  • app/services/webhook_handler.py - Webhook processing
  • app/controllers/payments.py - API endpoints
  • app/config/payments.py - Stripe configuration
  • frontend/src/hooks/api/usePayments.ts - React hooks
  • frontend/src/pages/Billing.tsx - Billing management UI