電子キオスク API v2.0

APIゲームカタログ

このAPIはゲームカタログを提供するように設計されています。例えば、エクソーラシステムで使用できる全プロジェクトの一覧です。APIはプロジェクト名やプロジェクトアイコン、決済パラメータなど各プロジェクト基本情報を提供します。上記の情報は、プロジェクトの決済ページの作成で使用可能です。

ゲームカタログAPIは、電子キオスク経由の決済とUIに「ゲームボタン」を配置するときに役立ちます。電子キオスクの画面上で「ゲームボタン」に置き換えた通常のXsollaボタンを差し替えることで、ユーザーは好みのプロジェクトで簡単かつ常に決済できます。

APIのURL： https://api.xsolla.com/projects/list/index.php

フォーマットのリクエスト

パラメータをリクエストしてゲーム一覧を取得

署名の生成

署名は決済の確認と実行中に、安全を確保します。文字列のMD5ハッシュアルゴリズムから形成され、上述のパラメータを連結して生成されます。さらに下記の順番で「|」を使って区切られます。

1md5(<ID>|<secret_key>)

secret_key: 相手方の秘密鍵。

例： 秘密鍵"SecretKey"がある相手方#184用の署名は、次のように形成されます：

$sign=md5(“184|SecretKey”)=0a8d9fb24fcbac2efafec5e51045d05c

リクエスト例：

https://api.xsolla.com/projects/list/index.php?id=184&sign=0a8d9fb24fcbac2efafec5e51045d05c

レスポンス形式

リクエストへのレスポンスは、ゲーム一覧と各ゲームの基本情報が載ったXML形式で送信されます。XMLの構造は次のとおりです：

 1<projectlist>
 2   <project>
 3       <id>12345</id>
 4       <name>Game</name>
 5       <virtual_currency>Game of currency</virtual_currency>
 6       <logo>http://static.xsolla.com/img/game/12345.gif</logo>
 7       <limits>
 8           <min>Minimum of amount game of currency</min>
 9           <max>max of amount game of currency</max>
10       </limits>
11       <prompt>enter nickname of personage</prompt>
12       <v1>nickname of personage</v1>
13   </project>
14   ...
15</projectlist>

項目の説明

エラーに対するレスポンス形式

エラーが起きた場合、APIはXML形式のメッセージで応答します。

1<error>
2    <description>Incorrect signature</description>
3</error>

エラーの説明

エージェントと連動

概要

連動する際の選択肢は2つあります：

• エクソーラボタン。こちらのボタンはエージェントに設置されます。エクソーラボタン選択後、ユーザーは事前に受け取った番号を入力して、この番号で決済します。エクソーラボタン経由の支払いを有効にする場合は、accountの項目を入力してください（project、“v1”、“v2”、“v3"は空欄にします）。account項目はいずれも9文字のエクソーラ番号を入力してください。エクソーラボタン設定の際は、マネージャーに問い合わせてロゴと番号を取得します。
• ゲーム用のボタン。こちらのボタンはエージェント側に配置され、ボタンはそれぞれ別のゲームに対応します。ユーザーは特定のゲームが1つ結びついたボタンをクリックして、ログイン後に自身のアカウントで支払いを実行します。エクソーラボタン経由の支払いを有効にする場合は、projectと"v1”、“v2”、“v3"の項目を入力してください（account項目は空欄にします）。端末に特定プロジェクト（ゲーム）ボタンがインストールされた後に、ユーザーはproject、“v1”、“v2”、“v3"の項目を入力できます。projectと"v1"の入力は必須ですが、“v2"と"v3"は任意です（項目の有無はプロジェクトそのものに依存します）。ゲームボタンを設定する際は、マネージャーに連絡してゲームのロゴとゲームの内部ID、認証方法（“v1”、“v2”、“v3"の入力ルール）、その他各ゲームの情報を受け取ってください。

ボタンはエージェントのシステムのエレメントで、エクソーラシステムを通して決済を開始させます。

エージェントをエクソーラシステムへ接続する前に、次のことを明確にしてください：

1. エクソーラシステムのパートナー番号（種類）。この番号は、エクソーラのカスタマーサクセスマネージャーに問い合わせると受け取れます。
2. secret_key-機密文字列パラメータ。デジタル署名（MD5文字列）の生成を必要とします。こちらは、アドミンページかカスタマーサクセスマネージャーを通してご確認いただけます。

APIとの連動は、次のようにHTTPリクエストをAPIゲートウェイへ送ります：

1https://ps.xsolla.com/api/gate

APIはGETリクエストかPOSTリクエストを受け取ります。全パラメータはUTF-8にエンコードされます。一致しないエンコードを使用すると、署名の際に問題が発生します。

フォーマットのリクエスト

エクソーラゲートウェイへのリクエスト形式は3種類あります：

• 利用できる決済の確認（command=check）
• 決済の実行（command=pay）
• 費用とゲーム通貨額を計算（command=calculate）

Checkコマンド：エクソーラ番号でユーザー認証

Checkコマンド：プロジェクト/v1/v2/v3でユーザー認証

Payコマンド：アカウントでサブスクライバーを認証

Payコマンド：プロジェクト/v1/v2/v3でサブスクライバーを認証

Calculateコマンド

MD5項目の生成

署名は安全な決済と、決済の確認を実現します。送信されたすべてのパラメータの値を、リクエストに従う場合と同じ順序で連結することにより引き出された文字列のMD5ハッシュを取ることで生成されます。オプションのパラメータ（存在する場合）および決済システムの秘密鍵は、エクソーラカスタマーサクセスマネージャーから受け取ってください。

