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>

We will automatically update v/1.js with new minor and patch releases of Tebex.js. This shouldn't present any breaking changes, but if you would prefer to stay on a fixed version, you can specify the full version number in the URL, for example https://js.tebex.io/v/1.1.1.js. Our version history can be found on our GitHub releases page.

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

OptionDetailsDefault

ident

Required. This should be the checkout request ident received via the Headless API or Checkout API.

theme

Checkout color theme - either "light" or "dark".

"light"

colors

Checkout brand 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>

Events

Events are fired by Tebex.js upon specific actions to alert your frontend and enable you to take action when required. These events should not be used to confirm actual receipt of payment - you should use Webhooks instead.

To add an event callback, use Tebex.checkout.on() . The first argument to this function should be the name of the event to listen to, and the second argument should be a function to call when that function is fired:

Tebex.checkout.on("payment:complete", (event) => {
    console.log("Payment completed!", event);
});

Available events are as follows:

NameFired Upon

"open"

The checkout popup opening.

"close"

The checkout popup closing.

"payment:complete"

The customer has successfully completed their payment.

"payment:error"

The customer experienced an error, such as incorrect card details or insufficient funds, when making a payment.

Custom Render Location

If you don't wish to use a popup, you can choose to render the checkout to an element within your page. To do this, use Tebex.checkout.render() instead of Tebex.checkout.launch():

Tebex.checkout.init({
    ident: "your checkout request ident goes here",
});

Tebex.checkout.render(
    // The element to render to
    document.getElementById("some-element");
    // The width of the checkout iframe, in pixels
    500,
    // The height of the checkout iframe, in pixels
    600
    // Boolean indicating whether you want to open a new tab on mobile
    // (defaults to true if unspecified)
    false
);

Web Components

As an alternative to using the Tebex.checkout JavaScript API, Tebex.js also provides a tebex-checkout Web Component.

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:

Popup Mode

This is the default mode. The component will display nothing initially, but will launch the checkout as a popup when activated, akin to Tebex.checkout.launch().

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

By adding the inline attribute to the checkout element, the element will instead be rendered inline within the rest of the page, in a similar way to Tebex.checkout.render().

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

HTML attributes take the place of Tebex.checkout.init()'s config options, along with a couple of extra options:

AttributeDetails

ident

Required. This should be the checkout request ident received via the Headless API or Checkout API.

theme

Checkout color theme - either "light" or "dark".

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.

For example:

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

Events

All events that can be listened to with Tebex.checkout.on() are exposed on the element as custom DOM events, which means you can use addEventListener to subscribe to them:

<html>
    <body>
        <tebex-checkout id="checkout"></tebex-checkout>
    </body>
    <script>
        const checkout = document.getElementById("checkout);
        
        checkout.addEventListener("open", () => {
            console.log("checkout opened");
        });

        checkout.addEventListener("close", () => {
            console.log("checkout closed");
        });

        checkout.addEventListener("payment:complete", (event) => {
            console.log("payment completed", event);
        });

        checkout.addEventListener("payment:error", (event) => {
            console.log("payment errored", event);
        });
    </script>
</html>

Framework Integration

Web Components such as tebex-checkout integrate seamlessly with most modern frontend frameworks without needing any special setup. However, if you are using Vue, please note that you may need to adjust your config to skip component resolution for tebex-checkout.

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>
PreviousOverviewNextOverview

Last updated