Transaktions- und Zahlungsdetails.
Webhooks (1.0)
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:
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ösung | Erforderlich/Optional | Wozu die Webhooks verwendet werden |
|---|---|---|
| Payments | Erforderlich |
|
| Store | Erforderlich |
|
| Game Sales | Optional | Fü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. |
| Subscriptions | Optional | Zum 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 Shop | Erforderlich |
|
| Digital Distribution Hub | Erforderlich |
Ausführliche Informationen zum Einrichten von Webhooks für den Digital Distribution Hub finden Sie in der Dokumentation. |
| Login | Optional | Empfang von Ereignisinformationen:
Ausführliche Informationen zur Einrichtung von Webhooks finden Sie in der -Login-Dokumentation. |
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.
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:
- Zahlung (
payment) und Erstattung (refund) mit Informationen über die Zahlungsdaten und Transaktionsdetails. - Erfolgreiche Bezahlung der Bestellung (
order_paid) und Stornierung der Bestellung (order_canceled) mit Informationen über die gekauften Artikel.
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 ‑Typ | Beschreibung |
|---|---|
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 ‑Typ | Beschreibung |
|---|---|
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:
- Zahlung, Erfolgreiche Bezahlung der Bestellung und Benutzervalidierung, sofern Sie separate Webhooks empfangen
- Erfolgreiche Bezahlung der Bestellung und Benutzervalidierung, sofern Sie kombinierte Webhooks empfangen
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.
So aktivieren Sie den Empfang von Webhooks:
- Navigieren Sie im Kundenportal-Projekt zum Menüpunkt Projekteinstellu ngen > Webhooks.
- Geben Sie im Feld Webhook-Server die URL Ihres Servers an, auf dem Sie Webhooks im Format
https://example.comempfangen 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.
- Generieren Sie einen geheimen Schlüssel:
- Klicken Sie im Abschnitt Secret keys auf Add key.
- Daraufhin öffnet sich ein Modalfenster. Vergeben Sie dort einen Namen für den Schlüssel, anhand dessen Sie ihn in der allgemeinen Liste identifizieren können.
- Klicken Sie auf Create key.
- Klicken Sie auf Copy secret, und speichern Sie den erstellten Schlüssel an einem sicheren Ort in Ihrem System.
- Klicken Sie auf Done.
- Bestätigen Sie, dass Sie den Schlüssel gespeichert haben, und klicken Sie auf Ok, close.
Hinweis
Empfehlungen:
- Speichern Sie den generierten geheimen Schlüssel an einem sicheren Ort in Ihrem System. Der Schlüssel wird im Kundenportal nur einmal angezeigt, nämlich dann, wenn er erstellt wird.
- Geben Sie Ihren geheimen Schlüssel an niemanden weiter.
- Der geheime Schlüssel muss auf Ihrem Server gespeichert sein, keinesfalls in Binärdateien oder im Frontend.
- Klicken Sie auf Webhooks aktivieren.
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:
- Navigieren Sie im Kundenportal-Projekt zum Menüpunkt Projekteinstellu ngen > Webhooks.
- Klicken Sie auf Webhooks deaktivieren.
Es empfiehlt sich, den geheimen Schlüssel regelmäßig auszutauschen, weil dies die Sicherheit Ihrer Integration erhöht. Sie können in Ihrem Projekt bis zu fünf geheime Schlüssel erstellen und zwischen ihnen wechseln. Gehen Sie dazu wie folgt vor:
- Klicken Sie unter Projekteinstellu ngen > Webhooks auf Add key.
- Daraufhin öffnet sich ein Modalfenster. Vergeben Sie dort einen Namen für den Schlüssel, anhand dessen Sie ihn in der allgemeinen Liste identifizieren können.
- Klicken Sie auf Create key.
- Klicken Sie auf Copy secret, und speichern Sie den erstellten Schlüssel an einem sicheren Ort in Ihrem System.
- Klicken Sie auf Done.
- Bestätigen Sie, dass Sie den Schlüssel gespeichert haben, und klicken Sie auf Ok, close.
Hinweis
Empfehlungen:
- Speichern Sie den generierten geheimen Schlüssel an einem sicheren Ort in Ihrem System. Der Schlüssel wird im Kundenportal nur einmal angezeigt, nämlich dann, wenn er erstellt wird.
- Geben Sie Ihren geheimen Schlüssel an niemanden weiter.
- Der geheime Schlüssel muss auf Ihrem Server gespeichert sein, keinesfalls in Binärdateien oder im Frontend.
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.
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.
| Schalter | Beschreibung |
|---|---|
| Infos über das gespeicherte Zahlungskonto anzeigen (wird nur angezeigt, wenn Sie sich am oder vor dem 22. Januar 2025 im Kundenportal registriert haben und Webhooks separat empfangen). | Informationen ü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.
|
order-Objekt dem Webhook hinzufügen (wird nur angezeigt, wenn Sie sich am oder vor dem 22. Januar 2025 im Kundenportal registriert haben und Webhooks separat empfangen) | Die 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:
|
| Individuelle Parameter senden. | Informationen ü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:
|
| Kartenmarke anzeigen. | Die Marke der Karte, mit der die Zahlung getätigt wurde. Zum Beispiel: Mastercard oder Visa. |
| Infos über den Erstattungsgrund anzeigen | Ausführliche Informationen zu den Gründen der Erstattung. |
| Länder-Quellensteuer und Nutzerakquisitionsgebühr anzeigen | Die Objekte payment_details.country_wht und payment_details.user_acquisition_fee werden im Webhook übermittelt. Der Schalter ist standardmäßig aktiviert. |
| 3DS-Infos senden | Das Objekt cards mit den Daten für die "3-D Secure"-Prüfung wird im Webhook übermittelt. |
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.
Der Testbereich im Kundenportal variiert je nach dem, welche Webhook- Empfangsoption ausgewählt sind.
Wenn Sie sich nach dem 22. Januar 2025 im Kundenportal registriert haben, empfangen Sie Webhooks in kombinierter Form:
| Registerkartenname für Webhook-Tests | Webhook-Name und ‑Typ |
|---|---|
| Payments und Store | Benutzervalidierung >Benutzervalidierung (user_validation) |
Spieldienste > kombinierte Webhooks >Erfolgreiche Bezahlung der Bestellung (order_paid) | |
Spieldienste > kombinierte Webhooks >Stornierung der Bestellung (order_canceled) | |
| Subscriptions | Benutzervalidierung >Benutzervalidierung (user_validation) |
Zahlungen >Zahlung (payment) |
Wenn Sie sich am oder vor dem 22. Januar 2025 für das Kundenportal registriert haben, empfangen Sie Webhooks separat:
| Registerkartenname für Webhook-Tests | Webhook-Name und ‑Typ |
|---|---|
| Store | Spieldienste > separate Webhooks >Erfolgreiche Bezahlung der Bestellung (order_paid) |
Spieldienste > separate Webhooks >Stornierung der Bestellung (order_canceled) | |
| Payments | Benutzervalidierung >Benutzervalidierung (user_validation) |
Zahlungen >Zahlung (payment) | |
| Subscriptions | Benutzervalidierung >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.
Im Folgenden ist der Testvorgang für das Szenario mit kombinierten Webhooks beschrieben.
Auf der Registerkarte Payments und Store können Sie die folgenden Webhooks testen:
- Benutzervalidierung (
user_validation) - Erfolgreiche Bezahlung der Bestellung (
order_paid) - Stornierung der Bestellung (
order_canceled)
So testen Sie die Webhooks:
- Wechseln Sie im Webhooks-Testbereich zur Registerkarte Payments und Store.
- Wählen Sie in der Drop-down-Liste den Artikeltyp aus. Falls Sie diesen Artikeltyp noch nicht im Kundenportal eingerichtet haben, klicken Sie auf die entsprechende Schaltfläche, um den Artikel zu konfigurieren. Kehren Sie nach dem Erstellen des Artikel zum Webhook-Testbereich zurück, und fahren Sie mit dem nächsten Schritt fort.
- Füllen Sie die Pflichtfelder aus:
- Benutzer-ID – Zum Testen können Sie eine beliebige Kombination aus Buchstaben und Ziffern eingeben.
- Geben Sie einen beliebigen Wert im Feld Xsolla-Bestell-ID ein.
- Xsolla-Rechnungs-ID – Transaktions-ID aufseiten von Xsolla. Zum Testen können Sie einen beliebigen numerischen Wert eingeben.
- 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.
- 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.
- 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.
- 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 das Kontrollkästchen Öffentliche Benutzer-ID verwenden unter Projekteinstellun gen > Integrationseinstellungen aktiviert ist, wird der Webhook Benutzersuche ebenfalls an die URL Ihres Webhookservers gesendet und das Testergebnis angezeigt.
Für jeden Webhook müssen Sie die Verarbeitung beider Szenarien, also erfolgreich und fehlerbehaftet, konfigurieren.
Hinweis
Um Webhooks zu testen, sollten Sie mindestens ein Abo-Modell im Kundenportal unter dem Menüpunkt Artikelkatalog > Abonnements erstellt haben.
Auf der Registerkarte Subscriptions können Sie die folgenden Webhooks testen:
- Benutzervalidierung (
user_validation) - Zahlung (
payment)
Hinweis
Ausführliche Informationen zum Testen anderer Abonnementverwaltungsszenarien finden Sie im Integrationsleitfaden.
So testen Sie die Webhooks:
- Wechseln Sie im Testbereich zur Registerkarte Subscriptions.
- 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
0an, um den Kauf eines Abonnements ohne Testzeitraum oder die Verlängerung eines Abonnements zu testen.
- 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.
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/24185.30.21.0/24185.30.22.0/24185.30.23.0/2434.102.38.17834.94.43.20735.236.73.23434.94.69.4434.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.8534.94.14.9534.94.25.3334.94.115.18534.94.154.2634.94.173.13234.102.48.3035.235.99.24835.236.32.13135.236.35.10035.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.
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:
Rufen Sie die Signatur aus dem
authorization-Header der eingehenden Webhook- Anfrage ab. Das Header-Format ist wie folgt:Signature <signature_value>.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.
Generieren Sie Ihre eigene Signatur für den Abgleich:
- 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.
- Wenden Sie die kryptografische Hash-Funktion SHA-1 auf den resultierenden String an. Als Ergebnis erhalten Sie einen hexadezimalen String aus Kleinbuchstaben.
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.
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"
}
}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"
}
}'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;
}
}Hinweis
Um die Convert.ToHexString-Methode nutzen zu können, brauchen Sie .NET 5.0 oder höher.
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;
}
}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);
}#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;
}
};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
}<?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));
}
}
?>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;
}
}
}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
4xxzurückgegeben, oder es wurde nach allen weiteren Zustellversuchen keine Antwort empfangen, oder es wurde der Statuscode5xxzurü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.
Fehlercodes für den HTTP-Code 400:
| Code | Nachricht |
|---|---|
| INVALID_USER | Ungültiger Benutzer |
| INVALID_PARAMETER | Ungültiger Parameter |
| INVALID_SIGNATURE | Unzulässige Signatur |
| INCORRECT_AMOUNT | Ungültiger Betrag |
| INCORRECT_INVOICE | Ungültige Rechnung |
HTTP/1.1 400 Bad Request
{
"error":{
"code":"INVALID_USER",
"message":"Invalid user"
}
}Richtlinien:
- Verwenden Sie ausschließlich HTTPS mit einem gültigen Zertifikat.
- Vergleichen Sie die Signatur stets mit dem Rohtext des Anfragerumpfs – die Daten dürfen nicht geparst oder neu kodiert werden.
- Übermitteln Sie keine sensiblen Daten in URLs und vermeiden Sie es, technische Details in Fehlermeldungen offenzulegen.
- Der Webhook-Endpunkt muss von der CSRF-Middleware ausgenommen sein – eingehende Anfragen von Xsolla enthalten kein CSRF-Token und werden bei fehlender Ausnahme abgelehnt.
- Weiße Liste für Xsolla-IP-Adressen.
Richtlinien:
- Akzeptieren Sie die
POST-Anfrage mit dem Rumpf und den Headern unverändert, ohne Änderungen. - Überprüfen Sie die Webhook-Signatur und antworten Sie mit dem entsprechenden Statuscode:
4xx– wenn die Signaturen nicht übereinstimmen;2xx– im Erfolgsfall. Wir empfehlen, vor der Ausführung der eigentlichen Geschäftslogik mit dem Statuscode204 No Contentzu antworten.200 OKist als Antwort ebenfalls zulässig.
- Leiten Sie die Payload zur weiteren Verarbeitung an einen asynchronen Job oder eine Warteschlange weiter.
- Implementieren Sie Idempotenz . Ihr System muss in der Lage sein, denselben Webhook mehr als einmal zu empfangen.
Ablauf (Beispiel):
HTTP POST /webhooks/xsolla
read raw_body, headers
if !verify_signature(raw_body, headers['authorization']):
return 400 {"error":{"code":"INVALID_SIGNATURE","message":"Invalid signature"}}
enqueue(raw_body)
return 204 # or 200Richtlinien:
- Verwenden Sie die Transaktions-ID und/oder die externe ID sowie die Bestell-ID als Idempotenzschlüssel.
- Speichern Sie die verarbeiteten IDs, und geben Sie das vorherige Ergebnis zurück, falls ein Duplikat empfangen wird.
- Vermeiden Sie die erneute Vergabe von Artikeln, doppelte Datenbankeinträge und doppelte Abbuchungen.
- Beachten Sie, dass bei aufeinanderfolgenden Zustellungen ein Fehler bei einem früheren Ereignis die Verarbeitung aller nachfolgenden Ereignisse blockiert.
Richtlinien:
- Verwenden Sie Warteschlangen und asynchrone Verarbeitung für ressourcenintensive Vorgänge wie API-Aufrufe von Drittanbietern, Abrechnungen und die Artikelvergabe.
- Legen Sie Timeouts für den Webhook-Handler fest (1–3 Sekunden). Bei vorübergehenden Ausfällen können Sie sich auf den Xsolla- Wiederholungsmechanismus verlassen.
- Implementieren Sie keine Wiederholungsversuche im Webhook-Handler – Xsolla kümmert sich um die erneute Zustellung.
- Protokollieren Sie Zeitstempel und Verarbeitungsstatus der Webhook-Zustellung; richten Sie Warnmeldungen für Spitzenauslastungen bei
5xx-Fehlern und erneuten Zustellungen ein. - Leiten Sie Korrelations-IDs aus dem Webhook an Ihre Protokolle und Ihr Überwachungssystem (Application Performance Monitoring, APM) weiter.
- Richten Sie Fehlerprotokollierung und ‑überwachung ein. Verschieben Sie Jobs bei nicht behebbaren Fehlern in eine Warteschlange für unzustellbare Nachrichten (Dead Letter Queue, DLQ). Entwickeln Sie ein sicheres Tool zur erneuten Ausführung von Ereignissen, das durch einen Idempotenzmechanismus geschützt ist.
Erfolgreicher Kauf – Artikel beim ersten Versuch zugeteilt:
Doppelt zugeteilt (Partner-Timeout beim ersten Versuch):
Erstattung:
Ausfall beim Partner:
Nein. Zahlungs-Webhooks verwenden das Server-zu-Server-Protokoll und werden an eine einzige URL gesendet, die in den Projekteinstellungen angegeben ist. Wenn Sie Benachrichtigungen in Ihrem Spiel, auf Ihrer Website oder in Ihrer App erhalten möchten, richten Sie auf Ihrem Server den Versand von Webhooks ein, um Daten zwischen Xsolla und Ihrem Spiel auszutauschen. Sie können Webhooks auch über die Entwicklerkonsole testen.
Hinweis
Wenn Sie die Integration lokal testen, erreichen `POST`-Anfragen von Xsolla keine URLs wie http://localhost:3000/my-webhook-endpoint. Nutzen Sie Dienste wie ngrok, mit denen Sie einen Tunnel für den externen Zugriff einrichten können, sodass Sie Anfragen von Xsolla lokal empfangen können. Weitere Informationen hierzu finden Sie beispielsweise in der ngrok-Dokumentation.
Stellen Sie sicher, dass Ihr Webhook-Server die HTTP-Anfragetypen POST und GET unterstützt.
Verwenden Sie die externe ID – hierbei handelt es sich um die Transaktions-ID in Ihrem Spiel, die der Bestellung in Ihrem System zugewiesen wurde. Aufseiten von Xsolla ist die externe ID mit der Transaktions-ID verknüpft, wodurch Xsolla doppelte Zahlungen für dieselbe Transaktion verhindern kann. Weitere Informationen zur Konfiguration finden Sie in unserer Dokumentation.
Empfehlungen:
- unmittelbar nach der Signaturprüfung mit
204oder200antworten - Webhook-Signatur gegen den unveränderten Anfragerumpf abgleichen
- Idempotenz für alle Vorgänge implementieren
- alle Ereignisse protokollieren und Fehlerüberwachung einrichten
- keine sensiblen Daten in URLs übermitteln und keine technischen Details in Fehlermeldungen offenlegen
Ausführliche Informationen finden Sie im Abschnitt Best Practices.
Damit Webhooks ordnungsgemäß funktionieren, müssen vor der Inbetriebnahme die folgenden Voraussetzungen erfüllt sein:
- HTTPS wird genutzt.
- Die Webhook-Signaturprüfung erfolgt gegen den unveränderten Rohtext des Anfragerumpfs.
- Sobald die Signatur bestätigt ist, wird mit dem Statuscode
204/200geantwort. - Idempotenz ist für alle Vorgänge implementiert.
- Fehlerprotokollierung und ‑überwachung sind konfiguriert.
- Sensible Daten werden nicht in URLs übermittelt, und technische Details werden in Fehlermeldungen nicht offengelegt.
- Versuche, einen Webhook erneut zu senden, werden gemäß der Xsolla- Wiederholungslogik unterstützt.
- Die gesamte Integration ist dokumentiert.
Hinweis
Der Benachrichtigungstyp wird im Parameter notification_type gesendet.
| Webhook | Benachrichtigungstyp | Beschreibung |
|---|---|---|
| Benutzervalidierung | user_validation | Wird versendet, um zu prüfen, ob ein Benutzer im Spiel existiert. |
| Benutzersuche | user_search | Wird versendet, um Benutzerinformationen anhand der öffentlichen Benutzer-ID abzurufen. |
| Zahlung | payment | Wird versendet, wenn ein Benutzer eine Zahlung abschließt. |
| Erstattung | refund | Wird versendet, falls eine Zahlung aus einem beliebigen Grund storniert werden muss. |
| Teilerstattung | partial_refund | Wird versendet, falls eine Zahlung aus einem beliebigen Grund teilweise storniert werden muss. |
| Abgelehnte Zahlung | ps_declined | Wird versendet, wenn eine Zahlung vom Zahlungssystem abgelehnt wird. |
| Abgelehnte Transaktion (AFS) | afs_reject | Wird versendet, wenn eine Transaktion während einer AFS-Prüfung abgelehnt wird. |
| Aktualisierte AFS-Blockliste | afs_black_list | Wird bei Aktualisierung der AFS-Blockliste versendet. |
| Abgeschlossenes Abonnement | create_subscription | Wird versendet, wenn ein Benutzer ein Abonnement abschließt. |
| Aktualisiertes Abonnement | update_subscription | Wird versendet, wenn ein Abonnement erneuert oder geändert wird. |
| Storniertes Abonnement | cancel_subscription | Wird versendet, wenn ein Abonnement gekündigt wird. |
| Automatisch endendes Abonnement | non_renewal_subscription | Wird versendet, wenn der Status auf "Automatisch endend" gesetzt wird. |
| Zahlungskonto hinzufügen | payment_account_add | Wird versendet, wenn ein Benutzer ein Zahlungskonto hinzufügt oder speichert. |
| Zahlungskonto entfernen | payment_account_remove | Wird 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 Partners | partner_side_catalog | Wird gesendet, wenn ein Benutzer mit dem Shop interagiert. |
| Erfolgreiche Bezahlung der Bestellung | order_paid | Wird gesendet, wenn eine Bestellung bezahlt wurde. |
| Stornierung der Bestellung | order_canceled | Wird gesendet, wenn eine Bestellung storniert wird. |
| Streitfall | dispute | Wird gesendet, wenn ein neuer Streiftall eröffnet wird. |
OpenAPI-Beschreibung herunterladen
Sprachen
Server
https://api.xsolla.com/merchant/v2/
Mock server
https://xsolla.redocly.app/_mock/de/webhooks/
Anfrage
Xsolla sendet den Webhook order_canceled an die angegebene URL, wenn die Zahlung vom Nutzer, Partner oder automatisch storniert wurde. Der Webhook enthält Informationen über zurückgesandte Artikel, Zahlungsdaten und Details zur stornierten Bestellung.
Der Webhook wird nicht gesendet, wenn die Zahlung nicht erfolgreich war, zum Beispiel:
- das Zahlungsportal geöffnet wurde, aber der Nutzer die Bestellung nicht bezahlt hat
- das Zahlungsportal geöffnet wurde, aber während der Zahlung Fehler auftraten
Die empfohlene Verarbeitungszeit für Webhooks beträgt maximal drei Sekunden.
Zahlungsdaten (Objekt).
Objekt mit Daten zu Quellensteuern, die in bestimmten Ländern aufgrund grenzüberschreitender Transaktionen erhoben werden.
Währung. Währungscode, bestehend aus drei Buchstaben gemäß ISO 4217.
Direkte Quellensteuer.
Währung. Währungscode, bestehend aus drei Buchstaben gemäß ISO 4217.
Vom Benutzer entrichteter Betrag (Objekt).
Währung. Währungscode, bestehend aus drei Buchstaben gemäß ISO 4217.
Gebühren des Zahlungssystems.
Währung. Währungscode, bestehend aus drei Buchstaben gemäß ISO 4217.
Betrag, der vom Zahlungssystem abgebucht wird.
Währung. Währungscode, bestehend aus drei Buchstaben gemäß ISO 4217.
Details zur Auszahlung (Objekt).
Währung. Währungscode, bestehend aus drei Buchstaben gemäß ISO 4217.
Wechselkurs zwischen Zahlungs- und Auszahlungswährung.
Objekt mit Daten über die Rückübertragungskosten, die Xsolla von Dritten auferlegt wurden.
Währung. Währungscode, bestehend aus drei Buchstaben gemäß ISO 4217.
Sales Tax (Objekt; nur in den USA und Kanada).
Währung. Währungscode, bestehend aus drei Buchstaben gemäß ISO 4217.
Der Gesamtbetrag der Nutzerakquisitionsgebühren, der für die durch Affiliate-Netzwerke und Influencer vermittelten Käufe abgezogen wird (Objekt).
Währung. Währungscode, bestehend aus drei Buchstaben gemäß ISO 4217.
Angaben zur MwSt. (Objekt, nur in der EU).
Währung. Währungscode, bestehend aus drei Buchstaben gemäß ISO 4217.
Betrag, der vom Xsolla-Konto abgebucht wird.
Währung. Währungscode, bestehend aus drei Buchstaben gemäß ISO 4217.
Xsolla-Gebühr (Objekt).
Währung. Währungscode, bestehend aus drei Buchstaben gemäß ISO 4217.
Objekt, welches Angaben zum Kauf enthält.
Angaben zum Abonnement (Objekt).
Gesamtpreis des Einkaufs (Objekt).
Währung. Währungscode, bestehend aus drei Buchstaben gemäß ISO 4217.
Benutzerdaten (Objekt).
Erstattungsinitiator. Der Feldwert wird gemäß der Tabelle übermittelt:
| Erstattungsinitiator | Feldwert |
|---|---|
| Spiel (über API). | API |
| Kundenportal-Nutzer (automatische Erstattung). | E-Mail-Adresse des Nutzers |
| Kundenportal-Nutzer (mit Unterstützung des Xsolla-Kundensupports). | support@xsolla.com |
| Xsolla (mit Unterstützung des Xsolla-Kundensupports). | support@xsolla.com |
Benutzerdefinierte Projekteinstellungen (Objekt).
Projekt-ID. Dieser Parameter wird im Kundenportal neben dem Projektnamen angezeigt.
Details zur Transaktion (Objekt).
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.
Liste der vom Nutzer gekauften Artikel.
Die im Array enthaltenen Parameter hängen von der Webhook-Version ab. In Version 2 sind zusätzliche Parameter enthalten: is_free, is_bonus und is_bundle_content. Geben Sie die entsprechende Nummer im Parameter version im API-Aufruf Informationen zu Webhook-Einstellungen aktualisieren an, um die Version zu wechseln.
One of:
Angewandte Werbeaktionen für bestimmte Artikel in der Bestellung. Das Array wird in den folgenden Fällen zurückgegeben:
- Eine Rabattaktion ist für einen bestimmten Artikel konfiguriert.
- Ein Promocode mit der Einstellung Rabatt auf ausgewählte Artikel wird angewendet.
Werden keine Werbeaktionen auf Artikelebene angewandt, wird ein leeres Array zurückgegeben.
Eindeutige ID des Artikels. Bei Artikeln vom Typ game_key wird ein Wert im Format sku_drm verwendet.
Artikeltyp. Für Artikel vom Typ bundle, einschließlich virtueller Währungspakete, zeigt das Array items Folgendes an:
- Parameter des Bundles oder des virtuellen Währungspakets
- Im Bundle enthaltene Artikel oder im Paket enthaltene Währungen
Der Typ value_point wird bei Vorgängen mit Treuepunkten verwendet, d. h., wenn Punkte ausgegeben oder gutgeschrieben werden.
Enum"virtual_good""virtual_currency""game_key""bundle""value_point"
Bestellinformationen.
Die Gesamtkosten eines Warenkorbs basierend auf der gewählten Währung.
Angewandte Gutscheine. Wird der Gutschein nicht angewendet, wird kein Array zurückgegeben.
Währung der Bestellung. Bei virtuellen Währungen wird die SKU und bei echten Währungen der aus drei Buchstaben bestehende Code gemäß ISO 4217 genutzt.
Zahlungswährungstyp. Bei einer kostenlosen Bestellung ist unknown als Wert angegeben.
| Enum Wert | Beschreibung |
|---|---|
| loyalty_point | Treuepunkte |
| real | echte Währung |
| unknown | kostenlose Bestellung |
| virtual | virtuelle Währung |
Rechnungs-ID bei Zahlungen mit echter Währung. Bei Zahlungen mit virtueller Währung oder bei kostenlosen Artikeln wird der Wert null genutzt.
Zahlungsmodus. default wird bei realen Zahlungen verwendet; sandbox bei Testzahlungen.
Enum"default""sandbox"
Zahlungsplattform. Bei Zahlungen über Xsolla wird der Wert xsolla verwendet. Bei anderen Zahlungen entspricht der Wert dem Namen der Publishing-Plattform: playstation_network, xbox_live, pc_standalone, nintendo_shop, google_play, app_store_ios, android_standalone, ios_standalone, android_other, ios_other, pc_other.
Enum"xsolla""playstation_network""xbox_live""pc_standalone""nintendo_shop""google_play""app_store_ios""android_standalone""ios_standalone""android_other"
Angewandte Promocodes. Wird der Promocode nicht angewandt, wird kein Array zurückgegeben.
Angewandte Werbeaktionen für die gesamte Bestellung. Das Array wird in den folgenden Fällen zurückgegeben:
- Eine Werbeaktion wirkt sich auf den Gesamtkaufbetrag aus, z. B. ein Aktionscode mit der Einstellung Rabatt auf Kauf.
- Es wird kein Rabatt auf den Kauf angewandt, aber es werden Bonusartikel der Bestellung hinzugefügt. In diesem Fall werden die Werte für den Preis mit (amount_with_discount) und ohne Rabatt (amount_without_discount) zurückgegeben, wobei beide Werte identisch sind, da kein Rabatt angewandt wird.
Werden keine Werbeaktionen auf Bestellebene angewandt, wird ein leeres Array zurückgegeben.
Benutzerinformationen.
Land des Benutzers. Ländercode, bestehend aus 2 Großbuchstaben gemäß ISO 3166-1 ALPHA-2.
- https://api.xsolla.com/merchant/v2/order-cancellation
- Mock serverhttps://xsolla.redocly.app/_mock/de/webhooks/order-cancellation
- CURL
- Payload
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": "order_canceled",
"items": [
{
"sku": "com.xsolla.v.item_1",
"type": "virtual_good",
"is_pre_order": false,
"quantity": 3,
"amount": "1000",
"promotions": [
{
"amount_without_discount": "6000",
"amount_with_discount": "5000",
"sequence": 1
},
{
"amount_without_discount": "5000",
"amount_with_discount": "4000",
"sequence": 2
}
],
"custom_attributes": {
"purchased": 0,
"attr": "value"
}
},
{
"sku": "com.xsolla.v.item_new_1",
"type": "bundle",
"is_pre_order": false,
"quantity": 1,
"amount": "1000",
"promotions": []
},
{
"sku": "com.xsolla.gold_1",
"type": "virtual_currency",
"is_pre_order": false,
"quantity": 1500,
"amount": null,
"promotions": []
}
],
"order": {
"id": 1,
"mode": "default",
"currency_type": "virtual",
"currency": "sku_currency",
"amount": "2000",
"status": "paid",
"platform": "xsolla",
"comment": null,
"invoice_id": "1",
"promotions": [
{
"amount_without_discount": "4000",
"amount_with_discount": "2000",
"sequence": 1
}
],
"promocodes": [
{
"code": "promocode_some_code",
"external_id": "promocode_sku"
}
],
"coupons": [
{
"code": "WINTER2021",
"external_id": "coupon_sku"
}
]
},
"user": {
"external_id": "id_xsolla_login_1",
"email": "email@example.com",
"country": "US"
},
"billing": {
"notification_type": "refund",
"settings": {
"project_id": 18404,
"merchant_id": 2340
},
"purchase": {
"subscription": {
"plan_id": "b5dac9c8",
"subscription_id": "10",
"date_create": "2014-09-22T19:25:25+04:00",
"currency": "USD",
"amount": 9.99
},
"total":{
"currency": "USD",
"amount": 200
}
},
"transaction": {
"id": 1,
"external_id": 1,
"dry_run": 1,
"agreement": 1
},
"refund_details": {
"code": 4,
"reason": "Potential fraud"
},
"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
}
}
}
}Anfrage
Xsolla sendet den Webhook order_paid an die angegebene URL, wenn der Nutzer die Bestellung erfolgreich bezahlt hat.
Der Webhook order_paid enthält Informationen zu den gekauften Artikeln, Zahlungsdaten und Transaktionsdetails.
Der Webhook order_paid wird nicht gesendet, wenn die Zahlung nicht erfolgreich war, zum Beispiel:
- die Zahlungsmaske geöffnet wurde, aber der Benutzer die Bestellung nicht bezahlt hat
- die Zahlungsmaske geöffnet wurde, aber während der Zahlung Fehler auftraten
Es wird empfohlen, den Webhook order_paid in weniger als drei Sekunden zu verarbeiten.
Hinweis
Die in einem Webhook versendeten Felder hängen von den folgenden Einstellungen ab:
- den im Kundenportal unter Projekteinstellungen > Webhooks > Erweiterte Einstellungen konfigurierten Einstellungen
- den bei Xsolla konfigurierten Einstellungen
Bei Fragen wenden Sie sich bitte an Ihren Customer Success Manager oder senden Sie eine E-Mail an csm@xsolla.com.
Die erwarteten Antworten sind im Abschnitt Antworten beschrieben. Sie können andere Antwortcodes verwenden. Abhängig vom Antwortcode und je nachdem, ob die automatische Zahlungserstattung aktiviert ist oder nicht, sieht die Webhook-Verarbeitungslogik aufseiten von Xsolla wie folgt aus:
| Antwortcode | Automatische Zahlungserstattung ist deaktiviert (standardmäßig) | Automatische Zahlungserstattung ist aktiviert |
|---|---|---|
400, 401, 402, 403, 404, 409, 422, 415 | Keine Aktionen | Benutzer erhält automatische eine Erstattung |
200, 201, 204 | Keine Aktionen | Keine Aktionen |
| Anderer Code oder keine Antwort auf Webhook | Mehrere Webhooks werden innerhalb eines bestimmten Zeitintervalls gesendet: Zwei Versuche im Abstand von 5 Minuten, sieben Versuche im Abstand von jeweils 15 Minuten, zehn Versuche im Abstand von jeweils 60 Minuten. | Mehrere Webhooks werden innerhalb eines bestimmten Zeitintervalls gesendet: Zwei Versuche im Abstand von 5 Minuten, sieben Versuche im Abstand von jeweils 15 Minuten, zehn Versuche im Abstand von jeweils 60 Minuten. Wurden alle Webhooks gesendet, ohne eine erfolgreiche Antwort erhalten zu haben, wird dem Benutzer automatisch eine Erstattung ausgestellt. |
Wenden Sie sich an Ihre Customer Success Manager oder senden Sie eine E-Mail an csm@xsolla.com, um die automatische Erstattungsfunktion zu verknüpfen.
Transaktions- und Zahlungsdetails.
Zahlungsdaten (Objekt).
Objekt mit Daten zu Quellensteuern, die in bestimmten Ländern aufgrund grenzüberschreitender Transaktionen erhoben werden.
Währung. Währungscode, bestehend aus drei Buchstaben gemäß ISO 4217.
Direkte Quellensteuer.
Währung. Währungscode, bestehend aus drei Buchstaben gemäß ISO 4217.
Vom Benutzer entrichteter Betrag (Objekt).
Währung. Währungscode, bestehend aus drei Buchstaben gemäß ISO 4217.
Gebühren des Zahlungssystems.
Währung. Währungscode, bestehend aus drei Buchstaben gemäß ISO 4217.
Betrag, der vom Zahlungssystem abgebucht wird.
Währung. Währungscode, bestehend aus drei Buchstaben gemäß ISO 4217.
Details zur Auszahlung (Objekt).
Währung. Währungscode, bestehend aus drei Buchstaben gemäß ISO 4217.
Wechselkurs zwischen Zahlungs- und Auszahlungswährung.
Objekt mit Daten über die Rückübertragungskosten, die Xsolla von Dritten auferlegt wurden.
Währung. Währungscode, bestehend aus drei Buchstaben gemäß ISO 4217.
Sales Tax (Objekt; nur in den USA und Kanada).
Währung. Währungscode, bestehend aus drei Buchstaben gemäß ISO 4217.
Der Gesamtbetrag der Nutzerakquisitionsgebühren, der für die durch Affiliate-Netzwerke und Influencer vermittelten Käufe abgezogen wird (Objekt).
Währung. Währungscode, bestehend aus drei Buchstaben gemäß ISO 4217.
Angaben zur MwSt. (Objekt, nur in der EU).
Währung. Währungscode, bestehend aus drei Buchstaben gemäß ISO 4217.
Betrag, der vom Xsolla-Konto abgebucht wird.
Währung. Währungscode, bestehend aus drei Buchstaben gemäß ISO 4217.
Xsolla-Gebühr (Objekt).
Währung. Währungscode, bestehend aus drei Buchstaben gemäß ISO 4217.
Objekt, welches Angaben zum Kauf enthält.
Angaben zum Gutschein (Objekt; falls ein Gutschein bei Abschluss des Abonnements genutzt wurde).
Benutzerdaten (Objekt).
Legt fest, ob die Identität des Spenders vor dem Beschenkten geheim gehalten werden soll.
Werbeaktionen, die bei dieser Transaktion Verwendung finden.
Angaben zum Abonnement (Objekt).
Währung. Währungscode, bestehend aus drei Buchstaben gemäß ISO 4217.
Datum, an dem das Abonnement abgeschlossen wurde. Datums- und Zeitangabe gemäß ISO 8601.
Nächstes Rechnungsdatum. Datums- und Zeitangabe gemäß ISO 8601.
ID des Abo-Modells (extern, falls das Abo-Modell über die API angelegt wurde).
Produkt-ID (falls sie im Zugriffstoken versendet wurde).
In der Xsolla-Datenbank erfasste Abonnement-ID.
Gesamtpreis des Einkaufs (Objekt).
Währung. Währungscode, bestehend aus drei Buchstaben gemäß ISO 4217.
Benutzerdefinierte Projekteinstellungen (Objekt).
Projekt-ID. Dieser Parameter wird im Kundenportal neben dem Projektnamen angezeigt.
Details zur Transaktion (Objekt).
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.
Externe Transaktions-ID. Ausführliche Informationen finden Sie in den FAQs.
Liste der vom Nutzer gekauften Artikel.
Die im Array enthaltenen Parameter hängen von der Webhook-Version ab. In Version 2 sind zusätzliche Parameter enthalten: is_free, is_bonus und is_bundle_content. Geben Sie die entsprechende Nummer im Parameter version im API-Aufruf Informationen zu Webhook-Einstellungen aktualisieren an, um die Version zu wechseln.
One of:
Angewandte Werbeaktionen für bestimmte Artikel in der Bestellung. Das Array wird in den folgenden Fällen zurückgegeben:
- Eine Rabattaktion ist für einen bestimmten Artikel konfiguriert.
- Ein Promocode mit der Einstellung Rabatt auf ausgewählte Artikel wird angewendet.
Werden keine Werbeaktionen auf Artikelebene angewandt, wird ein leeres Array zurückgegeben.
Eindeutige ID des Artikels. Bei Artikeln vom Typ game_key wird ein Wert im Format sku_drm verwendet.
Artikeltyp. Für Artikel vom Typ bundle, einschließlich virtueller Währungspakete, zeigt das Array items Folgendes an:
- Parameter des Bundles oder des virtuellen Währungspakets
- Im Bundle enthaltene Artikel oder im Paket enthaltene Währungen
Der Typ value_point wird bei Vorgängen mit Treuepunkten verwendet, d. h., wenn Punkte ausgegeben oder gutgeschrieben werden.
Enum"virtual_good""virtual_currency""game_key""bundle""value_point"
Bestellinformationen.
Die Gesamtkosten eines Warenkorbs basierend auf der gewählten Währung.
Angewandte Gutscheine. Wird der Gutschein nicht angewendet, wird kein Array zurückgegeben.
Währung der Bestellung. Bei virtuellen Währungen wird die SKU und bei echten Währungen der aus drei Buchstaben bestehende Code gemäß ISO 4217 genutzt.
Zahlungswährungstyp. Bei einer kostenlosen Bestellung ist unknown als Wert angegeben.
| Enum Wert | Beschreibung |
|---|---|
| loyalty_point | Treuepunkte |
| real | echte Währung |
| unknown | kostenlose Bestellung |
| virtual | virtuelle Währung |
Rechnungs-ID bei Zahlungen mit echter Währung. Bei Zahlungen mit virtueller Währung oder bei kostenlosen Artikeln wird der Wert null genutzt.
Zahlungsmodus. default wird bei realen Zahlungen verwendet; sandbox bei Testzahlungen.
Enum"default""sandbox"
Zahlungsplattform. Bei über Xsolla abgewickelten Zahlungen wird der Wert xsolla verwendet. Bei anderen Zahlungen wird als Wert der Name der entsprechenden Publishing-Plattform verwendet.
Enum"xsolla""playstation_network""xbox_live""pc_standalone""nintendo_shop""google_play""app_store_ios""android_standalone""ios_standalone""android_other"
Angewandte Promocodes. Wird der Promocode nicht angewandt, wird kein Array zurückgegeben.
Angewandte Werbeaktionen für die gesamte Bestellung. Das Array wird in den folgenden Fällen zurückgegeben:
- Eine Werbeaktion wirkt sich auf den Gesamtkaufbetrag aus, z. B. ein Aktionscode mit der Einstellung Rabatt auf Kauf.
- Es wird kein Rabatt auf den Kauf angewandt, aber es werden Bonusartikel der Bestellung hinzugefügt. In diesem Fall werden die Werte für den Preis mit (amount_with_discount) und ohne Rabatt (amount_without_discount) zurückgegeben, wobei beide Werte identisch sind, da kein Rabatt angewandt wird.
Werden keine Werbeaktionen auf Bestellebene angewandt, wird ein leeres Array zurückgegeben.
Benutzerinformationen.
Land des Benutzers. Ländercode, bestehend aus 2 Großbuchstaben gemäß ISO 3166-1 ALPHA-2.
- https://api.xsolla.com/merchant/v2/successful-order-payment
- Mock serverhttps://xsolla.redocly.app/_mock/de/webhooks/successful-order-payment
- CURL
- Payload
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": "order_paid",
"items": [
{
"sku": "com.xsolla.item_1",
"type": "virtual_good",
"is_pre_order": false,
"quantity": 3,
"amount": "1000",
"promotions": [
{
"amount_without_discount": "6000",
"amount_with_discount": "5000",
"sequence": 1
},
{
"amount_without_discount": "5000",
"amount_with_discount": "4000",
"sequence": 2
}
],
"custom_attributes":
{
"purchased": 0,
"attr": "value"
}
},
{
"sku": "com.xsolla.item_new_1",
"type": "bundle",
"is_pre_order": false,
"quantity": 1,
"amount": "1000",
"promotions": []
},
{
"sku": "com.xsolla.gold_1",
"type": "virtual_currency",
"is_pre_order": false,
"quantity": 1500,
"amount": null,
"promotions": []
}
],
"order": {
"id": 1,
"mode": "default",
"currency_type": "virtual",
"currency": "sku_currency",
"amount": "2000",
"status": "paid",
"platform": "xsolla",
"comment": null,
"invoice_id": "1",
"promotions": [
{
"amount_without_discount": "4000",
"amount_with_discount": "2000",
"sequence": 1
}
],
"promocodes": [
{
"code": "promocode_some_code",
"external_id": "promocode_sku"
}
],
"coupons": [
{
"code": "WINTER2021",
"external_id": "coupon_sku"
}
]
},
"user": {
"external_id": "id_xsolla_login_1",
"email": "gc_user@xsolla.com",
"country": "US"
},
"billing": {
"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
},
"total": {
"currency": "USD",
"amount": 200
},
"promotions": [{
"technical_name": "Demo Promotion",
"id": 853
}],
"coupon": {
"coupon_code": "ICvj45S4FUOyy",
"campaign_code": "1507"
}
},
"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"
}
}