Руководство по монетизации приложений

Вы можете монетизировать свои приложения, принимая платежи от пользователей. Биллинг Платформы позволяет быстро интегрировать возможность приема платежей за виртуальные товары и услуги. Если вы хотите принимать платежи от пользователей, вы можете это делать только через биллинг Платформы. Если ваше приложение принимает оплату в оффлайне (например, интернет-магазин с оплатой курьеру), то такие платежи реализовывать через биллинг не обязательно.

Как подключить платежи в вашем приложении

  1. Зайдите в JIRA http://apiok.ru/jira/documents/, введите данные о компании, приложите необходимые документы и акцептуйте оферту (резидентам РФ) или заключите договор (нерезидентам РФ)
  2. Проверьте, что ваша компания проверена и одобрена (Название компании появится во вкладке «Биллинг», при этом не должно быть сообщений, что она проверяется модератором). Проверка компании занимает как правило не более 7 дней.
  3. Реализуйте на вашем сервере скрипт оказания услуг (см. ниже)
  4. Активируйте прием платежей, указав url скрипта оказания услуг во вкладке Биллинг настроек вашего приложения
  5. Интегрируйте прием платежей через API-функции биллинга в ваше приложение и проверьте корректность обработки платежей
  6. Подайте приложение на модерацию в каталог, если вы этого еще не сделали.

Вопросы и комментарии по финансовым вопросам пишите на finance@odnoklassniki.ru Вопросы и комментарии по договору пишите на agreements@odnoklassniki.ru

Схема приема платежей с технической точки зрения

Шаг 1. Вы делаете внутри приложения экран, где пользователь может что-то купить, например, внутренннюю валюту или какой-то конкретный товар (услугу). Вы сами выбираете что вы продаете пользователю, в каком объеме — вы можете предоставить фиксированные пакеты или давать пользователю самому ввести количество — и сколько ваши товары будут стоить. На этом же экране должна быть кнопка «Купить» (или любой другой визуальный объект), по нажатию на которую произойдет вызов функции API для приема платежа — payments.showDialogjs. Все цены должны быть указаны в мэйликах — внутренней валюте Моего Мира. Один мэйлик = одному рублю. Шаг 2. Пользователь открывает ваш экран покупки, выбирает товары и нажимает кнопку «купить». Функция API приема платежа открывает поверх приложения слой с интерфейсом приема платежей через Биллинг Платформы.

Платежное окно

В окне приема платежа отображается за какую услугу будет принят платеж. Для указания стоимости услуги, нужно использовать параметр mailiki_price, в котором необходимо указать точную стоимость услуги в мэйликах. Шаг 3. Биллинг платформы обрабатывает платеж без участия приложения и, когда денежная транзакция будет завершена, оповещает пользователя об успешном платеже в окне, открывающемся поверх приложения. Шаг 4. Биллинг обращается к вашему скрипту оказания услуг (см. ниже) для того, чтобы приложение оказало оплаченную услугу: начислило виртуальную валюту, дало пользователю купленный бонус и т. п. Шаг 5. Приложение должно в своем интерфейсе показать пользователю, что оплаченная услуга оказана.

Вызов функции приема платежей

Прием платежей от пользователя осуществляется в окне, которое показывает функция payments.showDialogjs. Вам необходимо лишь в нужный момент вызвать эту функцию с нужными вам параметрами, все остальное Платформа сделает самостоятельно. Вам останется только оказать оплаченную услугу в скрипте оказания услуг. Подробности работы метода читайте в его документации — payments.showDialogjs. Обратите внимание, что при вызове метода вы указываете стоимость услуги для пользователя в мэйликах. Сумму дохода по транзакции в рублях, вы можете получить в параметре profit когда биллинг будет обращаться к вашему скрипту оказания услуг (см. ниже). Для тестирования окна приема платежей разработчик может выполнять вызов метода из-под аккаунта, в котором было добавлено приложение. В данном случае, метод будет работать, даже если приложение ещё не может принимать платежи.

Скрипт оказания услуг

Биллинг Платформы обращается к вашему серверу каждый раз когда происходит платеж в пользу вашего приложения. Биллинг обращается к скрипту только когда пользователь оплатил услугу, вам не надо заботиться о начатых, но не завершенных транзакциях. Скрипт получает от биллинга всю информацию о платеже, должен проверить подпись запроса (чтобы защититься от мошенничества), данные платежа и предоставить оплаченную пользователем услугу. Рекомендуем выполнять платные действия только в этом скрипте, так как это поможет защитить ваше приложения от накруток пользователями.

Формат запроса от биллинга к скрипту

В настройках приложения на вкладке Биллинг вы указываете URL скрипта. Биллинг Платформы делает GET-запрос на этот адрес каждый раз при поступлении нового платежа. В запросе передаются следующие параметры:

