電子キオスク 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桁のエクソーラ番号を入力する必要があります。エクソーラボタンをセットアップするには、ロゴと番号を入手するためにマネージャーにお問い合わせください。

• ゲームボタン。これらのボタンはエージェント側に配置され、それぞれ異なるゲームに対応します。ユーザーは特定のゲームのボタンをクリックし、自身の口座への支払いのためにログインします。ゲーム固有のボタンによる支払いを有効にするには、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にエンコードされます。一致しないエンコードを使用すると、署名の際に問題が発生します。

リクエスト形式

エクソーラへのリクエストは以下のケースで行うことができます：

• 決済が可能かどうかを確認する場合（command = check）
• 決済を行う場合（command = pay）
• 決済が成功したかどうかを確認する場合（command = status）
• コストおよびゲーム内通貨の数量を計算する場合（command = calculate）

Checkコマンド

Checkコマンド：エクソーラ番号によりユーザーを識別

Check コマンド：プロジェクト/v1/v2/v3によりユーザーを識別

Payコマンド

Payコマンド：アカウントによる登録者を識別

Payコマンド：プロジェクト/v1/v2/v3によるユーザーを識別

Statusコマンド

支払いの成否は、自社システムのトランザクションID（id パラメータ）またはエクソーラ側のトランザクションID（invoice パラメータ）で確認できます。両方のパラメータを渡す場合は、同一の決済に属している必要があります。一致しない場合、エクソーラは検証エラーを返します。

Statusコマンド：自社システムのトランザクションIDで支払い成功を確認

例：

1https://ps.xsolla.com/api/gate?command=status&id=xsollaid2&type=151&date=20060425180622&md5=0a8d9fb24fcbac2efafec5e51045d05c

Statusコマンド：エクソーラ側のトランザクションIDで支払い成功を確認

例：

1https://ps.xsolla.com/api/gate?command=status&invoice=987654321&type=151&date=20060425180622&md5=0a8d9fb24fcbac2efafec5e51045d05c

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

Statusコマンドの署名生成（自社システムのトランザクションIDで確認）

 1$request['command'] = 'status';
 2$request['id']      = 'xsollaid2';
 3$request['type']    = 151;
 4$request['date']    = '20110117000516';
 5
 6$md5 = '';
 7foreach ($request as $value) {
 8    $md5 .= $value;
 9}
10$request['md5'] = md5($md5 . $secret_key);

列：

statusxsollaid215120110117000516+secret_key

MD5：

7cfa05abde4ae2464142bf2ac7a72f32（例）

Statusコマンドの署名生成（エクソーラ側のトランザクションIDで確認）

 1$request['command'] = 'status';
 2$request['invoice'] = 987654321;
 3$request['type']    = 151;
 4$request['date']    = '20110117000516';
 5
 6$md5 = '';
 7foreach ($request as $value) {
 8    $md5 .= $value;
 9}
10$request['md5'] = md5($md5 . $secret_key);

列：

status98765432115120110117000516+secret_key

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

レスポンス

レスポンスコード

エクソーラは、result要素にステータスコード、comment要素に説明を含むXMLを生成します。

エラーを含むレスポンスの例：

1<response>
2  <result>7</result>
3  <comment>md5 error</comment>
4</response>

成功時のレスポンスコード

result に0が返る場合、レスポンスには決済に関する詳細情報を含むpaymentブロックも含まれます。決済ステータスは、statusパラメータのコードで渡されます。

Statusコマンドへの成功レスポンス例：

 1<response>
 2  <payment>
 3    <invoice>123456789</invoice>
 4    <id>xsollaid2</id>
 5    <sum>100.98</sum>
 6    <project>4783</project>
 7    <v1>XsollaUser</v1>
 8    <date>2026-01-23 12:34:56</date>  <!-- present only when status is succeeded -->
 9    <status>1</status>
10    <comment>succeeded</comment>
11    <statusKioskUrl>https://secure.xsolla.com/pages/status-kiosk?id=123456789&key=9e07b3…</statusKioskUrl>
12  </payment>
13  <result>0</result>
14</response>

決済システムトランザクションレジストリ 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と秘密パスワードを取得するにはカスタマーサクセスマネージャーまでお問い合わせるか、[email protected]に電子メールを送信してください。

リクエスト例

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です（値をコンマやセミコロンで区切ると、区切り文字として使えます）。
• 添付ファイル付き文書は、以前決済したメールアドレスから[email protected]へ送信されます。
• メールの件名は"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;[email protected]

例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;[email protected]

例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のクエリ後、エクソーラシステムは次のパラメータを受け取る必要があります：