Zahlungslösung integrieren
Damit Sie Referrals tracken und Auszahlungen an Kooperationspartner vornehmen können, müssen Sie zuerst die Xsolla-Bezahlstation integrieren. Anforderungen:
- Die Bezahlstation ist auf einer leistungsoptimierten Landing-Page integriert.
- Die Bezahlstation ist die einzige Zahlungsmethode auf der Landing-Page, die den Traffic durch das Partnernetzwerk-Prorgramms leitet.
Token abrufen
Zum Öffnen des Zahlungsportals benötigen Sie einen Token. Ein Token ist ein String, der verschlüsselte Daten über ein Spiel und einen Benutzer enthält. Sie müssen den Abruf eines Tokens implementieren, um den Benutzer zu identifizieren und den Kauf zu ermöglichen.
Implementieren Sie im Backend Ihrer Anwendung den Abruf eines Benutzerauthentifizierungstokens. Nutzen Sie dafür eine HTTP-POST-Anfrage mit HTTP-Basisauthentifizierung, und übermitteln Sie die erforderlichen Parameter im Anfragerumpf.
Der Token verfällt 14 Stunden nach dem letzten Aufruf der Xsolla-API. Implementieren Sie die Logik für den Erhalt eines neuen Tokens nach dessen Verfall. Es wird empfohlen, einen neuen Token im Hintergrund abzurufen, damit sich der Benutzer nicht erneut bei der Anwendung anmelden muss.
HTTP-Basisauthentifizierung
Die Xsolla-API nutzt die Basisauthentifizierung. Alle Anfragen an die API müssen den Header Authorization: Basic <your_authorization_basic_key>
enthalten, wobei <your_authorization_basic_key>
das gemäß dem Base64-Standard kodierte Paar Händler-ID:API-Schlüssel ist. Die Parameter finden Sie im Kundenportal:
- Die Händler-ID finden Sie:
- unter Projekteinstellungen > Webhooks.
- unter Firmeneinstellungen > Firma.
- in der URL in der Adresszeile des Browsers auf einer beliebigen Seite im Kundenportal. Die URL weist das folgende Format auf:
https://publisher.xsolla.com/Händler-ID/Kundeportalabschnitt
.
- Der API-Schlüssel wird im Kundenportal nur einmal angezeigt, nämlich dann, wenn er erstellt wird. Sie sind selbst dafür verantwortlich, den Schlüssel zu speichern. Einen neuen Schlüssel können Sie in den folgenden Abschnitten erstellen:
- Firmeneinstellungen > API-Schlüssel
- Projekteinstellungen > API-Schlüssel
Weitere Informationen über die Arbeit mit API-Schlüsseln finden Sie in der API-Referenz.
Wichtige Empfehlungen:
- Sie sind selbst dafür verantwortlich, den generierten API-Schlüssel zu speichern. Der API-Schlüssel wird im Kundenportal nur einmal angezeigt, nämlich dann, wenn er erstellt wird.
- Halten Sie Ihren API-Schlüssel geheim. Er gewährt den Zugang zu Ihrem persönlichen Konto und Ihren Projekten im Kundenportal.
- Der API-Schlüssel muss auf Ihrem Server gespeichert sein, niemals in Binärdateien oder im Frontend.
Anfragerumpf
Übermitteln Sie im Anfragerumpf die folgenden erforderlichen Parameter:
Parameter | Typ | Beschreibung |
---|---|---|
user.id | string | Eindeutige Benutzer-ID in Ihrem System. |
user.email | string | E-Mail-Adresse des Benutzers, an die Quittungen gesendet werden sollen. Wird der Parameter nicht übermittelt, erscheint auf der Zahlungsseite ein Pflichtfeld zur Eingabe einer E-Mail-Adresse. |
settings.project_id | integer | Xsolla-ID des Spiels. Diese finden Sie im Abschnitt Projekt im Kundenportal. |
Um das Benutzererlebnis weiter zu verbessern, können Sie auch die folgenden Parameter übermitteln:
Parameter | Typ | Beschreibung |
---|---|---|
user.name | string | Benutzeranzeigename auf den Quittungen. |
settings.currency | string | Bevorzugte Zahlungswährung. |
settings.language | string | Sprache der Benutzeroberfläche. |
Beispiel: Anfrage eines Benutzerauthentifizierungstokens
curl -i -X POST \
-u 2340:ZHgbSDVP6LtAJVWu \
https://api.xsolla.com/merchant/v2/merchants/<merchant_id>/token \
-H 'Content-Type: application/json' \
-d '{
"settings": {
"currency": "USD",
"language": "en",
"project_id": <project_id>,
"ui": {
"size": "medium"
}
},
"user": {
"email": {
"value": "<user_email>"
},
"id": {
"value": "<user_id>"
},
"name": {
"value": "<user_name>"
}
}
}'
Beispiel: Antwort mit Benutzerauthentifizierungstoken
{
"token": "1230OWrp0KF6uqvmN8jWuzLyoXMzxTyK_lc_en"
}
Zahlungsportal öffnen
Solange Sie keinen Vertrag mit Xsolla geschlossen haben, können Sie den Zahlungsvorgang nur im Sandbox-Modus testen. Falls Fehler auftreten, finden Sie hier deren Erläuterung.
Nutzen Sie folgende URL, um das Zahlungsportal in der Testumgebung aufzurufen: https://sandbox-secure.xsolla.com/paystation4/?access_token=ACCESS_TOKEN
; wobei ACCESS_TOKEN
der Token ist, der im vorherigen Schritt bezogen wurde.
Neues Fenster
Um die Benutzeroberfläche in einem neuen Fenster zu öffnen, nutzen Sie die folgende URL: https://sandbox-secure.xsolla.com/paystation4/?access_token=TOKEN
, wobei TOKEN
der erhaltene Token ist.
https://secure.xsolla.com/paystation4/?access_token=TOKEN
.Das Zahlungsportal lässt sich auch auf andere Wege öffnen:
- Mit Pay Station Embed. Einschränkung: beim Öffnen im Ingame-Browser (WebView) kann es zu Problemen kommen.
- in einem iframe. Einschränkung: beim Öffnen im Ingame-Browser (WebView) und in Ihrer mobilen App kann es zu Problemen kommen.
Pay Station Embed
BEISPIEL: ASYNCHRONES LADEN VON SCRIPTEN
- html
<script>
var options = {
access_token: 'ACCESS_TOKEN', //TODO use access token, received on previous step
sandbox: true //TODO please do not forget to remove this setting when going live
};
var s = document.createElement('script');
s.type = "text/javascript";
s.async = true;
s.src = "https://static.xsolla.com/embed/paystation/1.0.7/widget.min.js";
s.addEventListener('load', function (e) {
XPayStationWidget.init(options);
}, false);
var head = document.getElementsByTagName('head')[0];
head.appendChild(s);
</script>
<button data-xpaystation-widget-open>Buy Credits</button>
Pay Station Embed ermöglicht das Abrufen von Ereignissen aus dem Zahlungsportal via postMessage
. Diese Ereignisse können an Analytics-Systeme übermittelt werden. Wenden Sie sich zum Einrichten der Ereignisverarbeitung in Ihrem Analytics-System an Ihren Account Manager oder senden Sie eine E-Mail an am@xsolla.com.
Das Xsolla-Team hat ein Widget entwickelt, mit dem Sie das Zahlungsportal ganz einfach in Ihre Website integrieren können. Das Widget-Skript ist in unserem GitHub-Repository verfügbar.
Script-Initialisierungsparameter:
Parameter | Typ | Beschreibung |
---|---|---|
access_token | string | Token; wird über die API empfangen. Erforderlich. |
sandbox | boolean | Stellen Sie den Wert des Parameters auf true , um den Zahlungsvorgang auszutesten: Anstelle von sandbox-secure.xsolla.com wird secure.xsolla.com verwendet. |
lightbox | object | Lightbox-Parameter (Objekt; nur für die Desktop-Version). |
lightbox.width | string | Rahmenhöhe der Lightbox. Falls als Wert null festgelegt ist, wird die Höhe der Bezahlstation verwendet. Standardwert ist null . |
lightbox.height | string | Rahmenhöhe der Lightbox. Falls als Wert null festgelegt ist, wird die Höhe der Bezahlstation verwendet. Standardwert ist 100% . |
lightbox.zIndex | integer | Definiert die Stapelanordnung. Standardwert ist 1000 . |
lightbox.overlayOpacity | integer | Deckkraft der Einblendung (0 bis 1). Standardwert ist .6 . |
lightbox.overlayBackground | string | Hintergrundfarbe der Einblendung. Standardwert ist #000000 . |
lightbox.modal | boolean | Falls true festgelegt ist, kann der Lightbox-Rahmen nicht geschlossen werden. Standardwert ist false . |
lightbox.closeByClick | boolean | Falls true festgelegt ist, wird die Lightbox durch Klick auf die Einblendung geschlossen. Standardwert ist true . |
lightbox.closeByKeyboard | boolean | Falls true festgelegt ist, wird die Lightbox durch Drücken der Escape-Taste geschlossen. Standardwert ist true . |
lightbox.contentBackground | string | Hintergrundfarbe des Rahmens. Standardwert ist #ffffff . Beachten Sie, dass diese Farbänderungen keinen Einfluss auf den iframe der Bezahlstation selbst haben, sondern nur auf die Einstellungen der Lightbox, in dem der iframe angezeigt wird. |
lightbox.contentMargin | string | Breite des Rahmens. Standardwert ist 10px . |
lightbox.spinner | string | Art der animierten Ladeanzeige. Als Wert lässt sich entweder xsolla oder round festlegen. Standardwert ist xsolla . |
lightbox.spinnerColor | string | Farbe des Ladekreises. Kein Wert voreingestellt. |
childWindow | object | Optionen für das untergeordnete Fenster, welches die Benutzeroberfläche der Bezahlstation enthält. Wird in der mobilen Version unterstützt. |
childWindow.target | string | Stelle, an welcher das Bezahlstation-Fenster geöffnet werden soll. Als Wert lässt sich entweder _blank , _self , _parent festlegen. Standardwert ist _blank . |
Das Script ermöglicht Ihnen, die Ereignisse im Zahlungsportal zu verfolgen. Je nach Art des Ereignisses können Sie verschiedene Aktionen auf der Website ausführen.
Liste der Ereignisse:
Parameter | Beschreibung |
---|---|
init | Widget initialisiert. |
open | Widget geöffnet. |
load | Zahlungsportal (Bezahlstation) geladen. |
close | Zahlungsportal (Bezahlstation) geschlossen. |
status | Benutzer befindet sich auf der Statusseite. |
status-invoice | Benutzer befindet sich auf der Statusseite; Zahlung im Gange. |
status-delivering | Benutzer befindet sich auf der Statusseite; Zahlung abgeschlossen; Zahlungsbestätigung wurde versendet. |
status-done | Benutzer befindet sich auf der Statusseite, Zahlung wurde dem Benutzerkonto gutgeschrieben. |
status-troubled | Benutzer befindet sich auf der Statusseite; Zahlung fehlgeschlagen. |
Wenn Sie den Ladevorgang für das Zahlungsportal initialisieren möchten, verwenden Sie den folgenden Link: https://secure.xsolla.com/paystation4/?access_token=TOKEN
.
Für Testzwecke steht Ihnen die folgende URL zur Verfügung: https://sandbox-secure.xsolla.com/paystation4/?access_token=TOKEN
.
access_token
enthält personenbezogene Nutzerdaten. Stellen Sie sicher, dass Sie Server-zu-Server-Kommunikation einsetzen, wenn Sie diesen Parameter abrufen.Iframe
So öffnen Sie das Testumgebung in einem iframe:
- Implementieren Sie den
postMessage
-Mechanismus, um Zahlungsportal-Ereignisse empfangen zu können. - Öffnen Sie das Zahlungsportal über den folgenden Link:
https://sandbox-secure.xsolla.com/paystation4/?access_token=TOKEN
, wobeiTOKEN
der erhaltene Token ist.
Webhooks einrichten
Wenn Sie über Ereignisse (z. B. Änderung des Zahlungsstatus) benachrichtigt werden möchten, müssen Sie Webhooks im Kundenportal einrichten:
- Öffnen Sie Ihr Projekt im Kundenportal.
- Klicken Sie in der Seitenleiste auf Projekteinstellungen, und wechseln Sie zur Registerkarte Webhooks.
- Stellen Sie den Schalter Webhooks auf Ein.
- Geben Sie die Webhook-URL an.
- Daraufhin wird standardmäßig ein geheimer Schlüssel zum Signieren der Projekt-Webhooks generiert. Wenn Sie einen neuen geheimen Schlüssel generieren möchten, klicken Sie auf das Aktualisieren-Symbol.
- Klicken Sie auf Einstellungen speichern.
Es wird empfohlen, die folgenden Webhooks zu implementieren:
Um den Empfang des Webhooks zu bestätigen, muss Ihr Server wie folgt antworten:
- HTTP-Statuscode 204 ohne Nachrichtenrumpf.
- HTTP-Statuscode 400 samt Problembeschreibung, sofern der angegebene Benutzer nicht gefunden oder eine ungültige Signatur übermittelt wurde.
Zahlungsvorgang testen
Um den Zahlungsprozess auszuprobieren, können Sie den Sandbox-Modus verwenden. Die Sandbox ist eine eigenständige Testumgebung, welche alle Funktionen der Live-Umgebung, mit Ausnahme echter und abgelehnter Zahlungen, unterstützt. Sie können auf die Testumgebung zugreifen, indem Sie "mode":"sandbox"
beim Abrufen des Tokens senden.
In der Testumgebung können Sie den Zahlungsvorgang wie folgt testen:
Bankkartenzahlung testen
- Rufen Sie das Zahlungsportal in der Testumgebung auf.
- Wählen Sie unter Zahlungsarten die Gruppe Kredit-/Debitkarten aus.
- Geben Sie die Bankkartendaten ein. Geben Sie alle Werte in die verbleibenden Felder ein. Sie können auch falsche Angaben (Kartennummer oder Ablaufdatum) machen, um einen Fehler zu generieren.
- Klicken Sie auf Jetzt zahlen.
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.
PayPal-Zahlung testen
PayPal-Testkonto erstellen
Sie müssen ein Konto im PayPal-Sandboxmodus erstellen, um den Zahlungsvorgang zu testen:
- Öffnen Sie die PayPal Developer-Website.
- Melden Sie sich bei Ihrem Konto an oder erstellen Sie ein neues.
- Wechseln Sie zur Registerkarte
Sandbox accounts . - Klicken Sie auf der Seite
Sandbox test accounts aufCreate account . - Wählen Sie
Personal (Buyer Account) als Kontotyp aus, und wählen Sie ein Land. - Klicken Sie auf
Create .
Das erstellte Konto wird in der Liste der Sandbox Accounts angezeigt.
Ebenso können Sie die Informationen von bestehenden Sandbox Accounts verwenden:
sb-xmxij16980134@business.example.com | oi9_m_KW |
sb-p7pju16979920@business.example.com | 7%%p8ioS |
Testzahlung durchführen
- Öffnen Sie das Zahlungsportal in der Testumgebung.
- Wählen Sie PayPal als Zahlungsmethode aus.
- Geben Sie im Feld
Mock Response Code den Wert0
ein oder lassen Sie das Feld leer. - Geben Sie im Feld Postleitzahl fünf beliebige Ziffern ein.

- Klicken Sie auf Zahlen. Daraufhin werden Sie zu einem Fenster weitergeleitet, melden Sie sich dort bei Ihrem PayPal-Konto an.
- Geben Sie Informationen zu Ihrem Sandbox Account ein:
Email ID (E-Mail-Adresse) undSystem Generated Password (Passwort). Die entsprechenden Informationen finden Sie hier:- Melden Sie sich auf der PayPal Developer-Website bei Ihrem Konto an.
- Wechseln Sie zur Registerkarte
Sandbox accounts . - Wählen Sie auf der Seite
Sandbox test accounts ein Sandbox Account. - Klicken Sie auf •••, und wählen Sie in der Drop-down-Liste den Eintrag View/Edit account. Daraufhin öffnet sich ein Modalfenster mit den entsprechenden Daten.
- Schließen Sie die Testzahlung ab.
Live schalten
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/?access_token=TOKEN
.
Haben Sie einen Tippfehler oder einen anderen Textfehler gefunden? Wählen Sie den Text aus und drücken Sie Strg+Eingabe.