The following documentation was deprecated. Current version is available at developers.xsolla.com
ドキュメントに戻る

Xsolla PHP SDK

概要

Xsolla PHP SDKは、Xsolla APIと対話するためのオープンソースライブラリです。このプロジェクトの詳細は、Githubの[リンク]https://github.com/xsolla/xsolla-sdk-phpをご覧ください。

機能

  1. さまざまな方法でトークンを取得して、決済インターフェースを完全にカスタマイズ可能。
  2. すべてのAPIメソッドのクライアント。統合を簡単かつ便利にします。これを使用して、仮想通貨、アイテムおよびサブスクリプションプランの設定および更新、ユーザー残高の管理、レポートAPIを使用した財務情報の確認などを行うことができます。
  3. 便利なウェブフックサーバー： 1.まず、必要なコールバック関数1つだけです。 2.すべてのセキュリティチェックが既に実装されています：署名認証とIPホワイトリスト作成。 3.標準のサーバークラスが自分に合わない場合、通知処理ロジックを完全にカスタマイズ可能。
  4. SDKはGuzzle v3上に構築されており、永続的な接続、並列リクエスト、イベントとプラグイン（Symfony2 EventDispatcher経由）、サービスの説明、ワイヤロギング、キャッシング、柔軟なバッチ処理、切り捨て型指数バックオフでのリクエスト再試行などのの多くの機能を利用しています。

はじめに

[パブリッシャ―アカウント]を登録してproject.rtedを作成してください。 PHP SDKライブラリを使用するには、以下が必要です。

  1. MERCHANT_ID
  2. API_KEY
  3. PROJECT_ID
  4. PROJECT_KEY

これらのパラメータは、会社概要とプロジェクト設定の情報を使用して取得できます。

動作確認

  1. PHP 5.3.9+
  2. 以下のPHP拡張モジュールが必要です：
    1. curl
    2. json

インストール

Xsolla SDK for PHPをインストールするには、Composerを使用することをお勧めします。

$ cd /path/to/your/project
$ composer require xsolla/xsolla-sdk-php

別のインストール方法については、Github project siteをご覧ください。

使用法

トークンの取得

決済インターフェースをゲームに統合するには、アクセストークンが必要です。アクセストークンは、ゲーム、ユーザー、および購入パラメータを識別する文字列です。

トークンを取得するにはいくつかの方法があります。最も簡単なのは、createCommonPaymentインターフェースTokenメソッドを使うことです。XsollaシステムでプロジェクトのIDとゲーム内のユーザーのIDだけを渡す必要があります：

use Xsolla\SDK\API\XsollaClient;

$client = XsollaClient::factory(array(
 'merchant_id' => MERCHANT_ID,
 'api_key' => API_KEY
));
$paymentUIToken = $client->createCommonPaymentUIToken(PROJECT_ID, USER_ID,
$sandboxMode = true);

トークンのJSONでさらにパラメータを渡すことができます：

<?php

use Xsolla\SDK\API\XsollaClient;
use Xsolla\SDK\API\PaymentUI\TokenRequest;


$tokenRequest = new TokenRequest($projectId, $userId);
$tokenRequest->setUserEmail('email@example.com')
 ->setExternalPaymentId('12345')
 ->setSandboxMode(true)
 ->setUserName('USER_NAME')
 ->setCustomParameters(array('key1' => 'value1', 'key2' => 'value2'));

$xsollaClient = XsollaClient::factory(array(
 'merchant_id' => MERCHANT_ID,
 'api_key' => API_KEY
));
$token = $xsollaClient->createPaymentUITokenFromRequest($tokenRequest);

決済インターフェースを開くためのカスタムパラメーターを使用する場合（"settings.ui.theme"など）、この例を使用することができます。

<?php

use Xsolla\SDK\API\XsollaClient;

$tokenContent = array (
     'user' =>
         array (
             'id' =>
                 array (
                     'value' => '1234567',
                     'hidden' => true,
 )
 ),
     'settings' =>
         array (
             'project_id' => 14004,
             'ui' =>
                 array(
                     'theme' => 'dark'
 )
 )
);


$xsollaClient = XsollaClient::factory(array(
 'merchant_id' => MERCHANT_ID,
 'api_key' => API_KEY
));
$response = $xsollaClient->CreatePaymentUIToken(array('request' => $tokenContent));
$token = $response['token'];
決済インターフェースの統合（Pay Station）

次のコードを使用して、ページに決済インターフェースを追加することができます。

<html>
<head lang="en">
     <meta charset="UTF-8">
