Stripe Setup Guide

Prerequisites

• Stripe account (free to create)
• Access to Stripe Dashboard

Local Development Workflow

When You Need Stripe

You only need Stripe configured when:

• Testing subscription checkout flows
• Verifying webhook event handling
• Debugging billing-related features
• Testing plan upgrades/downgrades

For most development work (UI, authentication, organization management, etc.), pnpm dev is sufficient without Stripe.

Setting Up Stripe for Local Development

When you're ready to test billing features:

1. Run the guided setup (recommended):

   pnpm run setup:credentials --stripe

   This will guide you through setting up your Stripe API keys and configuring a webhook endpoint in the Stripe Dashboard.

2. Start development:

   pnpm dev

Manual Stripe Configuration

If you prefer manual setup, you'll need to set these Convex environment variables:

npx convex env set STRIPE_SECRET_KEY sk_test_...
npx convex env set STRIPE_WEBHOOK_SECRET whsec_...

Then create a webhook endpoint in the Stripe Dashboard pointing to your Convex site URL (see "Configure Webhooks" section below).

1. Create Stripe Account

1. Sign Up: Go to stripe.com and create an account
2. Verify Email: Complete email verification
3. Business Information: Add business details (can be updated later)
4. Dashboard Access: Access your Stripe Dashboard

2. Get API Keys

Test Mode Keys (Development)

1. Navigate to API Keys: Go to Developers > API Keys
2. Copy Secret Key: Copy the secret key to set in Convex:

# Test mode key (for development)
npx convex env set STRIPE_SECRET_KEY sk_test_51ABC123...

Note: TinyKit SaaS uses Convex backend actions for all Stripe operations, so no publishable key is needed in the frontend.

Live Mode Keys (Production)

Important: Only use live keys in production environments.

1. Toggle to Live Mode: Switch to Live mode in top-left of dashboard
2. Get Live Secret Key: Copy the live secret key
3. Production Environment: Set in Convex production environment

# Live mode key (for production only)
npx convex env set STRIPE_SECRET_KEY sk_live_51ABC123... --prod

3. Create Products and Prices

TinyKit SaaS includes a smart product sync system that can create products automatically from seed configuration.

Option A: Automatic Product Creation (Recommended)

1. Access Admin Panel: Navigate to /admin/products as an admin user
2. Product Status: System will detect you have no products
3. Create from Seed: Click "Sync from Stripe" button
4. Confirmation: Review the products that will be created from seed configuration
5. Execute: Confirm to create all products in Stripe and sync to database

The system will create these products automatically:

Personal Plans:

• Free: Basic workspace access
• Solo: $9/month, unlimited personal workspaces
• Premium: $19/month, advanced features and API access

Team Plans:

• Starter: $19/month or $190/year, up to 5 team members
• Professional: $29/month or $290/year, up to 20 team members (recommended)
• Enterprise: $39/month or $390/year, unlimited members
• Lifetime: $500 one-time payment, everything included

Option B: Manual Product Creation

If you prefer to create products manually:

Using Stripe Dashboard

1. Navigate to Products: Go to Products
2. Add Product: Click "Add product"
3. Product Details:
   • Name: "Professional Plan"
   • Description: "Advanced features for growing teams"
4. Pricing:
   • Price: $29.00
   • Billing: Monthly or Yearly
   • Currency: USD
5. Save Product: Click "Save product"
6. Repeat: Create all needed products and prices

Sync Products to Database

After creating products in Stripe (manually or automatically):

1. Access Admin Panel: Go to /admin/products
2. Sync from Stripe: Click "Sync from Stripe" if you have existing products
3. Verify: Check that all products and prices appear correctly

4. Configure Webhooks

Webhooks are essential for keeping your database synchronized with Stripe events.

Automatic Webhook Setup (Recommended)

The stripe:seed script automatically creates and configures the webhook endpoint:

pnpm run stripe:seed

This will:

1. Check if a webhook endpoint already exists for your Convex site URL
2. Create a new endpoint if none exists, with all required events pre-configured
3. Auto-set STRIPE_WEBHOOK_SECRET in your Convex environment
4. Update an existing endpoint if it's missing any required events

The webhook URL is derived from NEXT_PUBLIC_CONVEX_SITE_URL in your .env.local:

https://your-project.convex.site/stripe/webhook

Manual Webhook Setup

If you prefer to configure webhooks manually:

1. Go to Stripe Dashboard > Developers > Webhooks
2. Click "Add endpoint"
3. Set endpoint URL to your Convex site URL:

   https://your-project.convex.site/stripe/webhook

4. Select events: Click "Select all events" (recommended) or choose specific events
5. Click "Add endpoint"
6. Copy the Signing Secret and set it in Convex:

   npx convex env set STRIPE_WEBHOOK_SECRET whsec_...

Production Webhooks

For production, follow the manual setup steps above but:

1. Switch to Live mode in the Stripe Dashboard (top-left toggle)
2. Create a new webhook endpoint pointing to your production Convex site URL
3. Set the live webhook secret in Convex production environment:

   npx convex env set STRIPE_WEBHOOK_SECRET whsec_... --prod

Testing Webhooks

# Check your application logs to verify events are received
npx convex logs --tail | grep "stripe\|webhook"

# View webhook delivery status in Stripe Dashboard:
# Developers > Webhooks > [your endpoint] > Recent deliveries

5. Configure Customer Portal

The Customer Portal allows customers to manage their own billing.

Enable Customer Portal

