決済サービス
概要
Android ゲームポイント対応に伴い、Shell App Framework for Android の場合、仮想通貨は『ゲームポイント』となります。詳細は以下 URL をご確認ください。
https://docs.mobage.com/display/JPSA/AndroidGPShellApp
※ Shell App Framework for iOS の仮想通貨はこれまでどおり『ゲームポイント』となります。
決済サービスを使うと、モバコイン決済を使ったコンテンツ課金ができるようになります。
注意事項
フロー15.から16.による決済ステータスの確認、19.から20.によるアイテム付与漏れ対応が必須となっております。
購入アイテム付与の確定処理が正常に成功していれば問題ありませんが決済が失敗しているケースにつきましてはアイテム回収や取消し処理がゲームサーバー上にて必要となります。通信障害により購入アイテム付与の確定処理が行われないケースも想定されますので購入アイテム付与確定漏れ対応も必要となります。
サービスの流れ
- ユーザーがコンテンツの購入ページから Gadgetサーバーに対して購入リクエストを行います。
- Gadgetサーバーは通常のリクエスト通り、ゲームサーバーへリクエストを中継します。
- ゲームサーバーは API サーバーに対して決済情報を Payment API を利用して送信します。
- APIサーバーはPayment IDと決済ページのエンドポイントURLを生成してゲームサーバーに返します。
- ゲームサーバーは Gadgetサーバーに決済ページのエンドポイントURLへの遷移を含むレスポンスを返します。
- Gadgetサーバーはレスポンスをユーザーに中継します。
- ユーザーはプラットフォーム内に設置された決済ページにアクセスします。
- プラットフォーム内にて決済を行います。
- ユーザーが最終的に決済のリクエストを送ります。
- プラットフォームより売上確定のリクエストがゲームサーバーに送られます。該当Payment IDに対して既に購入アイテム付与開始処理している場合、エラーとする処理を行います。
- パートナーが売上確定リクエストに対してHTTP 200 OKのレスポンスを返すことによって売上が確定されます。
- ユーザーへパートナーが指定した購入終了ページへの遷移が返ります。
- ユーザーは購入終了ページへ遷移されます。その際に Payment ID が payment_id クエリパラメータとして付いてきます。
- Gadgetサーバーは通常のリクエスト通り、ゲームサーバーへリクエストを中継します。
- Payment API を利用して決済の成功可否を確認します。APIサーバーに対してリクエストを行います。
- APIサーバーより、指定された Payment ID の決済の成功可否が返ります。成功可否によってゲームサーバー上での購入アイテム付与の確定処理またはキャンセル処理などを行います。
- ゲームサーバーは決済が終了した旨のページを生成してGadgetサーバーへ返します。
- Gadgetサーバーはレスポンスをユーザーに中継します。
- 通信障害等により購入アイテム付与の確定処理が済んでいないPayment IDがある場合、バッチ等でPayment API を利用して決済の成功可否を確認して下さい。
- APIサーバーより、指定された Payment ID の決済の成功可否が返ります。決済ステータスが成功かつアイテム付与を行っていないPayment IDの場合、購入アイテム付与の確定処理を行います。
決済情報の開始と確認
決済を行う際に、Payment API を利用して決済情報を送信する必要があります。
リクエスト
決済情報として指定できる値は以下になります。
| パラメータ名 | 説明 |
|---|---|
| callbackUrl | ゲームサーバー側の決済完了通知用の URL |
| finishUrl | ゲームサーバー側の決済終了画面用の URL |
| itemId | ゲームサーバーがアイテムを区別する為の識別子 |
| name | アイテムの名称 |
| unitPrice | アイテムの単価(コイン) |
| amount | アイテムの購入個数 |
| description | アイテムの説明文 |
| imageUrl | アイテム画像のある URL |
- callbackUrl と finishUrl に指定できるポート番号は80/443のみになります。
API サーバーは決済を一意に認識する Payment ID と決済を行う為の endpointUrl 等を含めたレスポンスを所定のフォーマットで返します。ゲームサーバーはユーザーをこの endopointUrl にリダイレクトあるいはリンクを介して遷移させる必要があります。API Server とのやり取りに関する詳細は Payment API をご覧ください。
売上確定
決済ページへの遷移
API から取得した endpointUrl (=決済ページ) にて決済の確認を行います。通常はユーザーを API から取得した endpoingUrl にそのまま遷移すれば良いですが、決済ページの配色を変えたい場合には endpointUrl に以下のクエリパラメータを追加することにより可能です。
| パラメータ名 | 必須 | 説明 |
|---|---|---|
| p | ○ | Payment ID。endpointUrl に含まれています |
| app_id | ○ | アプリケーションID。endpointUrl に含まれています |
| color | body-color | |
| bkcolor | body-background-color | |
| hlcolor | hilight用のcolor | |
| hlbkcolor | hilight用のbackground-color |
- 値には、16進の色コードをurlエンコードした値を指定してください
サンプル
http://pfpay.mbga.jp/_pf_pay_confirm?p=AAAAAAAA-AAAA-AAAA-AAAA-AAAAAAAAAAAA&app_id=12000001&color=%23611c00&bkcolor=%23fffd6e&hlcolor=%23ffffff&hlbkcolor=%2347bc00
リクエスト
プラットフォームからの売上確定の時のcallbackUrlに対するリクエストは以下のクエリパラメータが追加されて送られます。
| opensocial_app_id | アプリケーション ID |
| opensocial_viewer_id | このアプリケーションを利用しているユーザーの ID |
| opensocial_owner_id | このアプリケーションをインストールしているユーザーの ID |
| payment_id | Payment ID |
| updated | 更新時間 |
| status | ステータス (常に10) |
- 現在は opensocial_viewer_id と opensocial_owner_id には同じ値が含まれます。
また、リクエストは OAuth による署名が適用されます。必ずこの妥当性の確認を行ってください。
レスポンス
売上確定のリクエストを受けたゲームサーバーは重複した Payment IDでないかの確認などの適切な処理を行った後に HTTP ステータス 200 の HTTP レスポンスを返す必要があります。
例)
Status: 200
Content-Type: text/plain
OK
HTTP ステータス 200 以外のレスポンスを返した場合はプラットフォーム上では売上を確定せず、ユーザーの決済も行いません。また、リクエストを受けてからレスポンスを返すまでに10秒以上かかった場合にもエラーと見なされます。
購入終了ページ
リクエスト
プラットフォームからの売上確定の後のfinishUrlに対するリクエストは以下のクエリパラメータが追加されて送られます。
| opensocial_app_id | アプリケーション ID |
| opensocial_viewer_id | このアプリケーションを利用しているユーザーの ID |
| opensocial_owner_id | このアプリケーションをインストールしているユーザーの ID |
| payment_id | Payment ID |
- 現在は opensocial_viewer_id と opensocial_owner_id には同じ値が含まれます。
また、リクエストは OAuth による署名が適用されます。必ずこの妥当性の確認を行ってください。
レスポンス
購入終了ページのリクエストを受けたゲームサーバーは決済のステータス確認やアイテム付与などの適切な処理を行った後に 購入終了ページのHTMLコンテンツを返す必要があります。
決済結果の確認
最後に決済が正常に終了しているかを確認します。
成功していればそのままレスポンスを返して終了ですが、万が一ゲームサーバー上では決済が確定していても決済失敗のステータスが返っている場合は決済の取り消しとアイテム付与の取り消しを行ってレスポンスを返す必要があります。
ユーザが購入した商品(アイテム等)をユーザに付与したことを確定するタイミングは、決済成功をAPIで確認した後としてください。
決済ステータスの遷移について
Payment API レスポンスのstatus値は下記の遷移が想定されます。
Payment ID は発行から30分で有効期限が失効されるため、それ以降のステータス変更は発生しません。
なお成功となった決済ステータスがエラーに変更されることはありません。
Sandbox におけるテスト
Sandbox ではテスト支援ページからテストアカウントにコインを擬似的に付与することができます。
詳しくは、Mobage Developers のテストアカウント一覧から該当のテストアカウントの詳細ページよりテスト支援ページをご覧ください。
更新履歴
- 2013/03/01
- ドキュメント移行
- 2013/02/22
- 決済ステータスの遷移について追記。
- 2013/01/08
- 決済セキュリティを強化。実装方法を変更。
- シーケンス画像を変更。
- 処理文言統一。
- 2012/08/09
- 注意事項を追加。
- 2011/09/28
- サンプルのURLのドメインを変更 ( game.mbga.jp -> pfpay.mbga.jp )
- 2011/05/23
- 「決済ページへの遷移」を追加。
- 2011/04/08
- 「決済情報として指定できる値」のURLパラメータの注意事項にポート番号を追加。
- 2011/02/23
- 「サービスの流れにおける」決済の成功可否の確認を「強く推奨」に変更。