入门

概览

艾克索拉API包括:

  • 支付中心API — 支付UI和令牌化方法
  • 商店API — 用于商店模块的方法:虚拟货币、虚拟物品、订阅、游戏密钥、促销、优惠券
  • 发布商帐户API — 发布商帐户项目管理及用户管理,以及用于报告、支持工单的方法
  • 登录管理器API — 使用自有界面认证用户的方法(请参阅集成指南

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

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

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

  • https://api.xsolla.com — 支付中心API、商店API、发布商帐户API
  • https://login.xsolla.com/api — 登录管理器API
大多数端点路径包含一个 merchant_id 参数。该参数指示应用程序所代表的商户。

发行说明

2.0版本中的改动:
  • 导出交易的新URL:https://api.xsolla.com/merchant/v2/merchants/{merchant_id}/reports/transactions/registry.{format}
  • 更改了响应格式:
    • 取消的交易在以下字段为负值:
      • 付款系统固定费用
      • 艾克索拉费用(固定)
      • 销售税
      • 虚拟货币购买金额
      • 简单结账购买金额
      • 物品购买金额
      • 汇回本国费用,总计
      • 扣除的费用,固定
      • 余额抵扣的费用
      • 从付款系统支付的金额
      • 从余额支付的金额
      • 从余额提现的金额
      • PIN码购买金额
    • 新增了以下字段:
      • 付款系统类型 - 支付类型
      • 增值税 - 向用户显示的增值税
      • 增值税,% - 该国家/地区的增值税百分比
      • 退款原因说明 - 对退款原因的说明
      • 直接帐户 - 是否为直接帐户
    • 删除了以下字段:
      • 付款系统外部费用(%)
      • 付款系统外部费用金额
      • 付款系统外部费用货币
      • 如“扣除的增值税”为0,则“扣除的增值税,%”设置为0。
    • 重命名了以下字段:
      • 增值税 -> 扣除的增值税
      • 增值税(%) -> 扣除的增值税,%
    • 以下字段等于0则未填:
      • 虚拟货币金额
      • 虚拟货币购买金额
      • 简单结账购买金额
      • PIN码购买金额
    • 如“虚拟货币购买金额”等于0,则“虚拟货币购买货币”为未填。
    • 如“简单结账购买金额”等于0,则“简单结账购买货币”为未填。
    • 如“PIN码购买金额”等于0,则“PIN码购买货币”为未填。“PIN码购物车内容”为空。

请求和响应

发送给艾克索拉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_idapi_key参数的值:

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

Notice: 请妥善保存API密钥,勿让他人知晓。该密钥提供您的个人帐户及发布商帐户中项目的访问凭证。
Copy
Full 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_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"
}

令牌

为使支付更加安全,艾克索拉 API 使用包含一系列支付参数的令牌,而不是通过 HTTP GET 请求直接在支付页面上接收数据。在调用支付页面之前,您应获取新的令牌。令牌的生命周期为 24 小时。

获取令牌

HTTP请求

POST https://api.xsolla.com/merchant/v2/merchants/{merchant_id}/token

艾克索拉支持通过任意用户参数创建令牌。您发送这些参数,我们会在您支付后收到这些参数。令牌包含所有用户参数。

