Widget API - Virtual Currency

Full API Reference.

Specify the currency for your application’s virtual cash. Virtual Currency API will help you manage the currencies.

Configuration

Once you have a project created in My Projects, you can start configure your project at Settings section to make it work properly with Widget API:

Widget Call

By replacing the value of ps parameter from all to specific payment systems API short codes, you can specify payment method for single payment method.

<?php
require_once('lib/paymentwall.php');
Paymentwall_Config::getInstance()->set(array(
    'api_type' => Paymentwall_Config::API_VC,
    'public_key' => 'YOUR_PROJECT_KEY',
    'private_key' => 'YOUR_SECRET_KEY'
));

$widget = new Paymentwall_Widget(
    'user40012', 
    'p1_1', 
    array(), // leave this array empty for Widget API
    array(
        'email' => 'user@hostname.com', 
        'history[registration_date]' => 'registered_date_of_user',
        'ps' => 'all' // Replace the value of 'ps' with specific payment system short code for Widget API uni
    )
);
echo $widget->getUrl();
?>

var Paymentwall = require('paymentwall');
Paymentwall.Configure(
    Paymentwall.Base.API_VC,
    'YOUR_PROJECT_KEY',
    'YOUR_SECRET_KEY'
);

var widget = new Paymentwall.Widget(
    'user40012', // uid
    'p1_1', // widget 
    [], // Product parts, leave empty for Widget API
    {
        'email': 'user@hostname.com',
        'history[registration_date]': 'registered_date_of_user',
        'ps': 'all', // Replace the value of 'ps' with specific payment system short code for Widget API uni
        'additional_param_name': 'additional_param_value'
    }
);
widget.getUrl();

Config.getInstance().setLocalApiType(Config.API_VC);
Config.getInstance().setPublicKey("YOUR_PROJECT_KEY");
Config.getInstance().setPrivateKey("YOUR_SECRET_KEY");

WidgetBuilder widgetBuilder = new WidgetBuilder("user12345", "p1_1");

widgetBuilder.setExtraParams(new LinkedHashMap<String, String>(){
{
    put("email", "user@hostname.com");
    put("history[registration_date]","registered_date_of_user");
    put("ps","all"); // Replace the value of 'ps' with specific payment system short code for Widget API uni
}
});

Widget widget = widgetBuilder.build();

return widget.getUrl();

require 'paymentwall' # alternatively, require_relative '/path/to/paymentwall-ruby/lib/paymentwall.rb'
Paymentwall::Base::setApiType(Paymentwall::Base::API_VC)
Paymentwall::Base::setAppKey('YOUR_PROJECT_KEY')
Paymentwall::Base::setSecretKey('YOUR_SECRET_KEY')

widget = Paymentwall::Widget.new(
    'user40012',
    'p1_1',
    [],
    {
        'email' => 'user@hostname.com',
        'history[registration_date]' => 'registered_date_of_user',
        'ps' => 'all', // Replace the value of 'ps' with specific payment system short code for Widget API uni
        'additional_param_name' => 'additional_param_value'
    }
)
puts widget.getUrl()

from paymentwall import *
Paymentwall.set_api_type(Paymentwall.API_VC)
Paymentwall.set_app_key('YOUR_PROJECT_KEY')
Paymentwall.set_secret_key('YOUR_SECRET_KEY')

widget = Widget(
    'user40012', 
    'p1_1', 
    [], // Product parts, leave empty for Widget API
    {
        'email' => 'user@hostname.com',
        'history[registration_date]' => 'registered_date_of_user',
        'ps' => 'all', // Replace the value of 'ps' with specific payment system short code for Widget API uni
        'additional_param_name' => 'additional_param_value'
    }
)
print(widget.get_url())

using Paymentwall;

Paymentwall_Base.setApiType(Paymentwall_Base.API_VC);
Paymentwall_Base.setAppKey("YOUR_PROJECT_KEY"); 
Paymentwall_Base.setSecretKey("YOUR_SECRET_KEY");

List<Paymentwall_Product> productList = new List<Paymentwall_Product>();

Paymentwall_Widget widget = new Paymentwall_Widget(
    "user40012", 
    "p1_1", 
    new Dictionary<string, string>() {
        {
            'email' => 'user@hostname.com',
            'history[registration_date]' => 'registered_date_of_user',
            'ps' => 'all', // Replace the value of 'ps' with specific payment system short code for Widget API uni
            'additional_param_name' => 'additional_param_value'
        }
    }
);
Response.Write(widget.getUrl());

Handle Pingback

Before you start, please read Pingbacks document to get an overview of Paymentwall Pingback system.

Sample Pingback Request for Virtual Currency :

http://www.yourserver.com/anypath?uid=pwuser&currency=200&type=0&ref=b1493096790&sign_version=2&sig=d94b23ba8585f29978706dd1b153ead9

Sample code using Paymentwall API Libraries at GitHub.

<?php
require_once('/path/to/paymentwall-php/lib/paymentwall.php');
Paymentwall_Config::getInstance()->set(array(
    'api_type' => Paymentwall_Config::API_VC,
    'public_key' => 'YOUR_APPLICATION_KEY', // available in your Paymentwall merchant area
    'private_key' => 'YOUR_SECRET_KEY', // available in your Paymentwall merchant area
));
$pingback = new Paymentwall_Pingback($_GET, $_SERVER['REMOTE_ADDR']);
if ($pingback->validate(true)) {
    $virtualCurrency = $pingback->getVirtualCurrencyAmount();
    if ($pingback->isDeliverable()) {
        // deliver the virtual currency
    } else if ($pingback->isCancelable()) {
        // withdraw the virtual currency
    } else if ($pingback->isUnderReview()) {
        // set "pending" status to order
    }
    echo 'OK'; // Paymentwall expects response to be OK, otherwise the pingback will be resent
} else {
    echo $pingback->getErrorSummary();
}
?>

