マイクロトラントランザクション実装ガイド (Steamworks ドキュメント)

Steamworks ドキュメンテーション

マイクロトラントランザクション実装ガイド

Steamworks ドキュメント > 機能 > マイクロトランザクション（ゲーム内購入） > マイクロトラントランザクション実装ガイド

概要

Steamゲーム内決済システムの目的は、ユーザーがゲームから退出せずにアイテムを購入できる環境を、開発者に簡単に提供することです。販売アイテムは、売り手が決定できます。武器や弾薬、ゲーム内通貨やゴールド、プレイヤーキャラクターのための服装等々、可能性はたくさんあります。ゲームはいくつでもアイテムを提供でき、個別での販売もまとめ売りも可能です。 Steamは販売アイテムの種類や、販売方法を制限することはありませんし、ゲームが他の販売メカニズムを持っている場合にその使用を妨げることはしません。 Steamプラットフォームでユーザーが慣れ親しんだ支払体験を提供することで、Steamウォレットを使用して簡単にゲーム内アイテムを購入できるようにすることが目的です。この種の統合を使えば、ゲームは新規Steamユーザーにアクセスできるだけでなく、新しくSteamに追加された支払方法にもすぐ対応できるようになります。

このシステムの下では、ゲームが購入を管理します。購入リクエストに対する成功応答が、ユーザーへの支払請求であるとともに、ゲームに対する即時的なイベント通知でもあります。購入が承認されると、アイテムを付与するかどうかの管理はゲームが行います。例えば、期限付きのアイテムの場合、ゲームがそのアイテムの使用期間を管理します。

ゲーム内購入に加えて、システムは会計とサポートシステムで利用可能な追加の機能を提供します：

顧客が支払いに失敗した場合の通知を受け取ります
Webサービスを通して、払い戻しとトランザクションステータスのクエリを発行できます
Steamstatsパートナーサイトアイテムとゲームの詳細な販売レポートをライブで入手できます

ゲーム内購入のベストプラクティス

開発中のSteamゲームでゲーム内購入をサポートするのであれば、取り掛かりとなるいくつかの提案やベストプラクティスがいくつかあります。 Steamでゲーム内購入を提供するゲームをローンチするにあたり、無料ゲームであれ、先行購入が必要なタイトルであれ、考慮するべき共通点があります。

ゲーム内エコノミーとそのベストプラクティスはマイクロトランザクション（ゲーム内購入）ドキュメントを参照してください。

決済システムの仕組み

決済システムは、ゲーム内での購入プロセス、Steamの請求Webサービスと、顧客による承認プロセスの組み合わせです。

次の順序で購入プロセスが進みます。ユーザーは、オーダー開始からトランザクション完了までのすべてをゲーム内で完結できます。

ユーザーがゲーム内アイテムの購入を希望する時、ゲームは購入リクエストをゲームの購入サーバーに送信します。購入リクエストの処理にはゲームシステムが採用しているサービスエンティティを、購入サーバーとして使用できます。それはWebサーバーでも、認証システムでもかまいません。サーバーに必要なのは、Steam請求サーバーとHTTPを介して通信することです。購入サーバーは、ユーザーの居住国、使用言語、使用通貨情報をSteam請求サーバーに対してリクエストできます。このデータを使用して、必要であれば価格設定を調整できます。
その後購入サーバーは、Steam Webサービスに対してクライアントの代わりに支払トランザクションを開始します。このリクエストは安全なHTTP POSTです。このリクエスト内には、ユーザーのメタデータ、ユーザーが購入を望んでいる各アイテムの説明と価格が含まれます。
このリクエストを受信すると、SteamはクライアントのSteamオーバーレイを自動的に有効化して、ユーザーに全アイテムとその価格のリストを提示し、トランザクションの確認と承認を促すボタンを表示します。ユーザーのSteamアカウント残高が不足している場合、オーバーレイがチャージプロセスへと案内します。 Steamオーバーレイは、ユーザーの支払情報をすべて収集して処理します。完了すると、ユーザーはその購入についての承認または拒否の通知を受け取ります。ゲームはこの通知のコールバックの受け取りを登録し、ゲームの購入サーバーにその結果を転送します。
購入サーバーは通知を受け取り、FinalizeTransactionの呼び出し要求をSteamに送り、処理を完了します。正常な応答が得られれば、ユーザーに対して請求が実行され、アイテムをユーザーに付与することができます。

