Coins, Virtual Currency and Microtransactions
PayVault includes a complete virtual currency system that we call Coins.
You should feel free to call the virtual currency whatever you want in your game, such as 'gold' or 'bucks' or simliar. Coins is just the PlayerIO term for the currency we use since it's much easier to talk about than 'generic vitual currency'.
We just provide simple API methods for working with it, and you are completely free to design the end-user experience however you like around it.
Downloading vault contents
The user's vaults contains their coin balance and any items they might have. Before you can access either of those from your client code, you'll have to update the contents of the user's vault using one of these methods:
Whenever you call Refresh(), the entire contents of the users vault will be downloaded from the PayVault Backend Service.
Once the vault contents has been downloaded once by any method, Refresh() will cause the system to only send the vault contents if the contents have changed since they were last downloaded, in order to save bandwidth.
Call any of the methods that modify the vault contents
The complete contents of a users vault, including the coin balance, is always downloaded after all the methods calls that modify the vault contents, such as Credit(), Debit(), Buy() and Consume(). This is done so you don't have to call Refresh() after every other method call.
Getting the coin balance
Coins are stored in the user's vaults, and all users are given an initial coin balance of zero and the coin balance can never become negative.
You can always access the coin balance of a user with the Coins property of the PayVault class, but note that you have to have downloaded the contents of the vault as described above before you attempt to read the property, or you'll get an error.
Credit() and Debit()
The Credit() and Debit() methods are used to put coins into and take coins out of a user's vault.
Both methods takes a coin amount and reason. The reason is stored in the user's vault history which can be viewed in the Control Panel, or read using the ReadHistory() method.
If the user doesn't have enough coins to complete a Debit() call, an error will be thrown. A user's coin balance can never be negative.
As mentioned above, when the Credit() and Debit() calls finish successfully, the coins property will automatically be updated with the latest coin balance.
By default, you can use the Debit() method from anywhere to remove coins from a user's vault, but you won't be able to call the Credit() method unless you explicitly give a connection the access right to call Credit() in the Control Panel.
Not having the right to call Credit() clientside keeps the system secure by not allowing curious users from being able to cheat and give themselves more coins whenever they feel like it.
However, in multiplayer code which runs in a trusted environment, you can always call both Credit() and Debit().
Buying more coins
When a user wants to buy more Coins from inside your game, call the GetBuyCoinsInfo() method with a provider and the required purchase arguments.
You'll get back everything you need to initiate payment for the user, such as an IFrame URL for SuperRewards or the parameters for a Kongregate API call.
Since the purchase arguments are provider specific, you should go to the PayVault Provider Documentation to find the various purchase arguments accepted by each provider.
Some games, like the ones on Facebook, usually navigate to a dedicated 'Buy Coins' or 'Earn Coins' page, thus leaving the game page. For these games you don't have to call GetBuyCoinsInfo() at all, since the buying of coins happens outside the game.
Here is an example of using GetBuyCoinsInfo() to buy coins:
Coins Redirect URL
For some of the providers where GetBuyCoinsInfo() returns a url that you are supposed to show to the user, it is possible to skip the PayVault method call by redirecting the user to the Coins Redirect url. This makes the coin buying process a single-step process, and it makes it easier to avoid popup-blockers and similar.
The Coins Redirect url takes the same parameters as the GetBuyCoinsInfo() method, except you pass them in as querystring parameters. In addition, you will also need to pass in your game id, the connectuserid, and the connection name. The main part of the url looks like this:
Then you attach the required parameters:
After that you have to attach the provider-specific parameters. Check the PayVault Provider Documentation for your chosen provider to see what extra parameters there are. For example if you are making a redirect url for PayPal, your final url will look something like this:
In the PayVault user Control Panel you will also find pre-made urls that you can copy-paste for each provider that supports this, given that you have enabled that provider in the PayVault setup.