Dynamic Purchasing

Dynamic Purchasing API

🚧
Approval required
If you are selling in-app purchases you will need to submit your game to [email protected] for QA testing and approval prior to publishing the game. You will be able to test the API before this, it only prevents launching without approval.

❗️
Edge case: already live games
If your game is already live and you now want to add in-app purchases you will need to contact us before you are able to test out the API functionality.

The Dynamic Purchasing API allows users to purchase virtual items in your game. 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.

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

You make a client API call to initiate a dynamic purchase and pass in an order_info string.
purchaseItemsRemote for web games
KongregateIAP_PurchaseDynamicItem for Kartridge games
We create an ItemOrder in our database with an id and your order_info string.
Our servers call back to yours to request item definitions for the given ItemOrder
The information received from your servers (name, description, icon, price) are displayed to the user in the shopping cart.
Once the user confirms the purchase, we call back to your servers once again.
Your servers award the user their virtual goods.

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 web game: https://www.kongregate.com/games/YourName/YourGame/edit or setting it in the Manage In-App-Purchases section of the Kartridge publishing flow.

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

Once the client API is loaded, you can access the virtual goods functions from the mtx object on the web API or the KongregateIAP prefix for the Kartridge API, for example kongregate.mtx.purchaseItemsRemote, KongregateIAP_PurchaseDynamicItem etc.

Requesting a Purchase

You may bring up the "purchase items" dialog box by using the purchaseItemsRemote method on the mtx API object for web or the KongregateIAP_PurchaseDynamicItem method for Kartridge. 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:

event - item_order_request.
game_id - The game_id.
buyer_id - The id of the user making the purchase.
recipient_id - The id of the user to receive the items.
order_id - A unique order id for this order in our database.
order_info - The order info string you passed into purchaseItemsRemote.

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.

name - The name of the item.
description - The description of the item (255 character max).
price - The price of the item in Kreds for web (integer) or USD for Kartridge (floating point)
image_url - A URL to an icon of the item. This icon will be rendered at 40x40 pixels.

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

{
  "items":
  [
    {
      "name":"Awesome Sword",
      "description":"A really neat sword!",
      "price":10,
      "image_url":"https://media.giphy.com/media/3o85xFGXZQIC29z74Q/giphy.gif"
    }
  ]
}

Once you deliver this JSON payload back to our servers, the items 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:

event - item_order_placed
game_id - The game_id.
buyer_id - The id of the user making the purchase.
recipient_id - The id of the user to receive the items.
order_id - A unique order id for this order in our database.
order_info - The order info string you passed into purchaseItemsRemote

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.

Dynamic Purchasing