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:

/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:

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:

STRIPE_SECRET_KEY=sk_live_... node scripts/verify-stripe-portal.js

---

🧪 TESTING (After Manual Tasks Complete)

Local Testing Workflow:

1. Ensure Development Server Running:

   # 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:

   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:

   ssh -i ~/.ssh/tractatus_deploy ubuntu@vps-93a693da.vps.ovh.net "systemctl status tractatus"
   

2. Deploy to Production:

   ./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:

   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:

# Shell diagnostic
/tmp/check-stripe-bank-name.sh

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

Check Customer Portal Configuration:

# Test mode
node scripts/verify-stripe-portal.js

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

Check Server Status:

# Local
curl http://localhost:9000/api/koha/transparency

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

Test Portal Endpoint:

# 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