メインコンテンツまでスキップ

アイテム課金をする

概要​

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 で指定する必要があります。

<?xml version="1.0" encoding="UTF-8" ?>
<Module>
<ModulePrefs ...>
<Require feature="opensocial-0.8" />
<Require feature="opensocial-payment" />
<Link rel="payment.handler" href="http://example.com/your-app/payment-handler" />
...
</ModulePrefs>
...
</Module>

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

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

決済情報の開始​

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

var itemParams = {};
itemParams[opensocial.BillingItem.Field.SKU_ID] = 12345;
itemParams[opensocial.BillingItem.Field.PRICE] = 100;
itemParams[opensocial.BillingItem.Field.COUNT] = 2;
itemParams[mbga.BillingItem.Field.NAME] = "マシンガン";
itemParams[mbga.BillingItem.Field.IMAGE_URL] = "http://example.com/pic.gif";
var item = opensocial.newBillingItem(itemParams);

var params = {};
params[opensocial.Payment.Field.ITEMS] = [item];
params[opensocial.Payment.Field.AMOUNT] = 200;
var payment = opensocial.newPayment(params);
opensocial.requestPayment(payment, function(response) {
if (response.hadError()) {
// error
} else {
var payment = response.getData();
var orderId = payment.getField(opensocial.Payment.Field.ORDER_ID);
// ...
}
});
  • 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 オブジェクトが含まれます。

{"ITEMS":[{"PRICE":100,"NAME":"マシンガン","SKU_ID":12345,"DESCRIPTION":"連射ができます。","COUNT":2,"IMAGE_URL":"http://example.com/item.jpg"}],"AMOUNT":200,"PAYMENT_TYPE":"payment","ORDERED_TIME":1284547429317,"PAYMENT_ID":xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx}

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

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

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

{"order_id":"12345","response_code":"OK"}

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

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

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

決済の確定​

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

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

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

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

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

{"order_id":"12345","response_code":"OK","amount":200}

この時、署名が正しく、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_timestampUNIX タイムスタンプ値
oauth_versionOAuth のバージョン (1.0 固定)
  1. Gadgetサーバから送られてきたクエリパラメータをすべて取得します。
  2. 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 以上を利用してください

use strict;
use warnings;

use OAuth::Lite::ServerUtil;
use OAuth::Lite::Util qw/parse_auth_header/;
use CGI;

my $consumer_secret = 'YOUR CONSUMER SECRET';

my $cgi = CGI->new;
my ($realm, $params) = parse_auth_header($ENV{HTTP_AUTHORIZATION});
for my $key ($cgi->url_param) {
$params->{$key} = [$cgi->url_param($key)];
}

my $util = OAuth::Lite::ServerUtil->new(strict => 0);
$util->support_signature_method('HMAC-SHA1');

my $valid = $util->verify_signature(
method => $cgi->request_method,
url => $cgi->url,
params => $params,
consumer_secret => $consumer_secret,
);

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

<?php
require_once 'OAuth.php';

$consumer_key = 'YOUR CONSUMER KEY';
$consumer_secret = 'YOUR CONSUMER SECRET';
$req = OAuthRequest::from_request(NULL, NULL, NULL);
$consumer = new OAuthConsumer($consumer_key, $consumer_secret, NULL);
$token = new OAuthToken(
$req->get_parameter('oauth_token'),
$req->get_parameter('oauth_token_secret'));
$sign_method = new OAuthSignatureMethod_HMAC_SHA1();
$sign = $req->get_parameter('oauth_signature');
$valid = $sign_method->check_signature($req, $consumer, $token, $sign);
?>

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

Body Hash の計算​

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

Base String の生成​

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

body_hashBody Hash
nonceリクエスト毎にユニークな値
timestampUNIX タイムスタンプ値
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:

#!/usr/bin/perl

use strict;
use warnings;

use Digest::SHA1 qw(sha1_base64 );
use Digest::HMAC_SHA1;
use URI::Escape;
use OAuth::Lite::Util qw(gen_random_key);
use JSON;

my $consumer_key = 'YOUR_CONSUMER_KEY';
my $consumer_secret = 'YOUR_CONSUMER_SECRET';

my $body = encode_json({order_id => 'ORDER_ID', response_code => 'OK'});
my %param = (
timestamp => time(),
nonce => gen_random_key(),
consumer_key => $consumer_key,
body_hash => sha1_base64($body),
);

my @pairs = ();
for my $k (sort keys %param) {
push @pairs, sprintf('%s=%s', uri_escape($k), uri_escape($param{$k}));
}
my $base_string = join('&', @pairs);

my $hmac = Digest::HMAC_SHA1->new($consumer_secret);
$hmac->add($base_string);
my $sign = $hmac->b64digest;

my $header = "$base_string&signature=" . uri_escape($sign);

print "Content-type: application/json\r\n";
print "X-MBGA-PAYMENT-SIGNATURE: $header\r\n";
print "\r\n";
print $body;

PHP:

<?php

$consumer_key = 'YOUR_CONSUMER_KEY';
$consumer_secret = 'YOUR_CONSUMER_SECRET';

$body = json_encode(
array(
order_id => '12345',
response_code => 'OK'
));

$param = array(
timestamp => time(),
nonce => md5(microtime()),
consumer_key => $consumer_key,
body_hash => rtrim(base64_encode(sha1($body, true)), '=')
);

$params = array();
ksort($param);
foreach ($param as $key => $value) {
$out = urlencode($key) . '=' . urlencode($value);
array_push($params, $out);
}

$base_string = implode('&', $params);
$sign = rtrim(base64_encode(hash_hmac('sha1', $base_string, $consumer_secret, true)), '=');

header("Content-type: application/json");
header("X-MBGA-PAYMENT-SIGNATURE: ".$base_string."&signature=".urlencode($sign));
print $body;
?>

エラーレスポンス​

エラーコード表示内容
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
    • エラーレスポンスの項目を追記