</head>
<body>
 <button data-xpaystation-widget-open>クレジットの購入</button>

     <?php \Xsolla\SDK\API\PaymentUI\PaymentUIScriptRenderer::send($paymentUIToken, $isSandbox = true); ?>
</body>
</html>

決済インターフェース統合の詳細と例は、リンクをご覧ください。

ウェブフックの受信

ウェブフックの処理に役立つサーバークラスのビルドがあります。

<?php

use Xsolla\SDK\Webhook\WebhookServer;
use Xsolla\SDK\Webhook\Message\Message;
use Xsolla\SDK\Exception\Webhook\XsollaWebhookException;

$callback = function (Message $message) {
     switch ($message->getNotificationType()) {
         case Message::USER_VALIDATION:
             /** @var Xsolla\SDK\Webhook\Message\UserValidationMessage $message */
             // TODO if user not found, you should throw Xsolla\SDK\Exception\Webhook\InvalidUserException
             break;
         case Message::PAYMENT:
             /** @var Xsolla\SDK\Webhook\Message\PaymentMessage $message */
             // TODO if the payment delivery fails for some reason, you should throw Xsolla\SDK\Exception\Webhook\XsollaWebhookException
             break;
         case Message::REFUND:
             /** @var Xsolla\SDK\Webhook\Message\RefundMessage $message */
             // TODO if you cannot handle the refund, you should throw Xsolla\SDK\Exception\Webhook\XsollaWebhookException
             break;
         default:
             throw new XsollaWebhookException('Notification type not implemented');
 }
};

$webhookServer = WebhookServer::create($callback, PROJECT_KEY);
$webhookServer->start();

標準のサーバークラスが合わない場合は、独自のものを作成できます：

<?php

use Xsolla\SDK\Webhook\WebhookRequest;
use Xsolla\SDK\Webhook\Message\Message;
use Xsolla\SDK\Webhook\WebhookResponse;
use Xsolla\SDK\Exception\Webhook\XsollaWebhookException;

$httpHeaders = array();//TODO fetch HTTP request headers from $_SERVER or apache_request_headers()
$httpRequestBody = file_get_contents('php://input');
$clientIPv4 = $_SERVER['REMOTE_ADDR'];
$request = new WebhookRequest($httpHeaders, $httpRequestBody, $clientIPv4);
//or $request = WebhookRequest::fromGlobals();

$this->webhookAuthenticator->authenticate($request, $authenticateClientIp = true);// throws Xsolla\SDK\Exception\Webhook\XsollaWebhookException

$requestArray = $request->toArray();

$message = Message::fromArray($requestArray);
switch ($message->getNotificationType()) {
     case Message::USER_VALIDATION:
         /** @var Xsolla\SDK\Webhook\Message\UserValidationMessage $message */
         $userArray = $message->getUser();
         $userId = $message->getUserId();
         $messageArray = $message->toArray();
         // TODO if user not found, you should throw Xsolla\SDK\Exception\Webhook\InvalidUserException
         break;
     case Message::PAYMENT:
         /** @var Xsolla\SDK\Webhook\Message\PaymentMessage $message */
         $userArray = $message->getUser();
         $paymentArray = $message->getTransaction();
         $paymentId = $message->getPaymentId();
         $externalPaymentId = $message->getExternalPaymentId();
         $paymentDetailsArray = $message->getPaymentDetails();
         $customParametersArray = $message->getCustomParameters();
         $isDryRun = $message->isDryRun();
         $messageArray = $message->toArray();
         // TODO if the payment delivery fails for some reason, you should throw Xsolla\SDK\Exception\Webhook\XsollaWebhookException
         break;
     case Message::REFUND:
         /** @var Xsolla\SDK\Webhook\Message\RefundMessage $message */
         $userArray = $message->getUser();
         $paymentArray = $message->getTransaction();
         $paymentId = $message->getPaymentId();
         $externalPaymentId = $message->getExternalPaymentId();
         $paymentDetailsArray = $message->getPaymentDetails();
         $customParametersArray = $message->getCustomParameters();
         $isDryRun = $message->isDryRun();
         $refundArray = $message->getRefundDetails();
         $messageArray = $message->toArray();
         // TODO if you cannot handle the refund, you should throw Xsolla\SDK\Exception\Webhook\XsollaWebhookException
         break;
     default:
         throw new XsollaWebhookException('Notification type not implemented');
}

サーバー上の通知の処理が完了したら、プロジェクトの[設定]ページですべてのウェブフック通知を受け取るURLを設定してください。

[テスト]タブでテストに通ると、すぐに実行できます。サンドボックスパラメータを使用している場合は、コードからサンドボックスパラメーターを忘れずに削除してください。

トラブルシューティング