Checkコマンド

 1<?php
 2  $request['command']='check';
 3  $request['account']=1234567;
 4  $request['sum']=150.75;
 5  $request['type']=151;
 6  $request['date']='20110117000516';
 7  $md5='';
 8  foreach ($request as $value) {
 9  $md5.=$value;
10  }
11  $request['md5']=md5($md5.$secret_key);
12?>

列：

check1234567150.7515120110117000516test

MD5：

1cad5a2c3457cffa8e857a507a7050ba

Payコマンド

 1<?php
 2$request['command']='pay';
 3$request['account']=1234567;
 4$request['sum']=150.75;
 5$request['id']=384957;
 6$request['type']=151;
 7$request['date']='20110117000516';
 8$md5='';
 9foreach ($request as $value) {
10$md5.=$value;
11}
12$request['md5']=md5($md5.$secret_key);
13?>

列：

pay1234567150.7538495715120110117000516test

MD5：

7cfa05abde4ae2464142bf2ac7a72f32

Calculateコマンド

 1<?php
 2  $request['command']='calculate';
 3  $request['project']=4783;
 4  $request['out']=12;
 5  $request['type']=151;
 6  $request['date']='20110117000516';
 7  $md5='';
 8  foreach ($request as $value) {
 9  $md5.=$value;
10  }
11  $request['md5']=md5($md5.$secret_key);
12?>

列：

calculate47831215120110117000516test

MD5：

e73e11a9cad00e205358e05254905af5

レスポンスコード

システムはXMLレスポンスを生成します。これにはコードステータスresultと記述commentが含まれます。

決済システム作動用のAPIレコード

このドキュメントは、決済システムのトランザクションレジストリAPIを使用して、ユーザーがプロジェクトの仮想アイテムやサービスを有料で利用することを想定しいる開発者を対象としています。プロジェクトの仮想製品やサービスの支払い機会をご提供します。このドキュメントを読む場合、API、HTTPリクエスト、ソフトウェア構造に関する基本知識が必要です。

APIとの連動性

• この作業は、サーバ間サーバ統合でのみ作動します。

• パラメータは全て文字コードUTF-8です。

• データが返す形式はcsvです。

APIメソッドの記述

• 取得−決済データの受け取り。

APIのURL

基本URL： https://api.xsolla.com/payments/

URLマスク

1https://api.xsolla.com/payments/v<number versions>/<command>?<parameter1=value1>&<parameter2=value2

取得

全決済システムの指定した相手方の（最終24時間以内）決済データを取得するリクエストを作成します。

APIアクセスの取得

APIへのアクセスを取得する場合は、一意のパートナーIDと秘密パスワードを取得するにはカスタマーサクセスマネージャーまでお問い合わせるか、csm@xsolla.comに電子メールを送信してください。

例のリクエスト

https://api.xsolla.com/payments/v1/Get?date=2013-08-20&id=1234&sign=8f683701c03b03fe49e6ef7bbfafb8fb

パラメータの入力

レスポンス

CSV形式で応答します（区切り記号はコンマ「,」を使用）：

69927355,95188933,394,2013-08-01T06:49:25+04:00,91.0000,RUB,done

記述項目：

署名の生成

パラメータはアルファベット順にキーでソートされます。署名は、パラメータ値と秘密鍵が連結した文字列のMD5ハッシュです（秘密鍵はマネージャーから受け取れます）。区切り記号は「|」。

例のリクエスト

1date = 2013-08-20;
2id=1234;
3secret_key=password.

列は次のようになります：

2013-08-20|1234|password

上記文字列のMD5：

e8df0ff2e4360300a5142cc28d86b422

完了コード一覧

決済システムのトランザクション照合

メール通知経由の照合

トランザクションの照合は、特定形式の添付ファイルをメールで送信して決済システムで行われます。照合の頻度は事前に決定されます。

トランザクション照合のドキュメント形式

トランザクション照合のドキュメント形式：

• ドキュメントはUTF-8にコード化して送信します。
• ドキュメントの形式は.csvです（値をコンマやセミコロンで区切ると、区切り文字として使えます）。
• 添付ファイル付き文書は、以前決済したメールアドレスからstats@xsolla.comへ送信されます。
• メールの件名は"stats registry"です。
• 添付ファイル名はstats_registry_periodです。期間は2つです（形式はYYYY-MM-DD）。start_dateTend_date期間が1日になる場合は（24時間）、Tより後は除外されます。

ドキュメントコンテンツ

レジストリ例

例1

197035765;6654448;10.00;9.50;RUB;done;2011-09-01 13:30:45;nickname
2
397035766;6634558;150.00;145.00;RUB;done;2011-09-01 16:43:54;vassilliy@mail.ru

例2（決済システムにpidがない場合）

1564;;10.00;9.50;RUB;done;2011-09-01 13:30:45;nickname
2
3456;;150.00;145.00;RUB;done;2011-09-01 16:43:54;vassilliy@mail.ru

例3（descがない場合は、最後にセミコロンを記入）

1564;6654855;10.00;9.50;RUB;done;2011-09-01 13:30:45;
2
3456;4588554;150.00;145.00;RUB;done;2011-09-01 16:43:54;

決済システムAPI経由の照合

トランザクション照合は、決済システムのHTTP（HTTPS）APIでも実行可能です。APIのクエリ後、エクソーラシステムは次のパラメータを受け取る必要があります：