Zong PayVault Provider

Setting up your Zong account

1. Sign up for Zong on http://zong.com/merchants/get-started. When you have filled out the form you will be contacted by a sales representative.
2. When you've got a Zong merchant account, go to the Profile tab in the Merchant console and set your outpayment currency to USD. You can check Accept simulation if you want to test it, otherwise leave it off.
3. Set your Callback URL to: http://api.playerio.com/payvault/zong/postback. You have to contact your Zong sales representative to have it changed.

Configuring PayVault on Player.IO

1. Enable Zong in the PayVault admin panel for your game.
2. Enter your Zong customer key. You can find this value on the Profile tab in the Zong Merchant console.
3. If you want to allow coin purchases through Zong, you need to add a single price point that will be used to calculate the exchange rate between coins and USD.
   
   You specify the exchange rate in the format [cent]USD=[coins].
   
   For example, the string '10USD=5' means that each coin costs 2 cent, and the string '200USD=1' means that each coin costs 2 dollars.

Buying Coins: GetBuyCoinsInfo()

Because of the way mobile payments work, you can't always bill an exact amount in a specific currency. End users will always be billed in their local currency, and an amount that is supported by all local carriers.

When you call GetBuyCoinsInfo() you will get back a countrycode and a list of pricepoints that are supported in that country. Each pricepoint contains the amount of coins it will award, the local price the end user will pay, the revenue you will get in USD, and a url that you should display to the user to initiate the purchase for that price point.

What you should do in your game is to display the detected country, and a dropdown of all supported Zong countries so that the user can change it if the geoip result was wrong, and a selection of the returned pricepoints. The user should then be able to choose a pricepoint, and then you redirect the user to the associated pricepoint url, either by redirecting the entire web browser, or by opening it in an IFrame overlay, or a popup window.

Here's an example of buying coins with Zong that just opens up the first pricepoint in a popup in ActionScript 3:

Required GetBuyCoinsInfo() Arguments
currency	The name of your virtual currency as displayed to users.
redirect	A url to a page that the user will be redirected to after finishing the purchase.
basketurl	A url to a page the user will be redirected to if he restarts the purchase.
app	The name of your game for internal reporting on Zong only. (max 25 chars)
Optional GetBuyDirectInfo() Arguments
username	The username of the user, if any.
country	The country code of the user. If you leave this empty, we will auto-detect it using geoip.
redirectparent	If set to true, finishing the purchase will cause the user to be completely redirected to the redirect url instead of just the IFrame.
Result Values
country	The country code of the user. Either the auto-detected one if you didn't specify one in the arguments, or the one you did specify.
coins1	The amount of coins this pricepoint will award, for example '42'.
price1	The price for these coins in the local currency, for example '8.00 EUR'.
payout1	The revenue for these coins in USD, for example '3.5500'.
url1	The url you should redirect the user to in order to initiate payment for these coins.
coins2, price2, payout2, url2	The data for the second pricepoint
...	...
coinsn, pricen, payoutn, urln	The data for the nth pricepoint

Buying Items: GetBuyDirectInfo()

Because of the way mobile payments work, you can't always bill an exact amount in a specific currency. End users will always be billed in their local currency, and an amount that is supported by all local carriers.

This means that when you call GetBuydirectInfo() you will get back a single pricepoint that best matches the item price, i.e. has a payout that is as close to and is larger than the item price.

Note that if your item price is too high, there might not be a matching pricepoint.

Example of buying an item directly with Zong in ActionScript 3:

Required GetBuyDirectInfo() Arguments
itemdesc	A short description of the purchase. (max 25 chars)
redirect	A url to a page that the user will be redirected to after finishing the purchase.
basketurl	A url to a page the user will be redirected to if he restarts the purchase.
app	The name of your game for internal reporting on Zong only. (max 25 chars)
Optional GetBuyDirectInfo() Arguments
username	The username of the user, if any.
country	The country code of the user. If you leave this empty, we will auto-detect it using geoip.
redirectparent	If set to true, finishing the purchase will cause the user to be completely redirected to the redirect url instead of just the IFrame.
Result Values
country	The country code of the user. Either the auto-detected one if you didn't specify one in the arguments, or the one you did specify.
price	The price for this purchase in the local currency, for example '8.00 EUR'.
payout	The revenue for this purchase in USD, for example '3.5500'.
url	The url you should redirect the user to in order to initiate payment for this purchase.