Erste Schritte

Überblick

Die Xsolla-API umfasst:

  • Bezahlstation-API — Zahlungsportal und Tokenisierungsverfahren
  • Online-Shop-API — Methoden für die Zusammenarbeit mit Modulen des Online-Shops: Virtuelle Währung, virtuelle Gegenstände, Abonnements, Spielschlüssel, Werbeaktionen, Gutscheine
  • Kundenportal-API — Kundenportalprojekte und Benutzerverwaltung, Methoden zur Verarbeitung von Berichten, Support-Tickets
  • Login-API — Methoden zur Benutzerauthentifizierung mittels Ihrer eigenen Schnittstelle (siehe Leitfaden zur Integration)

Die Xsolla-API basiert auf REST. Die API hat vorhersagbare, ressourcenorientierte URLs und verwendet HTTP-Statuscodes, um API-Fehler anzuzeigen. Die API antwortet stets im JSON-Format, auch im Falle von Fehlern.

Die API nutzt integrierte HTTP-Funktionen wie HTTP-Authentifizierung und HTTP-Methoden, die von gängigen HTTP-Clients interpretiert werden können. Die Schnittstelle unterstützt Cross-Origin Resource Sharing und gestattet Ihnen dadurch den sicheren Zugriff auf die API über eine clientseitige Webanwendung.

Die Xsolla-API nutzt folgende Endpunktpfade:

  • https://api.xsolla.com — Bezahlstation-API, Online-Shop-API, Kundenportal-API
  • https://login.xsolla.com/api — Login-API
Die meisten Endpunktpfade enthalten die merchant_id als Parameter. Dadurch ist ersichtlich, dass die Anwendung in Ihrem Auftrag handelt.

Versionshinweise

Änderungen in Version 2.0:
  • Neue URL zum Exportieren von Transaktionen: https://api.xsolla.com/merchant/v2/merchants/{merchant_id}/reports/transactions/registry.{format}
  • Geändertes Antwort-Format:
    • Stornierte Transaktionen weisen ab sofort negative Werte in folgenden Feldern auf:
      • Gebühr für das Zahlungssystem, Fixkosten
      • Xsolla-Einnahmebeteiligung, Fixkosten
      • Mehrwertssteuer
      • Kaufbetrag der virtuellen Währung
      • Kaufbetrag beim einfachen Checkout
      • Anzahl der erworbenen Gegenstände
      • Rückübertragungskosten, insgesamt
      • gedeckte Gebühren, Fixkosten
      • vom Guthaben gedeckte Gebühren
      • Auszahlungsbetrag aus dem Zahlungssystem
      • Zahlungsbetrag vom Guthaben
      • Vom Guthaben ausgezahlter Betrag
      • Kaufbetrag der PIN-Codes
    • Neue Felder wurden hinzugefügt:
      • Zahlungssystemart – Zahlungsart
      • MwSt. – dem Benutzer angezeigte MwSt
      • MwSt. in % — Prozentsatz der MwSt. im betreffenden Land
      • Erstattungsgrundbemerkung – Bemerkungen zum Grund der Erstattung
      • Direktkonto – je nach dem, ob es sich um ein Direktkonto handelt
    • folgende Felder wurden entfernt:
      • Gebühren des Zahlungssystems (%)
      • Betrag der externen Gebühr für das Zahlungssystem
      • Währung der externen Gebühr für das Zahlungssystem
      • Abgezogene MwSt. in % beträgt 0, falls die Abgezogene MwSt. 0 ist.
    • folgende Felder wurden umbenannt:
      • MwSt. -> Abgezogene MwSt
      • MwSt. (%) -> Abgezogene MwSt. in %
    • folgende Felder werden nicht ausgefüllt, wenn deren Wert "0" beträgt:
      • Betrag der virtuellen Währung
      • Kaufbetrag der virtuellen Währung
      • Kaufbetrag beim einfachen Checkout
      • Kaufbetrag der PIN-Codes
    • Währung, mit welcher die virtuelle Währung erworben wurde wird nicht ausgefüllt, wenn Kaufbetrag der virtuellen Währung 0 beträgt.
    • Währung beim einfachen Checkout wird nicht ausgefüllt, wenn Kaufbetrag beim einfachen Checkout 0 beträgt.
    • Währung beim PIN-Code-Kauf wird nicht ausgefüllt, wenn Kaufbetrag der PIN-Codes 0 beträgt. Warenkorbinhalt beim PIN-Code-Kauf bleibt leer.

Anfragen und Antworten

Die Anfragen an die Xsolla-API müssen:

  • über HTTPS gesendet werden,
  • TLS 1.2 oder höher nutzen,
  • Parameter zur Authentifizierung enthalten,
  • einen zusätzlichen Header für PUT- und POST-Anfragen aufweisen: Content-Type: application/json.

Authorization: Basic <your_authorization_basic_key>
Content-Type: application/json

Standardmäßig folgt auf sämtliche Anfragen eine Antwort samt JSON-Daten im Body und Content-Type: application/json im Header.

API-Änderungen

Xsolla kann die API-Funktionalität folgendermaßen ändern:

  • Neue API-Ressourcen hinzufügen;
  • Optionale Anfrageparameter hinzufügen;
  • Bestehenden API-Antworten neue Eigenschaften hinzufügen;
  • Bestehenden Parametern, die über zählbare Werte verfügen, neue Werte hinzufügen;
  • Neue Arten von Webhooks und neue JSON-Parameter hinzufügen;
  • Optionale HTTP-Anfrage-Header hinzufügen;
  • Anfragen, bei denen gültigen Parametern ungültige Werte zugeordnet wurden, ablehnen.
  • Unzulässig formatierte Anfragen, welche zuvor aufgrund von tolerantem Parsing akzeptiert wurden, ablehnen, falls sich die Logik des Parsers geändert hat.
  • Undokumentierte Funktionen jederzeit hinzufügen, ändern oder entfernen

Ihr Client sollte, unabhängig von derartigen Änderungen funktionsfähig bleiben. Beispielsweise sollten neue JSON-Parameter, welche von Ihrem Client nicht erkannt werden, den normalen Betrieb des Clients nicht behindern.

Ver­si­o­nie­rung

Alle Xsolla-API-Methoden unterstützen Versionierung. Wir werden immer dann eine neue Version veröffentlichen, wenn es Änderungen gibt, die mit der aktuellen Version nicht kompatibel sind. Die Version ist in der URL durch die Angabe von "v1"/"v2"/usw., welche auf das Präfix "/merchant" folgt, identifizierbar.

Nutzen Sie bitte die neuste Version, falls Sie das erste Mal mit der API arbeiten. Wenn Sie die Versionsangabe weglassen, verwenden wir standardmäßig die erste Version.

Info: Denken Sie bitte daran, dass wir API-Integrität nur innerhalb der gleichen Version garantieren können.

Authentifizierung

Xsolla-API nutzt Basisauthentifizierung. Alle Anfragen an die API müssen im Header Authorization: Basic <your_authorization_basic_key> enthalten, wobei <your_authorization_basic_key> dem, gemäß Base64-Standard, kodierten merchant_id:api_key-Paar entspricht.

Navigieren Sie zum Xsolla-Kundenportal, um die Werte der merchant_id- und api_key-Parameter zu erhalten:

  • merchant_id: Firmeneinstellungen > Firma > Händler-ID
  • api_key: Firmeneinstellungen > API-Schlüssel

Notice: Halten Sie Ihren API-Schlüssel geheim. Er ermöglicht den Zugriff auf Ihr persönliches Konto und Ihre Projekte im Kundenportal.
Copy
Full screen
http
  • http
  • curl
  • php
  • C#
  • python
  • ruby
  • java
  • js
Beispiel
GET https://api.xsolla.com/merchant/v2/merchants/{merchant_id}/events/messages
Headers:
  Authorization: Basic <your_authorization_basic_key>
curl --request GET \
--url 'https://api.xsolla.com/merchant/v2/merchants/{merchant_id}/events/messages' \
--header 'authorization: Basic <your_authorization_basic_key>'
<?php

// if you use Xsolla SDK for PHP
use Xsolla\SDK\API\XsollaClient;
$xsollaClient = XsollaClient::factory(array(
    'merchant_id' => MERCHANT_ID,
    'api_key' => API_KEY
));
$eventsList = $client->ListEvents(array());

// if you don’t use Xsolla SDK for PHP
$client = new http\Client;
$request = new http\Client\Request;

$request->setRequestUrl('https://api.xsolla.com/merchant/v2/merchants/{merchant_id}/events/messages');
$request->setRequestMethod('GET');
$request->setHeaders(array(
  'authorization' => 'Basic <your_authorization_basic_key>'
));

$client->enqueue($request)->send();
$response = $client->getResponse();

echo $response->getBody();
var client = new RestClient("https://api.xsolla.com/merchant/v2/merchants/{merchant_id}/events/messages");
var request = new RestRequest(Method.GET);
request.AddHeader("authorization", "Basic <your_authorization_basic_key>");
IRestResponse response = client.Execute(request);
import http.client

conn = http.client.HTTPSConnection("api.xsolla.com")

headers = { 'authorization': "Basic <your_authorization_basic_key>" }

conn.request("GET", "/merchant/v2/merchants/{merchant_id}/events/messages", headers=headers)

res = conn.getresponse()
data = res.read()

print(data.decode("utf-8"))
require 'uri'
require 'net/http'

url = URI("https://api.xsolla.com/merchant/v2/merchants/{merchant_id}/events/messages")

http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true
http.verify_mode = OpenSSL::SSL::VERIFY_NONE

request = Net::HTTP::Get.new(url)
request["authorization"] = 'Basic <your_authorization_basic_key>'

response = http.request(request)
puts response.read_body
OkHttpClient client = new OkHttpClient();

Request request = new Request.Builder()
  .url("https://api.xsolla.com/merchant/v2/merchants/{merchant_id}/events/messages")
  .get()
  .addHeader("authorization", "Basic <your_authorization_basic_key>")
  .build();

Response response = client.newCall(request).execute();
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://api.xsolla.com/merchant/v2/merchants/{merchant_id}/events/messages");
xhr.setRequestHeader("authorization", "Basic <your_authorization_basic_key>");

xhr.send(data);

Typen von Endpunkten

Der Endpunkttyp gibt an, welche Art von Daten der Endpunkt verarbeitet und welche Aktionen ausgeführt werden. Die häufigsten Aktionen sind:

Aktion HTTP-Methode Beschreibung
Erstellen POST Erstellt und speichert eine Entität des angegebenen Typs.
Auflisten GET Liefert eine Liste von Entitäten, die der Anfrage entsprechen. Um Details zu einer Entität anzufordern, muss zuerst deren ID mit Hilfe des Endpunkttyps "Auflisten" bestimmt werden. Danach muss diese ID am entsprechenden Endpunkt (Typ: "Abrufen") bereitgestellt werden.
Abrufen GET Liefert detaillierte Angaben zur Entität mit der angegebenen ID.
Ersetzen PUT Modifiziert alle Felder der Entität mit der angegebenen ID.
Aktualisieren PATCH Modifiziert bestimmte Felder der Entität mit der angegebenen ID.
Löschen DELETE Löscht die Entität mit der angegebenen ID.

Datumsformat

Alle Datumsangaben sind spezifiziert als Strings gemäß ISO 8601. Sie können die Datumstrings entweder als UTC (z. B.: 2013-01-15T00:00:00Z) angeben oder die Abweichung von der UTC anzeigen lassen Im letzteren Fall ist darauf zu achten,dass gegebenenfalls die Sommerzeit berücksichtigt werden muss.

Paginierung

Endpunkte des Typs "Auflisten" können die gelieferten Ergebnisse paginieren. Anstelle alle Ergebnisse in einer einzigen Antwort zu versenden Können diese Endpunkte einige der Ergebnisse gemeinsam mit einem Antwort-Header zurückgeben, welcher zu den nächsten Ergebnissen verlinkt. Zu diesem Zweck verwenden wir Offset- und Limit-Parameter.

Fehlerbehandlung

Liste der unterstützten HTTP-Statuscodes:

  • 200, 201, 204 — Kein Fehler.
  • 400 Bad Request — Weist oftmals darauf hin, dass ein erforderlicher Parameter fehlt. Weitere Informationen finden Sie im Nachrichtenrumpf.
  • 401 Unauthorized — Kein gültiger API-Schlüssel bereitgestellt.
  • 402 Request Failed — Anfrage trotz gültiger Parameter fehlgeschlagen.
  • 403 Forbidden — Keine Berechtigung. Weitere Informationen finden Sie im Nachrichtenrumpf.
  • 404 Not Found — Die angeforderte Ressource konnte nicht gefunden werden.
  • 409, 422 — Ungültige Anfrageparameter.
  • 412 Precondition Failed — Das Projekt wurde noch nicht aktiviert (wird bei der Get Token-Methode verwendet).
  • 415 Unsupported Media Type — Im HTTP-Header fehlt die Angabe "Content-Type: application/json".
  • 500, 502, 503, 504 Server Errors — Etwas ist schief gelaufen.

Xsolla verwendet konventionelle HTTP-Statuscodes, um zu verdeutlichen, ob die API-Anfrage erfolgreich war. steht 2xx für eine erfolgreiche Anfrage, 4xx weist auf einen Fehler bei den bereitgestellten Daten hin (z. B.:Fehlen eines erforderlichen Parameters, fehlgeschlagene Autorisierung usw.) und 5xx deutet auf ein Problem mit Xsollas

Jedoch entsprechen nicht alle Fehler exakt den HTTP-Statuscodes. Beispielsweise wird die API den Fehlercode 422 zurückgeben, falls eine Anfrage gültig war, aber fehlgeschlagen ist.

Alle API-Fehlerrückmeldungen liefern ein JSON-Objekt mit folgenden Feldern:

{< T "api_table_name" >}} Typ Beschreibung
http_status_code integer HTTP-Code.
message string Eine für Menschen verständliche Meldung, welche den Fehler beschreibt. Diese Nachricht wird immer in englischer Sprache ausgegeben. Verlassen Sie sich bei einem bestimmten Fehler nicht auf die Aussagekraft der Meldung, da sich diese Nachricht in Zukunft ändern könnte.
extended_message string Detailliertere Fehlerbeschreibung.
request_id string Eindeutige Request-ID, die wir eventuell für die Fehlersuche verwenden können.
{
    "http_status_code": 500,
    "message": "Internal Server Error",
    "extended_message": null,
    "request_id": "6445b85"
}

Token

Aus Sicherheitsgründen behandelt die Xsolla-API Zahlungsparameter innerhalb eines Tokens, anstatt sie direkt über GET-Anfragemethode zu empfangen. Sie müssen vor dem Aufbau der Zahlungsseite einen neuen Token beziehen. Ein Token ist 24 Stunden lang gültig.

Token abrufen

HTTP-ANFRAGE

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

Sie können einen Token mit beliebigen Nutzerparametern erstellen. Senden Sie diese Parameter beim Beziehen des Tokens. Wir senden diese Parameter nach erfolgreicher Bezahlung an Sie zurück. Ein Token kann ausschließlich Parameter enthalten, die entweder in diesem Dokument beschrieben sind oder vom Partner vorher definiert wurden.

