Zum Inhalt springen
/
Zahlungskonto hinzufügen

Webhooks (1.0)

Überblick

Webhooks sind Benachrichtigungen über Ereignisse im System. Wenn ein bestimmtes Ereignis eintritt, sendet Xsolla eine HTTP-Anfrage mitsamt den Ereignisdaten an Ihre Anwendung. In der Regel handelt es sich dabei um eine POST-Anfrage im JSON- Format.

Ereignisbeispiele:

  • Nutzer interagiert mit einem Artikelkatalog
  • Bestellung wird bezahlt oder storniert

Wenn ein bestimmtes Ereignis eintritt, benachrichtigt Xsolla Ihr System per Webhook. Infolgedessen können Sie Aktionen einleiten, wie zum Beispiel:

  • das Guthaben eines Nutzers aufladen
  • eine Zahlung erstatten
  • dem Nutzerkonto neue Artikel gewähren oder Artikel aus dem Nutzerkonto entfernen
  • ein Abonnement aktivieren
  • einen Nutzer bei Betrugsverdacht sperren

Beispielhafter Webhook-Ablauf bei der Zahlungsabwicklung:

Webhook für die Zahlungsabwicklung

Hinweis

Je nach verwendeter Lösung und Art der Integration können die Webhooks und die Interaktionsabfolge vom angegebenen Beispiel abweichen.

Videoanleitung für die Xsolla-Webhook-Integration:

Webhooks-Einstellungen beim Arbeiten mit Xsolla-Produkten und ‑Lösungen:

Produkt/LösungErforderlich/OptionalWozu die Webhooks verwendet werden
PaymentsErforderlich
  • Benutzervalidierung.
  • Transaktionsdetails im Falle einer erfolgreichen Zahlung oder Zahlungserstattung erhalten
  • gekaufte Artikel einem Nutzer gewähren und im Falle einer Stornierung der Bestellung die Artikel entfernen
In-Game StoreErforderlich
  • Benutzervalidierung.
  • Transaktionsdetails im Falle einer erfolgreichen Zahlung oder Zahlungserstattung erhalten
  • gekaufte Artikel einem Nutzer gewähren und im Falle einer Stornierung der Bestellung die Artikel entfernen
Game SalesOptionalFür den Verkauf von Spielschlüsseln sind keine Benutzervalidierung und keine Gewährung von Artikeln erforderlich. Dennoch können Sie Webhooks nutzen, wenn Sie Informationen über Ereignisse erhalten möchten, z. B., wenn eine Bestellung bezahlt oder storniert wird.
Wenn Sie sich für Webhooks entscheiden, ist es wichtig, alle eingehenden erforderlichen Webhooks zu verarbeiten.
SubscriptionsOptionalZum Abrufen von Informationen über den Abschluss, die Aktualisierung oder die Kündigung eines Abonnements. Alternativ können Sie die Informationen auch über die API anfordern.
Web ShopErforderlich
  • Benutzervalidierung.
  • Transaktionsdetails im Falle einer erfolgreichen Zahlung oder Zahlungserstattung erhalten
  • gekaufte Artikel einem Nutzer gewähren und im Falle einer Stornierung der Bestellung die Artikel entfernen
  • Für die Benutzerauthentifizierung, wenn Sie Benutzer über deren ID authentifizieren. Alternativ dazu können Sie Benutzer über Xsolla Login authentifizieren.
Digital Distribution HubErforderlich
  • Benutzervalidierung.
  • Transaktions-ID aufseiten von Xsolla mit der Transaktions-ID in Ihrem System verknüpfen
  • zusätzliche Transaktionsparameter in der Bestellung übermitteln
  • gekaufte Artikel einem Nutzer gewähren und im Falle einer Stornierung der Bestellung die Artikel entfernen

Ausführliche Informationen zum Einrichten von Webhooks für den Digital Distribution Hub finden Sie in der Dokumentation.

LoginOptional

Empfang von Ereignisinformationen:

  • Benutzerregistrierung/-autorisierung
  • Bestätigung der E-Mail-Adresse des Benutzers
  • Verknüpfung eines Social-Media-Kontos des Benuters

Ausführliche Informationen zur Einrichtung von Webhooks finden Sie in der -Login-Dokumentation.

Liste der erforderlichen Webhooks

Wenn Sie Produkte und Lösungen verwenden, die Webhooks erfordern, müssen Sie die Webhooks in Ihrem Kundenportal aktivieren, testen und deren Verarbeitung einrichten. Wenn bestimmte Ereignisse eintreten, werden die Webhooks der Reihe nach gesendet. Wenn Sie also einen der Webhooks nicht verarbeiten, werden die nachfolgenden Webhooks nicht gesendet. Die Liste der erforderlichen Webhooks finden Sie unten.

In-Game Store und Payments

Für den Kauf und die Rückgabe von Artikeln auf der Website hat Xsolla zwei Webhook-Sendeoptionen eingerichtet: Informationen über Zahlungs- und Transaktionsdaten sowie Informationen über gekaufte Artikeln können entweder separat oder zusammengefasst in einem Webhook gesendet werden.

Empfang von Informationen in kombinierten Webhooks:

Wenn Sie sich nach dem 22. Januar 2025 im Kundenportal registriert haben, werden alle Informationen in den Webhooks Erfolgreiche Bezahlung der Bestellung (order_paid) und Stornierung der Bestellung (order_canceled) übermittelt. In diesem Fall müssen Sie die Webhooks Zahlung (payment) und Erstattung (refund) nicht verarbeiten.

Empfang von Informationen in separaten Webhooks:

Wenn Sie sich am oder vor dem 22. Januar 2025 im Kundenportal registriert haben, empfangen Sie die folgenden Webhooks:

Sie müssen alle eingehenden Webhooks verarbeiten. Wenn Sie auf die neue Option (Empfang kombinierter Webhooks) umsteigen möchten, wenden Sie sich an Ihren Customer Success Manager oder senden Sie eine E-Mail an csm@xsolla.com.

Damit In-Game Store und die Zahlungsverwaltung uneingeschränkt funktionieren, muss die Verarbeitung der wichtigsten Webhooks implementiert sein.

Beim Empfang kombinierter Webhooks:

Webhook-Name und ‑TypBeschreibung
Benutzervalidierung >Benutzervalidierung (user_validation)Wird in verschiedenen Phasen des Zahlungsvorgangs gesendet, um sicherzustellen, dass der Nutzer im Spiel registriert ist.
Spieldienste > kombinierte Webhooks >Erfolgreiche Bezahlung der Bestellung (order_paid)Enthält Zahlungsdaten, Transaktionsdetails und Informationen über gekaufte Artikel. Verwenden Sie die Daten aus dem Webhook, um dem Nutzer Artikel zu gewähren.
Spieldienste > kombinierte Webhooks >Stornierung der Bestellung (order_canceled)Enthält Daten der stornierten Zahlung, Transaktionsdetails und Informationen über die gekauften Artikel. Verwenden Sie die Daten aus dem Webhook, um die gekauften Artikel zu entfernen.

Beim Empfang separater Webhooks:

