アイテムを課金する

次に Payment API を利用して課金アイテムを購入するプログラムを開発していきます。

Android ゲームポイント対応に伴い、Shell App Framework for Android の場合、仮想通貨は『ゲームポイント』となります。詳細は以下 URL をご確認ください。

https://docs.mobage.com/display/JPSA/AndroidGPShellApp

課金アイテムの購入を開始する

まずはじめに、課金アイテムの購入を開始するための画面を開発します。

以下のような payment_start.php を開発します。

前章と同様に、validator.php の ResuestValidator クラスを利用して、Gadget サーバーからのリクエストの妥当性検証を行います。

次に、HTML部分です。

アイテム購入のためには、Payment API を呼び出す必要がありますので、次の payment_confirm.php で詳説します。ここでは、payment_confirm.php へのリンクを追加してきます。

決済トランザクションを開始する

次に、Payment API を利用して Payment エントリを作成し、課金アイテムの詳細を表示する画面を開発します。

以下のような payment_confirm.php を開発します。

プログラムの処理を説明をしてきます。

はじめのGadget サーバーからゲームサーバーへのリクエストの妥当性検証は前章と同様ですので割愛します。

次に、API サーバーへのアクセスの準備をします。まずは、API サーバー OAuth のパラメーターに必要な、Consumer KeyとConsumer Secretを準備します。また、Payment API へのPOSTメソッドは Proxy モデル (OAuth のトークンを利用するモデル) を使用しますので、Gadget サーバーから渡される、OAuth のトークンと opensocial_viewer_id (画面を閲覧しているログインユーザーのID) を取得します。

必要な情報が揃ったので、OAuth のヘッダー情報を生成します。Payment エントリを作成するためのパスである /payment/@me/@self/@app を Sandbox 用の Endpoint URL を基準に作成します。Proxy モデルの場合は、リクエストパラメーターの xoauth_requestor_id に 上記で取得した opensocial_viewer_id の値を設定します。

次に、Payment エントリの情報を含む JSON 形式の POST データを準備します。Array 形式で callbackUrl (決済完了通知用の URL) と finishUrl (決済終了画面用の URL) および課金アイテムの情報を設定し、json_encode 関数で JSON 形式に変換します。callbackUrl および finishUrl に設定した URL に対するプログラムの実装は後述します。

上記で生成された OAuthの Authorization ヘッダーおよび POST データを利用して API サーバーへのリクエストを実行します。API サーバーからのレスポンスデータと HTTP ステータスコードを取得しておきます。

Payment API の POST メソッドでは、成功時には HTTP ステータスコードは 201 が返ります。ここでは、201 以外の場合はエラー画面を返すようにしておきます。

HTTP ステータスが 201 の場合は、レスポンスデータに含まれる JSON データを解析して、 Payment エントリの値を取り出します。このチュートリアルでは実装しませんが、status が 0 の状態でDB等にPaymentのデータをストアします。

最後に課金アイテムの情報をHTMLに埋め込みます。また、プラットフォーム側の決済画面のURLが含まれる endpoint 値をリンク先に埋め込みます。

決済確定通知を受け取る

次に、Payment エントリ作成時に callbackUrl で指定した決済確定通知を受け取るプログラムを開発します。このプログラムは、HTMLを表示するのではなく、プラットフォーム側に決済後に、処理が正常に行われたことを通知することが目的になります。ゲームからプラットフォームの決済画面に遷移し、ユーザーが決済を確定した直後に呼び出されます。

以下のような payment_callback.php を開発します。

プログラムの処理を説明をしてきます。

決済確定通知のリクエストは、Gadget サーバーではなく、プラットフォーム本体から送信されますが、Gadget サーバーからのリクエストの時と同様にリクエストの妥当性を検証します。

次に、決済確定通知のリクエストに付与するリクエストパラメーターをそれぞれ取得し、主に payment_id をキーにしてステータスの更新を行います。この時点では、まだアイテムの付与は確定していない状態にしておきます。このチュートリアルでは実装しませんが、ゲームサーバーのデータベースへアクセスし、payment_id から該当の Payment 情報を取得して、ステータスを確定に Update します。
この時点で開始済みのデータが存在しない場合は、重複したリクエスト等の予期しないリクエストのなので、エラーとして HTTP ステータス400等を返します。

また、リクエストパラメーターに付与されているstatusが 10 でない場合も同様に正常な決済ではないため、エラーとして HTTP ステータス400を返します。

最後に処理が正常な場合はレスポンスとして、文字列の OK を返します。

アイテム付与の開始処理等でなんらかのエラーが発生した場合は、HTTP ステータスコードを 200 以外を返すようにしてください。購入がエラー扱いとなり、決済がキャンセルされます。

購入終了ページを表示する

