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

mixiアプリ

mixiアプリ » 技術仕様（RESTful API方式） » モバイル » 課金API（mixiポイント決済）

課金API（mixiポイント決済）

mixiモバイルポイント利用プロトコルの詳細とmixiモバイルポイント決済方法の詳細を記載しています。

mixiモバイルポイント利用プロトコルは、mixiモバイルポイントを使ってアイテム等の購入を行うためのポイント決済情報のプロトコルです。mixiモバイルポイント利用プロトコルはHTTP上でAtom Syndication Format[RFC4287]をやり取りします。

mixiモバイルポイント決済方法はポイント決済情報の作成から購入の確定の処理までを記載しています。

課金APIの利用ついては、mixiペイメントプログラムの「企画申請」通過後に可能になりますのでご注意ください。

はじめに

mixiモバイルポイント利用プロトコルは、mixiモバイルポイントを使ったアイテム等の購入を行うための決済情報の作成を行うプロトコルでHTTPと、XMLを用います。このプロトコルはmixiモバイルポイントに関する次に示す機能を提供します。

  • mixiモバイルポイント利用の決済情報の作成

mixiモバイルポイント決済方法はポイント決済フロー、ポイントの残高不足時の処理、ポイント決済情報の確定等の情報を記載しています。

制限事項

この文書に記載されたAPI等の利用はmixiにより許可されたSAPのアプリでしか利用できません。アプリごとに許可が必要です。

mixiモバイルポイント決済方法

ポイント決済フロー

ポイント決済フローは下記の順番で処理が行われ決済情報の作成から購入確定までの処理がおこなれます。

  1. 後述のポイント決済情報の作成APIを利用してポイント決済情報を作成。
  2. ポイント決済情報で取得した決済コードを利用し、後述のmixiモバイルポイントインターフェースへ決済コードとともに遷移する
  3. ユーザーは購入商品内容を確認し購入ボタンを押す。購入ポイント不足時には購入を促す画面をmixiモバイル側で表示を行う。
  4. ユーザが購入を確定すると決済情報作成時に後述のpoint::url要素のcallback_url属性値へHTTP Requestをmixi側から行う。
  5. SAPでは上記のHTTP Requestに対し成功のレスポンスを行うことにより、購入を確定する。SAP側で何かしらのエラーがあった場合には失敗のレスポンスを行う。成功以外のレスポンスを受けた場合mixi側では購入の確定を行わない。
    またSAPが10秒以内にレスポンスを返さない場合は購入の確定を行わない。SAPでは10秒以内に処理が終了しない場合には失敗のレスポンスを行い、購入を確定しない処理を行わなければならない。
  6. SAPで必要であればポイント決済情報の確認のAPIを用いて決済の完了の確認を行う。
  7. 購入確定また失敗後にユーザへその旨を通知する画面をmixiモバイルで表示を行う。
    その画面には後述のpoint::url要素のfinish_url属性値へのリンクが置かれる。
  8. ユーザは上記のリンクによってSAP側へと戻る。

ポイントの残高不足

ポイント決済情報を作成してmixiモバイルポイントインターフェースへ決済コードとともに遷移したときにポイント不足により購入できない可能性があります。この場合mixiモバイル側では追加購入を促す画面を表示し、ポイントの追加購入後に商品を購入するフローを提供します。SAP側ではポイント不足による処理等は必要ありません。

mixiモバイルポイントインターフェース

mixiモバイルポイントインターフェースは決済情報作成APIを利用して作成された決済コードを受け取りユーザのポイント購入のフローを提供します。SAPはポイント決済情報作成時に取得したmixiモバイルポイントインターフェースURLへ
ユーザを誘導することでこの機能を利用します。ユーザの誘導はredirectを利用します。a要素での遷移はできません。
またmixiモバイルポイントインターフェースへのURLはごく短い時間のセッションとなります。
そのためユーザが商品を選択後にポイント決済情報を作成しそのまま指定されたURLへRedirectを行ってください。

mixiモバイルポイントインターフェースURL
ポイント決済情報作成時のatom entryのlink要素のhref属性値

ポイント決済情報の確定

ポイント決済情報URIで作成したポイント決済情報は購入が確定されなければ仮売り上げ状態となり、ユーザのポイント消費や売り上げとしては計上されません。

