The following documentation was deprecated. Current version is available at developers.xsolla.com
Zurück

Tokenisierung

Der Begriff "Tokenisierung" bezieht sich auf eine Reihe von API-Methoden, die es Ihnen ermöglichen, Zahlungen sicher abzuwickeln, ohne das Zahlungsportal aufzurufen oder den Benutzer einzubinden. Das Modul gestattet Ihnen:

  • Die Liste der gespeicherten Zahlungskonten anzuzeigen,
  • eine Zahlung über ein gespeichertes Zahlungskonto vorzunehmen,
  • ein Zahlungskonto zu löschen.

Tokenisierung wird für folgende Zahlungsarten unterstützt:

  • Kreditkarte
  • PayPal
  • Amazon
  • Skrill
  • Yandex
  • Webmoney
  • Qiwi
  • Liqpay Privat Bank

Benutzer-Szenarien

Partner-Szenarien

Integrationsleitfaden

Der Benutzer muss die erste Zahlung über die Benutzeroberfläche der Pay Station tätigen. Sobald die Zahlung erfolgt ist, generiert die Pay Station einen Token — eine gespeicherte Zahlungskonto-ID — und verwendet ihn im Anschluss, ohne Zutun des Benutzers oder Aufrufen der Benutzeroberfläche.

Gehen Sie folgendermaßen vor, um das Modul zu integrieren:

  1. Registrieren Sie sich im Xsolla-Kundenportal.
  2. Legen Sie ein neues Projekt an.
  3. Beziehen Sie einen Token.
  4. Konfigurieren Sie, wie das Zahlungsportals aufgerufen werden soll.
  5. Konfigurieren Sie die Webhook-Verarbeitung.
  6. Testen Sie den Zahlungsvorgang aus.
  7. Veröffentlichen Sie das Modul und unterschreiben Sie die Vereinbarung.
  8. Implementieren Sie Routineabläufe im Zusammenhang mit gespeicherten Konten.

Für die Integration benötigen Sie folgende Parameter:

  • Händler-ID — wird in der URL des Kundenportals angezeigt: https://publisher.xsolla.com/{merchant_id}/.
  • API-Schlüssel — wird unter Kundenportal > Einstellungen > Unternehmen generiert.
  • Projekt-ID — wird in der URL des Kundenportals beim Betrachten der Projekteinstellungen angezeigt: https://publisher.xsolla.com/{merchant_id}/projects/{project_id}/.
  • Geheimer Schlüssel des Projekts — wird in den Projekteinstellungen generiert.

Ein Projekt anlegen

  1. Gehen Sie zu Projekte und klicken Sie auf Neues Projekt anlegen.
  2. In den Einstellungen:
    a) Definieren Sie die Webhook-URL.
    b) Generieren Sie einen geheimen Schlüssel, um Webhooks für das Projekt signieren zu können.
    c) Aktivieren Sie das "Payment Wall"-Modul.

Token für das Zahlungsportal beziehen

Für die Integration in das Zahlungsportal müssen Sie einen Token beziehen. Ein Token ist ein String, der Spiel-/Benutzerdaten und Zahlungseinstellungen enthält. Die Xsolla-API verwendet die einfache HTTP-Authentifizierung. Geben Sie Ihre Händler-ID als Benutzernamen und den API-Schlüssel als Passwort an.

Um den Sandbox-Modus zu aktivieren, legen Sie Folgendes fest: "mode" = "sandbox".

URL zum Abrufen des Tokens:

https://api.xsolla.com/merchant/merchants/{merchant_id}/token

Sie können die HTTP-POST-Anfrage ändern, indem Sie die Parameter, die Sie an das Zahlungsportal übergeben wollen, einfügen. Sowohl die Anfrage als auch die Antwort erfolgt im JSON-Format.

Im Folgenden finden Sie ein Beispiel für das Abrufen des Tokens mittels PHP und Xsollas PHP-SDK. Wenn Sie eine andere Programmiersprache verwenden, beziehen Sie sich bitte auf das CURL-basierte Beispiel (klicken Sie auf CURL).

