2298d36bed
- Create Economist SubmissionTracking package correctly: * mainArticle = full blog post content * coverLetter = 216-word SIR— letter * Links to blog post via blogPostId - Archive 'Letter to The Economist' from blog posts (it's the cover letter) - Fix date display on article cards (use published_at) - Target publication already displaying via blue badge Database changes: - Make blogPostId optional in SubmissionTracking model - Economist package ID: 68fa85ae49d4900e7f2ecd83 - Le Monde package ID: 68fa2abd2e6acd5691932150 Next: Enhanced modal with tabs, validation, export 🤖 Generated with [Claude Code](https://claude.com/claude-code) Co-Authored-By: Claude <noreply@anthropic.com>
157 lines
4.9 KiB
Markdown
157 lines
4.9 KiB
Markdown
# 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
|