Important: This is required for the "Manage Billing" feature to work.

1. Access Portal Settings: Go to Billing > Customer portal
2. Activate Portal: Click "Activate test link" (for test mode)
3. Configure Features:
   • ✅ Subscriptions: Allow customers to cancel and switch plans
   • ✅ Payment methods: Allow adding and updating payment methods
   • ✅ Billing history: Show invoices and payments
   • ✅ Customer information: Allow updating customer details

Business Information

1. Business Details:

   • Business name: "Your Company Name"
   • Support email: "support@yourdomain.com"
   • Support phone: Your support phone number

2. Branding (optional):

   • Upload logo
   • Choose brand colors
   • Customize appearance

Policies and Terms

1. Terms of Service: Add link to your terms of service
2. Privacy Policy: Add link to your privacy policy
3. Cancellation Policy: Configure cancellation behavior

Save Configuration

Click "Save" to activate the Customer Portal. Test it works:

# Test customer portal access
# Visit your app and try "Manage Billing" button
# Should redirect to Stripe Customer Portal

6. Test Clock Setup (Development)

Test clocks help test time-based features like billing cycles and proration.

Create Test Clock

# Create test clock with specific frozen time
stripe test_clocks create --frozen-time $(date +%s)

# Create test clock for specific date
stripe test_clocks create --frozen-time 1640995200  # Jan 1, 2022

# List test clocks
stripe test_clocks list

Advance Test Clock

# Advance test clock to simulate time passage
stripe test_clocks advance clock_1234567890 --frozen-time $(date -d "+1 week" +%s)

# Advance to specific date
stripe test_clocks advance clock_1234567890 --frozen-time 1641600000  # Jan 8, 2022

Use Test Clock in Development

When creating subscriptions in development, they will automatically use the active test clock for accurate proration testing.

7. Environment Variables Summary

All Stripe configuration is done through Convex environment variables (backend-only). No Stripe keys are needed in .env.local since TinyKit SaaS uses Convex backend actions for all Stripe operations.

Convex Environment Variables (Development)

# Set Stripe configuration in Convex
npx convex env set STRIPE_SECRET_KEY sk_test_51ABC123...
npx convex env set STRIPE_WEBHOOK_SECRET whsec_1a2b3c4d5e6f7g8h9i0j...

Production Environment Variables

Convex Environment (Production)

# Set production Stripe configuration in Convex
npx convex env set STRIPE_SECRET_KEY sk_live_51ABC123... --prod
npx convex env set STRIPE_WEBHOOK_SECRET whsec_production_secret... --prod

Security Note: TinyKit SaaS stores all Stripe keys securely in the Convex environment. Secret keys never appear in frontend code or .env.local. No publishable key is required since all Stripe operations use Convex backend actions.

API Version: TinyKit SaaS automatically uses your Stripe account's default API version when no version is specified, ensuring compatibility and allowing you to upgrade API versions through your Stripe Dashboard.

8. Testing the Integration

Basic Functionality Test

1. Product Sync: Verify products appear in admin panel
2. Subscription Flow: Test creating a subscription
3. Webhook Delivery: Verify events are received and processed
4. Customer Portal: Test billing management features

Test Card Numbers

Use Stripe test cards for testing:

# Successful payment
4242 4242 4242 4242

# Declined payment
4000 0000 0000 0002

# Requires authentication (3D Secure)
4000 0025 0000 3155

# Insufficient funds
4000 0000 0000 9995

Subscription Testing

1. Create Subscription: Go through checkout flow
2. Upgrade Plan: Test plan changes and proration
3. Cancel Subscription: Test cancellation flow
4. Reactivate: Test reactivation if applicable

9. Production Preparation

Business Activation

Before going live:

1. Business Verification: Complete Stripe business verification
2. Bank Account: Add bank account for payouts
3. Tax Settings: Configure tax collection if required
4. Payout Schedule: Set payout frequency

Security Review

1. API Key Security: Ensure live keys are never exposed in client-side code
2. Webhook Security: Verify webhook signature validation is working
3. Environment Separation: Confirm test and live environments are properly separated

Monitoring Setup

1. Stripe Dashboard: Set up email alerts for important events
2. Application Monitoring: Monitor webhook processing and errors
3. Revenue Tracking: Set up revenue and churn monitoring

Troubleshooting

Common Issues

"No configuration provided" error in Customer Portal

• Solution: Complete Customer Portal configuration in Stripe Dashboard
• Check: Ensure portal is activated for the correct mode (test/live)

Webhook signature verification failed

• Solution: Verify STRIPE_WEBHOOK_SECRET matches the endpoint secret
• Check: Copy the Signing Secret from your webhook endpoint in the Stripe Dashboard

Products not appearing in admin panel

• Solution: Use admin interface to sync products from Stripe
• Check: Verify Stripe API keys are correctly configured

Test payments failing

• Solution: Use official Stripe test card numbers
• Check: Ensure you're in test mode and using test API keys

Proration amounts incorrect in development

• Solution: Create and use Stripe test clocks for consistent testing
• Check: Verify subscription is attached to test clock

Debug Commands

# Monitor Convex logs for webhook processing
npx convex logs --tail | grep "stripe\|webhook"

# Check webhook delivery in Stripe Dashboard:
# Developers > Webhooks > [your endpoint] > Recent deliveries

Support Resources

• Stripe Documentation
• Stripe Support
• Stripe Discord Community
• TinyKit SaaS Troubleshooting

← Back to Guides | Next: Email Setup →