Hytale Plugin

The Pixlpay Hytale plugin integrates directly with your Hytale server to automatically deliver purchased items to players.

Features

• Native Hytale Server integration
• Automatic polling for pending deliveries (every 60 seconds)
• Support for purchases, refunds, chargebacks, and subscription cancellations
• Offline player queuing (delivers when player connects)
• Purchase announcements to all players
• Promotional messages with clickable store links
• Heartbeat monitoring
• Debug logging

Requirements

• Hytale dedicated server (Early Access or later)
• Java 21+

Installation

Step 1: Download the Plugin

Download PixlPay.jar

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

Step 2: Install the Plugin

Copy pixlpay-hytale.jar to your server's plugins directory:

plugins/pixlpay-hytale.jar

Step 3: Start the Server

Start your Hytale server. The plugin will generate a default configuration file at plugins/PixlPay/config.json.

Step 4: Configure Your Secrets

Edit plugins/PixlPay/config.json with your secrets (see Configuration below).

Step 5: Restart the Server

Restart your server to apply the configuration.

Configuration

Edit plugins/PixlPay/config.json:

{
  "storeSecret": "YOUR_STORE_SECRET_HERE",
  "serverSecret": "YOUR_SERVER_SECRET_HERE",
  "debug": false,
  "announce": true,
  "promoEnabled": true,
  "promoIntervalMinutes": 30,
  "promoMessage": "Visit our store for exclusive items and ranks!",
  "promoLinkOnLogin": true,
  "promoLinkEnabled": false,
  "promoLinkIntervalMinutes": 15,
  "promoLinkMessage": "Click here to visit our store!",
  "promoLinkUrl": "https://pixlpay.net"
}

Configuration Options

Option	Default	Description
storeSecret	""	Your store's secret key (from dashboard)
serverSecret	""	This server's secret key (from dashboard)
debug	false	Enable verbose logging for troubleshooting
announce	true	Broadcast purchase announcements to all players
promoEnabled	true	Enable periodic store promotion messages
promoIntervalMinutes	30	How often to send promo messages (minutes)
promoMessage	"Visit our store..."	The promotional message text
promoLinkOnLogin	true	Send clickable store link when player joins
promoLinkEnabled	false	Enable periodic clickable store link broadcasts
promoLinkIntervalMinutes	15	How often to broadcast promo link (minutes)
promoLinkMessage	"Click here..."	The clickable link message text
promoLinkUrl	"https://pixlpay.net"	URL for the clickable store link

Getting Your Secrets

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

How It Works

1. Plugin polls Pixlpay API every 60 seconds for pending notifications
2. Plugin sends a heartbeat every 120 seconds to report server status
3. Four 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
   • Subscription Cancel: Executes when a subscription is cancelled
4. Commands requiring online players are queued if player is offline
5. When player connects (after a 22-second load delay), queued commands execute automatically
6. Multiple commands per product are supported (one per line)
7. Results are reported back to Pixlpay

Setting Up Products

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

Example Commands

Give Items:

give {player} wood 64
give {player} stone 32

Grant Permissions:

perm add {player} vip.kit

Available Placeholders

Placeholder	Description
{player}	Player's username
{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
perm add {player} vip.status

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.

Purchase Announcements

When announce is enabled (default), all players see a message when someone makes a purchase:

[pixlpay.net] PlayerName purchased Product Name!

This can be disabled by setting "announce": false in the config.

Promotional Features

Promo Messages

When promoEnabled is true, the plugin broadcasts your promoMessage to all online players at the interval specified by promoIntervalMinutes:

[pixlpay.net] Visit our store for exclusive items and ranks!

Clickable Store Links

The plugin can send clickable links that open in the player's browser:

• On Login: When promoLinkOnLogin is true, players receive a clickable link when they join
• Periodic Broadcasts: When promoLinkEnabled is true, broadcasts clickable links at the promoLinkIntervalMinutes interval

The link text is customizable via promoLinkMessage and the URL via promoLinkUrl.

Troubleshooting

Plugin Not Loading

Symptoms:

• Plugin doesn't appear in server console on startup
• No config file generated

Solutions:

1. Ensure Java 21+ is installed
2. Verify the JAR is in the correct plugins/ directory
3. Check server console for error messages

Authentication Errors (401)

Symptoms:

• "Authentication failed" in logs
• "Invalid store secret" message

Solutions:

1. Verify both secrets are correct in config
2. Check the keys match your Pixlpay dashboard
3. Ensure your store is approved on pixlpay.net (unapproved stores will show "Invalid store secret")
4. Restart the server after updating config

Commands Not Executing

Solutions:

1. Enable debug mode: set "debug": true in config
2. Check the server console for detailed logs
3. Verify player username matches exactly (case-insensitive)

Player Not Found

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

Solutions:

1. Ensure the player username matches exactly (the API sends usernames, not UUIDs)
2. Verify player is online if using "When Online" mode
3. Note: Players need ~22 seconds after connecting before they're marked as online

Support

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