tractatus/docs/STRIPE_CUSTOMER_PORTAL_NEXT_STEPS.md

# Stripe Customer Portal - Implementation Summary & Next Steps

**Date**: 2025-10-18
**Status**: Code Complete - Awaiting Manual Dashboard Configuration
**Priority**: Bank account name = URGENT (before Oct 25), Portal = Medium

---

## ✅ COMPLETED WORK

### 1. Customer Portal Code Implementation

All code for the Stripe Customer Portal integration has been completed and is ready to deploy:

#### Backend Changes:
- **src/controllers/koha.controller.js** (lines 253-307)
  - New `createPortalSession` endpoint
  - Finds customer by email
  - Creates Stripe billing portal session
  - Returns portal URL for redirect

- **src/routes/koha.routes.js** (lines 51-55)
  - Added POST /api/koha/portal route
  - Applied rate limiting (10 requests/hour)

#### Frontend Changes:
- **public/koha.html** (lines 295-332)
  - "Manage Your Subscription" section
  - Email input with validation
  - Loading and error states
  - Accessible markup

- **public/js/koha-donation.js** (lines 291-415)
  - `handleManageSubscription()` function
  - Email validation
  - API integration
  - Portal redirect logic

- **public/js/components/navbar.js** (lines 98-100)
  - Added "🤝 Support (Koha)" link to navigation menu

- **public/locales/en/koha.json** (lines 65-71, 85)
  - Internationalization for portal UI
  - Updated FAQ with cancellation instructions

### 2. Verification & Diagnostic Tools Created

#### Bank Account Verification:
- **scripts/check-stripe-bank-account.js**
  - Node.js script to check account configuration
  - Shows account type, country, email
  - Provides guidance for manual verification
  
- **/tmp/check-stripe-bank-name.sh**
  - Shell script diagnostic
  - Checks balance and payout status
  - Step-by-step dashboard checklist

#### Customer Portal Verification:
- **scripts/verify-stripe-portal.js**
  - Comprehensive portal configuration checker
  - Lists all configured features
  - Validates against requirements
  - Provides checklist for missing features
  - Works for both test and live mode

### 3. Documentation Created

- **STRIPE_PORTAL_CONFIGURATION_STEPS.md** - Detailed 8-step guide
- **STRIPE_FIX_FOR_JOHN_STROH.md** - Specific fix for bank account name
- **FIND_STRIPE_BANK_HOLDER_NAME.md** - Finding the dashboard setting
- **STRIPE_PAYOUT_DIAGNOSTIC.md** - Troubleshooting guide
- **STRIPE_BANK_NAME_MATCHING.md** - TSB requirements
- **STRIPE_ACCOUNT_NAME_FIX.md** - General account name fix guide

### 4. Environment Cleanup

- ✅ Background Stripe webhook listeners closed
- ✅ No orphaned processes
- ✅ Development server running on port 9000

---

## ⚠️ MANUAL TASKS REQUIRED

The following tasks **cannot** be automated and require manual action in the Stripe Dashboard:

### URGENT - Task 1: Update Bank Account Holder Name (Before Oct 25)

**Why Urgent**: Your first payout ($4.56 NZD) becomes available on Oct 25. If the bank account holder name doesn't match "John Geoffrey Stroh", TSB will reject the payout.

**Current Status**:
- ✅ Stripe account name: "John Geoffrey Stroh" (DONE)
- ❌ Bank account holder name: Needs verification/update

**How to Fix**:

1. Open: https://dashboard.stripe.com/settings/payouts
2. Scroll to: "Bank accounts and debit cards" section
3. Find: NZD account ending in "6-85"
4. Click: On the account row
5. Look for: "Account holder name" field
6. Should say: "John Geoffrey Stroh" ✅
7. If not: Change it to "John Geoffrey Stroh"

**If you can't edit the field**:
- Option A: Remove bank account, then re-add with correct name
  - Account number: 15-3959-0667036-85
  - Currency: NZD
  - Holder: John Geoffrey Stroh
  
- Option B: Contact Stripe Support
  - https://dashboard.stripe.com/support
  - Request: "Update bank account holder name to 'John Geoffrey Stroh' for NZD account ending in 6-85"

**Verify After**:
```bash
/tmp/check-stripe-bank-name.sh
```

**Deadline**: Before October 25, 2025 (first payout date)

---

### Task 2: Configure Customer Portal (Test Mode)

**Time Required**: ~10 minutes
**Priority**: Medium (needed before testing locally)

**Steps**:

1. **Open Test Mode Dashboard**:
   - URL: https://dashboard.stripe.com/test/settings/billing/portal

2. **Enable Features** (click each checkbox):
   - ☐ Customer can edit email address
   - ☐ Customer can update payment methods
   - ☐ Customer can cancel subscriptions
   - ☐ Customer can view invoice history

3. **Configure Cancellation Survey**:
   - ☐ Enable "Ask why they're cancelling"
   - ☐ Question 1: "Why are you cancelling?"
     - Options:
       - Too expensive
       - No longer need it
       - Found alternative
       - Other
   - ☐ Question 2: "How can we improve?" (optional text field)

4. **Business Information**:
   - ☐ Business name: `Tractatus AI Safety Framework`
   - ☐ Support email: `support@agenticgovernance.digital`
   - ☐ Privacy policy: (optional)
   - ☐ Terms of service: (optional)

5. **Save Configuration**:
   - ☐ Click "Save" or "Activate"

**Verify After**:
```bash
node scripts/verify-stripe-portal.js
```

Expected output: All checkboxes ✅

**Troubleshooting**:
- If survey doesn't appear: Check "Subscription cancellation" is enabled
- If can't save: Ensure all required fields filled
- Full guide: docs/STRIPE_PORTAL_CONFIGURATION_STEPS.md

---

### Task 3: Configure Customer Portal (Live Mode)

**Time Required**: ~10 minutes
**Priority**: Medium (needed before production deployment)

**Steps**:

Same as Task 2, but using live mode dashboard:
- URL: https://dashboard.stripe.com/settings/billing/portal

**Important**: Configuration must match test mode exactly.

**Verify After**:
```bash
STRIPE_SECRET_KEY=sk_live_... node scripts/verify-stripe-portal.js
```

---

## 🧪 TESTING (After Manual Tasks Complete)

### Local Testing Workflow:

1. **Ensure Development Server Running**:
   ```bash
   # If not running:
   npm start
   ```

2. **Test Customer Portal Access**:
   - Open: http://localhost:9000/koha.html
   - Scroll to: "Manage Your Subscription" section
   - Enter email: (use email from test donation)
   - Click: "Manage"
   - Expected: Redirect to Stripe Customer Portal
   - Verify: Can view subscription details
   - Verify: Can update payment method
   - Verify: Can cancel subscription
   - Verify: Cancellation survey appears

3. **Test Cancellation Flow**:
   - In portal, click "Cancel subscription"
   - Should show exit survey:
     - "Why are you cancelling?" (radio buttons)
     - "How can we improve?" (optional text)
   - Complete survey
   - Confirm cancellation
   - Verify: Redirected back to koha.html
   - Verify: Subscription shows as cancelled

4. **Verify Navigation**:
   - Go to: http://localhost:9000
   - Click: Hamburger menu (☰)
   - Verify: "🤝 Support (Koha)" link appears
   - Click: Link
   - Verify: Redirects to koha.html

5. **Check Logs**:
   ```bash
   tail -f /tmp/server-restart.log
   ```
   - Look for: `[KOHA] Customer portal session created for [email]`
   - Should be: INFO level (not ERROR)

### Test Checklist:

- ☐ Portal loads without errors
- ☐ Email validation works
- ☐ Invalid email shows error message
- ☐ Valid email redirects to Stripe portal
- ☐ Cancellation survey appears
- ☐ All survey options work
- ☐ Optional text field works
- ☐ Return URL redirects to koha.html
- ☐ Navbar link works
- ☐ No console errors
- ☐ No server errors in logs

---

## 🚀 DEPLOYMENT

### Prerequisites:

- ✅ Code changes complete (DONE)
- ☐ Bank account holder name updated
- ☐ Customer Portal configured (test mode)
- ☐ Customer Portal configured (live mode)
- ☐ Local testing passed

### Deployment Steps:

1. **Verify Production Server Status**:
   ```bash
   ssh -i ~/.ssh/tractatus_deploy ubuntu@vps-93a693da.vps.ovh.net "systemctl status tractatus"
   ```

2. **Deploy to Production**:
   ```bash
   ./scripts/deploy-full-project-SAFE.sh
   ```

   This will deploy:
   - src/controllers/koha.controller.js
   - src/routes/koha.routes.js
   - public/koha.html
   - public/js/koha-donation.js
   - public/js/components/navbar.js
   - public/locales/en/koha.json

3. **Verify Deployment**:
   - Check: https://agenticgovernance.digital/koha.html
   - Verify: "Manage Your Subscription" section appears
   - Check: Navbar menu shows Koha link
   - Test: Portal access with real customer email

4. **Monitor Logs**:
   ```bash
   ssh -i ~/.ssh/tractatus_deploy ubuntu@vps-93a693da.vps.ovh.net "tail -f /var/log/tractatus/app.log"
   ```

   Look for:
   - ✅ No errors on page load
   - ✅ Portal sessions created successfully
   - ✅ No 500 errors

