Abonnementinformationen abrufen

Informationen über Abonnementaktivitäten lassen sich auf die folgenden Arten abrufen:

• Informationen mithilfe von API-Aufrufen abrufen (geeignet für serverlose Integration)
• Informationen bei Änderung des Abonnementstatus mithilfe von Webhooks automatisch abrufen (geeignet für Serverintegration)

Über die API einrichten

Geben Sie die Projekt-ID als Pfadparameter projectId an. Sie finden diesen Parameter im Kundenportal neben dem Projektnamen.

Legen Sie als Abfrageparameter Folgendes fest:

• limit – Obergrenze für die Anzahl der Elemente pro Seite (standardmäßig werden 15 Elemente angezeigt).
• offset – Elementnummer, bei der die Liste beginnt (die Zählung beginnt bei 0).
• locale – Sprache der Benutzeroberfläche (standardmäßig ist Englisch voreingestellt). Eingabewerte müssen der Norm ISO 639-1 entsprechen.

1curl -X 'GET' \
2  'https://subscriptions.xsolla.com/api/user/v1/projects/{projectId}/subscriptions?locale=ru&limit=5&offset=5 ' \
3  -H 'accept: application/json' \
4  -H 'Authorization: Bearer client_user_jwt'

 1{
 2  "items": [
 3    {
 4      "id": 11111111,
 5      "plan_id": 11111,
 6      "plan_external_id": "TestChangePlanBase",
 7      "plan_name": "package_recurrent_name_66053",
 8      "plan_description": "package_recurrent_description_66053",
 9      "product_id": null,
10      "product_external_id": null,
11      "product_name": null,
12      "product_description": null,
13      "status": "active",
14      "date_create": "2021-03-11T13:50:11+03:00",
15      "date_next_charge": "2031-04-11T13:51:02+03:00",
16      "date_last_charge": "2021-03-11T13:51:02+03:00",
17      "charge": {
18        "amount": "0.2500",
19        "currency": "USD"
20      },
21      "period": {
22        "value": 1,
23        "unit": "day"
24      }
25    }
26  ],
27  "has_more": true
28}

Webhooks einrichten

Die Subscriptions-Lösung unterstützt Webhooks für die folgenden Ereignisse:

• Für ein Abonnement zahlen:
  • Benutzervalidierung
  • Zahlung
  • Abgeschlossenes Abonnement

• Abonnement verlängern:
  • Benutzervalidierung
  • Zahlung
  • Aktualisiertes Abonnement
• Abonnement kündigen: Gekündigtes Abonnement (Abonnement wurde im Kundenportal gekündigt oder alle Zahlungen wurden für alle gültigen Zeiträume storniert)

• Erstattung:
  • Rückerstattung (Zahlung wurde im Kundenportal storniert)
  • Aktualisiertes Abonnement (Die Zahlung wurde storniert, das Abonnement ist aber noch aktiv. Das kann passieren, wenn der Benutzer versehentlich zweimal für das Abonnement bezahlt und nur die letzte Zahlung storniert hat.)
  • Gekündigtes Abonnement (Zahlung wurde im Kundenportal storniert oder alle Zahlungen wurden für alle gültigen Zeiträume storniert)

So aktivieren Sie den Empfang von Webhooks:

