Discord Integration API

Complete API reference for Discord role delivery integration.

Overview

Pixlpay supports Discord role delivery for stores using the Discord platform. When customers purchase products that include Discord roles, the roles are queued for delivery to their Discord account.

How It Works

Pixlpay uses a Custom Discord Bot approach for role delivery. Store owners create their own Discord bot and configure it to point to Pixlpay's webhook endpoint. Roles are delivered when customers use the /claim command.

1. Customer purchases product with Discord role
2. Role queued to delivery queue (pending)
3. Customer runs /claim in Discord server
4. Discord sends interaction to Pixlpay webhook
5. Pixlpay uses store's bot token to assign role
6. Customer receives role instantly

Key Benefits

Feature	Description
Zero Hosting	No VPS or server required
Always Online	Discord's infrastructure ensures 100% uptime
Easy Setup	~5 minutes to configure
Instant Delivery	Roles assigned immediately when customer runs `/claim`
Secure	Bot token encrypted, Ed25519 signature verification

Setup Requirements

Create a Discord Application at Discord Developer Portal
Add a Bot to your application
Get your credentials:
- Application ID: Found in General Information
- Public Key: Found in General Information (64 hex characters)
- Bot Token: Found in Bot section
Configure the Interactions Endpoint URL in your Discord application
Invite the bot to your Discord server with Manage Roles permission

Full Setup Guide

API Endpoints

Get Custom Bot Configuration

http

GET /api/v1/tenant/discord/custom-bot
Authorization: Bearer YOUR_API_TOKEN
X-Tenant-Id: YOUR_STORE_ID

Response:

json

{
  "configured": true,
  "bot": {
    "application_id": "123456789012345678",
    "is_enabled": true,
    "slash_commands_registered": true,
    "last_interaction_at": "2025-01-20T14:30:00Z",
    "stats": {
      "total_interactions": 150,
      "total_roles_assigned": 120,
      "total_roles_removed": 10,
      "total_errors": 5,
      "success_rate": 96.0
    }
  },
  "interactions_url": "https://api.pixlpay.net/webhook/discord/interactions/your-store"
}

Save Custom Bot Credentials

http

POST /api/v1/tenant/discord/custom-bot
Authorization: Bearer YOUR_API_TOKEN
X-Tenant-Id: YOUR_STORE_ID
Content-Type: application/json

Request Body:

json

{
  "application_id": "123456789012345678",
  "public_key": "abc123def456...",
  "bot_token": "MTIzNDU2Nzg5MDEyMzQ1Njc4.ABcDEf.ghIJklMNopQRstUVwxYZ"
}

Field	Type	Required	Description
`application_id`	string	Yes	Discord Application ID (numeric snowflake)
`public_key`	string	Yes	Ed25519 public key (64 hex characters)
`bot_token`	string	Yes	Bot token from Discord Developer Portal

Response:

json

{
  "message": "Custom bot configured and commands registered successfully!",
  "bot": {
    "application_id": "123456789012345678",
    "is_enabled": true,
    "slash_commands_registered": true
  },
  "interactions_url": "https://api.pixlpay.net/webhook/discord/interactions/your-store"
}

Test Bot Connection

http

POST /api/v1/tenant/discord/custom-bot/test
Authorization: Bearer YOUR_API_TOKEN
X-Tenant-Id: YOUR_STORE_ID

Response (Success):

json

{
  "connected": true,
  "bot_name": "My Store Bot",
  "bot_id": "123456789012345678",
  "bot_avatar": "https://cdn.discordapp.com/avatars/123456789012345678/abc123.png"
}

Response (Failure):

json

{
  "connected": false,
  "error": "Invalid bot token"
}

Enable/Disable Bot

http

POST /api/v1/tenant/discord/custom-bot/toggle
Authorization: Bearer YOUR_API_TOKEN
X-Tenant-Id: YOUR_STORE_ID
Content-Type: application/json

Request Body:

json

{
  "enabled": true
}

Response:

json

{
  "message": "Bot enabled",
  "is_enabled": true
}

Register Slash Commands

Re-register /claim, /check, and /help commands if they are missing.

http

POST /api/v1/tenant/discord/custom-bot/register-commands
Authorization: Bearer YOUR_API_TOKEN
X-Tenant-Id: YOUR_STORE_ID

Response:

json

{
  "message": "Commands registered successfully! They may take up to an hour to appear globally.",
  "slash_commands_registered": true
}

