Setting up Payment

Configure Stripe integration to enable subscription billing and payment processing for your SaaS application.

💡 Getting started? Complete Installation, Build Product Context, and Landing Page Setup first to have your foundation ready!

🎯 Overview

This section will guide you through setting up a complete payment system using Stripe, including:

Stripe account creation and API key configuration
Environment variables setup for secure integration
Webhook configuration for real-time payment events
Product and pricing creation for your subscription plans
Testing the payment flow end-to-end

⏱️ Estimated time: 20-30 minutes

🔧 Stripe Account Setup

1. Create Stripe Account

If you don’t have a Stripe account yet:

Visit Stripe.com and create an account
Complete business verification (can be done later for testing)
Access your Dashboard at dashboard.stripe.com

2. Get API Keys

Locate your API keys:

Go to Developers → API keys in your Stripe dashboard
Copy your Publishable key and Secret key
Use test keys for development (they start with pk_test_ and sk_test_)


# Test keys look like this:
pk_test_51234567890abcdef...  # Publishable key
sk_test_51234567890abcdef...  # Secret key

⚠️ Important: Never expose secret keys in frontend code or public repositories.

🔐 Environment Configuration

1. Set Convex Environment Variables

Configure your Stripe keys in the Convex backend:


# Set Stripe secret key (backend only)
npx convex env set STRIPE_SECRET_KEY=sk_test_your_stripe_secret_key
 
# You'll set the webhook secret after creating webhooks (next step)

2. Frontend Configuration (Optional)

For advanced Stripe integrations, you might need the publishable key in frontend:


# Add to .env.local if needed for custom Stripe components
NEXT_PUBLIC_STRIPE_PUBLISHABLE_KEY=pk_test_your_stripe_publishable_key

⚠️ Note: The boilerplate handles most Stripe operations through the backend, so frontend keys are typically not needed.

🔗 Webhook Setup

Webhooks are crucial for real-time payment processing and subscription management.

1. Create Webhook Endpoint

In your Stripe dashboard:

Go to Developers → Webhooks
Click “Add endpoint”
Endpoint URL: https://your-convex-deployment.convex.cloud/stripe/webhook
Select events to listen to:
- checkout.session.completed
- customer.subscription.created
- customer.subscription.updated
- customer.subscription.deleted
- invoice.payment_succeeded
- invoice.payment_failed

2. Get Webhook Secret

After creating the webhook:

Click on your webhook in the Stripe dashboard
Copy the “Signing secret” (starts with whsec_)
Set it in Convex:


npx convex env set STRIPE_WEBHOOK_SECRET=whsec_your_webhook_secret

3. Webhook URL Format

Your webhook URL should be:


https://your-deployment-name.convex.cloud/stripe/webhook

Find your deployment URL:

Run npx convex dashboard and copy the URL
Or check your NEXT_PUBLIC_CONVEX_URL in .env.local

💰 Products and Pricing Setup

1. Using the Admin Interface (Recommended)

The boilerplate includes a built-in Stripe management interface:

Access admin interface:
- Go to http://localhost:3000/dev-app in development
- Navigate to “Stripe Price Manager”
Create products:
- Click “Create Product”
- Add product name, description, and features
- Set monthly and yearly pricing
- Configure feature metadata
Activate pricing:
- Only one price per interval can be active
- Mark your recommended plan as “Popular”
- Test different pricing configurations

2. Manual Stripe Dashboard Setup

Alternatively, create products directly in Stripe:

Go to Products in your Stripe dashboard
Create a new product:
- Name: “Starter Plan”
- Description: “Perfect for small teams”
Add pricing:
- Monthly: $29/month
- Yearly: $290/year (save 17%)
Repeat for other plans (Professional, Enterprise, etc.)

3. Example Product Structure


Starter Plan - $29/month
 
- Up to 5 workspaces
- Basic features
- Email support
 
Professional Plan - $99/month
 
