Getting Started

It is important to understand the whole flow before trying to implement any feature from the SDK:

  • Sign up to Wolopay .
  • Inside Wolopay control panel, create as many Applications as you wish. Configure items, articles, payment methods, shops, offers, etc.
  • Optionally Download SDK for PHP .
  • Integrate code as explained in this guide (including tests).
  • Send for approval.
  • Go Live

Introduction to the Document

The goal of this document is to describe Wolopay SDK features and capabilities, in order to detail all steps needed to integrate a game's shop with Wolopay. Once integrated, Wolopay will render the shop, show all options to the users, redirect them to the payment methods, receive payment notifications, and notify the game about payments. The document will detail: SDK functionality and implementation. Code examples How to program a unique request that handles all the payment process

Scope

This document explains, from a technical point of view, the different possible interactions with Wolopay’s SDK, as well as the parameters and answers involved in those interactions. It’s therefore intended for developers who will be in charge of integrating Wolopay SDK with the payment part of their Apps.

Introduction to Wolopay

Wolopay is the most advanced and flexible payment solution in the market. It allows:

  • Defining the "applications " of a merchant (like the games of a developer or publisher).
  • Defining one or more "items " sold in each game (gold, silver, bronze, coins, Arrows, Magic Mushroom, Mighty Sword...)
  • Defining an "article ", that is, a certain amount of items sold (so the user can’t choose the quantity). For example "10 silver coins " or "100 arrows "
  • Defining special items and articles, like Bundles, Random packs, or Gachas.
  • Defining "filters" to allow users see only a desired subset of them (like "wood related resources", or "Dark Cards")
  • Defining "tabs" to group the articles in categories (like "virtual currency", "resources", "weapons", "shields", "armors", etc).
  • Wolopay will allow the merchant to use certain "payment methods " to the game in each country.
  • The merchant will choose which articles are available in each shop and tab, and at which price per country. So one article may have different prices in different countries (because of the standard of living, for example).
  • Defining offers (a discount, or a different amount of "items " -like 2x1) in a period of time (can be programmed so it starts and ends automatically)
  • Defining promotional or "gift codes ", to be redeemed (so they can be given offline, or for specific actions, like answering a poll).
  • Limiting the number of times that one user can buy an article, redeem a code, or buy an offer.
  • Defining different combinations of all the above into different "shops ", that can be used depending on the user level
  • Etc.

With Wolopay and all the above mentioned, the merchant may choose to:

  • Define everything in Wolopay, and when the user wishes to buy something, call Wolopay so that the options are presented inside Wolopay System, and leave it open to the user to choose payment method and article.
  • When the user wishes to buy, he chooses the payment method (or it’s forced because it’s the only one) inside the game, and then tell Wolopay which payment method it is. In this way, the user will only be presented the articles allowed for that specific payment method. He chooses the article in Wolopay and pays.
  • When the user is going to buy, he chooses inside the game the article to be bought, then Wolopay is launched accordingly, and only the payment methods allowed for that article are shown. User chooses the payment method inside Wolopay and pays.

All the combinations above are improved with the ability to the customer to choose the user is allowed to change the country where the article is bought or not.

The Toolkit

The last version of the SDK can be found in GitHub .

Project contains

File or folder nameExplanation
srcContains the WolopayApi class definition file
src/WolopayApi.phpWolopayApi class definition
basic_processFolder that contains example of basic usage
basic/createTransaction.phpPHP Example for creating a transaction
basic/notification.phpPHP Example for verifying the veracity of a notification of payment Error: No se encuentra la fuente de referencia
basic/index.phpPHP Example of request to the system, so that it automatically launches Wolopay interface to the user, in a "lightbox" on top of the current page.
extra_featuresFolder that contains example of additional functionalities

Integration

Pre-Requisites

During the integration phase:

  • The merchant has to provide Wolopay with a Notification URL. This will be used to notify whenever there is a successful transaction.
  • Wolopay will provide the merchant with a customerId, and a private key, that will be used as part of the security mechanism explained below.

API

Please check this URL for the latest version of all methods

Security

All requests include WSSE authentication:

<?php
 
private function generateHeaderWSSE()
{
    $nonce = md5(rand().uniqid(), true);
    $created = gmdate(DATE_ISO8601, time());
 
    $digest = base64_encode(sha1($nonce.$created.$this->secret,true));
    $b64nonce = base64_encode($nonce);
 
    return  sprintf('UsernameToken Username="%s", PasswordDigest="%s", Nonce="%s", Created="%s"',
        $this->clientId,
        $digest,
        $b64nonce,
        $created
    );
}
 

And at the time of making the http request, include special header:

<?php
curl_setopt($ch, CURLOPT_HTTPHEADER, array('X-WSSE: '.$this->generateHeaderWSSE()));
 
 

Transactions

Create

As explained above, the first step is that the merchant creates a transaction. It is done making a request to transaction.format function using POST method, where format is one of json, xml or html, as desired to obtain the answer. Only the "gamer_id " (unique identifier of the user in the game) is mandatory.

If the transaction is done inside a store (facebook, steam), parameter "external_store" has to be used (for example: external_store=facebook)

