入门

概览

艾克索拉API包括:

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

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

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

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

请求和响应

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

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

Copy
Full screen
Small screen

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

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

API变更

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

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

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

版本控制

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

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

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

身份验证

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

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

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

Notice:
  • 请妥善保管您的API密钥。它是您的个人帐户和发布商帐户项目的访问凭证。
  • 更改API密钥可能导致您的所有项目无法付款。更新为新密钥之前,使用当前密钥的API调用将无法运行。
Copy
Full screen
Small screen
http
  • http
  • curl
  • php
  • C#
  • python
  • ruby
  • java
  • js
示例
GET https://api.xsolla.com/merchant/v2/merchants/{merchant_id}/events/messages
Headers:
  Authorization: Basic <your_authorization_basic_key>
curl --request GET \
--url 'https://api.xsolla.com/merchant/v2/merchants/{merchant_id}/events/messages' \
--header 'authorization: Basic <your_authorization_basic_key>'
<?php

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

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

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

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

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

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

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

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

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

print(data.decode("utf-8"))
require 'uri'
require 'net/http'

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

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

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

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

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

Response response = client.newCall(request).execute();
var data = null;

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

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

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

xhr.send(data);

端点类型

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

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

日期格式

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

分页

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

错误处理

受支持的HTTP错误列表:

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

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

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

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

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

{
    "http_status_code": 500,
    "message": "Internal Server Error",
    "extended_message": null,
    "request_id": "6445b85"
}

令牌

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

获取令牌

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

Notice: 此API方法在高负载状态下不可用。请求数量过多的情况下可能会限流。如需了解此API方法的流量控制详情,请联系您的帐户经理。

HTTP请求

Copy
Full screen
Small screen

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

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

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

Copy
Full screen
Small screen

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

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

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

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

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

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

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

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

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

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

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

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

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

conn.request("POST", "/merchant/v2/merchants/{merchant_id}/token", payload, headers)

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

print(data.decode("utf-8"))
require 'uri'
require 'net/http'

url = URI("https://api.xsolla.com/merchant/v2/merchants/{merchant_id}/token")

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

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

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

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

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

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

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

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

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

其他参数列表

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

请参阅高级诀窍

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

Webhooks

概览

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

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

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

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

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

您这一端操作的示例:

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

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

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

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

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

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

请求签名

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

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

Copy
Full screen
Small screen
http
  • http
  • curl
请求
POST /your_uri HTTP/1.1
Host: your.host
Accept: application/json
Content-Type: application/json
Content-Length: 165
Authorization: Signature 52eac2713985e212351610d008e7e14fae46f902

{"notification_type":"user_validation","user":{"ip":"127.0.0.1","phone":"18777976552","email":"email@example.com","id":1234567,"name":"Xsolla User","country":"US"}}
$curl -v 'https://your.hostname/your/uri' \
-X POST \
-H 'Authorization: Signature 52eac2713985e212351610d008e7e14fae46f902' \
-d '{
  "notification_type":
    "user_validation",
    "user":
      {
        "ip": "127.0.0.1",
        "phone": "18777976552",
        "email": "email@example.com",
        "id": 1234567,
        "name": "Xsolla User",
        "country": "US"
      }
    }'

响应

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

Webhook列表

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

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

用户验证

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

参数类型描述
notification_type
string通知类型。 必需
settings
object带有自定义项目设置的对象。
settings.project_id
integer游戏的艾克索拉ID。可以在发布商帐户中找到该ID。
settings.merchant_id
integer商户ID。
user
object带用户相关数据的对象。
user.ip
string用户IP地址。
user.phone
string用户电话号码(采用国际格式)。
user.email
string用户电子邮件。
user.id
string用户ID。 必需
user.name
string用户名。
user.country
string用户所在国家/地区。使用ISO 3166-1 alpha-2 标准规定的2字母组合表示国家/地区。
Copy
Full screen
Small screen
php
  • php
  • http
  • curl
请求
<?php

$request = array(
    'notification_type' => 'user_validation',
    'settings' => array(
       'project_id' => 18404,
       'merchant_id' => 2340
    ),
    'user' => array(
        'ip' => '127.0.0.1',
        'phone' => '18777976552',
        'email'=> 'email@example.com',
        'id'=> '1234567',
        'country' => 'US'
    )
);
POST /your/uri HTTP/1.1
Host: your.hostname
Accept: application/json
Content-Type: application/json
Content-Length: 240
Authorization: Signature 13342703ccaca5064ad33ba451d800c5e823db8f

{
    "notification_type": "user_validation",
    "settings": {
       "project_id": 18404,
       "merchant_id": 2340
    },
    "user": {
        "ip": "127.0.0.1",
        "phone": "18777976552",
        "email": "email@example.com",
        "id": "1234567",
        "name": "Xsolla User",
        "country": "US"
    }
}
$ curl -v 'https://your.hostname/your/uri' \
-X POST \
-H 'Accept: application/json' \
-H 'Content-Type: application/json' \
-H 'Authorization: Signature 13342703ccaca5064ad33ba451d800c5e823db8f' \
-d '{
    "notification_type":"user_validation",
    "settings": {
       "project_id": 18404,
       "merchant_id": 2340
    },    
    "user": {
        "ip": "127.0.0.1",
        "phone": "18777976552",
        "email": "email@example.com",
        "id": "1234567",
        "name": "Xsolla User",
        "country": "US"
    }
}'
响应
<?php

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

$callback = function (Message $message) {
    if ($message->isUserValidation()) {
       $userArray = $message->getUser();
       $userId = $message->getUserId();
       $messageArray = $message->toArray();
       //TODO if user not found, you should throw InvalidUserException
    }
};

$webhookServer = WebhookServer::create($callback, PROJECT_KEY);
$webhookServer->start();
HTTP/1.1 204 No Content
发送以通过公共用户ID检索用户的详细信息,该参数是用户的唯一标识,且会提供给用户(电子邮件、昵称等)。它允许用户在游戏商店之外的地方进行购买(例如通过自助终端机)。

参数类型描述
notification_type
string通知类型。 必需
settings
object带有自定义项目设置的对象。
settings.project_id
integer游戏的艾克索拉ID。可以在发布商帐户中找到该ID。
settings.merchant_id
integer商户ID。
user
object带用户相关数据的对象。 必需
user.public_id
string公共用户ID。
user.id
string用户ID。
Copy
Full screen
Small screen
php
  • php
  • http
  • curl
请求
<?php

$request = array(
    'notification_type' => 'user_search',
    'settings' => array(
       'project_id' => 18404,
       'merchant_id' => 2340
    ),
    'user' => array(
        'public_id' => 'public_email@example.com'
    )
);
POST /your/uri HTTP/1.1
Host: your.hostname
Accept: application/json
Content-Type: application/json
Content-Length: 240
Authorization: Signature 13342703ccaca5064ad33ba451d800c5e823db8f

{
    "notification_type": "user_search",
    "settings": {
       "project_id": 18404,
       "merchant_id": 2340
    },
    "user": {
        "public_id": "public_email@example.com"
    }
}
$ curl -v 'https://your.hostname/your/uri' \
-X POST \
-H 'Accept: application/json' \
-H 'Content-Type: application/json' \
-H 'Authorization: Signature 13342703ccaca5064ad33ba451d800c5e823db8f' \
-d '{
    "notification_type": "user_search",
    "settings": {
       "project_id": 18404,
       "merchant_id": 2340
    },
    "user": {
        "public_id": "public_email@example.com"
    }
}'
响应
<?php

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

$callback = function (Message $message) {
    if ($message instanceof \Xsolla\SDK\Webhook\Message\UserSearchMessage) {
        $userArray = $message->getUser();
        $userPublicId = $message->getUserPublicId();
        // TODO get a user from your database and fill the user data to model.
        $user = new \Xsolla\SDK\Webhook\User();
        $user->setId('user_id')
            ->setPublicId($userPublicId)
            ->setEmail('user_email') //Optional field
            ->setPhone('user_phone') //Optional field
            ->setName('user_name'); //Optional field
        //TODO if user not found, you should throw InvalidUserException
        return new \Xsolla\SDK\Webhook\Response\UserResponse($user);
    }
};
$webhookServer = WebhookServer::create($callback, PROJECT_KEY);
$webhookServer->start();
HTTP/1.1 200 OK
Content-Type: application/json

{
    "user": {
        "public_id": "public_email@example.com",
        "phone": "18777976552",
        "email": "email@example.com",
        "id": "1234567",
        "name": "Xsolla User"
    }
}
{
    "user": {
        "public_id": "public_email@example.com",
        "phone": "18777976552",
        "email": "email@example.com",
        "id": "1234567",
        "name": "Xsolla User"
    }
}

支付

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

