The following documentation was deprecated. Current version is available at developers.xsolla.com
CURL
HTTP
PHP
JS

简介

Xsolla API 是基于REST组建起来的。我们的 API 拥有面向资源的可预测 URL,可以使用 HTTP 响应代码指示 API 错误。

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

JSON 将在来自 API 的所有响应中返回,包括错误。

端点路径

Xsolla API 端点在基本 URL https://api.xsolla.com 中托管。 例如,List Projects端点的完整路径为 https://api.xsolla.com/merchant/v2/merchants/{merchant_id}/projects

大多数端点路径都包括一个 merchant_id 参数,该参数指示应用程序正在代表哪个商户。

API 端点

https://api.xsolla.com
https://api.xsolla.com
https://api.xsolla.com

请求和响应

对 Xsolla API 端点的请求必须包括以下 HTTP 头:Authorization, Accept

POST 和 PUT 请求必须包括另外一个头: Content-Type: application/json

默认情况下,所有的端点响应在响应正文中都以 JSON 格式提供数据并包括一个 Content-Type: application/json 头。

Authorization: Basic AUTHORIZATION_BASE64_ENCODED_STRING
Accept: application/json
Content-Type: application/json
Authorization: Basic AUTHORIZATION_BASE64_ENCODED_STRING
Accept: application/json
Content-Type: application/json
Authorization: Basic AUTHORIZATION_BASE64_ENCODED_STRING
Accept: application/json
Content-Type: application/json

API 变更

Xsolla 可能使用此 API 更改功能:

  • Xsolla可能添加新的 API 资源;

  • Xsolla 可能添加可选的请求参数;

  • Xsolla 可能向现有 API 响应添加新属性;

  • Xsolla 可能向已枚举值集合的现有参数添加新值;

  • Xsolla 可能添加新的 webhook 类型并将新参数添加到 JSON;

  • Xsolla 可能添加可选的 HTTP 请求头部;

  • Xsolla 可能拒绝任何有效参数包含无效参数值的请求;

  • 如解析逻辑被更正,则由于过度宽松的解析而被接受的不正确请求可能被拒绝

  • Xsolla 可能随时添加、更改或删除未记录的功能。

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

版本控制

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

如果首次使用API,请使用最新版本。如果忽略了版本,我们将默认使用第一个版本。请注意,我们只保证同一版本中的API完整性。

身份验证

Xsolla 采用 HTTP Basic Authentication。 提供您的商户 ID 作为基本身份验证用户名,并提供 API 键值(可在 Xsolla 商户 中的'设置'页面上找到)作为密码。

所有 API 请求必须通过 HTTPS 发送。通过普通 HTTP 调用将会失败。

必须针对所有请求进行身份验证。

请注意,您使用的TLS需要大于等于1.2,才能连接至API接口。

示例

<?php

use Xsolla\SDK\API\XsollaClient;

$xsollaClient = XsollaClient::factory(array(
    'merchant_id' => MERCHANT_ID,
    'api_key' => API_KEY
));
GET /merchant/v2/merchants/{merchant_id}/events/messages HTTP/1.1
User-Agent: xsolla-api-client/1.0
Host: api.xsolla.com
Accept: application/json
Authorization: Basic ZGVtb0B4c29sbGEuY29tOmRlbW8=
Content-Type: application/json
$ curl -v 'https://api.xsolla.com/merchant/v2/merchants/{merchant_id}/events/messages' \
-X GET \
-u merchant_id:merchant_api_key

端点类型

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

操作 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参数

向下一个 URL 发送后续请求(包括所有通常头)以提取下一组结果。重复此过程,直到接收到不含下一个 URL 的响应。

错误处理

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

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

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

名称 类型 描述
http_status_code
int HTTP代码
message
string 可读的错误描述信息。此信息始终是英文。对一些特定错误的说明,今后有可能会改变。
extended_message
string 错误的详细描述。
request_id
string 请求的唯一 ID,用于帮助我们诊断问题。

受支持的 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 - 发生错误。

令牌

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

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

参数 类型 描述
user
object 带有用户相关数据的对象。
user.id
object 带有用户 ID 相关数据的对象。必要。
user.id.value
string 用户 ID。
user.id.hidden
boolean 是否可以在支付 UI 上隐藏此元素。默认值为'True'。
user.id.allow_modify
boolean 用户是否可以修改支付 UI 上的字段。默认值为'False'。
user.name
object 带有用户昵称相关数据的对象。
user.name.value
string 用户昵称。
user.name.hidden
boolean 是否可以在支付 UI 上隐藏此元素。默认值为'True'。
user.name.allow_modify
boolean 用户是否可以修改支付 UI 上的字段。默认值为'False'。
user.email
object 带有用户电子邮件相关数据的对象。
user.email.value
string 用户电子邮件。
user.email.hidden
boolean 是否可以在支付 UI 上隐藏此元素。默认值为'True'。
user.email.allow_modify
boolean 用户是否可以修改支付 UI 上的字段。默认值为'False'。
user.country
object 带有用户所在的国家/地区相关数据的对象。
user.country.value
string 用户所在的国家/地区。使用 ISO 3166-1 alpha-2 standard标准规定的 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 该活动的实质。
settings
object 带有自定义项目设置的对象。
settings.external_id
string 交易的外部 ID。
settings.project_id
int Xsolla 系统中的游戏标识符。可以在 商户 中找到该标识符。必要。
settings.language
string 界面语言。符合 ISO 639-1 standard 标准规定的 2 字母语言代码。
settings.return_url
string 用户会在支付过后被重定向到此页面。参数"user_id", "foreinginvoice", "invoice_id"和"status"会被自动添加到此链接。
settings.currency
string 首选支付币种。使用ISO 4217标准规定的三字母组合表示币种。
settings.mode
string 设置'沙盒'值以测试支付流程。请注意,支付 UI 的 URL 将是 https://sandbox-secure.xsolla.com。
settings.payment_method
int 支付方法的 ID。
settings.payment_widget
string 支付小部件。可以是 'paybycash' 或 'giftcard' 。 如果参数已设置,用户将分别重定向到 Pay by Cash 或 Gift Cards 小部件。
settings.ui
object 带有界面设置相关数据的对象。
settings.ui.size
string 支付 UI 的大小。此参数可拥有以下值之一,具体取决于 支付 UI 的所需大小::
  • small: 支付 UI 支持的最小尺寸。当窗口大小严格受限时,请使用此值(尺寸:620 x 630
  • medium:支付 UI 的推荐大小。使用此值可以在灯箱中显示支付 UI(尺寸:740 x 760
  • large:在新窗口或者选项卡中显示支付 UI 的最佳大小(尺寸:820 x 840
settings.ui.theme
string 支付 UI 的外观主题。可以是'default'(默认值)或'dark'。
settings.ui.version
string 设备的类型。可以是'desktop'(默认值)或'mobile'。
settings.ui.desktop
object 带有对桌面版本有效的界面设置相关数据的对象。
settings.ui.desktop.header
object 带有标题设置相关数据的对象。
settings.ui.desktop.header.is_visible
boolean 标题在支付 UI 上是否可见。
settings.ui.desktop.header.visible_logo boolean 如果为 true,标题中将显示徽标(首先请把徽标文件提供给负责人)。
settings.ui.desktop.header.visible_name
boolean 标题中是否显示项目名称。
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_items_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)。
settings.ui.mobile.footer.is_visible
boolean 是否在移动版本的支付 UI 中隐藏或显示脚注。
settings.ui.license_url
string EULA 的链接。
settings.ui.components
object 带有模块菜单设置相关数据的对象。
settings.ui.components.virtual_items
object 带有虚拟物品模块设置相关数据的对象。
settings.ui.components.virtual_items.order
int 虚拟物品在模块菜单中的排列顺序。
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
int 虚拟货币在模块菜单中的排列顺序。
settings.ui.components.virtual_currency.hidden
boolean 虚拟货币在模块菜单中是否可见。
settings.ui.components.subscriptions
object 带有订阅模块设置相关数据的对象。
settings.ui.components.subscriptions.order
int 模块菜单中订阅的排列顺序。
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
int “我的帐户”页面在菜单中的位置。
settings.ui.user_account.info.enable
boolean 在菜单中显示还是隐藏“我的帐户”页面。
settings.ui.user_account.history
object 用户的“历史记录”页面。
settings.ui.user_account.history.order
int “历史记录”页面在菜单中的位置。
settings.ui.user_account.history.enable
boolean 在菜单中显示还是隐藏“历史记录”页面。
settings.ui.user_account.payment_accounts
object “我的支付帐户”页面。
settings.ui.user_account.payment_accounts.order
int “我的支付帐户”页面在菜单中的位置。
settings.ui.user_account.payment_accounts.enable
boolean 在菜单中显示还是隐藏“我的支付帐户”页面。
settings.ui.user_account.subscriptions
object “管理订阅”页面。
settings.ui.user_account.subscriptions.order
int “管理订阅”页面在菜单中的位置。
settings.ui.user_account.subscriptions.enable
boolean 在菜单中显示还是隐藏“管理订阅”页面。
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
int 物品数量。
purchase.virtual_items.available_groups
array 带有物品组 ID 的数组。支付 UI 中将仅显示指定组的物品。
purchase.subscription
object 带有订阅相关数据的对象。
purchase.subscription.plan_id
string 计划 ID。
purchase.subscription.product_id
string 产品 ID。
purchase.subscription.currency
string 购买计划的货币, 以此币种进行所有计算。
purchase.subscription.available_plans
string 包含订阅套餐相关数据的数组。只有这些套餐会显示在支付用户界面中。
purchase.subscription.trial_days
int 按天计的试用期。仅当创建订阅时使用并且仅用于未定义试用期的计划。
purchase.pin_codes
object 带有 PIN 码相关数据的对象。
purchase.pin_codes.currency
string 购买 PIN 码的币种,以此币种进行所有计算。
purchase.pin_codes.codes
array 带有 PIN 码相关数据的数组。
purchase.pin_codes.codes.digital_content
string 在“商户帐户”中设置的游戏的 SKU。
purchase.pin_codes.codes.drm
string 游戏应对其可用的 DRM。可以是“steam”、“playstation”、“xbox”、“uplay”、“origin”或“drmfree”。请确保您已在“商户帐户”中配置所需的 DRM。如果此参数未在令牌中传递,用户可以在支付接口中选择 DRM。
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 收礼人邮箱。
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" ] } } }

请求

<?php

use Xsolla\SDK\API\XsollaClient;
use Xsolla\SDK\API\PaymentUI\TokenRequest;

$tokenRequest = new TokenRequest($projectId, $userId);
$tokenRequest->setUserEmail('email@example.com')
    ->setExternalPaymentId('12345')
    ->setSandboxMode(true)
    ->setUserName('USER_NAME')
    ->setCustomParameters(array('key1' => 'value1', 'key2' => 'value2'));

$xsollaClient = XsollaClient::factory(array(
    'merchant_id' => MERCHANT_ID,
    'api_key' => API_KEY
));
$token = $xsollaClient->createPaymentUITokenFromRequest($tokenRequest);
POST /merchant/v2/merchants/{merchant_id}/token HTTP/1.1
Host: api.xsolla.com
Accept: application/json
Authorization: Basic ZGVtb0B4c29sbGEuY29tOmRlbW8=
Content-Type: application/json

{
  "user": {
          "id": {
              "value": "1234567",
              "hidden": true
          },
          "email": {
              "value": "email@example.com",
              "allow_modify": true,
              "hidden": false
          },
          "country": {
              "value": "US"
          }
      },
      "settings": {
          "project_id": 14004,
          "language":"en",
          "currency":"USD",
          "ui": {
              "size":"medium"
          }
      },
      "purchase": {
          "virtual_currency": {
              "quantity": 100
          },
          "virtual_items": {
              "items": [{
                  "sku":"SKU01",
                  "amount":1
              }]
          },
          "description": {
              "value": "Test Purchase"
          }
      },
      "custom_parameters": {
          "parameter1": "value1"
      }
}
$ curl -v 'https://api.xsolla.com/merchant/v2/merchants/{merchant_id}/token' \
-X POST \
-u merchant_id:merchant_api_key \
-H 'Content-Type: application/json' \
-H 'Accept: application/json' \
-d '{
  "user": {
      "id": {
          "value": "1234567",
          "hidden": true
      },
      "email": {
          "value": "email@example.com",
          "allow_modify": true,
          "hidden": false
      },
      "country": {
          "value": "US"
      }
  },
  "settings": {
      "project_id": 14004,
      "language":"en",
      "currency":"USD",
      "ui": {
          "size":"medium"
      }
  },
  "purchase": {
      "virtual_currency": {
          "quantity": 100
      },
      "virtual_items": {
          "items": [{
              "sku":"SKU01",
              "amount":1
          }]
      },
      "description": {
          "value": "Test Purchase"
      }
  },
  "custom_parameters": {
      "parameter1": "value1"
  }
    }'

响应

<?php

// example response
$token = 'uV0iCEvWkUGVqWerTgbrndWePOMiLAfO';
HTTP/1.1 200 OK
Content-Type: application/json

{
    "token": "uV0iCEvWkUGVqWerTgbrndWePOMiLAfO"
}
{
    "token": "uV0iCEvWkUGVqWerTgbrndWePOMiLAfO"
}

列出其他参数

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

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

Pay Station UI

Xsolla 团队还创建了一个脚本,用于简化将支付接口集成到您的网站的流程。脚本位于我们的 CDN 上,点击此处可以获取。 使用此 URL 将脚本集成到您的网站中。更多信息,请访问 Github 上的存储库。

用于脚本初始化的参数列表:

参数 类型 描述
access_token
string Pay Station 令牌,由 API 接收。 Required.
sandbox
boolean 设置为 true 以测试支付流程,将使用 sandbox-secure.xsolla.com 而不是 secure.xsolla.com。
lightbox
object 带有选项列表的对象,可用于打开 lightbox(桌面版本)。
lightbox.width
string lightbox 框架的宽度。如果为空,则取决于 Pay Station 的宽度。默认值为空。
lightbox.height
string lightbox 框架的高度。如果为空,则取决于 Pay Station 的高度。默认值为'100%'。
lightbox.zIndex
int 控制垂直堆叠顺序的属性,默认值为 1000。
lightbox.overlayOpacity
int 叠加的不透明度(从 0 到 1),默认值为'0.6'。
lightbox.overlayBackground
string 叠加的背景,默认值为'#000000'。
lightbox.modal
boolean lightbox 框架不可关闭,默认值为'False'。
lightbox.closeByClick
boolean 切换单击叠加关闭 lightbox,默认值为'true'。
lightbox.closeByKeyboard
boolean 切换按ESC键关闭 lightbox,默认值为'true'。
lightbox.contentBackground
string 框架的背景,默认值为'#ffffff'。
lightbox.contentMargin
string 框架页边,默认值为'10px'。
lightbox.spinner
string 旋转加载动画的类型,可以是'xsolla'或'round',默认值为'xsolla'。
lightbox.spinnerColor
string 旋转加载动画的颜色,非默认设置。
childWindow
object 针对包含 Pay Station 的子窗口的选项。适用于移动版本。
childWindow.target
string 目标选项指定在何处打开 Pay Station 窗口,可以是'_blank'、'_self'、'_parent',默认值为'_blank'。

脚本使您可以跟踪支付接口发生的事件。根据事件的类型,可以在网页上执行各种操作。

事件列表:

参数 描述
init
小部件初始化事件。
open
打开小部件时的事件。
load
加载支付接口 (Pay Station) 之后的事件。
close
关闭支付接口 (Pay Station) 之后的事件。
status
用户在状态页面上移动时的事件。
status-invoice
用户在状态页面上移动但支付尚未完成时的事件。
status-delivering
用户在状态页面上移动,支付完成以及我们正在发送支付通知时的事件。
status-done
用户在状态页面上移动且支付已成功完成时的事件。
status-troubled
用户在状态页面上移动但支付失败时的事件。

如果您想要自行初始化打开支付 UI,使用链接 https://secure.xsolla.com/paystation2/?access_token=ACCESS_TOKEN 即可,其中 ACCESS_TOKEN上一步接收到的令牌。

通过回调进行异步脚本加载的示例

<html>
<head lang="en">
    <meta charset="UTF-8">
</head>
<body>
    <button data-xpaystation-widget-open>Buy Credits</button>

    <?php \Xsolla\SDK\API\PaymentUI\PaymentUIScriptRenderer::send($paymentUIToken, $isSandbox = true); ?>
</body>
</html>
<script>
    var options = {
        access_token: 'abcdef1234567890abcdef1234567890'
    };
    var s = document.createElement('script');
    s.type = "text/javascript";
    s.async = true;
    s.src = "https://static.xsolla.com/embed/paystation/1.0.7/widget.min.js";
    s.addEventListener('load', function (e) {
        XPayStationWidget.init(options);
    }, false);
    var head = document.getElementsByTagName('head')[0];
    head.appendChild(s);
</script>

<button data-xpaystation-widget-open>Buy Credits</button>

测试信用卡的列表

在沙盒中,您可以使用下列信用卡模拟成功的支付:

卡号 过期日期 信用卡安全码 3D 安全 卡片类型
4111111111111111
12/20 123 No VISA
5555555555554444
11/19 321 No MasterCard
4000000000000010
12/20 123 Yes VISA
5200000000000114
11/19 321 Yes MasterCard
6759649826438453
12/25 321 Yes Maestro

此外,您还可以使用下列数据模拟被拒绝的交易:

卡号 过期日期 信用卡安全码 3D 安全 卡片类型 描述
4000000000000002
12/20 123 No VISA 资金不足
5200000000000007
11/19 321 No MasterCard 资金不足
4000000000000036
12/20 123 Yes VISA 拒绝
5200000000000031
11/19 321 Yes MasterCard 拒绝

Pay2Play 小组件

Xsolla 团队创建了一个 Pay2Play 小组件,用于简化将支付接口集成到您的网站的流程。小组件可以轻松嵌入到您的页面中,将为用户提供内容销售、可用 DRM 与平台列表,以及支付方式选择的详细信息。

脚本位于我们的 CDN 上,单击此处可以获取。使用此 URL 可以将脚本集成到您的网站上。

更多信息,请访问 Github 上的存储库

要使用 Pay2Play 服务,可以通过两种方式与 Xsolla 互动:

  1. 简单集成
  2. 高级集成

有关两种方式之间区别的信息,请参见集成指南 各个小组件初始化参数有所不同,具体取决于选定的互动方式。

简单集成

用于脚本初始化的参数列表:

参数 类型 描述
access_data
string 带有用户和支付相关数据的对象。必要。
target_element
boolean 小组件应被加载的页面元素(应使用 jQuery 选择器,例如“#widget-example”)。必要

对象 access_data 中的参数和 JSON 结构与用于获取令牌的参数和 JSON 结构类似。

高级集成

用于脚本初始化的参数列表:

参数 类型 描述
access_token
string 小组件的令牌,由 api接收。必要。
sandbox
boolean 设为 true 可以测试支付流程,将使用 sandbox-secure.xsolla.com,而不是 secure.xsolla.com。
target_element
boolean 页面的元素,应对小组件进行渲染的位置(应使用 jQuery 选择器,例如“#widget-example”)。必要

下列参数定义支付接口外观,并与 Xsolla Pay Station 小组件参数一致。

参数 类型 描述
lightbox
object 带有选项列表的对象,可用于 lightbox 开放(在桌面版本中)。
lightbox.width
string lightbox 框架的宽度。如果为空,则取决于 Pay Station 宽度。lightbox 框架的宽度。如果为空,则取决于 Pay Station 宽度。
lightbox.height
string lightbox 框架的高度。如果为空,则取决于 Pay Station 高度。默认值为“100%”。
lightbox.zIndex
int 控制垂直堆叠顺序的属性,默认值为 1000。
lightbox.overlayOpacity
int 叠加的不透明度(从 0 到 1),默认值为“.6”。
lightbox.overlayBackground
string 叠加的背景,默认值为“#000000”。
lightbox.modal
boolean lightbox 框架不可关闭,默认值为“false”。
lightbox.closeByClick
boolean 切换单击叠加是否应关闭 lightbox,默认值为“true”。
lightbox.closeByKeyboard
boolean 切换按 ESC 键是否应关闭 lightbox,默认值为“true”
lightbox.contentBackground
string 框架的背景,默认值为“#ffffff”。
lightbox.contentMargin
string 框架页边,默认值为“10px”。
lightbox.spinner
string 旋转加载动画的类型,可以是“xsolla”或“round”,默认值为“xsolla”。
lightbox.spinnerColor
string 旋转加载动画的颜色,非默认设置。
childWindow
object 针对包含 Pay Station 的子窗口的选项。适合移动版本。
childWindow.target
string 指定在何处打开 Pay Station 窗口的目标选项,可以是“_blank”、“_self”、“_parent”,默认值为“_blank”。

需要在 DOM 完全加载之后执行 XPay2PlayWidget.create() 。您可以跟踪相应事件,或者在加载小组件的页面元素后面添加脚本。

异步脚本加载示例(带简单集成 callback)

<script>
    var accessData = {"settings":{"project_id":14004},"purchase":{"pin_codes":{"codes":[{"digital_content":"game_sku"}]}}};
    var options = {
        access_data: accessData,
        target_element: '#widget-example-element'
    };
    var s = document.createElement('script');
    s.type = "text/javascript";
    s.async = true;
    s.src = "//static.xsolla.com/embed/pay2play/2.1.0/widget.min.js";
    s.addEventListener('load', function (e) {
        var widgetInstance = XPay2PlayWidget.create(options);
    }, false);
    var head = document.getElementsByTagName('head')[0];
    head.appendChild(s);
</script>
<script>
    var accessData = {"settings":{"project_id":14004},"purchase":{"pin_codes":{"codes":[{"digital_content":"game_sku"}]}}};
    var options = {
        access_data: accessData,
        target_element: '#widget-example-element'
    };
    var s = document.createElement('script');
    s.type = "text/javascript";
    s.async = true;
    s.src = "//static.xsolla.com/embed/pay2play/2.1.0/widget.min.js";
    s.addEventListener('load', function (e) {
        var widgetInstance = XPay2PlayWidget.create(options);
    }, false);
    var head = document.getElementsByTagName('head')[0];
    head.appendChild(s);
</script>

异步脚本加载示例(带高级集成 callback)

<script>
    var options = {
        access_token: 'abcdef1234567890abcdef1234567890',
        target_element: '#widget-example-element'
    };
    var s = document.createElement('script');
    s.type = "text/javascript";
    s.async = true;
    s.src = "//static.xsolla.com/embed/pay2play/2.1.0/widget.min.js";
    s.addEventListener('load', function (e) {
        var widgetInstance = XPay2PlayWidget.create(options);
    }, false);
    var head = document.getElementsByTagName('head')[0];
    head.appendChild(s);
</script>
<script>
    var options = {
        access_token: 'abcdef1234567890abcdef1234567890',
        target_element: '#widget-example-element'
    };
    var s = document.createElement('script');
    s.type = "text/javascript";
    s.async = true;
    s.src = "//static.xsolla.com/embed/pay2play/2.1.0/widget.min.js";
    s.addEventListener('load', function (e) {
        var widgetInstance = XPay2PlayWidget.create(options);
    }, false);
    var head = document.getElementsByTagName('head')[0];
    head.appendChild(s);
</script>

错误列表

Code Description
0004-0001
令牌过期或者不正确
0004-0008
错误的 URL (正在尝试访问secure.xsolla.com 上的沙盒模式 (sandbox mode) 或者 sandbox-secure.xsolla.com 上的即时模式 (live mode))
0002-0004
未签署协议
0004-0010
已禁止无服务器集成
0010-0001
未找到数字内容
0010-0003
数字内容未配置数字版权管理(DRM)
1000-0003
该项目没有启用支付模块

Storefront 虚拟货币

列示所有虚拟货币包。

HTTP 请求

GET https://api.xsolla.com/merchant/v2/projects/{project_id}/storefront/virtual_currency

请求参数:

参数 类型 描述
project_id
int 项目 ID。必要。
user_id
string 用户 ID。必要。
currency
string 虚拟货币包的币种。使用 ISO 4217 标准规定的三字母组合表示币种。必要。
language
string 界面语言。符合 ISO 639-1 标准规定的 2 字母语言代码(小写字母)。必要。

响应参数:

参数 类型 描述
packages
array 带有虚拟货币包相关数据的对象的数组。
packages.id
int 虚拟货币包在 Xsolla 系统中的 ID。
packages.quantity
float 虚拟货币的数量。
packages.quantity_without_discount
float 虚拟货币的数量,无折扣(促销时)。
packages.bonus_quantity
float 作为奖励的虚拟货币数量(促销时)。
packages.amount
float 虚拟货币包的价格(使用请求中发送的币种表示)。
packages.amount_without_discount
float 虚拟货币包的价格,无折扣(促销时)。
packages.currency
string 虚拟货币包的币种。使用 ISO 4217 标准规定的三字母组合表示币种。
packages.image
string 包图片的 URL。
packages.description
string 虚拟货币包的描述(使用请求中发送的语言表示)。
packages.bonus_items
array 带有作为奖励的物品相关数据的数组(促销时)。
packages.bonus_items.name
string 奖励物品的名称。
packages.bonus_items.quantity
int 奖励物品的数量。
packages.advertisement_label
object 带有虚拟货币包标签相关数据的对象。
packages.advertisement_label.type
string 虚拟货币包标签的类型。可以是“recommended”、“best_deal”、“special_offer”或空。
packages.advertisement_label.name
string 虚拟货币包标签已本地化的名称,取决于 packages.advertisement_label.type 的值。
packages.offer_label
string 促销的标签。

请求

<?php

$response = $xsollaClient->GetStorefrontVirtualCurrency(array(
    'project_id' => PROJECT_ID,
    'language' => LANGUAGE_ISO,
    'currency' => CURRENCY_ISO,
    'user_id' => USER_ID
));
GET /merchant/v2/projects/{project_id}/storefront/virtual_currency HTTP/1.1
User-Agent: xsolla-api-client/1.0
Host: api.xsolla.com
Accept: application/json
Authorization:Basic ZGVtb0B4c29sbGEuY29tOmRlbW8=
Content-Type: application/json
$ curl -v 'https://api.xsolla.com/merchant/v2/projects/{project_id}/storefront/virtual_currency' \
-X GET \
-u merchant_id:merchant_api_key

响应

<?php

// 示例响应
$response = array (
    'packages' =>
        array (
            array (
                'id' => 16913,
                'quantity' => 500,
                'quantity_without_discount' => 500,
                'bonus_quantity' => 10,
                'amount' => 4,
                'amount_without_discount' => 4.99,
                'currency' => 'USD',
                'image' => '//cdn2.xsolla.com/img/misc/images/5df58528dee219c2ab48e003f8f1a8f1.jpg',
                'description' => '500 Gold',
                'bonus_items' =>
                    array (
                        array (
                            'name' => 'Rabbit',
                            'quantity' => 1,
                        ),
                    ),
                'advertisement_label' =>
                    array (
                        'type' => 'recommended',
                        'name' => 'Most Popular',
                    ),
                'offer_label' => '',
            ),
        ),
);
HTTP/1.1 200 OK
Content-Type: application/json

{
    "packages":[
        {
            "id":16913,
            "quantity":500,
            "quantity_without_discount":500,
            "bonus_quantity":10,
            "amount":4,
            "amount_without_discount":4.99,
            "currency":"USD",
            "image":"\/\/cdn2.xsolla.com\/img\/misc\/images\/5df58528dee219c2ab48e003f8f1a8f1.jpg",
            "description":"500 Gold",
            "bonus_items":[
                {
                    "name":"Rabbit",
                    "quantity":1
                }
            ],
            "advertisement_label":{
                "type":"recommended",
                "name":"Most Popular"
            },
            "offer_label":""
         }
    ]
}
{
    "packages":[
        {
            "id":16913,
            "quantity":500,
            "quantity_without_discount":500,
            "bonus_quantity":10,
            "amount":4,
            "amount_without_discount":4.99,
            "currency":"USD",
            "image":"\/\/cdn2.xsolla.com\/img\/misc\/images\/5df58528dee219c2ab48e003f8f1a8f1.jpg",
            "description":"500 Gold",
            "bonus_items":[
                {
                    "name":"Rabbit",
                    "quantity":1
                }
            ],
            "advertisement_label":{
                "type":"recommended",
                "name":"Most Popular"
            },
            "offer_label":""
         }
    ]
}

Storefront 组

列示虚拟物品组。

HTTP 请求

GET https://api.xsolla.com/merchant/v2/projects/{project_id}/storefront/virtual_items/groups

请求参数:

参数 类型 描述
project_id
int 项目 ID。必要。
user_id
string 用户 ID。必要。
currency
string 虚拟货币包的币种。使用 ISO 4217 标准规定的三字母组合表示币种。必要。
language
string 界面语言。符合 ISO 639-1 标准规定的 2 字母语言代码(小写字母)。必要。

响应参数:

参数 类型 描述
groups
array 带有虚拟物品组相关数据的对象的数组。
groups.id
int 组在 Xsolla 系统中的 ID。
groups.external_id
string 组的外部 ID。
groups.name
string 组已本地化的名称。
groups.description
string 组已本地化的描述。
groups.level
int 组级别。
groups.children
array 带有子组相关信息的数组。每个子组的结构与父组的结构相同。

请求

<?php

$response = $xsollaClient->GetStorefrontVirtualGroups(array(
    'project_id' => PROJECT_ID,
    'language' => LANGUAGE_ISO,
    'currency' => CURRENCY_ISO,
    'user_id' => USER_ID
));
GET /merchant/v2/projects/{project_id}/storefront/virtual_items/groups HTTP/1.1
User-Agent: xsolla-api-client/1.0
Host: api.xsolla.com
Accept: application/json
Authorization:Basic ZGVtb0B4c29sbGEuY29tOmRlbW8=
Content-Type: application/json
$ curl -v 'https://api.xsolla.com/merchant/v2/projects/{project_id}/storefront/virtual_items/groups' \
-X GET \
-u merchant_id:merchant_api_key

响应

<?php

// 示例响应
$response = array (
    'groups' =>
        array (
            array (
                'id' => 1,
                'external_id' => '21',
                'name' => 'Group name 21',
                'description' => 'Group description 21',
                'children' =>
                    array (),
                'level' => 0,
            ),
            array (
                'id' => 2,
                'external_id' => '22',
                'name' => 'Group name 22',
                'description' => 'Group description 22',
                'children' =>
                    array (
                        array (
                            'id' => 3,
                            'external_id' => NULL,
                            'name' => 'Child group 1',
                            'description' => 'Child group 1',
                            'children' =>
                                array (),
                            'level' => 1,
                        ),
                        array (
                            'id' => 8,
                            'external_id' => NULL,
                            'name' => 'Child group 2',
                            'description' => 'Child group 2',
                            'children' =>
                                array (),
                            'level' => 1,
                        ),
                    ),
                'level' => 0,
            ),
        ),
);
HTTP/1.1 200 OK
Content-Type: application/json

{
    "groups":[
        {
            "id":1,
            "external_id":"21",
            "name":"Group name 21",
            "description":"Group description 21",
            "children":[],
            "level":0
        },
        {
            "id":2,
            "external_id":"22",
            "name":"Group name 22",
            "description":"Group description 22",
            "children":[
                {
                    "id":3,
                    "external_id": null,
                    "name":"Child group 1",
                    "description":"Child group 1",
                    "children":[],
                    "level":1
                },
                {
                    "id":8,
                    "external_id": null,
                    "name":"Child group 2",
                    "description":"Child group 2",
                    "children":[],
                    "level":1
                }
            ],
            "level":0
        }
    ]
}
{
    "groups":[
        {
            "id":1,
            "external_id":"21",
            "name":"Group name 21",
            "description":"Group description 21",
            "children":[],
            "level":0
        },
        {
            "id":2,
            "external_id":"22",
            "name":"Group name 22",
            "description":"Group description 22",
            "children":[
                {
                    "id":3,
                    "external_id": null,
                    "name":"Child group 1",
                    "description":"Child group 1",
                    "children":[],
                    "level":1
                },
                {
                    "id":8,
                    "external_id": null,
                    "name":"Child group 2",
                    "description":"Child group 2",
                    "children":[],
                    "level":1
                }
            ],
            "level":0
        }
    ]
}

Storefront 虚拟物品

列示所有虚拟物品。

HTTP 请求

GET https://api.xsolla.com/merchant/v2/projects/{project_id}/storefront/virtual_items/items

请求参数:

参数 类型 描述
project_id
int 项目 ID。必要。
user_id
string 用户 ID。必要。
group_id
int 虚拟物品组的 ID。必要。
currency
string 虚拟货币包的币种。使用 ISO 4217 标准规定的三字母组合表示币种。必要。
language
string 界面语言。符合 ISO 639-1 标准规定的 2 字母语言代码(小写字母)。必要。

响应参数:

参数 类型 描述
items
array 带有虚拟物品相关数据的对象的数组。
items.id
int Xsolla 系统中虚拟物品的 ID。
items.sku
string 虚拟物品的 SKU。
items.name
string 虚拟物品已本地化的名称。
items.image_url
string 虚拟物品图片的 URL。
items.description
string 虚拟物品已本地化的简单描述。
items.long_description
string 虚拟物品已本地化的详细描述。
items.currency
string 虚拟物品的币种。使用 ISO 4217 标准规定的三字母组合表示币种。
items.amount
float 虚拟物品的价格(使用请求中发送的币种表示)。
items.amount_without_discount
float 虚拟物品的价格,无折扣(促销时)。
items.vc_amount
float 以虚拟货币表示的虚拟物品价格。
items.vc_amount_without_discount
float 以虚拟货币表示的虚拟物品价格,无折扣(促销时)。
items.bonus_virtual_currency
object 带有作为奖励的虚拟货币相关数据的对象(促销时)。
items.bonus_virtual_currency.vc_amount
float 作为奖励的虚拟货币数量。
items.bonus_virtual_items
array 带有作为奖励的虚拟物品相关数据的数组(促销时)。
items.bonus_virtual_items.name
string 虚拟物品已本地化的名称。
items.bonus_virtual_items.quantity
int 虚拟物品的数量。
items.advertisement_label
object 带有虚拟物品标签相关数据的对象。
items.advertisement_label.type
string 虚拟物品标签的类型。可以是“recommended”、“best_deal”、“special_offer”或null。
items.advertisement_label.name
string 虚拟物品标签已本地化的名称(依据 items.advertisement_label.type 的值)。
items.offer_label
string 促销的标签。

请求

<?php

$response = $xsollaClient->GetStorefrontVirtualItems(array(
    'project_id' => PROJECT_ID,
    'language' => LANGUAGE_ISO,
    'currency' => CURRENCY_ISO,
    'user_id' => USER_ID,
    'group_id' => GROUP_ID
));
GET /merchant/v2/projects/{project_id}/storefront/virtual_items/items HTTP/1.1
User-Agent: xsolla-api-client/1.0
Host: api.xsolla.com
Accept: application/json
Authorization:Basic ZGVtb0B4c29sbGEuY29tOmRlbW8=
Content-Type: application/json
$ curl -v 'https://api.xsolla.com/merchant/v2/projects/{project_id}/storefront/virtual_items/items' \
-X GET \
-u merchant_id:merchant_api_key

响应

<?php

// 示例响应
$response = array (
    'items' =>
        array (
            array (
                'id' => 1678,
                'sku' => '1468',
                'name' => 'Rabbit',
                'image_url' => 'https://cdn3.xsolla.com/img/misc/merchant-digital-goods/4376c004fa33dc74483906561d617cb3.png',
                'description' => 'Rabbits are small mammals in the family Leporidae',
                'long_description' => NULL,
                'currency' => 'USD',
                'amount' => 0,
                'amount_without_discount' => 0,
                'vc_amount' => 2,
                'vc_amount_without_discount' => 2,
                'bonus_virtual_currency' => NULL,
                'bonus_virtual_items' =>
                    array (),
                'advertisement_label' => NULL,
                'offer_label' => '',
            ),
        ),
);
HTTP/1.1 200 OK
Content-Type: application/json

{
    "items":[
        {
            "id":1678,
            "sku":"1468",
            "name":"Rabbit",
            "image_url":"https:\/\/cdn3.xsolla.com\/img\/misc\/merchant-digital-goods\/4376c004fa33dc74483906561d617cb3.png",
            "description":"Rabbits are small mammals in the family Leporidae",
            "long_description": null,
            "currency":"USD",
            "amount":0,
            "amount_without_discount":0,
            "vc_amount":2,
            "vc_amount_without_discount":2,
            "bonus_virtual_currency": null,
            "bonus_virtual_items":[],
            "advertisement_label": null,
            "offer_label":""
        }
    ]
}
{
    "items":[
        {
            "id":1678,
            "sku":"1468",
            "name":"Rabbit",
            "image_url":"https:\/\/cdn3.xsolla.com\/img\/misc\/merchant-digital-goods\/4376c004fa33dc74483906561d617cb3.png",
            "description":"Rabbits are small mammals in the family Leporidae",
            "long_description": null,
            "currency":"USD",
            "amount":0,
            "amount_without_discount":0,
            "vc_amount":2,
            "vc_amount_without_discount":2,
            "bonus_virtual_currency": null,
            "bonus_virtual_items":[],
            "advertisement_label": null,
            "offer_label":""
        }
    ]
}

Storefront 订阅计划

列示所有订阅计划。

HTTP 请求

GET https://api.xsolla.com/merchant/v2/projects/{project_id}/storefront/subscriptions

请求参数:

参数 类型 描述
project_id
int 项目 ID。必要。
user_id
string 用户 ID。必要。
currency
string 虚拟货币包的币种。使用 ISO 4217 标准规定的三字母组合表示币种。必要。
language
string 界面语言。符合 ISO 639-1 标准规定的 2 字母语言代码(小写字母)。必要。

响应参数:

参数 类型 描述
packages
array 带有订阅计划相关数据的对象的数组。
packages.id
int 订阅计划在 Xsolla 系统中的 ID。
packages.is_active
boolean 计划是否处于活动状态。
packages.charge_amount
float 订阅计划的成本。
packages.charge_amount_without_discount
float 订阅计划的成本,无折扣(促销时)。
packages.charge_currency
string 订阅计划的币种。使用 ISO 4217 标准规定的三字母组合表示币种。
packages.period
int 订阅计划的计费周期。
packages.period_unit
string 计费周期的类型(日/月)。
packages.name
string 订阅计划已本地化的名称。
packages.description
string 订阅计划已本地化的描述。
packages.bonus_virtual_currency
object 带有作为奖励的虚拟货币相关数据的对象(促销时)。
packages.bonus_virtual_currency.vc_amount
float 作为奖励的虚拟货币数量。
packages.bonus_virtual_items
array 带有作为奖励的虚拟道具相关数据的数组(促销时)。
packages.bonus_virtual_items.name
string 虚拟道具已本地化的名称。
packages.bonus_virtual_items.quantity
int 虚拟道具数量。
packages.offer_label
string 促销的标签。
packages.is_trial
boolean 本订阅计划是否存在试用期。
packages.period_trial
int 试用期(按天计)。
active_user_package
object 带有用户有效订阅相关数据的对象。
active_user_package.date_next_charge
string 有效订阅下次收费的日期。符合 ISO 8601 标准规定的日期与时间。
active_user_package.id
string 活动订阅的计划 ID。

请求

<?php

$response = $xsollaClient->GetStorefrontSubscriptions(array(
    'project_id' => PROJECT_ID,
    'language' => LANGUAGE_ISO,
    'currency' => CURRENCY_ISO,
    'user_id' => USER_ID
));
GET /merchant/v2/projects/{project_id}/storefront/subscriptions HTTP/1.1
User-Agent: xsolla-api-client/1.0
Host: api.xsolla.com
Accept: application/json
Authorization:Basic ZGVtb0B4c29sbGEuY29tOmRlbW8=
Content-Type: application/json
$ curl -v 'https://api.xsolla.com/merchant/v2/projects/{project_id}/storefront/subscriptions' \
-X GET \
-u merchant_id:merchant_api_key

响应

<?php

// 示例响应
$response = array (
    'packages' =>
        array (
            array (
                'id' => '2.99_1_months',
                'is_active' => true,
                'charge_amount' => 2.99,
                'charge_amount_without_discount' => 2.99,
                'charge_currency' => 'USD',
                'period' => 1,
                'period_unit' => 'month',
                'name' => 'Silver Status',
                'description' => NULL,
                'bonus_virtual_currency' => NULL,
                'bonus_virtual_items' =>
                    array (),
                'offer_label' => '',
                'is_trial' => false,
                'period_trial' => 0,
            ),
            array (
                'id' => '4.99_1_months',
                'is_active' => true,
                'charge_amount' => 4.99,
                'charge_amount_without_discount' => 4.99,
                'charge_currency' => 'USD',
                'period' => 1,
                'period_unit' => 'month',
                'name' => 'Gold Status',
                'description' => NULL,
                'bonus_virtual_currency' => NULL,
                'bonus_virtual_items' =>
                    array (),
                'offer_label' => '',
                'is_trial' => false,
                'period_trial' => 0,
            ),
        ),
    'active_user_package' =>
        array (
            'date_next_charge' => '2016-06-28T06:35:02+00:00',
            'id' => '2.99_1_months'
        )
);
HTTP/1.1 200 OK
Content-Type: application/json

{
    "packages": [
        {
            "id": "2.99_1_months",
            "is_active": true,
            "charge_amount": 2.99,
            "charge_amount_without_discount": 2.99,
            "charge_currency": "USD",
            "period": 1,
            "period_unit": "month",
            "name": "Silver Status",
            "description": null,
            "bonus_virtual_currency": null,
            "bonus_virtual_items": [],
            "offer_label": "",
            "is_trial": false,
            "period_trial": 0
        },
        {
            "id": "4.99_1_months",
            "is_active": true,
            "charge_amount": 4.99,
            "charge_amount_without_discount": 4.99,
            "charge_currency": "USD",
            "period": 1,
            "period_unit": "month",
            "name": "Gold Status",
            "description": null,
            "bonus_virtual_currency": null,
            "bonus_virtual_items": [],
            "offer_label": "",
            "is_trial": false,
            "period_trial": 0
        }
    ],
    "active_user_package": {
            "date_next_charge": "2016-06-28T06:35:02+00:00",
            "id": "2.99_1_months"
        }
}
{
    "packages": [
        {
            "id": "2.99_1_months",
            "is_active": true,
            "charge_amount": 2.99,
            "charge_amount_without_discount": 2.99,
            "charge_currency": "USD",
            "period": 1,
            "period_unit": "month",
            "name": "Silver Status",
            "description": null,
            "bonus_virtual_currency": null,
            "bonus_virtual_items": [],
            "offer_label": "",
            "is_trial": false,
            "period_trial": 0
        },
        {
            "id": "4.99_1_months",
            "is_active": true,
            "charge_amount": 4.99,
            "charge_amount_without_discount": 4.99,
            "charge_currency": "USD",
            "period": 1,
            "period_unit": "month",
            "name": "Gold Status",
            "description": null,
            "bonus_virtual_currency": null,
            "bonus_virtual_items": [],
            "offer_label": "",
            "is_trial": false,
            "period_trial": 0
        }
    ],
    "active_user_package": {
            "date_next_charge": "2016-06-28T06:35:02+00:00",
            "id": "2.99_1_months"
        }
}

Storefront 促销

显示有效促销的相关信息。

HTTP 请求

GET https://api.xsolla.com/merchant/v2/projects/{project_id}/storefront/bonus

请求参数:

参数 类型 描述
project_id
int 项目 ID。必要。
user_id
string 用户 ID。必要。
currency
string 虚拟货币包的币种。使用 ISO 4217 标准规定的三字母组合表示币种。必要。
language
string 界面语言。符合 ISO 639-1 标准规定的 2 字母语言代码(小写字母)。必要。

响应参数:

参数 类型 描述
seconds
int 距离促销结束还剩下多长时间(秒)。
name
string 促销已本地化的名称。
description
string 促销已本地化的描述。

请求

<?php

$response = $xsollaClient->GetStorefrontBonus(array(
    'project_id' => PROJECT_ID,
    'language' => LANGUAGE_ISO,
    'currency' => CURRENCY_ISO,
    'user_id' => USER_ID
));
GET /merchant/v2/projects/{project_id}/storefront/bonus HTTP/1.1
User-Agent: xsolla-api-client/1.0
Host: api.xsolla.com
Accept: application/json
Authorization:Basic ZGVtb0B4c29sbGEuY29tOmRlbW8=
Content-Type: application/json
$ curl -v 'https://api.xsolla.com/merchant/v2/projects/{project_id}/storefront/bonus' \
-X GET \
-u merchant_id:merchant_api_key

响应

<?php

// 示例响应
$response = array (
    'seconds' => 619513283,
    'name' => 'Promotion name',
    'description' => 'Promotion description',
);
HTTP/1.1 200 OK
Content-Type: application/json

{
    "seconds":619513283,
    "name":"Promotion name",
    "description":"Promotion description"
}
{
    "seconds":619513283,
    "name":"Promotion name",
    "description":"Promotion description"
}

列示已保存的支付帐户

列示已保存的用户支付帐户。

HTTP 请求

GET https://api.xsolla.com/merchant/v2/projects/{project_id}/users/{user_id}/payment_accounts

参数 类型 描述
project_id
int 游戏 ID。
user_id
string 用户 ID。

请求

<?php

$response = $xsollaClient->ListPaymentAccounts(array(
    'project_id' => PROJECT_ID,
    'user_id' => USER_ID
));
GET /merchant/v2/projects/{project_id}/users/{user_id}/payment_accounts HTTP/1.1
User-Agent: xsolla-api-client/1.0
Host: api.xsolla.com
Accept: application/json
Authorization: Basic ZGVtb0B4c29sbGEuY29tOmRlbW8=
Content-Type: application/json
$ curl -v 'https://api.xsolla.com/merchant/v2/projects/{project_id}/users/{user_id}/payment_accounts' \
-X GET \
-u merchant_id:merchant_api_key

响应

<?php

// 示例响应
$response = array (
    array (
        'type' => 'card',
        'id' => 1,
        'name' => '411111******1111',
        'payment_system' =>
            array (
                'id' => 1380,
                'name' => 'Credit/Debit Cards',
            ),
    ),
);
HTTP/1.1 200 OK
Content-Type: application/json

[
    {
        "type": "card",
        "id": 1,
        "name": "411111******1111",
        "payment_system": {
            "id": 1380,
            "name": "Credit/Debit Cards"
        }
    }
]
[
    {
        "type": "card",
        "id": 1,
        "name": "411111******1111",
        "payment_system": {
            "id": 1380,
            "name": "Credit/Debit Cards"
        }
    }
]

使用已保存的支付帐户收费

使用已保存的支付帐户收费。

HTTP 请求

POST https://api.xsolla.com/merchant/v2/projects/{project_id}/users/{user_id}/payments/{type}/{account_id}

参数 类型 描述
project_id
int 游戏 ID。必要。
user_id
int 用户 ID。必要。
type
string 支付帐户类型:卡片/paypal。必要。
account_id
int Xsolla 系统中已保存的帐户的标识符。必要。
user
object 带有用户相关数据的对象。
user.ip
string 用户 IP。必要。
user.name
string 用户名。
purchase
object 带有购买相关数据的对象。
purchase.virtual_currency
object 带有虚拟货币相关数据的对象。
purchase.virtual_currency.quantity
float 使用虚拟货币购买的数量。
purchase.checkout
object 带有结账参数相关数据的对象。
purchase.checkout.currency
string 购买币种。使用 ISO 4217 标准规定的三字母组合表示币种。
purchase.checkout.amount
float 购买金额。
settings
object 带有购买设置相关数据的对象。
settings.mode
string 设置“沙盒”值以测试支付流程。对于真实支付,应移除此参数。

请求

<?php

$response = $xsollaClient->ChargePaymentAccount(array(
    'project_id' => PROJECT_ID,
    'user_id' => USER_ID,
    'type' => TYPE,
    'account_id' => ACCOUNT_ID,
    'request' => array (
         'user' =>
             array (
                 'ip' => '127.0.0.1',
                 'name' => 'John Smith',
             ),
         'purchase' =>
             array (
                 'virtual_currency' =>
                     array (
                         'quantity' => 100,
                     ),
                 'description' =>
                     array (
                         'value' => 'Test Purchase',
                     ),
             ),
         'settings' =>
             array (
                 'mode' => 'sandbox',
             ),
    )
));
POST /merchant/v2/projects/{project_id}/users/{user_id}/payments/{type}/{account_id} HTTP/1.1
User-Agent: xsolla-api-client/1.0
Host: api.xsolla.com
Accept: application/json
Authorization: Basic ZGVtb0B4c29sbGEuY29tOmRlbW8=
Content-Type: application/json

{
    "user": {
        "ip": "127.0.0.1",
        "name": "John Smith"
    },
    "purchase": {
        "virtual_currency": {
            "quantity": 100
        },
        "description": {
            "value": "Test Purchase"
        }
    },
    "settings": {
        "mode": "sandbox"
    }
}
$ curl -v 'https://api.xsolla.com/merchant/v2/projects/{project_id}/users/{user_id}/payments/{type}/{account_id}' \
-X POST \
-u merchant_id:merchant_api_key \
-H 'Content-Type: application/json' \
-H 'Accept: application/json' \
-d '{
    "user": {
        "ip": "127.0.0.1",
        "name": "John Smith"
    },
    "purchase": {
        "virtual_currency": {
            "quantity": 100
        },
        "description": {
            "value": "Test Purchase"
        }
    },
    "settings": {
        "mode": "sandbox"
    }
}'

响应

<?php

// 示例响应
$response = array (
    'transaction_id' => 119478390
);
HTTP/1.1 201 Created
Content-Type: application/json

{
    "transaction_id": 119478390
}
{
    "transaction_id": 119478390
}

删除已保存的支付帐户

删除已保存的支付帐户。

HTTP 请求

DELETE https://api.xsolla.com/merchant/v2/projects/{project_id}/users/{user_id}/payment_accounts/{type}/{account_id}

参数 类型 描述
project_id
int 游戏 ID。
user_id
string 用户身份参数。
type
string 支付帐户类型:卡片/paypal。
account_id
int Xsolla 系统中已保存的帐户的标识符。

请求

<?php

$response = $xsollaClient->DeletePaymentAccount(array(
    'project_id' => PROJECT_ID,
    'user_id' => USER_ID,
    'type' => TYPE,
    'account_id' => ACCOUNT_ID
));
DELETE /merchant/v2/projects/{project_id}/users/{user_id}/payment_accounts/{type}/{account_id} HTTP/1.1
User-Agent: xsolla-api-client/1.0
Host: api.xsolla.com
Accept: application/json
Authorization: Basic ZGVtb0B4c29sbGEuY29tOmRlbW8=
Content-Type: application/json
$ curl -v 'https://api.xsolla.com/merchant/v2/projects/{project_id}/users/{user_id}/payment_accounts/{type}/{account_id}' \
-X DELETE \
-u merchant_id:merchant_api_key

响应

<?php

// 示例响应
$response = null;
HTTP/1.1 204 No Content

创建计划

创建重复性计划

HTTP 请求

POST https://api.xsolla.com/merchant/v2/projects/{project_id}/subscriptions/plans

参数 类型 描述
project_id
int 游戏 ID。
external_id
string 外部计划标识符。可选。
name
array of strings 计划名称。值包含 : 对。
description
array of strings 计划描述。值包含 : 对。可选。
group_id
string 组的 ID。
charge
object 带有费用相关数据的对象。
charge.period
object 带有费用期间相关数据的对象。
charge.period.value
int 两次收费之间的间隔时间。
charge.period.type
string 期间类型:日/月。
charge.amount
float 支付金额。
charge.currency
string 购买币种。使用ISO 4217标准规定的三字母组合表示币种。
expiration
object 带有订阅过期相关数据的对象。
expiration.value
int 过期之前的时间。
expiration.type
string 使用期限类型:day / month。
trial
object 带有试用期相关数据的对象。可选。
trial.value
int 试用期时长。
trial.type
string 试用期类型:day.
grace_period
object 带有宽限期相关数据的对象。可选。
grace_period.value
int 宽限期时间量。
grace_period.type
string 宽限期类型:天。

请求

<?php

$response = $xsollaClient->CreateSubscriptionPlan(array(
    'project_id' => PROJECT_ID,
    'request' => array (
         'external_id' => 'sample_plan',
         'name' =>
             array (
                 'en' => 'Sample Plan',
             ),
         'description' =>
             array (
                 'en' => 'Basic options plan',
             ),
         'group_id' => 'USA Products',
         'charge' =>
             array (
                 'period' =>
                     array (
                         'value' => 1,
                         'type' => 'month',
                     ),
                 'amount' => 10,
                 'currency' => 'USD',
             ),
         'expiration' =>
             array (
                 'value' => '',
                 'type' => '',
             ),
     )

));
POST /merchant/v2/projects/{project_id}/subscriptions/plans HTTP/1.1
User-Agent: xsolla-api-client/1.0
Host: api.xsolla.com
Accept: application/json
Authorization: Basic ZGVtb0B4c29sbGEuY29tOmRlbW8=
Content-Type: application/json

{
    "external_id": "sample_plan",
    "name": {
        "en": "Sample Plan"
    },
    "description": {
        "en": "Basic options plan"
    },
    "group_id": "USA Products",
    "charge": {
        "period": {
            "value": 1,
            "type": "month"
        },
        "amount": 10,
        "currency": "USD"
    },
    "expiration": {
        "value": "",
        "type": ""
    }
}
$ curl -v 'https://api.xsolla.com/merchant/v2/projects/{project_id}/subscriptions/plans' \
-X POST \
-u merchant_id:merchant_api_key \
-H 'Content-Type: application/json' \
-H 'Accept: application/json' \
-d '{
    "external_id": "sample_plan",
    "name": {
        "en": "Sample Plan"
    },
    "description": {
        "en": "Basic options plan"
    },
    "group_id": "USA Products",
    "charge": {
        "period": {
            "value": 1,
            "type": "month"
        },
        "amount": 10,
        "currency": "USD",
    },
    "expiration": {
        "value": "",
        "type": ""
    }
}'

响应

<?php

// example response
$response = array (
    'plan_id' => 54
);
HTTP/1.1 201 Created
Content-Type: application/json

{
    "plan_id": 54
}
{
    "plan_id": 54
}

更新计划

更新重复性计划。

HTTP 请求

PUT https://api.xsolla.com/merchant/v2/projects/{project_id}/subscriptions/plans/{plan_id}

参数 类型 描述
project_id
int 游戏 ID。
plan_id
int 计划 ID。
external_id
string 外部计划标识符。可选。
name
array of strings 计划名称。由<地区语言>:<计划名称>组成的键值对。
description
array of strings 计划描述。由<地区语言>:<计划描述>组成的键值对。可选。
group_id
string 组的 ID。
charge
object 带有费用相关数据的对象。
charge.period
object 带有费用期间相关数据的对象。
charge.period.value
int 两次收费之间的间隔时间。
charge.period.type
string 期间类型:日/月。
charge.amount
float 支付金额。
charge.currency
string 购买币种。使用ISO 4217标准规定的三字母组合表示币种。
expiration
object 带有订阅过期相关数据的对象。
expiration.value
int 过期之前的时间。
expiration.type
string 使用期限类型:day / month。
trial
object 带有试用期相关数据的对象。可选。
trial.value
int 试用期时长。
trial.type
string 试用期类型:day.
grace_period
object 带有宽限期相关数据的对象。可选。
grace_period.value
int 宽限期时间量。
grace_period.type
string 宽限期类型:天。

请求

<?php

$response = $xsollaClient->UpdateSubscriptionPlan(array(
    'project_id' => PROJECT_ID,
    'plan_id' => PLAN_ID,
    'request' => array (
         'external_id' => 'sample_plan',
         'name' =>
             array (
                 'en' => 'Sample Plan',
             ),
         'description' =>
             array (
                 'en' => 'Basic options plan',
             ),
         'charge' =>
             array (
                 'period' =>
                     array (
                         'value' => 1,
                         'type' => 'month',
                     ),
                 'amount' => 10,
                 'currency' => 'USD',
             ),
         'expiration' =>
             array (
                 'value' => '',
                 'type' => '',
             ),
     )
));
PUT /merchant/v2/projects/{project_id}/subscriptions/plans/{plan_id} HTTP/1.1
User-Agent: xsolla-api-client/1.0
Host: api.xsolla.com
Accept: application/json
Authorization: Basic ZGVtb0B4c29sbGEuY29tOmRlbW8=
Content-Type: application/json

{
    "external_id": "sample_plan",
    "name": {
        "en": "Sample Plan"
    },
    "description": {
        "en": "Basic options plan"
    },
    "charge": {
        "period": {
            "value": 1,
            "type": "month"
        },
        "amount": 10,
        "currency": "USD"
    },
    "expiration": {
        "value": "",
        "type": ""
    }
}
$ curl -v 'https://api.xsolla.com/merchant/v2/projects/{project_id}/subscriptions/plans/{plan_id}' \
-X PUT \
-u merchant_id:merchant_api_key \
-H 'Content-Type: application/json' \
-H 'Accept: application/json' \
-d '{
    "external_id": "sample_plan",
    "name": {
        "en": "Sample Plan"
    },
    "description": {
        "en": "Basic options plan"
    },
    "charge": {
        "period": {
            "value": 1,
            "type": "month"
        },
        "amount": 10,
        "currency": "USD"
    },
    "expiration": {
        "value": "",
        "type": ""
    }
}'

