Digital Goods / Subscriptions / One-Time Payments API

Last 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 script

Introduction
Digital 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 payments
The technical integration includes two steps:
Paymentwall Widget Call
Pingback Processing

Paymentwall Widget Call

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 users 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).

Default widget call

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
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
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_2
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 its 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.
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 payments widgets (p1, p2, p3):
http://wallapi.com/api/subscription/?key=[APPLICATION_KEY]&uid=[USER_ID]&widget=[WIDGET]
For offers widgets (w1, w2, s1, s2, s3):
http://wallapi.com/api/?key=[APPLICATION_KEY]&uid=[USER_ID]&widget=[WIDGET]
Examples
http://wallapi.com/api/subscription/?key=7e5493348058db49c82dbcfe70f14716&uid=100&widget=p1
http://wallapi.com/api/subscription/?key=7e5493348058db49c82dbcfe70f14716&uid=100&widget=p2&ps=paypal
http://wallapi.com/api/?key=7e5493348058db49c82dbcfe70f14716&uid=100&widget=w1
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/subscription/?' .
http_build_query($params) . '" width="100%" height="100%"
frameborder="0"></iframe>';

Flexible Widget Call

Widget URL
http://wallapi.com/api/subscription
Request method
GET
Protocols supported
http, https
Parameters
Parametr

Required

Description

key

yes

Application key

uid

yes

User id, alphanumeric

widget

yes

Widget key, e.g. p1

amount

yes

Amount of the purchase, e.g.

10.00

currencyCode

yes

Currency of the purchase, e.g.

USD, EUR

ag_name

yes

Product name

ag_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 its 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 used

sign

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.

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 = 'http://wallapi.com/api/subscription';
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:

http://wallapi.com/api/subscription?key=7e5493348058db49c82dbcfe70f14716&uid=1234
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=2d84d1a259cc974c9b99b875207f1da5

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 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 Pingback
Format
http://www.yourserver.com/anypath?uid=[USER_ID]&goodsid=[GOODS_ID]&slength=[SUBSCRIPTION_LENG
TH]&speriod=[SUBSCRIPTION_PERIOD]&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). 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. It's 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

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) = 84d081d1af73ccdf5f7281a145d03ce6
Pingback URL example

http://www.yourserver.com/anypath?uid=1&goodsid=gold_membership&slength=3&speriod
=month&type=0&ref=3&sig=84d081d1af73ccdf5f7281a145d03ce6

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 subscription package that should be taken back from which userID. Format, Request method and
Parameters 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

Chargeback

Credit Card fraud

Ban user

Order fraud

Ban user

Bad data entry

Fake / proxy user

Rejected by advertiser

Duplicate conversions

Goodwill credit taken back

Cancelled order

10

Partially reversed transaction

Sample Pingback listener script

<?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;
$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) {

$str .= "$k=$v";
}

$str .= $secret;
return md5($str);
}