创建令牌

Xsolla Developers

或

前往发布商帐户

创建令牌Server-side

post/merchants/{merchant_id}/token

您可以通过任意用户参数创建令牌。您在获取令牌时发送这些参数并在成功支付后会收到发回的参数。令牌只能包含本文档中描述的参数或您预定义的参数。

如果任何参数以不正确的格式或类型发送，将不会获得令牌。作为响应，您将收到422 HTTP代码，JSON正文中有相应的错误描述。在extended_message中，您将收到具体错误参数的相关信息。

默认情况下，令牌有效期是24小时。如要更改该值，请联系您的客户成功经理或发送邮件至csm@xsolla.com。新值将对您公司在发布商帐户中创建的所有项目启用。

注意

调用此API方法后获得的令牌只能用于授权其他请求。只有在集成了订阅产品的情况下才能使用此令牌打开支付UI。

要在新窗口中打开支付UI，请使用以下链接：https://secure.xsolla.com/paystation4/?token={token} ，其中{token}是收到的令牌。

如要进行测试，请使用以下URL： https://sandbox-secure.xsolla.com/paystation4/?token={token}。

注意

此API调用不包含project_id路径参数，因此您需要使用在您公司的所有项目中都有效的API密钥来设置授权。

SecuritybasicAuth

Request

path Parameters

merchant_id

required

integer

商户ID。

Request Body schema: application/json

object

此对象包含配置防欺诈筛选条件的参数。参数列表如下所示。要添加自定义参数，请联系您的客户成功经理或发送邮件至csm@xsolla.com。

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

object

带有购买相关数据的对象。

object

带有订阅相关数据的对象。

available_plans	Array of strings 包含订阅套餐相关数据的数组。只有这些套餐会显示在支付用户界面中。
currency	string 购买计划的货币，以此币种进行所有计算。
operation	string 此操作的类型应用于用户订阅计划。要更改订阅计划，请传入`change_plan`值。需在`purchase.subscription.plan_id`参数中指定新计划的ID。
plan_id	string 订阅计划的外部ID。可在发布商帐户的订阅 > 订阅计划中找到。
product_id	string 产品ID。
trial_days	integer 试用期，以天为单位。

object

为用户配置支付流程和支付UI的设置。

project_id

required

integer

游戏的艾克索拉ID。可以在发布商帐户中找到该ID。

currency

string

首选支付币种。参照ISO 4217标准的三字母货币代码。

external_id

string

游戏中的交易ID。该值对每个用户支付必须唯一。详细信息请参阅文档。

language

string

界面语言。2字母（小写字母）语言代码。

mode

string

设置为sandbox值以测试支付流程。请使用https://sandbox-secure.xsolla.com来访问测试支付UI。

payment_method

integer

付款方式ID。

payment_widget

string

支付小部件。可以是 paybycash 或 giftcard。如果参数已设置，用户将分别重定向到 Pay by Cash 或 Gift Cards 小部件。

Enum: "paybycash" "giftcard"

object

重定向政策设置（对象）。

delay	integer 延迟时间（单位为秒），经过该时间后用户将自动重定向至返回URL。
manual_redirection_action	string 由用户点击关闭按钮或返回游戏按钮触发的支付中心行为。可以是`redirect`（默认）或`postmessage`。如果设置为`redirect`，则用户将被重定向至令牌中传入的URL或发布商帐户中指定的URL。如果设置为`postmessage`，则用户留在原页面。点击关闭按钮发起发送`close`事件，点击返回游戏则发起发送`return`事件。 Enum: "redirect" "postmessage"
redirect_button_caption	string 手动重定向按钮上的文字。
redirect_conditions	string 将用户重定向至返回URL的支付状态。可以是`none`, `successful`, `successful_or_canсeled`或`any`。 Enum: "none" "successful" "successful_or_canceled" "any"
status_for_manual_redirection	string 显示让用户重定向至返回URL按钮的支付状态。可以是`none`, `successful`, `successful_or_canсeled`或`any`。 Enum: "none" "successful" "successful_or_canceled" "any"

return_url

string

用户付款后重定向到的页面的URL。关于配置重定向的详细信息，请参阅文档。

object

带有界面设置相关数据的对象。

object

带有模块菜单设置相关数据的对象。

object

