{"_id":"57756ea1d44a3e0e00329c1e","__v":4,"category":{"_id":"56af6d6ecc4cbd0d00ce2c88","pages":["56af6e8460a37a0d00ed87ac","56af71e58be2ea0d00b48887","56af73a08be2ea0d00b48890"],"version":"56abbf55f25f160d00e17f51","__v":3,"project":"56abbf55f25f160d00e17f4e","sync":{"url":"","isSync":false},"reference":false,"createdAt":"2016-02-01T14:36:30.275Z","from_sync":false,"order":2,"slug":"concepts","title":"Kongregate APIs & Concepts"},"parentDoc":null,"user":"56abbec30b9e0b0d00616274","version":{"_id":"56abbf55f25f160d00e17f51","project":"56abbf55f25f160d00e17f4e","__v":12,"createdAt":"2016-01-29T19:36:53.665Z","releaseDate":"2016-01-29T19:36:53.665Z","categories":["56abbf56f25f160d00e17f52","56abca6bf9757e0d007c6650","56acddfa0ab3c00d00ce3332","56af65da9d32e30d0006d30f","56af66cab34d210d003d9ad0","56af6afcd21e9c0d00b628d1","56af6d6ecc4cbd0d00ce2c88","5705b12221cfed0e00e8c580","570a5676ade45d0e00c1ad33","570d7d25d1e4b82000d9e385","570eac3c3160d10e0041df0e","575709000fd6a3200010dded"],"is_deprecated":false,"is_hidden":false,"is_beta":false,"is_stable":true,"codename":"","version_clean":"1.0.0","version":"1.0"},"project":"56abbf55f25f160d00e17f4e","updates":[],"next":{"pages":[],"description":""},"createdAt":"2016-06-30T19:10:25.321Z","link_external":false,"link_url":"","githubsync":"","sync_unique":"","hidden":false,"api":{"results":{"codes":[]},"settings":"","auth":"required","params":[],"url":""},"isReference":false,"order":4,"body":"## Dynamic Purchasing API\n\n[block:callout]\n{\n  \"type\": \"warning\",\n  \"title\": \"Approval required\",\n  \"body\": \"If you are selling in-app purchases you will need to submit your game to apps:::at:::kongregate.com 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.\"\n}\n[/block]\n\n[block:callout]\n{\n  \"type\": \"danger\",\n  \"title\": \"Edge case: already live games\",\n  \"body\": \"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.\"\n}\n[/block]\n\nThe Dynamic Purchasing API allows users to purchase virtual items in your game using Kongregate's Kreds virtual 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 how the [Facebook Payments](https://developers.facebook.com/docs/games_payments/takingpayments) API works.\n\nHere is a very basic summary of how the API works. We will go into more detail about each part later on.\n\n*   You make a client API call to [purchaseItemsRemote](doc:client-api-mtx-purchaseitemsremote) and pass in an `order_info` string.\n*   We create an `ItemOrder` in our database with an `id` and your `order_info` string.\n*   Our servers call back to yours to request item definitions for the given `ItemOrder`\n*   The information received from your servers (name, description, icon, price) are displayed to the user in the shopping cart.\n*   Once the user confirms the purchase, we call back to your servers once again.\n*   Your servers award the user their virtual goods.\n\n### Setup\n\nIn 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:\n\n`http://www.kongregate.com/games/YourName/YourGame/edit`\n\nWe will cover the specific calls that will be made to that endpoint later.\n\nOnce the [client API is loaded](doc:client-api-introduction), you can access the virtual goods functions from the `mtx` object on the API, for example `kongregate.mtx.purchaseItemsRemote`, etc.\n\n### Requesting a Purchase\n\nYou may bring up the \"purchase items\" dialog box by using the [purchaseItemsRemote](doc:client-api-mtx-purchaseitemsremote) method on the `mtx` API 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.\n\n### Handling the item_order_request callback\n\nThis callback will be issued as a [signed request](doc:concepts-signed-requests) to your API callback URL when an order needs to be defined. The request will have the following parameters once decoded/verified:\n\n*   **event** - `item_order_request`.\n*   **game_id** - The game_id.\n*   **buyer_id** - The id of the user making the purchase.\n*   **recipient_id** - The id of the user to receive the items.\n*   **order_id** - A unique order id for this order in our database.\n*   **order_info** - The order info string you passed into `purchaseItemsRemote`.\n\nHere is an example of the decoded JSON parameters received for an `item_order_request` with the `order_info` set to 'sword':\n[block:code]\n{\n  \"codes\": [\n    {\n      \"code\": \"{\\n  \\\"event\\\":\\\"item_order_request\\\",\\n  \\\"game_id\\\":10000,\\n  \\\"buyer_id\\\":765,\\n  \\\"recipient_id\\\":765,\\n  \\\"order_id\\\":12345,\\n  \\\"order_info\\\":\\\"sword\\\"\\n}\",\n      \"language\": \"json\"\n    }\n  ]\n}\n[/block]\nYour 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.\n\n*   **name** - The name of the item.\n*   **description** - The description of the item (255 character max).\n*   **price** - The price of the item in Kreds. (integer)\n*   **image_url** - A URL to an icon of the item. This icon will be rendered at 40x40 pixels.\n\nHere is an example valid JSON response for the above callback:\n[block:code]\n{\n  \"codes\": [\n    {\n      \"code\": \"{\\n  \\\"items\\\":\\n  [\\n    {\\n      \\\"name\\\":\\\"Awesome Sword\\\",\\n      \\\"description\\\":\\\"A really neat sword!\\\",\\n      \\\"price\\\":10,\\n      \\\"image_url\\\":\\\"https://media.giphy.com/media/3o85xFGXZQIC29z74Q/giphy.gif\\\"\\n    }\\n  ]\\n}\",\n      \"language\": \"json\"\n    }\n  ]\n}\n[/block]\nOnce you deliver this JSON payload back to our servers, the shopping cart will be displayed to the user and they can confirm the purchase.\n\n### Handling the item_order_placed callback\n\nThis callback will be issued as a [signed request](doc:concepts-signed-requests) to your API callback URL when a user has confirmed an order. The request will have the following parameters once decoded/verified:\n\n*   **event** - `item_order_placed`\n*   **game_id** - The game_id.\n*   **buyer_id** - The id of the user making the purchase.\n*   **recipient_id** - The id of the user to receive the items.\n*   **order_id** - A unique order id for this order in our database.\n*   **order_info** - The order info string you passed into `purchaseItemsRemote`\n\nHere is an example of the decoded JSON parameters received for an `item_order_placed` with the `order_info` set to 'sword':\n[block:code]\n{\n  \"codes\": [\n    {\n      \"code\": \"{\\n  \\\"event\\\":\\\"item_order_placed\\\",\\n  \\\"game_id\\\":10000,\\n  \\\"buyer_id\\\":765,\\n  \\\"recipient_id\\\":765,\\n  \\\"order_id\\\":12345,\\n  \\\"order_info\\\":\\\"sword\\\"\\n}\",\n      \"language\": \"json\"\n    }\n  ]\n}\n[/block]\nAt 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:\n[block:code]\n{\n  \"codes\": [\n    {\n      \"code\": \"{\\\"state\\\":\\\"completed\\\"}\",\n      \"language\": \"json\"\n    }\n  ]\n}\n[/block]\n### Example\n\nAn basic PHP example can be found [here.](http://cdn1.kongregate.com/assets/files/0000/4388/dynamic-item-flow.zip) It demonstrates how to decode/verify the signed request and handle the various required callbacks for this flow.","excerpt":"","slug":"api-dynamic-purchasing","type":"basic","title":"Dynamic Purchasing"}