Parameter Typ Beschreibung
user
object Benutzerdaten (Objekt).
user.id
object Benutzer-ID (Objekt). Erforderlich.
user.id.value
string Benutzer-ID.
user.name
object Benutzername (Objekt).
user.name.value
string Benutzername.
user.email
object E-Mail des Benutzers (Objekt).
user.email.value
string E-Mail-Adresse des Benutzers. Muss gemäß RFC 822-Protokoll gültig sein.
user.phone
object Telefonnummer des Benutzers (Objekt).
user.phone.value
string Telefonnummer des Benutzers.
user.country
object Land des Benutzers (Objekt).
user.country.value
string Ländercode, bestehend aus 2 Großbuchstaben gemäß ISO 3166-1 ALPHA-2.
user.country.allow_modify
boolean Legt fest, ob der Benutzer das Feld im Zahlungsportal bearbeiten kann. Standardwert ist 'false'.
user.attributes
object Benutzerattribute zum Filtern der Liste der Gegenstände; repräsentiert durch eine gültige Reihe von JSON-Objekten bestehend aus Schlüssel-Wert-Paaren.
user.steam_id
object Steam-ID des Benutzers (Objekt).
user.steam_id.value
string Steam-ID.
user.tracking_id
object Tracking-ID des Benutzers (Objekt).
user.tracking_id.value
string Eindeutige Tracking-ID (wird bei Marketingkampagnen verwendet).
user.public_id.value
string Parameter, durch den der Benutzer eindeutig identifizierbar ist und der dem Benutzer bekannt ist (E-Mail, Benutzername, usw.). Gestattet dem Benutzer, Käufe außerhalb des Game-Stores zu tätigen (z. B. via Verkaufsterminals).
user.utm
object Datenverkehrsattribute (Objekt).
user.utm.utm_source
string Ursprung des Datenverkehrs.
user.utm.utm_medium
string Datenverkehrskanal (kontextbezogene Anzeigen, mediale Anzeigen, E-Mail-Listen, usw.).
user.utm.utm_campaign
string Kampagnenbezeichnung, ins Englische transliteriert oder übersetzt.
user.utm.utm_term
string Kampagnen-Keyword. Falls festgelegt, basieren die Statistiken auf den Keywords, die für die Zielgruppenwerbung verwendet werden, anstatt auf spezifischen Suchanfragen. In Google Analytics ist der angegebene 'utm_term' Teil des allgemeinen Berichts zu Suchbegriffen.
user.utm.utm_content
string Kampagneninhalt.
boolean Legt fest, ob der Benutzer eine juristische Person ist.
object Objekt mit Angaben zur juristischen Person. Objekt und alle seine Parameter sind erforderlich, falls für user.is_legal 'true' festgelegt ist.
string Vollständiger Name des Unternehmens.
string Vollständige Unternehmensanschrift.
string Steuerliche Identifikationsnummer.
string Land des Unternehmenssitzes. Ländercode, bestehend aus 2 Großbuchstaben gemäß ISO 3166-1 ALPHA-2.
settings
object Benutzerdefinierte Projekteinstellungen (Objekt).
settings.external_id
string Externe ID der Transaktion.
settings.project_id
integer Xsolla-ID des Spiels. Kann im Kundenportal eingesehen werden. Erforderlich.
settings.language
string Sprache der Benutzeroberfläche. Sprachencode, bestehend aus 2 Kleinbuchstaben gemäß ISO 639-1.
settings.return_url
string Seite, zu welcher der Benutzer nach der Zahlung weitergeleitet wird. Die folgenden Parameter werden dem Link automatisch hinzugefügt: 'user_id', 'foreigninvoice', 'invoice_id', 'status'.
settings.currency
string Bevorzugte Zahlungswährung. Währungscode, bestehend aus drei Buchstaben gemäß ISO 4217.
settings.mode
string Legen Sie als Wert 'sandbox' fest, um den Zahlungsvorgang auszutesten. Für einen solchen Fall nutzen Sie https://sandbox-secure.xsolla.com, um das Zahlungsportal auszutesten.
settings.payment_method
integer ID der Zahlungsart.
settings.payment_widget
string Zahlungs-Widget. Kann 'paybycash' oder 'giftcard' sein. Wenn der Parameter festgelegt ist, wird der Benutzer entsprechend zum Widget "Pay by Cash" oder zum Widget "Gift Cards" weitergeleitet.
settings.ui
object Schnittstellen-Einstellungen (Objekt).
settings.ui.theme
string Theme des Zahlungsportals. Als Wert lässt sich entweder 'default' (voreingestellt) oder 'default_dark' festlegen.
settings.ui.size
string Größe des Zahlungsportals. Folgende Größen sind möglich:
  • small: die kleinstmögliche Größe des Zahlungsportals. Verwenden Sie diese, wenn die Fenstergröße begrenzt ist (Abmessungen: 620 x 630)
  • medium: empfohlene Größe. Verwenden Sie diese, um das Zahlungsportal in einer Lightbox darzustellen (Abmessungen: 820 x 840)
  • large: optimal für die Anzeige des Zahlungsportals in einem neuen Fenster/Registerkarte (Abmessungen: 820 x 840)
settings.ui.version
string Gerätetyp. Als Wert lässt sich entweder 'desktop' (voreingestellt) oder 'mobile' festlegen.
settings.ui.desktop
object Schnittstellen-Einstellungen für die Desktop-Version (Objekt).
settings.ui.desktop.header
object Einstellungen für den Header (Objekt).
settings.ui.desktop.header.is_visible
boolean Legt fest, ob der Header im Zahlungsportal angezeigt wird.
boolean Falls der Wert 'true' festgelegt ist, erscheint Ihr Logo im Header (bitte senden Sie dazu das Logo als Bilddatei an Ihren Account Manager).
settings.ui.desktop.header.visible_name
boolean Legt fest, ob der Projektname im Header angezeigt wird.
settings.ui.desktop.header.visible_purchase
boolean Legt fest, ob die Kaufbeschreibung (purchase.description.value) im Header angezeigt wird. ‘true’ ist voreingestellt.
settings.ui.desktop.header.type
string Erscheinungsbild des Headers. Als Wert lässt sich entweder 'compact' (Projektname und Benutzer-ID sind ausgeblendet) oder 'normal' (voreingestellt) festlegen.
settings.ui.desktop.header.close_button
boolean Legt fest, ob eine Schließen-Schaltfläche in der Desktop-Version der Bezahlstation angezeigt wird. Die Schaltfläche schließt die Bezahlstation und leitet den Benutzer an die im "settings.return_url"-Parameter angegebene URL weiter. Standardmäßig ist False voreingestellt.
settings.ui.desktop.subscription_list
object Einstellungen zur Liste der Abo-Modelle (Objekt).
settings.ui.desktop.subscription_list.layout
string Listenvorlage. Als Wert lässt sich entweder 'list' (voreingestellt) oder 'grid' festlegen.
settings.ui.desktop.subscription_list.description
string Jeglicher Text, der im Zahlungsportal oberhalb der Liste der verfügbaren Abo-Modelle angezeigt werden soll.
settings.ui.desktop.subscription_list.display_local_price
boolean Falls als Wert 'true' festgelegt ist und falls die Landeswährung des Benutzers sich von der für das Abo-Modell festgelegten Währung unterscheidet, werden dem Benutzer beide Preise angezeigt: Einer in der Landes- und der andere in der Basiswährung.
settings.ui.desktop.virtual_item_list
object Einstellungen zur Liste der virtuellen Gegenstände (Objekt).
settings.ui.desktop.virtual_item_list.layout
string Listenvorlage. Als Wert lässt sich entweder 'list' (voreingestellt) oder 'grid' festlegen.
settings.ui.desktop.virtual_item_list.button_with_price
boolean Falls als Wert 'true' festgelegt ist, wird der Preis auf der Schaltfläche angezeigt. Falls 'false' festgelegt ist, wird der Preis links neben der Schaltfläche angezeigt. Standardwert ist 'false'.
settings.ui.desktop.virtual_item_list.view
string Virtuelle Gruppe an Elementen in vertikalem/horizontalem Menü anzeigen. Es kann 'horizontal_navigation' oder 'vertical' (Standard) sein.
settings.ui.desktop.virtual_currency_list
object Einstellungen zur Liste der virtuellen Währungen (Objekt).
settings.ui.desktop.virtual_currency_list.description
string Jeglicher Text, zur Anzeige oberhalb der Liste der virtuellen Währungen.
settings.ui.desktop.virtual_currency_list.button_with_price
boolean Falls als Wert 'true' festgelegt ist, wird der Preis auf der Schaltfläche angezeigt. Falls 'false' festgelegt ist, wird der Preis links neben der Schaltfläche angezeigt. Standardwert ist 'false'.
settings.ui.header.visible_virtual_currency_balance
boolean Legt fest, ob dieses Element im Zahlungsportal ausgeblendet werden kann. 'true' voreingestellt.
settings.ui.mobile.mode
string Ein Benutzer kann nur mit seinen gespeicherten Zahlungsarten bezahlen. Als Wert lässt sich lediglich 'saved_accounts' festlegen.
settings.ui.mobile.header.close_button
boolean Legt fest, ob eine Schaltfläche zum Schließen in der mobilen Version der Bezahlstation angezeigt wird. Bei Betätigung der Schaltfläche wird die Bezahlstation geschlossen und der Benutzer zur, im Parameter 'settings.return_url' festgelegten URL weitergeleitet. Standardwert ist 'false'.
boolean Legt fest, ob der Footer in der mobilen Version des Zahlungsportals ausgeblendet ist.
settings.ui.license_url
string Link zur EULA.
settings.ui.components
object Menü-Einstellungen (Objekt).
settings.ui.components.virtual_items
object Untermenü "Virtuelle Gegenstände".
settings.ui.components.virtual_items.order
integer Position des Untermenüs im Hauptmenü.
settings.ui.components.virtual_items.hidden
boolean Legt fest, ob das Untermenü angezeigt wird.
settings.ui.components.virtual_items.selected_group
string Gruppe, die nach dem Öffnen der Registerkarte "Virtuelle Gegenstände" angezeigt wird.
settings.ui.components.virtual_items.selected_item
string Gegenstand, der nach dem Öffnen der Registerkarte "Virtuelle Gegenstände" angezeigt wird (SKU des Gegenstands).
settings.ui.components.virtual_currency
object Untermenü "Virtuelle Währung".
settings.ui.components.virtual_currency.custom_amount
boolean Legt fest, ob der Benutzer eine willkürliche Menge der virtuellen Währung im Zahlungsportal eingeben kann.
settings.ui.components.virtual_currency.order
integer Position des Untermenüs im Hauptmenü.
settings.ui.components.virtual_currency.hidden
boolean Legt fest, ob das Untermenü angezeigt wird.
settings.ui.components.subscriptions
object Untermenü "Abo-Modelle" (Objekt).
settings.ui.components.subscriptions.order
integer Position des Untermenüs im Hauptmenü.
settings.ui.components.subscriptions.hidden
boolean Legt fest, ob das Untermenü angezeigt wird.
settings.ui.mode
string Schnittstellenmodus in der Bezahlstation. Als Wert lässt sich lediglich 'user_account' festlegen: Der Header enthält ausschließlich die Navigationsleiste des Benutzerkontos und der Benutzer kann kein Produkt auswählen oder eine Zahlung tätigen. Dieser Modus ist nur in der Desktop-Version verfügbar.
settings.ui.user_account
object Details zum Benutzerkonto (Objekt).
settings.ui.user_account.info
object Seite "Mein Konto".
settings.ui.user_account.info.order
integer Position des Untermenüs im Hauptmenü.
settings.ui.user_account.info.enable
boolean Legt fest, ob das Untermenü angezeigt wird. Standardwert ist 'false'.
settings.ui.user_account.history
object Untermenü "Historie".
settings.ui.user_account.history.order
integer Position des Untermenüs im Hauptmenü.
settings.ui.user_account.history.enable
boolean Legt fest, ob das Untermenü angezeigt wird. Standardwert ist 'false'.
settings.ui.user_account.payment_accounts
object Untermenü "Meine Zahlungskonten".
settings.ui.user_account.payment_accounts.order
integer Position des Untermenüs im Hauptmenü.
settings.ui.user_account.payment_accounts.enable
boolean Legt fest, ob das Untermenü angezeigt wird. Standardwert ist 'false'.
settings.ui.user_account.subscriptions
object Untermenü "Abonnements verwalten".
settings.ui.user_account.subscriptions.order
integer Position des Untermenüs im Hauptmenü.
settings.ui.user_account.subscriptions.enable
boolean Legt fest, ob das Untermenü angezeigt wird. Standardwert ist 'false'.
settings.shipping_enabled
boolean Ob das Formular für die Zustelladresse angezeigt werden soll. Standardwert ist 'false'.
purchase
object Objekt, welches Angaben zum Kauf enthält.
purchase.virtual_currency
object Objekt, welches Angaben zur virtuellen Währung enthält.
purchase.virtual_currency.quantity
float Kaufbetrag in der virtuellen Währung.
purchase.virtual_currency.currency
string Währung, in der das Virtuelle-Währungs-Angebotspaket erworben werden kann und die bei allen Kalkulationen verwendet werden soll.
purchase.virtual_items
object Objekt mit Daten über virtuelle Gegenstände, die erworben werden können.
purchase.virtual_items.currency
string Währung der bezogenen Gegenstände, die bei allen Kalkulationen verwendet werden soll.
purchase.virtual_items.items
array Daten zum Gegenstand (Array).
purchase.virtual_items.items.sku
string ID des Gegenstands.
purchase.virtual_items.items.amount
integer Gegenstandsmenge.
purchase.virtual_items.available_groups
array IDs der Gegenstandsgruppen (Array). Im Zahlungsportal werden lediglich Gegenstände aus der festgelegten Gruppe angezeigt.
purchase.subscription
object Daten zum Abonnement (Objekt).
purchase.subscription.plan_id
string ID des Abo-Modells.
purchase.subscription.operation
string Diese Operationsart kommt beim Abo-Modell des Nutzers zur Anwendung. Zur Änderung des Abo-Modells muss der "change_plan"-Wert übermittelt werden. Sie müssen die ID des neuen Abo-Modells im purchase.subscription.plan_id-Parameter festlegen.
purchase.subscription.product_id
string Produkt-ID.
purchase.subscription.currency
string Währung des Abo-Modells, die bei allen Kalkulationen verwendet werden soll.
purchase.subscription.available_plans
array Abonnement-Modelle (Array), die im Zahlungsportal angezeigt werden sollen.
purchase.subscription.trial_days
integer Probezeitraum in Tagen.
purchase.pin_codes
object Spielschlüssel (Objekt).
purchase.pin_codes.currency
string Währung eines Spielschlüssels innerhalb der Bestellung, die bei allen Kalkulationen verwendet werden soll.
purchase.pin_codes.codes
array Spielschlüssel (Array).
purchase.pin_codes.codes.digital_content
string Im Kundenportal festgelegte Spiel-SKU.
purchase.pin_codes.codes.drm
string Die für die Auslieferung des Spiels verwendete DRM-Plattform. Als Wert lässt sich entweder 'steam', 'playstation', 'xbox', 'uplay', 'origin', 'drmfree', 'gog', 'epicgames', 'nintendo_eshop', 'discord_game_store' oder 'oculus' festlegen. Stellen Sie sicher, dass Sie die benötigten DRM-Plattformen in Ihrem Kundenportal konfiguriert haben. Falls nicht im Token übermittelt, wird dieser Parameter durch den Benutzer im Zahlungsportal ausgewählt.
purchase.pin_codes.upgrade
object Objekt mit den Upgrade-Daten.
purchase.pin_codes.upgrade.id_user_history
integer ID des Eintrags, der Daten über den Benutzer und seine Pakete enthält.
purchase.pin_codes.upgrade.id
integer Upgrade-ID.
purchase.checkout
object Objekt, welches Angaben zur Bezahlung enthält.
purchase.checkout.currency
string Kaufwährung. Währungscode, bestehend aus drei Buchstaben gemäß ISO 4217.
purchase.checkout.amount
float Kaufbetrag.
purchase.description
object Kaufbeschreibung (Objekt).
purchase.description.value
string Allgemeine Kaufbeschreibung, die sich im Zahlungsportal und den E-Mail-Belegen wiederfindet. Um jedes Element einzeln zu übermitteln, verwenden Sie die Parameter des purchase.description.items-Arrays.
purchase.description.items
array of objects Array der Gegenstände.
purchase.description.items.name
string Name des Gegenstands.
purchase.description.items.image_url
string Link zum Gegenstandssymbol.
purchase.description.items.description
string Gegenstandsbeschreibung in der Bestellung.
purchase.description.items.price
object Objekt mit dem Preis des Gegenstands.
purchase.description.items.price.amount
string Preis des Gegenstands.
purchase.description.items.quantity
integer Anzahl der Gegenstände in der Bestellung.
purchase.description.items.is_bonus
boolean Legt fest, ob ein Gegenstand als Bonus verfügbar ist. 'false' ist voreingestellt.
purchase.gift
object Benutzerdaten (Objekt).
purchase.gift.giver_id
string Spender-ID.
purchase.gift.message
string Nachricht vom Spender.
purchase.gift.hide_giver_from_receiver
string Legt fest, ob die Identität des Spenders vor dem Beschenkten geheim gehalten werden soll. Standardwert ist 'true'.
purchase.gift.friends
array Array mit Daten über Freunde.
purchase.gift.friends.id
string ID des Geschenkempfängers.
purchase.gift.friends.name
string E-Mail des Geschenkempfängers.
purchase.gift.friends.email
string E-Mail des Geschenkempfängers.
purchase.coupon_code
object Informationen über einen Rabatt- bzw. Promocode oder Prämien beim Kauf (Objekt).
purchase.coupon_code.value
string Promocode-Wert.
purchase.coupon_code.hidden
boolean Blendet das Feld "Promocode-Wert" im Zahlungsportal aus. Standardmäßig ist 'false' festgelegt.
custom_parameters
object Ihre benutzerdefinierten Parameter, repräsentiert durch eine gültige Reihe von JSON-Objekten bestehend aus Schlüssel-Wert-Paaren.

Falls irgendein Parameter in einem unzulässigen Format oder als falscher Typ versendet wird, wird kein Token ausgegeben. Als Antwort erhalten Sie den HTTP-Statuscode 422 mit einer Fehlerbeschreibung im JSON-Body. Der Parameter extended_message gibt Aufschluss darüber, welche Parameter falsch waren.

{
    "extended_message": {
        "global_errors": [],
        "property_errors": {
            "settings.project_id": [
                "string value found, but an integer is required"
            ]
        }
    }
}

Copy
Full screen
http
  • http
  • curl
  • php
  • C#
  • python
  • ruby
  • java
  • js
Anfrage
POST https://api.xsolla.com/merchant/v2/merchants/{merchant_id}/token

Headers:
  Authorization: Basic <your_authorization_basic_key>
Content-Type: application/json