Webhook-Name und ‑TypBeschreibung
Benutzervalidierung >Benutzervalidierung (user_validation)Wird in verschiedenen Phasen des Zahlungsvorgangs gesendet, um sicherzustellen, dass der Nutzer im Spiel registriert ist.
Zahlungen >Zahlung (payment)Enthält Zahlungsdaten und Transaktionsdetails.
Spieldienste > separate Webhooks >Erfolgreiche Bezahlung der Bestellung (order_paid)Enthält Informationen über gekaufte Artikel. Verwenden Sie die Daten aus dem Webhook, um dem Nutzer Artikel hinzuzufügen.
Zahlungen >Erstattung (refund)Enthält Zahlungsdaten und Transaktionsdetails.
Spieldienste > separate Webhooks >Stornierung der Bestellung (order_canceled)Enthält Informationen über die gekauften Artikel und die ID der stornierten Transaktion. Verwenden Sie die Daten aus dem Webhook, um die gekauften Artikel zu entfernen.

Falls die Artikelkatalogpersonalisierung aufseiten Ihrer Anwendung implementiert ist, müssen Sie den Webhook Katalogpersonalisierung aufseiten des Partners einrichten.

Hinweis

Um echte Zahlungen entgegennehmen zu können, müssen Sie lediglich die Lizenzvereinbarung unterzeichnen und die Verarbeitung der folgenden Webhooks implementieren:

Subscriptions

Um Abo-Modelle automatisch zu verwalten, muss die Verarbeitung der wichtigsten Webhooks implementiert sein:

  • Benutzervalidierung (user_validation) – wird in verschiedenen Phasen des Bezahlvorgangs gesendet, um sicherzustellen, dass der Nutzer im Spiel registriert ist.
  • Zahlung (payment) – wird gesendet, wenn eine Bestellung bezahlt wird, und enthält Zahlungsdaten sowie Transaktionsdetails.
  • Abgeschlossenes Abonnement (create_subscription) – wird gesendet, wenn ein Webhook vom Typ Zahlung erfolgreich verarbeitet wurde oder der Nutzer ein Probeabo abgeschlossen hat. Der Webhook enthält Details über das abgeschlossene Abonnement und die Nutzerdaten. Verwenden Sie die Webhook-Daten, um das Abonnement für den Nutzer zu aktivieren.
  • Aktualisiertes Abonnement (update_subscription) – wird gesendet, wenn ein Abonnement verlängert oder geändert und Webhook vom Typ Zahlung erfolgreich verarbeitet wurde. Der Webhook enthält Details über das abgeschlossene Abonnement und die Nutzerdaten. Verwenden Sie die Webhook-Daten, um das Abonnement des Nutzers zu verlängern oder die Abonnementparameter zu ändern.
  • Erstattung (refund) – wird gesendet, wenn eine Bestellung storniert wird und enthält die Daten der stornierten Zahlung sowie Transaktionsdetails.
  • Gekündigtes Abonnement (cancel_subscription) – wird gesendet, wenn ein Webhook vom Typ Erstattung erfolgreich verarbeitet oder das Abonnement aus einem anderen Grund gekündigt wurde. Der Webhook enthält Informationen über das Abonnement und die Nutzerdaten. Verwenden Sie die Webhook-Daten, um die vom Nutzer abgeschlossenen Abonnements zu kündigen.

Webhooks im Kundenportal einrichten

Allgemeine Einstellungen

So aktivieren Sie den Empfang von Webhooks:

  1. Navigieren Sie im Kundenportal-Projekt zu Projekteinstellu ngen > Webhooks.
  2. Geben Sie im Feld Webhook-Server die URL Ihres Servers an, auf dem Sie Webhooks im Format https://example.com empfangen möchten. Sie können auch eine URL aus einem Tool, mit dem sich Webhooks testen lassen, angeben.

Hinweis:

Für die Datenübertragung wird das HTTPS-Protokoll verwendet; das HTTP-Protokoll wird nicht unterstützt.

  1. Standardmäßig wird ein geheimer Schlüssel zum Signieren von Projekt-Webhooks generiert. Wenn Sie einen neuen geheimen Schlüssel generieren möchten, klicken Sie auf das Aktualisieren-Symbol.
  2. Klicken Sie auf Webhooks aktiveren.

Enable webhooks

Hinweis

Webhooks können Sie auch über eine beliebige zweckbestimmte Website (z. B. webhook.site) oder Plattform (z. B. ngrok) testen.

Hinweis

Sie können Webhooks nicht gleichzeitig an verschiedene URLs senden. Im Kundenportal können Sie jedoch zunächst eine URL zum Testen angeben und diese dann durch die echte URL ersetzen.

So deaktivieren Sie den Empfang von Webhooks:

  1. Navigieren Sie im Kundenportal-Projekt zu Projekteinstellu ngen > Webhooks.
  2. Klicken Sie auf Webhooks deaktivieren.

Erweiterte Einstellungen

Für die Webhooks im Abschnitt Payments und Store sind erweiterte Einstellungen verfügbar. Diese werden automatisch unter dem Block Allgemeine Einstellungen angezeigt, nachdem Sie auf die Schaltfläche Webhooks abrufen geklickt haben.

Hinweis

Wenn die erweiterten Einstellungen nicht angezeigt werden, müssen Sie zuerst den Webhook-Empfang in den allgemeinen Einstellungen aktivieren und dann zur Registerkarte Testen > Payments und Store wechseln.

Hier können Sie den Empfang zusätzlicher Informationen in Webhooks einrichten. Dazu müssen Sie die entsprechenden Schalter aktivieren. In jeder Berechtigungszeile werden die Webhooks angezeigt, die von der Änderung der Einstellungen betroffen sind.

SchalterBeschreibung
Infos über das gespeicherte Zahlungskonto anzeigenInformationen über die gespeicherte Zahlungsmethode werden in dem benutzerdefinierten Objekt payment_account übermittelt.
Infos über Transaktionen anzeigen, die mit gespeicherten Zahlungsmethoden getätigt wurden

Informationen werden in den folgenden benutzerdefinierten Parametern des Webhooks übermittelt.

  • saved_payment_method:
    • 0 – die gespeicherte Zahlungsmethode wurde nicht verwendet
    • 1 – die Zahlungsmethode wurde während des aktuellen Bezahlvorgangs gespeichert
    • 2 – die zuvor gespeicherte Zahlungsmethode wird verwendet
  • payment_type:
    • 1 – Einmalzahlung
    • 2 – wiederkehrende Zahlung
Bestellobjekt dem Webhook hinzufügenDie Informationen über die Bestellung werden im order-Objekt des Zahlung-Webhooks übermittelt.
Nur notwendige Nutzerparameter ohne vertrauliche Daten senden

Im Webhook werden nur die folgenden Nutzerinformationen übermittelt:

  • ID
  • Land
Individuelle Parameter sendenInformationen über individuelle Tokenparameter werden in dem Webhook übermittelt.
BLZ und Endziffern von Karten anzeigen

Im Webhook werden nur die folgenden Informationen über die Bankkartennummer übermittelt:

  • die ersten sechs Ziffern im Parameter card_bin
  • die letzten vier Ziffern im Parameter card_suffix
Kartenmarke anzeigenDie Marke der Karte, mit der die Zahlung getätigt wurde. Zum Beispiel: Mastercard oder Visa.

Erweiterte Einstellungen

Webhooks im Kundenportal testen

Webhooks zu testen, hilft dabei, sicherzustellen, dass das Projekt sowohl bei Ihnen als auch aufseiten von Xsolla korrekt eingerichtet ist.

Sind die Webhooks erfolgreich eingerichtet, wird unterhalb des Einrichtungsbereichs ein Bereich zum Testen von Webhooks angezeigt.

Webhook- Testbereich

Der Testbereich im Kundenportal variiert je nach dem, welche Webhook- Empfangsoption ausgewählt sind.

