tractatus/docs/KOHA_STRIPE_SETUP.md

# Koha Donation System - Stripe Setup Guide

**Project:** Tractatus Framework
**Feature:** Phase 3 - Koha (Donation) System
**Date:** 2025-10-08
**Status:** Development

---

## Overview

The Koha donation system uses the existing Stripe account from `passport-consolidated` to process donations in NZD (New Zealand Dollars). This document guides you through setting up the required Stripe products and webhooks.

**Account:** Same Stripe test account as passport-consolidated
**Currency:** NZD (New Zealand Dollars)
**Payment Types:** Recurring monthly subscriptions + one-time donations

---

## 1. Stripe Products to Create

### Product: "Tractatus Framework Support"

**Description:** "Support the development and maintenance of the Tractatus AI Safety Framework. Your donation helps fund hosting, development, research, and community building."

**Statement Descriptor:** "TRACTATUS FRAMEWORK"
**Category:** Charity/Non-profit

---

## 2. Price IDs to Create

### 2.1 Monthly Tier: $5 NZD/month

```
Product: Tractatus Framework Support
Price:   $5.00 NZD
Billing: Recurring - Monthly
ID:      price_<generated_by_stripe>
```

**After creation, copy the Price ID and update .env:**
```bash
STRIPE_KOHA_5_PRICE_ID=price_<your_actual_price_id>
```

---

### 2.2 Monthly Tier: $15 NZD/month

```
Product: Tractatus Framework Support
Price:   $15.00 NZD
Billing: Recurring - Monthly
ID:      price_<generated_by_stripe>
```

**After creation, copy the Price ID and update .env:**
```bash
STRIPE_KOHA_15_PRICE_ID=price_<your_actual_price_id>
```

---

### 2.3 Monthly Tier: $50 NZD/month

```
Product: Tractatus Framework Support
Price:   $50.00 NZD
Billing: Recurring - Monthly
ID:      price_<generated_by_stripe>
```

**After creation, copy the Price ID and update .env:**
```bash
STRIPE_KOHA_50_PRICE_ID=price_<your_actual_price_id>
```

---

### 2.4 One-Time Donation (Custom Amount)

**Note:** For one-time donations, we don't create a fixed price. Instead, the donation form sends a custom amount to Stripe Checkout. No Price ID needed for this - the code handles it dynamically.

---

## 3. Webhook Configuration

### Create Webhook Endpoint

**URL (Development):**
```
http://localhost:9000/api/koha/webhook
```

**URL (Production):**
```
https://agenticgovernance.digital/api/koha/webhook
```

### Events to Subscribe To

Select these events in Stripe Dashboard:

- ✅ `checkout.session.completed`
- ✅ `payment_intent.succeeded`
- ✅ `payment_intent.payment_failed`
- ✅ `invoice.paid` (recurring payments)
- ✅ `invoice.payment_failed`
- ✅ `customer.subscription.created`
- ✅ `customer.subscription.updated`
- ✅ `customer.subscription.deleted`

### After Creating Webhook

Copy the **Webhook Signing Secret** and update .env:

```bash
STRIPE_KOHA_WEBHOOK_SECRET=whsec_<your_webhook_secret>
```

---

## 4. Testing Configuration

### Stripe Test Cards

Use these test cards for development:

| Card Number         | Scenario                    |
|---------------------|----------------------------|
| 4242 4242 4242 4242 | Successful payment         |
| 4000 0027 6000 3184 | 3D Secure required         |
| 4000 0000 0000 9995 | Payment declined           |
| 4000 0000 0000 0341 | Attaching card fails       |

**Expiry:** Any future date
**CVC:** Any 3 digits
**ZIP:** Any valid postal code

---

## 5. Step-by-Step Setup Instructions

### Step 1: Access Stripe Dashboard

