アイテム課金をする

概要

Mobageでのアイテム課金は「モバコイン」と呼ばれる仮想通貨で行われます。モバコインはPC、モバイルで共通で使うことができ、ユーザーは携帯キャリア決済、Web Money、クレジットカードなどで購入することができます。

Mobage決済APIを利用することによりユーザーに対してアイテム課金を行うことができます。

Mobage決済APIは OpenSocial Virtual Currency API rev. 4 を元に設計されています。

注意事項

下記フローの1.から6.は JS API でのリクエストとなり7.から10.は RESTful API でのリクエストとなります。
また PAYMENT_ID を指定した Payment API からの決済状態確認が必須となります。
正常に成功していれば問題ありませんが、決済失敗のステータスが返っている場合ではアイテムの回収と決済の取り消しがゲームサーバー上にて必要となります。

処理の流れ

1. ブラウザから opensocial.requestPayment() を呼び出して決済情報を作成します。
2. プラットフォームからゲームサーバーのエンドポイントURLに対して決済情報の確認のリクエストが送信されます。
3. ゲームサーバーはリクエストの妥当性を検証してレスポンスを返します。Mobageが正常なレスポンスを受け取ったらユーザーに決済を促します。
4. ユーザーが決済を許可したら、プラットフォームからエンドポイントURLに対して決済確定のリクエストが送信されます。
5. ゲームサーバーはリクエストの妥当性を検証してアイテム付与などの処理を行ってレスポンスを返します。プラットフォームが正常なレスポンスを受け取ったら決済が確定されます。
6. 最初に呼び出された opensocial.requestPayment() の引数に指定されたコールバックが呼ばれて終了します。
7. ブラウザから gadgets.io.makeRequest() などを利用してゲームサーバーへ決済の正否の確認を促すようリクエストします。
8. ゲームサーバーは RESTful API を利用して決済のステータスを確認するリクエストを送信します。
9. API サーバーによって指定された決済のステータスがレスポンスとして返ります。
10. 結果によって処理を行います。

事前準備

決済APIを利用するには Gadget XML で opensocial-payment Feature を Require する必要があります。

また、決済APIを利用するにはアプリケーションの Payment handler URL を登録する必要があります。これも Gadget XML で指定する必要があります。

この情報を Gadget XML をデベロッパーサイトで登録することによって決済APIを利用できるようになります。

また、レスポンスのサインなどで Consumer Secret が必要になるので用意しておく必要があります。Consumer Secret はデベロッパーサイトのアプリケーション管理画面で参照することができます。

決済情報の開始

決済情報の作成は Gadget から以下のようなコードで行います。

  • opensocial.newBillingItem() を使って注文するアイテムを生成します。指定する値はすべて必須になります。
    • SKU_ID はアプリケーションにおけるアイテム単位でユニークなIDを数字で指定します。
    • PRICE には単価を指定します。数字になります。
    • COUNT には購入個数を数字で指定します。COUNT の上限は 255 になります。 
    • NAME にはアイテム名を指定します。
    • IMAGE_URL にはアイテムの画像を指定します。180 X 180 で表示されるのでそれを考慮したサイズにするとよいでしょう。
  • opensocial.newPayment() で決済を生成します。
    • ITEMS には生成した BillingItem を配列で指定します。現在は1アイテムのみ指定できます。
    • AMOUNT には決済総額を数字で指定します。これは BillingItem の PRICE X COUNT と一致している必要があります。AMOUNT の上限は 50000 になります。
  • opensocial.requestPayment() で決済を開始します。

決済情報の確認

決済を開始するとコンテナからゲームサーバーに決済確認リクエストが HTTP リクエストとして送信されます。送信先URLは Gadget XML で指定した Payment Handler URL になります。

リクエストは POST メソッドで行われて、リクエストボディとして JSON フォーマットでシリアライズされた Payment オブジェクトが含まれます。

