title: Server Setup Guide description: Complete guide for Discord server owners to set up the bot and start selling paid roles

Server Setup Guide - For Discord Server Owners

Welcome! This guide will walk you through setting up the bot in your Discord server to sell paid roles and subscriptions.

Table of Contents

  1. Quick Start
  2. Features
  3. Step-by-Step Setup
  4. Creating Your First Role Package
  5. Testing Payments
  6. Payment Log Notifications
  7. Managing Role Packages
  8. Troubleshooting
  9. Command Reference
  10. Best Practices

Quick Start

Minimum setup to get started:

  1. ✅ Invite the bot to your server (with proper permissions)
  2. ✅ Run /server_config to configure your server
  3. ✅ Run /register_stripe to connect Stripe payments
  4. ✅ Run /create_sub to create a role package
  5. ✅ Run /push_sub_to to publish it to a channel

That's it! Users can now purchase roles in your server.

Features

💰
Paid Roles
Create and sell one-time role purchases. Users pay once and keep the role forever. Perfect for premium access, VIP status, or special perks.
🔄
Subscriptions
Set up recurring subscriptions with weekly, monthly, or yearly billing cycles. Automatically manage role assignments based on payment status.
🔐
Secure Payments
Full Stripe integration with webhook verification. All API keys and secrets are securely encrypted and stored safely in the database.
📊
Real-Time Payment Logs
Get instant notifications in your Discord channel when payments are created. Watch status updates in real-time as payments progress from session created to successful completion.
🛡️
Security
Your API keys are securely encrypted and stored safely. Rate limiting prevents spam and abuse. Supports both standard and restricted Stripe keys.
📈
Automated Verification
Automatic payment verification and role assignment. Runs every 60 seconds to ensure users get their roles promptly after payment.
🌐
Webhook Server
Built-in FastAPI server for receiving payment webhooks. Handles Stripe events seamlessly for instant role delivery.
🔒
Encrypted Secrets
All Stripe API keys (sk_live, sk_test, rk_live, rk_test) and webhook secrets are securely encrypted before being stored in the database.

Step-by-Step Setup

Step 1: Invite the Bot to Your Server

Required Permissions:

The bot needs these permissions to work properly: - ✅ Manage Roles - So it can assign/remove roles after payment - ✅ Send Messages - To post your role offers in channels - ✅ Embed Links - To create those nice-looking purchase embeds - ✅ Read Message History - To read slash commands - ✅ Use External Emojis - Makes everything look better!

How to Invite:

  1. Get the bot invite link from the bot owner
  2. Super important: Make sure the bot's role is above any roles you want to sell in your server's role hierarchy
  3. The bot can only manage roles that are below its own role in the list

⚠️ Important: The bot's role must be higher in the hierarchy than any role it will assign! If the bot's role is below the role you want to sell, it won't be able to give it to users. Just drag the bot's role higher in Server Settings → Roles.

Step 2: Configure Your Server

Run the /server_config command to set up your server settings.

What you'll configure:

Example:

/server_config

Then use the dropdown menus to select your log channel and creator role.

Why the Log Channel is Awesome:

When someone clicks "Purchase Role", you'll immediately see a notification in your log channel. As the payment progresses, it updates automatically:

The notifications also show timelines, so you can see exactly when each step happened. Plus, if a payment doesn't complete within 5 minutes, the notification automatically gets deleted to keep your channel clean.

Pro Tip: Set this up early so you can monitor all your payments in one place!

Step 3: Connect Stripe (Payment Processing)

To accept payments, you'll need to connect your Stripe account. Don't worry - it's free to set up and you only pay fees when you get paid!

3a. Create a Stripe Account

  1. Go to https://stripe.com and sign up
  2. Complete account verification (required for live payments)
  3. Start with Test Mode to test without real charges

3b. Get Your Stripe API Key

Stripe offers two types of API keys: Secret Keys and Restricted Keys. Both are supported and stored securely encrypted in the database.

Secret Keys (Full Access)

Test Mode: 1. Go to https://dashboard.stripe.com/apikeys 2. Make sure you're in Test Mode (toggle in top right) 3. Click "Reveal test key" next to "Secret key" 4. Copy the key (starts with sk_test_...)

Live Mode (Production): - Switch to Live Mode in Stripe Dashboard - Get your live API key (starts with sk_live_...) - ⚠️ Only use live keys when you're ready for real payments!

Restricted keys are safer because they only have the permissions your bot actually needs. It's like giving someone a key that only opens the doors they need - much safer!

To create a Restricted Key:

  1. Go to https://dashboard.stripe.com/apikeys
  2. Click "Create restricted key" (or "Restricted keys" tab)
  3. Select the permissions your bot needs:
  4. ✅ Read checkout sessions
  5. ✅ Write checkout sessions
  6. ✅ Read balance (or Read all balance data)
  7. ✅ Read payment intents
  8. ✅ Write payment intents (if needed)
  9. Click "Create key"
  10. Copy the key (starts with rk_test_... for test mode or rk_live_... for live mode)

