Abonnements

Die Lösung Abonnements gestattet es Benutzern, unter bestimmten Bedingungen Zugang zu einer Reihe von Diensten zu erhalten:

  • Produkte definieren – Dienste, die dem Benutzer im Rahmen eines Abonnements zur Verfügung gestellt werden.
  • Abo-Modelle((Abonnementbedingungen) definieren. Sie können Abo-Modelle für jede Währung erstellen und konfigurieren, Probezeiträume und Übergangsfristen festlegen, sich Abonnenten anzeigen lassen und den Abonnementstatus für einen bestimmten Benutzer ändern.
  • Ermöglicht es Benutzern, ihre Abonnements über ein Dashboard zu verwalten. Benutzer können sich detaillierte Abonnementinformationen und die Zahlungshistorie anzeigen lassen, das Abo-Modell ändern sowie das Abonnement aussetzen, verlängern oder kündigen.
  • Verwalten Sie Benutzerabonnements über das Kundenportal: Abo-Modelle für jede Währung erstellen und konfigurieren, Probezeiträume und Übergangsfristen festlegen, Abonnenten anzeigen und Abonnementstatus für einen bestimmten Benutzer ändern.
  • Aktivieren Sie die automatische Verlängerung über ein gespeichertes Zahlungskonto.
  • Verlängern Sie ein Abonnement manuell.

So funktioniert's

Schritt 1

Schritt 2

Schritt 3

Ablauf für den Nutzer

Abonnement-Status

Ein Abonnement kann einen der folgenden Status aufweisen:

  • Aktiv. Primärer Status. Das Abonnement wird nach der ersten erfolgreichen Zahlung erstellt und aktiviert. Weitere Gebühren können lediglich bei aktiven Abonnements anfallen.

Notice: Sie können ein Abonnement nicht manuell über die API anlegen — dies kann nur automatisch beim Kauf erfolgen.

  • Gekündigt. Das Abonnement wurde mit sofortiger Wirkung aus einem der folgenden Gründe gekündigt:
    • Status wurde über eine API-Methode oder über das Xsolla-Kundenportal geändert.
    • durch Nutzer gekündigt.
    • Abgelaufen, falls ein Ablaufdatum in den Parametern festgelegt wurde.
    • Maximale Anzahl der Abbuchungsversuche überschritten. Standardmäßig ist Drei voreingestellt. Bitte wenden Sie sich an Ihren Account Manager, um diesen Wert zu ändern.
    • Benutzer konnte im Spiel nicht gefunden werden.
    • Benutzerkonto wurde gelöscht.

Note: Wird ein Abonnement gekündigt, kann die letzte Zahlung erstattet werden. Diese Option steht sowohl dem Partner als auch dem Nutzer zur Verfügung.

  • Nicht verlängert. Verlängerung des Abonnements deaktiviert. Das Abonnement läuft bis zum Ende des aktuellen Abrechnungszeitraums weiter. Danach erfolgt ein Statuswechsel zu "Gekündigt". Eine Verlängerung kann aus einem der folgenden Gründe deaktiviert werden:
    • Status wurde über eine API-Methode oder über das Kundenportal geändert.
    • Deaktiviert durch Nutzer per Link in E-Mail.
    • Benutzerkonto wurde gelöscht.

Integrationsablauf

So integrieren Sie Abonnements:

  1. Im Kundenportal von Xsolla registrieren.
  2. Projekt erstellen.
  3. Abo-Modell einrichten.
  4. Token abrufen.
  5. Ablauf für den Aufruf der Benutzeroberfläche konfigurieren.

Note: In diesem Leitfaden werden die minimalen Einstellungen beschrieben, die für den Schnellstart der Lösung erforderlich sind. Bei Fragen wenden Sie sich bitte an Ihren Kontoverwalter.

Projekt anlegen

  1. Gehen Sie zu Projekte und klicken Sie auf Neues Projekt erstellen.
  2. Während der Einrichtung:
    1. Legen Sie die Webhook-URL fest.
    2. Generieren Sie einen geheimen Schlüssel, um Webhooks für das Projekt signieren zu können.

Abo-Modell einrichten

  1. Navigieren Sie zu den Abonnements-Einstellungen unter Projekt > Online-Shop > Abonnements.
  2. Definieren Sie folgende Parameter:
    • Name
    • Abrechnungszeitraum

Note: Ein Abo-Modell kann nur in einer Währung ausgepreist werden. Sie müssen für jede Projektwährung eine separate Gruppe von Abo-Modellen anlegen.

Webhooks einrichten

Sie müssen folgende Webhooks für das Modul Abonnements implementierten:

Bestätigen Sie den Erhalt eines Webhooks, indem Sie 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 des Webhook-Handlers zum Abschnitt Projekteinstellungen > Webhooks.

Token abrufen

Für die Integration in die Abonnements müssen Sie einen Token beziehen. Ein Token ist ein String, der Spiel-/Benutzerdaten und Zahlungseinstellungen enthält.

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

URL zum Abrufen des Tokens:

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

Token anfordern

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

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.

Copy
Full screen
  • 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');

$xsollaClient = XsollaClient::factory(array(
    'merchant_id' => MERCHANT_ID,
    'api_key' => API_KEY
));
$token = $xsollaClient->createPaymentUITokenFromRequest($tokenRequest);
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"
    }
}'

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

