エクソラ SDK

PHP SDK

エクソラ PHP SDKは、エクソラ APIと対話するためのオープンソースライブラリです。このプロジェクトの詳細は、GitHubのリンクをご覧ください。

機能

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

はじめる

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

  • MERCHANT_ID
  • API_KEY
  • PROJECT_ID
  • PROJECT_KEY

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

動作確認

  • PHP 5.3.9+
  • 以下のPHP拡張モジュールが必要です:
    • curl
    • json

インストール

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

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

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

使用法

トークンの取得

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

トークンを取得するにはいくつかの方法があります。最も簡単なのは、createCommonPaymentUIToken メソッドを使うことです。エクソラシステムでプロジェクトの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' => 'default_dark'
                )
        )
);


$xsollaClient = XsollaClient::factory(array(
    'merchant_id' => MERCHANT_ID,
    'api_key' => API_KEY
));
$response = $xsollaClient->CreatePaymentUIToken(array('request' => $tokenContent));
$token = $response['token'];

決済インターフェースの統合(決済ステーション)

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

<html>
<head lang="en">
    <meta charset="UTF-8">
</head>
<body>
    <button data-xpaystation-widget-open>Buy Credits</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を設定してください。

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

トラブルシューティング

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

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

トークンを取得するときなど、エクソラ PHP SDKを使用してサーバーにリクエストを送信すると、この種のエラーが発生することがあります。既定では、SSL証明書の検証を有効にし、オペレーティングシステムによって提供されるデフォルトのCAバンドルを使用します。ただし、すべてのシステムがディスク上に既知のCAバンドルを持っているわけではありません。たとえば、WindowsとOS XにはCAバンドルの共通の場所が1つもありません。

この問題を解決する方法はいくつかあります。

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

use Xsolla\SDK\API\XsollaClient;

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

制作。正しい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では、このファイルは次のパスにあります:

  • C:\windows\system32\curl-ca-bundle.crt
  • C:\windows\curl-ca-bundle.crt

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

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

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

「 Authorization header not found in Xsolla webhook request 」というメッセージの「 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」エラーコード

既定では、エクソラ 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 ドキュメントをご覧ください。