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.

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

Parameters:

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

POST

• HTTP POST form fields

• 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: