入门

概览

艾克索拉API包括:

艾克索拉API使用REST架构。该API拥有面向资源的可预测URL,并使用HTTP响应代码来指示API错误。API始终以JSON格式响应(包括发生错误时)。

我们使用HTTP身份验证和HTTP动词等内置HTTP功能(这些功能可被现行HTTP客户端理解),并且我们支持跨域资源共享,使您可以从客户端Web应用程序与我们的API进行安全交互。

艾克索拉API使用以下端点路径:

  • https://api.xsolla.com — Pay Station API、Commerce API、Publisher Account API
  • https://login.xsolla.com/api — Login API
大多数端点路径包含一个merchant_id参数。该参数指示应用程序所代表的商户。

请求和响应

发送给艾克索拉API的请求必须:

  • 通过HTTPS发送,
  • 使用TLS 1.2或更高版本,
  • 包含认证参数,
  • 对于PUT和POST请求额外包含一个头:Content-Type: application/json

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

    默认情况下,所有请求均返回一个正文中包含JSON数据、头中包含Content-Type: application/json的响应。

    API变更

    艾克索拉可能使用此API更改功能:

    • 艾克索拉可能添加新的API资源;
    • 艾克索拉可能添加可选的请求参数;
    • 艾克索拉可能向现有API响应添加新属性;
    • 艾克索拉可能向已枚举值集合的现有参数添加新值;
    • 艾克索拉可能添加新的webhook类型并将新参数添加到JSON;
    • 艾克索拉可能添加可选的HTTP请求头部;
    • 艾克索拉可能拒绝任何有效参数包含无效参数值的请求;
    • 如解析逻辑被更正,则由于过度宽松的解析而被接受的不正确请求可能被拒绝
    • 艾克索拉可能随时添加、更改或删除未记录的功能。

    您的客户端应保持正常工作状态,而不应受到这些更改的影响。例如,您的客户端无法识别的新JSON参数,但这不会影响其正常工作的能力。

    版本控制

    所有艾克索拉 API方法支持版本控制。当存在与当前版本不兼容的改动时,我们将发布一个新版本。可根据URL中"/merchant"前缀后面的"v1"/"v2"/等来识别版本。

    如果首次使用API,请使用最新版本。如果忽略了版本,我们将默认使用第一个版本。

    Info: 请注意,我们只保证同一版本中的API完整性。

    身份验证

    艾克索拉API使用基本认证。所有发送到API的请求必须包含Authorization: Basic <your_authorization_basic_key>头,其中<your_authorization_basic_key>是按照Base64标准加密的merchant_id:api_key对。

    艾克索拉发布商帐户中找到merchant_idapi_key参数的值:

    • merchant_id:公司设置 > 公司 > 商户ID
    • api_key:公司设置 > API密钥

    Notice:
    • 请妥善保管您的API密钥。它是您的个人帐户和发布商帐户项目的访问凭证。
    • 更改API密钥可能导致您的所有项目无法付款。更新为新密钥之前,使用当前密钥的API调用将无法运行。
    Copy
    Full screen
    Small screen
    http
    • http
    • curl
    • php
    • C#
    • python
    • ruby
    • java
    • js
    示例
    GET https://api.xsolla.com/merchant/v2/merchants/{merchant_id}/events/messages
    Headers:
      Authorization: Basic <your_authorization_basic_key>
    curl --request GET \
    --url 'https://api.xsolla.com/merchant/v2/merchants/{merchant_id}/events/messages' \
    --header 'authorization: Basic <your_authorization_basic_key>'
    <?php
    
    // if you use Xsolla SDK for PHP
    use Xsolla\SDK\API\XsollaClient;
    $xsollaClient = XsollaClient::factory(array(
        'merchant_id' => MERCHANT_ID,
        'api_key' => API_KEY
    ));
    $eventsList = $client->ListEvents(array());
    
    // if you don’t use Xsolla SDK for PHP
    $client = new http\Client;
    $request = new http\Client\Request;
    
    $request->setRequestUrl('https://api.xsolla.com/merchant/v2/merchants/{merchant_id}/events/messages');
    $request->setRequestMethod('GET');
    $request->setHeaders(array(
      'authorization' => 'Basic <your_authorization_basic_key>'
    ));
    
    $client->enqueue($request)->send();
    $response = $client->getResponse();
    
    echo $response->getBody();
    
    var client = new RestClient("https://api.xsolla.com/merchant/v2/merchants/{merchant_id}/events/messages");
    var request = new RestRequest(Method.GET);
    request.AddHeader("authorization", "Basic <your_authorization_basic_key>");
    IRestResponse response = client.Execute(request);
    
    import http.client
    
    conn = http.client.HTTPSConnection("api.xsolla.com")
    
    headers = { 'authorization': "Basic <your_authorization_basic_key>" }
    
    conn.request("GET", "/merchant/v2/merchants/{merchant_id}/events/messages", headers=headers)
    
    res = conn.getresponse()
    data = res.read()
    
    print(data.decode("utf-8"))
    require 'uri'
    require 'net/http'
    
    url = URI("https://api.xsolla.com/merchant/v2/merchants/{merchant_id}/events/messages")
    
    http = Net::HTTP.new(url.host, url.port)
    http.use_ssl = true
    http.verify_mode = OpenSSL::SSL::VERIFY_NONE
    
    request = Net::HTTP::Get.new(url)
    request["authorization"] = 'Basic <your_authorization_basic_key>'
    
    response = http.request(request)
    puts response.read_body
    OkHttpClient client = new OkHttpClient();
    
    Request request = new Request.Builder()
      .url("https://api.xsolla.com/merchant/v2/merchants/{merchant_id}/events/messages")
      .get()
      .addHeader("authorization", "Basic <your_authorization_basic_key>")
      .build();
    
    Response response = client.newCall(request).execute();
    var data = null;
    
    var xhr = new XMLHttpRequest();
    xhr.withCredentials = true;
    
    xhr.addEventListener("readystatechange", function () {
      if (this.readyState === this.DONE) {
        console.log(this.responseText);
      }
    });
    
    xhr.open("GET", "https://api.xsolla.com/merchant/v2/merchants/{merchant_id}/events/messages");
    xhr.setRequestHeader("authorization", "Basic <your_authorization_basic_key>");
    
    xhr.send(data);
    

    端点类型

    端点类型指示其处理的数据类型以及在数据上执行的操作。最常见的操作包括:

    操作HTTP 方法描述
    创建POST创建并保持对应类型的实体。
    列示GET返回与您提供的查询参数相匹配的所有实体的汇总信息。要获取特定实体的综合信息,首先获取实体的ID以及相应的“List”端点,然后向对应的“Retrieve”端点提供ID。
    检索GET提供与您提供的标识符相匹配的单个实体的综合信息。
    替换PUT修改与您提供的标识符相匹配的现有实体的所有字段。
    更新PATCH仅修改与您提供的标识符相匹配的现有实体的指定字段。
    删除DELETE删除与您提供的标识符相匹配的现有实体。

    日期格式

    所有日期表示都是ISO 8601格式的字符串。可以提供UTC日期字符串(例如2013-01-15T00:00:00Z)或者用于指示时区的UTC时区偏差日期字符串(例如2013-01-15T00:00:00-08:00表示比UTC时间晚八小时)。如果提供时区偏差日期,需确保根据情况正确计算夏时令时间。

    分页

    List端点可能会将返回的结果进行分页。也就是说,这些端点可能只会返回一部分结果,另外提供一个能够链接到下一组结果的响应头,而不是在一个响应中返回所有结果。为此,我们使用offset和limit参数。

    错误处理

    受支持的HTTP错误列表:

    • 200、201、204 - 一切都如期进行。
    • 400 Bad Request - 通常缺少必要参数。完整的描述可以在响应正文中找到。
    • 401 Unauthorized - 未提供有效API密钥。
    • 402 Request Failed - 参数有效,但请求失败。
    • 403 Forbidden - 没有足够的权限。完整的描述可以在响应正文中找到。
    • 404 Not Found - 请求的项目不存在。
    • 409、422 - 参数无效。
    • 412 Precondition failed - 在项目尚未激活时发生(在创建令牌方法中使用)。
    • 415 Unsupported media type - Content-Type: application/json HTTP 标头未发送。
    • 500、502、503、504 Server errors - 发生错误。

    艾克索拉使用传统HTTP响应代码指示API请求是成功还是失败。通常,2xx范围内的代码指示请求成功,4xx范围内的代码指示提供的信息导致错误(例如必要参数缺失、身份验证失败等),5xx范围内的代码指示艾克索拉服务器出现错误。

    不过,也不是所有错误都能明确地反映到HTTP响应代码中。不过,也不是所有错误都能明确地反映到HTTP响应代码中。如果请求有效但未成功完成,将返回422错误代码。

    所有API错误响应都提供JSON对象及以下字段:

    {< T "api_table_name" >}}类型描述
    http_status_codeintegerHTTP代码
    messagestring可读的错误描述信息。此信息始终是英文。对一些特定错误的说明,今后有可能会改变。
    extended_messagestring错误的详细描述。
    request_idstring请求的唯一ID,用于帮助我们诊断问题。
    Copy
    Full screen
    Small screen
    {
        "http_status_code": 500,
        "message": "Internal Server Error",
        "extended_message": null,
        "request_id": "6445b85"
    }

    Webhooks

    概览

    如果使用 webhook,您会收到艾克索拉交易事件的通知。可以使用 webhook 自动化后台及管理功能,例如提供状态和其他交易相关信息。

    Webhook用于通知事件相关信息,例如:

    • 即时支付,包括虚拟货币购买、物品购买、信用卡付款以及其他
    • 重复性支付和订阅行为
    • 交易相关的信用卡退单/退款

    很多情况下,触发 webhook 的操作是在您的网站上发生的用户操作。不过,其他操作也可以触发 webhook。例如,您的网站的后台流程可能调用会退回付款的 API 方法,或者支付系统可能会发送存在争议付款的通知。

    您接收到 webhook 并使用监听器(有时也称作处理器,它是您编写的一个程序)处理它们。该程序等待 webhook 并(通常)将其传递到恰当响应的管理流程。

    您这一端操作的示例:

    • 增加用户余额
    • 为用户解锁新物品
    • 启动订阅服务
    • 检测到欺诈后冻结用户

    您应接受来自以下IP地址的webhook:185.30.20.0/24185.30.21.0/24185.30.23.0/24

    Notice: 数据库中不得同时包含两个具有相同ID的成功交易。如果收到的Webhook的交易ID在数据库中已存在,则监听器应返回该次交易的上次处理结果。请避免向用户重复扣款或在数据库中创建重复记录。

    不能保证监听器能百分之百收到发送的所有Webhook。由于网络连接无法100%可靠,Webhook可能会丢失或延迟。此外,对于您服务器上的暂时错误,监听器可能返回HTTP响应代码5xx。例如,如果用户成功购买了一件虚拟物品但该物品未添加至用户的物品库,则监听器返回HTTP响应代码500。

    为解决这些问题,我们提供一种以不同间隔重新发送接收失败的消息,直到监听器确认接收到消息的重试机制。最长可能在发送初始Webhook的12小时内重新发送Webhook。最大重试次数为12次。

    Note: 请注意,尽管网络连接可能导致出错,但最有可能导致丢失、延迟或重复Webhook的原因是监听器本身存在逻辑问题。

    请求签名

    数字签名可以保障数据传输的安全。生成签名需要经历两个阶段。第一阶段是连结 JSON 内容与项目密钥。第二阶段包括对第一阶段的内容使用 SHA-1 加密哈希函数。

    您应检查生成的签名和 HTTP 头中传递的签名是否相同。

    Copy
    Full screen
    Small screen
    http
    • http
    • curl
    请求
    POST /your_uri HTTP/1.1
    Host: your.host
    Accept: application/json
    Content-Type: application/json
    Content-Length: 165
    Authorization: Signature 52eac2713985e212351610d008e7e14fae46f902
    
    {"notification_type":"user_validation","user":{"ip":"127.0.0.1","phone":"18777976552","email":"email@example.com","id":1234567,"name":"Xsolla User","country":"US"}}
    $curl -v 'https://your.hostname/your/uri' \
    -X POST \
    -H 'Authorization: Signature 52eac2713985e212351610d008e7e14fae46f902' \
    -d '{
      "notification_type":
        "user_validation",
        "user":
          {
            "ip": "127.0.0.1",
            "phone": "18777976552",
            "email": "email@example.com",
            "id": 1234567,
            "name": "Xsolla User",
            "country": "US"
          }
        }'

    响应

    艾克索拉API使用传统HTTP响应代码指示请求是成功还是失败。代码204指示处理成功。如提供的信息包含错误(例如缺少必要参数、扣款失败等),则会返回代码400。代码500指示您的服务器暂时出错。

    Webhook列表

    通知的类型在参数notification_type中发送。

    通知类型描述
    user_validation验证用户在游戏系统中是否存在。
    user_search通过公开用户 ID 获取用户信息。
    payment用户完成支付流程时发送。
    refund出于某些原因需要取消支付时发送。
    afs_reject交易在AFS检查过程中被拒绝时发送。
    afs_black_listAFS拦截列表发生更新时发送。
    create_subscription用户创建订阅时发送。
    update_subscription订阅发生续订或更改时发送。
    cancel_subscription取消订阅时发送。
    non_renewal_subscription状态设置为非续订时发送。
    get_pincode在艾克索拉API需要获取游戏密钥时发送。
    user_balance_operation用户余额发生变化时发送(操作类型以operation_type形式发送)。
    redeem_key用户激活密钥时发送。
    upgrade_refund取消升级时发送。
    payment_account_add用户添加或保存了支付帐户时发送。
    payment_account_remove用户从已保存的帐户中删除了支付帐户时发送。

    用户验证

    发送以验证该游戏用户是否存在。

    参数类型描述
    notification_type
    string通知类型。 必需
    settings
    object带有自定义项目设置的对象。
    settings.project_id
    integer游戏的艾克索拉ID。可以在发布商帐户中找到该ID。
    settings.merchant_id
    integer商户ID。
    user
    object带用户相关数据的对象。
    user.ip
    string用户IP地址。
    user.phone
    string用户电话号码(采用国际格式)。
    user.email
    string用户电子邮件。
    user.id
    string用户ID。 必需
    user.name
    string用户名。
    user.country
    string用户所在国家/地区。使用ISO 3166-1 alpha-2 标准规定的2字母组合表示国家/地区。
    Copy
    Full screen
    Small screen
    php
    • php
    • http
    • curl
    请求
    <?php
    
    $request = array(
        'notification_type' => 'user_validation',
        'settings' => array(
           'project_id' => 18404,
           'merchant_id' => 2340
        ),
        'user' => array(
            'ip' => '127.0.0.1',
            'phone' => '18777976552',
            'email'=> 'email@example.com',
            'id'=> '1234567',
            'country' => 'US'
        )
    );
    
    POST /your/uri HTTP/1.1
    Host: your.hostname
    Accept: application/json
    Content-Type: application/json
    Content-Length: 240
    Authorization: Signature 13342703ccaca5064ad33ba451d800c5e823db8f
    
    {
        "notification_type": "user_validation",
        "settings": {
           "project_id": 18404,
           "merchant_id": 2340
        },
        "user": {
            "ip": "127.0.0.1",
            "phone": "18777976552",
            "email": "email@example.com",
            "id": "1234567",
            "name": "Xsolla User",
            "country": "US"
        }
    }
    $ curl -v 'https://your.hostname/your/uri' \
    -X POST \
    -H 'Accept: application/json' \
    -H 'Content-Type: application/json' \
    -H 'Authorization: Signature 13342703ccaca5064ad33ba451d800c5e823db8f' \
    -d '{
        "notification_type":"user_validation",
        "settings": {
           "project_id": 18404,
           "merchant_id": 2340
        },    
        "user": {
            "ip": "127.0.0.1",
            "phone": "18777976552",
            "email": "email@example.com",
            "id": "1234567",
            "name": "Xsolla User",
            "country": "US"
        }
    }'
    响应
    <?php
    
    use Xsolla\SDK\Webhook\WebhookServer;
    use Xsolla\SDK\Webhook\Message\Message;
    use Xsolla\SDK\Exception\Webhook\XsollaWebhookException;
    
    $callback = function (Message $message) {
        if ($message->isUserValidation()) {
           $userArray = $message->getUser();
           $userId = $message->getUserId();
           $messageArray = $message->toArray();
           //TODO if user not found, you should throw InvalidUserException
        }
    };
    
    $webhookServer = WebhookServer::create($callback, PROJECT_KEY);
    $webhookServer->start();
    
    HTTP/1.1 204 No Content
    发送以通过公共用户ID检索用户的详细信息,该参数是用户的唯一标识,且会提供给用户(电子邮件、昵称等)。它允许用户在游戏商店之外的地方进行购买(例如通过自助终端机)。

    参数类型描述
    notification_type
    string通知类型。 必需
    settings
    object带有自定义项目设置的对象。
    settings.project_id
    integer游戏的艾克索拉ID。可以在发布商帐户中找到该ID。
    settings.merchant_id
    integer商户ID。
    user
    object带用户相关数据的对象。 必需
    user.public_id
    string公共用户ID。
    user.id
    string用户ID。
    Copy
    Full screen
    Small screen
    php
    • php
    • http
    • curl
    请求
    <?php
    
    $request = array(
        'notification_type' => 'user_search',
        'settings' => array(
           'project_id' => 18404,
           'merchant_id' => 2340
        ),
        'user' => array(
            'public_id' => 'public_email@example.com'
        )
    );
    
    POST /your/uri HTTP/1.1
    Host: your.hostname
    Accept: application/json
    Content-Type: application/json
    Content-Length: 240
    Authorization: Signature 13342703ccaca5064ad33ba451d800c5e823db8f
    
    {
        "notification_type": "user_search",
        "settings": {
           "project_id": 18404,
           "merchant_id": 2340
        },
        "user": {
            "public_id": "public_email@example.com"
        }
    }
    $ curl -v 'https://your.hostname/your/uri' \
    -X POST \
    -H 'Accept: application/json' \
    -H 'Content-Type: application/json' \
    -H 'Authorization: Signature 13342703ccaca5064ad33ba451d800c5e823db8f' \
    -d '{
        "notification_type": "user_search",
        "settings": {
           "project_id": 18404,
           "merchant_id": 2340
        },
        "user": {
            "public_id": "public_email@example.com"
        }
    }'
    响应
    <?php
    
    use Xsolla\SDK\Webhook\WebhookServer;
    use Xsolla\SDK\Webhook\Message\Message;
    
    $callback = function (Message $message) {
        if ($message instanceof \Xsolla\SDK\Webhook\Message\UserSearchMessage) {
            $userArray = $message->getUser();
            $userPublicId = $message->getUserPublicId();
            // TODO get a user from your database and fill the user data to model.
            $user = new \Xsolla\SDK\Webhook\User();
            $user->setId('user_id')
                ->setPublicId($userPublicId)
                ->setEmail('user_email') //Optional field
                ->setPhone('user_phone') //Optional field
                ->setName('user_name'); //Optional field
            //TODO if user not found, you should throw InvalidUserException
            return new \Xsolla\SDK\Webhook\Response\UserResponse($user);
        }
    };
    $webhookServer = WebhookServer::create($callback, PROJECT_KEY);
    $webhookServer->start();
    
    HTTP/1.1 200 OK
    Content-Type: application/json
    
    {
        "user": {
            "public_id": "public_email@example.com",
            "phone": "18777976552",
            "email": "email@example.com",
            "id": "1234567",
            "name": "Xsolla User"
        }
    }
    {
        "user": {
            "public_id": "public_email@example.com",
            "phone": "18777976552",
            "email": "email@example.com",
            "id": "1234567",
            "name": "Xsolla User"
        }
    }

    支付

    每当用户完成支付流程时,我们都会向您的支付通知脚本发送交易的详细信息。

    参数类型描述
    notification_type
    string通知类型。 必需
    settings
    object带有自定义项目设置的对象。
    settings.project_id
    integer游戏的艾克索拉ID。可以在发布商帐户中找到该ID。
    settings.merchant_id
    integer商户 ID。
    purchase
    object带有购买相关数据的对象。
    purchase.virtual_currency
    object带有购买虚拟货币相关数据的对象。
    purchase.virtual_currency.name
    string虚拟货币名称。
    purchase.virtual_currency.sku
    string虚拟货币包 SKU(如果针对虚拟货币包设置)。
    purchase.virtual_currency.quantity
    float数量。
    purchase.virtual_currency.currency
    string购买币种。参照ISO 4217标准的三字母货币代码。
    purchase.virtual_currency.amount
    float以实际货币表示的价格。
    purchase.checkout
    object带有结账参数相关数据的对象。
    purchase.checkout.currency
    string购买币种。参照ISO 4217标准的三字母货币代码。
    purchase.checkout.amount
    float购买金额。
    purchase.subscription
    object订阅详情(对象)。
    purchase.subscription.plan_id
    string计划 ID(如果计划通过 API 创建,则为外部 ID)。
    purchase.subscription.subscription_id
    integer艾克索拉数据库的订阅ID。
    purchase.subscription.product_id
    string产品 ID(如果在访问令牌中发送)。
    purchase.subscription.tags
    array计划标签。
    purchase.subscription.date_create
    string订阅的创建日期。符合 ISO 8601 标准规定的日期与时间。
    purchase.subscription.date_next_charge
    string下次收费的日期。符合ISO 8601标准规定的日期与时间。
    purchase.subscription.currency
    string订阅使用的币种。参照ISO 4217标准的三字母货币代码。
    purchase.subscription.amount
    float以实际货币表示的价格。
    purchase.virtual_items
    object带有购买的虚拟物品相关数据的对象。
    purchase.virtual_items.items
    array带有购买的物品相关数据的数组。
    purchase.virtual_items.items.sku
    string物品 ID。
    purchase.virtual_items.items.amount
    integer物品数量。
    purchase.virtual_items.currency
    string购买币种。参照ISO 4217标准的三字母货币代码。
    purchase.virtual_items.amount
    float购买金额。
    purchase.pin_codes
    object游戏密钥(数组)。
    purchase.pin_codes.digital_content
    string在发布商帐户中设置的游戏SKU。
    purchase.pin_codes.drm
    string用于分发游戏的DRM平台。可以是steamplaystationxboxuplayorigindrmfreegogepicgamesnintendo_eshopdiscord_game_storeoculus。请确保您已在发布商帐户中配置了所需的DRM平台。
    purchase.pin_codes.currency
    string购买游戏密钥的币种。参照ISO 4217标准的三字母货币代码。
    purchase.pin_codes.amount
    floatPIN 码的价格。
    purchase.pin_codes.upgrade
    object包含升级数据的对象。
    purchase.pin_codes.upgrade.digital_content_from
    object包含套餐数据的对象,用户从该套餐升级。
    purchase.pin_codes.upgrade.digital_content_from.digital_content
    string在发布商帐户中设置的游戏SKU。
    purchase.pin_codes.upgrade.digital_content_from.DRM
    string游戏DRM平台。
    purchase.pin_codes.upgrade.digital_content_to
    object包含套餐数据的对象,用户升级到该套餐。
    purchase.pin_codes.upgrade.digital_content_to.digital_content
    string在发布商帐户中设置的游戏SKU。
    purchase.pin_codes.upgrade.digital_content_to.DRM
    string游戏DRM平台。
    purchase.pin_codes.upgrade.currency
    string购买货币。为参照ISO 4217标准的三字母货币代码。
    purchase.pin_codes.upgrade.amount
    float以实际货币表示的价格。
    purchase.gift
    object礼物详情(对象)。
    purchase.gift.giver_id
    string送礼人ID。
    purchase.gift.receiver_id
    string收礼人ID。
    purchase.gift.receiver_email
    string收礼人邮箱。
    purchase.gift.message
    string送礼人留言。
    purchase.gift.hide_giver_from_receiver
    string是否对收礼人隐藏送礼人的身份信息。
    purchase.total
    object带有总购买价格相关数据的对象。 必需
    purchase.total.currency
    string购买币种。参照ISO 4217标准的三字母货币代码。
    purchase.total.amount
    float总购买金额。
    purchase.promotions
    array带有此交易所应用促销活动相关数据的数组。
    purchase.promotions.technical_name
    string促销活动的技术名称。
    purchase.promotions.id
    integer促销活动 ID。
    purchase.coupon
    object带有优惠券相关数据的对象(如果此交易使用了优惠券)。
    purchase.coupon.coupon_code
    string优惠券代码。
    purchase.coupon.campaign_code
    string优惠券营销活动的代码。
    user
    object带用户相关数据的对象。
    user.ip
    string用户 IP 地址。
    user.phone
    string用户电话号码(采用国际格式)。
    user.email
    string用户电子邮件。
    user.id
    string用户ID。 必需
    user.name
    string用户名。
    user.country
    string用户所在国家/地区。使用 ISO 3166-1 alpha-2 标准规定的 2 字母组合表示国家/地区。
    user.zip
    string邮编。
    transaction
    object交易 ID。 必需
    transaction.id
    integer交易ID。
    transaction.external_id
    string交易外部ID。
    transaction.payment_date
    string付款日期。
    transaction.payment_method
    integer付款方式标识符。
    transaction.payment_method_order_id
    string支付系统中的付款ID。
    transaction.dry_run
    integer测试交易。如为测试交易,该参数的值为1;如为真实交易,则不会发送该参数。
    transaction.agreement
    integer协议 ID。
    payment_details
    object带有支付详细信息的对象。 必需
    payment_details.payment
    object带有用户支付相关数据的对象。
    payment_details.payment.currency
    string货币。参照ISO 4217标准的三字母货币代码。
    payment_details.payment.amount
    string金额。
    payment_details.payment_method_sum
    object带有通过支付方式收费的金额相关数据的对象。
    payment_details.payment_method_sum.currency
    string货币。参照ISO 4217标准的三字母货币代码。
    payment_details.payment_method_sum.amount
    string金额。
    payment_details.xsolla_balance_sum
    object计入艾克索拉余额的金额。
    payment_details.xsolla_balance_sum.currency
    string货币。参照ISO 4217标准的三字母货币代码。
    payment_details.xsolla_balance_sum.amount
    string金额。
    payment_details.payout
    object带有支出详细信息的对象。
    payment_details.payout.currency
    string货币。参照ISO 4217标准的三字母货币代码。
    payment_details.payout.amount
    float金额。
    payment_details.vat
    object增值税大小(仅适用于欧盟)。
    payment_details.vat.currency
    string货币。参照ISO 4217标准的三字母货币代码。
    payment_details.vat.amount
    float金额。
    payment_details.payout_currency_rate
    float从支付币种到支出币种的汇率。
    payment_details.xsolla_fee
    object艾克索拉费用(对象)。
    payment_details.xsolla_fee.currency
    string货币。参照ISO 4217标准的三字母货币代码。
    payment_details.xsolla_fee.amount
    float金额。
    payment_details.payment_method_fee
    object支付系统佣金的大小。
    payment_details.payment_method_fee.currency
    string货币。参照ISO 4217标准的三字母货币代码。
    payment_details.payment_method_fee.amount
    float金额。
    payment_details.sales_tax
    object销售税(对象;仅适用于美国和加拿大)。
    payment_details.sales_tax.currency
    string货币。参照ISO 4217标准的三字母货币代码。
    payment_details.sales_tax.amount
    float金额。
    payment_details.direct_wht
    object直接预扣税。
    payment_details.direct_wht.currency
    string货币。参照ISO 4217标准的三字母货币代码。
    payment_details.direct_wht.amount
    float金额。
    payment_details.repatriation_commission
    object包含汇回本国费用数据的对象,该费用是第三方对艾克索拉收取的费用。
    payment_details.repatriation_commission.currency
    string汇回本国费用币种。参照ISO 4217标准的三字母货币代码。
    payment_details.repatriation_commission.amount
    float汇回本国费用金额。
    custom_parameters
    object您的自定义参数。
    Copy
    Full screen
    Small screen
    php
    • php
    • http
    • curl
    请求
    <?php
    
    $request = array(
        'notification_type' => 'payment',
        'settings' => array(
           'project_id' => 18404,
           'merchant_id' => 2340
        ),
        'purchase' => array(
            'virtual_currency' => array(
                'name' => 'Coins',
                'quantity' => 100,
                'currency' => 'USD',
                'amount' => 9.99
            ),
            'total' => array(
                'currency' => 'USD',
                'amount' => 9.99
            )
        ),
        'user' => array(
            'ip' => '127.0.0.1',
            'phone' => '18777976552',
            'email' => 'email@example.com',
            'id' => '1234567',
            'country' => 'US'
        ),
        'transaction' => array(
            'id' => 87654321,
            'payment_date' => '2014-09-23T19:25:25+04:00',
            'payment_method' => 1380,
            'payment_method_order_id' => 1234567890123456789,
            'dry_run' => 1
        ),
        'payment_details' => array(
            'payment' => array(
                'currency' => 'USD',
                'amount' => 9.99
            ),
            'vat' => array(
                'currency' => 'USD',
                'amount' => 0
            ),
            'sales_tax' => array(
                'currency' => 'USD',
                'amount' => 0
            ),
            'direct_wht' => array(
                'currency' => 'USD',
                'amount' => 70
            ),
            'payout_currency_rate' => 1,
            'payout' => array(
                'currency' => 'USD',
                'amount' => 9.49
            ),
            'xsolla_fee' => array(
                'currency' => 'USD',
                'amount' => 0.19
            ),
            'payment_method_fee' => array(
                'currency' => 'USD',
                'amount' => 0.31
            ),
            'repatriation_commission' => array(
                'currency' => 'USD',
                'amount' => 0.2
            )
        )
    );
    
    POST /your_uri HTTP/1.1
    Host: your.host
    Accept: application/json
    Content-Type: application/json
    Content-Length: 1721
    Authorization: Signature 34553d151e656110c656696c919f9a10e05de542
    
    {
        "notification_type": "payment",
        "settings": {
           "project_id": 18404,
           "merchant_id": 2340
        },
        "purchase":{
            "virtual_currency": {
                "name": "Coins",
                "sku": "test_package1",
                "quantity": 10,
                "currency": "USD",
                "amount": 100
            },
            "subscription": {
                "plan_id": "b5dac9c8",
                "subscription_id": "10",
                "product_id": "Demo Product",
                "date_create": "2014-09-22T19:25:25+04:00",
                "date_next_charge": "2014-10-22T19:25:25+04:00",
                "currency": "USD",
                "amount": 9.99
            },
            "checkout": {
                "currency": "USD",
                "amount": 50
            },
            "virtual_items": {
                "items": [
                    {
                        "sku": "test_item1",
                        "amount": 1
                    }
                ],
                "currency": "USD",
                "amount": 50
            },
            "total": {
                "currency": "USD",
                "amount": 200
            },
            "promotions": [{
                "technical_name": "Demo Promotion",
                "id": "853"
            }],
            "coupon": {
                "coupon_code": "ICvj45S4FUOyy",
                "campaign_code": "1507"
            }
        },
        "user": {
            "ip": "127.0.0.1",
            "phone": "18777976552",
            "email": "email@example.com",
            "id": "1234567",
            "name": "Xsolla User",
            "country": "US"
        },
        "transaction": {
            "id": 1,
            "external_id": 1,
            "payment_date": "2014-09-24T20:38:16+04:00",
            "payment_method": 1,
            "payment_method_order_id": 1234567890123456789,
            "dry_run": 1,
            "agreement": 1
        },
        "payment_details": {
            "payment": {
                "currency": "USD",
                "amount": 230
            },
            "vat": {
                "currency": "USD",
                "amount": 0
            },
            "sales_tax": {
                "currency": "USD",
                "amount": 0
            },
            "direct_wht": {
                "currency": "USD",
                "amount": 0.70
            },
            "payout_currency_rate": 1,
            "payout": {
                "currency": "USD",
                "amount": 200
            },
            "xsolla_fee": {
                "currency": "USD",
                "amount": 10
            },
            "payment_method_fee": {
                "currency": "USD",
                "amount": 20
            },
            "repatriation_commission": {
                "currency": "USD",
                "amount": "10"
            }
        },
        "custom_parameters": {
            "parameter1": "value1",
            "parameter2": "value2"
        }
    }
    $curl -v 'https://your.hostname/your/uri' \
    -X POST \
    -d '{
        "notification_type": "payment",
        "settings": {
           "project_id": 18404,
           "merchant_id": 2340
        },
        "purchase": {
            "virtual_currency": {
                "name": "Coins",
                "sku": "test_package1",
                "quantity": 10,
                "currency": "USD",
                "amount": 100
            },
            "subscription": {
                "plan_id": "b5dac9c8",
                "subscription_id": "10",
                "product_id": "Demo Product",
                "date_create": "2014-09-22T19:25:25+04:00",
                "date_next_charge": "2014-10-22T19:25:25+04:00",
                "currency": "USD",
                "amount": 9.99
            },
            "checkout": {
                "currency": "USD",
                "amount": 50
            },
            "virtual_items": {
                "items": [
                    {
                        "sku": "test_item1",
                        "amount": 1
                    }
                ],
                "currency": "USD",
                "amount": 50
            },
            "total": {
                "currency": "USD",
                "amount": 200
            },
            "promotions": [{
                "technical_name": "Demo Promotion",
                "id": "853"
            }],
            "coupon": {
                 "coupon_code": "ICvj45S4FUOyy",
                 "campaign_code": "1507"
            }
        },
        "user": {
            "ip": "127.0.0.1",
            "phone": "18777976552",
            "email": "email@example.com",
            "id": "1234567",
            "name": "Xsolla User",
            "country": "US"
        },
        "transaction": {
            "id": 1,
            "external_id": 1,
            "payment_date": "2014-09-24T20:38:16+04:00",
            "payment_method": 1,
            "payment_method_order_id": 1234567890123456789,
            "dry_run": 1,
            "agreement": 1
        },
        "payment_details": {
            "payment": {
                "currency": "USD",
                "amount": 230
            },
            "vat": {
                "currency": "USD",
                "amount": 0
            },
            "sales_tax": {
                "currency": "USD",
                "amount": 0
            },
            "direct_wht": {
                "currency": "USD",
                "amount": 0.70
            },
            "payout_currency_rate": 1,
            "payout": {
                "currency": "USD",
                "amount": 200
            },
            "xsolla_fee": {
                "currency": "USD",
                "amount": 10
            },
            "payment_method_fee": {
                "currency": "USD",
                "amount": 20
            },
            "repatriation_commission": {
                "currency": "USD",
                "amount": "10"
            }
        },
        "custom_parameters": {
            "parameter1": "value1",
            "parameter2": "value2"
        }
    }'
    响应
    <?php
    
    use Xsolla\SDK\Webhook\WebhookServer;
    use Xsolla\SDK\Webhook\Message\Message;
    use Xsolla\SDK\Exception\Webhook\XsollaWebhookException;
    
    $callback = function (Message $message) {
        if ($message->isPayment()) {
            $userArray = $message->getUser();
            $paymentArray = $message->getTransaction();
            $paymentId = $message->getPaymentId();
            $externalPaymentId = $message->getExternalPaymentId();
            $paymentDetailsArray = $message->getPaymentDetails();
            $customParametersArray = $message->getCustomParameters();
            $isDryRun = $message->isDryRun();
            $messageArray = $message->toArray();
            // TODO if the payment delivery fails for some reason, you should throw XsollaWebhookException
        }
    };
    
    $webhookServer = WebhookServer::create($callback, PROJECT_KEY);
    $webhookServer->start();
    
    HTTP/1.1 204 No Content

    退款

    付款被取消时发送。包含付款详情。请在高级诀窍中了解详细退款过程。

    参数类型描述
    notification_type
    string通知类型。 必需
    settings
    object带有自定义项目设置的对象。
    settings.project_id
    integer游戏的艾克索拉ID。可以在发布商帐户中找到该ID。
    settings.merchant_id
    integer商户ID。
    purchase
    object带有购买相关数据的对象。
    purchase.virtual_currency
    object带有购买虚拟货币相关数据的对象。
    purchase.virtual_currency.name
    string虚拟货币名称。
    purchase.virtual_currency.quantity
    float数量。
    purchase.virtual_currency.currency
    string购买币种。参照ISO 4217标准的三字母货币代码。
    purchase.virtual_currency.amount
    float以实际货币表示的价格。
    purchase.checkout
    object带有结账参数相关数据的对象。
    purchase.checkout.currency
    string购买币种。参照ISO 4217标准的三字母货币代码。
    purchase.checkout.amount
    float购买金额。
    purchase.subscription
    object订阅详情(对象)。
    purchase.subscription.plan_id
    string计划 ID(如果计划通过 API 创建,则为外部 ID)。
    purchase.subscription.tags
    array计划标签。
    purchase.subscription.subscription_id
    integer艾克索拉数据库的订阅ID。
    purchase.subscription.date_create
    string订阅的创建日期。符合 ISO 8601 标准规定的日期与时间。
    purchase.subscription.currency
    string订阅使用的币种。参照ISO 4217标准的三字母货币代码。
    purchase.subscription.amount
    float以实际货币表示的价格。
    purchase.virtual_items
    object带有购买的虚拟物品相关数据的对象。
    purchase.virtual_items.items
    array带有购买的物品相关数据的数组。
    purchase.virtual_items.items.sku
    string物品ID。
    purchase.virtual_items.items.amount
    integer物品数量。
    purchase.virtual_items.currency
    string购买币种。参照ISO 4217标准的三字母货币代码。
    purchase.virtual_items.amount
    float购买金额。
    purchase.pin_codes
    object游戏密钥(对象)。
    purchase.pin_codes.upgrade
    object包含升级数据的对象。
    purchase.pin_codes.upgrade.digital_content_from
    object包含套餐数据的对象,用户从该套餐升级。
    purchase.pin_codes.upgrade.digital_content_from.digital_content
    string在发布商帐户中设置的游戏SKU。
    purchase.pin_codes.upgrade.digital_content_from.DRM
    string游戏DRM平台。
    purchase.pin_codes.upgrade.digital_content_to
    object包含套餐数据的对象,用户升级到该套餐。
    purchase.pin_codes.upgrade.digital_content_to.digital_content
    string在发布商帐户中设置的游戏SKU。
    purchase.pin_codes.upgrade.digital_content_to.DRM
    string游戏DRM平台。
    purchase.pin_codes.upgrade.currency
    string购买货币。为参照ISO 4217标准的三字母货币代码。
    purchase.pin_codes.upgrade.amount
    float以实际货币表示的价格。
    purchase.total
    object带有总购买价格相关数据的对象。
    purchase.total.currency
    string购买币种。参照ISO 4217标准的三字母货币代码。
    purchase.total.amount
    float总购买金额。
    user
    object带用户相关数据的对象。
    user.ip
    string用户IP地址。
    user.phone
    string用户电话号码(采用国际格式)。
    user.email
    string用户电子邮件。
    user.id
    string用户ID。 必需
    user.name
    string用户名。
    user.country
    string用户所在国家/地区。使用ISO 3166-1 alpha-2 标准规定的2字母组合表示国家/地区。
    user.zip
    string邮编。
    transaction
    object交易ID。 必需
    transaction.id
    integer交易ID。
    transaction.external_id
    string交易外部ID。
    transaction.dry_run
    integer测试交易。如为测试交易,该参数的值为1;如为真实交易,则不会发送该参数。
    transaction.agreement
    integer协议ID。
    refund_details
    object退款详情(对象)。
    refund_details.code
    integer代码ID。
    refund_details.reason
    string退款原因。
    refund_details.author
    string退款申請人。
    payment_details
    object带有支付详细信息的对象。 必需
    payment_details.payment
    object带有用户支付相关数据的对象。
    payment_details.payment.currency
    string货币。参照ISO 4217标准的三字母货币代码。
    payment_details.payment.amount
    string金额。
    payment_details.payment_method_sum
    object带有通过支付方式收费的金额相关数据的对象。
    payment_details.payment_method_sum.currency
    string货币。参照ISO 4217标准的三字母货币代码。
    payment_details.payment_method_sum.amount
    string金额。
    payment_details.xsolla_balance_sum
    object计入艾克索拉余额的金额。
    payment_details.xsolla_balance_sum.currency
    string货币。参照ISO 4217标准的三字母货币代码。
    payment_details.xsolla_balance_sum.amount
    string金额。
    payment_details.payout
    object带有支出详细信息的对象。
    payment_details.payout.currency
    string货币。参照ISO 4217标准的三字母货币代码。
    payment_details.payout.amount
    float金额。
    payment_details.vat
    object增值税大小(仅适用于欧盟)。
    payment_details.vat.currency
    string货币。参照ISO 4217标准的三字母货币代码。
    payment_details.vat.amount
    float金额。
    payment_details.payout_currency_rate
    float从支付币种到支出币种的汇率。
    payment_details.xsolla_fee
    object艾克索拉费用(对象)。
    payment_details.xsolla_fee.currency
    string货币。参照ISO 4217标准的三字母货币代码。
    payment_details.xsolla_fee.amount
    float金额。
    payment_details.payment_method_fee
    object支付系统佣金的大小。
    payment_details.payment_method_fee.currency
    string货币。参照ISO 4217标准的三字母货币代码。
    payment_details.payment_method_fee.amount
    float金额。
    payment_details.sales_tax
    object销售税(对象;仅适用于美国和加拿大)。
    payment_details.sales_tax.currency
    string货币。参照ISO 4217标准的三字母货币代码。
    payment_details.sales_tax.amount
    float金额。
    payment_details.direct_wht
    object直接预扣税。
    payment_details.direct_wht.currency
    string货币。参照ISO 4217标准的三字母货币代码。
    payment_details.direct_wht.amount
    float金额。
    payment_details.repatriation_commission
    object包含汇回本国费用数据的对象,该费用是第三方对艾克索拉收取的费用。
    payment_details.repatriation_commission.currency
    string汇回本国费用币种。参照ISO 4217标准的三字母货币代码。
    payment_details.repatriation_commission.amount
    float汇回本国费用金额。
    custom_parameters
    object您的自定义参数。

    退款代码:

    代码退款理由描述
    1.Cancellation by the user request / the game request.用于在发布商帐户中发起取消的情况。
    2.退单。用于交易存在退单的情况。
    3.Integration Error.用于艾克索拉与游戏之间存在集成问题的情况。 这种情况下,我们不建议将用户列入黑名单。
    4.Fraud.用于存在潜在欺诈风险的情况。
    5.Test Payment.用于测试交易然后取消的情况。 这种情况下,我们不建议将用户列入黑名单。
    6.Expired Invoice.用于通过用后付费模式的支付系统进行交易的情况。
    7.PS debt cancel.用于支付系统进行交易后拒绝支出的情况。 这种情况下,我们不建议将用户列入黑名单。
    8.Cancellation by the PS request.用于支付系统请求取消的情况。 这种情况下,我们不建议将用户列入黑名单。
    9.Cancellation by the user request.用于用户请求取消的情况。可能出于某些原因导致用户对游戏或购买产生不满的情况下发生。 这种情况下,我们不建议将用户列入黑名单。
    10.Cancellation by the game request.用于游戏请求取消的情况。 这种情况下,我们不建议将用户列入黑名单。
    11.Account holder called to report fraud.用于账户持有人通知我们其未进行此交易的情况。
    12.Friendly fraud.用于接收到友好型欺诈相关消息的情况。
    Copy
    Full screen
    Small screen
    php
    • php
    • http
    • curl
    请求
    <?php
    
    $request = array(
        'notification_type' => 'refund',
        'settings' => array(
           'project_id' => 18404,
           'merchant_id' => 2340
        ),    
        'purchase' => array(
            'virtual_currency' => array(
                'name' => 'Coins',
                'quantity' => 100,
                'currency' => 'USD',
                'amount' => 9.99
            ),
            'total' => array(
                'currency' => 'USD',
                'amount' => 9.99
            )
        ),
        'user' => array(
            'ip' => '127.0.0.1',
            'phone' => '18777976552',
            'email' => 'email@example.com',
            'id' => '1234567',
            'country' => 'US'
        ),
        'transaction' => array(
            'id' => 87654321,
            'payment_date' => '2014-09-23T19:25:25+04:00',
            'payment_method' => 1380,
            'dry_run' => 1
        ),
        'refund_details' => array(
                'code' => 1,
                'reason' => 'Fraud'
        ),
        'payment_details' => array(
            'payment' => array(
                'currency' => 'USD',
                'amount' => 9.99
            ),
            'vat' => array(
                'currency' => 'USD',
                'amount' => 0
            ),
            'sales_tax' => array(
                'currency' => 'USD',
                'amount' => 0
            ),
            'direct_wht' => array(
                'currency' => 'USD',
                'amount' => 70
            ),
            'payout_currency_rate' => 1,
            'payout' => array(
                'currency' => 'USD',
                'amount' => 9.49
            ),
            'xsolla_fee' => array(
                'currency' => 'USD',
                'amount' => 0.19
            ),
            'payment_method_fee' => array(
                'currency' => 'USD',
                'amount' => 0.31
            ),
            'repatriation_commission' => array(
                'currency' => 'USD',
                'amount' => 0.2
            )
        )
    );
    
    POST /your_uri HTTP/1.1
    Host: your.host
    Accept: application/json
    Content-Type: application/json
    Content-Length: 1220
    Authorization: Signature 31bd5924dd6cbc9cbe99d331c4a086a57291f9d7
    
    {
        "notification_type": "refund",
        "settings": {
           "project_id": 18404,
           "merchant_id": 2340
        },
        "purchase": {
            "virtual_currency": {
                "name": "Coins",
                "quantity": 10,
                "currency": "USD",
                "amount": 100
            },
            "subscription": {
                "plan_id": "b5dac9c8",
                "subscription_id": "10",
                "date_create": "2014-09-22T19:25:25+04:00",
                "currency": "USD",
                "amount": 9.99
            },
            "checkout": {
                "currency": "USD",
                "amount": 50
            },
            "virtual_items": {
                "items": [
                    {
                        "sku": "test_item1",
                        "amount": 1
                    }
                ],
                "currency": "USD",
                "amount": 50
            },
            "total": {
                "currency": "USD",
                "amount": 200
            }
        },
        "user": {
            "ip": "127.0.0.1",
            "phone": "18777976552",
            "email": "email@example.com",
            "id": "1234567",
            "name": "Xsolla User",
            "country": "US"
        },
        "transaction": {
            "id": 1,
            "external_id": 1,
            "dry_run": 1,
            "agreement": 1
        },
        "refund_details": {
            "code": 1,
            "reason": "Fraud"
        },
        "payment_details": {
            "sales_tax": {
                "currency": "USD",
                "amount": 0
            },
            "direct_wht": {
                "currency": "USD",
                "amount": 0.70
            },
            "xsolla_fee": {
                "currency": "USD",
                "amount": "10"
            },
            "payout": {
                "currency": "USD",
                "amount": "200"
            },
            "payment_method_fee": {
                "currency": "USD",
                "amount": "20"
            },
            "payment": {
                "currency": "USD",
                "amount": "230"
            },
            "repatriation_commission": {
                "currency": "USD",
                "amount": "10"
            }
        }
    }
    $ curl -v 'https://your.hostname/your/uri' \
    -X POST \
    -d '{
            "notification_type": "refund",
            "settings": {
               "project_id": 18404,
               "merchant_id": 2340
            },
            "purchase": {
                "virtual_currency": {
                    "name": "Coins",
                    "quantity": 10,
                    "currency": "USD",
                    "amount": 100
                },
                "subscription": {
                    "plan_id": "b5dac9c8",
                    "subscription_id": "10",
                    "date_create": "2014-09-22T19:25:25+04:00",
                    "currency": "USD",
                    "amount": 9.99
                },
                "checkout": {
                    "currency": "USD",
                    "amount": 50
                },
                "virtual_items": {
                    "items": [
                        {
                            "sku": "test_item1",
                            "amount": 1
                        }
                    ],
                    "currency": "USD",
                    "amount": 50
                },
                "total":{
                    "currency": "USD",
                    "amount": 200
                }
            },
            "user": {
                "ip": "127.0.0.1",
                "phone": "18777976552",
                "email": "email@example.com",
                "id": "1234567",
                "name": "Xsolla User",
                "country": "US"
            },
            "transaction": {
                "id": 1,
                "external_id": 1,
                "dry_run": 1,
                "agreement": 1
            },
            "refund_details": {
                "code": 1,
                "reason": "Fraud"
            },
            "payment_details": {
                "sales_tax": {
                    "currency": "USD",
                    "amount": 0
                },
                "direct_wht": {
                    "currency": "USD",
                    "amount": 0.70
                },
                "xsolla_fee": {
                    "currency": "USD",
                    "amount": "10"
                },
                "payout": {
                    "currency": "USD",
                    "amount": "200"
                },
                "payment_method_fee": {
                    "currency": "USD",
                    "amount": "20"
                },
                "payment": {
                    "currency": "USD",
                    "amount": "230"
                },
                "repatriation_commission": {
                    "currency": "USD",
                    "amount": "10"
                }
            }
        }
    }'
    响应
    <?php
    
    use Xsolla\SDK\Webhook\WebhookServer;
    use Xsolla\SDK\Webhook\Message\Message;
    use Xsolla\SDK\Exception\Webhook\XsollaWebhookException;
    
    $callback = function (Message $message) {
        if ($message->isRefund()) {
            $userArray = $message->getUser();
            $paymentArray = $message->getTransaction();
            $paymentId = $message->getPaymentId();
            $externalPaymentId = $message->getExternalPaymentId();
            $paymentDetailsArray = $message->getPaymentDetails();
            $customParametersArray = $message->getCustomParameters();
            $isDryRun = $message->isDryRun();
            $refundArray = $message->getRefundDetails();
            $messageArray = $message->toArray();
            // TODO if you cannot handle the refund, you should throw XsollaWebhookException
        }
    };
    
    $webhookServer = WebhookServer::create($callback, PROJECT_KEY);
    $webhookServer->start();
    
    HTTP/1.1 204 No Content

    升级退款

    用户对与升级关联的付款进行退款时,艾克索拉将所有取消的升级以及当前游戏套餐的数据发送到Webhook URL。

    参数类型描述
    notification_type
    string通知类型。 必需
    settings
    object带有自定义项目设置的对象。
    settings.project_id
    integer游戏的艾克索拉ID。可以在发布商帐户中找到该ID。
    settings.merchant_id
    integer商户ID。
    purchase
    object包含购买数据的对象。 必需
    purchase.pin_codes
    object包含所购游戏套餐数据的对象。
    purchase.pin_codes.purchase_type
    string购买类型。可以是regular(购买套餐)或upgrade(升级套餐)。
    purchase.pin_codes.digital_content
    string在发布商帐户中设置的游戏SKU。
    purchase.pin_codes.DRM
    string游戏DRM平台。
    purchase.pin_codes.currency
    string购买货币。为参照ISO 4217标准的三字母货币代码。
    purchase.pin_codes.amount
    float以实际货币表示的价格。
    purchase.pin_codes.transaction
    object包含交易数据的对象。
    purchase.pin_codes.transaction.id
    integer交易ID。
    purchase.pin_codes.upgrade
    object包含升级数据的对象。
    purchase.pin_codes.upgrade.digital_content_from
    object包含套餐数据的对象,用户从该套餐升级。
    purchase.pin_codes.upgrade.digital_content_from.digital_content
    string在发布商帐户中设置的游戏SKU。
    purchase.pin_codes.upgrade.digital_content_from.DRM
    string游戏DRM平台。
    purchase.pin_codes.upgrade.digital_content_to
    object包含套餐数据的对象,用户升级到该套餐。
    purchase.pin_codes.upgrade.digital_content_to.digital_content
    string在发布商帐户中设置的游戏SKU。
    purchase.pin_codes.upgrade.digital_content_to.DRM
    string游戏DRM平台。
    ownership
    object包含用户所拥有套餐数据的对象。 必需
    ownership.digital_content
    string在发布商帐户中设置的游戏SKU。
    ownership.DRM
    string游戏DRM平台。
    Copy
    Full screen
    Small screen
    php
    • php
    • http
    • curl
    请求
    <?php
    
    $request = array (
      'notification_type' => 'upgrade_refund',
      'settings' => array(
         'project_id' => 18404,
         'merchant_id' => 2340
      ),
      'purchase' =>
      array (
        'pin_codes' =>
        array (
          0 =>
          array (
            'purchase_type' => 'regular',
            'digital_content' => 'silver',
            'DRM' => 'drmfree',
            'currency' => 'USD',
            'amount' => 40,
            'transaction' =>
            array (
              'id' => '361697569',
            ),
          ),
          1 =>
          array (
            'purchase_type' => 'upgrade',
            'upgrade' =>
            array (
              'digital_content_from' =>
              array (
                'digital_content' => 'silver',
                'DRM' => 'drmfree',
              ),
              'digital_content_to' =>
              array (
                'digital_content' => 'gold',
                'DRM' => 'drmfree',
              ),
            ),
            'currency' => 'USD',
            'amount' => 20,
            'transaction' =>
            array (
              'id' => '361697570'
            ),
          ),
          2 =>
          array (
            'purchase_type' => 'upgrade',
            'upgrade' =>
            array (
              'digital_content_from' =>
              array (
                'digital_content' => 'gold',
                'DRM' => 'drmfree',
              ),
              'digital_content_to' =>
              array (
                'digital_content' => 'platinum',
                'DRM' => 'drmfree',
              ),
            ),
            'currency' => 'USD',
            'amount' => 20,
            'transaction' =>
            array (
              'id' => '361697571'
            ),
          ),
        ),
      ),
      'ownership' =>
      array (
        'digital_content' => NULL,
        'DRM' => NULL,
      ),
    )
    
    POST /your_uri HTTP/1.1
    Host: your.host
    Accept: application/json
    Content-Type: application/json
    Authorization: Signature <signature>
    
    {
      "notification_type": "upgrade_refund",
      "settings": {
         "project_id": 18404,
         "merchant_id": 2340
      },
      "purchase": {
        "pin_codes": [
          {
            "purchase_type": "regular",
            "digital_content": "silver",
            "DRM": "drmfree",
            "currency": "USD",
            "amount": "40",
            "transaction": {
              "id": "361697569"
            }
          },
          {
            "purchase_type": "upgrade",
            "upgrade": {
              "digital_content_from": {
                "digital_content": "silver",
                "DRM": "drmfree"
              },
              "digital_content_to": {
                "digital_content": "gold",
                "DRM": "drmfree"
              }
            },
            "currency": "USD",
            "amount": "20",
            "transaction": {
              "id": "361697570"
            }
          },
          {
            "purchase_type": "upgrade",
            "upgrade": {
              "digital_content_from": {
                "digital_content": "gold",
                "DRM": "drmfree"
              },
              "digital_content_to": {
                "digital_content": "platinum",
                "DRM": "drmfree"
              }
            },
            "currency": "USD",
            "amount": "20",
            "transaction": {
              "id": "361697571"
            }
          }
        ]
      },
      "ownership": {
        "digital_content": null,
        "DRM": null
      }
    }
    $ curl -v 'https://your.hostname/your/uri' \
    -X POST \
    -d '{
      "notification_type": "upgrade_refund",
      "settings": {
         "project_id": 18404,
         "merchant_id": 2340
      },
      "purchase": {
        "pin_codes": [
          {
            "purchase_type": "regular",
            "digital_content": "silver",
            "DRM": "drmfree",
            "currency": "USD",
            "amount": "40",
            "transaction": {
              "id": "361697569"
            }
          },
          {
            "purchase_type": "upgrade",
            "upgrade": {
              "digital_content_from": {
                "digital_content": "silver",
                "DRM": "drmfree"
              },
              "digital_content_to": {
                "digital_content": "gold",
                "DRM": "drmfree"
              }
            },
            "currency": "USD",
            "amount": "20",
            "transaction": {
              "id": "361697570"
            }
          },
          {
            "purchase_type": "upgrade",
            "upgrade": {
              "digital_content_from": {
                "digital_content": "gold",
                "DRM": "drmfree"
              },
              "digital_content_to": {
                "digital_content": "platinum",
                "DRM": "drmfree"
              }
            },
            "currency": "USD",
            "amount": "20",
            "transaction": {
              "id": "361697571"
            }
          }
        ]
      },
      "ownership": {
        "digital_content": null,
        "DRM": null
      }
    }'
    响应

    AFS已拒绝交易

    当某笔交易在AFS检查过程中被取消时,艾克索拉将发送交易详情到URL Webhook。如需启用此通知,请联系帐户经理。

    参数类型描述
    notification_type
    string通知类型。 必需
    settings
    object带有自定义项目设置的对象。
    settings.project_id
    integer游戏的艾克索拉ID。可以在发布商帐户中找到该ID。
    settings.merchant_id
    integer商户ID。
    user
    object带用户相关数据的对象。
    user.ip
    string用户IP地址。
    user.phone
    string用户电话号码(采用国际格式)。
    user.email
    string用户电子邮件。
    user.id
    string用户ID。 必需
    user.name
    string用户名。
    user.country
    string用户所在国家/地区。使用ISO 3166-1 alpha-2 标准规定的2字母组合表示国家/地区。
    user.zip
    string邮编。
    transaction
    object交易ID。 必需
    transaction.id
    integer交易ID。
    transaction.external_id
    string交易外部ID。
    transaction.dry_run
    integer测试交易。如为测试交易,该参数的值为1;如为真实交易,则不会发送该参数。
    transaction.agreement
    integer协议ID。
    refund_details
    object退款详情(对象)。
    refund_details.code
    integer代码ID。
    refund_details.reason
    string退款原因。
    refund_details.author
    string退款申請人。
    Copy
    Full screen
    Small screen
    php
    • php
    • http
    • curl
    请求
    <?php
    
    $request = array(
      'notification_type' => 'afs_reject',
      'settings' => array(
        'project_id' => 18404,
        'merchant_id' => 2340
      ),
      'user' => array(
        'ip' => '127.0.0.1',
        'phone' => '18777976552',
        'email' => 'email@example.com',
        'id' => '1234567',
        'country' => 'US'
      ),
      'transaction' => array(
        'id' => 87654321,
        'payment_method' => 1380,
        'dry_run' => 1
      ),
      'refund_details' => array(
        'code' => 4,
        'reason' => 'Potential fraud'
      )
    );
    
    POST /your_uri HTTP/1.1
    Host: your.host
    Accept: application/json
    Content-Type: application/json
    Content-Length: 1220
    Authorization: Signature 31bd5924dd6cbc9cbe99d331c4a086a57291f9d7
    
    {
      "notification_type": "afs_reject",
      "settings": {
        "project_id": 18404,
        "merchant_id": 2340
      },
      "user": {
        "ip": "127.0.0.1",
        "phone": "18777976552",
        "email": "semail@example.com",
        "id": "1234567",
        "name": "Xsolla User",
        "country": "US"
      },
      "transaction": {
        "id": 1,
        "external_id": 1,
        "dry_run": 1,
        "agreement": 1
      },
      "refund_details": {
        "code": 4,
        "reason": "Potential fraud"
      }
    }
    $ curl -v 'https://your.hostname/your/uri' \
    -X POST \
    -d '{
      "notification_type": "afs_reject",
      "settings": {
        "project_id": 18404,
        "merchant_id": 2340
      },
      "user": {
        "ip": "127.0.0.1",
        "phone": "18777976552",
        "email": "semail@example.com",
        "id": "1234567",
        "name": "Xsolla User",
        "country": "US"
      },
      "transaction": {
        "id": 1,
        "external_id": 1,
        "dry_run": 1,
        "agreement": 1
      },
      "refund_details": {
        "code": 4,
        "reason": "Potential fraud"
      }
    }'
    响应
    <?php
    
    use Xsolla\SDK\Webhook\WebhookServer;
    use Xsolla\SDK\Webhook\Message\Message;
    use Xsolla\SDK\Exception\Webhook\XsollaWebhookException;
    
    $callback = function (Message $message) {
      if ($message->isRefund()) {
        $userArray = $message->getUser();
        $paymentArray = $message->getTransaction();
        $paymentId = $message->getPaymentId();
        $externalPaymentId = $message->getExternalPaymentId();
        $customParametersArray = $message->getCustomParameters();
        $isDryRun = $message->isDryRun();
        $refundArray = $message->getRefundDetails();
        $messageArray = $message->toArray();
        // TODO if you cannot handle the refund, you should throw XsollaWebhookException
      }
    };
    
    $webhookServer = WebhookServer::create($callback, PROJECT_KEY);
    $webhookServer->start();
    
    HTTP/1.1 204 No Content

    AFS更新的拦截列表

    AFS拦截列表发生更新(新增或移除了参数)时,艾克索拉会向Webhook URL发送通知。参数的增加在艾克索拉侧自动执行或根据请求执行。删除的移除只能根据请求执行。要启用此通知功能,请联系帐户经理。

    参数类型描述
    notification_type
    string通知类型。 必需
    event
    object包含AFS拦截列表事件信息的对象。 必需
    event.action
    string事件类型。可为以下值:addingremoving
    event.reason
    string事件原因。可为以下值:
    • 新增:chargeback — 拒付;fraud_activity — 欺诈;suspicious_activity — 可疑活动;ps_reported_fraud — 支付系统报告欺诈;linked_chargeback — 关联拒付;partner_request — 根据请求;friendly_fraud — 友好欺诈;user_reported_fraud — 用户报告欺诈;linked_parameter — AFS拦截列表中关联的参数;other_data_in_blacklist — AFS拦截列表中的其他参数;by_afs_filters — AFS筛选器;
    • 移除:wrongly_added — 误增;removed_by_cs_review — 向艾克索拉技术支持报告后移除;other_forgiveness_reason — 其他原因移除。
    event.parameter
    string发生事件的参数的名称。可为以下值:nick — 用户昵称;email — 用户邮箱地址;ps_account — 用户账单地址;ip_address — 用户IP地址;card_issuer — 用户信用卡发卡行;phone — 用户手机号码。
    event.parameter_value
    string发生事件的参数的值。
    event.date_of_last_action
    stringISO 8601格式的最近AFS拦截列表事件时间。
    event.transaction_id
    string发生事件的参数关联的交易ID。
    Copy
    Full screen
    Small screen
    http
    • http
    • curl
    请求
    POST /your_uri HTTP/1.1
    Host: your.host
    Accept: application/json
    Content-Type: application/json
    Content-Length: 233
    Authorization: Signature 32c64a80d2527dc08906ae1891bac4489509b9f6
    
    {
      "event": {
        "action": "adding",
        "date_of_last_action": "2020-11-27T10:09:05+03:00",
        "parameter": "email",
        "parameter_value": "some_cool_email@gmail.com",
        "reason": "ps_reported_fraud",
        "transaction_id": "111111111"
      },
      "notification_type": "afs_black_list"
    }
    $curl -v 'https://your.hostname/your/uri' \
    -X POST \
    -H 'Authorization: Signature 32c64a80d2527dc08906ae1891bac4489509b9f6' \
    -d '{
      "event": {
        "action": "adding",
        "date_of_last_action": "2020-11-27T10:09:05+03:00",
        "parameter": "email",
        "parameter_value": "some_cool_email@gmail.com",
        "reason": "ps_reported_fraud",
        "transaction_id": "111111111"
      },
      "notification_type": "afs_black_list"
    }'
    响应
    HTTP/1.1 204 No Content

    已创建订阅

    当用户创建订阅时,我们会在支付通知脚本上发送有关创建订阅的通知。

    参数类型描述
    notification_type
    string通知类型。 必需
    settings
    object带有自定义项目设置的对象。
    settings.project_id
    integer游戏的艾克索拉ID。可以在发布商帐户中找到该ID。
    settings.merchant_id
    integer商户ID。
    user
    object带用户相关数据的对象。
    user.id
    string用户ID。 必需
    user.name
    string用户名。
    subscription
    object订阅详情(对象)。
    subscription.plan_id
    string计划ID(如果计划通过API创建,则为外部ID)。
    subscription.tags
    array计划标签。
    subscription.subscription_id
    integer艾克索拉数据库的订阅ID。
    subscription.product_id
    string产品ID(如果在访问令牌中发送)。
    subscription.date_create
    string订阅的创建日期。符合ISO 8601标准规定的日期与时间。
    subscription.date_next_charge
    string下次收费的日期。符合ISO 8601标准规定的日期与时间。
    subscription.trial
    object带有订阅试用期相关数据的对象。
    subscription.trial.value
    integer试用期时长。
    subscription.trial.type
    string试用期类型:day。
    custom_parameters
    object您的自定义参数。
    Copy
    Full screen
    Small screen
    php
    • php
    • http
    • curl
    请求
    <?php
    
    $request = array(
        'notification_type' => 'create_subscription',
        'settings' => array(
           'project_id' => 18404,
           'merchant_id' => 2340
        ),
        'user' => array(
            'id' => '1234567',
            'name' => 'Xsolla User'
        ),
        'subscription' => array(
            'plan_id' => 'b5dac9c8',
            'subscription_id' => '10',
            'product_id' => 'Demo Product',
            'date_create' => '2014-09-22T19:25:25+04:00',
            'date_next_charge' => '2015-01-22T19:25:25+04:00',
            'trial' =>  array(
                    'value' =>  90,
                    'type' =>  'day'
                )
        )
    );
    
    POST /your/uri HTTP/1.1
    Host: your.hostname
    Accept: application/json
    Content-Type: application/json
    Content-Length: 240
    Authorization: Signature 13342703ccaca5064ad33ba451d800c5e823db8f
    
    {
        "notification_type": "create_subscription",
        "settings": {
           "project_id": 18404,
           "merchant_id": 2340
        },
        "user": {
            "id": "1234567",
            "name": "Xsolla User"
        },
        "subscription": {
            "plan_id": "b5dac9c8",
            "subscription_id": "10",
            "product_id": "Demo Product",
            "date_create": "2014-09-22T19:25:25+04:00",
            "date_next_charge": "2015-01-22T19:25:25+04:00",
            "trial": {
                    "value": 90,
                    "type": "day"
                }
        }
    }
    $ curl -v 'https://your.hostname/your/uri' \
    -X POST \
    -H 'Accept: application/json' \
    -H 'Content-Type: application/json' \
    -H 'Authorization: Signature 13342703ccaca5064ad33ba451d800c5e823db8f' \
    -d '{
            "notification_type": "create_subscription",
            "settings": {
               "project_id": 18404,
               "merchant_id": 2340
            },
            "user": {
                "id": "1234567",
                "name": "Xsolla User"
            },
            "subscription": {
                "plan_id": "b5dac9c8",
                "subscription_id": "10",
                "product_id": "Demo Product",
                "date_create": "2014-09-22T19:25:25+04:00",
                "date_next_charge": "2015-01-22T19:25:25+04:00",
                "trial": {
                        "value": 90,
                        "type": "day"
                    }
            }
        }'
    响应
    <?php
    
    use Xsolla\SDK\Webhook\WebhookServer;
    use Xsolla\SDK\Webhook\Message\Message;
    use Xsolla\SDK\Exception\Webhook\XsollaWebhookException;
    
    $callback = function (Message $message) {
        if ($message instanceof CreateSubscriptionMessage) {
           $messageArray = $message->toArray();
           // TODO if the subscription creation fails for some reason, you should throw XsollaWebhookException
        }
    };
    
    $webhookServer = WebhookServer::create($callback, PROJECT_KEY);
    $webhookServer->start();
    
    HTTP/1.1 204 No Content

    已更新订阅

    在订阅中的某些参数(plan_iddate_next_charge)发生变化以及每次续订订阅时,我们都会向您的 webhook URL 发送通知update_subscription

    参数类型描述
    notification_type
    string通知类型。 必需
    settings
    object带有自定义项目设置的对象。
    settings.project_id
    integer游戏的艾克索拉ID。可以在发布商帐户中找到该ID。
    settings.merchant_id
    integer商户ID。
    user
    object带用户相关数据的对象。
    user.id
    string用户ID。 必需
    user.name
    string用户名。
    subscription
    object订阅详情(对象)。
    subscription.plan_id
    string计划ID(如果计划通过API创建,则为外部ID)。
    subscription.tags
    array计划标签。
    subscription.subscription_id
    integer艾克索拉数据库的订阅ID。
    subscription.product_id
    string产品ID(如果在访问令牌中发送)。
    subscription.date_next_charge
    string下次收费的日期。符合ISO 8601标准规定的日期与时间。
    Copy
    Full screen
    Small screen
    php
    • php
    • http
    • curl
    请求
    <?php
    
    $request = array(
        'notification_type' => 'update_subscription',
        'settings' => array(
           'project_id' => 18404,
           'merchant_id' => 2340
        ),
        'user' => array(
            'id' => '1234567',
            'name' => 'Xsolla User'
        ),
        'subscription' => array(
            'plan_id' => 'b5dac9c8',
            'subscription_id' => '10',
            'product_id' => 'Demo Product',
            'date_next_charge' => '2015-01-22T19:25:25+04:00'
        )
    );
    
    POST /your/uri HTTP/1.1
    Host: your.hostname
    Accept: application/json
    Content-Type: application/json
    Content-Length: 240
    Authorization: Signature 13342703ccaca5064ad33ba451d800c5e823db8f
    
    {
        "notification_type": "update_subscription",
        "settings": {
           "project_id": 18404,
           "merchant_id": 2340
        },
        "user": {
            "id": "1234567",
            "name": "Xsolla User"
        },
        "subscription": {
            "plan_id": "b5dac9c8",
            "subscription_id": "10",
            "product_id": "Demo Product",
            "date_next_charge": "2015-01-22T19:25:25+04:00"
        }
    }
    $ curl -v 'https://your.hostname/your/uri' \
    -X POST \
    -H 'Accept: application/json' \
    -H 'Content-Type: application/json' \
    -H 'Authorization: Signature 13342703ccaca5064ad33ba451d800c5e823db8f' \
    -d '{
            "notification_type": "update_subscription",
            "settings": {
               "project_id": 18404,
               "merchant_id": 2340
            },
            "user": {
                "id": "1234567",
                "name": "Xsolla User"
            },
            "subscription": {
                "plan_id": "b5dac9c8",
                "subscription_id": "10",
                "product_id": "Demo Product",
                "date_next_charge": "2015-01-22T19:25:25+04:00"
            }
        }'
    响应
    <?php
    
    use Xsolla\SDK\Webhook\WebhookServer;
    use Xsolla\SDK\Webhook\Message\Message;
    use Xsolla\SDK\Exception\Webhook\XsollaWebhookException;
    
    $callback = function (Message $message) {
      if ($message instanceof UpdateSubscriptionMessage) {
         $messageArray = $message->toArray();
         // TODO if the subscription renewing fails for some reason, you should throw XsollaWebhookException
      }
    };
    
    $webhookServer = WebhookServer::create($callback, PROJECT_KEY);
    $webhookServer->start();
    
    HTTP/1.1 204 No Content

    已取消订阅

    出于某些理由取消订阅时,我们会在支付通知脚本上发送有关取消订阅的通知。

    参数类型描述
    notification_type
    string通知类型。 必需
    settings
    object带有自定义项目设置的对象。
    settings.project_id
    integer游戏的艾克索拉ID。可以在发布商帐户中找到该ID。
    settings.merchant_id
    integer商户ID。
    user
    object带用户相关数据的对象。
    user.id
    string用户ID。 必需
    user.name
    string用户名。
    subscription
    object订阅详情(对象)。
    subscription.plan_id
    string计划ID(如果计划通过API创建,则为外部ID)。
    subscription.tags
    array计划标签。
    subscription.subscription_id
    integer艾克索拉数据库的订阅ID。
    subscription.product_id
    string产品ID(如果在访问令牌中发送)。
    subscription.date_create
    string订阅的创建日期。符合ISO 8601标准规定的日期与时间。
    subscription.date_end
    string订阅结束的日期。符合ISO 8601标准规定的日期与时间。
    Copy
    Full screen
    Small screen
    php
    • php
    • http
    • curl
    请求
    <?php
    
    $request = array(
        'notification_type' => 'cancel_subscription',
        'settings' => array(
           'project_id' => 18404,
           'merchant_id' => 2340
        ),
        'user' => array(
            'id' => '1234567',
            'name' => 'Xsolla User'
        ),
        'subscription' => array(
            'plan_id' => 'b5dac9c8',
            'subscription_id' => '10',
            'product_id' => 'Demo Product',
            'date_create' => '2014-09-22T19:25:25+04:00',
            'date_end' => '2015-01-22T19:25:25+04:00',
        )
    );
    
    POST /your/uri HTTP/1.1
    Host: your.hostname
    Accept: application/json
    Content-Type: application/json
    Content-Length: 240
    Authorization: Signature 13342703ccaca5064ad33ba451d800c5e823db8f
    
    {
        "notification_type": "cancel_subscription",
        "settings": {
           "project_id": 18404,
           "merchant_id": 2340
        },
        "user":{
            "id": "1234567",
            "name": "Xsolla User"
        },
        "subscription": {
            "plan_id": "b5dac9c8",
            "subscription_id": "10",
            "product_id": "Demo Product",
            "date_create": "2014-09-22T19:25:25+04:00",
            "date_end": "2015-01-22T19:25:25+04:00"
        }
    }
    $ curl -v 'https://your.hostname/your/uri' \
    -X POST \
    -H 'Accept: application/json' \
    -H 'Content-Type: application/json' \
    -H 'Authorization: Signature 13342703ccaca5064ad33ba451d800c5e823db8f' \
    -d '{
            "notification_type": "cancel_subscription",
            "settings": {
               "project_id": 18404,
               "merchant_id": 2340
            },
            "user": {
                "id": "1234567",
                "name": "Xsolla User"
            },
            "subscription": {
                "plan_id": "b5dac9c8",
                "subscription_id": "10",
                "product_id": "Demo Product",
                "date_create": "2014-09-22T19:25:25+04:00",
                "date_end": "2015-01-22T19:25:25+04:00"
            }
        }'
    响应
    <?php
    
    use Xsolla\SDK\Webhook\WebhookServer;
    use Xsolla\SDK\Webhook\Message\Message;
    use Xsolla\SDK\Exception\Webhook\XsollaWebhookException;
    
    $callback = function (Message $message) {
        if ($message instanceof CancelSubscriptionMessage) {
           $messageArray = $message->toArray();
           // TODO if the subscription canceling fails for some reason, you should throw XsollaWebhookException
        }
    };
    
    $webhookServer = WebhookServer::create($callback, PROJECT_KEY);
    $webhookServer->start();
    
    HTTP/1.1 204 No Content

    到期性订阅

    订阅状态由于任何原因设置为非续订时,我们会向您的Webhook URL发送通知non_renewal_subscription。要启用该通知,请联系帐户经理。

    参数类型描述
    settings
    object带有自定义项目设置的对象。
    settings.project_id
    integer游戏的艾克索拉ID。可以在发布商帐户中找到该ID。必需
    settings.merchant_id
    integer商户ID。
    notification_type
    string通知类型。必需
    user
    object带用户相关数据的对象。
    user.id
    string用户ID。必需
    user.name
    string用户名。
    user.email
    string用户电子邮件。
    subscription
    object订阅详情(对象)。
    subscription.subscription_id
    integer艾克索拉数据库的订阅ID。
    subscription.plan_id
    string计划ID(如果计划通过API创建,则为外部ID)。
    subscription.date_create
    string订阅的创建日期。符合ISO 8601标准规定的日期与时间。
    subscription.date_next_charge
    string下一账单日期。此为用户订阅设置为不续订之前下一次付款的日期。格式为符合ISO 8601标准的日期和时间。
    subscription.currency
    string订阅使用的币种。参照ISO 4217标准的三字母货币代码。
    subscription.amount
    float以实际货币表示的价格。

    获取游戏密钥

    在用户每次成功购买后,为了获取游戏激活码我们将调用API访问您的服务器。

    参数类型描述
    notification_type
    string通知类型。
    settings
    object带有自定义项目设置的对象。
    settings.project_id
    integer游戏的艾克索拉ID。可以在发布商帐户中找到该ID。
    settings.merchant_id
    integer商户ID。
    user
    object带用户相关数据的对象。
    user.id
    string用户ID。 必需
    user.name
    string用户名。
    pin_code
    object游戏密钥详细信息(对象)。
    pin_code.digital_content
    string游戏的SKU。
    pin_code.DRM
    string游戏应对其可用的DRM。
    Copy
    Full screen
    Small screen
    php
    • php
    • http
    • curl
    请求
    <?php
    
    $request = array (
           'notification_type' => 'get_pincode',
           'settings' => array(
              'project_id' => 18404,
              'merchant_id' => 2340
           ),
           'user' =>
               array (
                   'id' => '1234567',
                   'name' => 'Xsolla User',
               ),
           'pin_code' =>
               array (
                   'digital_content' => 'Game SKU',
                   'DRM' => 'Steam',
               ),
       );
    
    POST /your/uri HTTP/1.1
    Host: your.hostname
    Accept: application/json
    Content-Type: application/json
    Content-Length: 240
    Authorization: Signature 13342703ccaca5064ad33ba451d800c5e823db8f
    
    {
        "notification_type": "get_pincode",
        "settings": {
           "project_id": 18404,
           "merchant_id": 2340
        },
        "user": {
            "id": "1234567",
            "name": "Xsolla User"
        },
        "pin_code": {
            "digital_content": "Game SKU",
            "DRM": "Steam"
        }
    }
    $ curl -v 'https://your.hostname/your/uri' \
    -X POST \
    -H 'Accept: application/json' \
    -H 'Content-Type: application/json' \
    -H 'Authorization: Signature 13342703ccaca5064ad33ba451d800c5e823db8f' \
    -d '{
            "notification_type": "get_pincode",
            "settings": {
               "project_id": 18404,
               "merchant_id": 2340
            },
            "user": {
                "id": "1234567",
                "name": "Xsolla User"
            },
            "pin_code": {
                "digital_content": "Game SKU",
                "DRM": "Steam"
            }
        }'
    响应
    <?php
    
    use Xsolla\SDK\Webhook\WebhookServer;
    use Xsolla\SDK\Webhook\Message\Message;
    use Xsolla\SDK\Exception\Webhook\XsollaWebhookException;
    
    $callback = function (Message $message) {
        if ($message instanceof GetPinCodeMessage) {
            $userArray = $message->getUser();
            $drmSku = $message->getDRM();
            $digitalContentSku = $message->getDigitalContent();
            // TODO get a pin code from your database or generate a new one. Put the pin code into variable $newPinCode
            $newPinCode = 'NEW_PIN_CODE';
            // TODO if the pin code creation or generation fail for some reason, you should throw XsollaWebhookException
            return new \Xsolla\SDK\Webhook\Response\PinCodeResponse($newPinCode);
        }
    };
    $webhookServer = WebhookServer::create($callback, PROJECT_KEY);
    $webhookServer->start();
    
    HTTP/1.1 200 OK
    Content-Type: application/json
    {
        "pin_code": "PIN_CODE"
    }

    激活密钥

    用户激活密钥时,艾克索拉会向您的Webhook URL发送通知。

    参数类型描述
    notification_type
    string通知类型。
    settings
    object带有自定义项目设置的对象。
    settings.project_id
    integer游戏的艾克索拉ID。可以在发布商帐户中找到该ID。
    settings.merchant_id
    integer商户 ID。
    key
    string激活密钥。
    sku
    string唯一密钥套餐ID。
    user_id
    string用户ID。
    activation_date
    datetime密钥激活日期,格式为ISO 8601规定的YYYYMMDDHHMMSS格式。
    user_country
    string用户所在国家/地区。参照ISO 3166-1 alpha-2标准的两个大写字母表示的国家/地区代码。
    restriction
    object包含区域限制簇设置的对象。该簇包含一个限制类型和该游戏适用的国家/地区、服务器和区域设置的列表。
    restriction.sku
    string唯一簇ID。
    restriction.name
    string簇名称。
    restriction.types
    array限制类型数组。
    restriction.countries
    array簇中的国家/地区数组。
    restriction.servers
    array游戏服务器数组。
    restriction.locales
    array区域设置数组。
    Copy
    Full screen
    Small screen
    php
    • php
    • http
    • curl
    请求
    <?php
    $request = array(
        'notification_type' => 'redeem_key',
        'settings' => array(
           'project_id' => 18404,
           'merchant_id' => 2340
        ),
        'key' => ‘wqdqwwddq9099022’,
        'sku' => 123,
        'user_id' => ‘sample_user’,
        'activation_date' => ‘2018-11-20T08:38:51+03:00,
        'user_country' => ‘EN’,
        'restriction' =>
               array(
                    'name' => ‘cls_1’,
                    'types' =>
                            array(
                                ‘activation’
                            ),
                    'countries' =>
                            array(
                                ‘RU’
                            ),
                 ),
    );  
    
    POST /your_uri HTTP/1.1
    Host: your.host
    Accept: application/json
    Content-Type: application/json
    Content-Length: 165
    Authorization: Signature 52eac2713985e212351610d008e7e14fae46f902
    
    {
      "notification_type": "redeem_key",
      "settings": {
         "project_id": 18404,
         "merchant_id": 2340
      },
      "key": "wqdqwwddq9099022",
      "sku": "123",
      "user_id": "sample_user",
      "activation_date": "2018-11-20T08:38:51+03:00",
      "user_country": "EN",
      "restriction": {
          "name": "cls_1",
          "types": [
               "activation"
            ],
            "countries": [
                 "RU"
            ]
      }
    }
    $ curl -v 'https://your.hostname/your/uri' \
    -X POST \
    -H 'Accept: application/json' \
    -H 'Content-Type: application/json' \
    -H 'Authorization: Signature 13342703ccaca5064ad33ba451d800c5e823db8f' \
    -d '{
      "notification_type": "redeem_key",
      "settings": {
            "project_id": 18404,
            "merchant_id": 2340
      },
      "key": "wqdqwwddq9099022",
      "sku": "123",
      "user_id": "sample_user",
      "activation_date": "2018-11-20T08:38:51+03:00",
      "user_country": "EN",
      "restriction": {
          "name": "cls_1",
          "types": [
               "activation"
            ],
            "countries": [
                 "RU"
             ]
        }
    }'
    响应
    <?php
    
    $response = null;
    
    HTTP/1.1 204 No Content

    列表好友

    该API应在合作伙伴侧实现。最大好友数为 2000。请参阅高级诀窍

    HTTP请求

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

    参数类型描述
    notification_type
    string定义获取好友列表请求类型的ID。值为friends_list
    user
    string购买礼品的用户的唯一ID。
    query
    string好友名称或ID(全部或部分)。
    limit
    string页面上元素数量的限制。 必需
    offset
    integer元素编号,从该元素开始生成列表(从0开始数)。
    sign
    string签名栏,按如下方式生成:
    • 串联以下三者:notification_type、根据键值按字母顺序排列的参数值、secret_key。
    • 对所得字符串应用SHA-1。
    Copy
    Full screen
    Small screen
    http
    • http
    • curl
    请求
    GET https://your.webhook.url?notification_type=friends_list&user=user_id&query=frien&offset=10&limit=20&sign=12dfg3f5gdsf4g5s6dfg2sdg1 HTTP/1.1
    Host: your.host
    Accept: application/json
    Content-Type: application/json
    Content-Length: 1220
    Authorization: Signature 31bd5924dd6cbc9cbe99d331c4a086a57291f9d7
    $ curl -v 'https://your.webhook.url?notification_type=friends_list&user=user_id&query=frien&offset=10&limit=20&sign=12dfg3f5gdsf4g5s6dfg2sdg1' \
    -X GET \
    -u merchant_id:merchant_api_key
    响应
    HTTP/1.1 200 OK
    Content-Type: application/json
    
    [
      {
        "friends": [
          {
            "id": "1",
            "name": "doctor",
            "email": "doctor@hospital.com",
            "image_url": "https://partner/link/doctor.jpg"
          },
          {
            "id": "2",
            "name": "cook",
            "email": "cook@kitchen.com",
            "image_url": "https://partner/link/cook.jpg"
          },
          {
            "id": "3",
            "name": "teacher",
            "email": "teacher@school.com"
          },
          {
            "id": "4",
            "name": "god",
            "email": "god@heaven.com",
            "image_url": "https://partner/link/god.jpg"
          }
          ],
        "total": 10
      }
    ]
    [
      {
      "friends": [
          {
            "id": "1",
            "name": "John Carter",
            "email": "carter@xsolla.com",
            "image_url": "https://partner/link/doctor.jpg"
          },
          {
            "id": "2",
            "name": "John Smith",
            "email": "smith@xsolla.com",
            "image_url": "https://partner/link/cook.jpg"
          }
        ],
      "total": 10
      }
    ]

    用户余额:支付

    用户支付时,我们会向您发送有关用户余额变化的特别通知。

    参数类型描述
    notification_type
    string通知类型。
    settings
    object带有自定义项目设置的对象。
    settings.project_id
    integer游戏的艾克索拉ID。可以在发布商帐户中找到该ID。
    settings.merchant_id
    integer商户ID。
    operation_type
    string操作类型。
    id_operation
    integer艾克索拉数据库中的操作ID。
    user
    object带用户相关数据的对象。
    user.id
    string用户ID。 必需
    user.name
    string用户名。
    user.email
    string用户电子邮件。
    virtual_currency_balance
    object带有系统中用户余额相关数据的对象。
    virtual_currency_balance.old_value
    string处理当前操作之前旧的用户余额值。
    virtual_currency_balance.new_value
    string处理当前操作之后新的用户余额值。
    virtual_currency_balance.diff
    string购买的游戏货币的金额。
    transaction
    object交易ID。 必需
    transaction.id
    integer交易ID。
    transaction.date
    string交易日期。
    Copy
    Full screen
    Small screen
    php
    • php
    • http
    • curl
    请求
    <?php
    
    $request = array(
        'settings' => array(
            'project_id' => 18404,
            'merchant_id' => 2340
        ),
        'virtual_currency_balance' => array(
            'old_value' => '0',
            'new_value' => '200',
            'diff' => '200'
        ),
        'user' => array(
            'name' => 'Xsolla User',
            'id' => '1234567',
            'email' => 'email@example.com'
        ),
        'transaction' => array(
            'id' => '123456789',
            'date' => '2015-05-19T15:54:40+03:00'
        ),
        'operation_type' => 'payment',
        'notification_type' => 'user_balance_operation',
        'id_operation' => '66989'
    );
    
    POST /your/uri HTTP/1.1
    Host: your.hostname
    Accept: application/json
    Content-Type: application/json
    Content-Length: 240
    Authorization: Signature 13342703ccaca5064ad33ba451d800c5e823db8f
    
    {
        "settings": {
            "project_id": 18404,
            "merchant_id": 2340
        },
        "virtual_currency_balance": {
            "old_value": "0",
            "new_value": "200",
            "diff": "200"
        },
        "user": {
            "name": "Xsolla User",
            "id": "1234567",
            "email": "email@example.com"
        },
        "transaction": {
            "id": "123456789",
            "date": "2015-05-19T15:54:40+03:00"
        },
        "operation_type": "payment",
        "notification_type": "user_balance_operation",
        "id_operation": "66989"
    }
    $ curl -v 'https://your.hostname/your/uri' \
    -X POST \
    -H 'Accept: application/json' \
    -H 'Content-Type: application/json' \
    -H 'Authorization: Signature 13342703ccaca5064ad33ba451d800c5e823db8f' \
    -d '{
            "settings": {
              "project_id": 18404,
              "merchant_id": 2340
            },
            "virtual_currency_balance": {
                "old_value": "0",
                "new_value": "200",
                "diff": "200"
            },
            "user": {
                "name": "Xsolla User",
                "id": "1234567",
                "email": "email@example.com"
            },
            "transaction": {
                "id": "123456789",
                "date": "2015-05-19T15:54:40+03:00"
            },
            "operation_type": "payment",
            "notification_type": "user_balance_operation",
            "id_operation": "66989"
        }'
    响应
    <?php
    
    use Xsolla\SDK\Webhook\WebhookServer;
    use Xsolla\SDK\Webhook\Message\Message;
    use Xsolla\SDK\Exception\Webhook\XsollaWebhookException;
    
    $callback = function (Message $message) {
        if ($message instanceof UserBalanceMessage) {
           $messageArray = $message->toArray();
           // TODO if the user balance operation fails for some reason, you should throw XsollaWebhookException
        }
    };
    
    $webhookServer = WebhookServer::create($callback, PROJECT_KEY);
    $webhookServer->start();
    
    HTTP/1.1 204 No Content

    用户余额:购买

    用户在游戏内进行购买时(例如购买虚拟物品),我们会向您发送有关用户余额变化的特别通知。

    参数类型描述
    notification_type
    string通知类型。
    settings
    object带有自定义项目设置的对象。
    settings.project_id
    integer游戏的艾克索拉ID。可以在发布商帐户中找到该ID。
    settings.merchant_id
    integer商户ID。
    operation_type
    string操作类型。
    id_operation
    integer艾克索拉数据库中的操作ID。
    user
    object带用户相关数据的对象。
    user.id
    string用户ID。 必需
    user.name
    string用户名。
    user.email
    string用户电子邮件。
    virtual_currency_balance
    object带有系统中用户余额相关数据的对象。
    virtual_currency_balance.old_value
    string处理当前操作之前旧的用户余额值。
    virtual_currency_balance.new_value
    string处理当前操作之后新的用户余额值。
    virtual_currency_balance.diff
    string购买的游戏货币的金额。
    items_operation_type
    string游戏内购买的操作类型。
    items
    array带有游戏内购买的物品相关数据的数组。
    items.sku
    string物品ID。
    items.amount
    integer物品数量。
    Copy
    Full screen
    Small screen
    php
    • php
    • http
    • curl
    请求
    <?php
    
    $request = array(
        'settings' => array(
                'project_id' => 18404,
                'merchant_id' => 2340
        ),
        'virtual_currency_balance' => array(
                'old_value' => '0',
                'new_value' => '200',
                'diff' => '200'
        ),
        'user' => array(
            'name' => 'Xsolla User',
            'id' => '1234567',
            'email' => 'email@example.com'
        ),
        'operation_type' => 'inGamePurchase',
        'notification_type' => 'user_balance_operation',
        'items_operation_type' =>  'add',
             'items' =>  array(
                 'sku' =>  '1468',
                 'amount' =>  '2'
             ),
        'id_operation' => '66989'
    );
    
    POST /your/uri HTTP/1.1
    Host: your.hostname
    Accept: application/json
    Content-Type: application/json
    Content-Length: 240
    Authorization: Signature 13342703ccaca5064ad33ba451d800c5e823db8f
    
    {
        "settings": {
            "project_id": 18404,
            "merchant_id": 2340
        },
        "virtual_currency_balance": {
            "old_value": "0",
            "new_value": "200",
            "diff": "200"
        },
        "user": {
            "name": "Xsolla User",
            "id": "1234567",
            "email": "email@example.com"
        },
        "operation_type": "inGamePurchase",
        "notification_type": "user_balance_operation",
        "items_operation_type": "add",
             "items": [{
             "sku": "1468",
             "amount": "2"
             }],
        "id_operation": "66989"
    }
    $ curl -v 'https://your.hostname/your/uri' \
    -X POST \
    -H 'Accept: application/json' \
    -H 'Content-Type: application/json' \
    -H 'Authorization: Signature 13342703ccaca5064ad33ba451d800c5e823db8f' \
    -d '{
            "settings": {
                "project_id": 18404,
                "merchant_id": 2340
            },
            "virtual_currency_balance": {
                "old_value": "0",
                "new_value": "200",
                "diff": "200"
            },
            "user": {
                "name": "Xsolla User",
                "id": "1234567",
                "email": "email@example.com"
            },
            "operation_type": "inGamePurchase",
            "notification_type": "user_balance_operation",
            "items_operation_type": "add",
                 "items": [{
                 "sku": "1468",
                 "amount": "2"
                 }],
            "id_operation": "66989"
        }'
    响应
    <?php
    
    use Xsolla\SDK\Webhook\WebhookServer;
    use Xsolla\SDK\Webhook\Message\Message;
    use Xsolla\SDK\Exception\Webhook\XsollaWebhookException;
    
    $callback = function (Message $message) {
        if ($message instanceof UserBalanceMessage) {
           $messageArray = $message->toArray();
           // TODO if the user balance operation fails for some reason, you should throw XsollaWebhookException
        }
    };
    
    $webhookServer = WebhookServer::create($callback, PROJECT_KEY);
    $webhookServer->start();
    
    HTTP/1.1 204 No Content

    用户余额:兑换优惠券

    如果用户兑换优惠券以获取游戏物品或虚拟货币,我们会向您发送与此有关的特别通知。

    参数类型描述
    notification_type
    string通知类型。
    settings
    object带有自定义项目设置的对象。
    settings.project_id
    integer游戏的艾克索拉ID。可以在发布商帐户中找到该ID。
    settings.merchant_id
    integer商户ID。
    operation_type
    string操作类型。
    id_operation
    integer艾克索拉数据库中的操作ID。
    user
    object带用户相关数据的对象。
    user.id
    string用户ID。 必需
    user.name
    string用户名。
    user.email
    string用户电子邮件。
    virtual_currency_balance
    object带有系统中用户余额相关数据的对象。
    virtual_currency_balance.old_value
    string处理当前操作之前旧的用户余额值。
    virtual_currency_balance.new_value
    string处理当前操作之后新的用户余额值。
    virtual_currency_balance.diff
    string购买的游戏货币的金额。
    items_operation_type
    string游戏内购买的操作类型。
    items
    array带有游戏内购买的物品相关数据的数组。
    items.sku
    string物品ID。
    items.amount
    integer物品数量。
    coupon
    object带有优惠券相关数据的对象。
    coupon.coupon_code
    string优惠券代码。
    coupon.campaign_code
    string优惠券营销活动的代码。
    Copy
    Full screen
    Small screen
    php
    • php
    • http
    • curl
    请求
    <?php
    
    $request = array(
        'settings' => array(
            'project_id' => 18404,
            'merchant_id' => 2340
        ),
        'virtual_currency_balance' => array(
            'old_value' => '0',
            'new_value' => '0',
            'diff' => '0'
        ),
        'user' => array(
            'name' => 'Xsolla User',
            'id' => '1234567',
            'email' => 'email@example.com'
        ),
        'operation_type' => 'coupon',
        'notification_type' => 'user_balance_operation',
        'items_operation_type' =>  'add',
             'items' =>  array(
                 'sku' =>  '1468',
                 'amount' =>  '2'
             ),
        'id_operation' => '66989',
        'coupon' =>  array(
             'coupon_code' =>  'test123',
             'campaign_code' =>  'Xsolla Campaign'
        )
    );
    
    POST /your/uri HTTP/1.1
    Host: your.hostname
    Accept: application/json
    Content-Type: application/json
    Content-Length: 240
    Authorization: Signature 13342703ccaca5064ad33ba451d800c5e823db8f
    
    {
        "settings": {
            "project_id": 18404,
            "merchant_id": 2340
        },
        "virtual_currency_balance": {
            "old_value": "0",
            "new_value": "0",
            "diff": "0"
        },
        "user": {
            "name": "Xsolla User",
            "id": "1234567",
            "email": "email@example.com"
        },
        "operation_type": "coupon",
        "notification_type": "user_balance_operation",
        "items_operation_type": "add",
             "items": [{
                 "sku": "1468",
                 "amount": "2"
             }],
        "id_operation": "66989",
        "coupon": {
             "coupon_code": "test123",
             "campaign_code": "Xsolla Campaign"
        }
    }
    $ curl -v 'https://your.hostname/your/uri' \
    -X POST \
    -H 'Accept: application/json' \
    -H 'Content-Type: application/json' \
    -H 'Authorization: Signature 13342703ccaca5064ad33ba451d800c5e823db8f' \
    -d '{
            "settings": {
                "project_id": 18404,
                "merchant_id": 2340
            },
            "virtual_currency_balance": {
                "old_value": "0",
                "new_value": "0",
                "diff": "0"
            },
            "user": {
                "name": "Xsolla User",
                "id": "1234567",
                "email": "email@example.com"
            },
            "operation_type": "coupon",
            "notification_type": "user_balance_operation",
            "items_operation_type": "add",
                 "items": [{
                     "sku": "1468",
                     "amount": "2"
                 }],
            "id_operation": "66989",
            "coupon": {
                 "coupon_code": "test123",
                 "campaign_code": "Xsolla Campaign"
            }
        }'
    响应
    <?php
    
    use Xsolla\SDK\Webhook\WebhookServer;
    use Xsolla\SDK\Webhook\Message\Message;
    use Xsolla\SDK\Exception\Webhook\XsollaWebhookException;
    
    $callback = function (Message $message) {
        if ($message instanceof UserBalanceMessage) {
           $messageArray = $message->toArray();
           // TODO if the user balance operation fails for some reason, you should throw XsollaWebhookException
        }
    };
    
    $webhookServer = WebhookServer::create($callback, PROJECT_KEY);
    $webhookServer->start();
    
    HTTP/1.1 204 No Content

    用户余额:手动更新

    如果需要手动更改用户余额,可以使用“Internal”操作类型。

    参数类型描述
    notification_type
    string通知类型。
    settings
    object带有自定义项目设置的对象。
    settings.project_id
    integer游戏的艾克索拉ID。可以在发布商帐户中找到该ID。
    settings.merchant_id
    integer商户ID。
    operation_type
    string操作类型。
    id_operation
    integer艾克索拉数据库中的操作ID。
    user
    object带用户相关数据的对象。
    user.id
    string用户ID。 必需
    user.name
    string用户名。
    user.email
    string用户电子邮件。
    virtual_currency_balance
    object带有系统中用户余额相关数据的对象。
    virtual_currency_balance.old_value
    string处理当前操作之前旧的用户余额值。
    virtual_currency_balance.new_value
    string处理当前操作之后新的用户余额值。
    virtual_currency_balance.diff
    string购买的游戏货币的金额。
    Copy
    Full screen
    Small screen
    php
    • php
    • http
    • curl
    请求
    <?php
    
    $request = array(
        'settings' => array(
            'project_id' => 18404,
            'merchant_id' => 2340
        ),
        'virtual_currency_balance' => array(
            'old_value' => '0',
            'new_value' => '100',
            'diff' => '100'
        ),
        'user' => array(
            'name' => 'Xsolla User',
            'id' => '1234567',
            'email' => 'email@example.com'
        ),
        'operation_type' => 'internal',
        'notification_type' => 'user_balance_operation',
        'id_operation' => '67002'
    );
    
    POST /your/uri HTTP/1.1
    Host: your.hostname
    Accept: application/json
    Content-Type: application/json
    Content-Length: 240
    Authorization: Signature 13342703ccaca5064ad33ba451d800c5e823db8f
    
    {
        "settings": {
            "project_id": 18404,
            "merchant_id": 2340
        },
        "virtual_currency_balance": {
            "old_value": "0",
            "new_value": "100",
            "diff": "100"
        },
        "user": {
            "name": "Xsolla User",
            "id": "1234567",
            "email": "email@example.com"
        },
        "operation_type": "internal",
        "notification_type": "user_balance_operation",
        "id_operation": "67002"
    }
    $ curl -v 'https://your.hostname/your/uri' \
    -X POST \
    -H 'Accept: application/json' \
    -H 'Content-Type: application/json' \
    -H 'Authorization: Signature 13342703ccaca5064ad33ba451d800c5e823db8f' \
    -d '{
            "settings": {
              "project_id": 18404,
              "merchant_id": 2340
            },
            "virtual_currency_balance": {
                "old_value": "0",
                "new_value": "100",
                "diff": "100"
            },
            "user": {
                "name": "Xsolla User",
                "id": "1234567",
                "email": "email@example.com"
            },
            "operation_type": "internal",
            "notification_type": "user_balance_operation",
            "id_operation": "67002"
        }'
    响应
    <?php
    
    use Xsolla\SDK\Webhook\WebhookServer;
    use Xsolla\SDK\Webhook\Message\Message;
    use Xsolla\SDK\Exception\Webhook\XsollaWebhookException;
    
    $callback = function (Message $message) {
        if ($message instanceof UserBalanceMessage) {
           $messageArray = $message->toArray();
           // TODO if the user balance operation fails for some reason, you should throw XsollaWebhookException
        }
    };
    
    $webhookServer = WebhookServer::create($callback, PROJECT_KEY);
    $webhookServer->start();
    
    HTTP/1.1 204 No Content

    用户余额:退款

    用户取消支付时,我们会向您发送有关用户余额变化的特别通知。

    参数类型描述
    notification_type
    string通知类型。
    settings
    object带有自定义项目设置的对象。
    settings.project_id
    integer游戏的艾克索拉ID。可以在发布商帐户中找到该ID。
    settings.merchant_id
    integer商户ID。
    operation_type
    string操作类型。
    id_operation
    integer艾克索拉数据库中的操作ID。
    user
    object带用户相关数据的对象。
    user.id
    string用户ID。 必需
    user.name
    string用户名。
    user.email
    string用户电子邮件。
    virtual_currency_balance
    object带有系统中用户余额相关数据的对象。
    virtual_currency_balance.old_value
    string处理当前操作之前旧的用户余额值。
    virtual_currency_balance.new_value
    string处理当前操作之后新的用户余额值。
    virtual_currency_balance.diff
    string购买的游戏货币的金额。
    transaction
    object交易ID。 必需
    transaction.id
    integer交易ID。
    transaction.date
    string交易日期。
    items_operation_type
    string游戏内购买的操作类型。
    items
    array带有游戏内购买的物品相关数据的数组。
    items.sku
    string物品ID。
    items.amount
    integer物品数量。
    Copy
    Full screen
    Small screen
    php
    • php
    • http
    • curl
    请求
    <?php
    
    $request = array(
         'settings' => array(
             'project_id' => 18404,
             'merchant_id' => 2340
         ),
         'virtual_currency_balance' => array(
             'old_value' => '0',
             'new_value' => '0',
             'diff' => '0'
         ),
         'user' => array(
             'name' => 'Xsolla User',
             'id' => '1234567',
             'email' => 'email@example.com'
         ),
         'transaction' => array(
             'id' => '123456789',
             'date' => '2015-05-19T15:54:40+03:00'
         ),
         'operation_type' => 'cancellation',
         'notification_type' => 'user_balance_operation',
         'items_operation_type' =>  'remove',
             'items' =>  array(
                 'sku' =>  '1468',
                 'amount' =>  '2'
             ),
         'id_operation' => '66989'
    );
    
    POST /your/uri HTTP/1.1
    Host: your.hostname
    Accept: application/json
    Content-Type: application/json
    Content-Length: 240
    Authorization: Signature 13342703ccaca5064ad33ba451d800c5e823db8f
    
    {
        "settings": {
            "project_id": 18404,
            "merchant_id": 2340
        },
        "virtual_currency_balance": {
            "old_value": "0",
            "new_value": "0",
            "diff": "0"
        },
        "user": {
            "name": "Xsolla User",
            "id": "1234567",
            "email": "email@example.com"
        },
        "transaction": {
            "id": "123456789",
            "date": "2015-05-19T15:54:40+03:00"
        },
        "operation_type": "cancellation",
        "notification_type": "user_balance_operation",
        "items_operation_type": "remove",
             "items": [{
                 "sku": "1468",
                 "amount": "2"
             }],
        "id_operation": "66989"
    }
    $ curl -v 'https://your.hostname/your/uri' \
    -X POST \
    -H 'Accept: application/json' \
    -H 'Content-Type: application/json' \
    -H 'Authorization: Signature 13342703ccaca5064ad33ba451d800c5e823db8f' \
    -d '{
            "settings": {
              "project_id": 18404,
              "merchant_id": 2340
            },
            "virtual_currency_balance": {
                "old_value": "0",
                "new_value": "0",
                "diff": "0"
            },
            "user": {
                "name": "Xsolla User",
                "id": "1234567",
                "email": "email@example.com"
            },
            "transaction": {
                "id": "123456789",
                "date": "2015-05-19T15:54:40+03:00"
            },
            "operation_type": "cancellation",
            "notification_type": "user_balance_operation",
            "items_operation_type": "remove",
                 "items": [{
                     "sku": "1468",
                     "amount": "2"
                 }],
            "id_operation": "66989"
        }'
    响应
    <?php
    
    use Xsolla\SDK\Webhook\WebhookServer;
    use Xsolla\SDK\Webhook\Message\Message;
    use Xsolla\SDK\Exception\Webhook\XsollaWebhookException;
    
    $callback = function (Message $message) {
        if ($message instanceof UserBalanceMessage) {
           $messageArray = $message->toArray();
           // TODO if the user balance operation fails for some reason, you should throw XsollaWebhookException
        }
    };
    
    $webhookServer = WebhookServer::create($callback, PROJECT_KEY);
    $webhookServer->start();
    
    HTTP/1.1 204 No Content

    添加支付帐户

    用户手动添加了支付帐户或在游戏内购物时保存了支付帐户时发送。要启用此通知,请联系帐户经理。

    参数类型描述
    notification_type
    string通知类型。 必需
    settings
    object带有自定义项目设置的对象。
    settings.project_id
    integer游戏的艾克索拉ID。可以在发布商帐户中找到该ID。
    settings.merchant_id
    integer商户ID。
    user
    object带用户相关数据的对象。
    user.ip
    string用户 IP 地址。
    user.email
    string用户电子邮件。
    user.id
    string用户ID。 必需
    user.name
    string用户名。
    user.country
    string用户所在国家/地区。使用 ISO 3166-1 alpha-2 标准规定的 2 字母组合表示国家/地区。
    user.zip
    string邮编。
    payment_account
    object支付帐户详细信息(对象)。
    payment_account.id
    string支付帐户ID。 必需
    payment_account.name
    string支付帐户在付款系统中的名称(例如支付卡卡号、邮箱等)。
    payment_account.payment_method
    integer付款方式ID。
    payment_account.type
    string支付帐户类型(例如银行卡、PayPal等)。
    Copy
    Full screen
    Small screen
    http
    • http
    • curl
    请求
    POST /your/uri HTTP/1.1
    Host:           your.hostname
    Accept:         application/json
    Content-Length: 255
    Content-Type:   application/json
    Authorization:  Signature d09695066c52c1b8bdae92f2d6eb59f5b5f89843
    
    {
        "notification_type": "payment_account_add",
        "settings": {
           "project_id": 18404,
           "merchant_id": 2340
        },
        "user": {
            "ip": "127.0.0.1",
            "email": "email@example.com",
            "id": "1234567",
            "name": "John Smith",
            "country": "RU",
            "zip": "12345"
        },
        "payment_account": {
            "id": "12345678",
            "name": "email@example.com",
            "payment_method": "24",
            "type": "paypal"
        }
    }
    $ curl -v 'https://your.hostname/your/uri' \
    -X POST \
    -H 'Accept: application/json' \
    -H 'Content-Type: application/json' \
    -H 'Authorization: Signature d09695066c52c1b8bdae92f2d6eb59f5b5f89843' \
    -d '{
        "notification_type":"payment_account_add",
        "settings": {
           "project_id": 18404,
           "merchant_id": 2340
        },
        "user": {
            "ip": "127.0.0.1",
            "email": "email@example.com",
            "id": "1234567",
            "name": "John Smith",
            "country": "RU",
            "zip": "12345"
        },
        "payment_account": {
            "id": "12345678",
            "name": "email@example.com",
            "payment_method": "24",
            "type": "paypal"
        }
    }'
    响应
    HTTP/1.1 204 No Content

    删除支付帐户

    用户从已保存的帐户中删除了支付帐户时发送。要启用此通知,请联系帐户经理。

    参数类型描述
    notification_type
    string通知类型。 必需
    settings
    object带有自定义项目设置的对象。
    settings.project_id
    integer游戏的艾克索拉ID。可以在发布商帐户中找到该ID。
    settings.merchant_id
    integer商户ID。
    user
    object带用户相关数据的对象。
    user.email
    string用户电子邮件。
    user.id
    string用户ID。 必需
    user.name
    string用户名。
    payment_account
    object支付帐户详细信息(对象)。
    payment_account.id
    string支付帐户ID。 必需
    payment_account.name
    string支付帐户在付款系统中的名称(例如支付卡卡号、邮箱等)。
    payment_account.payment_method
    integer付款方式ID。
    payment_account.type
    string支付帐户类型(例如银行卡、PayPal等)。
    Copy
    Full screen
    Small screen
    http
    • http
    • curl
    请求
    POST /your/uri HTTP/1.1
    Host:           your.hostname
    Accept:         application/json
    Content-Length: 258
    Content-Type:   application/json
    Authorization:  Signature d90d319f05df7b0f86d2485f48e7079f0f752523
    
    
    {
        "notification_type": "payment_account_remove",
        "settings": {
           "project_id": 18404,
           "merchant_id": 2340
        },
        "user": {
            "email": "email@example.com",
            "id": "1234567",
            "name": "John Smith"
        },
        "payment_account": {
            "id": "12345678",
            "name": "email@example.com",
            "payment_method": "24",
            "type": "paypal"
        }
    }
    $ curl -v 'https://your.hostname/your/uri' \
    -X POST \
    -H 'Accept: application/json' \
    -H 'Content-Type: application/json' \
    -H 'Authorization: Signature d09695066c52c1b8bdae92f2d6eb59f5b5f89843' \
    -d '{
        "notification_type": "payment_account_remove",
        "settings": {
           "project_id": 18404,
           "merchant_id": 2340
        },
        "user": {
            "email": "email@example.com",
            "id": "1234567",
            "name": "John Smith"
        },
        "payment_account": {
            "id": "12345678",
            "name": "email@example.com",
            "payment_method": "24",
            "type": "paypal"
        }
    }'
    响应
    HTTP/1.1 204 No Content

    Webhook错误

    永久性错误代码:

    代码消息
    INVALID_USER无效用户。
    INVALID_PARAMETER无效参数。
    INVALID_SIGNATURE无效签名。
    INCORRECT_AMOUNT金额不正确。
    INCORRECT_INVOICE发票不正确。
    Copy
    Full screen
    Small screen
    HTTP/1.1 400 Bad Request
    
    {
        "error":{
            "code":"INVALID_USER",
            "message":"Invalid user"
        }
    }

    本文对您的有帮助吗?
    谢谢!
    我们还有其他可改进之处吗? 留言
    非常抱歉
    请说明为何本文没有帮助到您。 留言
    感谢您的反馈!
    我们会查看您的留言并运用它改进用户体验。
    为此页面评分
    为此页面评分
    我们还有其他可改进之处吗?

    不想回答

    感谢您的反馈!
    上次更新时间: 2021年8月16日

    发现了错别字或其他内容错误? 请选择文本,然后按Ctrl+Enter。