1. Virtual Currency API
Last updated on 2012/08/22
Introduction
Paymentwall Widget Call
Introduction
Required Parameters
Optional Parameters
Security Parameters
Signature (version 1)
Signature (version 2)
Comments
URL
Examples
Signature (version 1) example
Signature (version 2) example
Pingback Processing
HTTP Pingback
Format
Request method
Protocols supported
Parameters
Example of parameters
Pingback URL example
Return value
Security
Chargeback processing
Sample Pingback listener script
Introduction
Virtual Currency API allows you to monetize applications and services with virtual currency economy. This API
fits you the best if you would like your users to be able to buy and earn coins, points, credits or any other virtual
currency.
Paymentwall Widget Call
Introduction
The Paymentwall is customized for each user landing on the iframe. The system collects any profile data passed
from the application, combines it with a user’s past behavioral data and customize the experience each time they
land on the Paymentwall. The age/sex/location data is used for appropriate offers targeting (e.g. – adult offers
not served to minors).
You can add the following parameters and customize the user experience.
Required Parameters
key – application key, can be found in General Settings of the application under your account.
uid – your internal ID of the end-user (e.g. Facebook Third-Party ID).
widget – widget type code with standard css schema (w1, w2) or with customized (w1_1, w1_2 etc.,
obtained in Widgets section of the application under your account), default: w1.
ps – required only for the Paymentwall Uni (single payment option) widget. Name of the payment method
which is displayed in the widget. Here are some of the most popular payment methods: paypal, amazon,
zong, paymo, daopay. We keep adding new methods even now, and if you want to use some other

2. method in Paymentwall Uni – feel free to enquire about it.
Optional Parameters
firstname – firsname of the user
lastname – lastname of the user
email – email of the user
birthday – date of user's birth (Unix timestamp or formatted string)
sex – sex of user (male, female)
location[city] – city name
location[state] – state/province name
location[address] - address
location[country] – country name
location[country_code] - ISO alpha-2 country code
location[zip] – postal code
Security Parameters
sign – widget signature. If you want to secure widget and disallow unauthorized widget access, you can
sign widget
sign_version – version of the signature. Optional. Default value is 1
ts – Time when request was initiated, represented as Unix timestamp - seconds since the Unix epoch
(January 1 1970 00:00:00 GMT). If it’s older then 60 minutes, user sees an error message.
Recommended for preventing widget from being shared.
If you would like to make the signature parameter mandatory for loading the widget, please contact us.
Signature (version 1)
Less secure. Signs only the id of the end-user. Any additional optional parameters can be changed without
changing the signature.
sign = MD5([USER_ID][SECRET_KEY]).
[USER_ID] - ID of the end-user passed in uid parameter.
[SECRET_KEY] - Secret Key of your application.
Signature (version 2)
More secure. Signs all the parameters passed into the widget.
sign =
MD5([PARAM_NAME_1]=[PARAM_VALUE_1][PARAM_NAME_2]=[PARAM_VALUE_2][PARAM_NAME_3]=[P
ARAM_VALUE_3]...[SECRET_KEY])
[SECRET_KEY] - Secret Key of your application
[PARAM_NAME_N] - name of the parameter that is on Nth position of alphabetical order of all parameters
[PARAM_VALUE_N] - value of the according parameter
Additional parameters (e.g. [PARAM_NAME_1], [PARAM_NAME_2]) are supposed to be sorted by parameter
name in alphabetical order. E.g. in case if parameters sign_version, widget, uid and key are used, the supposed
order in signature is: key=[KEY]sign_version=[SIGN_VERSION]uid=[USER_ID]widget=[WIDGET].
sign parameter itself is not present among signed parameters.
See the code example below.
Comments
MD5, or Message-Digest algorithm 5, is a 32 character long hexadecimal hash. For more details on this hash
function click here.

3. Hint for flash developers: if you're using flash application, don't store SECRET_KEY in it, since flash can be
decompiled and your SECRET_KEY might be known by fraudster. Instead, we kindly recommend you to
calculate signature in server script and pass it to flash via parameter.
URL
For offers widgets (w1, w2, s1, s2, s3):
http://wallapi.com/api/?key=[APPLICATION_KEY]&uid=[USER_ID]&widget=[WIDGET]
For payments widgets (p1, p2, p3):
http://wallapi.com/api/ps/?key=[APPLICATION_KEY]&uid=[USER_ID]&widget=[WIDGET]
Examples
http://wallapi.com/api/?key=6fa41754ad733d700161d57323d68535&uid=100&widget=w1
http://wallapi.com/api/ps?key=6fa41754ad733d700161d57323d68535&uid=100&widget=p1
http://wallapi.com/api/ps?key=6fa41754ad733d700161d57323d68535&uid=100&widget=p2&ps=daopay
Signature (version 1) example
SECRET_KEY = 3b5949e0c26b87767a4752a276de9570
uid = 100
sign = MD5([USER_ID][SECRET_KEY]) = MD5(1003b5949e0c26b87767a4752a276de9570) =
2fa09ff8065a6151844135261f95ad58
Signature (version 2) example
<?php
function calculateWidgetSignature($params, $secret) {
// work with sorted data
ksort($params);
// generate the base string
$baseString = '';
foreach($params as $key => $value) {
$baseString .= $key . '=' . $value;
}
$baseString .= $secret;
return md5($baseString);
}
$params = array(
'key' => '[APPLICATION_KEY]', // YOUR APPLICATION KEY
'uid' => '[USER_ID]',
'widget' => 'p1',
'sign_version' => 2,
'custom_parameter' => 'custom_value'
);
$secret = '[SECRET_KEY]'; // YOUR SECRET KEY
$params['sign'] = calculateWidgetSignature($params, $secret);
echo '<iframe src="http://wallapi.com/api/ps/?' . http_build_query($params) . '"
width="100%" height="100%" frameborder="0"></iframe>';

