8. Purchase

8.0.1. Workflow

When the wakool.purchase() function is called, user will be directed to Wakool platform's payment system. Once the payment is completed the platform will send an HTTP POST request directly to the game server's Payment callback URL with the transaction's details. When the game server acknowledged the request with a SUCCESS response, the EVENT_BROWSER_PURCHASE_VERIFY_VALID event will be triggered.

Purchase isn't allowed for users in guest mode.

Flow chart

8.0.2. Listening purchase events

Register the event listeners for purchase events in SDK loaded callback:

wakool.addEventListener(wakool.EVENT_BROWSER_PURCHASE_VERIFY_VALID, function(event) {
  // Purchase succeed...
  console.log('Purchase succeed! Wakool order ID:'+event.data.order_id);
wakool.addEventListener(wakool.EVENT_BROWSER_PURCHASE_VERIFY_INVALID, function(event) {
  // Purchase failed...

For purchase succeed events, the Wakool order ID can be obtained from event.data.order_id in the listener.

※ The events triggered on the client side are insecure and shouldn't be trusted. They are for UI/UX only. To determine whether the purchase is successful, payment callback should be used.

8.0.3. Calling purchase API

The purchase API:

wakool.purchase(product_id, server_id, character_id, params);


parameter name description
product_id The id of the purchased product
server_id The id of the server the user is playing (when applicable)
character_id The id of the player character (when applicable)
params Any info required for the transaction (optional)

8.0.4. Payment callback

Once the payment is completed, the platform informs the game server's payment callback URL directly with HTTP POST request (server-to-server).

  • HTTP method
  • HTTP POST form fields
parameter name type description
order_id string(60) the order id on the Wakool platform
order_date string(20) date time of the order (ISO 8601)
app_id string(60) app id on the Wakool platform
user_id int64 user id on the Wakool platform
item_id string(60) the id of the item to be purchased
server_id string(60) the server_id from the API was called
character_id string(60) the character_id from the API was called
pay_type string(20) payment type the user used for this purchase
pay_cash int32 the amount of the money paid(NT$)
pay_point int32 the amount of points purchased (in platform points)
params string(100) the additional info from the API was called
sign string(60) signature to validate this request
  • Signature verification

The signature is a lower-cased hexadecimal string of the MD5 value of a query string composed of the app_secret and the rest of the form data in the specified order. The values of the query string have to be urlencoded first.

Example in PHP:

$sign_data = [
  'app_secret'   => 'WAKOOL-APPSECRET-TEST001',
  'order_id'     => 'WAKOOL-ORDER0001',
  'order_date'   => '2015-12-23T09:20:48+0800',
  'app_id'       => 'WAKOOL-APPID-TEST001',
  'user_id'      => '100000001',
  'item_id'      => 'com.wakool.pay.item_300',
  'server_id'    => 'server01',
  'character_id' => 'user01',
  'pay_type'     => 'wakool',
  'pay_cash'     => '300',
  'pay_point'    => '350',
  'params'       => 'mygame-order-id:abcdef;mygame-user-id:123456'

// The signature used to validate the request
$sign = md5(http_build_query($sign_data));

The 12 parameters have to be in the order demonstrated in the example code above when constructing the query string and the values have to be urlencoded.

If you have difficulties verifying the signature, check to see if the order of the 12 parameters are correct.

8.0.5. Response

If for some reason the transaction needed to be cancelled when the purchase callback occurred, such as the order has already been processed, or the product's out of stock, game server may response with a non-success message informing the platform of the cancellation so the user won't be charged.

HTTP response:

purchase result response body
Transaction succeed SUCCESS
Transaction failed reason of failure

results matching ""

    No results matching ""