tractatus/docs/KOHA_STRIPE_SETUP.md

Koha Donation System - Stripe Setup Guide

Project: Tractatus Framework Feature: Phase 3 - Koha (Donation) System Date: 2025-10-18 (Updated with automated scripts) Status: ✅ Test Mode Active | Production Ready

---

Overview

The Koha donation system uses the existing Stripe account from passport-consolidated to process donations in multiple currencies. This document guides you through setting up the required Stripe products and webhooks.

Account: Same Stripe test account as passport-consolidated Currencies: 10 supported (NZD base + USD, EUR, GBP, AUD, CAD, JPY, CHF, SGD, HKD) Payment Types: Recurring monthly subscriptions + one-time donations Multi-Currency: Uses Stripe's currency_options feature for automatic conversion

---

Quick Start (Automated Setup)

✨ NEW: Automated setup scripts available!

Option A: Fully Automated Setup (Recommended)

# Step 1: Verify Stripe API connection
node scripts/test-stripe-connection.js

# Step 2: Create products and prices automatically
node scripts/setup-stripe-products.js

# Step 3: Server will restart automatically - prices now configured!

# Step 4: Test the complete integration
node scripts/test-stripe-integration.js

# Step 5: Set up webhooks for local testing (requires Stripe CLI)
./scripts/stripe-webhook-setup.sh

That's it! All products, prices, and configuration are set up automatically.

What the Scripts Do

1. test-stripe-connection.js - Verifies test API keys work and shows existing products/prices
2. setup-stripe-products.js - Creates the Tractatus product and 3 monthly price tiers with multi-currency support
3. test-stripe-integration.js - Tests checkout session creation for both monthly and one-time donations
4. stripe-webhook-setup.sh - Guides you through Stripe CLI installation and webhook setup

Option B: Manual Setup

Continue to Section 1 below for step-by-step manual instructions.

---

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.

---

2.5 Multi-Currency Setup with currency_options

IMPORTANT: To support multiple currencies with a single price ID, configure currency_options for each monthly tier price.

Method 1: Stripe Dashboard (Recommended)

1. Go to your product → Select a price (e.g., $5 NZD/month)
2. Click Add currency in the pricing section
3. Add each supported currency with converted amounts:

Base (NZD)	USD	EUR	GBP	AUD	CAD	JPY	CHF	SGD	HKD
$5.00	$3.00	€2.75	£2.35	$4.65	$4.10	¥470	2.65	$4.05	$23.40
$15.00	$9.00	€8.25	£7.05	$13.95	$12.30	¥1410	7.95	$12.15	$70.20
$50.00	$30.00	€27.50	£23.50	$46.50	$41.00	¥4700	26.50	$40.50	$234.00

4. Repeat for all three monthly tier prices

Method 2: Stripe API

Update existing prices via Stripe API:

stripe prices update price_YOUR_5_NZD_PRICE_ID \
  --currency-options[usd][unit_amount]=300 \
  --currency-options[eur][unit_amount]=275 \
  --currency-options[gbp][unit_amount]=235 \
  --currency-options[aud][unit_amount]=465 \
  --currency-options[cad][unit_amount]=410 \
  --currency-options[jpy][unit_amount]=470 \
  --currency-options[chf][unit_amount]=265 \
  --currency-options[sgd][unit_amount]=405 \
  --currency-options[hkd][unit_amount]=2340

Repeat for $15 and $50 tier prices with their corresponding amounts.

Exchange Rate Calculation

Our base currency is NZD. Exchange rates (as of 2025-10-08):

1 NZD = 0.60 USD = 0.55 EUR = 0.47 GBP = 0.93 AUD = 0.82 CAD
      = 94.0 JPY = 0.53 CHF = 0.81 SGD = 4.68 HKD

Note: Rates are configurable in src/config/currencies.config.js. Update periodically or integrate live exchange rate API.

One-Time Donations (Dynamic Currency)

For one-time donations, the code dynamically creates Stripe checkout sessions with the selected currency:

sessionParams.line_items = [{
  price_data: {
    currency: currentCurrency.toLowerCase(), // e.g., 'usd', 'eur'
    unit_amount: amount // Amount in cents/smallest currency unit
  }
}];

No additional configuration needed - Stripe handles any supported currency.

---

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 or Stripe CLI)
STRIPE_KOHA_WEBHOOK_SECRET=whsec_...

# Product ID (created by setup-stripe-products.js)
STRIPE_KOHA_PRODUCT_ID=prod_TFusJH4Q3br8gA

# Price IDs (created by setup-stripe-products.js)
STRIPE_KOHA_5_PRICE_ID=price_1SJP2fGhfAwOYBrf9yrf0q8C
STRIPE_KOHA_15_PRICE_ID=price_1SJP2fGhfAwOYBrfNc6Nfjyj
STRIPE_KOHA_50_PRICE_ID=price_1SJP2fGhfAwOYBrf0A62TOpf

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

✅ Current Status (2025-10-18):

• Product and prices are already created in test mode
• .env file is configured with actual IDs
• Server integration tested and working
• Ready for frontend testing with test cards

---

7. Testing the Integration

Test API Endpoint

Test 1: Monthly donation in NZD

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

Test 2: One-time donation in USD

curl -X POST http://localhost:9000/api/koha/checkout \
  -H "Content-Type: application/json" \
  -d '{
    "amount": 2500,
    "currency": "USD",
    "frequency": "one_time",
    "tier": "custom",
    "donor": {
      "name": "US Donor",
      "email": "us@example.com"
    },
    "public_acknowledgement": true,
    "public_name": "Anonymous US Supporter"
  }'

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 USD $9.00 (NZD $15.00)
[KOHA] Checkout session created: cs_test_...
[KOHA] Processing webhook event: checkout.session.completed
[KOHA] Checkout completed: monthly donation, tier: 15, currency: USD
[KOHA] Donation recorded: USD $9.00 (NZD $15.00)
[KOHA] Recurring donation recorded: EUR $8.25 (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. Current Status & Next Steps

✅ Completed (2025-10-18)

1. ✅ Stripe test account configured with existing credentials
2. ✅ Product "Tractatus Framework Support" created (prod_TFusJH4Q3br8gA)
3. ✅ Three monthly price tiers created with multi-currency support
4. ✅ .env file configured with actual product and price IDs
5. ✅ Backend API endpoints implemented and tested
6. ✅ Frontend donation form UI complete with i18n support
7. ✅ Checkout session creation tested for monthly and one-time donations
8. ✅ Automated setup scripts created for easy deployment

⏳ Pending

1. ⏳ Install Stripe CLI for local webhook testing
2. ⏳ Configure webhook endpoint and get signing secret
3. ⏳ Test complete payment flow with test cards in browser
4. ⏳ Build transparency dashboard data visualization
5. ⏳ Implement receipt email generation (Koha service has placeholder)
6. ⏳ Switch to production Stripe keys and test with real card
7. ⏳ Deploy to production server

🎯 Ready to Test

You can now test the donation system locally:

1. Visit http://localhost:9000/koha.html
2. Select a donation tier or enter custom amount
3. Fill in donor information
4. Use test card: 4242 4242 4242 4242
5. Complete checkout flow
6. Verify success page shows

---

Support

Issues: Report in GitHub Issues at https://github.com/yourusername/tractatus Questions: Contact john.stroh.nz@pm.me Stripe Docs: https://stripe.com/docs/api Test Cards: https://stripe.com/docs/testing

---

Last Updated: 2025-10-18 Version: 2.0 (Automated Setup) Status: ✅ Test Mode Active | Ready for Webhook Setup