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

Vorbestellungen

Das Modul "Vorbestellungen" ist eine auf Xsolla-Pay2Play basierende Lösung, die es Herausgebern gestattet, ihre Spiele vor dem offiziellen Release-Termin zu verkaufen. Wenn ein Benutzer ein Spiel vorbestellt, erhält er eine individuelle Nummer, die den Kauf bestätigt. Sobald das Spiel veröffentlicht wurde, liefern wir automatisch den PIN-Code an den Benutzer aus, damit dieser auf das Spiel zugreifen kann.

Integrationsleitfaden

Gehen Sie folgendermaßen vor, um das Modul zu integrieren:

  1. Registrieren Sie sich im Xsolla-Kundenportal.
  2. Legen Sie ein Projekt an.
  3. Konfigurieren Sie das Modul.
  4. Integrieren Sie das Pay2Play-Widget.
  5. Testen Sie den Zahlungsvorgang aus.
  6. Unterzeichnen Sie die Vereinbarung.
  7. Laden Sie die PIN-Codes zum Release-Termin hoch.

Ein Projekt anlegen

  1. Gehen Sie zu Projekte und klicken Sie auf Neues Projekt anlegen.
  2. In den Einstellungen:
    a) Setzen Sie die Einstellung zu Webhooks auf Aus.
    b) Setzen Sie die Einstellung zu Serverlose Integration auf Ein.
  3. Schalten Sie das Pay2Play-Modul ein.

Konfiguration des Moduls

  1. Gehen Sie zu den Pay2Play-Einstellungen und konfigurieren Sie die folgenden Parameter:
    a) Spielname.
    b) Beschreibung zum Spiel.
    c) Systemanforderungen.
    d) SKU — eine eindeutige Kennung.
    e) Release-Termin.
    f) Bild.
    g) DRM-Plattformen.
    h) Versionen der Betriebssysteme/Spiele-Konsolen, die von den ausgewählten DRM-Plattformen unterstützt werden.
  2. Klicken Sie auf Weiter.
  3. Legen Sie die Preise für die ausgewählten DRM-Plattformen fest.

Integration des Pay2Play-Widgets

Das Pay2Play-Widget ruft Ihren Store in einer Lightbox (bei Desktop-Bildschirmen) oder in einem neuen Fenster (bei mobilen Endgeräten) auf. Das Widget erkennt den Gerätetyp automatisch.

Um den Widget-Code zu erhalten, öffnen Sie die Moduleinstellungen in Ihrem Kundenportal und gehen Sie zur Registerkarte Veröffentlichen. Kopieren Sie den Code des gewünschten Widgets und fügen Sie ihn auf Ihrer Spiele-Website ein. Wir empfehlen Ihnen, asynchrones Laden zu verwenden.

Beispiel für asynchrones Laden eines Scripts:

  <script>
          var access_data = {"settings":{"project_id":14004,"mode":"sandbox"},"purchase":{"pin_codes":{"codes":[{"digital_content":"game_sku"}]}}};
          var target_element = "#widget-example-element";
          var s = document.createElement('script');
          s.type = "text/javascript";
          s.async = true;
          s.src = "//static.xsolla.com/embed/pay2play/2.1.0/widget.min.js";
          s.addEventListener('load', function (e) {
                  var widgetInstance = XPay2PlayWidget.create(access_data,target_element);
          }, false);
          var head = document.getElementsByTagName('head')[0];
          head.appendChild(s);
  </script>

Die komplette Liste der Widget-Initialisierungsparameter finden Sie in der API-Referenz Anleitungen zur Installation des Widgets finden Sie auf GitHub.

Wichtig! Sie müssen die Vereinbarung unterschreiben, bevor Sie echte Zahlungen akzeptieren können.

Zahlungsvorgang austesten

Xsolla-Sandbox ist eine eigenständige Umgebung, welche alle Funktionen der Live-Umgebung, mit Ausnahme echter Zahlungen, unterstützt. Sie können auf die Sandbox zugreifen, indem Sie "settings.mode" = "sandbox" innerhalb des access_data Objekts festlegen und versenden. Die JSON-Struktur und Parameter im access_data-Objekt sind dieselben wie bei der Tokenanfrage.

Gehen Sie folgendermaßen vor, um eine Kartenzahlung zu testen:

  1. Rufen Sie den Store im Sandbox-Modus auf.
  2. Wählen Sie den Gegenstand aus, den Sie erwerben möchten.
  3. Wählen Sie unter Zahlungsarten die Kredit-/Debitkarten Gruppe aus.
  4. Geben Sie die Bankkartendaten und alle Werte in die verbleibenden Felder ein. Sie können auch falsche Angaben (Kartennummer, Ablaufdatum oder CVV) machen, um einen Fehler zu generieren.

List of bank cards to be used for testing

Wichtig! Sandbox-Kartenzahlungen können lediglich in USD, EUR, RUB, GBP, SGD, HKD oder THB getätigt werden.

Hochladen der PIN-Codes

Gehen Sie in die Pay2Play-Moduleinstellungen sobald das Spiel veröffentlicht wurde und laden Sie die PIN-Codes für die ausgewählten DRM-Plattformen in der Registerkarte Codes hochladen hoch.

Zahlungen für einen autorisierten Benutzer tätigen

Bei Benutzern mit vorhandenem Spielekonto können Sie Benutzerdaten versenden, um eine autorisierte Transaktion zu tätigen. Gehen Sie folgendermaßen vor, um die Funktion zu aktivieren:

  1. Richten Sie das Projekt ein.
  2. Beziehen Sie einen Token.
  3. Richten Sie die Handhabung von Webhooks ein.

Sie benötigen die folgenden Parameter:

  • Händler-ID — wird in der URL des Kundenportals angezeigt: https://publisher.xsolla.com/{merchant_id}/.
  • API-Schlüssel — wird unter Kundenportal > Einstellungen > Unternehmen generiert.
  • Projekt-ID — wird in der URL des Kundenportals beim Betrachten der Projekteinstellungen angezeigt: https://publisher.xsolla.com/{merchant_id}/projects/{project_id}/.
  • Geheimer Schlüssel des Projekts — wird in den Projekteinstellungen generiert.

Ein Projekt einrichten

Gehen Sie folgendermaßen vor, um ein Projekt einzurichten:

  1. Setzen Sie die Einstellung für Webhooks auf Ein.
  2. Legen Sie die Webhook-URL fest.
  3. Generieren Sie einen geheimen Schlüssel, um Webhooks für das Projekt signieren zu können.
  4. Setzen Sie die Einstellung für Serverlose Integration auf Aus.

Token zum Öffnen des Shops abrufen

Sie benötigen einen Zugriffstoken, um die Benutzeroberfläche des Stores in Ihr Spiel zu integrieren. Ein Zugriffstoken ist ein String, mit dem die Spiele-, Benutzer- und Kaufparameter identifiziert werden.

Die Xsolla-API nutzt HTTP-Basic-Authentication. Geben Sie Ihre Händler-ID als Basic-Auth-Nutzername und den API-Schlüssel als Passwort an.

Legen Sie für den Parameter "mode" den Wert "sandbox" fest, um den Zahlungsvorgang auszutesten.

Token-Endpunkt-URL:

https://api.xsolla.com/merchant/merchants/{merchant_id}/token

Sie können die Parameter für die Store-Benutzeroberfläche in einer HTTP-POST-Anfrage verwenden. Anfrage- und Antwort-Nutzdaten sind als JSON formatiert.

Beispiel für eine Anfrage

Nachstehend finden Sie Beispielcode für das Anfordern des Tokens in PHP mit Hilfe des Xsolla-PHP-SDK. Falls Sie eine andere Programmiersprache verwenden, schauen Sie sich bitte das CURL-Beispiel an, indem Sie auf die Registerkarte "CURL" klicken.

PHP
CURL
<?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);
     curl -v https://api.xsolla.com/merchant/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"
         }
     }'

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

Webhooks einrichten

Xsolla sendet die folgenden Webhooks an Ihr Projekt:

  • Benutzervalidierung
  • Zahlung
  • Rückerstattung

Um zu bestätigen, dass Sie die Webhook-Benachrichtigungen ohne Probleme erhalten haben, sollte Ihr Server mit dem HTTP-Statuscode 204 ohne Nachrichtenrumpf antworten. Die ausführliche Beschreibung des Webhook-Mechanismus samt Beispielen finden Sie in der API-Referenz.

Eine Signatur erstellen

Gehen Sie folgendermaßen vor, um eine Signatur zu erstellen:

  1. Verknüpfen Sie die Daten aus der Anfrage des Xsolla-Servers mit dem geheimen Schlüssel des Projekts (wird in den Projekteinstellungen generiert).
  2. Wenden Sie den SHA1-Hash-Algorithmus bei den Strings an.
  3. Versenden Sie die Signatur im Signatur-Header.

Achten Sie bei der Handhabung von Webhooks darauf, dass die Signatur, welche Sie empfangen, mit jener übereinstimmt, die Sie im Signatur-Header festgelegt haben.

Benutzervalidierung

Der Xsolla-Server sendet eine Anfrage an die Webhook-URL des Projekts, um zu verifizieren, ob ein Benutzer im Spiel vorhanden ist.

Beispiel für eine Anfrage

PHP
CURL
$request = array(
     'notification_type' => 'user_validation',
     'user' => array(
         'ip' => '127.0.0.1',
         'phone' => '18777976552',
         'email'=> 'email@example.com',
         'id'=> '1234567',
         'country' => 'US'
     )
)
curl -v https://example.com/ \
-X POST \
-H 'Content-Type:application/json' \
-H 'Accept: application/json' \
-H 'Authorization: Signature 13342703ccaca5064ad33ba451d800c5e823db8f' \
-d '
{
     "notification_type": "user_validation",
     "user": {
         "ip": "127.0.0.1",
         "phone": "18777976552",
         "email": "email@example.com",
         "id": "1234567",
         "country": "US"
     }
}'

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

Zahlung

Immer wenn ein Benutzer eine Zahlung tätigt, sendet der Xsolla-Server einen Webhook inklusive Zahlungsdaten.

Beispiel für eine Anfrage

PHP
CURL
$request = array(
     'notification_type' => 'payment',
     'purchase' => array(
         'virtual_items' => array(
             'items' => array(
                 0 => array(
                     'sku' => 'test_item1',
                     'amount' => 1,
                     ),
                 1 => array(
                     'sku' => 'test_item2',
                     'amount' => 1,
                     ),
                 2 => array(
                     'sku' => 'test_item3',
                     'amount' => 1,
                     ),
             )
         ),
         'total' => array(
             'currency' => 'USD',
             'amount' => 9.99
         )
     ),
     'user' => array(
         'ip' => '127.0.0.1',
         'phone' => '18777976552',
         'email' => 'email@example.com',
         'id' => '1234567',
         'country' => 'US'
     ),
     'transaction' => array(
         'id' => 87654321,
         'payment_date' => '2014-09-23T19:25:25+04:00',
         'payment_method' => 1380,
         'dry_run' => 1
     ),
     'payment_details' => array(
         'payment' => array(
             'currency' => 'USD',
             'amount' => 9.99
         ),
         'vat' => array(
             'currency' => 'USD',
             'amount' => 0
         ),
         'payout_currency_rate' => 1,
         'payout' => array(
             'currency' => 'USD',
             'amount' => 9.49
         ),
         'xsolla_fee' => array(
             'currency' => 'USD',
             'amount' => 0.19
         ),
         'payment_method_fee' => array(
             'currency' => 'USD',
             'amount' => 0.31
         )
     )
)
curl -v https://example.com/ \
-X POST \
-H 'Content-Type:application/json' \
-H 'Accept: application/json' \
-H 'Authorization: Signature 13342703ccaca5064ad33ba451d800c5e823db8f' \
-d '
{
     "notification_type": "payment",
     "purchase": {
         "virtual_items": {
             "items": [
                 {
                     "sku": "test_item1",
                     "amount": 1
                 },
                 {
                     "sku": "test_item2",
                     "amount": 1
                 },
                 {
                     "sku": "test_item3",
                     "amount": 2
                 },
             ]
         },
         "total": {
             "currency": "USD",
             "amount": 9.99
         }
     },
     "user": {
         "ip": "127.0.0.1",
         "phone": "18777976552",
         "email": "email@example.com",
         "id": "1234567",
         "country": "US"
     },
     "transaction": {
         "id": 87654321,
         "payment_date": "2014-09-23T19:25:25+04:00",
         "payment_method": 1380,
         "dry_run": 1
     },
     "payment_details": {
         "payment": {
             "currency": "USD",
             "amount": 9.99
         },
         "vat": {
             "currency": "USD",
             "amount": 0
         },
         "payout_currency_rate": 1,
         "payout": {
             "currency": "USD",
             "amount": 9.49
         },
         "xsolla_fee": {
             "currency": "USD",
             "amount": 0.19
         },
         "payment_method_fee": {
             "currency": "USD",
             "amount": 0.31
         }
     }
}'

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