PHP
CURL
  <?php

  use Xsolla\SDK\API\XsollaClient;
  use Xsolla\SDK\API\PaymentUI\TokenRequest;

  $tokenRequest = new TokenRequest($projectId, $userId);
  $tokenRequest->setUserEmail('email@example.com')
      ->setExternalPaymentId('12345')
      ->setSandboxMode(true)
      ->setUserName('USER_NAME')
      ->setCustomParameters(array('key1' => 'value1', 'key2' => 'value2'));

  $xsollaClient = XsollaClient::factory(array(
      'merchant_id' => MERCHANT_ID,
      'api_key' => API_KEY
  ));
  $token = $xsollaClient->createPaymentUITokenFromRequest($tokenRequest);

      curl -v https://api.xsolla.com/merchant/merchants/{merchant_id}/token \
      -X POST \
      -u your_merchant_id:merchant_api_key \
      -H 'Content-Type:application/json' \
      -H 'Accept: application/json' \
      -d '
      {
          "user": {
              "id": {
                  "value": "1234567"
              },
              "email": {
                  "value": "email@example.com"
              }
          },
          "settings": {
              "project_id": 14004,
              "mode": "sandbox"
          }
      }'

Die vollständige Liste der Parameter finden Sie in der API-Referenz.

Zahlungsportal aufrufen

Das Zahlungsportal kann folgendermaßen aufgerufen werden:

  • Mittels eingebettetem Pay-Station-Script,
  • in einem neuem Fenster oder
  • in einem iFrame.

Nutzen Sie folgende URL, um das Zahlungsportal im Sandbox-Modus aufzurufen: https://sandbox-secure.xsolla.com/

Pay Station einbetten

Das Script Pay-Station einbetten bestimmt den Gerätetyp und ruft das Zahlungsportal in einer Lightbox (bei Desktop-Bildschirmen) oder in einem neuen Fenster (bei mobilen Endgeräten) auf. Wir empfehlen Ihnen, asynchrones Laden von Scripten zu verwenden.

Beispiel für asynchrones Laden:

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

Die vollständige Liste der Parameter finden Sie in der API-Referenz.

Neues Fenster

Nutzen Sie bitte folgenden Link, um das Zahlungsportal in einem neuen Fenster aufzurufen: https://secure.xsolla.com/paystation2/?access_token=ACCESS_TOKEN; wobei ACCESS_TOKEN der Token ist, der im vorherigen Schritt bezogen wurde.

iFrame

Um das Zahlungsportal in einem iFrame aufzurufen, müssen Sie Ihrerseits folgenden Mechanismus implementieren:

  • Definieren Sie den Gerätetyp (Desktop oder mobiles Endgerät) und übermitteln Sie ihn innerhalb des Tokens im settings.ui.version-Parameter;
  • Empfang von Ereignissen aus dem Zahlungsportal via postMessage.

Nutzen Sie bitte folgenden Link, um das Zahlungsportal in einem neuen Fenster aufzurufen: https://secure.xsolla.com/paystation2/?access_token=ACCESS_TOKEN; wobei ACCESS_TOKEN der Token ist, der im vorherigen Schritt bezogen wurde.

Konfiguration von Webhooks

Xsolla sendet die folgenden Webhooks an Ihr Projekt:

  • Benutzervalidierung
  • Zahlung
  • Rückerstattung

Bestätigen Sie den Erhalt eines Webhooks, indem Sie mit dem HTTP-Statuscode 204 ohne Nachrichtenrumpf antworten. Weitere Informationen und Beispiele zur Handhabung von Webhooks finden Sie in der API-Referenz.

Eine Signatur erstellen

Um eine elektronische Signatur zu erstellen:

  1. Verknüpfen Sie die Daten aus der Anfrage des Xsolla-Servers mit dem geheimen Schlüssel des Projekts (wird in den Projekteinstellungen generiert).
  2. Wenden Sie den SHA1-Hash-Algorithmus bei den Strings an.
  3. Versenden Sie die Signatur im Signatur-Header.