Имя Тип Описание
app_id int идентификатор вашего приложения
transaction_id int идентификатор денежной транзакции
service_id unsigned int идентификатор услуги, который был передан при вызове функции API по приему платежа
uid string идентификатор пользователя, который оплатил услугу
sig string подпись запроса, рассчитывается по аналогии с подписью запроса любого вызова API по защищенной схеме «сервер-сервер»
mailiki_price int номинал платежа в мэйликах, который был указан при вызове платежного окна
other_price int номинал платежа в копейках (для поддержки совместимости с старым протоколом)
profit int сумма в копейках, которую вы получите от Платформы (ваша прибыль)
debug bool флаг, определяющий режим отладки; если debug=1, то приложение должно учитывать, что это тестовый вызов. При реальных платежах параметр debug отсутствует

Каждый факт поступления денег от пользователя регистрируется как отдельная транзакция с уникальным идентификатором transaction_id. Вы можете фиксировать его для каждого факта оказания услуги пользователю, чтобы в принципе исключить возможность повторного оказания услуги по данной транзакции. Параметр service_id помогает вам определить какую именно услугу надо оказать пользователю. Вы реализуете эту логику сами, Платформа просто пробрасывает значение service_id, указанное при вызове payments.showDialogjs в скрипт оказания услуг чтобы помочь вам в этом. Параметр sig используется для проверки платежа на подлинность. Обязательно проверяйте подпись чтобы защититься от подделок запроса злоумышленниками. Пример такого запроса от биллинга скрипту оказания услуг:

https://example.com/billing.php?transaction_id=3751&service_id=19&
uid=10410773181171625989&mailiki_price=10&other_price=10000&profit=5000&
sig=b41467e049d82dad39f69769d13554d4&app_id=524632

Внимание!

Обязательно сверяйте стоимость услуги service_id с суммой, которую на самом деле оплатил пользователь — mailiki_price.

Формат требуемого ответа от скрипта

В ответ на запрос, скрипт оказания услуг должен отдать биллингу в json-формате следующую информацию:

Имя Тип Описание
status int статус обработки услуги: 1 — услуга оказана успешно; 2 — услуга не может быть оказана; 0 — услуга на данный момент не оказана, но может быть оказана позднее
error_code int код ошибки, если услуга не оказана (status равен 0 или 2); если status=1, то error_code передавать не нужно

Возможные значения error_code:

Разница между значением 0 и 2 параметра status следующая:

Если биллинг платформы от биллинга приложения получили таймаут или status=0, то биллинг платформы будем делать 3 попытки с интервалом в 5 секунд. Если все 3 попытки не увенчались успехом (т.е. биллинг платформы не получил от биллинга приложения status=1) то деньги будут возвращены пользователю, а попытки оповестить биллинг приложения будут прекращены.
 При получении ответа от биллинга приложения в неправильном формате, деньги возвращаются пользователю и попытки оповестить биллинг приложения сразу прекращаются. Если вы обнаруживаете повторное обращение биллинга к вашему скрипту (вы уже оказывали услугу с таким transaction_id), то мы рекомендуем возвращать ответ со status=1. Пример успешного ответа скрипта оказания услуг:

{  
  "status" : "1"
}

Пример ответа, сообщающий, что вы возможно сможете обработать платеж в следующий раз:

{  
  "status" : "0", 
  "error_code" : "701"
}

Пример ответа, сообщающий, что вы не можете обработать платеж ни в каком случае:

{  
  "status" : "2", 
  "error_code" : "702" 
}

Прием платежей в мобильных социальных приложениях

В мобильных социальных приложениях JS API не работает. Поэтому вместо вызова функции payments.showDialogjs надо направить пользователя на специальную страницу:

https://m.my.mail.ru/cgi-bin/app/paymentm

На страницу оплаты надо передать следующие GET-параметры:

Имя Тип Описание
appid int идентификатор вашего приложения; обязательный параметр
session_key string сессия текущего пользователя
service_id unsigned int идентификатор услуги; для каждой услуги должен быть постоянным и не 0; обязательный параметр
service_name string название услуги в именительном падеже; не более 40 символов; кодировка UTF-8; обязательный параметр
mailiki_price int стоимость услуги в мэйликах
mob int признак мобильного платежного окна; должен равняться 1

Пример адреса страницы оплаты:

https://m.my.mail.ru/cgi-bin/app/paymentm?appid=11111&service_id=1000&service_name=name&mailiki_price=5&mob=1

После оплаты пользователь сможет вернуться в ваше приложение, а ваш скрипт оказания услуг будет вызван биллингом так же, как и при оплате в «большом» Моем Мире.

Рекомендации по формированию цен

Вы сами определяете политику ценообразвания на предлагаемые в приложении виртуальные товары и услуги, управляя ценой с помощью параметра mailiki_price при вызове функции payments.showDialogjs. Вы вправе выставить любое сочетание этих цен, можете делать скидки пользователям в зависимости от различных условий: времени суток, половой принадлежности, активности, достигнутого уровня и т.д.

Необходимые функции API

Руководства