Custom Discord Bot

Set up your own Discord bot for seamless role delivery without hosting any infrastructure.

Overview

The Custom Discord Bot feature allows you to deliver Discord roles to customers without running any server software. Instead of hosting a bot yourself, you create a Discord application and Pixlpay handles all the interaction logic through Discord's HTTP interactions system.

Key Benefits

Feature	Description
Hosting	No hosting required - Pixlpay handles everything
Setup Time	~5 minutes to configure
Uptime	100% uptime via Discord's infrastructure
Maintenance	None - updates are automatic
Technical Skill	Beginner friendly - just paste credentials

Why Custom Discord Bot?

• Zero Hosting: The bot logic runs on Pixlpay's servers, triggered by Discord
• Always Online: No need to worry about your bot going offline
• Easy Setup: Just create a Discord application and paste credentials
• Instant Updates: New features are automatically available
• Same Security: Your bot token is encrypted and secure

Prerequisites

Before starting, you will need:

1. A Discord account with permission to manage a Discord server
2. Access to the Discord Developer Portal
3. A Pixlpay store with Discord integration enabled

Step-by-Step Setup

Step 1: Create a Discord Application

1. Go to the Discord Developer Portal
2. Click New Application (top right)
3. Enter a name for your bot (e.g., "My Store Bot")
4. Accept the Developer Terms of Service
5. Click Create

Step 2: Get Your Application Credentials

From your application's General Information page, you will need two values:

1. Application ID - A long number (e.g., 123456789012345678)
2. Public Key - A 64-character hexadecimal string

Keep These Safe

Copy both values somewhere safe - you will need them when configuring Pixlpay.

Step 3: Create Your Bot

1. Go to Bot in the left sidebar
2. Click Add Bot (or Reset Token if already created)
3. Click Yes, do it! to confirm

Once created, you need to get your Bot Token:

1. Under the bot's username, click Reset Token
2. Confirm the action
3. Copy the token immediately - it won't be shown again!

Keep Your Token Secret

Your bot token is like a password. Never share it publicly or commit it to version control. If compromised, reset it immediately.

Step 4: Set the Interactions Endpoint URL

This is the crucial step that connects Discord to Pixlpay:

1. Go to General Information in your Discord application
2. Find the Interactions Endpoint URL field
3. Enter your store's webhook URL in this format:

https://api.pixlpay.net/webhook/discord/interactions/{your-store-slug}

Replace {your-store-slug} with your actual store slug. For example, if your store is mystore.pixlpay.net, the URL would be:

https://api.pixlpay.net/webhook/discord/interactions/mystore

4. Click Save Changes

Finding Your Interactions URL

The exact URL is shown in your Pixlpay dashboard under Settings > Integrations > Discord > Custom Bot Setup. You can copy it directly from there.

Discord will immediately verify the endpoint by sending a PING request. If you see an error, make sure:

• The URL is exactly correct (no trailing slashes)
• You have saved your credentials in Pixlpay first (see Step 6)

Step 5: Invite the Bot to Your Server

Your bot needs to be in your Discord server to assign roles:

1. Go to OAuth2 > URL Generator in your Discord application
2. Under Scopes, select:
   • bot
   • applications.commands
3. Under Bot Permissions, select:
   • Manage Roles
4. Copy the Generated URL at the bottom
5. Open the URL in your browser
6. Select your Discord server from the dropdown
7. Click Authorize

Bot Role Position

After inviting the bot, go to Server Settings > Roles in Discord. Drag your bot's role above all the roles it needs to assign. Bots can only assign roles lower than their own role in the hierarchy.

Step 6: Configure in Pixlpay Dashboard

Now connect everything in your Pixlpay dashboard:

1. Go to Settings > Integrations > Discord
2. Scroll to Custom Bot Setup
3. Enter your credentials:
   • Application ID - From Step 2
   • Public Key - From Step 2
   • Bot Token - From Step 3
4. Click Save & Register Commands

Pixlpay will:

1. Validate your bot token
2. Register the slash commands (/claim, /check, /help)
3. Show a success message

Global Commands Take Time

Slash commands are registered globally, which can take up to 1 hour to appear in all servers. For immediate testing, commands appear instantly in the server where you created the bot.

Customer Commands

Once set up, your customers can use these commands in your Discord server:

/claim

Claims all pending role deliveries for the customer.

/claim

Response:

Roles assigned:
- VIP Member
- Premium Access

Your roles have been delivered!

/check

Shows pending and recently delivered roles.

/check

Response:

Pending roles:
- VIP Member

Recently delivered (last 24h):
- Premium Access (2 hours ago)

Use /claim to receive your pending roles!

/help

Displays available commands and how to use them.

/help

Response:

MyStore Bot Commands

/claim - Claim your purchased Discord roles
/check - View pending and recent role deliveries
/help - Show this help message

How it works:
1. Purchase a product with Discord roles on the store
2. Make sure your Discord account is linked on the store
3. Use /claim here to receive your roles

Need help? Contact the store owner for support.

How Delivery Works

The Custom Discord Bot uses Discord's HTTP Interactions model - a modern, webhook-based approach:

Customer purchases product with Discord role
              |
              v
   Pixlpay queues role delivery
   (stored in discord_delivery_queue)
              |
              v
   Customer runs /claim in Discord
              |
              v
   Discord sends HTTP POST to Pixlpay
   (to your Interactions Endpoint URL)
              |
              v
   Pixlpay verifies signature using Public Key
              |
              v
   Pixlpay assigns role using your Bot Token
              |
              v
   Customer receives role instantly!

Key Points

1. Customer-Initiated: Roles are delivered when customers use /claim
2. Instant Response: Discord requires a response within 3 seconds - Pixlpay handles this
3. Secure: Every interaction is cryptographically verified using Ed25519 signatures
4. Reliable: Discord's infrastructure ensures 100% uptime for command delivery

Dashboard Statistics

Monitor your bot's activity in the Pixlpay dashboard:

Statistic	Description
Total Interactions	All commands processed
Roles Assigned	Successfully delivered roles
Roles Removed	Roles removed (refunds, subscription cancellations)
Errors	Failed operations (permission issues, etc.)
Success Rate	Percentage of successful operations
Last Interaction	When the bot last processed a command

Troubleshooting

"This server is not connected to any store"

The Discord server isn't linked to your Pixlpay store.

Solution: Use the internal Pixlpay bot's /verify command to connect the server:

1. Invite the Pixlpay verification bot to your server
2. Run /verify {code} with your store's verification code
3. Try /claim again

"You don't have any pending role deliveries"

The customer doesn't have any roles waiting to be claimed.

Possible causes:

• Customer hasn't linked their Discord account on your store
• Customer hasn't completed a purchase with Discord roles
• Roles were already delivered

Solution: Have the customer:

1. Log in to their account on your store
2. Link their Discord account in account settings
3. Check their order includes Discord role delivery

Discord shows "Interaction failed"

The interaction endpoint couldn't respond in time or returned an error.

Possible causes:

• Incorrect Interactions Endpoint URL
• Bot credentials not configured in Pixlpay
• Bot is disabled in Pixlpay

Solution:

1. Verify the Interactions Endpoint URL is exactly correct
2. Check bot is enabled in Settings > Integrations > Discord
3. Re-save your bot credentials

Bot can't assign a role

The role assignment fails even though the command works.

Possible causes:

• Bot role is lower than the target role
• Bot doesn't have "Manage Roles" permission
• Role is managed by an integration (e.g., Nitro Booster)

Solution:

1. Go to Server Settings > Roles in Discord
2. Drag your bot's role above the roles it needs to assign
3. Check the bot has "Manage Roles" permission
4. Ensure target roles aren't integration-managed

Commands not appearing in Discord

Slash commands don't show up when typing /.

Possible causes:

• Commands were just registered (can take up to 1 hour)
• Bot isn't in the server
• applications.commands scope wasn't selected when inviting

Solution:

1. Wait up to 1 hour for global command propagation
2. Re-invite the bot with both bot and applications.commands scopes
3. Click "Re-register Commands" in Pixlpay dashboard

"Invalid signature" errors in logs

Discord signature verification is failing.

Possible causes:

• Incorrect Public Key entered in Pixlpay
• Public Key was regenerated in Discord

Solution:

1. Go to Discord Developer Portal > General Information
2. Copy the current Public Key
3. Update it in Pixlpay dashboard
4. Save changes

Security Notes

Why Custom Bot is Safe

The Custom Discord Bot approach maintains liability compliance through delegation:

1. Store Owner Ownership: You create and own the Discord application
2. Delegated Authority: You authorize Pixlpay to act on your behalf using your credentials
3. Revocable Access: You can reset your bot token anytime to revoke access
4. Same as Stripe: Similar to how you connect your Stripe account - you remain the owner

Token Security

Your bot token is protected:

• Encrypted at rest using Laravel's encryption
• Never exposed in API responses after saving
• Never logged or stored in plaintext
• Transmitted only over HTTPS

Interaction Verification

Every Discord interaction is verified:

• Discord signs each request with Ed25519
• Pixlpay verifies using your Public Key
• Invalid signatures are rejected immediately
• Prevents spoofed or tampered requests

Best Practices

1. Unique Bot Name: Give your bot a name related to your store for brand recognition
2. Custom Avatar: Upload a logo or avatar for your bot in Discord Developer Portal
3. Role Hierarchy: Keep your bot's role high in the hierarchy but below admin roles
4. Monitor Stats: Check the dashboard regularly for errors or unusual activity
5. Communicate: Tell customers to use /claim after purchase - add it to your order confirmation emails

Next Steps

• Discord Integration Overview - General Discord integration guide
• Products - Configure products with Discord roles
• Webhooks - Get notified when roles are delivered