Pay Station API v1.0

概览

此部分介绍用于支付中心的方法。请使用基本认证来调用方法。要打开支付UI并启用安全支付，需先获取令牌。

端点路径：https://api.xsolla.com。

打开支付中心

支付中心是一个完整的支付UI，允许用户在您的网站上购买游戏和商品。要轻松在网站上实现该支付UI，请从我们的CDN下载脚本。请使用该URL将脚本集成到您的网站。如需更多信息，请访问我们的GitHub存储库。

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

参数类型描述
access_token
string令牌，通过API接收。 必需。
sandbox
boolean设置为true以测试支付流程，将使用sandbox-secure.xsolla.com而不是secure.xsolla.com。
lightbox
object带有选项列表的对象，可用于打开lightbox（桌面版本）。
lightbox.width
stringLightbox框架的宽度。如果为null，则取决于支付中心的宽度。默认值为null。
lightbox.height
stringLightbox框架的高度。如果为null，则取决于支付中心的高度。默认值为100%。
lightbox.zIndex
integer控制垂直堆叠顺序的属性，默认值为1000。
lightbox.overlayOpacity
integer浮层不透明度（从0到1），默认值为.6。
lightbox.overlayBackground
string浮层背景色，默认值为#000000。
lightbox.modal
boolean如为true，lightbox框架不可关闭，默认值为false。
lightbox.closeByClick
boolean如为true，单击浮层将关闭lightbox，默认值为true。
lightbox.closeByKeyboard
boolean如为true，按ESC键将关闭lightbox，默认值为true。
lightbox.contentBackground
string框架的背景，默认值为#ffffff。请注意，颜色更改不会影响支付中心iframe本身，只会影响容纳iframe的灯箱的设置。
lightbox.contentMargin
string框架边距，默认值为 10px。
lightbox.spinner
string加载指示器的动画类型。可为xsolla或round。默认值为xsolla。
lightbox.spinnerColor
string旋转加载动画的颜色，非默认设置。
childWindow
object支付中心UI所在子窗口的选项。适用于移动版本。
childWindow.target
string指定打开支付中心窗口的位置，可以是_blank、_self、_parent，默认值为_blank。

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

事件列表：

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

如果您想要自行初始化打开支付UI，请使用此链接：https://secure.xsolla.com/paystation3/?access_token=ACCESS_TOKEN。

Note: 打开支付UI的链接必须只能使用https://前缀。

如用于测试，请使用以下URL：https://sandbox-secure.xsolla.com/paystation3/?access_token=ACCESS_TOKEN。

Notice: 参数access_token包含隐私用户数据。请确保获取该参数时使用服务器对服务器通信。

令牌

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

获取令牌

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

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

HTTP请求

Copy
Full screen
Small screen
  • http
POST https://api.xsolla.com/merchant/v2/merchants/{merchant_id}/token

参数类型描述
user
object带用户相关数据的对象。
user.id
object带有用户ID相关数据的对象。 必需。
user.id.value
string用户ID。
user.name
object带有用户昵称相关数据的对象。
user.name.value
string用户昵称。
user.age
integer用户年龄。
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.redirect_policy
object重定向政策设置（对象）。
settings.redirect_policy.redirect_conditions
string将用户重定向至返回URL的支付状态。可以是none、successful、successful_or_canceled或any。
settings.redirect_policy.delay
integer延迟时间（单位为秒），经过该时间后用户将自动重定向至返回URL。
settings.redirect_policy.status_for_manual_redirection
string显示让用户重定向至返回URL按钮的支付状态。可以是none、successful、successful_or_canceled或any。
settings.redirect_policy.redirect_button_caption
string手动重定向按钮上的文字。
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.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
  • http
{
    "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/v1/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"
    },
    "age": 19,
    "email": {
      "value": "john.smith@mail.com"
    },
    "id": {
      "value": "user_2"
    },
    "name": {
      "value": "John Smith"
    }
  }
}
curl --request POST \
  --url https://api.xsolla.com/merchant/v1/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"},"age":19,"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"},"age":19,"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/v1/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/v1/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\"},\"age\":19,\"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\"},\"age\":19,\"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/v1/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/v1/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\"},\"age\":19,\"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\"},\"age\":19,\"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/v1/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"
    },
    "age": 19, 
    "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/v1/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格式）。

