1 of 75

Developers

Welcome

Learn how to integrate Tebex and leave the complexities of monetization to us.

Getting Started

Get started integrating Tebex into your website or game

Welcome to your journey of launching your first project with Tebex! This guide will walk you through the essential steps to create, set up, and launch your store, ensuring a seamless experience for your customers. From building your first project in the creator panel to implementing automatic product delivery, we'll cover everything you need to know to get started.

Create a project

Setup your store or integrate our APIs

Create your packages

Implement product delivery

Make a test payment

Before going live, give everything a test run by going through the checkout process using the test payment method. Don’t worry, no real money needed here!

Submit for review

Ready to roll? Submit your project for review by our Content & Safety team. We’ll give it a quick check, and if everything looks good, you’ll be ready to launch within a day.

Go live

Integration Methods

Learn which integration method is best for you

Tebex offers multiple integration options tailored to meet different business needs, each equipped with unique features for specific use cases.

There are three integration methods available, as highlighted below. Each method varies in complexity, with the Webstore Builder being the easiest to get started with.

Checkout: Maximize revenue by utilizing Tebex’s global Merchant of Record platform. With over 100 payment methods, Tebex handles the entire checkout process, offering chargeback protection, fraud monitoring, 14-day payouts, and international sales tax coverage.

Package Management: Effortlessly set up and manage packages for sale on your project through the creator panel. You can organize packages into categories and easily define details such as names, descriptions, pricing, and images. You're also able to invite other team members to manage these too.

Hosted Webstore: Tebex provides a customizable webstore that allows you to start selling in minutes. This enables you to focus on your business, while we handle the hosting infrastructure & technical requirements for you.

Which integration method is best for me?

I want to sell packages that are dynamic in nature

I want to sell hundreds or thousands of packages through my own backend system

I want to sell physical goods or launch a marketplace

Tebex cannot support projects that aim to sell physical goods or provide marketplace services. If you are looking to pursue either of these options, we regret to inform you that we cannot collaborate in this capacity, and you will need to seek a payment partner elsewhere.

Let's begin!

Now that you've chosen your integration method, you can begin by exploring the relevant documentation:

SDKs

Tebex offers many different ways to integrate with your existing infrastructure.

Official SDKs

The SDKs below include support for Headless API, Checkout API, and Webhooks, complete with examples, making implementation of these APIs into your project as easy as possible.

OpenAPI Schema

Tebex APIs are documented using OpenAPI. These are used to generate our Endpoints documentation. Our schemas are available at the GitHub repositories below. The OpenAPI Generator can be used to generate an SDK in the language of your choice if we do not have your language available.

Other SDKs / Integration Options

Below are additional resources and projects that can help you implement Tebex into your project. If you've developed an SDK, please reach out to us at tebex-integrations@overwolf.com.

Tebex for Unreal Engine 5

If you're developing a game for UE5, Tebex makes monetization simple.

We've built an open-source SDK for Unreal Engine 5 that provides everything needed to quickly start integrating with Tebex:

C++ mappings for Headless API
C++ mappings for Plugin API
An example in-game Plugin

Tebex for Unity Engine

Tebex provides an example integration script for Unity games with a feature-complete implementation of Headless and Plugin API.

We provide our complete C# SDK used to develop our official plugins.

This repository serves as our full Tebex SDK for projects using C#. It is designed to be forked and modified for your particular requirements.

C# mappings for Headless API
C# mappings for Plugin API
An example in-game TebexCorePlugin which implements processing command deliverables on game servers.

GitHub Repositories:

Webstore Builder

Overview

Customise your store to match your games brand using our Webstore Builder.

The Webstore Builder enables you to fully customise the design of your store using templates & themes, providing your customers with a seamless transition from your existing website when they're making a purchase.

With the webstore builder, you can:

Examples

Browse examples of other Tebex stores for some inspiration.

Certified Tebex Designers

Feedback

Getting Started

The best way to understand the functionality of the Tebex templating engine is to create a copy of our default template, named Exo.

You can do this by navigating to Webstore -> Appearance in your control panel and creating a custom template based on Exo.

Twig

Discover the power of the Twig templating engine used by Tebex.

A common Twig file may look like the following:

<!DOCTYPE html>
<html>
    <head>
        <title>My Webpage</title>
    </head>
    <body>
        <ul id="navigation">
        {% for item in navigation %}
            <li><a href="{{ item.href }}">{{ item.caption }}</a></li>
        {% endfor %}
        </ul>

        <h1>My Webpage</h1>
        {{ a_variable }}
    </body>
</html>

Filters

Modify variable values with Twig filters.

Filters enable you to modify the content of variables within your template.

Available Filters

Filter

Documentation

escape

length

raw

money

slice

number_format

date

nl2br

replace

split

upper

lower

Filter Documentation

`money`

The money filter transforms a variable into a monetary format.

{% set value = 1 %}

{{ value|money }} // returns 1.00

Functions

View the available functions within your Twig template.

Functions generate content for you to use within your templates.

Available Functions

Function

Documentation

__

_p

config

asset

path

query

range

Function Documentation

`__`

Returns the equivalent translation from within your translations settings.

{{ __('Redeem coupons / gift cards') }}

// prints "Redeems coupons / gift cards" (Or the equivalent translation if another language is selected)

`_p`

Returns the plural translation from within your translation settings.

{{ _p(":count items for :amount :currency", basket.packages|length, {'count' : basket.packages|length, 'amount' : basket.price|money, 'currency' : basket.currency}) }}

// prints "5 items for $5.00 USD"

`config`

{{ config("header-colour") }}

// prints the associated config value with the key header-colour

`asset`

Returns the full url path of an asset from within your template.

{{ asset("style.css") }}

// Prints the URL of style.css, such as https://your-store.tebex.io/template-assets/style.css"

`path`

Returns the full url path of the current page.

{{ path() }}

// Prints the full URL of the current page the customer is browsing on your store

`query`

Returns a GET parameter from the current url.

