Введение

Цель системы внутриигровых платежей состоит в том, чтобы у разработчиков была возможность продавать свои товары пользователям, а пользователи при этом не пришлось покидать игровой процесс. При этом решение о том, что именно продаётся, принимает продавец. Это могут быть внутриигровые предметы, такие как оружие или боеприпасы, игровая валюта — монеты или золото, или даже наряды для персонажей. В игре может быть столько предметов, сколько сочтёт нужным разработчик, и они могут продаваться как по одному, так и собранными в наборы. В Steam нет ограничений на то, что и как продавать, равно как и запретов на использование играми иных механизмов продаж предметов. Задача состоит в том, чтобы пользователь в игре столкнулся со знакомым ему по платформе Steam платежным интерфейсом и не испытал проблем при покупке ваших продуктов с помощью средств кошелька Steam. Благодаря подобной интеграции у любой игры будет немедленный доступ к новым пользователям Steam и новым методам оплаты, как только они становятся доступными.

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

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

1. Получение уведомлений о неудачных попытках оплаты.
   
2. Возврат средств и отслеживание статуса транзакции через веб-интерфейс.
   
3. Доступ к подробным отчётам о продажах игр и предметов на партнёрском сайте в режиме реального времени.

Рекомендации

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

Рекомендации изложены в соответствующем разделе документации.

Обзор системы платежей

Система платежей представляет собой комбинацию внедрённого в игру процесса покупки, веб-службы расчётов Steam и процесса одобрения пользователем.

Далее описана последовательность действий при совершении покупки. Пользователь всегда сам начинает и завершает процесс покупки в игре.

1. Когда пользователь решает приобрести что-то в игре, игра посылает запрос на расчётный сервер. Расчётным сервером может быть любая служба, которую использует игра для управления запросами о покупке, к примеру, веб-сервер или система аутентификации. Общение между расчётными серверами Steam и игровым расчётным сервером происходит по протоколу HTTP. Игровой расчётный сервер может запрашивать информацию о стране, языке и валюте пользователя. Эти данные могут быть использованы для корректировки цен по усмотрению разработчика.
   
2. Игровой расчётный сервер затем посылает веб-службе Steam запрос на транзакцию от имени клиента. При запросе используется защищённый метод POST (HTTP). В содержимое запроса входят метаданные пользователя, описание и стоимость каждого приобретаемого предмета.
   
3. Получив запрос, Steam автоматически открывает оверлей и показывает пользователю диалоговое окно со всеми предметами, их стоимость и кнопку для подтверждения или авторизации транзакции. Если у пользователя недостаточно средств, оверлей проведёт его через процесс пополнения кошелька. Оверлей отвечает за сбор платёжной информации пользователя. По завершении процесса пользователь получит уведомление о том, что транзакция либо прошла, либо отклонена. Игра должна запросить полученное пользователем уведомление и переслать его на расчётный сервер.
   
4. После получения уведомления игровой расчётный сервер отправляет в Steam запрос FinalizeTransaction для завершения операции. Утвердительный ответ означает, что с пользователя списаны средства, а предметы могут быть переданы пользователю.

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

1. Пользователь решает приобрести что-то в игре или на сайте. Если в игре, запускается браузер с веб-страницей.
   
2. Расчётный сервер отправляет HTTP POST-запрос на проведение транзакции от имени пользователя. Если ответ утвердительный, пользовательскую сессию нужно перенаправить на страницу с уникальным URL, где пользователь может авторизовать транзакцию. При перенаправлении должна быть указана ссылка, куда пользователь возвращается после завершения авторизации.
   
3. Когда пользователь направляется назад на сайт, расчётный сервер запрашивает статус транзакции, и если она авторизована, сервер отправляет в Steam запрос FinalizeTransaction для завершения операции.

Установка связи

Подготовка

Сначала необходимо создать издательский ключ для веб-API. Инструкции приведены в соответствующем разделе документации. Этот ключ передается со всеми запросами сервера и используется для аутентификации этих запросов. Он отправляется как параметр key=.

Хранение информации о заказах

Необходимо хранить данные о заказах для последующих обращений к ним в случае необходимости. Для отсылки к транзакциям в Steam нужно использовать уникальный 64-битный ID заказа.

Отправка запросов

Все запросы необходимо отправлять, используя методы GET или POST протокола HTTP 1.1, с соединением, защищённым протоколом TLS. Content-Type должен быть указан как "application/x-www-form-urlencoded", а параметры POST должны содержаться в теле запроса в стандартном формате URL-кодирования. Текст должен быть в UTF-8.

Запросы проходят через следующий базовый URI:
https://partner.steam-api.com/ISteamMicroTxn/*

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

По умолчанию ответы возвращаются в формате JSON. По желанию можно указать формат XML, добавив параметр "format=xml" к запросу.
Внимание: схема JSON или XML должна быть гибкой, чтобы параметры могли быть отправлены и возвращены в произвольном порядке.

Тестирование

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

Запросы в тестовой среде проходят через другой базовый URI:
https://partner.steam-api.com/ISteamMicroTxnSandbox/*

Инструкция по интеграции

Внутриигровые покупки

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

• Шаг 1
  В игре должен поддерживаться API Steamworks. Это означает, что продукт должен включать заголовочный файл, связанный файл .lib, а также .dll. Инструкции по настройке доступны в разделе Обзор API Steamworks. Прежде чем продолжить, необходимо инициализировать API Steamworks!
  
• Шаг 2
  Когда пользователь решил приобрести один или несколько предметов в игре и указал их, необходимо получить определенные метаданные о пользователе:
  
  • SteamID: 64-битное число, уникальный идентификатор пользователя в системе Steam.
    
  • Код страны: страновой код стандарта ISO 3166 — страна, откуда пользователь совершает покупку. Использование кода необходимо для определения цены покупки.
    
  • Код валюты: код стандарта ISO 4217 — валюта, в которой будут списаны средства.
    
  • Код языка игрового клиента: код стандарта ISO 639-1 — язык, на котором запущен игровой клиент Steam.
    
  
  Данные о SteamID и языке могут быть получены при вызове следующих функций API Steamworks:
  
  • ISteamUser::GetSteamID
    
  • ISteamApps::GetCurrentGameLanguage
    
  
  Данные о стране и валюте пользователя могут быть получены при передаче SteamID пользователя в веб-API запросе ISteamMicroTxn/GetUserInfo.
  
  Эти метаданные пользователя должны быть собраны и отправляться вместе со стандартными данными о покупке на расчётный сервер.
  
• Шаг 3
  Расчётный сервер игры отправляет веб-службе Steam запрос на транзакцию от имени клиента Steam. Используйте описанную ниже функцию ISteamMicroTxn/InitTxn. При запросе необходимо отправить следующие данные:
  
  • OrderID: 64-битное число, которое присваивается покупке разработчиком и является ключом к транзакции. Оно используется как референтное значение в системе Steam.
    
  • SteamID: ID пользователя, полученный от клиента Steam в п. 3.
    
  • AppID: уникальный идентификатор приложения в Steam.
    
  • Язык: код стандарта ISO 639-1 — язык, используемый для отображения информации о предметах.
    
  • Валюта: код стандарта ISO 4217 — валюта, используемая для отображения информации о цене предметов. Если она не соответствует коду валюты пользователя, указанному во втором шаге, будет произведена автоматическая конвертация валюты по текущему рыночному курсу. Steam покажет пользователю цену после конвертации в местной валюте. Чтобы обеспечить наилучшее качество обслуживания, рекомендуем указывать цену в каждой валюте, которой ваши клиенты могут пользоваться.
    
  • Список предметов, которые хочет приобрести пользователь. Для каждого предмета указываются следующие данные:
    
    • ItemID: 32-битное число — присваиваемый разработчиком предмету идентификатор.
      
    • Количество: число предметов данного типа в транзакции.
      
    • Сумма: размер оплаты (в сотых долях единицы валюты) за приобретаемые предметы. Для некоторых валют должна быть указана полная стоимость. См. раздел Поддерживаемые валюты. Если приобретаемых предметов больше одного, данное значение равно произведению количества предметов и стоимости одного предмета.
      
    • Описание предмета: текстовое описание предмета, которое показывается пользователю в окне авторизации транзакции. Описание может быть переведено на основании данных о языке клиента Steam.
      
    • Категория предмета: необязательное текстовое описание категории, к которой относится предмет. Это значение используется для группирования данных во внутренних отчетах о продажах. Пользователю его показывать не нужно.
      
  
  Если транзакция принята Steam, клиент Steam автоматически уведомляется о необходимости авторизации покупки. Если возникает ошибка, проблему необходимо устранить, а транзакцию инициировать заново.
  
• Шаг 4
  При утвердительном ответе на запрос ISteamMicroTxn/InitTxn во внутриигровом оверлее пользователя будет показано уведомление о том, что ему нужно авторизовать транзакцию. На экран пользователя выводятся детали покупки, которые были отправлены в запросе. После этого пользователь может авторизовать транзакцию. Если у него при этом не хватает средств на покупку, Steam автоматически проведет пользователя через процесс пополнения кошелька. В конце концов игра получит уведомление, что транзакция авторизована или отклонена.
  
  Для получения уведомления об одобрении покупки или об отказе от неё необходимо создать обработчик обратного вызова ISteamUser::MicroTxnAuthorizationResponse_t. Результат обратного вызова содержит такие данные как AppID, OrderID и состояние авторизации транзакции. Игра может отправить этот результат на расчётный сервер, чтобы он смог завершить операцию. Подробное описание функций обратных вызовов доступно в соответствующем разделе документации.
  