Achten Sie bei der Handhabung von Webhooks darauf, dass die Signatur, welche Sie empfangen, mit jener übereinstimmt, die Sie im Signatur-Header festgelegt haben.

Benutzervalidierung

Der Xsolla-Server sendet eine Anfrage an die Webhook-URL des Projekts, um zu verifizieren, ob ein Benutzer im Spiel vorhanden ist.

Beispiel für eine Anfrage

PHP
CURL
  $request = array(
      'notification_type' => 'user_validation',
      'user' => array(
          'ip' => '127.0.0.1',
          'phone' => '18777976552',
          'email'=> 'email@example.com',
          'id'=> '1234567',
          'country' => 'US'
      )
  )

  curl -v https://example.com/ \
  -X POST \
  -H 'Content-Type:application/json' \
  -H 'Accept: application/json' \
  -H 'Authorization: Signature 13342703ccaca5064ad33ba451d800c5e823db8f' \
  -d '
  {
      "notification_type": "user_validation",
      "user": {
          "ip": "127.0.0.1",
          "phone": "18777976552",
          "email": "email@example.com",
          "id": "1234567",
          "country": "US"
      }
  }'

Die vollständige Liste der Parameter finden Sie in der API-Referenz.

Zahlung

Immer wenn ein Benutzer eine Zahlung tätigt, sendet der Xsolla-Server einen Webhook inklusive Zahlungsdaten.

Beispiel für eine Anfrage

PHP
CURL
  $request = array(
      'notification_type' => 'payment',
      'purchase' => array(
          'virtual_items' => array(
              'items' => array(
                  0 => array(
                      'sku' => 'test_item1',
                      'amount' => 1,
                      ),
                  1 => array(
                      'sku' => 'test_item2',
                      'amount' => 1,
                      ),
                  2 => array(
                      'sku' => 'test_item3',
                      'amount' => 1,
                      ),
              )
          ),
          'total' => array(
              'currency' => 'USD',
              'amount' => 9.99
          )
      ),
      'user' => array(
          'ip' => '127.0.0.1',
          'phone' => '18777976552',
          'email' => 'email@example.com',
          'id' => '1234567',
          'country' => 'US'
      ),
      'transaction' => array(
          'id' => 87654321,
          'payment_date' => '2014-09-23T19:25:25+04:00',
          'payment_method' => 1380,
          'dry_run' => 1
      ),
      'payment_details' => array(
          'payment' => array(
              'currency' => 'USD',
              'amount' => 9.99
          ),
          'vat' => array(
              'currency' => 'USD',
              'amount' => 0
          ),
          'payout_currency_rate' => 1,
          'payout' => array(
              'currency' => 'USD',
              'amount' => 9.49
          ),
          'xsolla_fee' => array(
              'currency' => 'USD',
              'amount' => 0.19
          ),
          'payment_method_fee' => array(
              'currency' => 'USD',
              'amount' => 0.31
          )
      )
  )

  curl -v https://example.com/ \
  -X POST \
  -H 'Content-Type:application/json' \
  -H 'Accept: application/json' \
  -H 'Authorization: Signature 13342703ccaca5064ad33ba451d800c5e823db8f' \
  -d '
  {
      "notification_type": "payment",
      "purchase": {
          "virtual_items": {
              "items": [
                  {
                      "sku": "test_item1",
                      "amount": 1
                  },
                  {
                      "sku": "test_item2",
                      "amount": 1
                  },
                  {
                      "sku": "test_item3",
                      "amount": 2
                  },
              ]
          },
          "total": {
              "currency": "USD",
              "amount": 9.99
          }
      },
      "user": {
          "ip": "127.0.0.1",
          "phone": "18777976552",
          "email": "email@example.com",
          "id": "1234567",
          "country": "US"
      },
      "transaction": {
          "id": 87654321,
          "payment_date": "2014-09-23T19:25:25+04:00",
          "payment_method": 1380,
          "dry_run": 1
      },
      "payment_details": {
          "payment": {
              "currency": "USD",
              "amount": 9.99
          },
          "vat": {
              "currency": "USD",
              "amount": 0
          },
          "payout_currency_rate": 1,
          "payout": {
              "currency": "USD",
              "amount": 9.49
          },
          "xsolla_fee": {
              "currency": "USD",
              "amount": 0.19
          },
          "payment_method_fee": {
              "currency": "USD",
              "amount": 0.31
          }
      }
  }'

