Discord Integration

Automatically assign Discord roles when customers make purchases.

Overview

The Discord integration allows you to:

• Assign roles when products are purchased
• Remove roles when subscriptions expire
• Require Discord authentication at checkout
• Sync customer Discord accounts

How It Works

Pixlpay uses a self-hosted bot architecture for Discord role delivery. You run your own Discord bot on your infrastructure, and it polls Pixlpay for pending role operations.

Customer Purchase
       |
       v
+------------------+
|  Pixlpay         |
|  (queues role)   |
+--------+---------+
         |
         |  Your bot polls every 30s
         v
+------------------+
|  Your Server     |
|  (Discord Agent) |
|       |          |
|       v          |
|  Discord API ----+--> Role Assigned
+------------------+

Why Self-Hosted?

Running your own bot gives you:

• Full Control - You own the bot, its permissions, and its behavior
• Security - Bot tokens and credentials stay on your infrastructure
• Customization - Modify the bot to fit your needs
• Reliability - No dependency on third-party bot hosting
• Data Privacy - Customer Discord data flows through your systems

Setting Up Discord

Step 1: Create a Discord Application

1. Go to Discord Developer Portal
2. Click New Application
3. Name it (e.g., "My Store Bot")
4. Go to Bot section
5. Click Add Bot or Reset Token
6. Copy the Bot Token (you'll need this later)
7. Important: Enable Server Members Intent under Privileged Gateway Intents

Step 2: Invite Bot to Your Server

1. Go to OAuth2 > URL Generator
2. Select scopes: bot
3. Select permissions: Manage Roles
4. Copy the generated URL
5. Open the URL and select your Discord server
6. Authorize the bot

Important

The bot's role must be higher than roles it assigns. Drag the bot's role above other roles in Server Settings > Roles.

Step 3: Configure Discord in Pixlpay

1. Go to Settings > Integrations > Discord in your store dashboard
2. Enter your Client ID and Client Secret (from OAuth2 section of Discord Developer Portal)
3. Click Save
4. Copy the Guild ID of your Discord server

Step 4: Create an API Token

Create an API token for your Discord Agent:

1. Go to Settings > API Tokens
2. Click Create Token
3. Name it (e.g., "Discord Agent")
4. Select the discord:agent scope
5. Click Generate
6. Copy the token immediately - it won't be shown again

Step 5: Set Up the Discord Agent

The Discord Agent is a Node.js application that runs on your server:

1. Download the agent from your Pixlpay dashboard or GitHub
2. Install dependencies:

cd discord-agent
npm install

3. Create a .env file:

cp .env.example .env

4. Configure your credentials:

# Your Pixlpay API Key (with discord:agent scope)
PIXLPAY_API_KEY=sk_live_your_api_key_here

# Your Discord Bot Token
DISCORD_BOT_TOKEN=your_discord_bot_token_here

# Optional: Your store's API URL (default: https://yourstore.pixlpay.net)
# PIXLPAY_API_URL=https://yourstore.pixlpay.net

5. Start the agent:

npm start

You should see:

=============================================
  Pixlpay Discord Agent
=============================================
  Bot: YourBot#1234
  Guilds: 1
  Poll Interval: 30s
=============================================

[Agent] Connected to guilds:
  - Your Server (123456789)

[Agent] Starting to poll for pending operations...

Running in Production

For production, use a process manager like PM2:

# Install PM2
npm install -g pm2

# Start the agent
pm2 start src/index.js --name "discord-agent"

# Save process list
pm2 save

# Set up auto-start on boot
pm2 startup

Or use Docker:

docker build -t pixlpay-discord-agent .
docker run -d --env-file .env pixlpay-discord-agent

See the Discord Agent Documentation for more deployment options.

Configuring Role Delivery

On Products

When creating or editing a product:

1. Go to the Delivery tab
2. Enable Discord Role
3. Select your Discord server
4. Choose the role to assign

Multiple Roles

You can assign multiple roles per product:

1. Click Add Role
2. Select additional roles
3. Save the product

Requiring Discord at Checkout

Force customers to connect Discord before purchase:

1. Go to Settings > Checkout
2. Enable Require Discord
3. Customers must authenticate before paying

Subscription Behavior

For subscription products:

• On Purchase - Role is assigned immediately
• On Renewal - Role remains active
• On Cancellation - Role is removed after period ends
• On Expiration - Role is automatically removed

Troubleshooting

Agent Not Receiving Operations

• Verify the API token has discord:agent scope
• Check the agent is running and connected to Discord
• Ensure the PIXLPAY_API_URL points to your store

Bot Can't Assign Role

• Ensure bot role is higher than target role in Discord
• Check bot has "Manage Roles" permission
• Verify role ID is correct
• Make sure Server Members Intent is enabled

Customer Not Receiving Role

• Confirm customer authenticated with Discord
• Check if customer is in your Discord server
• Check the order delivery status in your dashboard
• View agent logs for error messages

Discord Connection Failed

• Verify Client ID and Secret in Pixlpay settings
• Check redirect URI matches
• Regenerate bot token if needed

"Member not found in guild"

The customer is not in your Discord server. They need to join before the role can be assigned.

Best Practices

1. Use dedicated hosting - Run the agent on a VPS or cloud server with good uptime
2. Monitor the agent - Set up logging and alerts for failures
3. Secure your credentials - Never commit .env files to version control
4. Test before launch - Verify role assignment works before accepting real orders
5. Keep the agent updated - Check for updates to get bug fixes and improvements

Next Steps

• Discord Agent API Reference - Full API documentation
• Troubleshooting Guide - Common issues and solutions
• Game Servers - Deliver to game servers too