Payments

Payments & Billing Operations

Billing is 20% code and 80% configuration and business decisions. This skill helps you set up Stripe correctly, handle the edge cases, and avoid the mistakes that lose customer trust.

Core Principles

• Stripe is the right choice for 95% of bootstrapped SaaS. Do not overthink this decision.
• Test mode exists for a reason. Never touch live mode until you've tested every flow.
• Billing is the one place you cannot "move fast and break things." A billing bug loses trust permanently.
• Automate everything. Manual invoicing doesn't scale and you will forget.
• Tax compliance is not optional. Set it up from day one.

Stripe Setup Checklist

Stripe Configuration:
- [ ] Create Stripe account and verify identity
- [ ] Enable test mode (toggle in top-right of dashboard)
- [ ] Set up products and prices in Stripe Dashboard (not in code)
- [ ] Configure Customer Portal (Settings -> Billing -> Customer portal)
- [ ] Enable Stripe Tax (Settings -> Tax)
- [ ] Set up webhook endpoint in your app
- [ ] Add Stripe keys to environment variables
- [ ] Test complete purchase flow (test card: 4242424242424242)
- [ ] Test failed payment (decline card: 4000000000000002)
- [ ] Test subscription cancellation and upgrade/downgrade flows
- [ ] Switch to live mode, re-add live API keys
- [ ] Make one real purchase with your own card to verify

Tell AI:

Set up Stripe subscription billing for my SaaS:
- Monthly and annual pricing tiers: [list your tiers and prices]
- Checkout flow using Stripe Checkout (hosted payment page)
- Customer Portal for managing subscriptions
- Webhook handler for subscription events
- Environment variables for Stripe keys
Use [your framework/stack].

Products & Prices: Dashboard First

Always create products and prices in the Stripe Dashboard. Then reference them by Price ID in your code.

How to Set Up

1. Stripe Dashboard -> Products -> Create one Product per tier (e.g., "Starter", "Pro")
2. Add two Prices per product — monthly and annual
3. Copy the Price IDs (price_...) into your app config
4. Use lookup keys for cleaner code (e.g., starter_monthly, pro_annual)

Pricing Tips

• Annual pricing = monthly x 10 (2 months free)
• Show monthly price with annual savings highlighted
• Use Stripe's built-in trial period (set on the Price, not in code)
• Don't create "free" prices — handle free tier in your app logic

Subscription Lifecycle

Every state your app needs to handle:

Essential Webhooks

Your app MUST handle these events:

Tell AI:

Create a Stripe webhook handler for my [framework] app:
- Handle: checkout.session.completed, customer.subscription.updated,
  customer.subscription.deleted, invoice.payment_failed
- Verify webhook signatures using the endpoint secret
- Store subscription status in [database]
- Return 200 immediately (process async if needed)

Webhook security: Always verify signatures. Use stripe.webhooks.constructEvent(). Return 200 immediately — Stripe retries on timeout.

Customer Portal

Stripe's hosted Customer Portal lets users manage subscriptions without you building anything.

Configure in Settings -> Billing -> Customer portal:

• Allow: update payment method, cancel subscription, switch plans, view invoices
• Enable cancellation reason collection (gives you churn data)
• Set cancellation policy to "at end of billing period" (not immediate)

Tell AI:

Add a "Manage Billing" button to my app's settings page.
It should create a Stripe Customer Portal session and redirect the user.
Use [framework].

Failed Payments (Dunning)

~5-10% of recurring charges fail each month. Plan for it.

Automatic Recovery

1. Enable Smart Retries (Settings -> Billing -> Automatic collection) — Stripe retries 3 times over ~3 weeks, recovers 30-40% of failures automatically
2. Add your own email sequence on top of Smart Retries:

Tell AI:

Create a dunning email sequence for failed payments:
- Day 0: "Your payment didn't go through. Update your card." + Customer Portal link
- Day 3: "Reminder: your account is at risk."
- Day 7: "Final warning before downgrade."
- Day 14: Account downgraded. "We miss you" + reactivation link.
Tone: helpful, not threatening.

Tax Collection

You are legally required to collect sales tax / VAT in most jurisdictions.

Option 1: Stripe Tax (Recommended)

1. Settings -> Tax -> Enable Stripe Tax
2. Set your business address
3. Stripe automatically calculates and collects tax by customer location
4. Cost: 0.5% per transaction. Worth it.

Option 2: Merchant of Record

If tax terrifies you, use Paddle or Lemon Squeezy. They handle all tax collection and remittance. Trade-off: higher fees (~5-10% vs Stripe's ~3%) and less control.

Tax Registration

• Start with your home state/country. Expand as revenue grows.
• US: Register in your home state + states where you exceed ~$100K in sales
• EU: Need VAT registration if selling to EU customers

Pricing Implementation Patterns

Testing Checklist

Test every flow in Stripe test mode before going live:

- [ ] Successful purchase (card: 4242424242424242)
- [ ] Failed payment (card: 4000000000000002)
- [ ] 3D Secure authentication (card: 4000002500003155)
- [ ] Subscription cancellation and access revocation
- [ ] Plan upgrade (check proration)
- [ ] Plan downgrade (check scheduling)
- [ ] Customer Portal access
- [ ] Webhook delivery (Stripe Dashboard -> Webhooks -> logs)
- [ ] Trial expiration and conversion to paid

Going Live Checklist

- [ ] Switch to live mode in Stripe Dashboard
- [ ] Replace test API keys with live keys in production
- [ ] Update webhook endpoint URL and signing secret
- [ ] Verify Stripe Tax is enabled in live mode
- [ ] Make a real $1 purchase with your own card
- [ ] Verify webhook received in Stripe logs
- [ ] Refund your test purchase

Stripe Fees

Common Mistakes