6. Purchase

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

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

6.3. Calling purchase API

The purchase API:

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

Parameters:

6.4. Receive 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 (application/x-www-form-urlencoded)

• 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'   => '2024-09-06T09:20:48+08:00',
  'app_id'       => 'WAKOOL-APPID-TEST001',
  'user_id'      => '100000001',
  'item_id'      => 'net.wakool.mygame.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 sign value above is db8957bbdfa3968fa21597840f698c0f

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.

6.5. Response of payment callback

If the payment succeed, please respond with plain-text SUCCESS to notify us that the transaction is successful. Otherwise, if for some reason the transaction failed, such as the product's out of stock, or other exceptions, game server should respond with a non-success message informing the platform of the failure.

HTTP response: