Abonnements

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

  • Abonnementbasierte Produkte definieren.
  • Abo-Modelle 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.
  • Lassen Sie Benutzer Abonnements manuell verlängern.

Begriffserläuterung

Abo-Modell

Abo-Modell: Rechnungsbedingungen (Rechnungsbetrag, -währung und Abrechnungshäufigkeit), unter denen ein Benutzer Zugang zum Dienst erhält.

Abonnementbasiertes Produkt

Abonnementbasiertes Produkt: Ein Dienst oder eine Reihe von Diensten, die einem Benutzer bei Abschluss des Abonnements zur Verfügung gestellt werden.

Abonnement

Abonnement: Eine Kombination aus dem Produkt und dem gewählten Abo-Modell. Ein Benutzer ist im Besitz des Abonnements, wenn er den Abonnementplan wählt und Zugang zu dem/den Dienst(en) erhält. Die Anzahl der Abonnements, die ein Benutzer gleichzeitig abschließen kann, hängt von der Anzahl der Produkte im Projekt ab.

BEISPIEL 1

Produkt: Zugang zum Spiel

  • Abo-Modell Silver: 10 $ pro Monat
  • Abo-Modell Gold: 100 $ pro Jahr

Benutzer können eines der folgenden Abonnements auswählen:

  • Abonnement 1: Zugang zum Spiel mit dem 10-$-Monatsabo
  • Abonnement 2: Zugang zum Spiel mit dem 100-$-Jahresabo

BEISPIEL 2

Produkt 1: Zugang zu Spiel 1

Produkt 2: Zugang zu Spiel 2

  • Abo-Modell: 10 $ pro Monat

Ein Benutzer kann gleichzeitig zwei Abonnements abschließen:

  • Abonnement 1: Zugang zu Spiel 1 mit dem 10-$-Monatsabo
  • Abonnement 2: Zugang zu Spiel 2 mit dem 10-$-Monatsabo

Note: Wenn ein abonnementbasiertes Produkt nicht konfiguriert ist, kann ein Benutzer jeweils nur ein Abonnement abschließen. Um mehrere Abonnements gleichzeitig abzuschließen, müssen Sie die Produkte konfigurieren.

Übergangsfrist

Die Übergangsfrist entspricht dem Zeitraum, in dem der Benutzer nach Ablauf des Abonnements auf das Spiel weiterhin zugreifen kann. Merkmale:

  • Es werden nur Abonnements vom Typ Einmalzahlung unterstützt. Zahlung bei sich automatisch verlängernden Abonnements werden automatisch abgewickelt.
  • Sie können die Dauer der Übergangsfrist im Kundenportal ändern.
  • Das System sendet täglich eine Zahlungserinnerung, bis der Benutzer für das Abonnement zahlt oder die Übergangsfrist abgelaufen ist.
  • Der Benutzer zahlt den vollen Preis des Abonnements. Die Anzahl der Tage, welche der Benutzer in der Übergangsfrist verbringt, wird aus dem Hauptabrechnungszeitraum herausgerechnet, da diese Tage im Hauptabonnement inbegriffen sind.
  • Wenn der Wert in den Abo-Modell-Einstellungen im Feld Übergangsfrist 0 lautet, dann weist das Abo-Modell keine Übergangsfrist auf.

Anzahl der erneuten Abrechnungsversuche

Die Anzahl der erneuten Abrechnungsversuche ist ein Wert, welcher die Anzahl der Versuche definiert, Geld für ein Abonnement abzubuchen. Es werden nur sich automatisch verlängernde Abonnements mit einem gespeicherten Zahlungskonto unterstützt. Die Aktivierung erfolgt nach einer fehlgeschlagenen Abbuchung. Merkmale:

  • Das System versucht einmal täglich Geld vom Zahlungskonto abzubuchen.
  • Das System versucht, Geld abzubuchen, bis das Abonnement verlängert, vom Benutzer gekündigt oder nach Überschreiten der Anzahl der erneuten Abrechnungsversuche gekündigt wird.
  • Wenn die Einstellung aktiv ist, hat der Benutzer so lange Zugriff auf das Abonnement, bis die Anzahl der erneuten Abrechnungsversuche überschritten wird.
  • Wird das Abonnement durch den Benutzer verlängert, wird die Anzahl der Tage, an denen das System versucht hat, etwas abzubuchen (ein Tag pro Versuch), aus dem Hauptabrechnungszeitraum herausgerechnet, da diese Tage im Hauptabonnement inbegriffe.

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 angelegt 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, in E-Mail enthaltenem Link.
    • Benutzerkonto wurde gelöscht.

Integrationsablauf

So integrieren Sie Abonnements:

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

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 anlegen.
  2. Im Setup-Modus:
    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:

Copy
Full screen
Small screen
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
Small screen
php
  • 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).

Info: Nutzen Sie zum Testen des Zahlungsvorgang bei einem Abonnement mit Probezeitraum eine gültige Kreditkarte und schließen Sie die Zahlung ab. Testbankkarten eignen sich nur zum Testkauf von Abonnements ohne Probezeitraum, da Sie in einer Testumgebung kein Abrechnungskonto erstellen können.
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/paystation3/?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/paystation3/?access_token=ACCESS_TOKEN.

Produkt einrichten

API-Methoden dienen der Verwaltung von abonnementbasierten Produkten.

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: