Schnellstart

Integrationsablauf

So integrieren Sie die Payments-Lösung:

Erstellen Sie ein Projekt im Kundenportal. Ein Projekt entspricht hierbei einem Spiel. Wenn Sie mehrere Spiele haben, müssen Sie für jedes ein Projekt erstellen.
Ergänzen Sie den Katalog aufseiten von Xsolla um Artikel, die Sie verkaufen möchten.
Legen Sie eine Bestellung testweise an.
Testen Sie den Bezahlvorgang, und richten Sie Benachrichtigungen ein.
Unterzeichnen Sie die Xsolla-Lizenzvereinbarung im Kundenportal, um echte Zahlungen abwickeln zu können.

Sie können die Lizenzvereinbarung jederzeit unterzeichnen. Denken Sie jedoch daran, dass die Prüfung bis zu drei Werktage dauern kann.

Katalog erstellen

Virtuelle Gegenstände sind Ingame-Inhalte, die ein Nutzer gegen reale und virtuelle Währung kaufen kann. Wenn Sie aufseiten von Xsolla einen Katalog für virtuelle Gegenstände erstellen, können Sie länderspezifische Preise und Beschränkungen festlegen sowie Xsollas System für Werbeaktionen und andere Funktionen nutzen, die regelmäßig erweitert und überarbeitet werden.

Virtuelle Gegenstände erstellen

Artikelliste abrufen

Rufen Sie die API-Methode Liste virtueller Gegenstände abrufen auf, um die Liste der virtuellen Gegenstände abzurufen:

Übermitteln Sie im Anfrage-Header den standardmäßig für die Autorisierung verwendeten Xsolla-Login-JWT (Bearer-Token). Mithilfe des folgenden Tokens können Sie die API-Methode testweise aufrufen: Bearer eyJ0eXAiOiJKV1QiLCJhbGciOiJIUzI1NiJ9.eyJleHAiOjE5NjIyMzQwNDgsImlzcyI6Imh0dHBzOi8vbG9naW4ueHNvbGxhLmNvbSIsImlhdCI6MTU2MjE0NzY0OCwidXNlcm5hbWUiOiJ4c29sbGEiLCJ4c29sbGFfbG9naW5fYWNjZXNzX2tleSI6IjA2SWF2ZHpDeEVHbm5aMTlpLUc5TmMxVWFfTWFZOXhTR3ZEVEY4OFE3RnMiLCJzdWIiOiJkMzQyZGFkMi05ZDU5LTExZTktYTM4NC00MjAxMGFhODAwM2YiLCJlbWFpbCI6InN1cHBvcnRAeHNvbGxhLmNvbSIsInR5cGUiOiJ4c29sbGFfbG9naW4iLCJ4c29sbGFfbG9naW5fcHJvamVjdF9pZCI6ImU2ZGZhYWM2LTc4YTgtMTFlOS05MjQ0LTQyMDEwYWE4MDAwNCIsInB1Ymxpc2hlcl9pZCI6MTU5MjR9.GCrW42OguZbLZTaoixCZgAeNLGH2xCeJHxl8u8Xn2aI.
Übermitteln Sie im Pfad-Parameter project_id die Projekt-ID aus dem Kundenportal:

In der Antwort werden detaillierte Informationen über die in Ihrem Projekt erstellten virtuellen Gegenstände übermittelt. Damit Sie anschließend die Bestellung anlegen können, benötigen Sie die Artikel-SKU, die im Parameter items.sku übermittelt wird.

Bestellung anlegen

Eine Bestellung besteht aus Artikeln, die ein Benutzer im Shop kaufen möchte. Nachdem eine Bestellung bezahlt wurde, erhält der Benutzer die Artikel. Um eine Zahlung zu tätigen, muss der Benutzer im Spiel autorisiert sein.

Entscheiden Sie sich für eine Integrationsmethode, die zu Ihrem Spiel passt, um die entsprechende Einrichtungsanleitung anzuzeigen.

Merkmale	Serverseitig	Clientseitig
Server vorhanden	Sie benötigen einen eigenen Server, um Token abzurufen und die Serverauslastung zu steuern.	Sie benötigen keinen eigenen Server.
Land des Nutzers bestimmen	Sie müssen entweder das Land oder die IP-Adresse im Zahlungstoken übermitteln. Das beeinflusst die zur Auswahl stehenden Zahlungsmethoden.	Xsolla ermittelt das Land des Nutzers anhand der IP-Adresse.
Zahlungswährung bestimmen	Wenn Sie keine Währung im Token übermitteln, wird die Währung anhand des Landes des Benutzers ermittelt. Wenn Sie die Währung im Token übermitteln, zahlt der Benutzer in dieser Währung.	Das Land bestimmt die Währung.

Rufen Sie die API-Methode Zahlungstoken für den Kauf erstellen auf, und übermitteln Sie darin Informationen über den Nutzer und die Artikel. Dieser API-Aufruf eignet sich dazu, sowohl einen Artikel als auch mehrere zu verkaufen.

Übermitteln Sie den Parameter “sandbox”: true im Rumpf der Token-abrufen-Anfrage, um in die Testumgebung zu wechseln.

Der Wert des Parameters user_id:

Zu Testzwecken können Sie ein beliebiges Symbol in diesem Parameter übermitteln.
Um echte Zahlungen entgegenzunehmen, müssen Sie die Benutzer-ID aus Ihrem System in diesem Parameter übermitteln. Die ID wird im Webhook Benutzervalidierung übermittelt.

Anfragebeispiel:

Copy

Full screen

Small screen

curl -i -X POST \
  -u 224575:MYAPIKEY \
  https://store.xsolla.com/api/v2/project/224575/admin/payment/token \
  -H 'Content-Type: application/json' \
  -d '{
    "user": {
      "id": {
        "value": "myUserID"
      }
    },
    "purchase": {
      "items": [
        {
          "sku": "mySKU",
          "quantity": 1
        }
      ]
    },
    "sandbox": true
  }'

Integrieren Sie Xsolla Login:

Erstellen und speichern Sie mit der konfigurierten Login-Methode den Authentifizierungstoken, um einen Zahlungstoken zu erhalten. Der Zahlungstoken dient dazu, das Zahlungsportal zu öffnen und die Zahlung abzuwickeln.

Legen Sie eine Bestellung mithilfe des API-Aufrufs Bestellung mit dem angegebenen Artikel erstellen an, um den Zahlungsvorgang zu testen:

Wenn Sie einen Test auf der API-Dokumentationswebsite durchführen möchten, klicken Sie auf Try it, um die Oberfläche zum Erstellen einer Anfrage zu öffnen.
Geben Sie im Block Security in das Feld Bearer Token den Token ein, den Sie während des Authentifizierungsverfahrens erhalten haben.
Geben Sie im Block Body die Bestelldetails ein, z. B. die Artikelmenge. Um die Testumgebung zu nutzen, übermitteln Sie "sandbox": true.
Geben Sie im Block Parameters Folgendes an:
- project_id – Projekt-ID aus dem Kundenportal.
- item_sku – Artikel-SKU.

Die Antwort enthält Daten, die Sie für die weitere Arbeit benötigen:

token – Zahlungstoken

Anfragebeispiel:

Copy

Full screen

Small screen

curl -i -X POST \
  'https://store.xsolla.com/api/v2/project/{project_id}/payment/item/{item_sku}' \
  -H 'Authorization: Bearer <YOUR_JWT_HERE>' \
  -H 'Content-Type: application/json' \
  -d '{
    "sandbox": true,
    "quantity": 5,
    "settings": {
      "ui": {
        "theme": "63295a9a2e47fab76f7708e1",
      }
    },
    "custom_parameters": {
      "character_id": "ingameUsername"
    }
  }'

Um die Xsolla-API aufzurufen, können Sie die vorgefertigten SDK-Methoden für Spiel-Engines und Plattformen verwenden:

Testkauf durchführen

Beim Testen wird kein Geld von einem echten Bankkonto abgebucht, Sie nutzen stattdessen unsere Testkarten.

Solange Sie keinen Vertrag mit Xsolla geschlossen haben, können Sie den Zahlungsvorgang nur in der Testumgebung testen.

Zahlungsportal in der Testumgebung öffnen

Um die Benutzeroberfläche in einem neuen Fenster zu öffnen, nutzen Sie die folgende URL: https://sandbox-secure.xsolla.com/paystation4/?token=TOKEN, wobei TOKEN der beim Anlegen einer Bestellung erhaltene Token ist.

