Virtual Currency APILast updated on 2012/08/22       Introduction       Paymentwall Widget Call              Introduction ...
method in Paymentwall Uni – feel free to enquire about it.Optional Parameters       firstname – firsname of the user      ...
Hint for flash developers: if youre using flash application, dont store SECRET_KEY in it, since flash can bedecompiled and...
Pingback ProcessingWhenever a user pays or completes an offer, we send you a pingback, also known as callback, postback, o...
type = 0      ref = 3      sig = MD5(uid=[USER_ID]currency=[VIRTUAL_CURRENCY]type=[TYPE]ref=[REF][SECRET_KEY]) =      MD5(...
Sample Pingback listener script
<?phpdefine(SECRET, ); // YOUR SECRET KEYdefine(CREDIT_TYPE_CHARGEBACK, 2);$ipsWhitelist = array(,    174...
Paymentwall virtual-currency
Upcoming SlideShare
Loading in …5

Paymentwall virtual-currency


Published on

Published in: News & Politics
  • Be the first to comment

  • Be the first to like this

Paymentwall virtual-currency

  1. 1. Virtual Currency APILast 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 scriptIntroductionVirtual Currency API allows you to monetize applications and services with virtual currency economy. This APIfits you the best if you would like your users to be able to buy and earn coins, points, credits or any other virtualcurrency.Paymentwall Widget CallIntroductionThe Paymentwall is customized for each user landing on the iframe. The system collects any profile data passedfrom the application, combines it with a user’s past behavioral data and customize the experience each time theyland on the Paymentwall. The age/sex/location data is used for appropriate offers targeting (e.g. – adult offersnot 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. 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 users 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 codeSecurity 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 withoutchanging 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]=[PARAM_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 parameterAdditional parameters (e.g. [PARAM_NAME_1], [PARAM_NAME_2]) are supposed to be sorted by parametername in alphabetical order. E.g. in case if parameters sign_version, widget, uid and key are used, the supposedorder 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.CommentsMD5, or Message-Digest algorithm 5, is a 32 character long hexadecimal hash. For more details on this hashfunction click here.
  3. 3. Hint for flash developers: if youre using flash application, dont store SECRET_KEY in it, since flash can bedecompiled and your SECRET_KEY might be known by fraudster. Instead, we kindly recommend you tocalculate signature in server script and pass it to flash via parameter.URLFor offers widgets (w1, w2, s1, s2, s3):[APPLICATION_KEY]&uid=[USER_ID]&widget=[WIDGET]For payments widgets (p1, p2, p3):[APPLICATION_KEY]&uid=[USER_ID]&widget=[WIDGET]Examples (version 1) example SECRET_KEY = 3b5949e0c26b87767a4752a276de9570 uid = 100 sign = MD5([USER_ID][SECRET_KEY]) = MD5(1003b5949e0c26b87767a4752a276de9570) = 2fa09ff8065a6151844135261f95ad58Signature (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_build_query($params) . " width="100%" height="100%" frameborder="0"></iframe>;
  4. 4. Pingback ProcessingWhenever a user pays or completes an offer, we send you a pingback, also known as callback, postback, orinstant 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 PingbackFormat[USER_ID]&currency=[VIRTUAL_CURRENCY]&type= [TYPE]&ref=[REF]&sig=[SIGNATURE]Request methodGETProtocols supportedhttp, httpsParameters 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. 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) = 813bb3bb5a566fde24f6861c60396727Pingback URL example fde24f6861c60396727Return valueIf you are able to process the callback requests, please start your response message with OK.If we dont receive a confirmation message, or if the response status code is different from 200, well sendpingback again within 30 minutes and the subsequent retries will happen at 30 minute increments after that.SecurityPlease add the following IP Addresses as authorized IP addresses to access the script: processingRequired. This is used in cases of fraud, correction etc. Paymentwall sends request to the Callback URL andcommunicates how much virtual currency should be taken back from which userID. Format, Request methodand 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. 6. Sample Pingback listener script
  7. 7. <?phpdefine(SECRET, ); // YOUR SECRET KEYdefine(CREDIT_TYPE_CHARGEBACK, 2);$ipsWhitelist = array(,,,,;$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 ofcrediting to be implemented as well // Note that currency amount sent for chargeback isnegative, e.g. -5, so be caferul about the sign // Don’t deduct negative number, otherwise user will getcredits 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);}