• Шаг 5
  Для завершения транзакции расчётный сервер вызывает ISteamMicroTxn/FinalizeTxn со следующими параметрами:
  
  • OrderID: номер заказа, который был создан при инициализации транзакции.
    
  • AppID: уникальный идентификатор приложения.
    
  
  Утвердительный ответ означает, что покупка одобрена и предметы необходимо передать пользователю. Ответ с ошибкой означает, что покупка не состоялась. В этом случае будет показано соответствующее описание ошибки.
  
• Шаг 6
  Расчётному серверу нужно будет регулярно вызывать веб-API ISteamMicroTxn/GetReport, чтобы получать уведомления об изменениях статусов обработки платежей. Вызывать этот API следует как минимум раз в день, чтобы согласовать изменения в завершённых транзакциях, однако можно вызывать его и каждую минуту, чтобы фиксировать на серверах все изменения платежей.
  
  При необходимости вы можете использовать веб-API ISteamMicroTxn/RefundTxn для возвратов средств пользователям. При этом есть и другие способы отмены транзакций, которые потребуют вашего внимания. Если транзакция получает статус отмены (например, Refunded, PartialRefund, Chargedback, RefundedSuspsectedFraud или RefundedFriendlyFraud — см. подробнее), ваш внутренний сервер должен попытаться вернуть товары, связянные с этой транзакцией, если это возможно. Подробнее о мерах предотвращения наиболее распространённых видов мошенничества можно прочитать в документации.

Покупка через веб-службу

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

• Шаг 1
  Получите SteamID пользователя.
  
  • Если у пользователя запущена игра, для получения SteamID можно использовать ISteamUser::GetSteamID.
    
  • Если пользователь зашел на сайт, для получения SteamID используется API OpenID. Подробное описание OpenID приведено в соответствующем разделе документации.
    
  
  Обратите внимание: мы рекомендуем привязывать игровой аккаунт пользователя к SteamID, чтобы вход в аккаунт требовался только один раз.
  
• Шаг 2
  Получите данные о стране и валюте пользователя с помощью функции ISteamMicroTxn/GetUserInfo, которой нужно передать SteamID пользователя. Эти данные используются для определения верных цен и валют, которые нужно показать пользователю.
  
  Обратите внимание: у GetUserInfo есть необязательный параметр IP-адрес, который может использоваться для передачи в Steam информации о том, где находится пользователь. Отправляйте информацию о публичном IP-адресе пользователя со всеми покупками через веб-службу, а также всегда, когда пользователь вошёл в игру не через клиент Steam.
  
• Шаг 3
  Расчётный сервер игры отправляет запрос на проведение транзакции через веб-службу Steam, используя ISteamMicroTxn/InitTxn. Помимо описанных выше параметров, необходимых для проведения транзакции, требуется передать два дополнительных элемента данных:
  
  • usersession: этот параметр должен быть установлен в значение "web", показывающее, что пользователь будет авторизовывать транзакцию через браузер.
    
  • ipaddress: публичный IP-адрес пользователя.
    
  
  Если параметр usersession установлен в значение web, запрос InitTxn вернет дополнительный параметр steamurl. Это уникальная ссылка, куда необходимо перенаправить пользовательскую сессию, и которая идентифицирует транзакцию, созданную этим вызовом API.
  
  