1. Go to [dashboard.stripe.com](https://dashboard.stripe.com)
2. Ensure you're in **Test Mode** (toggle in top-right)
3. Log in with passport-consolidated credentials

### Step 2: Create Product

1. Navigate to **Products** → **Add Product**
2. Product name: `Tractatus Framework Support`
3. Description: `Support the development and maintenance of the Tractatus AI Safety Framework`
4. Image: Upload `/home/theflow/projects/tractatus/public/images/tractatus-icon.svg`
5. Click **Save Product**

### Step 3: Create Price IDs

For each monthly tier ($5, $15, $50):

1. In the product page, click **Add another price**
2. Select **Recurring**
3. Billing period: **Monthly**
4. Price: Enter amount (e.g., 5.00)
5. Currency: **NZD**
6. Click **Save**
7. **Copy the Price ID** (starts with `price_`)
8. Paste into `.env` file

### Step 4: Set Up Webhook

1. Navigate to **Developers** → **Webhooks**
2. Click **Add endpoint**
3. Endpoint URL: `http://localhost:9000/api/koha/webhook` (for development)
4. Description: `Tractatus Koha - Development`
5. Events to send: Select all 8 events listed in Section 3
6. Click **Add endpoint**
7. **Copy the Signing Secret** (click "Reveal")
8. Update `.env` with the webhook secret

### Step 5: Verify Configuration

Run this command to test:

```bash
npm run dev
```

Check logs for:
```
✅ Stripe webhook ready: /api/koha/webhook
✅ Koha service initialized
```

---

## 6. Environment Variables Checklist

After setup, your `.env` should have:

```bash
# Stripe Keys (from passport-consolidated)
STRIPE_SECRET_KEY=sk_test_51RX67k...
STRIPE_PUBLISHABLE_KEY=pk_test_51RX67k...

# Webhook Secret (from Step 4)
STRIPE_KOHA_WEBHOOK_SECRET=whsec_...

# Price IDs (from Step 3)
STRIPE_KOHA_5_PRICE_ID=price_...
STRIPE_KOHA_15_PRICE_ID=price_...
STRIPE_KOHA_50_PRICE_ID=price_...

# Frontend URL
FRONTEND_URL=http://localhost:9000
```

---

## 7. Testing the Integration

### Test API Endpoint

```bash
curl -X POST http://localhost:9000/api/koha/checkout \
  -H "Content-Type: application/json" \
  -d '{
    "amount": 1500,
    "frequency": "monthly",
    "tier": "15",
    "donor": {
      "name": "Test Donor",
      "email": "test@example.com"
    },
    "public_acknowledgement": false
  }'
```

**Expected Response:**
```json
{
  "success": true,
  "data": {
    "sessionId": "cs_test_...",
    "checkoutUrl": "https://checkout.stripe.com/c/pay/cs_test_...",
    "frequency": "monthly",
    "amount": 15
  }
}
```

### Test Webhook Locally

Use Stripe CLI for local webhook testing:

```bash
# Install Stripe CLI
brew install stripe/stripe-cli/stripe

# Forward webhooks to local server
stripe listen --forward-to localhost:9000/api/koha/webhook

# Trigger test event
stripe trigger checkout.session.completed
```

---

## 8. Production Setup

### Before Going Live

1. **Switch to Live Mode** in Stripe Dashboard
2. **Create live webhook** endpoint:
   - URL: `https://agenticgovernance.digital/api/koha/webhook`
   - Same 8 events as development
3. **Obtain live API keys** (starts with `sk_live_` and `pk_live_`)
4. **Update production .env** with live keys
5. **Test with real card** (small amount)
6. **Verify webhook delivery** in Stripe Dashboard

### Production Environment Variables

```bash
NODE_ENV=production
STRIPE_SECRET_KEY=sk_live_...
STRIPE_PUBLISHABLE_KEY=pk_live_...
STRIPE_KOHA_WEBHOOK_SECRET=whsec_live_...
FRONTEND_URL=https://agenticgovernance.digital
```

---

## 9. Monitoring & Troubleshooting

### Check Webhook Deliveries

1. Stripe Dashboard → **Developers** → **Webhooks**
2. Click on your endpoint
3. View **Recent deliveries**
4. Check for failed deliveries (red icons)

### Common Issues

| Issue | Solution |
|-------|----------|
| Webhook signature verification fails | Ensure `STRIPE_KOHA_WEBHOOK_SECRET` matches Dashboard |
| Price ID not found | Verify Price IDs in `.env` match Stripe Dashboard |
| Redirects fail after payment | Check `FRONTEND_URL` is correct |
| Donations not recording | Check MongoDB connection and logs |

### Debug Logging

Enable detailed Stripe logs:

```bash
# In koha.service.js, logger.info statements will show:
[KOHA] Creating checkout session: monthly donation of NZD $15.00
[KOHA] Checkout session created: cs_test_...
[KOHA] Processing webhook event: checkout.session.completed
[KOHA] Donation recorded: NZD $15.00
```

---

## 10. Security Considerations

### Webhook Security

- ✅ Signature verification enabled (via `verifyWebhookSignature`)
- ✅ Raw body parsing for Stripe webhooks
- ✅ HTTPS required in production
- ✅ Rate limiting on API endpoints

### Data Privacy

- ✅ Donor emails stored securely (for receipts only)
- ✅ Anonymous donations by default
- ✅ Opt-in public acknowledgement
- ✅ No credit card data stored (handled by Stripe)

### PCI Compliance

- ✅ Using Stripe Checkout (PCI compliant)
- ✅ No card data touches our servers
- ✅ Stripe handles all payment processing

---

## 11. Next Steps

After completing this setup:

1. ✅ Test donation flow end-to-end
2. ✅ Create frontend donation form UI
3. ✅ Build transparency dashboard
4. ✅ Implement receipt email generation
5. ✅ Add donor acknowledgement system
6. ⏳ Deploy to production

---

## Support

**Issues:** Report in GitHub Issues
**Questions:** Contact john.stroh.nz@pm.me
**Stripe Docs:** https://stripe.com/docs/api

---

**Last Updated:** 2025-10-08
**Version:** 1.0
**Status:** Ready for setup