С вас — идеи монетизации стриминга и реализация на API Яндекс.Денег, с нас — аудитория, реклама и деньги.

Шестой день рождения API переводов мы решили отпраздновать антихакатоном, на котором любой желающий может попробовать свои силы в борьбе за джекпот. Помимо денежного приза в 100 000 рублей мы поделимся с победителем прибылью от переводов через Яндекс.Деньги.

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

Как принять участие: нужно разработать готовое к использованию решение для сбора денег за стриминг в Сети.

Зачем это вообще нужно: количество сервисов с потоковой передачей платного контента стабильно растет, а удобного способа получения денег для них пока нет. По крайней мере такого, который был бы удобен не только владельцу сервиса, но и пользователям.

Насколько свободно творчество: в решении должны быть задействованы платежи через API Яндекс.Денег, все остальное — на ваше усмотрение. Жюри из экспертов компании выберет лучшее решение, а его авторы получат приз в 100 000 рублей и смогут забрать комиссию 0,5 % с каждой операции своего сервиса.

Когда будем подводить итоги: готовые прототипы и ваши анкеты мы принимаем до 1 августа 2017.

API позволяет выполнять следующие задачи:

• запрашивать баланс;

  
  

• просматривать историю операций;

  
  

• переводить деньги между кошельками;

  
  
• пополнять электронный кошелек с банковской карты.

Чтобы вам было проще погрузиться в решение задачи, разберем на примерах популярные сценарии использования API.

#1 Запрос доступа к операциям в кошельке

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

К слову, авторизация приложений в Яндекс.Деньгах соответствует следующим спецификациям:

• The OAuth 2.0 Authorization Framework
• The OAuth 2.0 Authorization Framework: Bearer Token Usage

Зарегистрируйте приложение и укажите его параметры. В качестве Redirect URI задайте адрес, на который Яндекс.Деньги будут отправлять пользователя после успешной OAuth-авторизации. После этого вы получаете свой уникальный идентификатор client_id.

Теперь можно запрашивать права на проведение необходимых нам действий с кошельками пользователей. Пример запроса авторизации с правом просмотра истории операций кошелька:

POST /oauth/authorize HTTP/1.1
Host: money.yandex.ru
Content-Type: application/x-www-form-urlencoded
Content-Length: 191

client_id=ABCDEFGHIJKLMNOPQRSTUVWXYZ0123456789ABCDEFGHIJKLMNOPQRSTUVWXYZ01&response_type=code&redirect_uri=https%3A%2F%2Fclient%2Eexample%2Ecom%2Fcb&scope=account%2Dinfo%20operation%2Dhistory

По запросу авторизации пользователь перенаправляется на страницу аутентификации, где вводит логин-пароль и может подтвердить или отклонить перечень запрошенных прав:

Интерфейс авторизации.

Результат авторизации возвращается как HTTP 302 Redirect – приложение перенаправит пользователя на адрес Redirect URI, который разработчик указал в параметрах запроса. Значение Redirect URI должно совпадать с настройками приложения, допуская возможность добавить в конце строки какие-либо дополнительные параметры. В адресе перенаправления с успешным результатом авторизации содержится параметр code — временный токен авторизации.

HTTP/1.1 302 Found
Location: https://client.example.com/cb?code=i1WsRn1uB1ehfbb37

Последний шаг – получение токена, для которого назначен определенный набор прав. После этого приложение меняет временный токен на токен авторизации, который разработчик будет использовать для доступа к информации в кошельке:

POST /oauth/token HTTP/1.1
Host: money.yandex.ru
Content-Type: application/x-www-form-urlencoded
Content-Length: 421

code=0DF3343A8D9C7B005B1952D9B933DC56ACB7FED6D3F2590A6FD90EC6391050EDFFCC993D325B41B00F58E5383F37F6831E8F415696E1CF07676EE8D0A3655CDD7C667189DFB69BFDB7116C0329303AB2554290048BAF9B767B4C335BF0E85830AC017AD2F14D97F529893C202D3B2C27A61EE53DC4FB04DAE8E815DE2E3F865F&client_id=ABCDEFGHIJKLMNOPQRSTUVWXYZ0123456789ABCDEFGHIJKLMNOPQRSTUVWXYZ01&grant_type=authorization_code&redirect_uri=https%3A%2F%2Fclient%2Eexample%2Ecom%2Fcb

А вот такой ответ придет при успешном обмене временного токена:

HTTP/1.1 200 OK
Content-Type: application/json
Content-Length: 293
Cache-Control: no-store

{
"access_token":"410012345678901.0123456789ABCDEFGHIJKLMNOPQRSTUVWXYZ0123456789ABCDEFGHIJKLMNOPQRSTUVWXYZ0123456789ABCDEFGHIJKLMNOPQRSTUVWXYZ0123456789ABCDEFGHIJKLMNOPQRSTUVWXYZ0123456789ABCDEFGHIJKLMNOPQRSTUVWXYZ0123456789ABCDEFGHIJKLMNOPQRSTUVWXYZ0123456789ABCDEFGHIJKLMNOPQRSTUVWXYZ0123"
}

Access_token является симметричным секретом, поэтому разработчику приложения стоит предпринять дополнительные меры по его защите: хранить токен в зашифрованном виде, предоставлять доступ только при успешном прохождении владельцем аутентификации.

#2 Просмотр истории операций

Когда токен получен, разработчик может использовать его для авторизованных действий с кошельком. Напомню, что конкретно эта авторизация позволила просматривать историю в кошельке пользователя.

Самый простой пример из области краудфандинга в соцсетях: некое сообщество ВКонтакте, посвященное футболу, — подписчиков много и активность хорошая, но это сделанный на досуге проект, а не цель жизни. Одно время паблик проводил встречи подписчиков и через электронный кошелек администратора собирал на эту и прочие нужды деньги. Для большей прозрачности распределения поступивших денег администратор создал таблицу и подтянул туда данные об истории операций через API. Когда кто-то отправляет в кошелек деньги, то все видят детали операции, отправителя и цель перевода.

Для просмотра данных воспользуемся методом operation-history, позволяющим персонализировать запрос разработчика. На выходе получим, например, последние 10 транзакций, или операции за последние полгода, или только расходные операции. Все зависит от аппетита пользователей, для которых разработчик создает сервис.

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

Пример запроса на получение пяти последних входящих зачислений в кошелек выглядит так:

POST /api/operation-history HTTP/1.1
Host: money.yandex.ru
Authorization: Bearer 410012345678901.7EE34A50588723226C886A475AD1D415471BF687CCC2AFC7664BA12F4EC2BDBA1EB82625E49BC29D114A6C6AF12F87639A877E81A5B77B81F003A9DB4CCEB9BD80C6E70B157C18410E884465276AACBD58C2D7B6022CBDFD0004B80704E82D3F0E4039A29655EFAA44F037D6BF763B0B803329FE8A0E511057173B04341C4317
Content-Type: application/x-www-form-urlencoded

records=5&type=deposition

Вот что на это может ответить сервис Яндекс.Денег:

{
  "next_record": "5",
  "operations": [

    {
      "operation_id": "548936732440013012",
      "title": "Перевод с банковской карты",
      "amount": 1.96,
      "direction": "in",
      "datetime": "2017-05-24T10:25:32Z",
      "label": "123007",
      "status": "success",
      "type": "deposition"
    },

    {
      "pattern_id": "p2p",
      "operation_id": "1097872036856016025",
      "title": "Перевод от 410012345678902",
      "amount": 0.99,
      "direction": "in",
      "datetime": "2017-05-24T10:13:38Z",
      "status": "success",
      "type": "incoming-transfer"
    },

    {
      "operation_id": "548428048231013012",
      "title": "Перевод с банковской карты",
      "amount": 1.96,
      "direction": "in",
      "datetime": "2017-05-18T13:07:28Z",
      "status": "success",
      "type": "deposition"
    },

    {
      "operation_id": "548427906481013012",
      "title": "Перевод с банковской карты",
      "amount": 1.96,
      "direction": "in",
      "datetime": "2017-05-18T13:05:06Z",
      "status": "success",
      "type": "deposition"
    },

    {
      "pattern_id": "p2p",
      "operation_id": "1096319740674326025",
      "title": "Перевод от 410012345678903",
      "amount": 0.01,
      "direction": "in",
      "datetime": "2017-05-15T10:37:50Z",
      "status": "success",
      "type": "incoming-transfer"
    }
  ]
}

Еще один пример сервиса на основе запроса к истории — коллективные закупки на форумах: люди договариваются скинуться и заказать что-то оптом по более низкой цене, а организатор собирает деньги на свой кошелек. Чтобы все видели, сколько участников в закупке и как расходуются деньги, можно использовать один из множества сервисов на базе API Яндекс.Денег. Сборщику достаточно авторизоваться кошельком в одном из таких сервисов.

#3 Проверка баланса