• Шаг 4
  Расчётный сервер игры перенаправляет пользовательскую сессию по ссылке от Steam, которая получена от InitTxn. Вместе с перенаправлением, задайте еще одну ссылку, куда пользователь вернется после того, как авторизует или отклонит транзакцию. Используйте полную ссылку (к примеру, http://www.steamgames.com) в следующей форме:
  returnurl=ваша_ссылка
  Когда пользователь будет перенаправлен в Steam, перед аутентификацией ему потребуется войти в свой аккаунт. Если пользователь выбрал Steam в качестве платёжного средства на вашем сайте, он будет ожидать это поведение. Однако если пользователь ранее уже вошёл в Steam и играл в игру, логично пропустить повторный вход в аккаунт. Это можно сделать с помощью встроенного в игровой оверлей веб-браузера. Когда браузер оверлея используется для авторизации, пользователь войдёт в аккаунт автоматически. Для запуска браузера используйте
  ISteamFriends::ActivateGameOverlayToWebPage
  
  Более подробно игровой оверлей описан здесь.
  
• Шаг 5
  Когда пользователь возвращается на сайт, вызовите ISteamMicroTxn/QueryTxn для получения результатов. Если статус заказа — Approved (одобрен), спишите средства, вызвав ISteamMicroTxn/FinalizeTxn. Откажитесь от транзакции, если у заказа будет любой другой статус.
  
  Внимание: если пользователь закроет браузер, а также если произойдет что-то, что не даст пользователю вернуться на ваш сайт, откажитесь от транзакции и не вызывайте FinalizeTxn. Даже если пользователь одобрил транзакцию, но обратное перенаправление не сработало, откажитесь о транзакции и начните заново.
  
• Шаг 6
  Расчётному серверу нужно будет регулярно вызывать веб-API ISteamMicroTxn/GetReport, чтобы получать уведомления об изменениях статусов обработки платежей. Вызывать этот API следует как минимум раз в день, чтобы согласовать изменения в завершённых транзакциях, однако можно вызывать его и каждую минуту, чтобы фиксировать на серверах все изменения платежей.
  
  При необходимости вы можете использовать веб-API ISteamMicroTxn/RefundTxn для возвратов средств пользователям. При этом есть и другие способы отмены транзакций, которые потребуют вашего внимания. Если транзакция получает статус отмены (например, Refunded, PartialRefund, Chargedback, RefundedSuspsectedFraud или RefundedFriendlyFraud — см. подробнее), ваш внутренний сервер должен попытаться вернуть товары, связянные с этой транзакцией, если это возможно. Подробнее о мерах предотвращения наиболее распространённых видов мошенничества можно прочитать в документации.

Приложение A: значения статусов

ISteamMicroTxn возвращает статус со следующими возможными значениями. Значения, как правило, будут расположены в поле ответа status.

• Init - Заказ создан, но не авторизован пользователем.
  
• Approved - Заказ одобрен пользователем.
  
• Succeeded - Заказ проведен.
  
• Failed - При заказе возникла ошибка или он не был одобрен.
  
• Refunded - Средства за заказ возвращены и продукт должен быть отозван игрой. Возврат средств может быть инициирован пользователем.
  
• PartialRefund - Средства за один или несколько предметов в корзине возвращены. Проверьте поле itemstatus для получения информации о каждом предмете.
  
• Chargedback - Заказ признан мошенническим или оспорен. Продукт должен быть отозван игрой.
  
• RefundedSuspectedFraud - Valve вернула средства за заказ, поскольку он может быть мошенническим. Продукт должна отозвать сама игра.
  
• RefundedFriendlyFraud - Valve вернула средства за заказ, поскольку платёж за него оспорили мошенническим способом. Продукт должна отозвать сама игра.

Приложение B: коды ошибок

ISteamMicroTxn возвращает коды ошибок со следующими возможными значениями. Значения, как правило, будут расположены в поле ответа errorcode.

• 1. Успешно
  
• 2. Операция не проведена
  
• 3. Недопустимый параметр
  
• 4. Внутренняя ошибка
  
• 5. Пользователь не одобрил транзакцию
  
• 6. Транзакция уже совершена
  
• 7. Пользователь не вошёл в аккаунт
  
• 8. Валюта не совпадает с валютой в профиле пользователя Steam
  
• 9. Аккаунт не существует или временно недоступен
  
• 10. Транзакция отклонена пользователем
  
• 11. Транзакция отклонена, поскольку пользователь находится в стране, для которой действуют ограничения
  
• 12. Транзакция отклонена, поскольку платёжное соглашение неактивно
  
• 13. Платёжное соглашение не может быть обработано, поскольку его тип — не GAME
  
• 14. Платёжное соглашение удержано по причине спорного платежа или отзыва средств
  
• 15. Платёжное соглашение не может быть обработано, поскольку его тип — не STEAM
  
• 16. У пользователя уже есть платёжное соглашение для этой игры
  
• 100. Недостаточно средств
  
• 101. Превышен срок ожидания завершения
  
• 102. Аккаунт заблокирован
  
• 103. Аккаунту запрещено совершать покупки
  
• 104. Транзакция отклонена, поскольку выявлено мошенничество
  
• 105. Нет сохранённого метода оплаты
  
• 106. Проведение транзакции привело бы к превышению лимита, установленного платёжным соглашением
  
• 107. У пользователя есть незавершённая транзакция, которая должна быть завершена перед началом новой транзакции.

Остались вопросы?

Вы можете задать вопросы об интеграции внутриигровых покупок в соответствующем разделе обсуждений группы разработчиков Steamworks.