Test Mode Restricted Key: rk_test_...
Live Mode Restricted Key: rk_live_...

Key Types Comparison
Key Type Prefix Access Level Security Use Case
Secret Key (Test) sk_test_ Full access to test account Standard Development & testing
Secret Key (Live) sk_live_ Full access to live account Standard Production (not recommended)
Restricted Key (Test) rk_test_ Limited permissions (test) Higher Recommended for testing
Restricted Key (Live) rk_live_ Limited permissions (live) Highest Recommended for production

Why Use Restricted Keys?

Important Notes: - All API keys (both sk_ and rk_ types) are securely encrypted before being stored in the database - Your keys are encrypted separately for each server for extra security - Never share your API keys publicly or commit them to version control - You can use either secret keys or restricted keys - the bot supports both

3c. Set Up Webhooks (Required for Automatic Role Assignment)

Webhooks are how Stripe tells your bot "hey, this payment completed!" so it can automatically assign roles. Without this, the bot wouldn't know when to give roles.

  1. Go to https://dashboard.stripe.com/webhooks
  2. Click "Add endpoint"
  3. Endpoint URL: Ask the bot owner for the webhook URL (usually https://yourdomain.com/webhooks/stripe)
  4. Description: "Discord Bot Payment Webhooks"
  5. Events to send: Select these events:
  6. ✅ checkout.session.completed
  7. ✅ payment_intent.succeeded
  8. ✅ charge.succeeded
  9. ✅ invoice.payment_succeeded
  10. ✅ charge.refunded
  11. ✅ payment_intent.payment_failed
  12. ✅ customer.subscription.deleted
  13. ✅ customer.subscription.updated
  14. Click "Add endpoint"
  15. Click "Reveal" under "Signing secret"
  16. Copy the webhook secret (starts with whsec_...)

3d. Register Stripe in Discord

Run the /register_stripe command:

Using a Secret Key:

/register_stripe api_key:sk_test_... webhook_secret:whsec_...

Using a Restricted Key (Recommended):

/register_stripe api_key:rk_test_... webhook_secret:whsec_...

What this does: - Encrypts and securely stores your Stripe API key (supports sk_live_, sk_test_, rk_live_, and rk_test_ keys) - Your keys are securely encrypted before storage in the database - Each server's keys are encrypted separately for additional security - Configures webhooks for automatic payment processing - Enables the bot to create checkout sessions and verify payments

Security Features: - 🔐 All API keys are encrypted at rest in the database - 🔑 Each server has its own separate encryption for extra protection - 🛡️ Uses industry-standard encryption methods - 🔒 Webhook secrets are also encrypted before storage

Check Status:

Run /stripe_api_status to verify your Stripe connection is working.

Creating Your First Role Package

Ready to create your first paid role? Let's do it step by step!

Step 1: Create the Role Package

Run /create_sub and an interactive form will pop up. Super easy!

What you'll need to fill in:

  1. Package Type:
  2. One-time purchase (user pays once, keeps role forever)

  3. Subscription (weekly, monthly, or yearly recurring payment)

  4. Basic Info:

  5. Title (like "Premium Member" or "VIP Access")
  6. Description (what users get - be clear and exciting!)

  7. Benefits (bullet points of perks they'll receive)

  8. Role Selection:

  9. Choose which Discord role(s) to assign

  10. Users get these roles after payment completes

  11. Pricing:

  12. Currency (USD, EUR, INR, etc.)
  13. Price amount

  14. For subscriptions: billing period (weekly/monthly/yearly)

  15. Button Text:

  16. What the purchase button says (like "Buy Now", "Subscribe", "Get Premium")

Here's how it works:

You: /create_sub
Bot: [Interactive form appears with dropdowns and text fields]
You: Fill in title, description, select role, set price
Bot: ✅ Role package created! Use /push_sub_to to publish it.

That's it! Your package is created and ready to publish.

Step 2: Publish the Role Package

Now let's get it in front of your community!

Run /push_sub_to to publish your package to a channel:

  1. Select the role package you just created
  2. Choose the channel where you want to post it
  3. The bot creates a beautiful embed with a purchase button

What users will see: - Nice-looking embed with all your package details - Purchase button that opens Stripe checkout - Clear pricing and benefits listed

Users can purchase two ways: - Clicking the button on the published embed - Running /purchase_role and selecting the package

Testing Payments

The easiest way to test is using the built-in test command:

Run /test_payment_flow - This automatically: - Creates a test role for you - Creates a test package ready to go - Sets everything up so you can test right away

Then follow these steps:

  1. Run /push_sub_to and select "Test Package"
  2. Click the purchase button
  3. Use Stripe test card: 4242 4242 4242 4242
  4. Any future expiry date (like 12/25)
  5. Any 3-digit CVC (like 123)
  6. Any ZIP code
  7. Complete the checkout
  8. Wait 30-60 seconds for webhook processing
  9. Check if the role was assigned!

Pro Tip: Watch your log channel (if you set one up) to see the payment notification update in real-time!

Manual Testing

If you want to test with your own setup instead:

Step 1: Create a test role - Go to Server Settings → Roles → Create Role - Name it "Test Premium" or something similar - Make sure bot's role is above it in the hierarchy

Step 2: Create a test package - Run /create_sub - Select your test role - Set price to $1.00 (or the minimum allowed) - Use your test Stripe API key (sk_test_... or rk_test_...)

Step 3: Publish and test - Run /push_sub_to and select your test package - Click the purchase button - Use test card: 4242 4242 4242 4242 - Verify the role gets assigned

Debugging Failed Payments

If a role wasn't assigned after payment:

  1. Check your log channel first:
  2. Look for the payment notification in your log channel
  3. See what status it shows (failed, in progress, etc.)

  4. Check if there are any error messages shown

  5. Run /debug_purchase:

  6. Shows purchase status
  7. Identifies what went wrong

  8. Provides fix buttons if possible

  9. Check common issues:

  10. Bot's role is below the role being assigned
  11. Bot missing "Manage Roles" permission
  12. Webhook not configured correctly
  13. Payment still processing (wait 60 seconds)

Payment Log Notifications

What Are Payment Logs?

Once you set up your log channel (in Step 2), you'll get real-time notifications every time someone tries to purchase a role in your server. It's like having a dashboard that shows you everything happening with payments!

How It Works

When someone clicks "Purchase Role", here's what you'll see:

🔵 Payment Session Created - This shows up immediately when someone clicks the purchase button - You'll see who's trying to buy, what package they want, and the price - Includes a purchase ID you can use for debugging if needed

⏳ Payment In Progress - The notification automatically updates when Stripe confirms the payment - You'll see the exact time when payment was confirmed

✅ Payment Successful - Final update shows roles were assigned successfully - You'll see which roles were given and when - Includes a complete timeline of the payment process

❌ Payment Failed - If something goes wrong, you'll see the error details - Shows what failed (role assignment, permissions, etc.) - Helps you quickly identify and fix issues

⌛ Payment Timed Out - If someone doesn't complete payment within 5 minutes, the notification gets deleted automatically - This keeps your log channel clean and focused on active payments - The purchase record is marked as "timeout" in the system

Timeline Tracking

Each notification shows a timeline of events:

All timestamps use Discord's relative time format (like "2 minutes ago"), so you can quickly see how fresh the information is.

Automatic Cleanup

The bot automatically cleans up timed-out payments after 5 minutes. This means:

Pro Tips

Managing Role Packages

Once you've created some packages, you'll want to manage them. Here's how!

View All Packages

Run /manage_subs to see everything you've created: - Lists all your role packages - Shows package details at a glance - Lets you edit or delete packages easily

Edit a Package

Need to change something? No problem!

  1. Run /manage_subs
  2. Select the package you want to edit
  3. Modify title, description, price, or anything else
  4. Changes apply to future purchases (existing ones stay the same)

Common edits: - Updating pricing - Adding new benefits - Changing subscription duration - Fixing typos in descriptions

Delete a Package

Sometimes you need to remove a package entirely.

  1. Run /manage_subs
  2. Select the package you want to delete
  3. Choose "Delete" option

⚠️ Important Warning: Deleting a package doesn't refund existing purchases or remove roles from users who already bought it. They keep what they paid for! Only delete if you're sure you don't want to sell it anymore.

View Analytics

Want to see how your packages are performing?

Run /role_analytics to see: - Total revenue per package (see what's selling!) - Number of purchases (how popular each package is) - Active subscriptions (who's subscribed right now) - Revenue over time (track your growth)

This is super useful for understanding what your community likes and making decisions about pricing and packages!

Troubleshooting

Having issues? Don't worry, we've got you covered! Here are the most common problems and how to fix them.

Bot Won't Assign Roles

Problem: Payment went through but the role wasn't assigned

Solutions (try these in order):

  1. Check your log channel first!
  2. Look for the payment notification
  3. See what status it shows - did it fail? Is it still in progress?
  4. Check for any error messages

  5. This is usually the fastest way to see what went wrong!

  6. Check bot permissions

  7. Bot needs "Manage Roles" permission (check server settings)
  8. Bot's role must be above the role being assigned

  9. Go to Server Settings → Roles and drag bot's role higher in the list

  10. Run /debug_purchase

  11. Shows the exact error
  12. Sometimes provides fix buttons if possible

  13. Shows full purchase status

  14. Check webhook configuration

  15. Run /stripe_api_status to verify everything is connected
  16. Make sure webhook secret is correct

  17. Check Stripe Dashboard → Webhooks for any errors

  18. Wait a bit

  19. Webhooks can take 30-60 seconds to process
  20. Automated verifier runs every 60 seconds
  21. Check again after 2 minutes
  22. Watch your log channel - it will update when payment processes!

Commands Not Appearing

Problem: Slash commands don't show up when you type /

Solutions:

  1. Wait 5-10 minutes - Discord caches commands and it takes time to update
  2. Restart Discord - Close and reopen the Discord app completely
  3. Check bot is online - Make sure the bot is actually running
  4. Verify invite URL - When you invited the bot, make sure it had applications.commands scope

Stripe Connection Issues

Problem: /stripe_api_status shows errors or won't connect

Solutions:

  1. Verify your API key
  2. Check it starts with sk_test_, sk_live_, rk_test_, or rk_live_
  3. Make sure you copied the full key (they're long!)
  4. For restricted keys (rk_), double-check it has the required permissions

  5. Try regenerating it in Stripe Dashboard

  6. Check your webhook secret

  7. Must start with whsec_
  8. Get it from Stripe Dashboard → Webhooks → Click on your endpoint

  9. Try re-registering with /register_stripe

  10. Test vs Live Mode

  11. Make sure you're using test keys (sk_test_ or rk_test_) in test mode
  12. Don't mix test and live keys - it won't work!

Payment Not Processing

Problem: Checkout opens but payment doesn't complete

Solutions:

  1. Check your log channel first!
  2. Did a notification appear when they clicked purchase?
  3. Is it stuck on "Payment Session Created"?
  4. Does it show "Payment In Progress" but never completes?

  5. The log channel will show you exactly where the process stopped

  6. Check webhook URL

  7. Must be publicly accessible (not localhost)
  8. Must use HTTPS (not HTTP)

  9. Contact bot owner if you're not sure about this

  10. Check Stripe Dashboard

  11. Go to Payments → See if the payment actually appears there
  12. Check Webhooks → See if the webhook was received by Stripe

  13. Look for any error messages

  14. Run /debug_purchase

  15. Shows payment status
  16. Identifies webhook issues
  17. Gives you more details about what's happening

Role Package Not Showing

Problem: Can't find your package in /push_sub_to or /purchase_role

Solutions:

  1. Check if package was created
  2. Run /manage_subs to see all your packages

  3. Verify the package actually exists in the list

  4. Check permissions

  5. Some commands require premium subscription (if enabled)

  6. Make sure you have admin permissions on the server

  7. Try creating again

  8. Run /create_sub again from the beginning
  9. Make sure you complete all the steps (don't cancel halfway through)

Command Reference

Setup Commands

Command Description Who Can Use
/server_config Configure server settings (log channel, creator role) Server Admin
/register_stripe Connect Stripe API key and webhook secret Server Admin
/remove_stripe Disconnect Stripe account Server Admin
/stripe_api_status Check Stripe connection status Server Admin

Role Package Commands

Command Description Who Can Use
/create_sub Create a new paid role package Admin (Premium required)
/manage_subs Edit or delete role packages Admin (Premium required)
/push_sub_to Publish role package to a channel Admin (Premium required)
/purchase_role Purchase a role package Anyone
/role_analytics View purchase stats and revenue Admin

Testing & Debugging

Command Description Who Can Use
/test_payment_flow Quick test setup (creates test role & package) Admin
/debug_purchase Debug why a role wasn't assigned Admin

Help Commands

Command Description Who Can Use
/onboard Interactive guided setup walkthrough Anyone
/faq Common questions and tutorials Anyone

Best Practices

Security

Organization

Pricing

Support & Monitoring

Getting Help

Stuck on something? Here's how to get help:

  1. Run /faq - Answers to the most common questions
  2. Run /onboard - Interactive setup guide that walks you through everything
  3. Check /stripe_api_status - Verify your Stripe connection is working
  4. Use /debug_purchase - Debug specific payment issues with detailed info
  5. Check your log channel - Often shows what's wrong right away
  6. Contact bot owner - For technical issues or if nothing else works

Next Steps

Awesome! You're all set up. Here's what to do next:

  1. ✅ Create multiple role packages - Different tiers at different price points
  2. ✅ Set up subscriptions - Recurring revenue is great for steady income
  3. ✅ Monitor analytics - Use /role_analytics to see what's working
  4. ✅ Promote your roles - Share them with your community!
  5. ✅ Offer creator roles - Let trusted members create packages too
  6. ✅ Watch your log channel - Keep an eye on payments to catch issues early

You're ready to start selling! Happy selling! 🎉