Die vollständige Liste der Parameter finden Sie in der API-Referenz.

Rückerstattung

Immer wenn ein Benutzer eine Zahlung storniert, sendet der Xsolla-Server einen Webhook inklusive Zahlungsinformationen.

Beispiel für eine Anfrage

PHP
CURL
  $request = array(
      'notification_type' => 'refund',
      'purchase' => array(
          'virtual_currency' => array(
              'name' => 'Coins',
              'quantity' => 100,
              'currency' => 'USD',
              'amount' => 9.99
          ),
          'total' => array(
              'currency' => 'USD',
              'amount' => 9.99
          )
      ),
      'user' => array(
          'ip' => '127.0.0.1',
          'phone' => '18777976552',
          'email' => 'email@example.com',
          'id' => '1234567',
          'country' => 'US'
      ),
      'transaction' => array(
          'id' => 87654321,
          'payment_date' => '2014-09-23T19:25:25+04:00',
          'payment_method' => 1380,
          'dry_run' => 1
      ),
      'refund_details' => (
              'code' => 1,
              'reason' => 'Fraud'
      ),
      'payment_details' => array(
          'payment' => array(
              'currency' => 'USD',
              'amount' => 9.99
          ),
          'vat' => array(
              'currency' => 'USD',
              'amount' => 0
          ),
          'payout_currency_rate' => 1,
          'payout' => array(
              'currency' => 'USD',
              'amount' => 9.49
          ),
          'xsolla_fee' => array(
              'currency' => 'USD',
              'amount' => 0.19
          ),
          'payment_method_fee' => array(
              'currency' => 'USD',
              'amount' => 0.31
          )
      )
  );

  curl -v https://example.com/ \
  -X POST \
  -H 'Content-Type:application/json' \
  -H 'Accept: application/json' \
  -H 'Authorization: Signature 13342703ccaca5064ad33ba451d800c5e823db8f' \
  -d '
  {
      "notification_type":"refund",
      "purchase":{
          "virtual_currency":{
              "name": "Coins",
              "quantity":10,
              "currency":"USD",
              "amount":100
          },
          "subscription":{
              "plan_id": "b5dac9c8",
              "subscription_id": "10",
              "date_create": "2014-09-22T19:25:25+04:00",
              "currency": "USD",
              "amount": 9.99
          },
          "checkout":{
              "currency":"USD",
              "amount":50
          },
          "virtual_items":{
              "items":[
                  {
                      "sku": "test_item1",
                      "amount":1
                  }
              ],
              "currency":"USD",
              "amount":50
          },
          "total":{
              "currency":"USD",
              "amount":200
          }
      },
      "user": {
          "ip": "127.0.0.1",
          "phone": "18777976552",
          "email": "email@example.com",
          "id": "1234567",
          "name": "Xsolla User",
          "country": "US"
      },
      "transaction":{
          "id":1,
          "external_id":1,
          "dry_run":1,
          "agreement":1
      },
      "refund_details":{
          "code":1,
          "reason":"Fraud"
      },
      "payment_details":{
          "xsolla_fee":{
              "currency":"USD",
              "amount":"10"
          },
          "payout":{
              "currency":"USD",
              "amount":"200"
          },
          "payment_method_fee":{
              "currency":"USD",
              "amount":"20"
          },
          "payment":{
              "currency":"USD",
             "amount":"230"
          }
      }
  }'

Die vollständige Liste der Parameter finden Sie in der API-Referenz.

Webhooks testen

