Billing

  1. The Mail.Ru platform presents a payment window for the project to accept payments (see article "Connecting the JS API").
  2. The partner must provide a URL (Billing URL), which will accept information about completed payments. The URL is set in the developer dashboard, on the game page, under the "Payment acceptance" tab.
  3. The data transfer API format is json.
  4. The data transfer protocol is http.
  5. No authorization is required to call the API. Requests must take place only between the servers of the partner and Mail.Ru.

Billing URL

Request format:

GET, http[s]://partner.place.com/api/billing/?uid=[int uid]&sum=[float sum]&tid=[varchar tid]&merchant_param=[varchar merchant_param]&sign=[md5 hash]

Main parameters:

http[s]://partner.place.com/api/billing/ - the URL that contains the partner API for receiving payment information from the Mail.Ru platform.

  • <uid> - id user (sent to the partner upon registration);
  • <sum> - the total in-game currency (based on ruble exchange rate), float type;
  • <tid> - a guid with a unique transaction ID;
  • <merchant_param> - json, parameters for calling the payment frame;
  • <sign> - a unique digital signature.

Signature calculation

To ensure that the request came from a trusted server, you must independently check the signature; then, to calculate the signature, you must follow the instructions below. Also you could use the signature calculator

1. Take the 4 GET parameters from the request:

  • <uid> - 596343600
  • <sum> - 120.5 rubles
  • <tid> -51aa3c7d-a32b-45ec-973e-10e6e9f70851)
  • <merchant_param> - {}

2. Sort the parameters by key (get sign)

{
    "merchant_param": "{}",
    "sum": 120.5,
    "tid": "51aa3c7d-a32b-45ec-973e-10e6e9f70851",
    "uid": "596343600"
}

3. Insert the key value into the line

$str = "merchant_param={}sum=120.5tid=51aa3c7d-a32b-45ec-973e-10e6e9f70851uid=596343600"

4. Generate a signature

$sign = md5($str . $secret)

$secret - game’s unique code. The partner can find this in the developer dashboard, on the game’s page, under the "System properties" tab. The relevant field is titled "Secret for api.games.mail.ru".

5. Compare the calculated sign with the one conveyed in the request. If they are identical, the request is valid.

Response format:

Successful:

{
    "status": "ok"
}

Error:

{
    "status": "error", 
    "errcode": 0
}

"errcode": "[int errcode]" - partner’s internal error code

"errmsg": "[string errmsg]" - partner’s error code description (for example, "Technical maintenance, please try again later").

Specific error codes:

{
    "status": "error", 
    "errcode": 0
}

This means that the partner cannot accept the payment at this time and requests the payment to be re-sent. After some time, the partner’s server receives a repeated notification.

Requirements:

  1. The partner checks the validity of the signature (sign), i.e. independently calculates the signature based on the parameters that came in the request and compares them with the parameters of the sign from the request.
  2. The partner checks the uniqueness of the payment (TID). However, in certain cases the Mail.Ru platform may send a second set of requests with the same TID. When a request containing a previously-sent TID is received, the partner should send the following response:
{
    "status": "ok"
}

At the same time, no need to credit the same payment.

  1. The partner checks that the payment total (sum) is correct, i.e. corresponds to the cost of the goods or currency that the user is buying.
  2. The partner should properly process and store the TID parameter for every payment received. The TID parameter is required to search and identify payments in log files, so it has to be present in the partner's statistics.

Receiving the payment window URL

Request format:

POST, https://games.mail.ru/app/[GMRID]/billing/client?sign=[md5 hash]

Main parameters:

https://games.mail.ru/app/[GMRID]/billing/client - URL that contains the API for calling the payment frame

  • GMRID - the id of the application, part of the PATH in the URL
  • sign - the parameter sign, contained in QUERY_STRING

Payment parameters:

  • merchant_param - parameters for inserting the bill (see below) in the JSON encoded format.

Important note: The main and payment parameters are required.

The bill issue parameters (merchant_param) are as follows:

  • uid - user identifier that opens a payment window
  • ip - the IPv4 address of the user making the payment
  • amount - total payment in the format: 00.00 (ruble as currency)
  • item_id - unique identifier of in-game items
  • additional_param - any additional parameters that the partner would like to add
  • description - payment description in the format of a UTF-8 line not exceeding 50 characters.

Forming request signature:

See "Signature calculation" section.

Examples of combining parameters:

a) purchase of an in-game item for 100 rubles:

$merchant_param = json_encode({
  "uid"              => "12345",          // current user’s uid
  "ip"               => "8.8.8.8",        // current user’s IP address
  "amount"           => 100,              // price of item in rubles
  "description"      => "Золотой сундук", // description of item in payment form (eg. gold chest)
  "item_id"          => "776",            // product order identifier
  "additional_param" => 1                 // additional parameter
});

b) purchase of game currency for 100 rubles:

$merchant_param = json_encode({
  "uid"              => "12345",                 // current user’s uid
  "ip"               => "8.8.8.8",               // current user’s IP address
  "amount"           => 100,                     // price of currency in rubles
  "description"      => "200 золотых кристалов", // description of item in payment form (eg. 200 gold crystals)
  "item_id"          => "777",                   // product order identifier
  "additional_param" => 2                        // additional parameter
});

Response format:

Successful:

{
    "status": "ok",
    "url": "[string url]"
}

Error:

{
    "status": "error",
    "errcode": "[int errcode]",
    "errmsg": "[string errmsg]"
}

Example request:

curl -si "https://games.mail.ru/app/1/billing/client?sign=b8eb7adb10938cb0d93ca364dbd75c25" -d "merchant_param=%7B%22ip%22%3A+%22127.0.0.1%22%2C+%22amount%22%3A+500%2C+%22extra_param%22%3A+%22test_value%22%2C+%22uid%22%3A+643128345%2C+%22description%22%3A+%22test+item%22%7D"