参数 类型 描述
user
object 带用户相关数据的对象。
user.id
object 带有用户 ID 相关数据的对象。 必需
user.id.value
string 用户ID。
user.name
object 带有用户昵称相关数据的对象。
user.name.value
string 用户昵称。
user.email
object 带有用户电子邮件相关数据的对象。
user.email.value
string 用户电子邮箱。必须符合RFC 822协议标准。
user.phone
object 用户电话号码(对象)。
user.phone.value
string 电话号码。
user.country
object 带有用户所在的国家/地区相关数据的对象。
user.country.value
string 使用 ISO 3166-1 alpha-2 标准规定的 2 字母组合表示国家/地区。
user.country.allow_modify
boolean 用户是否可以更改支付 UI 上的国家/地区。默认值为'false'。
user.attributes
object 带有用户属性相关数据的对象,用于筛选物品列表。应当是带键值对的有效 JSON 哈希。
user.steam_id
object 带有用户 Steam ID 相关数据的对象。
user.steam_id.value
string Steam ID。
user.tracking_id
object 带用户跟踪 ID 相关数据的对象。
user.tracking_id.value
string 唯一的跟踪 ID(用于营销活动)。
user.public_id.value
string 唯一识别用户并为用户所熟知的参数,与用户 ID(电子邮件、昵称等)不同。此参数在可以在游戏商店以外进行购买时使用(如现金售货亭中的游戏按键)。
user.utm
object 对象包含描述流量特性的数据。
user.utm.utm_source
string 流量来源。
user.utm.utm_medium
string 流量渠道(内容关联广告、媒体广告、邮件列表消息)。
user.utm.utm_campaign
string 活动标题。该参数应当包含直译的活动标题或者翻译为英文的活动标题。
user.utm.utm_term
string 活动关键词。在指定该参数的情况下,统计数据是基于在确定您的广告活动的目标对象过程中所使用的关键词数据而生成的,而不是基于检索项数据。在Google Analytics中,utm_term标签的内容成为包含检索项的综合报告中的一部分。
user.utm.utm_content
string 该活动的实质。
boolean 用户是否为法律实体。
object 包含法律实体详细信息的对象。如果user.is_legal为‘true’,则对象及其所有参数为必需
string 完整法定名称。
string 完整法定地址。
string 个人纳税人识别号。
string 公司所在国家/地区。参照ISO 3166-1 alpha-2标准的两个大写字母表示的国家/地区代码。
settings
object 带有自定义项目设置的对象。
settings.external_id
string 交易的外部 ID。
settings.project_id
integer 游戏的艾克索拉ID。可以在发布商帐户中找到该ID。 必需
settings.language
string 界面语言。符合 ISO 639-1 标准规定的 2 字母语言代码(小写字母)。
settings.return_url
string 用户会在支付过后被重定向到此页面。参数"user_id", "foreinginvoice", "invoice_id"和"status"会被自动添加到此链接。
settings.currency
string 首选支付币种。参照ISO 4217标准的三字母货币代码。
settings.mode
string 设置为'sandbox'值以测试支付流程。请使用https://sandbox-secure.xsolla.com来访问测试支付UI。
settings.payment_method
integer 付款方式标识符。
settings.payment_widget
string 支付小部件。可以是 'paybycash' 或 'giftcard' 。如果参数已设置,用户将分别重定向到 Pay by Cash 或 Gift Cards 小部件。
settings.ui
object 带有界面设置相关数据的对象。
settings.ui.theme
string 支付 UI 的外观主题。可以是'default'(默认值)或'default_dark'。
settings.ui.size
string 支付 UI 的大小。此参数可拥有以下值之一,具体取决于 支付 UI 的所需大小::
  • small: 支付 UI 支持的最小尺寸。当窗口大小严格受限时,请使用此值(尺寸:620 x 630)
  • medium:支付 UI 的推荐大小。使用此值可以在灯箱中显示支付 UI(尺寸:740 x 760)
  • large:在新窗口或者选项卡中显示支付 UI 的最佳大小(尺寸:820 x 840)
settings.ui.version
string 设备的类型。可以是'desktop'(默认值)或'mobile'。
settings.ui.desktop
object 带有对桌面版本有效的界面设置相关数据的对象。
settings.ui.desktop.header
object 带有标题设置相关数据的对象。
settings.ui.desktop.header.is_visible
boolean 标题在支付 UI 上是否可见。
boolean 如果为 'true',标题中将显示徽标(首先请把徽标文件提供给负责人)。
settings.ui.desktop.header.visible_name
boolean 标题中是否显示项目名称。
settings.ui.desktop.header.visible_purchase
boolean 是否在标题中显示购买描述(purchase.description.value)。默认为‘true’。
settings.ui.desktop.header.type
string 如何显示标题。不能为“compact”(隐藏项目名称和用户ID)或“normal”(默认)。
settings.ui.desktop.header.close_button
boolean 是否在支付中心桌面端显示 关闭 按钮。该按钮将关闭支付中心并将用户重定向到"settings.return_url"参数中指定的URL。默认为'false'。
settings.ui.desktop.subscription_list
object 带有订阅列表设置相关数据的对象。
settings.ui.desktop.subscription_list.layout
string 订阅列表模式。可以是'list'(默认值)或'grid'。
settings.ui.desktop.subscription_list.description
string 可以在此传递订阅相关的任意文本。文本将显示在订阅计划列表的上方。
settings.ui.desktop.subscription_list.display_local_price
boolean 如果 'true' 并且如果用户的当地货币与订阅计划的货币不同,则用户将看到两种价格:以当地货币和基础货币标价的价格。
settings.ui.desktop.virtual_item_list
object 带有虚拟物品列表设置相关数据的对象。
settings.ui.desktop.virtual_item_list.layout
string 订阅列表模式。可以是'list'(默认值)或'grid'。
settings.ui.desktop.virtual_item_list.button_with_price
boolean 如果为'true',则价格会显示在按钮里。如果为'false',则价格会显示在按钮左侧。默认值为'false'。
settings.ui.desktop.virtual_item_list.view
string 以垂直 / 水平菜单显示虚拟项目组。可以'horizontal_navigation' 或 'vertical'(默认)。
settings.ui.desktop.virtual_currency_list
object 带有虚拟货币列表设置相关数据的对象。
settings.ui.desktop.virtual_currency_list.description
string 可以在此传递虚拟货币列表相关的任意文本。文本将显示在虚拟货币包列表的上方。
settings.ui.desktop.virtual_currency_list.button_with_price
boolean 如果为'true',则价格会显示在按钮里。如果为'false',则价格会显示在按钮左侧。默认值为'false'。
settings.ui.header.visible_virtual_currency_Balance
boolean 此元素是否可在支付UI上隐藏。默认为'true'。
settings.ui.mobile.mode
string 用户仅可以通过他们已保存的付款方式进行付款。可以为'saved_accounts'。
settings.ui.mobile.header.close_button
boolean 是否在支付中心移动端显示 关闭 按钮,按此按钮时支付中心将关闭,并且用户将被重定向至在“settings.return_url”参数中指定的 URL(默认值为 'false')。
boolean 是否在移动版本的支付 UI 中隐藏或显示脚注。
settings.ui.license_url
string EULA 的链接。
settings.ui.components
object 带有模块菜单设置相关数据的对象。
settings.ui.components.virtual_items
object 带有虚拟物品模块设置相关数据的对象。
settings.ui.components.virtual_items.order
integer 虚拟物品在模块菜单中的排列顺序。
settings.ui.components.virtual_items.hidden
boolean 在菜单中显示还是隐藏“管理订阅”页面。
settings.ui.components.virtual_items.selected_group
string 用户打开虚拟物品选项卡时将会选择的组。
settings.ui.components.virtual_items.selected_item
string 用户打开虚拟物品选项卡时将会选择的物品。物品 SKU 应发送至此处。
settings.ui.components.virtual_currency
object 带有虚拟货币模块设置相关数据的对象。
settings.ui.components.virtual_currency.custom_amount
boolean 是否允许在支付UI中输入任意数量的虚拟货币。
settings.ui.components.virtual_currency.order
integer 虚拟物品在模块菜单中的排列顺序。
settings.ui.components.virtual_currency.hidden
boolean 在菜单中显示还是隐藏“管理订阅”页面。
settings.ui.components.subscriptions
object 带有订阅模块设置相关数据的对象。
settings.ui.components.subscriptions.order
integer 虚拟物品在模块菜单中的排列顺序。
settings.ui.components.subscriptions.hidden
boolean 在菜单中显示还是隐藏“管理订阅”页面。
settings.ui.mode
string 用户帐户中的支付界面。可能的值为“user_account”。请注意,标头仅包含用户帐户的导航菜单,而没有用于选择产品或进行付款的任何选项。“用户帐户”仅在桌面模式下可用。
settings.ui.user_account
object 对象以及有关用户账号的数据。
settings.ui.user_account.info
object “我的帐户”页面。
settings.ui.user_account.info.order
integer 虚拟物品在模块菜单中的排列顺序。
settings.ui.user_account.info.enable
boolean 在菜单中显示还是隐藏“管理订阅”页面。默认值为'false'。
settings.ui.user_account.history
object 用户的“历史记录”页面。
settings.ui.user_account.history.order
integer 虚拟物品在模块菜单中的排列顺序。
settings.ui.user_account.history.enable
boolean 在菜单中显示还是隐藏“管理订阅”页面。默认值为'false'。
settings.ui.user_account.payment_accounts
object “我的支付帐户”页面。
settings.ui.user_account.payment_accounts.order
integer 虚拟物品在模块菜单中的排列顺序。
settings.ui.user_account.payment_accounts.enable
boolean 在菜单中显示还是隐藏“管理订阅”页面。默认值为'false'。
settings.ui.user_account.subscriptions
object “管理订阅”页面。
settings.ui.user_account.subscriptions.order
integer 虚拟物品在模块菜单中的排列顺序。
settings.ui.user_account.subscriptions.enable
boolean 在菜单中显示还是隐藏“管理订阅”页面。默认值为'false'。
settings.shipping_enabled
boolean 是否显示收货地址表单。默认值为'false'。
purchase
object 带有购买相关数据的对象。
purchase.virtual_currency
object 带有虚拟货币相关数据的对象。
purchase.virtual_currency.quantity
float 使用虚拟货币购买的数量。
purchase.virtual_currency.currency
string 虚拟货币套餐的币种,以此币种进行所有计算。
purchase.virtual_items
object 带有购买的虚拟物品相关数据的对象。
purchase.virtual_items.currency
string 购买中虚拟物品的币种,以此币种进行所有计算。
purchase.virtual_items.items
array 带有购买的物品相关数据的数组。
purchase.virtual_items.items.sku
string 物品 ID。
purchase.virtual_items.items.amount
integer 物品数量。
purchase.virtual_items.available_groups
array 带有物品组 ID 的数组。支付 UI 中将仅显示指定组的物品。
purchase.subscription
object 带有订阅相关数据的对象。
purchase.subscription.plan_id
string 计划 ID。
purchase.subscription.operation
string 此操作的类型应用于用户订阅计划。要更改订阅计划,请传入‘change_plan’值。需在purchase.subscription.plan_id参数中指定新计划的ID。
purchase.subscription.product_id
string 产品ID。
purchase.subscription.currency
string 购买计划的货币, 以此币种进行所有计算。
purchase.subscription.available_plans
array 包含订阅套餐相关数据的数组。只有这些套餐会显示在支付用户界面中。
purchase.subscription.trial_days
integer 试用期,以天为单位。
purchase.pin_codes
object 游戏密钥(对象)。
purchase.pin_codes.currency
string 购买游戏密钥的币种,以此币种进行所有计算。
purchase.pin_codes.codes
array 游戏密钥(数组)。
purchase.pin_codes.codes.digital_content
string 在发布商帐户中设置的游戏SKU。
purchase.pin_codes.codes.drm
string 分发游戏的 DRM。可以是'steam'、'playstation'、'xbox'、'uplay'、'origin'或'drmfree'。请确保您已在“发布商帐户”中配置所需的 DRM。如果此参数未在令牌中传递,用户可以在支付 UI 中选择 DRM。
purchase.pin_codes.upgrade
object 包含升级数据的对象。
purchase.pin_codes.upgrade.id_user_history
integer 包含关于用户及其套餐数据的条目ID。
purchase.pin_codes.upgrade.id
integer 升级ID。
purchase.checkout
object 带有结账参数相关数据的对象。
purchase.checkout.currency
string 购买币种。参照ISO 4217标准的三字母货币代码。
purchase.checkout.amount
float 购买金额。
purchase.description
object 带有购买描述相关数据的对象。
purchase.description.value
string 包含在UI和电子邮件购买凭证中的购买描述。
purchase.gift
object 礼物详情(对象)。
purchase.gift.giver_id
string 送礼人ID。
purchase.gift.message
string 送礼人留言。
purchase.gift.hide_giver_from_receiver
string 是否对收礼人隐藏送礼人的身份信息。默认值为'true'。
purchase.gift.friends
array 包含好友数据的数组。
purchase.gift.friends.id
string 收礼人ID。
purchase.gift.friends.name
string 收礼人昵称。
purchase.gift.friends.email
string 收礼人邮箱。
purchase.coupon_code
object 关于购买时的折扣促销码或奖励的信息(对象)。
purchase.coupon_code.value
string 促销码值。
purchase.coupon_code.hidden
boolean 在支付UI中隐藏输入促销码的字段。默认为'false'。
custom_parameters
object 您的自定义参数。应当是带键值对的有效 JSON 哈希。

