Xsolla Documentation

概览

艾克索拉API包括：

Pay Station API — 支付UI和令牌化方法。
Store API — 用于游戏内商店和Buy Button模块的方法。
Subscription API — 用于订阅的方法。
Publisher Account API — 发布商帐户项目管理及用户管理，以及用于报告、支持工单的方法。
Login API — 使用自有界面认证用户的方法（请参阅集成指南）。

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

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

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

https://api.xsolla.com — Pay Station API、Store API、Publisher Account API
https://login.xsolla.com/api — Login API

大多数端点路径包含一个merchant_id参数。该参数指示应用程序所代表的商户。

请求和响应

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

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

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_id和api_key参数的值：

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

Notice:

请妥善保管您的API密钥。它是您的个人帐户和发布商帐户项目的访问凭证。
更改API密钥可能导致您的所有项目无法付款。更新为新密钥之前，使用当前密钥的API调用将无法运行。

示例

GET https://api.xsolla.com/merchant/v1/merchants/{merchant_id}/events/messages
Headers:
  Authorization: Basic <your_authorization_basic_key>

curl --request GET \
--url 'https://api.xsolla.com/merchant/v1/merchants/{merchant_id}/events/messages' \
--header 'authorization: Basic <your_authorization_basic_key>'

<?php

// if you use Xsolla SDK for PHP
use Xsolla\SDK\API\XsollaClient;
$xsollaClient = XsollaClient::factory(array(
    'merchant_id' => MERCHANT_ID,
    'api_key' => API_KEY
));
$eventsList = $client->ListEvents(array());

// if you don’t use Xsolla SDK for PHP
$client = new http\Client;
$request = new http\Client\Request;

$request->setRequestUrl('https://api.xsolla.com/merchant/v1/merchants/{merchant_id}/events/messages');
$request->setRequestMethod('GET');
$request->setHeaders(array(
  'authorization' => 'Basic <your_authorization_basic_key>'
));

$client->enqueue($request)->send();
$response = $client->getResponse();

echo $response->getBody();

var client = new RestClient("https://api.xsolla.com/merchant/v1/merchants/{merchant_id}/events/messages");
var request = new RestRequest(Method.GET);
request.AddHeader("authorization", "Basic <your_authorization_basic_key>");
IRestResponse response = client.Execute(request);

import http.client

conn = http.client.HTTPSConnection("api.xsolla.com")

headers = { 'authorization': "Basic <your_authorization_basic_key>" }

conn.request("GET", "/merchant/v1/merchants/{merchant_id}/events/messages", headers=headers)

res = conn.getresponse()
data = res.read()

print(data.decode("utf-8"))

require 'uri'
require 'net/http'

url = URI("https://api.xsolla.com/merchant/v1/merchants/{merchant_id}/events/messages")

http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true
http.verify_mode = OpenSSL::SSL::VERIFY_NONE

request = Net::HTTP::Get.new(url)
request["authorization"] = 'Basic <your_authorization_basic_key>'

response = http.request(request)
puts response.read_body

OkHttpClient client = new OkHttpClient();

Request request = new Request.Builder()
  .url("https://api.xsolla.com/merchant/v1/merchants/{merchant_id}/events/messages")
  .get()
  .addHeader("authorization", "Basic <your_authorization_basic_key>")
  .build();

Response response = client.newCall(request).execute();

var data = null;

var xhr = new XMLHttpRequest();
xhr.withCredentials = true;

xhr.addEventListener("readystatechange", function () {
  if (this.readyState === this.DONE) {
    console.log(this.responseText);
  }
});

xhr.open("GET", "https://api.xsolla.com/merchant/v1/merchants/{merchant_id}/events/messages");
xhr.setRequestHeader("authorization", "Basic <your_authorization_basic_key>");

xhr.send(data);

端点类型

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

操作	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_code	integer	HTTP代码
message	string	可读的错误描述信息。此信息始终是英文。对一些特定错误的说明，今后有可能会改变。
extended_message	string	错误的详细描述。
request_id	string	请求的唯一ID，用于帮助我们诊断问题。

{
    "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/24，185.30.21.0/24。

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

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

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

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

请求签名

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

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

请求

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_list	AFS拦截列表发生更新时发送。
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字母组合表示国家/地区。

请求

<?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。

请求

<?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平台。可以是'steam'、'playstation'、'xbox'、'uplay'、'origin'、'drmfree'、'gog'、'epicgames'、'nintendo_eshop'、'discord_game_store'或'oculus'。请确保您已在发布商帐户中配置了所需的DRM平台。
purchase.pin_codes.currency	string	购买游戏密钥的币种。参照ISO 4217标准的三字母货币代码。
purchase.pin_codes.amount	float	PIN 码的价格。
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	您的自定义参数。

请求

<?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.	用于接收到友好型欺诈相关消息的情况。

请求

<?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平台。

请求

<?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	退款申請人。

请求

<?php

$request = array(
  'notification_type' => 'afs_reject',
  'settings' => array(
    'project_id' => 18404,
    'merchant_id' => 2340
  ),
  'user' => array(
    'ip' => '127.0.0.1',
    'phone' => '18777976552',
    'email' => 'email@example.com',
    'id' => '1234567',
    'country' => 'US'
  ),
  'transaction' => array(
    'id' => 87654321,
    'payment_date' => '2014-09-23T19:25:25+04:00',
    'payment_method' => 1380,
    'dry_run' => 1
  ),
  'refund_details' => array(
    'code' => 4,
    'reason' => 'Potential fraud'
  )
);

POST /your_uri HTTP/1.1
Host: your.host
Accept: application/json
Content-Type: application/json
Content-Length: 1220
Authorization: Signature 31bd5924dd6cbc9cbe99d331c4a086a57291f9d7

{
  "notification_type": "afs_reject",
  "settings": {
    "project_id": 18404,
    "merchant_id": 2340
  },
  "user": {
    "ip": "127.0.0.1",
    "phone": "18777976552",
    "email": "semail@example.com",
    "id": "1234567",
    "name": "Xsolla User",
    "country": "US"
  },
  "transaction": {
    "id": 1,
    "external_id": 1,
    "dry_run": 1,
    "agreement": 1
  },
  "refund_details": {
    "code": 4,
    "reason": "Potential fraud"
  }
}

$ curl -v 'https://your.hostname/your/uri' \
-X POST \
-d '{
  "notification_type": "afs_reject",
  "settings": {
    "project_id": 18404,
    "merchant_id": 2340
  },
  "user": {
    "ip": "127.0.0.1",
    "phone": "18777976552",
    "email": "semail@example.com",
    "id": "1234567",
    "name": "Xsolla User",
    "country": "US"
  },
  "transaction": {
    "id": 1,
    "external_id": 1,
    "dry_run": 1,
    "agreement": 1
  },
  "refund_details": {
    "code": 4,
    "reason": "Potential fraud"
  }
}'

响应

<?php

use Xsolla\SDK\Webhook\WebhookServer;
use Xsolla\SDK\Webhook\Message\Message;
use Xsolla\SDK\Exception\Webhook\XsollaWebhookException;

$callback = function (Message $message) {
  if ($message->isRefund()) {
    $userArray = $message->getUser();
    $paymentArray = $message->getTransaction();
    $paymentId = $message->getPaymentId();
    $externalPaymentId = $message->getExternalPaymentId();
    $customParametersArray = $message->getCustomParameters();
    $isDryRun = $message->isDryRun();
    $refundArray = $message->getRefundDetails();
    $messageArray = $message->toArray();
    // TODO if you cannot handle the refund, you should throw XsollaWebhookException
  }
};

$webhookServer = WebhookServer::create($callback, PROJECT_KEY);
$webhookServer->start();

HTTP/1.1 204 No Content

AFS更新的拦截列表

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

参数	类型	描述
notification_type	string	通知类型。必需。
event	object	包含AFS拦截列表事件信息的对象。必需。
event.action	string	事件类型。可为以下值：adding、removing。
event.reason	string	事件原因。可为以下值：新增：chargeback — 拒付；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	string	ISO 8601格式的最近AFS拦截列表事件时间。
event.transaction_id	string	发生事件的参数关联的交易ID。

请求

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	您的自定义参数。

请求

<?php

$request = array(
    'notification_type' => 'create_subscription',
    'settings' => array(
       'project_id' => 18404,
       'merchant_id' => 2340
    ),
    'user' => array(
        'id' => '1234567',
        'name' => 'Xsolla User'
    ),
    'subscription' => array(
        'plan_id' => 'b5dac9c8',
        'subscription_id' => '10',
        'product_id' => 'Demo Product',
        'date_create' => '2014-09-22T19:25:25+04:00',
        'date_next_charge' => '2015-01-22T19:25:25+04:00',
        'trial' =>  array(
                'value' =>  90,
                'type' =>  'day'
            )
    )
);

POST /your/uri HTTP/1.1
Host: your.hostname
Accept: application/json
Content-Type: application/json
Content-Length: 240
Authorization: Signature 13342703ccaca5064ad33ba451d800c5e823db8f

