Minecraft Bedrock Plugin (PocketMine-MP)

The Pixlpay Minecraft Bedrock plugin integrates directly with your PocketMine-MP server to automatically deliver purchased items to players.

Features

• Native PocketMine-MP integration
• Automatic polling for pending deliveries
• Support for purchases, refunds, and chargebacks
• Online player queuing (wait for player to connect)
• Admin commands for debugging and management
• Detailed logging
• Persistent queue across server restarts

Requirements

• PocketMine-MP 5.0.0 or higher
• PHP 8.0 or higher
• Pixlpay store account with Game Server configured

Installation

Option 1: Phar Archive (Recommended)

Step 1: Download the Plugin

Download PixlPay.phar

Or get it from your Pixlpay Dashboard under Settings > Game Servers > Downloads.

Step 2: Install the Plugin

Copy PixlPay.phar to your server's plugins directory:

plugins/PixlPay.phar

Step 3: Start the Server

Start or restart your PocketMine-MP server. The plugin will generate a default configuration file at plugin_data/PixlPay/config.yml.

Option 2: Folder Plugin (Development)

1. Copy the entire plugin folder to your server's plugins/ directory
2. Rename it to PixlPay
3. Start or restart your server
4. Edit plugin_data/PixlPay/config.yml with your secrets

Configuration

Edit plugin_data/PixlPay/config.yml:

# Your Store Secret (from Pixlpay dashboard -> Game Servers)
store-secret: "your-store-secret-here"

# Your Server Secret (from Pixlpay dashboard -> Game Servers)
server-secret: "your-server-secret-here"

# Enable debug mode for verbose logging
debug-mode: false

Configuration Options

Option	Default	Description
store-secret	""	Your store's secret key (shared across all servers)
server-secret	""	This specific server's secret key (unique per server)
debug-mode	false	Enable verbose logging for troubleshooting

Getting Your Secrets

1. Log in to your Pixlpay Dashboard
2. Go to Settings > Game Servers
3. Click on your Minecraft Bedrock server (or add one)
4. Click Show Credentials to reveal the secrets
5. Copy both the Store Secret and Server Secret

Restart After Configuration

After entering your secrets, restart the server to apply the configuration.

How It Works

This plugin uses a PULL architecture for security:

1. Plugin polls Pixlpay API every 60 seconds for pending notifications
2. Plugin sends a heartbeat every 120 seconds to report server status
3. Three notification types are supported:
   • Purchase: Executes when player buys a product
   • Refund: Executes immediately when a refund is processed
   • Chargeback: Executes immediately when a dispute occurs
4. Commands requiring online players are queued if player is offline
5. When player connects, queued commands execute automatically
6. Multiple commands per product are supported (one per line)
7. Results are reported back to Pixlpay

The platform never connects directly to your server.

Timing Constants

Constant	Value	Purpose
Polling Interval	60 seconds	Time between API polls for pending commands
Online Check Interval	30 seconds	Time between checks for queued commands
Heartbeat Interval	120 seconds	Time between heartbeat status updates
Request Timeout	10 seconds	HTTP request timeout

Admin Commands

All commands require the pixlpay.admin permission (default: OP).

Command	Description
/pixlpay status	Show plugin status and configuration
/pixlpay poll	Force immediate poll for pending commands
/pixlpay queue	Show pending deliveries for offline players
/pixlpay history [count]	Show recent command execution history (default: 10)
/pixlpay test	Test API connection
/pixlpay debug	Toggle debug mode
/pixlpay heartbeat	Send heartbeat to API

Alias: /pp

Permissions

Permission	Description
pixlpay.admin	Access to all /pixlpay commands

By default, server operators (OP) have the pixlpay.admin permission.

Setting Up Products

When creating products in your Pixlpay dashboard, configure commands in the Delivery section.

Example Commands

Give Items:

give {player} diamond 64
give {player} iron_ingot 128
give {player} golden_apple 16

Grant Permissions (with LuckPerms):

lp user {player} parent add vip
lp user {player} permission set essentials.fly true

Server Messages:

say {player} just purchased VIP status!

Run Console Commands:

title {player} title Welcome VIP!
effect {player} speed 3600 2 true

Available Placeholders

