Огляд

Мета системи внутрішньоігрових платежів Steam — надати розробникам простий спосіб продавати довільні товари користувачам таким чином, щоби користувачі не залишали ігровий процес. Лише від продавця залежить, що він хоче продавати. Це можуть бути внутрішньоігрові предмети, як-от зброя чи спорядження, ігрова валюта (монети, золото) або ж просто вбрання для ігрового персонажа. Ви можете продавати у своїй грі стільки предметів, скільки захочете. Також можете продавати їх по одному чи комплектами по декілька. Steam не встановлює обмежень на те, що і як продавати, і не встановлює обмежень на ігрові механізми продажу. Його завдання полягає в тому, щоби привнести знайомий користувачу платіжний процес платформи Steam у вашу гру, щоби гравці легко могли витрачати кошти свого гаманця Steam на ваші продукти. За допомогою цього типу інтеграції ваша гра матиме миттєвий доступ до нових користувачів Steam і нових способів оплати, щойно ті стають доступними.

У цій системі придбання знаходиться повністю під вашим контролем. Успішна відповідь на запит про купівлю призведе до безпечного стягнення коштів із користувача та негайного сповіщення вас про цю подію. Після підтвердження придбання ви повинні надати відповідні предмети користувачу й управляти ними. Наприклад, якщо предмет дається на певний час, то ваша система повинна відстежувати час дії предмета.

Окрім підтримки внутрішньоігрових придбань, система надаватиме додаткову функціональність, яку можуть використовувати ваша бухгалтерська система та служба підтримки користувачів:

1. Ви можете отримувати сповіщення про невдалу спробу оплати.
   
2. Ви можете повертати кошти та відстежувати стан трансакції за допомогою веб-інтерфейсу.
   
3. Ви можете отримувати доступ до детальних звітів на нашому партнерському сайті, де в режимі реального часу показуються продажі предметів та ігор.

Найкращі практики внутрішньоігрових придбань

Якщо ви працюєте над продуктом із внутрішньоігровими придбаннями в Steam, то маємо для вас деякі поради, огляд найкращих практик і ресурси, що допоможуть вам розпочати. Ігри з вільним доступом та ігри, що купуються перед завантаженням, мають спільні елементи, про які варто знати до початку роботи над вашим випуском у Steam.

Дізнатися більше можна в розділі про мікротрансакції.

Як працює платіжна система

Платіжна система — це комбінація внутрішньоігрової системи придбання, веб-сервісу оплати Steam і процесу підтвердження з боку користувача.

Процес придбання описано далі. Ваш користувач завжди сам починає й завершує процес придбання у вашій грі.

1. Коли користувач вирішує щось придбати в грі, то гра посилає запит на сервер придбань. Сервером придбання може бути будь-яка служба, яку ваша гра використовує для управління запитами на придбання. Це може бути веб-сервер чи ваша система автентифікації. Комунікація між цим сервером та платіжними серверами Steam відбувається через HTTP. Ваш сервер придбань може надсилати запити до платіжних серверів Steam про країну користувача, валюту й мову. Ці дані можна використовувати для коригування вашої ціни.
   
2. Потім ваш сервер придбань ініціює трансакцію від імені клієнта й передає її до веб-служби Steam. Запит подається як захищений метод POST (HTTP). Вміст запиту включає метадані користувача, опис і вартість кожного предмета, які користувач хоче придбати.
   
3. Після отримання цього запиту Steam автоматично активує оверлей Steam і показує користувачу діалогове вікно з усіма предметами, їхню вартість і кнопку для підтвердження чи авторизації трансакції. Якщо в користувача недостатньо коштів на акаунті Steam, то оверлей проведе його через процес поповнення гаманця. Оверлей Steam збирає всю платіжну інформацію користувача. Після завершення процесу користувач отримає сповіщення, що придбання було прийняте, або було відхилене. Ваша гра повинна зареєструвати отримання зворотного виклику для цього сповіщення й перенаправити результат до вашого сервера придбань.
   
4. Ваш сервер придбань отримує сповіщення й надсилає виклик FinalizeTransaction до Steam, що завершує операцію. Успішна відповідь означає, що з користувача стягнені кошти, і ви можете передати предмети користувачу.

