С чего начать

Введение

API Иксоллы включает в себя:

  • Pay Station API — платежный интерфейс и методы токенизации.
  • Store API — методы для работы с модулями Внутриигровой магазин и Buy Button.
  • Subscription API — методы для подписок.
  • Publisher Account API — управление проектами и пользователями Личного кабинета, методы для работы с отчетами, тикетами поддержки.
  • Login API — методы аутентификации пользователей через собственный интерфейс (см. руководство по интеграции).

API Иксоллы использует REST-архитектуру. В API мы используем HTTP коды ответов для обозначения ошибок и URL, аналогичных структуре каталогов. Ответы API (включая ошибки) возвращаются в виде JSON.

Мы используем встроенные особенности HTTP, такие как HTTP аутентификация и HTTP методы, которые понимаются всеми HTTP клиентами, также мы поддерживаем CORS (Cross-origin resource sharing) для обеспечения безопасной работы с API вашего клиентского приложения.

API Иксоллы работает со следующими базовыми URL:

  • https://api.xsolla.com — Pay Station API, Store API, Publisher Account API
  • https://login.xsolla.com/api — Login API
Многие ресурсы включают в себя параметр merchant_id, который указывает, что приложение работает именно от вашего имени.

Запрос и ответ

Запросы к API Иксоллы должны:

  • отправляться по протоколу HTTPS;
  • использовать TLS версии 1.2 и выше;
  • содержать параметры аутентификации;
  • содержать дополнительный заголовок Content-Type: application/json для запросов типа PUT и POST.

