Kongregate Microtransaction Client API

The Microtransaction client API allows you to bring up the standard Kongregate checkout UI, enabling users to purchase virtual items in your game.

Setup

In order to use this API, 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:

You should also review the process of implementing the Kongregate APIs in general, as this documentation assumes that you have access to the Kongregate API object.

Once the API is loaded, you can access the microtransaction functions from the mtx object on the API, for example kongregate.mtx.purchaseItems, etc.

API Functions

Requesting Item Purchase

You may bring up the "purchase items" dialog box by using the purchaseItems method on the microtransaction services object. It takes either an array of item identifiers or an array of identifier/metadata objects, as well as a callback function which should be called with the result of the purchase, as shown below:

// Purchase item with no metadata:
kongregate.mtx.purchaseItems(["sword","shield"], onPurchaseResult );

// Purchase item with metadata:
var items:Array=[{identifier:"sword",data:"+1str"}];
kongregate.mtx.purchaseItems(items, onPurchaseResult);

// The purchase callback
function onPurchaseResult(result:Object){
  trace("Purchase success:" + result.success);
}

The second call shows how to attach a string of metadata to the item instance, which you can retrieve from the server later. It is important to note that the client can change this data using a browser plugin fairly easily, so it is a good idea to obfuscate this string, as well as verify its validity as it relates to your game.

Requesting User Item Instances

The inventory of any user can be requested by using the requestUserItemList method. This function takes a username string as the first argument, but you may pass in null or a blank string to request the inventory for the current user. The second argument is a callback function to call when retrieval is complete.

// Request the inventory for the current player
kongregate.mtx.requestUserItemList(null, onUserItems);

// The callback function
function onUserItems(result:Object):void{
  trace("User item list received, success: " + result.success);
  if( result.success ){
    for( var i:int = 0; i < result.data.length; i++ ){
      var item:Object = result.data[i];
      trace((i+1) + ". " + item.identifier + ", " + item.id + "," + item.data);
    }
  }
}

Displaying the Kred Purchase Dialog

You may bring up the "purchase kreds" dialog box by using the showKredPurchaseDialog method on the microtransaction services object. The only argument is the default purchase method you would like to display, which can be either "offers" to show the OfferPal Kred options, or "mobile" to show the mobile/Zong options. Any other value will simply show the default purchase dialog.

// Display a dialog informing users how to earn free Kreds.
kongregate.mtx.showKredPurchaseDialog("offers");

Handling Guest Users

Since guest users on Kongregate are not allowed to purchase items, you must decide how you want to handle them in your game. In general, whenever a guest user wants to purchase an item, it is a good idea to display a message letting them know they must sign in or register before they can purchase, and then display the registration lightbox. Further documentation on this process can be found here.