購入の確定はmixiモバイルポイントインターフェースでユーザが商品の内容を確認し、購入ボタンを押したことをmixiモバイルで確認後にコールバックとしてHTTP RequestがSAP指定のURLへ送られ、SAPが成功のレスポンスを返すことにより確定します。

SAPの指定するコールバック先のURLは後述の決済情報作成時のpoint::url要素のcallback_url属性値で指定します。

callback_urlへ送られるパラメータは下記となります。

opensocial_app_id アプリID
opensocial_owner_id ユーザのID
point_code 決済コード
status 10：購入成功
20：購入キャンセル
updated 購入確定日時UTC

さらにcallback_urlにはmixiアプリモバイルのproxyの仕様と同様にOauthによるSigned requestが適用されます。

※不正な購入を防ぐために必ずこの署名の検証を行ってください。

署名の検証はmixi Developer Centerの2-legged OAuthによるAPIアクセスを参考にしてください。

追加の仕様として各種oauthパラメータでベース文字列の作成時にopensocial_app_id, opensocial_owner_id , point_code, status, updatedを追加してください。

例としてベース文字列は下記の形となります。

  GET&http%3A%2F%2Fsap.co.jp%3A8677%2Ft%2Fcallback.pl&oauth_consumer_key%3Dxxxxxxxxx%26oauth_nonce%3D546f6a2c3a6f86b5f97c%26oauth_signature_method%3DHMAC-SHA1%26oauth_timestamp%3D1251959669%26oauth_version%3D1.0%26opensocial_app_id%3D1%26opensocial_owner_id%3D1%26point_code%3D7HBcfrCFnpHf7nCew3sy%26status%3D10%26updated%3D2009-09-03T06%253A34%253A29Z

SAPはcallback_urlへ送られたパラメータ内容を確認し、適切に処理できた場合に成功のレスポンスを返します。

成功のレスポンスで返すべきレスポンスの内容は下記となります。

  HTTP Responseの内容

    Status: 200
    Content-Type: text/plain    

    OK

上記以外のレスポンスをSAPが返した場合には購入の確定処理を行いません。

上記のレスポンスはSAPは10秒以内に行わなければなりません。10秒以内にレスポンスがなかった場合には購入確定の処理は行われません。SAPでは10秒以内に処理が行えなかった場合、成功以外のレスポンスを返し、購入確定の処理を行わないようにする必要があります。

購入確定また失敗後のSAP側へのユーザの誘導

購入確定または失敗時にはmixiモバイルポイントインターフェースでユーザにその旨を通知する画面を表示します。
表示される画面にはSAPへのリンクが表示され、そのリンクをユーザが押すことによりSAP側へ誘導します。

SAPへの誘導リンク先は後述の決済情報作成時のpoint::url要素のfinish_url属性値で指定します。

finish_urlへ送られるパラメータは下記となります。

point_code 決済コード
status 10：購入成功
20：購入キャンセル

finish_urlの遷移にはmixiアプリモバイルのproxyを通しての遷移となります。
mixiアプリモバイルのproxyについては別途資料を参照して下さい。

SAP側ではこのときに購入確定の処理を行わないようにしてください。
このリクエストはユーザの選択によるもののため必ず行われるではありません。

mixiモバイルポイント利用プロトコル

mixiモバイルポイント利用プロトコルはmixiモバイルポイントの決済情報を操作するために、次に示すHTTPメソッドを使用します。

  • POST mixiモバイルポイント利用の決済情報の作成
  • GET mixiモバイルポイント利用の決済情報の確認

mixiモバイルポイント利用の決済情報のデータはAtom Syndication Formatのentry要素で表現します。

ポイント決済情報の作成

指定されたポイント決済情報URIに対して、POSTリクエストを送信することで新しいポイント決済情報を作成できます。

22.jpg

ポイント決済情報URIは下記となります。

http://api.mixi-platform.com/atom/mobile/point/@me

上記URLに対しパラメータ xoauth_requestor_id が必要です。
xoauth_requestor_idはmixi Developer Centerの2-legged OAuthによるAPIアクセスを
参考にしてください。

