Widget API - Digital Goods

Full API Reference.

In-game virtual items, digital contents, full version of a game or software, Saas, and any one-time payment products can be stored on Terminal3 Payments side.

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_GOODS,
    '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_GOODS,
    '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_GOODS);
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_GOODS)
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_GOODS)
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_GOODS);
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 Terminal3 Payments Pingback system.

Sample Pingback Request for Digital Goods :

http://www.yourserver.com/anypath?uid=pwuser&goodsid=gold_membership&slength=1&speriod=month&type=0&ref=b1493096790&sign_version=2&sig=d94b23ba8585f29978706dd1b153ead9

Sample code using Terminal3 Payments API Libraries at GitHub.

<?php
require_once('/path/to/paymentwall-php/lib/paymentwall.php');
Paymentwall_Base::setApiType(Paymentwall_Base::API_GOODS);
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 = new Paymentwall_Pingback($_GET, $_SERVER['REMOTE_ADDR']);
if ($pingback->validate()) {
    $productId = $pingback->getProduct()->getId();
    if ($pingback->isDeliverable()) {
        // deliver the product
    } else if ($pingback->isCancelable()) {
        // withdraw the product
    } else if ($pingback->isUnderReview()) {
        // set "pending" as order status
    }
    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_GOODS,
    'YOUR_PROJECT_KEY',
    'YOUR_SECRET_KEY'
);

var pingback = new Paymentwall.Pingback("query data in pingback request", "ip address of pingback");
if (pingback.validate()) {
    var productId = pingback.getProduct().getId();
    if (pingback.isDeliverable()) {
        // deliver the product
    } else if (pingback.isCancelable()) {
        // withdraw the product
    } 
    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_GOODS);
Config.getInstance().setPublicKey("YOUR_PROJECT_KEY");
Config.getInstance().setPrivateKey("YOUR_SECRET_KEY");

Pingback pingback = new Pingback(request.getParameterMap(), request.getRemoteAddr());
if (pingback.validate(true)) {
    String goods = pingback.getProductId();
    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 'paymentwall' # alternatively, require_relative '/path/to/paymentwall-ruby/lib/paymentwall.rb'
Paymentwall::Base::setApiType(Paymentwall::Base::API_GOODS)
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()
    productId = pingback.getProduct().getId()
    if pingback.isDeliverable()
        # deliver the product
    elsif pingback.isCancelable()
        # withdraw the product
    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_GOODS)
Paymentwall.set_app_key('YOUR_PROJECT_KEY') # available in your merchant area
Paymentwall.set_secret_key('YOUR_SECRET_KEY') # available in your merchant area

pingback = Pingback({x:y for x, y in request.args.iteritems()}, request.remote_addr)

if pingback.validate():
    product_id = pingback.get_product().get_id()
    if pingback.is_deliverable():
        # deliver the product
        pass
    elif pingback.is_cancelable():
        # withdraw the product
        pass

    print('OK') # Paymentwall expects response to be OK, otherwise the pingback will be resent

else:
    print(pingback.get_error_summary())

using Paymentwall;

Paymentwall_Base.setApiType(Paymentwall_Base.API_GOODS);
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())
{
    string productId = pingback.getProduct().getId();
    if (pingback.isDeliverable())
    {
        //deliver the product
    }
    else if (pingback.isCancelable())
    {
        //withdraw the product
    }
    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 Terminal3 Payments 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 Terminal3 Payments 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@terminal3.com.
For business support, email us at sales@terminal3.com.
To contact sales, email sales@terminal3.com.