{
    "notification_type": "create_subscription",
    "settings": {
       "project_id": 18404,
       "merchant_id": 2340
    },
    "user": {
        "id": "1234567",
        "name": "Xsolla User"
    },
    "subscription": {
        "plan_id": "b5dac9c8",
        "subscription_id": "10",
        "product_id": "Demo Product",
        "date_create": "2014-09-22T19:25:25+04:00",
        "date_next_charge": "2015-01-22T19:25:25+04:00",
        "trial": {
                "value": 90,
                "type": "day"
            }
    }
}

$ curl -v 'https://your.hostname/your/uri' \
-X POST \
-H 'Accept: application/json' \
-H 'Content-Type: application/json' \
-H 'Authorization: Signature 13342703ccaca5064ad33ba451d800c5e823db8f' \
-d '{
        "notification_type": "create_subscription",
        "settings": {
           "project_id": 18404,
           "merchant_id": 2340
        },
        "user": {
            "id": "1234567",
            "name": "Xsolla User"
        },
        "subscription": {
            "plan_id": "b5dac9c8",
            "subscription_id": "10",
            "product_id": "Demo Product",
            "date_create": "2014-09-22T19:25:25+04:00",
            "date_next_charge": "2015-01-22T19:25:25+04:00",
            "trial": {
                    "value": 90,
                    "type": "day"
                }
        }
    }'

响应

<?php

use Xsolla\SDK\Webhook\WebhookServer;
use Xsolla\SDK\Webhook\Message\Message;
use Xsolla\SDK\Exception\Webhook\XsollaWebhookException;

$callback = function (Message $message) {
    if ($message instanceof CreateSubscriptionMessage) {
       $messageArray = $message->toArray();
       // TODO if the subscription creation fails for some reason, you should throw XsollaWebhookException
    }
};

$webhookServer = WebhookServer::create($callback, PROJECT_KEY);
$webhookServer->start();

HTTP/1.1 204 No Content

已更新订阅

在订阅中的某些参数（"plan_id"、"date_next_charge"）发生变化以及每次续订订阅时，我们都会向您的 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标准规定的日期与时间。

请求

<?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标准规定的日期与时间。

请求

<?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。

请求

<?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	区域设置数组。

请求

<?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请求

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。

请求

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	交易日期。

请求

<?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	物品数量。

请求

<?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	优惠券营销活动的代码。

请求

<?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	购买的游戏货币的金额。

请求

<?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	物品数量。

请求

<?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

Webhook错误

永久性错误代码：

代码	消息
INVALID_USER	无效用户。
INVALID_PARAMETER	无效参数。
INVALID_SIGNATURE	无效签名。
INCORRECT_AMOUNT	金额不正确。
INCORRECT_INVOICE	发票不正确。

HTTP/1.1 400 Bad Request

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

感谢您的反馈！

我们会查看您的留言并运用它改进用户体验。

Your browser is not supported. Please try a different browser

入门

概览

请求和响应

API变更

版本控制

身份验证

端点类型

日期格式

分页

错误处理

Webhooks

概览

请求签名

响应

Webhook列表

用户验证

notification_type

settings

settings.project_id

settings.merchant_id

user

user.ip

user.phone

user.email

user.id

user.name

user.country

用户搜索

notification_type

settings

settings.project_id

settings.merchant_id

user

user.public_id

user.id

支付

notification_type

settings

settings.project_id

settings.merchant_id

purchase

purchase.virtual_currency

purchase.virtual_currency.name

purchase.virtual_currency.sku

purchase.virtual_currency.quantity

purchase.virtual_currency.currency

purchase.virtual_currency.amount

purchase.checkout

purchase.checkout.currency

purchase.checkout.amount

purchase.subscription

purchase.subscription.plan_id

purchase.subscription.subscription_id

purchase.subscription.product_id

purchase.subscription.tags

purchase.subscription.date_create

purchase.subscription.date_next_charge

purchase.subscription.currency

purchase.subscription.amount

purchase.virtual_items

purchase.virtual_items.items

purchase.virtual_items.items.sku

purchase.virtual_items.items.amount

purchase.virtual_items.currency

purchase.virtual_items.amount

purchase.pin_codes

purchase.pin_codes.digital_content

purchase.pin_codes.drm

purchase.pin_codes.currency

purchase.pin_codes.amount

purchase.pin_codes.upgrade

purchase.pin_codes.upgrade.digital_content_from

purchase.pin_codes.upgrade.digital_content_from.digital_content

purchase.pin_codes.upgrade.digital_content_from.DRM

purchase.pin_codes.upgrade.digital_content_to

purchase.pin_codes.upgrade.digital_content_to.digital_content

purchase.pin_codes.upgrade.digital_content_to.DRM

purchase.pin_codes.upgrade.currency

purchase.pin_codes.upgrade.amount