PayVault handles the secure contents of each user's vault, but it doesn't handle the actual payments. Instead, PayVault provides a unified API for initiating payments using a host of different PayVault providers, and handles the technical parts of the integration such as calculating encrypted signatures and handling server postbacks for each of the providers.
Using a provider
In general, to use a provider, you need to follow these steps:
- Sign up for the provider, and set it up for PayVault. Each provider-specific page contains exact instructions.
- Enable the provider in the PayVault Control Panel for your game. This step usually involves copying bits of information from your account on the provider.
- Use the GetBuyCoinsInfo() and/or the GetBuyDirectInfo() methods to start payment flows. See below for details.
Read setup information for each provider here:
Buying Coins and Items with providers
Interacting with PayVault providers to buy coins or items directly happens via the GetBuyCoinsInfo() and GetBuyDirectInfo() methods.
The methods are very similar: You specify the name of a provider, like 'paypal' or 'socialgold', and some purchase arguments in the form of key-value pairs that gets passed to the provider. If the method is GetBuyDirectInfo(), you also specify which items to buy and their payload.
In other words, the methods takes these arguments:
- The exact name of the provider. You can find this on each provider-specific page.
- Purchase arguments. This is a simple list of key-values that you need to supply. Some are required to make the payment work, and some are optional and are only needed if you want to customize the payment experience. Check each provider-specific page to find out what these arguments are.
- (only GetBuyDirectInfo()): The items to buy, and their payload.
The return value from the methods is also a list of key-values pairs, that contains everything you need to start the payment process using the provider.
Depending on the provider it can simple be a URL that you can display to the user in a popup or an IFrame or to, or it can be arguments prepared for the provider's Flash API or similar.
Also depending on which Client API you're using, the key-value pairs will be passed in a suitable structure. For instance, ActionScript uses dynamic object while C# uses a Dictionary<string,string>.
When the user's payment is completed, his vault will be updated, and the transaction appears in the transaction history in the Control Panel.
Most providers supply their own transaction id which we store in the history so that you can cross-reference payments between PayVault and the provider if the need arises, for example in a dispute.
Using PayVault with SiteBox for Facebook Apps
If you are using SiteBox to host your game, there is a special payvault tag that you can use to display a payment IFrame directly, for those providers that have that functionality.
This means that you don't have to do the method call to PayVault to get an IFrame url and display it from your game, instead you can just have a page on SiteBox that displays that IFrame properly for you.