1. Navigieren Sie im Kundenportal-Projekt zum Menüpunkt Projekteinstellungen > Webhooks.
2. Geben Sie im Feld Webhook-Server die URL Ihres Servers (im Format https://example.com) an, unter dem Sie Webhooks empfangen möchten. Sie können auch eine URL aus einem Tool zum Testen von Webhooks eingeben.

3. Generieren Sie einen geheimen Schlüssel:

1. Klicken Sie im Abschnitt Secret keys auf Add key.
2. Daraufhin öffnet sich ein Modalfenster. Vergeben Sie dort einen Namen für den Schlüssel, anhand dessen Sie ihn in der allgemeinen Liste leicht wiederfinden können.
3. Klicken Sie auf Create key.
4. Klicken Sie auf Copy secret, und speichern Sie den erstellten Schlüssel in Ihrem System an einem sicheren Ort.
5. Klicken Sie auf Done.
6. Bestätigen Sie, dass Sie den Schlüssel gespeichert haben, und klicken Sie auf Ok, close.

4. Klicken Sie auf Webhooks aktivieren.

Geheimen Schlüssel austauschen

Sie können in Ihrem Projekt bis zu fünf geheime Schlüssel erstellen und zwischen ihnen wechseln.

Pro Projekt kann nur ein geheimer Schlüssel aktiv sein. Wenn Sie den Schlüssel ändern möchten, klicken Sie in der Zeile eines anderen Schlüssels auf Set as active, und bestätigen Sie die Aktion. Wir empfehlen Ihnen, den deaktiviertem Schlüssel zu löschen, sobald die Umstellung auf den neuen Schlüssel erfolgreich war.

5. Testen Sie die Webhooks im Kundenportal.
6. Testen Sie den Abonnementabschluss.
7. Testen Sie die Abonnementverlängerung.
8. Testen Sie die Abonnementkündigung.

Webhooks im Kundenportal testen

Auf der Registerkarte Subscriptions können Sie die folgenden Webhooks testen:

• Benutzervalidierung (user_validation)
• Zahlung (payment)

So testen Sie Webhooks:

1. Wechseln Sie im Testbereich zur Registerkarte Subscriptions.
2. Füllen Sie die Pflichtfelder aus:
   • Benutzer-ID – Zum Testen können Sie eine beliebige Kombination aus Buchstaben und Ziffern eingeben.
   • Xsolla-Rechnungs-ID – Transaktions-ID aufseiten von Xsolla. Zum Testen können Sie einen beliebigen numerischen Wert eingeben.
   • Öffentliche Benutzer-ID – ID, die einem Nutzer bekannt ist, z. B. E-Mail-Adresse oder Nickname. Dieses Feld wird angezeigt, wenn Sie das Kontrollkästchen Öffentliche Benutzer-ID verwenden in Ihrem Projekt unter Projekteinstellungen > Integrationseinstellungen aktiviert haben.
   • Betrag – Zahlungsbetrag. Zum Testen können Sie einen beliebigen numerischen Wert eingeben.
   • Währung – Wählen Sie eine Währung aus der Drop-down-Liste aus.
   • Abo-Modell-ID – ein Abo-Modell. Wählen Sie ein Modell aus der Drop-down-Liste.
   • Abonnementprodukt — Wählen Sie ein Produkt aus der Drop-down-Liste (optional). Die Liste wird angezeigt, sofern Produkte in Ihrem Projekt eingerichtet sind.
   • Rechnungs-ID – Transaktions-ID aufseiten Ihres Spiels. Zum Testen können Sie eine beliebige Kombination aus Buchstaben und Ziffern eingeben. Dieser Parameter ist für eine erfolgreiche Zahlung nicht zwingend erforderlich, Sie können ihn jedoch übermitteln, um die Transaktions-ID in Ihrem System mit der Transaktions-ID aufseiten von Xsolla zu verknüpfen.
   • Testzeitraum. Geben Sie den Wert 0 an, um den Kauf eines Abonnements ohne Testzeitraum oder die Verlängerung eines Abonnements zu testen.
3. Klicken Sie auf Testen.

Unter der angegebenen URL empfangen Sie Webhooks mit ausgefüllten Daten. Die Testergebnisse jedes Webhooks, sowohl für ein erfolgreiches als auch für ein fehlerhaftes Szenario, werden unter der Testen-Schaltfläche angezeigt.

Abonnementabschluss testen

Beim Testen einer Zahlung werden die Webhooks Gekündigtes Abonnement, Zahlung und Abgeschlossenes Abonnement an die von Ihnen im Schritt Webhooks einrichten angegebene URL gesendet. Um das Zahlungsverfahren zu testen, können Sie:

• die Testumgebung nutzen (für Abonnement mit einem Probezeitraum von 0 Tagen)
• eine echte Zahlung vornehmen und dann eine Erstattung über das Kundenportal veranlassen (für Abonnement mit einem Probezeitraum von mehr als 0 Tagen)

Testumgebung

1. Rufen Sie einen Token für die Testumgebung ab. Übermitteln Sie den Wert 0 an den Probezeitraum-Parameter (trial_days).
2. Wählen Sie die Zahlungsmethodengruppe Kredit-/Debitkarten aus.
3. Geben Sie die Daten einer Testbankkarte ein. Geben Sie in den übrigen Felder beliebige Werte ein. Sie können auch falsche Daten (Kartennummer, Ablaufdatum oder CVV) angeben, um einen Fehler zu erzeugen.

4. Empfangen Sie die Benutzervalidierung-, Zahlung- und Aktualisiertes Abonnement-Webhooks unter der von Ihnen im Schritt Webhooks einrichten angegebenen URL.

Echte Zahlung

1. Testen Sie die Webhooks im Kundenportal.
2. Unterzeichnen Sie die Lizenzvereinbarung.

3. Rufen Sie einen Token ab, um eine echte Zahlungen zu ermöglichen.

4. Öffnen Sie das Zahlungsportal mit dem folgenden Link: https://secure.xsolla.com/paystation4/?token=ACCESS_TOKEN, wobei ACCESS_TOKEN dem im vorherigen Schritt erlangten Token entspricht.
5. Wählen Sie die Zahlungsmethodengruppe Kredit-/Debitkarten.
6. Geben Sie gültige Bankkartendaten ein.

7. Empfangen Sie Benutzervalidierung-, Zahlung- und Aktualisiertes Abonnement-Webhooks über die von Ihnen im Schritt Webhooks einrichten angegebene Webhook-URL.
8. Erstatten Sie Ihre Zahlung. Navigieren Sie dafür im Kundenportal zum Menüpunkt Spieler-Support > Transaktionssuche.
9. Wählen Sie die testweise getätigte Transaktion aus, und klicken Sie auf die Schaltfläche Mehr (•••). Klicken Sie danach im Pop-up-Menü auf Erstatten (die Transaktion sollte den Status Abgeschlossen aufweisen). Daraufhin werden die Webhooks Gekündigtes Abonnement und Rückerstattung gesendet.

Abonnementverlängerung testen

1. Rufen Sie einen Token für die Testumgebung ab. Übermitteln Sie den Wert 0 an den Probezeitraum-Parameter (trial_days).
2. Bezahlen Sie für das Abonnement mit einer beliebigen Zahlungsmethode.
3. Öffnen Sie das Zahlungsportal erneut in der Testumgebung.
4. Zahlen Sie erneut mit einer beliebigen Zahlungsmethode, um das Abonnement zu verlängern.
5. Empfangen Sie die Webhooks Benutzervalidierung, Zahlung und Aktualisiertes Abonnement an der von Ihnen im Schritt Webhooks einrichten angegebenen Webhook-URL.

Abonnementkündigung testen

So testen Sie die Abonnementkündigung:

• Suche anhand von Abonnements
• Suche anhand kürzlicher Transaktionen
• API-Aufrufe

Suche anhand von Abonnements

1. Öffnen Sie das Kundenportal, und navigieren Sie zum Menüpunkt Spieler-Support > Abonnenten.
2. Suchen Sie das zu kündigende Abonnement.
3. Öffnen Sie das Abonnementstatusmenü und wählen Sie Folgendes aus:
   1. Kündigen und erstatten, um den Gekündigtes Abonnement- und den Rückerstattung-Webhook zu empfangen.
   2. Ohne Erstattung kündigen, um den Gekündigtes Abonnement-Webhook zu empfangen.

Suche anhand kürzlicher Transaktionen

1. Navigieren Sie im Kundenportal zum Menüpunkt Spieler-Support > Transaktionssuche.
2. Suchen Sie die kürzlich getätigten Transaktionen, die Sie stornieren möchten.
3. Klicken Sie auf das Symbol Mehr (•••). Klicken Sie im Pop-up-Menü auf Erstatten, um den Gekündigtes Abonnement- und den Rückerstattung-Webhook zu empfangen.

Über API-Aufrufe

Zahlungsportal in der Testumgebung öffnen

Rufen Sie im aktivem sandbox-Modus einen Token ab, um das Zahlungsportal in der Testumgebung zu öffnen. Der Link mit dem erforderlichen Token lässt sich auf folgende Weisen abrufen:

• Über das Kundenportal
• Über einen API-Aufruf

Über das Kundenportal

1. Testen Sie Webhooks im Kundenportal. Geben Sie den Wert 0 im Feld Probezeitraum ein, um ein Abonnement ohne Probezeitraum zu testen. Nachdem Sie eine Bestätigungsmeldung über einen erfolgreichen Test erhalten haben, wird ein Link mit dem erforderlichen Token unter der Überschrift URL der Testumgebung angezeigt.

2. Klicken Sie auf den Link mit der Bezeichnung URL der Testumgebung.

Über einen API-Aufruf

1. Übermitteln Sie die Parameter "settings":{"mode":"sandbox"} an die Methode Token erstellen. Übermitteln Sie die Parameter "purchase": {"subscription":{"trial_days": 0}}, um ein Abonnement ohne Probezeitraum zu testen.
2. Nutzen Sie dafür den folgenden Link: https://sandbox-secure.xsolla.com/paystation4/?token=ACCESS_TOKEN, wobei ACCESS_TOKEN dem im vorherigen Schritt abgerufenen Token entspricht.