Биллинг

  1. Платформа Mail.ru предоставляет платежное окно для приема платежей проектом (см. статью Подключение JS API).
  2. Партнер должен предоставить URL (Billing URL), который будет принимать информацию о совершенных платежах. URL указывается в кабинете разработчика, на странице игры, на вкладке "Прием платежей".
  3. Формат API передачи данных - json.
  4. Протокол передачи данных - http.
  5. Не требуется авторизация для вызова API. Запросы должны происходить только между серверами Партнера и Mail.ru.

Billing url

Формат запроса:

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]

Основные параметры:

http[s]://partner.place.com/api/billing/ - URL, который содержит партнерское API для получения информации о платежах от платформы Mail.ru.

  • <uid> - id пользователя (при регистрации сообщается партнеру);
  • <sum> - сумма в игровой валюте (получается из рублей по курсу), имеет тип float;
  • <tid> - guid, уникальный id транзакции;
  • <merchant_param> - json, параметры поднятия фрейма оплаты;
  • <sign> - уникальная цифровая подпись.

Подсчет подписи

Для того чтобы удостовериться что запрос пришел от довереного сервиса необходимо самостоятельно вычислить подпись. Помочь в вычисление подписи может калькулятор подписи. Для вычисления подписи необходимо:

1. Взять 4 GET-параметра из запроса:

  • <uid> - 596343600
  • <sum> - 120.5 рублей
  • <tid> -51aa3c7d-a32b-45ec-973e-10e6e9f70851)
  • <merchant_param> - {}

2. Сортируем параметры по ключам (исключаем переданный sign)

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

3. Склеиваем ключ-значение в строку

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

4. Генерируем подпись

$sign = md5($str . $secret)

$secret - уникальный ключ игры. Партнер может узнать его в кабинете разработчика, на странице игры, на вкладке "Системные свойства". Поле "Секрет для api.games.mail.ru".

5. Сверяем расчетный sign с переданным в запросе, если идентичны -> запрос корректный.

Формат ответа:

Успешно:

{
    "status": "ok"
}

Ошибка:

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

“errcode": "[int errcode]" - внутренний код ошибки партнера;

"errmsg": "[string errmsg]" - описание кода ошибки партнера (например, “Технические работы, повторите попытку позже”).

Специфические коды ошибок:

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

Означает, что партнер не может принять платеж в данный момент и запрашивает переотправку платежа. Через некоторое время сервер партнера получит повторное уведомление.

Требования:

  1. Партнер сам контролирует правильность подписи (sign), то есть самостоятельно считает подпись по параметрам которые пришли в запросе и сравнивает их с параметром sign из запроса.
  2. Партнер сам контролирует уникальность платежа (tid), однако, платформа Mail.ru, в отдельных случаях, может осуществлять повторную отправку запросов с одинаковым tid. При получении запроса, содержащего tid отправленный ранее, партнер должен отправить ответ
    {
        "status": "ok"
    }
    При этом второй раз тот же платеж зачислять не нужно.
  1. Партнер сам контролирует что сумма платежа (sum) является правильной, то есть соответсвует стоимости товара или валюты которую приобретает пользователь.
  2. Партнер должен обрабатывать должным образом и хранить параметр tid для каждого полученного платежа. Параметр tid необходим для поиска и идентификации платежей лог-файлах, поэтому необходимо его наличие в статистике партнера.

Получение URL платежного окна

Формат запроса:

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

Основные параметры:

https://games.mail.ru/app/[GMRID]/billing/client - URL, который содержит API для вызова фрэйма оплаты.

  • GMRID - id приложения, является частью PATH в URL;
  • sign - подпись параметров, передается в QUERY_STRING.

Платежные параметры:

  • merchant_param - параметры для выставления счета (см. ниже) в формате JSON encoded.

Важное примечание: Основные и платежные параметры являются обязательными.

Параметры выставления счета (merchant_param):

  • uid - идентификатор пользователя, который открывает платежное окно
  • ip - адрес IPv4 пользователя осуществляющего платеж
  • amount - сумма платежа в формате: 00.00 (рубль в качестве валюты);
  • item_id - уникальный идентификатор игрового предметов;
  • additional_param - любые дополнительные параметры, которые партнер хотел бы добавить;
  • description - описание платежа в формате: строка utf-8, не должно превышать 50 символов.

Формирование подписи запроса:

См. раздел "Подсчет подписи".

Примеры комбинации параметров:

a) покупка игрового предмета за 100 рублей:

$merchant_param = json_encode({
  "uid"              => "12345",          // uid текущего пользователя
  "ip"               => "8.8.8.8",        // ip адрес текущего пользователя
  "amount"           => 100,              // цена товара в рублях
  "description"      => "Золотой сундук", // описание товара в форме оплаты
  "item_id"          => "776",            // идентификатор заказа товара
  "additional_param" => 1                 // дополнительный параметр
});

b) покупка игровой валюты за 100 рублей:

$merchant_param = json_encode({
  "uid"              => "12345",                 // uid текущего пользователя
  "ip"               => "8.8.8.8",               // ip адрес текущего пользователя
  "amount"           => 100,                     // цена валюты в рублях
  "description"      => "200 золотых кристалов", // описание товара в форме оплаты
  "item_id"          => "777",                   // идентификатор заказа товара
  "additional_param" => 2                        // дополнительный параметр
});

Формат ответа:

Успешно:

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

Ошибка:

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

Пример запроса:

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"