Beim Empfang kombinierter Webhooks:

Registerkartenname für Webhook-TestsWebhook-Name und ‑Typ
Payments und StoreBenutzervalidierung >Benutzervalidierung (user_validation)
Spieldienste > kombinierte Webhooks >Erfolgreiche Bezahlung der Bestellung (order_paid)
Spieldienste > kombinierte Webhooks >Stornierung der Bestellung (order_canceled)
SubscriptionsBenutzervalidierung >Benutzervalidierung (user_validation)
Zahlungen >Zahlung (payment)

Beim Empfang separater Webhooks:

Registerkartenname für Webhook-TestsWebhook-Name und ‑Typ
StoreSpieldienste > separate Webhooks >Erfolgreiche Bezahlung der Bestellung (order_paid)
Spieldienste > separate Webhooks >Stornierung der Bestellung (order_canceled)
PaymentsBenutzervalidierung >Benutzervalidierung (user_validation)
Zahlungen >Zahlung (payment)
SubscriptionsBenutzervalidierung >Benutzervalidierung (user_validation)
Zahlungen >Zahlung (payment)

Hinweis

Wird im Testbereich eine Fehlermeldung angezeigt, wonach der Test nicht erfolgreich war, sollten Sie in den Einstellungen Ihres Webhook-Listener prüfen, wie dieser auf Webhooks antwortet. Die Gründe für den fehlgeschlagenen Test sind in den Testergebnissen ersichtlich.

Beispiel:

Sie haben eine spezielle Website (z. B. webhook.site) zum Testen verwendet.

Im Abschnitt Test: Antwort auf eine ungültige Signatur wird ein Fehler angezeigt.

Das liegt daran, dass Xsolla einen Webhook mit falscher Signatur gesendet hat und nun erwartet, dass Ihr Handler mit dem HTTP-Statuscode 4xx und dem Fehlercode INVALID_SIGNATURE antwortet.

webhook.site antwortet allen Webhooks mit dem HTTP-Statuscode 200, selbst solchen Webhooks mit ungültiger Signatur. Weil der HTTP-Statuscode 4xx nicht wie erwartet empfangen wurde, ist das Testergebnis fehlerhaft.

Testfehler

Im Folgenden ist der Testvorgang für das Szenario mit kombinierten Webhooks beschrieben.

Payments und Store

Auf der Registerkarte Payments und Store können Sie die folgenden Webhooks testen:

So testen Sie die Webhooks:

  1. Wechseln Sie im Webhooks-Testbereich zur Registerkarte Payments und Store.

  2. Wählen Sie im Drop-down-Menü einen Artikeltyp aus. Ist der ausgewählte Artikeltyp im Kundenportal nicht eingerichtet, klicken Sie auf:

    • Verknüpfen, sofern das entsprechende Modul noch nicht verknüpft ist,
    • Konfigurieren, sofern das Modul bereits verknüpft, aber die Einrichtung noch nicht abgeschlossen ist.
      Durch Klick auf die Schaltfläche werden Sie zum entsprechenden Abschnitt im Kundenportal weitergeleitet. Nachdem Sie den Artikel angelegt haben, sollten Sie zum Webhook-Testbereich zurückkehren und mit dem nächsten Schritt fortfahren.

  3. Füllen Sie die Pflichtfelder aus:

    1. Wählen Sie die SKU des Artikels aus der der Drop-down-Liste aus, und legen Sie die Menge fest. Sie können mehrere Artikel desselben Typs wählen, indem Sie auf + klicken und einen weiteren Artikel in der neuen Zeile hinzufügen.
    2. Benutzer- ID – Zum Testen können Sie eine beliebige Kombination aus Buchstaben und Ziffern angeben.
    3. Public-User-ID – ID, die dem Nutzer bekannt ist, z. B. E-Mail-Adresse oder Nickname. Dieses Feld wird angezeigt, sofern die Public-User-ID in Ihrem Projekt unter Pay Station > Einstellungen aktiviert ist.
    4. Geben Sie einen beliebigen Wert in das Feld Xsolla- Bestell-ID ein.
    5. Xsolla-Rechnungs-ID – Transaktions-ID aufseiten von Xsolla. Zum Testen können Sie eine beliebige Ziffernfolge angeben.
    6. Rechnungs-ID – Transaktions-ID aufseiten Ihres Spiels. Zum Testen können Sie eine beliebige Kombination aus Buchstaben und Ziffern angeben. Dieser Parameter ist für eine erfolgreiche Zahlung nicht erforderlich. Allerdings können Sie die Transaktions-ID aufseiten Ihres Spiels mit der Transaktions-ID aufseiten von Xsolla verknüpfen, indem Sie den Parameter übermitteln.
    7. Betrag – Zahlungsbetrag. Zum Testen können Sie eine beliebige Ziffernfolge angeben.
    8. Währung – Wählen Sie eine Währung aus der Drop-down-Liste aus.

  4. Klicken Sie auf Webhooks testen.

Die Webhooks Benutzervalidierung, Erfolgreiche Bezahlung der Bestellung und Stornierung der Bestellung werden zusammen mit den angegebenen Daten an die festgelegte URL gesendet. Die Testergebnisse der einzelnen Webhook-Typen werden unter der Schaltfläche Webhooks testen angezeigt.

Wenn in Ihrem Projekt die Public-User-ID aktiviert ist, werden ebenso die Ergebnisse einer Benutzerprüfung angezeigt.

Für jeden Webhook müssen Sie die Verarbeitung beider Szenarien, also erfolgreich und fehlerbehaftet, konfigurieren.

Abschnitt zum Testen von Zahlungen

Subscriptions

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

Hinweis

Im Kundenportal können Sie nur die grundlegenden Webhooks vom Typ "Benutzervalidierung" und "Zahlung" testen. Wie Sie andere Webhook-Typen testen, erfahren Sie unter:

Hinweis

Damit Sie Webhooks testen können, müssen Sie unter Kundenportal > Subscriptions > Abo-Modelle mindestens eine Abo-Modell erstellt haben.