响应

<?php

// example response
$response = array (
    'id' => '54',
    'external_id' => 'sample_plan',
    'name' =>
        array (
            'en' => 'Sample Plan'
        ),
    'description' =>
        array (
            'en' => 'Basic options plan'
        ),
    'charge' =>
        array (
            'period' =>
                array (
                    'value' => 1,
                    'type' => 'month'
                ),
            'amount' => 10,
            'currency' => 'USD'
        ),
    'expiration' =>
        array (
            'value' => '',
            'type' => ''
        ),
    'trial' =>
        array (
            'value' => 14,
            'type' => 'day'
        ),
    'status' =>
        array (
            'value' => 'disabled',
            'counters' =>
                array (
                    'active' => 0,
                    'canceled' => 0,
                    'expired' => 0
                )
        )
);
HTTP/1.1 200 OK
Content-Type: application/json

{
    "id": "54",
    "external_id": "sample_plan",
    "name": {
        "en": "Sample Plan"
    },
    "description": {
        "en": "Basic options plan"
    },
    "charge": {
        "period": {
            "value": 1,
            "type": "month"
        },
        "amount": 10,
        "currency": "USD"
    },
    "expiration": {
        "value": "",
        "type": ""
    },
    "trial": {
        "value": 14,
        "type": "day"
    },
    "status": {
        "value": "disabled",
        "counters": {
            "active": 0,
            "canceled": 0,
            "expired": 0
        }
    }
}
{
    "id": "54",
    "external_id": "sample_plan",
    "name": {
        "en": "Sample Plan"
    },
    "description": {
        "en": "Basic options plan"
    },
    "charge": {
        "period": {
            "value": 1,
            "type": "month"
        },
        "amount": 10,
        "currency": "USD"
    },
    "expiration": {
        "value": "",
        "type": ""
    },
    "trial": {
        "value": 14,
        "type": "day"
    },
    "status": {
        "value": "disabled",
        "counters": {
            "active": 0,
            "canceled": 0,
            "expired": 0
        }
    },
    "type":
}

删除计划

删除重复性计划。

HTTP 请求

DELETE https://api.xsolla.com/merchant/v2/projects/{project_id}/subscriptions/plans/{plan_id}/delete

参数 类型 描述
project_id
int 游戏 ID。
plan_id
int 计划 ID。

请求


<?php

$response = $xsollaClient->DeleteSubscriptionPlan(array(
    'project_id' => PROJECT_ID,
    'plan_id' => PLAN_ID
));
DELETE /merchant/v2/projects/{project_id}/subscriptions/plans/{plan_id}/delete HTTP/1.1
User-Agent: xsolla-api-client/1.0
Host: api.xsolla.com
Accept: application/json
Authorization: Basic ZGVtb0B4c29sbGEuY29tOmRlbW8=
Content-Type: application/json
$ curl -v 'https://api.xsolla.com/merchant/v2/projects/{project_id}/subscriptions/plans/{plan_id}/delete' \
-X DELETE \
-u merchant_id:merchant_api_key

响应

<?php

$response = null;
HTTP/1.1 204 No Content

禁用计划

禁用重复性计划。

HTTP 请求

DELETE https://api.xsolla.com/merchant/v2/projects/{project_id}/subscriptions/plans/{plan_id}

Parameter 类型 描述
project_id
int 游戏 ID。
plan_id
int 计划 ID。

请求


<?php

$response = $xsollaClient->DisableSubscriptionPlan(array(
    'project_id' => PROJECT_ID,
    'plan_id' => PLAN_ID
));
DELETE /merchant/v2/projects/{project_id}/subscriptions/plans/{plan_id} HTTP/1.1
User-Agent: xsolla-api-client/1.0
Host: api.xsolla.com
Accept: application/json
Authorization: Basic ZGVtb0B4c29sbGEuY29tOmRlbW8=
Content-Type: application/json
$ curl -v 'https://api.xsolla.com/merchant/v2/projects/{project_id}/subscriptions/plans/{plan_id}' \
-X DELETE \
-u merchant_id:merchant_api_key

响应

<?php

$response = null;
HTTP/1.1 204 No Content

启用计划

启用重复性计划。

HTTP 请求

PATCH https://api.xsolla.com/merchant/v2/projects/{project_id}/subscriptions/plans/{plan_id}

参数 类型 描述
project_id
int 游戏 ID。
plan_id
int 计划 ID。

请求


<?php

$response = $xsollaClient->EnableSubscriptionPlan(array(
    'project_id' => PROJECT_ID,
    'plan_id' => PLAN_ID
));
PATCH /merchant/v2/projects/{project_id}/subscriptions/plans/{plan_id} HTTP/1.1
User-Agent: xsolla-api-client/1.0
Host: api.xsolla.com
Accept: application/json
Authorization: Basic ZGVtb0B4c29sbGEuY29tOmRlbW8=
Content-Type: application/json
$ curl -v 'https://api.xsolla.com/merchant/v2/projects/{project_id}/subscriptions/plans/{plan_id}' \
-X PATCH \
-u merchant_id:merchant_api_key