参数类型描述
notification_type
string通知类型。 必需
settings
object带有自定义项目设置的对象。
settings.project_id
integer游戏的艾克索拉ID。可以在发布商帐户中找到该ID。
settings.merchant_id
integer商户 ID。
purchase
object带有购买相关数据的对象。
purchase.virtual_currency
object带有购买虚拟货币相关数据的对象。
purchase.virtual_currency.name
string虚拟货币名称。
purchase.virtual_currency.sku
string虚拟货币包 SKU(如果针对虚拟货币包设置)。
purchase.virtual_currency.quantity
float数量。
purchase.virtual_currency.currency
string购买币种。参照ISO 4217标准的三字母货币代码。
purchase.virtual_currency.amount
float以实际货币表示的价格。
purchase.checkout
object带有结账参数相关数据的对象。
purchase.checkout.currency
string购买币种。参照ISO 4217标准的三字母货币代码。
purchase.checkout.amount
float购买金额。
purchase.subscription
object订阅详情(对象)。
purchase.subscription.plan_id
string计划 ID(如果计划通过 API 创建,则为外部 ID)。
purchase.subscription.subscription_id
integer艾克索拉数据库的订阅ID。
purchase.subscription.product_id
string产品 ID(如果在访问令牌中发送)。
purchase.subscription.tags
array计划标签。
purchase.subscription.date_create
string订阅的创建日期。符合 ISO 8601 标准规定的日期与时间。
purchase.subscription.date_next_charge
string下次收费的日期。符合ISO 8601标准规定的日期与时间。
purchase.subscription.currency
string订阅使用的币种。参照ISO 4217标准的三字母货币代码。
purchase.subscription.amount
float以实际货币表示的价格。
purchase.virtual_items
object带有购买的虚拟物品相关数据的对象。
purchase.virtual_items.items
array带有购买的物品相关数据的数组。
purchase.virtual_items.items.sku
string物品 ID。
purchase.virtual_items.items.amount
integer物品数量。
purchase.virtual_items.currency
string购买币种。参照ISO 4217标准的三字母货币代码。
purchase.virtual_items.amount
float购买金额。
purchase.pin_codes
object游戏密钥(数组)。
purchase.pin_codes.digital_content
string在发布商帐户中设置的游戏SKU。
purchase.pin_codes.drm
string用于分发游戏的DRM平台。可以是'steam'、'playstation'、'xbox'、'uplay'、'origin'、'drmfree'、'gog'、'epicgames'、'nintendo_eshop'、'discord_game_store'或'oculus'。请确保您已在发布商帐户中配置了所需的DRM平台。
purchase.pin_codes.currency
string购买游戏密钥的币种。参照ISO 4217标准的三字母货币代码。
purchase.pin_codes.amount
floatPIN 码的价格。
purchase.pin_codes.upgrade
object包含升级数据的对象。
purchase.pin_codes.upgrade.digital_content_from
object包含套餐数据的对象,用户从该套餐升级。
purchase.pin_codes.upgrade.digital_content_from.digital_content
string在发布商帐户中设置的游戏SKU。
purchase.pin_codes.upgrade.digital_content_from.DRM
string游戏DRM平台。
purchase.pin_codes.upgrade.digital_content_to
object包含套餐数据的对象,用户升级到该套餐。
purchase.pin_codes.upgrade.digital_content_to.digital_content
string在发布商帐户中设置的游戏SKU。
purchase.pin_codes.upgrade.digital_content_to.DRM
string游戏DRM平台。
purchase.pin_codes.upgrade.currency
string购买货币。为参照ISO 4217标准的三字母货币代码。
purchase.pin_codes.upgrade.amount
float以实际货币表示的价格。
purchase.gift
object礼物详情(对象)。
purchase.gift.giver_id
string送礼人ID。
purchase.gift.receiver_id
string收礼人ID。
purchase.gift.receiver_email
string收礼人邮箱。
purchase.gift.message
string送礼人留言。
purchase.gift.hide_giver_from_receiver
string是否对收礼人隐藏送礼人的身份信息。
purchase.total
object带有总购买价格相关数据的对象。 必需
purchase.total.currency
string购买币种。参照ISO 4217标准的三字母货币代码。
purchase.total.amount
float总购买金额。
purchase.promotions
array带有此交易所应用促销活动相关数据的数组。
purchase.promotions.technical_name
string促销活动的技术名称。
purchase.promotions.id
integer促销活动 ID。
purchase.coupon
object带有优惠券相关数据的对象(如果此交易使用了优惠券)。
purchase.coupon.coupon_code
string优惠券代码。
purchase.coupon.campaign_code
string优惠券营销活动的代码。
user
object带用户相关数据的对象。
user.ip
string用户 IP 地址。
user.phone
string用户电话号码(采用国际格式)。
user.email
string用户电子邮件。
user.id
string用户ID。 必需
user.name
string用户名。
user.country
string用户所在国家/地区。使用 ISO 3166-1 alpha-2 标准规定的 2 字母组合表示国家/地区。
user.zip
string邮编。
transaction
object交易 ID。 必需
transaction.id
integer交易ID。
transaction.external_id
string交易外部ID。
transaction.payment_date
string付款日期。
transaction.payment_method
integer付款方式标识符。
transaction.payment_method_order_id
string支付系统中的付款ID。
transaction.dry_run
integer测试交易。如为测试交易,该参数的值为1;如为真实交易,则不会发送该参数。
transaction.agreement
integer协议 ID。
payment_details
object带有支付详细信息的对象。 必需
payment_details.payment
object带有用户支付相关数据的对象。
payment_details.payment.currency
string货币。参照ISO 4217标准的三字母货币代码。
payment_details.payment.amount
string金额。
payment_details.payment_method_sum
object带有通过支付方式收费的金额相关数据的对象。
payment_details.payment_method_sum.currency
string货币。参照ISO 4217标准的三字母货币代码。
payment_details.payment_method_sum.amount
string金额。
payment_details.xsolla_balance_sum
object计入艾克索拉余额的金额。
payment_details.xsolla_balance_sum.currency
string货币。参照ISO 4217标准的三字母货币代码。
payment_details.xsolla_balance_sum.amount
string金额。
payment_details.payout
object带有支出详细信息的对象。
payment_details.payout.currency
string货币。参照ISO 4217标准的三字母货币代码。
payment_details.payout.amount
float金额。
payment_details.vat
object增值税大小(仅适用于欧盟)。
payment_details.vat.currency
string货币。参照ISO 4217标准的三字母货币代码。
payment_details.vat.amount
float金额。
payment_details.payout_currency_rate
float从支付币种到支出币种的汇率。
payment_details.xsolla_fee
object艾克索拉费用(对象)。
payment_details.xsolla_fee.currency
string货币。参照ISO 4217标准的三字母货币代码。
payment_details.xsolla_fee.amount
float金额。
payment_details.payment_method_fee
object支付系统佣金的大小。
payment_details.payment_method_fee.currency
string货币。参照ISO 4217标准的三字母货币代码。
payment_details.payment_method_fee.amount
float金额。
payment_details.sales_tax
object销售税(对象;仅适用于美国和加拿大)。
payment_details.sales_tax.currency
string货币。参照ISO 4217标准的三字母货币代码。
payment_details.sales_tax.amount
float金额。
payment_details.direct_wht
object直接预扣税。
payment_details.direct_wht.currency
string货币。参照ISO 4217标准的三字母货币代码。
payment_details.direct_wht.amount
float金额。
payment_details.repatriation_commission
object包含汇回本国费用数据的对象,该费用是第三方对艾克索拉收取的费用。
payment_details.repatriation_commission.currency
string汇回本国费用币种。参照ISO 4217标准的三字母货币代码。
payment_details.repatriation_commission.amount
float汇回本国费用金额。
custom_parameters
object您的自定义参数。
Copy
Full screen
Small screen
php
  • php
  • http
  • curl
请求
<?php

$request = array(
    'notification_type' => 'payment',
    'settings' => array(
       'project_id' => 18404,
       'merchant_id' => 2340
    ),
    'purchase' => array(
        'virtual_currency' => array(
            'name' => 'Coins',
            'quantity' => 100,
            'currency' => 'USD',
            'amount' => 9.99
        ),
        'total' => array(
            'currency' => 'USD',
            'amount' => 9.99
        )
    ),
    'user' => array(
        'ip' => '127.0.0.1',
        'phone' => '18777976552',
        'email' => 'email@example.com',
        'id' => '1234567',
        'country' => 'US'
    ),
    'transaction' => array(
        'id' => 87654321,
        'payment_date' => '2014-09-23T19:25:25+04:00',
        'payment_method' => 1380,
        'payment_method_order_id' => 1234567890123456789,
        'dry_run' => 1
    ),
    'payment_details' => array(
        'payment' => array(
            'currency' => 'USD',
            'amount' => 9.99
        ),
        'vat' => array(
            'currency' => 'USD',
            'amount' => 0
        ),
        'sales_tax' => array(
            'currency' => 'EUR',
            'amount' => 0
        ),
        'direct_wht' => array(
            'currency' => 'EUR',
            'amount' => 70
        ),
        'payout_currency_rate' => 1,
        'payout' => array(
            'currency' => 'USD',
            'amount' => 9.49
        ),
        'xsolla_fee' => array(
            'currency' => 'USD',
            'amount' => 0.19
        ),
        'payment_method_fee' => array(
            'currency' => 'USD',
            'amount' => 0.31
        ),
        'repatriation_commission' => array(
            'currency' => 'USD',
            'amount' => 0.2
        )
    )
);
POST /your_uri HTTP/1.1
Host: your.host
Accept: application/json
Content-Type: application/json
Content-Length: 1721
Authorization: Signature 34553d151e656110c656696c919f9a10e05de542