Body:
  {
  "purchase": {
    "virtual_currency": {
      "quantity": 100
    },
    "virtual_items": {
      "items": [
        {
          "amount": 1,
          "sku": "SKU01"
        }
      ]
    }
  },
  "settings": {
    "currency": "USD",
    "language": "en",
    "project_id": 16184,
    "ui": {
      "components": {
        "virtual_currency": {
          "custom_amount": true
        }
      },
      "desktop": {
        "virtual_item_list": {
          "button_with_price": true,
          "layout": "list"
        }
      },
      "size": "medium"
    }
  },
  "user": {
    "country": {
      "allow_modify": true,
      "value": "US"
    },
    "email": {
      "value": "john.smith@mail.com"
    },
    "id": {
      "value": "user_2"
    },
    "name": {
      "value": "John Smith"
    }
  }
}
curl --request POST \
  --url https://api.xsolla.com/merchant/v2/merchants/{merchant_id}/token \
  --header 'authorization: Basic <your_authorization_basic_key>' \
  --header 'content-type: application/json' \
  --data '{"user":{"id":{"value":"user_2"},"name":{"value":"John Smith"},"email":{"value":"john.smith@mail.com"},"country":{"value":"US","allow_modify":true}},"settings":{"project_id":16184,"currency":"USD","language":"en","ui":{"size":"medium","desktop":{"virtual_item_list":{"layout":"list","button_with_price":true}},"components":{"virtual_currency":{"custom_amount":true}}}},"purchase":{"virtual_currency":{"quantity":100},"virtual_items":{"items":[{"sku":"SKU01","amount":1}]}}}'
<?php

$client = new http\Client;
$request = new http\Client\Request;

$body = new http\Message\Body;
$body->append('{"user":{"id":{"value":"user_2"},"name":{"value":"John Smith"},"email":{"value":"john.smith@mail.com"},"country":{"value":"US","allow_modify":true}},"settings":{"project_id":16184,"currency":"USD","language":"en","ui":{"size":"medium","desktop":{"virtual_item_list":{"layout":"list","button_with_price":true}},"components":{"virtual_currency":{"custom_amount":true}}}},"purchase":{"virtual_currency":{"quantity":100},"virtual_items":{"items":[{"sku":"SKU01","amount":1}]}}}');

$request->setRequestUrl('https://api.xsolla.com/merchant/v2/merchants/{merchant_id}/token');
$request->setRequestMethod('POST');
$request->setBody($body);

$request->setHeaders(array(
  'authorization' => 'Basic <your_authorization_basic_key>',
  'content-type' => 'application/json'
));

$client->enqueue($request)->send();
$response = $client->getResponse();

echo $response->getBody();
var client = new RestClient("https://api.xsolla.com/merchant/v2/merchants/{merchant_id}/token");
var request = new RestRequest(Method.POST);
request.AddHeader("authorization", "Basic <your_authorization_basic_key>");
request.AddHeader("content-type", "application/json");
request.AddParameter("application/json", "{\"user\":{\"id\":{\"value\":\"user_2\"},\"name\":{\"value\":\"John Smith\"},\"email\":{\"value\":\"john.smith@mail.com\"},\"country\":{\"value\":\"US\",\"allow_modify\":true}},\"settings\":{\"project_id\":16184,\"currency\":\"USD\",\"language\":\"en\",\"ui\":{\"size\":\"medium\",\"desktop\":{\"virtual_item_list\":{\"layout\":\"list\",\"button_with_price\":true}},\"components\":{\"virtual_currency\":{\"custom_amount\":true}}}},\"purchase\":{\"virtual_currency\":{\"quantity\":100},\"virtual_items\":{\"items\":[{\"sku\":\"SKU01\",\"amount\":1}]}}}", ParameterType.RequestBody);
IRestResponse response = client.Execute(request);
import http.client

conn = http.client.HTTPSConnection("api.xsolla.com")

payload = "{\"user\":{\"id\":{\"value\":\"user_2\"},\"name\":{\"value\":\"John Smith\"},\"email\":{\"value\":\"john.smith@mail.com\"},\"country\":{\"value\":\"US\",\"allow_modify\":true}},\"settings\":{\"project_id\":16184,\"currency\":\"USD\",\"language\":\"en\",\"ui\":{\"size\":\"medium\",\"desktop\":{\"virtual_item_list\":{\"layout\":\"list\",\"button_with_price\":true}},\"components\":{\"virtual_currency\":{\"custom_amount\":true}}}},\"purchase\":{\"virtual_currency\":{\"quantity\":100},\"virtual_items\":{\"items\":[{\"sku\":\"SKU01\",\"amount\":1}]}}}"

headers = {
    'content-type': "application/json",
    'authorization': "Basic <your_authorization_basic_key>"
    }

conn.request("POST", "/merchant/v2/merchants/{merchant_id}/token", payload, headers)

res = conn.getresponse()
data = res.read()

print(data.decode("utf-8"))
require 'uri'
require 'net/http'

url = URI("https://api.xsolla.com/merchant/v2/merchants/{merchant_id}/token")

http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true
http.verify_mode = OpenSSL::SSL::VERIFY_NONE

request = Net::HTTP::Post.new(url)
request["content-type"] = 'application/json'
request["authorization"] = 'Basic <your_authorization_basic_key>'
request.body = "{\"user\":{\"id\":{\"value\":\"user_2\"},\"name\":{\"value\":\"John Smith\"},\"email\":{\"value\":\"john.smith@mail.com\"},\"country\":{\"value\":\"US\",\"allow_modify\":true}},\"settings\":{\"project_id\":16184,\"currency\":\"USD\",\"language\":\"en\",\"ui\":{\"size\":\"medium\",\"desktop\":{\"virtual_item_list\":{\"layout\":\"list\",\"button_with_price\":true}},\"components\":{\"virtual_currency\":{\"custom_amount\":true}}}},\"purchase\":{\"virtual_currency\":{\"quantity\":100},\"virtual_items\":{\"items\":[{\"sku\":\"SKU01\",\"amount\":1}]}}}"

response = http.request(request)
puts response.read_body
OkHttpClient client = new OkHttpClient();

MediaType mediaType = MediaType.parse("application/json");
RequestBody body = RequestBody.create(mediaType, "{\"user\":{\"id\":{\"value\":\"user_2\"},\"name\":{\"value\":\"John Smith\"},\"email\":{\"value\":\"john.smith@mail.com\"},\"country\":{\"value\":\"US\",\"allow_modify\":true}},\"settings\":{\"project_id\":16184,\"currency\":\"USD\",\"language\":\"en\",\"ui\":{\"size\":\"medium\",\"desktop\":{\"virtual_item_list\":{\"layout\":\"list\",\"button_with_price\":true}},\"components\":{\"virtual_currency\":{\"custom_amount\":true}}}},\"purchase\":{\"virtual_currency\":{\"quantity\":100},\"virtual_items\":{\"items\":[{\"sku\":\"SKU01\",\"amount\":1}]}}}");
Request request = new Request.Builder()
  .url("https://api.xsolla.com/merchant/v2/merchants/{merchant_id}/token")
  .post(body)
  .addHeader("content-type", "application/json")
  .addHeader("authorization", "Basic <your_authorization_basic_key>")
  .build();

Response response = client.newCall(request).execute();
var data = JSON.stringify({
  "user": {
    "id": {
      "value": "user_2"
    },
    "name": {
      "value": "John Smith"
    },
    "email": {
      "value": "john.smith@mail.com"
    },
    "country": {
      "value": "US",
      "allow_modify": true
    }
  },
  "settings": {
    "project_id": 16184,
    "currency": "USD",
    "language": "en",
    "ui": {
      "size": "medium",
      "desktop": {
        "virtual_item_list": {
          "layout": "list",
          "button_with_price": true
        }
      },
      "components": {
        "virtual_currency": {
          "custom_amount": true
        }
      }
    }
  },
  "purchase": {
    "virtual_currency": {
      "quantity": 100
    },
    "virtual_items": {
      "items": [
        {
          "sku": "SKU01",
          "amount": 1
        }
      ]
    }
  }
});

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

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

xhr.open("POST", "https://api.xsolla.com/merchant/v2/merchants/{merchant_id}/token");
xhr.setRequestHeader("content-type", "application/json");
xhr.setRequestHeader("authorization", "Basic <your_authorization_basic_key>");

xhr.send(data);
Antwort
{
  "token": "eop57k1boA7nnYPtewZ6KEXJyJADEwRT"
}
{
  "token": "eop57k1boA7nnYPtewZ6KEXJyJADEwRT"
}
{
  "token": "eop57k1boA7nnYPtewZ6KEXJyJADEwRT"
}
{
  "token": "eop57k1boA7nnYPtewZ6KEXJyJADEwRT"
}
{
  "token": "eop57k1boA7nnYPtewZ6KEXJyJADEwRT"
}
{
  "token": "eop57k1boA7nnYPtewZ6KEXJyJADEwRT"
}
{
  "token": "eop57k1boA7nnYPtewZ6KEXJyJADEwRT"
}
{
  "token": "eop57k1boA7nnYPtewZ6KEXJyJADEwRT"
}

Liste der zusätzlichen Parameter

Sie können zusätzliche Parameter innerhalb des Token im custom_parameters-Objekt übergeben, um Filter zur Betrugsbekämpfung zu konfigurieren. Die empfohlenen Parameter sind in der nachfolgenden Tabelle aufgeführt. Sie können die Liste beliebig erweitern.

Siehe Anleitung

Parameter Typ Beschreibung
registration_date
string Datum der Kontoerstellung gemäß ISO 8601.
total_hours
integer Gesamtzahl der Spielstunden.
total_characters
integer Anzahl der Charaktere im Spiel.
social_networks_added
boolean Filtert danach, ob der Spieler Profile von sozialen Netzwerken verknüpft hat.
profile_image_added
boolean Filtert danach, ob der Spieler ein Profilbild hochgeladen hat.
active_date
string Letztmalig online; Datum gemäß ISO 8601.
total_friends
integer Anzahl der Freunde.
additional_verification
boolean Filtert danach, ob der Spieler Konto-Verifikationsverfahren verwendet.
win_rate
integer Gewinnquote.
last_change_password_date
string Datum der letzten Kennwortänderung; Datumsangabe gemäß ISO 8601.
chat_activity
boolean Filtert danach, ob der Spieler die Chatfunktion verwendet.
forum_activity
boolean Filtert danach, ob der Spieler die Chatfunktion verwendet.
total_bans
integer Filtert danach, wie oft der Spieler im Chat/Forum gesperrt wurde.
profile_completed
boolean Filtert danach, ob der Spieler auf seinem Profil zusätzliche Informationen hinzugefügt hat.
notifications_enabled
boolean Filtert danach, ob der Spieler den Erhalt von Benachrichtigungen aktiviert hat.
user_level
integer Level, Ansehen oder Rang des Spielers.
karma_points
integer Karma des Spielers.
total_sum
float Gesamtbetrag der Zahlungen.
non_premium_currency
float Betrag der gewöhnlichen ("non-premium") Währung.
total_game_events
integer Anzahl der Ingame-Events, an denen der Spieler teilgenommen hat.
total_gifts
integer Anzahl der Geschenke im Spiel, die der Spieler verschickt/erhalten hat.
tutorial_completed
boolean Filtert danach, ob der Spieler das Tutorial des Spiels absolviert hat.
completed_tasks
integer Anzahl der erledigten Aufgaben bzw. erreichten Ziele.
items_used
boolean Filtert danach, ob der Spieler im Spiel gekaufte Gegenstände verwendet.
pvp_activity
boolean Filtert danach, ob der Spieler an PvP-Schlachten teilnimmt.
total_clans
integer Anzahl der Clans, bei denen der Spieler Mitglied ist.
unlocked_achievements
integer Anzahl an freigeschalteten Errungenschaften.
total_inventory_value
float Gesamtwert des Inventars (in Ingame-Währung).
character_customized
boolean Filtert danach, ob der Spieler seinen Charakter individuell angepasst hat.
session_time
string Durchschnittliche Sitzungsdauer, Angabe gemäß ISO 8601.

Webhooks

Überblick

Webhooks ermöglichen Ihnen den Empfang von Ereignismeldungen, die Ihre Xsolla-Transaktionen betreffen. Nutzen Sie Webhooks, um Funktionen im Back-End und zusätzliche Funktionen zu automatisieren, z. B. das Bereitstellen von Statusinformationen und anderen,transaktionsbezogenen Informationen.

Wir nutzen Webhooks für:

  • Zahlungen, einschließlich dem Erwerb von virtuellen Währungen und Gegenständen, Kartenzahlungen, usw
  • Wiederkehrende Zahlungen und Abonnementzahlungen
  • Transaktionsbezogene Rückbuchungen/Rückerstattungen

In den meisten Fällen werden Webhooks durch Benutzeraktionen auf Ihrer Website ausgelöst. Jedoch können sie auch durchandere Aktionen hervorgerufen werden. Beispielsweise kann ein Back-End-Prozess auf Ihrer Website eine API-Methode aufrufen, um eine Zahlung zu erstatten,oder das Zahlungssystem kann eine Benachrichtigung über eine widersprüchliche Abbuchung versenden.

Sie müssen einen sogenannten "Listener" oder "Handler" programmieren oder verwenden, um Webhooks empfangen und verarbeiten zu können. Hierbei handelt es sich um ein Programm, das auf einen Webhook wartet und diesen in der Regel an eine Ihrer internen Behandlungsroutinen weiterleitet, welche entsprechend reagiert.

Beispielsweise können Sie nach dem Erhalt eines Webhooks folgendes ausführen:

  • Guthaben eines Benutzers aufladen
  • Einem Benutzer einen Gegenstand übergeben
  • Ein Abonnement aktivieren
  • Einen Benutzer blockieren, der betrügerische Handlungen durchführt oder durchgeführt hat, usw

Webhooks können über folgende IP-Adressen empfangen werden: 185.30.20.0/24, 185.30.21.0/24

Beachten Sie, dass Ihre Datenbank KEINE zwei erfolgreichen Transaktionen mit derselben Kennung enthalten darf. Falls Ihr Listener einen Webhook mit einer bereits vorhandenen Transaktions-ID empfängt,muss er das letzte Ergebnis für diese Transaktion als Antwort zurückgeben. Vermeiden Sie es, dem Benutzer etwas doppelt zu berechnen oder doppelte Datensätze in Ihrer Datenbank zu erstellen.

Wir können nicht garantieren, dass Ihr Listener alle von uns versendeten Webhooks empfangen kann. Da Internetverbindungen nicht hundertprozentig verlässlich sind, kann es vorkommen, dass Webhooks überhaupt nicht oder nicht rechtzeitig empfangen werden. Um solche Probleme zu beheben, stellen wir einen Wiederholungsmechanismusbereit, der nicht übermittelte Nachrichten in verschiedenen Zeitabständen erneut versendet, bis Ihr Listener den Empfang bestätigt. Ein Webhook kanninnerhalb von 12 Stunden, nachdem der vorhergehende Webhook versendet wurde, nochmals gesendet werden. Maximal werden 12 Wiederholungen ausgeführt.

Note: Obwohl Verbindungsprobleme zu Verlust, Verzögerung oder zum Duplizieren von Webhooks führen können Ist die häufigste Ursache eine fehlerhafte Logik im Listener selbst.

Signaturanfragen

Digitale Signaturen ermöglichen eine sichere Datenübertragung. (1) verknüpfen Sie den JSON-Body der Anfrage mit dem geheimen Schlüssel Ihres Projekts und (2) wenden Sie die SHA-1-Algorithmus auf den sich ergebenden String anwenden.

Stellen Sie sicher, dass die erstellte Signatur mit der im HTTP-Header übergebenen übereinstimmt.

Copy
Full screen
http
  • http
  • curl
Anfrage
POST /your_uri HTTP/1.1
Host: your.host
Accept: application/json
Content-Type: application/json
Content-Length: 165
Authorization: Signature 52eac2713985e212351610d008e7e14fae46f902

{"notification_type":"user_validation","user":{"ip":"127.0.0.1","phone":"18777976552","email":"email@example.com","id":1234567,"name":"Xsolla User","country":"US"}}
$curl -v 'https://your.hostname/your/uri' \
-X POST \
-H 'Authorization: Signature 52eac2713985e212351610d008e7e14fae46f902' \
-d '{"notification_type":"user_validation","user":{"ip":"127.0.0.1","phone":"18777976552","email":"email@example.com","id":1234567,"name":"Xsolla User","country":"US"}}'

Statuscodes

Xsolla-API akzeptiert konventionelle HTTP-Statuscodes für erfolgreiche und fehlgeschlagene Anfragen. Der Code 204 weist auf eine erfolgreiche Verarbeitung hin. Versenden Sie den Code 400 im Falle Nutzen Sie den Code 500, um auf temporäre Probleme mit Ihren Servern hinzuweisen.

Liste der Webhooks

Die Art der Benachrichtigung wird versendet als _notificationtype Parameter.

