diff --git a/docs/core/tasks.md b/docs/core/tasks.md index 295ba0c..3ac7af9 100644 --- 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. + +--- + diff --git a/docs/tasks/paymenter-pterodactyl-integration/README.md b/docs/tasks/paymenter-pterodactyl-integration/README.md new file mode 100644 index 0000000..214d7e6 --- /dev/null +++ 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