PAYMENT_TYPE: payment 固定です。
ORDERED_TIME: ブラウザで取得した値なので参考程度にご利用ください。

また、リクエストにはその妥当性を証明するための署名が含まれます。リクエストを受けたゲームサーバーは安全性のためにも署名の検証を行う必要があります。

リクエストの妥当性が証明できたら、ゲームサーバーは決済情報をゲームサーバー上に保存して、リクエストに含まれるMobage全体でユニークな決済IDの PAYMENT_ID に対になる形で、アプリケーションでユニークになる決済IDである ORDER_ID を発行してレスポンスに含めて返します。ORDER_ID は、英数小文字32文字以内に収まるようにして下さい。レスポンスはJSONフォーマットでシリアライズします。

このレスポンスは署名をする必要があります。

この時、署名が正しく、HTTPレスポンスコードが200、response_code が OK の場合のみ、正常なレスポンスと見なします。

レスポンスが正常な場合、ユーザーにポップアップで購入アイテムの情報が表示されます。

決済の確定

ユーザーが購入するに十分なコインを持っていて、購入を決定すると Payment Handler URL に決済確定のリクエストが HTTP リクエストとして送信されます。

リクエストは GET メソッドで行われて、クエリーパラメータに ORDER_ID が含まれます。

このリクエストにも決済確認リクエスト同様、署名がされているので署名の検証を行います。

署名の検証が成功したらリクエストに含まれる ORDER_ID を使ってゲームサーバーで保存されている決済情報を取得します。決済情報に問題がなければ決済の確定とユーザーへのアイテム付与を行ってレスポンスを返します。

レスポンスには ORDER_ID と最終確定総額である AMOUNT、RESPONSE_CODE を含めます。レスポンスはJSONフォーマットでシリアライズします。このレスポンスにも署名をする必要があります。

この時、署名が正しく、HTTPレスポンスコードが200、response_code が OK の場合のみ、正常なレスポンスと見なします。

正常なレスポンスが帰ってきたら、コインの引き落としが行われて決済が確定、完了します。

決済結果の確認

最後に決済が正常に終了しているか確認します。確認には gadgets.io.makeRequest() を利用して ORDER_ID を含めてゲームサーバーに問い合わせを行います。

リクエストを受け取ったゲームサーバーは ORDER_ID から保存してある決済情報の PAYMENT_ID を取得して Payment API で決済の状態を確認します。

正常に確定していればそのままレスポンスを返して終了ですが、万が一ゲームサーバー上では決済が確定しているはずなのに決済失敗のステータスが帰ってきた場合は決済の取り消しとアイテム付与の取り消しを行ってレスポンスを返す必要があります。

Mobageオープンプラットフォームからのリクエスト

クエリパラメータ

フィールド名

説明

opensocial_app_id

このアプリケーションの ID

opensocial_app_url

このアプリケーションの URL

opensocial_viewer_id

このアプリケーションを利用しているユーザーの ID

opensocial_owner_id

このアプリケーションをインストールしているユーザーの ID

PC版ではtoken, token_secretは渡ってこないため署名に含める必要はありません。

OAuth Signature の検証

Authorization ヘッダに含まれる OAuth Signature はGameServerへのリクエストが改ざんされていないことを検証するための情報です。悪意を持った第三者からのリクエストを受けて予期しない動作を起こさないように必ず OAuth Signature の検証を行って行ください。

検証には以下の手順を踏みます。

Base String の生成

生成は以下の手順で行います。

