1 files changed, 114 insertions, 0 deletions
diff --git a/Biz/PodcastItLater/STRIPE_TESTING.md b/Biz/PodcastItLater/STRIPE_TESTING.md
new file mode 100644
index 0000000..1461c06
--- /dev/null
+++ b/Biz/PodcastItLater/STRIPE_TESTING.md
@@ -0,0 +1,114 @@
+# Stripe Testing Guide
+
+## Testing Stripe Integration Without Real Transactions
+
+### 1. Use Stripe Test Mode
+
+Stripe provides test API keys that allow you to simulate payments without real money:
+
+1. Get your test keys from https://dashboard.stripe.com/test/apikeys
+2. Set environment variables with test keys:
+   ```bash
+   export STRIPE_SECRET_KEY="sk_test_..."
+   export STRIPE_WEBHOOK_SECRET="whsec_test_..."
+   export STRIPE_PRICE_ID_PRO="price_test_..."
+   ```
+
+### 2. Use Stripe Test Cards
+
+In test mode, use these test card numbers:
+- **Success**: `4242 4242 4242 4242`
+- **Decline**: `4000 0000 0000 0002`
+- **3D Secure**: `4000 0025 0000 3155`
+
+Any future expiry date and any 3-digit CVC will work.
+
+### 3. Trigger Test Webhooks
+
+Use Stripe CLI to trigger webhook events locally:
+
+```bash
+# Install Stripe CLI
+# https://stripe.com/docs/stripe-cli
+
+# Login
+stripe login
+
+# Forward webhooks to local server
+stripe listen --forward-to localhost:8000/stripe/webhook
+
+# Trigger specific events
+stripe trigger checkout.session.completed
+stripe trigger customer.subscription.created
+stripe trigger customer.subscription.updated
+stripe trigger invoice.payment_failed
+```
+
+### 4. Run Unit Tests
+
+The billing module includes unit tests that mock Stripe webhooks:
+
+```bash
+# Run billing tests
+AREA=Test python3 Biz/PodcastItLater/Billing.py test
+
+# Or use bild
+bild --test Biz/PodcastItLater/Billing.py
+```
+
+### 5. Test Migration on Production
+
+To fix the production database missing columns issue, you need to trigger the migration.
+
+The migration runs automatically when `Database.init_db()` is called, but production may have an old database.
+
+**Option A: Restart the web service**
+The init_db() runs on startup, so restarting should apply migrations.
+
+**Option B: Run migration manually**
+```bash
+# SSH to production
+# Run Python REPL with proper environment
+python3
+>>> import os
+>>> os.environ["AREA"] = "Live"
+>>> os.environ["DATA_DIR"] = "/var/podcastitlater"
+>>> import Biz.PodcastItLater.Core as Core
+>>> Core.Database.init_db()
+```
+
+### 6. Verify Database Schema
+
+Check that billing columns exist:
+
+```bash
+sqlite3 /var/podcastitlater/podcast.db
+.schema users
+```
+
+Should show:
+- `stripe_customer_id TEXT`
+- `stripe_subscription_id TEXT`
+- `subscription_status TEXT`
+- `current_period_start TEXT`
+- `current_period_end TEXT`
+- `plan_tier TEXT NOT NULL DEFAULT 'free'`
+- `cancel_at_period_end INTEGER DEFAULT 0`
+
+### 7. End-to-End Test Flow
+
+1. Start in test mode: `AREA=Test PORT=8000 python3 Biz/PodcastItLater/Web.py`
+2. Login with test account
+3. Go to /billing
+4. Click "Upgrade Now"
+5. Use test card: 4242 4242 4242 4242
+6. Stripe CLI will forward webhook to your local server
+7. Verify subscription updated in database
+
+### 8. Common Issues
+
+**KeyError in webhook**: Make sure you're using safe `.get()` access for all Stripe object fields, as the structure can vary.
+
+**Database column missing**: Run migrations by restarting the service or calling `Database.init_db()`.
+
+**Webhook signature verification fails**: Make sure `STRIPE_WEBHOOK_SECRET` matches your endpoint secret from Stripe dashboard.