Other Parameters

When creating the transaction, additionally to the mandatory parameters, an array of parameters can be passed in order to change the behavior of Wolopay (for example for pre-selecting a tab or article, to limit the articles or payment methods shown, to select your user language, etc.). Explanation of all parameters in the above mentioned url The request answers with the transaction information in the format specified in the request (json, xml, html).

Response

The answer to the "transaction create " will contain all the information relevant to the transaction. It’s also explained here .

Status

In order to check the status of a transaction, a request to transaction.format function using GET method has to be done, where format is one of json, xml or html, as desired to obtain the answer. The only mandatory parameter is "transaction_id "

Examples

Using the files of the toolkit supplied: first, create an Object of class WolopayApi, and set up a transaction with the rest of the parameters.

<?php
 
require_once "vendor/autoloader.php"; // if you are using composer
// require_once "WolopayApi.php"; // if you are not using composer
 
 
// Variables for creating WolopayApi object
$apiClientId     = '5432'; //Provided by Wolopay at integration time
$apiClientSecret = '123456'; //Provided by Wolopay at integration time
$sandbox         = false;
$debug           = true;
 
// Variables for creating the transaction
$gamerId      = 'user132'; //Unique User Id. (always the same id for that specific user)
$level        = '3'; //Level of the user, as agreed with Wolopay at integration time
$extraOptions = array();
$autoRedirect = true;
 
// Create object
$wolopayApi = new WolopayApi($apiClientId, $apiClientSecret, $sandbox, $debug);
 

Once the object is created, there are two options:

Receiving Data

The createTransaction method answers by default a JSON that includes the transaction Identifier and a URL that is the one to be launched in the browser; this URL is the one that "renders " the shop for the user to select articles, payment methods, etc., and to pay:

<?php
 
//Create transaction, and get transactionId and URL from the result.
$result = $wolopayApi->createTransaction($gamerId = 'user13', $level = 3);
$result->id; //  have a transactionId
header("Location: " . $result->url);

Auto Redirect

However, the method accepts a parameter autoRedirect, which instead of the JSON, automatically redirects to the aforementioned URL. With this option, when the method is requested, nothing else has to be done

<?php
 
//Create transaction
if (!$wolopayApi->createTransaction($gamerId, $level, $extraOptions, $autoRedirect)) {
    if ($debug) {
        echo "Error, Request can't be generated";
    }
    throw new \Exception("Request can't be generated");
}

Launching as an IFrame on top of the Window

The recommended way of launching Wolopay is by creating a Lightbox in JavaScript that "renders " the shop on top of the current window. In this way, browsers will not treat it as a pop-up (and therefore will not block it). Wolopay provides a JavaScript that can be included in the project in order to create the lightbox. The following snippets of code show a working example:

<html>
<head>
</head>
<body>
    <!-- Lightweight lightbox without jquery -->
    <script src="//wolopay.com/plugin/lightbox.js"></script>
    <a href="#" onclick="woPlugin.open('./createTransaction.php')">Click me to open the shop</a>
</body>
</html>

Being "createTransaction " a file with the 5.1 and 5.1.b code (having included WolopayApi.php with the class definition).

Steam Integration

In order to use Wolopay with Steam, the customer has to provide his Steam "App Id" and "Web Api Key" (found in partner.steamgames.com, menu: "Users and permissions", sub-menu: "Manage Groups").

the easiest way to integrate is the following (taking for granted that Wolopay is already integrated as explained in this tutorial).

  • User wants to buy, clicks the button of the shop in the game.
  • Game calls Wolopay "transaction" method with parameter "external_store=steam" and receives a json with a "shop url" -among other things.
  • Game opens a Steam embedded browser with Wolopay "shop URL" (obtained in previous step).
  • User interacts with Wolopay shop, selects what he wants to buy, and clicks continue.
  • Wolopay creates the transaction in Steam, so Steam makes a callback to your client to draw the overlay: (OnGameOverlayActivated).
  • User pays or cancels payment. In both cases, Steam makes another callback to the game client (OnMicroTxnAuthorizationResponse), that has to get it and make a request to Wolopay (see C++ example code below).
  • Upon reception, Wolopay checks status of transaction.
  • If successful, we notify the game to add items to the user (as explained in the Receiving Notifications section below).
// ------------------- SteamClient.h ------------------- //
class CSteamClient
{
private:
/* ....................... */
	STEAM_CALLBACK(CSteamClient, OnGameOverlayActivated, GameOverlayActivated_t);
	STEAM_CALLBACK(CSteamClient, OnMicroTxnAuthorizationResponse, MicroTxnAuthorizationResponse_t);
/* ....................... */
};
 
 
// ------------------- SteamClient.cpp ------------------- //
void CSteamClient::OnMicroTxnAuthorizationResponse(MicroTxnAuthorizationResponse_t *callback)
{
	std::stringstream js;
 
	js << "$.ajax({url: 'https://sandbox.wolopay.com/shop/payment/ipn_static/steam_client_ipn_pay_method/'";
	js << ", data: 'steamOrderId=" << callback->m_ulOrderID << "'";
	js << ", type: 'POST'});\n";
 
	SimpleHandler::GetInstance()->sendJavascript(js.str());
}
 
