Erste Schritte

Überblick

Die Xsolla-API umfasst Folgendes:

  • In-Game Store API – Methoden für die Verwendung mit Ingame-Online-Shop-Modulen
  • Pay Station API – Zahlungsportal- und Tokenisierungsmethoden
  • Subscription API – Methoden für Abonnements
  • Store API – Methoden für die Verwendung mit "Buy Button"-Modulen: Virtuelle Währung, virtuelle Gegenstände, Spielschlüssel, Werbeaktionen, Gutscheine
  • Publisher Account API – Methoden für die Verwendung mit Kundenportal-Projekten und Benutzern, Berichten sowie Support-Tickets
  • Login API – Methoden für die Benutzerauthentifizierung mithilfe Ihrer eigenen Benutzeroberfläche (siehe Integrationsanleitung)

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.

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.
  • Eine Änderung des API-Schlüssels kann dazu führen, dass Zahlungen an alle Ihre Projekte gestoppt werden. API-Aufrufe mit Ihrem derzeitigen Schlüssel funktionieren erst wieder, wenn Sie sie mit Ihrem neuen Schlüssel aktualisieren.
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:

AktionHTTP-MethodeBeschreibung
ErstellenPOSTErstellt und speichert eine Entität des angegebenen Typs.
AuflistenGETLiefert 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.
AbrufenGETLiefert detaillierte Angaben zur Entität mit der angegebenen ID.
ErsetzenPUTModifiziert alle Felder der Entität mit der angegebenen ID.
AktualisierenPATCHModifiziert bestimmte Felder der Entität mit der angegebenen ID.
LöschenDELETELö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" >}}TypBeschreibung
http_status_codeintegerHTTP-Code.
messagestringEine 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_messagestringDetailliertere Fehlerbeschreibung.
request_idstringEindeutige 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.

ParameterTypBeschreibung
user
objectBenutzerdaten (Objekt).
user.id
objectBenutzer-ID (Objekt). Erforderlich.
user.id.value
stringBenutzer-ID.
user.name
objectBenutzername (Objekt).
user.name.value
stringBenutzername.
user.email
objectE-Mail-Adresse des Benutzers (Objekt). Das user.email-Objekt ist ein integraler Bestandteil beim Erstellen von Betrugsschutzmodellen und bei der Zahlungsabwicklung. Es ist sowohl für Xsolla als auch für Zahlungssysteme erforderlich. Das Fehlen dieses Parameters kann zu niedrigeren Akzeptanzraten führen. Erforderlich.
user.email.value
stringE-Mail-Adresse des Benutzers. Muss gemäß RFC 822-Protokoll gültig sein. Erforderlich.
user.phone
objectTelefonnummer des Benutzers (Objekt).
user.phone.value
stringTelefonnummer des Benutzers.
user.country
objectLand des Benutzers (Objekt).
user.country.value
stringLändercode, bestehend aus 2 Großbuchstaben gemäß ISO 3166-1 ALPHA-2.
user.country.allow_modify
booleanLegt fest, ob der Benutzer das Feld im Zahlungsportal bearbeiten kann. Standardwert ist 'false'.
user.attributes
objectBenutzerattribute 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
objectSteam-ID des Benutzers (Objekt).
user.steam_id.value
stringSteam-ID.
user.tracking_id
objectTracking-ID des Benutzers (Objekt).
user.tracking_id.value
stringEindeutige Tracking-ID (wird bei Marketingkampagnen verwendet).
user.public_id.value
stringParameter, 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
objectDatenverkehrsattribute (Objekt).
user.utm.utm_source
stringUrsprung des Datenverkehrs.
user.utm.utm_medium
stringDatenverkehrskanal (kontextbezogene Anzeigen, mediale Anzeigen, E-Mail-Listen, usw.).
user.utm.utm_campaign
stringKampagnenbezeichnung, ins Englische transliteriert oder übersetzt.
user.utm.utm_term
stringKampagnen-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
stringKampagneninhalt.
booleanLegt fest, ob der Benutzer eine juristische Person ist.
objectObjekt mit Angaben zur juristischen Person. Objekt und alle seine Parameter sind erforderlich, falls für user.is_legal 'true' festgelegt ist.
stringVollständiger Name des Unternehmens.
stringVollständige Unternehmensanschrift.
stringSteuerliche Identifikationsnummer.
stringLand des Unternehmenssitzes. Ländercode, bestehend aus 2 Großbuchstaben gemäß ISO 3166-1 ALPHA-2.
settings
objectBenutzerdefinierte Projekteinstellungen (Objekt).
settings.external_id
stringExterne ID der Transaktion.
settings.project_id
integerXsolla-ID des Spiels. Kann im Kundenportal eingesehen werden. Erforderlich.
settings.language
stringSprache der Benutzeroberfläche. Sprachencode, bestehend aus 2 Kleinbuchstaben gemäß ISO 639-1.
settings.return_url
stringSeite, 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
stringBevorzugte Zahlungswährung. Währungscode, bestehend aus drei Buchstaben gemäß ISO 4217.
settings.mode
stringLegen 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
integerID der Zahlungsart.
settings.payment_widget
stringZahlungs-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
objectSchnittstellen-Einstellungen (Objekt).
settings.ui.theme
stringTheme des Zahlungsportals. Als Wert lässt sich entweder 'default' (voreingestellt) oder 'default_dark' festlegen.
settings.ui.size
stringGröß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
stringGerätetyp. Als Wert lässt sich entweder 'desktop' (voreingestellt) oder 'mobile' festlegen.
settings.ui.desktop
objectSchnittstellen-Einstellungen für die Desktop-Version (Objekt).
settings.ui.desktop.header
objectEinstellungen für den Header (Objekt).
settings.ui.desktop.header.is_visible
booleanLegt fest, ob der Header im Zahlungsportal angezeigt wird.
booleanFalls 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
booleanLegt fest, ob der Projektname im Header angezeigt wird.
settings.ui.desktop.header.visible_purchase
booleanLegt fest, ob die Kaufbeschreibung (purchase.description.value) im Header angezeigt wird. ‘true’ ist voreingestellt.
settings.ui.desktop.header.type
stringErscheinungsbild 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
booleanLegt 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
objectEinstellungen zur Liste der Abo-Modelle (Objekt).
settings.ui.desktop.subscription_list.layout
stringListenvorlage. Als Wert lässt sich entweder 'list' (voreingestellt) oder 'grid' festlegen.
settings.ui.desktop.subscription_list.description
stringJeglicher Text, der im Zahlungsportal oberhalb der Liste der verfügbaren Abo-Modelle angezeigt werden soll.
settings.ui.desktop.subscription_list.display_local_price
booleanFalls 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
objectEinstellungen zur Liste der virtuellen Gegenstände (Objekt).
settings.ui.desktop.virtual_item_list.layout
stringListenvorlage. Als Wert lässt sich entweder 'list' (voreingestellt) oder 'grid' festlegen.
settings.ui.desktop.virtual_item_list.button_with_price
booleanFalls 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
stringVirtuelle Gruppe an Elementen in vertikalem/horizontalem Menü anzeigen. Es kann 'horizontal_navigation' oder 'vertical' (Standard) sein.
settings.ui.desktop.virtual_currency_list
objectEinstellungen zur Liste der virtuellen Währungen (Objekt).
settings.ui.desktop.virtual_currency_list.description
stringJeglicher Text, zur Anzeige oberhalb der Liste der virtuellen Währungen.
settings.ui.desktop.virtual_currency_list.button_with_price
booleanFalls 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
booleanLegt fest, ob dieses Element im Zahlungsportal ausgeblendet werden kann. 'true' voreingestellt.
settings.ui.mobile.mode
stringEin Benutzer kann nur mit seinen gespeicherten Zahlungsarten bezahlen. Als Wert lässt sich lediglich 'saved_accounts' festlegen.
settings.ui.mobile.header.close_button
booleanLegt 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'.
booleanLegt fest, ob der Footer in der mobilen Version des Zahlungsportals ausgeblendet ist.
settings.ui.license_url
stringLink zur EULA.
settings.ui.components
objectMenü-Einstellungen (Objekt).
settings.ui.components.virtual_items
objectUntermenü "Virtuelle Gegenstände".
settings.ui.components.virtual_items.order
integerPosition des Untermenüs im Hauptmenü.
settings.ui.components.virtual_items.hidden
booleanLegt fest, ob das Untermenü angezeigt wird.
settings.ui.components.virtual_items.selected_group
stringGruppe, die nach dem Öffnen der Registerkarte "Virtuelle Gegenstände" angezeigt wird.
settings.ui.components.virtual_items.selected_item
stringGegenstand, der nach dem Öffnen der Registerkarte "Virtuelle Gegenstände" angezeigt wird (SKU des Gegenstands).
settings.ui.components.virtual_currency
objectUntermenü "Virtuelle Währung".
settings.ui.components.virtual_currency.custom_amount
booleanLegt fest, ob der Benutzer eine willkürliche Menge der virtuellen Währung im Zahlungsportal eingeben kann.
settings.ui.components.virtual_currency.order
integerPosition des Untermenüs im Hauptmenü.
settings.ui.components.virtual_currency.hidden
booleanLegt fest, ob das Untermenü angezeigt wird.
settings.ui.components.subscriptions
objectUntermenü "Abo-Modelle" (Objekt).
settings.ui.components.subscriptions.order
integerPosition des Untermenüs im Hauptmenü.
settings.ui.components.subscriptions.hidden
booleanLegt fest, ob das Untermenü angezeigt wird.
settings.ui.mode
stringSchnittstellenmodus 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
objectDetails zum Benutzerkonto (Objekt).
settings.ui.user_account.info
objectSeite "Mein Konto".
settings.ui.user_account.info.order
integerPosition des Untermenüs im Hauptmenü.
settings.ui.user_account.info.enable
booleanLegt fest, ob das Untermenü angezeigt wird. Standardwert ist 'false'.
settings.ui.user_account.history
objectUntermenü "Historie".
settings.ui.user_account.history.order
integerPosition des Untermenüs im Hauptmenü.
settings.ui.user_account.history.enable
booleanLegt fest, ob das Untermenü angezeigt wird. Standardwert ist 'false'.
settings.ui.user_account.payment_accounts
objectUntermenü "Meine Zahlungskonten".
settings.ui.user_account.payment_accounts.order
integerPosition des Untermenüs im Hauptmenü.
settings.ui.user_account.payment_accounts.enable
booleanLegt fest, ob das Untermenü angezeigt wird. Standardwert ist 'false'.
settings.ui.user_account.subscriptions
objectUntermenü "Abonnements verwalten".
settings.ui.user_account.subscriptions.order
integerPosition des Untermenüs im Hauptmenü.
settings.ui.user_account.subscriptions.enable
booleanLegt fest, ob das Untermenü angezeigt wird. Standardwert ist 'false'.
settings.shipping_enabled
booleanOb das Formular für die Zustelladresse angezeigt werden soll. Standardwert ist 'false'.
purchase
objectObjekt, welches Angaben zum Kauf enthält.
purchase.virtual_currency
objectObjekt, welches Angaben zur virtuellen Währung enthält.
purchase.virtual_currency.quantity
floatKaufbetrag in der virtuellen Währung.
purchase.virtual_currency.currency
stringWährung, in der das Virtuelle-Währungs-Angebotspaket erworben werden kann und die bei allen Kalkulationen verwendet werden soll.
purchase.virtual_items
objectObjekt mit Daten über virtuelle Gegenstände, die erworben werden können.
purchase.virtual_items.currency
stringWährung der bezogenen Gegenstände, die bei allen Kalkulationen verwendet werden soll.
purchase.virtual_items.items
arrayDaten zum Gegenstand (Array).
purchase.virtual_items.items.sku
stringID des Gegenstands.
purchase.virtual_items.items.amount
integerGegenstandsmenge.
purchase.virtual_items.available_groups
arrayIDs der Gegenstandsgruppen (Array). Im Zahlungsportal werden lediglich Gegenstände aus der festgelegten Gruppe angezeigt.
purchase.subscription
objectDaten zum Abonnement (Objekt).
purchase.subscription.plan_id
stringID des Abo-Modells.
purchase.subscription.operation
stringDiese 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
stringProdukt-ID.
purchase.subscription.currency
stringWährung des Abo-Modells, die bei allen Kalkulationen verwendet werden soll.
purchase.subscription.available_plans
arrayAbonnement-Modelle (Array), die im Zahlungsportal angezeigt werden sollen.
purchase.subscription.trial_days
integerProbezeitraum in Tagen.
purchase.pin_codes
objectSpielschlüssel (Objekt).
purchase.pin_codes.currency
stringWährung eines Spielschlüssels innerhalb der Bestellung, die bei allen Kalkulationen verwendet werden soll.
purchase.pin_codes.codes
arraySpielschlüssel (Array).
purchase.pin_codes.codes.digital_content
stringIm Kundenportal festgelegte Spiel-SKU.
purchase.pin_codes.codes.drm
stringDie 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
objectObjekt mit den Upgrade-Daten.
purchase.pin_codes.upgrade.id_user_history
integerID des Eintrags, der Daten über den Benutzer und seine Pakete enthält.
purchase.pin_codes.upgrade.id
integerUpgrade-ID.
purchase.checkout
objectObjekt, welches Angaben zur Bezahlung enthält.
purchase.checkout.currency
stringKaufwährung. Währungscode, bestehend aus drei Buchstaben gemäß ISO 4217.
purchase.checkout.amount
floatKaufbetrag.
purchase.description
objectKaufbeschreibung (Objekt).
purchase.description.value
stringAllgemeine 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 objectsArray der Gegenstände.
purchase.description.items.name
stringName des Gegenstands.
purchase.description.items.image_url
stringLink zum Gegenstandssymbol.
purchase.description.items.description
stringGegenstandsbeschreibung in der Bestellung.
purchase.description.items.price
objectObjekt mit dem Preis des Gegenstands.
purchase.description.items.price.amount
stringPreis des Gegenstands.
purchase.description.items.quantity
integerAnzahl der Gegenstände in der Bestellung.
purchase.description.items.is_bonus
booleanLegt fest, ob ein Gegenstand als Bonus verfügbar ist. 'false' ist voreingestellt.
purchase.gift
objectBenutzerdaten (Objekt).
purchase.gift.giver_id
stringSpender-ID.
purchase.gift.message
stringNachricht vom Spender.
purchase.gift.hide_giver_from_receiver
stringLegt fest, ob die Identität des Spenders vor dem Beschenkten geheim gehalten werden soll. Standardwert ist 'true'.
purchase.gift.friends
arrayArray mit Daten über Freunde.
purchase.gift.friends.id
stringID des Geschenkempfängers.
purchase.gift.friends.name
stringE-Mail des Geschenkempfängers.
purchase.gift.friends.email
stringE-Mail des Geschenkempfängers.
purchase.coupon_code
objectInformationen über einen Rabatt- bzw. Promocode oder Prämien beim Kauf (Objekt).
purchase.coupon_code.value
stringPromocode-Wert.
purchase.coupon_code.hidden
booleanBlendet das Feld "Promocode-Wert" im Zahlungsportal aus. Standardmäßig ist 'false' festgelegt.
custom_parameters
objectIhre 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