Gehen Sie folgendermaßen vor, um einen Webhook-Handler zu testen:

  1. Rufen Sie die Moduleinstellungen in Ihrem Kundenportal auf.
  2. Gehen Sie zur Registerkarte Testen.
  3. Geben Sie die Testdaten ein und klicken Sie auf Test. Der Xsolla-Server wird alle möglichen Webhooks senden.
  4. Im Falle einer gültigen Antwort wird der Test grün und im Falle eines Fehlers rot gekennzeichnet.

Zahlungsvorgang austesten

Xsolla-Sandbox ist eine eigenständige Umgebung, welche alle Funktionen der Live-Umgebung mit Ausnahme echter Zahlungen unterstützt. Sie können auf den Sandbox-Modus zugreifen, indem Sie "mode" = "sandbox" beim Abrufen des Tokens versenden.

Gehen Sie folgendermaßen vor, um eine Kartenzahlung zu testen:

  1. Rufen Sie das Zahlungsportal im Sandbox-Modus auf.
  2. Klicken Sie auf Kredit-/Debitkarten.
  3. Geben Sie die Kreditkartendaten aus der nachfolgenden Tabelle ein. Geben Sie alle Werte in die verbleibenden Felder ein. Sie können auch falsche Angaben (Kartennummer, Ablaufdatum oder CVV) angeben, um einen Fehler zu generieren.

Liste der Bankkarten, die für Testzwecke verwendet werden können

Wichtig: Sandbox-Kartenzahlungen können lediglich in USD, EUR, RUB, GBP, SGD, HKD oder THB getätigt werden.

Veröffentlichung des Moduls

Um das Modul nach dessen erfolgreichem Test zu veröffentlichen, öffnen Sie dessen Einstellungen im Kundenportal, gehen Sie zur Registerkarte Veröffentlichen und klicken Sie auf Ein.

Wichtig: Um echte Zahlungen akzeptieren zu können, müssen Sie Folgendes tun:

  1. Entfernen Sie den "sandbox"-Modus.
  2. Unterschreiben Sie die Vereinbarung.

Methoden zur Verwendung mit gespeicherten Zahlungskonten

Nachdem der Benutzer die erste Zahlung über das Zahlungsportal getätigt hat, wird sein Zahlungskonto gespeichert. Weitere Zahlungen können ohne Zutun des Benutzers oder Aufrufen der Benutzeroberfläche vorgenommen werden.

Liste der gespeicherten Zahlungskonten anzeigen

Beispiel für eine Anfrage

CURL
curl -v 'https://api.xsolla.com/merchant/projects/{project_id}/users/{user_id}/payment_accounts' \
-X GET \
-u merchant_id:merchant_api_key

Beispiel für eine Antwort

CURL
[
    {
        "type": "card",
        "id": 1,
        "name": "411111******1111",
        "payment_system": {
            "id": 1380,
            "name": "Credit/Debit Cards"
        }
    }
]

Die vollständige Liste der Parameter finden Sie in der API-Referenz.

Mittels gespeichertem Zahlungskonto bezahlen

Beispiel für eine Anfrage

CURL
$ curl -v 'https://api.xsolla.com/merchant/projects/{project_id}/users/{user_id}/payments/{type}/{account_id}' \
-X POST \
-u merchant_id:merchant_api_key \
-H 'Content-Type: application/json' \
-H 'Accept: application/json' \
-d '{
    "user": {
        "ip": "127.0.0.1",
        "name": "John Smith"
    },
    "purchase": {
        "virtual_currency": {
            "quantity": 100
        },
        "description": {
            "value": "Test Purchase"
        }
    },
    "settings": {
        "mode": "sandbox"
    }
}'

Beispiel für eine Antwort

CURL
{
    "transaction_id": 119478390
}

Die vollständige Liste der Parameter finden Sie in der API-Referenz.

Ein gespeichertes Zahlungskonto löschen

Beispiel für eine Anfrage

CURL
$ curl -v 'https://api.xsolla.com/merchant/projects/{project_id}/users/{user_id}/payment_accounts/{type}/{account_id}' \
-X DELETE \
-u merchant_id:merchant_api_key

Die vollständige Liste der Parameter finden Sie in der API-Referenz.