void CSteamClient::OnGameOverlayActivated(GameOverlayActivated_t *callback)
{
	/* Not needed to be implemented if openGl layer is loaded and "in front". */
	/* Except for logging purposes */
}
 
 
// ------------------- simple_handler.cc  ------------------- //
void SimpleHandler::sendJavascript(std::string js) {
	if (browser_list_.size() > 0) {
		CefRefPtr<CefBrowser> browser = browser_list_.front();
		CefRefPtr<CefFrame> frame = browser->GetMainFrame();
		frame->ExecuteJavaScript(js, frame->GetURL(), 0);
	}
}
 

Receiving Notifications

When a transaction finalizes into an effective purchase, that is, the user has paid for the article (or articles if he used the "cart "), Wolopay notifies the App accordingly, so that the user is granted the privileges bought (be it virtual currency, months of subscription, or a physical object). One request is done per article of the cart. If one article had a "gift ", this gift will also be notified in a separate request (as it’s, in fact, a different article).

In the same way, if there’s a chargeback (payment cancellation) or a refund (whether initiated by the payment method , whether initiated in Wolopay’s control panel), Wolopay also notifies the customer via HTTP. The parameters are the same (except "event ", which has a different value, as explained below). Again, one request is done per article of the original purchase. This is done for the cases in which the game has to take some action (like "removing " an article from the user, subtracting resources, or simply log the event for accounting).

Wolopay will make a request to the provided URL, with parameters via POST. Additionally, a security parameter will be sent in the header (Authorization: Signature XXXX), this parameter will be used for checking the authenticity of the transaction as explained below:

Mandatory Parameters to receive

ParameterDescription
event Specifies if notification is of a successful transaction (payment) or of a cancellation or refund. Possible values: payment.completed OR payment.cancelled. Of course, items have to be given only when: event=payment.completed
notificationId Unique identifier for the notification. This parameter has to be used in order to detect duplicated requests.
appId Identifier of the application. It?s mandatory only if the customer has more than one app.
gamerId Unique identifier of the user that has paid (as received when creating the transaction). This parameter has to be used to identify WHO to add the article
woloItemId The app may have more than one item, each of them having a unique numeric identifier (for example "coins=195", "months of premium account=196", a "welcome pack=197", etc.). This parameter indicates the "item" that has to be added to the user (as stored in Wolopay database). It will be provided by Wolopay at integration time. Instead of this, it's strongly recommended to use gameItemId (see below). This value may be used for mapping with already existing ids in the game. So for example, the game may have an item named "gold_coins", and Wolopay inserted as "195". When creating the item, the game may specify "gameItemId=gold_coins". When receiving the notification, the game should use "gameItemId", which will contain "gold_coins" (instead of "woloItemId" that will be 195) See below
gameItemId When creating the item in the "admin" control panel, the game can insert the name or id of the item in their side, so they can use it for identifying what to give to the user.
itemsQuantity Amount of "items" to be added to the user account.. For example, if the user selected "100 coins", itemsQuantity=100. If that same article has a 2x1 offer, the purchase was for 200, itemsQuantity=200

For a complete list of available parameters, please contact your account manager.

Checking Authenticity of a transaction notification

When receiving a notification of a successful transaction from Wolopay, a "secret " value is sent as a HEADER:

Authorization: Signature XXX

Being "XXXX " a "secret " value, obtained as a sha1 of the "query " received as POST plus the private key obtained at integration time.

In order to check the authenticity of the whole request received by the App, the following procedure has to be followed:

  • Get the POST query as received (in the order it is received), and along with the "private key " provided at integration time, get a value as follows: o $check = sha1($query. $privateKey)
  • Check if "secret " value received in the header equals the value obtained above ($check == $secret)
  • If they match, the request is valid.

Expected Answer

When Wolopay makes a "notification " request expects a 200 HTTP response code as answer, ONLY if the user was correctly added the purchased article (in fact, any code between 200 and 299).

In any other case, if the transaction did not finished correctly for any reason (for example, for a duplicated transaction, user not found, database or internal errors, etc), a 200 code must NOT be answered. Any 400 – 499 code would be the preferred code.

If Wolopay receives any http code other than a 200, the system will automatically re-try the request every 10 minutes up to 25 times. It’s recommended that you notify yourself of this situation in order to fix it as soon as possible.

Special Cases

Shopping Cart

Wolopay offers the end-users visiting the shop to buy multiple articles at once (except for SMS, voice and subscriptions).

If a user buys multiple articles in the same purchase, the game will receive one notification per article in the cart. Each notification will have:

A unique id (WONOT_xxxxxxxxxxxxx) that identifies ONE article per purchase, A transaction_id (WOT_xxxxxxxxxxxxx) that identifies the "transaction ", that is, the "purchase ". So all the articles in the cart, will have the same transaction_id The itemId and amount that has to be given to the user of the article in the notification (each notification may have different values in this parameter –or not if the user purchased more than 1 time the same article BUT each notification will have the total price paid in the purchase, that is, the price of the whole cart (and NOT of each individual article).