{
    "notification_type": "payment",
    "settings": {
       "project_id": 18404,
       "merchant_id": 2340
    },
    "purchase":{
        "virtual_currency": {
            "name": "Coins",
            "sku": "test_package1",
            "quantity": 10,
            "currency": "USD",
            "amount": 100
        },
        "subscription": {
            "plan_id": "b5dac9c8",
            "subscription_id": "10",
            "product_id": "Demo Product",
            "date_create": "2014-09-22T19:25:25+04:00",
            "date_next_charge": "2014-10-22T19:25:25+04:00",
            "currency": "USD",
            "amount": 9.99
        },
        "checkout": {
            "currency": "USD",
            "amount": 50
        },
        "virtual_items": {
            "items": [
                {
                    "sku": "test_item1",
                    "amount": 1
                }
            ],
            "currency": "USD",
            "amount": 50
        },
        "total": {
            "currency": "USD",
            "amount": 200
        },
        "promotions": [{
            "technical_name": "Demo Promotion",
            "id": "853"
        }],
        "coupon": {
            "coupon_code": "ICvj45S4FUOyy",
            "campaign_code": "1507"
        }
    },
    "user": {
        "ip": "127.0.0.1",
        "phone": "18777976552",
        "email": "email@example.com",
        "id": "1234567",
        "name": "Xsolla User",
        "country": "US"
    },
    "transaction": {
        "id": 1,
        "external_id": 1,
        "payment_date": "2014-09-24T20:38:16+04:00",
        "payment_method": 1,
        "payment_method_order_id": 1234567890123456789,
        "dry_run": 1,
        "agreement": 1
    },
    "payment_details": {
        "payment": {
            "currency": "USD",
            "amount": 230
        },
        "vat": {
            "currency": "USD",
            "amount": 0
        },
        "sales_tax": {
            "currency": "EUR",
            "amount": 0
        },
        "direct_wht": {
            "currency": "EUR",
            "amount": 0.70
        },
        "payout_currency_rate": 1,
        "payout": {
            "currency": "USD",
            "amount": 200
        },
        "xsolla_fee": {
            "currency": "USD",
            "amount": 10
        },
        "payment_method_fee": {
            "currency": "USD",
            "amount": 20
        },
        "repatriation_commission": {
            "currency": "USD",
            "amount": "10"
        }
    },
    "custom_parameters": {
        "parameter1": "value1",
        "parameter2": "value2"
    }
}
$curl -v 'https://your.hostname/your/uri' \
-X POST \
-d '{
    "notification_type": "payment",
    "settings": {
       "project_id": 18404,
       "merchant_id": 2340
    },
    "purchase": {
        "virtual_currency": {
            "name": "Coins",
            "sku": "test_package1",
            "quantity": 10,
            "currency": "USD",
            "amount": 100
        },
        "subscription": {
            "plan_id": "b5dac9c8",
            "subscription_id": "10",
            "product_id": "Demo Product",
            "date_create": "2014-09-22T19:25:25+04:00",
            "date_next_charge": "2014-10-22T19:25:25+04:00",
            "currency": "USD",
            "amount": 9.99
        },
        "checkout": {
            "currency": "USD",
            "amount": 50
        },
        "virtual_items": {
            "items": [
                {
                    "sku": "test_item1",
                    "amount": 1
                }
            ],
            "currency": "USD",
            "amount": 50
        },
        "total": {
            "currency": "USD",
            "amount": 200
        },
        "promotions": [{
            "technical_name": "Demo Promotion",
            "id": "853"
        }],
        "coupon": {
             "coupon_code": "ICvj45S4FUOyy",
             "campaign_code": "1507"
        }
    },
    "user": {
        "ip": "127.0.0.1",
        "phone": "18777976552",
        "email": "email@example.com",
        "id": "1234567",
        "name": "Xsolla User",
        "country": "US"
    },
    "transaction": {
        "id": 1,
        "external_id": 1,
        "payment_date": "2014-09-24T20:38:16+04:00",
        "payment_method": 1,
        "payment_method_order_id": 1234567890123456789,
        "dry_run": 1,
        "agreement": 1
    },
    "payment_details": {
        "payment": {
            "currency": "USD",
            "amount": 230
        },
        "vat": {
            "currency": "USD",
            "amount": 0
        },
        "sales_tax": {
            "currency": "EUR",
            "amount": 0
        },
        "direct_wht": {
            "currency": "EUR",
            "amount": 0.70
        },
        "payout_currency_rate": 1,
        "payout": {
            "currency": "USD",
            "amount": 200
        },
        "xsolla_fee": {
            "currency": "USD",
            "amount": 10
        },
        "payment_method_fee": {
            "currency": "USD",
            "amount": 20
        },
        "repatriation_commission": {
            "currency": "USD",
            "amount": "10"
        }
    },
    "custom_parameters": {
        "parameter1": "value1",
        "parameter2": "value2"
    }
}'
响应
<?php

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

$callback = function (Message $message) {
    if ($message->isPayment()) {
        $userArray = $message->getUser();
        $paymentArray = $message->getTransaction();
        $paymentId = $message->getPaymentId();
        $externalPaymentId = $message->getExternalPaymentId();
        $paymentDetailsArray = $message->getPaymentDetails();
        $customParametersArray = $message->getCustomParameters();
        $isDryRun = $message->isDryRun();
        $messageArray = $message->toArray();
        // TODO if the payment delivery fails for some reason, you should throw XsollaWebhookException
    }
};

$webhookServer = WebhookServer::create($callback, PROJECT_KEY);
$webhookServer->start();
HTTP/1.1 204 No Content

退款

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

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

退款代码:

代码退款理由描述
1.Cancellation by the user request / the game request.用于在发布商帐户中发起取消的情况。
2.退单。用于交易存在退单的情况。
3.Integration Error.用于艾克索拉与游戏之间存在集成问题的情况。 这种情况下,我们不建议将用户列入黑名单。
4.Fraud.用于存在潜在欺诈风险的情况。
5.Test Payment.用于测试交易然后取消的情况。 这种情况下,我们不建议将用户列入黑名单。
6.Expired Invoice.用于通过用后付费模式的支付系统进行交易的情况。
7.PS debt cancel.用于支付系统进行交易后拒绝支出的情况。 这种情况下,我们不建议将用户列入黑名单。
8.Cancellation by the PS request.用于支付系统请求取消的情况。 这种情况下,我们不建议将用户列入黑名单。
9.Cancellation by the user request.用于用户请求取消的情况。可能出于某些原因导致用户对游戏或购买产生不满的情况下发生。 这种情况下,我们不建议将用户列入黑名单。
10.Cancellation by the game request.用于游戏请求取消的情况。 这种情况下,我们不建议将用户列入黑名单。
11.Account holder called to report fraud.用于账户持有人通知我们其未进行此交易的情况。
12.Friendly fraud.用于接收到友好型欺诈相关消息的情况。
Copy
Full screen
Small screen
php
  • php
  • http
  • curl
请求
<?php

$request = array(
    'notification_type' => 'refund',
    'settings' => array(
       'project_id' => 18404,
       'merchant_id' => 2340
    ),    
    'purchase' => array(
        'virtual_currency' => array(
            'name' => 'Coins',
            'quantity' => 100,
            'currency' => 'USD',
            'amount' => 9.99
        ),
        'total' => array(
            'currency' => 'USD',
            'amount' => 9.99
        )
    ),
    'user' => array(
        'ip' => '127.0.0.1',
        'phone' => '18777976552',
        'email' => 'email@example.com',
        'id' => '1234567',
        'country' => 'US'
    ),
    'transaction' => array(
        'id' => 87654321,
        'payment_date' => '2014-09-23T19:25:25+04:00',
        'payment_method' => 1380,
        'dry_run' => 1
    ),
    'refund_details' => array(
            'code' => 1,
            'reason' => 'Fraud'
    ),
    'payment_details' => array(
        'payment' => array(
            'currency' => 'USD',
            'amount' => 9.99
        ),
        'vat' => array(
            'currency' => 'USD',
            'amount' => 0
        ),
        'sales_tax' => array(
            'currency' => 'EUR',
            'amount' => 0
        ),
        'direct_wht' => array(
            'currency' => 'EUR',
            'amount' => 70
        ),
        'payout_currency_rate' => 1,
        'payout' => array(
            'currency' => 'USD',
            'amount' => 9.49
        ),
        'xsolla_fee' => array(
            'currency' => 'USD',
            'amount' => 0.19
        ),
        'payment_method_fee' => array(
            'currency' => 'USD',
            'amount' => 0.31
        ),
        'repatriation_commission' => array(
            'currency' => 'USD',
            'amount' => 0.2
        )
    )
);
POST /your_uri HTTP/1.1
Host: your.host
Accept: application/json
Content-Type: application/json
Content-Length: 1220
Authorization: Signature 31bd5924dd6cbc9cbe99d331c4a086a57291f9d7

{
    "notification_type": "refund",
    "settings": {
       "project_id": 18404,
       "merchant_id": 2340
    },
    "purchase": {
        "virtual_currency": {
            "name": "Coins",
            "quantity": 10,
            "currency": "USD",
            "amount": 100
        },
        "subscription": {
            "plan_id": "b5dac9c8",
            "subscription_id": "10",
            "date_create": "2014-09-22T19:25:25+04:00",
            "currency": "USD",
            "amount": 9.99
        },
        "checkout": {
            "currency": "USD",
            "amount": 50
        },
        "virtual_items": {
            "items": [
                {
                    "sku": "test_item1",
                    "amount": 1
                }
            ],
            "currency": "USD",
            "amount": 50
        },
        "total": {
            "currency": "USD",
            "amount": 200
        }
    },
    "user": {
        "ip": "127.0.0.1",
        "phone": "18777976552",
        "email": "email@example.com",
        "id": "1234567",
        "name": "Xsolla User",
        "country": "US"
    },
    "transaction": {
        "id": 1,
        "external_id": 1,
        "dry_run": 1,
        "agreement": 1
    },
    "refund_details": {
        "code": 1,
        "reason": "Fraud"
    },
    "payment_details": {
        "sales_tax": {
            "currency": "EUR",
            "amount": 0
        },
        "direct_wht": {
            "currency": "EUR",
            "amount": 0.70
        },
        "xsolla_fee": {
            "currency": "USD",
            "amount": "10"
        },
        "payout": {
            "currency": "USD",
            "amount": "200"
        },
        "payment_method_fee": {
            "currency": "USD",
            "amount": "20"
        },
        "payment": {
            "currency": "USD",
            "amount": "230"
        },
        "repatriation_commission": {
            "currency": "USD",
            "amount": "10"
        }
    }
}
$ curl -v 'https://your.hostname/your/uri' \
-X POST \
-d '{
        "notification_type": "refund",
        "settings": {
           "project_id": 18404,
           "merchant_id": 2340
        },
        "purchase": {
            "virtual_currency": {
                "name": "Coins",
                "quantity": 10,
                "currency": "USD",
                "amount": 100
            },
            "subscription": {
                "plan_id": "b5dac9c8",
                "subscription_id": "10",
                "date_create": "2014-09-22T19:25:25+04:00",
                "currency": "USD",
                "amount": 9.99
            },
            "checkout": {
                "currency": "USD",
                "amount": 50
            },
            "virtual_items": {
                "items": [
                    {
                        "sku": "test_item1",
                        "amount": 1
                    }
                ],
                "currency": "USD",
                "amount": 50
            },
            "total":{
                "currency": "USD",
                "amount": 200
            }
        },
        "user": {
            "ip": "127.0.0.1",
            "phone": "18777976552",
            "email": "email@example.com",
            "id": "1234567",
            "name": "Xsolla User",
            "country": "US"
        },
        "transaction": {
            "id": 1,
            "external_id": 1,
            "dry_run": 1,
            "agreement": 1
        },
        "refund_details": {
            "code": 1,
            "reason": "Fraud"
        },
        "payment_details": {
            "sales_tax": {
                "currency": "EUR",
                "amount": 0
            },
            "direct_wht": {
                "currency": "EUR",
                "amount": 0.70
            },
            "xsolla_fee": {
                "currency": "USD",
                "amount": "10"
            },
            "payout": {
                "currency": "USD",
                "amount": "200"
            },
            "payment_method_fee": {
                "currency": "USD",
                "amount": "20"
            },
            "payment": {
                "currency": "USD",
                "amount": "230"
            },
            "repatriation_commission": {
                "currency": "USD",
                "amount": "10"
            }
        }
    }
}'
响应
<?php

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

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

$webhookServer = WebhookServer::create($callback, PROJECT_KEY);
$webhookServer->start();
HTTP/1.1 204 No Content

升级退款

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

参数类型描述
notification_type
string通知类型。 必需
settings
object带有自定义项目设置的对象。
settings.project_id
integer游戏的艾克索拉ID。可以在发布商帐户中找到该ID。
settings.merchant_id
integer商户ID。
purchase
object包含购买数据的对象。 必需
purchase.pin_codes
object包含所购游戏套餐数据的对象。
purchase.pin_codes.purchase_type
string购买类型。可以是“regular”(购买套餐)或“upgrade”(升级套餐)。
purchase.pin_codes.digital_content
string在发布商帐户中设置的游戏SKU。
purchase.pin_codes.DRM
string游戏DRM平台。
purchase.pin_codes.currency
string购买货币。为参照ISO 4217标准的三字母货币代码。
purchase.pin_codes.amount
float以实际货币表示的价格。
purchase.pin_codes.transaction
object包含交易数据的对象。
purchase.pin_codes.transaction.id
integer交易ID。
purchase.pin_codes.upgrade
object包含升级数据的对象。
purchase.pin_codes.upgrade.digital_content_from
object包含套餐数据的对象,用户从该套餐升级。
purchase.pin_codes.upgrade.digital_content_from.digital_content
string在发布商帐户中设置的游戏SKU。
purchase.pin_codes.upgrade.digital_content_from.DRM
string游戏DRM平台。
purchase.pin_codes.upgrade.digital_content_to
object包含套餐数据的对象,用户升级到该套餐。
purchase.pin_codes.upgrade.digital_content_to.digital_content
string在发布商帐户中设置的游戏SKU。
purchase.pin_codes.upgrade.digital_content_to.DRM
string游戏DRM平台。
ownership
object包含用户所拥有套餐数据的对象。 必需
ownership.digital_content
string在发布商帐户中设置的游戏SKU。
ownership.DRM
string游戏DRM平台。
Copy
Full screen
Small screen
php
  • php
  • http
  • curl
请求
<?php

$request = array (
  'notification_type' => 'upgrade_refund',
  'settings' => array(
     'project_id' => 18404,
     'merchant_id' => 2340
  ),
  'purchase' =>
  array (
    'pin_codes' =>
    array (
      0 =>
      array (
        'purchase_type' => 'regular',
        'digital_content' => 'silver',
        'DRM' => 'drmfree',
        'currency' => 'USD',
        'amount' => 40,
        'transaction' =>
        array (
          'id' => '361697569',
        ),
      ),
      1 =>
      array (
        'purchase_type' => 'upgrade',
        'upgrade' =>
        array (
          'digital_content_from' =>
          array (
            'digital_content' => 'silver',
            'DRM' => 'drmfree',
          ),
          'digital_content_to' =>
          array (
            'digital_content' => 'gold',
            'DRM' => 'drmfree',
          ),
        ),
        'currency' => 'USD',
        'amount' => 20,
        'transaction' =>
        array (
          'id' => '361697570'
        ),
      ),
      2 =>
      array (
        'purchase_type' => 'upgrade',
        'upgrade' =>
        array (
          'digital_content_from' =>
          array (
            'digital_content' => 'gold',
            'DRM' => 'drmfree',
          ),
          'digital_content_to' =>
          array (
            'digital_content' => 'platinum',
            'DRM' => 'drmfree',
          ),
        ),
        'currency' => 'USD',
        'amount' => 20,
        'transaction' =>
        array (
          'id' => '361697571'
        ),
      ),
    ),
  ),
  'ownership' =>
  array (
    'digital_content' => NULL,
    'DRM' => NULL,
  ),
)
POST /your_uri HTTP/1.1
Host: your.host
Accept: application/json
Content-Type: application/json
Authorization: Signature <signature>