So testen Sie die Webhooks:

  1. Wechseln Sie im Testbereich zur Registerkarte Subscriptions.
  2. Füllen Sie die Pflichtfelder aus:

  1. Benutzer-ID – Zum Testen können Sie eine beliebige Kombination aus Buchstaben und Ziffern angeben.
  2. Xsolla-Rechnungs- ID – Transaktions-ID aufseiten von Xsolla. Zum Testen können Sie eine beliebige Ziffernfolge angeben.
  3. Public- User-ID – ID, die einem Nutzer bekannt ist, z. B. E-Mail-Adresse oder Nickname. Dieses Feld wird angezeigt, sofern die Public-User-ID in Ihrem Projekt unter Pay Station > Einstellungen > Sonstige Einstellungen aktiviert ist.
  4. Währung – Wählen Sie eine Währung aus der Drop-down-Liste aus.
  5. ID des Abo-Modells – Abo-Modell. Wählen Sie ein Abo-Modell aus der Drop-down-Liste.
  6. Abo-Produkt – Wählen Sie ein Produkt aus der Drop-down-Liste (optional).
  7. Betrag – Zahlungsbetrag. Zum Testen können Sie eine beliebige Ziffernfolge angeben.
  8. Rechnungs-ID – Transaktions-ID aufseiten Ihres Spiels. Zum Testen können Sie eine beliebige Kombination aus Buchstaben und Ziffern angeben. Dieser Parameter ist nicht erforderlich, um die Zahlung erfolgreich zu verarbeiten. Allerdings können Sie die Transaktions-ID aufseiten Ihres Spiels mit der Transaktions-ID aufseiten von Xsolla verknüpfen, indem Sie den Parameter übermitteln.
  9. Probezeitraum. Wenn Sie den Absc hluss eines Abonnements ohne Probezeitraum oder die Verlängerung eines Abonnements testen möchten, geben Sie den Wert 0 an.
  • Klicken Sie auf Webhooks testen.

    • Unter der angegebenen URL erhalten Sie Webhooks mit ausgefüllten Daten. Die Testergebnisse jedes Webhooks, sowohl für ein erfolgreiches Szenario als auch für ein Fehlerszenario, werden unter der Schaltfläche Webhooks testen angezeigt.

    Webhook-Listener

    Ein Webhook-Listener ist ein Programmcode, der es ermöglicht, eingehende Webhooks unter einer bestimmten URL-Adresse zu empfangen, eine Signatur zu generieren und dem Xsolla-Webhook-Server zu antworten.

    Hinweis

    Sie können die Pay Station PHP SDK-Bibliothek verwenden, die vorgefertigte Klassen für die Verarbeitung von Webhooks enthält.

    Implementieren Sie anwendungsseitig den Empfang von Webhooks von den folgenden IP-Adressen:

    • 185.30.20.0/24
    • 185.30.21.0/24
    • 185.30.22.0/24
    • 185.30.23.0/24
    • 34.102.38.178
    • 34.94.43.207
    • 35.236.73.234
    • 34.94.69.44
    • 34.102.22.197

    Wenn Sie das Produkt Login integriert haben, müssen zusätzlich implementieren, dass Webhooks von den folgenden IP-Adressen verarbeitet werden:

    • 34.94.0.85
    • 34.94.14.95
    • 34.94.25.33
    • 34.94.115.185
    • 34.94.154.26
    • 34.94.173.132
    • 34.102.48.30
    • 35.235.99.248
    • 35.236.32.131
    • 35.236.35.100
    • 35.236.117.164

    Einschränkungen:

    • In der Datenbank Ihrer Anwendung dürfen nicht mehrere erfolgreiche Transaktionen mit derselben ID vorhanden sein.
    • Wenn der Webhook-Listener einen Webhook mit einer ID empfängt, die bereits in der Datenbank vorhanden ist, muss das Ergebnis der zuvor verarbeiteten Transaktion zurückgeben werden. Es wird davon abgeraten, dem Nutzer einen gekauften Artikel zweimal zu gewähren und doppelte Datensätze in der Datenbank anzulegen.

    Signatur generieren

    Um eine sichere Datenübertragung zu gewährleisten, müssen Sie verifizieren, ob der Webhook tatsächlich vom Xsolla-Server gesendet und während der Übertragung nicht manipuliert wurde. Generieren Sie dazu Ihre eigene Signatur basierend auf der Payload des Anfragerumpfs und vergleichen Sie diese mit der Signatur im authorization-Header der eingehenden Anfrage. Wenn die Signaturen übereinstimmen, ist der Webhook authentisch und kann gefahrlos verarbeitet werden.

    Verifizierungsablauf:

    1. Rufen Sie die Signatur aus dem authorization-Header der eingehenden Webhook- Anfrage ab. Das Header-Format ist wie folgt: Signature <signature_value>.

    2. Rufen Sie den Webhook-Anfragerumpf im JSON-Format ab.

      Hinweis

      Verwenden Sie die JSON-Payload genau so, wie Sie sie erhalten haben. Die Payload darf nicht geparst oder neu codiert werden, da dies die Formatierung verändert, woraufhin die Signaturüberprüfung fehlschlägt.

    3. Generieren Sie Ihre eigene Signatur für den Abgleich:

      1. Verknüpfen Sie die JSON-Payload mit dem geheimen Schlüssel Ihres Projekts, indem Sie den Schlüssel an das Ende des Strings anhängen.
      2. Wenden Sie die kryptografische Hash-Funktion SHA-1 auf den resultierenden String an. Als Ergebnis erhalten Sie einen hexadezimalen String aus Kleinbuchstaben.

      3. Vergleichen Sie die generierte Signatur mit der Signatur im authorization-Header. Wenn beide übereinstimmen, ist der Webhook authentisch.

      Nachfolgend finden Sie Beispiele für die Implementierung der Signaturgenerierung für die folgenden Sprachen: C#, C++, Go, PHP und Node.js.

      Beispielhafter Webhook (HTTP):

      POST /your_uri HTTP/1.1
host: your.host
accept: application/json
content-type: application/json
content-length: 165
authorization: Signature 52eac2713985e212351610d008e7e14fae46f902
{
  "notification_type":"user_validation",
  "user":{
      "ip":"127.0.0.1",
      "phone":"18777976552",
      "email":"email@example.com",
      "id":1234567,
      "name":"Xsolla User",
      "country":"US"
  }
}

      Beispielhafter Webhook (curl):

      curl -v 'https://your.hostname/your/uri' \
-X POST \
-H 'authorization: Signature 52eac2713985e212351610d008e7e14fae46f902' \
-d '{
  "notification_type":
    "user_validation",
    "user":
      {
        "ip": "127.0.0.1",
        "phone": "18777976552",
        "email": "email@example.com",
        "id": 1234567,
        "name": "Xsolla User",
        "country": "US"
      }
    }'

      Implementierung der Signaturgenerierung in C# (Allgemeines Beispiel):

      Hinweis

      Dieses Code-Beispiel ist kompatibel mit .NET Framework 4.0 und höher sowie mit .NET Core und anderen modernen .NET-Versionen. Die Signaturüberprüfung verwendet einen Vergleich mit konstanter Zeit mithilfe der ConstantTimeEquals-Methode zur Verhinderung von Timing-Angriffen.

      using System;
using System.Security.Cryptography;
using System.Text;
public static class XsollaWebhookSignature
{
    public static string ComputeSha1(string jsonBody, string secretKey)
    {
        // Concatenation of the JSON from the request body and the project's secret key
        string dataToSign = jsonBody + secretKey;
        using (SHA1 sha1 = SHA1.Create())
        {
            byte[] hashBytes = sha1.ComputeHash(Encoding.UTF8.GetBytes(dataToSign));
            // Convert hash bytes to lowercase hexadecimal string
            var hexString = new StringBuilder(hashBytes.Length * 2);
            foreach (byte b in hashBytes)
            {
                hexString.Append(b.ToString("x2"));
            }
            return hexString.ToString();
        }
    }
    public static bool VerifySignature(string jsonBody, string secretKey, string receivedSignature)
    {
        string computedSignature = ComputeSha1(jsonBody, secretKey);
        string receivedSignatureLower = receivedSignature.ToLower();
        // Use constant-time comparison to prevent timing attacks
        return ConstantTimeEquals(computedSignature, receivedSignatureLower);
    }
    private static bool ConstantTimeEquals(string a, string b)
    {
        if (a.Length != b.Length)
        {
            return false;
        }
        int result = 0;
        for (int i = 0; i < a.Length; i++)
        {
            result |= a[i] ^ b[i];
        }
        return result == 0;
    }
}

      Implementierung der Signaturgenerierung in C# (.NET 5.0 und höher):

      Hinweis

      Um die Convert.ToHexString-Methode nutzen zu können, brauchen Sie .NET 5.0 oder höher.

      Über .NET 7.0 oder höher verfügen, können Sie anstelle von ConstantTimeEquals auch die CryptographicOperations.FixedTimeEquals-Methode verwenden.

      // For .NET 5.0 and later, you can use the more concise Convert.ToHexString method:
using System;
using System.Security.Cryptography;
using System.Text;
public static class XsollaWebhookSignature
{
    public static string ComputeSha1(string jsonBody, string secretKey)
    {
        string dataToSign = jsonBody + secretKey;
        using var sha1 = SHA1.Create();
        byte[] hashBytes = sha1.ComputeHash(Encoding.UTF8.GetBytes(dataToSign));
        return Convert.ToHexString(hashBytes).ToLower();
    }
    public static bool VerifySignature(string jsonBody, string secretKey, string receivedSignature)
    {
        string computedSignature = ComputeSha1(jsonBody, secretKey);
        string receivedSignatureLower = receivedSignature.ToLower();
        // Use constant-time comparison to prevent timing attacks
        return ConstantTimeEquals(computedSignature, receivedSignatureLower);
    }
    private static bool ConstantTimeEquals(string a, string b)
    {
        if (a.Length != b.Length)
        {
            return false;
        }
        int result = 0;
        for (int i = 0; i < a.Length; i++)
        {
            result |= a[i] ^ b[i];
        }
        return result == 0;
    }
}

      Implementierung der Signaturgenerierung in C# (.NET 7.0 und höher):

      Hinweis

      Wenn Sie über .NET 7.0 oder höher verfügen, könne Sie die CryptographicOperations.FixedTimeEquals-Methode verwenden.

      // For .NET 7.0+, you can use the built-in CryptographicOperations.FixedTimeEquals:
using System.Security.Cryptography;
public static bool VerifySignature(string jsonBody, string secretKey, string receivedSignature)
{
    string computedSignature = ComputeSha1(jsonBody, secretKey);
    byte[] computedBytes = Encoding.UTF8.GetBytes(computedSignature);
    byte[] receivedBytes = Encoding.UTF8.GetBytes(receivedSignature.ToLower());
    return CryptographicOperations.FixedTimeEquals(computedBytes, receivedBytes);
}

      Implementierung der Signaturgenerierung in C++ (Beispiel):

      #include <string>
#include <sstream>
#include <iomanip>
#include <openssl/sha.h>
class XsollaWebhookSignature {
public:
    static std::string computeSha1(const std::string& jsonBody, const std::string& secretKey) {
        // Concatenation of the JSON from the request body and the project's secret key
        std::string dataToSign = jsonBody + secretKey;
        unsigned char digest[SHA_DIGEST_LENGTH];
        // Create SHA1 hash
        SHA1(reinterpret_cast<const unsigned char*>(dataToSign.c_str()),
             dataToSign.length(), digest);
        // Convert to lowercase hexadecimal string
        std::ostringstream hexStream;
        hexStream << std::hex << std::setfill('0');
        for (int i = 0; i < SHA_DIGEST_LENGTH; ++i) {
            hexStream << std::setw(2) << static_cast<unsigned int>(digest[i]);
        }
        return hexStream.str();
    }
    static bool verifySignature(const std::string& jsonBody, const std::string& secretKey, const std::string& receivedSignature) {
        std::string computedSignature = computeSha1(jsonBody, secretKey);
        // Timing-safe comparison
        if (computedSignature.length() != receivedSignature.length()) {
            return false;
        }
        volatile unsigned char result = 0;
        for (size_t i = 0; i < computedSignature.length(); ++i) {
            result |= (computedSignature[i] ^ receivedSignature[i]);
        }
        return result == 0;
    }
};

      Implementierung der Signaturgenerierung in Go (Beispiel):

      package main
import (
	"crypto/sha1"
    "crypto/subtle"
	"encoding/hex"
	"strings"
)
type XsollaWebhookSignature struct{}
func (x *XsollaWebhookSignature) ComputeSha1(jsonBody, secretKey string) string {
	// Concatenation of the JSON from the request body and the project's secret key
	dataToSign := jsonBody + secretKey
	// Create SHA1 hash
	h := sha1.New()
	h.Write([]byte(dataToSign))
	signature := h.Sum(nil)
	// Convert to lowercase hexadecimal string
	return strings.ToLower(hex.EncodeToString(signature))
}
func (x *XsollaWebhookSignature) VerifySignature(jsonBody, secretKey, receivedSignature string) bool {
	computedSignature := x.ComputeSha1(jsonBody, secretKey)
	receivedSignatureLower := strings.ToLower(receivedSignature)
	// Use constant time comparison to prevent timing attacks
	return subtle.ConstantTimeCompare([]byte(computedSignature), []byte(receivedSignatureLower)) == 1
}

      Implementierung der Signaturgenerierung in PHP (Beispiel):

      <?php
class XsollaWebhookSignature
{
    /**
     * Compute SHA1 signature from webhook JSON body and secret key
     *
     * @param string $jsonBody The raw JSON body from webhook
     * @param string $secretKey The project's secret key
     * @return string The lowercase SHA1 signature
     */
    public static function computeSha1(string $jsonBody, string $secretKey): string
    {
        // Concatenation of the JSON from the request body and the project's secret key
        $dataToSign = $jsonBody . $secretKey;
        // Generate SHA1 signature
        $signature = sha1($dataToSign);
        return strtolower($signature);
    }
    /**
     * Verify webhook signature using timing-safe comparison
     *
     * @param string $jsonBody The raw JSON body from webhook
     * @param string $secretKey The project's secret key  
     * @param string $receivedSignature The signature from authorization header
     * @return bool True if signature is valid, false otherwise
     */
    public static function verifySignature(string $jsonBody, string $secretKey, string $receivedSignature): bool
    {
        $computedSignature = self::computeSha1($jsonBody, $secretKey);
        // Use hash_equals for timing-safe comparison
        return hash_equals($computedSignature, strtolower($receivedSignature));
    }
}
?>

      Implementierung der Signaturgenerierung in Node.js (Beispiel):

      const crypto = require('crypto');
class XsollaWebhookSignature {
    // IMPORTANT: jsonBody must be the raw JSON string exactly as received from Xsolla
    static computeSha1(jsonBody, secretKey) {
        // Concatenation of the JSON from the request body and the project's secret key
        const dataToSign = jsonBody + secretKey;
        // Create SHA1 hash
        const hash = crypto.createHash('sha1');
        hash.update(dataToSign, 'utf8');
        // Convert to lowercase hexadecimal string
        return hash.digest('hex').toLowerCase();
    }
    static verifySignature(jsonBody, secretKey, receivedSignature) {
        const computedSignature = this.computeSha1(jsonBody, secretKey);
        const cleanReceivedSignature = receivedSignature.toLowerCase();
        // Check if signatures have the same length before using timingSafeEqual
        if (computedSignature.length !== cleanReceivedSignature.length) {
            return false;
        }
        try {
            return crypto.timingSafeEqual(
                Buffer.from(computedSignature, 'hex'),
                Buffer.from(cleanReceivedSignature, 'hex')
            );
        } catch (error) {
            // Return false if there's any error (e.g., invalid hex characters)
            return false;
        }
    }
}

      Dem Webhook antworten

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

      • mit dem HTTP-Statuscode 200, 201 oder 204 ohne Nachrichtenrumpf im Falle einer positiven Antwort
      • mit dem HTTP-Statuscode 400 samt Problembeschreibung, sofern der angegebene Benutzer nicht gefunden oder eine ungültige Signatur übermittelt wurde. Ihr Webhook-Handler kann ebenso mit dem HTTP-Stautscode 5xx antworten, wenn Ihr Server vorübergehend Probleme hat.

      Wenn der Xsolla-Server keine Antwort auf die Webhooks Erfolgreiche Bezahlung der Bestellung und Stornierung der Bestellung empfangen hat oder aber eine Antwort mit dem HTTP-Statuscode 5xx, werden die Webhooks gemäß dem folgenden Zeitplan erneut gesendet:

      • zwei Versuche im Abstand von 5 Minuten
      • sieben Versuche im Abstand von jeweils 15 Minuten
      • zehn Versuche im Abstand von jeweils 60 Minuten

      Innerhalb von 12 Stunden nach dem ersten Versuch werden maximal 20 Versuche unternommen, Webhooks zu senden.

      Die Logik für das erneute Senden der Webhooks Zahlung und Erstattung ist auf der jeweiligen Webhook- Seite beschrieben.

      Hinweis

      Die Zahlung wird dem Nutzer auch dann erstattet, wenn alle folgenden Bedingungen erfüllt sind:

      • Xsolla hat die Erstattung veranlasst.
      • Als Antwort auf einen Webhook wurde ein Statuscode 4xx zurückgegeben, oder es wurde nach allen weiteren Zustellversuchen keine Antwort empfangen, oder es wurde der Statuscode 5xx zurückgegeben.

      Wenn der Xsolla-Server keine Antwort auf den Webhook Benutzervalidierung empfangen hat oder aber eine Antwort mit dem HTTP-Statuscode 400 oder 5xx, wird der Webhook Benutzervalidierung nicht erneut gesendet. Stattdessen wird dem Nutzer eine Fehlermeldung angezeigt und die Webhooks Zahlung und Erfolgreiche Bezahlung der Bestellung werden nicht gesendet.

      Fehler

      Fehlercodes für den HTTP-Code 400:

      CodeNachricht
      INVALID_USERUngültiger Benutzer
      INVALID_PARAMETERUngültiger Parameter
      INVALID_SIGNATUREUnzulässige Signatur
      INCORRECT_AMOUNTUngültiger Betrag
      INCORRECT_INVOICEUngültige Rechnung
      HTTP/1.1 400 Bad Request
{
    "error":{
        "code":"INVALID_USER",
        "message":"Invalid user"
    }
}

      Liste der Webhooks

      Hinweis

      Der Benachrichtigungstyp wird im Parameter notification_type gesendet.

      WebhookBenachrichtigungstypBeschreibung
      Benutzervalidierunguser_validationWird versendet, um zu prüfen, ob ein Benutzer im Spiel existiert.
      Benutzersucheuser_searchWird versendet, um Benutzerinformationen anhand der öffentlichen Benutzer-ID abzurufen.
      ZahlungpaymentWird versendet, wenn ein Benutzer eine Zahlung abschließt.
      ErstattungrefundWird versendet, falls eine Zahlung aus einem beliebigen Grund storniert werden muss.
      Teilerstattungpartial_refundWird versendet, falls eine Zahlung aus einem beliebigen Grund teilweise storniert werden muss.
      Abgelehnte Zahlungps_declinedWird versendet, wenn eine Zahlung vom Zahlungssystem abgelehnt wird.
      Abgelehnte Transaktion (AFS)afs_rejectWird versendet, wenn eine Transaktion während einer AFS-Prüfung abgelehnt wird.
      Aktualisierte AFS-Blocklisteafs_black_listWird bei Aktualisierung der AFS-Blockliste versendet.
      Abgeschlossenes Abonnementcreate_subscriptionWird versendet, wenn ein Benutzer ein Abonnement abschließt.
      Aktualisiertes Abonnementupdate_subscriptionWird versendet, wenn ein Abonnement erneuert oder geändert wird.
      Storniertes Abonnementcancel_subscriptionWird versendet, wenn ein Abonnement gekündigt wird.
      Automatisch endendes Abonnementnon_renewal_subscriptionWird versendet, wenn der Status auf "Automatisch endend" gesetzt wird.
      Zahlungskonto hinzufügenpayment_account_addWird versendet, wenn ein Benutzer ein Zahlungskonto hinzufügt oder speichert.
      Zahlungskonto entfernenpayment_account_removeWird versendet, wenn ein Benutzer das Zahlungskonto aus den gespeicherten Konten entfernt.
      Benutzervalidierung im Web Shop-Wird von einer Web Shop-Seite gesendet, um zu prüfen, ob ein Benutzer im Spiel vorhanden ist.
      Katalogpersonalisierung aufseiten des Partnerspartner_side_catalogWird gesendet, wenn ein Benutzer mit dem Shop interagiert.
      Erfolgreiche Bezahlung der Bestellungorder_paidWird gesendet, wenn eine Bestellung bezahlt wurde.
      Stornierung der Bestellungorder_canceledWird gesendet, wenn eine Bestellung storniert wird.
      StreitfalldisputeWird gesendet, wenn ein neuer Streiftall eröffnet wird.
      OpenAPI-Beschreibung herunterladen
      index.json
      index.yaml
      Sprachen
      Server
      Mock server
      https://xsolla.redocly.app/_mock/de/webhooks/
      https://api.xsolla.com/merchant/v2/

      Benutzervalidierung

      Webhooks

      Payments

      Webhooks

      Zahlungskonto hinzufügenWebhook

      Anfrage

      Xsolla sendet eine Webhook vom Typ payment_account_add an die Webhook-URL, wenn ein Benutzer bei einem Ingame-Kauf ein Zahlungskonto hinzufügt oder speichert. Wenden Sie sich an Ihren Customer Success Manager oder senden Sie eine E-Mail an csm@xsolla.com, wenn Sie diesen Webhook erhalten möchten.

      Bodyapplication/json
      notification_typestring(notification_type)erforderlich

      Benachrichtigungstyp.

      payment_accountobject

      Details des Zahlungskontos (Objekt).

      settingsobject

      Benutzerdefinierte Projekteinstellungen (Objekt).

      userobject

      Benutzerdaten (Objekt).

      curl -v 'https://your.hostname/your/uri' \