次に、Payment エントリ作成時に finishUrl で指定した購入終了ページを開発します。決済確定通知の処理が正常に終わった場合に、プラットフォームの決済画面から遷移します。ただ購入終了ページを表示するだけでなく、Payment エントリを最後に取得し、決済のステータスが完了していることを確認し、アイテム付与の確定処理を行います。

以下のような payment_finish.php を開発します。

プログラムの処理を説明をしてきます。

はじめに、この購入終了ページは Gadget サーバーを経由してリクエストされますので、今までと同様にリクエストの妥当性を検証します。

次に、API サーバーへのアクセスの準備をします。まずは、API サーバー OAuth のパラメーターに必要な、Consumer KeyとConsumer Secretを準備します。また、Payment API への GET メソッドは Trusted モデル (OAuth のトークンを利用しないモデル) を使用することができます。Gadget サーバーから渡される、Payment エントリの ID と opensocial_viewer_id (画面を閲覧しているログインユーザーのID) を取得します。また、Trusted モデルの場合は、アプリケーションIDも必要になりますので定義しておきます。アプリケーションIDは、デベロッパーサイト上の「アプリケーション詳細」ページで確認できますので、その値をプログラムに設定してください。必要な情報が揃ったので、OAuth のヘッダー情報を生成します。Payment エントリを取得するためのパスである /payment/{userId}/@self/@app/{paymentId} を Sandbox 用の Endpoint URL を基準に作成します。Trusted モデルの場合は、リクエストパラメーターの xoauth_requestor_id にアプリケーションIDの値を設定します。また、OAuth トークンを設定しないために、@me は使えませんので、直接ユーザーIDを指定します。

上記で生成された OAuthの Authorization ヘッダーを利用して API サーバーへのリクエストを実行します。API サーバーからのレスポンスデータと HTTP ステータスコードを取得しておきます。

Payment API の GET メソッドでは、成功時には HTTP ステータスコードは 200 が返ります。ここでは、200 以外の場合はエラーページを返すようにしておきます。

HTTP ステータスが 200 の場合は、レスポンスデータに含まれる JSON データを解析して、 status の値を取り出し、決済のステータスが 10 (成功) であることを確認します。決済ステータスが 10 の場合は、アイテム付与の確定処理を行います。このチュートリアルでは実装しませんが、ゲームサーバーのデータベースへアクセスし、該当のpayment_id レコードが未確定状態で存在することを確認してから確定状態にします。

万が一、決済ステータスが 10 以外の場合は、決済が完了していませんので、課金アイテムの付与の確定処理をしないようにします。この処理を行わないと、ユーザーが決済していないにもかかわらず、課金アイテムを付与したことになってしまいます。

あとは、購入が終了した旨をユーザーへ通知する画面を表示するのみです。

実機で確認する

では、開発した4つのPHPプログラムを以下のようにゲームサーバーに配置します。

PHP ファイル

URL

payment_start.php

http://dev.gameserver.com/payment_start.php

payment_confirm.php

http://dev.gameserver.com/payment_confirm.php

payment_callback.php

http://dev.gameserver.com/payment_callback.php

payment_finish.php

http://dev.gameserver.com/payment_finish.php

また、前章で作成した index.html に payment_start.php へのリンクを以下のように追加して再配置してください。

さて、前章と同様の手順でアプリケーションにアクセスしてください。以下のように、Buy Something のリンクが追加されています。

Buy Something をタップして遷移し、Click to Buy Sample Item をタップすると、ゲーム内のアイテム詳細画面が表示されます。

Buy をタップすると、プラットフォーム側の決済画面に遷移します。

購入が完了すると、payment_callback.php が呼ばれた後に、payment_finish.php に遷移して決済完了です。

アイテム付与漏れの救済処理

購入完了ページを表示する際に不具合などが発生し、決済されたにも関わらず、アイテムの付与がされていなかったケースを考慮して、救済する処理を作成する必要があります。このチュートリアルでは実装しませんが、ゲームサーバーのデータベースにストアしている決済の履歴上はアイテム付与をしていない Payment ID に対して API サーバーが返す決済のステータスが 10 ではないものが付与漏れのPayment ID となります。
例えば、以下のような SQL で抽出することが可能です。

尚、その逆に万が一決済が完了おらずにアイテムを付与しているものを抽出する場合は、以下のような SQL になります。

上記のようなレコードが存在する場合は、正しい状態に戻すように運用しなければなりません。

正常な状態は以下のような、SQLで抽出できるレコードになります。

これで、アイテムの課金のチュートリアルは完了です。

参考資料

決済サービスの詳細はこちらを参照してください。
PaymentAPIの詳細はこちらを参照してください。

更新履歴

  • 2013/03/01
    • ドキュメント移行

PREVIOUS

ログインユーザーの情報を表示する

NEXT

モバ友を招待してインセンティブを付与する