Benutzern Käufe gewähren

Implementieren Sie, dass den Nutzern in Ihrer Anwendung Käufe gewährt werden, indem Sie die in den Webhooks von Xsolla empfangenen Informationen (Transaktionsdetails und gekauften Artikel) verwenden.

Für den ordnungsgemäßen Betrieb des Ingame-Shops und des Zahlungsmanagements ist es notwendig, die Verarbeitung der wichtigsten Webhooks zu implementieren:

Das folgende Schema veranschaulicht den Ablauf beim Kauf und bei der Erstattung von Artikeln unter Verwendung kombinierter Webhooks.

  %%{init: {'themeVariables': { 'noteBkgColor': 'transparent', 'noteBorderColor': 'transparent' }}}%%
sequenceDiagram
    participant User as Nutzer
    participant GameClient as Spiel-Client
    participant Xsolla as Xsolla
    participant GameServer as Spielserver
    %% Item Purchase
    rect rgb(243, 243, 241)
        Note over User, GameServer: Artikelkauf
    end
        User ->> GameClient: meldet sich an
        activate GameClient
        GameClient ->> Xsolla: sendet Nutzerauthentifizierungsanfrage
        activate Xsolla
        Xsolla -->> GameClient: gibt JWT/OAuth 2.0-Token zurück
        deactivate Xsolla
        GameClient ->> Xsolla: sendet JWT, Projekt-ID, Paginierungsparameter
        activate Xsolla
        Xsolla -->> GameClient: gibt Artikel-Array zurück
        deactivate Xsolla
        GameClient -->> User: zeigt Storefront an
        deactivate GameClient
        User ->> GameClient: wählt Artikel aus und klickt auf “Zahlen”
        activate GameClient
        GameClient ->> Xsolla: erstellt Bestellanfrage
        deactivate GameClient
        activate Xsolla
        Xsolla -->> GameClient: gibt Zahlungstoken zurück
        deactivate Xsolla
        activate GameClient
        GameClient ->> Xsolla: öffnet Zahlungsportal-URL mit dem empfangenen Token
        deactivate GameClient
        activate Xsolla
        Xsolla ->> GameServer: sendet den Webhook “Benutzervalidierung”
        activate GameServer
        GameServer -->> Xsolla: antwortet mit dem Status “Erfolgreich”
        deactivate GameServer
        Xsolla -->> User: zeigt Zahlungsportal an
        deactivate Xsolla
        User ->> Xsolla: wählt Zahlungsmethode aus und klickt auf “Zahlen”
        activate Xsolla
        Xsolla ->> GameServer: sendet den Webhook “Erfolgreiche Bezahlung der Bestellung”
        activate GameServer
        activate GameServer
        Note right of GameServer: gewährt dem Nutzer die Käufe
        deactivate GameServer
        GameServer -->> Xsolla: antwortet mit dem Status “Erfolgreich”
        deactivate GameServer
        Xsolla -->> User: zeigt an, dass die Zahlung erfolgreich war
        deactivate Xsolla
    %% Refund / Chargeback
    rect rgb(243, 243, 241)
        Note over User, GameServer: Erstattung/Rückbuchung
    end
        User ->> Xsolla: beantragt Erstattung oder Rückbuchung
        activate Xsolla
        Xsolla ->> GameServer: sendet den Webhook “Stornierung der Bestellung”
        activate GameServer
        activate GameServer
        Note right of GameServer: entfernt Artikel aus dem Nutzerinventar
        deactivate GameServer
        GameServer -->> Xsolla: antwortet mit dem Status “Erfolgreich”
        deactivate GameServer
        Xsolla -->> User: erstattet die Zahlung
        deactivate Xsolla

Wenn die Personalisierung des Artikelkatalogs aufseiten Ihrer Anwendung implementiert ist, müssen Sie dafür sorgen, dass die Verarbeitung der Katalogpersonalisierung aufseiten des Partners erfolgt.

Webhooks im Kundenportal einrichten

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.

Webhooks im Kundenportal testen