-X POST \
-H 'accept: application/json' \
-H 'content-type: application/json' \
-H 'authorization: Signature d09695066c52c1b8bdae92f2d6eb59f5b5f89843' \
-d '{
    "notification_type":"payment_account_add",
    "settings": {
      "project_id": 18404,
      "merchant_id": 2340
    },
    "user": {
        "ip": "127.0.0.1",
        "email": "email@example.com",
        "id": "1234567",
        "name": "John Smith",
        "country": "US",
        "zip": "12345"
    },
    "payment_account": {
        "id": "12345678",
        "name": "email@example.com",
        "payment_method": "24",
        "country": "US",
        "type": "paypal"
    }
}'

      Antworten

      Zur Signalisierung einer erfolgreiche Verarbeitung.

      Antwort
      Kein Inhalt

      TeilerstattungWebhook

      Anfrage

      Wird ein Betrag teilweise erstattet, sendet Xsolla die Details der stornierten Transaktion in einem Webhook vom Typ partial_refund an die Webhook-URL. Weitere Informationen zu Teilerstattungen finden Sie in dieser Anleitung.

      Wenn Sie die Webhook-URL im Kundenportal speichern, können Sie Berechtigungen erteilen, detaillierte Informationen in Webhooks zu empfangen. Aktivieren Sie dazu im Kundenportal unter Projekteins tellungen > Webhooks > Erweiterte Einstellungen den folgenden Schalter.

      Hinweis

      Wenn Sie sich am oder vor dem 22. Januar 2025 im Kundenportal registriert haben, finden Sie die Schalter unter Projekteinstellungen > Webhooks > Testen > Payments > Erweiterte Einstellungen.

      SchalterBeschreibung
      Infos über Transaktionen anzeigen, die mit gespeicherten Zahlungsmethoden getätigt wurden

      Informationen werden in den folgenden benutzerdefinierten Parametern des Webhooks übermittelt.

      • saved_payment_method:
        • 0 – die gespeicherte Zahlungsmethode wurde nicht verwendet
        • 1 – die Zahlungsmethode wurde während des aktuellen Bezahlvorgangs gespeichert
        • 2 – die zuvor gespeicherte Zahlungsmethode wird verwendet
      • payment_type:
        • 1 – Einmalzahlung
        • 2 – wiederkehrende Zahlung

      Codes zur Rückerstattung:

      CodeGrundBeschreibung
      1Cancellation by the user request / the game requestAus dem Kundenportal heraus eingeleitete Stornierung.
      3Integration errorIntegrationsprobleme zwischen Xsolla und dem Spiel.
      Empfehlung: Benutzer nicht auf Sperrliste setzen.
      5Test paymentTestweise getätigte Transaktion gefolgt von Stornierung.
      Empfehlung: Benutzer nicht auf Sperrliste setzen.
      7Fraud notification from PSZahlung wurde vom Zahlungssystem abgelehnt. Potenzieller Betrug durch Zahlungssystem entdeckt.
      Empfehlung: Benutzer auf Sperrliste setzen.
      9Cancellation by the user requestDer Benutzer war aus irgendeinem Grund nicht zufrieden mit dem Spiel oder dem Einkauf.
      Empfehlung: Benutzer nicht auf Sperrliste setzen.
      10Cancellation by the game requestDas Spiel hat die Stornierung angefordert.
      Empfehlung: Benutzer nicht auf Sperrliste setzen.
      Bodyapplication/json
      custom_parametersobject

      Ihre benutzerdefinierten Parameter.

      notification_typestring(notification_type)erforderlich

      Benachrichtigungstyp.

      payment_detailsobjecterforderlich

      Zahlungsdaten (Objekt).

      payment_details.​direct_whtobject

      Direkte Quellensteuer.

      payment_details.​paymentobject

      Vom Benutzer entrichteter Betrag (Objekt).

      payment_details.​payment_method_feeobject

      Gebühren des Zahlungssystems.

      payment_details.​payment_method_sumobject

      Betrag, der vom Zahlungssystem abgebucht wird.

      payment_details.​payoutobject

      Details zur Auszahlung (Objekt).

      payment_details.​payout_currency_ratestring

      Wechselkurs zwischen Zahlungs- und Auszahlungswährung.

      payment_details.​repatriation_commissionobject

      Objekt mit Daten über die Rückübertragungskosten, die Xsolla von Dritten auferlegt wurden.

      payment_details.​sales_taxobject

      Sales Tax (Objekt; nur in den USA und Kanada).

      payment_details.​vatobject

      Angaben zur MwSt. (Objekt, nur in der EU).

      payment_details.​xsolla_balance_sumobject

      Betrag, der vom Xsolla-Konto abgebucht wird.

      payment_details.​xsolla_feeobject

      Xsolla-Gebühr (Objekt).

      purchaseobject

      Objekt, welches Angaben zum Kauf enthält.

      refund_detailsobject

      Benutzerdaten (Objekt).

      settingsobject

      Benutzerdefinierte Projekteinstellungen (Objekt).

      transactionobjecterforderlich

      Details zur Transaktion (Objekt).

      transaction.​agreementinteger

      ID der Vereinbarung.

      transaction.​datestring

      Transaktionsdatum.

      transaction.​dry_runinteger

      Testtransaktion. Der Parameter hat den Wert 1, wenn es sich um eine Testtransaktion handelt. Er wird nicht gesendet, wenn es sich um eine echte Transaktion handelt.

      transaction.​external_idstring

      Externe ID der Transaktion.

      transaction.​idinteger

      ID der Transaktion.

      userobject

      Benutzerdaten (Objekt).

      curl -v 'https://your.hostname/your/uri' \