ParameterTypBeschreibung
registration_date
stringDatum der Kontoerstellung gemäß ISO 8601.
total_hours
integerGesamtzahl der Spielstunden.
total_characters
integerAnzahl der Charaktere im Spiel.
social_networks_added
booleanFiltert danach, ob der Spieler Profile von sozialen Netzwerken verknüpft hat.
profile_image_added
booleanFiltert danach, ob der Spieler ein Profilbild hochgeladen hat.
active_date
stringLetztmalig online; Datum gemäß ISO 8601.
total_friends
integerAnzahl der Freunde.
additional_verification
booleanFiltert danach, ob der Spieler Konto-Verifikationsverfahren verwendet.
win_rate
integerGewinnquote.
last_change_password_date
stringDatum der letzten Kennwortänderung; Datumsangabe gemäß ISO 8601.
chat_activity
booleanFiltert danach, ob der Spieler die Chatfunktion verwendet.
forum_activity
booleanFiltert danach, ob der Spieler die Chatfunktion verwendet.
total_bans
integerFiltert danach, wie oft der Spieler im Chat/Forum gesperrt wurde.
profile_completed
booleanFiltert danach, ob der Spieler auf seinem Profil zusätzliche Informationen hinzugefügt hat.
notifications_enabled
booleanFiltert danach, ob der Spieler den Erhalt von Benachrichtigungen aktiviert hat.
user_level
integerLevel, Ansehen oder Rang des Spielers.
karma_points
integerKarma des Spielers.
total_sum
floatGesamtbetrag der Zahlungen.
non_premium_currency
floatBetrag der gewöhnlichen ("non-premium") Währung.
total_game_events
integerAnzahl der Ingame-Events, an denen der Spieler teilgenommen hat.
total_gifts
integerAnzahl der Geschenke im Spiel, die der Spieler verschickt/erhalten hat.
tutorial_completed
booleanFiltert danach, ob der Spieler das Tutorial des Spiels absolviert hat.
completed_tasks
integerAnzahl der erledigten Aufgaben bzw. erreichten Ziele.
items_used
booleanFiltert danach, ob der Spieler im Spiel gekaufte Gegenstände verwendet.
pvp_activity
booleanFiltert danach, ob der Spieler an PvP-Schlachten teilnimmt.
total_clans
integerAnzahl der Clans, bei denen der Spieler Mitglied ist.
unlocked_achievements
integerAnzahl an freigeschalteten Errungenschaften.
total_inventory_value
floatGesamtwert des Inventars (in Ingame-Währung).
character_customized
booleanFiltert danach, ob der Spieler seinen Charakter individuell angepasst hat.
session_time
stringDurchschnittliche 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

Notice: Ihre Datenbank darf KEINE zwei erfolgreichen Transaktionen mit derselben Kennung enthalten. 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 gesendeten Webhooks erhält. Da Internetverbindungen nicht 100 % zuverlässig sind, kann es vorkommen, dass Webhooks nicht rechtzeitig oder gar nicht empfangen werden. Außerdem kann es passieren, dass Ihr Listener mit einen HTTP-Statuscode 5xx (temporärer Server-Fehler) antwortet. Beispielsweise antwortet Ihr Listener mit dem HTTP-Statuscode 500, falls ein virtueller Gegenstand, den ein Benutzer erfolgreich gekauft hat, nicht dem Inventar des Benutzers hinzugefügt wurde.

Um solche Probleme zu beheben, stellen wir einen Wiederholungsmechanismus bereit, der nicht übermittelte Nachrichten in verschiedenen Zeitabständen erneut versendet, bis Ihr Listener sie empfängt. Ein weiterer Webhook kann innerhalb von 12 Stunden nach dem vorherigen gesendet werden. Maximal sind 12 Versuche möglich.

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

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 BenachrichtigungBeschreibung
user_validationÜberprüft, ob ein Benutzer im Spiel bereits vorhanden ist.
user_searchFordert Benutzerdaten anhand der Public User ID an.
paymentWird versendet, wenn ein Benutzer eine Zahlung abschließt.
refundWird versendet, falls eine Zahlung aus einem beliebigen Grund storniert werden muss.
afs_rejectWird versendet, wenn eine Transaktion während einer AFS-Prüfung abgelehnt wird, sendet Xsolla Transaktionsdaten an den URL-Webhook.
create_subscriptionWird versendet, wenn ein Benutzer ein Abonnement abschließt.
update_subscriptionWird versendet, wenn ein Abonnement erneuert oder geändert wird.
cancel_subscriptionWird versendet, wenn ein Abonnement gekündigt wird.
get_pincodeWird versendet, wenn die Xsolla-API den Spielschlüssel abrufen möchte.
user_balance_operationWird versendet, wenn sich der Kontostand eines Benutzers ändert (die Änderungsart wird versendet als _operationtype).
redeem_keyWird gesendet, wenn ein Benutzer einen Schlüssel aktiviert.
upgrade_refundWird bei Stornierung des Upgrades versendet.
inventory_getGegenstandsliste aus dem Spielinventar abrufen und an Sekundärmarkt übermitteln.
inventory_pullGegenstände aus dem Spielinventar an den Sekundärmarkt pullen.
inventory_pushGegenstände vom Sekundärmarkt in das Spielinventar pushen.
payment_account_addWird gesendet, wenn ein Benutzer ein Zahlungskonto hinzufügt oder speichert.
payment_account_removeWird gesendet, wenn ein Benutzer das Zahlungskonto aus den gespeicherten Konten entfernt.

Benutzervalidierung

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

ParameterTypBeschreibung
user
objectBenutzerdaten (Objekt).
user.ip
stringBenutzer-IP.
user.phone
stringTelefonnummer des Benutzers.
user.email
stringE-Mail des Benutzers.
user.id
stringBenutzer-ID. Erforderlich.
user.name
stringBenutzername.
user.country
stringLand 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).

ParameterTypBeschreibung
notification_type
stringArt der Benachrichtigung. Erforderlich.
user
objectBenutzerdaten (Objekt). Erforderlich.
user.public_id
stringPublic User ID.
user.id
stringBenutzer-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.

ParameterTypBeschreibung
notification_type
stringArt der Benachrichtigung. Erforderlich.
purchase
objectObjekt, welches Angaben zum Kauf enthält.
purchase.virtual_currency
objectZu erwerbende virtuelle Währung (Objekt).
purchase.virtual_currency.name
stringName der virtuellen Währung.
purchase.virtual_currency.sku
stringSKU des virtuellen Währungspakets (falls für das Angebotspaket festgelegt).
purchase.virtual_currency.quantity
floatMenge.
purchase.virtual_currency.currency
stringKaufwährung. Währungscode, bestehend aus drei Buchstaben gemäß ISO 4217.
purchase.virtual_currency.amount
floatPreis in echter Währung.
purchase.checkout
objectObjekt, welches Angaben zur Bezahlung enthält.
purchase.checkout.currency
stringKaufwährung. Währungscode, bestehend aus drei Buchstaben gemäß ISO 4217.
purchase.checkout.amount
floatKaufbetrag.
purchase.subscription
objectAngaben zum Abonnement (Objekt).
purchase.subscription.plan_id
stringID des Abo-Modells (extern, falls das Abo-Modell über die API angelegt wurde).
purchase.subscription.subscription_id
integerIn der Xsolla-Datenbank erfasste Abonnement-ID.
purchase.subscription.product_id
stringProdukt-ID (falls sie im Zugriffstoken versendet wurde).
purchase.subscription.tags
arrayAbo-Modell-Markierungen.
purchase.subscription.date_create
stringDatum, an dem das Abonnement abgeschlossen wurde. Datums- und Zeitangabe gemäß ISO 8601.
purchase.subscription.date_next_charge
stringNächstes Rechnungsdatum. Datums- und Zeitangabe gemäß ISO 8601.
purchase.subscription.currency
stringWährung, in welcher das Abonnement erworben wird. Währungscode, bestehend aus drei Buchstaben gemäß ISO 4217.
purchase.subscription.amount
floatPreis in echter Währung.
purchase.virtual_items
objectDie beim Kauf erworbenen virtuellen Gegenstände.
purchase.virtual_items.items
arrayDaten zum Gegenstand (Array).
purchase.virtual_items.items.sku
stringID des Gegenstands.
purchase.virtual_items.items.amount
integerGegenstandsmenge.
purchase.virtual_items.currency
stringKaufwährung. Währungscode, bestehend aus drei Buchstaben gemäß ISO 4217.
purchase.virtual_items.amount
floatKaufbetrag.
purchase.pin_codes
objectSpielschlüssel (Array).
purchase.pin_codes.digital_content
stringIm Kundenportal festgelegte Spiel-SKU.
purchase.pin_codes.drm
stringDie 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
stringWährung, mit welcher der Spielschlüssel erworben wird. Währungscode, bestehend aus drei Buchstaben gemäß ISO 4217.
purchase.pin_codes.amount
floatPreis.
purchase.pin_codes.upgrade
objectObjekt mit Upgrade-Daten.
purchase.pin_codes.upgrade.digital_content_from
objectObjekt mit Daten über das Paket, von dem aus der Benutzer ein Upgrade durchgeführt hat.
purchase.pin_codes.upgrade.digital_content_from.digital_content
stringIm Kundenportal festgelegte Spiel-SKU.
purchase.pin_codes.upgrade.digital_content_from.DRM
stringDRM-Plattform des Spiels.
purchase.pin_codes.upgrade.digital_content_to
objectObjekt mit Daten über das Paket, auf das der Benutzer ein Upgrade durchgeführt hat.
purchase.pin_codes.upgrade.digital_content_to.digital_content
stringIm Kundenportal festgelegte Spiel-SKU.
purchase.pin_codes.upgrade.digital_content_to.DRM
stringDRM-Plattform des Spiels.
purchase.pin_codes.upgrade.currency
stringKaufwährung. Währungscode, bestehend aus drei Buchstaben gemäß ISO 4217.
purchase.pin_codes.upgrade.amount
floatPreis in echter Währung.
purchase.gift
objectBenutzerdaten (Objekt).
purchase.gift.giver_id
stringSpender-ID.
purchase.gift.receiver_id
stringID des Geschenkempfängers.
purchase.gift.receiver_email
stringE-Mail des Geschenkempfängers.
purchase.gift.message
stringNachricht vom Spender.
purchase.gift.hide_giver_from_receiver
stringLegt fest, ob die Identität des Spenders vor dem Beschenkten geheim gehalten werden soll.
purchase.total
objectGesamtpreis des Einkaufs (Objekt). Erforderlich.
purchase.total.currency
stringKaufwährung. Währungscode, bestehend aus drei Buchstaben gemäß ISO 4217.
purchase.total.amount
floatGesamtbetrag der Zahlung.
purchase.promotions
arrayWerbeaktionen, die bei dieser Transaktion Verwendung finden.
purchase.promotions.technical_name
stringArbeitstitel der Werbeaktion.
purchase.promotions.id
integerID der Werbeaktion.
purchase.coupon
objectAngaben zum Gutschein (Objekt; falls ein Gutschein bei Abschluss des Abonnements genutzt wurde).
purchase.coupon.coupon_code
stringGutscheincode.
purchase.coupon.campaign_code
stringKampagne.
user
objectBenutzerdaten (Objekt).
user.ip
stringBenutzer-IP.
user.phone
stringTelefonnummer des Benutzers.
user.email
stringE-Mail des Benutzers.
user.id
stringBenutzer-ID. Erforderlich.
user.name
stringBenutzername.
user.country
stringLand des Benutzers. Ländercode, bestehend aus 2 Großbuchstaben gemäß ISO 3166-1 ALPHA-2.
user.zip
stringPostleitzahl des Benutzers.
transaction
objectDetails zur Transaktion (Objekt). Erforderlich.
transaction.id
integerID der Transaktion.
transaction.external_id
stringExterne ID der Transaktion.
transaction.payment_date
stringZahlungsdatum.
transaction.payment_method
integerID der Zahlungsart.
transaction.payment_method_order_id
stringZahlungs-ID im Zahlungssystem.
transaction.dry_run
integerTesttransaktion. Der Parameter hat den Wert 1, wenn es sich um eine Testtransaktion handelt. Er wird nicht gesendet, wenn es sich um eine echte Transaktion handelt.
transaction.agreement
integerID der Vereinbarung.
payment_details
objectZahlungsdaten (Objekt). Erforderlich.
payment_details.payment
objectVom Benutzer entrichteter Betrag (Objekt).
payment_details.payment.currency
stringWährung. Währungscode, bestehend aus drei Buchstaben gemäß ISO 4217.
payment_details.payment.amount
stringBetrag.
payment_details.payment_method_sum
objectBetrag, der vom Zahlungssystem abgebucht wird.
payment_details.payment_method_sum.currency
stringWährung. Währungscode, bestehend aus drei Buchstaben gemäß ISO 4217.
payment_details.payment_method_sum.amount
stringBetrag.
payment_details.xsolla_balance_sum
objectBetrag, der vom Xsolla-Konto abgebucht wird.
payment_details.xsolla_balance_sum.currency
stringWährung. Währungscode, bestehend aus drei Buchstaben gemäß ISO 4217.
payment_details.xsolla_balance_sum.amount
stringBetrag.
payment_details.payout
objectDetails zur Auszahlung (Objekt).
payment_details.payout.currency
stringWährung. Währungscode, bestehend aus drei Buchstaben gemäß ISO 4217.
payment_details.payout.amount
floatBetrag.
payment_details.vat
objectAngaben zur MwSt. (Objekt, nur in der EU).
payment_details.vat.currency
stringWährung. Währungscode, bestehend aus drei Buchstaben gemäß ISO 4217.
payment_details.vat.amount
floatBetrag.
payment_details.payout_currency_rate
floatWechselkurs zwischen Zahlungs- und Auszahlungswährung.
payment_details.xsolla_fee
objectXsolla-Gebühr (Objekt).
payment_details.xsolla_fee.currency
stringWährung. Währungscode, bestehend aus drei Buchstaben gemäß ISO 4217.
payment_details.xsolla_fee.amount
floatBetrag.
payment_details.payment_method_fee
objectGebühren des Zahlungssystems.
payment_details.payment_method_fee.currency
stringWährung. Währungscode, bestehend aus drei Buchstaben gemäß ISO 4217.
payment_details.payment_method_fee.amount
floatBetrag.
payment_details.sales_tax
objectSales Tax (Objekt; nur in den USA).
payment_details.sales_tax.currency
stringWährung. Währungscode, bestehend aus drei Buchstaben gemäß ISO 4217.
payment_details.sales_tax.amount
floatBetrag.
payment_details.repatriation_commission
objectObjekt mit Daten über die Rückübertragungskosten, die Xsolla von Dritten auferlegt wurden.
payment_details.repatriation_commission.currency
stringWährung der Rückübertragungskosten. Währungscode, bestehend aus drei Buchstaben gemäß ISO 4217.
payment_details.repatriation_commission.amount
floatBetrag der Rückübertragungskosten.
custom_parameters
objectIhre 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,
        'payment_method_order_id' => 1234567890123456789,
        '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,
        "payment_method_order_id":1234567890123456789,
        "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,
        "payment_method_order_id":1234567890123456789,
        "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.