Zahlungsvorgang austesten

Zum Ausprobieren des Zahlungsvorgangs können Sie:

  • die Testumgebung (Sandbox-Modus) nutzen
  • Eine echte Zahlung tätigen und anschließend eine Rückerstattung über das Kundenportal vornehmen

Xsolla-Sandbox ist eine eigenständige Testumgebung, welche alle Funktionen der Live-Umgebung, mit Ausnahme echter Zahlungen, unterstützt. Sie können auf die Testumgebung zugreifen, indem Sie "mode":"sandbox" beim Abrufen des Tokens versenden.

So testen Sie eine Kartenzahlung:

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

Liste der Bankkarten, die für den Test verwendet werden

Note: Bankkartenzahlungen in der Testumgebung können in folgenden Währungen getätigt werden: USD, EUR, RUB, GBP, AED, ALL, AMD, ARS, AUD, AZN, BGN, BRL, BYN, CAD, CHF, CLP, CNY, COP, CZK, DKK, DZD, EGP, GEL, HKD, HRK, HUF, IDR, ILS, INR, ISK, JPY, KES, KGS, KRW, KZT, MAD, MDL, MKD, MNT, MXN, MYR, NGN, PEN, PHP, PKR, PLN, RON, RSD, SAR, SEK, SGD, THB, TRY, TWD, UAH, UYU, UZS, VEF, VND, ZAR.
Notice: Um echte Zahlungen erhalten zu können, entfernen Sie zuerst "mode":"sandbox".

Um den Zahlungsvorgang mit echten Zahlungen zu testen, empfiehlt es sich zudem, eine Bankkarte zu verwenden:

  1. Öffnen Sie die Abonnements-UI.
  2. Wählen Sie den zu kaufenden Gegenstand aus.
  3. Wählen Sie als Zahlungsverfahren Kredit-/Debitkarten aus.
  4. Geben Sie gültige Kartendaten ein.
  5. Rufen Sie nach erfolgter Zahlung die Transaktionssuche im Kundenportal auf.
  6. Wählen Sie Ihre testweise getätigte Transaktion aus und klicken Sie auf Rückerstatten (Die Transaktion muss den Status Abgeschlossen aufweisen).

Note: Zum Testen des Zahlungsvorgangs empfiehlt sich die Nutzung einer Visa oder MasterCard.

Abonnements-UI öffnen

Nutzen Sie folgenden Link, um die Abonnements-UI 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. Für Testzwecke steht Ihnen folgende URL zur Verfügung: https://sandbox-secure.xsolla.com/paystation2/?access_token=ACCESS_TOKEN.

Werbemöglichkeiten

Gutscheine

Gutscheine ermöglichen es Partnern, eine Werbekampagne zu erstellen, bestehend aus Gutscheincodes, die entweder vom Partner hochgeladen oder im Kundenportal generiert werden können. Gutscheine gewähren einem Benutzer virtuelle Währung, virtuelle Gegenstände oder Probetage für ein Abo-Modell. Passen Sie die Anzahl der Einlösungen und ggf. das Verfallsdatum an.

Siehe Anleitung

Prämien

Die Prämien-Funktion ermöglicht es Benutzern, einen Gegenstand als Prämie zu erhalten, wenn sie ein Bezahlabonnement abschließen.

Siehe Anleitung

Anleitungen

Mit unseren Anleitungen können Sie einige der erweiterten Funktionen von Abonnements ausprobieren: