Tebex Integration

AuroraMC uses the Tebex Headless API to handle all payment processing. This means the checkout happens directly through Tebex's secure payment page — no sensitive payment data ever touches your server.

How It Works

The checkout flow has three steps:

1. Customer adds items to cart
2. Customer enters Minecraft username and clicks "Checkout"
3. AuroraMC creates a Tebex basket, adds packages, and redirects to Tebex payment page

After payment completes, the customer is redirected back to your store:

• Successful payment → /success page
• Cancelled payment → /cancel page

Tebex handles the actual package delivery to your Minecraft server through its plugin system.

Setup

Step 1 — Enable the Headless API

1. Log in to your Tebex Dashboard
2. Go to Settings → API Keys
3. Under Headless API, click Enable
4. Copy the Public Token

Step 2 — Add Your Token

Paste the token into your .env file:

VITE_TEBEX_PUBLIC_TOKEN=your_public_token_here

[!IMPORTANT] Restart the dev server after changing .env — Vite only reads environment files on startup.

Step 3 — Map Products to Tebex Packages

Each product in your store needs to be linked to a Tebex Package ID. Edit config/products.config.ts:

export const productMapping: Record<string, number> = {
    'gold-1000': 1234567,
    'example-rank': 7654321,
};

The key is the product id from src/lib/store-data.ts. The value is the Tebex Package ID.

Finding Tebex Package IDs

1. In the Tebex dashboard, go to Packages
2. Click on any package
3. The URL will look like: https://creator.tebex.io/packages/1234567
4. The number at the end (1234567) is the Package ID

Checkout Flow (Technical)

The entire checkout is handled by src/lib/tebex.ts. Here's what happens when a customer clicks "Checkout":

1. Basket Creation

A new Tebex basket is created with the customer's Minecraft username:

POST https://headless.tebex.io/api/accounts/{token}/baskets
Body: { username, complete_url, cancel_url }

• complete_url is set to your site's /success page
• cancel_url is set to your site's homepage

2. Adding Packages

Each cart item is added to the basket one by one:

POST https://headless.tebex.io/api/baskets/{basketId}/packages
Body: { package_id, quantity }

The package_id comes from your mapping in products.config.ts.

3. Redirect to Payment

After all packages are added, the checkout URL is retrieved from the updated basket and the customer is redirected to Tebex's payment page.

Validation

AuroraMC includes a validateProductMapping() function in products.config.ts that checks for products with missing or zero-value Tebex IDs:

const { valid, missing } = validateProductMapping();
// valid: false if any products have no Tebex mapping
// missing: array of product IDs that aren't mapped

Use this during development to make sure all your products are properly connected before going live.

Common Issues

"Failed to create basket"

• Your VITE_TEBEX_PUBLIC_TOKEN is incorrect or expired
• The Headless API is not enabled in your Tebex dashboard
• Your Tebex webstore has been suspended

"Failed to add package"

• The Tebex Package ID in your mapping doesn't exist
• The package has been deleted or disabled in Tebex
• The Package ID doesn't match any package in your webstore

Checkout Redirects to Wrong Page

Check the complete_url and cancel_url in src/lib/tebex.ts. By default, these use window.location.origin to build the redirect URLs. If you're using a custom domain, make sure your site's origin is correct.