如果任何参数以不正确的格式或类型发送,将不会获得令牌。作为响应,您将接收到 422 HTTP 代码,Json 正文中有相应的错误描述。在"extended_message"中, 我们将向您提供关于不正确请求参数有关的信息。

{
    "extended_message": {
        "global_errors": [],
        "property_errors": {
            "settings.project_id": [
                "string value found, but an integer is required"
            ]
        }
    }
}

Copy
Full screen
http
  • http
  • curl
  • php
  • C#
  • python
  • ruby
  • java
  • js
请求
POST https://api.xsolla.com/merchant/v2/merchants/{merchant_id}/token

Headers:
  Authorization: Basic <your_authorization_basic_key>
Content-Type: application/json

Body:
  {
  "purchase": {
    "virtual_currency": {
      "quantity": 100
    },
    "virtual_items": {
      "items": [
        {
          "amount": 1,
          "sku": "SKU01"
        }
      ]
    }
  },
  "settings": {
    "currency": "USD",
    "language": "en",
    "project_id": 16184,
    "ui": {
      "components": {
        "virtual_currency": {
          "custom_amount": true
        }
      },
      "desktop": {
        "virtual_item_list": {
          "button_with_price": true,
          "layout": "list"
        }
      },
      "size": "medium"
    }
  },
  "user": {
    "country": {
      "allow_modify": true,
      "value": "US"
    },
    "email": {
      "value": "john.smith@mail.com"
    },
    "id": {
      "value": "user_2"
    },
    "name": {
      "value": "John Smith"
    }
  }
}
curl --request POST \
  --url https://api.xsolla.com/merchant/v2/merchants/{merchant_id}/token \
  --header 'authorization: Basic <your_authorization_basic_key>' \
  --header 'content-type: application/json' \
  --data '{"user":{"id":{"value":"user_2"},"name":{"value":"John Smith"},"email":{"value":"john.smith@mail.com"},"country":{"value":"US","allow_modify":true}},"settings":{"project_id":16184,"currency":"USD","language":"en","ui":{"size":"medium","desktop":{"virtual_item_list":{"layout":"list","button_with_price":true}},"components":{"virtual_currency":{"custom_amount":true}}}},"purchase":{"virtual_currency":{"quantity":100},"virtual_items":{"items":[{"sku":"SKU01","amount":1}]}}}'
<?php

$client = new http\Client;
$request = new http\Client\Request;

$body = new http\Message\Body;
$body->append('{"user":{"id":{"value":"user_2"},"name":{"value":"John Smith"},"email":{"value":"john.smith@mail.com"},"country":{"value":"US","allow_modify":true}},"settings":{"project_id":16184,"currency":"USD","language":"en","ui":{"size":"medium","desktop":{"virtual_item_list":{"layout":"list","button_with_price":true}},"components":{"virtual_currency":{"custom_amount":true}}}},"purchase":{"virtual_currency":{"quantity":100},"virtual_items":{"items":[{"sku":"SKU01","amount":1}]}}}');

$request->setRequestUrl('https://api.xsolla.com/merchant/v2/merchants/{merchant_id}/token');
$request->setRequestMethod('POST');
$request->setBody($body);

$request->setHeaders(array(
  'authorization' => 'Basic <your_authorization_basic_key>',
  'content-type' => 'application/json'
));

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

