claude-home/productivity/n8n/workflows/QUICK-START.md

Ko-fi → Paper Dynasty Quick Start Guide

Get the Ko-fi integration running in 30 minutes.

Prerequisites Checklist

Before you start, gather these items:

• Ko-fi verification token (from Ko-fi dashboard)
• Paper Dynasty API key (production)
• Discord webhook URL for notifications
• List of Ko-fi product codes you'll sell
• Access to n8n at https://n8n.manticorum.com

Setup Steps

Step 1: Get Ko-fi Verification Token (2 minutes)

1. Login to Ko-fi: https://ko-fi.com/
2. Navigate to: Settings → API → Webhooks → Advanced (dropdown)
3. Copy the Verification Token (looks like: 8c2a3835-4544-4f27-a53a-adfd1fcc5664)
4. Save it securely - you'll add it to n8n next

Step 2: Create Discord Webhook (2 minutes)

1. Open Discord channel where you want notifications
2. Channel Settings → Integrations → Webhooks → New Webhook
3. Name it: "Ko-fi Paper Dynasty"
4. Copy webhook URL (looks like: https://discord.com/api/webhooks/...)
5. Save URL - you'll add it to n8n next

Step 3: Configure n8n Credentials (5 minutes)

Login to n8n and create three credentials:

Credential 1: Ko-fi Verification Token

1. n8n → Settings → Credentials → Add Credential
2. Search for "Generic Credential"
3. Name: Ko-fi Verification Token
4. Add field: verification_token
5. Value: [paste your Ko-fi token here]
6. Save

Credential 2: Paper Dynasty API

1. Add Credential → Search for "Header Auth"
2. Name: Paper Dynasty API
3. Header Name: Authorization
4. Value: Bearer [your-pd-api-key]
5. Save

Credential 3: Discord Webhook

1. Add Credential → Search for "Discord Webhook"
2. Name: Discord Ko-fi Notifications
3. Webhook URL: [paste Discord webhook URL]
4. Save

Step 4: Create Product Mapping (5 minutes)

1. n8n → Settings → Variables → Add Variable
2. Variable Name: KOFI_PRODUCT_MAP
3. Value: Copy and customize this JSON:

{
  "pack-standard-5": {
    "name": "5-Pack Standard",
    "pack_type_id": 1,
    "quantity": 5,
    "pack_cardset_id": null
  },
  "pack-premium-10": {
    "name": "10-Pack Premium",
    "pack_type_id": 3,
    "quantity": 10,
    "pack_cardset_id": null
  }
}

Important: Replace pack-standard-5 and pack-premium-10 with your actual Ko-fi product codes.

4. Save variable

Step 5: Import Workflow (10 minutes)

Option A: Manual Creation

Follow the detailed node-by-node instructions in kofi-paper-dynasty.md

Option B: JSON Import (if workflow JSON provided)

1. n8n → Workflows → Add Workflow → Import from File
2. Select workflow JSON file
3. Review imported nodes
4. Update credential references if needed
5. Activate workflow

Key Nodes to Verify:

• Webhook path: /kofi-paperdy (use /webhook-test/kofi-paperdy initially)
• Token validation references correct credential
• Product mapping loads from variable
• API endpoints correct (https://pd.manticorum.com/api/v2/)
• Discord notifications reference correct credential

Step 6: Test the Workflow (5 minutes)

Quick Test with cURL:

# Replace YOUR_KOFI_TOKEN_HERE with your actual token
curl -X POST 'https://n8n.manticorum.com/webhook-test/kofi-paperdy' \
  -H 'Content-Type: application/x-www-form-urlencoded' \
  --data-urlencode 'data={
    "verification_token": "YOUR_KOFI_TOKEN_HERE",
    "message_id": "quick-test-001",
    "timestamp": "2025-11-13T12:00:00Z",
    "type": "Shop Order",
    "from_name": "Test User",
    "message": "Team: SKB",
    "amount": "5.00",
    "email": "[email protected]",
    "currency": "USD",
    "kofi_transaction_id": "quick-test-001",
    "shop_items": [
      {
        "direct_link_code": "pack-standard-5",
        "variation_name": "5-Pack Standard",
        "quantity": 1
      }
    ],
    "discord_userid": null
  }'

Expected Results:

• ✅ n8n shows successful execution
• ✅ Discord notification received
• ✅ If using real API, 5 packs granted to team SKB

Step 7: Configure Ko-fi Webhook (3 minutes)

1. Ko-fi → Settings → API → Webhooks
2. Webhook URL: https://n8n.manticorum.com/webhook-test/kofi-paperdy (test first!)
3. Save
4. Click "Test Webhook" button
5. Verify n8n receives webhook and processes successfully
6. Check Discord for test notification

Step 8: Go Live (2 minutes)

Once testing is successful:

1. Update workflow webhook path:

   • n8n → Edit Workflow → Webhook node
   • Change path from webhook-test/kofi-paperdy to webhook/kofi-paperdy
   • Save and activate workflow

2. Update Ko-fi webhook URL:

   • Ko-fi → Settings → API → Webhooks
   • Change URL to: https://n8n.manticorum.com/webhook/kofi-paperdy
   • Save

3. Monitor first transactions:

   • Watch Discord channel closely
   • Review n8n execution logs
   • Verify packs granted correctly in Paper Dynasty

Done! Your Ko-fi integration is now live.

---

Post-Setup Tasks

Create Ko-fi Products

For each pack type you want to sell:

1. Ko-fi → Shop → Add Product
2. Product Name: "5-Pack Standard Bundle"
3. Price: $5.00
4. Description: "Five standard Paper Dynasty packs"
5. Advanced Settings → Product Code: pack-standard-5
   • ⚠️ This MUST match your product mapping!
6. Add product image
7. Publish product

Repeat for each pack type (premium, team choice, etc.)

Document Your Product Codes

Keep a master list of all Ko-fi product codes and their mappings:

Ko-fi Code	Pack Type	Quantity	Price	PD pack_type_id
pack-standard-5	Standard	5	$5.00	1
pack-standard-10	Standard	10	$9.00	1
pack-premium-5	Premium	5	$10.00	3
pack-premium-10	Premium	10	$18.00	3
pack-team-choice	Team Choice	1	$3.00	8

Update this when adding new products!

Set Up Monitoring

Create a monitoring checklist:

• Check Discord notifications daily
• Review n8n execution logs weekly
• Verify pack distribution accuracy weekly
• Update product mapping when adding Ko-fi products
• Test disaster recovery monthly

Backup n8n

Create weekly backup:

ssh root@10.10.0.210 "
cd /opt/n8n && \
docker compose exec -T postgres pg_dump -U n8n n8n > \
/root/n8n-backup-\$(date +%Y%m%d-%H%M%S).sql
"

# Download backup
scp root@10.10.0.210:/root/n8n-backup-*.sql ~/backups/n8n/

---

Troubleshooting

Webhook Not Receiving Data

Check:

# Test webhook endpoint
curl -I https://n8n.manticorum.com/webhook-test/kofi-paperdy

# Should return: 200 OK or 400 Bad Request (not 404)

Fix:

• Ensure workflow is Active (toggle in n8n UI)
• Verify webhook path matches Ko-fi configuration
• Check n8n logs: ssh root@10.10.0.210 "cd /opt/n8n && docker compose logs -f n8n"

Token Validation Failing

Check:

• Token in n8n credential matches Ko-fi exactly (no spaces!)
• Credential name in IF node: {{ $credentials.kofiVerificationToken.verification_token }}

Fix:

• Re-copy token from Ko-fi
• Update n8n credential
• Test again

Team Not Found

Check:

• User has discord_userid linked in Paper Dynasty
• OR user included team abbrev in message (e.g., "Team: SKB")
• Team abbreviation exists in PD database

Fix:

• Manual review Discord notification will be sent
• Admin grants packs manually using transaction ID

Packs Not Granted

Check:

• n8n execution log shows 200 OK from PD API
• Product code exists in KOFI_PRODUCT_MAP variable
• pack_type_id is valid

Verify in Paper Dynasty:

from api_client import PaperDynastyAPI
api = PaperDynastyAPI(environment='prod')
api.list_packs(team_id=69, opened=False, limit=20)

---

Next Steps

Now that your integration is running:

1. Read full documentation: kofi-paper-dynasty.md
2. Review test scenarios: kofi-testing-guide.md
3. Customize product mapping: Add more pack types
4. Set up monitoring alerts: Create health check workflow
5. Document your process: Add notes for future reference

---

Support Resources

Documentation:

• Full Setup: kofi-paper-dynasty.md
• Testing Guide: kofi-testing-guide.md
• Product Mapping: kofi-product-mapping-template.json
• n8n Context: /productivity/n8n/CONTEXT.md

External Resources:

• Ko-fi Webhook Docs: https://help.ko-fi.com/hc/en-us/articles/360004162298
• n8n Documentation: https://docs.n8n.io/
• Paper Dynasty API: See /home/cal/.claude/skills/paper-dynasty/SKILL.md

Need Help?

• Review n8n execution logs for detailed error messages
• Check Discord notifications for manual review requests
• Test with cURL to isolate issues
• Consult troubleshooting guide in main documentation

---

Change Log

2025-11-13 - Initial Version

• Created quick start guide
• Defined 30-minute setup process
• Added troubleshooting quick reference
• Included post-setup tasks and monitoring