Erste Schritte

Überblick

Die Xsolla-API umfasst:

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 — Pay Station API, Commerce API, Publisher Account 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.

Copy
Full screen
Small screen
    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
    Small screen
    http
    • http
    • curl
    • php
    • C#
    • python
    • ruby
    • java
    • js
    Beispiel
    GET https://api.xsolla.com/merchant/v1/merchants/{merchant_id}/events/messages
    Headers:
      Authorization: Basic <your_authorization_basic_key>
    curl --request GET \
    --url 'https://api.xsolla.com/merchant/v1/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/v1/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/v1/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/v1/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/v1/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/v1/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/v1/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.
    Copy
    Full screen
    Small screen
    {
        "http_status_code": 500,
        "message": "Internal Server Error",
        "extended_message": null,
        "request_id": "6445b85"
    }

    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, 185.30.23.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
    Small 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 notification_type 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.
    afs_black_listWird bei Aktualisierung der AFS-Blockliste versendet.
    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.
    non_renewal_subscriptionWird gesendet, wenn der Status auf "Automatisch endend" gesetzt 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 operation_type).
    redeem_keyWird gesendet, wenn ein Benutzer einen Schlüssel aktiviert.
    upgrade_refundWird bei Stornierung des Upgrades versendet.
    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
    notification_type
    stringArt der Benachrichtigung. Erforderlich.
    settings
    objectBenutzerdefinierte Projekteinstellungen (Objekt).
    settings.project_id
    integerXsolla-ID des Spiels. Kann im Kundenportal eingesehen werden.
    settings.merchant_id
    integerHändler-ID.
    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
    Small screen
    php
    • php
    • http
    • curl
    Anfrage
    <?php
    
    $request = array(
        'notification_type' => 'user_validation',
        'settings' => array(
           'project_id' => 18404,
           'merchant_id' => 2340
        ),
        '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",
        "settings": {
           "project_id": 18404,
           "merchant_id": 2340
        },
        "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",
        "settings": {
           "project_id": 18404,
           "merchant_id": 2340
        },    
        "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.
    settings
    objectBenutzerdefinierte Projekteinstellungen (Objekt).
    settings.project_id
    integerXsolla-ID des Spiels. Kann im Kundenportal eingesehen werden.
    settings.merchant_id
    integerHändler-ID.
    user
    objectBenutzerdaten (Objekt). Erforderlich.
    user.public_id
    stringPublic User ID.
    user.id
    stringBenutzer-ID.
    Copy
    Full screen
    Small screen
    php
    • php
    • http
    • curl
    Anfrage
    <?php
    
    $request = array(
        'notification_type' => 'user_search',
        'settings' => array(
           'project_id' => 18404,
           'merchant_id' => 2340
        ),
        '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",
        "settings": {
           "project_id": 18404,
           "merchant_id": 2340
        },
        "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",
        "settings": {
           "project_id": 18404,
           "merchant_id": 2340
        },
        "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.
    settings
    objectBenutzerdefinierte Projekteinstellungen (Objekt).
    settings.project_id
    integerXsolla-ID des Spiels. Kann im Kundenportal eingesehen werden.
    settings.merchant_id
    integerHändler-ID.
    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 und Kanada).
    payment_details.sales_tax.currency
    stringWährung. Währungscode, bestehend aus drei Buchstaben gemäß ISO 4217.
    payment_details.sales_tax.amount
    floatBetrag.
    payment_details.direct_wht
    objectDirekte Quellensteuer.
    payment_details.direct_wht.currency
    stringWährung. Währungscode, bestehend aus drei Buchstaben gemäß ISO 4217.
    payment_details.direct_wht.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
    Small screen
    php
    • php
    • http
    • curl
    Anfrage
    <?php
    
    $request = array(
        'notification_type' => 'payment',
        'settings' => array(
           'project_id' => 18404,
           'merchant_id' => 2340
        ),
        '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
            ),
            'sales_tax' => array(
                'currency' => 'USD',
                'amount' => 0
            ),
            'direct_wht' => array(
                'currency' => 'USD',
                'amount' => 70
            ),
            '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",
        "settings": {
           "project_id": 18404,
           "merchant_id": 2340
        },
        "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
            },
            "sales_tax": {
                "currency": "USD",
                "amount": 0
            },
            "direct_wht": {
                "currency": "USD",
                "amount": 0.70
            },
            "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",
        "settings": {
           "project_id": 18404,
           "merchant_id": 2340
        },
        "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
            },
            "sales_tax": {
                "currency": "USD",
                "amount": 0
            },
            "direct_wht": {
                "currency": "USD",
                "amount": 0.70
            },
            "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. Mehr über den Erstattungsvorgang erfahren Sie in der Anleitung.

    ParameterTypBeschreibung
    notification_type
    stringArt der Benachrichtigung. Erforderlich.
    settings
    objectBenutzerdefinierte Projekteinstellungen (Objekt).
    settings.project_id
    integerXsolla-ID des Spiels. Kann im Kundenportal eingesehen werden.
    settings.merchant_id
    integerHändler-ID.
    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 und Kanada).
    payment_details.sales_tax.currency
    stringWährung. Währungscode, bestehend aus drei Buchstaben gemäß ISO 4217.
    payment_details.sales_tax.amount
    floatBetrag.
    payment_details.direct_wht
    objectDirekte Quellensteuer.
    payment_details.direct_wht.currency
    stringWährung. Währungscode, bestehend aus drei Buchstaben gemäß ISO 4217.
    payment_details.direct_wht.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.Rückbuchung.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
    Small screen
    php
    • php
    • http
    • curl
    Anfrage
    <?php
    
    $request = array(
        'notification_type' => 'refund',
        'settings' => array(
           'project_id' => 18404,
           'merchant_id' => 2340
        ),    
        '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
            ),
            'sales_tax' => array(
                'currency' => 'USD',
                'amount' => 0
            ),
            'direct_wht' => array(
                'currency' => 'USD',
                'amount' => 70
            ),
            '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",
        "settings": {
           "project_id": 18404,
           "merchant_id": 2340
        },
        "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": {
            "sales_tax": {
                "currency": "USD",
                "amount": 0
            },
            "direct_wht": {
                "currency": "USD",
                "amount": 0.70
            },
            "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",
            "settings": {
               "project_id": 18404,
               "merchant_id": 2340
            },
            "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": {
                "sales_tax": {
                    "currency": "USD",
                    "amount": 0
                },
                "direct_wht": {
                    "currency": "USD",
                    "amount": 0.70
                },
                "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.
    settings
    objectBenutzerdefinierte Projekteinstellungen (Objekt).
    settings.project_id
    integerXsolla-ID des Spiels. Kann im Kundenportal eingesehen werden.
    settings.merchant_id
    integerHändler-ID.
    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
    Small screen
    php
    • php
    • http
    • curl
    Anfrage
    <?php
    
    $request = array (
      'notification_type' => 'upgrade_refund',
      'settings' => array(
         'project_id' => 18404,
         'merchant_id' => 2340
      ),
      '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",
      "settings": {
         "project_id": 18404,
         "merchant_id": 2340
      },
      "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",
      "settings": {
         "project_id": 18404,
         "merchant_id": 2340
      },
      "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 an den Account Manager.

    ParameterTypBeschreibung
    notification_type
    stringArt der Benachrichtigung. Erforderlich.
    settings
    objectBenutzerdefinierte Projekteinstellungen (Objekt).
    settings.project_id
    integerXsolla-ID des Spiels. Kann im Kundenportal eingesehen werden.
    settings.merchant_id
    integerHändler-ID.
    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
    Small screen
    php
    • php
    • http
    • curl
    Anfrage
    <?php
    
    $request = array(
      'notification_type' => 'afs_reject',
      'settings' => array(
        'project_id' => 18404,
        'merchant_id' => 2340
      ),
      '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",
      "settings": {
        "project_id": 18404,
        "merchant_id": 2340
      },
      "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",
      "settings": {
        "project_id": 18404,
        "merchant_id": 2340
      },
      "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

    Aktualisierte AFS-Blockliste

    Wenn die AFS-Blockliste aktualisiert wird (Hinzufügen oder Entfernen eines Parameters), sendet Xsolla die Benachrichtigung an die Webhook-URL. Das Hinzufügen von Parametern geschieht auf Anfrage oder automatisch aufseiten von Xsolla. Das Entfernen von Parametern ist nur auf Anfrage möglich. Wenden Sie sich zum Aktivieren dieser Benachrichtigung an den Account Manager.

    ParameterTypBeschreibung
    notification_type
    stringArt der Benachrichtigung. Erforderlich.
    event
    objectObjekt mit Informationen über das AFS-Blocklistenereignis. Erforderlich.
    event.action
    stringEreignistyp. Mögliche Werte: adding, removing.
    event.reason
    stringUrsache des Ereignisses. Mögliche Werte:
    • Hinzufügen: chargeback – Rückbuchung, fraud_activity – Betrug, suspicious_activity – verdächtige Aktivität, ps_reported_fraud – Betrugsbenachrichtigung durch das Zahlungssystem, linked_chargeback – rückbuchungsbezogen, partner_request – auf Anfrage, friendly_fraud – Rückbuchungsbetrug, user_reported_fraud – Benutzer meldet Betrug, linked_parameter – verknüpfter Parameter in AFS-Blockliste, other_data_in_blacklist – sonstiger Parameter in AFS-Blockliste, by_afs_filters – AFS-Filter.
    • Entfernen:wrongly_added – versehentlich hinzugefügt, removed_by_cs_review – nach Meldung an den technischen Support von Xsolla entfernt, other_forgiveness_reason – sonstiger Grund für das Entfernen.
    event.parameter
    stringName des Parameters, durch den das Ereignis aufgetreten ist. Mögliche Werte: nick – Nickname des Benutzers, email – E-Mail-Adresse des Benutzers, ps_account – Abrechnungskonto des Benutzers, ip_address – IP-Adresse des Benutzers, card_issuer – kreditkartenausgebendes Institut des Benutzers, phone – Telefonnummer des Benutzers.
    event.parameter_value
    stringWert des Parameters, durch den das Ereignis aufgetreten ist.
    event.date_of_last_action
    stringZeitpunkt des letzten AFS-Blocklistenereignisses im ISO 8601-Format.
    event.transaction_id
    stringTransaktions-ID, die dem Parameter zugeordnet ist, durch den das Ereignis aufgetreten ist.
    Copy
    Full screen
    Small screen
    http
    • http
    • curl
    Anfrage
    POST /your_uri HTTP/1.1
    Host: your.host
    Accept: application/json
    Content-Type: application/json
    Content-Length: 233
    Authorization: Signature 32c64a80d2527dc08906ae1891bac4489509b9f6
    
    {
      "event": {
        "action": "adding",
        "date_of_last_action": "2020-11-27T10:09:05+03:00",
        "parameter": "email",
        "parameter_value": "some_cool_email@gmail.com",
        "reason": "ps_reported_fraud",
        "transaction_id": "111111111"
      },
      "notification_type": "afs_black_list"
    }
    $curl -v 'https://your.hostname/your/uri' \
    -X POST \
    -H 'Authorization: Signature 32c64a80d2527dc08906ae1891bac4489509b9f6' \
    -d '{
      "event": {
        "action": "adding",
        "date_of_last_action": "2020-11-27T10:09:05+03:00",
        "parameter": "email",
        "parameter_value": "some_cool_email@gmail.com",
        "reason": "ps_reported_fraud",
        "transaction_id": "111111111"
      },
      "notification_type": "afs_black_list"
    }'
    Antwort
    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.
    settings
    objectBenutzerdefinierte Projekteinstellungen (Objekt).
    settings.project_id
    integerXsolla-ID des Spiels. Kann im Kundenportal eingesehen werden.
    settings.merchant_id
    integerHändler-ID.
    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.
    custom_parameters
    objectIhre benutzerdefinierten Parameter.
    Copy
    Full screen
    Small screen
    php
    • php
    • http
    • curl
    Anfrage
    <?php
    
    $request = array(
        'notification_type' => 'create_subscription',
        'settings' => array(
           'project_id' => 18404,
           'merchant_id' => 2340
        ),
        '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",
        "settings": {
           "project_id": 18404,
           "merchant_id": 2340
        },
        "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",
            "settings": {
               "project_id": 18404,
               "merchant_id": 2340
            },
            "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

    Wir senden die Benachrichtigung update_subscription an Ihre Webhook-URL, wenn einige Parameter im Abonnement (plan_id, date_next_charge) geändert wurden und falls ein Abonnement verlängert wird.

    ParameterTypBeschreibung
    notification_type
    stringArt der Benachrichtigung. Erforderlich.
    settings
    objectBenutzerdefinierte Projekteinstellungen (Objekt).
    settings.project_id
    integerXsolla-ID des Spiels. Kann im Kundenportal eingesehen werden.
    settings.merchant_id
    integerHändler-ID.
    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
    Small screen
    php
    • php
    • http
    • curl
    Anfrage
    <?php
    
    $request = array(
        'notification_type' => 'update_subscription',
        'settings' => array(
           'project_id' => 18404,
           'merchant_id' => 2340
        ),
        '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",
        "settings": {
           "project_id": 18404,
           "merchant_id": 2340
        },
        "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",
            "settings": {
               "project_id": 18404,
               "merchant_id": 2340
            },
            "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.
    settings
    objectBenutzerdefinierte Projekteinstellungen (Objekt).
    settings.project_id
    integerXsolla-ID des Spiels. Kann im Kundenportal eingesehen werden.
    settings.merchant_id
    integerHändler-ID.
    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
    Small screen
    php
    • php
    • http
    • curl
    Anfrage
    <?php
    
    $request = array(
        'notification_type' => 'cancel_subscription',
        'settings' => array(
           'project_id' => 18404,
           'merchant_id' => 2340
        ),
        '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",
        "settings": {
           "project_id": 18404,
           "merchant_id": 2340
        },
        "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",
            "settings": {
               "project_id": 18404,
               "merchant_id": 2340
            },
            "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

    Automatisch endendes Abo

    Wenn ein Abonnementstatus aus irgendeinem Grund auf "Automatisch endend" gesetzt wird, senden wir die Benachrichtigung non_renewal_subscription an Ihre Webhook-URL.

    ParameterTypBeschreibung
    settings
    objectBenutzerdefinierte Projekteinstellungen (Objekt).
    settings.project_id
    integerXsolla-ID des Spiels. Kann im Kundenportal eingesehen werden. Erforderlich.
    settings.merchant_id
    integerHändler-ID.
    notification_type
    stringArt der Benachrichtigung. Erforderlich.
    user
    objectBenutzerdaten (Objekt).
    user.id
    stringBenutzer-ID. Erforderlich.
    user.name
    stringBenutzername.
    user.email
    stringE-Mail des Benutzers.
    subscription
    objectAngaben zum Abonnement (Objekt).
    subscription.subscription_id
    integerIn der Xsolla-Datenbank erfasste Abonnement-ID.
    subscription.plan_id
    stringID des Abo-Modells (extern, falls das Abo-Modell über die API angelegt wurde).
    subscription.date_create
    stringDatum, an dem das Abonnement abgeschlossen wurde. Datums- und Zeitangabe gemäß ISO 8601.
    subscription.date_next_charge
    stringNächstes Rechnungsdatum. Das ist das Datum, an dem die nächste Zahlung erwartet wurde, bevor das Benutzerabonnement auf "Automatisch endend" gesetzt wurde. Datum und Uhrzeit gemäß ISO 8601.
    subscription.currency
    stringWährung, in welcher das Abonnement erworben wird. Währungscode, bestehend aus drei Buchstaben gemäß ISO 4217.
    subscription.amount
    floatPreis in echter Währung.

    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.
    settings
    objectBenutzerdefinierte Projekteinstellungen (Objekt).
    settings.project_id
    integerXsolla-ID des Spiels. Kann im Kundenportal eingesehen werden.
    settings.merchant_id
    integerHändler-ID.
    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
    Small screen
    php
    • php
    • http
    • curl
    Anfrage
    <?php
    
    $request = array (
           'notification_type' => 'get_pincode',
           'settings' => array(
              'project_id' => 18404,
              'merchant_id' => 2340
           ),
           '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",
        "settings": {
           "project_id": 18404,
           "merchant_id": 2340
        },
        "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",
            "settings": {
               "project_id": 18404,
               "merchant_id": 2340
            },
            "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.
    settings
    objectBenutzerdefinierte Projekteinstellungen (Objekt).
    settings.project_id
    integerXsolla-ID des Spiels. Kann im Kundenportal eingesehen werden.
    settings.merchant_id
    integerHändler-ID.
    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
    Small screen
    php
    • php
    • http
    • curl
    Anfrage
    <?php
    $request = array(
        'notification_type' => 'redeem_key',
        'settings' => array(
           'project_id' => 18404,
           'merchant_id' => 2340
        ),
        '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",
      "settings": {
         "project_id": 18404,
         "merchant_id": 2340
      },
      "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",
      "settings": {
            "project_id": 18404,
            "merchant_id": 2340
      },
      "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

    Copy
    Full screen
    Small screen
    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
    Small 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.
    settings
    objectBenutzerdefinierte Projekteinstellungen (Objekt).
    settings.project_id
    integerXsolla-ID des Spiels. Kann im Kundenportal eingesehen werden.
    settings.merchant_id
    integerHändler-ID.
    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
    Small screen
    php
    • php
    • http
    • curl
    Anfrage
    <?php
    
    $request = array(
        'settings' => array(
            'project_id' => 18404,
            'merchant_id' => 2340
        ),
        '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
    
    {
        "settings": {
            "project_id": 18404,
            "merchant_id": 2340
        },
        "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 '{
            "settings": {
              "project_id": 18404,
              "merchant_id": 2340
            },
            "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.
    settings
    objectBenutzerdefinierte Projekteinstellungen (Objekt).
    settings.project_id
    integerXsolla-ID des Spiels. Kann im Kundenportal eingesehen werden.
    settings.merchant_id
    integerHändler-ID.
    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
    Small screen
    php
    • php
    • http
    • curl
    Anfrage
    <?php
    
    $request = array(
        'settings' => array(
                'project_id' => 18404,
                'merchant_id' => 2340
        ),
        '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
    
    {
        "settings": {
            "project_id": 18404,
            "merchant_id": 2340
        },
        "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 '{
            "settings": {
                "project_id": 18404,
                "merchant_id": 2340
            },
            "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.
    settings
    objectBenutzerdefinierte Projekteinstellungen (Objekt).
    settings.project_id
    integerXsolla-ID des Spiels. Kann im Kundenportal eingesehen werden.
    settings.merchant_id
    integerHändler-ID.
    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
    Small screen
    php
    • php
    • http
    • curl
    Anfrage
    <?php
    
    $request = array(
        'settings' => array(
            'project_id' => 18404,
            'merchant_id' => 2340
        ),
        '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
    
    {
        "settings": {
            "project_id": 18404,
            "merchant_id": 2340
        },
        "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 '{
            "settings": {
                "project_id": 18404,
                "merchant_id": 2340
            },
            "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.
    settings
    objectBenutzerdefinierte Projekteinstellungen (Objekt).
    settings.project_id
    integerXsolla-ID des Spiels. Kann im Kundenportal eingesehen werden.
    settings.merchant_id
    integerHändler-ID.
    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
    Small screen
    php
    • php
    • http
    • curl
    Anfrage
    <?php
    
    $request = array(
        'settings' => array(
            'project_id' => 18404,
            'merchant_id' => 2340
        ),
        '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
    
    {
        "settings": {
            "project_id": 18404,
            "merchant_id": 2340
        },
        "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 '{
            "settings": {
              "project_id": 18404,
              "merchant_id": 2340
            },
            "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.
    settings
    objectBenutzerdefinierte Projekteinstellungen (Objekt).
    settings.project_id
    integerXsolla-ID des Spiels. Kann im Kundenportal eingesehen werden.
    settings.merchant_id
    integerHändler-ID.
    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
    Small screen
    php
    • php
    • http
    • curl
    Anfrage
    <?php
    
    $request = array(
         'settings' => array(
             'project_id' => 18404,
             'merchant_id' => 2340
         ),
         '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
    
    {
        "settings": {
            "project_id": 18404,
            "merchant_id": 2340
        },
        "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 '{
            "settings": {
              "project_id": 18404,
              "merchant_id": 2340
            },
            "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

    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.
    Copy
    Full screen
    Small screen
    HTTP/1.1 400 Bad Request
    
    {
        "error":{
            "code":"INVALID_USER",
            "message":"Invalid user"
        }
    }

    War dieser Artikel hilfreich?
    Vielen Dank!
    Gibt es etwas, das wir verbessern können? Nachricht
    Das tut uns leid
    Bitte erläutern Sie, weshalb dieser Artikel nicht hilfreich ist. Nachricht
    Vielen Dank für Ihr Feedback!
    Wir werden Ihr Feedback aufgreifen und dazu nutzen, Ihr Erlebnis verbessern.