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

Tägliche Belohnungen

Tägliche Belohnungen werden an Benutzer verteilt, die ein Premium-Abonnement abschließen. Jedes Premium-Abonnement verfügt über seine eigenen Belohnungen.

Benutzer-Szenarien

Partner-Szenarien

Integrationsleitfaden

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

  1. Registrieren Sie sich im Xsolla-Kundenportal.
  2. Legen Sie ein neues Projekt an.
  3. Konfigurieren Sie das Modul.
  4. Konfigurieren Sie die Belohnungen für ein Premium-Abonnement.
  5. Fordern Sie einen Token an.
  6. Richten Sie das Aufrufen der Store-Benutzeroberfläche ein.
  7. Richten Sie das Webhook-Handling ein.
  8. Testen Sie den Zahlungsvorgang aus.
  9. Veröffentlichen Sie das Modul und unterzeichnen Sie die Vereinbarung.

Folgende Parameter sind für die Integration erforderlich:

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

In diesem Leitfaden werden die minimalen Einstellungen beschrieben, die für den Schnellstart des Moduls erforderlich sind. Die vollständige Liste der Parameter finden Sie in der API-Referenz. Bei Fragen wenden Sie sich bitte an Ihren Account Manager.

Ein Projekt anlegen

  1. Gehen Sie zu Projekte und klicken Sie auf Neues Projekt anlegen.
  2. In den Einstellungen:
    a) Definieren Sie die Webhook-URL.
    b) Generieren Sie einen geheimen Schlüssel, um Webhooks für das Projekt signieren zu können.
    c) Schalten Sie das Abonnement-Modul aktiv.
    d) Gehen Sie zu Benutzer und stellen Sie Benutzerdaten in Xsolla abspeichern auf Ein.

Modul einrichten

  1. Gehen Sie zu den Abonnement-Moduleinstellungen und klicken Sie auf Neues Abo-Modell anlegen. Definieren Sie folgende Parameter:
    a) Name.
    b) Zahlungszyklus.
  2. Klicken Sie auf Anlegen.
  3. Klicken Sie auf Zurück zur Liste der Abo-Modelle, um zu den Grundeinstellungen des Moduls zurückzukehren und, je nach Bedarf, weitere Abo-Modelle anzulegen.

Wichtig: Ein Abo-Modell kann ausschließlich eine Währung haben. Sie müssen für jede Projektwährung eine separate Gruppe von Abo-Modellen anlegen.

Belohnungen für ein Premium-Abo-Modell einrichten

Sie können folgende Belohnungen zu einem Premium-Abo-Modell hinzufügen:

  1. Ein individueller Rabatt auf virtuelle Gegenstände und Angebotspakete mit Ingame-Währung im Game-Store.
  2. Wiederkehrende Aufstockung von Ingame-Währung.
  3. Wiederkehrende Aufstockung von virtuellen Gegenständen. Ein Benutzer kann Folgendes erhalten:
    • Zufällige Gegenstände aus einer Liste; das Spektrum von Gegenständen und die Wahrscheinlichkeit, mit der man die Gegenstände erhält, lassen sich in den Projekteinstellungen konfigurieren.
    • Bestimmte Gegenstände; die Reihenfolge ist in den Projekteinstellungen definiert.

Wichtig: Je nach gewählter Belohnung müssen Sie beim Modul Virtuelle Gegenstände und/oder beim Modul Virtuelle Währung zusätzliche Einstellungen vornehmen.

Um Belohnungen einzurichten, senden Sie eine Anfrage an integration@xsolla.com.

Token beziehen, um den Store aufzurufen

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.

Benutzeroberfläche des Stores aufrufen

Es gibt drei Möglichkeiten, den Store aufzurufen:

  • Verwenden Sie das eingebettete Pay-Station-Script.
  • Neues Fenster.
  • Iframe.

Nutzen Sie folgende URL, um den Store im Sandbox-Modus aufzurufen: https://sandbox-secure.xsolla.com/.

Pay Station einbetten

Das Script Pay-Station einbetten bestimmt den Gerätetyp und ruft die Store-Benutzeroberfläche in einer Lightbox (bei Desktop-Bildschirmen) oder in einem neuen Fenster (bei mobilen Endgeräten) auf. Wir empfehlen Ihnen, asynchrones Laden von Scripten zu verwenden.

Beispiel für asynchrones Laden eines Scripts:

  <script>
      var options = {
          access_token: 'ACCESS_TOKEN', //TODO use access token, received on previous step
          sandbox: true //TODO please do not forget to remove this setting when going live
      };
      var s = document.createElement('script');
      s.type = "text/javascript";
      s.async = true;
      s.src = "https://static.xsolla.com/embed/paystation/1.0.7/widget.min.js";
      s.addEventListener('load', function (e) {
          XPayStationWidget.init(options);
      }, false);
      var head = document.getElementsByTagName('head')[0];
      head.appendChild(s);
  </script>

<button data-xpaystation-widget-open>Buy Credits</button>

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

Neues Fenster

Nutzen Sie bitte folgenden Link, um die Store-Benutzeroberfläche in einem neuen Fenster aufzurufen: https://secure.xsolla.com/paystation2/?access_token=ACCESS_TOKEN; wobei ACCESS_TOKEN der Token ist, der im vorherigen Schritt bezogen wurde.

Iframe

Um die Benutzeroberfläche des Stores in einem iframe aufzurufen, müssen Sie Ihrerseits folgenden Mechanismus implementieren:

  • Definieren Sie den Gerätetyp (Desktop oder mobiles Endgerät) und senden Sie ihn innerhalb des Tokens mittels settings.ui.version Parameter;
  • Empfang von Ereignissen aus dem Zahlungsportal via postMessage.

Nutzen Sie bitte folgenden Link, um die Store-Benutzeroberfläche in einem neuen Fenster aufzurufen: https://secure.xsolla.com/paystation2/?access_token=ACCESS_TOKEN; wobei ACCESS_TOKEN der Token ist, der im vorherigen Schritt bezogen wurde.

Webhooks einrichten

Xsolla sendet die folgenden Webhooks an Ihr Projekt:

  • Zahlung
  • Abonnement abgeschlossen
  • Inventar-Inhalt geändert
  • Abonnement aktualisiert/verlängert
  • Rückerstattung
  • Abonnement gekündigt

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.

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.

Abonnement abgeschlossen

Immer wenn ein Benutzer ein Abonnement abschließt, sendet der Xsolla-Server einen Webhook inklusive Abonnement-Informationen.

Beispiel für eine Anfrage

PHP
CURL
<?php
$request = array(
     'notification_type' => 'create_subscription',
     'user' => (
         'id' => '1234567',
         'name' => 'Xsolla User'
     ),
     'subscription' => (
         'plan_id' => 'b5dac9c8',
         'subscription_id' => '10',
         'product_id' => 'Demo Product',
         'date_create' => '2014-09-22T19:25:25+04:00',
         'date_next_charge' => '2015-01-22T19:25:25+04:00',
         'trial' =>  (
                 'value' =>  90,
                 'type' =>  'day'
             )
     )
);

$ curl -v 'https://your.hostname/your/uri' \
-X POST \
-H 'Accept: application/json' \
-H 'Content-Type: application/json' \
-H 'Authorization: Signature 13342703ccaca5064ad33ba451d800c5e823db8f' \
-d '{
         "notification_type":"create_subscription",
         "user":{
             "id":"1234567",
             "name":"Xsolla User"
         },
         "subscription":{
             "plan_id":"b5dac9c8",
             "subscription_id":"10",
             "product_id":"Demo Product",
             "date_create":"2014-09-22T19:25:25+04:00",
             "date_next_charge":"2015-01-22T19:25:25+04:00",
             "trial": {
                     "value": 90,
                     "type": "day"
                 }
         }
     }'

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

Inventar-Inhalt geändert

Immer wenn sich das Inventar eines Benutzers ändert (Hinzufügen oder Entfernen von Gegenständen), sendet der Xsolla-Server einen Webhook zum Projekt-Server.

Beispiel für eine Anfrage

PHP
CURL
$request = array(
     'virtual_currency_balance' => (
             'old_value' => '0',
             'new_value' => '200',
             'diff' => '200'
     ),
     'user' => (
         'name' => 'Xsolla User',
         'id' => '1234567',
         'email' => 'email@example.com'
     ),
     'operation_type' => 'inGamePurchase',
     'notification_type' => 'user_balance_operation',
     'items_operation_type' =>  'add',
          'items' =>  array(
              'sku' =>  '1468',
              'amount' =>  '2'
          ),
     'id_operation' => '66989'
);

curl -v https://example.com/ \
-X POST \
-H 'Content-Type:application/json' \
-H 'Accept: application/json' \
-H 'Authorization: Signature 13342703ccaca5064ad33ba451d800c5e823db8f' \
-d '
{
     "virtual_currency_balance":{
         "old_value":"0",
         "new_value":"200",
         "diff":"200"
     },
     "user":{
         "name":"Xsolla User",
         "id":"1234567",
         "email":"semail@example.com
     },
     "operation_type":"inGamePurchase",
     "notification_type":"user_balance_operation",
     "items_operation_type": "add",
          "items": [{
          "sku": "1468",
          "amount": "2"
          }],
     "id_operation":"66989"
}'

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

Abonnement aktualisiert/verlängert

Immer wenn ein Benutzer zu einem anderen Abo-Modell wechselt, das Abonnement verlängert oder wenn sich das nächste Abrechnungsdatum ändert, sendet der Xsolla-Server einen Webhook.

Beispiel für eine Anfrage

PHP
CURL
<?php
$request = array(
     'notification_type' => 'update_subscription',
     'user' => (
         'id' => '1234567',
         'name' => 'Xsolla User'
     ),
     'subscription' => (
         'plan_id' => 'b5dac9c8',
         'subscription_id' => '10',
         'product_id' => 'Demo Product',
         'date_next_charge' => '2015-01-22T19:25:25+04:00'
     )
);

$ curl -v 'https://your.hostname/your/uri' \
-X POST \
-H 'Accept: application/json' \
-H 'Content-Type: application/json' \
-H 'Authorization: Signature 13342703ccaca5064ad33ba451d800c5e823db8f' \
-d '{
         "notification_type":"update_subscription",
         "user":{
             "id":"1234567",
             "name":"Xsolla User"
         },
         "subscription":{
             "plan_id":"b5dac9c8",
             "subscription_id":"10",
             "product_id":"Demo Product",
             "date_next_charge":"2015-01-22T19:25:25+04:00"
         }
     }'

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.

Abonnement gekündigt

Immer wenn ein Abonnement gekündigt wird, sendet der Xsolla-Server einen Webhook.

Beispiel für eine Anfrage

PHP
CURL
<?php
$request = array(
     'notification_type' => 'cancel_subscription',
     'user' => (
         'id' => '1234567',
         'name' => 'Xsolla User'
     ),
     'subscription' => (
         'plan_id' => 'b5dac9c8',
         'subscription_id' => '10',
         'product_id' => 'Demo Product',
         'date_create' => '2014-09-22T19:25:25+04:00',
         'date_end' => '2015-01-22T19:25:25+04:00',
     )
);

$ curl -v 'https://your.hostname/your/uri' \
-X POST \
-H 'Accept: application/json' \
-H 'Content-Type: application/json' \
-H 'Authorization: Signature 13342703ccaca5064ad33ba451d800c5e823db8f' \
-d '{
         "notification_type":"cancel_subscription",
         "user":{
             "id":"1234567",
             "name":"Xsolla User"
         },
         "subscription":{
             "plan_id":"b5dac9c8",
             "subscription_id":"10",
             "product_id":"Demo Product",
             "date_create":"2014-09-22T19:25:25+04:00",
             "date_end":"2015-01-22T19:25:25+04:00"
         }
     }'

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.

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 den Sandbox-Modus zugreifen, indem Sie "mode = "sandbox" beim Abrufen des Tokens versenden.

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. Klicken Sie auf Kredit-/Debitkarten.
  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.

Veröffentlichung des Moduls

Um das Modul nach dessen erfolgreichem Test zu veröffentlichen, öffnen Sie dessen Einstellungen im Kundenportal, gehen Sie zur Registerkarte Veröffentlichen und klicken Sie auf Ein.

Wichtig: Bevor Sie echte Zahlungen annehmen können, müssen Sie:

  1. "mode" = "sandbox" entfernen.
  2. Unterzeichnen Sie die Vereinbarung.