PayVault Essentials

There are a few basic concepts you need to know in order to use PayVault:

PayVault

• Each user has a vault containing their coins and items. Initially the vault has zero coins and no items.
• You can mix and match which PayVault features you use. Tailor the experience to your game. For instance, you shouldn't use the virtual currency system if you're only selling a single "fullversion" item in your game.

• It's your money! PayVault doesn't have any sort of shared currency that's shared between games. When a user buys coins in your game using a provider, it becomes your money and your coins, and you don't have to worry about the user not spending all the coins in your game.

Coins / Virtual Currency

• "Coins" is the Player.IO convenience term for virtual currency. You're free to call it whatever you want in your game: gold, bucks, horseshoes, etc..
• A user's vault contains their coins. Check the Coins property to get the user's balance.

• Call GetBuyCoinsInfo() to get info on how to initiate a 'buy coins' flow. The info is PayVault provider specific, so you'll have to consult the info page for the providers you use to get the full details.
• Call Credit() to give coins to the user. By default, only trusted serverside code can call this method. This can be changed using connection accessrights.
• Call Debit() to take coins from the user
• Some providers have a Coins Redirect URL. You can initiate a 'buy coins' flow by redirecting the user to this, which makes it easier to bypass popup blockers.

Items

Example of a PayVault item with a price in coins.

• A user's vault contains their items. Items can be bought, given and used with various API methods.
• The items than can be bought in your game are called PayVault items.
• A PayVault item is just a BigDB object in the 'PayVaultItems' table. Since they are BigDB objects, they can contain complex datastructures (properties, arrays, nested objects).
  
• If a PayVaultItem has an integer 'PriceCoins' property, it can be bought with coins. Call the Buy() method to buy an item with coins (only works if the user has enough coins to buy the item)
• If a PayVaultItem has an integer 'Price[Currency]' property, such as 'PriceUSD', it can be bought directly with real money completely bypassing the coins system. Call the GetBuyDirectInfo() method to get info on how to display the payment flow. The info is PayVault provider specific, and only some providers support direct purchase, so you'll have to consult the info page for the providers you use to get the full details.
• You can use the Give() method to give items to users.

  And they won't be charged anything for the item. By default, only trusted serverside code can call this method. This can be changed using connection accessrights.

  • Give() always works if if the item has a bool 'FreelyGivable' property set to true. So you don't have to enable Give() for all items, if there are just a few items you want to be able to give from clientside code.
• Call Consume() to remove an item from a user's vault. This is useful for consumable items such as temporary powerups, upgrades etc.
• The entire updated contents of a users vault is downloaded after most method calls, like Buy() or Consume(). You shouldn't have thousands and thousands of really large items in there. There are no limits though, so just use good judgement.
• You can optionally specify an payload for each item when using Buy(), GetBuyItemInfo() or Give(). This payload will get merged onto the PayVault item when you list the items in a user's vault.
• Payload is meant for minor customizations of PayVault items. For instance, instead of having 10 different PayVault items for cars in 10 colors, you might you might have one 'car' item with all the attributes of a car such as 'speed','acceleration','topspeed' and use payload to specify the color of the car. Attributes in the underlying PayVault item always takes precedence over attributes with the same name in the payload.
• Payloads are immutable, so you can't change them with code. But the admin panel has an interface to change them manually if you really need to.
• You don't have to use the built-in PayVault item management. If your game has specific needs that don't fit with well with the built-in item management, you can roll your own using BigDB, and the Credit() and Debit() methods.

The API

• The same API is available to client-side code and multiplayer serverside code. You can mix and match how you interact with the system. Serverside multiplayer code always has full access rights, since the code is running in a trusted enviroment.
• You can set different access rights to control which methods are available where. By default, client-side code can't call Credit() or Give(), to prevent users from just giving themselves coins and items.
• The methods are the same in all clients. All PayVault clients (ActionScript, Multiplayer Code, .NET, ...) support the following methods:
  
  
  • The Coins property contains the amount of coins currently in the user's vault.
  • The Items array contains all the items currently in the user's vault.
  • The Refresh() method downloads the entire contents of the user's vault. You have to call this method before accessing the Coins or Items property, or you'll get an error.
  • The Credit() method puts coins into the user's vault.
  • The Debit() method takes coins out of the user's vault. An error is thrown if the user doesn't have enough coins
  • The Buy() method is used to buy items using coins. You can buy multiple items at once and specify individual payloads for each. The transaction will only complete if the user has enough coins. Bought items go into the user's vault.
  • The Consume() method is used to remove items from the user's vault. You should use this for consumable items such as powerups or upgrades.
  • The GetBuyCoinsInfo() method is to get information on payment flows for buying coins.
  • The GetBuyDirectInfo() method is used to buy items without introducing the user to coins. Prices are shown in real-world currency, which is useful if you're just selling a single item like 'fullversion'.
  • The ReadHistory() method can be used to build an in-game view of a user's transactions. This lets users browse their history and see when they bought coins and what they used them for.

Providers

• PayVault doesn't directly accept money from end-users. Instead we use a set of PayVault providers, such as PayPal, SuperRewards & SocialGold to accept money from end-users.
• You can view all current PayVault providers here We add additional providers on request.
• A provider can support buying coins, direct item purchase or both. You have to check the specific provider page to see what it supports.

Admin Interface

• PayVault has great analytics. In the admin panel you can see overall development of your virtual economy, which providers convert the best, which items are most popular and their individual sales history, look at revenue in different currencies, and much more.
• You can browse all transactions to know exactly what's going on. Filter based on search criteria, and even find the transaction ids from the PayVault providers so you can lookup transactions at the provider's for more info.
• You can manage individual users from the admin panel. See their latest transactions, view their coin development, check out which items they have in their vault, edit payloads, give them items and more... All from an easy, helpful and fast web interface.

Payment Graph™ (beta):

• The latest in predictive payment technologies, now in beta.Uniquely to our platform, the software has the ability to compare balances, payments, and composite scores to determine probability of payment by the unique customer based on previous use and payment frequencies (payment velocities) in a customer’s social graph or profile. We offer payment interfaces with all the major transaction providers and layer the Payment Graph™ feature on top.

  Our Business Intelligence platform uses the data stored in a multi-vectored profile unique as a fingerprint for a given customer/end-user. This feature, part of our PayVault Suite of services, allows our partners to optimize the offer management layers resulting in better conversion rates and customer affinity.

  Our integrated solution will be available to use externally with other BI solutions like Omniture, SAP Business Objects and Informatica in 2012.

  Learn more about our PayVault features at GDC Austin 2011.