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:

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:

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:

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:

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

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:

# 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

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:

{
  "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:

# 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

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:

# 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