feat: implement Koha donation system backend (Phase 3)
Backend API complete for NZD donation processing via Stripe.
**New Backend Components:**
Database Model:
- src/models/Donation.model.js - Donation schema with privacy-first design
- Anonymous donations by default, opt-in public acknowledgement
- Monthly recurring and one-time donation support
- Stripe integration (customer, subscription, payment tracking)
- Public transparency metrics aggregation
- Admin statistics and reporting
Service Layer:
- src/services/koha.service.js - Stripe integration service
- Checkout session creation (monthly + one-time)
- Webhook event processing (8 event types)
- Subscription management (cancel, update)
- Receipt email generation (placeholder)
- Transparency metrics calculation
- Based on passport-consolidated StripeService pattern
Controller:
- src/controllers/koha.controller.js - HTTP request handlers
- POST /api/koha/checkout - Create donation checkout
- POST /api/koha/webhook - Stripe webhook receiver
- GET /api/koha/transparency - Public metrics
- POST /api/koha/cancel - Cancel recurring donation
- GET /api/koha/verify/:sessionId - Verify payment status
- GET /api/koha/statistics - Admin statistics
Routes:
- src/routes/koha.routes.js - API endpoint definitions
- src/routes/index.js - Koha routes registered
**Infrastructure:**
Server Configuration:
- src/server.js - Raw body parsing for Stripe webhooks
- Required for webhook signature verification
- Route-specific middleware for /api/koha/webhook
Environment Variables:
- .env.example - Koha/Stripe configuration template
- Stripe API keys (reuses passport-consolidated account)
- Price IDs for NZD monthly tiers ($5, $15, $50)
- Webhook secret for signature verification
- Frontend URL for payment redirects
**Documentation:**
- docs/KOHA_STRIPE_SETUP.md - Complete setup guide
- Step-by-step Stripe Dashboard configuration
- Product and price creation instructions
- Webhook endpoint setup
- Testing procedures with test cards
- Security and compliance notes
- Production deployment checklist
**Key Features:**
✅ Privacy-first design (anonymous by default)
✅ NZD currency support (New Zealand Dollars)
✅ Monthly recurring subscriptions ($5, $15, $50 NZD)
✅ One-time custom donations
✅ Public transparency dashboard metrics
✅ Stripe webhook signature verification
✅ Subscription cancellation support
✅ Receipt tracking (email generation ready)
✅ Admin statistics and reporting
**Architecture:**
- Reuses existing Stripe account from passport-consolidated
- Separate webhook endpoint (/api/koha/webhook vs /api/stripe/webhook)
- Separate MongoDB collection (koha_donations)
- Compatible with existing infrastructure
**Next Steps:**
- Create Stripe products in Dashboard (use setup guide)
- Build donation form frontend UI
- Create transparency dashboard page
- Implement receipt email service
- Test end-to-end with Stripe test cards
- Deploy to production
🤖 Generated with [Claude Code](https://claude.com/claude-code)
Co-Authored-By: Claude <noreply@anthropic.com>
ebfeadb900