購入オプションが通常Webページ経由で処理されるゲームの場合や、ゲームのWebサイト上でSteamを支払方法として提供したい場合には、オプションでブラウザーベースでの統合を利用することも可能です。このソリューションでは、次の順序で購入プロセスが進みます。

ユーザーがゲーム内またはゲームのWebサイトで購入したいアイテムを見つけたとします。ゲーム内の場合、ブラウザーを立ち上げてゲームのWebページを開きます。
安全なHTTP POST形式で、購入サーバーがユーザーに代わってWebトランザクションを開始します。成功すると、購入サーバーはユーザーのブラウザーセッションをリダイレクトするための固有のSteam URLを返し、トランザクションが承認されます。リダイレクト時には、承認の完了後にユーザーが戻されるリターンURLを指定します。
ユーザーがゲームサイトに戻ると購入サーバーはトランザクションのステータスをリクエストし、正常に承認されると、SteamへのFinalizeTransaction呼び出しによって代金が取得されます。

接続のセットアップ

前提条件

まずはWebAPIパブリッシャーキーを作成します。作成方法はWeb APIキーを使用した認証を参照してください。このキーはすべてのWebサーバーのリクエスト時に送信され、サーバーのリクエストの承認に使われます。リクエストと共にkey=<your key here>パラメーターとして送信されます。

注文の保存

将来的に参照できるよう、お使いのシステム上に個々の注文情報を保存してください。 Steam内ではトランザクションの参照には一意の64 ビット注文IDを使用します。

リクエストの送信

全てのリクエストは、TLSセキュアな接続を使用してHTTP 2.2 GETまたはPOSTを使って送信されるべきです。コンテンツのタイプは「application/x-www-form-urlencoded」（アプリケーション/URLエンコードされたx-www-形式）で、リクエストのボディ内に標準のURLエンコード方式でPOSTパラメーターを含めます。テキストはUTF-8で送信する必要があります。

リクエストはベースURIを経由します：
https://partner.steam-api.com/ISteamMicroTxn/*

コマンドの中にはPass、Failを結果として返すものもあります。結果がFailの場合、追加のエラーコードと説明が追加されます。 Passの場合には、これらのキーが表示されることはありません。

応答は、デフォルトではJSON形式で返されます。オプションでリクエストに「format=xml」パラメーターを追加することでXML形式を指定することもできます。
注記：この場合、パラメーターキーを送信し、順序不同で返せるフレキシブルなJSONまたはXMLソリューションの実装が必要です。

テストの実施

Steamは統合テスト用にデベロッパーサンドボックスを提供しています。サンドボックスは通常のAPIから利用できるリクエストにすべて対応していますが、テスターのSteamウォレットから実際にクレジットが引き出されることはありません。

サンドボックスへのアクセスには別のベースURIを使用します：
https://partner.steam-api.com/ISteamMicroTxnSandbox/*

統合ステップ

ゲーム内購入

統合されたストアがあり、ユーザーエクスペリエンスがゲーム内で完結する場合のステップです。

ステップ1
ゲームはSteamworks APIを使う必要があります。これはヘッダーファイルを含め、libファイルにリンクし、製品と共ににDLLを提出することを意味します。詳細はSteamworks API概要を参照してください。以下のステップを続行する前にまず、正常にSteamworks APIを初期化することが必要です。
ステップ2
ユーザーがゲーム内で1つ以上のアイテムの購入を選択します。アイテムが識別されると、ゲームはユーザーに関するメタデータをいくつか収集する必要があります：
- Steam ID - 64 ビットの数列でSteamシステム内のユーザーを一意的に識別します。
- 国コード - ユーザーのISO 3166国コードで、ユーザーの購入実行場所を示します。この情報を使い、その購入に際して適用する価格を決定します。
- 通貨コード - ユーザーへの請求に使用されるISO 4217通貨コード
- クライアントのゲーム言語コード - Steamクライアントのゲームが現在実行中のISO 639-1言語コード
SteamIDおよび言語はSteamworks API呼び出しから取得できます：
- ISteamUser::GetSteamID
- ISteamApps::GetCurrentGameLanguage
ユーザーの国および通貨タイプを取得するには、ISteamMicroTxn/GetUserInfo web APIリクエストでユーザーのSteam IDを渡してください。

このユーザーのメタデータは通常の購入データとバンドルされ購入サーバーに送られます。
ステップ3
購入サーバーはSteamクライアントに代わり、Steamウェブサービスを介して購入リクエストを実行します。このドキュメント内で後述するISteamMicroTxn/InitTxnを使用します。リクエストと共に以下のデータの送信が必要です：
- 注文ID - この購入に割り当てる一意の64ビットの数値。このトランザクションに使用するあなたのキーです。 Steamシステム内でトランザクションを参照するのに使用します。
- Steam ID - ステップ3でSteamクライアントから受け取ったユーザーID
- App ID - Steamゲームに一意の識別子
- 言語－あなたのアイテムがリストされたISO 639-1言語コード
- 通貨 - 入力した価格のISO 4217通貨コード。これが、ユーザーの通貨コードがステップ2で提供されたものと一致しない場合には、現在の為替レートで自動両替が適用されます。 Steamは、ユーザーの通貨に両替した価格を表示し、ユーザーの承認を求めます。最適な顧客体験を提供するには、顧客が使用すると考えられるすべての通貨での価格を提供することです。
- ユーザーが購入しようとしている1つ以上のアイテムのリスト。各アイテムに以下のデータを指定します：
  - アイテムID－あなたが付けるアイテム用32ビット識別子
  - 数量－トランザクション内のこのタイプの商品の数
  - 合計－この商品に対してユーザーに請求する合計金額（100分の1単位で記載）。通貨によっては小数点以下の価格設定をサポートしていない場合があります。詳細情報は対応通貨を参照してください。この商品の数量値が1より大きい場合には、この値が請求額になります（合計＝数量ｘitem_cost）。
  - 商品説明－アイテムについての説明テキスト。トランザクションの承認の際にユーザーに表示されます。 Steamクライアントで設定された言語コードに基づき、ローカライズされた説明を表示することができます。
  - アイテムカテゴリー－アイテムが所属するカテゴリーのための任意の説明テキスト。この値は、バックエンドのSteamレポートで販売データをグループ化するのに使用され、ユーザーに表示されることはありません。
Steamがトランザクションを受け入れると自動的に、購入の承認を求めるようSteamクライアントに対して通知されます。エラーが返された場合は、問題を修正し、新しい購入トランザクションが送信される必要があります。
ステップ4
ISteamMicroTxn/InitTxnが正常に施行されると、ユーザーはSteamのゲーム内オーバーレイを通してトランザクションの承認が必要であることを知らせる通知を受け取ります。トランザクションの詳細は購入リクエストによって提供された商品説明を使って表示されます。これでユーザーがトランザクションを承認できるようになります。ユーザーのアカウントのSteamウォレットに十分な残高がない場合、Steamは自動的にチャージプロセスにユーザーを案内します。最後にあなたのゲームはトランザクションが承認または拒否されたかの通知を受け取ります。

ゲームはISteamUser::MicroTxnAuthorizationResponse_tコールバックハンドラーを登録し、承認（または拒否）イベントの通知を受け取る必要があります。このコールバック結果には、AppID、注文IDとトランザクションの承認状態が含まれます。ゲームはこの結果を購入サーバーに送信し、購入サーバーはトランザクションを確定できることを知ることになります。詳細情報はコールバックセクションを参照してください。
ステップ5
購入サーバーは ISteamMicroTxn/FinalizeTxn APIコマンドを使用して以下のパラメーターでトランザクションを確定します：
- 注文ID－トランザクションを実行するために作成した注文ID
- App ID－あなたのSteamゲームに一意の識別子
正常なレスポンスが返された場合、それは購入が承諾され、アイテムが付与されるべきことを意味します。エラーのレスポンスは購入が正しく完了しなかったことを意味し、該当するエラーメッセージが表示されます。
ステップ6
購入サーバーがトランザクションの決済ステータス変更に関する通知を受け取るには、ISteamMicroTxn/GetReport APIを定期的に呼び出す必要があります。支払のアップデートを照合するには、このAPIを少なくとも1日に1回呼び出す必要がありますが、サーバーがトランザクションの常に最新の状態に保つために、このAPIを毎分呼び出しても問題ありません。

ご自身の判断で、ISteamMicroTxn/RefundTxn APIを使用して顧客のトランザクションを返金することができます。ただし、トランザクションを取り消す方法は他にもあり、これらは注意を要します。トランザクションが取り消された状態（例：Refunded、PartialRefund、Chargedback、RefundedSuspsectedFraud、RefundedFriendlyFraud－参照：付録A：ステータスの値）になった場合、バックエンドは可能な限り、取り消されたトランザクションに関連するアイテムの回収を試みる必要があります。不正行為（詐欺）に備えるのドキュメントを確認し、最も一般的な種類の不正行為を防止するための対策を講じるようにしてください。

Webベースの購入

あなたのゲームストアがWebページである場合、または既存のストア会計システムにSteamを支払方法として追加するだけの場合は、以下の手順で統合してください：

ステップ1
ユーザーのSteamIDを入手します。
- ユーザーが現在ゲーム内にいる場合、Steamworks APIを使ってSteamIDを受け取ります：ISteamUser::GetSteamID。
- ユーザーがあなたのウェブサイトにいる場合、 Steamworks OpenID API を使ってユーザーの SteamID を安全に取得します。 OpenIDの詳細はWebブラウザベースのOpenID認証を参照してください。
注記： ユーザーのゲームアカウントを SteamID にリンクさせ、二次的なログインを 1 度実行するだけですむようにすることをお勧めします。
ステップ 2
ユーザーの国と通貨情報を取得するにはユーザーの Steam ID を渡して ISteamMicroTxn/GetUserInfo web API リクエストを呼び出してください。このデータを使って、そのユーザーの通貨値に合った価格でストアを表示できます。

注意： GetUserInfoにはオプションのIPアドレスパラメーターがあり、これを使うことでユーザーの居住地についての情報をSteamに与えることができます。 Webベースでの購入している時、またはSteamクライアントでログインせずにゲームをプレイしている時のユーザーのすべてのパブリックIPアドレスを送信します。
ステップ3
購入サーバーがISteamMicroTxn/InitTxnを使用して、Steam Webサービス経由で購入リクエストを開始します。通常のゲーム内での購入で提供する情報に加えて、もう2つのデータを提供が必要です。
- usersession - これは「web」に設定し、ユーザーがブラウザーを通じてトランザクションを承認することを示します。
- ipaddress - ユーザーのパブリックIPアドレス
usersessionがWEBに設定されている場合、InitTxnリクエストは追加のsteamurlパラメーターを返します。これは、ユーザーのWebセッションをリダイレクトする先の固有のURLで、このAPIコールによって作成されたトランザクションを識別します。
ステップ4
購入サーバーはユーザーのWebセッションをInitTxn APIコールに返されたSteam URLにリダイレクトします。リダイレクトに伴い、トランザクションの承認（または拒否）後にユーザーが返送される場所のURLを付加します。次の形式でフルパスで指定された URL（例：http://www.steamgames.com）を使用します：
returnurl=ここにあなたのURL
Steam URLにリダイレクトされたユーザーは、認証前にSteamにログインする必要があります。ゲームのWebサイト上でSteamを支払方法として選択したユーザーにとって、このログインは想定される動作です。しかし、ユーザーが既にSteamにログインしゲームをプレイしている場合は、この2度目のログインはスキップするのが望ましいでしょう。スキップは、ゲームのオーバーレイに内蔵されているWebブラウザーの機能で実現することができます。認証にゲームのオーバーレイブラウザを使用するのであれば、ユーザーは自動的にログイン済みの状態になります。ブラウザーの起動には次のSteamworks APIコールを使用します：
ISteamFriends::ActivateGameOverlayToWebPage

