feat: add Task #83 - Paymenter → Pterodactyl Auto-Provisioning Integration (CRITICAL)

🚨 BLOCKS SOFT LAUNCH - Must complete before accepting first subscriber Created comprehensive task documentation for automating subscriber provisioning between Paymenter billing and Pterodactyl Panel. Problem: - Currently every new subscriber requires manual Pterodactyl account creation - Tier changes require manual permission updates - Cancellations require manual cleanup - Does NOT scale beyond 5-10 subscribers Solution: Automated webhook bridge: Paymenter → Integration → Pterodactyl API Customer subscribes → server access granted in 30 seconds (zero touch) Task includes: - 4 integration options to investigate (native extensions vs custom) - Pterodactyl API setup guide with required permissions - 10-tier subscription mapping (Awakened → Founder) - Webhook configuration and security - Full lifecycle testing requirements (create/upgrade/cancel) - Success criteria checklist (4 phases) - Error handling and logging requirements - Manual override procedure for edge cases Research priority: 1. Check Paymenter docs for native Pterodactyl integration 2. Check Blueprint marketplace for Paymenter module 3. Fall back to n8n workflow if no native option 4. Last resort: custom webhook script Time estimate: 4-6 hours Priority: CRITICAL (Tier 0 - blocks soft launch) Status: 🔴 BLOCKING SOFT LAUNCH Related: - Task #2 (LuckPerms Discord sync - depends on this) - Blocks acceptance of real subscribers Documentation: docs/tasks/paymenter-pterodactyl-integration/README.md Added to docs/core/tasks.md as Task #83 Created by: The Verifier (Chronicler #41) Session: March 26, 2026, 2:20 AM CST
2026-03-26 07:03:11 +00:00
parent 252b2c5c64
commit ee7fbabf7e
2 changed files with 413 additions and 0 deletions
--- a/docs/core/tasks.md
+++ b/docs/core/tasks.md
@@ -2483,3 +2483,43 @@ Plane v2.4.2 was deployed with 5 projects, member invites, and Fire/Frost labels

 ---

