Successfully reported this slideshow.
We use your LinkedIn profile and activity data to personalize ads and to show you more relevant ads. You can change your ad preferences anytime.

Paymentwall subscriptions-api


Published on

Published in: Entertainment & Humor
  • Be the first to comment

  • Be the first to like this

Paymentwall subscriptions-api

  1. 1. Digital Goods / Subscriptions / One-Time Payments APILast updated on 2012/08/22 Introduction Paymentwall Widget Call Default widget call Required parameters Optional Parameters Security Parameters Signature (version 1) Signature (version 2) Comments URL Examples Signature (version 1) example Signature (version 2) example Flexible Widget Call Widget URL Request method Protocols supported Parameters Signature calculation & building widget URL Pingback Processing HTTP Pingback Format Request method Protocols supported Parameters: Example of parameters: Pingback URL example Return value Security Chargeback processing Sample Pingback listener scriptIntroductionDigital Goods / Subscriptions / One-Time Payments API allows you to monetize such products and services as Recurring membership In-game virtual items Digital content Full version of a game Other one-time paymentsThe technical integration includes two steps: Paymentwall Widget Call Pingback ProcessingPaymentwall Widget Call
  2. 2. The 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).Default widget callRequired 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 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 code default_goodsid – SKU ID of the product that is selected by default display_goodsid – SKU ID of the only product that should be displayed hide_goodsid – array of SKU IDs of the products that should be hidden, e.g. hide_goodsid[0]=product_2&hide_goodsid[1]=product_3 will hide products with SKU ids product_3 and product_2Security 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)
  3. 3. 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.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 payments widgets (p1, p2, p3):[APPLICATION_KEY]&uid=[USER_ID]&widget=[WIDGET]For offers widgets (w1, w2, s1, s2, s3):[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
  4. 4. <?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>;Flexible Widget CallWidget URL methodGETProtocols supportedhttp, httpsParameters Parametr Required Description key yes Application key uid yes User id, alphanumeric widget yes Widget key, e.g. p1
  5. 5. amount yes Amount of the purchase, e.g. 10.00currencyCode yes Currency of the purchase, e.g. USD, EURag_name yes Product nameag_external_id yes Alphanumeric SKU ID of the product in your system, which we communicate back to you via the pingback as goodsid parameter.ag_type yes Either fixed or subscription. subscription type is used for time based products, e.g. 3 month membership; fixed is used for one-time payments, like lifetime membership.ag_period_length yes* Length of product period, e.g. 3. Required when ag_type is subscription.ag_period_type yes* Type of product period. Possible values: day, week, month, year. Required when ag_type is subscription.ag_recurring no Possible values: 1, 0. Whether the product is recurring. Recurring billing is supported only when ag_type is subscription.ts no 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.sign_version yes Version of signature. sign_version=2 needs to be usedsign yes Request signature. All parameters in request need to be signed. Refer to instructions on sig nature (version 2) above or signature calculation code below.
  6. 6. Signature calculation & building widget URL <?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 => 7e5493348058db49c82dbcfe70f14716, uid => 123456, widget => p1, //ts => time(), sign_version => 2, amount => 13.37, currencyCode => EUR, ag_name => "Gold" Membership, ag_external_id => gold3w, ag_type => subscription, ag_period_length => 3, ag_period_type => week, ag_recurring => 1 ); $secret = b3842906095a44c6b538e8571dacc990; $params[sign] = calculateWidgetSignature($params, $secret); $url =; echo <iframe src=" . $url . ? . http_build_query($params) . " width="750" height="800" frameborder="0"></iframe>;Given example will output an iframe with the following source: 56&widget=p1&sign_version=2&amount=13.37&currencyCode=EUR&ag_name=%22Gold%22+Memb ership&ag_external_id=gold3w&ag_type=subscription&ag_period_length=3&ag_period_ty pe=week&ag_recurring=1&sign=2d84d1a259cc974c9b99b875207f1da5Pingback 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
  7. 7. 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 product 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]&goodsid=[GOODS_ID]&slength=[SUBSCRIPTION_LENGTH]&speriod=[SUBSCRIPTION_PERIOD]&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). The uid parameter is also case-insensitive, so the usernames such as superUser and Superuser are going to be the same thing; goodsid – SKU ID of product (subscription, package) that you enter when defining them, alphanumeric, e.g. gold_membership; slength – length of product, positive whole number, e.g. 5. When sold item is a fixed package, slength contains empty string; speriod – period of product: day, week, month, year. When sold item is a fixed package, speriod contains empty string; type – type of callback. 0 – when product is bought, 1 – when product is given as a customer service courtesy (write-off), 2 – in case of chargeback (see below); ref – reference id, alphanumeric. Its a unique parameter that is going same for the initial pingback as well as for the negative pingback (chargeback). E.g. If the pingback occurred with the reference "itest", then the negative pingback should also occur with the reference "itest"; sig = MD5(uid=[USER_ID]goodsid=[GOODS_ID]slength=[PRODUCT_LENGTH]speriod=[PRODUCT_PERIOD ]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 goodsid = gold_membership slength = 3 speriod = month type = 0
  8. 8. ref = 3 sig = MD5(uid=[USER_ID]goodsid=[GOODS_ID]slength=[PRODUCT_LENGTH]speriod=[PRODUCT_PE RIOD]type=[TYPE]ref=[REF][SECRET_KEY]) = MD5(uid=1goodsid=gold_membershipslength=3speriod=monthtype=0ref=33b5949e0c26b87767a4752a2 76de9570) = 84d081d1af73ccdf5f7281a145d03ce6Pingback URL example =month&type=0&ref=3&sig=84d081d1af73ccdf5f7281a145d03ce6Return 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 subscription package that should be taken back from which userID. Format, Request method andParameters are the same as for common Callback except for slength – if applicable (not a fixed package), negative whole number (e.g. 2), empty string otherwise 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
  9. 9. Sample Pingback listener script <?php define(SECRET, ); // YOUR SECRET KEY define(CREDIT_TYPE_CHARGEBACK, 2); $ipsWhitelist = array(,,,, ); $userId = isset($_GET[uid]) ? $_GET[uid] : null; $goodsId = isset($_GET[goodsid]) ? $_GET[goodsid] : null; $length = isset($_GET[slength]) ? $_GET[slength] : null; $period = isset($_GET[speriod]) ? $_GET[speriod] : 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($goodsId) && isset($type) && !empty($refId) && !empty($signature)) { $signatureParams = array( uid => $userId, goodsid => $goodsId, slength => $length, speriod => $period, 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) { // Take membership from user // This is optional, but we recommend this type of crediting to be implemented as well } else { // Give membership to user } } } if ($result) { echo OK; } /** * Generates signature using given parameters array and secret * * @param array $params * @param string $secret * @return string */ function calculatePingbackSignature($params, $secret) { $str = ; foreach ($params as $k=>$v) {
  10. 10. $str .= "$k=$v";}
  11. 11. $str .= $secret; return md5($str);}