Placeholder	Description
{player}	Player's username (or XUID in online mode)
{quantity}	Quantity purchased
{order_id}	Order ID
{order_number}	Order number
{product_name}	Product name
{customer_email}	Customer email
{customer_name}	Customer name

Multiple Commands

Add multiple commands, one per line:

give {player} diamond_sword 1
give {player} diamond_helmet 1
give {player} diamond_chestplate 1
give {player} diamond_leggings 1
give {player} diamond_boots 1
lp user {player} parent add vip
say {player} just became a VIP!

Execution Modes

Configure per-product in your Pixlpay dashboard:

Mode	Behavior
Immediate	Commands execute immediately, even if player is offline
When Online	Commands are queued until the player connects

For items that need to be given directly to a player's inventory, use "When Online" to ensure the player is connected.

Player Identification

Players are identified by their Xbox XUID (Xbox User ID) when the server is running in online mode. For servers running in offline mode, the player's username is used as a fallback.

When setting up products in your Pixlpay store, use the {player} placeholder in commands - it will automatically resolve to the correct identifier.

Offline Player Support

If a player is offline when a purchase is made:

1. The command is queued locally
2. When the player joins, queued commands are executed
3. Queued commands persist across server restarts

This ensures players never miss their purchases, even if they're offline or the server restarts.

Log Files

Logs are stored in plugin_data/PixlPay/logs/:

File	Contents
pixlpay-general_YYYY-MM-DD.log	All events (comprehensive log for debugging)
pixlpay-deliveries_YYYY-MM-DD.log	Successful deliveries
pixlpay-errors_YYYY-MM-DD.log	Errors and warnings only

Log Levels

Level	Description
[INFO]	General information (shown in console and files)
[DEBUG]	Verbose debug info (requires debug-mode: true)
[WARN]	Warnings (also written to error log)
[ERROR]	Errors (also written to error log)
[DELIVERY] / [REFUND] / [CHARGEBACK]	Command execution events

Troubleshooting

"Store Secret not configured"

Symptoms:

• Warning message on server startup

Solutions:

1. Edit plugin_data/PixlPay/config.yml
2. Add your Store Secret from the Pixlpay dashboard
3. Restart the server

Authentication Errors (401/403)

Symptoms:

• "Authentication failed" in logs
• Commands not being received

Solutions:

1. Verify both secrets are correct in config
2. Check the keys match your Pixlpay dashboard
3. Ensure you're using the correct Store Secret and Server Secret pair
4. Restart the server after updating config

"API request timed out"

Symptoms:

• Timeout errors in logs

Solutions:

1. Check your server's network connectivity
2. The plugin requires HTTPS access to api.pixlpay.net
3. Verify no firewall is blocking outbound HTTPS connections

Commands Not Executing

Solutions:

1. Check the command works when typed in console manually
2. Enable debug mode: /pixlpay debug
3. Check status: /pixlpay status
4. Test connection: /pixlpay test
5. Check logs in plugin_data/PixlPay/logs/

Player Not Found

Symptoms: Commands execute but player doesn't receive items.

Solutions:

1. Ensure player identifier format is correct (XUID for online mode, username for offline mode)
2. Verify player is online if using "When Online" mode
3. Check if player has inventory space
4. Test command manually in console

Common Item IDs

Item	ID
Diamond	diamond
Iron Ingot	iron_ingot
Gold Ingot	gold_ingot
Emerald	emerald
Diamond Sword	diamond_sword
Diamond Pickaxe	diamond_pickaxe
Diamond Armor Set	diamond_helmet, diamond_chestplate, diamond_leggings, diamond_boots
Golden Apple	golden_apple
Enchanted Golden Apple	enchanted_golden_apple
Elytra	elytra
Totem of Undying	totem_of_undying

TIP

For a complete list of item IDs, see the Minecraft Wiki or use autocomplete in your server console.

Security Best Practices

1. Protect your config file - Don't expose plugin_data/PixlPay/config.yml publicly
2. Use unique Server Secrets - Each server should have its own secret
3. Monitor your logs - Check for unauthorized access attempts
4. Keep PocketMine updated - Ensure you're running the latest version
5. Backup configurations - Keep copies of your config files

Support

• Troubleshooting Guide
• Command Reference
• Discord Support
• Contact Support