If you have a virtual currency on your server (such as coins or tokens) you can implement the ability for players to use this currency to purchase packages on your webstore. Virtual currency is available to Premium, Ultimate & Enterprise customers.

Our game currency integration works with two simple webhook requests - one to query a player's balance during checkout, and another to remove the spent coins from their balance after they have completed their purchase.

In order to protect a player's in-game currency and to ensure it's not being used by a different player fraudulently, the player must be logged in with a Tebex Account, and must also be using a verified game profile to purchase.

Checkout Flow

 

How To Setup Virtual Currency

This feature does not create a virtual currency for you - you need to have an existing virtual currency on your server and the ability to create webhooks that can manipulate your currency. If you have a developer who will be doing this work for you, we recommend sending them this article for help with configuring virtual currency on your webstore.

  1. Go to Integrations in your Tebex Store control panel.
  2. Go to Virtual Currency.
  3. Enter the following options:

Options

  1. Enable - We recommend leaving this option disabled until you are ready to go live and have created your query/update endpoints.
  2. Exchange Rate - All store purchases take place in a fiat (real) currency (your default store currency). The exchange rate defines how much of your virtual currency should equal 1 unit of your store currency. For example, if you want 10 coins to equal $1 (if your store is in USD), then you'd enter 10.
  3. Query URL - Enter the URL of the query endpoint you have created (See below for code examples).
  4. Update URL - Enter the URL of the update endpoint you have created (See below for code examples). 

 

Custom Templates

If you have a custom template then you will need to add {% include "virtualcurrency.html" %} to checkout.html just above the line that reads:

<form method="post" action="{% if basket.price > 0 %}/checkout/pay{% else %}/checkout/free{% endif %}" {% if basket.price > 0 %}class="gateway"{% endif %}>

 

Query Endpoint Example

When a customer selects that they'd like to checkout using their virtual currency we send a webhook request to your query endpoint with their username ID. This endpoint should return their current balance.

Example GET Request

http://example.com/tebex/balance.php?username=d8d5a9237b2043d8883b1150148d6955

Request Query Parameters

  1. username - The username ID of the user (Such as Minecraft UUID/Steam ID etc).

Request Headers

We send a X-BC-Sig header so that you can verify the request's legitimacy, it contains a SHA256 hash of the following concatenated together to make one string:

  1. Your webstore's shared secret key, this can be found by going to Integrations > API Keys in your Tebex Store control panel.
  2. The username value from the query string, in this example it will be d8d5a9237b2043d8883b1150148d6955.

 You can calculate this signature using the following example PHP code:

hash("sha256", $sharedSecret . $username);

Example JSON Response

{
  "balance": 1200
}

 

Update Endpoint Example

When a customer proceeds to checkout with their virtual currency we will send a POST request containing the username ID and the amount they have just spent from their balance. Your update endpoint will receive a JSON encoded POST request with the following parameters:

{
  "username": "d8d5a9237b2043d8883b1150148d6955",
  "amount": 100,
  "value": 10
}

Request JSON Body

  1. username - The username ID of the user (Such as Minecraft UUID/Steam ID)
  2. amount - The amount of virtual currency the customer has spent.
  3. value - The fiat currency value (e.g GBP/USD) the customer has spent.

Request Headers

We send a X-BC-Sig header so that you can verify the request's legitimacy, it contains a SHA256 hash of the following concatenated together to make one string:

  1. Your webstore's shared secret key, this can be found by going to Integrations > API Keys in your Tebex Store control panel.
  2. The username property from the body of the request.
  3. The value property from the body of the request.

 You can calculate this signature using the following example PHP code:

hash("sha256", $sharedSecret . $username . $value);

Did this answer your question?