Billing Setup

BadgerPanel includes a full-featured billing system for monetizing your game server hosting. This guide covers setting up payment gateways, creating products, configuring coupons, and managing the billing lifecycle.

Enable Billing First

The billing system is disabled by default. Enable it in Admin > Settings > Feature Flags or set BILLING_ENABLED=true in your .env file and restart the API.

Payment Gateways

Stripe Setup

Stripe is the recommended payment gateway for BadgerPanel. It supports credit/debit cards, saved payment methods, and automatic recurring billing.

1. Create a Stripe Account

Sign up at stripe.com and complete the onboarding process to activate live payments.

2. Get Your API Keys

1. Go to the Stripe Dashboard
2. Navigate to Developers > API keys
3. Copy your Publishable key (pk_live_...) and Secret key (sk_live_...)

Test vs Live Keys

Stripe provides test keys (pk_test_..., sk_test_...) for development. Test keys simulate payments without processing real charges. Always use test keys during setup and switch to live keys for production.

3. Configure Stripe Webhook

Stripe webhooks notify BadgerPanel about payment events (successful charges, refunds, disputes).

1. In the Stripe Dashboard, go to Developers > Webhooks
2. Click Add endpoint
3. Set the endpoint URL to:

https://panel.your-domain.com/api/v1/billing/webhooks/stripe

4. Select these events:

   • payment_intent.succeeded
   • payment_intent.payment_failed
   • charge.refunded
   • charge.dispute.created
   • customer.subscription.updated
   • customer.subscription.deleted
   • invoice.payment_succeeded
   • invoice.payment_failed

5. Copy the Webhook signing secret (whsec_...)

4. Set Environment Variables

STRIPE_ENABLED=true
STRIPE_SECRET_KEY=sk_live_your-stripe-secret-key
STRIPE_PUBLISHABLE_KEY=pk_live_your-stripe-publishable-key
STRIPE_WEBHOOK_SECRET=whsec_your-stripe-webhook-secret

Restart the API:

docker compose restart api

5. Verify Stripe Integration

1. Go to Admin > Settings > Billing in the panel
2. You should see Stripe listed as an active gateway
3. Make a test purchase (use Stripe test mode first)

PayPal Setup

PayPal provides an alternative payment method for customers who prefer it.

1. Create a PayPal Business Account

Sign up at developer.paypal.com.

2. Create an App

1. Go to the PayPal Developer Dashboard
2. Click Create App
3. Name it (e.g., "BadgerPanel")
4. Copy the Client ID and Secret

3. Set Environment Variables

PAYPAL_ENABLED=true
PAYPAL_CLIENT_ID=your-paypal-client-id
PAYPAL_CLIENT_SECRET=your-paypal-client-secret
PAYPAL_MODE=sandbox  # Change to "live" for production

Restart the API:

docker compose restart api

Sandbox Testing

Use PAYPAL_MODE=sandbox with sandbox credentials to test payments without real charges. Create sandbox buyer accounts in the PayPal Developer Dashboard under Sandbox > Accounts.

Account Credits

Account credits let users pre-load a balance and pay for services from their credit balance.

Credits are enabled automatically when at least one payment gateway (Stripe or PayPal) is configured. Users can:

• Purchase credits via Stripe or PayPal
• Apply credits at checkout (alone or combined with a payment method)
• View their credit balance and transaction history

Admins can:

• Add or remove credits from any user account with a note
• View all credit transactions in the admin area

WHMCS Integration

If you already use WHMCS for billing, BadgerPanel can synchronize with it bidirectionally.

Configuration

WHMCS_ENABLED=true
WHMCS_URL=https://billing.your-domain.com
WHMCS_API_IDENTIFIER=your-whmcs-api-identifier
WHMCS_API_SECRET=your-whmcs-api-secret

Setting Up the WHMCS API

1. Log into your WHMCS admin area
2. Go to Setup > Staff Management > Manage API Credentials
3. Click Generate New API Credential
4. Copy the Identifier and Secret

Sync Capabilities

Data	Direction	Description
Clients	WHMCS -> Panel	Import WHMCS customers as panel users
Products	Bidirectional	Sync product definitions and pricing
Orders	Panel -> WHMCS	Orders placed in the panel create WHMCS orders
Invoices	Bidirectional	Invoice status synced between systems
Services	Panel -> WHMCS	Service status changes reflected in WHMCS

Sync Configuration

In Admin > Settings > WHMCS Integration, configure:

• Sync interval -- How often to sync (default: every 15 minutes)
• Auto-import clients -- Automatically create panel accounts for WHMCS clients
• Product mapping -- Map panel products to WHMCS products

Initial Sync

The first sync may take several minutes if you have many existing WHMCS customers and services. Monitor the sync logs in Admin > WHMCS > Sync Logs for errors.

Creating Products

Products define what customers can purchase. Each product specifies the game server resources, pricing, and billing cycles.

Step 1: Create Product Categories

Categories organize your storefront:

1. Navigate to Admin > Billing > Categories
2. Click Create Category
3. Enter a name (e.g., "Minecraft Hosting", "Rust Servers")
4. Optionally add a description and sort order
5. Save

Step 2: Create a Product

1. Navigate to Admin > Billing > Products
2. Click Create Product
3. Fill in the product details:

Basic Information:

Field	Description	Example
Name	Product display name	Minecraft Starter
Category	Product category	Minecraft Hosting
Description	Short description	Perfect for small communities
Features	Marketing bullet points	2 GB RAM, 10 GB SSD, 3 Backups

Server Resources:

Field	Description	Example
Nest	Game category	Minecraft
Egg	Server template	Paper
Node / Cluster	Where to deploy	US-East-1
Memory (MB)	RAM allocation	2048
CPU (%)	CPU allocation	200
Disk (MB)	Storage allocation	10240
Swap (MB)	Swap memory	0
I/O	Disk I/O weight	500
Databases	Number of databases	2
Backups	Number of backup slots	3
Allocations	Number of ports	1

Pricing:

Cycle	Price	Setup Fee
Monthly	$5.00	$0.00
Quarterly	$13.50	$0.00
Semi-Annual	$25.00	$0.00
Annual	$48.00	$0.00

Pricing Strategy

Offer discounts for longer billing cycles to encourage annual subscriptions. A common pattern is 10% off for quarterly, 15% off for semi-annual, and 20% off for annual.

Stock & Limits:

Field	Description	Example
Stock	Available quantity (0 = unlimited)	50
Per-user Limit	Max purchases per user (0 = unlimited)	3

4. Click Create Product

Step 3: Configure Multiple Plans

Create tiered products for different customer needs:

Plan	Memory	CPU	Disk	Monthly Price
Starter	2 GB	200%	10 GB	$5
Standard	4 GB	300%	25 GB	$10
Premium	8 GB	400%	50 GB	$20
Enterprise	16 GB	600%	100 GB	$40

Coupons & Discounts

Creating a Coupon

1. Navigate to Admin > Billing > Coupons
2. Click Create Coupon
3. Configure the coupon:

Field	Description	Example
Code	Coupon code customers enter	WELCOME20
Type	Discount type	Percentage or Fixed Amount
Value	Discount value	20 (20% or $20 depending on type)
Max Uses	Total redemptions allowed (0 = unlimited)	100
Max Uses Per User	Per-customer limit	1
Expires At	Expiration date	2025-12-31
Products	Apply to specific products or all	All products
Free Setup	Waive setup fees	Yes/No

Coupon Types

Type	Description	Example
Percentage	Percentage off the order total	20% off = $10 -> $8
Fixed Amount	Fixed dollar amount off	$5 off = $10 -> $5
Free Setup	Waives setup fees only	Setup fee $0 instead of $10

Marketing Campaigns

Create campaign-specific coupons (e.g., SUMMER2025, LAUNCH50) with usage limits and expiration dates. Track redemption statistics in the coupon detail page.

Order Workflow

When a customer completes a purchase:

1. Customer adds product(s) to cart
2. Selects billing cycle per item
3. Applies coupon code (optional)
4. Proceeds to checkout
5. Selects payment method (Stripe, PayPal, or credits)
6. Payment processed
   |
   +-- Success:
   |     - Order status -> "Completed"
   |     - Service created -> "Active"
   |     - Server provisioned automatically on the configured node
   |     - Invoice generated and emailed
   |
   +-- Failure:
         - Order status -> "Failed"
         - No service or server created
         - Customer notified of failure

Service Lifecycle

After a successful purchase, a Service is created representing the active subscription:

State	Description	Server Status
Active	Subscription is current and paid	Running
Suspended	Overdue payment or admin action	Stopped, data preserved
Cancelled	Customer requested cancellation	Runs until end of billing period
Terminated	Permanently deactivated	Deleted

Automatic Suspension & Termination

Configure automatic actions for overdue invoices:

• Days until suspension -- How many days after a missed payment before the service is suspended (e.g., 3 days)
• Days until termination -- How many days after suspension before the service is terminated (e.g., 14 days)

Configure these in Admin > Settings > Billing.

Termination Is Permanent

When a service is terminated, the game server and its data are deleted. Ensure your suspension window gives customers adequate time to pay overdue invoices.

Invoice Management

Automatic Invoices

Invoices are generated automatically for:

• New orders
• Subscription renewals (generated before the due date)
• Upgrade/downgrade prorations

Manual Invoices

Admins can create manual invoices:

1. Navigate to Admin > Billing > Invoices
2. Click Create Invoice
3. Select the customer and add line items
4. Set the due date and send

Invoice Emails

Invoices are emailed to customers automatically when generated. Ensure your email configuration is set up correctly.

Tax Configuration

Taxes can be configured in Admin > Settings > Billing:

• Set a default tax rate (percentage)
• Tax is applied to invoice line items
• Tax amount is shown separately on invoices

Next Steps

• Configuration -- Environment variables for billing
• Getting Started -- Panel deployment
• MySQL Setup -- Database hosts for game servers