Rückerstattung

Falls der Benutzer die Zahlung storniert, sendet der Xsolla-Server eine Webhook-Benachrichtigung mit Zahlungsdaten.

Beispiel für eine Anfrage

PHP
CURL
$request = array(
     'notification_type' => 'refund',
     'purchase' => array(
         'virtual_currency' => array(
             'name' => 'Coins',
             'quantity' => 100,
             'currency' => 'USD',
             'amount' => 9.99
         ),
         'total' => array(
             'currency' => 'USD',
             'amount' => 9.99
         )
     ),
     'user' => array(
         'ip' => '127.0.0.1',
         'phone' => '18777976552',
         'email' => 'email@example.com',
         'id' => '1234567',
         'country' => 'US'
     ),
     'transaction' => array(
         'id' => 87654321,
         'payment_date' => '2014-09-23T19:25:25+04:00',
         'payment_method' => 1380,
         'dry_run' => 1
     ),
     'refund_details' => (
             'code' => 1,
             'reason' => 'Fraud'
     ),
     'payment_details' => array(
         'payment' => array(
             'currency' => 'USD',
             'amount' => 9.99
         ),
         'vat' => array(
             'currency' => 'USD',
             'amount' => 0
         ),
         'payout_currency_rate' => 1,
         'payout' => array(
             'currency' => 'USD',
             'amount' => 9.49
         ),
         'xsolla_fee' => array(
             'currency' => 'USD',
             'amount' => 0.19
         ),
         'payment_method_fee' => array(
             'currency' => 'USD',
             'amount' => 0.31
         )
     )
);
curl -v https://example.com/ \
-X POST \
-H 'Content-Type:application/json' \
-H 'Accept: application/json' \
-H 'Authorization: Signature 13342703ccaca5064ad33ba451d800c5e823db8f' \
-d '
{
     "notification_type":"refund",
     "purchase":{
         "virtual_currency":{
             "name": "Coins",
             "quantity":10,
             "currency":"USD",
             "amount":100
         },
         "subscription":{
             "plan_id": "b5dac9c8",
             "subscription_id": "10",
             "date_create": "2014-09-22T19:25:25+04:00",
             "currency": "USD",
             "amount": 9.99
         },
         "checkout":{
             "currency":"USD",
             "amount":50
         },
         "virtual_items":{
             "items":[
                 {
                     "sku": "test_item1",
                     "amount":1
                 }
             ],
             "currency":"USD",
             "amount":50
         },
         "total":{
             "currency":"USD",
             "amount":200
         }
     },
     "user": {
         "ip": "127.0.0.1",
         "phone": "18777976552",
         "email": "email@example.com",
         "id": "1234567",
         "name": "Xsolla User",
         "country": "US"
     },
     "transaction":{
         "id":1,
         "external_id":1,
         "dry_run":1,
         "agreement":1
     },
     "refund_details":{
         "code":1,
         "reason":"Fraud"
     },
     "payment_details":{
         "xsolla_fee":{
             "currency":"USD",
             "amount":"10"
         },
         "payout":{
             "currency":"USD",
             "amount":"200"
         },
         "payment_method_fee":{
             "currency":"USD",
             "amount":"20"
         },
         "payment":{
             "currency":"USD",
            "amount":"230"
         }
     }
}'

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

Webhooks testen