1. HTTP リクエストメソッドを取得します。(例: GET)
2. URL からクエリパラメータを除いたものを用意します。(例: http://example.com/123456789)
3. Authorization ヘッダから realm と oauth_signature を除くプロトコルパラメータを取得します。

Authorization ヘッダから取得するパラメータ

フィールド名

説明

oauth_body_hash

ボディコンテンツのSHA1ハッシュ値 (POST リクエストの時にのみ含まれます)

oauth_consumer_key

アプリケーション登録時に発行される値

oauth_nonce

リクエスト毎にユニークな値

oauth_signature_method

署名方法 (HMAC-SHA1 固定)

oauth_timestamp

UNIX タイムスタンプ値

oauth_version

OAuth のバージョン (1.0 固定)

4. Gadgetサーバから送られてきたクエリパラメータをすべて取得します。
5. 3から4で取得したパラメータを仕様にしたがって結合します。
キーと値はそれぞれ英数字,"-", ".","_","~"以外のすべての文字をパーセントエンコードして "=" で連結します。
また、連結したキーと値のペアはアルファベット順にソートして,"&" で連結します

Signature の生成と比較

Signature は Base String をキー文字列で署名して生成します。

キー文字列はアプリケーション登録時に発行された Consumer Secret と Authorization ヘッダの oauth_token_secret をパーセントエンコードし,"&" で連結した値です。ダイジェスト値の生成には Authorization ヘッダの oauth_signature_method で指定されているアルゴリズム (現在はHMAC-SHA1固定) を利用します。この値をさらに BASE64 エンコードしたものが Signature になります(ダイジェスト値を生成したときに改行が追加される場合は取り除いてください。)。

この値と Authorization ヘッダの oauth_signature を比較することによってリクエストの検証を行うことができます。

サンプル

Perl: OAuth::Lite モジュールは 1.24 以上を利用してください

PHP: OAuth ライブラリはここから入手できます。

Mobageオープンプラットフォームへのレスポンスの署名方法

Body Hash の計算

レスポンスのボディから base64 ダイジェスト値を生成します。アルゴリズムにはSHA1を利用します。この際に末尾に "=" がつく場合には削除します。

Base String の生成

生成した Body Hash に加えて以下の値を利用します

body_hash

Body Hash

nonce

リクエスト毎にユニークな値

timestamp

UNIX タイムスタンプ値

consumer_key

アプリケーション登録時に発行される値

キーと値はそれぞれ英数字,"-", ".","_","~"以外のすべての文字をパーセントエンコードして "=" で連結します。また、連結したキーと値のペアはアルファベット順にソートして,"&" で連結します。

Signature の生成

生成した Base String を Consumer Secret をキーとしてHMAC-SHA1で base64 ダイジェスト値を生成します。この際に末尾に "=" がつく場合には削除します。

Header の生成

生成した Signature を URI エスケープしたものを値、"signature" をキーとして "=" で連結して、Base String に "&" で連結します。

body_hash=xxx&consumer_key=xxx&nonce=xxx&timestamp=xxx&signature=xxx

この値を X-MBGA-PAYMENT-SIGNATURE ヘッダに含めてレスポンスをします。

サンプル

Perl:

PHP:

エラーレスポンス

エラーコード

表示

内容

APP_NETWORK_FAILURE

ネットワークエラーです

レスポンスコードが 200 以外、タイムアウト(10秒)

INVALID_TOKEN

認証エラーです

X-MBGA-PAYMENT-SIGNATURE ヘッダが不正

MALFORMED_REQUEST

リクエストが不正です

opensocial.requestPayment() のパラメータ、もしくはアプリのステータスが不正

NOT_IMPLEMENTED

決済されませんでした

Payment Handler URL が不正

PAYMENT_ERROR

購入時にエラーが発生しました

platform側のエラー

UNKNOWN_ERROR

エラーが発生しました

レスポンスのJSONが不正


更新履歴

  • 2017/05/18
    • OAuth ライブラリのリンク先を修正
  • 2012/12/18
    • シーケンス画像を変更
  • 2012/8/9
    • 注意事項を追記
  • 2011/8/31
    • 決済情報の開始にパラメータの上限を追記
  • 2011/3/9
    • エラーレスポンスの項目を追記

 

PREVIOUS

自由文の入力・表示をする

NEXT

RESTful API リファレンス