Kongregate Developers

Kreds External Purchase API

This API allows you to launch the Kongregate purchase flow inside a window, which allows you to integrate Kreds functionality in the case that you cannot use our standard lightbox. This method of using our purchasing API is for special circumstances only. Please use our standard API for most games. If you think you need to use the External Purchase API, please contact apps@kongregate.com prior to beginning the integration to get approval.

Starting the purchase flow

To start the purchase flow, you simply need to create a popup window or link which points to the API endpoint on our servers, and includes parameters defining the items you wish to purchase. Note that this URL should be opened using the HTTPS protocol. The URL below will be referred to as the External Purchase API endpoint in the rest of the documentation.

GET url: https://www.kongregate.com/api/purchase_items
required params:
  game_id: The game_id of your game. Use this as opposed to the api_key to 
           ensure your api_key stays private.
  identifiers: Comma-delimited list of identifiers to display in the shopping cart.
  order_info: Order Info string to be used instead of identifiers if using the 
                    Dynamic Purchase API.
  success_url: The URL to redirect to upon a successful purchase. Make sure to
               properly encode this parameter.

The window will use the player's existing Konregate cookies for authentication, so you don't need to pass in their game_auth_token. Also note that if the user is a guest, this method will have undefined behavior, so make sure the user is authenticated before starting the purchase flow. Once a successful purchase is made, the window will be redirected to the success_url endpoint that you passed in as a parameter. You can find your game ID on the API Information page for your game.

Because you will not be able to retrieve a client callback for this type of purchase, you will need to use our callback URL so you can be alerted of when a purchase is made.

Please ensure that the size of the window is at least 760x700 pixels. This allows for enough room to display all the possible content inside the frame.

Example

The example below shows an HTML page which utilizes the Kongregate External Purchase API. Notice the parameters on the link's href attribute:

<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Strict//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-strict.dtd">
<html lang="en" xml:lang="en" xmlns="http://www.w3.org/1999/xhtml">
  <head>
    <title>Purchase Frame</title>
    <style type="text/css">
      html{border: none; overflow: hidden; background-color: #fff; height: 100%;}
      body{border: none; background-color: #fff;margin:0; padding:0;}
    </style>
  </head>
  
  <body>
    <a href="https://www.kongregate.com/api/purchase_items?game_id=76252&identifiers=nerf_sword%2Cnerf_bat&success_url=http%3A%2F%2Fkong.dreamhosters.com%2Fexamples%2Fiframe_checkout%2Fconfirmation.html">
      Click here to purchase!
    </a>
  </body>
</html>

If you are signed into your Kongregate account you can view what the purchase frame will look like by clicking here. Please note that this is not just a test purchase frame - if you complete the purchase you will be charged real money/kreds. It is posted to show what the above code will generate.

Iframes are no longer supported

Overview

Using the External Purchase API inside of an iframe element is no longer supported as of November 1st, 2014. While we regret having to break backward compatibility with some existing games, this change was required in order to protect against clickjacking attacks and increase security for our users by setting X-Frame-Options to SAMEORIGIN for our purchasing endpoints.

Migrating

If you are the developer of a game that is currently embedding the External Purchase API inside of an iframe you can work around the issue by replacing the iframe with a link/button which points to the External Purchase API endpoint on Kongregate directly. Once the Kongregate purchase flow is successful the URL will be redirected as normal. In general, the link you want to open is exactly the same as the one you are currently using for the iframe's src attribute.

You can view the code earlier in the documentation for an example of how to start the purchase flow without using an iframe.

Comments