ポイント決済情報作成の例

  POST /atom/mobile/point/@me?xoauth_requestor_id=xxxxxxxx HTTP/1.1
  Host: api.mixi-platform.com
  Content-Length: xxx
  Content-Type: application/atom+xml;type=entry
  Authorization: xxxxxxxxxxxx

  <?xml version="1.0" encoding="utf-8"?>
  <entry xmlns="http://www.w3.org/2005/Atom"
         xmlns:app="http://www.w3.org/2007/app"
         xmlns:point="http://mixi.jp/atom/ns#point">
    <title />
    <id />
    <updated />
    <author><name /></author>
    <content type="text/xml">
      <point:url callback_url="http://xxxx" finish_url="http://xxxx" />
      <point:items>
        <point:item id="SAP指定アイテムID" name="エクスカリバー" point="100" />
      </point:items>
    </content>
  </entry>

SAPテスト購入時のpoint:item要素例

  <point:url callback_url="http://xxxx" finish_url="http://xxxx" />
  <point:items>
    <point:item id="SAP指定アイテムID" name="エクスカリバー" point="100" />
  </point:items>
  <point:status is_test="true" />

point:url要素はcontent要素の子要素です。
point:url要素には必要なURIを記述する。この要素は必須です。

callback_url ユーザがポイント消費確定時にサーバから通知するSAPのURI。必須の属性です。URIのみを記述してください。クエリパラメータには対応していません。文字数は半角255文字以内としてください。
finish_url ユーザがポイント消費またキャンセル時の戻り先のSAPのURI。必須の属性です。URIのみを記述してください。クエリパラメータには対応していません。文字数は半角255文字以内としてください。

point:items要素はcontent要素の子要素です。
point:items要素には購入するアイテム情報のpoint:item要素を記述する。この要素は必須です。
point:item要素は必ず一つ必要です。複数書くことはできません。

point:item要素はpoint:items要素の子要素です。
point:item要素には購入するアイテム情報の詳細を記述する。この要素はpoint:items要素に必ず一つ必要です。複数書くことはできません。

id SAPで管理しているアイテムのIDを記述する。必須の属性です。半角英数字で、文字数は半角64文字以内としてください。
name ポイント消費時にユーザに表示するアイテムの名前を記述する。必須の属性です。
文字数は半角128文字以内としてください。
point 購入アイテムの消費ポイントです。アイテムの単価となります。1以上の数値を指定します。必須の属性です。上限下限等の設定単位は別途mixiペイメントプログラム（課金）のご案内を確認してください。

point:status要素はcontent要素の子要素です。
point:status要素にはこの決済のステータスを記述します。この要素は省略可能です。

is_test SAPでのテスト購入時に”true”を指定します。”true”が指定された場合のテスト購入では
ポイントの消費は行われません。この項目は省略可能です。省略した場合はテスト購入にはなりません。※テスト期間中（開発中）はこのフラグをつけなくてもすべてテスト購入となります。本番利用中にSAPでテスト購入を行う場合などに指定します。

ポイント決済情報作成時応答の例

  HTTP/1.1 200
  Content-Length: xxx
  Content-Type: application/atom+xml;type=entry;charset=utf-8

  <?xml version="1.0" encoding="utf-8"?>
  <entry xmlns="http://www.w3.org/2005/Atom">
    <title />
    <id>ポイント決済コード</id>
    <updated>ポイント決済情報作成日時(UTC)</updated>
    <author />
    <content />
    <link rel="related" href="mixiモバイルポイントインターフェースURL"/>
  </entry>

atom entryの各要素の意味は下記になります。

id要素はポイント決済コードを表します。この値は一つの決済フローを通して決済情報を特定するための値となります。
SAPではこの値を保存して決済の確定処理などを行います。
ポイント決済コードはすべての決済でユニークな値であり、再利用されることはありません。
文字数は半角40文字以内となります。
updated要素はこの決済が作成された日時となります。時間表記はUTCとなります。
link要素はmixiモバイルポイントインターフェースURLを含みます。href属性値がmixiモバイルポイントインターフェースURLとなります。

ポイント決済情報の確認

作成したポイント決済情報の内容を確認することが出来ます。ポイント決済情報には購入状態が含まれ購入が完了しているか等を確認することが出来ます。