Art der Benachrichtigung Beschreibung
user_validation Überprüft, ob ein Benutzer im Spiel bereits vorhanden ist.
user_search Fordert Benutzerdaten anhand der Public User ID an.
payment Wird versendet, wenn ein Benutzer eine Zahlung abschließt.
refund Wird versendet, falls eine Zahlung aus einem beliebigen Grund storniert werden muss.
afs_reject Wird versendet, wenn eine Transaktion während einer AFS-Prüfung abgelehnt wird, sendet Xsolla Transaktionsdaten an den URL-Webhook.
create_subscription Wird versendet, wenn ein Benutzer ein Abonnement abschließt.
update_subscription Wird versendet, wenn ein Abonnement erneuert oder geändert wird.
cancel_subscription Wird versendet, wenn ein Abonnement gekündigt wird.
get_pincode Wird versendet, wenn die Xsolla-API den Spielschlüssel abrufen möchte.
user_balance_operation Wird versendet, wenn sich der Kontostand eines Benutzers ändert (die Änderungsart wird versendet als _operationtype).
redeem_key Wird gesendet, wenn ein Benutzer einen Schlüssel aktiviert.
upgrade_refund Wird bei Stornierung des Upgrades versendet.
inventory_get Gegenstandsliste aus dem Spielinventar abrufen und an Sekundärmarkt übermitteln.
inventory_pull Gegenstände aus dem Spielinventar an den Sekundärmarkt pullen.
inventory_push Gegenstände vom Sekundärmarkt in das Spielinventar pushen.

Benutzervalidierung

Wird versendet, um zu verifizieren, dass ein Benutzer im Spiel vorhanden ist.

Parameter Typ Beschreibung
user
object Benutzerdaten (Objekt).
user.ip
string Benutzer-IP.
user.phone
string Telefonnummer des Benutzers.
user.email
string E-Mail des Benutzers.
user.id
string Benutzer-ID. Erforderlich.
user.name
string Benutzername.
user.country
string Land des Benutzers. Ländercode, bestehend aus 2 Großbuchstaben gemäß ISO 3166-1 ALPHA-2.
Copy
Full screen
php
  • php
  • http
  • curl
Anfrage
<?php

$request = array(
    'notification_type' => 'user_validation',
    'user' => array(
        'ip' => '127.0.0.1',
        'phone' => '18777976552',
        'email'=> 'email@example.com',
        'id'=> '1234567',
        'country' => 'US'
    )
);
POST /your/uri HTTP/1.1
Host: your.hostname
Accept: application/json
Content-Type: application/json
Content-Length: 240
Authorization: Signature 13342703ccaca5064ad33ba451d800c5e823db8f

{
    "notification_type":"user_validation",
    "user": {
        "ip": "127.0.0.1",
        "phone": "18777976552",
        "email": "email@example.com",
        "id": "1234567",
        "name": "Xsolla User",
        "country": "US"
    }
}
$ curl -v 'https://your.hostname/your/uri' \
-X POST \
-H 'Accept: application/json' \
-H 'Content-Type: 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",
        "name": "Xsolla User",
        "country": "US"
    }
}'
Antwort
<?php

use Xsolla\SDK\Webhook\WebhookServer;
use Xsolla\SDK\Webhook\Message\Message;
use Xsolla\SDK\Exception\Webhook\XsollaWebhookException;

$callback = function (Message $message) {
    if ($message->isUserValidation()) {
       $userArray = $message->getUser();
       $userId = $message->getUserId();
       $messageArray = $message->toArray();
       //TODO if user not found, you should throw InvalidUserException
    }
};

$webhookServer = WebhookServer::create($callback, PROJECT_KEY);
$webhookServer->start();
HTTP/1.1 204 No Content
Wird versendet, um Benutzerdaten mittels Public User ID abzurufen.Die Public User ID ist ein Parameter, durch den der Benutzer eindeutig identifizierbar ist und der dem Benutzer bekannt ist (E-Mail, Benutzername, usw.). Gestattet dem Benutzer, Käufe außerhalb des Game-Stores zu tätigen (z. B. via Verkaufsterminals).

Parameter Typ Beschreibung
notification_type
string Art der Benachrichtigung. Erforderlich.
user
object Benutzerdaten (Objekt). Erforderlich.
user.public_id
string Public User ID.
user.id
string Benutzer-ID.
Copy
Full screen
php
  • php
  • http
  • curl
Anfrage
<?php

$request = array(
    'notification_type' => 'user_search',
    'user' => array(
        'public_id' => 'public_email@example.com'
    )
);
POST /your/uri HTTP/1.1
Host: your.hostname
Accept: application/json
Content-Type: application/json
Content-Length: 240
Authorization: Signature 13342703ccaca5064ad33ba451d800c5e823db8f

{
    "notification_type":"user_search",
    "user": {
        "public_id": "public_email@example.com"
    }
}
$ curl -v 'https://your.hostname/your/uri' \
-X POST \
-H 'Accept: application/json' \
-H 'Content-Type: application/json' \
-H 'Authorization: Signature 13342703ccaca5064ad33ba451d800c5e823db8f' \
-d '{
    "notification_type":"user_search",
    "user": {
        "public_id": "public_email@example.com"
    }
}'
Antwort
<?php

use Xsolla\SDK\Webhook\WebhookServer;
use Xsolla\SDK\Webhook\Message\Message;

$callback = function (Message $message) {
    if ($message instanceof \Xsolla\SDK\Webhook\Message\UserSearchMessage) {
        $userArray = $message->getUser();
        $userPublicId = $message->getUserPublicId();
        // TODO get a user from your database and fill the user data to model.
        $user = new \Xsolla\SDK\Webhook\User();
        $user->setId('user_id')
            ->setPublicId($userPublicId)
            ->setEmail('user_email') //Optional field
            ->setPhone('user_phone') //Optional field
            ->setName('user_name'); //Optional field
        //TODO if user not found, you should throw InvalidUserException
        return new \Xsolla\SDK\Webhook\Response\UserResponse($user);
    }
};
$webhookServer = WebhookServer::create($callback, PROJECT_KEY);
$webhookServer->start();
HTTP/1.1 200 OK
Content-Type: application/json

{
    "user": {
        "public_id": "public_email@example.com",
        "phone": "18777976552",
        "email": "email@example.com",
        "id": "1234567",
        "name": "Xsolla User"
    }
}
{
    "user": {
        "public_id": "public_email@example.com",
        "phone": "18777976552",
        "email": "email@example.com",
        "id": "1234567",
        "name": "Xsolla User"
    }
}

Zahlung

Wird versendet, wenn ein Benutzer eine Zahlung abschließt. Enthält Zahlungsdaten.

Parameter Typ Beschreibung
notification_type
string Art der Benachrichtigung. Erforderlich.
purchase
object Objekt, welches Angaben zum Kauf enthält.
purchase.virtual_currency
object Zu erwerbende virtuelle Währung (Objekt).
purchase.virtual_currency.name
string Name der virtuellen Währung.
purchase.virtual_currency.sku
string SKU des virtuellen Währungspakets (falls für das Angebotspaket festgelegt).
purchase.virtual_currency.quantity
float Menge.
purchase.virtual_currency.currency
string Kaufwährung. Währungscode, bestehend aus drei Buchstaben gemäß ISO 4217.
purchase.virtual_currency.amount
float Preis in echter Währung.
purchase.checkout
object Objekt, welches Angaben zur Bezahlung enthält.
purchase.checkout.currency
string Kaufwährung. Währungscode, bestehend aus drei Buchstaben gemäß ISO 4217.
purchase.checkout.amount
float Kaufbetrag.
purchase.subscription
object Angaben zum Abonnement (Objekt).
purchase.subscription.plan_id
string ID des Abo-Modells (extern, falls das Abo-Modell über die API angelegt wurde).
purchase.subscription.subscription_id
integer In der Xsolla-Datenbank erfasste Abonnement-ID.
purchase.subscription.product_id
string Produkt-ID (falls sie im Zugriffstoken versendet wurde).
purchase.subscription.tags
array Abo-Modell-Markierungen.
purchase.subscription.date_create
string Datum, an dem das Abonnement abgeschlossen wurde. Datums- und Zeitangabe gemäß ISO 8601.
purchase.subscription.date_next_charge
string Nächstes Rechnungsdatum. Datums- und Zeitangabe gemäß ISO 8601.
purchase.subscription.currency
string Währung, in welcher das Abonnement erworben wird. Währungscode, bestehend aus drei Buchstaben gemäß ISO 4217.
purchase.subscription.amount
float Preis in echter Währung.
purchase.virtual_items
object Die beim Kauf erworbenen virtuellen Gegenstände.
purchase.virtual_items.items
array Daten zum Gegenstand (Array).
purchase.virtual_items.items.sku
string ID des Gegenstands.
purchase.virtual_items.items.amount
integer Gegenstandsmenge.
purchase.virtual_items.currency
string Kaufwährung. Währungscode, bestehend aus drei Buchstaben gemäß ISO 4217.
purchase.virtual_items.amount
integer Kaufbetrag.
purchase.pin_codes
object Spielschlüssel (Array).
purchase.pin_codes.digital_content
string Im Kundenportal festgelegte Spiel-SKU.
purchase.pin_codes.drm
string Die für die Auslieferung des Spiels verwendete DRM-Plattform. Als Wert lässt sich entweder 'steam', 'playstation', 'xbox', 'uplay', 'origin', 'drmfree', 'gog', 'epicgames', 'nintendo_eshop', 'discord_game_store' oder 'oculus' festlegen. Stellen Sie sicher, dass Sie die benötigten DRM-Plattformen in Ihrem Kundenportal konfiguriert haben.
purchase.pin_codes.currency
string Währung, mit welcher der Spielschlüssel erworben wird. Währungscode, bestehend aus drei Buchstaben gemäß ISO 4217.
purchase.pin_codes.amount
float Preis.
purchase.pin_codes.upgrade
object Objekt mit Upgrade-Daten.
purchase.pin_codes.upgrade.digital_content_from
object Objekt mit Daten über das Paket, von dem aus der Benutzer ein Upgrade durchgeführt hat.
purchase.pin_codes.upgrade.digital_content_from.digital_content
string Im Kundenportal festgelegte Spiel-SKU.
purchase.pin_codes.upgrade.digital_content_from.DRM
string DRM-Plattform des Spiels.
purchase.pin_codes.upgrade.digital_content_to
object Objekt mit Daten über das Paket, auf das der Benutzer ein Upgrade durchgeführt hat.
purchase.pin_codes.upgrade.digital_content_to.digital_content
string Im Kundenportal festgelegte Spiel-SKU.
purchase.pin_codes.upgrade.digital_content_to.DRM
string DRM-Plattform des Spiels.
purchase.pin_codes.upgrade.currency
string Kaufwährung. Währungscode, bestehend aus drei Buchstaben gemäß ISO 4217.
purchase.pin_codes.upgrade.amount
float Preis in echter Währung.
purchase.gift
object Benutzerdaten (Objekt).
purchase.gift.giver_id
string Spender-ID.
purchase.gift.receiver_id
string ID des Geschenkempfängers.
purchase.gift.receiver_email
string E-Mail des Geschenkempfängers.
purchase.gift.message
string Nachricht vom Spender.
purchase.gift.hide_giver_from_receiver
string Legt fest, ob die Identität des Spenders vor dem Beschenkten geheim gehalten werden soll.
purchase.total
object Gesamtpreis des Einkaufs (Objekt). Erforderlich.
purchase.total.currency
string Kaufwährung. Währungscode, bestehend aus drei Buchstaben gemäß ISO 4217.
purchase.total.amount
float Gesamtbetrag der Zahlung.
purchase.promotions
array Werbeaktionen, die bei dieser Transaktion Verwendung finden.
purchase.promotions.technical_name
string Arbeitstitel der Werbeaktion.
purchase.promotions.id
integer ID der Werbeaktion.
purchase.coupon
object Angaben zum Gutschein (Objekt; falls ein Gutschein bei Abschluss des Abonnements genutzt wurde).
purchase.coupon.coupon_code
string Gutscheincode.
purchase.coupon.campaign_code
string Kampagne.
user
object Benutzerdaten (Objekt).
user.ip
string Benutzer-IP.
user.phone
string Telefonnummer des Benutzers.
user.email
string E-Mail des Benutzers.
user.id
string Benutzer-ID. Erforderlich.
user.name
string Benutzername.
user.country
string Land des Benutzers. Ländercode, bestehend aus 2 Großbuchstaben gemäß ISO 3166-1 ALPHA-2.
user.zip
string Postleitzahl.
transaction
object Details zur Transaktion (Objekt). Erforderlich.
transaction.id
integer ID der Transaktion.
transaction.external_id
string Externe ID der Transaktion.
transaction.payment_date
string Zahlungsdatum.
transaction.payment_method
integer ID der Zahlungsart.
transaction.dry_run
integer Transaktion zur Testzwecken. 1 falls es sich um eine testweise durchgeführte Transaktion handelt, ansonsten 0.
transaction.agreement
integer ID der Vereinbarung.
payment_details
object Zahlungsdaten (Objekt). Erforderlich.
payment_details.payment
object Vom Benutzer entrichteter Betrag (Objekt).
payment_details.payment.currency
string Währung. Währungscode, bestehend aus drei Buchstaben gemäß ISO 4217.
payment_details.payment.amount
string Betrag.
payment_details.payment_method_sum
object Betrag, der vom Zahlungssystem abgebucht wird.
payment_details.payment_method_sum.currency
string Währung. Währungscode, bestehend aus drei Buchstaben gemäß ISO 4217.
payment_details.payment_method_sum.amount
string Betrag.
payment_details.xsolla_balance_sum
object Betrag, der vom Xsolla-Konto abgebucht wird.
payment_details.xsolla_balance_sum.currency
string Währung. Währungscode, bestehend aus drei Buchstaben gemäß ISO 4217.
payment_details.xsolla_balance_sum.amount
string Betrag.
payment_details.payout
object Details zur Auszahlung (Objekt).
payment_details.payout.currency
string Währung. Währungscode, bestehend aus drei Buchstaben gemäß ISO 4217.
payment_details.payout.amount
float Betrag.
payment_details.vat
object Angaben zur MwSt. (Objekt, nur in der EU).
payment_details.vat.currency
string Währung. Währungscode, bestehend aus drei Buchstaben gemäß ISO 4217.
payment_details.vat.amount
float Betrag.
payment_details.payout_currency_rate
float Wechselkurs zwischen Zahlungs- und Auszahlungswährung.
payment_details.xsolla_fee
object Xsolla-Gebühr (Objekt).
payment_details.xsolla_fee.currency
string Währung. Währungscode, bestehend aus drei Buchstaben gemäß ISO 4217.
payment_details.xsolla_fee.amount
float Betrag.
payment_details.payment_method_fee
object Gebühren des Zahlungssystems.
payment_details.payment_method_fee.currency
string Währung. Währungscode, bestehend aus drei Buchstaben gemäß ISO 4217.
payment_details.payment_method_fee.amount
float Betrag.
payment_details.sales_tax
object Sales Tax (Objekt; nur in den USA).
payment_details.sales_tax.currency
string Währung. Währungscode, bestehend aus drei Buchstaben gemäß ISO 4217.
payment_details.sales_tax.amount
float Betrag.
payment_details.repatriation_commission
object Objekt mit Daten über die Rückübertragungskosten, die Xsolla von Dritten auferlegt wurden.
payment_details.repatriation_commission.currency
string Währung der Rückübertragungskosten. Währungscode, bestehend aus drei Buchstaben gemäß ISO 4217.
payment_details.repatriation_commission.amount
float Betrag der Rückübertragungskosten.
custom_parameters
object Ihre benutzerdefinierten Parameter.
Copy
Full screen
php
  • php
  • http
  • curl
Anfrage
<?php

$request = array(
    'notification_type' => 'payment',
    '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
    ),
    '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
        ),
        'repatriation_commission' => array(
            'currency' => 'USD',
            'amount' => 0.2
        )
    )
);
POST /your_uri HTTP/1.1
Host: your.host
Accept: application/json
Content-Type: application/json
Content-Length: 1721
Authorization: Signature 34553d151e656110c656696c919f9a10e05de542

