Payment process pipeline

In-game payment procedure is processed in 4 steps and requires validation from game server:

  1. Game must call FAPI.UI.showPayment method.
  2. Payment can be done immediately or after confirmation from user in a payment dialog:
    • If confirmation dialog is displayed and user pressed “Cancel” button, payment is not proceed.
    • In all other cases API will send a HTTP GET request to “Callback URL” that was specified in application settings. Possible request parameters and their values are described here callbacks.payment.
  3. Game server must validate received request and give back a specific response. If game server does not respond to a sent request, payment gets cancelled and currency (OKs) is not taken from user.
  4. If game server responds correctly, callback function gets called on client side. This function takes a parameter “amount” which is equal to product price.

Server validation

Lets look a bit closer to a process of in-game payment on game server’s side:

  1. Server receives a request from API.
  2. Server reads all GET parameters from this request.
  3. Server checks if product’s id, name and price is correct.
  4. Server verifies a request signature (GET parameter sig).
  5. (Optional but highly recommended) Server logs all the required data about transaction.
  6. If steps 3 and 4 are finished without an error, server must return a success message to API-server in response to a request. If validation is finished with an error, game server returns a failure message to API-server. Required response format is described here callbacks.payment.

Transaction_id parameter is unique for every payment. Game server must ignore any duplicated transactions. If transaction with such id was processed before, game server must respond with a response similar to the first one

Examples

Examples for steps 3 and 4 are can be found here. Php programming language was chosen as the most popular language for web-based games development tool but any other language can be used, too.

Full version can be found on github (for example to work you must specify your public and secret keys, products list).

Step 3 example

// payment validation function
public static function checkPayment($productCode, $price) {
    if (array_key_exists($productCode, self::$catalog) && self::$catalog[$productCode] == $price) {
        return true;
    } else {
        return false;
    }
}

Step 4 example (you need to set your secret key for example to work)

// function calculates a signature for a received request
// signature calculation algorithm can be found on this page https://apiok.ru/en/dev/methods/
function calcSignature($request) {
    $tmp = $request;
    unset($tmp["sig"]);
    ksort($tmp);
    $resstr = "";
    foreach($tmp as $key=>$value) {
        $resstr = $resstr.$key."=".$value;
    }
    // secret key goes here
    $resstr = $resstr.self::APP_SECRET_KEY;
    return md5($resstr);
}