ParameterTypBeschreibung
notification_type
stringArt der Benachrichtigung. Erforderlich.
purchase
objectObjekt, welches Angaben zum Kauf enthält.
purchase.virtual_currency
objectZu erwerbende virtuelle Währung (Objekt).
purchase.virtual_currency.name
stringName der virtuellen Währung.
purchase.virtual_currency.quantity
floatMenge.
purchase.virtual_currency.currency
stringKaufwährung. Währungscode, bestehend aus drei Buchstaben gemäß ISO 4217.
purchase.virtual_currency.amount
floatPreis in echter Währung.
purchase.checkout
objectObjekt, welches Angaben zur Bezahlung enthält.
purchase.checkout.currency
stringKaufwährung. Währungscode, bestehend aus drei Buchstaben gemäß ISO 4217.
purchase.checkout.amount
floatKaufbetrag.
purchase.subscription
objectAngaben zum Abonnement (Objekt).
purchase.subscription.plan_id
stringID des Abo-Modells (extern, falls das Abo-Modell über die API angelegt wurde).
purchase.subscription.tags
arrayAbo-Modell-Markierungen.
purchase.subscription.subscription_id
integerIn der Xsolla-Datenbank erfasste Abonnement-ID.
purchase.subscription.date_create
stringDatum, an dem das Abonnement abgeschlossen wurde. Datums- und Zeitangabe gemäß ISO 8601.
purchase.subscription.currency
stringWährung, in welcher das Abonnement erworben wird. Währungscode, bestehend aus drei Buchstaben gemäß ISO 4217.
purchase.subscription.amount
floatPreis in echter Währung.
purchase.virtual_items
objectDie beim Kauf erworbenen virtuellen Gegenstände.
purchase.virtual_items.items
arrayDaten zum Gegenstand (Array).
purchase.virtual_items.items.sku
stringID des Gegenstands.
purchase.virtual_items.items.amount
integerGegenstandsmenge.
purchase.virtual_items.currency
stringKaufwährung. Währungscode, bestehend aus drei Buchstaben gemäß ISO 4217.
purchase.virtual_items.amount
floatKaufbetrag.
purchase.pin_codes
objectSpielschlüssel (Objekt).
purchase.pin_codes.upgrade
objectObjekt mit Upgrade-Daten.
purchase.pin_codes.upgrade.digital_content_from
objectObjekt mit Daten über das Paket, von dem aus der Benutzer ein Upgrade durchgeführt hat.
purchase.pin_codes.upgrade.digital_content_from.digital_content
stringIm Kundenportal festgelegte Spiel-SKU.
purchase.pin_codes.upgrade.digital_content_from.DRM
stringDRM-Plattform des Spiels.
purchase.pin_codes.upgrade.digital_content_to
objectObjekt mit Daten über das Paket, auf das der Benutzer ein Upgrade durchgeführt hat.
purchase.pin_codes.upgrade.digital_content_to.digital_content
stringIm Kundenportal festgelegte Spiel-SKU.
purchase.pin_codes.upgrade.digital_content_to.DRM
stringDRM-Plattform des Spiels.
purchase.pin_codes.upgrade.currency
stringKaufwährung. Währungscode, bestehend aus drei Buchstaben gemäß ISO 4217.
purchase.pin_codes.upgrade.amount
floatPreis in echter Währung.
purchase.total
objectGesamtpreis des Einkaufs (Objekt).
purchase.total.currency
stringKaufwährung. Währungscode, bestehend aus drei Buchstaben gemäß ISO 4217.
purchase.total.amount
floatGesamtbetrag der Zahlung.
user
objectBenutzerdaten (Objekt).
user.ip
stringBenutzer-IP.
user.phone
stringTelefonnummer des Benutzers.
user.email
stringE-Mail des Benutzers.
user.id
stringBenutzer-ID. Erforderlich.
user.name
stringBenutzername.
user.country
stringLand des Benutzers. Ländercode, bestehend aus 2 Großbuchstaben gemäß ISO 3166-1 ALPHA-2.
user.zip
stringPostleitzahl des Benutzers.
transaction
objectDetails zur Transaktion (Objekt). Erforderlich.
transaction.id
integerID der Transaktion.
transaction.external_id
stringExterne ID der Transaktion.
transaction.dry_run
integerTesttransaktion. Der Parameter hat den Wert 1, wenn es sich um eine Testtransaktion handelt. Er wird nicht gesendet, wenn es sich um eine echte Transaktion handelt.
transaction.agreement
integerID der Vereinbarung.
refund_details
objectBenutzerdaten (Objekt).
refund_details.code
integerCode-ID.
refund_details.reason
stringGrund für die Rückerstattung.
refund_details.author
stringInitiator der Rückerstattung.
payment_details
objectZahlungsdaten (Objekt). Erforderlich.
payment_details.payment
objectVom Benutzer entrichteter Betrag (Objekt).
payment_details.payment.currency
stringWährung. Währungscode, bestehend aus drei Buchstaben gemäß ISO 4217.
payment_details.payment.amount
stringBetrag.
payment_details.payment_method_sum
objectBetrag, der vom Zahlungssystem abgebucht wird.
payment_details.payment_method_sum.currency
stringWährung. Währungscode, bestehend aus drei Buchstaben gemäß ISO 4217.
payment_details.payment_method_sum.amount
stringBetrag.
payment_details.xsolla_balance_sum
objectBetrag, der vom Xsolla-Konto abgebucht wird.
payment_details.xsolla_balance_sum.currency
stringWährung. Währungscode, bestehend aus drei Buchstaben gemäß ISO 4217.
payment_details.xsolla_balance_sum.amount
stringBetrag.
payment_details.payout
objectDetails zur Auszahlung (Objekt).
payment_details.payout.currency
stringWährung. Währungscode, bestehend aus drei Buchstaben gemäß ISO 4217.
payment_details.payout.amount
floatBetrag.
payment_details.vat
objectAngaben zur MwSt. (Objekt, nur in der EU).
payment_details.vat.currency
stringWährung. Währungscode, bestehend aus drei Buchstaben gemäß ISO 4217.
payment_details.vat.amount
floatBetrag.
payment_details.payout_currency_rate
floatWechselkurs zwischen Zahlungs- und Auszahlungswährung.
payment_details.xsolla_fee
objectXsolla-Gebühr (Objekt).
payment_details.xsolla_fee.currency
stringWährung. Währungscode, bestehend aus drei Buchstaben gemäß ISO 4217.
payment_details.xsolla_fee.amount
floatBetrag.
payment_details.payment_method_fee
objectGebühren des Zahlungssystems.
payment_details.payment_method_fee.currency
stringWährung. Währungscode, bestehend aus drei Buchstaben gemäß ISO 4217.
payment_details.payment_method_fee.amount
floatBetrag.
payment_details.sales_tax
objectSales Tax (Objekt; nur in den USA).
payment_details.sales_tax.currency
stringWährung. Währungscode, bestehend aus drei Buchstaben gemäß ISO 4217.
payment_details.sales_tax.amount
floatBetrag.
payment_details.repatriation_commission
objectObjekt mit Daten über die Rückübertragungskosten, die Xsolla von Dritten auferlegt wurden.
payment_details.repatriation_commission.currency
stringWährung der Rückübertragungskosten. Währungscode, bestehend aus drei Buchstaben gemäß ISO 4217.
payment_details.repatriation_commission.amount
floatBetrag der Rückübertragungskosten.
custom_parameters
objectIhre benutzerdefinierten Parameter.