响应

<?php

$response = null;
HTTP/1.1 204 No Content

列示所有计划

列示所有重复性计划。

HTTP 请求

GET https://api.xsolla.com/merchant/v2/projects/{project_id}/subscriptions/plans

参数 类型 描述
project_id
int 游戏 ID。
external_id
string 外部计划标识符。
limit
int 获取重复性计划列表的限制。
offset
int 重复性计划列表的起始页面。
group_id
string 这些计划与之连接的组的 ID。
product_id
int 这些计划与之连接的产品的 ID。

请求


<?php

$response = $xsollaClient->ListSubscriptionPlans(array(
    'project_id' => PROJECT_ID
));
GET /merchant/v2/projects/{project_id}/subscriptions/plans?external_id=1&limit=1&offset=1 HTTP/1.1
User-Agent: xsolla-api-client/1.0
Host: api.xsolla.com
Accept: application/json
Authorization: Basic ZGVtb0B4c29sbGEuY29tOmRlbW8=
Content-Type: application/json
$ curl -v 'https://api.xsolla.com/merchant/v2/projects/{project_id}/subscriptions/plans?external_id=1&limit=1&offset=1' \
-X GET \
-u merchant_id:merchant_api_key

响应

<?php

// example response
$response = array (
    array (
        'id' => '54',
        'external_id' => 'sample_plan',
        'name' =>
            array (
                'en' => 'Sample Plan'
            ),
        'description' =>
            array (
                'en' => 'Basic options plan'
            ),
        'group_id' => 'USA Products',
        'charge' =>
            array (
                'period' =>
                    array (
                        'value' => 1,
                        'type' => 'month'
                    ),
                'amount' => 10,
                'currency' => 'USD'
            ),
        'expiration' =>
            array (
                'value' => 90,
                'type' => 'day'
            ),
        'trial' =>
            array (
                'value' => 14,
                'type' => 'day'
            ),
        'status' =>
            array (
                'value' => 'disabled',
                'counters' =>
                    array (
                        'active' => 0,
                        'canceled' => 0,
                        'expired' => 0
                    )
            )
    )
);
HTTP/1.1 200 OK
Content-Type: application/json

[
    {
        "id": "54",
        "external_id": "sample_plan",
        "name": {
            "en": "Sample Plan"
        },
        "description": {
            "en": "Basic options plan"
        },
        "group_id": "USA Products",
        "charge": {
            "period": {
                "value": 1,
                "type": "month"
            },
            "amount": 10,
            "currency": "USD"
        },
        "expiration": {
            "value": 90,
            "type": "day"
        },
        "trial": {
            "value": 14,
            "type": "day"
        },
        "status": {
            "value": "disabled",
            "counters": {
                "active": 0,
                "canceled": 0,
                "expired": 0
            }
        }
    }
]
[
    {
        "id": "54",
        "external_id": "sample_plan",
        "name": {
            "en": "Sample Plan"
        },
        "description": {
            "en": "Basic options plan"
        },
        "group_id": "USA Products",
        "charge": {
            "period": {
                "value": 1,
                "type": "month"
            },
            "amount": 10,
            "currency": "USD",
        },
        "expiration": {
            "value": 90,
            "type": "day",
        },
        "trial": {
            "value": 14,
            "type": "day"
        },
        "status": {
            "value": "disabled",
            "counters": {
                "active": 0,
                "canceled": 0,
                "expired": 0
            }
        }
    }
]

创建产品

创建产品。

HTTP 请求

POST https://api.xsolla.com/merchant/v2/projects/{project_id}/subscriptions/products

参数 类型 描述
project_id
int 游戏 ID。
name
string 产品名称。
group_id
string 组的 ID。

请求

<?php

$response = $xsollaClient->CreateSubscriptionProduct(array(
    'project_id' => PROJECT_ID,
    'request' => array(
        'name' => 'Demo Product',
        'group_id' => 'USA Products'
    ),
));
POST /merchant/v2/projects/{project_id}/subscriptions/products HTTP/1.1
User-Agent: xsolla-api-client/1.0
Host: api.xsolla.com
Accept: application/json
Authorization: Basic ZGVtb0B4c29sbGEuY29tOmRlbW8=
Content-Type: application/json

{
    "name": "Demo Product",
    "group_id": "USA Products"
}
$ curl -v 'https://api.xsolla.com/merchant/v2/projects/{project_id}/subscriptions/products' \
-X POST \
-u merchant_id:merchant_api_key \
-H 'Content-Type: application/json' \
-H 'Accept: application/json' \
-d '{
        "name": "Demo Product",
        "group_id": "USA Products"
    }'

响应

<?php

// example response
$response = array (
    'product_id' => '64'
);
HTTP/1.1 201 Created
Content-Type: application/json

{
    "product_id": "64"
}
{
    "product_id": "64"
}

更新产品

更新产品。

HTTP 请求

PUT https://api.xsolla.com/merchant/v2/projects/{project_id}/subscriptions/products/{product_id}

参数 类型 描述
project_id
int 游戏 ID。
product_id
int 产品 ID。
name
string 产品名称。
group_id
string 组的 ID。

请求

<?php

$response = $xsollaClient->UpdateSubscriptionProduct(array(
    'project_id' => PROJECT_ID,
    'request' => array(
        'name' => 'Demo Product',
        'group_id' => 'USA Products'
    ),
));
PUT /merchant/v2/projects/{project_id}/subscriptions/products/{product_id} HTTP/1.1
User-Agent: xsolla-api-client/1.0
Host: api.xsolla.com
Accept: application/json
Authorization: Basic ZGVtb0B4c29sbGEuY29tOmRlbW8=
Content-Type: application/json

{
        "name": "Demo Product",
        "group_id": "USA Products"
}
$ curl -v 'https://api.xsolla.com/merchant/v2/projects/{project_id}/subscriptions/products/{product_id}' \
-X PUT \
-u merchant_id:merchant_api_key \
-H 'Content-Type: application/json' \
-H 'Accept: application/json' \
-d '{
            "name": "Demo Product",
            "group_id": "USA Products"
    }'

响应

<?php

// example response
$response = array (
    'id' => '64',
    'name' => 'Demo Product',
    'group_id' => 'USA Products'
);
HTTP/1.1 200 OK
Content-Type: application/json

{
    "id": "64",
    "name": "Demo Product",
    "group_id": "USA Products"
}
{
    "id": "64",
    "name": "Demo Product",
    "group_id": "USA Products"
}

删除产品

删除产品。

HTTP 请求

DELETE https://api.xsolla.com/merchant/v2/projects/{project_id}/subscriptions/products/{product_id}

参数 类型 描述
project_id
int 游戏 ID。
product_id
string 产品 ID。

请求


<?php

$response = $xsollaClient->DeleteSubscriptionProduct(array(
    'project_id' => PROJECT_ID,
    'product_id' => PRODUCT_ID
));
DELETE /merchant/v2/projects/{project_id}/subscriptions/products/{product_id} HTTP/1.1
User-Agent: xsolla-api-client/1.0
Host: api.xsolla.com
Accept: application/json
Authorization: Basic ZGVtb0B4c29sbGEuY29tOmRlbW8=
Content-Type: application/json
$ curl -v 'https://api.xsolla.com/merchant/v2/projects/{project_id}/subscriptions/products/{product_id}' \
-X DELETE \
-u merchant_id:merchant_api_key

响应

<?php

$response = null;
HTTP/1.1 204 No Content

列出所有产品

列示所有重复性产品。

HTTP 请求

GET https://api.xsolla.com/merchant/v2/projects/{project_id}/subscriptions/products

参数 类型 描述
project_id
int 游戏 ID。
group_id
string 这些产品的相关联组的 ID。
product_id
int 产品 ID。
limit
int 获取重复性计划列表的限制。
offset
int 重复性计划列表的起始页面。

请求


<?php

$response = $xsollaClient->DeleteSubscriptionProduct(array(
    'project_id' => PROJECT_ID
));
GET /merchant/v2/projects/{project_id}/subscriptions/products?group_id=USA%20Products&limit=1&offset=1 HTTP/1.1
User-Agent: xsolla-api-client/1.0
Host: api.xsolla.com
Accept: application/json
Authorization: Basic ZGVtb0B4c29sbGEuY29tOmRlbW8=
Content-Type: application/json
$ curl -v 'https://api.xsolla.com/merchant/v2/projects/{project_id}/subscriptions/products?group_id=USA%20Products&limit=1&offset=1' \
-X GET \
-u merchant_id:merchant_api_key

响应

<?php

// example response
$response = array (
    array (
        'id' => 3,
        'group_id' => 'USA Products',
        'name' => 'Demo Product'
    )
);
HTTP/1.1 200 OK
Content-Type: application/json

[
    {
        "id": 3,
        "group_id": "USA Products",
        "name": "Demo Product"
    }
]
[
    {
        "id": 3,
        "group_id": "USA Products",
        "name": "Demo Product"
    }
]

更新订阅

更新重复性订阅。可以更新订阅的状态(活动或已取消)以及推迟当前订阅的下一次收费日期。

HTTP 请求

PUT https://api.xsolla.com/merchant/v2/projects/{project_id}/users/{user_id}/subscriptions/{subscription_id}

参数 类型 描述
project_id
int 游戏 ID。
subscription_id
int 订阅 ID。
user_id
string 用户 ID。
status
string 定期支付状态:active / canceled / non_renewing。
cancel_subscription_payment
boolean 如果设为 true,此订阅的最后一次付款将被退回。只有状态更改为“canceled”,此选项才会有效。
timeshift
object 带有续费周期相关数据的对象。
timeshift.value
string 距离续费的时间(可以是负值)。
timeshift.type
string 续费周期类型:日/月。

请求

<?php

$response = $xsollaClient->UpdateSubscription(array(
    'project_id' => PROJECT_ID,
    'user_id' => USER_ID,
    'subscription_id' => SUBSCRIPTION_ID,
    'request' => array (
         'status' => 'canceled',
         'timeshift' =>
             array (
                 'value' => '30',
                 'type' => 'day',
             )
    )
));
PUT /merchant/v2/projects/{project_id}/users/{user_id}/subscriptions/{subscription_id} HTTP/1.1
User-Agent: xsolla-api-client/1.0
Host: api.xsolla.com
Accept: application/json
Authorization: Basic ZGVtb0B4c29sbGEuY29tOmRlbW8=
Content-Type: application/json

{
    "status": "canceled",
    "timeshift": {
         "value": "30",
         "type": "day"
    }
}
$ curl -v 'https://api.xsolla.com/merchant/v2/projects/{project_id}/users/{user_id}/subscriptions/{subscription_id}' \
-X PUT \
-u merchant_id:merchant_api_key \
-H 'Content-Type: application/json' \
-H 'Accept: application/json' \
-d '{
    "status": "canceled",
    "timeshift": {
         "value": "30",
         "type": "day"
    }
}'

响应

<?php

// example response
$response = array (
    'id' => 45,
    'plan' =>
        array (
            'id' => '54',
            'external_id' => 'sample_plan',
            'group_id' => 'USA Products',
            'project_id' => 14004,
            'name' =>
                array (
                    'en' => 'Sample Plan'
                ),
            'description' =>
                array (
                    'en' => 'Basic options plan'
                ),
            'localized_name' => 'Basic Plan',
            'charge' =>
                array (
                    'period' =>
                        array (
                            'value' => 1,
                            'type' => 'month'
                        ),
                    'amount' => 10,
                    'currency' => 'USD'
                ),
            'expiration' =>
                array (
                    'value' => 90,
                    'type' => 'day'
                ),
            'trial' =>
                array (
                    'value' => 14,
                    'type' => 'day'
                ),
            'status' =>
                array (
                    'value' => 'active',
                    'counters' =>
                        array (
                            'active' => 0,
                            'canceled' => 1,
                            'expired' => 0
                        )
                )
        ),
    'user' =>
        array (
            'id' => '20',
        ),
    'product' => null,
    'charge_amount' => 10,
    'currency' => 'USD',
    'date_create' => '2014-09-30T15:34:17+06:00',
    'date_end' => '2014-10-07T15:34:17+06:00',
    'date_last_charge' => '2014-10-01T15:34:17+06:00',
    'date_next_charge' => '2014-11-01T15:34:17+06:00',
    'status' => 'canceled'
);
HTTP/1.1 200 OK
Content-Type: application/json

{
    "id": 45,
    "plan": {
        "id": "54",
        "external_id": "sample_plan",
        "group_id": "USA Products",
        "project_id": 14004,
        "name": {
                "en": "Sample Plan"
        },
        "description": {
            "en": "Basic options plan"
        },
        "localized_name": "Basic Plan",
        "charge": {
            "period": {
                "value": 1,
                "type": "month"
            },
            "amount": 10,
            "currency": "USD"
        },
        "expiration": {
            "value": 90,
            "type": "day"
        },
        "trial": {
            "value": 14,
            "type": "day"
        },
        "status": {
            "value": "active",
            "counters": {
                "active": 0,
                "canceled": 1,
                "expired": 0
            }
        }
    },
    "user": {
        "id": "20"
    },
    "product": null,
    "charge_amount": 10,
    "currency": "USD",
    "date_create": "2014-09-30T15:34:17+06:00",
    "date_end": "2014-10-07T15:34:17+06:00",
    "date_last_charge": "2014-10-01T15:34:17+06:00",
    "date_next_charge": "2014-11-01T15:34:17+06:00",
    "status": "canceled"
}
{
    "id": 45,
    "plan": {
        "id": "54",
        "external_id": "sample_plan",
        "group_id": "USA Products",
        "project_id": 14004,
        "name": {
            "en": "Sample Plan"
        },
        "description": {
            "en": "Basic options plan"
        },
        "localized_name": "Basic Plan",
        "charge": {
            "period": {
                "value": 1,
                "type": "month"
            },
            "amount": 10,
            "currency": "USD"
        },
        "expiration": {
            "value": 90,
            "type": "day"
        },
        "trial": {
            "value": 14,
            "type": "day"
        },
        "status": {
            "value": "active",
            "counters": {
                "active": 0,
                "canceled": 1,
                "expired": 0
            }
        }
    },
    "user": {
        "id": "20"
    },
    "product": null,
    "charge_amount": 10,
    "currency": "USD",
    "date_create": "2014-09-30T15:34:17+06:00",
    "date_end": "2014-10-07T15:34:17+06:00",
    "date_last_charge": "2014-10-01T15:34:17+06:00",
    "date_next_charge": "2014-11-01T15:34:17+06:00",
    "status": "canceled"
}

列示所有订阅

列示所有重复性订阅。

HTTP 请求

GET https://api.xsolla.com/merchant/v2/projects/{project_id}/users/{user_id}/subscriptions

参数 类型 描述
project_id
int 游戏 ID。
user_id
string 用户在游戏中的 ID。
status
string 定期支付状态:active / canceled / non_renewing / new。
limit
int 获取支付的限制。
offset
int 支付列表的起始页面。
datetime_from
datetime 日期范围的开始时间。
datetime_to
datetime 日期范围的结束时间。
plan_id
string 计划 ID。
product_id
string 产品 ID。

请求


<?php

$response = $xsollaClient->ListSubscriptions(array(
    'project_id' => PROJECT_ID,
    'user_id' => USER_ID
));
GET /merchant/v2/projects/{project_id}/users/{user_id}/subscriptions?status=active&limit=1&offset=1&datetime_from=2014-10-01T00%3A00%3A00Z&datetime_to=2014-10-02T00%3A00%3A00Z HTTP/1.1
User-Agent: xsolla-api-client/1.0
Host: api.xsolla.com
Accept: application/json
Authorization: Basic ZGVtb0B4c29sbGEuY29tOmRlbW8=
Content-Type: application/json
$ curl -v 'https://api.xsolla.com/merchant/v2/projects/{project_id}/users/{user_id}/subscriptions?status=active&limit=1&offset=1&datetime_from=2014-10-01T00%3A00%3A00Z&datetime_to=2014-10-02T00%3A00%3A00Z' \
-X GET \
-u merchant_id:merchant_api_key

响应

<?php

// example response
$response = array (
    array (
        'id' => 45,
        'plan' =>
            array (
                'id' => '54',
                'external_id' => 'sample_plan',
                'group_id' => 'USA Products',
                'project_id' => 14004,
                'name' =>
                    array (
                        'en' => 'Sample Plan'
                    ),
                'description' =>
                    array (
                        'en' => 'Basic options plan'
                    ),
                'localized_name' => 'Basic Plan',
                'charge' =>
                    array (
                        'period' =>
                            array (
                                'value' => 1,
                                'type' => 'month'
                            ),
                        'amount' => 10,
                        'currency' => 'USD'
                    ),
                'expiration' =>
                    array (
                        'value' => 90,
                        'type' => 'day'
                    ),
                'trial' =>
                    array (
                        'value' => 14,
                        'type' => 'day'
                    ),
                'status' =>
                    array (
                        'value' => 'disabled',
                        'counters' =>
                            array (
                                'active' => 0,
                                'canceled' => 0,
                                'expired' => 0
                            )
                    )
            ),
        'user' =>
            array (
                'id' => '20'
            ),
        'product' => null,
        'charge_amount' => 10,
        'currency' => 'USD',
        'date_create' => '2014-09-30T15:34:17+04:00',
        'date_end' => '2014-10-07T15:34:17+04:00',
        'date_last_charge' => '2014-10-01T15:34:17+04:00',
        'date_next_charge' => null,
        'status' => 'active'
    )
);
HTTP/1.1 200 OK
Content-Type: application/json

[
    {
        "id": 45,
        "plan": {
            "id": "54",
            "external_id": "sample_plan",
            "group_id": "USA Products",
            "project_id": 14004,
            "name": {
                "en": "Sample Plan"
            },
            "description": {
                "en": "Basic options plan"
            },
            "localized_name": "Basic Plan",
            "charge": {
                "period": {
                    "value": 1,
                    "type": "month"
                },
                "amount": 10,
                "currency": "USD"
            },
            "expiration": {
                "value": 90,
                "type": "day"
            },
            "trial": {
                "value": 14,
                "type": "day"
            },
            "status": {
                "value": "disabled",
                "counters": {
                    "active": 0,
                    "canceled": 0,
                    "expired": 0
                }
            }
        },
        "user": {
            "id": "20"
        },
        "product": null,
        "charge_amount": 10,
        "currency": "USD",
        "date_create": "2014-09-30T15:34:17+04:00",
        "date_end": "2014-10-07T15:34:17+04:00",
        "date_last_charge": "2014-10-01T15:34:17+04:00",
        "date_next_charge": null,
        "status": "active"
    }
]
[
    {
        "id": 45,
        "plan": {
            "id": "54",
            "external_id": "sample_plan",
            "group_id": "USA Products",
            "project_id": 14004,
            "name": {
                "en": "Sample Plan"
            },
            "description": {
                "en": "Basic options plan"
            },
            "localized_name": "Basic Plan",
            "charge": {
                "period": {
                    "value": 1,
                    "type": "month"
                },
                "amount": 10,
                "currency": "USD"
            },
            "expiration": {
                "value": 90,
                "type": "day"
            },
            "trial": {
                "value": 14,
                "type": "day"
            },
            "status": {
                "value": "disabled",
                "counters": {
                    "active": 0,
                    "canceled": 0,
                    "expired": 0
                }
            }
        },
        "user": {
            "id": "20"
        },
        "product": null,
        "charge_amount": 10,
        "currency": "USD",
        "date_create": "2014-09-30T15:34:17+04:00",
        "date_end": "2014-10-07T15:34:17+04:00",
        "date_last_charge": "2014-10-01T15:34:17+04:00",
        "date_next_charge": null,
        "status": "active"
    }
]

列示所有支付

列示所有重复性支付。

HTTP 请求

GET https://api.xsolla.com/merchant/v2/projects/{project_id}/subscriptions/payments

参数 类型 描述
project_id
int 游戏 ID。
user_id
string 用户在项目中的 ID。
status
string 定期支付状态:processing / canceled / done.
limit
int 获取费用列表的限制。
offset
int 费用列表的起始页面。
datetime_from
datetime 日期范围的开始时间。
datetime_to
datetime 日期范围的结束时间。
subscription_id
int 订阅 ID。

请求


<?php

$response = $xsollaClient->ListSubscriptionPayments(array(
    'project_id' => PROJECT_ID
));
GET /merchant/v2/projects/{project_id}/subscriptions/payments?status=done&limit=1&offset=1&datetime_from=2014-10-01T00%3A00%3A00Z&datetime_to=2014-10-02T00%3A00%3A00Z HTTP/1.1
User-Agent: xsolla-api-client/1.0
Host: api.xsolla.com
Accept: application/json
Authorization: Basic ZGVtb0B4c29sbGEuY29tOmRlbW8=
Content-Type: application/json
$ curl -v 'https://api.xsolla.com/merchant/v2/projects/{project_id}/subscriptions/payments?status=done&limit=1&offset=1&datetime_from=2014-10-01T00%3A00%3A00Z&datetime_to=2014-10-02T00%3A00%3A00Z' \
-X GET \
-u merchant_id:merchant_api_key

响应

<?php

// example response
$response = array (
    array (
        'id' => 35,
        'id_payment' => 118441192,
        'date_payment' => '2014-09-30T15:34:17+04:00',
        'status' => 'done',
        'subscription' =>
            array (
                'id' => 45,
                'plan' =>
                    array (
                        'id' => '54',
                        'external_id' => 'sample_plan',
                        'group_id' => 'USA Products',
                        'name' =>
                            array (
                                'en' => 'Sample Plan'
                            ),
                        'description' =>
                            array (
                                'en' => 'Basic options plan'
                            ),
                        'localized_name' => 'Basic Plan',
                        'charge' =>
                            array (
                                'period' =>
                                    array (
                                        'value' => 1,
                                        'type' => 'month'
                                    ),
                                'amount' => 10,
                                'currency' => 'USD'
                            ),
                        'expiration' =>
                            array (
                                'value' => 90,
                                'type' => 'day'
                            ),
                        'trial' =>
                            array (
                                'value' => 14,
                                'type' => 'day'
                            ),
                        'status' =>
                            array (
                                'value' => 'disabled',
                                'counters' =>
                                    array (
                                        'active' => 0,
                                        'closed' => 0,
                                        'expired' => 0
                                    )
                            )
                    ),
                'user' =>
                    array (
                        'id' => 20,
                        'name' => 'John Smith'
                    ),
                'product' => null,
                'charge_amount' => 10,
                'currency' => 'USD',
                'date_create' => '2014-09-30T15:34:17+04:00',
                'date_end' => '2014-10-07T15:34:17+04:00',
                'date_last_charge' => '2014-10-01T15:34:17+04:00',
                'date_next_charge' => '2014-11-01T15:34:17+04:00',
                'status' => 'done'
            )
    )
);
HTTP/1.1 200 OK
Content-Type: application/json

[
    {
        "id": 35,
        "id_payment": 118441192,
        "date_payment": "2014-09-30T15:34:17+04:00",
        "status": "done",
        "subscription": {
            "id": 45,
            "plan": {
                "id": "54",
                "external_id": "sample_plan",
                "group_id": "USA Products",
                "name": {
                    "en": "Sample Plan"
                },
                "description": {
                    "en": "Basic options plan"
                },
                "localized_name": "Basic Plan",
                "charge": {
                    "period": {
                        "value": 1,
                        "type": "month"
                    },
                    "amount": 10,
                    "currency": "USD"
                },
                "expiration": {
                    "value": 90,
                    "type": "day"
                },
                "trial": {
                    "value": 14,
                    "type": "day"
                },
                "status": {
                    "value": "disabled",
                    "counters": {
                        "active": 0,
                        "closed": 0,
                        "expired": 0
                    }
                }
            },
            "user": {
                "id": 20,
                "name": "John Smith"
            },
            "product": null,
            "charge_amount": 10,
            "currency": "USD",
            "date_create": "2014-09-30T15:34:17+04:00",
            "date_end": "2014-10-07T15:34:17+04:00",
            "date_last_charge": "2014-10-01T15:34:17+04:00",
            "date_next_charge": "2014-11-01T15:34:17+04:00",
            "status": "done"
        }
    }
]
[
    {
        "id": 35,
        "id_payment": 118441192,
        "date_payment": "2014-09-30T15:34:17+04:00",
        "status": "done",
        "subscription": {
            "id": 45,
            "plan": {
                "id": "54",
                "external_id": "sample_plan",
                "group_id": "USA Products",
                "name": {
                    "en": "Sample Plan"
                },
                "description": {
                    "en": "Basic options plan"
                },
                "localized_name": "Basic Plan",
                "charge": {
                    "period": {
                        "value": 1,
                        "type": "month"
                    },
                    "amount": 10,
                    "currency": "USD"
                },
                "expiration": {
                    "value": 90,
                    "type": "day"
                },
                "trial": {
                    "value": 14,
                    "type": "day"
                },
                "status": {
                    "value": "disabled",
                    "counters": {
                        "active": 0,
                        "closed": 0,
                        "expired": 0
                    }
                }
            },
            "user": {
                "id": 20,
                "name": "John Smith"
            },
            "product": null,
            "charge_amount": 10,
            "currency": "USD",
            "date_create": "2014-09-30T15:34:17+04:00",
            "date_end": "2014-10-07T15:34:17+04:00",
            "date_last_charge": "2014-10-01T15:34:17+04:00",
            "date_next_charge": "2014-11-01T15:34:17+04:00",
            "status": "done"
        }
    }
]

按用户列示所有支付

按用户列示所有重复性支付。

HTTP 请求

GET https://api.xsolla.com/merchant/v2/projects/{project_id}/users/{user_id}/subscriptions/payments

参数 类型 描述
project_id
int 游戏 ID。
user_id
string 用户在项目中的 ID。
status
string 定期支付状态:processing / canceled / done.
limit
int 获取费用列表的限制。
offset
int 费用列表的起始页面。
datetime_from
datetime 日期范围的开始时间。
datetime_to
datetime 日期范围的结束时间。
subscription_id
int 订阅 ID。

请求


<?php

$response = $xsollaClient->ListUserSubscriptionPayments(array(
    'project_id' => PROJECT_ID,
    'user_id' => USER_ID
));
GET /merchant/v2/projects/{project_id}/users/{user_id}/subscriptions/payments?status=done&limit=1&offset=1&datetime_from=2014-10-01T00%3A00%3A00Z&datetime_to=2014-10-02T00%3A00%3A00Z HTTP/1.1
User-Agent: xsolla-api-client/1.0
Host: api.xsolla.com
Accept: application/json
Authorization: Basic ZGVtb0B4c29sbGEuY29tOmRlbW8=
Content-Type: application/json
$ curl -v 'https://api.xsolla.com/merchant/v2/projects/{project_id}/users/{user_id}/subscriptions/payments?status=done&limit=1&offset=1&datetime_from=2014-10-01T00%3A00%3A00Z&datetime_to=2014-10-02T00%3A00%3A00Z' \
-X GET \
-u merchant_id:merchant_api_key

响应

<?php

// example response
$response = array (
    array (
        'id' => 35,
        'id_payment' => 118441192,
        'date_payment' => '2014-09-30T15:34:17+04:00',
        'status' => 'done',
        'subscription' =>
            array (
                'id' => 45,
                'plan' =>
                    array (
                        'id' => '54',
                        'external_id' => 'sample_plan',
                        'group_id' => 'USA Products',
                        'project_id' => 14004,
                        'name' =>
                            array (
                                'en' => 'Sample Plan'
                            ),
                        'description' =>
                            array (
                                'en' => 'Basic options plan'
                            ),
                        'localized_name' => 'Basic Plan',
                        'charge' =>
                            array (
                                'period' =>
                                    array (
                                        'value' => 1,
                                        'type' => 'month'
                                    ),
                                'amount' => 10,
                                'currency' => 'USD'
                            ),
                        'expiration' =>
                            array (
                                'value' => 90,
                                'type' => 'day'
                            ),
                        'trial' =>
                            array (
                                'value' => 14,
                                'type' => 'day'
                            ),
                        'status' =>
                            array (
                                'value' => 'disabled',
                                'counters' =>
                                    array (
                                        'active' => 0,
                                        'closed' => 0,
                                        'expired' => 0
                                    )
                            )
                    ),
                'user' =>
                    array (
                        'id' => 20,
                        'name' => 'John Smith'
                    ),
                'product' => null,
                'charge_amount' => 10,
                'currency' => 'USD',
                'date_create' => '2014-09-30T15:34:17+04:00',
                'date_end' => '2014-10-07T15:34:17+04:00',
                'date_last_charge' => '2014-10-01T15:34:17+04:00',
                'date_next_charge' => '2014-11-01T15:34:17+04:00',
                'status' => 'done'
            )
    )
);
HTTP/1.1 200 OK
Content-Type: application/json

[
    {
        "id": 35,
        "id_payment": 118441192,
        "date_payment": "2014-09-30T15:34:17+04:00",
        "status": "done",
        "subscription": {
            "id": 45,
            "plan": {
                "id": "54",
                "external_id": "sample_plan",
                "group_id": "USA Products",
                "project_id": 14004,
                "name": {
                    "en": "Sample Plan"
                },
                "description": {
                    "en": "Basic options plan"
                },
                "localized_name": "Basic Plan",
                "charge": {
                    "period": {
                        "value": 1,
                        "type": "month"
                    },
                    "amount": 10,
                    "currency": "USD"
                },
                "expiration": {
                    "value": 90,
                    "type": "day"
                },
                "trial": {
                    "value": 14,
                    "type": "day"
                },
                "status": {
                    "value": "disabled",
                    "counters": {
                        "active": 0,
                        "closed": 0,
                        "expired": 0
                    }
                }
            },
            "user": {
                "id": 20,
                "name": "John Smith"
            },
            "product": null,
            "charge_amount": 10,
            "currency": "USD",
            "date_create": "2014-09-30T15:34:17+04:00",
            "date_end": "2014-10-07T15:34:17+04:00",
            "date_last_charge": "2014-10-01T15:34:17+04:00",
            "date_next_charge": "2014-11-01T15:34:17+04:00",
            "status": "done"
        }
    }
]
[
    {
        "id": 35,
        "id_payment": 118441192,
        "date_payment": "2014-09-30T15:34:17+04:00",
        "status": "done",
        "subscription": {
            "id": 45,
            "plan": {
                "id": "54",
                "external_id": "sample_plan",
                "group_id": "USA Products",
                "project_id": 14004,
                "name": {
                    "en": "Sample Plan"
                },
                "description": {
                    "en": "Basic options plan"
                },
                "localized_name": "Basic Plan",
                "charge": {
                    "period": {
                        "value": 1,
                        "type": "month"
                    },
                    "amount": 10,
                    "currency": "USD"
                },
                "expiration": {
                    "value": 90,
                    "type": "day"
                },
                "trial": {
                    "value": 14,
                    "type": "day"
                },
                "status": {
                    "value": "disabled",
                    "counters": {
                        "active": 0,
                        "closed": 0,
                        "expired": 0
                    }
                }
            },
            "user": {
                "id": 20,
                "name": "John Smith"
            },
            "product": null,
            "charge_amount": 10,
            "currency": "USD",
            "date_create": "2014-09-30T15:34:17+04:00",
            "date_end": "2014-10-07T15:34:17+04:00",
            "date_last_charge": "2014-10-01T15:34:17+04:00",
            "date_next_charge": "2014-11-01T15:34:17+04:00",
            "status": "done"
        }
    }
]

列示所有货币

列示所有重复性货币。

HTTP 请求

GET https://api.xsolla.com/merchant/v2/projects/{project_id}/subscriptions/currencies

参数 类型 描述
project_id
int 游戏 ID。

请求


<?php

$response = $xsollaClient->ListSubscriptionCurrencies(array(
    'project_id' => PROJECT_ID
));
GET /merchant/v2/projects/{project_id}/subscriptions/currencies HTTP/1.1
User-Agent: xsolla-api-client/1.0
Host: api.xsolla.com
Accept: application/json
Authorization: Basic ZGVtb0B4c29sbGEuY29tOmRlbW8=
Content-Type: application/json
$ curl -v 'https://api.xsolla.com/merchant/v2/projects/{project_id}/subscriptions/currencies' \
-X GET \
-u merchant_id:merchant_api_key

响应

<?php

// example response
$response = array(
    "AED",
    "ALL",
    "AMD",
    "ARS",
    "AUD",
    "AZN",
    "BGN",
    "BRL",
    "BYR",
    "CAD",
    "CHF",
    "CLP",
    "CNY",
    "COP",
    "CZK",
    "DKK",
    "DZD",
    "EGP",
    "EUR",
    "GBP",
    "GEL",
    "HKD",
    "HRK",
    "HUF",
    "IDR",
    "ILS",
    "INR",
    "JPY",
    "KES",
    "KGS",
    "KRW",
    "KZT",
    "MAD",
    "MDL",
    "MKD",
    "MNT",
    "MXN",
    "MYR",
    "NGN",
    "NOK",
    "NZD",
    "PEN",
    "PHP",
    "PKR",
    "PLN",
    "RON",
    "RSD",
    "RUB",
    "SAR",
    "SEK",
    "SGD",
    "THB",
    "TRY",
    "UAH",
    "USD",
    "UYU",
    "UZS",
    "VND",
    "ZAR"
);
HTTP/1.1 200 OK
Content-Type: application/json

[
    "AED",
    "ALL",
    "AMD",
    "ARS",
    "AUD",
    "AZN",
    "BGN",
    "BRL",
    "BYR",
    "CAD",
    "CHF",
    "CLP",
    "CNY",
    "COP",
    "CZK",
    "DKK",
    "DZD",
    "EGP",
    "EUR",
    "GBP",
    "GEL",
    "HKD",
    "HRK",
    "HUF",
    "IDR",
    "ILS",
    "INR",
    "JPY",
    "KES",
    "KGS",
    "KRW",
    "KZT",
    "MAD",
    "MDL",
    "MKD",
    "MNT",
    "MXN",
    "MYR",
    "NGN",
    "NOK",
    "NZD",
    "PEN",
    "PHP",
    "PKR",
    "PLN",
    "RON",
    "RSD",
    "RUB",
    "SAR",
    "SEK",
    "SGD",
    "THB",
    "TRY",
    "UAH",
    "USD",
    "UYU",
    "UZS",
    "VND",
    "ZAR"
]
[
    "AED",
    "ALL",
    "AMD",
    "ARS",
    "AUD",
    "AZN",
    "BGN",
    "BRL",
    "BYR",
    "CAD",
    "CHF",
    "CLP",
    "CNY",
    "COP",
    "CZK",
    "DKK",
    "DZD",
    "EGP",
    "EUR",
    "GBP",
    "GEL",
    "HKD",
    "HRK",
    "HUF",
    "IDR",
    "ILS",
    "INR",
    "JPY",
    "KES",
    "KGS",
    "KRW",
    "KZT",
    "MAD",
    "MDL",
    "MKD",
    "MNT",
    "MXN",
    "MYR",
    "NGN",
    "NOK",
    "NZD",
    "PEN",
    "PHP",
    "PKR",
    "PLN",
    "RON",
    "RSD",
    "RUB",
    "SAR",
    "SEK",
    "SGD",
    "THB",
    "TRY",
    "UAH",
    "USD",
    "UYU",
    "UZS",
    "VND",
    "ZAR"
]

列示所有用户属性

获取用户属性列表

HTTP 请求

GET https://api.xsolla.com/merchant/v2/projects/{project_id}/user_attributes

参数 类型 描述
project_id
int 游戏 ID。

请求


<?php

$response = $xsollaClient->ListUserAttributes(array(
    'project_id' => PROJECT_ID
));
GET /merchant/v2/projects/{project_id}/user_attributes HTTP/1.1
User-Agent: xsolla-api-client/1.0
Host: api.xsolla.com
Accept: application/json
Authorization: Basic ZGVtb0B4c29sbGEuY29tOmRlbW8=
$ curl -v 'https://api.xsolla.com/merchant/v2/projects/{project_id}/user_attributes' \
-X GET \
-u merchant_id:merchant_api_key

响应

<?php

// example response
$response = array (
    array (
        'id' => 2,
        'key' => 'level',
        'localized_name' =>
            array (
                'en' => 'Level'
            ),
        'name' => 'Level',
        'type' => 'int',
        'list_of_values' =>
            array (
            ),
        'visible' => true,
        'skip_condition_on_nonexistent_key' => false
    ),
    array (
        'id' => 3,
        'key' => 'class',
        'localized_name' =>
            array (
            )
        'name' => null,
        'type' => 'string',
        'list_of_values' =>
            array (
            ),
        'visible' => true,
        'skip_condition_on_nonexistent_key' => false
    ),
    array (
        'id' => 4,
        'key' => 'type',
        'localized_name' =>
            array (
            )
        'name' => null,
        'type' => 'enum',
        'list_of_values' =>
            array (
                0 => 'class1',
                1 => 'class2',
                2 => 'class3'
            ),
        'visible' => true,
        'skip_condition_on_nonexistent_key' => false
    ),
    array (
        'id' => 5,
        'key' => 'date',
        'localized_name' =>
            array (
                'en' => 'Date'
            ),
        'name' => 'Date',
        'type' => 'date',
        'list_of_values' =>
            array (
            ),
        'visible' => true,
        'skip_condition_on_nonexistent_key' => false
    )
);
HTTP/1.1 200 OK
Content-Type: application/json
[
    {
        "id": 2,
        "key": "level",
        "localized_name": {
            "en": "Level"
        },
        "name": "Level",
        "type": "int",
        "list_of_values": [],
        "visible":true,
        "skip_condition_on_nonexistent_key": false
    },
    {
        "id": 3,
        "key": "class",
        "localized_name": [],
        "name": null,
        "type": "string",
        "list_of_values": [],
        "visible":true
    },
    {
        "id": 4,
        "key": "type",
        "localized_name": [],
        "name": null,
        "type": "enum",
        "list_of_values": [
            "class1",
            "class2",
            "class3"
        ],
        "visible":true,
        "skip_condition_on_nonexistent_key": false
    },
    {
        "id": 5,
        "key": "date",
        "localized_name": {
            "en": "Date"
        },
        "name": "Date",
        "type": "date",
        "list_of_values": [],
        "visible":true,
        "skip_condition_on_nonexistent_key": false
    }
]
[
    {
        "id": 2,
        "key": "level",
        "localized_name": {
            "en": "Level"
        },
        "name": "Level",
        "type": "int",
        "list_of_values": [],
        "visible":true,
        "skip_condition_on_nonexistent_key": false
    },
    {
        "id": 3,
        "key": "class",
        "localized_name": [],
        "name": null,
        "type": "string",
        "list_of_values": [],
        "visible":true,
        "skip_condition_on_nonexistent_key": false
    },
    {
        "id": 4,
        "key": "type",
        "localized_name": [],
        "name": null,
        "type": "enum",
        "list_of_values": [
            "class1",
            "class2",
            "class3"
        ],
        "visible":true,
        "skip_condition_on_nonexistent_key": false
    },
    {
        "id": 5,
        "key": "date",
        "localized_name": {
            "en": "Date"
        },
        "name": "Date",
        "type": "date",
        "list_of_values": [],
        "visible":true,
        "skip_condition_on_nonexistent_key": false
    }
]

获取用户属性

显示用户属性

HTTP 请求

GET https://api.xsolla.com/merchant/v2/projects/{project_id}/user_attributes/{user_attribute_id}

参数 类型 描述
project_id
int 游戏 ID。
user_attribute_id
int 用户属性 ID。

请求


<?php

$response = $xsollaClient->GetUserAttribute(array(
    'project_id' => PROJECT_ID,
    'user_attribute_id' => USER_ATTRIBUTE_ID
));
GET /merchant/v2/projects/{project_id}/user_attributes/{user_attribute_id} HTTP/1.1
User-Agent: xsolla-api-client/1.0
Host: api.xsolla.com
Accept: application/json
Authorization: Basic ZGVtb0B4c29sbGEuY29tOmRlbW8=
$ curl -v 'https://api.xsolla.com/merchant/v2/projects/{project_id}/user_attributes/{user_attribute_id}' \
-X GET \
-u merchant_id:merchant_api_key

响应

<?php

// example response
$response = array (
    'id' => 2,
    'key' => 'level',
    'localized_name' =>
        array (
            'en' => 'level',
            'de' => 'niveau'
        ),
    'name' => 'Level',
    'type' => 'int',
    'list_of_values' =>
        array (),
    'visible' => true,
    'skip_condition_on_nonexistent_key' => false
);
HTTP/1.1 200 OK
Content-Type: application/json
{
    "id": 2,
    "key": "level",
    "localized_name": {
        "en": "level",
        "de": "niveau"
    },
    "name": "Level",
    "type": "int",
    "list_of_values": [],
    "visible":true,
    "skip_condition_on_nonexistent_key": false
}
{
    "id": 2,
    "key": "level",
    "localized_name": {
        "en": "level",
        "de": "niveau"
    },
    "name": "Level",
    "type": "int",
    "list_of_values": [],
    "visible":true,
    "skip_condition_on_nonexistent_key": false
}

创建用户属性

创建用户属性。

HTTP 请求

POST https://api.xsolla.com/merchant/v2/projects/{project_id}/user_attributes

参数 类型 描述
project_id
int 游戏 ID。必要。
key
string 用户属性键值。必要。
name
array of strings 用户属性本地化名称的数组。必要。
类型
string 键值类型。可以是“int”、“string”、“enum”或“date”。必要。
list_of_values
array enum 类型可能值的数组。必要。
skip_condition_on_nonexistent_key
boolean 键值不存在时是否应跳过条件。

请求

<?php

$response = $xsollaClient->CreateUserAttribute(array(
    'project_id' => PROJECT_ID,
    'request' => array (
         'key' => 'class',
         'name' =>
             array (
                 'en' => 'Сlass',
                 'de' => 'Classe',
             ),
         'type' => 'enum',
         'list_of_values' =>
             array (
                 'Warrior',
                 'magic',
             ),
     )
));
POST /merchant/v2/projects/{project_id}/user_attributes HTTP/1.1
User-Agent: xsolla-api-client/1.0
Host: api.xsolla.com
Accept: application/json
Authorization: Basic ZGVtb0B4c29sbGEuY29tOmRlbW8=
Content-Type: application/json
{
    "key": "class",
    "name": {
        "en": "Сlass",
        "de": "Classe"
    },
    "type": "enum",
    "list_of_values": ["Warrior", "magic"],
    "visible":true
}
$ curl -v 'https://api.xsolla.com/merchant/v2/projects/{project_id}/user_attributes' \
-X POST \
-u merchant_id:merchant_api_key \
-H 'Content-Type: application/json' \
-H 'Accept: application/json' \
-d '{
    "key": "class",
    "name": {
        "en": "Сlass",
        "de": "Classe"
    },
    "type": "enum",
    "list_of_values": ["Warrior", "magic"],
    "visible":true
}'

响应

<?php

// example response
$response = array (
    'id' => 77
);
HTTP/1.1 201 Created
Content-Type: application/json

{
    "id": 77
}
{
    "id": 77
}

更新用户属性

更新用户属性。

HTTP 请求

PUT https://api.xsolla.com/merchant/v2/projects/{project_id}/user_attributes/{user_attribute_id}

参数 类型 描述
project_id
int 游戏 ID。必要。
user_attribute_id
int User attribute ID.
key
string 用户属性键值。必要。
name
array of strings 用户属性本地化名称的数组。必要。
type
string 键值类型。可以是“int”、“string”、“enum”或“date”。必要。
list_of_values
array enum 类型可能值的数组。必要。
skip_condition_on_nonexistent_key
boolean 键值不存在时是否应跳过条件。

请求

<?php

$response = $xsollaClient->UpdateUserAttribute(array(
    'project_id' => PROJECT_ID,
    'user_attribute_id' => USER_ATTRIBUTE_ID,
    'request' => array(
         'key' => 'class',
         'name' =>
             array (
                 'en' => 'Сlass',
                 'de' => 'Classe',
             ),
         'type' => 'enum',
         'list_of_values' =>
             array (
                 'Warrior',
                 'magic',
             ),
         'skip_condition_on_nonexistent_key' => false
     )
));
PUT /merchant/v2/projects/{project_id}/user_attributes/{user_attribute_id} HTTP/1.1
User-Agent: xsolla-api-client/1.0
Host: api.xsolla.com
Accept: application/json
Authorization: Basic ZGVtb0B4c29sbGEuY29tOmRlbW8=
Content-Type: application/json
{
    "key": "class",
    "localized_name": {
        "en": "Сlass",
        "de": "Classe"
    },
    "type": "enum",
    "list_of_values": ["Warrior", "magic"],
    "visible":true,
    "skip_condition_on_nonexistent_key": false
}
$ curl -v 'https://api.xsolla.com/merchant/v2/projects/{project_id}/user_attributes/{user_attribute_id}' \
-X PUT \
-u merchant_id:merchant_api_key \
-H 'Content-Type: application/json' \
-H 'Accept: application/json' \
-d '{
    "key": "class",
    "localized_name": {
        "en": "Сlass",
        "de": "Classe"
    },
    "type": "enum",
    "list_of_values": ["Warrior", "magic"],
    "visible":true,
    "skip_condition_on_nonexistent_key": false
}'

响应

<?php

$response = null;
HTTP/1.1 204 No Content

删除用户属性

删除用户属性。

HTTP 请求

DELETE https://api.xsolla.com/merchant/v2/projects/{project_id}/user_attributes/{user_attribute_id}

参数 类型 描述
project_id
int 游戏 ID。
user_attribute_id
int 用户属性 ID。

请求


<?php

$response = $xsollaClient->DeleteUserAttribute(array(
    'project_id' => PROJECT_ID,
    'user_attribute_id' => USER_ATTRIBUTE_ID
));
DELETE /merchant/v2/projects/{project_id}/user_attributes/{user_attribute_id} HTTP/1.1
User-Agent: xsolla-api-client/1.0
Host: api.xsolla.com
Accept: application/json
Authorization: Basic ZGVtb0B4c29sbGEuY29tOmRlbW8=
Content-Type: application/json
$ curl -v 'https://api.xsolla.com/merchant/v2/projects/{project_id}/user_attributes/{user_attribute_id}' \
-X DELETE \
-u merchant_id:merchant_api_key

响应

<?php

$response = null;
HTTP/1.1 204 No Content

创建物品

创建虚拟物品。

HTTP 请求

POST https://api.xsolla.com/merchant/v2/projects/{project_id}/virtual_items/items

参数 类型 描述
project_id
int 游戏 ID。
sku
string 物品唯一 ID。SKU 必须仅包含小写拉丁字母、数字、破折号和下划线。
item_code
string 物品附加码。可选。
name
array of strings 物品本地化名称的数组。
description
array of strings 物品本地化简单描述的数组。
long_description
array of strings 物品本地化详细描述的数组。
prices
array 物品价格的数组。
default_currency
string 默认的购买币种。使用 ISO 4217 规定的 3 字母组合表示货币。
enabled
boolean 对购买启用。
permanent
boolean 用户是否可以多次购买物品。
image_url
string 图像 URL。
item_type
string 物品类型:Consumable / Expiration / Permanent / Lootboxes / Physical
expiration
int 过期时间(秒)。仅用于“Expiration”物品类型
groups
array of integers 物品组列表。
deleted
boolean 此物品是否已被删除。
user_attribute_conditions
array of objects 用户属性条件列表。
user_attribute_conditions.right_operand
array of values 与当前用户属性值相比较的值
user_attribute_conditions.user_attribute_key
string 用户属性条件键值。
user_attribute_conditions.operation
string 比较操作类型。可以是“greater”、“greaterOrEqual”、“equal”、“notEqual”、“less”、“lessOrEqual”、“between”、“in”、“notIn”。
user_attribute_conditions.action
string 动作类型。可以是“hide”、“block”或“warning”
advertisement_type
string 特殊标签会在支付 UI 中显示。可以是“recommended”、“best_deal”、“special_offer”或null。
virtual_currency_price
int 使用虚拟货币表示的物品价格。如果仅可以用真实货币购买物品,则为null。
purchase_limit
int 您可以购买此物品的次数。如果无限制,则为null。
keywords
array 在支付 UI 中搜索物品所用的关键词。

请求

<?php

$response = $xsollaClient->CreateVirtualItem(array(
    'project_id' => PROJECT_ID,
    'request' => array (
         'sku' => 'T-43-3-unique-id',
         'item_code' => 'chinese-medium-tank',
         'name' =>
             array (
                 'en' => 'T-34-3',
             ),
         'description' =>
             array (
                 'en' => 'Chinese Tier VIII medium tank.',
             ),
         'long_description' =>
             array (
                 'en' => 'This Chinese Tier VIII medium tank is a real beast in its class.',
             ),
         'prices' =>
             array (
                 'USD' => 40.09,
             ),
         'default_currency' => 'USD',
         'enabled' => true,
         'permanent' => false,
         'image_url' => 'http://livedemo.xsolla.com/airplanes/tank5.jpg',
         'item_type' => 'Expiration',
         'expiration' => 1296000,
         'groups' =>
             array (
                 24,
                 25,
             ),
         'user_attribute_conditions' =>
             array (
             array (
                     'right_operand' =>
                         array (
                             'magic',
                         ),
                     'id' => 2015,
                     'user_attribute_key' => 'type',
                     'operation' => 'equal',
                     'action' => 'hide',
                     'name' => null,
                 ),
             ),
         'virtual_currency_price' => null,
         'purchase_limit' => null,
         'keywords' =>
             array (
                 'de' =>
                     array (
                         'Inhalt',
                         'Aufgaben',
                         'Region',
                         'Landschaft',
                     ),
                 'en' =>
                     array (
                         'content',
                         'quests',
                         'region',
                         'landscape',
                     ),
             ),
         'advertisement_type' => 'recommended',
         'deleted' => false,
    )
));
POST /merchant/v2/projects/{project_id}/virtual_items/items HTTP/1.1
User-Agent: xsolla-api-client/1.0
Host: api.xsolla.com
Accept: application/json
Authorization: Basic ZGVtb0B4c29sbGEuY29tOmRlbW8=
Content-Type: application/json

{
    "sku": "T-43-3-unique-id",
    "item_code": "chinese-medium-tank",
    "name": {
        "en": "T-34-3"
    },
    "description": {
        "en": "Chinese Tier VIII medium tank."
    },
    "long_description": {
            "en": "This Chinese Tier VIII medium tank is a real beast in its class."
    },
    "prices": {
        "USD": 40.09
    },
    "default_currency": "USD",
    "enabled": true,
    "permanent": false,
    "image_url": "http:\/\/livedemo.xsolla.com\/airplanes\/tank5.jpg",
    "item_type": "Expiration",
    "expiration": 1296000,
    "groups": [
        24,
        25
    ],
    "user_attribute_conditions": [
         {
             "right_operand": [
                 "magic"
             ],
             "id": 2015,
             "user_attribute_key": "type",
             "operation": "equal",
             "action": "hide",
             "name":null
         }
    ],
    "virtual_currency_price": null,
    "purchase_limit": null,
    "keywords": {
        "de":[
            "Inhalt","Aufgaben","Region","Landschaft"
        ],
        "en":[
            "content","quests","region","landscape"
        ]
    },
    "advertisement_type": "recommended",
    "deleted": false
}
$ curl -v 'https://api.xsolla.com/merchant/v2/projects/{project_id}/virtual_items/items' \
-X POST \
-u merchant_id:merchant_api_key \
-H 'Content-Type: application/json' \
-H 'Accept: application/json' \
-d '{
    "sku": "T-43-3-unique-id",
    "item_code": "chinese-medium-tank",
    "name": {
        "en": "T-34-3"
    },
    "description": {
        "en": "Chinese Tier VIII medium tank."
    },
    "long_description": {
            "en": "This Chinese Tier VIII medium tank is a real beast in its class."
    },
    "prices": {
        "USD": 40.09
    },
    "default_currency": "USD",
    "enabled": true,
    "permanent": false,
    "image_url": "http:\/\/livedemo.xsolla.com\/airplanes\/tank5.jpg",
    "item_type": "Expiration",
    "expiration": 1296000,
    "groups": [
        24,
        25
    ],
    "user_attribute_conditions": [
         {
             "right_operand": [
                 "magic"
             ],
             "id": 2015,
             "user_attribute_key": "type",
             "operation": "equal",
             "action": "hide",
             "name":null
         }
    ],
    "virtual_currency_price": null,
    "purchase_limit": null,
    "keywords": {
        "de":[
            "Inhalt","Aufgaben","Region","Landschaft"
        ],
        "en":[
            "content","quests","region","landscape"
        ]
    },
    "advertisement_type": "recommended",
    "deleted": false
}'

响应

<?php

// example response
$response = array (
    'item_id' => 77
);
HTTP/1.1 201 Created
Content-Type: application/json

{
    "item_id": 77
}
{
    "item_id": 77
}

获取物品

获取虚拟物品。

HTTP 请求

GET https://api.xsolla.com/merchant/v2/projects/{project_id}/virtual_items/items/{item_id}

参数 类型 描述
item_id
int 物品 ID。

请求


<?php

$response = $xsollaClient->GetVirtualItem(array(
    'project_id' => PROJECT_ID,
    'item_id' => ITEM_ID
));
GET /merchant/v2/projects/{project_id}/virtual_items/items/{item_id} HTTP/1.1
User-Agent: xsolla-api-client/1.0
Host: api.xsolla.com
Accept: application/json
Authorization: Basic ZGVtb0B4c29sbGEuY29tOmRlbW8=
Content-Type: application/json
$ curl -v 'https://api.xsolla.com/merchant/v2/projects/{project_id}/virtual_items/items/{item_id}' \
-X GET \
-u merchant_id:merchant_api_key

响应

<?php

// example response
$response = array (
    'id' => 77,
    'sku' => 'T-43-3-unique-id',
    'item_code' => 'chinese-medium-tank',
    'name' =>
        array (
            'en' => 'T-34-3'
        ),
    'description' =>
        array (
            'en' => 'Chinese Tier VIII medium tank.'
        ),
    'long_description' =>
        array (
            'en' => 'This Chinese Tier VIII medium tank is a real beast in its class.'
        ),
    'prices' =>
        array (
            'USD' => 40.09
        ),
    'default_currency' => 'USD',
    'enabled' => true,
    'permanent' => false,
    'image_url' => 'http://livedemo.xsolla.com/airplanes/tank5.jpg',
    'item_type' => 'Expiration',
    'expiration' => 1296000,
    'groups' =>
        array (
            24,
            25
        ),
    'user_attribute_conditions' =>
        array (
        array (
                'right_operand' =>
                     array (
                        'magic',
                    ),
                'id' => 2015,
                'user_attribute_key' => 'type',
                'operation' => 'equal',
                'action' => 'hide',
                'name' => null,
            ),
        ),
    'virtual_currency_price' => null,
    'purchase_limit' => null,
    'keywords' =>
        array (
            'de' =>
                array (
                    'Inhalt',
                    'Aufgaben',
                    'Region',
                    'Landschaft',
                ),
            'en' =>
                array (
                    'content',
                    'quests',
                    'region',
                    'landscape',
                ),
        ),
    'advertisement_type' => 'recommended',
    'deleted' => false,
);
HTTP/1.1 200 OK
Content-Type: application/json

{
    "id": 77,
    "sku": "T-43-3-unique-id",
    "item_code": "chinese-medium-tank",
    "name": {
        "en": "T-34-3"
    },
    "description": {
        "en": "Chinese Tier VIII medium tank."
    },
    "long_description": {
            "en": "This Chinese Tier VIII medium tank is a real beast in its class."
    },
    "prices": {
        "USD": 40.09
    },
    "default_currency": "USD",
    "enabled": true,
    "permanent": false,
    "image_url": "http:\/\/livedemo.xsolla.com\/airplanes\/tank5.jpg",
    "item_type": "Expiration",
    "expiration": 1296000,
    "groups": [
        24,
        25
    ],
    "user_attribute_conditions": [
         {
             "right_operand": [
                 "magic"
             ],
             "id": 2015,
             "user_attribute_key": "type",
             "operation": "equal",
             "action": "hide",
             "name":null
         }
    ],
    "virtual_currency_price": null,
    "purchase_limit": null,
    "keywords": {
        "de":[
            "Inhalt","Aufgaben","Region","Landschaft"
        ],
        "en":[
            "content","quests","region","landscape"
        ]
    },
    "advertisement_type": "recommended",
    "deleted": false
}
{
    "id": 77,
    "sku": "T-43-3-unique-id",
    "item_code": "chinese-medium-tank",
    "name": {
        "en": "T-34-3"
    },
    "description": {
        "en": "Chinese Tier VIII medium tank."
    },
    "long_description": {
            "en": "This Chinese Tier VIII medium tank is a real beast in its class."
    },
    "prices": {
        "USD": 40.09
    },
    "default_currency": "USD",
    "enabled": true,
    "permanent": false,
    "image_url": "http:\/\/livedemo.xsolla.com\/airplanes\/tank5.jpg",
    "item_type": "Expiration",
    "expiration": 1296000,
    "groups": [
        24,
        25
    ],
    "user_attribute_conditions": [
         {
             "right_operand": [
                 "magic"
             ],
             "id": 2015,
             "user_attribute_key": "type",
             "operation": "equal",
             "action": "hide",
             "name":null
         }
    ],
    "virtual_currency_price": null,
    "purchase_limit": null,
    "keywords": {
        "de":[
            "Inhalt","Aufgaben","Region","Landschaft"
        ],
        "en":[
            "content","quests","region","landscape"
        ]
    },
    "advertisement_type": "recommended",
    "deleted": false
}

更新物品

更新虚拟物品。

HTTP 请求

PUT https://api.xsolla.com/merchant/v2/projects/{project_id}/virtual_items/items/{item_id}

参数 类型 描述
item_id
int ID 项目。
sku
string 物品的唯一 ID。SKU 只能包含小写拉丁字符、数字、连接号和下划线。
item_code
string 物品附加代码。可选。
name
array of strings 物品本地化名称的数组。
description
array of strings 物品本地化描述的数组。
prices
array 物品价格数组。
default_currency
string 购买使用的默认币种。使用 ISO 4217 标准规定的三字母组合表示币种。
enabled
boolean 对购买启用。
permanent
boolean 用户是否可以多次购买物品。
item_type
string 物品的类型:Consumable / Expiration / Permanent / Lootboxes / Physical
expiration
int 过期时间(秒)。仅用于'Expiration'物品类型。
groups
array of integers 物品组列表。
deleted
boolean 物品是否已被删除。
user_attribute_conditions
array of objects 用户属性条件列表。
user_attribute_conditions.right_operand
array of values 用于与当前用户属性值进行比较的值。
user_attribute_conditions.user_attribute_key
string 用户属性条件的键值。
user_attribute_conditions.operation
string 比较运算的类型。可以是'greater'、'greaterOrEqual'、'equal'、'notEqual'、'less'、'lessOrEqual'、'between'、'in'、'notIn'。
user_attribute_conditions.action
string 动作类型。可以是“hide”、“block”或“warning”。
advertisement_type
string 特殊标签会在支付 UI 中显示。可以是“recommended”、“best_deal”或null。
virtual_currency_price
int 使用虚拟货币表示的物品价格。如果仅可以用真实货币购买物品,则为null。
purchase_limit
int 您可以购买此物品的次数。如果无限制,则为null。
keywords
array 在支付 UI 中搜索物品所用的关键词。

请求

<?php

$response = $xsollaClient->UpdateVirtualItem(array(
    'project_id' => PROJECT_ID,
    'request' => array (
         'sku' => 'T-43-3-unique-id',
         'item_code' => 'chinese-medium-tank',
         'name' =>
             array (
                 'en' => 'T-34-3',
             ),
         'description' =>
             array (
                 'en' => 'Chinese Tier VIII medium tank.',
             ),
         'long_description' =>
             array (
                 'en' => 'This Chinese Tier VIII medium tank is a real beast in its class.',
             ),
         'prices' =>
             array (
                 'USD' => 40.09,
             ),
         'default_currency' => 'USD',
         'enabled' => true,
         'permanent' => false,
         'image_url' => 'http://livedemo.xsolla.com/airplanes/tank5.jpg',
         'item_type' => 'Expiration',
         'expiration' => 1296000,
         'groups' =>
             array (
                 24,
                 25,
             ),
         'user_attribute_conditions' =>
             array (
             array (
                     'right_operand' =>
                         array (
                             'magic',
                         ),
                     'id' => 2015,
                     'user_attribute_key' => 'type',
                     'operation' => 'equal',
                     'action' => 'hide',
                     'name' => null,
                 ),
             ),
         'virtual_currency_price' => null,
         'purchase_limit' => null,
         'keywords' =>
             array (
                 'de' =>
                     array (
                         'Inhalt',
                         'Aufgaben',
                         'Region',
                         'Landschaft',
                     ),
                 'en' =>
                     array (
                         'content',
                         'quests',
                         'region',
                         'landscape',
                     ),
             ),
         'advertisement_type' => 'recommended',
         'deleted' => false,
    )
));
PUT /merchant/v2/projects/{project_id}/virtual_items/items/{item_id} HTTP/1.1
User-Agent: xsolla-api-client/1.0
Host: api.xsolla.com
Accept: application/json
Authorization: Basic ZGVtb0B4c29sbGEuY29tOmRlbW8=
Content-Type: application/json
{
    "sku": "T-43-3-unique-id",
    "item_code": "chinese-medium-tank",
    "name": {
        "en": "T-34-3"
    },
    "description": {
        "en": "Chinese Tier VIII medium tank."
    },
    "long_description": {
            "en": "This Chinese Tier VIII medium tank is a real beast in its class."
    },
    "prices": {
        "USD": 40.09
    },
    "default_currency": "USD",
    "enabled": true,
    "permanent": false,
    "image_url": "http:\/\/livedemo.xsolla.com\/airplanes\/tank5.jpg",
    "item_type": "Expiration",
    "expiration": 1296000,
    "groups": [
        24,
        25
    ],
    "user_attribute_conditions": [
         {
             "right_operand": [
                 "magic"
             ],
             "id": 2015,
             "user_attribute_key": "type",
             "operation": "equal",
             "action": "hide",
             "name":null
         }
    ],
    "virtual_currency_price": null,
    "purchase_limit": null,
    "keywords": {
        "de":[
            "Inhalt","Aufgaben","Region","Landschaft"
        ],
        "en":[
            "content","quests","region","landscape"
        ]
    },
    "advertisement_type": "recommended",
    "deleted": false
}
$ curl -v 'https://api.xsolla.com/merchant/v2/projects/{project_id}/virtual_items/items/{item_id}' \
-X PUT \
-u merchant_id:merchant_api_key \
-H 'Content-Type: application/json' \
-H 'Accept: application/json' \
-d '{
    "sku": "T-43-3-unique-id",
    "item_code": "chinese-medium-tank",
    "name": {
        "en": "T-34-3"
    },
    "description": {
        "en": "Chinese Tier VIII medium tank."
    },
    "long_description": {
            "en": "This Chinese Tier VIII medium tank is a real beast in its class."
    },
    "prices": {
        "USD": 40.09
    },
    "default_currency": "USD",
    "enabled": true,
    "permanent": false,
    "image_url": "http:\/\/livedemo.xsolla.com\/airplanes\/tank5.jpg",
    "item_type": "Expiration",
    "expiration": 1296000,
    "groups": [
        24,
        25
    ],
    "user_attribute_conditions": [
         {
             "right_operand": [
                 "magic"
             ],
             "id": 2015,
             "user_attribute_key": "type",
             "operation": "equal",
             "action": "hide",
             "name":null
         }
    ],
    "virtual_currency_price": null,
    "purchase_limit": null,
    "keywords": {
        "de":[
            "Inhalt","Aufgaben","Region","Landschaft"
        ],
        "en":[
            "content","quests","region","landscape"
        ]
    },
    "advertisement_type": "recommended",
    "deleted": false
}'

