The following documentation was deprecated. Current version is available at developers.xsolla.com

Überblick

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ände, zur Verwaltung des Benutzerkontostandes, zum Überprüfen der Finanzdaten mit Hilfe der Report-API usw. verwenden.
  3. Praktischer Webhook-Server:
    1. Zum Starten benötigen Sie nur eine Rückruf-Funktion.
    2. Alle Sicherheitsüberprüfungen bereits implementiert: Signatur-Authentifizierung und IP-Whitelisting.
    3. 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(https://publisher.xsolla.com/signup) und legen Sie das Projekt an. Um die PHP-SDK-Bibliothek zu nutzen, benötigen Sie:

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

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

Systemvoraussetzungen

  1. PHP 5.3.9+
  2. Folgende PHP-Erweiterungen werden benötigt:
    1. curl
    2. 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' => 'dark'
                 )
         )
);


$xsollaClient = XsollaClient::factory(array(
     'merchant_id' => MERCHANT_ID,
     'api_key' => API_KEY
));
$response = $xsollaClient->CreatePaymentUIToken(array('request' => $tokenContent));
$token = $response['token'];
Zahlungsportal (Pay Station) 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 eingebaute 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 erfolgreichem Test in der Registerkarte "Testing", können Sie den Live-Betrieb starten. Bitte vergessen Sie nicht, die Sandbox-Parameter aus dem Code zu entfernen, falls Sie diese verwendet haben.

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 Token abrufen.

Standardmäßig aktivieren wir die SSL-Zertifikatsprüfung und verwenden das standardmäßige CA-Bundle des Betriebssystems. 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.

1) Entwicklung

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

use Xsolla\SDK\API\XsollaClient;

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

2) 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:

  1. C:\windows\system32\curl-ca-bundle.crt
  2. 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 https://curl.haxx.se/ca/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.

Überblick

Xsolla hat das Android-Client-SDK entwickelt, um Zahlungen aus Ihrer Anwendung zu akzeptieren. Sie können die Funktionalität überprüfen, indem Sie diese apk herunterladen.

Vor dem Start wählen Sie bitte eines der hier aufgeführten Module aus, implementieren das Webhook-Handling und erstellen Sie einen Zugriffstoken.

Systemvoraussetzungen

  1. Mindestens erforderliche Android OS Version: 4.0
  2. Für das Xsolla-Android-SDK wird eine Internetverbindung benötigt

Download

Download über Jcentral:

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

oder Gradle:

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

Installation

Sie können unser Xsolla-Android-SDK in Android-Studio hinzufügen. Bitte folgen Sie dazu diesen Schritten:

  1. Modul importieren - File > Import Module > xsollasdk
  2. Abhängigkeit hinzufügen - File > Project Structure > Your App Module > Dependency > + > Module Dependency > xsollasdk
  3. Fügen Sie im gradlew-Abschnitt in Android folgendes hinzu:
      packagingOptions {
         exclude 'META-INF/LICENSE'
         exclude 'META-INF/NOTICE'
      }
    

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

Zahlung tätigen

Damit das SDKs korrekt funktioniert sollten Sie sicherstellen, dass Sie über einen Zugriffstoken verfügen. Weitere Informationen zur Beschaffung des Tokens finden Sie hier.

Xsolla-Benutzeroberfläche

Nehmen wir als Beispiel eine einfache Anwendung, die eine Zahlungsschaltfläche besitzt. Mit einem Klick darauf öffnet sich die Benutzeroberfläche unseres Shops.


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

Sobald die Zahlung verarbeitet wurde, kann Ihre Anwendung ein Ergebnis in OnActivityResult erhalten. Wir senden Ihnen außerdem einen Webhook an Ihren Server, selbst wenn die Anwendung geschlossen wurde.

Überblick

Xsolla hat ein Unity-SDK entwickelt, um Zahlungen aus Desktop-, Web- oder mobilen Anwendungen zu akzeptieren.

Laden Sie die neueste Version des Xsolla-Unity-SDK von GitHub herunter.

Systemvoraussetzungen

Xsolla-Unity-SDK arbeitet mit Unity 5.0 und höher.

Integration

Wesentliche Merkmale:

  • Gespeicherte Zahlungsarten;

  • Erwerb von virtueller Währung;

  • Erwerb von virtuellen Gegenständen;

  • Erwerb von Abonnements;

  • Werbeaktionen;

  • Einlösen von Gutscheinen;

  • Zahlungsverhalten von Benutzern.

Wenn Sie Zahlungen über das Zahlungsportal von Xsolla akzeptieren möchten, gehen Sie folgendermaßen vor:

  1. Webhook-Verarbeitung einrichten: http://developers.xsolla.com/api_v2.html#Webhooks
  2. Erstellen Sie einen Xsolla-Zugriffstoken, um Zahlungen mit maximaler Sicherheit durchzuführen. Die Dokumentation zum Erstellen eines Tokens finden Sie hier: http://developers.xsolla.com/api_v2.html#payment_ui
  3. Fügen Sie das XsollaSDK-Script jedem Objekt hinzu oder verwenden Sie vorgefertigte Objekte, die sich unter 'Resources -> Prefabs' befinden;
  4. Rufen Sie XsollaSDK(instance) auf, um ein gebrauchsfertiges Zahlungsformular zu generieren.
  5. Rufen Sie die Methode CreatePaymentForm (token, actionOk (XsollaStatusData), actionError(XsollaError), actionMore(string)) auf
Parameter Description
Token Ihren Einkaufstoken beziehen Sie mit der "Token abrufen"-Methode
actionOk Wird aufgerufen, wenn der Zahlungsvorgang abgeschlossen ist. Geben Sie hier Ihre Funktion für die Zahlungsakzeptanz ein.
actionError Wird aufgerufen, wenn der Zahlungsvorgang abgebrochen oder aus irgendeinem Grund fehlgeschlagen ist. Fügen Sie hier Ihre Funktion für die Ereignisbehandlungsroutine ein.
  1. Sie können außerdem XsollaSDK.InitPaystation (string token) verwenden, um das Zahlungsportal im integrierten Browser zu starten.

Wenn Sie Ihr eigenes Zahlungsportal verwenden möchten, sollten Sie eine eigene Klasse erstellen, welche die XsollaPaystation-Klasse erweitert.

Zum Beispiel können Sie den XsollaPaystationController verwenden.

SDK-Antwort-Objekte:

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

Probieren Sie es aus!

Bitte werfen Sie einen Blick in unsere Demo.

Wir bieten außerdem Testszenarien unter "XsollaUnitySDK" -> "Resources" -> "Scenes" an:

  1. XsollaFarmFreshScene - emuliert einen Shop mit Gegenständen.
  2. XollaTokenTestScene - hier können Sie Ihr Token testen.