Get Bot Invite URL

http

GET /api/v1/tenant/discord/custom-bot/invite-url
Authorization: Bearer YOUR_API_TOKEN
X-Tenant-Id: YOUR_STORE_ID

Response:

json

{
  "url": "https://discord.com/api/oauth2/authorize?client_id=123456789012345678&permissions=268435456&scope=bot%20applications.commands"
}

Get Bot Statistics

http

GET /api/v1/tenant/discord/custom-bot/stats
Authorization: Bearer YOUR_API_TOKEN
X-Tenant-Id: YOUR_STORE_ID

Response:

json

{
  "stats": {
    "total_interactions": 150,
    "total_roles_assigned": 120,
    "total_roles_removed": 10,
    "total_errors": 5,
    "success_rate": 96.0,
    "last_interaction_at": "2025-01-20T14:30:00Z",
    "is_active": true
  }
}

Remove Custom Bot

http

DELETE /api/v1/tenant/discord/custom-bot
Authorization: Bearer YOUR_API_TOKEN
X-Tenant-Id: YOUR_STORE_ID

Response:

json

{
  "message": "Custom bot removed"
}

Discord Slash Commands

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

Command	Description
`/claim`	Claim all pending role deliveries
`/check`	View pending and recent role deliveries
`/help`	Show available commands and instructions

Discord Interactions Webhook

Pixlpay receives Discord interactions at:

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

This webhook:

Verifies Ed25519 signatures using your Public Key
Handles PING verification (type 1)
Processes slash commands (type 2)
Processes button clicks (type 3)

You do not need to implement this webhook - Pixlpay handles everything. Just set the URL in your Discord application's settings.

Error Responses

All endpoints return consistent error formats:

401 Unauthorized

json

{
  "success": false,
  "error": "Unauthorized",
  "message": "Invalid or missing API token"
}

403 Forbidden

json

{
  "success": false,
  "error": "Forbidden",
  "message": "Token does not have required scope"
}

404 Not Found

json

{
  "success": false,
  "error": "Not Found",
  "message": "Operation not found"
}

422 Unprocessable Entity

json

{
  "success": false,
  "error": "Validation Error",
  "message": "The given data was invalid",
  "errors": {
    "application_id": ["Application ID must be a numeric Discord snowflake."]
  }
}

429 Too Many Requests

json

{
  "success": false,
  "error": "Too Many Requests",
  "message": "Rate limit exceeded",
  "retry_after": 60
}

Rate Limits

Standard API rate limits apply (60 requests per minute).

Delivery Queue Status Values

Status	Description
`pending`	Awaiting delivery (customer needs to run `/claim`)
`completed`	Successfully delivered
`failed`	Failed after maximum retry attempts
`expired`	Expired without being claimed (default: 72 hours)

Delivery Source Values:

Value	Description
`interaction`	Delivered via Custom Bot `/claim` command
`auto`	Automatically delivered (future feature)
`manual`	Manually delivered by store owner

Discord Integration Guide - Setup instructions
Custom Discord Bot Setup - Detailed setup guide
Authentication - API token setup
Webhook Events - Discord webhook payloads

Discord Integration API ​

Overview ​

How It Works ​

Key Benefits ​

Setup Requirements ​

API Endpoints ​

Get Custom Bot Configuration ​

Save Custom Bot Credentials ​

Test Bot Connection ​

Enable/Disable Bot ​

Register Slash Commands ​

Get Bot Invite URL ​

Get Bot Statistics ​

Remove Custom Bot ​

Discord Slash Commands ​

Discord Interactions Webhook ​

Error Responses ​

401 Unauthorized ​

403 Forbidden ​

404 Not Found ​

422 Unprocessable Entity ​

429 Too Many Requests ​

Rate Limits ​

Delivery Queue Status Values ​

Related Documentation ​

Discord Integration API

Overview

How It Works

Key Benefits

Setup Requirements

API Endpoints

Get Custom Bot Configuration

Save Custom Bot Credentials

Test Bot Connection

Enable/Disable Bot

Register Slash Commands

Get Bot Invite URL

Get Bot Statistics

Remove Custom Bot

Discord Slash Commands

Discord Interactions Webhook

Error Responses

401 Unauthorized

403 Forbidden

404 Not Found

422 Unprocessable Entity

429 Too Many Requests

Rate Limits

Delivery Queue Status Values

Related Documentation