firefrost-operations-manual/docs/tasks/paymenter-pterodactyl-integration

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

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:

{
  "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