Xsolla-SDK

PHP-SDK

Das Xsolla-PHP-SDK ist eine Open-Source-Bibliothek für die Interaktion mit der Xsolla-API. Dieser Link führt zu dem Projekt auf Github.

Funktionen

  1. Individuell anpassbares Zahlungsportal mit Hilfe verschiedener Methoden der Tokenanfrage.
  2. Ein Client für alle API-Methoden zur einfachen und komfortablen Integration. Sie können den Client zum Einrichten und Aktualisieren von Abo-Modellen, virtuellen Währungen & Gegenständen, zur Verwaltung des Benutzerguthabens, zum Überprüfen der Finanzdaten mit Hilfe der Report-API usw. verwenden.
  3. Praktischer Webhook-Server:
    • Zum Starten benötigen Sie nur eine Rückruf-Funktion.
    • Alle Sicherheitsüberprüfungen bereits implementiert: Signatur-Authentifizierung und IP-Whitelisting.
    • Vollständige Anpassung der Logik der Benachrichtigungsverarbeitung, falls Ihnen die standardmäßige Server-Klasse nicht passt.
  4. Das SDK basiert auf Guzzle v3 und nutzt viele seiner Funktionen, einschließlich persistente Verbindungen, parallele Anfragen, Ereignisse und Plug-Ins (über den Symfony2 EventDispatcher), Leistungsbeschreibungen, Protokollierung, Caching, flexibles Batching und erneute Anfrage mit beschränktem exponentiellen Zurückweichen (truncated exponential back-off).

Erste Schritte

Bitte registrieren Sie sich im Kundenportal und legen Sie das Projekt an. Um die PHP-SDK-Bibliothek zu nutzen, benötigen Sie:

  • MERCHANT_ID
  • API_KEY
  • PROJECT_ID
  • PROJECT_KEY

Diese Parameter erhalten Sie über die Daten in Ihrem Firmeneinstellungen und Ihren Projekteinstellungen.

Systemvoraussetzungen

  • PHP 5.3.9+
    • Folgende PHP-Erweiterungen werden benötigt:
    • curl
    • json

Installation

Es wird im empfohlen, das Xsolla-SDK für PHP über den Composer zu installieren.

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

Bitte besuchen Sie unsere Github-Projektseite, um sich über weitere Installationsmöglichkeiten zu informieren.

Nutzung

Token abrufen

Sie sollten einen Zugriffstoken beziehen, um das Zahlungsportal in Ihr Spiel zu integrieren. Ein Zugriffstoken ist ein String, mit dem die Spiele-, Benutzer- und Kaufparameter identifiziert werden.

Es gibt mehrere Möglichkeiten, Token abzurufen. Am einfachsten ist es, die createCommonPaymentUIToken-Methode zu verwenden. Dazu müssen Sie lediglich die ID des Projektes im Xsolla-System und die ID des Benutzers in Ihrem Spiel übergeben:

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);

Weitere Parameter können dem Token im JSON übergeben werden:

<?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);

Wenn Sie einige benutzerdefinierte Parameter für das Aufrufen des Zahlungsportals verwenden möchten (z. B. “settings.ui.theme”), können Sie dieses Beispiel verwenden:

<?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'];

Zahlungsportal (Bezahlstation) integrieren

Sie können den folgenden Code verwenden, um das Zahlungsportal auf Ihrer Seite hinzuzufügen:

<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>

Weitere Informationen und Beispiele zur Integration des Zahlungsportals finden Sie hier.

Empfang von Webhooks

Es gibt eine integrierte Server-Klasse, die Ihnen bei der Handhabung von Webhooks behilflich ist.

<?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();

Wenn Ihnen die standardmäßige Server-Klasse nicht zusagt, können Sie eine eigene anlegen:

<?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');
}

Nachdem Sie die Verarbeitung der Benachrichtigungen auf Ihrem Server abgeschlossen haben, richten Sie bitte die URL ein, die alle Webhook-Benachrichtigungen für Ihr Projekt auf der Seite “Einstellungen” erhalten soll.

Nach dem erfolgreichen Test können Sie den Live-Betrieb starten. Wenn Sie die Parameter der Testumgebung verwendet haben, vergessen Sie bitte nicht, diese aus dem Code zu entfernen.

Fehlerbehebung

Hier finden Sie einige Tipps zur Handhabung und Vermeidung der häufigsten Fehler die im Zusammenhang mit dem Xsolla-PHP-SDK auftreten.

[curl] 77: Fehler bei der Konfiguration des Location-Prüfzertifikats CAfile

Dieser Fehler kann auftreten, wenn Sie die Anfrage mit dem Xsolla-PHP-SDK an unseren Server senden, z. B. wenn Sie einen Token abrufen. Standardmäßig aktivieren wir die SSL-Zertifikatsprüfung und verwenden das von Ihrem Betriebssystem bereitgestellte standardmäßige CA-Bundle. Allerdings ist nicht bei allen Betriebssystemen ein bekanntes CA-Bundle auf der Festplatte gespeichert. Beispielsweise haben Windows und OS X keinen gemeinsamen Speicherort für CA-Bundles.

Es gibt mehrere Möglichkeiten, dieses Problem zu lösen.

Entwicklung. Sie können die Zertifikatsprüfung deaktivieren, wenn Sie sich im Entwicklungsmodus befinden. Sie müssen dieses Verhalten in der Produktionsumgebung zusätzlich testen.

use Xsolla\SDK\API\XsollaClient;

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

Produktion. Sicherer und zuverlässiger ist die Bereitstellung des richtigen CA-Bundles. Sie können den CA-Pfad zur Datei mit folgendem Code angeben:

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');

Unter Windows kann diese Datei unter folgenden Dateipfaden gefunden werden:

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

Bitte überprüfen Sie, ob diese Dateien vorliegen und legen Sie den entsprechenden CA-Pfad fest.

Wenn dieses Zertifikat nicht an den genannten Speicherorten vorliegt, können Sie versuchen, das von Mozilla zur Verfügung gestellte Zertifikat zu verwenden, das Sie hier herunterladen können (durch den Hauptentwickler von cURL bereitgestellt).

In einigen PHP-Versionen für Windows gibt es ein Problem mit der programmgesteuerten Konfiguration von Zertifikatspfaden. Um dieses Problem zu lösen, laden Sie die Datei cacert.pem herunter und geben Sie den Pfad zu dieser Datei direkt in der php.ini an: curl.cainfo=c:/cacert.pem.

"Fehlercode "INVALID_SIGNATURE" samt Nachricht "Authorization header not found in Xsolla webhook request""

Standardmäßig übergibt php-cgi unter Apache den “HTTP Basic user/pass” nicht an PHP Damit dies funktioniert, müssen Sie die folgende Zeile zur .htaccess oder zur httpd.conf-Apache-Datei hinzufügen:

RewriteEngine On
RewriteCond %{HTTP:Authorization} ^(.+)$
RewriteRule .* - [E=HTTP_AUTHORIZATION:%{HTTP:Authorization}]

Fehlercode "INVALID_CLIENT_IP" in Ihrem Webhook-Server

Standardmäßig überprüft das Xsolla-PHP-SDK aus Sicherheitsgründen die IPs, von denen der Webhook gesendet wurde. Der Fehlercode “INVALID_CLIENT_IP” wird zurückgegeben, wenn Sie Ihren Webhook-Server von einem Localhost aus in einer Entwicklungsumgebung testen oder wenn Ihr Applikationsserver im Produktionsmodus hinter einem Proxy, z. B. einem Load Balancer, läuft.

Wenn Sie sich hinter einem Proxy befinden, sollten Sie Ihren Proxy selbst in die weiße Liste eintragen.

Wenn Sie sich in einer Entwicklungsumgebung befinden, können Sie die IP-Prüfung mit dem folgenden Code deaktivieren:

use Xsolla\SDK\Webhook\WebhookServer;

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

Sicherere und zuverlässigere wäre es, Ihre Reverse-Proxy-IP-Adresse für den Webhook-Server festzulegen.

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();

Weitere Informationen finden Sie in der Symfonie-Dokumentation.