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 7.1.3+
  • 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.

Pay Station UE4 SDK

Das Pay Station UE4 SDK kommt zum Einsatz, um das Xsolla-Zahlungsportal in Anwendungen zu integrieren, die auf der Unreal Engine basieren.

Siehe Demo:

Systemvoraussetzungen

  • 64-bit-Betriebssystem
  • Windows 10
  • Mac OS X 10.11 und höher
  • Visual Studio 2017
  • Unreal Engine v4.19 und höher

Integrationsablauf

  1. Registrieren Sie sich im Xsolla-Kundenportal.
  2. Erstellen Sie ein Projekt im Kundenportal.
  3. Beziehen Sie einen Token.
  4. Richten Sie Webhooks ein.
  5. Installieren und konfigurieren Sie das Plugin für das "Unreal Engine"-Projekt.

Zur Integration sind folgende Parameter nötig:

  • merchantId: ID eines Händlers, wird unter Projekteinstellungen > Webhooks angezeigt
  • apiKey: API-Schlüssel. Dieser Parameter wird unter Firmeneinstellungen > API-Schlüssel generiert
  • projectId: ID des Projekts, wird unter Projekteinstellungen > Webhooks angezeigt
  • projectSecretKey: Geheimer Schlüssel des Projekts. Dieser Parameter wird unter Projekteinstellungen > Webhooks generiert

Projekt anlegen

  1. Melden Sie sich um Kundenportal an.
  2. Gehen Sie zu Projekte und klicken Sie auf Neues Projekt anlegen.
  3. In den Projekteinstellungen:
    • Legen Sie die Webhook-URL fest
    • Generieren Sie einen geheimen Schlüssel, um Webhooks für das Projekt signieren zu können

    Token abrufen

    Damit das SDK ordnungsgemäß funktioniert, müssen Sie einen Token beziehen. Ein Zugriffstoken ist ein String, welcher zur Autorisierung von Anfragen des Clients gegenüber dem Server genutzt wird.

    Xsolla-API nutzt Basisauthentifizierung. Geben Sie Ihre Händler-ID als Benutzernamen und Ihren API-Schlüssel als Passwort an.

    URL zum Abrufen des Token: https://api.xsolla.com/merchant/v2/merchants/{merchant_id}/token

    Sie können die HTTP-POST-Anfrage ändern, indem Sie die Parameter, die Sie an das Zahlungsportal übergeben wollen, einfügen. Sowohl die Anfrage als auch die Antwort erfolgt im JSON-Format.

    Beispiel mit 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"
                }
        }
    }'

    Die vollständige Liste der Parameter finden Sie in der API-Referenz.

    Webhooks einrichten

    Folgende Webhooks müssen implementiert werden:

    Um den Empfang eines Webhook zu bestätigen, muss Ihr Server mit dem HTTP-Statuscode 204 ohne Nachrichtenrumpf antworten. Mehr zum Thema Webhooks, einschließlich Beispielen, finden Sie in der API-Referenz. Gehen Sie zum Testen von Webhooks zum Abschnitt Projekteinstellungen > Webhooks.

    Plugin installieren und einrichten

    1. Führen Sie den Epic Games Launcher aus, navigieren Sie zu My projects und wählen Sie ein Projekt aus, zu dem Sie das Plugin hinzufügen möchten.
    2. Laden Sie das Plugin herunter.
    3. Entpacken Sie das Archiv in den Ordner {YourProject}/Plugins. Falls kein Ordner mit dem Namen Plugins vorhanden ist, erstellen Sie einen.
    4. Öffnen Sie die Plugin-Einstellungen: Settings > Project Settings > Xsolla Pay Station.
    5. Legen Sie den Parameter Server URL fest. Dieser Parameter entspricht der URL zum Abrufen eines Tokens. Die folgende URL kann zu Testzwecken verwendet werden: https://livedemo.xsolla.com/paystation/token_unreal.php.

    Note: Setzen Sie zum Öffnen des Zahlungsportals in der Testumgebung ein Häkchen vor die Option Sandbox mode [Testumgebung] und übermitteln Sie "mode":"sandbox" in der Token abrufen-Anfrage.

    C++ Projekt einrichten

    Note: Nutzen Sie zum Einrichten Ihres Projekts Visual Studio für Windows oder Xcode für Mac OS.

    1. Generieren Sie Projektdateien, indem Sie im Kontextmenü Ihres Projekts folgendes auswählen:
      • im Falle von Windows: Generate Visual Studio project files,
      • im Falle von Mac OS: Open Xcode.
    2. Fügen Sie in der {YourProject}.Target.cs- und der {YourProjectEditor}.Target.cs-Datei unter ExtraModuleNames XsollaPayStationPlugin hinzu.
    3. Fügen Sie in der {YourModule}.Build.cs-Datei unter PublicDependencyModuleNames oder PrivateDependencyModuleNames XsollaPayStationPlugin hinzu.
    4. Binden Sie die XsollaPayStationPlugin.h-Datei ein.
    5. Konfigurieren Sie mithilfe der Funktion XsollaPayStationPlugin::Get()->Create(), wie das Zahlungsportal aufgerufen werden soll. Legen Sie folgende Parameter fest:
      • EShopSizeEnum: Die Größe der Benutzeroberfläche. Mögliche Größen: VE_Small (620 x 630), VE_Medium (740 x 760) und VE_Large (820 x 840).
      • userId: Ingame-Benutzer-ID.
      • OnPayStationClosedCallback(): Aktivierung einer Rückruf-Funktion beim Schließen der Bezahlstation.

    Nach Aufruf der Funktion XsollaPayStationPlugin::Get()->Create():

    1. Sendet das Plugin eine Anfrage an den Server über die in den Projekteinstellungen im Parameter Server URL festgelegte URL. Die Benutzer-ID und der Indikator für die Testumgebung (Sandbox-Modus) wird in der Anfrage übermittelt.
    2. Empfängt das Plugin einen Token in der Server-Antwort und öffnet das Zahlungsportal.

    Beispiel

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

    Blueprint-Projekt anlegen

    Legen Sie mithilfe der Funktion Open Xsolla Pay Station fest, wie das Zahlungsportal aufgerufen werden soll. Spezifizieren Sie folgende Parameter:

    • Shop Size: Fenstergröße der Benutzeroberfläche. Mögliche Parameter: "Small" (620 x 630), "Medium" (740 x 760) und "Large" (820 x 840).
    • User Id: Benutzer-ID.
    • On Pay Station Closed: Aktivierung einer Rückruf-Funktion beim Schließen der Bezahlstation.

    Nach Aktivierung der Funktion Open Xsolla Pay Station:

    1. Sendet das Plugin eine Anfrage an den Server über die in den Projekteinstellungen im Parameter Server URL festgelegte URL. Die Benutzer-ID und der Indikator für die Testumgebung (Sandbox-Modus) wird in der Anfrage übermittelt.
    2. Empfängt das Plugin einen Token in der Server-Antwort und öffnet das Zahlungsportal.

    Beispiel für ein Blueprint-Projekt samt Aufrufen des Zahlungsportals: