How Delivery Works

Understanding the Pixlpay delivery architecture helps you troubleshoot issues and configure your servers correctly.

Pull-Based Architecture

Pixlpay uses a pull model where your game server actively fetches pending deliveries from our API. This is different from a push model where we would connect directly to your server.

┌─────────────┐     ┌─────────────┐     ┌─────────────┐
│  Customer   │────▶│   Pixlpay   │◀────│ Your Server │
│             │     │   Platform  │     │   Plugin    │
└─────────────┘     └─────────────┘     └─────────────┘
     Makes              Queues            Polls for
    Purchase           Commands           Commands

Why Pull-Based?

Benefit	Explanation
Security	Pixlpay never initiates connections to your server
Firewall Friendly	No inbound ports needed on your server
No Credentials Stored	RCON passwords stay on your server, not our platform
Reliability	Commands queue during server restarts or outages
Your Control	You decide when and how commands execute

The Delivery Flow

1. Purchase Made

When a customer completes a purchase:

1. Payment is processed via your payment gateway
2. Order is marked as "paid" in Pixlpay
3. Delivery commands are queued for each product

2. Plugin Polls API

Your game server plugin periodically calls our API:

GET /api/v1/agent/commands/pending
Headers:
  X-Store-Secret: your_store_secret
  X-Server-Secret: your_server_secret

The API returns pending commands for this specific server.

3. Command Execution

The plugin processes each command:

1. Replaces placeholders with actual values ({player}, {quantity}, etc.)
2. Executes the command on your game server
3. Records success or failure

4. Status Reporting

After execution, the plugin reports back:

POST /api/v1/agent/commands/{id}/confirm
# or
POST /api/v1/agent/commands/{id}/fail

This updates the order in your dashboard.

Notification Types

Plugins handle four types of notifications:

Purchase Notifications

Triggered when a customer successfully pays for an order.

• Can be configured to wait for player online
• Most common notification type
• Commands defined per-product

Refund Notifications

Triggered when you issue a refund through your dashboard or the payment provider.

• Execute immediately (don't wait for online)
• Typically remove items or revoke access
• Optional - configure per-product

Chargeback Notifications

Triggered when a customer disputes a payment with their bank.

• Execute immediately
• Usually more severe than refund commands
• Recommended for subscription/rank products

Subscription Cancel Notifications

Triggered when a subscription is canceled or expires.

• Execute immediately (don't wait for online)
• Revokes ongoing subscription benefits
• Essential for subscription products - prevents players keeping perks after subscription ends

How Subscription Cancellations Are Detected

Pixlpay detects subscription cancellations through multiple methods:

1. Webhooks - Instant notification from payment providers (Stripe, PayPal, etc.)
2. Sync Jobs - Hourly polling of payment provider APIs to catch missed webhooks
3. Manual Actions - When you or the customer cancels via dashboard

This ensures subscription cancel commands run reliably, even if webhooks fail.

Online vs Offline Delivery

Immediate Execution

Commands execute as soon as they're received, regardless of player status. Good for:

• Server-wide announcements
• Adding resources to a shared pool
• Commands that don't require a player

Wait for Online

Commands queue until the player connects to the server. Good for:

• Giving items directly to a player
• Setting player-specific permissions
• Spawning items near the player

Configure this per-product in your Pixlpay dashboard under Product > Delivery Settings.

Polling Intervals

Component	Interval	Purpose
Command Polling	5-60 seconds	Check for new deliveries
Heartbeat	2 minutes	Keep server status updated

All plugins poll at the same default interval of 60 seconds. This balances responsiveness with API efficiency.

Delivery Queue

Commands that can't be delivered immediately are queued:

• Offline Players: If "wait for online" is enabled
• Server Restarts: Commands resume when the server comes back
• Temporary Failures: Retried automatically

View queued commands:

• In your Pixlpay dashboard under Orders
• Using plugin commands like /pixlpay queue

Authentication

All communication uses dual-secret authentication:

Header	Purpose
X-Store-Secret	Identifies your store
X-Server-Secret	Identifies this specific server

Both secrets must match for commands to be delivered. This prevents:

• Unauthorized servers from receiving commands
• Commands leaking to wrong servers
• Replay attacks

Error Handling

Transient Failures

Network issues, temporary API unavailability, etc.:

• Plugin retries automatically
• Exponential backoff prevents overload
• Commands eventually deliver

Permanent Failures

Invalid credentials, deleted server, etc.:

• Logged with error details
• Check plugin logs for diagnostics
• May require configuration update

Command Execution Failures

Invalid command syntax, player not found, etc.:

• Reported to API as failed
• Visible in order details
• May need manual intervention

Best Practices

1. Test Commands First - Verify commands work in-game before adding to products
2. Use Meaningful Names - Name servers clearly in your dashboard
3. Monitor Logs - Check plugin logs regularly for issues
4. Handle Offline Players - Decide per-product whether to wait
5. Set Up Refund/Chargeback Commands - Protect against fraud

Troubleshooting

See our Troubleshooting Guide for common issues and solutions.