- Up to 25 workspaces
- Advanced features
- Priority support
 
Enterprise Plan - $299/month
 
- Unlimited workspaces
- All features
- Dedicated support

🧪 Testing Payment Flow

1. Test User Journey

Complete flow test:

Sign up for a new account
Create a workspace (should prompt for subscription)
Select a plan and proceed to checkout
Use test card: 4242 4242 4242 4242
- Any future expiry date
- Any 3-digit CVC
Complete payment and verify subscription activation

2. Test Cards

Stripe provides test cards for different scenarios:


# Successful payment
4242 4242 4242 4242
 
# Declined payment
4000 0000 0000 0002
 
# Requires 3D Secure authentication
4000 0027 6000 3184
 
# Expired card
4000 0000 0000 0069

3. Verify Integration

Check these work correctly:

✅ Checkout flow completes successfully
✅ User subscription shows as active
✅ Webhook events are received (check Convex logs)
✅ Billing portal is accessible from workspace settings
✅ Plan features are properly enabled/disabled

🔍 Troubleshooting

Common Issues

“Stripe keys not configured” error:


# Verify your environment variables are set
npx convex env list | grep STRIPE

Webhook events not received:


# Check webhook URL format
https://your-deployment.convex.cloud/stripe/webhook
 
# Verify webhook secret is correct
npx convex env get STRIPE_WEBHOOK_SECRET

Checkout session creation fails:


# Ensure you have active prices in Stripe
# Check Convex logs for detailed error messages
npx convex logs

Testing Webhook Delivery

In Stripe dashboard:

Go to Developers → Webhooks
Click on your webhook endpoint
Check “Recent deliveries” for success/failure status
Use “Send test webhook” to verify connectivity

Environment Verification

Check your setup:


# Verify all required environment variables
npx convex env list
 
# Should show:
# STRIPE_SECRET_KEY=sk_test_...
# STRIPE_WEBHOOK_SECRET=whsec_...

🚀 Production Setup

1. Switch to Live Mode

When ready for production:

Get live API keys from Stripe dashboard
Update environment variables:


# Production Stripe keys
npx convex env set --prod STRIPE_SECRET_KEY=sk_live_your_live_secret_key
npx convex env set --prod STRIPE_WEBHOOK_SECRET=whsec_your_live_webhook_secret

Create new webhook with production URL
Update products and pricing for live customers

2. Business Verification

For live payments, Stripe requires:

Business information verification
Bank account connection
Tax information (if applicable)
Identity verification for account owner

3. Production Checklist

Live API keys configured in production environment
Production webhook created with live URL
Business verification completed in Stripe
Bank account connected for payouts
Products and pricing finalized for launch
Tax settings configured (if applicable)
Payment flow tested end-to-end in production

📊 Monitoring and Analytics

Built-in Analytics

The admin interface provides:

Revenue tracking and subscription metrics
Plan performance analysis
Customer lifecycle insights
Failed payment monitoring

Stripe Dashboard

Monitor in Stripe:

Revenue reports and growth trends
Customer behavior and retention
Payment failures and recovery
Subscription metrics and churn analysis

🔐 Security Best Practices

API Key Management

✅ Never expose secret keys in frontend code
✅ Use test keys for development and staging
✅ Rotate keys periodically for security
✅ Monitor key usage in Stripe dashboard

Webhook Security

✅ Verify webhook signatures (handled automatically)
✅ Use HTTPS for all webhook endpoints
✅ Monitor webhook deliveries for failures
✅ Handle duplicate events gracefully

Next Steps

After completing payment setup:

Customizing the App - Adapt the boilerplate to your specific needs
Test your complete user journey from signup to paid subscription
Review Stripe Price Manager documentation for advanced features

💡 Note: You’ve already completed Build Product Context and Landing Page Setup, so you have a clear plan and can start building your audience!

Your SaaS now has a complete payment system ready for subscription billing! 🎉

Next: Continue with Customizing the App →