Dynamic Purchasing


## Dynamic Purchasing API [block:callout] { "type": "warning", "title": "Approval required", "body": "If you are selling in-app purchases you will need to submit your game to apps@kongregate.com 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." } [/block] [block:callout] { "type": "danger", "title": "Edge case: already live games", "body": "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." } [/block] The Dynamic Purchasing API allows users to purchase virtual items in your game using Kongregate's Kreds virtual 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 how the [Facebook Payments](https://developers.facebook.com/docs/games_payments/takingpayments) API works. 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 [purchaseItemsRemote](doc:client-api-mtx-purchaseitemsremote) and pass in an `order_info` string. * 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 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](doc:client-api-introduction), you can access the virtual goods 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](doc:client-api-mtx-purchaseitemsremote) method on the `mtx` API 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](doc:concepts-signed-requests) 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': [block:code] { "codes": [ { "code": "{\n \"event\":\"item_order_request\",\n \"game_id\":10000,\n \"buyer_id\":765,\n \"recipient_id\":765,\n \"order_id\":12345,\n \"order_info\":\"sword\"\n}", "language": "json" } ] } [/block] 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. (integer) * **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: [block:code] { "codes": [ { "code": "{\n \"items\":\n [\n {\n \"name\":\"Awesome Sword\",\n \"description\":\"A really neat sword!\",\n \"price\":10,\n \"image_url\":\"https://media.giphy.com/media/3o85xFGXZQIC29z74Q/giphy.gif\"\n }\n ]\n}", "language": "json" } ] } [/block] 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](doc:concepts-signed-requests) 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': [block:code] { "codes": [ { "code": "{\n \"event\":\"item_order_placed\",\n \"game_id\":10000,\n \"buyer_id\":765,\n \"recipient_id\":765,\n \"order_id\":12345,\n \"order_info\":\"sword\"\n}", "language": "json" } ] } [/block] 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: [block:code] { "codes": [ { "code": "{\"state\":\"completed\"}", "language": "json" } ] } [/block] ### Example An basic PHP example can be found [here.](http://cdn1.kongregate.com/assets/files/0000/4388/dynamic-item-flow.zip) It demonstrates how to decode/verify the signed request and handle the various required callbacks for this flow.