{
    "notification_type":"payment",
    "purchase":{
        "virtual_currency":{
            "name":"Coins",
            "sku":"test_package1",
            "quantity":10,
            "currency":"USD",
            "amount":100
        },
        "subscription":{
            "plan_id": "b5dac9c8",
            "subscription_id": "10",
            "product_id": "Demo Product",
            "date_create": "2014-09-22T19:25:25+04:00",
            "date_next_charge": "2014-10-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
        },
        "promotions":[{
            "technical_name":"Demo Promotion",
            "id":"853"
        }],
        "coupon":{
            "coupon_code":"ICvj45S4FUOyy",
            "campaign_code":"1507"
        }
    },
    "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,
        "payment_date":"2014-09-24T20:38:16+04:00",
        "payment_method":1,
        "dry_run":1,
        "agreement":1
    },
    "payment_details":{
        "payment":{
            "currency":"USD",
            "amount":230
        },
        "vat": {
            "currency": "USD",
            "amount": 0
        },
        "payout_currency_rate": 1,
        "payout":{
            "currency":"USD",
            "amount":200
        },
        "xsolla_fee":{
            "currency":"USD",
            "amount":10
        },
        "payment_method_fee":{
            "currency":"USD",
            "amount":20
        },
        "repatriation_commission":{
            "currency":"USD",
            "amount":"10"
        }
    },
    "custom_parameters":{
        "parameter1":"value1",
        "parameter2":"value2"
    }
}
$curl -v 'https://your.hostname/your/uri' \
-X POST \
-d '{
    "notification_type":"payment",
    "purchase":{
        "virtual_currency":{
            "name":"Coins",
            "sku":"test_package1",
            "quantity":10,
            "currency":"USD",
            "amount":100
        },
        "subscription":{
            "plan_id": "b5dac9c8",
            "subscription_id": "10",
            "product_id": "Demo Product",
            "date_create": "2014-09-22T19:25:25+04:00",
            "date_next_charge": "2014-10-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
        },
        "promotions":[{
            "technical_name":"Demo Promotion",
            "id":"853"
        }],
        "coupon":{
             "coupon_code":"ICvj45S4FUOyy",
             "campaign_code":"1507"
        }
    },
    "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,
        "payment_date":"2014-09-24T20:38:16+04:00",
        "payment_method":1,
        "dry_run":1,
        "agreement":1
    },
    "payment_details":{
        "payment":{
            "currency":"USD",
            "amount":230
        },
        "vat": {
            "currency": "USD",
            "amount": 0
        },
        "payout_currency_rate": 1,
        "payout":{
            "currency":"USD",
            "amount":200
        },
        "xsolla_fee":{
            "currency":"USD",
            "amount":10
        },
        "payment_method_fee":{
            "currency":"USD",
            "amount":20
        },
        "repatriation_commission":{
            "currency":"USD",
            "amount":"10"
        }
    },
    "custom_parameters":{
        "parameter1":"value1",
        "parameter2":"value2"
    }
}'
Antwort
<?php

use Xsolla\SDK\Webhook\WebhookServer;
use Xsolla\SDK\Webhook\Message\Message;
use Xsolla\SDK\Exception\Webhook\XsollaWebhookException;

$callback = function (Message $message) {
    if ($message->isPayment()) {
        $userArray = $message->getUser();
        $paymentArray = $message->getTransaction();
        $paymentId = $message->getPaymentId();
        $externalPaymentId = $message->getExternalPaymentId();
        $paymentDetailsArray = $message->getPaymentDetails();
        $customParametersArray = $message->getCustomParameters();
        $isDryRun = $message->isDryRun();
        $messageArray = $message->toArray();
        // TODO if the payment delivery fails for some reason, you should throw XsollaWebhookException
    }
};

$webhookServer = WebhookServer::create($callback, PROJECT_KEY);
$webhookServer->start();
HTTP/1.1 204 No Content

Rückerstattung

Wird immer dann versendet, wenn eine Zahlung storniert wird. Enthält Zahlungsdaten.

Parameter Typ Beschreibung
notification_type
string Art der Benachrichtigung. Erforderlich.
purchase
object Objekt, welches Angaben zum Kauf enthält.
purchase.virtual_currency
object Zu erwerbende virtuelle Währung (Objekt).
purchase.virtual_currency.name
string Name der virtuellen Währung.
purchase.virtual_currency.quantity
float Menge.
purchase.virtual_currency.currency
string Kaufwährung. Währungscode, bestehend aus drei Buchstaben gemäß ISO 4217.
purchase.virtual_currency.amount
float Preis in echter Währung.
purchase.checkout
object Objekt, welches Angaben zur Bezahlung enthält.
purchase.checkout.currency
string Kaufwährung. Währungscode, bestehend aus drei Buchstaben gemäß ISO 4217.
purchase.checkout.amount
float Kaufbetrag.
purchase.subscription
object Angaben zum Abonnement (Objekt).
purchase.subscription.plan_id
string ID des Abo-Modells (extern, falls das Abo-Modell über die API angelegt wurde).
purchase.subscription.tags
array Abo-Modell-Markierungen.
purchase.subscription.subscription_id
integer In der Xsolla-Datenbank erfasste Abonnement-ID.
purchase.subscription.date_create
string Datum, an dem das Abonnement abgeschlossen wurde. Datums- und Zeitangabe gemäß ISO 8601.
purchase.subscription.currency
string Währung, in welcher das Abonnement erworben wird. Währungscode, bestehend aus drei Buchstaben gemäß ISO 4217.
purchase.subscription.amount
float Preis in echter Währung.
purchase.virtual_items
object Die beim Kauf erworbenen virtuellen Gegenstände.
purchase.virtual_items.items
array Daten zum Gegenstand (Array).
purchase.virtual_items.items.sku
string ID des Gegenstands.
purchase.virtual_items.items.amount
integer Gegenstandsmenge.
purchase.virtual_items.currency
string Kaufwährung. Währungscode, bestehend aus drei Buchstaben gemäß ISO 4217.
purchase.virtual_items.amount
integer Kaufbetrag.
purchase.pin_codes
object Spielschlüssel (Objekt).
purchase.pin_codes.upgrade
object Objekt mit Upgrade-Daten.
purchase.pin_codes.upgrade.digital_content_from
object Objekt mit Daten über das Paket, von dem aus der Benutzer ein Upgrade durchgeführt hat.
purchase.pin_codes.upgrade.digital_content_from.digital_content
string Im Kundenportal festgelegte Spiel-SKU.
purchase.pin_codes.upgrade.digital_content_from.DRM
string DRM-Plattform des Spiels.
purchase.pin_codes.upgrade.digital_content_to
object Objekt mit Daten über das Paket, auf das der Benutzer ein Upgrade durchgeführt hat.
purchase.pin_codes.upgrade.digital_content_to.digital_content
string Im Kundenportal festgelegte Spiel-SKU.
purchase.pin_codes.upgrade.digital_content_to.DRM
string DRM-Plattform des Spiels.
purchase.pin_codes.upgrade.currency
string Kaufwährung. Währungscode, bestehend aus drei Buchstaben gemäß ISO 4217.
purchase.pin_codes.upgrade.amount
float Preis in echter Währung.
purchase.total
object Gesamtpreis des Einkaufs (Objekt).
purchase.total.currency
string Kaufwährung. Währungscode, bestehend aus drei Buchstaben gemäß ISO 4217.
purchase.total.amount
float Gesamtbetrag der Zahlung.
user
object Benutzerdaten (Objekt).
user.ip
string Benutzer-IP.
user.phone
string Telefonnummer des Benutzers.
user.email
string E-Mail des Benutzers.
user.id
string Benutzer-ID. Erforderlich.
user.name
string Benutzername.
user.country
string Land des Benutzers. Ländercode, bestehend aus 2 Großbuchstaben gemäß ISO 3166-1 ALPHA-2.
user.zip
string Postleitzahl.
transaction
object Details zur Transaktion (Objekt). Erforderlich.
transaction.id
integer ID der Transaktion.
transaction.external_id
string Externe ID der Transaktion.
transaction.dry_run
integer Transaktion zur Testzwecken. 1 falls es sich um eine testweise durchgeführte Transaktion handelt, ansonsten 0.
transaction.agreement
integer ID der Vereinbarung.
refund_details
object Benutzerdaten (Objekt).
refund_details.code
integer Code-ID.
refund_details.reason
string Grund für die Rückerstattung.
refund_details.author
string Initiator der Rückerstattung.
payment_details
object Zahlungsdaten (Objekt). Erforderlich.
payment_details.payment
object Vom Benutzer entrichteter Betrag (Objekt).
payment_details.payment.currency
string Währung. Währungscode, bestehend aus drei Buchstaben gemäß ISO 4217.
payment_details.payment.amount
string Betrag.
payment_details.payment_method_sum
object Betrag, der vom Zahlungssystem abgebucht wird.
payment_details.payment_method_sum.currency
string Währung. Währungscode, bestehend aus drei Buchstaben gemäß ISO 4217.
payment_details.payment_method_sum.amount
string Betrag.
payment_details.xsolla_balance_sum
object Betrag, der vom Xsolla-Konto abgebucht wird.
payment_details.xsolla_balance_sum.currency
string Währung. Währungscode, bestehend aus drei Buchstaben gemäß ISO 4217.
payment_details.xsolla_balance_sum.amount
string Betrag.
payment_details.payout
object Details zur Auszahlung (Objekt).
payment_details.payout.currency
string Währung. Währungscode, bestehend aus drei Buchstaben gemäß ISO 4217.
payment_details.payout.amount
float Betrag.
payment_details.vat
object Angaben zur MwSt. (Objekt, nur in der EU).
payment_details.vat.currency
string Währung. Währungscode, bestehend aus drei Buchstaben gemäß ISO 4217.
payment_details.vat.amount
float Betrag.
payment_details.payout_currency_rate
float Wechselkurs zwischen Zahlungs- und Auszahlungswährung.
payment_details.xsolla_fee
object Xsolla-Gebühr (Objekt).
payment_details.xsolla_fee.currency
string Währung. Währungscode, bestehend aus drei Buchstaben gemäß ISO 4217.
payment_details.xsolla_fee.amount
float Betrag.
payment_details.payment_method_fee
object Gebühren des Zahlungssystems.
payment_details.payment_method_fee.currency
string Währung. Währungscode, bestehend aus drei Buchstaben gemäß ISO 4217.
payment_details.payment_method_fee.amount
float Betrag.
payment_details.sales_tax
object Sales Tax (Objekt; nur in den USA).
payment_details.sales_tax.currency
string Währung. Währungscode, bestehend aus drei Buchstaben gemäß ISO 4217.
payment_details.sales_tax.amount
float Betrag.
payment_details.repatriation_commission
object Objekt mit Daten über die Rückübertragungskosten, die Xsolla von Dritten auferlegt wurden.
payment_details.repatriation_commission.currency
string Währung der Rückübertragungskosten. Währungscode, bestehend aus drei Buchstaben gemäß ISO 4217.
payment_details.repatriation_commission.amount
float Betrag der Rückübertragungskosten.
custom_parameters
object Ihre benutzerdefinierten Parameter.

Codes zur Rückerstattung:

Code Grund Beschreibung
1. Cancellation by the user request / the game request. Aus dem Kundenportal heraus eingeleitete Stornierung.
2. Chargeback. Rückbuchung der Transaktion angefordert.
3. Integration Error. Integrationsprobleme zwischen Xsolla und dem Spiel. Empfehlung: Setzen Sie den Benutzer nicht auf eine schwarze Liste.
4. Fraud. Betrug vermutet.
5. Test Payment. Testweise getätigte Transaktion gefolgt von Stornierung. Empfehlung: Setzen Sie den Benutzer nicht auf eine schwarze Liste.
6. Expired Invoice. Rechnung überfällig (wird bei Postpaid-Zahlungsweise genutzt).
7. PS debt cancel. Auszahlung wurde durch das Zahlungssystem abgelehnt. Empfehlung: Setzen Sie den Benutzer nicht auf eine schwarze Liste.
8. Cancellation by the PS request. Zahlungssystem hat Stornierung angefordert. Empfehlung: Setzen Sie den Benutzer nicht auf eine schwarze Liste.
9. Cancellation by the user request. Der Benutzer war aus irgendeinem Grund nicht zufrieden mit dem Spiel oder dem Einkauf. Empfehlung: Setzen Sie den Benutzer nicht auf eine schwarze Liste.
10. Cancellation by the game request. Das Spiel hat die Stornierung angefordert. Empfehlung: Setzen Sie den Benutzer nicht auf eine schwarze Liste.
11. Account holder called to report fraud. Der Kontoinhaber gibt an, dass die Transaktion nicht von ihm getätigt wurde.
12. Friendly fraud. Es wurde ein "Friendly Fraud" gemeldet.
Copy
Full screen
php
  • php
  • http
  • curl
Anfrage
<?php

$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' => array(
            '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
        ),
        'repatriation_commission' => array(
            'currency' => 'USD',
            'amount' => 0.2
        )
    )
);
POST /your_uri HTTP/1.1
Host: your.host
Accept: application/json
Content-Type: application/json
Content-Length: 1220
Authorization: Signature 31bd5924dd6cbc9cbe99d331c4a086a57291f9d7

{
    "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"
        },
        "repatriation_commission":{
            "currency":"USD",
            "amount":"10"
        }
    }
}
$ curl -v 'https://your.hostname/your/uri' \
-X POST \
-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"
            },
            "repatriation_commission":{
                "currency":"USD",
                "amount":"10"
            }
        }
    }
}'
Antwort
<?php

use Xsolla\SDK\Webhook\WebhookServer;
use Xsolla\SDK\Webhook\Message\Message;
use Xsolla\SDK\Exception\Webhook\XsollaWebhookException;

$callback = function (Message $message) {
    if ($message->isRefund()) {
        $userArray = $message->getUser();
        $paymentArray = $message->getTransaction();
        $paymentId = $message->getPaymentId();
        $externalPaymentId = $message->getExternalPaymentId();
        $paymentDetailsArray = $message->getPaymentDetails();
        $customParametersArray = $message->getCustomParameters();
        $isDryRun = $message->isDryRun();
        $refundArray = $message->getRefundDetails();
        $messageArray = $message->toArray();
        // TODO if you cannot handle the refund, you should throw XsollaWebhookException
    }
};

$webhookServer = WebhookServer::create($callback, PROJECT_KEY);
$webhookServer->start();
HTTP/1.1 204 No Content

Upgrade zurückerstatten

Falls einem Benutzer die mit dem Upgrade verbundene Zahlung zurückerstattet wird, sendet Xsolla die Daten bezüglich aller stornierten Upgrades und das aktuelle Spielpaket an die Webhook-URL.

Parameter Typ Beschreibung
notification_type
string Art der Benachrichtigung. Erforderlich.
purchase
object Objekt mit den Kaufdaten. Erforderlich.
purchase.pin_codes
object Objekt mit Daten zu den gekauften Spielpaketen.
purchase.pin_codes.purchase_type
string Kauftyp. Kann "regular" (Kauf des Pakets) oder "upgrade" (Upgrade des Pakets) lauten.
purchase.pin_codes.digital_content
string Im Kundenportal festgelegte Spiel-SKU.
purchase.pin_codes.DRM
string DRM-Plattform des Spiels.
purchase.pin_codes.currency
string Kaufwährung. Währungscode, bestehend aus drei Buchstaben gemäß ISO 4217.
purchase.pin_codes.amount
float Preis in echter Währung.
purchase.pin_codes.transaction
object Objekt mit den Transaktionsdaten.
purchase.pin_codes.transaction.id
integer ID der Transaktion.
purchase.pin_codes.upgrade
object Objekt mit den Upgrade-Daten.
purchase.pin_codes.upgrade.digital_content_from
object Objekt mit Daten über das Paket, von dem aus der Benutzer ein Upgrade durchgeführt hat.
purchase.pin_codes.upgrade.digital_content_from.digital_content
string Im Kundenportal festgelegte Spiel-SKU.
purchase.pin_codes.upgrade.digital_content_from.DRM
string DRM-Plattform des Spiels.
purchase.pin_codes.upgrade.digital_content_to
object Objekt mit Daten über das Paket, auf das der Benutzer ein Upgrade durchgeführt hat.
purchase.pin_codes.upgrade.digital_content_to.digital_content
string Im Kundenportal festgelegte Spiel-SKU.
purchase.pin_codes.upgrade.digital_content_to.DRM
string DRM-Plattform des Spiels.
ownership
object Objekt mit Daten über Pakete, die dem Benutzer gehören. Erforderlich.
ownership.digital_content
string Im Kundenportal festgelegte Spiel-SKU.
ownership.DRM
string DRM-Plattform des Spiels.
Copy
Full screen
php
  • php
  • http
  • curl
Anfrage
<?php

$request = array (
  'notification_type' => 'upgrade_refund',
  'purchase' =>
  array (
    'pin_codes' =>
    array (
      0 =>
      array (
        'purchase_type' => 'regular',
        'digital_content' => 'silver',
        'DRM' => 'drmfree',
        'currency' => 'USD',
        'amount' => '40',
        'transaction' =>
        array (
          'id' => '361697569',
        ),
      ),
      1 =>
      array (
        'purchase_type' => 'upgrade',
        'upgrade' =>
        array (
          'digital_content_from' =>
          array (
            'digital_content' => 'silver',
            'DRM' => 'drmfree',
          ),
          'digital_content_to' =>
          array (
            'digital_content' => 'gold',
            'DRM' => 'drmfree',
          ),
        ),
        'currency' => 'USD',
        'amount' => '20',
        'transaction' =>
        array (
          'id' => '361697570'
        ),
      ),
      2 =>
      array (
        'purchase_type' => 'upgrade',
        'upgrade' =>
        array (
          'digital_content_from' =>
          array (
            'digital_content' => 'gold',
            'DRM' => 'drmfree',
          ),
          'digital_content_to' =>
          array (
            'digital_content' => 'platinum',
            'DRM' => 'drmfree',
          ),
        ),
        'currency' => 'USD',
        'amount' => '20',
        'transaction' =>
        array (
          'id' => '361697571'
        ),
      ),
    ),
  ),
  'ownership' =>
  array (
    'digital_content' => NULL,
    'DRM' => NULL,
  ),
)
POST /your_uri HTTP/1.1
Host: your.host
Accept: application/json
Content-Type: application/json
Authorization: Signature <signature>