4. Pingback Processing
Whenever a user pays or completes an offer, we send you a pingback, also known as callback, postback, or
instant payment notification.
Pingbacks can be sent in one of the two formats:
Type Description
HTTP request HTTP request is sent from our servers to your
Pingback listener script where we communicate to
your server details about the payment so that your
server can process the pingback automatically and
deliver the virtual currency to the according user.
URL of your script that listens for pingbacks is called
Pingback URL.
This format is preferrable.
Email An email is sent to the address that you configure as
your Pingback Email once a user pays or completes
an offer. Once you receive the email, you should
deliver the product manually to the according user.
HTTP Pingback
Format
http://www.yourserver.com/anypath?uid=[USER_ID]&currency=[VIRTUAL_CURRENCY]&type=
[TYPE]&ref=[REF]&sig=[SIGNATURE]
Request method
GET
Protocols supported
http, https
Parameters
uid – id of user to be credited. The value of uid parameter from Paymentwall Call is used (e.g. Facebook
Third-Party ID).
currency – positive whole number
type – type of callback. 0 – when a credit is given, 1 – when a credit is given as a customer service
courtesy (write-off), 2 – in case of chargeback (see below)
ref – reference id, alphanumeric
sig = MD5(uid=[USER_ID]currency=[VIRTUAL_CURRENCY]type=[TYPE]ref=[REF][SECRET_KEY]) –
MD5 (Message-Digest algorithm 5) hash in form of 32 digit hexadecimal number.
Example of parameters
SECRET_KEY = 3b5949e0c26b87767a4752a276de9570
uid = 1
currency = 2

5. type = 0
ref = 3
sig = MD5(uid=[USER_ID]currency=[VIRTUAL_CURRENCY]type=[TYPE]ref=[REF][SECRET_KEY]) =
MD5(uid=1currency=2type=0ref=33b5949e0c26b87767a4752a276de9570) =
813bb3bb5a566fde24f6861c60396727
Pingback URL example
http://www.yourserver.com/anypath?uid=1&currency=2&type=0&ref=3&sig=813bb3bb5a566
fde24f6861c60396727
Return value
If you are able to process the callback requests, please start your response message with 'OK'.
If we don't receive a confirmation message, or if the response status code is different from 200, we'll send
pingback again within 30 minutes and the subsequent retries will happen at 30 minute increments after that.
Security
Please add the following IP Addresses as authorized IP addresses to access the script:
174.36.92.186
174.36.96.66
174.36.92.187
174.36.92.192
174.37.14.28
Chargeback processing
Required. This is used in cases of fraud, correction etc. Paymentwall sends request to the Callback URL and
communicates how much virtual currency should be taken back from which userID. Format, Request method
and Parameters are the same as for common Callback except for
currency – negative whole number (e.g. 2)
type = 2 in case of ChargeBack
reason – code of ChargeBack reason. Possible reasons are:
Code Reason Recommedation
1 Chargeback
2 Credit Card fraud Ban user
3 Order fraud Ban user
4 Bad data entry
5 Fake / proxy user
6 Rejected by advertiser
7 Duplicate conversions
8 Goodwill credit taken back
9 Cancelled order
10 Partially reversed transaction

6. Sample Pingback listener script

7. <?php
define('SECRET', ''); // YOUR SECRET KEY
define('CREDIT_TYPE_CHARGEBACK', 2);
$ipsWhitelist = array(
'174.36.92.186',
'174.36.96.66',
'174.36.92.187',
'174.36.92.192',
'174.37.14.28'
);
$userId = isset($_GET['uid']) ? $_GET['uid'] : null;
$credits = isset($_GET['currency']) ? $_GET['currency'] : null;
$type = isset($_GET['type']) ? $_GET['type'] : null;
$refId = isset($_GET['ref']) ? $_GET['ref'] : null;
$signature = isset($_GET['sig']) ? $_GET['sig'] : null;
$result = false;
if (!empty($userId) && !empty($credits) && isset($type) && !empty($refId) &&
!empty($signature)) {
$signatureParams = array(
'uid' => $userId,
'currency' => $credits,
'type' => $type,
'ref' => $refId
);
$signatureCalculated = calculatePingbackSignature($signatureParams,
SECRET);
// check if IP is in whitelist and if signature matches
if (in_array($_SERVER['REMOTE_ADDR'], $ipsWhitelist) && ($signature ==
$signatureCalculated)) {
$result = true;
if ($type == CREDIT_TYPE_CHARGEBACK) {
// Deduct credits from user
// This is optional, but we recommend this type of
crediting to be implemented as well
// Note that currency amount sent for chargeback is
negative, e.g. -5, so be caferul about the sign
// Don’t deduct negative number, otherwise user will get
credits instead of losing them
}
else {
// Give credits to user
}
}
}
if ($result) {
echo 'OK';
}
function calculatePingbackSignature($params, $secret) {
$str = '';
foreach ($params as $k=>$v) {
$str .= "$k=$v";
}
$str .= $secret;
return md5($str);
}