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:

Event	Subscription Status	Your App Should
Payment succeeds after checkout	active	Grant paid features
Card fails on renewal	past_due	Show "update payment" banner
All retries fail	unpaid or canceled	Downgrade to free tier
Customer cancels	active (until period end)	Continue access until period ends, then downgrade
Customer upgrades	active (new plan)	Prorate and grant new plan immediately
Customer downgrades	active (current plan)	Schedule change for end of billing period

---

Essential Webhooks

Your app MUST handle these events:

Event	What Happened	Your App Should
checkout.session.completed	Customer finished checkout	Activate subscription, grant access
customer.subscription.updated	Plan changed or status changed	Update user's plan in database
customer.subscription.deleted	Subscription fully canceled	Revoke paid access, move to free tier
invoice.payment_failed	Recurring payment failed	Show "update payment" banner, send email

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

Pattern	How It Works	Stripe Setup
Free trial -> Paid	14-day trial, no card. Enter card to continue.	Track trial in your DB. Create Checkout Session when trial ends.
Freemium -> Upgrade	Free forever. Upgrade when hitting limits.	No Stripe for free users. Checkout Session on upgrade only.
Card-required trial	Enter card at signup. Auto-charges after 14 days.	Create subscription with trial_period_days: 14.

---

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

Fee	Amount
Standard (US cards)	2.9% + $0.30 per transaction
International cards	+1.5%
Stripe Tax	+0.5% per transaction
Chargebacks	$15 per dispute
Monthly/setup fees	None

---

Common Mistakes

Mistake	Fix
Hardcoding prices in your app	Use Stripe Price IDs from the Dashboard
Skipping webhook signature verification	Always verify — prevents spoofed events
Not handling past_due status	Show a banner, send dunning emails
Granting access based on Checkout redirect only	Use webhooks — redirects can fail silently
Forgetting to test decline cards	Test every failure path, not just happy path
Ignoring tax collection	Set up Stripe Tax or use a Merchant of Record
Building your own billing portal	Use Stripe's hosted Customer Portal