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 |

Source & license

This open-source skill is cataloged on AgentStack and links to its original source — we do not rehost the code.

• Author: whawkinsiv
• Source: whawkinsiv/solo-founder-skills
• License: MIT

Install and usage instructions live in the source repository linked above.