Sobald Sie Webhooks in Ihrem Projekt aktiviert haben, wird im Kundenportal unter den erweiterten Einstellungen ein Bereich zum Testen von Webhooks angezeigt.

Sie können die folgenden Webhooks testen:

Falls reale Werte fehlen, können Sie beliebige Werte eingeben.

Außerdem können Sie Webhooks testen, wenn Sie Käufe in der Testumgebung oder im Live-Modus tätigen. Erstattungen lassen sich nur im Live-Modus testen.

Dem Webhook antworten

Um den Empfang eines Webhooks zu bestätigen, muss Ihr Server wie folgt antworten:

• HTTP-Statuscode 200, 201 oder 204 ohne Nachrichtenrumpf im Falle einer positiven Antwort.
• HTTP-Statuscode 400 samt Problembeschreibung, sofern der angegebene Benutzer nicht gefunden oder eine ungültige Signatur übermittelt wurde.

Ihr Webhook-Handler kann ebenso mit einem HTTP-Statuscode 5xx antworten, falls Ihr Server vorübergehend Probleme hat.

Nächste Schritte

1. Richten Sie den Abonnementverkauf ein (optional).
2. Richten Sie die Benutzerauthentifizierung ein.

Konfigurieren von Artikelinformationen in Webhooks

Sie können konfigurieren, welche Artikeldaten in den Webhooks Erfolgreiche Bezahlung der Bestellung und Stornierung der Bestellung über den Array items integriert sind.

Aktivierung der Integration zusätzlicher Parameter

Aktivieren Sie die Integration von zusätzlichen Parametern die Folgendes angeben:

• ob der Artikel kostenlos ist (is_free)
• ob der Artikel ein Bonus ist (is_bonus)
• ob der Artikel ein Teil eines Bundles ist (is_bundle_content)

Um diese Parameter zu erhalten, müssen Sie Ihre Webhooks auf die Version 2 mithilfe des API-Aufrufs Informationen zu Webhook-Einstellungen aktualisieren umschalten. In der Version 1 (Standard) sind diese Parameter nicht verfügbar.

Beispiel eines Arrays von Artikeln mit zusätzlichen Parametern:

 1"items": [
 2      {
 3        "sku": "com.xsolla.item_new_1",
 4        "type": "bundle",
 5        "is_pre_order": false,
 6        "is_free": false,
 7        "is_bonus": false,
 8        "is_bundle_content": false,
 9        "quantity": 1,
10        "amount": "1000",
11        "promotions": []
12      },
13      {
14        "sku": "com.xsolla.gold_1",
15        "type": "virtual_currency",
16        "is_pre_order": false,
17        "is_free": false,
18        "is_bonus": false,
19        "is_bundle_content": true,
20        "quantity": 1500,
21        "amount": "[null]",
22        "promotions": []
23      }
24 ]

Deaktivierung der Integration von Bundle-Inhalten

Standardmäßig enthalten Webhooks alle Elemente aus dem Bundle als Liste einzelner Artikel. Sie können den Webhook so konfigurieren, dass er nur das Bundle selbst enthält, ohne dessen Inhalt aufzulisten.

In diesem Fall werden die im Bundle enthaltenen Artikel nicht im Array der items einbezogen. Im oben angezeigten Array wird der Artikel mit dem SKU-com.xsolla.gold_1, der Teil des Bundles ist, ausgeschlossen.

Beispiel eines Arrays von Artikeln, wenn Bundle-Inhalte deaktiviert sind:

 1
 2"items": [
 3      {
 4        "sku": "com.xsolla.item_new_1",
 5        "type": "bundle",
 6        "is_pre_order": false,
 7        "is_free": false,
 8        "is_bonus": false,
 9        "is_bundle_content": false,
10        "quantity": 1,
11        "amount": "1000",
12        "promotions": []
13      }
14 ]

Um die Integration des Bundle-Contents zu deaktivieren, kontaktieren Sie Ihren Customer Success Manager oder senden Sie eine E-Mail an csm@xsolla.com.

Nützliche Links