tractatus/docs/stripe-analysis/STRIPE_ACCOUNT_SETUP_ANALYSIS_2025-10-21.md

# Stripe Account Setup Analysis & Recommendations

**Date**: 2025-10-21  
**Status**: Action Required  
**Priority**: Medium (affects production payment processing)

---

## Email Summary

Stripe has sent two emails requiring attention:

### Email 1: Setup Guide Continuation
> "Now that you've completed your business profile, you're almost ready to start accepting payments. To continue, go to your Dashboard and start the next task in your setup guide."

**Status**: ✅ Business profile complete, ⏳ Additional setup required

### Email 2: Open Case On Hold
> "We wanted to let you know that your case is on hold while we await your response to our previous note."

**Status**: ⚠️ Awaiting response (case may be time-sensitive)

---

## Current Stripe Integration Status

### Technical Implementation: ✅ COMPLETE

**Live Test Keys Configured**:
- Secret Key: `sk_test_51RX67k...` (configured)
- Publishable Key: `pk_test_51RX67k...` (configured)
- Webhook Secret: `whsec_e8195...` (configured)
- Product ID: `prod_TFusJH4Q3br8gA` (configured)
- Price IDs: 3 donation tiers ($5, $15, $50)

**Implementation Files**:
- `src/routes/koha.routes.js` - 6 endpoints (checkout, webhook, transparency, cancel, verify, statistics)
- `src/controllers/koha.controller.js` - 8,037 bytes, full checkout flow
- `src/services/koha.service.js` - 16,397 bytes, complete donation logic

**API Endpoints Live**:
- `POST /api/koha/checkout` - Create Stripe Checkout session
- `POST /api/koha/webhook` - Handle Stripe webhook events
- `GET /api/koha/transparency` - Public transparency log
- `POST /api/koha/cancel` - Cancel donation session
- `GET /api/koha/verify/:sessionId` - Verify completed donation
- `GET /api/koha/statistics` - Admin donation analytics

**Code Status**: Production-ready, test mode active

---

## Account Setup Status

### ✅ Completed
1. Business profile created
2. Test API keys generated
3. Products and prices configured
4. Webhook endpoints configured
5. Code integration complete

### ⏳ Pending (From Stripe Setup Guide)

Likely remaining steps:
1. **Tax Information** - Complete W-9 (US) or W-8BEN (international)
2. **Bank Account Verification** - Add/verify bank for payouts
3. **Identity Verification** - Upload business documentation (EIN, articles of incorporation)
4. **Compliance Review** - Complete Stripe's compliance questionnaire
5. **Business Website Review** - Provide business details, website URL, business model description
6. **Risk Assessment** - May require additional documentation based on business type

---

## Open Case Analysis

**Hypothesis**: The open case likely relates to one of:

1. **Identity/Business Verification** - Most common reason for cases
   - Requires: Government-issued ID, proof of business registration
   - Timeline: Usually 1-3 business days after submission

2. **Website/Business Model Clarification** - Second most common
   - Requires: Detailed business description, pricing transparency, refund policy
   - Timeline: Same-day to 48 hours

3. **Bank Account Issue** - Less common but possible
   - Requires: Bank account verification, micro-deposits confirmation
   - Timeline: 2-3 business days

4. **Compliance/Regulatory** - Rare but time-sensitive
   - Requires: Specific documentation based on jurisdiction
   - Timeline: Varies, can be urgent

**Risk**: Delayed response may result in:
- Account restrictions
- Payment processing delays
- Case escalation requiring more documentation

---

## Recommended Actions (Prioritized)

### Immediate (Today)

1. **Respond to Open Case**
   - Action: Reply directly to Stripe's previous email
   - Check: Search email inbox for earlier Stripe message detailing the case
   - If not found: Log into Stripe Dashboard → Support → View open cases
   - Response: Provide requested information or ask for clarification if unclear