-X POST \
-d '{
        "notification_type": "partial_refund",
        "settings": {
          "project_id": 18404,
          "merchant_id": 2340
        },
        "purchase": {
            "checkout": {
                "currency": "USD",
                "amount": 50
            },
            "total":{
                "currency": "USD",
                "amount": 200
            }
        },
        "user": {
            "ip": "127.0.0.1",
            "phone": "18777976552",
            "email": "email@example.com",
            "id": "1234567",
            "name": "John Smith",
            "country": "US"
        },
        "transaction": {
            "id": 1,
            "external_id": 1,
            "dry_run": 1,
            "agreement": 1,
            "date": "2022-03-01 10:53:15"
        },
        "refund_details": {
            "author": "email@example.com",
            "date": "2022-03-01 10:56:48"
        },
        "payment_details": {
            "sales_tax": {
                "currency": "USD",
                "amount": 0
            },
            "direct_wht": {
                "currency": "USD",
                "amount": 0.70
            },
            "xsolla_fee": {
                "currency": "USD",
                "amount": "10"
            },
            "payout": {
                "currency": "USD",
                "amount": "200"
            },
            "payment_method_fee": {
                "currency": "USD",
                "amount": "20"
            },
            "payment": {
                "currency": "USD",
                "amount": "230"
            },
            "repatriation_commission": {
                "currency": "USD",
                "amount": 10
            }
        }
    }
}'

      Antworten

      Zur Signalisierung einer erfolgreiche Verarbeitung.

      Antwort
      Kein Inhalt

      ZahlungWebhook

      Anfrage

      Wenn ein Nutzer eine Zahlung abschließt, sendet Xsolla die Zahlungsdetails in einem Webhook vom Typ payment an die Webhook-URL.

      Die erwarteten Antwortcodes sind im Abschnitt Responses beschrieben, Sie können jedoch auch andere Antwortcodes verwenden:

      AntwortcodeBeschreibung
      200, 201, 204Eine erfolgreiche Antwort.
      4xxEin Fehler ist aufgetreten. Beispielsweise wurde der angegebene Nutzer nicht gefunden oder eine ungültige Signatur wurde übermittelt.
      5xxEin temporärer Serverfehler. Bei einer solchen Antwort versucht Xsolla automatisch, den Webhook erneut zu senden. Dabei verlängert sich das Intervall zwischen den Versuchen schrittweise, bis Ihr Listener den Empfang bestätigt. Es werden maximal 12 Versuche innerhalb eines Zeitraums von 48 Stunden unternommen.

      Wenn Sie die Webhook-URL im Kundenporta l speichern, können Sie auch den Empfang zusätzlicher Informationen in Webhooks einrichten.

      Hinweis

      Wenn Sie sich am oder vor dem 22. Januar 2025 im Kundenportal registriert haben, finden Sie die Schalter in Ihre Projekt unter Einstellungen > Webhooks > Testen > Payments > Erweiterte Einstellungen.

      SchalterBeschreibung
      Infos über das gespeicherte Zahlungskonto anzeigenInformationen über die gespeicherte Zahlungsmethode werden in dem benutzerdefinierten Objekt payment_account übermittelt.
      Infos über Transaktionen anzeigen, die mit gespeicherten Zahlungsmethoden getätigt wurden

      Informationen werden in den folgenden benutzerdefinierten Parametern des Webhooks übermittelt.

      • saved_payment_method:
        • 0 – die gespeicherte Zahlungsmethode wurde nicht verwendet
        • 1 – die Zahlungsmethode wurde während des aktuellen Bezahlvorgangs gespeichert
        • 2 – die zuvor gespeicherte Zahlungsmethode wird verwendet
      • payment_type:
        • 1 – Einmalzahlung
        • 2 – wiederkehrende Zahlung
      Bestellobjekt dem Webhook hinzufügenDie Informationen über die Bestellung werden im order-Objekt des Zahlung-Webhooks übermittelt.
      Nur notwendige Nutzerparameter ohne vertrauliche Daten senden

      Im Webhook werden nur die folgenden Nutzerinformationen übermittelt:

      • ID
      • Land
      BLZ und Endziffern von Karten anzeigen

      Im Webhook werden nur die folgenden Informationen über die Bankkartennummer übermittelt:

      • die ersten sechs Ziffern im Parameter card_bin
      • die letzten vier Ziffern im Parameter card_suffix
      Kartenmarke anzeigenDie Marke der Karte, mit der die Zahlung getätigt wurde. Zum Beispiel: Mastercard oder Visa.

      Hinweis

      Die in einem Webhook versendeten Felder hängen von Folgendem ab:

      • den erweiterten Einstellungen im Kundenportal
      • den bei Xsolla konfigurierten benutzerdefinierten Einstellungen

      Bei Fragen wenden Sie sich bitte an Ihren Customer Success Manager oder senden Sie eine E-Mail an csm@xsolla.com.

      Bodyapplication/json
      custom_parametersobject

      Ihre benutzerdefinierten Parameter.

      notification_typestring(notification_type)erforderlich

      Benachrichtigungstyp.

      payment_detailsobjecterforderlich

      Zahlungsdaten (Objekt).

      payment_details.​country_whtobject

      Quellensteuer, die in bestimmten Ländern aufgrund grenzüberschreitender Transaktionen anfällt (Objekt).

      payment_details.​direct_whtobject

      Direkte Quellensteuer.

      payment_details.​paymentobject

      Vom Benutzer entrichteter Betrag (Objekt).

      payment_details.​payment_method_feeobject

      Gebühren des Zahlungssystems.

      payment_details.​payment_method_sumobject

      Betrag, der vom Zahlungssystem abgebucht wird.

      payment_details.​payoutobject

      Details zur Auszahlung (Objekt).

      payment_details.​payout_currency_ratestring

      Wechselkurs zwischen Zahlungs- und Auszahlungswährung.

      payment_details.​repatriation_commissionobject

      Objekt mit Daten über die Rückübertragungskosten, die Xsolla von Dritten auferlegt wurden.

      payment_details.​sales_taxobject

      Sales Tax (Objekt; nur in den USA und Kanada).

      payment_details.​user_acquisition_feeobject

      Der Gesamtbetrag der Nutzerakquisitionsgebühren, der für die durch Affiliate-Netzwerke und Influencer vermittelten Käufe abgezogen wird (Objekt).

      payment_details.​vatobject

      Angaben zur MwSt. (Objekt, nur in der EU).

      payment_details.​xsolla_balance_sumobject

      Betrag, der vom Xsolla-Konto abgebucht wird.

      payment_details.​xsolla_feeobject

      Xsolla-Gebühr (Objekt).

      purchaseobject

      Objekt, welches Angaben zum Kauf enthält.

      settingsobject

      Benutzerdefinierte Projekteinstellungen (Objekt).

      transactionobjecterforderlich

      Details zur Transaktion (Objekt).

      transaction.​agreementinteger

      ID der Vereinbarung.

      transaction.​dry_runinteger

      Testtransaktion. Der Parameter hat den Wert 1, wenn es sich um eine Testtransaktion handelt. Er wird nicht gesendet, wenn es sich um eine echte Transaktion handelt.

      transaction.​external_idstring(external-id)

      Externe Transaktions-ID. Ausführliche Informationen finden Sie in den FAQs.

      transaction.​idinteger

      ID der Transaktion.

      transaction.​payment_datestring

      Zahlungsdatum.

      transaction.​payment_methodinteger

      ID der Zahlungsart.

      transaction.​payment_method_namestring

      Name der Zahlungsmethode.

      transaction.​payment_method_order_idstring

      Zahlungs-ID im Zahlungssystem.

      userobject

      Benutzerdaten (Objekt).

      curl -v 'https://your.hostname/your/uri' \
-X POST \
-d '{
    "notification_type": "payment",
    "settings": {
      "project_id": 18404,
      "merchant_id": 2340
    },
    "purchase": {
        "subscription": {
            "plan_id": "b5dac9c8",
            "subscription_id": "10",
            "product_id": "Demo Product",
            "date_create": "2014-09-22T19:25:25+04:00",
            "date_next_charge": "2014-10-22T19:25:25+04:00",
            "currency": "USD",
            "amount": 9.99
        },
        "checkout": {
            "currency": "USD",
            "amount": 50
        },
        "total": {
            "currency": "USD",
            "amount": 200
        },
        "promotions": [{
            "technical_name": "Demo Promotion",
            "id": 853
        }],
        "coupon": {
            "coupon_code": "ICvj45S4FUOyy",
            "campaign_code": "1507"
        },
        "order": {
          "id": 1234
          "lineitems": [
          {
            "sku": "com.xsolla.item_1",
            "quantity": 1,
            "price": {
              "currency": "EUR",
              "amount": 6.5
              }
          }
          ]
          }
    },
    "user": {
        "ip": "127.0.0.1",
        "phone": "18777976552",
        "email": "email@example.com",
        "id": "1234567",
        "name": "John Smith",
        "country": "US"
    },
    "transaction": {
        "id": 1,
        "external_id": 1,
        "payment_date": "2014-09-24T20:38:16+04:00",
        "payment_method": 1,
        "payment_method_name": "PayPal",
        "payment_method_order_id": 1234567890123456789,
        "dry_run": 1,
        "agreement": 1
    },
    "payment_details": {
        "payment": {
            "currency": "USD",
            "amount": 230
        },
        "vat": {
            "currency": "USD",
            "amount": 0,
            "percent": 20
        },
        "sales_tax": {
            "currency": "USD",
            "amount": 0,
            "percent": 0
        },
        "direct_wht": {
            "currency": "USD",
            "amount": 0,
            "percent": 0
        },
        "payout_currency_rate": "1",
        "payout": {
            "currency": "USD",
            "amount": 200
        },
        "country_wht": {
            "currency": "USD",
            "amount": 2,
            "percent": 10
        },
        "user_acquisition_fee": {
            "currency": "USD",
            "amount": 2,
            "percent": 1
        },
        "xsolla_fee": {
            "currency": "USD",
            "amount": 10
        },
        "payment_method_fee": {
            "currency": "USD",
            "amount": 20
        },
        "repatriation_commission": {
            "currency": "USD",
            "amount": 10
        }
    },
    "custom_parameters": {
        "parameter1": "value1",
        "parameter2": "value2"
    }
}'

      Antworten

      Zur Signalisierung einer erfolgreiche Verarbeitung.

      Antwort
      Kein Inhalt

      Kombinierte Webhooks

      Webhooks

      Separate Webhooks

      Webhooks

      Personalisierungs-Webhook

      Webhooks

      Anti-fraud

      Webhooks

      Subscriptions

      Webhooks