リクエストを送信することで、ポイント決済情報URIにて特定されるポイント決済情報の内容を取得することができます。

22-12.gif

1. クライアントはポイント決済情報URIに対して確認する決済コードとともにGETリクエストを送信する。
2. 成功すると、サーバはHTTPステータスコード200と決済情報のentry文書を返します。

ポイント決済情報URIは下記となります。

  https://api.mixi-platform.com/atom/mobile/point/@me

上記URLに対しパラメータ xoauth_requestor_id と point_code が必要です。xoauth_requestor_idはmixi Developer Centerの2-legged OAuthによるAPIアクセスを参考にしてください。point_codeはポイント決済情報作成時のatom entryのid要素となります。

ポイント決済情報の確認ではAPIから保証されたatom entry文書を受け取るためにhttpsを利用してください。

ポイント決済情報確認の例

  GET /atom/mobile/point/@me?xoauth_requestor_id=xxxxxxxx&point_code=XXXXXX
  Authorization: xxxxxxxxxxxx

ポイント決済情報確認時応答の例

  HTTP/1.1 200
  Content-Length: xxx
  Content-Type: application/atom+xml;type=entry;charset=utf-8

  <?xml version="1.0" encoding="utf-8"?>
  <entry xmlns="http://www.w3.org/2005/Atom"
         xmlns:app="http://www.w3.org/2007/app"
         xmlns:point="http://mixi.jp/atom/ns#point">
    <title />
    <id>ポイント決済コード</id>
    <updated>最終状態変更日時(UTC)</updated>
    <author><name /></author>
    <content type="text/xml">
      <point:url callback_url="http://xxxx" finish_url="http://xxxx" />
      <point:items>
        <point:item id="SAP指定アイテムID" name="エクスカリバー" point="100" />
      </point:items>
      <point:status>create</point:status>
    </content>
  </entry>

atom entryの各要素についてはポイント決済情報作成の例を参照してください。
ここでは追記分のみを記載します。

id要素はポイント決済コードです。ポイント決済情報作成時の応答のid要素と同じ値になります。

updated要素はpoint:status要素の値の最終変更日時となります。

point:status要素の値は現在の購入状態を表します。
値の内容はそれぞれ下記の状態を表します。

create ポイントを決済情報を作成した状態です。ユーザが明示的にキャンセルなどを選択しなかった場合もこの状態です。
cancel ユーザが明示的にキャンセルを選択し、キャンセル処理に成功した状態です。
complete ユーザが明示的に購入を選択し、購入処理に成功した状態です。
pay_back ポイントの払い戻し処理が完了した状態です

認証情報

mixiモバイルポイント利用プロトコルを利用する全てのリクエストには認証情報を付与する必要があります。認証の手段としてOAuthプロトコルを採用しています。

  • OAuth

Oauthの認証方法はmixi Developer Centerの2-legged OAuthによるAPIアクセスを参考にしてください。

ポイント決済情報作成時の認証について

ポイント決済情報の作成ではatomでAPIへ送られるRequest Bodyの検証が必要となり、oauth_body_hashがoauthパラメータに必要となります。

oauth_body_hashはPOSTする決済情報作成のatomをsha1でハッシュを作成したのちbase64でエンコードしてください。

Oauth_body_hash作成サンプルコード
perl

  use MIME::Base64;
  use Digest::SHA;
  my $body_hash = MIME::Base64::encode_base64(Digest::SHA::sha1($atom_body));
  chomp $body_hash;

php

  $body_hash = base64_encode(sha1($atom_body, true));

作成した値をOauthのsignatureベース文字列に付与してOauthのSignatureを作成します。

サンプル HTTP Request:

  POST /atom/mobile/point/@me?xoauth_requestor_id=xxxxxxxx HTTP/1.1
  Host: api.mixi-platform.com
  Content-Length: xxx
  Content-Type: application/atom+xml;type=entry
  Authorization: xxxxxxxxxxxx

  <?xml version="1.0" encoding="utf-8"?>
  <entry xmlns="http://www.w3.org/2005/Atom"
         xmlns:app="http://www.w3.org/2007/app"
         xmlns:point="http://mixi.jp/atom/ns#point">
    <title />
    <id />
    <updated />
    <author><name /></author>
    <content type="text/xml">
      <point:url callback_url="http://xxxx" finish_url="http://xxxx" />
      <point:items>
        <point:item id="SAP指定アイテムID" name="エクスカリバー" point="100" />
      </point:items>
    </content>
  </entry>