echo $response->getBody();
var client = new RestClient("https://api.xsolla.com/merchant/v2/merchants/{merchant_id}/token");
var request = new RestRequest(Method.POST);
request.AddHeader("authorization", "Basic <your_authorization_basic_key>");
request.AddHeader("content-type", "application/json");
request.AddParameter("application/json", "{\"user\":{\"id\":{\"value\":\"user_2\"},\"name\":{\"value\":\"John Smith\"},\"email\":{\"value\":\"john.smith@mail.com\"},\"country\":{\"value\":\"US\",\"allow_modify\":true}},\"settings\":{\"project_id\":16184,\"currency\":\"USD\",\"language\":\"en\",\"ui\":{\"size\":\"medium\",\"desktop\":{\"virtual_item_list\":{\"layout\":\"list\",\"button_with_price\":true}},\"components\":{\"virtual_currency\":{\"custom_amount\":true}}}},\"purchase\":{\"virtual_currency\":{\"quantity\":100},\"virtual_items\":{\"items\":[{\"sku\":\"SKU01\",\"amount\":1}]}}}", ParameterType.RequestBody);
IRestResponse response = client.Execute(request);
import http.client

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

payload = "{\"user\":{\"id\":{\"value\":\"user_2\"},\"name\":{\"value\":\"John Smith\"},\"email\":{\"value\":\"john.smith@mail.com\"},\"country\":{\"value\":\"US\",\"allow_modify\":true}},\"settings\":{\"project_id\":16184,\"currency\":\"USD\",\"language\":\"en\",\"ui\":{\"size\":\"medium\",\"desktop\":{\"virtual_item_list\":{\"layout\":\"list\",\"button_with_price\":true}},\"components\":{\"virtual_currency\":{\"custom_amount\":true}}}},\"purchase\":{\"virtual_currency\":{\"quantity\":100},\"virtual_items\":{\"items\":[{\"sku\":\"SKU01\",\"amount\":1}]}}}"

headers = {
    'content-type': "application/json",
    'authorization': "Basic <your_authorization_basic_key>"
    }

conn.request("POST", "/merchant/v2/merchants/{merchant_id}/token", payload, 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}/token")

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

request = Net::HTTP::Post.new(url)
request["content-type"] = 'application/json'
request["authorization"] = 'Basic <your_authorization_basic_key>'
request.body = "{\"user\":{\"id\":{\"value\":\"user_2\"},\"name\":{\"value\":\"John Smith\"},\"email\":{\"value\":\"john.smith@mail.com\"},\"country\":{\"value\":\"US\",\"allow_modify\":true}},\"settings\":{\"project_id\":16184,\"currency\":\"USD\",\"language\":\"en\",\"ui\":{\"size\":\"medium\",\"desktop\":{\"virtual_item_list\":{\"layout\":\"list\",\"button_with_price\":true}},\"components\":{\"virtual_currency\":{\"custom_amount\":true}}}},\"purchase\":{\"virtual_currency\":{\"quantity\":100},\"virtual_items\":{\"items\":[{\"sku\":\"SKU01\",\"amount\":1}]}}}"

response = http.request(request)
puts response.read_body
OkHttpClient client = new OkHttpClient();

MediaType mediaType = MediaType.parse("application/json");
RequestBody body = RequestBody.create(mediaType, "{\"user\":{\"id\":{\"value\":\"user_2\"},\"name\":{\"value\":\"John Smith\"},\"email\":{\"value\":\"john.smith@mail.com\"},\"country\":{\"value\":\"US\",\"allow_modify\":true}},\"settings\":{\"project_id\":16184,\"currency\":\"USD\",\"language\":\"en\",\"ui\":{\"size\":\"medium\",\"desktop\":{\"virtual_item_list\":{\"layout\":\"list\",\"button_with_price\":true}},\"components\":{\"virtual_currency\":{\"custom_amount\":true}}}},\"purchase\":{\"virtual_currency\":{\"quantity\":100},\"virtual_items\":{\"items\":[{\"sku\":\"SKU01\",\"amount\":1}]}}}");
Request request = new Request.Builder()
  .url("https://api.xsolla.com/merchant/v2/merchants/{merchant_id}/token")
  .post(body)
  .addHeader("content-type", "application/json")
  .addHeader("authorization", "Basic <your_authorization_basic_key>")
  .build();

Response response = client.newCall(request).execute();
var data = JSON.stringify({
  "user": {
    "id": {
      "value": "user_2"
    },
    "name": {
      "value": "John Smith"
    },
    "email": {
      "value": "john.smith@mail.com"
    },
    "country": {
      "value": "US",
      "allow_modify": true
    }
  },
  "settings": {
    "project_id": 16184,
    "currency": "USD",
    "language": "en",
    "ui": {
      "size": "medium",
      "desktop": {
        "virtual_item_list": {
          "layout": "list",
          "button_with_price": true
        }
      },
      "components": {
        "virtual_currency": {
          "custom_amount": true
        }
      }
    }
  },
  "purchase": {
    "virtual_currency": {
      "quantity": 100
    },
    "virtual_items": {
      "items": [
        {
          "sku": "SKU01",
          "amount": 1
        }
      ]
    }
  }
});

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

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

xhr.open("POST", "https://api.xsolla.com/merchant/v2/merchants/{merchant_id}/token");
xhr.setRequestHeader("content-type", "application/json");
xhr.setRequestHeader("authorization", "Basic <your_authorization_basic_key>");

xhr.send(data);
响应
{
  "token": "eop57k1boA7nnYPtewZ6KEXJyJADEwRT"
}
{
  "token": "eop57k1boA7nnYPtewZ6KEXJyJADEwRT"
}
{
  "token": "eop57k1boA7nnYPtewZ6KEXJyJADEwRT"
}
{
  "token": "eop57k1boA7nnYPtewZ6KEXJyJADEwRT"
}
{
  "token": "eop57k1boA7nnYPtewZ6KEXJyJADEwRT"
}
{
  "token": "eop57k1boA7nnYPtewZ6KEXJyJADEwRT"
}
{
  "token": "eop57k1boA7nnYPtewZ6KEXJyJADEwRT"
}
{
  "token": "eop57k1boA7nnYPtewZ6KEXJyJADEwRT"
}

其他参数列表

您可以在令牌的custom_parameters对象中传递其他参数以配置反欺诈筛选器。下表列出了一些推荐参数。您可以根据需要扩展该列表。

请参阅高级诀窍

参数 类型 描述
registration_date
string 帐户创建日期(按照ISO 8601格式)。
total_hours
integer 游戏总时数。
total_characters
integer 游戏角色数。
social_networks_added
boolean 玩家是否有关联的社交媒体帐户资料。
profile_image_added
boolean 玩家是否上传了简介头像。
active_date
string 上一次出现日期(按照ISO 8601格式)。
total_friends
integer 好友数。
additional_verification
boolean 玩家是否使用了帐户验证流程。
win_rate
integer 赢率。
last_change_password_date
string 上一次密码更改日期(按照ISO 8601格式)。
chat_activity
boolean 玩家是否使用了聊天功能。
forum_activity
boolean 玩家是否使用了论坛功能。
total_bans
integer 玩家在聊天/论坛中被禁言的次数。
profile_completed
boolean 玩家在帐户资料中是否添加了其它信息。
notifications_enabled
boolean 玩家是否启用了通知。
user_level
integer 玩家的等级、口碑或排名。
karma_points
integer 玩家的贡献/业力。
total_sum
float 付款总额。
non_premium_currency
float 非高级货币数量。
total_game_events
integer 玩家参与的游戏事件数。
total_gifts
integer 玩家发出/收到的游戏礼物数。
tutorial_completed
boolean 玩家是否完成了游戏教程。
completed_tasks
integer 完成的任务/目标数。
items_used
boolean 玩家是否使用了购买的游戏装备。
pvp_activity
boolean 玩家是否参与了玩家对战。
total_clans
integer 玩家所属的家族数。
unlocked_achievements
integer 未解锁的通关数。
total_inventory_value
float 库存总值(以游戏货币为单位)。
character_customized
boolean 玩家是否对角色进行了自定义。
session_time
string 平均会话时间(按照ISO 8601格式)。

Webhooks

概览

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

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

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

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

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

您这一端操作的示例:

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

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

请注意,数据库中不得同时包含两个具有相同 ID 的成功交易。如果系统再次发送的 webhook 的 ID 在数据库中已存在,则监听器应返回上次请求的处理结果。请勿再向用户提供购买产品或在数据库中创建重复记录。

Webhook 服务不会假设监听器将收到所有 webhook。由于 Internet 并不是 100% 可靠,webhook 可能会丢失或延迟。为解决这些问题,webhook 服务包括一种以不同间隔重新发送消息,直到监听器确认接收到消息的重试机制。最长可以在发送原始 webhook 的十二小时后重新发送 webhook。最大重试次数为 12。

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

请求签名

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

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

Copy
Full 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检查过程中被拒绝时发送。
create_subscription 用户创建订阅时发送。
update_subscription 订阅发生续订或更改时发送。
cancel_subscription 取消订阅时发送。
get_pincode 在艾克索拉API需要获取游戏密钥时发送。
user_balance_operation 用户余额发生变化时发送(操作类型以operation_type形式发送)。
redeem_key 用户激活密钥时发送。
upgrade_refund 取消升级时发送。
inventory_get 从游戏物品库获取物品列表发送到二级市场。
inventory_pull 从游戏物品库提取物品到二级市场。
inventory_push 从二级市场将物品放入游戏物品库。

用户验证

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

参数 类型 描述
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
php
  • php
  • http
  • curl
请求
<?php