{
  "notification_type": "upgrade_refund",
  "settings": {
     "project_id": 18404,
     "merchant_id": 2340
  },
  "purchase": {
    "pin_codes": [
      {
        "purchase_type": "regular",
        "digital_content": "silver",
        "DRM": "drmfree",
        "currency": "USD",
        "amount": "40",
        "transaction": {
          "id": "361697569"
        }
      },
      {
        "purchase_type": "upgrade",
        "upgrade": {
          "digital_content_from": {
            "digital_content": "silver",
            "DRM": "drmfree"
          },
          "digital_content_to": {
            "digital_content": "gold",
            "DRM": "drmfree"
          }
        },
        "currency": "USD",
        "amount": "20",
        "transaction": {
          "id": "361697570"
        }
      },
      {
        "purchase_type": "upgrade",
        "upgrade": {
          "digital_content_from": {
            "digital_content": "gold",
            "DRM": "drmfree"
          },
          "digital_content_to": {
            "digital_content": "platinum",
            "DRM": "drmfree"
          }
        },
        "currency": "USD",
        "amount": "20",
        "transaction": {
          "id": "361697571"
        }
      }
    ]
  },
  "ownership": {
    "digital_content": null,
    "DRM": null
  }
}
$ curl -v 'https://your.hostname/your/uri' \
-X POST \
-d '{
  "notification_type": "upgrade_refund",
  "settings": {
     "project_id": 18404,
     "merchant_id": 2340
  },
  "purchase": {
    "pin_codes": [
      {
        "purchase_type": "regular",
        "digital_content": "silver",
        "DRM": "drmfree",
        "currency": "USD",
        "amount": "40",
        "transaction": {
          "id": "361697569"
        }
      },
      {
        "purchase_type": "upgrade",
        "upgrade": {
          "digital_content_from": {
            "digital_content": "silver",
            "DRM": "drmfree"
          },
          "digital_content_to": {
            "digital_content": "gold",
            "DRM": "drmfree"
          }
        },
        "currency": "USD",
        "amount": "20",
        "transaction": {
          "id": "361697570"
        }
      },
      {
        "purchase_type": "upgrade",
        "upgrade": {
          "digital_content_from": {
            "digital_content": "gold",
            "DRM": "drmfree"
          },
          "digital_content_to": {
            "digital_content": "platinum",
            "DRM": "drmfree"
          }
        },
        "currency": "USD",
        "amount": "20",
        "transaction": {
          "id": "361697571"
        }
      }
    ]
  },
  "ownership": {
    "digital_content": null,
    "DRM": null
  }
}'
响应

AFS已拒绝交易

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

参数类型描述
notification_type
string通知类型。 必需
settings
object带有自定义项目设置的对象。
settings.project_id
integer游戏的艾克索拉ID。可以在发布商帐户中找到该ID。
settings.merchant_id
integer商户ID。
user
object带用户相关数据的对象。
user.ip
string用户IP地址。
user.phone
string用户电话号码(采用国际格式)。
user.email
string用户电子邮件。
user.id
string用户ID。 必需
user.name
string用户名。
user.country
string用户所在国家/地区。使用ISO 3166-1 alpha-2 标准规定的2字母组合表示国家/地区。
user.zip
string邮编。
transaction
object交易ID。 必需
transaction.id
integer交易ID。
transaction.external_id
string交易外部ID。
transaction.dry_run
integer测试交易。如为测试交易,该参数的值为1;如为真实交易,则不会发送该参数。
transaction.agreement
integer协议ID。
refund_details
object退款详情(对象)。
refund_details.code
integer代码ID。
refund_details.reason
string退款原因。
refund_details.author
string退款申請人。
Copy
Full screen
Small screen
php
  • php
  • http
  • curl
请求
<?php

$request = array(
  'notification_type' => 'afs_reject',
  'settings' => array(
    'project_id' => 18404,
    'merchant_id' => 2340
  ),
  'user' => array(
    'ip' => '127.0.0.1',
    'phone' => '18777976552',
    'email' => 'email@example.com',
    'id' => '1234567',
    'country' => 'US'
  ),
  'transaction' => array(
    'id' => 87654321,
    'payment_date' => '2014-09-23T19:25:25+04:00',
    'payment_method' => 1380,
    'dry_run' => 1
  ),
  'refund_details' => array(
    'code' => 4,
    'reason' => 'Potential fraud'
  )
);
POST /your_uri HTTP/1.1
Host: your.host
Accept: application/json
Content-Type: application/json
Content-Length: 1220
Authorization: Signature 31bd5924dd6cbc9cbe99d331c4a086a57291f9d7

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

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

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

$webhookServer = WebhookServer::create($callback, PROJECT_KEY);
$webhookServer->start();
HTTP/1.1 204 No Content

AFS更新的拦截列表

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

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

{
  "event": {
    "action": "adding",
    "date_of_last_action": "2020-11-27 10:09:05",
    "parameter": "email",
    "parameter_value": "some_cool_email@gmail.com",
    "reason": "ps_reported_fraud",
    "transaction_id": "111111111"
  },
  "notification_type": "afs_black_list"
}
$curl -v 'https://your.hostname/your/uri' \
-X POST \
-H 'Authorization: Signature 32c64a80d2527dc08906ae1891bac4489509b9f6' \
-d '{
  "event": {
    "action": "adding",
    "date_of_last_action": "2020-11-27 10:09:05",
    "parameter": "email",
    "parameter_value": "some_cool_email@gmail.com",
    "reason": "ps_reported_fraud",
    "transaction_id": "111111111"
  },
  "notification_type": "afs_black_list"
}'
响应
HTTP/1.1 204 No Content

已创建订阅

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

参数类型描述
notification_type
string通知类型。 必需
settings
object带有自定义项目设置的对象。
settings.project_id
integer游戏的艾克索拉ID。可以在发布商帐户中找到该ID。
settings.merchant_id
integer商户ID。
user
object带用户相关数据的对象。
user.id
string用户ID。 必需
user.name
string用户名。
subscription
object订阅详情(对象)。
subscription.plan_id
string计划ID(如果计划通过API创建,则为外部ID)。
subscription.tags
array计划标签。
subscription.subscription_id
integer艾克索拉数据库的订阅ID。
subscription.product_id
string产品ID(如果在访问令牌中发送)。
subscription.date_create
string订阅的创建日期。符合ISO 8601标准规定的日期与时间。
subscription.date_next_charge
string下次收费的日期。符合ISO 8601标准规定的日期与时间。
subscription.trial
object带有订阅试用期相关数据的对象。
subscription.trial.value
integer试用期时长。
subscription.trial.type
string试用期类型:day。
custom_parameters
object您的自定义参数。
Copy
Full screen
Small screen
php
  • php
  • http
  • curl
请求
<?php

$request = array(
    'notification_type' => 'create_subscription',
    'settings' => array(
       'project_id' => 18404,
       'merchant_id' => 2340
    ),
    'user' => array(
        'id' => '1234567',
        'name' => 'Xsolla User'
    ),
    'subscription' => array(
        'plan_id' => 'b5dac9c8',
        'subscription_id' => '10',
        'product_id' => 'Demo Product',
        'date_create' => '2014-09-22T19:25:25+04:00',
        'date_next_charge' => '2015-01-22T19:25:25+04:00',
        'trial' =>  array(
                'value' =>  90,
                'type' =>  'day'
            )
    )
);
POST /your/uri HTTP/1.1
Host: your.hostname
Accept: application/json
Content-Type: application/json
Content-Length: 240
Authorization: Signature 13342703ccaca5064ad33ba451d800c5e823db8f

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

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

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

$webhookServer = WebhookServer::create($callback, PROJECT_KEY);
$webhookServer->start();
HTTP/1.1 204 No Content

已更新订阅

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

参数类型描述
notification_type
string通知类型。 必需
settings
object带有自定义项目设置的对象。
settings.project_id
integer游戏的艾克索拉ID。可以在发布商帐户中找到该ID。
settings.merchant_id
integer商户ID。
user
object带用户相关数据的对象。
user.id
string用户ID。 必需
user.name
string用户名。
subscription
object订阅详情(对象)。
subscription.plan_id
string计划ID(如果计划通过API创建,则为外部ID)。
subscription.tags
array计划标签。
subscription.subscription_id
integer艾克索拉数据库的订阅ID。
subscription.product_id
string产品ID(如果在访问令牌中发送)。
subscription.date_next_charge
string下次收费的日期。符合ISO 8601标准规定的日期与时间。
Copy
Full screen
Small screen
php
  • php
  • http
  • curl
请求
<?php

$request = array(
    'notification_type' => 'update_subscription',
    'settings' => array(
       'project_id' => 18404,
       'merchant_id' => 2340
    ),
    'user' => array(
        'id' => '1234567',
        'name' => 'Xsolla User'
    ),
    'subscription' => array(
        'plan_id' => 'b5dac9c8',
        'subscription_id' => '10',
        'product_id' => 'Demo Product',
        'date_next_charge' => '2015-01-22T19:25:25+04:00'
    )
);
POST /your/uri HTTP/1.1
Host: your.hostname
Accept: application/json
Content-Type: application/json
Content-Length: 240
Authorization: Signature 13342703ccaca5064ad33ba451d800c5e823db8f

{
    "notification_type": "update_subscription",
    "settings": {
       "project_id": 18404,
       "merchant_id": 2340
    },
    "user": {
        "id": "1234567",
        "name": "Xsolla User"
    },
    "subscription": {
        "plan_id": "b5dac9c8",
        "subscription_id": "10",
        "product_id": "Demo Product",
        "date_next_charge": "2015-01-22T19:25:25+04:00"
    }
}
$ curl -v 'https://your.hostname/your/uri' \
-X POST \
-H 'Accept: application/json' \
-H 'Content-Type: application/json' \
-H 'Authorization: Signature 13342703ccaca5064ad33ba451d800c5e823db8f' \
-d '{
        "notification_type": "update_subscription",
        "settings": {
           "project_id": 18404,
           "merchant_id": 2340
        },
        "user": {
            "id": "1234567",
            "name": "Xsolla User"
        },
        "subscription": {
            "plan_id": "b5dac9c8",
            "subscription_id": "10",
            "product_id": "Demo Product",
            "date_next_charge": "2015-01-22T19:25:25+04:00"
        }
    }'