### Production Testing:

- ☐ Use LIVE mode credentials
- ☐ Test with real customer email (from actual donation)
- ☐ Verify portal redirect works
- ☐ Verify cancellation survey appears (don't complete it!)
- ☐ Test return URL redirect
- ☐ Monitor logs for errors

---

## 📊 VERIFICATION COMMANDS

### Check Bank Account Configuration:
```bash
# Shell diagnostic
/tmp/check-stripe-bank-name.sh

# Node.js diagnostic
node scripts/check-stripe-bank-account.js
```

### Check Customer Portal Configuration:
```bash
# Test mode
node scripts/verify-stripe-portal.js

# Live mode
STRIPE_SECRET_KEY=sk_live_... node scripts/verify-stripe-portal.js
```

### Check Server Status:
```bash
# Local
curl http://localhost:9000/api/koha/transparency

# Production
curl https://agenticgovernance.digital/api/koha/transparency
```

### Test Portal Endpoint:
```bash
# Test mode (local)
curl -X POST http://localhost:9000/api/koha/portal \
  -H "Content-Type: application/json" \
  -d '{"email": "test@example.com"}'

# Should return portal URL or 404 if no subscription
```

---

## ⏰ TIMELINE

### Immediate (Today):
1. Update bank account holder name (URGENT - before Oct 25)
2. Configure Customer Portal (test mode)
3. Test locally
4. Configure Customer Portal (live mode)

### Tomorrow or Next:
5. Deploy to production
6. Monitor first real customer using portal
7. Verify payout succeeds (Oct 25-28)

### Oct 25-28:
- First payout attempt (if bank name correct: ✅ succeeds)
- Money arrives in TSB account Oct 27-30

---

## 📋 SUPPORT INFORMATION

### If Payout Fails:
1. Check: Bank account holder name matches "John Geoffrey Stroh"
2. Check: TSB account is active and accepting payments
3. Contact: Stripe Support (https://dashboard.stripe.com/support)
4. Contact: TSB (0800 872 000)

### If Portal Doesn't Work:
1. Verify: Portal configured in correct mode (test/live)
2. Check: STRIPE_SECRET_KEY matches mode
3. Verify: Customer has active subscription
4. Check: Email matches subscription email exactly
5. Review: Server logs for errors

### If Tests Fail:
1. Clear browser cache
2. Check: .env has correct keys
3. Verify: Server running on port 9000
4. Check: MongoDB running on port 27017
5. Review: Console errors (F12)

---

## 📖 REFERENCE DOCUMENTS

- **Configuration**: docs/STRIPE_PORTAL_CONFIGURATION_STEPS.md
- **Bank Account Fix**: docs/STRIPE_FIX_FOR_JOHN_STROH.md
- **Finding Settings**: docs/FIND_STRIPE_BANK_HOLDER_NAME.md
- **Troubleshooting**: docs/STRIPE_PAYOUT_DIAGNOSTIC.md
- **TSB Requirements**: docs/STRIPE_BANK_NAME_MATCHING.md

---

## ✅ CURRENT STATUS SUMMARY

| Task | Status | Action Required |
|------|--------|----------------|
| Code Implementation | ✅ Complete | None - ready to deploy |
| Verification Tools | ✅ Complete | None - ready to use |
| Documentation | ✅ Complete | None - available in docs/ |
| Bank Account Name | ⚠️ Pending | YOU - Update in dashboard |
| Portal Config (Test) | ⚠️ Pending | YOU - Configure in dashboard |
| Portal Config (Live) | ⚠️ Pending | YOU - Configure in dashboard |
| Local Testing | ⏳ Blocked | Waiting for portal config |
| Production Deployment | ⏳ Blocked | Waiting for all above |

---

## 🎯 NEXT ACTIONS FOR YOU

**Priority 1 (URGENT - Before Oct 25)**:
- [ ] Update Stripe bank account holder name to "John Geoffrey Stroh"
- [ ] Verify using: `/tmp/check-stripe-bank-name.sh`

**Priority 2 (This Week)**:
- [ ] Configure Customer Portal (test mode)
- [ ] Verify using: `node scripts/verify-stripe-portal.js`
- [ ] Test locally
- [ ] Configure Customer Portal (live mode)

**Priority 3 (After Testing)**:
- [ ] Deploy to production: `./scripts/deploy-full-project-SAFE.sh`
- [ ] Monitor production logs
- [ ] Test with real customer email

---

**Last Updated**: 2025-10-18
**Code Complete**: Yes ✅
**Ready to Deploy**: After manual dashboard tasks ✅
**Estimated Time to Complete**: 30 minutes of dashboard work