Wie Sie das Zahlungsportal anderweitig öffnen können, erfahren Sie in der Dokumentation.

Testzahlung durchführen

Rufen Sie das Zahlungsportal in der Testumgebung auf.
Wählen Sie Bankkarte als Zahlungsmethode.
Geben Sie die Bankkartendaten ein. In die anderen Felder (z. B. Name oder Adresse) können Sie beliebige Daten eingeben. Sie können auch falsche Angaben (Kartennummer oder Ablaufdatum) machen, um zu testen, ob ein Fehler generiert wird.
Klicken Sie auf Zahlen.

Liste der Testkarten

Sehen Sie sich die komplette Liste der verfügbaren Testbankkarten an.

Informationen zu Postleitzahlen

Neben den Kartendaten müssen Sie zusätzlich die Postleitzahl angeben, wenn mindestens eine der folgenden Bedingungen erfüllt ist:

Der Benutzer ist in den USA oder in Kanada wohnhaft.
Anhand der Bank Identification Number (BIN) ist ersichtlich, dass die Karte in den USA ausgestellt wurde.

Sie können eine beliebige gültige Postleitzahl angeben (z. B. 12345), diese bestimmt die Höhe der Sales Tax und hat keinen Einfluss auf den Verlauf der Testzahlung.
In der Testumgebung lassen sich Bankkartenzahlungen in den folgenden Währungen tätigen: USD, EUR, RUB, GBP, AED, ALL, AMD, ARS, AUD, AZN, BGN, BRL, BYN, CAD, CHF, CLP, CNY, COP, CZK, DKK, DZD, EGP, GEL, HKD, HRK, HUF, IDR, ILS, INR, ISK, JPY, KES, KGS, KRW, KZT, MAD, MDL, MKD, MNT, MXN, MYR, NGN, PEN, PHP, PKR, PLN, RON, RSD, SAR, SEK, SGD, THB, TRY, TWD, UAH, UYU, UZS, VEF, VND, ZAR.

In der Testumgebung können Sie mittels Bankkarten und PayPal Einmalzahlungen sowie Zahlungen mit gespeicherten Zahlungsmethoden testen.

Webhooks einrichten

Erfolgte die Integration serverseitig, müssen Sie die angelegten Bestellungen validieren, indem Sie den entsprechenden Code als Antwort auf die Webhooks senden. Erfolgte die Integration aufseiten des Clients, können Sie mithilfe von Webhooks Benachrichtigungen über konfigurierte Ereignisse (z. B. Änderung des Zahlungsstatus) erhalten.

So aktivieren Sie den Empfang von Webhooks:

Öffnen Sie Ihr Projekt im Kundenportal.
Klicken Sie in der Seitenleiste auf Projekteinstellungen, und wechseln Sie zur Registerkarte Webhooks.
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.
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.
Klicken Sie auf Webhooks aktivieren.

PHP-SDK

Verwenden Sie fertige Klassen für die Verarbeitung von Webhooks.

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

Um Benachrichtigungen über Benutzervalidierungen und erfolgreiche Zahlungen zu erhalten, konfigurieren Sie die folgenden Webhooks:

Benutzervalidierung – Benachrichtigung darüber, ob der Nutzer im Spiel registriert ist.
Zahlung – Benachrichtigung über getätigte Zahlung.

Ausführliche Informationen zum Einrichten und Testen von Webhooks finden Sie in der Dokumentation.

Webhook-Listener konfigurieren

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.

Informationen über die Generierung der Signatur und das Senden von Antworten an den Webhook

Signatur generieren

Beim Empfang eines Webhooks ist die Sicherheit der Datenübermittlung zu gewährleisten. Dazu muss aus den Webhook-Daten eine Signatur generiert und danach überprüft werden, ob sie mit der im HTTP-Anfrage-Header gesendeten Signatur übereinstimmt. So generieren Sie eine Signatur:

Verketten Sie das JSON aus dem Anfragerumpf mit dem geheimen Schlüssel des Projekts.
Wenden Sie die kryptografische Hash-Algorithmus SHA-1 auf den im ersten Schritt erhaltenen String an.

Dem Webhook antworten

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

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

