Please help us improving it by reporting us any bugs or suggestions to [email protected], we put our best efforts in order to make life easier for you and the other developers, and your help will be greatly appreciated.
In this document we’ll dig into the in-game items purchases that allow your players to buy paid items for your game. Please refer to the MINIPLAY APIs OVERVIEW document first if you haven’t read it yet, knowledge of the concepts explained there is required.
Miniplay provides game developers the ability to use our micropayments platform in order to allow players purchase paid items in the games, in addition, we also allow developers to handle & manage free items, that can be granted by you as rewards for players. The only limitation is that you can’t give users paid items.
Most of social games have their own infrastructure and manage their own economies and user inventories, in that case, you can use our platform just as a mere payment gateway. As soon as an user purchases an item, it will be added to his Miniplay Inventory for your game and your servers will receive a signed HTTP POST request with the purchase detail and minicoins you earned in the process, in that moment, you can remove all the items in the Miniplay user inventory for your game and add them to your own platform, that’s what we call to consume the items or use the items.
We can accommodate to your preferences but the best practice here is to only create packages of your own currency as items to avoid user confusion, let’s put an example: Your game has "gold" as currency and a lot of items that can be purchased with "gold", that way we only create the following 5 items:
Be noticed that you must consume the item from the inventory, never add the amount to your platform without consuming it first from our user inventory for your game.
In case of casual games, most don’t have their own infrastructure, so you can fully rely on our inventory management, just tell us what the items are available on your game shop.
Here’s our currency equivalence:
After the user completes the purchase (handled by us), you’ll receive 2 callbacks: a client callback and a server callback (if you provided us a callback url).
All our client APIs allows you to set a custom callback when calling the buy() method, it will be called after the user completes or cancels the operation. Please refer to the corresponding API for detailed documentation.
If you provide us a callback url, every completed purchase will be signed and notified to your server/s, so you can consume the items purchased by the user and add them to your platform. Every call to your server will include the amount of minicoins that the user spent and the transaction id, so you can write your own transactions log.
Please make sure you allow incoming connections to your 80 port from our IP range: 217.13.124.0/24
For further information regarding server callbacks please refer to the REST S2S API documentation - Item purchases.
NOTICE: if you have your own inventory and currency, the best practice is, instead of reading the items array that we provide you in the callback, load all the user inventory and consume every item you found inside (inserting them into your system in the process) that way, you can consume items that could haven’t been consumed previously. A even better added practice is to also load the full user inventory on the game initialization and consume any item you found there. Don't add items to your own inventory or economy without consuming them from our inventory, or users would have the items both your's and our's!
In order to provide you more security or the ability to decide whether or not an item can be sold to an user (i.e. promotions, discounted or special items), we support S2S item pre-validations (for all or for a few items), in this case, we'll request your authorization (via an S2S callback) for every item purchase.
We’re working on a fully featured dashboard to track all your movements, until is ready, the REST S2S API provide you with access to a complete transaction log for your game.
Please download the following excel and use it a sample to request the items setup
Download the Excel example here: http://bit.ly/IngamePurchases