{
  "notification_type": "upgrade_refund",
  "purchase": {
    "pin_codes": [
      {
        "purchase_type": "regular",
        "digital_content": "silver",
        "DRM": "drmfree",
        "currency": "USD",
        "amount": "40",
        "transaction": {
          "id": "361697569"
        }
      },
      {
        "purchase_type": "upgrade",
        "upgrade": {
          "digital_content_from": {
            "digital_content": "silver",
            "DRM": "drmfree"
          },
          "digital_content_to": {
            "digital_content": "gold",
            "DRM": "drmfree"
          }
        },
        "currency": "USD",
        "amount": "20",
        "transaction": {
          "id": "361697570"
        }
      },
      {
        "purchase_type": "upgrade",
        "upgrade": {
          "digital_content_from": {
            "digital_content": "gold",
            "DRM": "drmfree"
          },
          "digital_content_to": {
            "digital_content": "platinum",
            "DRM": "drmfree"
          }
        },
        "currency": "USD",
        "amount": "20",
        "transaction": {
          "id": "361697571"
        }
      }
    ]
  },
  "ownership": {
    "digital_content": null,
    "DRM": null
  }
}
$ curl -v 'https://your.hostname/your/uri' \
-X POST \
-d '{
  "notification_type": "upgrade_refund",
  "purchase": {
    "pin_codes": [
      {
        "purchase_type": "regular",
        "digital_content": "silver",
        "DRM": "drmfree",
        "currency": "USD",
        "amount": "40",
        "transaction": {
          "id": "361697569"
        }
      },
      {
        "purchase_type": "upgrade",
        "upgrade": {
          "digital_content_from": {
            "digital_content": "silver",
            "DRM": "drmfree"
          },
          "digital_content_to": {
            "digital_content": "gold",
            "DRM": "drmfree"
          }
        },
        "currency": "USD",
        "amount": "20",
        "transaction": {
          "id": "361697570"
        }
      },
      {
        "purchase_type": "upgrade",
        "upgrade": {
          "digital_content_from": {
            "digital_content": "gold",
            "DRM": "drmfree"
          },
          "digital_content_to": {
            "digital_content": "platinum",
            "DRM": "drmfree"
          }
        },
        "currency": "USD",
        "amount": "20",
        "transaction": {
          "id": "361697571"
        }
      }
    ]
  },
  "ownership": {
    "digital_content": null,
    "DRM": null
  }
}'
Antwort

Abgelehnte Transaktion (AFS)

Wenn eine Transaktion während einer AFS-Prüfung abgelehnt wird, sendet Xsolla Transaktionsdaten an den URL-Webhook. Um diese Benachrichtigung zu aktivieren, wenden Sie sich bitte an den Account Manager.

Parameter Typ Beschreibung
notification_type
string Art der Benachrichtigung. Erforderlich.
user
object Benutzerdaten (Objekt).
user.ip
string Benutzer-IP.
user.phone
string Telefonnummer des Benutzers.
user.email
string E-Mail des Benutzers.
user.id
string Benutzer-ID. Erforderlich.
user.name
string Benutzername.
user.country
string Land des Benutzers. Ländercode, bestehend aus 2 Großbuchstaben gemäß ISO 3166-1 ALPHA-2.
user.zip
string Postleitzahl.
transaction
object Details zur Transaktion (Objekt). Erforderlich.
transaction.id
integer ID der Transaktion.
transaction.external_id
string Externe ID der Transaktion.
transaction.dry_run
integer Transaktion zur Testzwecken. 1 falls es sich um eine testweise durchgeführte Transaktion handelt, ansonsten 0.
transaction.agreement
integer ID der Vereinbarung.
refund_details
object Benutzerdaten (Objekt).
refund_details.code
integer Code-ID.
refund_details.reason
string Grund für die Rückerstattung.
refund_details.author
string Initiator der Rückerstattung.
Copy
Full screen
php
  • php
  • http
  • curl
Anfrage
<?php

$request = array(
    'notification_type' => 'afs_reject',
    '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' => array(
            'code' => 4,
            'reason' => 'Potential fraud'
    )
);
POST /your_uri HTTP/1.1
Host: your.host
Accept: application/json
Content-Type: application/json
Content-Length: 1220
Authorization: Signature 31bd5924dd6cbc9cbe99d331c4a086a57291f9d7

{
    "notification_type":"afs_reject",
    "user": {
        "ip": "127.0.0.1",
        "phone": "18777976552",
        "email": "semail@example.com,
        "id": "1234567",
        "name": "Xsolla User",
        "country": "US"
    },
    "transaction":{
        "id":1,
        "external_id":1,
        "dry_run":1,
        "agreement":1
    },
    "refund_details":{
        "code":4,
        "reason":"Potential fraud"
    }
}
$ curl -v 'https://your.hostname/your/uri' \
-X POST \
-d '{
  "notification_type":"afs_reject",
  "user": {
      "ip": "127.0.0.1",
      "phone": "18777976552",
      "email": "semail@example.com,
      "id": "1234567",
      "name": "Xsolla User",
      "country": "US"
  },
  "transaction":{
      "id":1,
      "external_id":1,
      "dry_run":1,
      "agreement":1
  },
  "refund_details":{
      "code":4,
      "reason":"Potential fraud"
  }
}'
Antwort
<?php

use Xsolla\SDK\Webhook\WebhookServer;
use Xsolla\SDK\Webhook\Message\Message;
use Xsolla\SDK\Exception\Webhook\XsollaWebhookException;

$callback = function (Message $message) {
    if ($message->isRefund()) {
        $userArray = $message->getUser();
        $paymentArray = $message->getTransaction();
        $paymentId = $message->getPaymentId();
        $externalPaymentId = $message->getExternalPaymentId();
        $customParametersArray = $message->getCustomParameters();
        $isDryRun = $message->isDryRun();
        $refundArray = $message->getRefundDetails();
        $messageArray = $message->toArray();
        // TODO if you cannot handle the refund, you should throw XsollaWebhookException
    }
};

$webhookServer = WebhookServer::create($callback, PROJECT_KEY);
$webhookServer->start();
HTTP/1.1 204 No Content

Abgeschlossenes Abonnement

Wenn ein Benutzer ein Abonnement abschließt, senden wir eine Benachrichtigung an Ihr Payment-Notification-Script.

Parameter Typ Beschreibung
notification_type
string Art der Benachrichtigung. Erforderlich.
user
object Benutzerdaten (Objekt).
user.id
string Benutzer-ID. Erforderlich.
user.name
string Benutzername.
subscription
object Angaben zum Abonnement (Objekt).
subscription.plan_id
string ID des Abo-Modells (extern, falls das Abo-Modell über die API angelegt wurde).
subscription.tags
array Abo-Modell-Markierungen.
subscription.subscription_id
integer In der Xsolla-Datenbank erfasste Abonnement-ID.
subscription.product_id
string Produkt-ID (falls sie im Zugriffstoken versendet wurde).
subscription.date_create
string Datum, an dem das Abonnement abgeschlossen wurde. Datums- und Zeitangabe gemäß ISO 8601.
subscription.date_next_charge
string Nächstes Rechnungsdatum. Datums- und Zeitangabe gemäß ISO 8601.
subscription.trial
object Probezeitraum (Objekt).
subscription.trial.value
integer Probezeitraum.
subscription.trial.type
string Art des Probezeitraums: day.
Copy
Full screen
php
  • php
  • http
  • curl
Anfrage
<?php

$request = array(
    'notification_type' => 'create_subscription',
    'user' => array(
        'id' => '1234567',
        'name' => 'Xsolla User'
    ),
    'subscription' => array(
        'plan_id' => 'b5dac9c8',
        'subscription_id' => '10',
        'product_id' => 'Demo Product',
        'date_create' => '2014-09-22T19:25:25+04:00',
        'date_next_charge' => '2015-01-22T19:25:25+04:00',
        'trial' =>  array(
                'value' =>  90,
                'type' =>  'day'
            )
    )
);
POST /your/uri HTTP/1.1
Host: your.hostname
Accept: application/json
Content-Type: application/json
Content-Length: 240
Authorization: Signature 13342703ccaca5064ad33ba451d800c5e823db8f

{
    "notification_type":"create_subscription",
    "user":{
        "id":"1234567",
        "name":"Xsolla User"
    },
    "subscription":{
        "plan_id":"b5dac9c8",
        "subscription_id":"10",
        "product_id":"Demo Product",
        "date_create":"2014-09-22T19:25:25+04:00",
        "date_next_charge":"2015-01-22T19:25:25+04:00",
        "trial": {
                "value": 90,
                "type": "day"
            }
    }
}
$ curl -v 'https://your.hostname/your/uri' \
-X POST \
-H 'Accept: application/json' \
-H 'Content-Type: application/json' \
-H 'Authorization: Signature 13342703ccaca5064ad33ba451d800c5e823db8f' \
-d '{
        "notification_type":"create_subscription",
        "user":{
            "id":"1234567",
            "name":"Xsolla User"
        },
        "subscription":{
            "plan_id":"b5dac9c8",
            "subscription_id":"10",
            "product_id":"Demo Product",
            "date_create":"2014-09-22T19:25:25+04:00",
            "date_next_charge":"2015-01-22T19:25:25+04:00",
            "trial": {
                    "value": 90,
                    "type": "day"
                }
        }
    }'
Antwort
<?php

use Xsolla\SDK\Webhook\WebhookServer;
use Xsolla\SDK\Webhook\Message\Message;
use Xsolla\SDK\Exception\Webhook\XsollaWebhookException;

$callback = function (Message $message) {
    if ($message instanceof CreateSubscriptionMessage) {
       $messageArray = $message->toArray();
       // TODO if the subscription creation fails for some reason, you should throw XsollaWebhookException
    }
};

$webhookServer = WebhookServer::create($callback, PROJECT_KEY);
$webhookServer->start();
HTTP/1.1 204 No Content

Aktualisiertes Abonnement

Wird immer dann versendet, wenn sich entweder der Parameter "plan_id" oder "date_next_charge" des Abonnements ändert oder wenn das Abonnement verlängert wurde.

Parameter Typ Beschreibung
notification_type
string Art der Benachrichtigung. Erforderlich.
user
object Benutzerdaten (Objekt).
user.id
string Benutzer-ID. Erforderlich.
user.name
string Benutzername.
subscription
object Angaben zum Abonnement (Objekt).
subscription.plan_id
string ID des Abo-Modells (extern, falls das Abo-Modell über die API angelegt wurde).
subscription.tags
array Abo-Modell-Markierungen.
subscription.subscription_id
integer In der Xsolla-Datenbank erfasste Abonnement-ID.
subscription.product_id
string Produkt-ID (falls sie im Zugriffstoken versendet wurde).
subscription.date_next_charge
string Nächstes Rechnungsdatum. Datums- und Zeitangabe gemäß ISO 8601.
Copy
Full screen
php
  • php
  • http
  • curl
Anfrage
<?php

$request = array(
    'notification_type' => 'update_subscription',
    'user' => array(
        'id' => '1234567',
        'name' => 'Xsolla User'
    ),
    'subscription' => array(
        'plan_id' => 'b5dac9c8',
        'subscription_id' => '10',
        'product_id' => 'Demo Product',
        'date_next_charge' => '2015-01-22T19:25:25+04:00'
    )
);
POST /your/uri HTTP/1.1
Host: your.hostname
Accept: application/json
Content-Type: application/json
Content-Length: 240
Authorization: Signature 13342703ccaca5064ad33ba451d800c5e823db8f

{
    "notification_type":"update_subscription",
    "user":{
        "id":"1234567",
        "name":"Xsolla User"
    },
    "subscription":{
        "plan_id":"b5dac9c8",
        "subscription_id":"10",
        "product_id":"Demo Product",
        "date_next_charge":"2015-01-22T19:25:25+04:00"
    }
}
$ curl -v 'https://your.hostname/your/uri' \
-X POST \
-H 'Accept: application/json' \
-H 'Content-Type: application/json' \
-H 'Authorization: Signature 13342703ccaca5064ad33ba451d800c5e823db8f' \
-d '{
        "notification_type":"update_subscription",
        "user":{
            "id":"1234567",
            "name":"Xsolla User"
        },
        "subscription":{
            "plan_id":"b5dac9c8",
            "subscription_id":"10",
            "product_id":"Demo Product",
            "date_next_charge":"2015-01-22T19:25:25+04:00"
        }
    }'
Antwort
<?php

use Xsolla\SDK\Webhook\WebhookServer;
use Xsolla\SDK\Webhook\Message\Message;
use Xsolla\SDK\Exception\Webhook\XsollaWebhookException;

$callback = function (Message $message) {
  if ($message instanceof UpdateSubscriptionMessage) {
     $messageArray = $message->toArray();
     // TODO if the subscription renewing fails for some reason, you should throw XsollaWebhookException
  }
};

$webhookServer = WebhookServer::create($callback, PROJECT_KEY);
$webhookServer->start();
HTTP/1.1 204 No Content

Gekündigtes Abonnement

Wenn ein Abonnement aus irgendeinem Grund gekündigt wird, senden wir eine Benachrichtigung an Ihr Payment-Notification-Script.

Parameter Typ Beschreibung
notification_type
string Art der Benachrichtigung. Erforderlich.
user
object Benutzerdaten (Objekt).
user.id
string Benutzer-ID. Erforderlich.
user.name
string Benutzername.
subscription
object Angaben zum Abonnement (Objekt).
subscription.plan_id
string ID des Abo-Modells (extern, falls das Abo-Modell über die API angelegt wurde).
subscription.tags
array Abo-Modell-Markierungen.
subscription.subscription_id
integer In der Xsolla-Datenbank erfasste Abonnement-ID.
subscription.product_id
string Produkt-ID (falls sie im Zugriffstoken versendet wurde).
subscription.date_create
string Datum, an dem das Abonnement abgeschlossen wurde. Datums- und Zeitangabe gemäß ISO 8601.
subscription.date_end
string Kündigungszeitpunkt des Abonnements. Datums- und Zeitangabe gemäß ISO 8601.
Copy
Full screen
php
  • php
  • http
  • curl
Anfrage
<?php

$request = array(
    'notification_type' => 'cancel_subscription',
    'user' => array(
        'id' => '1234567',
        'name' => 'Xsolla User'
    ),
    'subscription' => array(
        'plan_id' => 'b5dac9c8',
        'subscription_id' => '10',
        'product_id' => 'Demo Product',
        'date_create' => '2014-09-22T19:25:25+04:00',
        'date_end' => '2015-01-22T19:25:25+04:00',
    )
);
POST /your/uri HTTP/1.1
Host: your.hostname
Accept: application/json
Content-Type: application/json
Content-Length: 240
Authorization: Signature 13342703ccaca5064ad33ba451d800c5e823db8f

{
    "notification_type":"cancel_subscription",
    "user":{
        "id":"1234567",
        "name":"Xsolla User"
    },
    "subscription":{
        "plan_id":"b5dac9c8",
        "subscription_id":"10",
        "product_id":"Demo Product",
        "date_create":"2014-09-22T19:25:25+04:00",
        "date_end":"2015-01-22T19:25:25+04:00"
    }
}
$ curl -v 'https://your.hostname/your/uri' \
-X POST \
-H 'Accept: application/json' \
-H 'Content-Type: application/json' \
-H 'Authorization: Signature 13342703ccaca5064ad33ba451d800c5e823db8f' \
-d '{
        "notification_type":"cancel_subscription",
        "user":{
            "id":"1234567",
            "name":"Xsolla User"
        },
        "subscription":{
            "plan_id":"b5dac9c8",
            "subscription_id":"10",
            "product_id":"Demo Product",
            "date_create":"2014-09-22T19:25:25+04:00",
            "date_end":"2015-01-22T19:25:25+04:00"
        }
    }'
Antwort
<?php

use Xsolla\SDK\Webhook\WebhookServer;
use Xsolla\SDK\Webhook\Message\Message;
use Xsolla\SDK\Exception\Webhook\XsollaWebhookException;

$callback = function (Message $message) {
    if ($message instanceof CancelSubscriptionMessage) {
       $messageArray = $message->toArray();
       // TODO if the subscription canceling fails for some reason, you should throw XsollaWebhookException
    }
};

$webhookServer = WebhookServer::create($callback, PROJECT_KEY);
$webhookServer->start();
HTTP/1.1 204 No Content

Spielschlüssel anfordern

Nach jeder erfolgreichen Zahlung werden wir API-Aufrufe an Ihrem Server durchführen, um die Spielschlüssel abzurufen.

Parameter Typ Beschreibung
notification_type
string Art der Benachrichtigung.
user
object Benutzerdaten (Objekt).
user.id
string Benutzer-ID. Erforderlich.
user.name
string Benutzername.
pin_code
object Angaben zu den Spielschlüsseln (Objekt).
pin_code.digital_content
string Spiel-SKU.
pin_code.DRM
string Die für die Auslieferung des Spiels verwendete DRM-Plattform.
Copy
Full screen
php
  • php
  • http
  • curl
Anfrage
<?php

