Zahlungslösung integrieren

Damit Sie Referrals tracken und Auszahlungen an Kooperationspartner vornehmen können, müssen Sie zuerst die Xsolla-Bezahlstation integrieren. Anforderungen:

  1. Die Bezahlstation ist auf einer leistungsoptimierten Landing-Page integriert.
  2. 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.

API-Referenz
Sehen Sie sich die komplette Liste der Parameter an.

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

Achtung

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:

ParameterTypBeschreibung
user.id
stringEindeutige Benutzer-ID in Ihrem System.
user.email
stringE-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
integerXsolla-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:

ParameterTypBeschreibung
user.name
stringBenutzeranzeigename auf den Quittungen.
settings.currency
stringBevorzugte Zahlungswährung.
settings.language
stringSprache der Benutzeroberfläche.

Beispiel: Anfrage eines Benutzerauthentifizierungstokens

Copy
Full screen
Small screen

    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

    Copy
    Full screen
    Small screen

      {
          "token": "1230OWrp0KF6uqvmN8jWuzLyoXMzxTyK_lc_en"
      }

      Zahlungsportal öffnen

      Hinweis

      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.

      Hinweis
      Nutzen Sie den obigen Link, um das Zahlungsportal in der Testumgebung zu öffnen. Verwenden Sie nach dem Projektlaunch die folgende URL: 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

      Achtung
      Diese Art, das Zahlungsportal zu öffnen, unterstützt nicht den Verkauf von Spielschlüsseln. Befolgen Sie die Anleitung, um Spielschlüssel zu verkaufen.

      BEISPIEL: ASYNCHRONES LADEN VON SCRIPTEN

      Copy
      Full screen
      Small screen

      <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:

      ParameterTypBeschreibung
      access_token
      stringToken; wird über die API empfangen. Erforderlich.
      sandbox
      booleanStellen Sie den Wert des Parameters auf true, um den Zahlungsvorgang auszutesten: Anstelle von sandbox-secure.xsolla.com wird secure.xsolla.com verwendet.
      lightbox
      objectLightbox-Parameter (Objekt; nur für die Desktop-Version).
      lightbox.width
      stringRahmenhöhe der Lightbox. Falls als Wert null festgelegt ist, wird die Höhe der Bezahlstation verwendet. Standardwert ist null.
      lightbox.height
      stringRahmenhöhe der Lightbox. Falls als Wert null festgelegt ist, wird die Höhe der Bezahlstation verwendet. Standardwert ist 100%.
      lightbox.zIndex
      integerDefiniert die Stapelanordnung. Standardwert ist 1000.
      lightbox.overlayOpacity
      integerDeckkraft der Einblendung (0 bis 1). Standardwert ist .6.
      lightbox.overlayBackground
      stringHintergrundfarbe der Einblendung. Standardwert ist #000000.
      lightbox.modal
      booleanFalls true festgelegt ist, kann der Lightbox-Rahmen nicht geschlossen werden. Standardwert ist false.
      lightbox.closeByClick
      booleanFalls true festgelegt ist, wird die Lightbox durch Klick auf die Einblendung geschlossen. Standardwert ist true.
      lightbox.closeByKeyboard
      booleanFalls true festgelegt ist, wird die Lightbox durch Drücken der Escape-Taste geschlossen. Standardwert ist true.
      lightbox.contentBackground
      stringHintergrundfarbe 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
      stringBreite des Rahmens. Standardwert ist 10px.
      lightbox.spinner
      stringArt der animierten Ladeanzeige. Als Wert lässt sich entweder xsolla oder round festlegen. Standardwert ist xsolla.
      lightbox.spinnerColor
      stringFarbe des Ladekreises. Kein Wert voreingestellt.
      childWindow
      objectOptionen für das untergeordnete Fenster, welches die Benutzeroberfläche der Bezahlstation enthält. Wird in der mobilen Version unterstützt.
      childWindow.target
      stringStelle, 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:

      ParameterBeschreibung
      initWidget initialisiert.
      openWidget geöffnet.
      loadZahlungsportal (Bezahlstation) geladen.
      closeZahlungsportal (Bezahlstation) geschlossen.
      statusBenutzer befindet sich auf der Statusseite.
      status-invoiceBenutzer befindet sich auf der Statusseite; Zahlung im Gange.
      status-deliveringBenutzer befindet sich auf der Statusseite; Zahlung abgeschlossen; Zahlungsbestätigung wurde versendet.
      status-doneBenutzer befindet sich auf der Statusseite, Zahlung wurde dem Benutzerkonto gutgeschrieben.
      status-troubledBenutzer 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.

      Hinweis
      Beim Aufrufen des Zahlungsportals muss zwingend der Präfix https:// verwendet werden.

      Für Testzwecke steht Ihnen die folgende URL zur Verfügung: https://sandbox-secure.xsolla.com/paystation4/?access_token=TOKEN.

      Achtung
      Der Parameter 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:

      1. Implementieren Sie den postMessage-Mechanismus, um Zahlungsportal-Ereignisse empfangen zu können.
      2. Öffnen Sie das Zahlungsportal über den folgenden Link: https://sandbox-secure.xsolla.com/paystation4/?access_token=TOKEN, wobei TOKEN 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:

      1. Öffnen Sie Ihr Projekt im Kundenportal.
      2. Klicken Sie in der Seitenleiste auf Projekteinstellungen, und wechseln Sie zur Registerkarte Webhooks.
      3. Stellen Sie den Schalter Webhooks auf Ein.
      4. Geben Sie die Webhook-URL an.
      5. 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.
      6. 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.

      Hinweis
      Weitere Informationen zu Webhooks finden Sie in der API-Referenz.

      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.

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

      In der Testumgebung können Sie den Zahlungsvorgang wie folgt testen:

      Bankkartenzahlung testen

      1. Rufen Sie das Zahlungsportal in der Testumgebung auf.
      2. Wählen Sie unter Zahlungsarten die Gruppe Kredit-/Debitkarten aus.
      3. 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.
      4. Klicken Sie auf Jetzt zahlen.
      Liste der Testkarten
      Sehen Sie sich die komplette Liste der verfügbaren Testbankkarten an.
      Hinweis

      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.

      Achtung
      Lesen Sie die Beschreibung aller verfügbaren Testszenarien für Einmal-Käufe und gespeicherte Karten.

      PayPal-Zahlung testen

      PayPal-Testkonto erstellen

      Sie müssen ein Konto im PayPal-Sandboxmodus erstellen, um den Zahlungsvorgang zu testen:

      1. Öffnen Sie die PayPal Developer-Website.
      2. Melden Sie sich bei Ihrem Konto an oder erstellen Sie ein neues.
      3. Wechseln Sie zur Registerkarte Sandbox accounts.
      4. Klicken Sie auf der Seite Sandbox test accounts auf Create account.
      5. Wählen Sie Personal (Buyer Account) als Kontotyp aus, und wählen Sie ein Land.
      6. 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:

      Email IDSystem Generated Password
      sb-xmxij16980134@business.example.comoi9_m_KW
      sb-p7pju16979920@business.example.com7%%p8ioS

      Testzahlung durchführen

      1. Öffnen Sie das Zahlungsportal in der Testumgebung.
      2. Wählen Sie PayPal als Zahlungsmethode aus.
      3. Geben Sie im Feld Mock Response Code den Wert 0 ein oder lassen Sie das Feld leer.
      4. Geben Sie im Feld Postleitzahl fünf beliebige Ziffern ein.

      1. Klicken Sie auf Zahlen. Daraufhin werden Sie zu einem Fenster weitergeleitet, melden Sie sich dort bei Ihrem PayPal-Konto an.
      2. Geben Sie Informationen zu Ihrem Sandbox Account ein: Email ID (E-Mail-Adresse) und System Generated Password (Passwort). Die entsprechenden Informationen finden Sie hier:
        1. Melden Sie sich auf der PayPal Developer-Website bei Ihrem Konto an.
        2. Wechseln Sie zur Registerkarte Sandbox accounts.
        3. Wählen Sie auf der Seite Sandbox test accounts ein Sandbox Account.
        4. 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.
      3. Schließen Sie die Testzahlung ab.

      Achtung
      Lesen Sie die Beschreibung aller verfügbaren Testszenarien für Einmal-Käufe und gespeicherte PayPal-Konten.

      Live schalten

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

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

      Achtung
      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.
      Ihr Fortschritt
      Vielen Dank für Ihr Feedback!
      Letztmalig aktualisiert: 5. Juli 2021

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

      Problem melden
      Wir überprüfen unsere Inhalte ständig. Ihr Feedback hilft uns, sie zu verbessern.
      Geben Sie eine E-Mail-Adresse an, damit wir Sie erreichen können
      Vielen Dank für Ihr Feedback!