/payments

name: payments
description: "Use this skill when the user needs to set up Stripe, implement subscriptions, handle billing, configure payment plans, manage failed payments, deal with refunds, set up tax collection, or troubleshoot payment issues. Covers Stripe configuration, subscription lifecycle, dunning, tax compliance, and billing operations for bootstrapped SaaS."

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 auto