Игровые стримеры часто работают с несколькими мониторами, поэтому команда Яндекс.Денег разработала виджет, в котором можно указать цель сбора денег, необходимую сумму – и отслеживать прогресс. Например, стример хочет купить новую PlayStation 4. Как только в кошельке наберется нужная сумма, Яндекс.Деньги пришлют в виджет уведомление, что пора делать заказ.

Виджет накопления.

Другой пример, когда стриминговому сервису нужен постоянный доступ к балансу — программа лояльности: в личном кабинете стримера, к примеру, можно разместить пиццерийный оффер со скидкой, по которому можно мгновенно заказать пиццу. Но перед этим сервис должен убедиться, что денег на счете достаточно для заказа.

Для просмотра баланса можно воспользоваться методом account-info:

POST /api/account-info HTTP/1.1
Host: money.yandex.ru
Authorization: Bearer 410012345678901.1578E01607EB3899853D2883E47841A195BC561F1F8CF479D593B662AD60B2D146EE49F02D750CB2972E51E0DF10369AE77FD930D82B7563AA0D65FA709A7C31EB59D4FFC1F2E85A14A817BDFB282C5A82FF1B79C65D2AE7B3BAE1C1C7D89CBE80477FF1C51A8F3DD9A032475BE629235949B7A2CA7823AC6AC06DB3176F9B54
Content-Type: application/x-www-form-urlencoded

В ответ сервер вернет следующее:

{
  "account": "410012345678901",
  "balance": 192.45,
  "currency": "643",
  "account_type": "professional",
  "identified": true,
  "account_status": "identified",
  "cards_linked": [
    {
      "type": "MasterCard",
      "id": "4005641800",
      "pan_fragment": "532130******2227"
    }
  ],
  "balance_details": {
    "total": 192.45,
    "available": 192.45,
    "blocked": 1
  }
}

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

#4 Перевод из кошелька

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

Как это работает:

1. После получения подтверждения от пользователя, API попробует списать из кошелька запрошенную сумму.

   
   

2. Если денег на балансе не хватает, сервис ответит not_enough_funds.

   
   
3. Далее сервис может списать деньги с привязанной к кошельку карты, если пользователь это разрешил. Автоматическое списание с привязанной карты доступно только получателям-юрлицам. Кроме того, списать деньги с карты не получится при переводе между кошельками.

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

Подписка выглядит следующим образом:

1. Рядом с кнопкой «Поддержать» может стоять галка «Подписаться на ежемесячный платеж в пользу этого стримера».

   
   
2. Когда пользователь нажимает на кнопку «Поддержать», разработчик проверяет условие регулярных платежей и корректирует список запрашиваемых прав в запросе к Яндекс.Деньгам.

Поскольку речь идет об операции в кошельке, нужно запросить разрешение на ее проведение – запрос на предоставление доступа остается практически как в примере №1, но меняется набор прав (scope).

Набор запрашиваемых прав, который позволяет совершить единовременный перевод на сумму 1000 рублей в кошелек 410012345678901, выглядит следующим образом:

payment.to-account("410012345678901").limit(,1000)

Если же отправитель подписался на регулярные платежи, авторизация может иметь следующее значение:

payment.to-account("410012345678901").limit(30,1000)

Где 30 — период времени в сутках, 1000 — общая сумма платежей за период.

Пример запроса на регулярное списание:

POST /oauth/authorize HTTP/1.1
Host: money.yandex.ru
Content-Type: application/x-www-form-urlencoded

client_id=49414287408917F4BC735301F4731878533F409F3BA8EA055D0D441EE002F69B&redirect_uri=http%3A%2F%2Fexample.com%2Fapi%2Fredirect_uri.php&response_type=code&scope=payment.to-account(%22410012345678903%22).limit(30%2C1000)

Отправитель же увидит красивую форму:

После получения токена разработчику нужно выполнить списание через методы request-payment и process-payment:

POST /api/request-payment HTTP/1.1
Host: money.yandex.ru
Content-Type: application/x-www-form-urlencoded
Authorization: Bearer 410012345678901.D2E0917C3E09DE474DD3BF6288DDCB6818D55B6BBC8A9386ABA2A983F3F4666102F9B7A2D370D7079891299907368389F3BA8E2BE04597DCFF4CF02F4E3423896776D1C5CCE30A09B5D2E73874C5FE33CAE19286EAB03D146B46A188939BEC1ADA93F3530ECBFACA2591715F686EDBC9F616A7BF912CF4DC9CFB689473328347

pattern_id=p2p&to=410012345678903&amount=10&comment=Transfer+to+Nuke73&message=Transfer+from+SuperMan

Пример ответа:

{
  "status": "success",
  "request_id": "333235373335343733345f646366303562383436613661306133373130663766343166303137666131336262656637353539655f323537353532373836",
  "recipient_identified": true,
  "multiple_recipients_found": false,
  "recipient_account_type": "professional",
  "recipient_account_status": "identified",
  "contract_amount": 10,
  "money_source": {
    "cards": {
      "allowed": false
    },

    "wallet": {
      "allowed": true
    },

    "card": {
      "allowed": "false"
    }
  }
}

К слову о переводах и комиссиях. В личном кабинете можно выбрать, кто платит комиссию за перевод – за это отвечают параметры amount и amount_due. Если в шаблоне платежа указан параметр amount_due, то именно эта сумма поступит в кошелек стримера (комиссию оплачивает зритель). Если же стример готов взять её на себя, то на входе указывается параметр amount. Таким образом, amount (сумма к переводу) равняется сумме комиссии и amount_due (сумма к получению).

Перевод выполняется после вызова метода process-payment уже без участия пользователя, который один раз при авторизации доступа подтвердил свои намерения. В качестве request_id используется идентификатор из ответа метода request-payment.

POST /api/process-payment HTTP/1.1
Host: money.yandex.ru
Content-Type: application/x-www-form-urlencoded
Authorization: Bearer 410012345678901.D2E0917C3E09DE474DD3BF6288DDCB6818D55B6BBC8A9386ABA2A983F3F4666102F9B7A2D370D7079891299907368389F3BA8E2BE04597DCFF4CF02F4E3423896776D1C5CCE30A09B5D2E73874C5FE33CAE19286EAB03D146B46A188939BEC1ADA93F3530ECBFACA2591715F686EDBC9F616A7BF912CF4DC9CFB689473328347

request_id=333235373335343733345f646366303562383436613661306133373130663766343166303137666131336262656637353539655f323537353532373836

Пример ответа:

{
  "status": "success",
  "payer": "410012345678901",
  "payee": "410012345678903",
  "credit_amount": 9.95,
  "payment_id": "549038975018120011"
}

Отлично – списание с кошелька прошло успешно.

#5 Перевод с банковской карты

Перевод с банковской карты отличается от перевода из кошелька:

• Во-первых, он не требует запроса на авторизацию. Чтобы идентифицировать приложение для оплаты картами, разработчик регистрирует в Яндекс.Деньгах его копию и получает instance_id с помощью одноименного метода;

  
  
• Во-вторых, отправителю где-то нужно указать реквизиты своей банковской карты. Чтобы отображать эту форму, разработчику нужно сформировать платеж на основе стандартизированного шаблона методом request-external-payment, а затем инициировать платежную операцию с помощью process-external-payment.

Если перевод сформировался успешно, метод request-external-payment вернет следующее:

{
  "status": "success",
  "title": "Перевод на счет 410011498692222",
  "contract_amount": 102.04,
  "request_id": "333235373135303437315f36313764393332336462393164373433353264303465346432626262313465353933363763333133",
  "money_source": {
    "payment-card": {}
  }
}

После получения request_id – уникального идентификатора контекста платежа – можно инициировать платежную операцию и перенаправить пользователя на форму Яндекс.Денег. Для этого используется POST-запрос по адресу acs_uri с параметрами acs_params, где плательщику нужно указать данные банковской карты.

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

POST /api/process-external-payment HTTP/1.1
Host: money.yandex.ru
Content-Type: application/x-www-form-urlencoded

request_id=333235373135303437315f36313764393332336462393164373433353264303465346432626262313465353933363763333133&instance_id=hh2CVJWrU9uU7N2hpEh1LvjfyBAby8USyMUEF4DM8AS6w93o53M3xrlGHsMUiWTL&ext_auth_success_uri=http%3A%2F%2Fexample.com%2Fsuccess%2F&ext_auth_fail_uri=http%3A%2F%2Fexample.com%2Ffalse%2F&request_token=false

И ответ:

{
  "status": "ext_auth_required",
  "acs_uri": "https://m.money.yandex.ru/internal/public-api/to-payment-type",
  "acs_params": {
    "cps_context_id": "333235373135303437315f36313764393332336462393164373433353264303465346432626262313465353933363763333133",
    "paymentType": "FC"
  }
}

Карточная форма Яндекс.Денег.

