Kongregate Developers

Dynamic Item Orders API

The Dynamic Item Order API allows users to purchase virtual items in your game using Kongregate's kreds currency. The API includes both client and server-side components. This API differs from the standard virtual goods API in the fact that you do not have to pre-define your items. Instead, our servers will contact yours to request item definitions. This flow is very similar to the Facebook Credits API.

Here is a very basic summary of how the API works. We will go into more detail about each part later on.

Setup

In order to use this API, your game must have the an API callback URL set. If you haven't done this already you can do so by editing your game:

http://www.kongregate.com/games/YourName/YourGame/edit

We will cover the specific calls that will be made to that endpoint later.

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

Requesting a Purchase

You may bring up the "purchase items" dialog box by using the purchaseItemsRemote method on the microtransaction services object. The dialog box will call back to your servers to request item definitions for the order_info string that you pass into this function.

Handling the item_order_request callback

This callback will be issued as a signed request to your API callback URL when an order needs to be defined. The request will have the following parameters once decoded/verified:

Here is an example of the decoded JSON parameters received for an item_order_request with the order_info set to 'sword':

{
  "event":"item_order_request",
  "game_id":10000,
  "buyer_id":765,
  "recipient_id":765,
  "order_id":12345,
  "order_info":"sword"
}

Your callback should render a JSON object with a single element items which is an array of item definitions. Each item needs to have the following elements, all of which are required and cannot be blank.

Here is an example valid JSON response for the above callback:

{
  "items":
  [
    {
      "name":"Awesome Sword",
      "description":"A really neat sword!",
      "price":10,
      "image_url":"http://www.swordssource.com/userfiles/image/Fantasy%20sword1.jpg"
    }
  ]
}

Once you deliver this JSON payload back to our servers, the shopping cart will be displayed to the user and they can confirm the purchase.

Handling the item_order_placed callback

This callback will be issued as a signed request to your API callback URL when a user has confirmed an order. The request will have the following parameters once decoded/verified:

Here is an example of the decoded JSON parameters received for an item_order_placed with the order_info set to 'sword':

{
  "event":"item_order_placed",
  "game_id":10000,
  "buyer_id":765,
  "recipient_id":765,
  "order_id":12345,
  "order_info":"sword"
}

At this point you should render a JSON response object with a single attribute state. You may either set state to completed or canceled. If you cancel the order the user's Kreds will be refunded and they will be notified via private message. If you wish to complete the order, you should render the completed status and award the user their virtual items at this point. Here is an example of a valid completed JSON response:

{"state":"completed"}

Example

An basic PHP example can be found here. It demonstrates how to decode/verify the signed request and handle the various required callbacks for this flow.

Comments