ここでは、Xsolla PHP SDKによって返される最も頻繁に起きるエラーの処理と防止方法に関するいくつかのヒントをご紹介します。

[curl] 77: ロケーション検証証明書の設定中にエラーが発生：CAfile

トークンを取得するときなど、Xsolla PHP SDKを使用してサーバーにリクエストを送信すると、この種のエラーが発生することがあります。

既定では、SSL証明書の検証を有効にし、オペレーティングシステムによって提供されるデフォルトのCAバンドルを使用します。ただし、すべてのシステムがディスク上に既知のCAバンドルを持っているわけではありません。たとえば、WindowsとOS XにはCAバンドルの共通の場所が1つもありません。 この問題を解決する方法はいくつかあります。

1) 開発

開発モードのときは、証明書の検証を無効にすることができます。プロダクション環境でこの問題について追加のテストが必要であることをご報告ください。

use Xsolla\SDK\API\XsollaClient;

$client = XsollaClient::factory(array(
 'merchant_id' => MERCHANT_ID,
 'api_key' => API_KEY
));
$client->setDefaultOption('ssl.certificate_authority', false);

2) 制作

正しいCAバンドルを提供すると、より安全で信頼性の高くなります。次のコードを使用して、ファイルへのCAパスを指定できます。

use Xsolla\SDK\API\XsollaClient;

$client = XsollaClient::factory(array(
 'merchant_id' => MERCHANT_ID,
 'api_key' => API_KEY
));
$сlient->setDefaultOption('ssl.certificate_authority', '/path/to/file');

Windowsでは、このファイルは次のパスにあります。

  1. C:\windows\system32\curl-ca-bundle.crt
  2. C:\windows\curl-ca-bundle.crt

これらのファイルの存在を確認し、適切なCAパスを設定してください。

上記の場所にこの証明書がない場合は、mozillaから提供された証明書を使用してみてください。この証明書はここ（cURLのメンテナー提供）からダウンロードできます。

Windows用のphpのバージョンの中には、証明書パスのプログラムによる設定に問題がありものもあります。この問題を解決するには、ファイルhttps://curl.haxx.se/ca/cacert.pemをダウンロードし、このファイルへのパスを直接=php.ini:curl.cainfo=c:/cacert.pemに指定してください。

「 Xsolla ウェブフックリクエストで認証ヘッダーが見つかりません 」というメッセージの「 INVALID_SIGNATURE」エラーコード

既定では、Apacheのphp-cgiは HTTP Basic user / pass[値のペア]をPHPに渡しません

これを有効にするには、.htaccessまたはhttpd.confApacheファイルに次の行を追加する必要があります。

RewriteEngine On
RewriteCond %{HTTP:Authorization} ^(.+)$
RewriteRule .* - [E=HTTP_AUTHORIZATION:%{HTTP:Authorization}]
ウェブフックサーバーの「INVALID_CLIENT_IP」エラーコード

既定では、Xsolla PHP SDKはセキュリティ上の理由からウェブフックが送信したIPをチェックしています。 エラーコード 「INVALID_CLIENT_IP」は、開発環境のlocalhostからウェブフックサーバーをテストするか、アプリケーションサーバーがプロダクションのロードバランサのような何らかのプロキシの背後で動作する場合に返されます。 プロキシの背後にある場合は、プロキシを手動でホワイトリストに登録する必要があります。

開発環境にある場合は、次のコードを使用してIPチェックを無効にすることができます。

use Xsolla\SDK\Webhook\WebhookServer;

$webhookServer = WebhookServer::create($callback, PROJECT_KEY);
$webhookServer->start($webhookRequest = null, $authenticateClientIp = false);

より安全で信頼性の高い方法は、リバースプロキシIPアドレスをウェブフックサーバーに設定することです。

use Xsolla\SDK\Webhook\WebhookServer;
use Symfony\Component\HttpFoundation\Request;

$request = Request::createFromGlobals();
$request->setTrustedProxies(array('YOUR_PROXY_SERVER_IP_OR_CIDR'));

$webhookServer = WebhookServer::create($callback, PROJECT_KEY);
$webhookServer->start();

詳細については、Symfony ドキュメントをご覧ください。

Xsolla Android SDK

概要

Xsollaはアプリケーションからの支払いを受け入れるAndroid Client SDKを作成しました。this apkをダウンロードして作業を確認できます。

開始する前に、ここに記載されているモジュールの1つを選択し、ウェブフックの処理を実装し、アクセストークンを作成してください。

動作確認

  1. Android OS版の最低動作環境： 4.0
  2. インターネット接続はXsolla Android SDKにとって不可欠です

ダウンロード

Jcentralからダウンロード：