响应
<?php

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

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

$webhookServer = WebhookServer::create($callback, PROJECT_KEY);
$webhookServer->start();
HTTP/1.1 204 No Content

已取消订阅

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

参数类型描述
notification_type
string通知类型。 必需
settings
object带有自定义项目设置的对象。
settings.project_id
integer游戏的艾克索拉ID。可以在发布商帐户中找到该ID。
settings.merchant_id
integer商户ID。
user
object带用户相关数据的对象。
user.id
string用户ID。 必需
user.name
string用户名。
subscription
object订阅详情(对象)。
subscription.plan_id
string计划ID(如果计划通过API创建,则为外部ID)。
subscription.tags
array计划标签。
subscription.subscription_id
integer艾克索拉数据库的订阅ID。
subscription.product_id
string产品ID(如果在访问令牌中发送)。
subscription.date_create
string订阅的创建日期。符合ISO 8601标准规定的日期与时间。
subscription.date_end
string订阅结束的日期。符合ISO 8601标准规定的日期与时间。
Copy
Full screen
Small screen
php
  • php
  • http
  • curl
请求
<?php

$request = array(
    'notification_type' => 'cancel_subscription',
    'settings' => array(
       'project_id' => 18404,
       'merchant_id' => 2340
    ),
    'user' => array(
        'id' => '1234567',
        'name' => 'Xsolla User'
    ),
    'subscription' => array(
        'plan_id' => 'b5dac9c8',
        'subscription_id' => '10',
        'product_id' => 'Demo Product',
        'date_create' => '2014-09-22T19:25:25+04:00',
        'date_end' => '2015-01-22T19:25:25+04:00',
    )
);
POST /your/uri HTTP/1.1
Host: your.hostname
Accept: application/json
Content-Type: application/json
Content-Length: 240
Authorization: Signature 13342703ccaca5064ad33ba451d800c5e823db8f

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

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

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

$webhookServer = WebhookServer::create($callback, PROJECT_KEY);
$webhookServer->start();
HTTP/1.1 204 No Content

到期性订阅

订阅状态由于任何原因设置为非续订时,我们会向您的Webhook URL发送通知non_renewal_subscription

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

获取游戏密钥

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

参数类型描述
notification_type
string通知类型。
settings
object带有自定义项目设置的对象。
settings.project_id
integer游戏的艾克索拉ID。可以在发布商帐户中找到该ID。
settings.merchant_id
integer商户ID。
user
object带用户相关数据的对象。
user.id
string用户ID。 必需
user.name
string用户名。
pin_code
object游戏密钥详细信息(对象)。
pin_code.digital_content
string游戏的SKU。
pin_code.DRM
string游戏应对其可用的DRM。
Copy
Full screen
Small screen
php
  • php
  • http
  • curl
请求
<?php

$request = array (
       'notification_type' => 'get_pincode',
       'settings' => array(
          'project_id' => 18404,
          'merchant_id' => 2340
       ),
       'user' =>
           array (
               'id' => '1234567',
               'name' => 'Xsolla User',
           ),
       'pin_code' =>
           array (
               'digital_content' => 'Game SKU',
               'DRM' => 'Steam',
           ),
   );
POST /your/uri HTTP/1.1
Host: your.hostname
Accept: application/json
Content-Type: application/json
Content-Length: 240
Authorization: Signature 13342703ccaca5064ad33ba451d800c5e823db8f

{
    "notification_type": "get_pincode",
    "settings": {
       "project_id": 18404,
       "merchant_id": 2340
    },
    "user": {
        "id": "1234567",
        "name": "Xsolla User"
    },
    "pin_code": {
        "digital_content": "Game SKU",
        "DRM": "Steam"
    }
}
$ curl -v 'https://your.hostname/your/uri' \
-X POST \
-H 'Accept: application/json' \
-H 'Content-Type: application/json' \
-H 'Authorization: Signature 13342703ccaca5064ad33ba451d800c5e823db8f' \
-d '{
        "notification_type": "get_pincode",
        "settings": {
           "project_id": 18404,
           "merchant_id": 2340
        },
        "user": {
            "id": "1234567",
            "name": "Xsolla User"
        },
        "pin_code": {
            "digital_content": "Game SKU",
            "DRM": "Steam"
        }
    }'
响应
<?php

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

$callback = function (Message $message) {
    if ($message instanceof GetPinCodeMessage) {
        $userArray = $message->getUser();
        $drmSku = $message->getDRM();
        $digitalContentSku = $message->getDigitalContent();
        // TODO get a pin code from your database or generate a new one. Put the pin code into variable $newPinCode
        $newPinCode = 'NEW_PIN_CODE';
        // TODO if the pin code creation or generation fail for some reason, you should throw XsollaWebhookException
        return new \Xsolla\SDK\Webhook\Response\PinCodeResponse($newPinCode);
    }
};
$webhookServer = WebhookServer::create($callback, PROJECT_KEY);
$webhookServer->start();
HTTP/1.1 200 OK
Content-Type: application/json
{
    "pin_code": "PIN_CODE"
}

激活密钥

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

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

{
  "notification_type": "redeem_key",
  "settings": {
     "project_id": 18404,
     "merchant_id": 2340
  },
  "key": "wqdqwwddq9099022",
  "sku": "123",
  "user_id": "sample_user",
  "activation_date": "2018-11-20T08:38:51+03:00",
  "user_country": "EN",
  "restriction": {
      "name": "cls_1",
      "types": [
           "activation"
        ],
        "countries": [
             "RU"
        ]
  }
}
$ curl -v 'https://your.hostname/your/uri' \
-X POST \
-H 'Accept: application/json' \
-H 'Content-Type: application/json' \
-H 'Authorization: Signature 13342703ccaca5064ad33ba451d800c5e823db8f' \
-d '{
  "notification_type": "redeem_key",
  "settings": {
        "project_id": 18404,
        "merchant_id": 2340
  },
  "key": "wqdqwwddq9099022",
  "sku": "123",
  "user_id": "sample_user",
  "activation_date": "2018-11-20T08:38:51+03:00",
  "user_country": "EN",
  "restriction": {
      "name": "cls_1",
      "types": [
           "activation"
        ],
        "countries": [
             "RU"
         ]
    }
}'
响应
<?php

$response = null;
HTTP/1.1 204 No Content

列表好友

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

HTTP请求

Copy
Full screen
Small screen

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

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

[
  {
    "friends": [
      {
        "id": "1",
        "name": "doctor",
        "email": "doctor@hospital.com",
        "image_url": "https://partner/link/doctor.jpg"
      },
      {
        "id": "2",
        "name": "cook",
        "email": "cook@kitchen.com",
        "image_url": "https://partner/link/cook.jpg"
      },
      {
        "id": "3",
        "name": "teacher",
        "email": "teacher@school.com"
      },
      {
        "id": "4",
        "name": "god",
        "email": "god@heaven.com",
        "image_url": "https://partner/link/god.jpg"
      }
      ],
    "total": 10
  }
]
[
  {
  "friends": [
      {
        "id": "1",
        "name": "John Carter",
        "email": "carter@xsolla.com",
        "image_url": "https://partner/link/doctor.jpg"
      },
      {
        "id": "2",
        "name": "John Smith",
        "email": "smith@xsolla.com",
        "image_url": "https://partner/link/cook.jpg"
      }
    ],
  "total": 10
  }
]

用户余额:支付

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

参数类型描述
notification_type
string通知类型。
settings
object带有自定义项目设置的对象。
settings.project_id
integer游戏的艾克索拉ID。可以在发布商帐户中找到该ID。
settings.merchant_id
integer商户ID。
operation_type
string操作类型。
id_operation
integer艾克索拉数据库中的操作ID。
user
object带用户相关数据的对象。
user.id
string用户ID。 必需
user.name
string用户名。
user.email
string用户电子邮件。
virtual_currency_balance
object带有系统中用户余额相关数据的对象。
virtual_currency_balance.old_value
string处理当前操作之前旧的用户余额值。
virtual_currency_balance.new_value
string处理当前操作之后新的用户余额值。
virtual_currency_balance.diff
string购买的游戏货币的金额。
transaction
object交易ID。 必需
transaction.id
integer交易ID。
transaction.date
string交易日期。
Copy
Full screen
Small screen
php
  • php
  • http
  • curl
请求
<?php

$request = array(
    'settings' => array(
        'project_id' => 18404,
        'merchant_id' => 2340
    ),
    'virtual_currency_balance' => array(
        'old_value' => '0',
        'new_value' => '200',
        'diff' => '200'
    ),
    'user' => array(
        'name' => 'Xsolla User',
        'id' => '1234567',
        'email' => 'email@example.com'
    ),
    'transaction' => array(
        'id' => '123456789',
        'date' => '2015-05-19T15:54:40+03:00'
    ),
    'operation_type' => 'payment',
    'notification_type' => 'user_balance_operation',
    'id_operation' => '66989'
);
POST /your/uri HTTP/1.1
Host: your.hostname
Accept: application/json
Content-Type: application/json
Content-Length: 240
Authorization: Signature 13342703ccaca5064ad33ba451d800c5e823db8f