直接支付

要了解为应用设置令牌化的详细信息，请参阅支付中心文档。

列示已保存的支付帐户

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

HTTP请求

Copy
Full screen
Small screen
  • http
GET https://api.xsolla.com/merchant/v2/projects/{project_id}/users/{user_id}/payment_accounts

参数类型描述
project_id
integer项目ID。
user_id
string用户ID。
Copy
Full screen
Small screen
http
  • http
  • curl
  • php
  • C#
  • python
  • ruby
  • java
  • js
请求
GET https://api.xsolla.com/merchant/v1/projects/{project_id}/users/{user_id}/payment_accounts

Headers:
  Authorization: Basic <your_authorization_basic_key>
curl --request GET \
  --url https://api.xsolla.com/merchant/v1/projects/{project_id}/users/{user_id}/payment_accounts \
  --header 'authorization: Basic <your_authorization_basic_key> '
<?php

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

$request->setRequestUrl('https://api.xsolla.com/merchant/v1/projects/{project_id}/users/{user_id}/payment_accounts');
$request->setRequestMethod('GET');
$request->setHeaders(array(
  'authorization' => 'Basic <your_authorization_basic_key> '
));

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

echo $response->getBody();

var client = new RestClient("https://api.xsolla.com/merchant/v1/projects/{project_id}/users/{user_id}/payment_accounts");
var request = new RestRequest(Method.GET);
request.AddHeader("authorization", "Basic <your_authorization_basic_key> ");
IRestResponse response = client.Execute(request);

import http.client

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

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

conn.request("GET", "/merchant/v1/projects/{project_id}/users/{user_id}/payment_accounts", headers=headers)

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

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

url = URI("https://api.xsolla.com/merchant/v1/projects/{project_id}/users/{user_id}/payment_accounts")

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

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

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

Request request = new Request.Builder()
  .url("https://api.xsolla.com/merchant/v1/projects/{project_id}/users/{user_id}/payment_accounts")
  .get()
  .addHeader("authorization", "Basic <your_authorization_basic_key> ")
  .build();

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

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

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

xhr.open("GET", "https://api.xsolla.com/merchant/v1/projects/{project_id}/users/{user_id}/payment_accounts");
xhr.setRequestHeader("authorization", "Basic <your_authorization_basic_key> ");

xhr.send(data);
响应
[
  {
    "id": 4612345,
    "name": "PP_saved_account",
    "payment_system": {
      "id": 24,
      "name": "PayPal"
    },
    "type": "paypal"
  }
]
[
  {
    "id": 4612345,
    "name": "PP_saved_account",
    "payment_system": {
      "id": 24,
      "name": "PayPal"
    },
    "type": "paypal"
  }
]
[
  {
    "id": 4612345,
    "name": "PP_saved_account",
    "payment_system": {
      "id": 24,
      "name": "PayPal"
    },
    "type": "paypal"
  }
]
[
  {
    "id": 4612345,
    "name": "PP_saved_account",
    "payment_system": {
      "id": 24,
      "name": "PayPal"
    },
    "type": "paypal"
  }
]

[
  {
    "id": 4612345,
    "name": "PP_saved_account",
    "payment_system": {
      "id": 24,
      "name": "PayPal"
    },
    "type": "paypal"
  }
]
[
  {
    "id": 4612345,
    "name": "PP_saved_account",
    "payment_system": {
      "id": 24,
      "name": "PayPal"
    },
    "type": "paypal"
  }
]
[
  {
    "id": 4612345,
    "name": "PP_saved_account",
    "payment_system": {
      "id": 24,
      "name": "PayPal"
    },
    "type": "paypal"
  }
]
[
  {
    "id": 4612345,
    "name": "PP_saved_account",
    "payment_system": {
      "id": 24,
      "name": "PayPal"
    },
    "type": "paypal"
  }
]