响应

<?php

$response = null;
HTTP/1.1 204 No Content

删除物品

删除虚拟物品。

HTTP 请求

DELETE https://api.xsolla.com/merchant/v2/projects/{project_id}/virtual_items/items/{item_id}

参数 类型 描述
item_id
int 物品 ID。

请求


<?php

$response = $xsollaClient->DeleteVirtualItem(array(
    'project_id' => PROJECT_ID,
    'item_id' => ITEM_ID
));
DELETE /merchant/v2/projects/{project_id}/virtual_items/items/{item_id} HTTP/1.1
User-Agent: xsolla-api-client/1.0
Host: api.xsolla.com
Accept: application/json
Authorization: Basic ZGVtb0B4c29sbGEuY29tOmRlbW8=
Content-Type: application/json
$ curl -v 'https://api.xsolla.com/merchant/v2/projects/{project_id}/virtual_items/items/{item_id}' \
-X DELETE \
-u merchant_id:merchant_api_key

响应

<?php

$response = null;
HTTP/1.1 204 No Content

列示所有物品

列示虚拟物品。

HTTP 请求

GET https://api.xsolla.com/merchant/v2/projects/{project_id}/virtual_items/items

参数 类型 描述
project_id
int 游戏 ID。
offset
int 用户物品列表的起始页码。
limit
int 获取用户物品列表的限制。
has_price
string 物品出售的类型。可以是“virtual_currency”(如果可以使用虚拟货币购买物品)或“real_currency”(如果可以使用真实货币购买物品)。

请求


<?php

$response = $xsollaClient->ListVirtualItems(array(
    'project_id' => PROJECT_ID
));
GET /merchant/v2/projects/{project_id}/virtual_items/items HTTP/1.1
User-Agent: xsolla-api-client/1.0
Host: api.xsolla.com
Accept: application/json
Authorization: Basic ZGVtb0B4c29sbGEuY29tOmRlbW8=
Content-Type: application/json
$ curl -v 'https://api.xsolla.com/merchant/v2/projects/{project_id}/virtual_items/items' \
-X GET \
-u merchant_id:merchant_api_key

响应

<?php

// example response
$response = array (
    array (
            'id' => 46,
            'sku' => 'T-43-3-unique-id',
            'localized_name' => 'T-34-3',
            'prices' =>
                array (
                    'USD' => 40.09
                ),
            'default_currency' => 'USD',
            'enabled' => true,
            'permanent' => false,
            'groups' =>
                array (
                    25
                ),
            'advertisement_type' => null,
            'virtual_currency_price' => null
        )
);
HTTP/1.1 200 OK
Content-Type: application/json

[
    {
        "id": 46,
        "sku": "T-43-3-unique-id",
        "localized_name": "T-34-3",
        "prices": {
            "USD": 40.09
        },
        "default_currency": "USD",
        "enabled": true,
        "permanent": false,
        "groups": [
            25
        ],
        "advertisement_type": null,
        "virtual_currency_price": null
    }
]
[
    {
        "id": 46,
        "sku": "T-43-3-unique-id",
        "localized_name": "T-34-3",
        "prices": {
            "USD": 40.09
        },
        "default_currency": "USD",
        "enabled": true,
        "permanent": false,
        "groups": [
            25
        ],
        "advertisement_type": null,
        "virtual_currency_price": null
    }
]

创建组

创建虚拟物品组。

HTTP 请求

POST https://api.xsolla.com/merchant/v2/projects/{project_id}/virtual_items/groups

参数 类型 描述
project_id
int 游戏 ID。
name
array of strings 物品组本地化名称的数组。
description
array of strings 物品组本地化描述的数组。
enabled
boolean 是否可以使用此组。
parent_id
int 父组 ID。
code
int 组的唯一代码。

请求

<?php

$response = $xsollaClient->CreateVirtualItemsGroup(array(
    'project_id' => PROJECT_ID,
    'request' => array (
         'name' =>
             array (
                 'en' => 'Tanks',
             ),
         'description' =>
             array (
                 'en' => 'Tanks Group',
             ),
         'enabled' => true,
         'parent_id' => null,
         'code' => null
     )
));
POST /merchant/v2/projects/{project_id}/virtual_items/groups HTTP/1.1
User-Agent: xsolla-api-client/1.0
Host: api.xsolla.com
Accept: application/json
Authorization: Basic ZGVtb0B4c29sbGEuY29tOmRlbW8=
Content-Type: application/json

{
    "name": {
        "en": "Tanks"
    },
    "description": {
        "en": "Tanks Group"
    },
    "enabled": true,
    "parent_id": null,
    "code": null
}
$ curl -v 'https://api.xsolla.com/merchant/v2/projects/{project_id}/virtual_items/groups' \
-X POST \
-u merchant_id:merchant_api_key \
-H 'Content-Type: application/json' \
-H 'Accept: application/json' \
-d '{
    "name": {
        "en": "Tanks"
    },
    "description": {
        "en": "Tanks Group"
    },
    "enabled": true,
    "parent_id": null,
    "code": null
}'

响应

<?php

// example response
$response = array (
    'group_id' => 7
);
HTTP/1.1 201 Created
Content-Type: application/json

{
    "group_id": 7
}
{
    "group_id": 7
}

获取组

获取虚拟物品组。

HTTP 请求

GET https://api.xsolla.com/merchant/v2/projects/{project_id}/virtual_items/groups/{group_id}

参数 类型 描述
group_id
int 物品组 ID。

请求


<?php

$response = $xsollaClient->GetVirtualItemsGroup(array(
    'project_id' => PROJECT_ID,
    'group_id' => GROUP_ID
));
GET /merchant/v2/projects/{project_id}/virtual_items/groups/{group_id} HTTP/1.1
User-Agent: xsolla-api-client/1.0
Host: api.xsolla.com
Accept: application/json
Authorization: Basic ZGVtb0B4c29sbGEuY29tOmRlbW8=
Content-Type: application/json
$ curl -v 'https://api.xsolla.com/merchant/v2/projects/{project_id}/virtual_items/groups/{group_id}' \
-X GET \
-u merchant_id:merchant_api_key

响应

<?php

// example response
$response = array (
    'id' => 25,
    'name' =>
        array (
            'en' => 'Tanks'
        ),
    'description' =>
        array (
            'en' => 'Tanks Group'
        ),
    'enabled' => true,
    'parent_id' => null,
    'code' => null
);
HTTP/1.1 200 OK
Content-Type: application/json

{
    "id": 25,
    "name": {
        "en": "Tanks"
    },
    "description": {
        "en": "Tanks Group"
    },
    "enabled": true,
    "parent_id": null,
    "code": null
}
{
    "id": 25,
    "name": {
        "en": "Tanks"
    },
    "description": {
        "en": "Tanks Group"
    },
    "enabled": true,
    "parent_id": null,
    "code": null
}

更新组

更新虚拟物品组。

HTTP 请求

PUT https://api.xsolla.com/merchant/v2/projects/{project_id}/virtual_items/groups/{group_id}

参数 类型 描述
group_id
int 物品组 ID。
name
array of strings 物品组本地化名称的数组。
description
array of strings 物品组本地化描述的数组。
enabled
boolean 是否可以使用此组。
parent_id
int 父组 ID。
code
int 组的唯一代码。

请求

<?php

$response = $xsollaClient->UpdateVirtualItemsGroup(array(
    'project_id' => PROJECT_ID,
    'group_id' => GROUP_ID,
    'request' => array (
         'name' =>
             array (
                 'en' => 'Tanks',
             ),
         'description' =>
             array (
                 'en' => 'Tanks Group',
             ),
         'enabled' => true,
         'parent_id' => null,
         'code' => null
     )
));
PUT /merchant/v2/projects/{project_id}/virtual_items/groups/{group_id} HTTP/1.1
User-Agent: xsolla-api-client/1.0
Host: api.xsolla.com
Accept: application/json
Authorization: Basic ZGVtb0B4c29sbGEuY29tOmRlbW8=
Content-Type: application/json

{
    "name": {
        "en": "Tanks"
    },
    "description": {
        "en": "Tanks Group"
    },
    "enabled": true,
    "parent_id": null,
    "code": null
}
$ curl -v 'https://api.xsolla.com/merchant/v2/projects/{project_id}/virtual_items/groups/{group_id}' \
-X PUT \
-u merchant_id:merchant_api_key \
-H 'Content-Type: application/json' \
-H 'Accept: application/json' \
-d '{
    "name": {
        "en": "Tanks"
    },
    "description": {
        "en": "Tanks Group"
    },
    "enabled": true,
    "parent_id": null,
    "code": null
}'

响应

<?php

$response = null;
HTTP/1.1 204 No Content

删除组

删除虚拟物品组。

HTTP 请求

DELETE https://api.xsolla.com/merchant/v2/projects/{project_id}/virtual_items/groups/{group_id}

参数 类型 描述
group_id
int 物品组 ID。

请求


<?php

$response = $xsollaClient->DeleteVirtualItemsGroup(array(
    'project_id' => PROJECT_ID,
    'group_id' => GROUP_ID
));
DELETE /merchant/v2/projects/{project_id}/virtual_items/groups/{group_id} HTTP/1.1
User-Agent: xsolla-api-client/1.0
Host: api.xsolla.com
Accept: application/json
Authorization: Basic ZGVtb0B4c29sbGEuY29tOmRlbW8=
Content-Type: application/json
$ curl -v 'https://api.xsolla.com/merchant/v2/projects/{project_id}/virtual_items/groups/{group_id}' \
-X DELETE \
-u merchant_id:merchant_api_key

响应

<?php

$response = null;
HTTP/1.1 204 No Content

列示所有组

列示所有虚拟物品组。

HTTP 请求

GET https://api.xsolla.com/merchant/v2/projects/{project_id}/virtual_items/groups

参数 类型 描述
project_id
int 游戏 ID。

请求


<?php

$response = $xsollaClient->ListVirtualItemsGroups(array(
    'project_id' => PROJECT_ID
));
GET /merchant/v2/projects/{project_id}/virtual_items/groups HTTP/1.1
User-Agent: xsolla-api-client/1.0
Host: api.xsolla.com
Accept: application/json
Authorization: Basic ZGVtb0B4c29sbGEuY29tOmRlbW8=
Content-Type: application/json
$ curl -v 'https://api.xsolla.com/merchant/v2/projects/{project_id}/virtual_items/groups' \
-X GET \
-u merchant_id:merchant_api_key

响应

<?php

// example response
$response = array (
    array (
        'id' => 25,
        'localized_name' => 'Tanks',
        'enabled' => true,
        'parent_id' => null,
        'has_groups' => false,
        'has_virtual_items' => true,
        'virtual_items_count' => 6,
        'code' => null
    )
);
HTTP/1.1 200 OK
Content-Type: application/json

[
    {
        "id": 25,
        "localized_name": "Tanks",
        "enabled": true,
        "parent_id": null,
        "has_groups": false,
        "has_virtual_items": true,
        "virtual_items_count": 6,
        "code": null
    }
]
[
    {
        "id": 25,
        "localized_name": "Tanks",
        "enabled": true,
        "parent_id": null,
        "has_groups": false,
        "has_virtual_items": true,
        "virtual_items_count": 6,
        "code": null
    }
]

Lootboxes (BETA)

创建礼物盒

创建宝箱。

HTTP请求

POST https://api.xsolla.com/merchant/v2/projects/{project_id}/virtual_items/items

参数 类型 描述
project_id
int 游戏ID。
sku
string 物品唯一ID。SKU可能仅包含小写字母、数字、破折号和下划线。
item_code
string 物品附加代码。可选
name
array of strings 本地化物品名称。
description
array of strings 本地化物品描述。
long_description
array of strings 本地化物品长描述。
prices
array 物品价格。
default_currency
string 默认订单货币。参照ISO 4217标准的三位数字代码。
enabled
boolean 启用物品。
permanent
boolean 如为true,则该物品仅可购买一次。
image_url
string 物品图像URL。
item_type
string 物品类型:'lootbox'
expiration
int 寿命(单位为秒)。仅适用于Expiration类型物品
groups
array of integers 物品所属组。
deleted
boolean 物品是否已删除。
user_attribute_conditions
array of objects 用户属性条件。
user_attribute_conditions.right_operand
array 用户属性对比值。
user_attribute_conditions.user_attribute_key
string 用户属性条件键。
user_attribute_conditions.operation
string 运算类型。可以是'greater'、'greaterOrEqual'、'equal'、'notEqual'、'less'、'lessOrEqual'、'between'、'in'、'notIn'。
user_attribute_conditions.action
string 动作类型。可以是'hide'、'block'、'warning'。
advertisement_type
string 付款UI中为物品显示的特殊横幅类型。可以是'recommended'、'best_deal'、'special_offer'、null。
virtual_currency_price
int 以游戏内货币计算的价格。如果为'null',则物品仅能通过真实货币购买。
purchase_limit
int 物品可购买的次数。如果为'null',则购买次数无限制。
keywords
array 用于在付款UI中查找物品的关键字。
key_virtual_item_id
int 用于打开宝箱的虚拟物品ID。
opening_price_vc
int 打开宝箱的虚拟货币价格。
slots
array 宝箱槽。指定在每个槽中出现的物品组的数组。
slots.id
int 槽ID。
slots.value
object 槽内容。每个槽的drop_rate总和必须为100%。
slots.value.virtual_item
array 可在槽中出现的虚拟物品。
slots.value.virtual_item.id
int 物品ID。
slots.value.virtual_item.amount
float 物品数量。
slots.value.virtual_item.drop_rate
decimal 物品在槽中出现的概率(精确到小数点后2位)。
slots.value.virtual_currency
object 可在槽中出现的虚拟货币。
slots.value.virtual_currency.amount
float 货币数量。
slots.value.virtual_currency.drop_rate
decimal 物品在槽中出现的概率(精确到小数点后2位)。
slots.value.attribute
array 可投入槽的物品属性。
slots.value.attribute.type
int 用于选择在宝箱中出现的物品的属性类型。
slots.value.attribute.value
string 属性值。例如"rare"。
slots.value.attribute.drop_rate
string 包含该属性的物品在槽中出现的概率(精确到小数点后2位)。
slots.compensation_for_duplicate_percent
int 以虚拟货币计算的重复物品补偿(物品价格百分比)。
slots.compensation_for_duplicate_value
float 以虚拟货币计算的重复物品补偿(绝对值)。
limits
object 宝箱中物品的数量限制。
limits.virtual_item
object 虚拟物品限制。
limits.virtual_item.id
int 物品ID。
limits.virtual_item.max_items
int 物品可在宝箱中出现的最大次数。
limits.attribute
object 属性限制。
limits.attribute.type
int 用于限制的属性类型。
limits.attribute.value
string 用于限制的属性值。
limits.attribute.max_items
int 带有此属性的物品可投入礼物盒等最大次数。

请求

<?php

$response = $xsollaClient->CreateVirtualItem(array(
'project_id' => PROJECT_ID,
'request' => array (
'sku' => 'T-43-3-unique-id',
'item_code' => 'chinese-medium-tank',
'name' =>
array (
'en' => 'T-34-3',
),
'description' =>
array (
'en' => 'Chinese Tier VIII medium tank.',
),
'long_description' =>
array (
'en' => 'This Chinese Tier VIII medium tank is a real beast in its class.',
),
'prices' =>
array (
'USD' => 40.09,
),
'default_currency' => 'USD',
'enabled' => true,
'permanent' => false,
'image_url' => 'http://livedemo.xsolla.com/airplanes/tank5.jpg',
'item_type' => 'lootbox',
'expiration' => 1296000,
'groups' =>
array (
24,
25,
),
'user_attribute_conditions' =>
array (
array (
'right_operand' =>
array (
'magic',
),
'id' => 2015,
'user_attribute_key' => 'type',
'operation' => 'equal',
'action' => 'hide',
'name' => null,
),
),
'virtual_currency_price' => null,
'purchase_limit' => null,
'keywords' =>
array (
'de' =>
array (
'Inhalt',
'Aufgaben',
'Region',
'Landschaft',
),
'en' =>
array (
'content',
'quests',
'region',
'landscape',
),
),
'advertisement_type' => 'recommended',
'deleted' => false,
)
));
POST /merchant/v2/projects/{project_id}/virtual_items/items HTTP/1.1
User-Agent: xsolla-api-client/1.0
Host: api.xsolla.com
Accept: application/json
Authorization: Basic ZGVtb0B4c29sbGEuY29tOmRlbW8=
Content-Type: application/json

{
"sku": "T-43-3-unique-id",
"item_code": "chinese-medium-tank",
"name": {
"en": "T-34-3"
},
"description": {
"en": "Chinese Tier VIII medium tank."
},
"long_description": {
"en": "This Chinese Tier VIII medium tank is a real beast in its class."
},
"prices": {
"USD": 40.09
},
"default_currency": "USD",
"enabled": true,
"permanent": false,
"image_url": "http:\/\/livedemo.xsolla.com\/airplanes\/tank5.jpg",
"item_type": "lootbox",
"expiration": 1296000,
"groups": [
24,
25
],
"user_attribute_conditions": [
{
"right_operand": [
"magic"
],
"id": 2015,
"user_attribute_key": "type",
"operation": "equal",
"action": "hide",
"name":null
}
],
"virtual_currency_price": null,
"purchase_limit": null,
"keywords": {
"de":[
"Inhalt","Aufgaben","Region","Landschaft"
],
"en":[
"content","quests","region","landscape"
]
},
"advertisement_type": "recommended",
"deleted": false,
"slots":[
{
"id":123,
"value":{
"virtual_items":[
{
"id":123,
"amount":10,
"drop_rate":20
},
{
"id":321,
"amount":15,
"drop_rate":50
}
],
"attribute":[
{
"type":1,
"value":"rare",
"drop_rate":20
}
],
"virtual_currency":[
{
"amount":100,
"drop_rate":10
}
]
},
"compensation_for_duplicate_percent":10,
"compensation_for_duplicate_value":50
}
],
"limits":{
"virtual_item":{
"id":123,
"max_items":5
},
"attribute":{
"type":1,
"value":"rare",
"max_items":5
}
}
}
$ curl -v 'https://api.xsolla.com/merchant/v2/projects/{project_id}/virtual_items/items' \
-X POST \
-u merchant_id:merchant_api_key \
-H 'Content-Type: application/json' \
-H 'Accept: application/json' \
-d '{
"sku": "T-43-3-unique-id",
"item_code": "chinese-medium-tank",
"name": {
"en": "T-34-3"
},
"description": {
"en": "Chinese Tier VIII medium tank."
},
"long_description": {
"en": "This Chinese Tier VIII medium tank is a real beast in its class."
},
"prices": {
"USD": 40.09
},
"default_currency": "USD",
"enabled": true,
"permanent": false,
"image_url": "http:\/\/livedemo.xsolla.com\/airplanes\/tank5.jpg",
"item_type": "lootbox",
"expiration": 1296000,
"groups": [
24,
25
],
"user_attribute_conditions": [
{
"right_operand": [
"magic"
],
"id": 2015,
"user_attribute_key": "type",
"operation": "equal",
"action": "hide",
"name":null
}
],
"virtual_currency_price": null,
"purchase_limit": null,
"keywords": {
"de":[
"Inhalt","Aufgaben","Region","Landschaft"
],
"en":[
"content","quests","region","landscape"
]
},
"advertisement_type": "recommended",
"deleted": false,
"slots":[
{
"id":123,
"value":{
"virtual_items":[
{
"id":123,
"amount":10,
"drop_rate":20
},
{
"id":321,
"amount":15,
"drop_rate":50
}
],
"attribute":[
{
"type":1,
"value":"rare",
"drop_rate":20
}
],
"virtual_currency":[
{
"amount":100,
"drop_rate":10
}
]
},
"compensation_for_duplicate_percent":10,
"compensation_for_duplicate_value":50
}
],
"limits":{
"virtual_item":{
"id":123,
"max_items":5
},
"attribute":{
"type":1,
"value":"rare",
"max_items":5
}
}
}'

响应

<?php

// example response
$response = array (
'item_id' => 77
);
HTTP/1.1 201 Created
Content-Type: application/json

{
"item_id": 77
}
{
"item_id": 77
}

更新宝箱

更新宝箱。

HTTP请求

PUT https://api.xsolla.com/merchant/v2/projects/{project_id}/virtual_items/items/{item_id}

参数 类型 描述
project_id
int 游戏ID。
sku
string 物品唯一ID。SKU可能仅包含小写字母、数字、破折号和下划线。
item_code
string 物品附加代码。可选
name
array of strings 本地化物品名称。
description
array of strings 本地化物品描述。
long_description
array of strings 本地化物品长描述。
prices
array 物品价格。
default_currency
string 默认订单货币。参照ISO 4217标准的三位数字代码。
enabled
boolean 启用物品。
permanent
boolean 如为true,则该物品仅可购买一次。
image_url
string 物品图像URL。
item_type
string 物品类型:'lootbox'
expiration
int 寿命(单位为秒)。仅适用于Expiration类型物品
groups
array of integers 物品所属组。
deleted
boolean 物品是否已删除。
user_attribute_conditions
array of objects 用户属性条件。
user_attribute_conditions.right_operand
array 用户属性对比值。
user_attribute_conditions.user_attribute_key
string 用户属性条件键。
user_attribute_conditions.operation
string 运算类型。可以是'greater'、'greaterOrEqual'、'equal'、'notEqual'、'less'、'lessOrEqual'、'between'、'in'、'notIn'。
user_attribute_conditions.action
string 动作类型。可以是'hide'、'block'、'warning'。
advertisement_type
string 付款UI中为物品显示的特殊横幅类型。可以是'recommended'、'best_deal'、'special_offer'、null。
virtual_currency_price
int 以游戏内货币计算的价格。如果为'null',则物品仅能通过真实货币购买。
purchase_limit
int 物品可购买的次数。如果为'null',则购买次数无限制。
keywords
array 用于在付款UI中查找物品的关键字。
key_virtual_item_id
int 用于打开宝箱的虚拟物品ID。
opening_price_vc
int 打开宝箱的虚拟货币价格。
slots
array 宝箱槽。指定在每个槽中出现的物品组的数组。
slots.id
int 槽ID。
slots.value
object 槽内容。每个槽的drop_rate总和必须为100%。
slots.value.virtual_item
array 可在槽中出现的虚拟物品。
slots.value.virtual_item.id
int 物品ID。
slots.value.virtual_item.amount
float 物品数量。
slots.value.virtual_item.drop_rate
decimal 物品在槽中出现的概率(精确到小数点后2位)。
slots.value.virtual_currency
object 可在槽中出现的虚拟货币。
slots.value.virtual_currency.amount
float 货币数量。
slots.value.virtual_currency.drop_rate
decimal 物品在槽中出现的概率(精确到小数点后2位)。
slots.value.attribute
array 可投入槽的物品属性。
slots.value.attribute.type
int 用于选择在宝箱中出现的物品的属性类型。
slots.value.attribute.value
string 属性值。例如"rare"。
slots.value.attribute.drop_rate
string 包含该属性的物品在槽中出现的概率(精确到小数点后2位)。
slots.compensation_for_duplicate_percent
int 以虚拟货币计算的重复物品补偿(物品价格百分比)。
slots.compensation_for_duplicate_value
float 以虚拟货币计算的重复物品补偿(绝对值)。
limits
object 宝箱中物品的数量限制。
limits.virtual_item
object 虚拟物品限制。
limits.virtual_item.id
int 物品ID。
limits.virtual_item.max_items
int 物品可在宝箱中出现的最大次数。
limits.attribute
object 属性限制。
limits.attribute.type
int 用于限制的属性类型。
limits.attribute.value
string 用于限制的属性值。
limits.attribute.max_items
int 带有此属性的物品可投入礼物盒等最大次数。

请求

<?php

$response = $xsollaClient->CreateVirtualItem(array(
'project_id' => PROJECT_ID,
'request' => array (
'sku' => 'T-43-3-unique-id',
'item_code' => 'chinese-medium-tank',
'name' =>
array (
'en' => 'T-34-3',
),
'description' =>
array (
'en' => 'Chinese Tier VIII medium tank.',
),
'long_description' =>
array (
'en' => 'This Chinese Tier VIII medium tank is a real beast in its class.',
),
'prices' =>
array (
'USD' => 40.09,
),
'default_currency' => 'USD',
'enabled' => true,
'permanent' => false,
'image_url' => 'http://livedemo.xsolla.com/airplanes/tank5.jpg',
'item_type' => 'lootbox',
'expiration' => 1296000,
'groups' =>
array (
24,
25,
),
'user_attribute_conditions' =>
array (
array (
'right_operand' =>
array (
'magic',
),
'id' => 2015,
'user_attribute_key' => 'type',
'operation' => 'equal',
'action' => 'hide',
'name' => null,
),
),
'virtual_currency_price' => null,
'purchase_limit' => null,
'keywords' =>
array (
'de' =>
array (
'Inhalt',
'Aufgaben',
'Region',
'Landschaft',
),
'en' =>
array (
'content',
'quests',
'region',
'landscape',
),
),
'advertisement_type' => 'recommended',
'deleted' => false,
)
));
POST /merchant/v2/projects/{project_id}/virtual_items/items HTTP/1.1
User-Agent: xsolla-api-client/1.0
Host: api.xsolla.com
Accept: application/json
Authorization: Basic ZGVtb0B4c29sbGEuY29tOmRlbW8=
Content-Type: application/json

{
"sku": "T-43-3-unique-id",
"item_code": "chinese-medium-tank",
"name": {
"en": "T-34-3"
},
"description": {
"en": "Chinese Tier VIII medium tank."
},
"long_description": {
"en": "This Chinese Tier VIII medium tank is a real beast in its class."
},
"prices": {
"USD": 40.09
},
"default_currency": "USD",
"enabled": true,
"permanent": false,
"image_url": "http:\/\/livedemo.xsolla.com\/airplanes\/tank5.jpg",
"item_type": "lootbox",
"expiration": 1296000,
"groups": [
24,
25
],
"user_attribute_conditions": [
{
"right_operand": [
"magic"
],
"id": 2015,
"user_attribute_key": "type",
"operation": "equal",
"action": "hide",
"name":null
}
],
"virtual_currency_price": null,
"purchase_limit": null,
"keywords": {
"de":[
"Inhalt","Aufgaben","Region","Landschaft"
],
"en":[
"content","quests","region","landscape"
]
},
"advertisement_type": "recommended",
"deleted": false
}
$ curl -v 'https://api.xsolla.com/merchant/v2/projects/{project_id}/virtual_items/items' \
-X POST \
-u merchant_id:merchant_api_key \
-H 'Content-Type: application/json' \
-H 'Accept: application/json' \
-d '{
"sku": "T-43-3-unique-id",
"item_code": "chinese-medium-tank",
"name": {
"en": "T-34-3"
},
"description": {
"en": "Chinese Tier VIII medium tank."
},
"long_description": {
"en": "This Chinese Tier VIII medium tank is a real beast in its class."
},
"prices": {
"USD": 40.09
},
"default_currency": "USD",
"enabled": true,
"permanent": false,
"image_url": "http:\/\/livedemo.xsolla.com\/airplanes\/tank5.jpg",
"item_type": "lootbox",
"expiration": 1296000,
"groups": [
24,
25
],
"user_attribute_conditions": [
{
"right_operand": [
"magic"
],
"id": 2015,
"user_attribute_key": "type",
"operation": "equal",
"action": "hide",
"name":null
}
],
"virtual_currency_price": null,
"purchase_limit": null,
"keywords": {
"de":[
"Inhalt","Aufgaben","Region","Landschaft"
],
"en":[
"content","quests","region","landscape"
]
},
"advertisement_type": "recommended",
"deleted": false
}'

响应

<?php

$response = null;
HTTP/1.1 204 No Content

获取宝箱

检索宝箱的有关信息。

HTTP请求

GET https://api.xsolla.com/merchant/v2/projects/{project_id}/virtual_items/items/{item_id}

参数 类型 描述
item_id
int 物品ID。

请求


<?php

$response = $xsollaClient->GetVirtualItem(array(
'project_id' => PROJECT_ID,
'item_id' => ITEM_ID
));
GET /merchant/v2/projects/{project_id}/virtual_items/items/{item_id} HTTP/1.1
User-Agent: xsolla-api-client/1.0
Host: api.xsolla.com
Accept: application/json
Authorization: Basic ZGVtb0B4c29sbGEuY29tOmRlbW8=
Content-Type: application/json
$ curl -v 'https://api.xsolla.com/merchant/v2/projects/{project_id}/virtual_items/items/{item_id}' \
-X GET \
-u merchant_id:merchant_api_key

响应

<?php

// example response
$response = array (
'id' => 77,
'sku' => 'T-43-3-unique-id',
'item_code' => 'chinese-medium-tank',
'name' =>
array (
'en' => 'T-34-3'
),
'description' =>
array (
'en' => 'Chinese Tier VIII medium tank.'
),
'long_description' =>
array (
'en' => 'This Chinese Tier VIII medium tank is a real beast in its class.'
),
'prices' =>
array (
'USD' => 40.09
),
'default_currency' => 'USD',
'enabled' => true,
'permanent' => false,
'image_url' => 'http://livedemo.xsolla.com/airplanes/tank5.jpg',
'item_type' => 'lootbox',
'expiration' => 1296000,
'groups' =>
array (
24,
25
),
'user_attribute_conditions' =>
array (
array (
'right_operand' =>
array (
'magic',
),
'id' => 2015,
'user_attribute_key' => 'type',
'operation' => 'equal',
'action' => 'hide',
'name' => null,
),
),
'virtual_currency_price' => null,
'purchase_limit' => null,
'keywords' =>
array (
'de' =>
array (
'Inhalt',
'Aufgaben',
'Region',
'Landschaft',
),
'en' =>
array (
'content',
'quests',
'region',
'landscape',
),
),
'advertisement_type' => 'recommended',
'deleted' => false,
);
HTTP/1.1 200 OK
Content-Type: application/json

{
"id": 77,
"sku": "T-43-3-unique-id",
"item_code": "chinese-medium-tank",
"name": {
"en": "T-34-3"
},
"description": {
"en": "Chinese Tier VIII medium tank."
},
"long_description": {
"en": "This Chinese Tier VIII medium tank is a real beast in its class."
},
"prices": {
"USD": 40.09
},
"default_currency": "USD",
"enabled": true,
"permanent": false,
"image_url": "http:\/\/livedemo.xsolla.com\/airplanes\/tank5.jpg",
"item_type": "lootbox",
"expiration": 1296000,
"groups": [
24,
25
],
"user_attribute_conditions": [
{
"right_operand": [
"magic"
],
"id": 2015,
"user_attribute_key": "type",
"operation": "equal",
"action": "hide",
"name":null
}
],
"virtual_currency_price": null,
"purchase_limit": null,
"keywords": {
"de":[
"Inhalt","Aufgaben","Region","Landschaft"
],
"en":[
"content","quests","region","landscape"
]
},
"advertisement_type": "recommended",
"deleted": false
}
{
"id": 77,
"sku": "T-43-3-unique-id",
"item_code": "chinese-medium-tank",
"name": {
"en": "T-34-3"
},
"description": {
"en": "Chinese Tier VIII medium tank."
},
"long_description": {
"en": "This Chinese Tier VIII medium tank is a real beast in its class."
},
"prices": {
"USD": 40.09
},
"default_currency": "USD",
"enabled": true,
"permanent": false,
"image_url": "http:\/\/livedemo.xsolla.com\/airplanes\/tank5.jpg",
"item_type": "lootbox",
"expiration": 1296000,
"groups": [
24,
25
],
"user_attribute_conditions": [
{
"right_operand": [
"magic"
],
"id": 2015,
"user_attribute_key": "type",
"operation": "equal",
"action": "hide",
"name":null
}
],
"virtual_currency_price": null,
"purchase_limit": null,
"keywords": {
"de":[
"Inhalt","Aufgaben","Region","Landschaft"
],
"en":[
"content","quests","region","landscape"
]
},
"advertisement_type": "recommended",
"deleted": false
}

列出宝箱

获取宝箱列表。

HTTP请求

GET https://api.xsolla.com/merchant/v2/projects/{project_id}/virtual_items/items

参数 类型 描述
project_id
int 游戏ID。
offset
int 页码。
limit
int 每页记录。
has_price
string 可用于购买物品的货币类型。可以是'virtual_currency'或'real_currency'(分别对应于可用虚拟或真实货币购买的物品)。

请求


<?php

$response = $xsollaClient->ListVirtualItems(array(
'project_id' => PROJECT_ID
));
GET /merchant/v2/projects/{project_id}/virtual_items/items HTTP/1.1
User-Agent: xsolla-api-client/1.0
Host: api.xsolla.com
Accept: application/json
Authorization: Basic ZGVtb0B4c29sbGEuY29tOmRlbW8=
Content-Type: application/json
$ curl -v 'https://api.xsolla.com/merchant/v2/projects/{project_id}/virtual_items/items' \
-X GET \
-u merchant_id:merchant_api_key

响应

<?php

// example response
$response = array (
array (
'id' => 46,
'sku' => 'T-43-3-unique-id',
'localized_name' => 'T-34-3',
'prices' =>
array (
'USD' => 40.09
),
'default_currency' => 'USD',
'enabled' => true,
'permanent' => false,
'groups' =>
array (
25
),
'advertisement_type' => null,
'virtual_currency_price' => null
)
);
HTTP/1.1 200 OK
Content-Type: application/json

[
{
"id": 46,
"sku": "T-43-3-unique-id",
"localized_name": "T-34-3",
"prices": {
"USD": 40.09
},
"default_currency": "USD",
"enabled": true,
"permanent": false,
"groups": [
25
],
"advertisement_type": null,
"virtual_currency_price": null
}
]
[
{
"id": 46,
"sku": "T-43-3-unique-id",
"localized_name": "T-34-3",
"prices": {
"USD": 40.09
},
"default_currency": "USD",
"enabled": true,
"permanent": false,
"groups": [
25
],
"advertisement_type": null,
"virtual_currency_price": null
}
]

打开宝箱

HTTP请求

POST https://api.xsolla.com/merchant/v2/projects/{project_id}/virtual_items/items/{item_id}/open

参数 类型 描述
slots
array 宝箱槽。指定在每个槽中出现的物品组的数组。
slots.id
int 槽ID。
slots.value
object 槽内容。每个槽的drop_rate总和必须为100%。
slots.value.virtual_item
array 可在槽中出现的虚拟物品。
slots.value.virtual_item.id
int 物品ID。
slots.value.virtual_item.amount
float 物品数量。
slots.value.virtual_item.drop_rate
decimal 物品在槽中出现的概率(精确到小数点后2位)。
slots.value.virtual_currency
object 可在槽中出现的虚拟货币。
slots.value.virtual_currency.amount
float 货币数量。
slots.value.virtual_currency.drop_rate
decimal 物品在槽中出现的概率(精确到小数点后2位)。
slots.value.attribute
array 可投入槽的物品属性。
slots.value.attribute.type
int 用于选择在宝箱中出现的物品的属性类型。
slots.value.attribute.value
string 属性值。例如"rare"。
slots.value.attribute.drop_rate
string 包含该属性的物品在槽中出现的概率(精确到小数点后2位)。
slots.compensation_for_duplicate_percent
int 以虚拟货币计算的重复物品补偿(物品价格百分比)。
slots.compensation_for_duplicate_value
float 以虚拟货币计算的重复物品补偿(绝对值)。

请求

<?php

$response = $xsollaClient->GetVirtualItem(array(
'project_id' => PROJECT_ID,
'item_id' => ITEM_ID
));
POST /merchant/v2/projects/{project_id}/virtual_items/items/{item_id}/open HTTP/1.1
User-Agent: xsolla-api-client/1.0
Host: api.xsolla.com
Accept: application/json
Authorization: Basic ZGVtb0B4c29sbGEuY29tOmRlbW8=
Content-Type: application/json
$ curl -v 'https://api.xsolla.com/merchant/v2/projects/{project_id}/virtual_items/items/{item_id}/open' \
-X POST \
-u merchant_id:merchant_api_key \
-H 'Content-Type: application/json' \
-H 'Accept: application/json' \

响应

<?php
HTTP/1.1 200 OK

删除宝箱

删除宝箱。

HTTP请求

DELETE https://api.xsolla.com/merchant/v2/projects/{project_id}/virtual_items/items/{item_id}

参数 类型 描述
item_id
int 物品ID。

请求


<?php

$response = $xsollaClient->DeleteVirtualItem(array(
'project_id' => PROJECT_ID,
'item_id' => ITEM_ID
));
DELETE /merchant/v2/projects/{project_id}/virtual_items/items/{item_id} HTTP/1.1
User-Agent: xsolla-api-client/1.0
Host: api.xsolla.com
Accept: application/json
Authorization: Basic ZGVtb0B4c29sbGEuY29tOmRlbW8=
Content-Type: application/json
$ curl -v 'https://api.xsolla.com/merchant/v2/projects/{project_id}/virtual_items/items/{item_id}' \
-X DELETE \
-u merchant_id:merchant_api_key

响应

<?php

$response = null;
HTTP/1.1 204 No Content

列示货币包

获取项目虚拟货币设置。

HTTP 请求

GET https://api.xsolla.com/merchant/v2/projects/{project_id}/virtual_currency

参数 类型 描述
project_id
int 游戏 ID。

请求


<?php

$response = $xsollaClient->GetProjectVirtualCurrencySettings(array(
    'project_id' => PROJECT_ID
));
GET /merchant/v2/projects/{project_id}/virtual_currency HTTP/1.1
User-Agent: xsolla-api-client/1.0
Host: api.xsolla.com
Accept: application/json
Authorization: Basic ZGVtb0B4c29sbGEuY29tOmRlbW8=
Content-Type: application/json
$ curl -v 'https://api.xsolla.com/merchant/v2/projects/{project_id}/virtual_currency' \
-X GET \
-u merchant_id:merchant_api_key

响应

<?php

// example response
$response = array (
    'id' => 1,
    'vc_name' =>
        array (
            'en' => 'Golden Coins'
        ),
    'base' =>
        array (
            'USD' => 0.04,
            'EUR' => 0.03
        ),
    'default_currency' => 'USD',
    'min' => 0,
    'max' => 0,
    'is_currency_discrete' => true,
    'allow_user_sum' => true,
    'packets' =>
        array (
            'USD' =>
                array (
                    array (
                        'id' => 1,
                        'sku' => 'vc_usd',
                        'amount' => 100,
                        'price' => 10,
                        'image_url' => '//images.storage.com/some_image',
                        'description' =>
                            array (
                                'en' => 'Standard Package'
                            ),
                        'label' =>
                            array (
                                'en' => 'Standard Package'
                            ),
                        'bonus' => 0,
                        'advertisement_type' => 'recommended'
                        'enabled' => true
                    )
                ),
            'EUR' =>
                array (
                    array (
                        'id' => 2,
                        'sku' => 'vc_eur',
                        'amount' => 80,
                        'price' => 5,
                        'image_url' => null,
                        'description' =>
                            array (
                                'en' => 'Standard Package'
                            ),
                        'label' =>
                            array (
                                'en' => 'Standard Package'
                            ),
                        'bonus' => 0,
                        'advertisement_type' => 'recommended'
                        'enabled' => true
                    )
                )
        ),
    'type' => 'packets',
);
HTTP/1.1 200 OK
Content-Type: application/json

{
    "id": 1,
    "vc_name": {
        "en": "Golden Coins"
    },
    "base": {
        "USD": 0.04,
        "EUR": 0.03
    },
    "default_currency": "USD",
    "min": 0,
    "max": 0,
    "is_currency_discrete": true,
    "allow_user_sum": true,
    "packets": {
        "USD": [
            {
                "id": 1,
                "sku": "vc_usd",
                "amount": 100,
                "price": 10,
                "image_url": "//images.storage.com/some_image",
                "description": {
                    "en": "Standard Package"
                },
                "label": {
                    "en": "Standard Package"
                },
                "bonus": 0,
                "advertisement_type": "recommended",
                "enabled": true
            }
        ],
        "EUR": [
            {
                "id": 2,
                "sku": "vc_eur",
                "amount": 80,
                "price": 5,
                "image_url": null,
                "description": {
                    "en": "Standard Package"
                },
                "label": {
                    "en": "Standard Package"
                },
                "bonus": 0,
                "advertisement_type": "recommended",
                "enabled": true
            }
        ]
    },
    "type": "packets"
}
{
    "id": 1,
    "vc_name": {
        "en": "Golden Coins"
    },
    "base": {
        "USD": 0.04,
        "EUR": 0.03
    },
    "default_currency": "USD",
    "min": 0,
    "max": 0,
    "is_currency_discrete": true,
    "allow_user_sum": true,
    "packets": {
        "USD": [
            {
                "id": 1,
                "sku": "vc_usd",
                "amount": 100,
                "price": 10,
                "image_url": "//images.storage.com/some_image",
                "description": {
                    "en": "Standard Package"
                },
                "label": {
                    "en": "Standard Package"
                },
                "bonus": 0,
                "advertisement_type": "recommended",
                "enabled": true
            }
        ],
        "EUR": [
            {
                "id": 2,
                "sku": "vc_eur",
                "amount": 80,
                "price": 5,
                "image_url": null,
                "description": {
                    "en": "Standard Package"
                },
                "label": {
                    "en": "Standard Package"
                },
                "bonus": 0,
                "advertisement_type": "recommended",
                "enabled": true
            }
        ]
    },
    "type": "packets"
}

更新货币包

更新项目虚拟货币设置。

HTTP 请求

PUT https://api.xsolla.com/merchant/v2/projects/{project_id}/virtual_currency

参数 类型 描述
project_id
int 游戏 ID。
vc_name
array of strings 产品名称。由<地区语言>:<产品名称>组成的键值对。
base
array 主要产品货币的 JSON 对象,其中键是货币(使用 ISO 4217 标准规定的 3 字母组合表示币种),值是货币金额。
default_currency
string 默认币种。
min
float 最小购买金额。
max
float 最大购买金额。
is_currency_discrete
boolean 虚拟货币是否可以使用美分。
allow_user_sum
boolean 是否允许在货币包之间支付任意金额。
amount
float 货币包中虚拟货币的金额。
sku
string 虚拟货币包的唯一 ID。
price
float 虚拟货币包的价格。
image_url
string 货币包图像 URL。
description
array of strings 带有货币包本地化名称的数组。由<地区语言>:<货币包名称>组成的键值对。
label
array of strings 带有货币包本地化标签的数组。由<地区语言>:<货币包标签>组成的键值对。
bonus
float 货币包的折扣金额。
advertisement_type
string 虚拟货币包的标签类型。可以是“recommended”、“best_deal”、“special_offer”或null。
enabled
boolean 是否启用虚拟货币包。

请求

<?php

$response = $xsollaClient->UpdateProjectVirtualCurrencySettings(array(
    'project_id' => PROJECT_ID,
    'request' => array (
         'vc_name' =>
             array (
                 'en' => 'Golden Coins'
             ),
         'base' =>
             array (
                 'USD' => 0.04,
                 'EUR' => 0.02,
             ),
         'default_currency' => 'USD',
         'min' => 0,
         'max' => 0,
         'is_currency_discrete' => true,
         'allow_user_sum' => true,
         'packets' =>
             array (
                 'USD' =>
                     array (
                         array (
                             'id' => 1,
                             'sku' => 'vc_usd',
                             'amount' => 100,
                             'price' => 10,
                             'image_url' => '//images.storage.com/some_image',
                             'description' =>
                                 array (
                                     'en' => 'Standard Package'
                                 ),
                             'label' =>
                                 array (
                                     'en' => 'Standard Package'
                                 ),
                             'bonus' => 0,
                             'advertisement_type' => 'recommended'
                             'enabled' => true
                         )
                     ),
                 'EUR' =>
                     array (
                         array (
                             'id' => 2,
                             'sku' => 'vc_eur',
                             'amount' => 80,
                             'price' => 5,
                             'image_url' => null,
                             'description' =>
                                 array (
                                     'en' => 'Standard Package'
                                 ),
                             'label' =>
                                 array (
                                     'en' => 'Standard Package'
                                 ),
                             'bonus' => 0,
                             'advertisement_type' => 'recommended'
                             'enabled' => true
                         )
                     )
             ),
         'type' => 'packets',
     )
));
PUT /merchant/v2/projects/{project_id}/virtual_currency HTTP/1.1
User-Agent: xsolla-api-client/1.0
Host: api.xsolla.com
Accept: application/json
Authorization: Basic ZGVtb0B4c29sbGEuY29tOmRlbW8=
Content-Type: application/json

{
    "vc_name": {
        "en": "Golden Coins"
    },
    "base": {
        "USD": 0.04,
        "EUR": 0.03
    },
    "default_currency": "USD",
    "min": 0,
    "max": 0,
    "is_currency_discrete": true,
    "allow_user_sum": true,
    "packets": {
        "USD": [
            {
                "id": 1,
                "sku": "vc_usd",
                "amount": 100,
                "price": 10,
                "image_url": "//images.storage.com/some_image",
                "description": {
                    "en": "Standard Package"
                },
                "label": {
                    "en": "Standard Package"
                },
                "bonus": 0,
                "advertisement_type": "recommended",
                "enabled": true
            }
        ],
        "EUR": [
            {
                "id": 2,
                "sku": "vc_eur",
                "amount": 80,
                "price": 5,
                "image_url": null,
                "description": {
                    "en": "Standard Package"
                },
                "label": {
                    "en": "Standard Package"
                },
                "bonus": 0,
                "advertisement_type": "recommended",
                "enabled": true
            }
        ]
    }
}
$ curl -v 'https://api.xsolla.com/merchant/v2/projects/{project_id}/virtual_currency' \
-X PUT \
-u merchant_id:merchant_api_key \
-H 'Content-Type: application/json' \
-H 'Accept: application/json' \
-d '{
    "vc_name": {
        "en": "Golden Coins"
    },
    "base": {
        "USD": 0.04,
        "EUR": 0.03
    },
    "default_currency": "USD",
    "min": 0,
    "max": 0,
    "is_currency_discrete": true,
    "allow_user_sum": true,
    "packets": {
        "USD": [
            {
                "id": 1,
                "sku": "vc_usd",
                "amount": 100,
                "price": 10,
                "image_url": "//images.storage.com/some_image",
                "description": {
                    "en": "Standard Package"
                },
                "label": {
                    "en": "Standard Package"
                },
                "bonus": 0,
                "advertisement_type": "recommended",
                "enabled": true
            }
        ],
        "EUR": [
            {
                "id": 2,
                "sku": "vc_eur",
                "amount": 80,
                "price": 5,
                "image_url": null,
                "description": {
                    "en": "Standard Package"
                },
                "label": {
                    "en": "Standard Package"
                },
                "bonus": 0,
                "advertisement_type": "recommended",
                "enabled": true
            }
        ]
    }
}'

响应

<?php

$response = null;
HTTP/1.1 204 No Content

电子钱包

本部分将介绍处理玩家余额的方法。方法提供各种余额结转操作,例如查看余额、充值、提现和其他用户相关功能。

创建新用户

创建新用户。

HTTP 请求

POST https://api.xsolla.com/merchant/v2/projects/{project_id}/users

参数 类型 描述
project_id
int 游戏 ID。必要。
user_id
string 用户 ID。必要。
user_name
string 用户名。
user_custom
string 用户标识的自定义参数。
email
string 电子邮件。

请求

<?php

$response = $xsollaClient->CreateWalletUser(array(
    'project_id' => PROJECT_ID,
    'request' => array(
        'user_id' => USER_ID
    )
));
POST /merchant/v2/projects/{project_id}/users HTTP/1.1
User-Agent: xsolla-api-client/1.0
Host: api.xsolla.com
Accept: application/json
Authorization: Basic ZGVtb0B4c29sbGEuY29tOmRlbW8=
Content-Type: application/json

{
    "user_id": 1
}
$ curl -v 'https://api.xsolla.com/merchant/v2/projects/{project_id}/users' \
-X POST \
-u merchant_id:merchant_api_key \
-H 'Content-Type: application/json' \
-H 'Accept: application/json' \
-d '{
    "user_id": 1
}'

响应

HTTP/1.1 204 No Content

获取用户

检索用户数据。

HTTP 请求

GET https://api.xsolla.com/merchant/v2/projects/{project_id}/users/{user_id}

参数 类型 描述
project_id
int 游戏 ID。
user_id
string 用户在游戏中的 ID。

请求

<?php

$response = $xsollaClient->GetWalletUser(array(
    'project_id' => PROJECT_ID,
    'user_id' => USER_ID
));
GET /merchant/v2/projects/{project_id}/users/{user_id} HTTP/1.1
User-Agent: xsolla-api-client/1.0
Host: api.xsolla.com
Accept: application/json
Authorization: Basic ZGVtb0B4c29sbGEuY29tOmRlbW8=
Content-Type: application/json
$ curl -v 'https://api.xsolla.com/merchant/v2/projects/{project_id}/users/{user_id}' \
-X GET \
-u merchant_id:merchant_api_key

响应

<?php

// example response
$response = array (
    'user_id' => 0,
    'user_name' => 'John',
    'user_custom' => 'Smith',
    'email' => 'email@example.com',
    'register_date' => '2014-10-08T21:44:32+04:00',
    'balance' => 100,
    'wallet_amount' => 1.5,
    'wallet_currency' => 'USD',
    'enabled' => true
);
HTTP/1.1 200 OK
Content-Type: application/json

{
    "user_id": 0,
    "user_name": "John",
    "user_custom": "Smith",
    "email": "email@example.com",
    "register_date": "2014-10-08T21:44:32-08:00",
    "balance": 100,
    "wallet_amount": 1.5,
    "wallet_currency": "USD",
    "enabled": true
}
{
    "user_id": 0,
    "user_name": "John",
    "user_custom": "Smith",
    "email": "email@example.com",
    "register_date": "2014-10-08T21:44:32-08:00",
    "balance": 100,
    "wallet_amount": 1.5,
    "wallet_currency": "USD",
    "enabled": true
}

更新用户

更新用户信息。

HTTP 请求

PUT https://api.xsolla.com/merchant/v2/projects/{project_id}/users/{user_id}

Parameter Type 描述
project_id
int 游戏 ID。必要。
user_id
string 用户 ID。必要。
user_name
string 用户名。
user_custom
string 用户标识的自定义参数。
email
string 电子邮件。
enabled
boolean 此用户是否已启用。 必要。

请求

<?php

$response = $xsollaClient->UpdateWalletUser(array(
    'project_id' => PROJECT_ID,
    'user_id' => USER_ID,
    'request' => array(
        'enabled' => true
    )
));
PUT /merchant/v2/projects/{project_id}/users/{user_id} HTTP/1.1
User-Agent: xsolla-api-client/1.0
Host: api.xsolla.com
Accept: application/json
Authorization: Basic ZGVtb0B4c29sbGEuY29tOmRlbW8=
Content-Type: application/json

{
    "enabled": true
}
$ curl -v 'https://api.xsolla.com/merchant/v2/projects/{project_id}/users/{user_id}' \
-X PUT \
-u merchant_id:merchant_api_key \
-H 'Content-Type: application/json' \
-H 'Accept: application/json' \
-d '{
    "enabled": true
}'

响应

<?php

$response = null;
HTTP/1.1 204 No Content

列示所有用户

列示所有用户。

HTTP 请求

GET https://api.xsolla.com/merchant/v2/projects/{project_id}/users

参数 类型 描述
project_id
int 游戏 ID。必要。
user_requisites
string 用户 ID。
email
string 用户电子邮件。
offset
int 搜索用户时的起始页码。必要。
limit
int 响应中用户数量的限制。必要。

请求

<?php

$response = $xsollaClient->ListWalletUsers(array(
    'project_id' => PROJECT_ID,
    'limit' => 1,
    'offset' => 0
));
GET /merchant/v2/projects/{project_id}/users?offset=1&limit=1 HTTP/1.1
User-Agent: xsolla-api-client/1.0
Host: api.xsolla.com
Accept: application/json
Authorization: Basic ZGVtb0B4c29sbGEuY29tOmRlbW8=
Content-Type: application/json
$ curl -v 'https://api.xsolla.com/merchant/v2/projects/{project_id}/users?offset=1&limit=1' \
-X GET \
-u merchant_id:merchant_api_key

响应

<?php

// example response
$response = array (
    'recordsTotal' => 1,
    'data' =>
        array (
            array (
                'user_id' => 0,
                'user_name' => 'John',
                'user_custom' => 'Smith',
                'email' => 'email@example.com',
                'register_date' => '2014-10-08T21:44:32-08:00',
                'balance' => 100,
                'wallet_amount' => 1.5,
                'wallet_currency' => 'USD',
                'enabled' => true
            )
        )
);
HTTP/1.1 200 OK
Content-Type: application/json

{
    "recordsTotal": 1,
    "data": [
        {
            "user_id": 0,
            "user_name": "John",
            "user_custom": "Smith",
            "email": "email@example.com",
            "register_date": "2014-10-08T21:44:32-08:00",
            "balance": 100,
            "wallet_amount": 1.5,
            "wallet_currency": "USD",
            "enabled": true
        }
    ]
}
{
    "recordsTotal": 1,
    "data": [
        {
            "user_id": 0,
            "user_name": "John",
            "user_custom": "Smith",
            "email": "email@example.com",
            "register_date": "2014-10-08T21:44:32-08:00",
            "balance": 100,
            "wallet_amount": 1.5,
            "wallet_currency": "USD",
            "enabled": true
        }
    ]
}

列示所有操作

列示所有操作。

HTTP 请求

GET https://api.xsolla.com/merchant/v2/projects/{project_id}/users/{user_id}/transactions

参数 类型 描述
project_id
int 游戏 ID。
user_id
string 用户在游戏中的 ID。
datetime_from
datetime 日期范围的开始时间。
datetime_to
datetime 日期范围的结束时间。
transaction_type
string 操作的类型,可以是“payment”、“coupon”、“inGamePurchase”、“internal”或“cancellation”。

请求

<?php

$response = $xsollaClient->ListWalletUserOperations(array(
    'project_id' => PROJECT_ID,
    'user_id' => USER_ID,
    'datetime_from' => '2015-01-01T00:00:00Z',
    'datetime_to' => '2016-01-01T00:00:00Z'
));
GET /merchant/v2/projects/{project_id}/users/{user_id}/transactions?datetime_from=2014-10-14T00%3A00%3A00Z&datetime_to=2014-10-15T00%3A00%3A00Z HTTP/1.1
User-Agent: xsolla-api-client/1.0
Host: api.xsolla.com
Accept: application/json
Authorization: Basic ZGVtb0B4c29sbGEuY29tOmRlbW8=
Content-Type: application/json
$ curl -v 'https://api.xsolla.com/merchant/v2/projects/{project_id}/users/{user_id}/transactions?datetime_from=2014-10-14T00%3A00%3A00Z&datetime_to=2014-10-15T00%3A00%3A00Z' \
-X GET \
-u merchant_id:merchant_api_key

响应

<?php

// example response
$response = array (
    array (
        'operation_id' => 647287,
        'transaction_id' => 1234567,
        'coupon_id' => null,
        'coupon_code' => null,
        'transaction_type' => 'invoice',
        'comment' => 'Incoming payment',
        'date' => '2014-10-28T12:00:00+04:00',
        'amount' => 1000,
        'sum' => 10,
        'currency' => 'USD',
        'status' => 'notified',
        'user_balance' => 100,
        'user_id' => '1234567'
    ),
    array (
        'operation_id' => 647288,
        'transaction_id' => null,
        'coupon_id' => null,
        'coupon_code' => 'DemoCoupon',
        'transaction_type' => 'coupon',
        'comment' => 'Coupon Redeem',
        'date' => '2014-10-28T14:00:00+04:00',
        'amount' => 0,
        'sum' => null,
        'currency' => null,
        'status' => 'failed',
        'user_balance' => 100,
        'user_id' => '1234567'
    )
);
HTTP/1.1 200 OK
Content-Type: application/json

[
    {
        "operation_id": 647287,
        "transaction_id": 1234567,
        "coupon_id": null,
        "coupon_code": null,
        "transaction_type": "invoice",
        "comment": "Incoming payment",
        "date": "2014-10-28T12:00:00+04:00",
        "amount": 1000,
        "sum": 10,
        "currency": "USD",
        "status": "notified",
        "user_balance": 100,
        "user_id": "1234567"
    },
    {
        "operation_id": 647288,
        "transaction_id": null,
        "coupon_id": 12345,
        "coupon_code": "DemoCoupon",
        "transaction_type": "coupon",
        "comment": "Coupon Redeem",
        "date": "2014-10-28T14:00:00+04:00",
        "amount": 0,
        "sum": null,
        "currency": null,
        "status": "failed",
        "user_balance": 100,
        "user_id": "1234567"
    }
]
[
    {
        "operation_id": 647287,
        "transaction_id": 1234567,
        "coupon_id": null,
        "coupon_code": null,
        "transaction_type": "invoice",
        "comment": "Incoming payment",
        "date": "2014-10-28T12:00:00+04:00",
        "amount": 1000,
        "sum": 10,
        "currency": "USD",
        "status": "notified",
        "user_balance": 100,
        "user_id": "1234567"
    },
    {
        "operation_id": 647288,
        "transaction_id": null,
        "coupon_id": 12345,
        "coupon_code": "DemoCoupon",
        "transaction_type": "coupon",
        "comment": "Coupon Redeem",
        "date": "2014-10-28T14:00:00+04:00",
        "amount": 0,
        "sum": null,
        "currency": null,
        "status": "failed",
        "user_balance": 100,
        "user_id": "1234567"
    }
]

更改余额

更改余额。

HTTP 请求

POST https://api.xsolla.com/merchant/v2/projects/{project_id}/users/{user_id}/recharge

参数 类型 描述
project_id
int 游戏 ID。
user_id
string 用户在游戏中的 ID。
amount
float 虚拟货币的金额。
comment
string 通常是更改余额的原因。

请求

<?php

$response = $xsollaClient->RechargeWalletUserBalance(array(
    'project_id' => PROJECT_ID,
    'user_id' => USER_ID,
    'request' => array(
        'amount' => 10,
        'comment' => 'Incoming payment'
    )
));
POST /merchant/v2/projects/{project_id}/users/{user_id}/recharge HTTP/1.1
User-Agent: xsolla-api-client/1.0
Host: api.xsolla.com
Accept: application/json
Authorization: Basic ZGVtb0B4c29sbGEuY29tOmRlbW8=
Content-Type: application/json

{
    "amount": 10,
    "comment": "Incoming payment"
}
$ curl -v 'https://api.xsolla.com/merchant/v2/projects/{project_id}/users/{user_id}/recharge' \
-X POST \
-u merchant_id:merchant_api_key \
-H 'Content-Type: application/json' \
-H 'Accept: application/json' \
-d '{
    "amount": 10,
    "comment": "Incoming payment"
}'

响应

<?php

// example response
$response = array (
    'amount' => 110
);
HTTP/1.1 200 OK
Content-Type: application/json

{
    "amount": 110
}
{
    "amount": 110
}

列示所有虚拟物品

获取用户虚拟物品。

HTTP 请求

GET https://api.xsolla.com/merchant/v2/projects/{project_id}/users/{user_id}/virtual_items

参数 类型 描述
project_id
int 游戏 ID。
user_id
string 用户在游戏中的 ID。
offset
int 用户物品列表的起始页面。
limit
int 获取用户物品列表的限制。

请求

<?php

$response = $xsollaClient->ListWalletUserVirtualItems(array(
    'project_id' => PROJECT_ID,
    'user_id' => USER_ID,
    'limit' => 1,
    'offset' => 0
));
GET /merchant/v2/projects/{project_id}/users/{user_id}/virtual_items?offset=1&limit=1 HTTP/1.1
User-Agent: xsolla-api-client/1.0
Host: api.xsolla.com
Accept: application/json
Authorization: Basic ZGVtb0B4c29sbGEuY29tOmRlbW8=
Content-Type: application/json
$ curl -v 'https://api.xsolla.com/merchant/v2/projects/{project_id}/users/{user_id}/virtual_items?offset=1&limit=1' \
-X GET \
-u merchant_id:merchant_api_key

响应

<?php

// example response
$response = array (
    array (
        'id' => 1,
        'sku' => 'item1',
        'quantity' => 10
    ),
    array (
        'id' => 2,
        'sku' => 'item2',
        'quantity' => 5
    ),
);
HTTP/1.1 200 OK
Content-Type: application/json

