Documentation
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.
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]
| 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 |
| 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 |
| 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 (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.
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. |
| 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
http://www.yourserver.com/anypath?uid=[USER_ID]¤cy=[VIRTUAL_CURRENCY]&type=[TYPE]&ref=[REF]&sig=[SIGNATURE]
GET
HTTP, HTTPS
- 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
- 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
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.
- 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
http://www.yourserver.com/anypath?uid=1¤cy=2&type=0&ref=3&sig=813bb3bb5a566fde24f6861c60396727
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.
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.
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/
