mixi Developer Center (ミクシィ デベロッパーセンター)

PC向け課金API（クレジットカード対応）を利用することにより、
クレジットカード決済を使ったアイテム課金をmixiアプリPC版に組み込むことができます。ここでは、mixiアプリにてPC向け課金APIをどのように利用して組み込むかを説明いたします。

制限事項

ここで説明するPC向け課金APIの利用は、mixiより許可されたSAPが開発したmixiアプリのみで利用することができます。その際、SAPは開発するmixiアプリごとに許可を得なければなりません。

利用手順

PC向け課金APIは、OpenSocial Virtual Currency APIをベースに、mixi Platform独自の決済確認フローを追加したAPIです。決済内容を保護するために、mixiアプリから規定のJavaScript APIを呼び出すだけでなく、いくつかバックエンド側(SAP側の外部サーバ)上で行わなければならない処理があります。

OpenSocial Virtual Currency APIについての詳しいリファレンスは、以下を参照ください。

【OpenSocial Virtual Currency API】
https://docs.google.com/Doc?id=dfjcf7w4_10ddst9xd9&hl=en

【上記の日本語訳】
http://docs.google.com/View?id=dhsg598c_994hdb9pwcf

事前準備

PC向け課金APIでは、通信内容の妥当性検証を行うために、署名の生成や検証を行うことになります。使われる署名は、HMAC-SHA1にて生成された文字列となります。この際に使用されるキーは、mixiアプリの設定画面(edit_appli.pl)にて表示されるConsumer Secretです。予めこのConsumer Secret文字列をその画面より入手しておきます。

PC向け課金APIを利用する際には、Gadget XMLファイルに以下の宣言が書かれている必要があります。

<Module>
  <ModulePrefs ...>
    <Require feature="opensocial-payment" />
    ...
  </ModulePrefs>
  ...
</Module>

基本的な処理フロー

mixiアプリ内でPC向け課金APIを利用する際の代表的な処理フローを以下に示します。

1. mixiアプリからバックエンドサーバに決済情報の作成を依頼する
2. バックエンドサーバにて決済情報を作成し、mixiアプリに返却する
3. 決済情報を元に、決済のためのAPIを呼び出す
4. mixiサーバからバックエンドサーバに、ペイメントコードが送信される
5. バックエンドサーバはペイメントコードを保持し、mixiサーバに結果を返却する
6. 決済のための情報入力および確認画面に遷移し、ユーザの操作後に決済処理が行われる
7. mixiサーバからバックエンドサーバに、決済処理ステータスが送信される
8. バックエンドサーバは決済情報を確認後、mixiサーバに結果を返却する
9. 決済完了画面が表示され、ユーザが「mixiアプリへ戻る」ボタンを押下する
10. mixiアプリが再起動し、決済ステータスがパラメータとして渡される

決済情報の作成

ユーザが何らかのアイテムの購入をmixiアプリ内で希望した際に、最初にmixiアプリからバックエンドサーバに対して、決済情報の作成を依頼します。この時点で、購入対象のアイテムIDが決定します。

作成の依頼は、gadgets.io.makeRequest()関数を利用すると良いでしょう。その際に、署名付きリクエストを利用すると、バックエンド側サーバにて通信内容の妥当性検証を行うことが可能です。

以下に、サンプルコードを記載いたします。

var itemId = 123; // アイテムID
var url = "http://sap.server.host/create_order"; // バックエンドサーバのURL

var p = {};
p[gadgets.io.RequestParameters.AUTHORIZATION] = gadgets.io.AuthorizationType.SIGNED;
p[gadgets.io.RequestParameters.POST_DATA] = gadgets.io.encodeValues({item_id: itemId});
p[gadgets.io.RequestParameters.METHOD] = gadgets.io.MethodType.POST;
gadgets.io.makeRequest(url, function(response) {
  // do something
}, p);

決済情報の作成

決済情報の作成要求を受け取ったバックエンドサーバでは、アイテムIDを元に必要な情報を準備し、それらを元に署名を作成します。これらを結果としてmixiアプリに返却します。

決済情報として必要な項目を以下に示します。

まず、これらの項目を「&」で連結して、1つの文字列を作成します。その際に、項目名はアルファベット順とします。また、全ての項目値はURIエスケープを行っておきます。

callback_url=http%3A%2F%2Fsap.server.host%2Fcreate_order&inventory_code=123&is_test=true&item_id=123&item_price=500

この文字列に対して、さらに以下の加工を行います。その結果は、上記のパラメータに対する署名となります。

• 上記文字列全体をURIエスケープする – (1)
• 予め入手したConsumer Secretの末尾に”&”を付与する – (2)
• (2)をキーとしてHMAC-SHA1アルゴリズムを使用し、(1)のダイジェスト値を得る – (3)
• (3)をBASE64エンコードする

上記のパラメータ値および生成した署名を、mixiアプリに結果として返却します。