Codes zur Rückerstattung:

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

ParameterTypBeschreibung
notification_type
stringArt der Benachrichtigung. Erforderlich.
purchase
objectObjekt mit den Kaufdaten. Erforderlich.
purchase.pin_codes
objectObjekt mit Daten zu den gekauften Spielpaketen.
purchase.pin_codes.purchase_type
stringKauftyp. Kann "regular" (Kauf des Pakets) oder "upgrade" (Upgrade des Pakets) lauten.
purchase.pin_codes.digital_content
stringIm Kundenportal festgelegte Spiel-SKU.
purchase.pin_codes.DRM
stringDRM-Plattform des Spiels.
purchase.pin_codes.currency
stringKaufwährung. Währungscode, bestehend aus drei Buchstaben gemäß ISO 4217.
purchase.pin_codes.amount
floatPreis in echter Währung.
purchase.pin_codes.transaction
objectObjekt mit den Transaktionsdaten.
purchase.pin_codes.transaction.id
integerID der Transaktion.
purchase.pin_codes.upgrade
objectObjekt mit den Upgrade-Daten.
purchase.pin_codes.upgrade.digital_content_from
objectObjekt mit Daten über das Paket, von dem aus der Benutzer ein Upgrade durchgeführt hat.
purchase.pin_codes.upgrade.digital_content_from.digital_content
stringIm Kundenportal festgelegte Spiel-SKU.
purchase.pin_codes.upgrade.digital_content_from.DRM
stringDRM-Plattform des Spiels.
purchase.pin_codes.upgrade.digital_content_to
objectObjekt mit Daten über das Paket, auf das der Benutzer ein Upgrade durchgeführt hat.
purchase.pin_codes.upgrade.digital_content_to.digital_content
stringIm Kundenportal festgelegte Spiel-SKU.
purchase.pin_codes.upgrade.digital_content_to.DRM
stringDRM-Plattform des Spiels.
ownership
objectObjekt mit Daten über Pakete, die dem Benutzer gehören. Erforderlich.
ownership.digital_content
stringIm Kundenportal festgelegte Spiel-SKU.
ownership.DRM
stringDRM-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.

ParameterTypBeschreibung
notification_type
stringArt der Benachrichtigung. Erforderlich.
user
objectBenutzerdaten (Objekt).
user.ip
stringBenutzer-IP.
user.phone
stringTelefonnummer des Benutzers.
user.email
stringE-Mail des Benutzers.
user.id
stringBenutzer-ID. Erforderlich.
user.name
stringBenutzername.
user.country
stringLand des Benutzers. Ländercode, bestehend aus 2 Großbuchstaben gemäß ISO 3166-1 ALPHA-2.
user.zip
stringPostleitzahl des Benutzers.
transaction
objectDetails zur Transaktion (Objekt). Erforderlich.
transaction.id
integerID der Transaktion.
transaction.external_id
stringExterne ID der Transaktion.
transaction.dry_run
integerTesttransaktion. Der Parameter hat den Wert 1, wenn es sich um eine Testtransaktion handelt. Er wird nicht gesendet, wenn es sich um eine echte Transaktion handelt.
transaction.agreement
integerID der Vereinbarung.
refund_details
objectBenutzerdaten (Objekt).
refund_details.code
integerCode-ID.
refund_details.reason
stringGrund für die Rückerstattung.
refund_details.author
stringInitiator 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.