<dependency>
<groupId>com.xsolla.android</groupId>
<artifactId>xsollasdk</artifactId>
<version>2.3.0</version>
</dependency>

またはGradle：

compile 'com.xsolla.android:xsollasdk:2.3.0'

インストール

Xsolla Android SDKをAndroid Studioに追加することができます。この手順に従ってください：

  1. モジュールをインポートする - File > Import Module > xsollasdk
  2. 依存関係の追加- File > Project Structure > Your App Module > Dependency > + > Module Dependency > xsollasdk
  3. 次のようにAndroidセクションでビルドgradlewを追加してください。
      packagingOptions {
     exclude 'META-INF/LICENSE'
     exclude 'META-INF/NOTICE'
}

Here you can find the link to this project on Github.

決済の実行

SDKを正常に動作させるには、アクセストークンがあることを確認してください。トークンを取得する方法の詳細は、こちらをご参照ください。

Xsolla インターフェース

たとえば、決済ボタンがある簡単なアプリケーションを例に取ってみましょう。これをクリックすると、ショップインターフェースが開きます。


public class MainActivity extends Activity {

  public void openShop(String token, boolean isTestPayment) {
     XsollaSDK.createPaymentForm(this, token, isTestPayment);
 }

  protected void onActivityResult(int requestCode, int resultCode, Intent data) {
    switch (requestCode){
      case XsollaActivity.REQUEST_CODE:
        if(data != null) {
          long objectId = data.getExtras().getLong(XsollaActivity.EXTRA_OBJECT_ID);
          if (resultCode == RESULT_OK) {
            XStatus statusData = (XStatus) XsollaObject.getRegisteredObject(objectId);
            Toast.makeText(this, statusData.toString(), Toast.LENGTH_LONG).show();
          } else {
            XError error = (XError) XsollaObject.getRegisteredObject(objectId);
            Toast.makeText(this, error.toString(), Toast.LENGTH_LONG).show();
 }
 }
 }
 }
}

決済が処理されると、アプリケーションはOnActivityResultの結果を取得できます。また、アプリケーションが終了していても、サーバー上にウェブフックを送信します。

Xsolla Unity SDK

概要

Xsollaは、デスクトップ、Web、またはモバイルアプリケーションでの支払いを受け入れられるUnity SDKを作成しました。

GitHubからXsolla Unity SDKの最新リリースをダウンロードしてください。

動作確認

Xsolla Unity SDKは、Unity 5.0以上で動作します。

統合

主な機能：

*保存された決済方法。

*仮想通貨の購入。

*仮想商品の購入。

*サブスクリプションの購入。

*プロモーション。

*クーポンの利用。

*ユーザーの決済履歴。

Xsollaの決済インターフェースで支払いを受け取りたい場合は、次の手順を実行してください。

  1. ウェブフック処理を設定する：http://developers.xsolla.com/api_v2.html#webhooks
  2. 万全のセキュリティで決済を行うためのXsollaアクセストークンを作成しましょう。トークンの作成に関するドキュメントは、こちらをご覧ください。。http://developers.xsolla.com/api_v2.html#payment_ui
  3. 任意のオブジェクトにXsollaSDKスクリプトを追加するか、 「Resources - > Prefabs」フォルダからプレハブを使用してください。
  4. すぐに使える支払いフォームを生成するには、XsollaSDK(instance) を呼び出します。
  5. メソッド CreatePaymentForm(token, actionOk(XsollaStatusData), actionError(XsollaError), actionMore(string))を呼び出します
Parameter 説明文
トークン 購入したトークンは[トークンの取得]メソッドを使用して、取得されました。
actionOk 支払い処理が完了したときに呼び出されます。ここに決済受付機能を挿入してください。
actionError 何らかの理由で支払い処理がキャンセルまたは失敗したときに呼び出されます。イベント処理関数をここに挿入します。
  1. ネイティブブラウザでXsollaSDK.InitPaystation(string token)を使用して決済インターフェースを起動することもできます。

独自の決済インターフェースを使用する場合は、Xsolla Pay Stationクラスを拡張する独自のクラスを作成する必要があります。

例えば、XsollaPaystationControllerを使用できます。

SDKレスポンスオブジェクト：

public class XsollaResult {
     public string invoice{ get; set;}
     public Status status{ get; set;}
     public Dictionary<string, object> purchases;
}

お試しください！

デモをご覧ください。

「XsollaUnitySDK」→ 「Resources」→「_Scenes」フォルダにもテストシーンがあります：

  1. XsollaFarmFreshScene - アイテムショップをエミュレートします。
  2. XollaTokenTestScene - ここでトークンをテストできます。