通过已保存的帐户收费

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

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

HTTP请求

Copy
Full screen
Small screen
  • http
POST https://api.xsolla.com/merchant/v2/projects/{project_id}/users/{user_id}/payments/{type}/{account_id}

参数类型描述
project_id
integer项目ID。 必需。
user_id
string用户ID。 必需。
type
string支付帐户类型。 必需。 可为以下值：card — 银行卡；amazon — Amazon Pay；skrill — Skrill Digital Wallet；yandex — Yandex.Money；paymasterwebmoney — WebMoney；paypal — PayPal；qiwi — QIWI Wallet。

如果收到HTTP 200成功状态代码，则请求返回一个交易ID及其状态。可能状态有：
  • processing — 正在处理交易
  • done — 交易处理成功
  • error — 交易处理过程中发生错误
  • canceled — 交易被取消
  • held — 用户帐户中的资金被冻结
如果收到HTTP 422错误状态代码，则请求返回一个错误代码及详细错误描述。
account_id
integer艾克索拉数据库中已保存的帐户的ID。 必需。
user
object带用户相关数据的对象。
user.ip
string用户IP。 必需。
user.name
string用户名。
object包含法律实体详细信息的对象。
string完整法定名称。
string完整法定地址。
string个人纳税人识别号。
string公司所在国家/地区。参照ISO 3166-1 alpha-2标准的两个大写字母表示的国家/地区代码。
purchase
object带有购买相关数据的对象。
purchase.virtual_currency
object带有虚拟货币相关数据的对象。
purchase.virtual_currency.quantity
float使用虚拟货币购买的数量。
purchase.checkout
object带有结账参数相关数据的对象。
purchase.checkout.currency
string购买币种。参照ISO 4217标准的三字母货币代码。
purchase.checkout.amount
float购买金额。
settings
object带有购买设置相关数据的对象。
settings.mode
string设置sandbox值以测试支付流程。对于真实支付，应移除此参数。
custom_parameters
string您的自定义参数。应当是带键值对的有效JSON哈希。
Copy
Full screen
Small screen
http
  • http
  • curl
  • php
  • C#
  • python
  • ruby
  • java
  • js
请求
POST https://api.xsolla.com/merchant/v1/projects/{project_id}/users/{user_id}/payments/{type}/{account_id}

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

Body:
  {
  "card": {
    "cvn": "123"
  },
  "purchase": {
    "description": {
      "value": "currency purchase"
    },
    "virtual_currency": {
      "quantity": 100
    }
  },
  "settings": {
    "currency": "USD",
    "external_id": "ext123",
    "save": true
  },
  "user": {
    "id": "user123",
    "ip": "111.11.11.11",
    "name": "John Smith",
    "legal" : {
      "name": "My Awesome Company",
      "address": "17 Crown Street London SW2 0JW United Kingdom",
      "vat_id": "GB111111111",
      "country": "GB"
  }
}
curl --request POST \
  --url https://api.xsolla.com/merchant/v1/projects/{project_id}/users/{user_id}/payments/{type}/{account_id} \
  --header 'authorization: Basic <your_authorization_basic_key>' \
  --header 'content-type: application/json' \
  --data '{"user":{"id":"user123","ip":"111.11.11.11","name":"John Smith","legal":{"name":"My Awesome Company","address":"17 Crown Street London SW2 0JW United Kingdom","vat_id":"GB111111111","country":" GB"}},"card":{"cvn":"123"},"purchase":{"virtual_currency":{"quantity":100},"description":{"value":"currency purchase"}},"settings":{"save":true,"currency":"USD","external_id":"ext123"}}'
<?php

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

$body = new http\Message\Body;
$body->append('{"user":{"id":"user123","ip":"111.11.11.11","name":"John Smith","legal":{"name":"My Awesome Company","address":"17 Crown Street London SW2 0JW United Kingdom","vat_id":"GB111111111","country":" GB"}},"card":{"cvn":"123"},"purchase":{"virtual_currency":{"quantity":100},"description":{"value":"currency purchase"}},"settings":{"save":true,"currency":"USD","external_id":"ext123"}}');

$request->setRequestUrl('https://api.xsolla.com/merchant/v1/projects/{project_id}/users/{user_id}/payments/{type}/{account_id}');
$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/v1/projects/{project_id}/users/{user_id}/payments/{type}/{account_id}");
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\":\"user123\",\"ip\":\"111.11.11.11\",\"name\":\"John Smith\",\"legal\":{\"name\":\"My Awesome Company\",\"address\":\"17 Crown Street London SW2 0JW United Kingdom\",\"vat_id\":\"GB111111111\",\"country\":\"GB\"}},\"card\":{\"cvn\":\"123\"},\"purchase\":{\"virtual_currency\":{\"quantity\":100},\"description\":{\"value\":\"currency purchase\"}},\"settings\":{\"save\":true,\"currency\":\"USD\",\"external_id\":\"ext123\"}}", ParameterType.RequestBody);
IRestResponse response = client.Execute(request);

import http.client

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

payload = "{\"user\":{\"id\":\"user123\",\"ip\":\"111.11.11.11\",\"name\":\"John Smith\",\"legal\":{\"name\":\"My Awesome Company\",\"address\":\"17 Crown Street London SW2 0JW United Kingdom\",\"vat_id\":\"GB111111111\",\"country\":\"GB\"}},\"card\":{\"cvn\":\"123\"},\"purchase\":{\"virtual_currency\":{\"quantity\":100},\"description\":{\"value\":\"currency purchase\"}},\"settings\":{\"save\":true,\"currency\":\"USD\",\"external_id\":\"ext123\"}}"

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

conn.request("POST", "/merchant/v1/projects/{project_id}/users/{user_id}/payments/{type}/{account_id}", 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/v1/projects/{project_id}/users/{user_id}/payments/{type}/{account_id}")

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\":\"user123\",\"ip\":\"111.11.11.11\",\"name\":\"John Smith\",\"legal\":{\"name\":\"My Awesome Company\",\"address\":\"17 Crown Street London SW2 0JW United Kingdom\",\"vat_id\":\"GB111111111\",\"country\":\"GB\"}},\"card\":{\"cvn\":\"123\"},\"purchase\":{\"virtual_currency\":{\"quantity\":100},\"description\":{\"value\":\"currency purchase\"}},\"settings\":{\"save\":true,\"currency\":\"USD\",\"external_id\":\"ext123\"}}"

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\":\"user123\",\"ip\":\"111.11.11.11\",\"name\":\"John Smith\",\"legal\":{\"name\":\"My Awesome Company\",\"address\":\"17 Crown Street London SW2 0JW United Kingdom\",\"vat_id\":\"GB111111111\",\"country\":\"GB\"}},\"card\":{\"cvn\":\"123\"},\"purchase\":{\"virtual_currency\":{\"quantity\":100},\"description\":{\"value\":\"currency purchase\"}},\"settings\":{\"save\":true,\"currency\":\"USD\",\"external_id\":\"ext123\"}}");
Request request = new Request.Builder()
  .url("https://api.xsolla.com/merchant/v1/projects/{project_id}/users/{user_id}/payments/{type}/{account_id}")
  .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": "user123",
    "ip": "111.11.11.11",
    "name": "John Smith",
    "legal" : {
      "name": "My Awesome Company",
      "address": "17 Crown Street London SW2 0JW United Kingdom",
      "vat_id": "GB111111111",
      "country": "GB"
    },
  },
  "card": {
    "cvn": "123"
  },
  "purchase": {
    "virtual_currency": {
      "quantity": 100
    },
    "description": {
      "value": "currency purchase"
    }
  },
  "settings": {
    "save": true,
    "currency": "USD",
    "external_id": "ext123"
  }
});

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/v1/projects/{project_id}/users/{user_id}/payments/{type}/{account_id}");
xhr.setRequestHeader("content-type", "application/json");
xhr.setRequestHeader("authorization", "Basic <your_authorization_basic_key>");

xhr.send(data);
响应
{
    "transaction_id": 123458390
}
{
    "transaction_id": 123458390
}
{
    "transaction_id": 123458390
}
{
    "transaction_id": 123458390
}

{
    "transaction_id": 123458390
}
{
    "transaction_id": 123458390
}
{
    "transaction_id": 123458390
}
{
    "transaction_id": 123458390
}

删除已保存的支付帐户

删除已保存的支付帐户。

HTTP请求

Copy
Full screen
Small screen
  • http
DELETE https://api.xsolla.com/merchant/v2/projects/{project_id}/users/{user_id}/payment_accounts/{type}/{account_id}

参数类型描述
project_id
integer项目ID。
user_id
string用户ID。
type
string支付帐户类型。 可为以下值：card — 银行卡；amazon — Amazon Pay；skrill — Skrill Digital Wallet；yandex — Yandex.Money；paymasterwebmoney — WebMoney；paypal — PayPal；qiwi — QIWI Wallet。

如果收到HTTP 200成功状态代码，则请求返回一个交易ID及其状态。可能状态有：
  • processing — 正在处理交易
  • done — 交易处理成功
  • error — 交易处理过程中发生错误
  • canceled — 交易被取消
  • held — 用户帐户中的资金被冻结
如果收到HTTP 422错误状态代码，则请求返回一个错误代码及详细错误描述。
account_id
integer艾克索拉数据库中已保存的帐户的ID。
Copy
Full screen
Small screen
http
  • http
  • curl
  • php
  • C#
  • python
  • ruby
  • java
  • js
请求
DELETE https://api.xsolla.com/merchant/v1/projects/{project_id}/users/{user_id}/payment_accounts/{type}/{account_id}

Headers:
  Authorization: Basic <your_authorization_basic_key>
curl --request DELETE \
  --url https://api.xsolla.com/merchant/v1/projects/{project_id}/users/{user_id}/payment_accounts/{type}/{account_id} \
  --header 'authorization: Basic <your_authorization_basic_key>'
<?php

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

$request->setRequestUrl('https://api.xsolla.com/merchant/v1/projects/{project_id}/users/{user_id}/payment_accounts/{type}/{account_id}');
$request->setRequestMethod('DELETE');
$request->setHeaders(array(
  'authorization' => 'Basic <your_authorization_basic_key>'
));

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

echo $response->getBody();

var client = new RestClient("https://api.xsolla.com/merchant/v1/projects/{project_id}/users/{user_id}/payment_accounts/{type}/{account_id}");
var request = new RestRequest(Method.DELETE);
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("DELETE", "/merchant/v1/projects/{project_id}/users/{user_id}/payment_accounts/{type}/{account_id}", headers=headers)

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

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

url = URI("https://api.xsolla.com/merchant/v1/projects/{project_id}/users/{user_id}/payment_accounts/{type}/{account_id}")

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

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

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

Request request = new Request.Builder()
  .url("https://api.xsolla.com/merchant/v1/projects/{project_id}/users/{user_id}/payment_accounts/{type}/{account_id}")
  .delete(null)
  .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("DELETE", "https://api.xsolla.com/merchant/v1/projects/{project_id}/users/{user_id}/payment_accounts/{type}/{account_id}");
xhr.setRequestHeader("authorization", "Basic <your_authorization_basic_key>");

xhr.send(data);
响应
本文对您的有帮助吗？
谢谢！
我们还有其他可改进之处吗？ 留言
非常抱歉
请说明为何本文没有帮助到您。 留言
感谢您的反馈！
我们会查看您的留言并运用它改进用户体验。