Непосредственное проведение платежа ложится на плечи Яндекс.Денег. После указания реквизитов банковской карты и нажатия на кнопку «Заплатить» пользователь попадет на страницу 3-D Secure своего банка-эмитента и после ввода пароля возвращается к сервису разработчика: если 3-D Secure-аутентификация по банковской карте завершается успешно, он попадет на страницу с подтверждением платежа (ext_auth_success_uri). Если же банк-эмитент отказал в аутентификации, пользователь перенаправляется на страницу с ошибкой (ext_auth_fail_uri).

Адреса перенаправления разработчик может указать при вызове метода process-external-payment.

Когда плательщик переходит на страницу успеха после проверки 3-D Secure, нужно удостовериться что авторизация по банковской карте тоже прошла успешно. Для этого разработчик повторно вызывает process-external-payment с ранее полученным request_id.

Пример ответа:

{
  "status": "success",
}

Обычно авторизация карты происходит в промежутке 10-20 секунд после аутентификации. Если в момент повторного вызова process-external-payment мы не получили состояние авторизации от банка, разработчик об этом обязательно узнает.

Пример подобного ответа:

{
 "status": "in_progress", 
 "next_retry": "5000"
}

Next_retry — рекомендуемое время в миллисекундах, когда следует повторить запрос. Поле присутствует только при статусе in_progress.

Дополнительные возможности: конструктор форм и кнопок

Платежное решение с использованием API требует определенных усилий и сложного технологического взаимодействия. Более простой вариант заключается в использовании готовых настраиваемых форм Яндекс.Денег: в них информация о переводе разбита на параметры и передается методом POST на специальный адрес.

Пример интерфейса формы переводов в кошелек стримера на Яндексе.

Сценарий перевода с использованием кастомизированной формы выглядит так:

1. Отправитель выбирает, как перевести деньги — из электронного кошелька или с банковской карты.

   
   

2. Разработчик формирует строку из набора параметров Яндекс.Денег и передает их методом POST на адрес money.yandex.ru/quickpay/confirm.xml вместе с уникальной меткой платежа (label) для дальнейшей идентификации. Детали операции разработчик хранит в своей базе.

   
   

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

   
   

4. Получатель узнает о поступлении средств через HTTP-уведомление, email, SMS, push. Адрес обработчика уведомлений получателю нужно заранее указать в настройках кошелька.

   
   
5. Разработчик анализирует поступившие на адрес обработчика детали и принимает решение о дальнейших действиях. В нашем случае, если входящая сумма удовлетворяла условиям стримера, в его видеопотоке передавалось сообщение подписчика с анимированным сопровождением. Сообщение воспроизводилось с использованием технологии SpeechKit.

В этом сценарии есть один недостаток: для нормальной работы сервиса от стримера требуются лишние манипуляции с настройками HTTP-уведомлений внутри кошелька.

В отличии от API, формы и кнопки позволяют переводить деньги с привязанной банковской карты. Однако комиссия берется только с получателя.

Чтобы не требовать от стримера лишних манипуляций, достаточно научиться смотреть в его историю операций и сопоставлять уникальную метку перевода с данными из базы. Осталось только получить доступ к операциям стримера, для чего в самом начале статьи мы попросили стримера подтвердить доступ к правам account-info и operation-history. Первый метод поможет нам узнать номер кошелька стримера, второй — информацию по операциям.

Вот так выглядит ответ на запрос последних двух операций в кошельке стримера через API методом operation-history (перевод поступил через кастомизированную форму):

{
  "next_record": "2",
  "operations": [
    {
      "operation_id": "549575176734053012",
      "title": "Перевод с банковской карты",
      "amount": 49,
      "direction": "in",
      "datetime": "2017-05-31T19:46:16Z",
      "label": "yadonate#1782",
      "status": "success",
      "type": "deposition"
    },

    {
      "pattern_id": "p2p",
      "operation_id": "1098088627442030025",
      "title": "Перевод от 410011498790000",
      "amount": 9.95,
      "direction": "in",
      "datetime": "2017-05-25T16:18:33Z",
      "label": "testpayment",
      "status": "success",
      "type": "incoming-transfer"
    }
  ]
}

После проверки успешности перевода в кошелек стримера можно творить в видеопотоке любимую вами магию.

В этом посте мы рассмотрели только самые базовые идеи и сценарии использования API для стриминговых сервисов. Если что-то непонятно, смело спрашивайте в комментариях. А если среди читателей есть стримеры или их зрители — поделитесь мнением о том, как сделать донаты удобнее и веселее.

Зарегистрироваться для участия можно на Яндекс.Событиях. Прототипы и анкеты принимаем до 1 августа 2017.

От винта!