oauth_body_hashの作成

<?xml version="1.0" encoding="utf-8"?>
  <entry xmlns="http://www.w3.org/2005/Atom"
         xmlns:app="http://www.w3.org/2007/app"
         xmlns:point="http://mixi.jp/atom/ns#point">
    <title />
    <id />
    <updated />
    <author><name /></author>
    <content type="text/xml">
      <point:url callback_url="http://xxxx" finish_url="http://xxxx" />
      <point:items>
        <point:item id="SAP指定アイテムID" name="エクスカリバー" point="100" />
      </point:items>
    </content>
  </entry>

からsha1でhash作成後base64でエンコード

g3EeCmyqqAEMz1h2mNsLvpcPdnc=

この値を利用して下記のような値でベース文字列を生成します。

1. POST
2. http://api.mixi-platform.com/atom/mobile/point/@me
3.

oauth_body_hash=g3EeCmyqqAEMz1h2mNsLvpcPdnc%3D&oauth_consumer_key=38dacb31c1759ea5ecc8&oauth_nonce=aiueo&oauth_signature_method=HMAC-SHA1&oauth_timestamp=1259823826&oauth_version=1.0&xoauth_requestor_id=xxxxxxxx

※3.のそれぞれの値はURIエスケープが必要です。oauth_body_hashの値のエスケープを忘れないでください。

http://oauth.net/core/1.0a#encoding_parameters

ここより先は2-legged OAuthによるAPIアクセスと同じようにsignatureを生成してください。

作成されるベース文字列

  POST&http%3A%2F%2Fapi.mixi-platform.com%2Fatom%2Fmobile%2Fpoint%2F%40me&oauth_body_hash%3Dg3EeCmyqqAEMz1h2mNsLvpcPdnc%253D%26oauth_consumer_key%3D38dacb31c1759ea5ecc8%26oauth_nonce%3Daiueo%26oauth_signature_method%3DHMAC-SHA1%26oauth_timestamp%3D1259823826%26oauth_version%3D1.0%26xoauth_requestor_id%3Dxxxxxxxx

コンシューマーシークレットを’abcdefg’とした場合 ‘abcdefg&’ でシグネチャを生成

ASu9mQUwqQdJLlD4SnzdtGrc8lY=

あとは生成されたパラメータをAuthorizationヘッダに追加して、APIリクエストを送信します。

ポイント決済情報確認時の認証について

ポイント決済情報の確認時にはパラメータにxoauth_requestor_idのほかにpoint_codeが必要となります。

ベース文字列の作成時にpoint_codeを追加してベース文字列を作成してください。

例としてベース文字列は下記の形となります。

GET&http%3A%2F%2Fapi.mixi-platform.com%2Fatom%2Fmobile%2Fpoint%2F%40me&oauth_consumer_key%3D524b15d913a24e98bc45%26oauth_nonce%3Daiueo%26oauth_signature_method%3DHMAC-SHA1%26oauth_timestamp%3D1259909972%26oauth_version%3D1.0%26point_code%3DRpmmatcnpw8WLtg5HY9k%26xoauth_requestor_id%3Dxxxxxxxx

制限事項

作成、確認のAPIに対しバッチ処理などの連続した処理を行わないでください。基本的にはユーザのアクセスがあった時にAPIを利用してください。mixi側では一定の制限を超えるリクエストがあった場合等にAPI実行に対する制限を行うことがあります。

ポイント決済情報の確認も2-legged OAuthによるAPIアクセスの仕様のためユーザがアプリを解除した場合には決済情報を確認することができなくなります。

プロトコルバージョン

http://api.mixi-platform.com/atom/mobile/point/@me

revision 1.1.0
2009年09月14日公開
2009年12月03日改定
2010年02月25日改定

文献

[RFC4287]:
Nottingham, M. and R. Sayre, “The Atom Syndication Format”,
RFC 4287, December 2005.

このページの上部へ

©MIXI