Ihr Webhook-Handler kann ebenso mit einem HTTP-Statuscode 5xx antworten, falls Ihr Server vorübergehend Probleme hat. Erfolgt keine Antwort auf die Webhooks Bestellung erfolgreich bezahlt und Bestellung storniert oder wurde eine Antwort mit dem Code 5xx empfangen, werden die Webhooks nach folgendem 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. Erfolgt keine Antwort auf den Webhook Zahlung oder wurde eine Antwort mit dem Code 5xx empfangen, werden die Webhooks in längeren Zeitabständen erneut gesendet. Innerhalb von 12 Stunden werden maximal 12 Versuche unternommen. Erfolgt keine Antwort auf den Webhook Benutzervalidierung oder wurde eine Antwort mit dem Code 400 oder 5xx empfangen, wird der Webhook Benutzervalidierung nicht erneut gesendet. In diesem Fall wird dem Benutzer ein Fehler angezeigt und die Webhooks Zahlung und Bestellung erfolgreich bezahlt werden nicht gesendet.

Launch

Solange Sie die Lizenzvereinbarung nicht unterzeichnet haben, können Sie das Zahlungsportal nur in der Testumgebung öffnen.

Lizenzvereinbarung unterschreiben

Wenn Sie die Lizenzvereinbarung unterzeichnen, können Sie echte Zahlungen über alle von Xsolla unterstützten Zahlungsmethoden entgegennehmen. So unterzeichnen Sie die Lizenzvereinbarung:

Öffnen Sie das Kundenportal.
Navigieren Sie über die Seitenleiste zu Vereinbarungen und Steuern > Vereinbarungen.
Klicken Sie auf der Registerkarte Lizenzvereinbarung auf Antragsformular ausfüllen.
Geben Sie die Informationen in die entsprechenden Felder ein.

Ihr Antrag wird innerhalb von drei Geschäftstagen geprüft. Sollten während des Prüfverfahrens Fragen auftauchen, wird Xsolla den im Antrag angegebenen Ansprechpartner kontaktieren. Nachdem Xsolla das Prüfverfahren abgeschlossen hat, ändert sich der Vereinbarungsstatus in Unterschrieben.

In die Produktionsumgebung wechseln

Nachdem die erste echte Zahlung erfolgt ist, tritt eine strenge Sandbox-Zahlungsrichtlinie in Kraft. Nur Benutzer, die im Kundenportal unter Firmeneinstellungen > Nutzer aufgeführt sind, können Zahlungen in der Testumgebung vornehmen.

Nachdem Sie die vorangegangenen Schritte durchgeführt haben, können Sie echte Zahlungen entgegennehmen:

Stellen Sie sicher, dass Sie die Xsolla-Lizenzvereinbarung unterzeichnet haben.
Entfernen Sie den Parameter “sandbox”: true aus dem Anfragerumpf, wenn Sie einen Token abrufen.
Öffnen Sie das Zahlungsportal über den folgenden Link: https://secure.xsolla.com/paystation4/?token=TOKEN.

Dieser Leitfaden beschreibt die Mindesteinstellungen, die für den Schnellstart der Integration erforderlich sind. Falls Sie Fragen haben, kontaktieren Sie uns über den Xsolla Chat in der unteren rechten Ecke der Seite oder senden Sie eine E-Mail an einen Customer Success Manager unter csm@xsolla.com.

Vielen Dank für Ihr Feedback!

Wir werden Ihr Feedback aufgreifen und dazu nutzen, Ihr Erlebnis verbessern.

Diese Seite bewerten

Jetzt nicht

Vielen Dank für Ihr Feedback!

Letztmalig aktualisiert: 18. März 2024

Haben Sie einen Tippfehler oder einen anderen Textfehler gefunden? Wählen Sie den Text aus und drücken Sie Strg+Eingabe.

Your browser is not supported. Please try a different browser

Payments

Schnellstart

Integrationsablauf

Katalog erstellen

Virtuelle Gegenstände erstellen

Artikelliste abrufen

Bestellung anlegen

Testkauf durchführen

Zahlungsportal in der Testumgebung öffnen

Testzahlung durchführen

Webhooks einrichten

Webhook-Listener konfigurieren

Signatur generieren

Dem Webhook antworten

Launch

Lizenzvereinbarung unterschreiben

In die Produktionsumgebung wechseln

War dieser Artikel hilfreich?

Diese Seite bewerten

Vielen Dank für Ihr Feedback!