[
         {
            "id": 1,
            "sku": "item1",
            "quantity": 10
         },
         {
            "id": 2,
            "sku": "item2",
            "quantity": 5
         }
]
[
         {
            "id": 1,
            "sku": "item1",
            "quantity": 10
         },
         {
            "id": 2,
            "sku": "item2",
            "quantity": 5
         }
]

列出所有用户的虚拟物品

获取项目所有用户的虚拟物品。

HTTP 请求

GET https://api.xsolla.com/merchant/v2/projects/{project_id}/users/virtual_items/total

参数 类型 描述
project_id
int 游戏 ID。
user_id
string 用户在游戏中的 ID。
offset
int 用户物品列表的起始页面。
limit
int 获取用户物品列表的限制。

请求

<?php

$response = $xsollaClient->ListWalletUserVirtualItems(array(
    'project_id' => PROJECT_ID,
    'user_id' => USER_ID,
    'limit' => 1,
    'offset' => 0
));
GET /merchant/v2/projects/{project_id}/users/{user_id}/virtual_items?offset=1&limit=1 HTTP/1.1
User-Agent: xsolla-api-client/1.0
Host: api.xsolla.com
Accept: application/json
Authorization: Basic ZGVtb0B4c29sbGEuY29tOmRlbW8=
Content-Type: application/json
$ curl -v 'https://api.xsolla.com/merchant/v2/projects/{project_id}/users/{user_id}/virtual_items?offset=1&limit=1' \
-X GET \
-u merchant_id:merchant_api_key

响应

<?php

// example response
$response = array (
  array (
      'user_id' => 'V1',
      'virtual_items' =>
          array (
              'id' => 1,
              'sku' => 'item1',
              'quantity' => '10'
            ),
            array (
                'id' => 2,
                'sku' => 'item2',
                'quantity' => '5'
              ),
        ),   
  array (
      'user_id' => 'V2',
      'virtual_items' =>
          array (
              'id' => 1,
              'sku' => 'item1',
              'quantity' => '9'
              ),
        ),            
);
HTTP/1.1 200 OK
Content-Type: application/json

[
{
   "user_id": "V1",
   "virtual_items": [
      {
         "id": 1,
         "sku": "item1",
         "quantity": 10
      },
      {
         "id": 2,
         "sku": "item2",
         "quantity": 5
      }
   ]
},
{
   "user_id": "V2",
   "virtual_items": [
      {
         "id": 1,
         "sku": "item1",
         "quantity": 9
      }
   ]      
}
]
[
{
   "user_id": "V1",
   "virtual_items": [
      {
         "id": 1,
         "sku": "item1",
         "quantity": 10
      },
      {
         "id": 2,
         "sku": "item2",
         "quantity": 5
      }
   ]
},
{
   "user_id": "V2",
   "virtual_items": [
      {
         "id": 1,
         "sku": "item1",
         "quantity": 9
      }
   ]
}
]

为用户添加物品

向用户帐户添加虚拟物品。

HTTP 请求

POST https://api.xsolla.com/merchant/v2/projects/{project_id}/users/{user_id}/virtual_items/add

参数 类型 描述
project_id
int 游戏 ID。
user_id
string 用户在游戏中的 ID。
virtual_items
array 带有虚拟物品相关数据的数组。
virtual_items.virtual_item
object 带有虚拟物品相关数据的对象。
virtual_items.virtual_item.sku
string 物品的唯一 ID。
virtual_items.amount
int 物品金额。

请求

<?php

$response = $xsollaClient->AddVirtualItemToWalletUser(array(
    'project_id' => PROJECT_ID,
    'user_id' => USER_ID,
    'request' => array(
        'virtual_items' => array(
            array(
                'virtual_item' => array(
                    'sku' => 'ar23_shop_expiration_3'
                ),
                'amount' => 2
            )
        )
    )
));
POST /merchant/v2/projects/{project_id}/users/{user_id}/virtual_items/add HTTP/1.1
User-Agent: xsolla-api-client/1.0
Host: api.xsolla.com
Accept: application/json
Authorization: Basic ZGVtb0B4c29sbGEuY29tOmRlbW8=
Content-Type: application/json

{
    "virtual_items": [
        {
            "virtual_item":
                {
                    "sku" : "ar23_shop_expiration_3"
                },
            "amount": 2
        }
    ]
}
$ curl -v 'https://api.xsolla.com/merchant/v2/projects/{project_id}/users/{user_id}/virtual_items/add' \
-X POST \
-u merchant_id:merchant_api_key
-d '{
        "virtual_items": [
            {
                "virtual_item":
                    {
                        "sku" : "ar23_shop_expiration_3"
                    },
                "amount": 2
            }
        ]
    }'

响应

<?php

$response = null;
HTTP/1.1 204 No Content

从用户删除物品

从用户帐户中删除虚拟物品。

HTTP 请求

POST https://api.xsolla.com/merchant/v2/projects/{project_id}/users/{user_id}/virtual_items/remove

参数 类型 描述
project_id
int 游戏 ID。
user_id
string 用户在游戏中的 ID。
virtual_items
array 带有虚拟物品相关数据的数组。
virtual_items.virtual_item
object 带有虚拟物品相关数据的对象。
virtual_items.virtual_item.sku
string 物品的唯一 ID。
virtual_items.amount
int 物品金额。

请求

<?php

$response = $xsollaClient->DeleteVirtualItemFromWalletUser(array(
    'project_id' => PROJECT_ID,
    'user_id' => USER_ID,
    'request' => array(
        'virtual_items' => array(
            array(
                'virtual_item' => array(
                    'sku' => 'ar23_shop_expiration_3'
                ),
                'amount' => 2,
            )
        )
    )
));
POST /merchant/v2/projects/{project_id}/users/{user_id}/virtual_items/remove HTTP/1.1
User-Agent: xsolla-api-client/1.0
Host: api.xsolla.com
Accept: application/json
Authorization: Basic ZGVtb0B4c29sbGEuY29tOmRlbW8=
Content-Type: application/json

{
    "virtual_items": [
        {
            "virtual_item":
                {
                    "sku" : "ar23_shop_expiration_3"
                },
            "amount": 2
        }
    ]
}
$ curl -v 'https://api.xsolla.com/merchant/v2/projects/{project_id}/users/{user_id}/virtual_items/remove' \
-X POST \
-u merchant_id:merchant_api_key
-d '{
        "virtual_items": [
            {
                "virtual_item":
                    {
                        "sku" : "ar23_shop_expiration_3"
                    },
                "amount": 2
            }
        ]
    }'

响应

<?php

$response = null;
HTTP/1.1 204 No Content

创建 游戏交付 实体。

创建 游戏交付 实体。

HTTP REQUEST

POST https://api.xsolla.com/merchant/v2/projects/{project_id}/game_delivery

参数 类型 描述
project_id
int 项目 ID。
sku
string 游戏交付 唯一 ID。SKU 必须仅包含小写拉丁字母、数字、破折号和下划线。
name
object 游戏交付 实体本地化名称的数组。
description
object 游戏交付 实体本地化简单描述的数组。
system_requirements
string 当前游戏的系统要求。
image_url
string 图像 URL。可选。
long_description
string 游戏交付 实体的详细描述。可选。
locales_list
string 本地化语种列表,使用逗号分隔。可选。
publisher
string 游戏的发行商。可选。
developer
string 游戏的开发商。可选。
video_link string 游戏相关视频的链接。可选。
genre
string 游戏类型。可选。
additional_info
string 游戏的附加信息。可选。
forum_link string 论坛的链接。可选。
support_link string 提供支持的联系人网页链接。可选。
old_price
string 游戏的原价。可选。
parent_id
int 父游戏 ID。可选。
default_currency
string 默认的购买币种。使用 ISO 4217 规定的 3 字母组合表示币种。
release_date
string 游戏的预计发布日期。可选。
drm
array 带有 DRM 相关数据的数组。
drm.id
int 可用于本游戏的 DRM 的 ID。
drm.prices
array DRM 游戏价格数组。可选。
drm.platforms
array 带有 DRM 平台相关数据的数组。
drm.platforms.id
int 此 DRM 支持的平台的 ID。
drm.enabled
boolean 是否对此游戏启用 DRM。
obtain_code_from_db
boolean 是否使用我们数据库中的 PIN 码。可选。
obtain_code_from_api
boolean 是否使用通过 API 收到的 PIN 码。可选。

请求

<?php

$response = $xsollaClient->CreateGameDeliveryEntity(array(
    'project_id' => PROJECT_ID,
    'request' => array (
         'sku' => 'GTA5',
         'name' =>
             array (
                 'en' => 'GTA V',
             ),
         'description' =>
             array (
                 'en' => 'Grand Theft Auto V is an open world, action-adventure video game developed by Rockstar North and published by Rockstar Games.',
             ),
         'system_requirements' => 'OS: Windows 8.1 64 Bit, Windows 8 64 Bit, Windows 7 64 Bit Service Pack 1, Windows Vista 64 Bit Service Pack 2* (*NVIDIA video card recommended if running Vista OS)',
         'image_url' => '//cdn2.xsolla.com/img/misc/merchant/default-item.png',
         'long_description' => NULL,
         'locales_list' => NULL,
         'publisher' => NULL,
         'developer' => NULL,
         'video_link' => NULL,
         'genre' => NULL,
         'additional_info' => NULL,
         'forum_link' => NULL,
         'support_link' => NULL,
         'old_price' => NULL,
         'parent_id' => NULL,
         'default_currency' => 'EUR',
         'release_date' => '2016-01-01T00:00:00+00:00',
         'drm' =>
             array (
                 array (
                     'id' => 1,
                     'platforms' =>
                         array (
                             array (
                                 'id' => 1,
                             ),
                             array (
                                 'id' => 2,
                             ),
                         ),
                     'prices' =>
                         array (
                             'USD' => 19.99,
                             'EUR' => 18.5,
                         ),
                     'enabled' => true
                 ),
             ),
         'obtain_code_from_api' => false,
         'obtain_code_from_db' => false,
     )
));
POST /merchant/v2/projects/{project_id}/game_delivery HTTP/1.1
User-Agent: xsolla-api-client/1.0
Host: api.xsolla.com
Accept: application/json
Authorization: Basic ZGVtb0B4c29sbGEuY29tOmRlbW8=
Content-Type: application/json

{
    "sku":"GTA5",
    "name":{
        "en":"GTA V"
    },
    "description":{
        "en":"Grand Theft Auto V is an open world, action-adventure video game developed by Rockstar North and published by Rockstar Games."
    },
    "system_requirements":"OS: Windows 8.1 64 Bit, Windows 8 64 Bit, Windows 7 64 Bit Service Pack 1, Windows Vista 64 Bit Service Pack 2* (*NVIDIA video card recommended if running Vista OS)",
    "image_url":"//cdn2.xsolla.com/img/misc/merchant/default-item.png",
    "long_description":null,
    "locales_list":null,
    "publisher":null,
    "developer":null,
    "video_link":null,
    "genre":null,
    "additional_info":null,
    "forum_link":null,
    "support_link":null,
    "old_price":null,
    "parent_id":null,
    "default_currency":"EUR",
    "release_date":"2016-01-01T00:00:00+00:00",
    "drm":[
        {
            "id":1,
            "platforms":[
                {
                    "id":1
                },
                {
                    "id":2
                }
            ],
            "prices":{
                "USD":19.99,
                "EUR":18.5
            },
            "enabled":true
        }
    ],
    "obtain_code_from_api":false,
    "obtain_code_from_db":false
}
$ curl -v 'https://api.xsolla.com/merchant/v2/projects/{project_id}/game_delivery' \
-X POST \
-u merchant_id:merchant_api_key \
-H 'Content-Type: application/json' \
-H 'Accept: application/json' \
-d '{
    "sku":"GTA5",
    "name":{
        "en":"GTA V"
    },
    "description":{
        "en":"Grand Theft Auto V is an open world, action-adventure video game developed by Rockstar North and published by Rockstar Games."
    },
    "system_requirements":"OS: Windows 8.1 64 Bit, Windows 8 64 Bit, Windows 7 64 Bit Service Pack 1, Windows Vista 64 Bit Service Pack 2* (*NVIDIA video card recommended if running Vista OS)",
    "image_url":"//cdn2.xsolla.com/img/misc/merchant/default-item.png",
    "long_description":null,
    "locales_list":null,
    "publisher":null,
    "developer":null,
    "video_link":null,
    "genre":null,
    "additional_info":null,
    "forum_link":null,
    "support_link":null,
    "old_price":null,
    "parent_id":null,
    "default_currency":"EUR",
    "release_date":"2016-01-01T00:00:00+00:00",
    "drm":[
        {
            "id":1,
            "platforms":[
                {
                    "id":1
                },
                {
                    "id":2
                }
            ],
            "prices":{
                "USD":19.99,
                "EUR":18.5
            },
            "enabled":true
        }
    ],
    "obtain_code_from_api":false,
    "obtain_code_from_db":false
}'

响应

<?php

// example response
$response = array (
    'id' => 77
);
HTTP/1.1 201 Created
Content-Type: application/json

{
    "id": 77
}
{
    "id": 77
}

获取 游戏交付 实体。

获取 游戏交付 实体。

HTTP REQUEST

GET https://api.xsolla.com/merchant/v2/projects/{project_id}/game_delivery/{game_delivery_id}

参数 类型 描述
project_id
int 项目 ID。
game_delivery_id
int 游戏交付 实体的 ID。

请求

<?php

$response = $xsollaClient->GetGameDeliveryEntity(array(
    'project_id' => PROJECT_ID,
    'game_delivery_id' => GAME_DELIVERY_ID
));
GET /merchant/v2/projects/{project_id}/game_delivery/{game_delivery_id} HTTP/1.1
User-Agent: xsolla-api-client/1.0
Host: api.xsolla.com
Accept: application/json
Authorization: Basic ZGVtb0B4c29sbGEuY29tOmRlbW8=
Content-Type: application/json
$ curl -v 'https://api.xsolla.com/merchant/v2/projects/{project_id}/game_delivery/{game_delivery_id}' \
-X GET \
-u merchant_id:merchant_api_key

响应

<?php

// example response
$response = array (
    array (
        'id' => 9,
        'sku' => 'GTA5',
        'name' =>
            array (
                'en' => 'GTA V',
            ),
        'description' =>
            array (
                'en' => 'Grand Theft Auto V is an open world, action-adventure video game developed by Rockstar North and published by Rockstar Games.',
            ),
        'system_requirements' => 'OS: Windows 8.1 64 Bit, Windows 8 64 Bit, Windows 7 64 Bit Service Pack 1, Windows Vista 64 Bit Service Pack 2* (*NVIDIA video card recommended if running Vista OS)',
        'image_url' => '//cdn2.xsolla.com/img/misc/merchant/default-item.png',
        'long_description' => NULL,
        'locales_list' => NULL,
        'publisher' => NULL,
        'developer' => NULL,
        'video_link' => NULL,
        'genre' => NULL,
        'additional_info' => NULL,
        'forum_link' => NULL,
        'support_link' => NULL,
        'old_price' => NULL,
        'parent_id' => NULL,
        'default_currency' => 'EUR',
        'release_date' => '2016-01-01T00:00:00+00:00',
        'drm' =>
            array (
                array (
                    'id' => 1,
                    'name' => 'Steam',
                    'image' => NULL,
                    'platforms' =>
                        array (
                            array (
                                'id' => 1,
                                'name' => 'Windows',
                            ),
                            array (
                                'id' => 2,
                                'name' => 'Linux',
                            ),
                        ),
                    'prices' =>
                        array (
                            'USD' => 19.99,
                            'EUR' => 18.5,
                        ),
                    'codes' =>
                        array (
                            'total' => 0,
                            'active' => 0,
                            'used' => 0,
                        ),
                ),
            ),
        'obtain_code_from_api' => false,
        'obtain_code_from_db' => false,
    )
);
HTTP/1.1 200 OK
Content-Type: application/json

{
    "id": 9,
    "sku": "GTA5",
    "name": {
        "en": "GTA V"
    },
    "description": {
        "en": "Grand Theft Auto V is an open world, action-adventure video game developed by Rockstar North and published by Rockstar Games."
    },
    "system_requirements": "OS: Windows 8.1 64 Bit, Windows 8 64 Bit, Windows 7 64 Bit Service Pack 1, Windows Vista 64 Bit Service Pack 2* (*NVIDIA video card recommended if running Vista OS)",
    "image_url": "//cdn2.xsolla.com/img/misc/merchant/default-item.png",
    "long_description": null,
    "locales_list": null,
    "publisher": null,
    "developer": null,
    "video_link": null,
    "genre": null,
    "additional_info": null,
    "forum_link": null,
    "support_link": null,
    "old_price": null,
    "parent_id": null,
    "default_currency": "EUR",
    "release_date": "2016-01-01T00:00:00+00:00",
    "drm": [
        {
            "id": 1,
            "name": "Steam",
            "image": null,
            "platforms": [
                {
                    "id": 1,
                    "name": "Windows"
                },
                {
                    "id": 2,
                    "name": "Linux"
                }
            ],
            "prices": {
                "USD": 19.99,
                "EUR": 18.5
            },
            "codes": {
                "total": 0,
                "active": 0,
                "used": 0
            }
        },
        {
            "id": 2,
            "name": "Playstation",
            "image": null,
            "platforms": [
                {
                    "id": 3,
                    "name": "Playstation 3"
                },
                {
                    "id": 4,
                    "name": "Playstation 4"
                }
            ],
            "prices": {
                "USD": 19.99,
                "EUR": 18.5
            },
            "codes": {
                "total": 0,
                "active": 0,
                "used": 0
            }
        }
    ],
    "obtain_code_from_api": false,
    "obtain_code_from_db": false
}
{
    "id": 9,
    "sku": "GTA5",
    "name": {
        "en": "GTA V"
    },
    "description": {
        "en": "Grand Theft Auto V is an open world, action-adventure video game developed by Rockstar North and published by Rockstar Games."
    },
    "system_requirements": "OS: Windows 8.1 64 Bit, Windows 8 64 Bit, Windows 7 64 Bit Service Pack 1, Windows Vista 64 Bit Service Pack 2* (*NVIDIA video card recommended if running Vista OS)",
    "image_url": "//cdn2.xsolla.com/img/misc/merchant/default-item.png",
    "long_description": null,
    "locales_list": null,
    "publisher": null,
    "developer": null,
    "video_link": null,
    "genre": null,
    "additional_info": null,
    "forum_link": null,
    "support_link": null,
    "old_price": null,
    "parent_id": null,
    "default_currency": "EUR",
    "release_date": "2016-01-01T00:00:00+00:00",
    "drm": [
        {
            "id": 1,
            "name": "Steam",
            "image": null,
            "platforms": [
                {
                    "id": 1,
                    "name": "Windows"
                },
                {
                    "id": 2,
                    "name": "Linux"
                }
            ],
            "prices": {
                "USD": 19.99,
                "EUR": 18.5
            },
            "codes": {
                "total": 0,
                "active": 0,
                "used": 0
            }
        },
        {
            "id": 2,
            "name": "Playstation",
            "image": null,
            "platforms": [
                {
                    "id": 3,
                    "name": "Playstation 3"
                },
                {
                    "id": 4,
                    "name": "Playstation 4"
                }
            ],
            "prices": {
                "USD": 19.99,
                "EUR": 18.5
            },
            "codes": {
                "total": 0,
                "active": 0,
                "used": 0
            }
        }
    ],
    "obtain_code_from_api": false,
    "obtain_code_from_db": false
}

更新 游戏交付 实体。

更新 游戏交付 实体。

HTTP REQUEST

PUT https://api.xsolla.com/merchant/v2/projects/{project_id}/game_delivery/{game_delivery_id}

参数 类型 描述
project_id
int 项目 ID。
game_delivery_id
int 游戏交付 实体的 ID。
sku
string 游戏交付 唯一 ID。SKU 必须仅包含小写拉丁字母、数字、破折号和下划线。
name
object 游戏交付 实体本地化名称的数组。
description
object 游戏交付 实体本地化简单描述的数组。
system_requirements
string 当前游戏的系统要求。
image_url
string 图像 URL。可选。
long_description
string 游戏交付 实体的详细描述。可选。
locales_list
string 本地化语种列表,使用逗号分隔。可选。
publisher
string 游戏的发行商。可选。
developer
string 游戏的开发商。可选。
video_link string 游戏相关视频的链接。可选。
genre
string 游戏类型。可选。
additional_info
string 游戏的附加信息。可选。
forum_link string 论坛的链接。可选。
support_link string 提供支持的联系人网页链接。可选。
old_price
string 游戏的原价。可选。
parent_id
int 父游戏 ID。可选。
default_currency
string 默认的购买币种。使用 ISO 4217 规定的 3 字母组合表示币种。
release_date
string 游戏的预计发布日期。可选。
drm
array 带有 DRM 相关数据的数组。
drm.id
int 可用于本游戏的 DRM 的 ID。
drm.prices
array DRM 游戏价格数组。可选。
drm.platforms
array 带有 DRM 平台相关数据的数组。
drm.platforms.id
int 此 DRM 支持的平台的 ID。
drm.enabled
boolean 是否对此游戏启用 DRM。
obtain_code_from_db
boolean 是否使用我们数据库中的 PIN 码。可选。
obtain_code_from_api
boolean 是否使用通过 API 收到的 PIN 码。可选。

请求

<?php

$response = $xsollaClient->UpdateGameDeliveryEntity(array(
    'project_id' => PROJECT_ID,
    'game_delivery_id' => GAME_DELIVERY_ID
    'request' => array (
         'sku' => 'GTA5',
         'name' =>
             array (
                 'en' => 'GTA V',
             ),
         'description' =>
             array (
                 'en' => 'Grand Theft Auto V is an open world, action-adventure video game developed by Rockstar North and published by Rockstar Games.',
             ),
         'system_requirements' => 'OS: Windows 8.1 64 Bit, Windows 8 64 Bit, Windows 7 64 Bit Service Pack 1, Windows Vista 64 Bit Service Pack 2* (*NVIDIA video card recommended if running Vista OS)',
         'image_url' => '//cdn2.xsolla.com/img/misc/merchant/default-item.png',
         'long_description' => NULL,
         'locales_list' => NULL,
         'publisher' => NULL,
         'developer' => NULL,
         'video_link' => NULL,
         'genre' => NULL,
         'additional_info' => NULL,
         'forum_link' => NULL,
         'support_link' => NULL,
         'old_price' => NULL,
         'parent_id' => NULL,
         'default_currency' => 'EUR',
         'release_date' => '2016-01-01T00:00:00+00:00',
         'drm' =>
             array (
                 array (
                     'id' => 1,
                     'platforms' =>
                         array (
                             array (
                                 'id' => 1,
                             ),
                             array (
                                 'id' => 2,
                             ),
                         ),
                     'prices' =>
                         array (
                             'USD' => 19.99,
                             'EUR' => 18.5,
                         ),
                     'enabled' => true
                 ),
             ),
         'obtain_code_from_api' => false,
         'obtain_code_from_db' => false,
     )
));
PUT /merchant/v2/projects/{project_id}/game_delivery/{game_delivery_id} HTTP/1.1
User-Agent: xsolla-api-client/1.0
Host: api.xsolla.com
Accept: application/json
Authorization: Basic ZGVtb0B4c29sbGEuY29tOmRlbW8=
Content-Type: application/json
{
    "sku":"GTA5",
    "name":{
        "en":"GTA V"
    },
    "description":{
        "en":"Grand Theft Auto V is an open world, action-adventure video game developed by Rockstar North and published by Rockstar Games."
    },
    "system_requirements":"OS: Windows 8.1 64 Bit, Windows 8 64 Bit, Windows 7 64 Bit Service Pack 1, Windows Vista 64 Bit Service Pack 2* (*NVIDIA video card recommended if running Vista OS)",
    "image_url":"//cdn2.xsolla.com/img/misc/merchant/default-item.png",
    "long_description":null,
    "locales_list":null,
    "publisher":null,
    "developer":null,
    "video_link":null,
    "genre":null,
    "additional_info":null,
    "forum_link":null,
    "support_link":null,
    "old_price":null,
    "parent_id":null,
    "default_currency":"EUR",
    "release_date":"2016-01-01T00:00:00+00:00",
    "drm":[
        {
            "id":1,
            "platforms":[
                {
                    "id":1
                },
                {
                    "id":2
                }
            ],
            "prices":{
                "USD":19.99,
                "EUR":18.5
            },
            "enabled":true
        }
    ],
    "obtain_code_from_api":false,
    "obtain_code_from_db":false
}
$ curl -v 'https://api.xsolla.com/merchant/v2/projects/{project_id}/game_delivery/{game_delivery_id}' \
-X PUT \
-u merchant_id:merchant_api_key \
-H 'Content-Type: application/json' \
-H 'Accept: application/json' \
-d '{
    "sku":"GTA5",
    "name":{
        "en":"GTA V"
    },
    "description":{
        "en":"Grand Theft Auto V is an open world, action-adventure video game developed by Rockstar North and published by Rockstar Games."
    },
    "system_requirements":"OS: Windows 8.1 64 Bit, Windows 8 64 Bit, Windows 7 64 Bit Service Pack 1, Windows Vista 64 Bit Service Pack 2* (*NVIDIA video card recommended if running Vista OS)",
    "image_url":"//cdn2.xsolla.com/img/misc/merchant/default-item.png",
    "long_description":null,
    "locales_list":null,
    "publisher":null,
    "developer":null,
    "video_link":null,
    "genre":null,
    "additional_info":null,
    "forum_link":null,
    "support_link":null,
    "old_price":null,
    "parent_id":null,
    "default_currency":"EUR",
    "release_date":"2016-01-01T00:00:00+00:00",
    "drm":[
        {
            "id":1,
            "platforms":[
                {
                    "id":1
                },
                {
                    "id":2
                }
            ],
            "prices":{
                "USD":19.99,
                "EUR":18.5
            },
            "enabled":true
        }
    ],
    "obtain_code_from_api":false,
    "obtain_code_from_db":false
}'

响应

<?php

$response = null;
HTTP/1.1 204 No Content

所有 游戏交付 实体的列表。

所有 游戏交付 实体的列表。

HTTP REQUEST

GET https://api.xsolla.com/merchant/v2/projects/{project_id}/game_delivery

参数 类型 描述
project_id
int 项目 ID。

请求

<?php

$response = $xsollaClient->ListGameDeliveryEntities(array(
    'project_id' => PROJECT_ID
));
GET /merchant/v2/projects/{project_id}/game_delivery HTTP/1.1
User-Agent: xsolla-api-client/1.0
Host: api.xsolla.com
Accept: application/json
Authorization: Basic ZGVtb0B4c29sbGEuY29tOmRlbW8=
Content-Type: application/json
$ curl -v 'https://api.xsolla.com/merchant/v2/projects/{project_id}/game_delivery' \
-X GET \
-u merchant_id:merchant_api_key

响应

<?php

// example response
$response = array (
    array (
        array (
            'id' => 9,
            'localized_name' => 'GTA V',
            'parent_id' => NULL,
            'default_currency' => 'EUR',
            'drm' =>
                array (
                    array (
                        'id' => 1,
                        'name' => 'Steam',
                        'image' => NULL,
                        'platforms' =>
                            array (
                                array (
                                    'id' => 1,
                                    'name' => 'Windows',
                                ),
                                array (
                                    'id' => 2,
                                    'name' => 'Linux',
                                ),
                            ),
                        'prices' =>
                            array (
                                'USD' => 19.99,
                                'EUR' => 18.5,
                            ),
                        'codes' =>
                            array (
                                'total' => 1000,
                                'active' => 999,
                                'used' => 1,
                            ),
                        ),
                    array (
                        'id' => 2,
                        'name' => 'Playstation',
                        'image' => NULL,
                        'platforms' =>
                            array (
                                array (
                                    'id' => 3,
                                    'name' => 'Playstation 3',
                                ),
                                array (
                                    'id' => 4,
                                    'name' => 'Playstation 4',
                                ),
                            ),
                        'prices' =>
                            array (
                                'USD' => 19.99,
                                'EUR' => 18.5,
                            ),
                        'codes' =>
                            array (
                                'total' => 1000,
                                'active' => 999,
                                'used' => 1,
                            ),
                    ),
                ),
        ),
    )
);
HTTP/1.1 200 OK
Content-Type: application/json

[
    {
        "id": 9,
        "localized_name": "GTA V",
        "parent_id": null,
        "default_currency": "EUR",
        "drm": [
            {
                "id": 1,
                "name": "Steam",
                "image": null,
                "platforms": [
                    {
                        "id": 1,
                        "name": "Windows"
                    },
                    {
                        "id": 2,
                        "name": "Linux"
                    }
                ],
                "prices": {
                    "USD": 19.99,
                    "EUR": 18.5
                },
                "codes": {
                    "total": 1000,
                    "active": 999,
                    "used": 1
                }
            },
            {
                "id": 2,
                "name": "Playstation",
                "image": null,
                "platforms": [
                    {
                        "id": 3,
                        "name": "Playstation 3"
                    },
                    {
                        "id": 4,
                        "name": "Playstation 4"
                    }
                ],
                "prices": {
                    "USD": 19.99,
                    "EUR": 18.5
                },
                "codes": {
                    "total": 1000,
                    "active": 999,
                    "used": 1
                }
            }
        ]
    }
]
[
    {
        "id": 9,
        "localized_name": "GTA V",
        "parent_id": null,
        "default_currency": "EUR",
        "drm": [
            {
                "id": 1,
                "name": "Steam",
                "image": null,
                "platforms": [
                    {
                        "id": 1,
                        "name": "Windows"
                    },
                    {
                        "id": 2,
                        "name": "Linux"
                    }
                ],
                "prices": {
                    "USD": 19.99,
                    "EUR": 18.5
                },
                "codes": {
                    "total": 1000,
                    "active": 999,
                    "used": 1
                }
            },
            {
                "id": 2,
                "name": "Playstation",
                "image": null,
                "platforms": [
                    {
                        "id": 3,
                        "name": "Playstation 3"
                    },
                    {
                        "id": 4,
                        "name": "Playstation 4"
                    }
                ],
                "prices": {
                    "USD": 19.99,
                    "EUR": 18.5
                },
                "codes": {
                    "total": 1000,
                    "active": 999,
                    "used": 1
                }
            }
        ]
    }
]

可用 DRM 平台的列表。

可用 DRM 平台的列表。

HTTP REQUEST

GET https://api.xsolla.com/merchant/v2/merchants/{merchant_id}/drm

参数 类型 描述
merchant_id
int 商户 ID。

请求

<?php

$response = $xsollaClient->ListGameDeliveryDrmPlatforms();
GET /merchant/v2/merchants/{merchant_id}/drm HTTP/1.1
User-Agent: xsolla-api-client/1.0
Host: api.xsolla.com
Accept: application/json
Authorization: Basic ZGVtb0B4c29sbGEuY29tOmRlbW8=
Content-Type: application/json
$ curl -v 'https://api.xsolla.com/merchant/v2/merchants/{merchant_id}/drm' \
-X GET \
-u merchant_id:merchant_api_key

响应

<?php