{
    "settings": {
        "project_id": 18404,
        "merchant_id": 2340
    },
    "virtual_currency_balance": {
        "old_value": "0",
        "new_value": "200",
        "diff": "200"
    },
    "user": {
        "name": "Xsolla User",
        "id": "1234567",
        "email": "email@example.com"
    },
    "transaction": {
        "id": "123456789",
        "date": "2015-05-19T15:54:40+03:00"
    },
    "operation_type": "payment",
    "notification_type": "user_balance_operation",
    "id_operation": "66989"
}
$ curl -v 'https://your.hostname/your/uri' \
-X POST \
-H 'Accept: application/json' \
-H 'Content-Type: application/json' \
-H 'Authorization: Signature 13342703ccaca5064ad33ba451d800c5e823db8f' \
-d '{
        "settings": {
          "project_id": 18404,
          "merchant_id": 2340
        },
        "virtual_currency_balance": {
            "old_value": "0",
            "new_value": "200",
            "diff": "200"
        },
        "user": {
            "name": "Xsolla User",
            "id": "1234567",
            "email": "email@example.com"
        },
        "transaction": {
            "id": "123456789",
            "date": "2015-05-19T15:54:40+03:00"
        },
        "operation_type": "payment",
        "notification_type": "user_balance_operation",
        "id_operation": "66989"
    }'
响应
<?php

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

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

$webhookServer = WebhookServer::create($callback, PROJECT_KEY);
$webhookServer->start();
HTTP/1.1 204 No Content

用户余额:购买

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

参数类型描述
notification_type
string通知类型。
settings
object带有自定义项目设置的对象。
settings.project_id
integer游戏的艾克索拉ID。可以在发布商帐户中找到该ID。
settings.merchant_id
integer商户ID。
operation_type
string操作类型。
id_operation
integer艾克索拉数据库中的操作ID。
user
object带用户相关数据的对象。
user.id
string用户ID。 必需
user.name
string用户名。
user.email
string用户电子邮件。
virtual_currency_balance
object带有系统中用户余额相关数据的对象。
virtual_currency_balance.old_value
string处理当前操作之前旧的用户余额值。
virtual_currency_balance.new_value
string处理当前操作之后新的用户余额值。
virtual_currency_balance.diff
string购买的游戏货币的金额。
items_operation_type
string游戏内购买的操作类型。
items
array带有游戏内购买的物品相关数据的数组。
items.sku
string物品ID。
items.amount
integer物品数量。
Copy
Full screen
Small screen
php
  • php
  • http
  • curl
请求
<?php

$request = array(
    'settings' => array(
            'project_id' => 18404,
            'merchant_id' => 2340
    ),
    'virtual_currency_balance' => array(
            'old_value' => '0',
            'new_value' => '200',
            'diff' => '200'
    ),
    'user' => array(
        'name' => 'Xsolla User',
        'id' => '1234567',
        'email' => 'email@example.com'
    ),
    'operation_type' => 'inGamePurchase',
    'notification_type' => 'user_balance_operation',
    'items_operation_type' =>  'add',
         'items' =>  array(
             'sku' =>  '1468',
             'amount' =>  '2'
         ),
    'id_operation' => '66989'
);
POST /your/uri HTTP/1.1
Host: your.hostname
Accept: application/json
Content-Type: application/json
Content-Length: 240
Authorization: Signature 13342703ccaca5064ad33ba451d800c5e823db8f

{
    "settings": {
        "project_id": 18404,
        "merchant_id": 2340
    },
    "virtual_currency_balance": {
        "old_value": "0",
        "new_value": "200",
        "diff": "200"
    },
    "user": {
        "name": "Xsolla User",
        "id": "1234567",
        "email": "email@example.com"
    },
    "operation_type": "inGamePurchase",
    "notification_type": "user_balance_operation",
    "items_operation_type": "add",
         "items": [{
         "sku": "1468",
         "amount": "2"
         }],
    "id_operation": "66989"
}
$ curl -v 'https://your.hostname/your/uri' \
-X POST \
-H 'Accept: application/json' \
-H 'Content-Type: application/json' \
-H 'Authorization: Signature 13342703ccaca5064ad33ba451d800c5e823db8f' \
-d '{
        "settings": {
            "project_id": 18404,
            "merchant_id": 2340
        },
        "virtual_currency_balance": {
            "old_value": "0",
            "new_value": "200",
            "diff": "200"
        },
        "user": {
            "name": "Xsolla User",
            "id": "1234567",
            "email": "email@example.com"
        },
        "operation_type": "inGamePurchase",
        "notification_type": "user_balance_operation",
        "items_operation_type": "add",
             "items": [{
             "sku": "1468",
             "amount": "2"
             }],
        "id_operation": "66989"
    }'
响应
<?php

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

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

$webhookServer = WebhookServer::create($callback, PROJECT_KEY);
$webhookServer->start();
HTTP/1.1 204 No Content

用户余额:兑换优惠券

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

参数类型描述
notification_type
string通知类型。
settings
object带有自定义项目设置的对象。
settings.project_id
integer游戏的艾克索拉ID。可以在发布商帐户中找到该ID。
settings.merchant_id
integer商户ID。
operation_type
string操作类型。
id_operation
integer艾克索拉数据库中的操作ID。
user
object带用户相关数据的对象。
user.id
string用户ID。 必需
user.name
string用户名。
user.email
string用户电子邮件。
virtual_currency_balance
object带有系统中用户余额相关数据的对象。
virtual_currency_balance.old_value
string处理当前操作之前旧的用户余额值。
virtual_currency_balance.new_value
string处理当前操作之后新的用户余额值。
virtual_currency_balance.diff
string购买的游戏货币的金额。
items_operation_type
string游戏内购买的操作类型。
items
array带有游戏内购买的物品相关数据的数组。
items.sku
string物品ID。
items.amount
integer物品数量。
coupon
object带有优惠券相关数据的对象。
coupon.coupon_code
string优惠券代码。
coupon.campaign_code
string优惠券营销活动的代码。
Copy
Full screen
Small screen
php
  • php
  • http
  • curl
请求
<?php

$request = array(
    'settings' => array(
        'project_id' => 18404,
        'merchant_id' => 2340
    ),
    'virtual_currency_balance' => array(
        'old_value' => '0',
        'new_value' => '0',
        'diff' => '0'
    ),
    'user' => array(
        'name' => 'Xsolla User',
        'id' => '1234567',
        'email' => 'email@example.com'
    ),
    'operation_type' => 'coupon',
    'notification_type' => 'user_balance_operation',
    'items_operation_type' =>  'add',
         'items' =>  array(
             'sku' =>  '1468',
             'amount' =>  '2'
         ),
    'id_operation' => '66989',
    'coupon' =>  array(
         'coupon_code' =>  'test123',
         'campaign_code' =>  'Xsolla Campaign'
    )
);
POST /your/uri HTTP/1.1
Host: your.hostname
Accept: application/json
Content-Type: application/json
Content-Length: 240
Authorization: Signature 13342703ccaca5064ad33ba451d800c5e823db8f

{
    "settings": {
        "project_id": 18404,
        "merchant_id": 2340
    },
    "virtual_currency_balance": {
        "old_value": "0",
        "new_value": "0",
        "diff": "0"
    },
    "user": {
        "name": "Xsolla User",
        "id": "1234567",
        "email": "email@example.com"
    },
    "operation_type": "coupon",
    "notification_type": "user_balance_operation",
    "items_operation_type": "add",
         "items": [{
             "sku": "1468",
             "amount": "2"
         }],
    "id_operation": "66989",
    "coupon": {
         "coupon_code": "test123",
         "campaign_code": "Xsolla Campaign"
    }
}
$ curl -v 'https://your.hostname/your/uri' \
-X POST \
-H 'Accept: application/json' \
-H 'Content-Type: application/json' \
-H 'Authorization: Signature 13342703ccaca5064ad33ba451d800c5e823db8f' \
-d '{
        "settings": {
            "project_id": 18404,
            "merchant_id": 2340
        },
        "virtual_currency_balance": {
            "old_value": "0",
            "new_value": "0",
            "diff": "0"
        },
        "user": {
            "name": "Xsolla User",
            "id": "1234567",
            "email": "email@example.com"
        },
        "operation_type": "coupon",
        "notification_type": "user_balance_operation",
        "items_operation_type": "add",
             "items": [{
                 "sku": "1468",
                 "amount": "2"
             }],
        "id_operation": "66989",
        "coupon": {
             "coupon_code": "test123",
             "campaign_code": "Xsolla Campaign"
        }
    }'
响应
<?php

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

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

$webhookServer = WebhookServer::create($callback, PROJECT_KEY);
$webhookServer->start();
HTTP/1.1 204 No Content

用户余额:手动更新

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