var Paymentwall = require('paymentwall');
Paymentwall.Configure(
    Paymentwall.Base.API_VC,
    'YOUR_PROJECT_KEY',
    'YOUR_SECRET_KEY'
);

var pingback = new Paymentwall.Pingback("query data in pingback request", "ip address of pingback");
if (pingback.validate(true)) {
    var virtualCurrency = pingback.getVirtualCurrencyAmount();
    if (pingback.isDeliverable()) {
        // deliver the virtual currency
    } else if (pingback.isCancelable()) {
        // withdraw the virtual currency
    } 
    console.log('OK'); // Paymentwall expects the string OK in response, otherwise the pingback will be resent
} else {
    console.log(pingback.getErrorSummary());
}

import com.paymentwall.java.*;

Config.getInstance().setLocalApiType(Config.API_VC);
Config.getInstance().setPublicKey("YOUR_PROJECT_KEY");
Config.getInstance().setPrivateKey("YOUR_SECRET_KEY");

Pingback pingback = new Pingback(request.getParameterMap(), request.getRemoteAddr());
if (pingback.validate(true)) {
    Integer currency = pingback.getVirtualCurrencyAmount();
    String userId = pingback.getUserId();
    if (pingback.isDeliverable()) {
        // deliver Product to user with userId
    } else if (pingback.isCancelable()) {
        // withdraw Product from user with userId
    }
    return "OK";
} else {
    return pingback.getErrorSummary();
}

require_relative '/path/to/paymentwall-ruby/lib/paymentwall.rb'
Paymentwall::Base::setApiType(Paymentwall::Base::API_VC)
Paymentwall::Base::setAppKey('YOUR_PROJECT_KEY') # available in your Paymentwall merchant area
Paymentwall::Base::setSecretKey('YOUR_SECRET_KEY') # available in your Paymentwall merchant area

pingback = Paymentwall::Pingback.new(request_get_params, request_ip_address)
if pingback.validate(true)
    virtualCurrency = pingback.getVirtualCurrencyAmount()
    if pingback.isDeliverable()
        # deliver the virtual currency
    elsif pingback.isCancelable()
        # withdraw the virual currency
    end 
    puts 'OK' # Paymentwall expects response to be OK, otherwise the pingback will be resent
else
    puts pingback.getErrorSummary()
end

from paymentwall import *
Paymentwall.set_api_type(Paymentwall.API_VC)
Paymentwall.set_app_key('YOUR_PROJECT_KEY')
Paymentwall.set_secret_key('YOUR_SECRET_KEY')

pingback = Pingback({x:y for x, y in request.args.iteritems()}, request.remote_addr)
if pingback.validate(True):
    virtual_currency = pingback.get_vc_amount()
    if pingback.is_deliverable():
        # deliver the virtual currency
        pass
    elif pingback.is_cancelable():
        # withdraw the virtual currency
        pass 
    print('OK') # Paymentwall expects response to be OK, otherwise the pingback will be resent
else:
    print(pingback.get_error_summary())
end

using Paymentwall;

Paymentwall_Base.setApiType(Paymentwall_Base.API_VC);
Paymentwall_Base.setAppKey("YOUR_PROJECT_KEY"); // available in your Paymentwall merchant area
Paymentwall_Base.setSecretKey("YOUR_SECRET_KEY"); // available in your Paymentwall merchant area


NameValueCollection parameters = Request.QueryString;
Paymentwall_Pingback pingback = new Paymentwall_Pingback(parameters, HttpContext.Current.Request.ServerVariables["REMOTE_ADDR"]);
if (pingback.validate(true))
{
    float virtualCurrency = float.Parse(pingback.getVirtualCurrencyAmount());
    if (pingback.isDeliverable())
    {
        // deliver the virtual currency
    } else 
    {
        // withdraw the virtual currency
    }
    Response.Write("OK"); // Paymentwall expects response to be OK, otherwise the pingback will be resent
}
else {
    Response.Write(pingback.getErrorSummary());
}

Before you submit the project, please test your pingback integration using Test Pingback Tool.

You should check whether your pingback listener is :

  • responding OK to Paymentwall pingback requests.
  • filtering duplicate reference id requests.
  • filtering wrong signature requests. You can test this by checking Use a dummy value feature in Test Pingback Tool.

Success Page

If you would like to redirect the user after a payment is made, you can pass the success_url and failure_url parameters as optional parameter that will be used as the address of landing page after your users made payments. You can also use client side callback if you want to take more actions.

To enable client side callback, please contact to devsupport@paymentwall.com with your Paymentwall account email address.

Next Step

Once you have successfully integrated our widget and set up for the pingback listener, you can submit your project for review.

See project go live.

Questions?

Common questions are covered in the FAQ.
For integration and API questions, feel free to reach out Integration Team via integration@paymentwall.com.
For business support, email us at merchantsupport@paymentwall.com.
To contact sales, email bizdev@paymentwall.com.

To suggest a change to this documentation you can submit a pull request on GitHub.