{{ query("test" }}

// Returns the GET param of "test" if it is provided in the URL.

Global Variables

Accessing global variables to help populate your template with live data.

Global variables are variables which are available across all pages of your store.

store

The global store object contains all information associated with the project itself, such as store name.

Variables

Type

Description

name

string

The name of the project.

currency

string

The base currency of the project.

css

string

The custom theme currently active on the project.

logo

string

The full url of the custom logo of the project.

favicon

string

The full url of the custom favicon of the project.

noLogin

Boolean

If the project requires no login (e.g. if no username system is being used).

categories

array[category]

An array of package categories of the project.

Request Variable

Pages

The entry point for each page on your store.

The only pages that are not accessible to the public are the following:

index.html

The index.html page is the homepage of your store.

Root Object

Variables

Type

Description

description

string

The homepage content of the store.

Request Variable

checkout.html

Receive an ident for Tebex.js

GET /checkout/ident

Response

{
    "ident":"null if customer is not logged in"
}

Using Tebex.js

username.html

The username.html page is responsible for allowing your customers login to your store.

Root Object

Variables

Type

Description

external

Boolean

provider

String

The name of the login provider, such as FiveM, Discord or Steam.

url

String

The URL that the customer should be directed to so they can perform their login with the external provider.

If the external variable is true, let the user click a link to proceed to login via the external login provider:

<p>Please login with your {{ provider }} account to continue.</p>
<a href="{{ url }}">Login</a>

If the external variable is false, provide a form submitting to the current url, including an ign form parameter. The ign parameter should be a text field allowing the customer to enter their username freehand.

An example can be seen below:

<form method="post">
    <input type="text" name="ign" placeholder="Enter your in-game username" />
    <button type="submit">Login</button>
</form>

Full Working Example

An example of a flow supporting both external and non-external login providers is shown below:

{% if external %}
    <a href="{{ url }}">Login via {{ provider }}</a>
{% else %}
    <form method="post">
        <input
            type="text"
            name="ign"
            placeholder="Enter your in-game username"
        />
        <button type="submit">Login</button>
    </form>
{% endif %}

Request Variable

options.html

Root Object

Variables

Type

Description

options.package

An object containing information about the current package.

options.variables

Package Object

Variable

Type

Description

name

string

The name of the package.

chooseServer

boolean

customPrice

boolean

If the package requires the customer to enter how much they want to pay for the package.

category

string

The category ID of the package.

price

string

The price of the package.

Variable Object

Variable

Type

Description

description

string

A summary of the description of the variable.

type

string

Either dropdown, discord_id, or show an input field for freehand input by the customer.

id

string

The ID of the variable.

options

If the type is dropdown, we include an array of options the customer should select from.

value

string

The current value of the variable.

discord_tag

string

If the variable is type is discord_id and the value is not empty, this will include their discord tag once they have logged in.

Variable Option Object

Variable

Type

Description

default

boolean

If this variable option should be selected by default.

name

string

The name of the dropdown option.

price

string

The additional price the customer would pay by selecting this variable option.

Request Variable

package.html

Root Object

Request Variable

cms/page.html

Root Object

Request Variable

module.communitygoal.html

Request Variable

module.featuredpackage.html

The featured package module allows you to feature a package, bringing more attention to it on your store.

Request Variable

Headless API

Checkout API

Tebex.js

Webhooks

Game Server API

Affiliate API

Web Components

With this, you can embed a Tebex Checkout into your page by placing the <tebex-checkout></tebex-checkout> HTML tag anywhere in your page's <body>, so long as Tebex.js is also loaded into the page:

<html>
    <head>
        <script defer src="https://js.tebex.io/v/1.js"></script>
    </head>
    <body>
        <tebex-checkout></tebex-checkout>
    </body>
</html>

Due to Web Component quirks, you must include both opening and closing HTML tags (like <tebex-checkout></tebex-checkout>). Using a self-closing tag (<tebex-checkout/>) is not valid.

Modes

Two modes are available for tebex-checkout:

The simplest way to achieve this is by placing a button inside the <tebex-checkout> and </tebex-checkout> tags. Tebex.js will automatically attach handlers so that clicking the button will launch the checkout:

<tebex-checkout ident="...">
    <button>Open Checkout</button>
</tebex-checkout>

You don't have to use a button here, it could be any HTML - styled however you see fit - as long as it's clickable!

Alternatively, if you would prefer to open the checkout from your code (i.e. instead of having a user click something), you can leave the tebex-checkout empty and add the open attribute to it whenever you are ready for it to launch:

<script>
    function openCheckout() {
        const checkout = document.getElementById("checkout");
        checkout.setAttribute("open", "true");
    }
    // call openCheckout() when you want the checkout to launch...
</script>

<tebex-checkout id="checkout" ident="..."></tebex-checkout>

Inline Mode

It will automatically take up 100% of the width of its container and set its height to a sane default for displaying the iframe checkout content, but you can use the height attribute to manually set the height, in CSS pixels:

<tebex-checkout inline ident="..." height="800"></tebex-checkout>

Common Attributes

Attribute

Details

ident

locale

Default language for checkout text. Specified as an ISO locale code, e.g. "en_US" for American English, "de_DE" for German, etc. Users can change the language from within the checkout panel UI.

theme

Checkout color theme. Must be one of the following options:

"light"
"dark"
"auto" - applies the theme based on the user's light/dark mode system preference.
"default" - applies the theme option you have selected in your store's settings.

color-primary

Checkout primary brand color.

color-secondary

Checkout secondary brand color.

popup-on-mobile

If set, when in popup mode, the checkout will always launch in the current browser window rather than opening a new page, even on mobile devices.

redirect-on-complete

If set to a URL, the user will be redirected to this page once the payment has completed.

For example:

<tebex-checkout theme="dark" color-primary="#ff0000"></tebex-checkout>

Framework Integration

Example

In Vue, this is how you could include an inline tebex-checkout component and call a function when the payment complete event fires:

<script setup>
   import "@tebexio/tebex.js";

    const ident = ref("");

    // something to fetch the ident here
    
    function onPaymentComplete() {
        console.log("payment completed");
    }
</script>

<template>
    <tebex-checkout inline :ident="ident" @payment:complete="onPaymentComplete"></tebex-checkout>
</template>

Integration

Tebex.js enables you to integrate a seamless checkout experience for customers without them leaving your website or game.

Installation

From NPM

Tebex.js is available as an NPM package, which you can install using your preferred JS package manager:

npm install @tebexio/tebex.js

The Tebex object can then be imported into your code like so:

import Tebex from "@tebexio/tebex.js";

From Our CDN

Alternatively, we also provide Tebex.js via our own CDN, which you can add as a script within the <head> tag of your website:

<script defer src="https://js.tebex.io/v/1.js"></script>

When installing Tebex.js this way, the Tebex object will become available globally on the window object.

We recommend using defer on the script to prevent it from blocking your website's initial page render, but when doing do, it's important to wait for the page load event before you begin configuring the checkout:

<script>
    addEventListener("load", function() {
        // Configure Tebex.js here
    });
</script>

Config

Before your checkout can be launched, it must first be configured by calling the Tebex.checkout.init() method. This method takes an object containing config options:

Tebex.checkout.init({
    ident: "checkout request ident"
});

Options

Option

Details

Default

ident

locale

Default language for checkout text. Specified as an ISO locale code, e.g. "en_US" for American English, "de_DE" for German, etc. Users can change the language from within the checkout panel UI.

English

theme

Checkout color theme. Must be one of the following options:

"light"
"dark"
"auto" - applies the theme based on the user's light/dark mode system preference.
"default" - applies the theme option you have selected in your store's settings.

"default"

colors

[]

You're able to retrieve the checkout request ident by using the {{ basket.ident }} global Twig variable if you are using a Tebex hosted webstore.

Brand Color Config

Brand colors can be specified as an array of objects with name and color keys. name must be either "primary" or "secondary", while color must be a valid CSS color:


Tebex.checkout.init({
    //..
    colors: [
        {
            name: "primary",
            color: "#910f0f",
        },
        {
            name: "secondary",
            color: "#25c235"
        }
    ]
});

Launch

When you are ready to show the Tebex.js checkout to your user, you can call the Tebex.checkout.launch() method. On desktop devices this will open the checkout as a popup, while on mobile devices it will open as a new tab.

If you are only calling the Tebex.checkout.launch() inside a click event, you might prefer to also call Tebex.checkout.init()inside your click handler.

This way, you don't need to wait for the page load event to fire to configure your checkout:

<!-- Include the Tebex.js script here -->
<script>
  function checkout() {
    Tebex.checkout.init({
      ident: "your checkout request ident goes here"
    };
    Tebex.checkout.launch();
  }
</script>
<!-- ... -->
<button onclick="checkout()">Checkout</button>

Overview

Receive real time notifications of payments, subscriptions, and much more.

Webhooks enable you to receive notifications upon certain webstore events, for example when a new payment is made. We will send a HTTP request containing a JSON object to any configured endpoints that are subscribing to the respective event. Webhooks are a great way to integrate Tebex with your own website, forum or internal database.

How To Setup Webhooks Endpoints

Go to Developers > Webhooks > Endpoints.
Click Add Endpoint.
Enter the URL of your webhook endpoint.
Select the types of webhooks that you'd like to subscribe to.
Click Add.

After adding your endpoint, you will receive a warning to inform you that we haven't been able to validate endpoint. Please see the section below for further information about handling validation webhooks.

Handling Validation Webhooks

Webhooks will not be sent to an endpoint unless it has been validated first. This is to ensure we are not sending HTTP requests to URLs that are not expecting our webhooks.

The validation webhook that we send will look similar to the example below. To identify a validation webhook you can check the type property in the JSON body.

Upon receiving a validation webhook you must respond with a 200 OK response containing a JSON object that has an id property representing the validation webhook's ID, please see the example response below.

Once your endpoint is setup to successfully handle validation webhooks, please visit Developers > Webhooks > Endpoints and click the Validate button next to the endpoint to re-send the validation webhook.

Verifying Webhook Authenticity

IP Address

Webhooks from Tebex will only ever be sent from the two IP addresses listed below.

18.209.80.3 54.87.231.232

When building your webhook endpoint, we suggest that you check the IP address of the sender and throw a 404 Not Found error if the IP address isn't in the above list.

Signature

In addition to checking the IP address, we strongly advise that you verify the X-Signature header that we send with all requests.

The signature is generated by SHA256 hashing the JSON body and then building a SHA256 HMAC with the body hash as the data/content and your webhook secret as the key.

Your webhook secret is displayed on the Developers > Webhooks > Endpoints page. Please see our example code snippets below of how to generate the signature.

If the signature that you generate doesn't match the X-Signature header, please disregard the webhook because it is not from Tebex.

Some frameworks such as Express (Node.js) automatically parse JSON request bodies which can result in a signature mismatch. Please ensure the signature is calculated using the raw request body and not a parsed version of the body.

Handling Webhooks

All of our webhooks are sent using the standardised format with the following properties:

When handling a webhook, please ensure you respond with a 2XX status code (anywhere between 200-299). If your endpoint responds with any other status code we will automatically try to resend the webhook later-on.

After several attempts of retrying we will mark the webhook as failed and your endpoint may require validating again.

Webhook Types

payment.completed Sent when a payment is completed.
payment.declined Sent when a payment is declined.
payment.refunded Sent when a payment is refunded.
payment.dispute.opened Sent when a dispute is opened against a payment.
payment.dispute.won Sent when a dispute against a payment is won.
payment.dispute.lost Sent when a dispute against a payment is lost.
payment.dispute.closed Sent when a dispute against a payment is closed.
recurring-payment.started Sent when a recurring payment starts.
recurring-payment.renewed Sent when a recurring payment renews.
recurring-payment.ended Sent when a recurring payment ends and the purchased products should be revoked from the customer.
recurring-payment.cancellation.requested Sent when a customer requests to cancel a recurring payment. The cancellation will take place at the end of the current billing period (i.e. when renewal would typically occur) and a recurring-payment.ended webhook will be sent.
recurring-payment.cancellation.aborted Sent when a customer aborts the outstanding cancellation request. The recurring payment will renew as normal.
validation.webhook Sent when initially adding a new webhook endpoint.

Webhook Subjects

Useful Status IDs

Decline Reasons

Useful Status IDs

Testing Webhooks

Our webhook testing feature allows you to manually trigger webhooks from your control panel. Please follow the steps below to send a test webhook.

Navigate to Developers > Webhooks in your control panel.
Click the Send Test button.
Choose the type of webhook you'd like to send.
Provide a valid transaction ID if you've selected a payment webhook type, or enter a recurring payment reference if you've chosen a recurring payment webhook type.
Click the Send Test button.

Referrals

Create Referral

POST https://affiliate.tebex.io/api/referrals

This endpoint should be called when your customer requests that they want to install Tebex on their game server. It will send an email to the customer containing a link which allows them to setup their webstore and ensure your affiliate account is associated with the customer.

Headers

Name

Type

Description

Authorization

string

Bearer <Your API Key>

Request Body

Name

Type

Description

link

string

The UUID of your referral link within your affiliate panel. You can find this on https://affiliate.tebex.io/links, under your Link name.

reference

string

A unique ID that references the customer's game server within your management panel. You will use this to identify the game server when we send the installation webhook.

game_type_id

number

The ID of the game type found within the game types endpoint.

server_name

string

The name of your customer's game server.

string

The email address of the customer.

last_name

string

The last name of the customer.

first_name

string

The first name of the customer.

{
  "data": {
    "reference": "123456",
    "secret": null,
    "game_type": {
      "id": 1
    },
    "setup_at": null
  }
}

Get Referral

GET https://affiliate.tebex.io/api/referrals/:reference

Retrieve an existing referral. This method is useful for checking if a customer has created their webstore and can also be used to retrieve the plugin urls and locations of the premade config files.

Path Parameters

Name

Type

Description

reference

string

The reference provided when you created the referral.

Headers

Name

Type

Description

Authorization

string

Bearer <Your API Key>

{
  "data": {
    "reference": "123456",
    "secret": "9a6747fc6259aa374ab4e1bb03074b6ec672cf99",
    "game_type": {
      "id": 1,
      "plugins": {
        "bukkit": {
          "platform": "bukkit",
          "version": "10.2",
          "url": "https://d2vpaemuugs53a.cloudfront.net/latest/10.2/bukkit/BuycraftX.jar",
          "config": "http://affiliate.tebex.io/api/referrals/123456/config/bukkit"
        },
        "sponge": {
          "platform": "sponge",
          "version": "10.2",
          "url": "https://d2vpaemuugs53a.cloudfront.net/latest/10.2/sponge/BuycraftX.jar",
          "config": "http://affiliate.tebex.io/api/referrals/123456/config/sponge"
        },
        "bungeecord": {
          "platform": "bungeecord",
          "version": "10.2",
          "url": "https://d2vpaemuugs53a.cloudfront.net/latest/10.2/bungeecord/BuycraftX.jar",
          "config": "http://affiliate.tebex.io/api/referrals/123456/config/bungeecord"
        },
        "forge": {
          "platform": "forge",
          "version": "12.0.1",
          "url": "https://d2vpaemuugs53a.cloudfront.net/latest/minecraft-java/12.0.1/forge/BuycraftX.jar",
          "config": "http://affiliate.tebex.io/api/referrals/123456/config/forge"
        }
      }
    },
    "setup_at": "2020-11-17T09:41:57+00:00"
  }
}

Get Referral Config File

GET https://affiliate.tebex.io/api/referrals/:reference/config/:platform

Retrieve the premade config file for a specific platform (such as Minecraft Spigot or Forge). The config file will include the customer's secret key, removing any need of manual setup of the Tebex plugin on the server's behalf.

Path Parameters

Name

Type

Description

platform

string

The plugin platform such as bukkit or forge.

reference

string

The reference provided when you created the referral.

Headers

Name

Type

Description

Authorization

string

Bearer <Your API Key>

#BuycraftX configuration file
push-commands=true
server-key=a8ba0940f9deb37b79d66fa19f8b36ba5df14fa2
verbose=false
disable-buy-command=false
check-for-updates=true
buy-command-name=buy
is-bungeecord=false
language=en-GB

Developers

Welcome

Getting Started

Create a project

Setup your store or integrate our APIs

Create your packages

Implement product delivery

Make a test payment

Submit for review

Go live

Integration Methods

Which integration method is best for me?

Let's begin!

SDKs

Official SDKs

OpenAPI Schema

Other SDKs / Integration Options

Tebex for Unreal Engine 5

Tebex for Unity Engine

Webstore Builder

Overview

Examples

Certified Tebex Designers

Feedback

Getting Started

Getting Started

Twig

Filters

Available Filters

Filter Documentation

money

Functions

Available Functions

Function Documentation

__

_p

config

asset

path

query

Global Variables

store

Request Variable

page

Request Variable

Pages

index.html

Root Object

Request Variable

checkout.html

Receive an ident for Tebex.js

Using Tebex.js

username.html

Root Object

External Login

Non-External Login

Full Working Example

Request Variable

options.html

Root Object

Package Object

Variable Object

Variable Option Object

Request Variable

package.html

Root Object

Request Variable

cms/page.html

Root Object

Request Variable

module.communitygoal.html

Request Variable

module.featuredpackage.html

Request Variable

Headless API

Checkout API

Tebex.js

Webhooks

Game Server API

Affiliate API

`money`

`__`

`_p`

`config`

`asset`

`path`

`query`

`money`

`__`

`_p`

`config`

`asset`

`path`

`query`