firefrost-operations-manual/docs/tasks/paymenter-pterodactyl-integration/README.md

# 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 ($50 one-time)**
- Pterodactyl role: `subscriber_sovereign`
- 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