ParameterTypBeschreibung
notification_type
stringArt der Benachrichtigung. Erforderlich.
user
objectBenutzerdaten (Objekt).
user.id
stringBenutzer-ID. Erforderlich.
user.name
stringBenutzername.
subscription
objectAngaben zum Abonnement (Objekt).
subscription.plan_id
stringID des Abo-Modells (extern, falls das Abo-Modell über die API angelegt wurde).
subscription.tags
arrayAbo-Modell-Markierungen.
subscription.subscription_id
integerIn der Xsolla-Datenbank erfasste Abonnement-ID.
subscription.product_id
stringProdukt-ID (falls sie im Zugriffstoken versendet wurde).
subscription.date_create
stringDatum, an dem das Abonnement abgeschlossen wurde. Datums- und Zeitangabe gemäß ISO 8601.
subscription.date_next_charge
stringNächstes Rechnungsdatum. Datums- und Zeitangabe gemäß ISO 8601.
subscription.trial
objectProbezeitraum (Objekt).
subscription.trial.value
integerProbezeitraum.
subscription.trial.type
stringArt 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.

ParameterTypBeschreibung
notification_type
stringArt der Benachrichtigung. Erforderlich.
user
objectBenutzerdaten (Objekt).
user.id
stringBenutzer-ID. Erforderlich.
user.name
stringBenutzername.
subscription
objectAngaben zum Abonnement (Objekt).
subscription.plan_id
stringID des Abo-Modells (extern, falls das Abo-Modell über die API angelegt wurde).
subscription.tags
arrayAbo-Modell-Markierungen.
subscription.subscription_id
integerIn der Xsolla-Datenbank erfasste Abonnement-ID.
subscription.product_id
stringProdukt-ID (falls sie im Zugriffstoken versendet wurde).
subscription.date_next_charge
stringNä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.

ParameterTypBeschreibung
notification_type
stringArt der Benachrichtigung. Erforderlich.
user
objectBenutzerdaten (Objekt).
user.id
stringBenutzer-ID. Erforderlich.
user.name
stringBenutzername.
subscription
objectAngaben zum Abonnement (Objekt).
subscription.plan_id
stringID des Abo-Modells (extern, falls das Abo-Modell über die API angelegt wurde).
subscription.tags
arrayAbo-Modell-Markierungen.
subscription.subscription_id
integerIn der Xsolla-Datenbank erfasste Abonnement-ID.
subscription.product_id
stringProdukt-ID (falls sie im Zugriffstoken versendet wurde).
subscription.date_create
stringDatum, an dem das Abonnement abgeschlossen wurde. Datums- und Zeitangabe gemäß ISO 8601.
subscription.date_end
stringKü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.

ParameterTypBeschreibung
notification_type
stringArt der Benachrichtigung.
user
objectBenutzerdaten (Objekt).
user.id
stringBenutzer-ID. Erforderlich.
user.name
stringBenutzername.
pin_code
objectAngaben zu den Spielschlüsseln (Objekt).
pin_code.digital_content
stringSpiel-SKU.
pin_code.DRM
stringDie 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.

ParameterTypBeschreibung
notification_type
stringArt der Benachrichtigung.
key
stringAktivierungsschlüssel.
sku
stringIndividuelle Schlüsselpaket-ID.
user_id
stringBenutzer-ID.
activation_date
datetimeDatum der Schlüsselaktivierung gemäß folgendem Format und ISO 8601: JJJJMMTTHHMMSS.
user_country
stringLand des Benutzers. Ländercode, bestehend aus 2 Großbuchstaben gemäß ISO 3166-1 ALPHA-2.
restriction
objectObjekt 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
stringIndividuelle Cluster-ID.
restriction.name
stringClustername.
restriction.types
arrayArray der Beschränkungsart.
restriction.countries
arrayArray der Länder im Cluster.
restriction.servers
arrayArray der Spielserver.
restriction.locales
arrayArray 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

ParameterTypBeschreibung
notification_type
stringArt der Benachrichtigung. Erforderlich. Der Wert lautet "friends_list".
user
stringEindeutige ID des Benutzers, der das Geschenk erwirbt.
query
stringName oder ID des Freundes (ganz oder teilweise).
limit
stringBegrenzung der Elementanzahl auf der Seite. Erforderlich.
offset
integerElementnummer, aus der die Liste generiert wird (die Zählung beginnt bei 0).
sign
stringSignaturzeile, 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.

ParameterTypBeschreibung
notification_type
stringArt der Benachrichtigung.
operation_type
stringOperationsart.
id_operation
integerOperations-ID in der Xsolla-Datenbank.
user
objectBenutzerdaten (Objekt).
user.id
stringBenutzer-ID. Erforderlich.
user.name
stringBenutzername.
user.email
stringE-Mail des Benutzers.
virtual_currency_balance
objectDaten zum Kontostand des Benutzers (Objekt).
virtual_currency_balance.old_value
stringKontostand vor der Transaktion.
virtual_currency_balance.new_value
stringKontostand nach der Transaktion.
virtual_currency_balance.diff
stringMenge der beim Kauf erworbenen virtuellen Währung.
transaction
objectDetails zur Transaktion (Objekt). Erforderlich.
transaction.id
integerID der Transaktion.
transaction.date
stringTransaktionsdatum.
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.

ParameterTypBeschreibung
notification_type
stringArt der Benachrichtigung.
operation_type
stringOperationsart.
id_operation
integerOperations-ID in der Xsolla-Datenbank.
user
objectBenutzerdaten (Objekt).
user.id
stringBenutzer-ID. Erforderlich.
user.name
stringBenutzername.
user.email
stringE-Mail des Benutzers.
virtual_currency_balance
objectDaten zum Kontostand des Benutzers (Objekt).
virtual_currency_balance.old_value
stringKontostand vor der Transaktion.
virtual_currency_balance.new_value
stringKontostand nach der Transaktion.
virtual_currency_balance.diff
stringMenge der beim Kauf erworbenen virtuellen Währung.
items_operation_type
stringOperationstyp, der bei den virtuellen Gegenstände zum Einsatz kommt.
items
arrayIm Einkauf enthaltene virtuelle Gegenstände (array of objects).
items.sku
stringID des Gegenstands.
items.amount
integerGegenstandsmenge.
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.

ParameterTypBeschreibung
notification_type
stringArt der Benachrichtigung.
operation_type
stringOperationsart.
id_operation
integerOperations-ID in der Xsolla-Datenbank.
user
objectBenutzerdaten (Objekt).
user.id
stringBenutzer-ID. Erforderlich.
user.name
stringBenutzername.
user.email
stringE-Mail des Benutzers.
virtual_currency_balance
objectDaten zum Kontostand des Benutzers (Objekt).
virtual_currency_balance.old_value
stringKontostand vor der Transaktion.
virtual_currency_balance.new_value
stringKontostand nach der Transaktion.
virtual_currency_balance.diff
stringMenge der beim Kauf erworbenen virtuellen Währung.
items_operation_type
stringOperationstyp, der bei den virtuellen Gegenstände zum Einsatz kommt.
items
arrayIm Einkauf enthaltene virtuelle Gegenstände (array of objects).
items.sku
stringID des Gegenstands.
items.amount
integerGegenstandsmenge.
coupon
objectAngaben zum Gutschein (Objekt).
coupon.coupon_code
stringGutscheincode.
coupon.campaign_code
stringKampagne.
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.