// example response
$response = array (
    array (
        'drm' =>
            array (
                array (
                    'id' => 1,
                    'name' => 'Steam',
                    'image' => '//cdn2.xsolla.com/misc/game_delivery/drms/set2/1.1450132085.png',
                ),
                array (
                    'id' => 2,
                    'name' => 'Playstation',
                    'image' => '//cdn2.xsolla.com/misc/game_delivery/drms/set2/2.1449183647.png',
                ),
                array (
                    'id' => 3,
                    'name' => 'XBox',
                    'image' => '//cdn2.xsolla.com/misc/game_delivery/drms/set2/3.1449183647.png',
                )
            ),
        'platforms' =>
            array (
                array (
                    'id' => 1,
                    'name' => 'Windows',
                ),
                array (
                    'id' => 2,
                    'name' => 'Linux',
                ),
                array (
                    'id' => 3,
                    'name' => 'Playstation 4',
                ),
            ),
    )
);
HTTP/1.1 200 OK
Content-Type: application/json

{
    "drm": [
        {
            "id": 1,
            "name": "Steam",
            "image": "//cdn2.xsolla.com/misc/game_delivery/drms/set2/1.1450132085.png"
        },
        {
            "id": 2,
            "name": "Playstation",
            "image": "//cdn2.xsolla.com/misc/game_delivery/drms/set2/2.1449183647.png"
        },
        {
            "id": 3,
            "name": "XBox",
            "image": "//cdn2.xsolla.com/misc/game_delivery/drms/set2/3.1449183647.png"
        },
        {
            "id": 4,
            "name": "Uplay",
            "image": "//cdn2.xsolla.com/misc/game_delivery/drms/set2/4.1450201713.png"
        },
        {
            "id": 5,
            "name": "Origin",
            "image": "//cdn2.xsolla.com/misc/game_delivery/drms/set2/5.1450201747.png"
        },
        {
            "id": 6,
            "name": "DRM Free",
            "image": "//cdn2.xsolla.com/misc/game_delivery/drms/set2/6.1450201849.png"
        }
    ],
    "platforms": [
        {
            "id": 1,
            "name": "Windows"
        },
        {
            "id": 2,
            "name": "Linux"
        },
        {
            "id": 3,
            "name": "Playstation 3"
        },
        {
            "id": 4,
            "name": "Playstation 4"
        },
        {
            "id": 5,
            "name": "XBox One"
        },
        {
            "id": 6,
            "name": "Mac"
        },
        {
            "id": 7,
            "name": "XBox 360"
        }
    ]
}
{
    "drm": [
        {
            "id": 1,
            "name": "Steam",
            "image": "//cdn2.xsolla.com/misc/game_delivery/drms/set2/1.1450132085.png"
        },
        {
            "id": 2,
            "name": "Playstation",
            "image": "//cdn2.xsolla.com/misc/game_delivery/drms/set2/2.1449183647.png"
        },
        {
            "id": 3,
            "name": "XBox",
            "image": "//cdn2.xsolla.com/misc/game_delivery/drms/set2/3.1449183647.png"
        },
        {
            "id": 4,
            "name": "Uplay",
            "image": "//cdn2.xsolla.com/misc/game_delivery/drms/set2/4.1450201713.png"
        },
        {
            "id": 5,
            "name": "Origin",
            "image": "//cdn2.xsolla.com/misc/game_delivery/drms/set2/5.1450201747.png"
        },
        {
            "id": 6,
            "name": "DRM Free",
            "image": "//cdn2.xsolla.com/misc/game_delivery/drms/set2/6.1450201849.png"
        }
    ],
    "platforms": [
        {
            "id": 1,
            "name": "Windows"
        },
        {
            "id": 2,
            "name": "Linux"
        },
        {
            "id": 3,
            "name": "Playstation 3"
        },
        {
            "id": 4,
            "name": "Playstation 4"
        },
        {
            "id": 5,
            "name": "XBox One"
        },
        {
            "id": 6,
            "name": "Mac"
        },
        {
            "id": 7,
            "name": "XBox 360"
        }
    ]
}

获取优惠券

按代码获取有关优惠券的信息。

HTTP 请求

GET https://api.xsolla.com/merchant/v2/projects/{project_id}/coupons/{code}

参数 类型 描述
project_id
int 游戏 ID。
code
string 优惠券代码。

请求

<?php

$response = $xsollaClient->GetCoupon(array(
    'project_id' => PROJECT_ID,
    'code' => COUPON_CODE
));
GET /merchant/v2/projects/{project_id}/coupons/{code} HTTP/1.1
User-Agent: xsolla-api-client/1.0
Host: api.xsolla.com
Accept: application/json
Authorization: Basic ZGVtb0B4c29sbGEuY29tOmRlbW8=
Content-Type: application/json
$ curl -v 'https://api.xsolla.com/merchant/v2/projects/{project_id}/coupons/{code}' \
-X GET \
-u merchant_id:merchant_api_key

响应

<?php

// example response
$response = array (
    'coupon_id' => 1,
    'project_id' => 1,
    'coupon_code' => 'CouPoNCoDe',
    'campaign_code' => 'CaMPaiGNCoDe',
    'virtual_currency_amount' => 0,
    'is_active' => 1,
    'redeems_count_remain' => 1,
    'redeems_count_for_user' => null,
    'expiration_date' => '2014-10-16 21:44:31',
    'virtual_items' =>
        array (
            'virtual_item' =>
                array (
                    'id' => 77,
                    'sku' => 'T-43-3-unique-id',
                    'item_code' => null,
                    'advertisement_type' => null,
                    'name' =>
                        array (
                            'en' => 'T-34-3',
                        ),
                    'description' =>
                        array (
                            'en' => 'This Chinese Tier VIII medium tank is a real beast in its class.',
                        ),
                    'long_description' =>
                        array (
                        ),
                    'prices' =>
                        array (
                            'USD' => 40.09,
                        ),
                    'default_currency' => 'USD',
                    'enabled' => true,
                    'permanent' => false,
                    'purchase_limit' => 1,
                    'keywords' =>
                        array (
                        ),
                    'image_url' => 'http://livedemo.xsolla.com/airplanes/tank5.jpg',
                    'groups' =>
                        array (25),
                    'item_type' => 'Expiration',
                    'expiration' => 1296000,
                    'virtual_currency_price' => null,
                ),
            'amount' => 1
        )
);
HTTP/1.1 200 OK
Content-Type: application/json

{
    "coupon_id": 1,
    "project_id": 1,
    "coupon_code": "CouPoNCoDe",
    "campaign_code": "CaMPaiGNCoDe",
    "virtual_currency_amount": 0,
    "is_active": 1,
    "redeems_count_remain": 1,
    "redeems_count_for_user": null,
    "expiration_date": "2014-10-16 21:44:31",
    "virtual_items": {
        "virtual_item": {
            "id": 77,
            "sku": "T-43-3-unique-id",
            "item_code": "chinese-medium-tank",
            "advertisement_type": null,
            "name": {
                "en": "T-34-3"
            },
            "description": {
                "en": "This Chinese Tier VIII medium tank is a real beast in its class."
            },
            "long_description": [],
            "prices": {
                "USD": 40.09
            },
            "default_currency": "USD",
            "enabled": true,
            "permanent": false,
            "purchase_limit": 1,
            "keywords": [],
            "image_url": "http:\/\/livedemo.xsolla.com\/airplanes\/tank5.jpg",
            "groups": [
                25
            ],
            "item_type": "Expiration",
            "expiration": 1296000,
            "virtual_currency_price": null,
            "item_code": null
        },
        "amount": 1
    }
}
{
    "coupon_id": 1,
    "project_id": 1,
    "coupon_code": "CouPoNCoDe",
    "campaign_code": "CaMPaiGNCoDe",
    "virtual_currency_amount": 0,
    "is_active": 1,
    "redeems_count_remain": 1,
    "redeems_count_for_user": null,
    "expiration_date": "2014-10-16 21:44:31",
    "virtual_items": {
        "virtual_item": {
            "id": 77,
            "sku": "T-43-3-unique-id",
            "item_code": "chinese-medium-tank",
            "advertisement_type": null,
            "name": {
                "en": "T-34-3"
            },
            "description": {
                "en": "This Chinese Tier VIII medium tank is a real beast in its class."
            },
            "long_description": [],
            "prices": {
                "USD": 40.09
            },
            "default_currency": "USD",
            "enabled": true,
            "permanent": false,
            "purchase_limit": 1,
            "keywords": [],
            "image_url": "http:\/\/livedemo.xsolla.com\/airplanes\/tank5.jpg",
            "groups": [
                25
            ],
            "item_type": "Expiration",
            "expiration": 1296000,
            "virtual_currency_price": null,
            "item_code": null
        },
        "amount": 1
    }
}

兑换优惠券

按代码兑换优惠券。

HTTP 请求

POST https://api.xsolla.com/merchant/v2/projects/{project_id}/coupons/{code}/redeem

参数 类型 描述
project_id
int 游戏 ID。
code
string 优惠券代码。
user_id
string 用户在游戏中的 ID。

请求

<?php

$response = $xsollaClient->RedeemCoupon(array(
    'project_id' => PROJECT_ID,
    'code' => COUPON_CODE,
    'request' => array(
        'user_id' => 1
    )
));
POST /merchant/v2/projects/{project_id}/coupons/{code}/redeem HTTP/1.1
User-Agent: xsolla-api-client/1.0
Host: api.xsolla.com
Accept: application/json
Authorization: Basic ZGVtb0B4c29sbGEuY29tOmRlbW8=
Content-Type: application/json

{
    "user_id": 1
}
$ curl -v 'https://api.xsolla.com/merchant/v2/projects/{project_id}/coupons/{code}/redeem' \
-X POST \
-u merchant_id:merchant_api_key \
-H 'Content-Type: application/json' \
-H 'Accept: application/json' \
-d '{
    "user_id": 1
}'

响应

<?php

// example response
$response = array (
    'coupon_id' => 1,
    'project_id' => 1,
    'coupon_code' => 'CouPoNCoDe',
    'campaign_code' => 'CaMPaiGNCoDe',
    'virtual_currency_amount' => 0,
    'is_active' => 1,
    'redeems_count_remain' => 1,
    'redeems_count_for_user' => null,
    'expiration_date' => '2014-10-16 21:44:31',
    'virtual_items' =>
        array (
            'virtual_item' =>
                array (
                    'id' => 77,
                    'sku' => 'T-43-3-unique-id',
                    'item_code' => null,
                    'advertisement_type' => null,
                    'name' =>
                        array (
                            'en' => 'T-34-3',
                        ),
                    'description' =>
                        array (
                            'en' => 'This Chinese Tier VIII medium tank is a real beast in its class.',
                        ),
                    'long_description' =>
                        array (
                        ),
                    'prices' =>
                        array (
                            'USD' => 40.09,
                        ),
                    'default_currency' => 'USD',
                    'enabled' => true,
                    'permanent' => false,
                    'purchase_limit' => 1,
                    'keywords' =>
                        array (
                        ),
                    'image_url' => 'http://livedemo.xsolla.com/airplanes/tank5.jpg',
                    'groups' =>
                        array (25),
                    'item_type' => 'Expiration',
                    'expiration' => 1296000,
                    'virtual_currency_price' => null,
                ),
            'amount' => 1
        )
);
HTTP/1.1 200 OK
Content-Type: application/json

{
    "coupon_id": 1,
    "project_id": 1,
    "coupon_code": "CouPoNCoDe",
    "campaign_code": "CaMPaiGNCoDe",
    "virtual_currency_amount": 0,
    "is_active": 1,
    "redeems_count_remain": 1,
    "redeems_count_for_user": null,
    "expiration_date": "2014-10-16 21:44:31",
    "virtual_items": {
        "virtual_item": {
            "id": 77,
            "sku": "T-43-3-unique-id",
            "item_code": "chinese-medium-tank",
            "advertisement_type": null,
            "name": {
                "en": "T-34-3"
            },
            "description": {
                "en": "This Chinese Tier VIII medium tank is a real beast in its class."
            },
            "long_description": [],
            "prices": {
                "USD": 40.09
            },
            "default_currency": "USD",
            "enabled": true,
            "permanent": false,
            "purchase_limit": 1,
            "keywords": [],
            "image_url": "http:\/\/livedemo.xsolla.com\/airplanes\/tank5.jpg",
            "groups": [
                25
            ],
            "item_type": "Expiration",
            "expiration": 1296000,
            "virtual_currency_price": null,
            "item_code": null
        },
        "amount": 1
    }
}
{
    "coupon_id": 1,
    "project_id": 1,
    "coupon_code": "CouPoNCoDe",
    "campaign_code": "CaMPaiGNCoDe",
    "virtual_currency_amount": 0,
    "is_active": 1,
    "redeems_count_remain": 1,
    "redeems_count_for_user": null,
    "expiration_date": "2014-10-16 21:44:31",
    "virtual_items": {
        "virtual_item": {
            "id": 77,
            "sku": "T-43-3-unique-id",
            "item_code": "chinese-medium-tank",
            "advertisement_type": null,
            "name": {
                "en": "T-34-3"
            },
            "description": {
                "en": "This Chinese Tier VIII medium tank is a real beast in its class."
            },
            "long_description": [],
            "prices": {
                "USD": 40.09
            },
            "default_currency": "USD",
            "enabled": true,
            "permanent": false,
            "purchase_limit": 1,
            "keywords": [],
            "image_url": "http:\/\/livedemo.xsolla.com\/airplanes\/tank5.jpg",
            "groups": [
                25
            ],
            "item_type": "Expiration",
            "expiration": 1296000,
            "virtual_currency_price": null,
            "item_code": null
        },
        "amount": 1
    }
}

创建新促销活动

创建新促销活动。

HTTP 请求

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

Parameter Type 描述
merchant_id
int 商户 ID。
technical_name
string 促销活动的技术名称。
label
array of strings 本地化标签数组,显示在支付 UI 中。
name
array of strings 本地化促销活动名称的数组。
description
array of strings 本地化促销活动描述的数组。
project_id
int 要应用促销活动的游戏 ID。

请求

<?php

$response = $xsollaClient->CreatePromotion(array(
    'request' => array (
         'technical_name' => 'Sample Promotion',
         'label' =>
              array (
                  'en' => '30% SAVE',
              ),
         'name' =>
             array (
                 'en' => '30% PayPal Discount',
             ),
         'description' =>
             array (
                 'en' => '30% PayPal Discount Sample',
             ),
         'project_id' => 1,
     )
));
POST /merchant/v2/merchants/{merchant_id}/promotions HTTP/1.1
User-Agent: xsolla-api-client/1.0
Host: api.xsolla.com
Accept: application/json
Authorization: Basic ZGVtb0B4c29sbGEuY29tOmRlbW8=
Content-Type: application/json

{
    "technical_name": "Sample Promotion",
    "label": {
        "en": "30% SAVE"
    },
    "name": {
        "en": "30% PayPal Discount"
    },
    "description": {
        "en": "30% PayPal Discount Sample"
    },
    "project_id": 1
}
$ curl -v 'https://api.xsolla.com/merchant/v2/merchants/{merchant_id}/promotions' \
-X POST \
-u merchant_id:merchant_api_key \
-H 'Content-Type: application/json' \
-H 'Accept: application/json' \
-d '{
        "technical_name": "Sample Promotion",
        "label": {
            "en": "30% SAVE"
        },
        "name": {
            "en": "30% PayPal Discount"
        },
        "description": {
            "en": "30% PayPal Discount Sample"
        },
        "project_id": 1
    }'

响应

<?php

// example response
$response = array (
    'id' => 1
);
HTTP/1.1 201 Created

{
    "id": 1
}
{
    "id": 1
}

获取促销活动

获取促销活动。

HTTP 请求

GET https://api.xsolla.com/merchant/v2/merchants/{merchant_id}/promotions/{promotion_id}

参数 类型 描述
merchant_id
int 商户 ID。
promotion_id
int 促销活动 ID。

请求

<?php

$response = $xsollaClient->GetPromotion(array(
    'promotion_id' => 'PROMOTION_ID'
));
GET /merchant/v2/merchants/{merchant_id}/promotions/{promotion_id} HTTP/1.1
User-Agent: xsolla-api-client/1.0
Host: api.xsolla.com
Accept: application/json
Authorization: Basic ZGVtb0B4c29sbGEuY29tOmRlbW8=
Content-Type: application/json
$ curl -v 'https://api.xsolla.com/merchant/v2/merchants/{merchant_id}/promotions/{promotion_id}' \
-X GET \
-u merchant_id:merchant_api_key

响应

<?php

// example response
$response = array (
    'id' => 1,
    'project_id' => 1,
    'technical_name' => 'Sample Promotion',
    'name' =>
        array (
            'en' => '30% PayPal Discount'
        ),
    'description' =>
        array (
            'en' => '30% PayPal Discount Sample'
        ),
    'read_only' => false,
    'enabled' => false
);
HTTP/1.1 200 OK
Content-Type: application/json

{
    "id": 1,
    "project_id": 1,
    "technical_name": "Sample Promotion",
    "label": {
        "en": "30% SAVE"
    },
    "name": {
        "en": "30% PayPal Discount"
    },
    "description": {
        "en": "30% PayPal Discount Sample"
    },
    "read_only": false,
    "enabled": false
}
{
    "id": 1,
    "project_id": 1,
    "technical_name": "Sample Promotion",
    "label": {
        "en": "30% SAVE"
    },
    "name": {
        "en": "30% PayPal Discount"
    },
    "description": {
        "en": "30% PayPal Discount Sample"
    },
    "read_only": false,
    "enabled": false
}

更新促销活动

更新促销活动。如果促销活动为只读 ("read_only" = true),则不允许更改"project_id"参数。

HTTP 请求

PUT https://api.xsolla.com/merchant/v2/merchants/{merchant_id}/promotions/{promotion_id}

Parameter Type 描述
merchant_id
int 商户 ID。
promotion_id
int 促销活动 ID。
technical_name
string 促销活动的技术名称。
label
array of strings 本地化标签数组,显示在支付 UI 中。
name
array of strings 本地化促销名称数组。
description
array of strings 本地化促销描述数组。
project_id
int 要应用促销活动的游戏 ID。

请求

<?php

$response = $xsollaClient->UpdatePromotion(array(
    'request' => array (
         'technical_name' => 'Sample Promotion',
         'label' =>
              array (
                  'en' => '30% SAVE',
              ),
         'name' =>
             array (
                 'en' => '30% PayPal Discount',
             ),
         'description' =>
             array (
                 'en' => '30% PayPal Discount Sample',
             ),
         'project_id' => 1,
     )
));
PUT /merchant/v2/merchants/{merchant_id}/promotions/{promotion_id} HTTP/1.1
User-Agent: xsolla-api-client/1.0
Host: api.xsolla.com
Accept: application/json
Authorization: Basic ZGVtb0B4c29sbGEuY29tOmRlbW8=
Content-Type: application/json

{
    "technical_name": "Sample Promotion",
    "label": {
        "en": "30% SAVE"
    },
    "name": {
        "en": "30% PayPal Discount"
    },
    "description": {
        "en": "30% PayPal Discount Sample"
    },
    "project_id": 1
}
$ curl -v 'https://api.xsolla.com/merchant/v2/merchants/{merchant_id}/promotions/{promotion_id}' \
-X PUT \
-u merchant_id:merchant_api_key \
-H 'Content-Type: application/json' \
-H 'Accept: application/json' \
-d '{
        "technical_name": "Sample Promotion",
        "label": {
            "en": "30% SAVE"
        },
        "name": {
            "en": "30% PayPal Discount"
        },
        "description": {
            "en": "30% PayPal Discount Sample"
        },
        "project_id": 1
    }'

响应

<?php

$response = null;
HTTP/1.1 204 No Content

检查促销活动

检查促销活动是否准备好激活。此方法可返回错误列表(如果存在)。

HTTP 请求

GET https://api.xsolla.com/merchant/v2/merchants/{merchant_id}/promotions/{promotion_id}/review

参数 类型 描述
merchant_id
int 商户 ID。
promotion_id
int 促销活动 ID。

请求

<?php

$response = $xsollaClient->ReviewPromotion(array(
    'promotion_id' => 'PROMOTION_ID'
));
GET /merchant/v2/merchants/{merchant_id}/promotions/{promotion_id}/review HTTP/1.1
User-Agent: xsolla-api-client/1.0
Host: api.xsolla.com
Accept: application/json
Authorization: Basic ZGVtb0B4c29sbGEuY29tOmRlbW8=
Content-Type: application/json
$ curl -v 'https://api.xsolla.com/merchant/v2/merchants/{merchant_id}/promotions/{promotion_id}/review' \
-X GET \
-u merchant_id:merchant_api_key

响应

<?php

// example response
$response = array (
    array (
        'component' => 'rewards',
        'message' => 'You didn\'t select any reward'
    ),
    array (
        'component' => 'periods',
        'message' => 'Please set the promotion time periods.'
    )
);
HTTP/1.1 200 OK
Content-Type: application/json

[
  {
    "component": "rewards",
    "message": "You didn't select any reward"
  },
  {
    "component": "periods",
    "message": "Please set the promotion time periods."
  }
]
[
  {
    "component": "rewards",
    "message": "You didn't select any reward"
  },
  {
    "component": "periods",
    "message": "Please set the promotion time periods."
  }
]

切换促销活动

切换促销活动。将促销活动的状态从启用更改为禁用,反之亦然。

HTTP 请求

PUT https://api.xsolla.com/merchant/v2/merchants/{merchant_id}/promotions/{promotion_id}/toggle

Parameter Type 描述
merchant_id
int 商户 ID。
promotion_id
int 促销活动 ID。

请求

<?php

$response = $xsollaClient->TogglePromotion(array(
    'promotion_id' => 'PROMOTION_ID'
));
PUT /merchant/v2/merchants/{merchant_id}/promotions/{promotion_id}/toggle HTTP/1.1
User-Agent: xsolla-api-client/1.0
Host: api.xsolla.com
Accept: application/json
Authorization: Basic ZGVtb0B4c29sbGEuY29tOmRlbW8=
Content-Type: application/json
$ curl -v 'https://api.xsolla.com/merchant/v2/merchants/{merchant_id}/promotions/{promotion_id}/toggle' \
-X PUT \
-u merchant_id:merchant_api_key \

响应

<?php

$response = null;
HTTP/1.1 204 No Content

删除促销活动

删除促销活动。仅允许删除禁用的促销活动 (enabled = false)。

HTTP 请求

DELETE https://api.xsolla.com/merchant/v2/merchants/{merchant_id}/promotions/{promotion_id}

参数 类型 描述
merchant_id
int 商户 ID。
promotion_id
int 促销活动 ID。

请求

<?php

$response = $xsollaClient->DeletePromotion(array(
    'promotion_id' => 'PROMOTION_ID'
));
DELETE /merchant/v2/merchants/{merchant_id}/promotions/{promotion_id} HTTP/1.1
User-Agent: xsolla-api-client/1.0
Host: api.xsolla.com
Accept: application/json
Authorization: Basic ZGVtb0B4c29sbGEuY29tOmRlbW8=
Content-Type: application/json
$ curl -v 'https://api.xsolla.com/merchant/v2/merchants/{merchant_id}/promotions/{promotion_id}' \
-X DELETE \
-u merchant_id:merchant_api_key

响应

<?php

$response = null;
HTTP/1.1 204 No Content

列示所有促销活动

列示所有促销活动。

HTTP 请求

GET https://api.xsolla.com/merchant/v2/merchants/{merchant_id}/promotions

参数 类型 描述
merchant_id
int 商户 ID。

请求

<?php

$response = $xsollaClient->ListPromotions(array(
));
GET /merchant/v2/merchants/{merchant_id}/promotions HTTP/1.1
User-Agent: xsolla-api-client/1.0
Host: api.xsolla.com
Accept: application/json
Authorization: Basic ZGVtb0B4c29sbGEuY29tOmRlbW8=
Content-Type: application/json
$ curl -v 'https://api.xsolla.com/merchant/v2/merchants/{merchant_id}/promotions' \
-X GET \
-u merchant_id:merchant_api_key

响应

<?php

// example response
$response = array (
    array (
        'id' => 1,
        'project' =>
            array (
                'id' => 1,
                'localized_name' => 'Demo Project'
            ),
        'technical_name' => '25% bonus',
        'read_only' => true,
        'enabled' => true,
        'is_active' => false,
        'datetime' =>
            array (
                'from' => '2014-10-15T00:00:00+04:00',
                'to' => '2014-10-16T23:59:59+04:00'
            )
    )
);
HTTP/1.1 200 OK
Content-Type: application/json

[
    {
        "id": 1,
        "project": {
            "id": 1,
            "localized_name": "Demo Project"
        },
        "technical_name": "25% bonus",
        "read_only": true,
        "enabled": true,
        "is_active": false,
        "datetime": {
            "from": "2014-10-15T00:00:00+04:00",
            "to": "2014-10-16T23:59:59+04:00"
        }
    }
]
[
    {
        "id": 1,
        "project": {
            "id": 1,
            "localized_name": "Demo Project"
        },
        "technical_name": "25% bonus",
        "read_only": true,
        "enabled": true,
        "is_active": false,
        "datetime": {
            "from": "2014-10-15T00:00:00+04:00",
            "to": "2014-10-16T23:59:59+04:00"
        }
    }
]

获取主题

获取促销活动主题。

HTTP 请求

GET https://api.xsolla.com/merchant/v2/merchants/{merchant_id}/promotions/{promotion_id}/subject

参数 类型 描述
merchant_id
int 商户 ID。
promotion_id
int 促销活动 ID。

请求

<?php

$response = $xsollaClient->GetPromotionSubject(array(
    'promotion_id' => 'PROMOTION_ID'
));
GET /merchant/v2/merchants/{merchant_id}/promotions/{promotion_id}/subject HTTP/1.1
User-Agent: xsolla-api-client/1.0
Host: api.xsolla.com
Accept: application/json
Authorization: Basic ZGVtb0B4c29sbGEuY29tOmRlbW8=
Content-Type: application/json
$ curl -v 'https://api.xsolla.com/merchant/v2/merchants/{merchant_id}/promotions/{promotion_id}/subject' \
-X GET \
-u merchant_id:merchant_api_key

响应

<?php

// example response
$response = array (
    'id' => 1,
    'purchase' => false,
    'items' =>
        array (
            't-43-3-unique-id'
        ),
    'packages' => NULL,
    'subscriptions' =>
        array (
            'plans' =>
            array (
                array (
                        'id' => 123456,
                        'localized_name' => 'Subscription plan',
                        'external_id' => '894db422'
                      )
            ),
            'products' =>
            array (
                654321
            ),
            'max_charges_count' => null,
        ),
    'digital_contents' => null
);
HTTP/1.1 200 OK
Content-Type: application/json

{
    "id": 1,
    "purchase": false,
    "items": null,
    "packages": null,
    "subscriptions": {
        "plans": [
            {
                "id":123456,
                "localized_name":"Subscription plan",
                "external_id":"894db422"
            }
        ],
        "products": [
            654321
        ],
        "max_charges_count": null
    },
    "digital_contents": null
}
{
    "id": 1,
    "purchase": false,
    "items": null,
    "packages": null,
    "subscriptions": {
        "plans": [
            {
                "id":123456,
                "localized_name":"Subscription plan",
                "external_id":"894db422"
            }
        ],
        "products": [
            654321
        ],
        "max_charges_count": null
    },
    "digital_contents": null
}

设定主题

设定促销活动主题。如果促销活动为只读 (read_only = true),则不允许更新主题。主题可以采用以下值:“purchase”、“items”或“packages”。

HTTP 请求

PUT https://api.xsolla.com/merchant/v2/merchants/{merchant_id}/promotions/{promotion_id}/subject

Parameter Type 描述
merchant_id
int 商户 ID。
promotion_id
int 促销活动 ID。
purchase
boolean 促销活动是否应当适用于整个购买。
items
虚拟物品 SKU 的数组 (object) 或为null 促销将应用到列出的虚拟物品。
items.sku
string 物品 SKU。
packages
虚拟货币金额 (float) 的数组或为null 促销活动适用于列出的虚拟货币包。
subscriptions
object or null 将要进行促销的订阅计划或产品相关数据的对象。
subscriptions.plans
array 将要进行促销的订阅计划的数组。
subscriptions.products
array 将要进行促销的订阅产品的数组。
subscriptions.max_charges_count
int 将要进行促销的最多收费次数。

请求

<?php

$response = $xsollaClient->SetPromotionSubject(array(
    'request' => array (
        'purchase' => false,
        'items' => array (
            array (
                'sku' => 't-43-3-unique-id'
            )
        ),
        'packages' => null,
        'subscriptions' =>
            array (
                'plans' =>
                array (
                    array (
                            'id' => 123456
                          )
                ),
                'products' =>
                array (
                    654321
                ),
                'max_charges_count' => null,
            ),
        'digital_contents' =>
            array (
                array (
                    'id' => 1,
                    'localized_name' => 'test',
                    'drm' =>
                        array (
                            array (
                                'id' => 1,
                                'name' => 'Steam',
                            ),
                            array (
                                'id' => 2,
                                'name' => 'Playstation',
                            )
                        )
                )
            )
    )
));
PUT /merchant/v2/merchants/{merchant_id}/promotions/{promotion_id}/subject HTTP/1.1
User-Agent: xsolla-api-client/1.0
Host: api.xsolla.com
Accept: application/json
Authorization: Basic ZGVtb0B4c29sbGEuY29tOmRlbW8=
Content-Type: application/json

{
    "purchase": false,
    "items": [
        {
            "sku":"t-43-3-unique-id"
        }
    ],
    "packages": null,
    "subscriptions": {
        "plans": [
            {
                "id":123456
            }
        ],
        "products": [
            654321
        ],
        "max_charges_count": null
    },
    "digital_contents":[
        {
            "id":1,
            "localized_name":"test",
            "drm":[
                {
                    "id":1,
                    "name":"Steam"
                },
                {
                    "id":2,
                    "name":"Playstation"
                }
            ]
        }
    ]
}
$ curl -v 'https://api.xsolla.com/merchant/v2/merchants/{merchant_id}/promotions/{promotion_id}/subject' \
-X PUT \
-u merchant_id:merchant_api_key \
-H 'Content-Type: application/json' \
-H 'Accept: application/json' \
-d '{
        "purchase": false,
        "items": [
            {
                "sku":"t-43-3-unique-id"
            }
        ],
        "packages": null,
        "subscriptions": {
            "plans": [
            {
                "id":123456
            }
            ],
            "products": [
                654321
            ],
            "max_charges_count": null
        },
        "digital_contents":[
            {
                "id":1,
                "localized_name":"test",
                "drm":[
                    {
                        "id":1,
                        "name":"Steam"
                    },
                    {
                        "id":2,
                        "name":"Playstation"
                    }
                ]
            }
        ]
    }'

响应

<?php

$response = null;
HTTP/1.1 204 No Content

获取支付系统

获取促销活动的支付系统。如果支付系统列表为空,促销活动将对所有支付系统有效。

HTTP 请求

GET https://api.xsolla.com/merchant/v2/merchants/{merchant_id}/promotions/{promotion_id}/payment_systems

参数 类型 描述
merchant_id
int 商户 ID。