Gehen Sie folgendermaßen vor, um einen Webhook-Handler zu testen:

  1. Öffnen Sie die Moduleinstellungen im Kundenportal.
  2. Gehen Sie zur Registerkarte Testen.
  3. Geben Sie die Testdaten ein und klicken Sie auf Test. Der Xsolla-Server wird alle möglichen Webhooks senden.
  4. Im Falle einer gültigen Antwort wird der Test grün und im Falle eines Fehlers rot gekennzeichnet.

Geldspenden für den Entwickler

Ein Projekt kann bei jedem Kauf Geldspenden erhalten. Um die Funktion zu aktivieren, rufen Sie die Moduleinstellungen auf, gehen zur Registerkarte Preise und setzen Geldspenden im Pay2Play-Widget zulassen auf Ein. Für jede aktiv geschaltete Währung stehen drei Spendenbeträge zur Auswahl.

Der Benutzer kann den Spendenbetrag vor Betreten des Stores auswählen. Diese Geldspenden werden auf die Einkaufssumme aufgeschlagen.

Anzahl der Vorbestellungen beschränken

Sie können die Anzahl der Vorbestellungen für jedes Projekt beschränken. Sie erhalten eine Benachrichtigung via E-Mail, wenn a) 100 oder weniger Vorbestellungen verbleiben, und wenn b) das Limit erreicht wurde und daher keine weiteren Vorbestellungen mehr möglich sind. Falls ein Benutzer versucht, das festgelegte Limit für die Vorbestellungen zu überschreiten, wird die Zahlung nicht bearbeitet.

Regionale Beschränkungen beim Verkauf

Das Modul Vorbestellungen ermöglicht es Ihnen, regionale Beschränkungen bei Vorbestellungen festzulegen. Insbesondere können Sie:

  • Für einzelne Länder oder Ländergruppen unterschiedliche Preise festlegen;
  • den Verkauf in bestimmten Ländern verbieten.

Sobald das Projekt ordnungsgemäß konfiguriert ist, wird dem Benutzer eine entsprechende Warnung angezeigt, falls er versucht, aus einem Land heraus, welches gesperrt wurde, eine Vorbestellung zu tätigen. Zahlungen aus Ländern, die von Vorbestellungen ausgeschlossen sind, werden nicht verarbeitet.

Kontaktieren Sie Ihren Account Manager, um diese Funktion zu aktivieren. Für jede Plattform, bei der regionale Beschränkungen zur Anwendung kommen, benötigen wir folgende Informationen:

  • Art der Beschränkung:
    • Aktivierung: Ein PIN-Code kann nur in bestimmten Ländern aktiviert werden.
    • Veröffentlichung: Ein PIN-Code kann in jedem Land aktiviert werden, aber das Spiel kann nur in bestimmten Ländern veröffentlicht werden.
    • Aktivierung und Veröffentlichung: Ein PIN-Code kann nur in bestimmten Ländern aktiviert werden und das Spiel kann nur in bestimmten Ländern veröffentlicht werden.
  • Liste der Ländergruppen mit unterschiedlichen Preisen bei der Vorbestellung.
  • Einstellungen für jede Ländergruppe:
    • Gruppenname.
    • SKU — eine eindeutige Gruppenkennung.
    • Liste mit Preisen in verschiedenen Währungen. Stellen Sie sicher, dass Sie innerhalb der Moduleinstellungen den Preis in der Standardwährung festlegen.
    • Liste der Länder innerhalb einer jeden Gruppe.
  • Liste der Länder, in denen die Möglichkeit der Vorbestellung deaktiviert wurde (falls vorhanden).

Für jede einzelne Plattform kann ein Land entweder zu einer Gruppe mit unterschiedlichen Preisen oder zu einer Gruppe, bei der die Möglichkeit zur Vorbestellung deaktiviert wurde, gehören. Falls ein Land in keiner dieser Gruppen gelistet ist, so sind Vorbestellungen ohne jegliche Einschränkungen und zum Preis, der in den Moduleinstellungen festgelegt ist, möglich.

Wichtig: Stellen Sie sicher, dass Sie die PIN-Codes erst auf unser System hochladen, nachdem die regionalen Beschränkungen konfiguriert wurden, falls die PIN-Code-Aktivierung und das Release des Spiels von Ihnen oder durch die Plattform durchgeführt wird.