$request = array (
       'notification_type' => 'get_pincode',
       'user' =>
           array (
               'id' => '1234567',
               'name' => 'Xsolla User',
           ),
       'pin_code' =>
           array (
               'digital_content' => 'Game SKU',
               'DRM' => 'Steam',
           ),
   );
POST /your/uri HTTP/1.1
Host: your.hostname
Accept: application/json
Content-Type: application/json
Content-Length: 240
Authorization: Signature 13342703ccaca5064ad33ba451d800c5e823db8f

{
    "notification_type":"get_pincode",
    "user":{
        "id":"1234567",
        "name":"Xsolla User"
    },
    "pin_code":{
        "digital_content":"Game SKU",
        "DRM":"Steam"
    }
}
$ curl -v 'https://your.hostname/your/uri' \
-X POST \
-H 'Accept: application/json' \
-H 'Content-Type: application/json' \
-H 'Authorization: Signature 13342703ccaca5064ad33ba451d800c5e823db8f' \
-d '{
        "notification_type":"get_pincode",
        "user":{
            "id":"1234567",
            "name":"Xsolla User"
        },
        "pin_code":{
            "digital_content":"Game SKU",
            "DRM":"Steam"
        }
    }'
Antwort
<?php

use Xsolla\SDK\Webhook\WebhookServer;
use Xsolla\SDK\Webhook\Message\Message;
use Xsolla\SDK\Exception\Webhook\XsollaWebhookException;

$callback = function (Message $message) {
    if ($message instanceof GetPinCodeMessage) {
        $userArray = $message->getUser();
        $drmSku = $message->getDRM();
        $digitalContentSku = $message->getDigitalContent();
        // TODO get a pin code from your database or generate a new one. Put the pin code into variable $newPinCode
        $newPinCode = 'NEW_PIN_CODE';
        // TODO if the pin code creation or generation fail for some reason, you should throw XsollaWebhookException
        return new \Xsolla\SDK\Webhook\Response\PinCodeResponse($newPinCode);
    }
};
$webhookServer = WebhookServer::create($callback, PROJECT_KEY);
$webhookServer->start();
HTTP/1.1 200 OK
Content-Type: application/json
{
    "pin_code": "PIN_CODE"
}

Schlüssel aktivieren

Bei der Aktivierung eines Schlüssels durch einen Benutzer sendet Xsolla eine Benachrichtigung an Ihre Webhook-URL.

Parameter Typ Beschreibung
notification_type
string Art der Benachrichtigung.
key
string Aktivierungsschlüssel.
sku
string Individuelle Schlüsselpaket-ID.
user_id
string Benutzer-ID.
activation_date
datetime Datum der Schlüsselaktivierung gemäß folgendem Format und ISO 8601: JJJJMMTTHHMMSS.
user_country
string Land des Benutzers. Ländercode, bestehend aus 2 Großbuchstaben gemäß ISO 3166-1 ALPHA-2.
restriction
object Objekt mit Cluster-Einstellungen bezüglich regionaler Beschränkungen. Das Cluster enthält eine Beschränkungsart und eine Liste der Länder, Server und Gebietsschemata, in bzw. auf denen das Spiel verfügbar ist.
restriction.sku
string Individuelle Cluster-ID.
restriction.name
string Clustername.
restriction.types
array Array der Beschränkungsart.
restriction_countries
array Array der Länder im Cluster.
restriction.servers
array Array der Spielserver.
restriction.locales
array Array der Gebietsschemata.
Copy
Full screen
php
  • php
  • http
  • curl
Anfrage
<?php
$request = array(
    'notification_type' => 'redeem_key',
    'key' => ‘wqdqwwddq9099022’,
    'sku' => 123,
    'user_id' => ‘sample_user’,
    'activation_date' => ‘2018-11-20T08:38:51+03:00,
    'user_country' => ‘EN’,
    'restriction' =>
           array(
                'name' => ‘cls_1’,
                'types' =>
                        array(
                            ‘activation’
                        ),
                'countries' =>
                        array(
                            ‘RU’
                        ),
             ),
);  
POST /your_uri HTTP/1.1
Host: your.host
Accept: application/json
Content-Type: application/json
Content-Length: 165
Authorization: Signature 52eac2713985e212351610d008e7e14fae46f902

{
  "notification_type": "redeem_key",
  "key": "wqdqwwddq9099022",
  "sku": "123",
  "user_id": "sample_user",
  "activation_date": "2018-11-20T08:38:51+03:00",
  "user_country": "EN",
  "restriction": {
      "name": "cls_1",
      "types": [
           "activation"
        ],
        "countries": [
             "RU"
        ]
  }
}
$ curl -v 'https://your.hostname/your/uri' \
-X POST \
-H 'Accept: application/json' \
-H 'Content-Type: application/json' \
-H 'Authorization: Signature 13342703ccaca5064ad33ba451d800c5e823db8f' \
-d '{
     "notification_type": "redeem_key",
  "key": "wqdqwwddq9099022",
  "sku": "123",
  "user_id": "sample_user",
  "activation_date": "2018-11-20T08:38:51+03:00",
  "user_country": "EN",
  "restriction": {
      "name": "cls_1",
      "types": [
           "activation"
        ],
        "countries": [
             "RU"
         ]
    }
}'
Antwort
<?php

$response = null;
HTTP/1.1 204 No Content

Freunde auflisten

Die API sollte auf Seiten des Partners implementiert werden. Die Maximalanzahl der Freunde beträgt 2000. Siehe Anleitung.

HTTP-ANFRAGE

GET https://your.webhook.url?notification_type=friends_list&user=user_id&query=frien&offset=10&limit=20&sign=12dfg3f5gdsf4g5s6dfg2sdg1

Parameter Typ Beschreibung
notification_type
string Art der Benachrichtigung. Erforderlich. Der Wert lautet "friends_list".
user
string Eindeutige ID des Benutzers, der das Geschenk erwirbt.
query
string Name oder ID des Freundes (ganz oder teilweise).
limit
string Begrenzung der Elementanzahl auf der Seite. Erforderlich.
offset
integer Elementnummer, aus der die Liste generiert wird (die Zählung beginnt bei 0).
sign
string Signaturzeile, die wie folgt erzeugt wird:
  • Aneinanderreihen von notification_type + Parameterwerte, alphabetisch sortiert nach dem Schlüssel + secret_key
  • SHA-1-Algorithmus auf den sich ergebenden String anwenden
Copy
Full screen
http
  • http
  • curl
Anfrage
GET https://your.webhook.url?notification_type=friends_list&user=user_id&query=frien&offset=10&limit=20&sign=12dfg3f5gdsf4g5s6dfg2sdg1 HTTP/1.1
Host: your.host
Accept: application/json
Content-Type: application/json
Content-Length: 1220
Authorization: Signature 31bd5924dd6cbc9cbe99d331c4a086a57291f9d7
$ curl -v 'https://your.webhook.url?notification_type=friends_list&user=user_id&query=frien&offset=10&limit=20&sign=12dfg3f5gdsf4g5s6dfg2sdg1' \
-X GET \
-u merchant_id:merchant_api_key
Antwort
HTTP/1.1 200 OK
Content-Type: application/json

[
  {
    "friends": [
      {
        "id": "1",
        "name": "doctor",
        "email": "doctor@hospital.com",
        "image_url": "https://partner/link/doctor.jpg"
      },
      {
        "id": "2",
        "name": "cook",
        "email": "cook@kitchen.com",
        "image_url": "https://partner/link/cook.jpg"
      },
      {
        "id": "3",
        "name": "teacher",
        "email": "teacher@school.com"
      },
      {
        "id": "4",
        "name": "god",
        "email": "god@heaven.com",
        "image_url": "https://partner/link/god.jpg"
      }
      ],
    "total": 10
  }
]
[
  {
  "friends": [
      {
        "id": "1",
        "name": "John Carter",
        "email": "carter@xsolla.com",
        "image_url": "https://partner/link/doctor.jpg"
      },
      {
        "id": "2",
        "name": "John Smith",
        "email": "smith@xsolla.com",
        "image_url": "https://partner/link/cook.jpg"
      }
    ],
  "total": 10
  }
]

Kontostand des Benutzers: Zahlung

Wird immer dann versendet, wenn ein Benutzer eine Zahlung tätigt.

Parameter Typ Beschreibung
notification_type
string Art der Benachrichtigung.
operation_type
string Operationsart.
id_operation
integer Operations-ID in der Xsolla-Datenbank.
user
object Benutzerdaten (Objekt).
user.id
string Benutzer-ID. Erforderlich.
user.name
string Benutzername.
user.email
string E-Mail des Benutzers.
virtual_currency_balance
object Daten zum Kontostand des Benutzers (Objekt).
virtual_currency_balance.old_value
string Kontostand vor der Transaktion.
virtual_currency_balance.new_value
string Kontostand nach der Transaktion.
virtual_currency_balance.diff
string Menge der beim Kauf erworbenen virtuellen Währung.
transaction
object Details zur Transaktion (Objekt). Erforderlich.
transaction.id
integer ID der Transaktion.
transaction.date
string Transaktionsdatum.
Copy
Full screen
php
  • php
  • http
  • curl
Anfrage
<?php

$request = array(
    'virtual_currency_balance' => array(
        'old_value' => '0',
        'new_value' => '200',
        'diff' => '200'
    ),
    'user' => array(
        'name' => 'Xsolla User',
        'id' => '1234567',
        'email' => 'email@example.com'
    ),
    'transaction => array(
        'id' => '123456789',
        'date' => '2015-05-19T15:54:40+03:00'
    ),
    'operation_type' => 'payment',
    'notification_type' => 'user_balance_operation',
    'id_operation' => '66989'
);
POST /your/uri HTTP/1.1
Host: your.hostname
Accept: application/json
Content-Type: application/json
Content-Length: 240
Authorization: Signature 13342703ccaca5064ad33ba451d800c5e823db8f

{
    "virtual_currency_balance":{
        "old_value":"0",
        "new_value":"200",
        "diff":"200"
    },
    "user":{
        "name":"Xsolla User",
        "id":"1234567",
        "email":"email@example.com"
    },
    "transaction":{
        "id":"123456789",
        "date":"2015-05-19T15:54:40+03:00"
    },
    "operation_type":"payment",
    "notification_type":"user_balance_operation",
    "id_operation":"66989"
}
$ curl -v 'https://your.hostname/your/uri' \
-X POST \
-H 'Accept: application/json' \
-H 'Content-Type: application/json' \
-H 'Authorization: Signature 13342703ccaca5064ad33ba451d800c5e823db8f' \
-d '{
        "virtual_currency_balance":{
            "old_value":"0",
            "new_value":"200",
            "diff":"200"
        },
        "user":{
            "name":"Xsolla User",
            "id":"1234567",
            "email":"email@example.com"
        },
        "transaction":{
            "id":"123456789",
            "date":"2015-05-19T15:54:40+03:00"
        },
        "operation_type":"payment",
        "notification_type":"user_balance_operation",
        "id_operation":"66989"
    }'
Antwort
<?php

use Xsolla\SDK\Webhook\WebhookServer;
use Xsolla\SDK\Webhook\Message\Message;
use Xsolla\SDK\Exception\Webhook\XsollaWebhookException;

$callback = function (Message $message) {
    if ($message instanceof UserBalanceMessage) {
       $messageArray = $message->toArray();
       // TODO if the user balance operation fails for some reason, you should throw XsollaWebhookException
    }
};

$webhookServer = WebhookServer::create($callback, PROJECT_KEY);
$webhookServer->start();
HTTP/1.1 204 No Content

Kontostand des Benutzers: Kauf

Wird versendet, wenn ein Benutzer irgendetwas im Spiel erwirbt. Wird versendet, wenn ein Benutzer eine Zahlung storniert.

Parameter Typ Beschreibung
notification_type
string Art der Benachrichtigung.
operation_type
string Operationsart.
id_operation
integer Operations-ID in der Xsolla-Datenbank.
user
object Benutzerdaten (Objekt).
user.id
string Benutzer-ID. Erforderlich.
user.name
string Benutzername.
user.email
string E-Mail des Benutzers.
virtual_currency_balance
object Daten zum Kontostand des Benutzers (Objekt).
virtual_currency_balance.old_value
string Kontostand vor der Transaktion.
virtual_currency_balance.new_value
string Kontostand nach der Transaktion.
virtual_currency_balance.diff
string Menge der beim Kauf erworbenen virtuellen Währung.
items_operation_type
string Operationstyp, der bei den virtuellen Gegenstände zum Einsatz kommt.
items
array Im Einkauf enthaltene virtuelle Gegenstände (array of objects).
items.sku
string ID des Gegenstands.
items.amount
integer Gegenstandsmenge.
Copy
Full screen
php
  • php
  • http
  • curl
Anfrage
<?php

$request = array(
    'virtual_currency_balance' => array(
            'old_value' => '0',
            'new_value' => '200',
            'diff' => '200'
    ),
    'user' => array(
        'name' => 'Xsolla User',
        'id' => '1234567',
        'email' => 'email@example.com'
    ),
    'operation_type' => 'inGamePurchase',
    'notification_type' => 'user_balance_operation',
    'items_operation_type' =>  'add',
         'items' =>  array(
             'sku' =>  '1468',
             'amount' =>  '2'
         ),
    'id_operation' => '66989'
);
POST /your/uri HTTP/1.1
Host: your.hostname
Accept: application/json
Content-Type: application/json
Content-Length: 240
Authorization: Signature 13342703ccaca5064ad33ba451d800c5e823db8f

{
    "virtual_currency_balance":{
        "old_value":"0",
        "new_value":"200",
        "diff":"200"
    },
    "user":{
        "name":"Xsolla User",
        "id":"1234567",
        "email":"email@example.com"
    },
    "operation_type":"inGamePurchase",
    "notification_type":"user_balance_operation",
    "items_operation_type": "add",
         "items": [{
         "sku": "1468",
         "amount": "2"
         }],
    "id_operation":"66989"
}
$ curl -v 'https://your.hostname/your/uri' \
-X POST \
-H 'Accept: application/json' \
-H 'Content-Type: application/json' \
-H 'Authorization: Signature 13342703ccaca5064ad33ba451d800c5e823db8f' \
-d '{
        "virtual_currency_balance":{
            "old_value":"0",
            "new_value":"200",
            "diff":"200"
        },
        "user":{
            "name":"Xsolla User",
            "id":"1234567",
            "email":"email@example.com"
        },
        "operation_type":"inGamePurchase",
        "notification_type":"user_balance_operation",
        "items_operation_type": "add",
             "items": [{
             "sku": "1468",
             "amount": "2"
             }],
        "id_operation":"66989"
    }'
Antwort
<?php

use Xsolla\SDK\Webhook\WebhookServer;
use Xsolla\SDK\Webhook\Message\Message;
use Xsolla\SDK\Exception\Webhook\XsollaWebhookException;

$callback = function (Message $message) {
    if ($message instanceof UserBalanceMessage) {
       $messageArray = $message->toArray();
       // TODO if the user balance operation fails for some reason, you should throw XsollaWebhookException
    }
};

$webhookServer = WebhookServer::create($callback, PROJECT_KEY);
$webhookServer->start();
HTTP/1.1 204 No Content

Kontostand des Benutzers: Einen Gutschein einlösen

Wird versendet, wenn ein Benutzer einen Gutschein einlöst, um virtuelle Gegenstände oder virtuelle Währung zu erhalten.

Parameter Typ Beschreibung
notification_type
string Art der Benachrichtigung.
operation_type
string Operationsart.
id_operation
integer Operations-ID in der Xsolla-Datenbank.
user
object Benutzerdaten (Objekt).
user.id
string Benutzer-ID. Erforderlich.
user.name
string Benutzername.
user.email
string E-Mail des Benutzers.
virtual_currency_balance
object Daten zum Kontostand des Benutzers (Objekt).
virtual_currency_balance.old_value
string Kontostand vor der Transaktion.
virtual_currency_balance.new_value
string Kontostand nach der Transaktion.
virtual_currency_balance.diff
string Menge der beim Kauf erworbenen virtuellen Währung.
items_operation_type
string Operationstyp, der bei den virtuellen Gegenstände zum Einsatz kommt.
items
array Im Einkauf enthaltene virtuelle Gegenstände (array of objects).
items.sku
string ID des Gegenstands.
items.amount
integer Gegenstandsmenge.
coupon
object Angaben zum Gutschein (Objekt).
coupon.coupon_code
string Gutscheincode.
coupon.campaign_code
string Kampagne.
Copy
Full screen
php
  • php
  • http
  • curl
Anfrage
<?php

$request = array(
    'virtual_currency_balance' => array(
        'old_value' => '0',
        'new_value' => '0',
        'diff' => '0'
    ),
    'user' => array(
        'name' => 'Xsolla User',
        'id' => '1234567',
        'email' => 'email@example.com'
    ),
    'operation_type' => 'coupon',
    'notification_type' => 'user_balance_operation',
    'items_operation_type' =>  'add',
         'items' =>  array(
             'sku' =>  '1468',
             'amount' =>  '2'
         ),
    'id_operation' => '66989',
    'coupon' =>  array(
         'coupon_code' =>  'test123',
         'campaign_code' =>  'Xsolla Campaign'
    )
);
POST /your/uri HTTP/1.1
Host: your.hostname
Accept: application/json
Content-Type: application/json
Content-Length: 240
Authorization: Signature 13342703ccaca5064ad33ba451d800c5e823db8f

{
    "virtual_currency_balance":{
        "old_value":"0",
        "new_value":"0",
        "diff":"0"
    },
    "user":{
        "name":"Xsolla User",
        "id":"1234567",
        "email":"email@example.com"
    },
    "operation_type":"coupon",
    "notification_type":"user_balance_operation",
    "items_operation_type": "add",
         "items": [{
             "sku": "1468",
             "amount": "2"
         }],
    "id_operation":"66989",
    "coupon": {
         "coupon_code": "test123",
         "campaign_code": "Xsolla Campaign"
    }
}
$ curl -v 'https://your.hostname/your/uri' \
-X POST \
-H 'Accept: application/json' \
-H 'Content-Type: application/json' \
-H 'Authorization: Signature 13342703ccaca5064ad33ba451d800c5e823db8f' \
-d '{
        "virtual_currency_balance":{
            "old_value":"0",
            "new_value":"0",
            "diff":"0"
        },
        "user":{
            "name":"Xsolla User",
            "id":"1234567",
            "email":"email@example.com"
        },
        "operation_type":"coupon",
        "notification_type":"user_balance_operation",
        "items_operation_type": "add",
             "items": [{
                 "sku": "1468",
                 "amount": "2"
             }],
        "id_operation":"66989",
        "coupon": {
             "coupon_code": "test123",
             "campaign_code": "Xsolla Campaign"
        }
    }'
Antwort
<?php

use Xsolla\SDK\Webhook\WebhookServer;
use Xsolla\SDK\Webhook\Message\Message;
use Xsolla\SDK\Exception\Webhook\XsollaWebhookException;

$callback = function (Message $message) {
    if ($message instanceof UserBalanceMessage) {
       $messageArray = $message->toArray();
       // TODO if the user balance operation fails for some reason, you should throw XsollaWebhookException
    }
};

$webhookServer = WebhookServer::create($callback, PROJECT_KEY);
$webhookServer->start();
HTTP/1.1 204 No Content

Kontostand des Benutzers: Manuelle Aktualisierung

Wird versendet, wenn der Kontostand eines Benutzers manuell geändert wird.

Parameter Typ Beschreibung
notification_type
string Art der Benachrichtigung.
operation_type
string Operationsart.
id_operation
integer Operations-ID in der Xsolla-Datenbank.
user
object Benutzerdaten (Objekt).
user.id
string Benutzer-ID. Erforderlich.
user.name
string Benutzername.
user.email
string E-Mail des Benutzers.
virtual_currency_balance
object Daten zum Kontostand des Benutzers (Objekt).
virtual_currency_balance.old_value
string Kontostand vor der Transaktion.
virtual_currency_balance.new_value
string Kontostand nach der Transaktion.
virtual_currency_balance.diff
string Menge der beim Kauf erworbenen virtuellen Währung.
Copy
Full screen
php
  • php
  • http
  • curl
Anfrage
<?php

$request = array(
    'virtual_currency_balance' => array(
        'old_value' => '0',
        'new_value' => '100',
        'diff' => '100'
    ),
    'user' => array(
        'name' => 'Xsolla User',
        'id' => '1234567',
        'email' => 'email@example.com'
    ),
    'operation_type' => 'internal',
    'notification_type' => 'user_balance_operation',
    'id_operation' => '67002'
);
POST /your/uri HTTP/1.1
Host: your.hostname
Accept: application/json
Content-Type: application/json
Content-Length: 240
Authorization: Signature 13342703ccaca5064ad33ba451d800c5e823db8f

{
    "virtual_currency_balance":{
        "old_value":"0",
        "new_value":"100",
        "diff":"100"
    },
    "user":{
        "name":"Xsolla User",
        "id":"1234567",
        "email":"email@example.com"
    },
    "operation_type":"internal",
    "notification_type":"user_balance_operation",
    "id_operation":"67002"
}
$ curl -v 'https://your.hostname/your/uri' \
-X POST \
-H 'Accept: application/json' \
-H 'Content-Type: application/json' \
-H 'Authorization: Signature 13342703ccaca5064ad33ba451d800c5e823db8f' \
-d '{
        "virtual_currency_balance":{
            "old_value":"0",
            "new_value":"100",
            "diff":"100"
        },
        "user":{
            "name":"Xsolla User",
            "id":"1234567",
            "email":"email@example.com"
        },
        "operation_type":"internal",
        "notification_type":"user_balance_operation",
        "id_operation":"67002"
    }'
Antwort
<?php

use Xsolla\SDK\Webhook\WebhookServer;
use Xsolla\SDK\Webhook\Message\Message;
use Xsolla\SDK\Exception\Webhook\XsollaWebhookException;

$callback = function (Message $message) {
    if ($message instanceof UserBalanceMessage) {
       $messageArray = $message->toArray();
       // TODO if the user balance operation fails for some reason, you should throw XsollaWebhookException
    }
};

$webhookServer = WebhookServer::create($callback, PROJECT_KEY);
$webhookServer->start();
HTTP/1.1 204 No Content

Kontostand des Benutzers: Rückerstattung

Wird versendet, wenn ein Benutzer eine Zahlung abschließt. Wird versendet, wenn ein Benutzer eine Zahlung storniert.

Parameter Typ Beschreibung
notification_type
string Art der Benachrichtigung.
operation_type
string Operationsart.
id_operation
integer Operations-ID in der Xsolla-Datenbank.
user
object Benutzerdaten (Objekt).
user.id
string Benutzer-ID. Erforderlich.
user.name
string Benutzername.
user.email
string E-Mail des Benutzers.
virtual_currency_balance
object Daten zum Kontostand des Benutzers (Objekt).
virtual_currency_balance.old_value
string Kontostand vor der Transaktion.
virtual_currency_balance.new_value
string Kontostand nach der Transaktion.
virtual_currency_balance.diff
string Menge der beim Kauf erworbenen virtuellen Währung.
transaction
object Details zur Transaktion (Objekt). Erforderlich.
transaction.id
integer ID der Transaktion.
transaction.date
string Transaktionsdatum.
items_operation_type
string Operationstyp, der bei den virtuellen Gegenstände zum Einsatz kommt.
items
array Im Einkauf enthaltene virtuelle Gegenstände (array of objects).
items.sku
string ID des Gegenstands.
items.amount
integer Gegenstandsmenge.
Copy
Full screen
php
  • php
  • http
  • curl
Anfrage
<?php

$request = array(
     'virtual_currency_balance' => array(
         'old_value' => '0',
         'new_value' => '0',
         'diff' => '0'
     ),
     'user' => array(
         'name' => 'Xsolla User',
         'id' => '1234567',
         'email' => 'email@example.com'
     ),
     'transaction' => array(
         'id' => '123456789',
         'date' => '2015-05-19T15:54:40+03:00'
     ),
     'operation_type' => 'cancellation',
     'notification_type' => 'user_balance_operation',
     'items_operation_type' =>  'remove',
         'items' =>  array(
             'sku' =>  '1468',
             'amount' =>  '2'
         ),
     'id_operation' => '66989'
);
POST /your/uri HTTP/1.1
Host: your.hostname
Accept: application/json
Content-Type: application/json
Content-Length: 240
Authorization: Signature 13342703ccaca5064ad33ba451d800c5e823db8f

{
    "virtual_currency_balance":{
        "old_value":"0",
        "new_value":"0",
        "diff":"0"
    },
    "user":{
        "name":"Xsolla User",
        "id":"1234567",
        "email":"email@example.com"
    },
    "transaction":{
        "id":"123456789",
        "date":"2015-05-19T15:54:40+03:00"
    },
    "operation_type":"cancellation",
    "notification_type":"user_balance_operation",
    "items_operation_type": "remove",
         "items": [{
             "sku": "1468",
             "amount": "2"
         }],
    "id_operation":"66989"
}
$ curl -v 'https://your.hostname/your/uri' \
-X POST \
-H 'Accept: application/json' \
-H 'Content-Type: application/json' \
-H 'Authorization: Signature 13342703ccaca5064ad33ba451d800c5e823db8f' \
-d '{
        "virtual_currency_balance":{
            "old_value":"0",
            "new_value":"0",
            "diff":"0"
        },
        "user":{
            "name":"Xsolla User",
            "id":"1234567",
            "email":"email@example.com"
        },
        "transaction":{
            "id":"123456789",
            "date":"2015-05-19T15:54:40+03:00"
        },
        "operation_type":"cancellation",
        "notification_type":"user_balance_operation",
        "items_operation_type": "remove",
             "items": [{
                 "sku": "1468",
                 "amount": "2"
             }],
        "id_operation":"66989"
    }'
Antwort
<?php

use Xsolla\SDK\Webhook\WebhookServer;
use Xsolla\SDK\Webhook\Message\Message;
use Xsolla\SDK\Exception\Webhook\XsollaWebhookException;

$callback = function (Message $message) {
    if ($message instanceof UserBalanceMessage) {
       $messageArray = $message->toArray();
       // TODO if the user balance operation fails for some reason, you should throw XsollaWebhookException
    }
};

$webhookServer = WebhookServer::create($callback, PROJECT_KEY);
$webhookServer->start();
HTTP/1.1 204 No Content

Sekundärmarkt: Gegenstandsliste abrufen

Wenn ein Sekundärmarkt Daten von Gegenständen aus einem Spielinventar abfragt, sendet Xsolla eine Benachrichtigung an Ihre Webhook-URL.

Parameter Typ Beschreibung
notification_type
string Art der Benachrichtigung.
project_id
integer Projekt-ID.
payload
object Objekt mit den Benutzer- und Sekundärmarkt-Daten.
payload.user
object Objekt mit den Benutzerdaten.
payload.user.id
string Benutzer-ID.
payload.secondary_market
object Objekt mit Sekundärmarkt-Daten.
payload.secondary_market.id
string Sekundärmarkt-ID.
Copy
Full screen
php
  • php
  • http
  • curl
Anfrage
<?php

$request = array(
 'notification_type' => 'inventory_get',
 'project_id' => 1024,
 'payload' => array(
   'user' => array(
     'id' => 'username'
   ),
   'secondary_market' => array(
     'id' => '1'
   ),
 ),
);
POST /your_uri HTTP/1.1
Host: your.host
Content-Type: application/json
Authorization: Signature sha1(body + project_secret)

{
    "notification_type": "inventory_get",
    "project_id": 1024,
    "payload": {
         "user": {
             "id": "username"
              },
          "secondary_market": {
              "id": "1"
          }
     }  
}
$ curl -v 'https://your.hostname/your/uri' \
-X POST \
-u merchant_id:merchant_api_key \
-H 'Content-Type: application/json' \
-d '{
    "notification_type": "inventory_get",
    "project_id": 1024,
    "payload": {
         "user": {
             "id": "username"
          },
          "secondary_market": {
              "id": "1"
          }
     }  
}
Antwort
<?php

$response = array(
 'user' => array(
  'id' => 'username'
  ),
  'items' => array(
   array(
    'sku' => 'sku1',
    'instance_id' => 'instance1'
    ),
    array(
     'sku' => 'sku2',
     'instance_id' => 'instance2'
    ),
  ),
)
HTTP/1.1 204

{
    "user": {
        "id": "username"
    },
    "items": [
        {
            "sku": "sku1",
            "instance_id": “instance1”
        },
        {
            "sku": "sku2",
            "instance_id": “instance2”
        }
    ],
}
{
    "user": {
        "id": "username"
    },
    "items": [
        {
        "sku": "sku1",
        "instance_id": "instance1"
        },
        {
        "sku": "sku2",
        "instance_id": "instance2"
        }
    ],
}

Sekundärmarkt: Spielgegenstände pullen

Wenn ein Sekundärmarkt Gegenstände aus einem Spielinventar abfragt, sendet Xsolla eine Benachrichtigung an Ihre Webhook-URL.

Parameter Typ Beschreibung
notification_type
string Art der Benachrichtigung.
project_id
integer Projekt-ID.
payload
object Objekt mit den Benutzer- und Sekundärmarkt-Daten.
payload.user
object Objekt mit den Benutzerdaten.
payload.user.id
string Benutzer-ID.
items
array Array mit Gegenstandsdaten.
items.sku
string SKU des Gegenstands.
items.instance_id
string Eindeutige ID des Gegenstands innerhalb des Spiels.
payload.secondary_market
object Objekt mit Sekundärmarkt-Daten.
payload.secondary_market.id
string Sekundärmarkt-ID.
Copy
Full screen
php
  • php
  • http
  • curl
Anfrage
<?php

$request = array(
  'notification_type' => 'inventory_pull',
  'project_id' => 1024,
  'payload' => array(
    'user' => array(
      'id' => 'username'
    ),
    'items' => array(
      array(
        'sku' => 'sku1',
        'instance_id' => 'instance1'
      ),
      array(
        'sku' => 'sku2',
        'instance_id' => 'instance2'
      ),
    )
    'secondary_market' => array(
      'id' => '1'
    ),
  ),
);
POST /your_uri HTTP/1.1
Host: your.host
Content-Type: application/json
Authorization: Signature sha1(body + project_secret)

{
    "notification_type": "inventory_pull",
    "project_id": 1024,
    "payload": {
        "user": {
            "id": "username"
        },
        "items": [
            {
                "sku": "sku1",
                "instance_id": "instance1"
            },
            {
                "sku": "sku2",
                "instance_id": "instance2"
            },
        ],
        "secondary_market": {
            "id": "1"
        }
    }
}
$ curl -v 'https://your.hostname/your/uri' \
-X POST \
-u merchant_id:merchant_api_key \
-H 'Content-Type: application/json' \
-d '{
    "notification_type": "inventory_pull",
    "project_id": 1024,
    "payload": {
         "user": {
             "id": "username"
              },
         "items": [
            {
                "sku": "sku1",
                "instance_id": "instance1"
            },
            {
                "sku": "sku2",
                "instance_id": "instance2"
            }
          ],
          "secondary_market": {
              "id": "1"
          }
     }  
}
Antwort
<?php

$response = null;
HTTP/1.1 204 No Content

Sekundärmarkt: Spielgegenstände pushen

Wenn ein Sekundärmarkt Gegenstände in ein Spielinventar pusht, sendet Xsolla eine Benachrichtigung an Ihre Webhook-URL.

Parameter Typ Beschreibung
notification_type
string Art der Benachrichtigung.
project_id
integer Projekt-ID.
payload
object Objekt mit den Benutzer- und Sekundärmarkt-Daten.
payload.user
object Objekt mit den Benutzerdaten.
payload.user.id
string Benutzer-ID.
items
array Array mit Gegenstandsdaten.
items.sku
string SKU des Gegenstands.
items.instance_id
string Eindeutige ID des Gegenstands innerhalb des Spiels.
payload.secondary_market
object Objekt mit Sekundärmarkt-Daten.
payload.secondary_market.id
string Sekundärmarkt-ID.
Copy
Full screen
php
  • php
  • http
  • curl
Anfrage
<?php

$request = array(
  'notification_type' => 'inventory_push',
  'project_id' => 1024,
  'payload' => array(
    'user' => array(
      'id' => 'username'
    )
    'items' => array(
      array(
        'sku' => 'sku1',
        'instance_id' => 'instance1'
      ),
      array(
        'sku' => 'sku2',
        'instance_id' => 'instance2'
      ),
    ),
    'secondary_market' => array(
      'id' => '1'
    ),
  ),
);
POST /your_uri HTTP/1.1
Host: your.host
Content-Type: application/json
Authorization: Signature sha1(body + project_secret)

{
    "notification_type": "inventory_push",
    "project_id": 1024,
    "payload": {
        "user": {
            "id": "username"
        },
        "items": [
            {
                "sku": "sku1",
                "instance_id": "instance1"
            },
            {
                "sku": "sku2",
                "instance_id": "instance2"
            }
        ],
        "secondary_market": {
            "id": "1"
        }
    }
}
$ curl -v 'https://your.hostname/your/uri' \
-X POST \
-u merchant_id:merchant_api_key \
-H 'Content-Type: application/json' \
-d '{
    "notification_type": "inventory_push",
    "project_id": 1024,
    "payload": {
         "user": {
             "id": "username"
              },
          "items": [
              {
                  "sku": "sku1",
                  "instance_id": "instance1"
              },
              {
                  "sku": "sku2",
                  "instance_id": "instance2"
              }
          ],
          "secondary_market": {
               "id": "1"
          }
     }  
}
Antwort
<?php

$response = null;
HTTP/1.1 204 No Content

Webhook-Fehler

Codes bei permanenten Fehlern:

Code Nachricht
INVALID_USER Ungültiger Benutzer.
INVALID_PARAMETER Ungültiger Parameter.
INVALID_SIGNATURE Ungültige Signatur.
INCORRECT_AMOUNT Ungültiger Betrag.
INCORRECT_INVOICE Ungültige Rechnung.
HTTP/1.1 400 Bad Request

{
    "error":{
        "code":"INVALID_USER",
        "message":"Invalid user"
    }
}