Getting Started

Overview

Xsolla API includes:

Xsolla API uses the REST architecture. The API has predictable, resource-oriented URLs and uses HTTP response codes to indicate API errors. The API always responds in the JSON format, including in case of errors.

The API uses built-in HTTP features such as HTTP authentication and HTTP verbs, which can be interpreted by off-the-shelf HTTP clients. It also supports cross-origin resource sharing, allowing you to access it securely from a client web application.

Xsolla API uses the following endpoint paths:

  • https://api.xsolla.com — Pay Station API, Commerce API, Publisher Account API
  • https://login.xsolla.com/api — Login API
Most endpoint paths include the merchant_id parameter. This indicates that the requesting application is running on your behalf.

Requests and Responses

The requests to Xsolla API must:

  • be sent over HTTPS,
  • use TLS 1.2 or higher,
  • contain authentication parameters,
  • contain an additional header: Content-Type: application/json for PUT and POST requests.

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

    By default, all requests return a response with JSON data in the body and Content-Type: application/json in the header.

    API Changes

    Xsolla may change the API functionality as follows:

    • Add new API resources
    • Add optional request parameters
    • Add new properties to existing API responses
    • Add new values for existing parameters with enumerable values
    • Add new webhook types and JSON parameters
    • Add optional HTTP request headers
    • Reject any request in which valid parameters contain invalid values
    • Reject improperly formed requests that were previously accepted due to lenient parsing, if the parsing logic is changed
    • Add, change, or remove undocumented functionality at any time

    Your client should remain functional regardless of such changes. For example, new JSON parameters that aren’t recognized by your client should not hinder its normal operation.

    Versioning

    All Xsolla API methods support versioning. We will issue a new version every time there are changes incompatible with the current version. The version is identified by "v1"/"v2"/etc. following the "/merchant" prefix in the URL.

    If this is your first time working with the API, use the latest version. If you omit the version, we will use the first version by default.

    Info: Keep in mind that we can only guarantee API integrity within the same version.

    Authentication

    Xsolla API uses basic access authentication. All requests to API must contain the Authorization: Basic <your_authorization_basic_key> header, where <your_authorization_basic_key> is the merchant_id:api_key pair encoded according to the Base64 standard.

    Go to Xsolla Publisher Account to find values of the merchant_id and api_key parameters:

    • merchant_id: Company settings > Company > Merchant ID
    • api_key: Company settings > API key

    Notice:
    • Keep your API key in secret. It provides access to your personal account and your projects in Publisher Account.
    • Changing the API key may stop payments to all your projects. API calls that use your current key will stop working until you update them with your new key.
    Copy
    Full screen
    Small screen
    http
    • http
    • curl
    • php
    • C#
    • python
    • ruby
    • java
    • js
    Example
    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);
    

    Endpoint Types

    The type of an endpoint indicates what kind of data it handles and what action it performs on it. The most common actions are:

    ActionHTTP MethodDescription
    CreatePOSTCreates and saves an entity of the specified type.
    ListGETReturns a list of entities matching the query. To get details on an entity, first find out its ID using the corresponding List endpoint, and then provide this ID to the corresponding Retrieve endpoint.
    RetrieveGETProvides details on the entity with the specified ID.
    ReplacePUTModifies all fields of the entity with the specified ID.
    UpdatePATCHModifies specified fields of the entity with the specified ID.
    DeleteDELETEDeletes the entity with the specified ID.

    Date Format

    All dates are specified as strings according to ISO 8601. You can specify date strings either in UTC (e.g., 2013-01-15T00:00:00Z), or indicating the UTC offset (e.g., 2013-01-15T00:00:00-08:00 for eight hours behind UTC). In the latter case, make sure to take into account the daylight saving time, if applicable.

    Pagination

    List endpoints might paginate the results they return. This means that, instead of returning all results in a single response, these endpoints might return some of the results, along with a response header that links to the next set of results. For this purpose we use offset and limit parameters.

    Errors Handling

    List of supported HTTP errors:

    • 200, 201, 204 — No error
    • 400 Bad Request — This often indicates a required parameter missing. Refer to the response body for details
    • 401 Unauthorized — No valid API key provided
    • 402 Request Failed — Request failed despite valid parameters
    • 403 Forbidden — No permission. Refer to the response body for details
    • 404 Not Found — The requested item doesn't exist
    • 409, 422 — Invalid request parameters
    • 412 Precondition Failed — The project has not been activated yet (used in the Get Token method)
    • 415 Unsupported Media Type — 'Content-Type: application/json' missing in HTTP header
    • 500, 502, 503, 504 Server Errors — Something went wrong

    Xsolla uses conventional HTTP response codes to indicate whether the API request was successful. In general, 2xx indicates success, 4xx indicates an error in the provided information (e.g., a required parameter missing, failed authorization, etc.), and 5xx indicates a problem with Xsolla's servers.

    But not all errors perfectly match HTTP response codes. For example, if a request was valid but failed, the API will return the 422 error code.

    All API error responses provide a JSON object with the following fields:

    {< T "api_table_name" >}}TypeDescription
    http_status_codeintegerHTTP code.
    messagestringA human-readable message describing the error. This message is always in English. Do not rely on this value for any particular error, because it might change in the future.
    extended_messagestringMore detailed error description.
    request_idstringUnique request ID that might be used for troubleshooting.
    Copy
    Full screen
    Small screen
    {
        "http_status_code": 500,
        "message": "Internal Server Error",
        "extended_message": null,
        "request_id": "6445b85"
    }

    Webhooks

    Overview

    Webhooks allow you to receive notifications of events that happen to your Xsolla transactions. Use webhooks to automate back-end and supplementary functions, such as providing status and other transaction-related information.

    We use webhooks for:

    • Payments, including purchases of virtual currency and items, bank card payments, and so on
    • Recurring payments and subscription actions
    • Transaction-related charge-backs/refunds

    In most cases, webhooks are triggered by user actions on your website. But they can come from other actions, too. For example, a back-end process on your website may invoke an API method to refund a payment, or the payment system may send a notification about a disputed charge.

    You must write or use a so-called listener, or handler, to receive and process webhooks. This is a program that waits for a webhook and usually passes it to an internal workflow of yours, which responds appropriately.

    For example, you can do the following after receiving a webhook:

    • Filling up a user’s balance
    • Unlocking new item for a user
    • Starting subscription service
    • Blocking user after fraud detection

    Listen to webhooks at the following IP addresses: 185.30.20.0/24, 185.30.21.0/24, 185.30.23.0/24.

    Notice: Your database must NOT contain two successful transactions with the same ID. If your listener receives a webhook with an existing transaction ID, it must return the latest result for that transaction. Avoid charging the user twice or creating duplicate records in your database.

    We cannot guarantee that your listener will receive all the webhooks we send. As internet connection is not 100% reliable, webhooks may fail to come on time or at all. Moreover, your listener may return a 5xx HTTP code for a temporary error on your server. For example, your listener returns a 500 HTTP response code in case a virtual item that a user purchased successfully was not added to the user's inventory.

    To address these issues, we provide a retry mechanism that resends failed messages at various intervals until your listener receives them. A repeated webhook may be sent within 12 hours after the previous one. The maximum number of retries is 12.

    Note: Although connection problems may indeed result in lost, delayed, or duplicate webhooks, the most common cause is faulty logic on the listener side.

    Sign Requests

    Digital signatures enable secure data transmission. To generate the signature, (1) concatenate the request's JSON body with your project's secret key and (2) apply SHA-1 hashing to the resulting string.

    Make sure that the created signature matches the one passed in the HTTP header.

    Copy
    Full screen
    Small screen
    http
    • http
    • curl
    Request
    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"
          }
        }'

    Response Codes

    Xsolla API accepts conventional HTTP response codes for successful and failed requests. Code 204 indicates successful processing. Return code 400 in case of an error in the provided information (e.g., a required parameter missing, a failed recharge, etc.). Use code 500 for temporary errors with your servers.

    Webhooks List

    The type of notification is sent in the notification_type parameter.

    Notification TypeDescription
    user_validationCheck if a user exists in the game.
    user_searchGet user info based on Public User ID.
    paymentSent when a user completes a payment.
    refundSent when a payment must be canceled for any reason.
    afs_rejectSent when a transaction is declined during an AFS check.
    afs_black_listSent when the AFS blocklist is updated.
    create_subscriptionSent when a user creates a subscription.
    update_subscriptionSent when a subscription is renewed or changed.
    cancel_subscriptionSent when a subscription is canceled.
    non_renewal_subscriptionSent when status is set to nonrenewing.
    get_pincodeSent when Xsolla API needs to obtain the game keys.
    user_balance_operationSent when a user balance changes (the type of operation is sent in operation_type).
    redeem_keySent when a user activates a key.
    upgrade_refundSent when the upgrade is cancelled.
    payment_account_addSent when a user adds or saves payment account.
    payment_account_removeSent when a user removes the payment account from saved accounts.

    User Validation

    Sent to verify that a user exists in the game.

    ParameterTypeDescription
    notification_type
    stringType of notification. Required.
    settings
    objectCustom project settings (object).
    settings.project_id
    integerGame’s Xsolla ID. Can be found in Publisher Account.
    settings.merchant_id
    integerMerchant ID.
    user
    objectUser details (object).
    user.ip
    stringUser IP.
    user.phone
    stringUser phone.
    user.email
    stringUser email.
    user.id
    stringUser ID. Required.
    user.name
    stringUsername.
    user.country
    stringUser's country. Two-letter uppercase country code per ISO 3166-1 alpha-2.
    Copy
    Full screen
    Small screen
    php
    • php
    • http
    • curl
    Request
    <?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"
        }
    }'
    Response
    <?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
    Sent to retrieve user details using their Public User ID — a parameter that uniquely identifies the user and is known to them (email, screen name, etc). It allows the user to make purchases outside the game store (e.g., via cash kiosks).

    ParameterTypeDescription
    notification_type
    stringType of notification. Required.
    settings
    objectCustom project settings (object).
    settings.project_id
    integerGame’s Xsolla ID. Can be found in Publisher Account.
    settings.merchant_id
    integerMerchant ID.
    user
    objectUser details (object). Required.
    user.public_id
    stringPublic user ID.
    user.id
    stringUser ID.
    Copy
    Full screen
    Small screen
    php
    • php
    • http
    • curl
    Request
    <?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"
        }
    }'
    Response
    <?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"
        }
    }

    Payment

    Sent whenever a user completes a payment. Includes payment details.

    ParameterTypeDescription
    notification_type
    stringType of notification. Required.
    settings
    objectCustom project settings (object).
    settings.project_id
    integerGame’s Xsolla ID. Can be found in Publisher Account.
    settings.merchant_id
    integerMerchant ID.
    purchase
    objectPurchase details (object).
    purchase.virtual_currency
    objectVirtual currency to purchase (object).
    purchase.virtual_currency.name
    stringVirtual currency name.
    purchase.virtual_currency.sku
    stringVirtual currency package SKU (if set for the virtual currency package).
    purchase.virtual_currency.quantity
    floatQuantity.
    purchase.virtual_currency.currency
    stringCurrency of the purchase. Three-letter currency code per ISO 4217.
    purchase.virtual_currency.amount
    floatPrice in real currency.
    purchase.checkout
    objectCheckout details (object).
    purchase.checkout.currency
    stringCurrency of the purchase. Three-letter currency code per ISO 4217.
    purchase.checkout.amount
    floatPurchase amount.
    purchase.subscription
    objectSubscription details (object).
    purchase.subscription.plan_id
    stringPlan ID (external if the plan was created via API).
    purchase.subscription.subscription_id
    integerSubscription ID in Xsolla database.
    purchase.subscription.product_id
    stringProduct ID (if sent in the access token).
    purchase.subscription.tags
    arrayPlan tags.
    purchase.subscription.date_create
    stringSubscription creation date. Date and time per ISO 8601.
    purchase.subscription.date_next_charge
    stringNext billing date. Date and time per ISO 8601.
    purchase.subscription.currency
    stringSubscription currency. Three-letter currency code per ISO 4217.
    purchase.subscription.amount
    floatPrice in real currency.
    purchase.virtual_items
    objectVirtual items in purchase (object).
    purchase.virtual_items.items
    arrayItem data (array).
    purchase.virtual_items.items.sku
    stringItem ID.
    purchase.virtual_items.items.amount
    integerItem quantity.
    purchase.virtual_items.currency
    stringCurrency of the purchase. Three-letter currency code per ISO 4217.
    purchase.virtual_items.amount
    floatPurchase amount.
    purchase.pin_codes
    objectGame keys (array).
    purchase.pin_codes.digital_content
    stringGame SKU set in Publisher Account.
    purchase.pin_codes.drm
    stringDRM platform used to distribute the game. Can be steam, playstation, xbox, uplay, origin, drmfree, gog, epicgames, nintendo_eshop, discord_game_store, or oculus. Make sure that you have configured the required DRM platforms in your Publisher Account.
    purchase.pin_codes.currency
    stringCurrency that the game keys is purchased for. Three-letter currency code per ISO 4217.
    purchase.pin_codes.amount
    floatPrice.
    purchase.pin_codes.upgrade
    objectObject with upgrade data.
    purchase.pin_codes.upgrade.digital_content_from
    objectObject with data on the package, from which the user upgraded.
    purchase.pin_codes.upgrade.digital_content_from.digital_content
    stringGame SKU set in Publisher Account.
    purchase.pin_codes.upgrade.digital_content_from.DRM
    stringGame DRM platform.
    purchase.pin_codes.upgrade.digital_content_to
    objectObject with data on the package, to which the user upgraded.
    purchase.pin_codes.upgrade.digital_content_to.digital_content
    stringGame SKU set in Publisher Account.
    purchase.pin_codes.upgrade.digital_content_to.DRM
    stringGame DRM platform.
    purchase.pin_codes.upgrade.currency
    stringPurchase currency. Three-letter currency code per ISO 4217.
    purchase.pin_codes.upgrade.amount
    floatPrice in real currency.
    purchase.gift
    objectGift details (object).
    purchase.gift.giver_id
    stringGiver ID.
    purchase.gift.receiver_id
    stringGift recipient ID.
    purchase.gift.receiver_email
    stringGift recipient email.
    purchase.gift.message
    stringMessage from the giver.
    purchase.gift.hide_giver_from_receiver
    stringWhether to hide the giver identity from the recipient.
    purchase.total
    objectTotal price of purchase (object). Required.
    purchase.total.currency
    stringCurrency of the purchase. Three-letter currency code per ISO 4217.
    purchase.total.amount
    floatTotal payment amount.
    purchase.promotions
    arrayPromotions applied to this transaction (array).
    purchase.promotions.technical_name
    stringTechnical name of the promotion.
    purchase.promotions.id
    integerPromotion ID.
    purchase.coupon
    objectCoupon details (object; if a coupon was used when creating the subscription).
    purchase.coupon.coupon_code
    stringCoupon code.
    purchase.coupon.campaign_code
    stringCampaign code.
    user
    objectUser details (object).
    user.ip
    stringUser IP.
    user.phone
    stringUser phone.
    user.email
    stringUser email.
    user.id
    stringUser ID. Required.
    user.name
    stringUsername.
    user.country
    stringUser's country. Two-letter uppercase country code per ISO 3166-1 alpha-2.
    user.zip
    stringUser's ZIP or postal code.
    transaction
    objectTransaction details (object). Required.
    transaction.id
    integerTransaction ID.
    transaction.external_id
    stringTransaction external ID.
    transaction.payment_date
    stringDate of payment.
    transaction.payment_method
    integerPayment method identifier.
    transaction.payment_method_order_id
    stringPayment ID in the payment system.
    transaction.dry_run
    integerTest transaction. The parameter has the 1 value if it is a test transaction, or is not sent if the transaction is real.
    transaction.agreement
    integerAgreement ID.
    payment_details
    objectPayment details (object). Required.
    payment_details.payment
    objectAmount paid by the user (object).
    payment_details.payment.currency
    stringCurrency. Three-letter currency code per ISO 4217.
    payment_details.payment.amount
    stringAmount.
    payment_details.payment_method_sum
    objectAmount debited from the payment system.
    payment_details.payment_method_sum.currency
    stringCurrency. Three-letter currency code per ISO 4217.
    payment_details.payment_method_sum.amount
    stringAmount.
    payment_details.xsolla_balance_sum
    objectAmount debited from Xsolla balance.
    payment_details.xsolla_balance_sum.currency
    stringCurrency. Three-letter currency code per ISO 4217.
    payment_details.xsolla_balance_sum.amount
    stringAmount.
    payment_details.payout
    objectPayout details (object).
    payment_details.payout.currency
    stringCurrency. Three-letter currency code per ISO 4217.
    payment_details.payout.amount
    floatAmount.
    payment_details.vat
    objectVAT details (object; EU only).
    payment_details.vat.currency
    stringCurrency. Three-letter currency code per ISO 4217.
    payment_details.vat.amount
    floatAmount.
    payment_details.payout_currency_rate
    floatExchange rate between payment and payout currencies.
    payment_details.xsolla_fee
    objectXsolla fee (object).
    payment_details.xsolla_fee.currency
    stringCurrency. Three-letter currency code per ISO 4217.
    payment_details.xsolla_fee.amount
    floatAmount.
    payment_details.payment_method_fee
    objectPayment system fee.
    payment_details.payment_method_fee.currency
    stringCurrency. Three-letter currency code per ISO 4217.
    payment_details.payment_method_fee.amount
    floatAmount.
    payment_details.sales_tax
    objectSales tax (object; USA and Canada only).
    payment_details.sales_tax.currency
    stringCurrency. Three-letter currency code per ISO 4217.
    payment_details.sales_tax.amount
    floatAmount.
    payment_details.direct_wht
    objectDirect withholding tax.
    payment_details.direct_wht.currency
    stringCurrency. Three-letter currency code per ISO 4217.
    payment_details.direct_wht.amount
    floatAmount.
    payment_details.repatriation_commission
    objectObject with data on repatriation costs, imposed on Xsolla by third parties.
    payment_details.repatriation_commission.currency
    stringRepatriation costs currency. Three-letter currency code per ISO 4217.
    payment_details.repatriation_commission.amount
    floatRepatriation costs amount.
    custom_parameters
    objectYour custom parameters.
    Copy
    Full screen
    Small screen
    php
    • php
    • http
    • curl
    Request
    <?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"
        }
    }'
    Response
    <?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

    Refund

    Sent whenever a payment is canceled. Includes payment details. Learn more about a refund process in the recipe.

    ParameterTypeDescription
    notification_type
    stringType of notification. Required.
    settings
    objectCustom project settings (object).
    settings.project_id
    integerGame’s Xsolla ID. Can be found in Publisher Account.
    settings.merchant_id
    integerMerchant ID.
    purchase
    objectPurchase details (object).
    purchase.virtual_currency
    objectVirtual currency to purchase (object).
    purchase.virtual_currency.name
    stringVirtual currency name.
    purchase.virtual_currency.quantity
    floatQuantity.
    purchase.virtual_currency.currency
    stringCurrency of the purchase. Three-letter currency code per ISO 4217.
    purchase.virtual_currency.amount
    floatPrice in real currency.
    purchase.checkout
    objectCheckout details (object).
    purchase.checkout.currency
    stringCurrency of the purchase. Three-letter currency code per ISO 4217.
    purchase.checkout.amount
    floatPurchase amount.
    purchase.subscription
    objectSubscription details (object).
    purchase.subscription.plan_id
    stringPlan ID (external if the plan was created via API).
    purchase.subscription.tags
    arrayPlan tags.
    purchase.subscription.subscription_id
    integerSubscription ID in Xsolla database.
    purchase.subscription.date_create
    stringSubscription creation date. Date and time per ISO 8601.
    purchase.subscription.currency
    stringSubscription currency. Three-letter currency code per ISO 4217.
    purchase.subscription.amount
    floatPrice in real currency.
    purchase.virtual_items
    objectVirtual items in purchase (object).
    purchase.virtual_items.items
    arrayItem data (array).
    purchase.virtual_items.items.sku
    stringItem ID.
    purchase.virtual_items.items.amount
    integerItem quantity.
    purchase.virtual_items.currency
    stringCurrency of the purchase. Three-letter currency code per ISO 4217.
    purchase.virtual_items.amount
    floatPurchase amount.
    purchase.pin_codes
    objectGame keys (object).
    purchase.pin_codes.upgrade
    objectObject with upgrade data.
    purchase.pin_codes.upgrade.digital_content_from
    objectObject with data on the package, from which the user upgraded.
    purchase.pin_codes.upgrade.digital_content_from.digital_content
    stringGame SKU set in Publisher Account.
    purchase.pin_codes.upgrade.digital_content_from.DRM
    stringGame DRM platform.
    purchase.pin_codes.upgrade.digital_content_to
    objectObject with data on the package, to which the user upgraded.
    purchase.pin_codes.upgrade.digital_content_to.digital_content
    stringGame SKU set in Publisher Account.
    purchase.pin_codes.upgrade.digital_content_to.DRM
    stringGame DRM platform.
    purchase.pin_codes.upgrade.currency
    stringPurchase currency. Three-letter currency code per ISO 4217.
    purchase.pin_codes.upgrade.amount
    floatPrice in real currency.
    purchase.total
    objectTotal price of purchase (object).
    purchase.total.currency
    stringCurrency of the purchase. Three-letter currency code per ISO 4217.
    purchase.total.amount
    floatTotal payment amount.
    user
    objectUser details (object).
    user.ip
    stringUser IP.
    user.phone
    stringUser phone.
    user.email
    stringUser email.
    user.id
    stringUser ID. Required.
    user.name
    stringUsername.
    user.country
    stringUser's country. Two-letter uppercase country code per ISO 3166-1 alpha-2.
    user.zip
    stringUser's ZIP or postal code.
    transaction
    objectTransaction details (object). Required.
    transaction.id
    integerTransaction ID.
    transaction.external_id
    stringTransaction external ID.
    transaction.dry_run
    integerTest transaction. The parameter has the 1 value if it is a test transaction, or is not sent if the transaction is real.
    transaction.agreement
    integerAgreement ID.
    refund_details
    objectRefund details (object).
    refund_details.code
    integerCode ID.
    refund_details.reason
    stringRefund reason.
    refund_details.author
    stringRefund initiator.
    payment_details
    objectPayment details (object). Required.
    payment_details.payment
    objectAmount paid by the user (object).
    payment_details.payment.currency
    stringCurrency. Three-letter currency code per ISO 4217.
    payment_details.payment.amount
    stringAmount.
    payment_details.payment_method_sum
    objectAmount debited from the payment system.
    payment_details.payment_method_sum.currency
    stringCurrency. Three-letter currency code per ISO 4217.
    payment_details.payment_method_sum.amount
    stringAmount.
    payment_details.xsolla_balance_sum
    objectAmount debited from Xsolla balance.
    payment_details.xsolla_balance_sum.currency
    stringCurrency. Three-letter currency code per ISO 4217.
    payment_details.xsolla_balance_sum.amount
    stringAmount.
    payment_details.payout
    objectPayout details (object).
    payment_details.payout.currency
    stringCurrency. Three-letter currency code per ISO 4217.
    payment_details.payout.amount
    floatAmount.
    payment_details.vat
    objectVAT details (object; EU only).
    payment_details.vat.currency
    stringCurrency. Three-letter currency code per ISO 4217.
    payment_details.vat.amount
    floatAmount.
    payment_details.payout_currency_rate
    floatExchange rate between payment and payout currencies.
    payment_details.xsolla_fee
    objectXsolla fee (object).
    payment_details.xsolla_fee.currency
    stringCurrency. Three-letter currency code per ISO 4217.
    payment_details.xsolla_fee.amount
    floatAmount.
    payment_details.payment_method_fee
    objectPayment system fee.
    payment_details.payment_method_fee.currency
    stringCurrency. Three-letter currency code per ISO 4217.
    payment_details.payment_method_fee.amount
    floatAmount.
    payment_details.sales_tax
    objectSales tax (object; USA and Canada only).
    payment_details.sales_tax.currency
    stringCurrency. Three-letter currency code per ISO 4217.
    payment_details.sales_tax.amount
    floatAmount.
    payment_details.direct_wht
    objectDirect withholding tax.
    payment_details.direct_wht.currency
    stringCurrency. Three-letter currency code per ISO 4217.
    payment_details.direct_wht.amount
    floatAmount.
    payment_details.repatriation_commission
    objectObject with data on repatriation costs, imposed on Xsolla by third parties.
    payment_details.repatriation_commission.currency
    stringRepatriation costs currency. Three-letter currency code per ISO 4217.
    payment_details.repatriation_commission.amount
    floatRepatriation costs amount.
    custom_parameters
    objectYour custom parameters.

    Refund codes:

    CodeReasonDescription
    1.Cancellation by the user request / the game request.Cancellation initiated from Publisher Account.
    2.Charge-back.Transaction charge-back requested.
    3.Integration Error.Issues in integration between Xsolla and the game. Recommendation: Do not blacklist the user.
    4.Fraud.Fraud suspected.
    5.Test Payment.Test transaction followed by cancellation. Recommendation: Do not blacklist the user.
    6.Expired Invoice.Invoice overdue (used for postpaid model).
    7.PS debt cancel.Payout refused by payment system. Recommendation: Do not blacklist the user.
    8.Cancellation by the PS request.Cancellation requested by payment system. Recommendation: Do not blacklist the user.
    9.Cancellation by the user request.The user was not satisfied with the game or the purchase for any reason. Recommendation: Do not blacklist the user.
    10.Cancellation by the game request.Cancellation requested by the game. Recommendation: Do not blacklist the user.
    11.Account holder called to report fraud.The account owner states that they didn't make the transaction.
    12.Friendly fraud.Friendly fraud reported.
    Copy
    Full screen
    Small screen
    php
    • php
    • http
    • curl
    Request
    <?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"
                }
            }
        }
    }'
    Response
    <?php
    
    use Xsolla\SDK\Webhook\WebhookServer;
    use Xsolla\SDK\Webhook\Message\Message;
    use Xsolla\SDK\Exception\Webhook\XsollaWebhookException;
    
    $callback = function (Message $message) {
        if ($message->isRefund()) {
            $userArray = $message->getUser();
            $paymentArray = $message->getTransaction();
            $paymentId = $message->getPaymentId();
            $externalPaymentId = $message->getExternalPaymentId();
            $paymentDetailsArray = $message->getPaymentDetails();
            $customParametersArray = $message->getCustomParameters();
            $isDryRun = $message->isDryRun();
            $refundArray = $message->getRefundDetails();
            $messageArray = $message->toArray();
            // TODO if you cannot handle the refund, you should throw XsollaWebhookException
        }
    };
    
    $webhookServer = WebhookServer::create($callback, PROJECT_KEY);
    $webhookServer->start();
    
    HTTP/1.1 204 No Content

    Upgrade Refund

    When a user refunds the payment associated with the upgrade, Xsolla sends the data on all cancelled upgrades and the current game package to the webhook URL.

    ParameterTypeDescription
    notification_type
    stringNotification type. Required.
    settings
    objectCustom project settings (object).
    settings.project_id
    integerGame’s Xsolla ID. Can be found in Publisher Account.
    settings.merchant_id
    integerMerchant ID.
    purchase
    objectObject with the purchase data. Required.
    purchase.pin_codes
    objectObject with data on the purchased game packages.
    purchase.pin_codes.purchase_type
    stringPurchase type. Can be regular (purchasing the package) or upgrade (upgrading the package).
    purchase.pin_codes.digital_content
    stringGame SKU set in Publisher Account.
    purchase.pin_codes.DRM
    stringGame DRM platform.
    purchase.pin_codes.currency
    stringPurchase currency. Three-letter currency code per ISO 4217.
    purchase.pin_codes.amount
    floatPrice in real currency.
    purchase.pin_codes.transaction
    objectObject with the transaction data.
    purchase.pin_codes.transaction.id
    integerTransaction ID.
    purchase.pin_codes.upgrade
    objectObject with the upgrade data.
    purchase.pin_codes.upgrade.digital_content_from
    objectObject with data on the package, from which the user upgraded.
    purchase.pin_codes.upgrade.digital_content_from.digital_content
    stringGame SKU set in Publisher Account.
    purchase.pin_codes.upgrade.digital_content_from.DRM
    stringGame DRM platform.
    purchase.pin_codes.upgrade.digital_content_to
    objectObject with data on the package, to which the user upgraded.
    purchase.pin_codes.upgrade.digital_content_to.digital_content
    stringGame SKU set in Publisher Account.
    purchase.pin_codes.upgrade.digital_content_to.DRM
    stringGame DRM platform.
    ownership
    objectObject with data on packages owned by the user. Required.
    ownership.digital_content
    stringGame SKU set in Publisher Account.
    ownership.DRM
    stringGame DRM platform.
    Copy
    Full screen
    Small screen
    php
    • php
    • http
    • curl
    Request
    <?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
      }
    }'
    Response

    AFS Rejected Transaction

    When a transaction is declined during an AFS check, Xsolla sends transaction details to the URL webhook. To enable this notification, contact the Account Manager.

    ParameterTypeDescription
    notification_type
    stringType of notification. Required.
    settings
    objectCustom project settings (object).
    settings.project_id
    integerGame’s Xsolla ID. Can be found in Publisher Account.
    settings.merchant_id
    integerMerchant ID.
    user
    objectUser details (object).
    user.ip
    stringUser IP.
    user.phone
    stringUser phone.
    user.email
    stringUser email.
    user.id
    stringUser ID. Required.
    user.name
    stringUsername.
    user.country
    stringUser's country. Two-letter uppercase country code per ISO 3166-1 alpha-2.
    user.zip
    stringUser's ZIP or postal code.
    transaction
    objectTransaction details (object). Required.
    transaction.id
    integerTransaction ID.
    transaction.external_id
    stringTransaction external ID.
    transaction.dry_run
    integerTest transaction. The parameter has the 1 value if it is a test transaction, or is not sent if the transaction is real.
    transaction.agreement
    integerAgreement ID.
    refund_details
    objectRefund details (object).
    refund_details.code
    integerCode ID.
    refund_details.reason
    stringRefund reason.
    refund_details.author
    stringRefund initiator.
    Copy
    Full screen
    Small screen
    php
    • php
    • http
    • curl
    Request
    <?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"
      }
    }'
    Response
    <?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 Updated Blocklist

    When the AFS blocklist is updated (add or remove a parameter), Xsolla sends the notification to the webhook URL. The parameter addition is performed automatically on the Xsolla side or on request. Parameter removing is possible only on request. To enable this notification, contact the Account Manager.

    ParameterTypeDescription
    notification_type
    stringType of notification. Required.
    event
    objectObject with information about AFS blocklist event. Required.
    event.action
    stringType of event. Possible values: adding, removing.
    event.reason
    stringCause of event. Possible values:
    • Addition: chargeback — chargeback, fraud_activity — fraud, suspicious_activity — suspicious activity, ps_reported_fraud — payment system notification about fraud, linked_chargeback — chargeback relation, partner_request — on request, friendly_fraud — friendly fraud, user_reported_fraud — user report about fraud, linked_parameter — linked parameter in AFS blocklist, other_data_in_blacklist — other parameters in AFS blocklist, by_afs_filters — AFS filter.
    • Removing: wrongly_added — added by mistake, removed_by_cs_review — removed after reporting to Xsolla technical support, other_forgiveness_reason — other reason for removing.
    event.parameter
    stringName of parameter by which event occurred. Possible values: nick — user’s nickname, email — user’s email address, ps_account — user’s billing account, ip_address — user’s IP address, card_issuer — user’s credit card issuing bank, phone — user’s phone number.
    event.parameter_value
    stringValue of parameter by which event occurred.
    event.date_of_last_action
    stringTime of the latest AFS blocklist event in the ISO 8601 format.
    event.transaction_id
    stringTransaction ID associated with the parameter by which the event occurred.
    Copy
    Full screen
    Small screen
    http
    • http
    • curl
    Request
    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"
    }'
    Response
    HTTP/1.1 204 No Content

    Created Subscription

    When a user creates a subscription, we send a notification to your payment notification script.

    ParameterTypeDescription
    notification_type
    stringType of notification. Required.
    settings
    objectCustom project settings (object).
    settings.project_id
    integerGame’s Xsolla ID. Can be found in Publisher Account.
    settings.merchant_id
    integerMerchant ID.
    user
    objectUser details (object).
    user.id
    stringUser ID. Required.
    user.name
    stringUsername.
    subscription
    objectSubscription details (object).
    subscription.plan_id
    stringPlan ID (external if the plan was created via API).
    subscription.tags
    arrayPlan tags.
    subscription.subscription_id
    integerSubscription ID in Xsolla database.
    subscription.product_id
    stringProduct ID (if sent in the access token).
    subscription.date_create
    stringSubscription creation date. Date and time per ISO 8601.
    subscription.date_next_charge
    stringNext billing date. Date and time per ISO 8601.
    subscription.trial
    objectTrial period (object).
    subscription.trial.value
    integerTrial period.
    subscription.trial.type
    stringTrial period type: day.
    custom_parameters
    objectYour custom parameters.
    Copy
    Full screen
    Small screen
    php
    • php
    • http
    • curl
    Request
    <?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"
                    }
            }
        }'
    Response
    <?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

    Updated Subscription

    If some parameters in subscription (plan_id, date_next_charge) were changed and in case of every subscription renewal, we send the notification update_subscription on your webhook URL.

    ParameterTypeDescription
    notification_type
    stringType of notification. Required.
    settings
    objectCustom project settings (object).
    settings.project_id
    integerGame’s Xsolla ID. Can be found in Publisher Account.
    settings.merchant_id
    integerMerchant ID.
    user
    objectUser details (object).
    user.id
    stringUser ID. Required.
    user.name
    stringUsername.
    subscription
    objectSubscription details (object).
    subscription.plan_id
    stringPlan ID (external if the plan was created via API).
    subscription.tags
    arrayPlan tags.
    subscription.subscription_id
    integerSubscription ID in Xsolla database.
    subscription.product_id
    stringProduct ID (if sent in the access token).
    subscription.date_next_charge
    stringNext billing date. Date and time per ISO 8601.
    Copy
    Full screen
    Small screen
    php
    • php
    • http
    • curl
    Request
    <?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"
            }
        }'
    Response
    <?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

    Canceled Subscription

    When a subscription is canceled for any reason, we send a notification to your payment notification script.

    ParameterTypeDescription
    notification_type
    stringType of notification. Required.
    settings
    objectCustom project settings (object).
    settings.project_id
    integerGame’s Xsolla ID. Can be found in Publisher Account.
    settings.merchant_id
    integerMerchant ID.
    user
    objectUser details (object).
    user.id
    stringUser ID. Required.
    user.name
    stringUsername.
    subscription
    objectSubscription details (object).
    subscription.plan_id
    stringPlan ID (external if the plan was created via API).
    subscription.tags
    arrayPlan tags.
    subscription.subscription_id
    integerSubscription ID in Xsolla database.
    subscription.product_id
    stringProduct ID (if sent in the access token).
    subscription.date_create
    stringSubscription creation date. Date and time per ISO 8601.
    subscription.date_end
    stringSubscription termination date. Date and time per ISO 8601.
    Copy
    Full screen
    Small screen
    php
    • php
    • http
    • curl
    Request
    <?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"
            }
        }'
    Response
    <?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

    Nonrenewing Subscription

    When a subscription status is set to nonrenewing for any reason, we send the notification non_renewal_subscription to your webhook URL.

    ParameterTypeDescription
    settings
    objectCustom project settings (object).
    settings.project_id
    integerGame’s Xsolla ID. Can be found in Publisher Account. Required.
    settings.merchant_id
    integerMerchant ID.
    notification_type
    stringType of notification. Required.
    user
    objectUser details (object).
    user.id
    stringUser ID. Required.
    user.name
    stringUsername.
    user.email
    stringUser email.
    subscription
    objectSubscription details (object).
    subscription.subscription_id
    integerSubscription ID in Xsolla database.
    subscription.plan_id
    stringPlan ID (external if the plan was created via API).
    subscription.date_create
    stringSubscription creation date. Date and time per ISO 8601.
    subscription.date_next_charge
    stringNext billing date. This is the date when a next payment was expected before user subscription was set to non-renew. Date and time per ISO 8601.
    subscription.currency
    stringSubscription currency. Three-letter currency code per ISO 4217.
    subscription.amount
    floatPrice in real currency.

    Get Game Keys

    We will be making API calls to your server to obtain game activation codes after each successful payment.

    ParameterTypeDescription
    notification_type
    stringType of notification.
    settings
    objectCustom project settings (object).
    settings.project_id
    integerGame’s Xsolla ID. Can be found in Publisher Account.
    settings.merchant_id
    integerMerchant ID.
    user
    objectUser details (object).
    user.id
    stringUser ID. Required.
    user.name
    stringUsername.
    pin_code
    objectGame keys details (object).
    pin_code.digital_content
    stringGame SKU.
    pin_code.DRM
    stringDRM platform used to distribute the game.
    Copy
    Full screen
    Small screen
    php
    • php
    • http
    • curl
    Request
    <?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"
            }
        }'
    Response
    <?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"
    }

    Activate key

    When a user activates a key, Xsolla sends a notification to your webhook URL.

    ParameterTypeDescription
    notification_type
    stringNotification type.
    settings
    objectCustom project settings (object).
    settings.project_id
    integerGame’s Xsolla ID. Can be found in Publisher Account.
    settings.merchant_id
    integerMerchant ID.
    key
    stringActivation key.
    sku
    stringUnique key package ID.
    user_id
    stringUser ID.
    activation_date
    datetimeKey activation date in the YYYYMMDDHHMMSS format per ISO 8601.
    user_country
    stringUser country. Two-letter uppercase country code per ISO 3166-1 alpha-2 is used.
    restriction
    objectObject with regional restriction cluster settings. The cluster includes a restriction type and a list of countries, servers and locales for which the game is available.
    restriction.sku
    stringUnique cluster ID.
    restriction.name
    stringCluster name.
    restriction.types
    arrayArray of restriction types.
    restriction.countries
    arrayArray of countries in the cluster.
    restriction.servers
    arrayArray of game servers.
    restriction.locales
    arrayArray of locales.
    Copy
    Full screen
    Small screen
    php
    • php
    • http
    • curl
    Request
    <?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"
             ]
        }
    }'
    Response
    <?php
    
    $response = null;
    
    HTTP/1.1 204 No Content

    Get Friends

    The API should be implemented on the partner’s side. The maximum number of friends is 2000. See the recipe.

    HTTP REQUEST

    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

    ParameterTypeDescription
    notification_type
    stringID that defines the type of request to get the list of friends. The value is friends_list.
    user
    stringUnique ID of the user buying the gift.
    query
    stringFriend’s name or ID (full or partial).
    limit
    stringLimit for the number of elements on the page. Required.
    offset
    integerNumber of the element from which the list is generated (the count starts from 0).
    sign
    stringSignature line, generated as follows:
    • Concatenate notification_type + parameter values sorted alphabetically by the key + secret_key
    • Apply SHA-1 to the resulting string
    Copy
    Full screen
    Small screen
    http
    • http
    • curl
    Request
    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
    Response
    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
      }
    ]

    User Balance: Payment

    Sent whenever a user makes a payment.

    ParameterTypeDescription
    notification_type
    stringType of notification.
    settings
    objectCustom project settings (object).
    settings.project_id
    integerGame’s Xsolla ID. Can be found in Publisher Account.
    settings.merchant_id
    integerMerchant ID.
    operation_type
    stringType of operation.
    id_operation
    integerOperation ID in Xsolla database.
    user
    objectUser details (object).
    user.id
    stringUser ID. Required.
    user.name
    stringUsername.
    user.email
    stringUser email.
    virtual_currency_balance
    objectUser balance data (object).
    virtual_currency_balance.old_value
    stringBalance before transaction.
    virtual_currency_balance.new_value
    stringBalance after transaction.
    virtual_currency_balance.diff
    stringQuantity of virtual currency in the purchase.
    transaction
    objectTransaction details (object). Required.
    transaction.id
    integerTransaction ID.
    transaction.date
    stringDate of transaction.
    Copy
    Full screen
    Small screen
    php
    • php
    • http
    • curl
    Request
    <?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"
        }'
    Response
    <?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

    User Balance: Purchase

    Sent when a user purchases something inside the game. Specifies the change in the user's balance.

    ParameterTypeDescription
    notification_type
    stringType of notification.
    settings
    objectCustom project settings (object).
    settings.project_id
    integerGame’s Xsolla ID. Can be found in Publisher Account.
    settings.merchant_id
    integerMerchant ID.
    operation_type
    stringType of operation.
    id_operation
    integerOperation ID in Xsolla database.
    user
    objectUser details (object).
    user.id
    stringUser ID. Required.
    user.name
    stringUsername.
    user.email
    stringUser email.
    virtual_currency_balance
    objectUser balance data (object).
    virtual_currency_balance.old_value
    stringBalance before transaction.
    virtual_currency_balance.new_value
    stringBalance after transaction.
    virtual_currency_balance.diff
    stringQuantity of virtual currency in the purchase.
    items_operation_type
    stringType of operation made with virtual items.
    items
    arrayVirtual items within the purchase (array of objects).
    items.sku
    stringItem ID.
    items.amount
    integerItem quantity.
    Copy
    Full screen
    Small screen
    php
    • php
    • http
    • curl
    Request
    <?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"
        }'
    Response
    <?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

    User Balance: Redeem Coupon

    Sent when a user redeems a coupon to receive virtual items or virtual currency.

    ParameterTypeDescription
    notification_type
    stringType of notification.
    settings
    objectCustom project settings (object).
    settings.project_id
    integerGame’s Xsolla ID. Can be found in Publisher Account.
    settings.merchant_id
    integerMerchant ID.
    operation_type
    stringType of operation.
    id_operation
    integerOperation ID in Xsolla database.
    user
    objectUser details (object).
    user.id
    stringUser ID. Required.
    user.name
    stringUsername.
    user.email
    stringUser email.
    virtual_currency_balance
    objectUser balance data (object).
    virtual_currency_balance.old_value
    stringBalance before transaction.
    virtual_currency_balance.new_value
    stringBalance after transaction.
    virtual_currency_balance.diff
    stringQuantity of virtual currency in the purchase.
    items_operation_type
    stringType of operation made with virtual items.
    items
    arrayVirtual items within the purchase (array of objects).
    items.sku
    stringItem ID.
    items.amount
    integerItem quantity.
    coupon
    objectCoupon details (object).
    coupon.coupon_code
    stringCoupon code.
    coupon.campaign_code
    stringCampaign code.
    Copy
    Full screen
    Small screen
    php
    • php
    • http
    • curl
    Request
    <?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"
            }
        }'
    Response
    <?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

    User Balance: Manual Update

    Sent when a user's balance is changed manually.

    ParameterTypeDescription
    notification_type
    stringType of notification.
    settings
    objectCustom project settings (object).
    settings.project_id
    integerGame’s Xsolla ID. Can be found in Publisher Account.
    settings.merchant_id
    integerMerchant ID.
    operation_type
    stringType of operation.
    id_operation
    integerOperation ID in Xsolla database.
    user
    objectUser details (object).
    user.id
    stringUser ID. Required.
    user.name
    stringUsername.
    user.email
    stringUser email.
    virtual_currency_balance
    objectUser balance data (object).
    virtual_currency_balance.old_value
    stringBalance before transaction.
    virtual_currency_balance.new_value
    stringBalance after transaction.
    virtual_currency_balance.diff
    stringQuantity of virtual currency in the purchase.
    Copy
    Full screen
    Small screen
    php
    • php
    • http
    • curl
    Request
    <?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"
        }'
    Response
    <?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

    User Balance: Refund

    Sent when a user cancels a payment. Specifies the change in the user's balance.

    ParameterTypeDescription
    notification_type
    stringType of notification.
    settings
    objectCustom project settings (object).
    settings.project_id
    integerGame’s Xsolla ID. Can be found in Publisher Account.
    settings.merchant_id
    integerMerchant ID.
    operation_type
    stringType of operation.
    id_operation
    integerOperation ID in Xsolla database.
    user
    objectUser details (object).
    user.id
    stringUser ID. Required.
    user.name
    stringUsername.
    user.email
    stringUser email.
    virtual_currency_balance
    objectUser balance data (object).
    virtual_currency_balance.old_value
    stringBalance before transaction.
    virtual_currency_balance.new_value
    stringBalance after transaction.
    virtual_currency_balance.diff
    stringQuantity of virtual currency in the purchase.
    transaction
    objectTransaction details (object). Required.
    transaction.id
    integerTransaction ID.
    transaction.date
    stringDate of transaction.
    items_operation_type
    stringType of operation made with virtual items.
    items
    arrayVirtual items within the purchase (array of objects).
    items.sku
    stringItem ID.
    items.amount
    integerItem quantity.
    Copy
    Full screen
    Small screen
    php
    • php
    • http
    • curl
    Request
    <?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"
        }'
    Response
    <?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

    Webhooks Errors

    Permanent error codes:

    CodeMessage
    INVALID_USERInvalid user.
    INVALID_PARAMETERInvalid parameter.
    INVALID_SIGNATUREInvalid signature.
    INCORRECT_AMOUNTIncorrect amount.
    INCORRECT_INVOICEIncorrect invoice.
    Copy
    Full screen
    Small screen
    HTTP/1.1 400 Bad Request
    
    {
        "error":{
            "code":"INVALID_USER",
            "message":"Invalid user"
        }
    }

    Was this article helpful?
    Thank you!
    Is there anything we can improve? Message
    We're sorry to hear that
    Please explain why this article wasn't helpful to you. Message
    Thank you for your feedback!
    We'll review your message and use it to help us improve your experience.