Як альтернативу для ігор, у яких придбання відбуваються через веб-сторінку, а також коли платформа Steam використовується як спосіб оплати на вашому сайті, ви можете інтегрувати платіжну систему через веб-оглядач. У такому випадку процес придбання відбувається наступним чином:

1. Користувач вирішує придбати щось у грі чи на вашому веб-сайті. Якщо в грі, то запускається веб-оглядач із вашою веб-сторінкою.
   
2. Ваш сервер придбань ініціює веб-трансакцію від імені користувача у формі захищеного запиту HTTP POST. У разі успіху повертається унікальний URL Steam, на який ви повинні перенаправити користувацький сеанс, де він зможе авторизувати трансакцію. Під час перенаправлення слід вказати URL, куди користувач повернеться після завершення авторизації.
   
3. Коли користувач повертається назад на ваш сайт, ваш сервер придбань запитує статус трансакції й у разі її успішної авторизації надсилає до Steam виклик FinalizeTransaction, який завершує операцію.

Установлення підключення

Підготовка

Спершу необхідно створити ключ видавця для веб-API. Інструкції можна знайти в розділі про авторизацію у веб-API. Цей ключ передається з усіма запитами веб-сервера й використовується для автентифікації цих запитів. Він надсилається як параметр key=<your key here>.

Зберігання замовлень

Зберігайте дані кожного замовлення для майбутніх звертань до них у вашій системі. Для відсилання до трансакцій у Steam використовуйте унікальний 64-бітний ідентифікатор замовлення.

Надсилання запитів

Усі запити необхідно надсилати за допомогою методів 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=xm» до запиту.
Примітка: вам слід впровадити гнучке рішення для JSON чи XML, щоби параметри могли відправлятися й надсилатися в довільному порядку.

Тестування

Steam надає розробникам середовище для тестування інтеграції. Середовище підтримує всі запити, що доступні через звичайний API, але при цьому реальні кошти з гаманця Steam тестувальника не стягуватимуться.

Запити в тестувальному середовищі відбуваються через інший базовий URI:
https://partner.steam-api.com/ISteamMicroTxnSandbox/*

Кроки інтеграції

Внутрішньоігрові придбання

Це для ігор, що мають інтегровану крамницю й користувач не виходить із гри.

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

Придбання через веб

Якщо ваша ігрова крамниця є веб-сторінкою або якщо Steam використовується як спосіб оплати для замовлень на вашому сайті, то для інтеграції потрібно здійснити наступні кроки:

• Крок 1
  Отримайте SteamID користувача.
  
  • Якщо користувач у грі, то використовуйте API Steamworks для отримання SteamID: ISteamUser::GetSteamID.
    
  • Якщо користувач на вашому сайті, то для безпечного отримання SteamID можна використати API OpenID. Подробиці OpenID можна знайти в розділі про веб-авторизацію.
    
  
  Примітка: рекомендуємо пов’язати ігровий акаунт користувача з його SteamID, щоби вхід в акаунт потрібно було робити лише один раз.
  
• Крок 2
  Отримайте країну та валюту користувача викликом веб-API ISteamMicroTxn/GetUserInfo, куди потрібно передати SteamID користувача. Ці дані можна використовувати для визначення належних цін та валют у вашій крамниці для цього користувача.
  
  Примітка: GetUserInfo має необов’язковий параметр IP-адреси, який можна використовувати для передачі в Steam інформації про розташування користувача. Надсилайте публічну IP-адресу користувача під час усіх придбань через веб-оглядач, а також завжди, коли користувач увійшов у гру не через Steam.
  
• Крок 3
  Ваш сервер придбань ініціює запит на придбання через веб-службу Steam за допомогою ISteamMicroTxn/InitTxn. Окрім описаних вище параметрів для внутрішньоігрових придбань потрібно передати ще два елементи даних:
  
  • usersession — цей параметр слід установити як «web», це означає, що користувач авторизуватиме трансакцію через веб-оглядач.
    
  • ipaddress — публічна IP-адреса користувача.
    
  
  Коли usersession установлено як «web», запит InitTxn поверне додатковий параметр steamurl. Це унікальна URL-адреса, куди слід перенаправити користувацький веб-сеанс, і котра ідентифікує створену цим викликом API трансакцію.
  
  
• Крок 4
  Ваш сервер придбань перенаправляє користувацький веб-сеанс до URL-адреси Steam, яку було повернуто у виклику API InitTxn. Разом із перенаправленням вкажіть вашу власну URL-адресу, куди користувач повернеться після того, як авторизує чи відхилить трансакцію. Використовуйте повне посилання (наприклад, http://www.steamgames.com) у такій формі:
  returnurl=ваше_посилання
  Коли користувач буде перенаправлений у Steam, перед автентифікацією йому потрібно буде ввійти у свій акаунт. Якщо користувач обрав Steam як спосіб оплати на вашому сайті, то він очікуватиме саме таку поведінку. Однак якщо користувач уже ввійшов у Steam і грав у гру, то повторний вхід варто пропустити. Це можна зробити за допомогою вбудованого в ігровий оверлей веб-оглядача. Якщо використовувати оглядач ігрового оверлея для авторизації, то користувач увійде автоматично. Для запуску веб-оглядача використовуйте виклик API Steamworks
  ISteamFriends::ActivateGameOverlayToWebPage
  
  Докладнішу інформацію можна знайти в розділі про оверлей.
  
• Крок 5
  Коли користувач повертається на ваш сайт, викличте ISteamMicroTxn/QueryTxn для отримання результатів. Якщо статус замовлення «Approved» (схвалено), то стягніть кошти за допомогою виклику ISteamMicroTxn/FinalizeTxn. Скасуйте трансакцію, якщо повернувся будь-який інший статус.
  
  Примітка: якщо користувач закриє веб-оглядач, або якщо трапиться щось, що не дасть користувачу повернутися на ваш сайт, скасуйте трансакцію й не викликайте FinalizeTxn. Навіть якщо користувач схвалив трансакцію, але зворотне перенаправлення не спрацювало, то скасуйте трансакцію й розпочніть нову.
  
• Крок 6
  Вашому серверу придбань знадобиться регулярно викликати API ISteamMicroTxn/GetReport, щоб отримувати сповіщення про зміни стану опрацювання трансакцій. Цей API слід викликати принаймні раз на день, щоб улагоджувати оновлення стану опрацювання трансакцій, проте це можна робити навіть щохвилини, щоб ваші сервери завжди мали актуальну інформацію.
  
  Ви можете на свій розсуд повертати кошти користувачам, використовуючи API ISteamMicroTxn/RefundTxn. Існують і інші шляхи скасування трансакцій, які можуть потребувати вашої уваги. Коли трансакція переходить у стан скасування (як-от Refunded, PartialRefund, Chargedback, RefundedSuspsectedFraud або RefundedFriendlyFraud — див. «Додаток А: значення стану»), ваш внутрішній сервер за можливості має спробувати повернути назад пов’язані предмети. Радимо переглянути цю документацію та пересвідчитися, що ви вжили заходів для попередження найрозповсюдженіших типів шахрайства.

Додаток А: значення стану

Це можливі значення стану, який повертається через веб-API ISteamMicroTxn. Ключ відповіді, де знаходяться ці стани, зазвичай зветься status.

• Init — замовлення створено, але не авторизовано користувачем.
  
• Approved — замовлення схвалене користувачем.
  
• Succeeded — замовлення успішно проведено.
  
• Failed — помилка замовлення або його було відхилено.
  
• Refunded — кошти за замовлення було повернено, тож продукт потрібно відкликати в грі. Повернення коштів може ініціювати користувач.
  
• PartialRefund — повернено кошти за один чи більше предметів у кошику. Перевірте поле itemstatus кожного предмета для подробиць.
  
• Chargedback — замовлення є шахрайським або сумнівним, тож продукт слід відкликати в грі.
  
• RefundedSuspectedFraud — замовлення було відшкодовано з боку Valve через підозру в шахрайстві. Продукт має бути відкликаний грою.
  
• RefundedFriendlyFraud — замовлення було відшкодовано з боку Valve через відкликання коштів із боку покупця (т.зв. «дружнє шахрайство»). Продукт має бути відкликаний грою.

Додаток Б: коди помилок

Це можливі коди помилок, що повертаються через веб-API 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 — користувач має трансакцію в черзі, яку необхідно завершити перед початком нової трансакції.

Маєте ще питання?

Ви можете поставити їх в обговоренні інтеграції внутрішньоігрових придбань.