$request = array(
    'notification_type' => 'user_validation',
    '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",
    "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",
    "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 通知类型。 必需
user
object 带用户相关数据的对象。 必需
user.public_id
string 公共用户 ID。
user.id
string 用户ID。
Copy
Full screen
php
  • php
  • http
  • curl
请求
<?php

$request = array(
    'notification_type' => 'user_search',
    '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",
    "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",
    "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 通知类型。 必需
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
integer 购买金额。
purchase.pin_codes
object 游戏密钥(数组)。
purchase.pin_codes.digital_content
string 在发布商帐户中设置的游戏SKU。
purchase.pin_codes.drm
string 用于分发游戏的 DRM 平台。可以是'steam'、'playstation'、'xbox'、'uplay'、'origin'或'drmfree'。请确保您已在“发布商帐户”中配置所需的 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.dry_run
integer 测试交易:1 - 测试/ 0 - 实际。如为测试交易,值为1,否则值为0。
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.repatriation_commission
object 包含汇回本国费用数据的对象,该费用是第三方对艾克索拉收取的费用。
payment_details.repatriation_commission.currency
string 汇回本国费用币种。参照ISO 4217标准的三字母货币代码。
payment_details.repatriation_commission.amount
float 汇回本国费用金额。
custom_parameters
object 您的自定义参数。
Copy
Full screen
php
  • php
  • http
  • curl
请求
<?php

$request = array(
    'notification_type' => 'payment',
    '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
    ),
    'payment_details' => array(
        'payment' => array(
            'currency' => 'USD',
            'amount' => 9.99
        ),
        'vat' => array(
            'currency' => 'USD',
            'amount' => 0
        ),
        '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",
    "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,
        "dry_run":1,
        "agreement":1
    },
    "payment_details":{
        "payment":{
            "currency":"USD",
            "amount":230
        },
        "vat": {
            "currency": "USD",
            "amount": 0
        },
        "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",
    "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,
        "dry_run":1,
        "agreement":1
    },
    "payment_details":{
        "payment":{
            "currency":"USD",
            "amount":230
        },
        "vat": {
            "currency": "USD",
            "amount": 0
        },
        "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 通知类型。 必需
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
integer 购买金额。
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 - 测试/ 0 - 实际。如为测试交易,值为1,否则值为0。
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.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. Chargeback. 用于交易存在退单的情况。
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
php
  • php
  • http
  • curl
请求
<?php

$request = array(
    'notification_type' => 'refund',
    '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
        ),
        '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",
    "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":{
        "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",
        "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":{
            "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 通知类型。 必需
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
php
  • php
  • http
  • curl
请求
<?php

$request = array (
  'notification_type' => 'upgrade_refund',
  '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",
  "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",
  "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 通知类型。 必需
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 - 测试/ 0 - 实际。如为测试交易,值为1,否则值为0。
transaction.agreement
integer 协议 ID。
refund_details
object 退款详情(对象)。
refund_details.code
integer 代码ID。
refund_details.reason
string 退款原因。
refund_details.author
string 退款申請人。
Copy
Full screen
php
  • php
  • http
  • curl
请求
<?php

$request = array(
    'notification_type' => 'afs_reject',
    '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",
    "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",
  "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

已创建订阅

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

参数 类型 描述
notification_type
string 通知类型。 必需
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.
Copy
Full screen
php
  • php
  • http
  • curl
请求
<?php

$request = array(
    'notification_type' => 'create_subscription',
    '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",
    "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",
        "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 通知类型。 必需
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
php
  • php
  • http
  • curl
请求
<?php

$request = array(
    'notification_type' => 'update_subscription',
    '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",
    "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",
        "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 通知类型。 必需
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
php
  • php
  • http
  • curl
请求
<?php

$request = array(
    'notification_type' => 'cancel_subscription',
    '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",
    "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",
        "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

获取游戏密钥

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

参数 类型 描述
notification_type
string 通知类型。
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
php
  • php
  • http
  • curl
请求
<?php

$request = array (
       'notification_type' => 'get_pincode',
       '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",
    "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",
        "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 通知类型。
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
php
  • php
  • http
  • curl
请求
<?php
$request = array(
    'notification_type' => 'redeem_key',
    '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",
  "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",
  "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。
Copy
Full 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 通知类型。
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
php
  • php
  • http
  • curl
请求
<?php

$request = array(
    '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

{
    "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 '{
        "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 通知类型。
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
php
  • php
  • http
  • curl
请求
<?php

$request = array(
    '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

{
    "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 '{
        "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 通知类型。
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
php
  • php
  • http
  • curl
请求
<?php

$request = array(
    '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

{
    "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 '{
        "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 通知类型。
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
php
  • php
  • http
  • curl
请求
<?php

$request = array(
    '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

{
    "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 '{
        "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 通知类型。
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
php
  • php
  • http
  • curl
请求
<?php

$request = array(
     '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

{
    "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 '{
        "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 URL发送通知。

参数 类型 描述
notification_type
string 通知类型。
project_id
integer 项目ID。
payload
object 包含用户和二级市场数据的对象。
payload.user
object 包含用户数据的对象。
payload.user.id
string 用户ID。
payload.secondary_market
object 包含二级市场数据的对象。
payload.secondary_market.id
string 二级市场ID。
Copy
Full screen
php
  • php
  • http
  • curl
请求
<?php

$request = array(
 'notification_type' => 'inventory_get',
 'project_id' => 1024,
 'payload' => array(
   'user' => array(
     'id' => 'username'
   ),
   'secondary_market' => array(
     'id' => '1'
   ),
 ),
);
POST /your_uri HTTP/1.1
Host: your.host
Content-Type: application/json
Authorization: Signature sha1(body + project_secret)

{
    "notification_type": "inventory_get",
    "project_id": 1024,
    "payload": {
         "user": {
             "id": "username"
              },
          "secondary_market": {
              "id": "1"
          }
     }  
}
$ curl -v 'https://your.hostname/your/uri' \
-X POST \
-u merchant_id:merchant_api_key \
-H 'Content-Type: application/json' \
-d '{
    "notification_type": "inventory_get",
    "project_id": 1024,
    "payload": {
         "user": {
             "id": "username"
          },
          "secondary_market": {
              "id": "1"
          }
     }  
}
响应
<?php

$response = array(
 'user' => array(
  'id' => 'username'
  ),
  'items' => array(
   array(
    'sku' => 'sku1',
    'instance_id' => 'instance1'
    ),
    array(
     'sku' => 'sku2',
     'instance_id' => 'instance2'
    ),
  ),
)
HTTP/1.1 204

{
    "user": {
        "id": "username"
    },
    "items": [
        {
            "sku": "sku1",
            "instance_id": “instance1”
        },
        {
            "sku": "sku2",
            "instance_id": “instance2”
        }
    ],
}
{
    "user": {
        "id": "username"
    },
    "items": [
        {
        "sku": "sku1",
        "instance_id": "instance1"
        },
        {
        "sku": "sku2",
        "instance_id": "instance2"
        }
    ],
}

二级市场:提取游戏物品

二级市场请求提取游戏物品库中的物品时,艾克索拉会向您的Webhook URL发送通知。

参数 类型 描述
notification_type
string 通知类型。
project_id
integer 项目ID。
payload
object 包含用户和二级市场数据的对象。
payload.user
object 包含用户数据的对象。
payload.user.id
string 用户ID。
items
array 包含物品数据的数组。
items.sku
string 物品SKU。
items.instance_id
string 游戏中的唯一物品ID。
payload.secondary_market
object 包含二级市场数据的对象。
payload.secondary_market.id
string 二级市场ID。
Copy
Full screen
php
  • php
  • http
  • curl
请求
<?php

$request = array(
  'notification_type' => 'inventory_pull',
  'project_id' => 1024,
  'payload' => array(
    'user' => array(
      'id' => 'username'
    ),
    'items' => array(
      array(
        'sku' => 'sku1',
        'instance_id' => 'instance1'
      ),
      array(
        'sku' => 'sku2',
        'instance_id' => 'instance2'
      ),
    )
    'secondary_market' => array(
      'id' => '1'
    ),
  ),
);
POST /your_uri HTTP/1.1
Host: your.host
Content-Type: application/json
Authorization: Signature sha1(body + project_secret)

{
    "notification_type": "inventory_pull",
    "project_id": 1024,
    "payload": {
        "user": {
            "id": "username"
        },
        "items": [
            {
                "sku": "sku1",
                "instance_id": "instance1"
            },
            {
                "sku": "sku2",
                "instance_id": "instance2"
            },
        ],
        "secondary_market": {
            "id": "1"
        }
    }
}
$ curl -v 'https://your.hostname/your/uri' \
-X POST \
-u merchant_id:merchant_api_key \
-H 'Content-Type: application/json' \
-d '{
    "notification_type": "inventory_pull",
    "project_id": 1024,
    "payload": {
         "user": {
             "id": "username"
              },
         "items": [
            {
                "sku": "sku1",
                "instance_id": "instance1"
            },
            {
                "sku": "sku2",
                "instance_id": "instance2"
            }
          ],
          "secondary_market": {
              "id": "1"
          }
     }  
}
响应
<?php

$response = null;
HTTP/1.1 204 No Content

二级市场:放入游戏物品

二级市场将物品放入游戏物品库时,艾克索拉会向您的Webhook URL发送通知。

参数 类型 描述
notification_type
string 通知类型。
project_id
integer 项目ID。
payload
object 包含用户和二级市场数据的对象。
payload.user
object 包含用户数据的对象。
payload.user.id
string 用户ID。
items
array 包含物品数据的数组。
items.sku
string 物品SKU。
items.instance_id
string 游戏中的唯一物品ID。
payload.secondary_market
object 包含二级市场数据的对象。
payload.secondary_market.id
string 二级市场ID。
Copy
Full screen
php
  • php
  • http
  • curl
请求
<?php

$request = array(
  'notification_type' => 'inventory_push',
  'project_id' => 1024,
  'payload' => array(
    'user' => array(
      'id' => 'username'
    )
    'items' => array(
      array(
        'sku' => 'sku1',
        'instance_id' => 'instance1'
      ),
      array(
        'sku' => 'sku2',
        'instance_id' => 'instance2'
      ),
    ),
    'secondary_market' => array(
      'id' => '1'
    ),
  ),
);
POST /your_uri HTTP/1.1
Host: your.host
Content-Type: application/json
Authorization: Signature sha1(body + project_secret)

{
    "notification_type": "inventory_push",
    "project_id": 1024,
    "payload": {
        "user": {
            "id": "username"
        },
        "items": [
            {
                "sku": "sku1",
                "instance_id": "instance1"
            },
            {
                "sku": "sku2",
                "instance_id": "instance2"
            }
        ],
        "secondary_market": {
            "id": "1"
        }
    }
}
$ curl -v 'https://your.hostname/your/uri' \
-X POST \
-u merchant_id:merchant_api_key \
-H 'Content-Type: application/json' \
-d '{
    "notification_type": "inventory_push",
    "project_id": 1024,
    "payload": {
         "user": {
             "id": "username"
              },
          "items": [
              {
                  "sku": "sku1",
                  "instance_id": "instance1"
              },
              {
                  "sku": "sku2",
                  "instance_id": "instance2"
              }
          ],
          "secondary_market": {
               "id": "1"
          }
     }  
}
响应
<?php

$response = null;
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"
    }
}