エクソラ 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 7.1.3+
  • 以下の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 ドキュメントをご覧ください。

Pay Station UE4 SDK

Pay Station UE4 SDKは、Unreal Engineベースのアプリを備えたエクソラ決済ステーションの統合に使用します。

デモはこちらから:

動作確認

  • OS 64ビット
  • Windows 10
  • Mac OS X 10.11以降
  • Visual Studio 2017
  • Unreal Engine v4.19以降

統合フロー

  1. エクソラのパブリッシャーアカウントを登録。
  2. パブリッシャーアカウントでプロジェクトの作成
  3. トークンの取得
  4. ウェブフックの設定
  5. Unreal Engineのプロジェクト用にプラグインのインストールと設定

統合する場合は次のパラメータが必要です:

  • merchantId – マーチャントのID。プロジェクト設定 > ウェブフックで表示
  • apiKey – APIキー。会社設定 > APIキーセクションで生成されるパラメータです
  • projectId – プロジェクトのID。プロジェクト設定 > ウェブフックで表示
  • projectSecretKey – プロジェクトの秘密鍵。プロジェクト設定 > ウェブフックセクションで生成されるパラメータです

プロジェクトの作成

  1. パブリッシャーアカウントにログインする。
  2. プロジェクトを開いて新規プロジェクトの作成をクリック。
  3. プロジェクト設定ですること:
    • ウェブフックのURLを指定
    • プロジェクトのウェブフック署名用の秘密鍵を生成する

    トークンの取得

    SDKが適切に作動するようにトークンを取得してください。アクセストークンは、クライアントのサーバーリクエストの許可に使用します。

    エクソラAPIは基本アクセス認証を採用しています。マーチャントIDをユーザー名、APIキーをパスワードとして指定します。

    トークン回収用URL:https://api.xsolla.com/merchant/v2/merchants/{merchant_id}/token

    決済インターフェースに引き渡すパラメータを含めることで、HTTP POSTリクエストを変更できます。リクエストとレスポンスは両方ともJSON形式です。

    cURLの例:

    curl -v https://api.xsolla.com/merchant/v2/merchants/{merchant_id}/token \
    -X POST \
    -u your_merchant_id:merchant_api_key \
    -H 'Content-Type:application/json' \
    -H 'Accept: application/json' \
    -d '
    {
        "user": {
            "id": {
                "value": "1234567"
            },
            "email": {
                "value": "email@example.com"
            }
        },
        "settings": {
            "project_id": 14004,
            "mode": "sandbox"
        },
        "purchase": {
                "checkout": {
                    "amount": 9.99,
                    "currency": "USD"
                }
        }
    }'

    パラメータの完全なリストはAPI リファレンスをご参照ください。

    ウェブフックの設定

    次のウェブフックを実装してください。

    ウェブフックの受信を確定する場合は、サーバーがメッセージ本文なしでHTTPコード204で応答します。APIリファレンスから、ウェブフックについて(例など)詳しくご参照いただけます。 ウェブフックをテストする場合は、プロジェクト設定 > ウェブフックセクションを開いてください。

    プラグインのインストールと設定

    1. Epic Gamesランチャーを実行する場合は、My projectsを開いてプラグインを追加したいプロジェクトを選択します。
    2. プラグインのダウンロード
    3. {YourProject}/Pluginsフォルダーのアーカイブを解凍する。Pluginsフォルダーがない場合は作成してください。
    4. Settings > Project Settings > Xsolla Pay Stationの順番でプラグイン設定を開きます。
    5. Server URLパラメータ(トークン取得用URL)を指定します。テスト用にhttps://livedemo.xsolla.com/paystation/token_unreal.phpURLをご使用いただけます。

    Note: サンドボックスモードで決済インターフェイスを開く場合は、Sandbox modeにチェックを入れてトークン取得リクエストに"mode": "sandbox"を渡します。

    C++プロジェクトの設定

    Note: プロジェクト設定にはWindowsならVisual Studio、Mac OSならXcodeをご使用ください。

    1. プロジェクトのコンテキストメニューを選んでプロジェクトファイルを生成する場合:
      • Generate Visual Studio project files(Windows用)。
      • Open Xcode(Mac OS用)。
    2. XsollaPayStationPlugin{YourProject}.Target.cs{YourProjectEditor}.Target.csファイルのExtraModuleNamesに追加する。
    3. XsollaPayStationPlugin{YourModule}.Build.csファイルのPublicDependencyModuleNamesPrivateDependencyModuleNamesに追加する。
    4. XsollaPayStationPlugin.hファイルをインクルードする。
    5. XsollaPayStationPlugin::Get()->Create()関数で、決済ステーションの表示設定をする。次のパラメータを指定する:
      • EShopSizeEnum - インターフェイスのサイズ。利用出来るサイズ:VE_Small - 620 x 630、VE_Medium - 740 x 760、VE_Large - 820 x 840。
      • userId - ゲーム内のユーザーID。
      • OnPayStationClosedCallback() - 決済ステーションを閉じるコールバック関数を作動する。

    XsollaPayStationPlugin::Get()->Create()関数を呼び出したら、プラグインは次のように働きます:

    1. Server URLパラメータ内のプロジェクト設定のURLを使って、サーバーにリクエストを送信。ユーザーIDとサンドボックスモードインジケータをリクエストで渡す。
    2. サーバーのレスポンスでトークンを受け取り、決済インターフェイスを表示。

    ---------------- HEADER -----------------
    
        UFUNCTION(BlueprintCallable)
        void OnPayStationClosedCallback();
    
    protected:
        // Called when the game starts or when spawned
        virtual void BeginPlay() override;
    
    ---------------- SOURCE -----------------
    
    // Called when the game starts or when spawned
    void AMyActor::BeginPlay()
    {
        Super::BeginPlay();
    
        FOnPaymantSucceeded OnPayStationClosedCallback;
        OnPayStationClosedCallback.BindUFunction(this, "OnPayStationClosedCallback");
    
        XsollaPayStationPlugin::Get()->Create(EShopSizeEnum::VE_Large, userId("exampleid"), OnPayStationClosedCallback);
    
    }
    
    void AMyActor::OnPayStationClosedCallback()
    {
        UE_LOG(LogTemp, Warning, TEXT(""));
    }
    

    設計プロジェクトの設定

    Open Xsolla Pay Station関数で、決済インターフェイスが開くように設定します。次のパラメータを指定してください:

    • Shop Size – インターフェイスウィンドウのサイズです。利用出来るパラメータ:Small – 620 x 630、Medium – 740 x 760、Large – 820 x 840。
    • User Id – ユーザーIDです。
    • On Pay Station Closed – 決済ステーションを閉じるコールバック関数を作動します。

    Open Xsolla Pay Station関数の作動後、プラグインは次のように働きます:

    1. Server URLパラメータ内のプロジェクト設定のURLを使って、サーバーにリクエストを送信。ユーザーIDとサンドボックスモードインジケータをリクエストで渡す。
    2. サーバーのレスポンスでトークンを受け取り、決済インターフェイスを表示。

    決済インターフェイス表示機能をつけた設計プロジェクトの例: