Integration der Store API

So funktioniert's

Sie können die Store API in Ihren Online-Shop-Server einbinden oder, vorausgesetzt Sie haben den Server in Xsolla integriert (Integration mit Token), zu den neuen Methoden der Store API wechseln.

Hauptmerkmale:

  • Autorisierung über Xsolla-Login oder den Zugriffstoken der Bezahlstation
  • Verwaltung virtueller Gegenstände
  • Verwaltung des Benutzer-Inventars
  • Warenkorb- und Bestellungsverwaltung

Für wen ist es

  • Partner, die eine Online-Shop-Benutzeroberfläche entwickeln und eine Drittanbieterlösung zur Serverimplementierung nutzen möchten.
  • Partner, die den Server in Xsolla bereits integriert haben und die neuen API-Methoden im Online-Shop integrieren möchten.

Wie komme ich dazu

So verknüpfen sie die Store API mit Ihrer App:

  1. Konfigurieren Sie das Modul Virtuelle Gegenstände im Kundenportal.
  2. Konfigurieren Sie die Authentifizierung.
  3. Implementieren Sie die Methoden für die Online-Shop-Verwaltung.

Zur Integration benötigen Sie die Projekt-ID, welche unter Projekteinstellungen > Webhooks zu finden ist. Die Projekt-ID kommt in den Anfragen der Store API zum Einsatz.

Modul "Virtuelle Gegenstände" im Kundenportal einrichten

  1. Gehen Sie zu Projekte und klicken Sie auf die Schaltfläche Projekt erstellen.
  2. Geben Sie einen Projektnamen ein und klicken Sie auf Erstellen.

  1. Navigieren Sie zu Projekteinstellungen > Integrationseinstellungen und prüfen Sie, ob Neue Online-Shop-Managementmethoden integrieren aktiviert ist.
  2. Verknüpfen Sie den Online-Shop mit Ihrem Projekt.
  3. Verknüpfen Sie das Modul Virtuelle Gegenstände.

  1. Erstellen Sie eine Gegenstandsgruppe.

  1. Erstellen Sie Gegenstände.

  1. Aktivieren Sie die Option "Im Online-Shop anzeigen", nachdem Sie die Gegenstände erstellt haben.

Authentifizierungseinrichtung

Die folgenden Optionen zur Benutzerauthentifizierung stehen zur Verfügung:

  • Über Xsolla-Login. Wählen Sie diese Option, wenn Sie den Server nicht in Xsolla integriert haben.
  • Über den Zugriffstoken der Bezahlstation. Wählen Sie diese Option, wenn Sie den Server in Xsolla integriert haben.

Authentifizierung über Xsolla-Login

  1. Richten Sie ein Projekt im Kundenportal ein. Befolgen Sie dabei die Anweisungen.
  2. Implementieren Sie den Aufruf der Autorisierungsmethoden mithilfe des JSON-Web-Tokens oder OAuth 2.0-Protokolls

Wenn die Nutzerdaten bei Xsolla hinterlegt sind, implementieren Sie den Aufruf der folgenden Methoden:

Sind die Nutzerdaten bei PlayFab hinterlegt, nutzen Sie die PlayFab-Anleitung.

Sind die Nutzerdaten bei Ihnen hinterlegt, nutzen Sie die Anleitung Kundenseitiger Speicherort.

Authentifizierung über den Zugriffstoken der Bezahlstation

Authentifizierungsablauf:

  1. Ihre Anwendung (Client) sendet die Authentifizierungsanfrage an Ihren Server.
  2. Ihr Server sendet die Händler-ID und den API-Schlüssel an den Xsolla-Server und fragt den access_token an.
  3. Der Xsolla-Server sendet den access_token an Ihren Server.
  4. Ihr Server sendet den access_token an Ihren Client.

Der empfangene access_token wird als Autorisierungstoken zur Authentifizierung in der Store API und zur Erstellung einer Online-Shop-Benutzeroberfläche genutzt.

Methoden zur Online-Shop-Verwaltung

Methoden zur Online-Shop-Verwaltung umfassen die folgenden Methodengruppen:

Get Virtual Items List

Implementieren Sie die API-Methode Get virtual items list, um sich die komplette Liste der zu Ihrem Online-Shop hinzugefügten virtuellen Gegenstände anzeigen zu lassen.

BEISPIEL

var data = null;

var xhr = new XMLHttpRequest();
xhr.withCredentials = true;

xhr.addEventListener("readystatechange", function () {
  if (this.readyState === this.DONE) {
    console.log(this.responseText);
  }
});

xhr.open("GET", "https://store.xsolla.com/api/v2/project/44056/items/virtual_items?locale=en");

xhr.send(data);

//RESPONSE

"items": [
    {
      "attributes": [],
      "description": "Conquer your foes with vindication using the Basic Blaster! ",
      "groups": [
        "all",
        "featured",
        "Xsolla",
        "weapons"
      ],
      "image_url": "https://cdn.xsolla.net/img/misc/images/0c59a7698d4f66c1008b27ee752089b7.png",
      "is_free": false,
      "name": "Xsolla Basic Blaster 1",
      "order": 1,
      "price": {
        "amount": "0.9950000000000000",
        "amount_without_discount": "1.9900000000000000",
        "currency": "USD"
      },
      "sku": "gun_1",
      "type": "virtual_good"

Get Item Groups List

  1. Implementieren Sie die API-Methode Get item groups list, um sich die komplette Liste der zu Ihrem Online-Shop hinzugefügten Gruppen virtueller Gegenstände anzeigen zu lassen.
  2. Geben Sie für jeden Wert des bei der Methode Get virtual items list erhaltenen sku-Parameters die external_id der zugehörigen Gruppe an. Ordnen Sie die sku und die external_id genauso an, wie die Gegenstände im Kundenportal gruppiert sind.

BEISPIEL

var data = null;

var xhr = new XMLHttpRequest();
xhr.withCredentials = true;

xhr.addEventListener("readystatechange", function () {
  if (this.readyState === this.DONE) {
    console.log(this.responseText);
  }
});

xhr.open("GET", "https://store.xsolla.com/api/v2/project/44056/items/groups");

xhr.send(data);

//RESPONSE

  "groups": [
    {
      "children": [],
      "description": "all",
      "external_id": "all",
      "id": 10,
      "image_url": "http://none",
      "level": 0,
      "name": "all",
      "order": null,
      "parent_external_id": null
    }

Get Cart

Implementieren Sie für den Kauf von virtuellen Gegenständen die API-Methode Get cart by ID oder Get current user’s cart. Die Cart ID wird genutzt, um Gegenstände hinzuzufügen bzw. zu entfernen.

BEISPIEL

var data = null;

var xhr = new XMLHttpRequest();
xhr.withCredentials = true;

xhr.addEventListener("readystatechange", function () {
  if (this.readyState === this.DONE) {
    console.log(this.responseText);
  }
});

xhr.open("GET", "https://store.xsolla.com/api/v2/project/44056/cart/custom_id?locale=en&currency=USD");
xhr.setRequestHeader("authorization", "Bearer eyJ0eXAiOiJKV1QiLCJhbGciOiJIUzI1NiJ9.eyJleHAiOjE5NjIyMzQwNDgsImlzcyI6Imh0dHBzOi8vbG9naW4ueHNvbGxhLmNvbSIsImlhdCI6MTU2MjE0NzY0OCwidXNlcm5hbWUiOiJ4c29sbGEiLCJ4c29sbGFfbG9naW5fYWNjZXNzX2tleSI6IjA2SWF2ZHpDeEVHbm5aMTlpLUc5TmMxVWFfTWFZOXhTR3ZEVEY4OFE3RnMiLCJzdWIiOiJkMzQyZGFkMi05ZDU5LTExZTktYTM4NC00MjAxMGFhODAwM2YiLCJlbWFpbCI6InN1cHBvcnRAeHNvbGxhLmNvbSIsInR5cGUiOiJ4c29sbGFfbG9naW4iLCJ4c29sbGFfbG9naW5fcHJvamVjdF9pZCI6ImU2ZGZhYWM2LTc4YTgtMTFlOS05MjQ0LTQyMDEwYWE4MDAwNCIsInB1Ymxpc2hlcl9pZCI6MTU5MjR9.GCrW42OguZbLZTaoixCZgAeNLGH2xCeJHxl8u8Xn2aI");

xhr.send(data);

//RESPONSE

{
  "cart_id": "custom_id",
  "is_free": true,
  "items": [],
  "price": null
}

Note: Um den Schnellkauf von Gegenständen (d. h. ohne einen Warenkorb anzulegen) zu aktivieren, nutzen Sie die API-Methode Create order with specified item.

Create Order with All Items

  1. Implementieren Sie eine der folgenden API-Methoden:
    1. Create order with all items from particular cart, wenn Sie den Warenkorb mittels ID abgerufen haben.
    2. Create order with all items from current cart, wenn Sie den aktuellen Warenkorb abgerufen haben.

Die angelegte Bestellung erhält den Status New.

  1. Um das Zahlungsportal in einem neuen Fenster zu öffnen, nutzen Sie folgenden Link: https://secure.xsolla.com/paystation3/?access_token=ACCESS_TOKEN, wobei ACCESS_TOKEN der Token ist, den Sie beim Anlegen der Bestellung erhalten haben.
  2. So testen Sie den Zahlungsvorgang:
    1. Nutzen Sie folgende URL: https://sandbox-secure.xsolla.com/paystation3/?access_token=ACCESS_TOKEN.
    2. Legen Sie in der Anfrage als Wert für den sandbox parameter true fest.
    3. Werfen Sie einen Blick in die Liste der Bankkarten, die für Testzwecke verwendet werden können.

BEISPIEL

var data = JSON.stringify({
  "currency": "USD",
  "locale": "en",
  "sandbox": false
});

var xhr = new XMLHttpRequest();
xhr.withCredentials = true;

xhr.addEventListener("readystatechange", function () {
  if (this.readyState === this.DONE) {
    console.log(this.responseText);
  }
});

xhr.open("POST", "https://store.xsolla.com/api/v2/project/44056/payment/cart/custom_id");
xhr.setRequestHeader("content-type", "application/json");
xhr.setRequestHeader("authorization", "Bearer eyJ0eXAiOiJKV1QiLCJhbGciOiJIUzI1NiJ9.eyJleHAiOjE5NjIyMzQwNDgsImlzcyI6Imh0dHBzOi8vbG9naW4ueHNvbGxhLmNvbSIsImlhdCI6MTU2MjE0NzY0OCwidXNlcm5hbWUiOiJ4c29sbGEiLCJ4c29sbGFfbG9naW5fYWNjZXNzX2tleSI6IjA2SWF2ZHpDeEVHbm5aMTlpLUc5TmMxVWFfTWFZOXhTR3ZEVEY4OFE3RnMiLCJzdWIiOiJkMzQyZGFkMi05ZDU5LTExZTktYTM4NC00MjAxMGFhODAwM2YiLCJlbWFpbCI6InN1cHBvcnRAeHNvbGxhLmNvbSIsInR5cGUiOiJ4c29sbGFfbG9naW4iLCJ4c29sbGFfbG9naW5fcHJvamVjdF9pZCI6ImU2ZGZhYWM2LTc4YTgtMTFlOS05MjQ0LTQyMDEwYWE4MDAwNCIsInB1Ymxpc2hlcl9pZCI6MTU5MjR9.GCrW42OguZbLZTaoixCZgAeNLGH2xCeJHxl8u8Xn2aI");

xhr.send(data);

//RESPONSE  

{
  "order_id": 641,
  "token": "f4puMEFFDZcx9nv5HoNHIkPe9qghvBQo"
}

Get Order

Implementieren Sie die API-Methode Get order, um festzustellen, ob der Kauf bereits abgewickelt wurde. Folgende Bestellungsstatus sind möglich:

  • New: Bestellung ist angelegt, wurde aber nicht bezahlt
  • Paid: Bestellung wurde bezahlt
  • Cancelled: Bestellung ist storniert
  • Done: Bestellung wurde bezahlt und der Gegenstand dem Inventar hinzugefügt

Note: Die Statusprüfung sollte in regelmäßigen Abständen erfolgen, da eine einmalige Prüfung jederzeit erfolgen kann, bevor einer Bestellung der Status "Neu" zugeordnet wird.

BEISPIEL

var data = null;

var xhr = new XMLHttpRequest();
xhr.withCredentials = true;

xhr.addEventListener("readystatechange", function () {
  if (this.readyState === this.DONE) {
    console.log(this.responseText);
  }
});

xhr.open("GET", "https://store.xsolla.com/api/v2/project/44056/order/656");
xhr.setRequestHeader("authorization", "Bearer eyJ0eXAiOiJKV1QiLCJhbGciOiJIUzI1NiJ9.eyJleHAiOjE5NjIyMzQwNDgsImlzcyI6Imh0dHBzOi8vbG9naW4ueHNvbGxhLmNvbSIsImlhdCI6MTU2MjE0NzY0OCwidXNlcm5hbWUiOiJ4c29sbGEiLCJ4c29sbGFfbG9naW5fYWNjZXNzX2tleSI6IjA2SWF2ZHpDeEVHbm5aMTlpLUc5TmMxVWFfTWFZOXhTR3ZEVEY4OFE3RnMiLCJzdWIiOiJkMzQyZGFkMi05ZDU5LTExZTktYTM4NC00MjAxMGFhODAwM2YiLCJlbWFpbCI6InN1cHBvcnRAeHNvbGxhLmNvbSIsInR5cGUiOiJ4c29sbGFfbG9naW4iLCJ4c29sbGFfbG9naW5fcHJvamVjdF9pZCI6ImU2ZGZhYWM2LTc4YTgtMTFlOS05MjQ0LTQyMDEwYWE4MDAwNCIsInB1Ymxpc2hlcl9pZCI6MTU5MjR9.GCrW42OguZbLZTaoixCZgAeNLGH2xCeJHxl8u8Xn2aI");

xhr.send(data);

//RESPONSE

{
  "content": {
    "is_free": false,
    "items": [
      {
        "is_free": false,
        "price": {
          "amount": "0.9950",
          "amount_without_discount": "1.9900",
          "currency": "USD"
        },
        "quantity": 123,
        "sku": "gun_1"
      }
    ],
    "price": {
      "amount": "122.3850",
      "amount_without_discount": "122.3850",
      "currency": "USD"
    }
  },
  "order_id": 656,
  "status": "new"
}

Get User’s Inventory

Implementieren Sie die API-Methode Get user’s inventory, um eine Liste der nach dem Kauf zum Inventar hinzugefügten Gegenstände abzurufen.

BEISPIEL

var data = null;

var xhr = new XMLHttpRequest();
xhr.withCredentials = true;

xhr.addEventListener("readystatechange", function () {
  if (this.readyState === this.DONE) {
    console.log(this.responseText);
  }
});

xhr.open("GET", "https://store.xsolla.com/api/v2/project/44056/user/inventory/items");
xhr.setRequestHeader("authorization", "Bearer eyJ0eXAiOiJKV1QiLCJhbGciOiJIUzI1NiJ9.eyJleHAiOjE5NjIyMzQwNDgsImlzcyI6Imh0dHBzOi8vbG9naW4ueHNvbGxhLmNvbSIsImlhdCI6MTU2MjE0NzY0OCwidXNlcm5hbWUiOiJ4c29sbGEiLCJ4c29sbGFfbG9naW5fYWNjZXNzX2tleSI6IjA2SWF2ZHpDeEVHbm5aMTlpLUc5TmMxVWFfTWFZOXhTR3ZEVEY4OFE3RnMiLCJzdWIiOiJkMzQyZGFkMi05ZDU5LTExZTktYTM4NC00MjAxMGFhODAwM2YiLCJlbWFpbCI6InN1cHBvcnRAeHNvbGxhLmNvbSIsInR5cGUiOiJ4c29sbGFfbG9naW4iLCJ4c29sbGFfbG9naW5fcHJvamVjdF9pZCI6ImU2ZGZhYWM2LTc4YTgtMTFlOS05MjQ0LTQyMDEwYWE4MDAwNCIsInB1Ymxpc2hlcl9pZCI6MTU5MjR9.GCrW42OguZbLZTaoixCZgAeNLGH2xCeJHxl8u8Xn2aI");

xhr.send(data);

//RESPONSE

{
  "items": [
    {
      "description": "Conquer your foes with vindication using the Basic Blaster! ",
      "image_url": "https://cdn.xsolla.net/img/misc/images/0c59a7698d4f66c1008b27ee752089b7.png",
      "instance_id": null,
      "long_description": "Conquer your foes with vindication using the Basic Blaster! Conquer your foes with vindication using the Basic Blaster! ",
      "name": "Xsolla Basic Blaster 1",
      "quantity": 22,
      "sku": "gun_1",
      "type": "virtual_good"
    },
    {
      "description": "Protect your noggin' with style",
      "image_url": "https://cdn.xsolla.net/img/misc/images/b79342cdf24f0f8557b63c87e8326e62.png",
      "instance_id": null,
      "long_description": "merchant_virtual_items_virtual_item_long_description_159429",
      "name": "Xsolla Helmet",
      "quantity": 18,
      "sku": "helmet_1",
      "type": "virtual_good"
    }
  ]
}