Note: This feature is currently in closed beta, and it will not function unless your game is included in the beta program. If you feel you are a good test candidate for this feature then please let us know.

Overview

This document will give you an overview of how Kongregate's microtransaction service works, and how you can use it to sell virtual items in your game. It is aimed at developers who have their own back-end and can implement secure server-to-server transactions.

Kongregate players can purchase Kreds and use them for various things such as tipping game developers, buying Kongai cards, as well as purchasing virtual items in games. Adding virtual items to your game is a simple process, and is a great way to generate additional revenue for your game.

The Server API is used for querying Kongregate's servers about item information and player inventories, while the Client API enables you to bring up the standard shopping cart UI to enable the purchase of virtual items.

Setup

In order to use microtransactions, your game must have special permissions granted by an administrator. This will allow you to access the item management tools by adding /items to the end of your game URL, for example:

http://www.kongregate.com/games/BenV/mygame/items

Item Consumption

The first step for integrating Kongregate's microtransaction system is thinking of what you'd like to sell in your game. We have found that in general, selling in-game currency such as gold, credits, or points, works very well. Typically, developers will sell this currency in "packages" for a certain amount of Kreds, giving discounts for the larger packages. Your game can then check the player's inventory, consume the package, and award your own in-game currency to the player at that time. Once the package has been used/consumed on our end it will no longer show up when you request the player's inventory. The player can then use the awarded currency to purchase items in your game.

Kongregate supports this kind of transaction through what we call "limited-use" items. When you define your item, you can set the amount of times it can be "used" or "consumed" before it will be removed from the player's inventory. Typically you will want to set this value to 1, which means that after the item is used once it will be removed from the Kongregate database.

For example, say you have a game which sells items for gold. You might set an item which is a package of 500 gold. When the user purchases one of the packages, you make a server-to-server request to ask Kongregate what items the user has in their inventory. The server responds, saying that the user has a single "500 gold" item in their inventory. Your server should then "use" the item by issuing a web request to Kongregate, and if this is successful, the player should be awarded 500 gold in your game. If you were to immediately request the player's inventory again from Kongregate, it would be empty, since the item was successfully consumed.

We recommend this "consumption" approach due to its simplicity and flexibility. It reduces the amount of items you need to manage on Kongregate, since you will typically only have a few currency packages that you sell. It gives you the freedom to add new purchasable items to your game client without having to change something on our end. It also allows a greater level of abstraction if you happen to have the need to manage multiple microtransaction systems for your game.

Creating Your Items

In order to set up your items, you can simply add /items on to the end of your game URL (remove the _preview string first if there is one). This will take you to the item creation user interface. Using this interface you can add, modify, and tag items for your game. Once you set up an item, it will be available for use immediately.

Items have several pieces of data associated with them:

  • Identifier: The identifier string of the item. Users will not see this, but you can use it to store information about the item such as "gold-500"
  • Name: The visible name for the item, which the end user will see.
  • Description: The description of the item. This shows up in the shopping cart.
  • Price: The item price in Kreds
  • Uses: The number of times the item can be used before being removed from the player's inventory
  • Tags: You can give the item any number of tags.

Purchasing Items

You can use the Microtransaction Client API in order to bring up the standard shopping cart UI with one or more items. At this point, we will prompt the user to purchase Kreds if they don't have any. The client API allows you to register a callback when the checkout window is closed, at which point you can let your game server know the player's inventory needs to be checked.

Testing this functionality as a developer is easy - we make all purchases free (cost 0 kreds) automatically for developers playing their own games. You should not need to purchase any kreds from us to do any testing of your game.

Inventory Invalidation

When a user purchases an item, this invalidates their inventory. When this happens, your server needs to request their updated inventory from our back end. This can be done using the Microtransaction Web Services API. If the player's inventory has limited-use items in it, you need to iterate through the items and use each one. Upon each successful item consumption, the relevant item or currency should be awarded to the player by your game server.

We highly recommend you create a simple invalidateInventory function in your server logic which performs this procedure for a given user. This function should be called immediately after the user is authenticated, as well as whenever the user purchases an item. The game client can inform the server when a player's inventory needs to be checked after a purchase, or you can use a web service callback.

Implementation

To get started, continue on to read the Client API and Server API documentation.