※ URIエスケープは、こちら(http://oauth.net/core/1.0a#encoding_parameters)に則って行ってください。

決済APIの呼び出し

バックエンドサーバから得られた決済情報に基づいて、決済のためのAPIを呼び出します。このAPIとして、opensocial.requestPayment()関数を利用します。

var paymentHandlerUrl = "http://sap.server.host/create_order";

var params = {};
params[opensocial.Payment.Field.AMOUNT] = 250;
params[mixi.Payment.Field.ITEM_NAME] = "エクスカリバー";
params[mixi.Payment.Field.SIGNATURE] = "TmihyproUc02HOh17W0uz++WdYM=";
params[mixi.Payment.Field.ITEM_ID] = 123
params[mixi.Payment.Field.IS_TEST] = 'true';
params[mixi.Payment.Field.INVENTORY_CODE] = 123;
params[opensocial.Payment.Field.PAYMENT_TYPE] = opensocial.Payment.PaymentType.PAYMENT;

var payment = opensocial.newPayment(params);

opensocial.requestPayment(payment, paymentHandlerUrl);

まず、決済オブジェクトをopensocial.newPayment()関数で生成します。その際に必要となる項目は、以下となります。

実際の決済処理は、opensocial.requestPayment()関数によって呼び出します。この関数は、以下の引数を受け付けます。

1. 決済オブジェクト
2. mixiサーバから呼び出されるバックエンドサーバのURL

requestPayment()関数を呼び出すと、mixiサーバに決済開始要求がmixiアプリから送信されます。

ペイメントコードの送信

mixiアプリからrequestPayment()関数が呼び出された後、mixiサーバはpaymentHandlerUrl引数にて指定されたバックエンドサーバのURLにペイメントコードを送信します。その際に送られるパラメータは以下となります。

このリクエストは、2-legged OAuthによる署名が施されています。署名は、Authenticationヘッダに記載されています。不正な購入を防ぐために、必ずこの署名の検証を行ってください。検証方法は、以下のURLを参照ください。ただし、検証時のベース文字列として、上記にあげたパラメータに関しても含めるようにしてください。

[OAuth Signatureの検証方法について]
http://developer.mixi.co.jp/appli/spec/mob/validate-oauth-signature

結果の返却

署名の検証後、ペイメントコードなど決済内容をバックエンドサーバ側で保持します。その後、成功のレスポンスを返却します。

Status: 200
Content-Type: text/plain

OK

このレスポンスは、10秒以内に行う必要があります。10秒以内にレスポンスがなかった場合、決済処理は行われません。

ユーザによる決済確認

mixiサーバが結果を受信後、決済のための情報をユーザに入力してもらうための画面に遷移します。そこでユーザは、パスワード入力、クレジットカード情報の入力および確認を行います。その後、mixiサーバ内で決済処理が実行されます。

決済処理のテストの場合は、対象mixiアプリの利用者が開発者自身だったときにのみ、テストであることを示すための表示が行われます。

決済処理ステータスの送信

mixiサーバ内で決済処理が行われた後に、再度バックエンドサーバに決済確定のためのリクエストが送信されます。リクエストは、requestPayment()関数の呼び出し時に渡されたpaymentHandlerUrlで指定したURLとなります。リクエストに含まれるパラメータは、以下となります。

このリクエストは、2-legged OAuthによる署名が施されています。署名は、Authenticationヘッダに記載されています。不正な購入を防ぐために、必ずこの署名の検証を行ってください。検証方法は以下のURLを参照ください。ただし、検証時のベース文字列として、上記にあげたパラメータに関しても含めるようにしてください。

[OAuth Signatureの検証方法について]
http://developer.mixi.co.jp/appli/spec/mob/validate-oauth-signature

結果の返却

署名の検証後、リクエストに含まれる各パラメータに基づいて、バックエンドサーバ側にて決済内容の確認とアイテム購入処理などを行います。その後、その後、成功のレスポンスを返却します。

Status: 200
Content-Type: text/plain

OK

このレスポンスは、10秒以内に行う必要があります。10秒以内にレスポンスがなかった場合、決済確定の処理は行われません。

ユーザへの決済完了表示

バックエンドサーバから結果を受け取ったmixiサーバは、ユーザに決済結果を示す画面を表示します。ユーザは、「mixiアプリへ戻る」ボタンを押下します。

mixiアプリの再起動

最後に、mixiアプリを起動するためにrun_appli.plページに遷移します。その際、決済ステータスが起動パラメータとして渡されます。

決済に成功したかどうかをmixiアプリにて確認するために、gadgets.views.getParams()関数を利用します。

var params = gadgets.views.getParams();
var mixiPaymentStatus = params["mixiPaymentStatus"];
if (mixiPaymentStatus && mixiPaymentStatus == "ok") {
  // 決済成功時の処理
}

この起動パラメータは、悪意を持ったユーザによって容易に変更することが可能です。そのため、このパラメータ値に基づいて決済に関する重要な判断を行うことはできませんので、ご注意ください。

課金テスト時の動作について

課金API（クレジット）実装の段階においては、必ず決済「成功」「失敗」両方の動作確認を行って下さい。

※決済に失敗すると取引不成立となり、ユーザーへは請求されず、弊社からもお支払いの対象外となります。課金失敗にもかかわらず課金成功と同じ動作フローとならないよう、十分ご確認ください。

テスト方法

1. 「テスト課金」の条件を整える
   • 課金ステータスが「テスト中」である
     課金の企画申請をされてからテスト申請が承認されるまでの間は、課金ステータスは「テスト中」となります。
   • アプリの課金API呼び出しパラメータを「is_test=true」とする
2. 決済テストを行う
   • 上記の「テスト課金」の条件が整っている状態で、下記のカード番号を入れて動作をご確認ください。
     

     カード番号	結果	決済処理ステータス
     0000-0000-0000-0000	成功	10=購入成功
     上記以外	失敗	10以外

3. アプリの決済成功時・失敗時動作を確認する
   決済処理ステータスに応じて、正しい動作分岐をすることをご確認ください。
   とくに失敗の場合は下記の点にご注意下さい。
   • 成功時だけ引き渡されるべきアイテムが引き渡されないこと
   • 決済成功履歴に本取引が表示されないこと