ParameterTypBeschreibung
notification_type
stringArt der Benachrichtigung.
operation_type
stringOperationsart.
id_operation
integerOperations-ID in der Xsolla-Datenbank.
user
objectBenutzerdaten (Objekt).
user.id
stringBenutzer-ID. Erforderlich.
user.name
stringBenutzername.
user.email
stringE-Mail des Benutzers.
virtual_currency_balance
objectDaten zum Kontostand des Benutzers (Objekt).
virtual_currency_balance.old_value
stringKontostand vor der Transaktion.
virtual_currency_balance.new_value
stringKontostand nach der Transaktion.
virtual_currency_balance.diff
stringMenge 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.

ParameterTypBeschreibung
notification_type
stringArt der Benachrichtigung.
operation_type
stringOperationsart.
id_operation
integerOperations-ID in der Xsolla-Datenbank.
user
objectBenutzerdaten (Objekt).
user.id
stringBenutzer-ID. Erforderlich.
user.name
stringBenutzername.
user.email
stringE-Mail des Benutzers.
virtual_currency_balance
objectDaten zum Kontostand des Benutzers (Objekt).
virtual_currency_balance.old_value
stringKontostand vor der Transaktion.
virtual_currency_balance.new_value
stringKontostand nach der Transaktion.
virtual_currency_balance.diff
stringMenge der beim Kauf erworbenen virtuellen Währung.
transaction
objectDetails zur Transaktion (Objekt). Erforderlich.
transaction.id
integerID der Transaktion.
transaction.date
stringTransaktionsdatum.
items_operation_type
stringOperationstyp, der bei den virtuellen Gegenstände zum Einsatz kommt.
items
arrayIm Einkauf enthaltene virtuelle Gegenstände (array of objects).
items.sku
stringID des Gegenstands.
items.amount
integerGegenstandsmenge.
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

Zahlungskonto hinzufügen

Wird immer dann gesendet, wenn ein Benutzer ein Zahlungskonto manuell hinzufügt oder etwas im Spiel kauft und dabei ein Zahlungskonto speichert. Wenden Sie sich zum Aktivieren dieser Benachrichtigung an den Account Manager.

ParameterTypBeschreibung
notification_type
stringArt der Benachrichtigung. Erforderlich.
user
objectBenutzerdaten (Objekt).
user.ip
stringBenutzer-IP.
user.email
stringE-Mail des Benutzers.
user.id
stringBenutzer-ID. Erforderlich.
user.name
stringBenutzername.
user.country
stringLand des Benutzers. Ländercode, bestehend aus 2 Großbuchstaben gemäß ISO 3166-1 ALPHA-2.
user.zip
stringPostleitzahl des Benutzers.
payment_account
objectDetails des Zahlungskontos (Objekt).
payment_account.id
stringID des Zahlungskontos. Erforderlich.
payment_account.name
stringDer Name des Zahlungskontos im Zahlungssystem, z. B. Zahlungskartennummer, E-Mail-Adresse
payment_account.payment_method
integerID der Zahlungsart.
payment_account.type
stringArt des Zahlungskontos, z. B. Karte, PayPal.
Copy
Full screen
http
  • http
  • curl
Anfrage
POST /your/uri HTTP/1.1
Host:           your.hostname
Accept:         application/json
Content-Length: 255
Content-Type:   application/json
Authorization:  Signature d09695066c52c1b8bdae92f2d6eb59f5b5f89843

{
    "notification_type": "payment_account_add",
    "user": {
        "ip": "127.0.0.1",
        "email": "email@example.com",
        "id": "1234567",
        "name": "John Smith",
        "country": "RU",
        "zip": "12345"
    },
    "payment_account": {
        "id": "12345678",
        "name": "email@example.com",
        "payment_method": "24",
        "type": "paypal"
    }
}
$ curl -v 'https://your.hostname/your/uri' \
-X POST \
-H 'Accept: application/json' \
-H 'Content-Type: application/json' \
-H 'Authorization: Signature d09695066c52c1b8bdae92f2d6eb59f5b5f89843' \
-d '{
    "notification_type":"payment_account_add",
    "user": {
        "ip": "127.0.0.1",
        "email": "email@example.com",
        "id": "1234567",
        "name": "John Smith",
        "country": "RU",
        "zip": "12345"
    },
    "payment_account": {
        "id": "12345678",
        "name": "email@example.com",
        "payment_method": "24",
        "type": "paypal"
    }
}'
Antwort
HTTP/1.1 204 No Content

Zahlungskonto entfernen

Wird immer dann gesendet, wenn ein Benutzer das Zahlungskonto aus den gespeicherten Konten entfernt. Wenden Sie sich zum Aktivieren dieser Benachrichtigung an Ihren Account Manager.

ParameterTypBeschreibung
notification_type
stringArt der Benachrichtigung. Erforderlich.
user
objectBenutzerdaten (Objekt).
user.email
stringE-Mail des Benutzers.
user.id
stringBenutzer-ID. Erforderlich.
user.name
stringBenutzername.
payment_account
objectDetails des Zahlungskontos (Objekt).
payment_account.id
stringID des Zahlungskontos. Erforderlich.
payment_account.name
stringDer Name des Zahlungskontos im Zahlungssystem, z. B. Zahlungskartennummer, E-Mail-Adresse
payment_account.payment_method
integerID der Zahlungsart.
payment_account.type
stringArt des Zahlungskontos, z. B. Karte, PayPal.
Copy
Full screen
http
  • http
  • curl
Anfrage
POST /your/uri HTTP/1.1
Host:           your.hostname
Accept:         application/json
Content-Length: 258
Content-Type:   application/json
Authorization:  Signature d90d319f05df7b0f86d2485f48e7079f0f752523


{
    "notification_type": "payment_account_remove",
    "user": {
        "email": "email@example.com",
        "id": "1234567",
        "name": "John Smith"
    },
    "payment_account": {
        "id": "12345678",
        "name": "email@example.com",
        "payment_method": "24",
        "type": "paypal"
    }
}
$ curl -v 'https://your.hostname/your/uri' \
-X POST \
-H 'Accept: application/json' \
-H 'Content-Type: application/json' \
-H 'Authorization: Signature d09695066c52c1b8bdae92f2d6eb59f5b5f89843' \
-d '{
    "notification_type": "payment_account_remove",
    "user": {
        "email": "email@example.com",
        "id": "1234567",
        "name": "John Smith"
    },
    "payment_account": {
        "id": "12345678",
        "name": "email@example.com",
        "payment_method": "24",
        "type": "paypal"
    }
}'
Antwort
HTTP/1.1 204 No Content

Webhook-Fehler

Codes bei permanenten Fehlern:

CodeNachricht
INVALID_USERUngültiger Benutzer.
INVALID_PARAMETERUngültiger Parameter.
INVALID_SIGNATUREUngültige Signatur.
INCORRECT_AMOUNTUngültiger Betrag.
INCORRECT_INVOICEUngültige Rechnung.
HTTP/1.1 400 Bad Request

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