ゲームオーバーレイの使用の詳細はこちらを参照してください。
ステップ5
ユーザーがゲームサイトに戻ったら、ISteamMicroTxn/QueryTxn APIコールで結果を取得してください。注文のステータスが「Approved（承認）」の場合、ISteamMicroTxn/FinalizeTxn APIコールで代金を取得してください。それ以外のステータスが返された場合には、トランザクションを破棄してください。

注意：ユーザーがブラウザーを閉じるか、サイトに戻ることを妨げるような何かが起こった場合には、トランザクションを放棄し、FinalizeTxnを発行しないでください。ユーザーがトランザクションを承認したにもかかわらず、何らかの理由でリダイレクトされなかった場合、トランザクションを破棄して最初からやり直してください。
ステップ6
購入サーバーがトランザクションの決済ステータス変更に関する通知を受け取るには、ISteamMicroTxn/GetReport APIを定期的に呼び出す必要があります。決済情報のアップデートを照合するには、このAPIを少なくとも1日に1回呼び出す必要がありますが、サーバーがトランザクションの常に最新の状態に保つために、毎分呼び出しても問題ありません。

ご自身の判断で、ISteamMicroTxn/RefundTxn APIを使用して顧客のトランザクションを返金することができます。ただし、トランザクションを取り消す方法は他にもあり、これらは注意を要します。トランザクションが取り消された状態（例：Refunded、PartialRefund、Chargedback、RefundedSuspsectedFraud、RefundedFriendlyFraud－参照：付録A：ステータスの値）になった場合、バックエンドは可能な限り、取り消されたトランザクションに関連するアイテムの回収を試みる必要があります。不正行為（詐欺）に備えるのドキュメントを確認し、最も一般的な種類の不正行為を防止するための対策を講じるようにしてください。

付録A：ステータスの値

ISteamMicroTxnWeb APIによって返される可能性のあるステータスの値です。これらの値を持つレスポンスキーは通常ステータスと呼ばれます。

Init－注文は作成されたが、ユーザーが承認していない状態
Approved－注文が作成され、ユーザーが承認した状態
Succeeded－注文が正常に処理された状態
Failed－注文が失敗したか、拒否された状態
Refunded－注文が返金され、ゲームがアイテムを無効化することが必要な状態。返品プロセスはユーザー自身で開始できます。
PartialRefund－カート内の1つ以上のアイテムが返品された状態。各アイテムのitemstatusフィールドで詳細をチェックしてください。
Chargedback－注文が不正取引または異議の対象となったため、ゲームがアイテムを無効化することが必要な状態
RefundedSuspectedFraud－不正購入が疑われたため、Valveによって注文が返金された状態。製品の無効化はゲーム側で実施される必要があります。
RefundedFriendlyFraud－本人の承認なしの購入（Friendly Fraud）と判断されたため、Valveによって注文が返品された状態。製品の無効化はゲーム側で実施される必要があります。

付録B：エラーコード

ISteamMicroTxnWeb APIによって返される可能性のあるエラーコードです。これらの値を持つレスポンスキーは通常エラーコードと呼ばれます。

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 - ユーザーには、新規取引を開始する前に完了するべき保留中の取引がある

他にもご質問がありますか？

ご質問はこちらの掲示板をご利用ください。