TinyKit Pro Docs
Guides

Stripe Setup Guide

Complete guide to setting up Stripe integration for TinyKit Pro's billing and subscription system.

Complete guide to setting up Stripe integration for TinyKit Pro's billing and subscription system.

Prerequisites

  • Stripe account (free to create)
  • Access to Stripe Dashboard
  • Stripe CLI installed (optional but recommended)

Local Development Workflow

TinyKit Pro separates development commands to make getting started easier:

Development Commands

CommandDescriptionWhen to Use
bun devFrontend + Convex backend onlyMost development work, no Stripe needed
bun dev:fullFrontend + Convex + Stripe webhooksTesting billing flows and subscription features

When You Need Stripe

You only need Stripe webhook forwarding (bun dev:full) 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.), bun dev is sufficient.

Setting Up Stripe for Local Development

When you're ready to test billing features:

  1. Install Stripe CLI:

    # macOS
brew install stripe/stripe-cli/stripe

# Windows (with scoop)
scoop install stripe

# Linux (Debian/Ubuntu)
curl -s https://packages.stripe.dev/api/security/keypair/stripe-cli-gpg/public | gpg --dearmor | sudo tee /usr/share/keyrings/stripe.gpg
echo "deb [signed-by=/usr/share/keyrings/stripe.gpg] https://packages.stripe.dev/stripe-cli-debian-local stable main" | sudo tee -a /etc/apt/sources.list.d/stripe.list
sudo apt update && sudo apt install stripe

  2. Login to Stripe:

    stripe login

  3. Run the guided setup (recommended):

    bun setup:credentials --stripe

    This will guide you through setting up your Stripe API keys and webhook secret.

  4. Start development with Stripe:

    bun dev:full

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_WEBHOOKS_SECRET whsec_...

The webhook secret is displayed when running stripe listen. See the "Configure Webhooks" section below for details.

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 Pro 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 Pro includes a smart product sync system that can create products automatically from seed configuration.

  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

Using Stripe CLI

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

# Login to Stripe
stripe login

# Create products
stripe products create --name="Professional Plan"
stripe products create --name="Enterprise Plan"

# Create prices for each product
stripe prices create --unit-amount=2900 --currency=usd --recurring-interval=month --product=prod_ABC123
stripe prices create --product=prod_ABC123 --unit-amount=29000 --currency=usd --recurring-interval=year

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.

Development Webhooks

For local development, use Stripe CLI to forward webhooks:

# Forward webhooks to local development server
stripe listen --forward-to localhost:3210/stripe

# Copy the webhook signing secret that appears in the output
whsec_1a2b3c4d5e6f7g8h9i0j...

# Add to your .env.local
STRIPE_WEBHOOKS_SECRET=whsec_1a2b3c4d5e6f7g8h9i0j...

Keep this command running during development to receive webhook events.

Production Webhooks

For production deployment:

  1. Create Webhook Endpoint:

    • Go to Developers > Webhooks
    • Click "Add endpoint"
    • URL: https://yourdomain.com/stripe
    • Description: "TinyKit Pro Webhook Endpoint"

  2. Select Events: Choose these essential events:

    customer.subscription.created
customer.subscription.updated
customer.subscription.deleted
invoice.payment_succeeded
invoice.payment_failed
customer.created
customer.updated

  3. Webhook Secret: Copy the webhook signing secret and add to production environment variables

Testing Webhooks

# Test webhook delivery
stripe trigger customer.subscription.created
stripe trigger invoice.payment_succeeded

# View webhook logs
stripe logs tail

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

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 Pro 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_WEBHOOKS_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_WEBHOOKS_SECRET whsec_production_secret... --prod

Security Note: TinyKit Pro 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 Pro 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_WEBHOOKS_SECRET matches the endpoint secret
  • Check: Use the secret from stripe listen output for development

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 Stripe webhook events
stripe logs tail

# View webhook delivery details
stripe webhooks list
stripe webhooks logs webhook_endpoint_id

# Check webhook endpoint status
stripe webhook_endpoints retrieve webhook_endpoint_id

# Test specific webhook events
stripe trigger customer.subscription.created --add subscription:items:0:price=price_1234

Support Resources

← Back to Guides | Next: Email Setup →

On this page

PrerequisitesLocal Development WorkflowDevelopment CommandsWhen You Need StripeSetting Up Stripe for Local DevelopmentManual Stripe Configuration1. Create Stripe Account2. Get API KeysTest Mode Keys (Development)Live Mode Keys (Production)3. Create Products and PricesOption A: Automatic Product Creation (Recommended)Option B: Manual Product CreationUsing Stripe DashboardUsing Stripe CLISync Products to Database4. Configure WebhooksDevelopment WebhooksProduction WebhooksTesting Webhooks5. Configure Customer PortalEnable Customer PortalBusiness InformationPolicies and TermsSave Configuration6. Test Clock Setup (Development)Create Test ClockAdvance Test ClockUse Test Clock in Development7. Environment Variables SummaryConvex Environment Variables (Development)Production Environment VariablesConvex Environment (Production)8. Testing the IntegrationBasic Functionality TestTest Card NumbersSubscription Testing9. Production PreparationBusiness ActivationSecurity ReviewMonitoring SetupTroubleshootingCommon IssuesDebug CommandsSupport Resources

Ship your startup faster. In minutes.

Get TinyKit Pro