参数类型描述
notification_type
string通知类型。
settings
object带有自定义项目设置的对象。
settings.project_id
integer游戏的艾克索拉ID。可以在发布商帐户中找到该ID。
settings.merchant_id
integer商户ID。
operation_type
string操作类型。
id_operation
integer艾克索拉数据库中的操作ID。
user
object带用户相关数据的对象。
user.id
string用户ID。 必需
user.name
string用户名。
user.email
string用户电子邮件。
virtual_currency_balance
object带有系统中用户余额相关数据的对象。
virtual_currency_balance.old_value
string处理当前操作之前旧的用户余额值。
virtual_currency_balance.new_value
string处理当前操作之后新的用户余额值。
virtual_currency_balance.diff
string购买的游戏货币的金额。
Copy
Full screen
Small screen
php
  • php
  • http
  • curl
请求
<?php

$request = array(
    'settings' => array(
        'project_id' => 18404,
        'merchant_id' => 2340
    ),
    'virtual_currency_balance' => array(
        'old_value' => '0',
        'new_value' => '100',
        'diff' => '100'
    ),
    'user' => array(
        'name' => 'Xsolla User',
        'id' => '1234567',
        'email' => 'email@example.com'
    ),
    'operation_type' => 'internal',
    'notification_type' => 'user_balance_operation',
    'id_operation' => '67002'
);
POST /your/uri HTTP/1.1
Host: your.hostname
Accept: application/json
Content-Type: application/json
Content-Length: 240
Authorization: Signature 13342703ccaca5064ad33ba451d800c5e823db8f

{
    "settings": {
        "project_id": 18404,
        "merchant_id": 2340
    },
    "virtual_currency_balance": {
        "old_value": "0",
        "new_value": "100",
        "diff": "100"
    },
    "user": {
        "name": "Xsolla User",
        "id": "1234567",
        "email": "email@example.com"
    },
    "operation_type": "internal",
    "notification_type": "user_balance_operation",
    "id_operation": "67002"
}
$ curl -v 'https://your.hostname/your/uri' \
-X POST \
-H 'Accept: application/json' \
-H 'Content-Type: application/json' \
-H 'Authorization: Signature 13342703ccaca5064ad33ba451d800c5e823db8f' \
-d '{
        "settings": {
          "project_id": 18404,
          "merchant_id": 2340
        },
        "virtual_currency_balance": {
            "old_value": "0",
            "new_value": "100",
            "diff": "100"
        },
        "user": {
            "name": "Xsolla User",
            "id": "1234567",
            "email": "email@example.com"
        },
        "operation_type": "internal",
        "notification_type": "user_balance_operation",
        "id_operation": "67002"
    }'
响应
<?php

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

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

$webhookServer = WebhookServer::create($callback, PROJECT_KEY);
$webhookServer->start();
HTTP/1.1 204 No Content

用户余额:退款

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

参数类型描述
notification_type
string通知类型。
settings
object带有自定义项目设置的对象。
settings.project_id
integer游戏的艾克索拉ID。可以在发布商帐户中找到该ID。
settings.merchant_id
integer商户ID。
operation_type
string操作类型。
id_operation
integer艾克索拉数据库中的操作ID。
user
object带用户相关数据的对象。
user.id
string用户ID。 必需
user.name
string用户名。
user.email
string用户电子邮件。
virtual_currency_balance
object带有系统中用户余额相关数据的对象。
virtual_currency_balance.old_value
string处理当前操作之前旧的用户余额值。
virtual_currency_balance.new_value
string处理当前操作之后新的用户余额值。
virtual_currency_balance.diff
string购买的游戏货币的金额。
transaction
object交易ID。 必需
transaction.id
integer交易ID。
transaction.date
string交易日期。
items_operation_type
string游戏内购买的操作类型。
items
array带有游戏内购买的物品相关数据的数组。
items.sku
string物品ID。
items.amount
integer物品数量。
Copy
Full screen
Small screen
php
  • php
  • http
  • curl
请求
<?php

$request = array(
     'settings' => array(
         'project_id' => 18404,
         'merchant_id' => 2340
     ),
     'virtual_currency_balance' => array(
         'old_value' => '0',
         'new_value' => '0',
         'diff' => '0'
     ),
     'user' => array(
         'name' => 'Xsolla User',
         'id' => '1234567',
         'email' => 'email@example.com'
     ),
     'transaction' => array(
         'id' => '123456789',
         'date' => '2015-05-19T15:54:40+03:00'
     ),
     'operation_type' => 'cancellation',
     'notification_type' => 'user_balance_operation',
     'items_operation_type' =>  'remove',
         'items' =>  array(
             'sku' =>  '1468',
             'amount' =>  '2'
         ),
     'id_operation' => '66989'
);
POST /your/uri HTTP/1.1
Host: your.hostname
Accept: application/json
Content-Type: application/json
Content-Length: 240
Authorization: Signature 13342703ccaca5064ad33ba451d800c5e823db8f

{
    "settings": {
        "project_id": 18404,
        "merchant_id": 2340
    },
    "virtual_currency_balance": {
        "old_value": "0",
        "new_value": "0",
        "diff": "0"
    },
    "user": {
        "name": "Xsolla User",
        "id": "1234567",
        "email": "email@example.com"
    },
    "transaction": {
        "id": "123456789",
        "date": "2015-05-19T15:54:40+03:00"
    },
    "operation_type": "cancellation",
    "notification_type": "user_balance_operation",
    "items_operation_type": "remove",
         "items": [{
             "sku": "1468",
             "amount": "2"
         }],
    "id_operation": "66989"
}
$ curl -v 'https://your.hostname/your/uri' \
-X POST \
-H 'Accept: application/json' \
-H 'Content-Type: application/json' \
-H 'Authorization: Signature 13342703ccaca5064ad33ba451d800c5e823db8f' \
-d '{
        "settings": {
          "project_id": 18404,
          "merchant_id": 2340
        },
        "virtual_currency_balance": {
            "old_value": "0",
            "new_value": "0",
            "diff": "0"
        },
        "user": {
            "name": "Xsolla User",
            "id": "1234567",
            "email": "email@example.com"
        },
        "transaction": {
            "id": "123456789",
            "date": "2015-05-19T15:54:40+03:00"
        },
        "operation_type": "cancellation",
        "notification_type": "user_balance_operation",
        "items_operation_type": "remove",
             "items": [{
                 "sku": "1468",
                 "amount": "2"
             }],
        "id_operation": "66989"
    }'
响应
<?php

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

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

$webhookServer = WebhookServer::create($callback, PROJECT_KEY);
$webhookServer->start();
HTTP/1.1 204 No Content

添加支付帐户

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

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

{
    "notification_type": "payment_account_add",
    "settings": {
       "project_id": 18404,
       "merchant_id": 2340
    },
    "user": {
        "ip": "127.0.0.1",
        "email": "email@example.com",
        "id": "1234567",
        "name": "John Smith",
        "country": "RU",
        "zip": "12345"
    },
    "payment_account": {
        "id": "12345678",
        "name": "email@example.com",
        "payment_method": "24",
        "type": "paypal"
    }
}
$ curl -v 'https://your.hostname/your/uri' \
-X POST \
-H 'Accept: application/json' \
-H 'Content-Type: application/json' \
-H 'Authorization: Signature d09695066c52c1b8bdae92f2d6eb59f5b5f89843' \
-d '{
    "notification_type":"payment_account_add",
    "settings": {
       "project_id": 18404,
       "merchant_id": 2340
    },
    "user": {
        "ip": "127.0.0.1",
        "email": "email@example.com",
        "id": "1234567",
        "name": "John Smith",
        "country": "RU",
        "zip": "12345"
    },
    "payment_account": {
        "id": "12345678",
        "name": "email@example.com",
        "payment_method": "24",
        "type": "paypal"
    }
}'
响应
HTTP/1.1 204 No Content

删除支付帐户

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

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


{
    "notification_type": "payment_account_remove",
    "settings": {
       "project_id": 18404,
       "merchant_id": 2340
    },
    "user": {
        "email": "email@example.com",
        "id": "1234567",
        "name": "John Smith"
    },
    "payment_account": {
        "id": "12345678",
        "name": "email@example.com",
        "payment_method": "24",
        "type": "paypal"
    }
}
$ curl -v 'https://your.hostname/your/uri' \
-X POST \
-H 'Accept: application/json' \
-H 'Content-Type: application/json' \
-H 'Authorization: Signature d09695066c52c1b8bdae92f2d6eb59f5b5f89843' \
-d '{
    "notification_type": "payment_account_remove",
    "settings": {
       "project_id": 18404,
       "merchant_id": 2340
    },
    "user": {
        "email": "email@example.com",
        "id": "1234567",
        "name": "John Smith"
    },
    "payment_account": {
        "id": "12345678",
        "name": "email@example.com",
        "payment_method": "24",
        "type": "paypal"
    }
}'
响应
HTTP/1.1 204 No Content

Webhook错误

永久性错误代码:

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

HTTP/1.1 400 Bad Request

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