Руководство по монетизации приложений
Вы можете монетизировать свои приложения, принимая платежи от пользователей. Биллинг Платформы позволяет быстро интегрировать возможность приема платежей за виртуальные товары и услуги. Если вы хотите принимать платежи от пользователей, вы можете это делать только через биллинг Платформы. Если ваше приложение принимает оплату в оффлайне (например, интернет-магазин с оплатой курьеру), то такие платежи реализовывать через биллинг не обязательно.
Как подключить платежи в вашем приложении
- Зайдите в JIRA http://apiok.ru/jira/documents/, введите данные о компании, приложите необходимые документы и акцептуйте оферту (резидентам РФ) или заключите договор (нерезидентам РФ)
- Проверьте, что ваша компания проверена и одобрена (Название компании появится во вкладке «Биллинг», при этом не должно быть сообщений, что она проверяется модератором). Проверка компании занимает как правило не более 7 дней.
- Реализуйте на вашем сервере скрипт оказания услуг (см. ниже)
- Активируйте прием платежей, указав url скрипта оказания услуг во вкладке Биллинг настроек вашего приложения
- Интегрируйте прием платежей через API-функции биллинга в ваше приложение и проверьте корректность обработки платежей
- Подайте приложение на модерацию в каталог, если вы этого еще не сделали.
Вопросы и комментарии по финансовым вопросам пишите на 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:
- 701 User not found — если приложение не смогло найти пользователя для оказания услуги
- 702 Service not found — если услуга с данный идентификатором не существуем в вашем приложении
- 703 Incorrect price for given uid and service_id — если данная услуга для данного пользователя не могла быть оказана за указанную цену
- 700 Other error — другая ошибка
Разница между значением 0 и 2 параметра status следующая:
- status=0 сообщает биллингу, что у вас возникли временные трудности, например, проблемы с серверами или программным кодом; в таком случае биллинг обратится с данной транзакцией к скрипту обработки платежей снова
- status=2 означает, что вы вообще не сможете обработать данную транзакцию, например, потому что вам не удается идентифицировать пользователя; в таком случае, биллинг больше не будет обращаться с этой транзакцией к скрипту оказания услуг
Если биллинг платформы от биллинга приложения получили таймаут или 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. Вы вправе выставить любое сочетание этих цен, можете делать скидки пользователям в зависимости от различных условий: времени суток, половой принадлежности, активности, достигнутого уровня и т.д.