Notes

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 an api and private keys, that will be used as part of the security mechanism.

The last version of the Wolopay Library API can be found in GitHub .

Please check this URL for the latest version of all API methods.

The fastest way to begin is to use the library mentioned above, and use the credentials provided by Wolopay (also available in the control panel)

The rest of this document will assume you're using the library.

Transaction Create

The first step is to create a transaction.

The answer to the “create_transaction” method is a JSON containing all the information relevant to the transaction, including a field named "url". This is the URL of the shop, the one that “renders” the shop for the user to select articles, payment methods, to pay, etc. The user has to be redirected (or an Iframe of LightBox shown) to this URL.

<?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);

However, the method in the API Library 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");
}

Despite the above methods, 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>

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).

A request will be made to the URL provided to Wolopay, 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:

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.
woloAppId Identifier given by Wolopay to the application. The customer can define its own Id (external to Wolopay) when creating the project: It's sent as gameAppId. Either woloAppId or gameAppId are mandatory only if the customer has more than one game/app.
gameAppId Identifier given by the customer to identify the game or 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

Instead of adding a certain "quantity of items" (using the parameters above), customer may choose to add "articles" (that is, the identifier that represents the tuple "quantity, itemId") by their articleId. This can be done receiving parameter woloArticleId, or, if the article has been given its identifier in the game during the configuration, getting parameter gameArticleId Of course, in this case a "quantity" is not needed, as each request is of one article (which implicitly means a certain quantity).

There are many other parameters available (like price, currency, exchange rates, fees...). Please contact customers@Wolopay.com for more information.

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 item (in fact, any code between 200 and 299).

In any other case, if the transaction did not finish 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.

Checking Authenticity of a transaction notification

The WolopayApi class has a method for checking the Authenticity of the requests:

<?php
 
$wolopayApi = new \Wolopay\WolopayApi($apiClientId, $apiClientSecret, $sandbox, $debug);
 
// Verify this request is from wolopay
if (!$wolopayApi->isAValidRequest()){
 
    // Be careful, If you are using php v <= 5.3 and you write some text (like errors, print_r, echo ...)
    // PHP httpCode Header doesn't work
    $wolopayApi->setHttpCode(400, 'Bad Request');
    echo "This payment is invalid";
    throw new \Exception("invalid request");
}
 
// IMPORTANT: Last verifications is with your system. you will need to ensure that the $_POST['notificationId']
// wasn't used and success
if ($_POST['event'] === 'payment.completed'){
 
    if ($_POST['test']){
        echo "Your logic when it was a test";
    }
 
}elseif ($_POST['event'] === 'payment.cancelled'){
 
    if ($_POST['test']){
        echo "Your logic when it was a test";
    }
}