2. **Complete Setup Guide**
   - Action: Log into Stripe Dashboard (https://dashboard.stripe.com)
   - Navigate: Look for "Setup Guide" or "Get Started" banner
   - Complete: All remaining tasks in the checklist
   - Estimated time: 15-30 minutes

### Short-Term (This Week)

3. **Verify Bank Account** (if not done)
   - Action: Add business bank account for payouts
   - Process: Stripe will send micro-deposits for verification
   - Timeline: 1-2 business days

4. **Upload Identity Documents** (if requested)
   - Action: Prepare business registration documents
   - Documents may include:
     - Articles of incorporation
     - EIN letter (IRS)
     - Business license
     - Government-issued ID of business owner

5. **Review and Update Business Details**
   - Action: Stripe Dashboard → Settings → Business Settings
   - Verify:
     - Business name: "Tractatus AI Safety Framework" or official entity name
     - Business URL: https://agenticgovernance.digital
     - Business description: AI safety framework for LLM governance
     - Support email: (from ADMIN_EMAIL: john.stroh.nz@pm.me)
     - Refund policy: (if accepting donations, state non-refundable policy)

### Production Preparation (Before Going Live)

6. **Switch to Live Keys** (after approval)
   - Current: Test mode (`sk_test_...`, `pk_test_...`)
   - Production: Live mode (`sk_live_...`, `pk_live_...`)
   - Action: Update .env file with live keys after Stripe approval

7. **Test Webhook in Production**
   - Action: Configure webhook endpoint in Stripe for production
   - URL: `https://agenticgovernance.digital/api/koha/webhook`
   - Events: `checkout.session.completed`, `payment_intent.succeeded`

8. **Monitor First Transactions**
   - Action: Closely monitor first 5-10 transactions
   - Verify: Webhook processing, database logging, email confirmations
   - Review: Stripe Dashboard analytics

---

## Email Response Draft

**Subject**: Re: Case on hold - Stripe account setup

**Body**:
```
Hello Stripe Team,

Thank you for reaching out. I apologize for the delay in responding.

I have completed my business profile as indicated in your previous email. I am ready to proceed with the remaining setup steps.

Could you please clarify what specific information or documentation you need from me to move forward? I want to ensure I provide everything necessary to resolve this case and complete my account setup.

My account details:
- Business: Tractatus AI Safety Framework
- Website: https://agenticgovernance.digital
- Use case: Processing voluntary donations (Koha) for open-source AI safety framework

I have already integrated your API (test mode) and configured webhook endpoints. I'm ready to provide any additional documentation needed for verification.

Please let me know the next steps, and I'll respond promptly.

Thank you,
[Your Name]
[Business Name]
```

---

## Technical Notes

### Current Implementation Ready For
- ✅ Test donations in test mode
- ✅ Webhook event handling
- ✅ Database logging of transactions
- ✅ Transparency page (public donation log)
- ✅ Admin analytics dashboard

### Blocked Until Stripe Approval
- ❌ Live payment processing (requires live keys)
- ❌ Real payouts to bank account (requires bank verification)
- ❌ Production webhook events (requires live mode)

### inst_009 Accuracy
**Current instruction**:
> "Email services (verification emails, donation receipts, media responses) are deferred until production requirements are finalized. Use auto-verify stubs for newsletter subscriptions and log-only for donation confirmations. Stripe payment processing is ACTIVE for Koha donations (test mode)."

**Status**: ✅ Accurate
- Stripe integration is complete and active in test mode
- Production activation blocked by Stripe account setup, not code implementation

---

## Risk Assessment

**Current Risk Level**: 🟡 MEDIUM

**If Case Remains Unresolved**:
- Timeline: 7-14 days → Account may be restricted
- Timeline: 30+ days → Test keys may be deactivated
- Impact: Cannot go live with payment processing

**If Setup Guide Not Completed**:
- Timeline: No immediate risk
- Impact: Cannot activate live mode when ready

**Recommended Timeline**: Respond to case within 24-48 hours

---

## References

- **Stripe Dashboard**: https://dashboard.stripe.com
- **Stripe API Docs**: https://stripe.com/docs
- **Koha Implementation**: `src/controllers/koha.controller.js`
- **Current Config**: `.env` (test keys)
- **inst_009**: Updated 2025-10-21 (accurate status)

---

## Next Steps Checklist

- [ ] Search email for original Stripe case message
- [ ] Log into Stripe Dashboard
- [ ] View open case details
- [ ] Respond to case with requested information
- [ ] Complete remaining setup guide tasks
- [ ] Verify bank account (if required)
- [ ] Upload identity documents (if required)
- [ ] Document Stripe approval status
- [ ] Update .env with live keys (after approval)
- [ ] Test first live transaction (after approval)

---

**Priority**: User should handle Stripe account setup personally (business decision, legal/financial documentation required). Claude Code cannot access Stripe Dashboard or respond to emails on behalf of the business.

**Status**: This document provides all necessary context for user to proceed independently.