# Stripe Customer Portal Setup Guide

## Overview

The Stripe Customer Portal allows donors to self-service manage their subscriptions without contacting support. This includes:
- Viewing subscription details and invoices
- Updating payment methods
- Cancelling subscriptions
- Viewing payment history

## Implementation Status

✅ Backend endpoint created: `POST /api/koha/portal`
✅ Frontend UI added to koha.html
✅ i18n translations added
✅ Route configured in koha.routes.js

⚠️ **REQUIRED**: Configure Customer Portal in Stripe Dashboard (both test and live mode)

---

## Step 1: Configure Test Mode Portal

1. Go to: https://dashboard.stripe.com/test/settings/billing/portal
2. Click **"Activate test mode"** or **"Configure"**
3. Enable the following features:

### Customer Information
- ✅ **Email address**: Allow customers to edit
- ✅ **Payment methods**: Allow customers to update

### Subscriptions
- ✅ **Allow customers to cancel subscriptions**: Yes
- **Cancellation behavior**: Cancel at period end (recommended)
- ✅ **Cancellation survey**: Enable with custom questions:
  - "Why are you cancelling?" (required)
    - Too expensive
    - No longer need it
    - Found an alternative
    - Not what I expected
    - Other (with text input)
  - "How can we improve?" (optional, text input)

### Invoice History
- ✅ **Show invoice history**: Yes

### Business Information
- **Business name**: Tractatus AI Safety Framework
- **Support email**: support@agenticgovernance.digital
- **Privacy policy URL**: https://agenticgovernance.digital/about/values.html
- **Terms of service URL**: https://agenticgovernance.digital/about/values.html

4. Click **"Save changes"**

---

## Step 2: Configure Live Mode Portal

1. Switch to **Live mode** in Stripe Dashboard (toggle in top-right)
2. Go to: https://dashboard.stripe.com/settings/billing/portal
3. Repeat **exact same configuration** as test mode above
4. Click **"Save changes"**

---

## Step 3: Test the Portal (Test Mode)

1. Open http://localhost:9000/koha.html in your browser
2. Scroll to the **"Manage Your Subscription"** section
3. Enter the email address of a test subscription (e.g., the one you created during testing)
4. Click **"Manage"**
5. You should be redirected to the Stripe Customer Portal
6. Verify:
   - Subscription details are visible
   - Payment method can be updated
   - Cancellation option is available
   - Cancellation survey appears when attempting to cancel

---

## Step 4: Deploy to Production

Once test mode is configured and working:

1. **Configure live mode** (Step 2 above)
2. **Deploy updated files**:
   ```bash
   ./scripts/deploy-full-project-SAFE.sh
   ```

3. **Files being deployed**:
   - `src/controllers/koha.controller.js` (new createPortalSession endpoint)
   - `src/routes/koha.routes.js` (new /portal route)
   - `public/koha.html` (new Manage Subscription section)
   - `public/js/koha-donation.js` (new portal functionality)
   - `public/locales/en/koha.json` (new translations)

4. **Verify production**:
   - Go to https://agenticgovernance.digital/koha.html
   - Test "Manage Subscription" with your live subscription email
   - Confirm portal redirect works
   - Test cancellation flow (you can cancel the test $5 subscription if desired)

---

## Exit Survey Data Access

After customers cancel subscriptions, you can view their survey responses:

1. Go to Stripe Dashboard → **Billing** → **Subscriptions**
2. Click on a cancelled subscription
3. Look for **"Cancellation feedback"** section
4. Survey responses will be displayed there

This data helps you understand churn reasons and improve the donation experience.

---

## Security Notes

- ✅ Email verification: The portal endpoint only accepts email addresses that match Stripe customer records
- ✅ Rate limiting: Portal endpoint is protected by rate limiter (10 requests/hour per IP)
- ✅ No authentication required: This is intentional - Stripe Customer Portal has its own secure authentication via email
- ✅ Session expiration: Portal sessions expire after 30 minutes

---

## Troubleshooting

### Error: "No subscription found for this email address"
- The email doesn't have an active Stripe subscription
- Check that the email matches exactly (case-insensitive)
- Verify the subscription exists in Stripe Dashboard

### Error: "No configuration provided..."
- Customer Portal not configured in Stripe Dashboard
- Follow Step 1 (test) or Step 2 (live) above

### Portal session created but redirect fails
- Check browser console for errors
- Verify `FRONTEND_URL` in .env is correct
- Check that koha-donation.js has `window.location.href = data.data.url;`

---

## Next Steps

1. ✅ Configure test mode portal (Step 1)
2. ✅ Test locally (Step 3)
3. ✅ Configure live mode portal (Step 2)
4. ✅ Deploy to production (Step 4)
5. 🎉 Donors can now self-manage their subscriptions!

---

**Last Updated**: 2025-10-18
**Status**: Ready for configuration and deployment