Copy
Full screen
Small screen
    Authorization: Basic <your_authorization_basic_key>
    Content-Type: application/json

    По умолчанию все запросы возвращают ответ в виде JSON с заголовком Content-Type: application/json.

    Изменения API

    Иксолла может изменять функциональные возможности API:

    • Добавлять новые ресурсы API;
    • Добавлять необязательные параметры запроса;
    • Добавлять новые свойства к существующим ответам API;
    • Добавлять новые значения для параметров, имеющих перечисление возможных значений;
    • Добавлять новые типы вебхуков и новые параметры в JSON;
    • Добавлять необязательные заголовки в HTTP-запросы;
    • Отклонять любой запрос, если его параметры принимают недопустимые значения;
    • Ошибочно сформированные запросы могут быть приняты из-за избыточно мягкого анализа синтаксиса. В будущем, если проверка будет более строгой, подобные запросы могут быть отклонены;
    • Добавлять, изменять или удалять незадокументированные функциональные возможности в любое время.

    Ваш клиент должен продолжать работать независимо от этих изменений. К примеру, новые параметры JSON, которые не распознаются вашим клиентом, не должны мешать его работе.

    Версионирование

    Все разделы API Иксоллы поддерживают версионирование. Мы будем выпускать новую версию всякий раз, когда будут появляться несовместимые с текущей версией изменения. Версия обозначается идентификатором ("v1"/"v2" и т. п.), который указывается в URL после префикса "/merchant".

    Если вы начинаете работу с API, используйте самую последнюю версию. Если вы не указали версию команды, то по умолчанию будет вызвана первая версия.

    Info: Целостность работы API гарантируется в рамках одной версии.

    Аутентификация

    API Иксоллы использует базовую HTTP-аутентификацию. Все запросы к API должны содержать заголовок Authorization: Basic <your_authorization_basic_key>, где <your_authorization_basic_key> — пара merchant_id:api_key, закодированная по стандарту Base64.

    Значения параметров merchant_id и api_key вы можете найти в Личном кабинете Иксолла:

    • merchant_id: Настройки компании > Компания > ID продавца
    • api_key: Настройки компании > Ключ API

    Notice:
    • Никому не сообщайте ваш ключ API, так как он дает доступ к управлению аккаунтом и проектами в Личном кабинете.
    • Изменения ключа API может остановить платежи во все ваши проекты. Вызовы API, которые используют старый ключ, перестанут работать до тех пор, пока вы не обновите их с помощью нового ключа.
    Copy
    Full screen
    Small screen
    http
    • http
    • curl
    • php
    • C#
    • python
    • ruby
    • java
    • js
    Пример
    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);
    

    Команды управления ресурсами

    Все команды API указывают на тип данных, который должен быть обработан, и на действие, которое требуется совершить с этими данными. Стандартный список действий:

    ДействиеHTTP-методОписание
    СозданиеPOSTСоздает и сохраняет сущность соответствующего типа.
    СписокGETВозвращает список сущностей, удовлетворяющих запросу.
    ПолучениеGETВозвращает данные по конкретному идентификатору, которые вы присылаете в запросе.
    ЗаменаPUTЗаменяет все поля для сущности, переданной в запросе.
    ИзменениеPATCHИзменяет только указанные поля существующего объекта, который соответствует идентификатору из запроса
    УдалениеDELETEУдаляет существующий объект, который соответствует идентификатору из запроса.

    Формат даты

    Все представления дат передаются в строках согласно ISO 8601. Вы можете либо передавать дату в UTC (например, 2013-01-15T00:00:00Z), либо смещение от UTC для обозначения часового пояса (например, 2013-01-15T00:00:00-08:00 8 часов от UTC).

    Постраничная навигация

    Результат запроса должен выводиться постранично. Это означает, что вместо вывода всех результатов выполнения запроса выводится только часть. Для этого необходимо использовать параметры limit и offset.

    Типы ошибок

    Список поддерживаемых HTTP ответов:

    • 200, 201, 204 — Успешный ответ.
    • 400 Bad Request — Отсутствует обязательный параметр. Полное описание можно найти в теле ответа.
    • 401 Unauthorized — Недействительный ключ API.
    • 402 Request Failed — Параметры верны, но запрос не прошел.
    • 403 Forbidden — Нет прав доступа. Полное описание можно найти в теле ответа.
    • 404 Not Found — Соответствующего ресурса нет по данному URI.
    • 409, 422 — Параметры не верны.
    • 412 Precondition Failed — Ошибка происходит, когда проект не активирован (используется в методе получения токена).
    • 415 Unsupported Media Type — Content-Type: application/json HTTP заголовок не был отправлен.
    • 500, 502, 503, 504 Server Errors — что-то пошло не так.

    Иксолла использует стандартные HTTP коды для обозначения успешных или неуспешных запросов. В общем случае код в 2xx диапазоне обозначает успех, код диапазона 4хх означает ошибку в результате передачи некорректных параметров (например, обязательный параметр не передан, или авторизация не прошла и т.д.), код 5хх диапазона означает серверную ошибку.

    Не все ошибки в точности соответствуют HTTP кодам. Например, если запрос был верным, но не смог завершиться успешно, мы вернем 422 ошибку.

    В случае ошибочного ответа мы возвращаем JSON объект со следующими полями:

    {< T "api_table_name" >}}ТипОписание
    http_status_codeintegerHTTP код.
    messagestringПонятное сообщение с описанием ошибки. Текст всегда на английском языке. Вы не должны использовать это поле в случае какой-либо ошибки, так как значение может измениться в будущем.
    extended_messagestringРасширенное описание ошибки.
    request_idstringУникальный ID запроса, используется, чтобы помочь нам диагностировать проблему.
    Copy
    Full screen
    Small screen
    {
        "http_status_code": 500,
        "message": "Internal Server Error",
        "extended_message": null,
        "request_id": "6445b85"
    }

    Оповещения

    Введение

    Используйте webhook-и для оповещения о событиях, которые происходят с транзакцией в Иксолле. Вы можете использовать оповещения для автоматизации бэк-офиса и функций, таких как отображение статуса.

    Webhook — это сервис для оповещения о событиях, таких как:

    • совершение платежей, включая покупку виртуальной валюты, покупку предметов, и других
    • рекуррентные платежи и действия с подписками
    • Charge-back/refund по транзакции

    В большинстве случаев действие, которое вызывает webhook, является следствием действия пользователя на странице оплаты. Тем не менее и другие действия могут вызывать webhook.

    Например, вы можете отменить платеж через API Иксоллы, либо платежная система может нас оповестить об оспариваемой операции.

    Примеры действий в результате обработки webhook:

    • Пополнение баланса пользователя
    • Предоставление новых предметов пользователю
    • Начало предоставления подписки
    • Блокировка пользователя в случае подозрения в мошенничестве

    Вы должны принимать оповещения со следующих IP адресов: 185.30.20.0/24, 185.30.21.0/24.

    Notice: В вашей базе данных не должно быть двух успешных транзакций с одинаковым ID. Если ваш обработчик оповещений получил оповещение с ID, который уже есть в вашей базе, вы должны вернуть результат предыдущей обработки данной транзакции. Пожалуйста, не зачисляйте пользователю покупку еще раз и не создавайте дублирующих записей в базе данных.

    Мы не гарантируем, что ваш обработчик получит все оповещения. Поскольку интернет-соединение не является на 100% надежным, оповещения могут теряться или задерживаться. Ваш обработчик оповещений также может возвращать код статуса HTTP 5xx при временных проблемах на вашем сервере. Например, если пользователь совершил успешную покупку виртуального предмета, но она не была добавлена в инвентарь, обработчик вернет код статуса HTTP 500.

    Для решения этой проблемы сервис оповещений Иксоллы включает в себя механизм повторных оповещений. Повторные оповещения отправляются в течение 12 часов с момента первой попытки, пока ваш обработчик не подтвердит получение. Максимальное количество попыток — 12.

    Note: Хотя интернет-соединение является частой причиной проблем с оповещениями, наиболее вероятной причиной все же является проблема в логике обработчика оповещений.

    Подпись запроса

    Подпись обеспечивает безопасность передачи данных. Генерация подписи состоит из двух шагов. Первый шаг — конкатенация JSON из тела запроса и секретного ключа проекта. Второй шаг — применение SHA-1 криптографической хэш-функции к получившейся на первом шаге строке.

    Вы должны проверить, что подпись, которую вы сформировали, совпадает с подписью, отправленной в HTTP заголовке.

    Copy
    Full screen
    Small screen
    http
    • http
    • curl
    Запрос
    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"
          }
        }'

    Ответ

    Иксолла использует HTTP коды ответа для обозначения успешного или ошибочного запроса. Код 204 обозначает успешную обработку оповещения. В случае возникновения ошибки вы должны вернуть 400 код (например, отсутствует обязательный параметр, или пополнение баланса невозможно). Код 500 обозначает временную серверную ошибку.

    Список типов оповещения

    Тип оповещения передается в параметре notification_type.

    Тип оповещенияОписание
    user_validationПроверка существования пользователя в игре.
    user_searchПолучение информации о пользователе по параметру Public user ID.
    paymentОповещение об успешном платеже.
    refundОповещение об отмене платежа.
    afs_rejectОповещение об отмене транзакциии AFS системой.
    afs_black_listОповещение об изменении черного списка AFS.
    create_subscriptionОповещение о создании подписки.
    update_subscriptionОповещение о продлении подписки или о смене каких-либо параметров внутри подписки.
    cancel_subscriptionОповещение об отмене подписки.
    non_renewal_subscriptionОповещение о смене статуса на непродлеваемый.
    get_pincodeЗапрос на получение ключа.
    user_balance_operationОповещение об изменении баланса пользователя (тип операции отправляется в оповещении operation_type).
    redeem_keyОповещение об активации ключа.
    upgrade_refundОповещение об отмене апгрейда.
    payment_account_addОповещение о добавлении или сохранении платежного аккаунта.
    payment_account_removeОповещение об удалении платежного аккаунта.

    Проверка существования пользователя

    Сервер Иксоллы отправляет запрос на webhook URL, чтобы удостовериться, что данный пользователь существует в игре.

    ПараметрТипОписание
    notification_type
    stringТип оповещения. Обязательный.
    settings
    objectОбъект, содержащий настройки проекта.
    settings.project_id
    integerID игры в Иксолле. Вы можете найти этот параметр в Личном кабинете.
    settings.merchant_id
    integerID продавца.
    user
    objectОбъект с информацией о пользователе.
    user.ip
    stringIP адрес пользователя.
    user.phone
    stringНомер телефона пользователя (в международном формате).
    user.email
    stringEmail пользователя.
    user.id
    stringID пользователя. Обязательный.
    user.name
    stringИмя пользователя.
    user.country
    stringСтрана пользователя. Используется двухбуквенное обозначение страны согласно стандарту ISO 3166-1 alpha-2.
    Copy
    Full screen
    Small screen
    php
    • php
    • http
    • curl
    Запрос
    <?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"
        }
    }'
    Ответ
    <?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
    Public User ID — параметр, по которому можно однозначно идентифицировать пользователя и который хорошо известен пользователю в отличие от User ID (в качестве Public User ID может быть email, никнейм и т.д.). Этот webhook используется, когда есть возможность совершить оплату вне игры (например, при оплате на кнопку игры в терминале).

    ПараметрТипОписание
    notification_type
    stringТип оповещения. Обязательный.
    settings
    objectОбъект, содержащий настройки проекта.
    settings.project_id
    integerID игры в Иксолле. Вы можете найти этот параметр в Личном кабинете.
    settings.merchant_id
    integerID продавца.
    user
    objectОбъект с информацией о пользователе. Обязательный.
    user.public_id
    stringPublic ID пользователя.
    user.id
    stringID пользователя.
    Copy
    Full screen
    Small screen
    php
    • php
    • http
    • curl
    Запрос
    <?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"
        }
    }'
    Ответ
    <?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"
        }
    }

    Успешный платеж

    Когда пользователь успешно совершает оплату, мы отправляем детали о платеже на webhook URL.

    ПараметрТипОписание
    notification_type
    stringТип оповещения. Обязательный.
    settings
    objectОбъект, содержащий настройки проекта.
    settings.project_id
    integerID игры в Иксолле. Вы можете найти этот параметр в Личном кабинете.
    settings.merchant_id
    integerID продавца.
    purchase
    objectОбъект с информацией о заказе.
    purchase.virtual_currency
    objectОбъект с данными о приобретенной виртуальной валюте.
    purchase.virtual_currency.name
    stringНазвание виртуальной валюты.
    purchase.virtual_currency.sku
    stringАртикул пакета виртуальной валюты (если задан для пакета виртуальной валюты).
    purchase.virtual_currency.quantity
    floatКоличество бонусного товара.
    purchase.virtual_currency.currency
    stringВалюта заказа. Используется трехбуквенное обозначение валюты согласно стандарту ISO 4217.
    purchase.virtual_currency.amount
    floatСумма покупки.
    purchase.checkout
    objectОбъект с информацией о заказе.
    purchase.checkout.currency
    stringВалюта заказа. Используется трехбуквенное обозначение валюты согласно стандарту ISO 4217.
    purchase.checkout.amount
    floatСумма заказа.
    purchase.subscription
    objectОбъект с данными о подписке.
    purchase.subscription.plan_id
    stringID плана (внешний id, если план был создан через API).
    purchase.subscription.subscription_id
    integerID подписки в базе данных Иксоллы.
    purchase.subscription.product_id
    stringID продукта (если был отправлен в токене).
    purchase.subscription.tags
    arrayТеги плана.
    purchase.subscription.date_create
    stringДата создания подписки. Дата и время согласно стандарту ISO 8601.
    purchase.subscription.date_next_charge
    stringДата следующего списания. Дата и время согласно стандарту ISO 8601.
    purchase.subscription.currency
    stringВалюта рекуррентного плана. Используется трехбуквенное обозначение валюты согласно стандарту ISO 4217.
    purchase.subscription.amount
    floatСумма покупки.
    purchase.virtual_items
    objectОбъект с данными о предметах в покупке.
    purchase.virtual_items.items
    arrayМассив с данными о предмете.
    purchase.virtual_items.items.sku
    stringID предмета (артикул).
    purchase.virtual_items.items.amount
    integerКоличество этого предмета в заказе.
    purchase.virtual_items.currency
    stringВалюта заказа. Используется трехбуквенное обозначение валюты согласно стандарту ISO 4217.
    purchase.virtual_items.amount
    floatСумма заказа.
    purchase.pin_codes
    objectМассив с данными о ключах.
    purchase.pin_codes.digital_content
    stringАртикул игры, настраивается в Личном кабинете.
    purchase.pin_codes.drm
    stringDRM-платформа, на которой игра будет доступна. Может принимать значения 'steam', 'playstation', 'xbox', 'uplay', 'origin', 'drmfree', 'gog', 'epicgames', 'nintendo_eshop', 'discord_game_store' или 'oculus'. Пожалуйста, убедитесь, что нужная DRM-платформа настроена в Личном кабинете.
    purchase.pin_codes.currency
    stringВалюта покупки. Используется трехбуквенное обозначение валюты согласно стандарту ISO 4217.
    purchase.pin_codes.amount
    floatСтоимость ключа
    purchase.pin_codes.upgrade
    objectОбъект с информацией об апгрейде.
    purchase.pin_codes.upgrade.digital_content_from
    objectОбъект с информацией о пакете пользователя, с которого был произведен апгрейд.
    purchase.pin_codes.upgrade.digital_content_from.digital_content
    stringАртикул игры, настраивается в Личном кабинете.
    purchase.pin_codes.upgrade.digital_content_from.DRM
    stringDRM-платформа игры.
    purchase.pin_codes.upgrade.digital_content_to
    objectОбъект с информацией о пакете, на который пользователь перешел в рамках апгрейда.
    purchase.pin_codes.upgrade.digital_content_to.digital_content
    stringАртикул игры, настраивается в Личном кабинете.
    purchase.pin_codes.upgrade.digital_content_to.DRM
    stringDRM-платформа игры.
    purchase.pin_codes.upgrade.currency
    stringВалюта покупки. Используется трехбуквенное обозначение валюты согласно стандарту ISO 4217.
    purchase.pin_codes.upgrade.amount
    floatСумма покупки.
    purchase.gift
    objectОбъект с информацией о подарке.
    purchase.gift.giver_id
    stringID дарителя.
    purchase.gift.receiver_id
    stringID получателя подарка.
    purchase.gift.receiver_email
    stringEmail получателя подарка.
    purchase.gift.message
    stringСообщение от дарителя.
    purchase.gift.hide_giver_from_receiver
    stringФлаг, показывать ли дарителя получателю подарка.
    purchase.total
    objectОбъект с данными об общей стоимости покупки. Обязательный.
    purchase.total.currency
    stringВалюта заказа. Используется трехбуквенное обозначение валюты согласно стандарту ISO 4217.
    purchase.total.amount
    floatОбщая сумма покупки.
    purchase.promotions
    arrayМассив с данными акций, которые действуют на данную покупку.
    purchase.promotions.technical_name
    stringТехническое название акции.
    purchase.promotions.id
    integerID акции.
    purchase.coupon
    objectОбъект с информацией о купоне (если при создании подписки был использован купон).
    purchase.coupon.coupon_code
    stringКод купона.
    purchase.coupon.campaign_code
    stringКод кампании купонов.
    user
    objectОбъект с информацией о пользователе.
    user.ip
    stringIP адрес пользователя.
    user.phone
    stringНомер телефона пользователя (в международном формате).
    user.email
    stringEmail пользователя.
    user.id
    stringID пользователя. Обязательный.
    user.name
    stringИмя пользователя.
    user.country
    stringСтрана пользователя. Используется двухбуквенное обозначение страны согласно стандарту ISO 3166-1 alpha-2.
    user.zip
    stringПочтовый индекс.
    transaction
    objectОбъект с информацией о транзакции, связанной с этой операцией. Обязательный.
    transaction.id
    integerID транзакции.
    transaction.external_id
    stringВнешний ID транзакции.
    transaction.payment_date
    stringДата платежа.
    transaction.payment_method
    integerID способа оплаты в системе Иксоллы.
    transaction.payment_method_order_id
    stringID платежа в платежной системе.
    transaction.dry_run
    integerПризнак тестовой транзакции. Значение параметра равно 1 для тестового платежа, для реального платежа параметр не передается.
    transaction.agreement
    integerID соглашения.
    payment_details
    objectОбъект с финансовыми данными платежа. Обязательный.
    payment_details.payment
    objectОбъект с данными о сумме, которую оплатил пользователь.
    payment_details.payment.currency
    stringВалюта. Используется трехбуквенное обозначение валюты согласно стандарту ISO 4217.
    payment_details.payment.amount
    stringСумма.
    payment_details.payment_method_sum
    objectОбъект с данными о сумме, которая была оплачена из платежной системы.
    payment_details.payment_method_sum.currency
    stringВалюта. Используется трехбуквенное обозначение валюты согласно стандарту ISO 4217.
    payment_details.payment_method_sum.amount
    stringСумма.
    payment_details.xsolla_balance_sum
    objectОбъект с данными о сумме, которая была оплачена с Иксолла-баланса.
    payment_details.xsolla_balance_sum.currency
    stringВалюта. Используется трехбуквенное обозначение валюты согласно стандарту ISO 4217.
    payment_details.xsolla_balance_sum.amount
    stringСумма.
    payment_details.payout
    objectОбъект с данными о сумме выплаты.
    payment_details.payout.currency
    stringВалюта. Используется трехбуквенное обозначение валюты согласно стандарту ISO 4217.
    payment_details.payout.amount
    floatСумма.
    payment_details.vat
    objectРазмер VAT (только для Евросоюза).
    payment_details.vat.currency
    stringВалюта. Используется трехбуквенное обозначение валюты согласно стандарту ISO 4217.
    payment_details.vat.amount
    floatСумма.
    payment_details.payout_currency_rate
    floatКурс валюты платежа к валюте выплаты.
    payment_details.xsolla_fee
    objectРазмер комиссии Иксоллы.
    payment_details.xsolla_fee.currency
    stringВалюта. Используется трехбуквенное обозначение валюты согласно стандарту ISO 4217.
    payment_details.xsolla_fee.amount
    floatСумма.
    payment_details.payment_method_fee
    objectРазмер комиссии платежной системы.
    payment_details.payment_method_fee.currency
    stringВалюта. Используется трехбуквенное обозначение валюты согласно стандарту ISO 4217.
    payment_details.payment_method_fee.amount
    floatСумма.
    payment_details.sales_tax
    objectРазмер налога (только для США и Канады).
    payment_details.sales_tax.currency
    stringВалюта. Используется трехбуквенное обозначение валюты согласно стандарту ISO 4217.
    payment_details.sales_tax.amount
    floatСумма.
    payment_details.direct_wht
    objectНалог, удерживаемый у источника выплаты.
    payment_details.direct_wht.currency
    stringВалюта. Используется трехбуквенное обозначение валюты согласно стандарту ISO 4217.
    payment_details.direct_wht.amount
    floatСумма.
    payment_details.repatriation_commission
    objectОбъект с информацией о затратах на репатриацию, возлагаемых на Иксоллу третьими сторонами.
    payment_details.repatriation_commission.currency
    stringВалюта затрат на репатриацию. Используется трехбуквенное обозначение валюты согласно стандарту ISO 4217.
    payment_details.repatriation_commission.amount
    floatСумма затрат на репатриацию.
    custom_parameters
    objectВаши дополнительные параметры.
    Copy
    Full screen
    Small screen
    php
    • php
    • http
    • curl
    Запрос
    <?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"
        }
    }'
    Ответ
    <?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

    Отмена платежа

    При отмене платежа Иксолла присылает детали отмененной транзакции на webhook URL. Подробная информация о процессе возврата платежа приведена в рецепте.

    ПараметрТипОписание
    notification_type
    stringТип оповещения. Обязательный.
    settings
    objectОбъект, содержащий настройки проекта.
    settings.project_id
    integerID игры в Иксолле. Вы можете найти этот параметр в Личном кабинете.
    settings.merchant_id
    integerID продавца.
    purchase
    objectОбъект с информацией о заказе.
    purchase.virtual_currency
    objectОбъект с данными о приобретенной виртуальной валюте.
    purchase.virtual_currency.name
    stringНазвание виртуальной валюты.
    purchase.virtual_currency.quantity
    floatКоличество бонусного товара.
    purchase.virtual_currency.currency
    stringВалюта заказа. Используется трехбуквенное обозначение валюты согласно стандарту ISO 4217.
    purchase.virtual_currency.amount
    floatСумма покупки.
    purchase.checkout
    objectОбъект с информацией о заказе.
    purchase.checkout.currency
    stringВалюта заказа. Используется трехбуквенное обозначение валюты согласно стандарту ISO 4217.
    purchase.checkout.amount
    floatСумма заказа.
    purchase.subscription
    objectОбъект с данными о подписке.
    purchase.subscription.plan_id
    stringID плана (внешний id, если план был создан через API).
    purchase.subscription.tags
    arrayТеги плана.
    purchase.subscription.subscription_id
    integerID подписки в базе данных Иксоллы.
    purchase.subscription.date_create
    stringДата создания подписки. Дата и время согласно стандарту ISO 8601.
    purchase.subscription.currency
    stringВалюта рекуррентного плана. Используется трехбуквенное обозначение валюты согласно стандарту ISO 4217.
    purchase.subscription.amount
    floatСумма покупки.
    purchase.virtual_items
    objectОбъект с данными о предметах в покупке.
    purchase.virtual_items.items
    arrayМассив с данными о предмете.
    purchase.virtual_items.items.sku
    stringID предмета (артикул).
    purchase.virtual_items.items.amount
    integerКоличество этого предмета в заказе.
    purchase.virtual_items.currency
    stringВалюта заказа. Используется трехбуквенное обозначение валюты согласно стандарту ISO 4217.
    purchase.virtual_items.amount
    floatСумма заказа.
    purchase.pin_codes
    objectОбъект с данными о ключе.
    purchase.pin_codes.upgrade
    objectОбъект с информацией об апгрейде.
    purchase.pin_codes.upgrade.digital_content_from
    objectОбъект с информацией о пакете пользователя, с которого был произведен апгрейд.
    purchase.pin_codes.upgrade.digital_content_from.digital_content
    stringАртикул игры, настраивается в Личном кабинете.
    purchase.pin_codes.upgrade.digital_content_from.DRM
    stringDRM-платформа игры.
    purchase.pin_codes.upgrade.digital_content_to
    objectОбъект с информацией о пакете, на который пользователь перешел в рамках апгрейда.
    purchase.pin_codes.upgrade.digital_content_to.digital_content
    stringАртикул игры, настраивается в Личном кабинете.
    purchase.pin_codes.upgrade.digital_content_to.DRM
    stringDRM-платформа игры.
    purchase.pin_codes.upgrade.currency
    stringВалюта покупки. Используется трехбуквенное обозначение валюты согласно стандарту ISO 4217.
    purchase.pin_codes.upgrade.amount
    floatСумма покупки.
    purchase.total
    objectОбъект с данными об общей стоимости покупки.
    purchase.total.currency
    stringВалюта заказа. Используется трехбуквенное обозначение валюты согласно стандарту ISO 4217.
    purchase.total.amount
    floatОбщая сумма покупки.
    user
    objectОбъект с информацией о пользователе.
    user.ip
    stringIP адрес пользователя.
    user.phone
    stringНомер телефона пользователя (в международном формате).
    user.email
    stringEmail пользователя.
    user.id
    stringID пользователя. Обязательный.
    user.name
    stringИмя пользователя.
    user.country
    stringСтрана пользователя. Используется двухбуквенное обозначение страны согласно стандарту ISO 3166-1 alpha-2.
    user.zip
    stringПочтовый индекс.
    transaction
    objectОбъект с информацией о транзакции, связанной с этой операцией. Обязательный.
    transaction.id
    integerID транзакции.
    transaction.external_id
    stringВнешний ID транзакции.
    transaction.dry_run
    integerПризнак тестовой транзакции. Значение параметра равно 1 для тестового платежа, для реального платежа параметр не передается.
    transaction.agreement
    integerID соглашения.
    refund_details
    objectОбъект с финансовыми данными рефанда.
    refund_details.code
    integerID кода.
    refund_details.reason
    stringПричина отмены.
    refund_details.author
    stringАвтор рефанда.
    payment_details
    objectОбъект с финансовыми данными платежа. Обязательный.
    payment_details.payment
    objectОбъект с данными о сумме, которую оплатил пользователь.
    payment_details.payment.currency
    stringВалюта. Используется трехбуквенное обозначение валюты согласно стандарту ISO 4217.
    payment_details.payment.amount
    stringСумма.
    payment_details.payment_method_sum
    objectОбъект с данными о сумме, которая была оплачена из платежной системы.
    payment_details.payment_method_sum.currency
    stringВалюта. Используется трехбуквенное обозначение валюты согласно стандарту ISO 4217.
    payment_details.payment_method_sum.amount
    stringСумма.
    payment_details.xsolla_balance_sum
    objectОбъект с данными о сумме, которая была оплачена с Иксолла-баланса.
    payment_details.xsolla_balance_sum.currency
    stringВалюта. Используется трехбуквенное обозначение валюты согласно стандарту ISO 4217.
    payment_details.xsolla_balance_sum.amount
    stringСумма.
    payment_details.payout
    objectОбъект с данными о сумме выплаты.
    payment_details.payout.currency
    stringВалюта. Используется трехбуквенное обозначение валюты согласно стандарту ISO 4217.
    payment_details.payout.amount
    floatСумма.
    payment_details.vat
    objectРазмер VAT (только для Евросоюза).
    payment_details.vat.currency
    stringВалюта. Используется трехбуквенное обозначение валюты согласно стандарту ISO 4217.
    payment_details.vat.amount
    floatСумма.
    payment_details.payout_currency_rate
    floatКурс валюты платежа к валюте выплаты.
    payment_details.xsolla_fee
    objectРазмер комиссии Иксоллы.
    payment_details.xsolla_fee.currency
    stringВалюта. Используется трехбуквенное обозначение валюты согласно стандарту ISO 4217.
    payment_details.xsolla_fee.amount
    floatСумма.
    payment_details.payment_method_fee
    objectРазмер комиссии платежной системы.
    payment_details.payment_method_fee.currency
    stringВалюта. Используется трехбуквенное обозначение валюты согласно стандарту ISO 4217.
    payment_details.payment_method_fee.amount
    floatСумма.
    payment_details.sales_tax
    objectРазмер налога (только для США и Канады).
    payment_details.sales_tax.currency
    stringВалюта. Используется трехбуквенное обозначение валюты согласно стандарту ISO 4217.
    payment_details.sales_tax.amount
    floatСумма.
    payment_details.direct_wht
    objectНалог, удерживаемый у источника выплаты.
    payment_details.direct_wht.currency
    stringВалюта. Используется трехбуквенное обозначение валюты согласно стандарту ISO 4217.
    payment_details.direct_wht.amount
    floatСумма.
    payment_details.repatriation_commission
    objectОбъект с информацией о затратах на репатриацию, возлагаемых на Иксоллу третьими сторонами.
    payment_details.repatriation_commission.currency
    stringВалюта затрат на репатриацию. Используется трехбуквенное обозначение валюты согласно стандарту ISO 4217.
    payment_details.repatriation_commission.amount
    floatСумма затрат на репатриацию.
    custom_parameters
    objectВаши дополнительные параметры.

    Коды отмены:

    КодПричина отменыОписание
    1.Cancellation by the user request / the game request.Используется, если отмена произошла из Личного кабинета.
    2.Charge-back.Используется, если по транзакции был charge-back.
    3.Integration Error.Используется в случае проблем с интеграцией между Иксоллой и игрой. В этом случае мы не рекомендуем заносить пользователя в черный список.
    4.Fraud.Используется в случае потенциального фрода.
    5.Test Payment.Используется в случае совершения тестового платежа с последующей отменой. В этом случае мы не рекомендуем заносить пользователя в черный список.
    6.Expired Invoice.Используется, если был выбран способ оплаты с системой отложенного платежа.
    7.PS debt cancel.Используется, если транзакция была совершена через платежную систему, которая не произвела выплату по данной транзакции. В этом случае мы не рекомендуем заносить пользователя в черный список.
    8.Cancellation by the PS request.Используется, когда платежная система запросила отмену транзакции. В этом случае мы не рекомендуем заносить пользователя в черный список.
    9.Cancellation by the user request.Используется, если игра или заказ не удовлетворяют требованиям пользователя по каким-либо причинам. В этом случае мы не рекомендуем заносить пользователя в черный список.
    10.Cancellation by the game request.Используется, когда игра просит отменить транзакцию. В этом случае мы не рекомендуем заносить пользователя в черный список.
    11.Account holder called to report fraud.Используется, когда владелец аккаунта сообщил, что не совершал данный платеж.
    12.Friendly fraud.Используется, если нам сообщили о friendly fraud.
    Copy
    Full screen
    Small screen
    php
    • php
    • http
    • curl
    Запрос
    <?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"
                }
            }
        }
    }'
    Ответ
    <?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

    Отмена апгрейда

    Если пользователь отменил платеж, связанный с апгрейдом, Иксолла отправляет данные об отмененных апгрейдах и текущем пакете на webhook URL.

    ПараметрТипОписание
    notification_type
    stringТип оповещения. Обязательный.
    settings
    objectОбъект, содержащий настройки проекта.
    settings.project_id
    integerID игры в Иксолле. Вы можете найти этот параметр в Личном кабинете.
    settings.merchant_id
    integerID продавца.
    purchase
    objectОбъект с информацией о покупке. Обязательный.
    purchase.pin_codes
    objectОбъект с информацией о купленных пакетах игры.
    purchase.pin_codes.purchase_type
    stringТип покупки. Принимает значения “regular” – покупка пакета, “upgrade” – апгрейд пакета.
    purchase.pin_codes.digital_content
    stringАртикул игры, настраивается в Личном кабинете.
    purchase.pin_codes.DRM
    stringDRM-платформа игры.
    purchase.pin_codes.currency
    stringВалюта покупки. Используется трехбуквенное обозначение валюты согласно стандарту ISO 4217.
    purchase.pin_codes.amount
    floatСумма покупки.
    purchase.pin_codes.transaction
    objectОбъект с информацией о транзакции.
    purchase.pin_codes.transaction.id
    integerID транзакции.
    purchase.pin_codes.upgrade
    objectОбъект с информацией об апгрейде.
    purchase.pin_codes.upgrade.digital_content_from
    objectОбъект с информацией о пакете пользователя, с которого был произведен апгрейд.
    purchase.pin_codes.upgrade.digital_content_from.digital_content
    stringАртикул игры, настраивается в Личном кабинете.
    purchase.pin_codes.upgrade.digital_content_from.DRM
    stringDRM-платформа игры.
    purchase.pin_codes.upgrade.digital_content_to
    objectОбъект с информацией о пакете, на который пользователь перешел в рамках апгрейда.
    purchase.pin_codes.upgrade.digital_content_to.digital_content
    stringАртикул игры, настраивается в Личном кабинете.
    purchase.pin_codes.upgrade.digital_content_to.DRM
    stringDRM-платформа игры.
    ownership
    objectОбъект с информацией о пакетах, которыми владеет пользователь. Обязательный.
    ownership.digital_content
    stringАртикул игры, настраивается в Личном кабинете.
    ownership.DRM
    stringDRM-платформа игры.
    Copy
    Full screen
    Small screen
    php
    • php
    • http
    • curl
    Запрос
    <?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
      }
    }'
    Ответ

    Транзакция отклонена при проверке AFS

    Если транзакция была отклонена при проверке AFS, Иксолла присылает детали транзакции на webhook URL. Для включения оповещения, пожалуйста, обратитесь к аккаунт-менеджеру проекта.

    ПараметрТипОписание
    notification_type
    stringТип оповещения. Обязательный.
    settings
    objectОбъект, содержащий настройки проекта.
    settings.project_id
    integerID игры в Иксолле. Вы можете найти этот параметр в Личном кабинете.
    settings.merchant_id
    integerID продавца.
    user
    objectОбъект с информацией о пользователе.
    user.ip
    stringIP адрес пользователя.
    user.phone
    stringНомер телефона пользователя (в международном формате).
    user.email
    stringEmail пользователя.
    user.id
    stringID пользователя. Обязательный.
    user.name
    stringИмя пользователя.
    user.country
    stringСтрана пользователя. Используется двухбуквенное обозначение страны согласно стандарту ISO 3166-1 alpha-2.
    user.zip
    stringПочтовый индекс.
    transaction
    objectОбъект с информацией о транзакции, связанной с этой операцией. Обязательный.
    transaction.id
    integerID транзакции.
    transaction.external_id
    stringВнешний ID транзакции.
    transaction.dry_run
    integerПризнак тестовой транзакции. Значение параметра равно 1 для тестового платежа, для реального платежа параметр не передается.
    transaction.agreement
    integerID соглашения.
    refund_details
    objectОбъект с финансовыми данными рефанда.
    refund_details.code
    integerID кода.
    refund_details.reason
    stringПричина отмены.
    refund_details.author
    stringАвтор рефанда.
    Copy
    Full screen
    Small screen
    php
    • php
    • http
    • curl
    Запрос
    <?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"
      }
    }'
    Ответ
    <?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

    Обновление черного списка AFS

    При обновлении черного списка AFS (добавление или удаление параметра) Иксолла присылает оповещение на webhook URL. Добавление параметра выполняется автоматически на стороне Иксоллы или по запросу. Удаление параметра возможно только по запросу. Для включения оповещения, добавления или удаления параметра обратитесь к аккаунт-менеджеру проекта.

    ПараметрТипОписание
    notification_type
    stringТип оповещения. Обязательный.
    event
    objectОбъект с информацией о событии черного списка AFS. Обязательный.
    event.action
    stringТип события. Возможные значения: adding, removing.
    event.reason
    stringПричина события. Возможные значения:
    • Добавление: chargeback — chargeback, fraud_activity — мошенничество, suspicious_activity — подозрительная активность, ps_reported_fraud — оповещение платежной системы о фроде, linked_chargeback — связь с chargeback, partner_request — по запросу, friendly_fraud — дружеский фрод, user_reported_fraud — сообщение о фроде от пользователя, linked_parameter — связанный параметр в черном списке, other_data_in_blacklist — другие параметры в черном списке, by_afs_filters — фильтр AFS.
    • Удаление: wrongly_added — добавлен по ошибке, removed_by_cs_review — удален после обращения в техническую поддержку Иксоллы, other_forgiveness_reason — другая причина удаления.
    event.parameter
    stringНазвание параметра, по которому возникло событие. Возможные значения: nick — никнейм пользователя, email — email-адрес пользователя, ps_account — платежный аккаунт пользователя, ip_address — IP-адрес пользователя, card_issuer — банк-эмитент кредитной карты пользователя, phone — номер телефона пользователя.
    event.parameter_value
    stringЗначение параметра, по которому возникло событие.
    event.date_of_last_action
    stringВремя последнего события черного списка AFS в формате ISO 8601.
    event.transaction_id
    stringID транзакции, связанной с параметром, по которому возникло событие.
    Copy
    Full screen
    Small screen
    http
    • http
    • curl
    Запрос
    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"
    }'
    Ответ
    HTTP/1.1 204 No Content

    Создание подписки

    Когда пользователь создает подписку, Иксолла присылает оповещение на webhook URL.

    ПараметрТипОписание
    notification_type
    stringТип оповещения. Обязательный.
    settings
    objectОбъект, содержащий настройки проекта.
    settings.project_id
    integerID игры в Иксолле. Вы можете найти этот параметр в Личном кабинете.
    settings.merchant_id
    integerID продавца.
    user
    objectОбъект с информацией о пользователе.
    user.id
    stringID пользователя. Обязательный.
    user.name
    stringИмя пользователя.
    subscription
    objectОбъект с данными о подписке.
    subscription.plan_id
    stringID плана (внешний id, если план был создан через API).
    subscription.tags
    arrayТеги плана.
    subscription.subscription_id
    integerID подписки в базе данных Иксоллы.
    subscription.product_id
    stringID продукта (если был отправлен в токене).
    subscription.date_create
    stringДата создания подписки. Дата и время согласно стандарту ISO 8601.
    subscription.date_next_charge
    stringДата следующего списания. Дата и время согласно стандарту ISO 8601.
    subscription.trial
    objectОбъект с информацией о триальном периоде подписки.
    subscription.trial.value
    integerДлительность триального периода.
    subscription.trial.type
    stringТип триального периода: day.
    custom_parameters
    objectВаши дополнительные параметры.
    Copy
    Full screen
    Small screen
    php
    • php
    • http
    • curl
    Запрос
    <?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"
                    }
            }
        }'
    Ответ
    <?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

    Изменение подписки

    В случае изменения каких-либо параметров ("plan_id", "date_next_charge") подписки и в случае каждого продления подписки, мы отправляем оповещение "update_subscription" на ваш webhook URL.

    ПараметрТипОписание
    notification_type
    stringТип оповещения. Обязательный.
    settings
    objectОбъект, содержащий настройки проекта.
    settings.project_id
    integerID игры в Иксолле. Вы можете найти этот параметр в Личном кабинете.
    settings.merchant_id
    integerID продавца.
    user
    objectОбъект с информацией о пользователе.
    user.id
    stringID пользователя. Обязательный.
    user.name
    stringИмя пользователя.
    subscription
    objectОбъект с данными о подписке.
    subscription.plan_id
    stringID плана (внешний id, если план был создан через API).
    subscription.tags
    arrayТеги плана.
    subscription.subscription_id
    integerID подписки в базе данных Иксоллы.
    subscription.product_id
    stringID продукта (если был отправлен в токене).
    subscription.date_next_charge
    stringДата следующего списания. Дата и время согласно стандарту ISO 8601.
    Copy
    Full screen
    Small screen
    php
    • php
    • http
    • curl
    Запрос
    <?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"
            }
        }'
    Ответ
    <?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

    Отмена подписки

    Когда подписка отменяется по каким-либо причинам, Иксолла присылает оповещение на webhook URL.

    ПараметрТипОписание
    notification_type
    stringТип оповещения. Обязательный.
    settings
    objectОбъект, содержащий настройки проекта.
    settings.project_id
    integerID игры в Иксолле. Вы можете найти этот параметр в Личном кабинете.
    settings.merchant_id
    integerID продавца.
    user
    objectОбъект с информацией о пользователе.
    user.id
    stringID пользователя. Обязательный.
    user.name
    stringИмя пользователя.
    subscription
    objectОбъект с данными о подписке.
    subscription.plan_id
    stringID плана (внешний id, если план был создан через API).
    subscription.tags
    arrayТеги плана.
    subscription.subscription_id
    integerID подписки в базе данных Иксоллы.
    subscription.product_id
    stringID продукта (если был отправлен в токене).
    subscription.date_create
    stringДата создания подписки. Дата и время согласно стандарту ISO 8601.
    subscription.date_end
    stringДата окончания срока действия подписки. Дата и время согласно стандарту ISO 8601.
    Copy
    Full screen
    Small screen
    php
    • php
    • http
    • curl
    Запрос
    <?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"
            }
        }'
    Ответ
    <?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

    Непродлеваемая подписка

    Если по какой-либо причине статус подписки меняется на непродлеваемый, мы отправляем уведомление non_renewal_subscription на ваш webhook URL.

    ПараметрТипОписание
    settings
    objectОбъект, содержащий настройки проекта.
    settings.project_id
    integerID игры в Иксолле. Вы можете найти этот параметр в Личном кабинете. Обязательный.
    settings.merchant_id
    integerID продавца.
    notification_type
    stringТип оповещения. Обязательный.
    user
    objectОбъект с информацией о пользователе.
    user.id
    stringID пользователя. Обязательный.
    user.name
    stringИмя пользователя.
    user.email
    stringEmail пользователя.
    subscription
    objectОбъект с данными о подписке.
    subscription.subscription_id
    integerID подписки в базе данных Иксоллы.
    subscription.plan_id
    stringID плана (внешний id, если план был создан через API).
    subscription.date_create
    stringДата создания подписки. Дата и время согласно стандарту ISO 8601.
    subscription.date_next_charge
    stringДата следующего списания. Это дата следующего платежа, ожидаемого до того, как статус подписки пользователя был изменен на непродлеваемый. Дата и время согласно стандарту ISO 8601.
    subscription.currency
    stringВалюта рекуррентного плана. Используется трехбуквенное обозначение валюты согласно стандарту ISO 4217.
    subscription.amount
    floatСумма покупки.

    Получение ключа

    Иксолла отправляет API вызовы к вашему серверу для получения ключа игры после каждого успешного платежа.

    ПараметрТипОписание
    notification_type
    stringТип оповещения.
    settings
    objectОбъект, содержащий настройки проекта.
    settings.project_id
    integerID игры в Иксолле. Вы можете найти этот параметр в Личном кабинете.
    settings.merchant_id
    integerID продавца.
    user
    objectОбъект с информацией о пользователе.
    user.id
    stringID пользователя. Обязательный.
    user.name
    stringИмя пользователя.
    pin_code
    objectОбъект с информацией о ключе.
    pin_code.digital_content
    stringАртикул игры.
    pin_code.DRM
    stringDRM-платформа, на которой игра будет доступна.
    Copy
    Full screen
    Small screen
    php
    • php
    • http
    • curl
    Запрос
    <?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"
            }
        }'
    Ответ
    <?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"
    }

    Активация ключа

    Когда пользователь активирует ключ, Иксолла присылает оповещение на webhook URL.

    ПараметрТипОписание
    notification_type
    stringТип оповещения.
    settings
    objectОбъект, содержащий настройки проекта.
    settings.project_id
    integerID игры в Иксолле. Вы можете найти этот параметр в Личном кабинете.
    settings.merchant_id
    integerID продавца.
    key
    stringКлюч активации.
    sku
    stringУникальный ID пакета ключей.
    user_id
    stringID пользователя.
    activation_date
    datetimeДата активации ключа в формате ГГГГММДДЧЧММСС согласно стандарту ISO 8601.
    user_country
    stringСтрана пользователя. Используется двухбуквенное обозначение страны согласно стандарту ISO 3166-1 alpha-2.
    restriction
    objectОбъект с настройками кластера регионального ограничения. Кластер включает в себя тип ограничения, список стран, серверов и языковых версий, для которых доступна игра.
    restriction.sku
    stringУникальный ID кластера.
    restriction.name
    stringИмя кластера.
    restriction.types
    arrayМассив типов ограничений.
    restriction.countries
    arrayМассив стран, входящих в кластер.
    restriction.servers
    arrayМассив серверов игры.
    restriction.locales
    arrayМассив языковых версий игры.
    Copy
    Full screen
    Small screen
    php
    • php
    • http
    • curl
    Запрос
    <?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"
             ]
        }
    }'
    Ответ
    <?php
    
    $response = null;
    
    HTTP/1.1 204 No Content

    Получение списка друзей

    API должен быть реализован на стороне партнера. Максимальный размер списка друзей — 2000. Посмотреть рецепт.

    HTTP-ЗАПРОС

    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

    ПараметрТипОписание
    notification_type
    string'friends_list' — идентификатор , определяющий тип запрос на список друзей.
    user
    stringУникальный идентификатор пользователя, который делает покупку другу.
    query
    stringИмя или идентификатор друга. Может передавать часть имени или идентификатора друга.
    limit
    stringЛимит количества элементов на странице. Обязательный.
    offset
    integerНомер элемента, c которого выполняется вывод на странице (нумерация ведется с 0).
    sign
    stringСтрока для подписи формируется следующим образом:
    • notification_type + значения параметров, отсортированных по ключу в алфавитном порядке + secret_key
    • Второй шаг — применение SHA-1 криптографической хэш-функции к получившейся на первом шаге строке.
    Copy
    Full screen
    Small screen
    http
    • http
    • curl
    Запрос
    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
    Ответ
    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
      }
    ]

    Баланс пользователя: внутренняя операция

    Когда пользователь совершает платеж, Иксолла присылает специальное оповещение об изменении баланса пользователя.

    ПараметрТипОписание
    notification_type
    stringТип оповещения.
    settings
    objectОбъект, содержащий настройки проекта.
    settings.project_id
    integerID игры в Иксолле. Вы можете найти этот параметр в Личном кабинете.
    settings.merchant_id
    integerID продавца.
    operation_type
    stringТип операции.
    id_operation
    integerID операции в базе данных Иксоллы.
    user
    objectОбъект с информацией о пользователе.
    user.id
    stringID пользователя. Обязательный.
    user.name
    stringИмя пользователя.
    user.email
    stringEmail пользователя.
    virtual_currency_balance
    objectОбъект с данными о балансе пользователя.
    virtual_currency_balance.old_value
    stringЗначение баланса до совершения данной операции.
    virtual_currency_balance.new_value
    stringЗначение баланса после совершения данной операции.
    virtual_currency_balance.diff
    stringКоличество виртуальной валюты в заказе.
    transaction
    objectОбъект с информацией о транзакции, связанной с этой операцией. Обязательный.
    transaction.id
    integerID транзакции.
    transaction.date
    stringДата транзакции.
    Copy
    Full screen
    Small screen
    php
    • php
    • http
    • curl
    Запрос
    <?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"
        }'
    Ответ
    <?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

    Баланс пользователя: покупка в игре

    Когда пользователь совершает покупку в игре (например, покупка предметов), Иксолла присылает специальное оповещение об изменении баланса пользователя.

    ПараметрТипОписание
    notification_type
    stringТип оповещения.
    settings
    objectОбъект, содержащий настройки проекта.
    settings.project_id
    integerID игры в Иксолле. Вы можете найти этот параметр в Личном кабинете.
    settings.merchant_id
    integerID продавца.
    operation_type
    stringТип операции.
    id_operation
    integerID операции в базе данных Иксоллы.
    user
    objectОбъект с информацией о пользователе.
    user.id
    stringID пользователя. Обязательный.
    user.name
    stringИмя пользователя.
    user.email
    stringEmail пользователя.
    virtual_currency_balance
    objectОбъект с данными о балансе пользователя.
    virtual_currency_balance.old_value
    stringЗначение баланса до совершения данной операции.
    virtual_currency_balance.new_value
    stringЗначение баланса после совершения данной операции.
    virtual_currency_balance.diff
    stringКоличество виртуальной валюты в заказе.
    items_operation_type
    stringТип операции с предметами.
    items
    arrayМассив данных о предмете в заказе.
    items.sku
    stringID предмета (артикул).
    items.amount
    integerКоличество этого предмета в заказе.
    Copy
    Full screen
    Small screen
    php
    • php
    • http
    • curl
    Запрос
    <?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"
        }'
    Ответ
    <?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

    Баланс пользователя: активация купона

    Если пользователь активировал купон для получения предметов или виртуальной валюты в игре, Иксолла присылает специальное оповещение об изменении баланса пользователя.

    ПараметрТипОписание
    notification_type
    stringТип оповещения.
    settings
    objectОбъект, содержащий настройки проекта.
    settings.project_id
    integerID игры в Иксолле. Вы можете найти этот параметр в Личном кабинете.
    settings.merchant_id
    integerID продавца.
    operation_type
    stringТип операции.
    id_operation
    integerID операции в базе данных Иксоллы.
    user
    objectОбъект с информацией о пользователе.
    user.id
    stringID пользователя. Обязательный.
    user.name
    stringИмя пользователя.
    user.email
    stringEmail пользователя.
    virtual_currency_balance
    objectОбъект с данными о балансе пользователя.
    virtual_currency_balance.old_value
    stringЗначение баланса до совершения данной операции.
    virtual_currency_balance.new_value
    stringЗначение баланса после совершения данной операции.
    virtual_currency_balance.diff
    stringКоличество виртуальной валюты в заказе.
    items_operation_type
    stringТип операции с предметами.
    items
    arrayМассив данных о предмете в заказе.
    items.sku
    stringID предмета (артикул).
    items.amount
    integerКоличество этого предмета в заказе.
    coupon
    objectОбъект с данными о купоне.
    coupon.coupon_code
    stringКод купона.
    coupon.campaign_code
    stringКод кампании купонов.
    Copy
    Full screen
    Small screen
    php
    • php
    • http
    • curl
    Запрос
    <?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"
            }
        }'
    Ответ
    <?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

    Баланс пользователя: изменение вручную

    Если необходимо изменить баланс пользователя вручную, вы можете использовать тип операции "Internal".

    ПараметрТипОписание
    notification_type
    stringТип оповещения.
    settings
    objectОбъект, содержащий настройки проекта.
    settings.project_id
    integerID игры в Иксолле. Вы можете найти этот параметр в Личном кабинете.
    settings.merchant_id
    integerID продавца.
    operation_type
    stringТип операции.
    id_operation
    integerID операции в базе данных Иксоллы.
    user
    objectОбъект с информацией о пользователе.
    user.id
    stringID пользователя. Обязательный.
    user.name
    stringИмя пользователя.
    user.email
    stringEmail пользователя.
    virtual_currency_balance
    objectОбъект с данными о балансе пользователя.
    virtual_currency_balance.old_value
    stringЗначение баланса до совершения данной операции.
    virtual_currency_balance.new_value
    stringЗначение баланса после совершения данной операции.
    virtual_currency_balance.diff
    stringКоличество виртуальной валюты в заказе.
    Copy
    Full screen
    Small screen
    php
    • php
    • http
    • curl
    Запрос
    <?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"
        }'
    Ответ
    <?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

    Баланс пользователя: отмена платежа

    Когда пользователь отменяет платеж, Иксолла присылает специальное оповещение об изменении баланса пользователя.

    ПараметрТипОписание
    notification_type
    stringТип оповещения.
    settings
    objectОбъект, содержащий настройки проекта.
    settings.project_id
    integerID игры в Иксолле. Вы можете найти этот параметр в Личном кабинете.
    settings.merchant_id
    integerID продавца.
    operation_type
    stringТип операции.
    id_operation
    integerID операции в базе данных Иксоллы.
    user
    objectОбъект с информацией о пользователе.
    user.id
    stringID пользователя. Обязательный.
    user.name
    stringИмя пользователя.
    user.email
    stringEmail пользователя.
    virtual_currency_balance
    objectОбъект с данными о балансе пользователя.
    virtual_currency_balance.old_value
    stringЗначение баланса до совершения данной операции.
    virtual_currency_balance.new_value
    stringЗначение баланса после совершения данной операции.
    virtual_currency_balance.diff
    stringКоличество виртуальной валюты в заказе.
    transaction
    objectОбъект с информацией о транзакции, связанной с этой операцией. Обязательный.
    transaction.id
    integerID транзакции.
    transaction.date
    stringДата транзакции.
    items_operation_type
    stringТип операции с предметами.
    items
    arrayМассив данных о предмете в заказе.
    items.sku
    stringID предмета (артикул).
    items.amount
    integerКоличество этого предмета в заказе.
    Copy
    Full screen
    Small screen
    php
    • php
    • http
    • curl
    Запрос
    <?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"
        }'
    Ответ
    <?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

    Оповещения — ошибки

    Коды ошибок:

    КодОписание
    INVALID_USERНеверный пользователь.
    INVALID_PARAMETERНеверный параметр.
    INVALID_SIGNATUREНевалидная подпись.
    INCORRECT_AMOUNTНекорректная сумма.
    INCORRECT_INVOICEНеверный заказ.
    Copy
    Full screen
    Small screen
    HTTP/1.1 400 Bad Request
    
    {
        "error":{
            "code":"INVALID_USER",
            "message":"Invalid user"
        }
    }

    Была ли статья полезна?
    Спасибо!
    Что может сделать статью еще лучше? Сообщение
    Жаль, что так произошло
    Расскажите, почему статья не была полезна. Сообщение
    Спасибо за обратную связь!
    Ваши мысли и идеи помогут нам улучшить ваш пользовательский опыт.