带有订阅模块设置相关数据的对象。

hidden	boolean 在菜单中显示还是隐藏“管理订阅”页面。
order	integer 虚拟物品在模块菜单中的排列顺序。

object

带有虚拟货币模块设置相关数据的对象。

custom_amount	boolean 是否允许在支付UI中输入任意数量的虚拟货币。
hidden	boolean 在菜单中显示还是隐藏“管理订阅”页面。
order	integer 虚拟物品在模块菜单中的排列顺序。

object

带有虚拟物品模块设置相关数据的对象。

hidden	boolean 在菜单中显示还是隐藏“管理订阅”页面。
order	integer 虚拟物品在模块菜单中的排列顺序。
selected_group	string 用户打开虚拟物品选项卡时将会选择的组。
selected_item	string 用户打开虚拟物品选项卡时将会选择的物品。物品 SKU 应发送至此处。

currency_format

string

设置为code以在支付UI中显示三字母的ISO 4217货币代码。默认显示货币符号而不是三字母货币代码。

object

带有对桌面版本有效的界面设置相关数据的对象。

object

带有标题设置相关数据的对象。

close_button

boolean

是否在支付UI中显示关闭按钮。该按钮将关闭支付UI并将用户重定向到settings.return_url参数中指定的URL。默认为false。

close_button_icon

string

支付UI中的关闭按钮图标。

Enum:	Description
arrow	支付UI页眉左侧的←图标。
cross	支付UI页眉右侧的×图标。

is_visible

boolean

标题在支付UI上是否可见。

type

string

如何显示标题。不能为compact（隐藏项目名称和用户ID）或normal（默认）。

Enum: "compact" "normal"

visible_logo

boolean

如为true，Logo在标题中显示。要上传图片，请在发布商帐户中打开您的项目，然后前往支付中心 > 设置部分。

visible_name

boolean

标题中是否显示项目名称。

visible_purchase

boolean

是否在标题中显示购买描述（purchase.description.value）。默认为true。

object

带有订阅列表设置相关数据的对象。

description	string 可以在此传递订阅相关的任意文本。文本将显示在订阅计划列表的上方。
display_local_price	boolean 如为`true`且如果用户的当地货币与订阅计划的货币不同，则用户将看到两种价格：以当地货币和基础货币标价的价格。

gp_quick_payment_button

boolean

Google Pay支付方式的显示方式。如为true，则通过Google Pay快速支付的按钮在支付UI顶部显示。如为false，则根据PayRank算法在支付方式列表中显示Google Pay。默认为false。

object

visible_virtual_currency_balance

boolean

此元素是否可在支付UI上隐藏。默认为true。

is_cart_open_by_default

boolean

打开支付UI移动版本时购物车商品列表的显示方式。如为true，列表以扩展视图显示。如为false（默认）或未传入此参数，列表以折叠视图显示。

is_independent_windows

boolean

是否将用户从嵌入式启动器浏览器(WebView)跳转到其默认的浏览器来进行购买。默认为false。

is_payment_methods_list_mode

boolean

打开支付UI时是否显示在该用户所在国家/地区可用的支付方式。如为false（默认），将显示在settings.payment_method参数中传入的支付方式或PayRank算法选择的支付方式。

is_prevent_external_link_open

boolean

是否禁用将链接重定向至外部资源。默认为false。点击外部链接时，将通过postMessage机制发送external-link-open事件。重定向链接的地址在url参数中传递。

is_search_field_hidden

boolean

是否在支付UI中显示支付方式搜索栏。如为true，则隐藏搜索栏，默认为false。

is_show_close_widget_warning

boolean

关闭支付页面前鼠标悬停在 ×图标时是否显示交易正在处理中的警告。如传入false，或未传入参数，则不显示警告。默认为true。

is_three_ds_independent_windows

boolean

Default: false

是否在新浏览器窗口中打开3-D Secure检查。如果您的设置强制执行内容安全政策(CSP)，请设置为true。

layout

string

支付UI主要元素的位置。您可以在游戏内打开支付UI和/或交换订单信息和支付方式信息列的位置。详细信息请参阅自定义说明。

Enum: "embed" "column_reverse" "embed_column_reverse"

object

close_button

boolean

是否在支付中心移动端显示关闭按钮。该按钮将关闭支付中心并将用户重定向到settings.return_url参数中指定的URL。默认为false。

close_button_icon

string

支付UI中的关闭按钮图标。

Enum:	Description
arrow	支付UI页眉左侧的←图标。
cross	支付UI页眉右侧的×图标。

mode

string

支付中心的界面模式。可能的值为user_account。请注意，页眉仅包含用户帐户的导航菜单，而没有用于选择产品或进行付款的任何选项。“用户帐户”仅在桌面模式下可用。

theme

string

支付UI主题。可以是63295a9a2e47fab76f7708e1（浅色主题（默认）），或63295aab2e47fab76f7708e3（深色主题）。您也可以创建自定义主题，然后在此参数中传入其ID。

Enum: "63295a9a2e47fab76f7708e1" "63295aab2e47fab76f7708e3"

object

对象以及有关用户账号的数据。

object

保存的支付方式部分。

enable	boolean 指定是否在支付UI中显示前往支付方式编辑页面的铅笔图标。默认为`true`。
order	integer >= 1 该部分在支付UI下拉列表中的位置。如传入了`settings.ui.user_account.payment_accounts.enable`，则该属性为必需。

object

带用户相关数据的对象。

required

object

value

required

string

存储在己侧的游戏内唯一用户ID。请确保传入现有用户ID。如遇到错误，请参阅常见问题回答。

age

integer

用户年龄。

attributes

object

带有用户属性相关数据的对象，用于筛选物品列表。应当是带键值对的有效JSON哈希。

object

allow_modify	boolean 用户是否可以更改支付UI上的国家/地区。如果令牌中传入了`country.value`值，则值默认为`false`。
value	string 使用ISO 3166-1 alpha-2标准规定的2字母组合表示国家/地区。

object <= 100 characters

user.email对象是反欺诈模型的必要部分，有助于提高接受率。同时它也是艾克索拉和支付系统的要求。如果未传入该参数，支付页面将显示输入邮箱必填字段。购买凭证将发送至在该参数中传入的或在支付页面上输入的邮箱地址。

value required	string 用户电子邮箱。必须符合RFC 822协议标准。
allow_modify	boolean 用户是否可在支付UI中输入其邮箱。如令牌中传入了`user.email.value`参数，该值默认为`false`。

is_legal

boolean

用户是否为法律实体。

object

包含法律实体详细信息的对象。如果user.is_legal为true，则对象及其所有参数为必需。

address	string 完整法定地址。
country	string 公司所在国家/地区。参照ISO 3166-1 alpha-2标准的两个大写字母表示的国家/地区代码。
name	string 完整法定名称。
vat_id	string 个人纳税人识别号。

object

allow_modify	boolean 用户是否可在支付UI中输入其名字。如令牌中传入了`user.name.value`参数，该值默认为`false`。
value	string 用户昵称。

object or null

value

string

电话号码。

object

value

string

唯一识别用户并为用户所熟知的参数，与用户ID（电子邮件、昵称等）不同。此参数在可以在游戏商店以外进行购买时使用（如现金售货亭中的游戏按键）。

object

value

string

Steam ID。

object

value

string = 32 characters

唯一用户ID — 用于营销活动。可包含数字和英文字符。

object

对象包含描述流量特性的数据。

utm_campaign	string 活动标题。该参数应当包含直译的活动标题或者翻译为英文的活动标题。
utm_content	string 该活动的实质。
utm_medium	string 流量渠道（内容关联广告、媒体广告、邮件列表消息）。
utm_source	string 流量来源。
utm_term	string 活动关键词。在指定该参数的情况下，统计数据是基于在确定您的广告活动的目标对象过程中所使用的关键词数据而生成的，而不是基于检索项数据。在Google Analytics中，`utm_term`标签的内容成为包含检索项的综合报告中的一部分。

Responses

200

Created.

422

Unprocessable Entity.

Request samples

application/json

{"settings": {"currency": "USD",
"language": "en",
"project_id": 16184,
"ui": {"size": "medium"
}
},
"user": {"email": {"value": "email@example.com"
},
"id": {"value": "user_2"
},
"name": {"value": "John Smith"
}
}
}

Response samples

application/json

{"token": "eop57k1boA7nnYPtewZ6KEXJyJADEwRT"
}