Paymentwall website uses cookies to store your browsing preferences on your device. However, cookies do not collect personal information.

For more information about how we use cookies, check our cookie policy

Close

Documentation

New Documentation Getting Started API Libraries APIs Checklists Flows Integrations Mobile SDKs Reference Smart TV SDK SpiderPipe Testing Payments
Contacts
If you still have questions regarding integration, please email us at devsupport@paymentwall.com

Virtual Currency API

Introduction

Virtual Currency API allows you to monetize projects 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

The Paymentwall is customized for each user landing on the iframe. The system collects any profile data passed from the project, 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.

Widget URL

For offers widgets (w1, w2, s1, s2, s3):

https://api.paymentwall.com/api/?key=[PROJECT_KEY]&uid=[USER_ID]&widget=[WIDGET]

For payments widgets (p1, p2, p3):

https://api.paymentwall.com/api/ps/?key=[PROJECT_KEY]&uid=[USER_ID]&widget=[WIDGET]

Parameters

Parameter Required Possible Values Description
key yes hexadecimal, 32 characters long Project key, can be found in General Settings of the Project inside of your Merchant Account
uid yes alphanumeric, up to 64 characters long ID of the end-user in your system(usually it is an email) who is viewing the widget. Examples: numeric ID, username or email.

Please note that uid parameter is case-insensitive (e.g. JohnDoe and johndoe are considered the same user). If your project allows case sensitive usernames, please use a numeric ID for the uid parameter
widget yes alphanumeric Widget key, e.g. p1. Can be obtained in Merchant Account / Projects / Widgets section
ps only for Uni widget (p2) cc, paysafecard, zong, etc. Name of the payment method which is displayed in the widget. List of shortcodes.
sign recommended hexadecimal, 32 characters long, lowercase If you want to secure widget and disallow unauthorized widget access, you can sign widget. By default this parameter is not required for widget call. If you want to make it required, please contact us.
sign_version no 2, 3 Signature version
email yes string End-user's email. If this parameter is present, Paymentwall will automatically send a payment / offer completion receipt to the user.
User Profile API parameters yes array Parameters for enhanced Risk Scoring, such as lastname, firstname, address, birthday, engagement history. Refer to User Profile API
evaluation no 1, 0 If 1, widget can be loaded even until the project status is Live without being logged into the merchant account in the same browser session. Requires signature version 2 or higher.
country_code no ISO 3166-1 alpha-2 code of the country Overrides default geo-targeting. Requires widget signature.
rv no 1, 0 enable/disable reviews: rv=1 (on, default), rv=0 (off)
th no 1, 0 enable/disable thumbs th=1 (on, default), th=0 (off)
tm no 1, 0 enable/disable tell me more layer. (optional, tm=1 (on, default), tm=0 (off) Note: (only available for the Offerwall Cool UI)
vcr no digit Custom virtual currency exchange rate overriding project settings - amount of virtual currency to be given per 1 unit of real currency. Can be activated for the project per request.
vcc no currency code Custom virtual currency exchange rate overriding project settings - code of real currency to use for custom exchange rate. Example - vcr=1000, vcc=EUR - give 1000 Virtual Currency for each 1 EUR spent by the user. Can be activated for the project per request.
vc no string Custom name of virtual currency overriding project settings. Can be activated for the project per request.
pingback_url no URL URL of pingback listener script where pingbacks should be sent. Takes effect only if activated for the merchant account per request. Requires widget call to be signed with signature version 2 or higher.
success_url no URL URL of the page where the end-user should be redirected to after the payment is complete. This URL shouldn't be used instead of the Pingback Processing for the actual product delivery and updating the merchant's database.
promo no array allows to pass bonus dynamically, for example promo[0][type]=percent_bonus, promo[0][discount]=50, promo[0][minimum_amount]=2.95, promo[0][minimum_amount_currency]=EUR adds 50% of virtual currency for all prices greater or equal 2.95 EUR. Requires signed widget call with sign_version=3

Mobile Widget Use Case

Widget Type Description
Paymentwall Mobile widget parameter is m2 or m2_x (e.g. m2_1). Widget base URL is https://api.paymentwall.com/api/ps/
Offerwall Mobile widget parameter is mw1 or mw1_x (e.g. mw1_2). Widget base URL is https://api.paymentwall.com/api/

For mobile websites, users should be redirected to Widget page as an external standalone page.

For mobile apps, the Widget URL should be embed into project via WebView.

Signature Calculation

Signature (version 1)

sign = MD5([USER_ID][SECRET_KEY])

MD5 lowercase hash in the form of 32 digit hexadecimal number.

Example:

  • SECRET_KEY = 3b5949e0c26b87767a4752a276de9570
  • uid = 100
  • sign = MD5([USER_ID][SECRET_KEY]) = MD5(1003b5949e0c26b87767a4752a276de9570) = 2fa09ff8065a6151844135261f95ad58

Signature (version 2 and 3)

Please refer to Signature Calculation documentation.

Widget Call Sample

Using Paymentwall PHP library at GitHub

require_once('/path/to/paymentwall-php/lib/paymentwall.php');
Paymentwall_Base::setApiType(Paymentwall_Base::API_VC);
Paymentwall_Base::setAppKey('YOUR_SECRET_KEY'); // available in your Paymentwall merchant area
Paymentwall_Base::setSecretKey('YOUR_SECRET_KEY'); // available in your Paymentwall merchant area

$widget = new Paymentwall_Widget(
    'user40012', // id of the end-user who's making the payment
    'p1_1', // widget code, e.g. p1; can be picked inside of your merchant account
    array(), // array of products - leave blank for Virtual Currency API
    array('email' => 'user@hostname.com') // additional parameters
);
echo $widget->getHtmlCode();

For more code samples in different programming languages, please visit https://www.paymentwall.com/en/documentation/getting-started/

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 preferable.
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 - pingback signature

  • For pingback signature version 1
    sig = MD5(uid=[USER_ID]currency=[VIRTUAL_CURRENCY]type=[TYPE]ref=[REF][SECRET_KEY])

    For pingback signature version 2, please refer to Signature Calculation documentation.

  • sign_version - optional. Equals 2 if pingback signature version is 2
  • is_test - value defined as 1 if the payment is done via Test Payment method, or if the pingback is sent via Test Pingback Tool. Otherwise this parameter is not present in the request

Parameters Sample

  • SECRET_KEY = 3b5949e0c26b87767a4752a276de9570
  • uid = 1
  • currency = 2
  • 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 Sample

http://www.yourserver.com/anypath?uid=1&currency=2&type=0&ref=3&sig=813bb3bb5a566fde24f6861c60396727

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.92.187
  • 174.36.92.192
  • 174.36.96.66
  • 174.37.14.28

Please note that certain load balancing services, such as CloudFlare, may alter the originating IP of the request. In such case, the IP address of the request visible on your server may different from original IP address. In this case, using HTTP_X_REAL_IP request header should help getting the original Paymentwall's IP to check if it is whitelisted.

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 Recommendation
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 Canceled order, e.g. refund
10 Partially reversed transaction

Sample Pingback Listening Script

Using Paymentwall PHP library at GitHub.

require_once('/path/to/paymentwall-php/lib/paymentwall.php');
Paymentwall_Base::setApiType(Paymentwall_Base::API_VC);
Paymentwall_Base::setAppKey('YOUR_SECRET_KEY'); // available in your Paymentwall merchant area
Paymentwall_Base::setSecretKey('YOUR_SECRET_KEY'); // available in your Paymentwall merchant area

$pingback = new Paymentwall_Pingback($_GET, $_SERVER['REMOTE_ADDR']);
if ($pingback->validate()) {
    $virtualCurrency = $pingback->getVirtualCurrencyAmount();
    if ($pingback->isDeliverable()) {
    // deliver the virtual currency
    } else if ($pingback->isCancelable()) {
    // withdraw the virtual currency
    }
    echo 'OK'; // Paymentwall expects response to be OK, otherwise the pingback will be resent
} else {
echo $pingback->getErrorSummary();
}

For more code samples in different programming languages, please visit https://www.paymentwall.com/en/documentation/getting-started/

More details:

This page needs JavaScript
Your browser is
not supported anymore.
Please update to the more recent one.
This page needs JavaScript
This page needs JavaScript.
Please enable it in your browser settings and try again.
We use cookies on this website to make your browsing experience better. By using the Paymentwall website you agree to our Cookies Policy.