+### 83. Paymenter → Pterodactyl Auto-Provisioning Integration
+**Time:** 4-6 hours  
+**Status:** 🔴 BLOCKING SOFT LAUNCH  
+**Priority:** Tier 0 — CRITICAL (Must complete before first subscriber)  
+**Documentation:** `docs/tasks/paymenter-pterodactyl-integration/`
+
+Integrate Paymenter billing system with Pterodactyl Panel to automatically provision server access when customers subscribe. Without this, every subscriber requires manual account creation, tier changes, and cancellations — not sustainable beyond 5-10 subscribers.
+
+**Key Deliverables:**
+- Research integration method (Paymenter extension, Blueprint module, or custom bridge)
+- Configure Pterodactyl API access with appropriate permissions
+- Set up Paymenter webhooks for subscription lifecycle events
+- Map 10 subscription tiers to Pterodactyl user roles
+- Test full subscription lifecycle (create → upgrade → cancel)
+- Implement error handling and logging
+- Document manual override procedure for edge cases
+
+**Dependencies:**
+- Stripe integration (already working ✅)
+- Subscription tiers created in Paymenter (already complete ✅)
+- Pterodactyl Panel operational (already working ✅)
+
+**Integration Flow:**
+```
+Customer subscribes via Paymenter → Stripe webhook fires → 
+Paymenter processes → Webhook to integration bridge → 
+Pterodactyl API creates user → Customer receives access (30 seconds)
+```
+
+**Options to investigate:**
+1. Native Paymenter Pterodactyl extension (check docs)
+2. Blueprint marketplace Paymenter module
+3. Custom n8n workflow (already have n8n on TX1)
+4. Direct webhook script
+
+**Context:**
+Currently Paymenter and Pterodactyl work independently. Subscribers pay via Paymenter, but server access must be granted manually in Pterodactyl. This blocks soft launch as it won't scale. Integration enables zero-touch subscriber onboarding.
+
+---
+
--- a/docs/tasks/paymenter-pterodactyl-integration/README.md
+++ b/docs/tasks/paymenter-pterodactyl-integration/README.md
@@ -0,0 +1,373 @@
+# Task #83: Paymenter → Pterodactyl Auto-Provisioning Integration
+
+**Created:** March 26, 2026  
+**Status:** 🔴 BLOCKING SOFT LAUNCH  
+**Priority:** CRITICAL - Must complete before accepting first subscriber  
+**Time Estimate:** 4-6 hours  
+**Assigned To:** Next Chronicler + Michael
+
+---
+
+## 🚨 WHY THIS IS CRITICAL
+
+**Without this integration:**
+- ❌ Every new subscriber requires manual Pterodactyl account creation
+- ❌ Every payment failure requires manual suspension
+- ❌ Every tier change requires manual permission updates
+- ❌ Every cancellation requires manual cleanup
+- ❌ **This does not scale beyond 5-10 subscribers**
+
+**With this integration:**
+- ✅ Subscriber pays → server access granted automatically (30 seconds)
+- ✅ Payment fails → server suspended after grace period (automated)
+- ✅ Subscriber upgrades tier → permissions updated (instant)
+- ✅ Subscriber cancels → access removed cleanly (automated)
+- ✅ **Scales to hundreds of subscribers with zero manual work**
+
+---
+
+## 📊 CURRENT STATE vs DESIRED STATE
+
+### Current State (NOT SUSTAINABLE)
+```
+Customer subscribes via Paymenter
+        ↓
+Michael gets email notification
+        ↓
+Michael manually logs into Pterodactyl Panel
+        ↓
+Michael manually creates user account
+        ↓
+Michael manually assigns permissions
+        ↓
+Michael manually emails customer credentials
+        ↓
+(Repeat for every subscriber, every tier change, every cancellation)
+```
+
+### Desired State (REQUIRED FOR LAUNCH)
+```
+Customer subscribes via Paymenter (Stripe payment)
+        ↓
+Stripe webhook → Paymenter
+        ↓
+Paymenter webhook → Integration Bridge
+        ↓
+Pterodactyl API: Create/update user automatically
+        ↓
+Email sent to customer automatically (Pterodactyl)
+        ↓
+Customer has access in 30 seconds
+        ↓
+(Zero manual intervention)
+```
+
+---
+
+## 🔧 INTEGRATION ARCHITECTURE
+
+### Components Required
+
+**1. Paymenter Side:**
+- Stripe webhooks (already configured ✅)
+- Paymenter product configuration (10 tiers created ✅)
+- Webhook URL endpoint (needs configuration ❌)
+
+**2. Bridge/Middleware:**
+- **Option A:** Paymenter extension (if available)
+- **Option B:** Custom webhook receiver + API bridge
+- **Option C:** n8n workflow (already have n8n on TX1)
+- **Option D:** Pterodactyl Paymenter module (check Blueprint marketplace)
+
+**3. Pterodactyl Side:**
+- API access enabled
+- API key created
+- User role templates defined
+- Server group permissions configured
+
+---
+
+## 📋 IMPLEMENTATION OPTIONS
+
+### Option A: Paymenter Pterodactyl Extension (RECOMMENDED IF EXISTS)
+
+**Check if Paymenter has native Pterodactyl integration:**
+- Paymenter docs: https://paymenter.org/docs/
+- Extensions marketplace
+- GitHub: paymenter/paymenter
+
+**Pros:**
+- ✅ Native integration (officially supported)
+- ✅ Likely handles edge cases
+- ✅ Maintained by Paymenter team
+
+**Cons:**
+- ❓ May not exist yet (Paymenter is newer)
+- ❓ May not support all tier features
+
+---
+
+### Option B: Pterodactyl Blueprint Extension
+
+**Check Blueprint marketplace for Paymenter integration:**
+- Pterodactyl Panel → Extensions (Blueprint installed ✅)
+- Search for "Paymenter", "billing", "provisioning"
+
+**Pros:**
+- ✅ Installed via Blueprint (easy)
+- ✅ Lives in Pterodactyl (central management)
+
+**Cons:**
+- ❓ May not exist
+- ❓ Quality varies
+
+---
+
+### Option C: Custom n8n Workflow
+
+**Build webhook bridge using existing n8n instance:**
+- n8n already deployed on TX1 ✅
+- Paymenter webhook → n8n → Pterodactyl API
+
+**Pros:**
+- ✅ Full control over logic
+- ✅ Already have n8n infrastructure
+- ✅ Can handle complex tier mapping
+
+**Cons:**
+- ❌ Requires custom workflow development
+- ❌ Must maintain ourselves
+- ❌ More moving parts
+
+---
+
+### Option D: Direct Webhook Script
+
+**Simple PHP/Python script on Billing VPS:**
+- Receives Paymenter webhooks
+- Calls Pterodactyl API directly
+
+**Pros:**
+- ✅ Simplest architecture
+- ✅ Minimal dependencies
+
+**Cons:**
+- ❌ Must write from scratch
+- ❌ Harder to debug
+- ❌ Security concerns (webhook validation)
+
+---
+
+## 🎯 RECOMMENDED APPROACH
+
+**Priority order to investigate:**
+
+1. **Check Paymenter documentation** for native Pterodactyl integration
+2. **Check Blueprint marketplace** for Paymenter extension
+3. **Fall back to n8n workflow** if no native option exists
+
+---
+
+## 📝 PREREQUISITE INFORMATION NEEDED
+
+### Paymenter Configuration
+- ✅ Base URL: https://billing.firefrostgaming.com
+- ✅ Admin access: Available
+- ❓ Webhook secret key: (generate if needed)
+- ❓ Webhook URL format: (depends on integration method)
+
+### Pterodactyl Configuration
+- ✅ Panel URL: https://panel.firefrostgaming.com (Panel VPS 45.94.168.138)
+- ❓ API key: (needs creation)
+- ❓ API permissions: (needs definition)
+- ❓ User role templates: (needs creation)
+
+### Subscription Tier Mapping
+
+**Tier 1: The Awakened ($1 one-time)**
+- Pterodactyl role: `subscriber_awakened`
+- Server access: All public Frost Path servers
+- Permissions: Basic (view, connect)
+
+**Tier 2: Fire Elemental / Frost Elemental ($5/mo)**
+- Pterodactyl role: `subscriber_elemental`
+- Server access: All Frost Path servers
+- Permissions: Basic + home teleport
+
+**Tier 3: Fire Knight / Frost Knight ($10/mo)**
+- Pterodactyl role: `subscriber_knight`
+- Server access: All Frost Path servers
+- Permissions: Elemental + extra homes
+
+**Tier 4: Fire Master / Frost Master ($15/mo)**
+- Pterodactyl role: `subscriber_master`
+- Server access: All Frost Path + priority slots
+- Permissions: Knight + creative plot access
+
+**Tier 5: Fire Legend / Frost Legend ($20/mo)**
+- Pterodactyl role: `subscriber_legend`
+- Server access: All servers + beta access
+- Permissions: Master + special perks
+
+**Tier 6: Sovereign (Founder) ($50 one-time)**
+- Pterodactyl role: `subscriber_founder`
+- Server access: ALL servers including future ones
+- Permissions: Everything non-staff
+
+---
+
+## 🔑 PTERODACTYL API SETUP
+
+### Step 1: Create API Key
+
+**On Panel VPS (45.94.168.138):**
+1. SSH to Panel VPS
+2. Login to Pterodactyl admin panel
+3. Account → API Credentials
+4. Create new Application API Key
+5. Name: "Paymenter Auto-Provisioning"
+6. Permissions needed:
+   - `user.read` - Read user data
+   - `user.create` - Create new users
+   - `user.update` - Update user permissions
+   - `user.delete` - Remove users (on cancellation)
+7. Copy API key to Vaultwarden
+
+### Step 2: Test API Access
+
+```bash
+curl -H "Authorization: Bearer YOUR_API_KEY" \
+  -H "Content-Type: application/json" \
+  https://panel.firefrostgaming.com/api/application/users
+```
+
+Should return list of users.
+
+---
+
+## 🔗 WEBHOOK CONFIGURATION
+
+### Paymenter Webhooks
+
+**Paymenter should send webhooks for:**
+- `subscription.created` - New subscriber
+- `subscription.updated` - Tier change
+- `subscription.cancelled` - Cancellation
+- `payment.failed` - Failed payment (trigger grace period)
+- `payment.succeeded` - Successful payment (restore access)
+
+**Webhook payload example:**
+```json
+{
+  "event": "subscription.created",
+  "subscription_id": "12345",
+  "customer_email": "user@example.com",
+  "product_id": "fire-elemental",
+  "tier": "elemental",
+  "status": "active"
+}
+```
+
+### Webhook Security
+
+**Validate webhooks with:**
+- Webhook signature verification
+- IP whitelist (Billing VPS only)
+- HTTPS only
+- Secret key validation
+
+---
+
+## ✅ SUCCESS CRITERIA
+
+### Phase 1: Basic Provisioning
+- [ ] Paymenter → Pterodactyl integration method chosen
+- [ ] Pterodactyl API key created and tested
+- [ ] Test user created via API successfully
+- [ ] Test user can login to Pterodactyl Panel
+
+### Phase 2: Webhook Automation
+- [ ] Webhook endpoint configured and receiving events
+- [ ] New subscription creates Pterodactyl user automatically
+- [ ] Email sent to customer with login details
+- [ ] Customer can access servers within 60 seconds of payment
+
+### Phase 3: Full Lifecycle
+- [ ] Tier upgrades update permissions automatically
+- [ ] Payment failures trigger grace period (7 days)
+- [ ] Suspension after grace period works
+- [ ] Cancellations remove access cleanly
+- [ ] Reactivation restores access
+
+### Phase 4: Production Ready
+- [ ] Tested with 5+ dummy subscriptions (full lifecycle)
+- [ ] Error handling works (failed API calls, network issues)
+- [ ] Logging configured (can debug issues)
+- [ ] Rollback plan documented
+- [ ] Manual override procedure documented (for edge cases)
+
+---
+
+## 🚨 BEFORE SOFT LAUNCH
+
+**This integration MUST be:**
+- ✅ Fully tested end-to-end
+- ✅ Handling all subscription lifecycle events
+- ✅ Logging errors for debugging
+- ✅ Backed by manual override procedure
+
+**DO NOT accept real subscribers until this works.**
+
+Manual provisioning for 1-2 test subscribers is fine.  
+Manual provisioning for 10+ subscribers is not sustainable.
+
+---
+
+## 📚 RESOURCES
+
+**Paymenter Documentation:**
+- https://paymenter.org/docs/
+- https://github.com/paymenter/paymenter
+
+**Pterodactyl API Documentation:**
+- https://dashflo.net/docs/api/pterodactyl/v1/
+- Panel → Account → API (in-panel docs)
+
+**Similar Integrations:**
+- WHMCS → Pterodactyl modules (for reference)
+- Blesta → Pterodactyl modules (for reference)
+
+---
+
+## 🔄 RELATED TASKS
+
+**Depends on:**
+- None (all prerequisites complete)
+
+**Blocks:**
+- Soft launch acceptance of real subscribers
+- Task #2 (LuckPerms deployment - Phase 3 Discord sync)
+
+**Related:**
+- Task #33 (Paymenter Citadel theme - cosmetic only)
+- Task #71 (Paymenter tier preview tool - planning only)
+
+---
+
+## 📝 NEXT STEPS
+
+1. **Research integration options** (Paymenter docs, Blueprint marketplace)
+2. **Choose integration method** (native extension vs custom bridge)
+3. **Create Pterodactyl API key** with correct permissions
+4. **Configure webhook endpoint** (depends on chosen method)
+5. **Test with dummy subscription** (create → access → cancel)
+6. **Document deployment** in this task directory
+7. **Deploy to production** after successful testing
+8. **Monitor first 10 real subscriptions** manually
+
+---
+
+**Standard:** This task follows FFG-STD-002 (Task Documentation Standard)
+
+**Created by:** The Verifier (Chronicler #41)  
+**Date:** March 26, 2026, 2:15 AM CST